Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

Proactive cards

What fox9 may say unprompted (the card), how the announcement governor tiers it, and the answers the operator may give.

Living doc, checked against the code 2026-11-14

proactive-card.v1 — what Vulpine may say unprompted, and what the operator may answer

  • Status: live. The types, the goldens and the validator are in the protocol crate. The gateway wires the governor, the spoken card and the answer grammar. Two producers cut a card: a finished herdr agent’s report cuts a herdr_lifecycle suggestion, Read it / Dismiss (herdr_report_card in ws/reports.rs), and the agent door turns a linked agent’s show or result into a suggestion with one Dismiss action (agent_door.rs).
  • Relates: ADR 0030 (the announcement governor, which decides WHETHER and WHEN), ADR 0028 (hash-bound approvals) and the approval socket (where a requires_confirm answer lands).
  • Types: ProactiveCard, ProactiveCardKind, ProactiveCardAction, ProactiveCardVerb in crates/protocol/src/lib.rs; ts-rs bindings in packages/protocol/src/generated/.
  • Goldens: benchmarks/fixtures/proactive-card.v1/golden/{suggestion,alert,digest}.json; refusals: invalid/{hex-in-speech,unknown-verb,arg-missing}.json. cargo test -p vulpine-protocol proactive_card runs both sets.

Why a card

A card says what an unsolicited announcement is and what the operator may do about it. Its text is authored upstream, but its answers come from a closed set of verbs the gateway already runs, never from a fresh brain turn. A spoken “shall I?” can never dispatch something the brain invented.

Shape (schema 1)

field type rule
schema u32 1
id string 1..=64 chars; the governor candidate id
kind suggestion | alert | digest a suggestion asks, an alert tells, a digest sums up
source string a snake_case governor source (Source::as_str in announce_governor.rs): background_work, herdr_lifecycle, agent, approval_card, camera_event, alarm, …
title string 1..=80 chars; the text surface’s headline
spoken_form string 1..=280 chars; exactly what the voice says; no hex (sha/UUID-shaped tokens, sha256:, citation tokens are refused)
body_md string ≤ 4000 chars; may be empty
actions array 1..=4 of { verb, label (1..=40), arg? }
created_at_ms, ttl_ms u64 ttl ≥ 1000

Verbs (closed; an unknown verb fails to deserialise)

verb arg what the gateway does
dismiss — drops the card, reaction ignored
snooze ms (u64) re-offers after the delay (governor TTL permitting)
sitrep — GatewayReport::Sitrep
start_over — GatewayReport::StartOver
mic_recalibrate — GatewayReport::MicRecalibrate
reading_control a ReadingAction name GatewayReport::ReadingControl
home_undo — GatewayReport::HomeUndo
home_verb "on <subject>" / "off <subject>" GatewayReport::HomeVerb (the candidates-or-ask contract still applies)
approval_card ledger seq (u64) speaks that approval card; the next utterance answers it
herdr_agent_report ledger seq (u64) GatewayReport::HerdrAgentReport
herdr_prompt_relay ledger seq (u64) GatewayReport::HerdrPromptRelay

A new verb needs a GatewayReport shape first. Nothing here takes free text from the card into a brain turn.

How a card is spoken and answered

The spoken line and the answer grammar are crates/voice_gateway/src/proactive_card.rs. A card answer reaches the same verb handlers the spoken grammar in turn.rs reaches.

The candidate carries the card. Candidate has card: Option<ProactiveCard>. Every producer but the two above passes None, and the gate decides the same for them. The governor decides WHETHER on {source, score, ttl, reason} and never reads the card.

The exact spoken form. spoken_form, then the labels as one closed question; never the title, never body_md:

<spoken_form, a full stop added if it has no final punctuation> Say <labels>.

The labels are lower-cased at the first letter (unless the second is also upper case) and joined a / a or b / a, b, or c. The suggestion golden speaks as:

The agent in pane one three has finished the tracker migration. Shall I read its report? Say read the report or not now.

A card is spoken on the session’s voice, never through the room verb: the answer has to come back to the mic that heard the question. It is validated (ProactiveCard::validate) and run through tts_text::normalize_tts_text, the no-hex scrub every spoken line gets. A card that fails either is dropped with outcome: invalid and a proactive_card_refused row, never half-spoken. A card line gets no age clause: the question is asked now or not at all.

The answer grammar. After a card is spoken the session holds pending_card { id, kind, source, tier, actions, deadline_ms, card } on LiveSessionState. It is attached at speak time and carried across a loadout rebuild. An over_and_out rotation drops it. The deadline is the card’s ttl_ms clamped to [5 s, 10 min].

The next utterance (STT final or text_utterance) is matched before the turn machine, in the seat answer_pending_approval_card takes, so turn.rs’s MIN_ARMED_REQUEST_CHARS floor never eats a short label (“done”, “not now”). Matching ignores case, punctuation and repeated whitespace, and drops a leading hey / fox9 / fox nine / fox 9. The match must consume the whole phrase: a label inside a longer sentence (“read the report from the overnight lane to me”) goes to the brain. Beside the producer’s label, each verb answers to its own fixed phrases (dismiss / not now / never mind, snooze, sitrep, start over, recalibrate the mic, undo that, …).

verb routing what happens
dismiss routes (local) card closed, answered(dismiss)
snooze routes (local) re-admitted to the board after arg ms, clamped to [5 s, 60 min] (default 10 min), score 0.7, reason proactive_card_snoozed
sitrep routes GatewayReport::Sitrep
start_over routes GatewayReport::StartOver { phrase: StartOver }
mic_recalibrate routes GatewayReport::MicRecalibrate
reading_control routes GatewayReport::ReadingControl { action } from the arg (an unparsable arg is unrouted)
home_undo routes GatewayReport::HomeUndo { phrase: <label> }
home_verb unrouted an open subject plus the candidates-or-ask contract; needs its own confirm tier
approval_card unrouted the seq lives in a session ledger the answer path does not reach
herdr_agent_report routes speaks the ledger line attached to the action at speak time; unrouted when the ledger has evicted the seq
herdr_prompt_relay unrouted as approval_card

A requires_confirm action is not wired and is recorded unrouted. No match is not an answer: the utterance goes to the brain as it would without a card. The card stays pending until its deadline, then resolves ignored and holds nothing. Answering a card counts as operator engagement, so the announcement watch resolves Accepted.

Trace. One proactive_card { id, kind, source, tier, outcome } row per state change, outcome ∈ admitted | spoken | deferred(<reason>) | answered(<verb>) | ignored | invalid | unrouted(<verb>). admitted means a producer put it on the board (tier none). A card answered by an utterance also carries answered_by: voice | text. deferred(...) rows are written for candidates the governor holds. A card that goes terminal (notify / drop) is traced by the announcement rows only, because the governor has released it.

Admin projection

One row per card on Errors & Events, from AdminEventSink::record_proactive_card(outcome, message, warning): component_id: gateway.announcements, the outcome as the phase, ids and counts in the message, never a card’s text. A card nobody answered is written ignored; no expired outcome is written.

GovernorProjection.cards_by_kind counts queued and digest-bound candidates by card kind, beside spoken_last_hour. It reaches the panel as AdminAnnouncementsSnapshot.cards_by_kind?: AdminAnnouncementCardKind[] (optional, so an older Admin build reads the snapshot unchanged).

Validation elsewhere

A non-Rust surface validates a card against the same golden and invalid files. Its TypeScript types are generated into packages/protocol; no TypeScript validator ships.

Was this page helpful?