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_lifecyclesuggestion,Read it/Dismiss(herdr_report_cardinws/reports.rs), and the agent door turns a linked agent’sshoworresultinto a suggestion with oneDismissaction (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_confirmanswer lands). - Types:
ProactiveCard,ProactiveCardKind,ProactiveCardAction,ProactiveCardVerbincrates/protocol/src/lib.rs; ts-rs bindings inpackages/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_cardruns 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.