Brain tools
The bundled pi extension that gives the voice brain its gateway tools: work capture and status, background work, alarms and timers, the self-tools over the Admin socket, and the bounded Herdr tools.
Living doc, checked against the code 2026-11-14
The bundled Pi extension that gives the voice brain its brain_* tools: work capture and status, background work,
alarms, watches, self-reports and bounded Herdr control. Each tool is a closed request that the Gateway validates.
Tools
brain_capture_work: submits bounded text to the webhook receiver (the Receiver MCP below) as a durable, idempotent inbox envelope. Success means captured for review, not landed in Memento.brain_work_status: reads bounded canonical workflow status frommm serveviamemory_work_status.brain_background_work_start,brain_background_work_statusandbrain_background_work_cancel: background work owned by the calling brain continuity. The Gateway mints the work IDs, caps global and per-continuity admission, and owns the accepted/running/completed/canceled/failed state. Each attempt runs in a separate ephemeral Pi process with no tools, extensions, skills, context files, approval or persistent session. Foreground loadout tools never cross into it.[tools] background_toolset = "herdr-readonly"gives the attempt the fixed read-only Herdr status toolset and the extension bundles that define it.research-readonly(the operator loadouts) addspi_code_searchand thefox9docsreads. A call to a tool outside the attempt’s grant stops it (background_work_tool_refused). A completed job’s sources (titles and hosts) show as onecard.v1panel beside the spoken result. These tools expose no session selector, caller ID, command, shell, MCP method, transcript or approval field.brain_alarm_set,brain_alarm_listandbrain_alarm_cancel: schedule, list and cancel Gateway-owned alarms and timers. The Gateway fires them with a chime and a spoken line on the live frontend, never on a room speaker. The set and list answers carryrings_on(the frontend’s room, the gateway machine’s default output).brain_watch_set,brain_watch_listandbrain_watch_cancel: “tell me when X”. A watch is a typed condition (arrive_home,enter_room, a herdragentreaching done or needs-you, an agent’scipassing or failing, acameralabel, asoundclass heard in a room, anoutputmarker printed by a Gateway-owned pane) plus the line to say. The Gateway keeps it in<state>/watches.json(owner-only, at most 32 open) and speaks the line through its announcement governor when the condition happens, with no brain turn. Ids arewatch-<n>, never read aloud. There is no URL condition.brain_mic_recalibrate,brain_gateway_health,brain_frontend_statusandbrain_frontend_control: self-tools over the Gateway Admin socket. They run one rate-limited mic recalibration step, read the health (the grouped issue line when something is wrong, else the components) and capture liveness, and queue one desktop-clientreconnect,statusorshowcaseaction. The outcome lands on the Admin event timeline.brain_vulpine_report {topic, window_hours?, host?}: Vulpine’s report on itself over the Admin socket (get_vulpine_report, owner-local). The topics:health;latency(felt reply time per hour from a two-day ring, the slowest hour in the asker’s local time and its slowest leg);nightly(the newest harness nightly receipt and its failed suites);errors(warnings and failures by component, and the usage ledger’s failed tools);events(today’s gateway events as hourly counts);connections(connector, device and extension rows: set up, broken, never seen);usage;host(one inventory host’s uptime, load, memory, disk and GPU from the fleet store’s last probe, plus the Vulpine launchd jobs on the gateway’s own host);tools(the tools by kind and each MCP server);setup(what is not set up, each with its next step); andfeatures(the feature switches that ship and are off). Ahostlabel outside the inventory is refused with the inventory’s labels. The tool speaks the gateway’ssayand labeled facts and puts up itscard.v1. A report holds counts and names only: never an event message, a transcript word, a path, an id or a hex token.brain_herdr_state,brain_herdr_agentandbrain_herdr_pane: bounded read-only Herdr workspace/agent/pane observation.brain_herdr_work_graph: no arguments. Reads the current continuity’s Gateway-owned work/ownership/agent/pane graph, observer freshness, and deduplicated blocked/done attention. Blocked and done are lifecycle states, never verified task success. It returns no pane output, transcript, path contents or cross-continuity records.brain_herdr_attention: takes one Gateway-ownedownership_idand returns what changed in that pane’s repository: at most 32 sorted relative paths with status and addition/deletion counts, in at most 17 KiB, with no file contents or patch bodies. The root is the loadout’s configured relative project root and must be a direct, non-linked repository with an ordinary.gitdirectory.brain_herdr_command: takes a Gateway-ownedownership_idand one closed recipe (working_directoryorgit_status_short). The Gateway reserves an available owned pane and asks Vigil for a single-use confirmation. No native command method is admitted: approval settles ascommand_held, and nothing runs.brain_herdr_create_agent_paneandbrain_herdr_start_agent: create one Gateway-owned pane from exact source context, then start one closed agent kind using only the returned ownership ID.brain_herdr_cancel_owned_agent: closes one exact continuity-owned started-agent pane, with bounded reconciliation on uncertain transport.brain_herdr_wait: starts one Gateway-owned wait bound to the current monitored target, pane, continuity and observer generation.brain_herdr_focus: sends one typedpane_idto the Gateway dispatch socket and waits for the Gateway’s result. It does not call Herdr.brain_herdr_close(the bundled operator loadouts allow it): closes exactly one named pane (pane_id) or workspace (workspace_id) in two calls. The first call closes nothing. The Gateway reads the session and HOLDs on any doubt (a working or blocked agent, the last pane or workspace, a Gateway-owned pane, a worktree workspace, a name two targets answer to), or answers with a read-back and a single-use code. The operator says the exact words the read-back names (close <name>); the Gateway hears them itself, and a plain yes is not enough. The second call carries the code. The Gateway re-reads the session, saves each closing pane’s recent output toherdr-closed/in its private state folder, closes, and proves the other panes or workspaces are still there. The schema has no confirmation field a model could fill.
Every tool here speaks tool.v1: it is called as {action, args} and declared from its manifest,
catalog/pi/tools/<name>/tool.toml (handler native). The old flat call is still accepted. A new brain tool adds a
manifest and a row in v1.ts beside its registration, and a row in crates/voice_gateway/src/routing/brain_v1.rs
when the gateway reads its call.
Agent prompts are not a brain-tools tool. The extension does not register brain_herdr_prompt_agent, and Agent
loadouts do not allow it. The brain messages Herdr panes through pi_herdr_prompt in
catalog/pi/extensions/vulpine-tools/, which re-checks the pane’s identity before it sends.
No generic approval, message bus, session selection, arbitrary MCP call, shell execution or model-selected Herdr method is exposed. Every Herdr mutation not listed above is absent.
Background status keeps the raw final result text for at most five minutes. After that, status may return a
result-free tombstone with payload_retained: false. The Gateway persists the work ledger in a private Redb store, so
a restart keeps the accepted queue. An attempt in flight at a restart settles as failed.
Brain loop containment (catalog/pi/extensions/vulpine-tools/containment.ts) watches for a brain that repeats
itself. Each assistant message is reduced to its normalized text plus its tool-call shapes (name and key-sorted
arguments) and hashed. When the tail of a session repeats the same message, or the same cycle of two, three times
within 120 s, the extension writes one brain_loop_suspected receipt to the tool-receipt spool. The receipt’s tool
is pi_brain_containment, with fields session (an ordinal), repeats, window (the cycle length), lane
(foreground or background) and aborted. The Admin’s Tools view lists it with the other receipts.
- It is observe-only and on by default.
VULPINE_BRAIN_CONTAINMENT=0turns it off. - With
VULPINE_BRAIN_CONTAINMENT_ABORT_BACKGROUND=1(default off), a background lane whose tail reaches five repeats is aborted and leaves a second receipt with codeBRAIN_LOOP_ABORTED. A foreground voice turn is never aborted. - Only the read-only remote background tier loads it. The tool-free tier runs Pi without extensions and is not watched.
Adding a tool: the six places it must be registered
A brain tool missing from any one of these places fails silently: the brain says the tool is unavailable, or never
calls it, and nothing logs an error. Most new tools are pi_* tools in
catalog/pi/extensions/vulpine-tools/; the brain_*
tools in this bundle differ only in places 1 and 6. In order:
| # | place | the file | the check that proves it |
|---|---|---|---|
| 1 | The registration in the Pi extension | pi_*: the domain’s register<Domain>Tools(cx) in catalog/pi/extensions/vulpine-tools/<domain>.ts through cx.registerTool (schema in schemas.ts, the guard’s per-tool rule in guard.ts). brain_*: crates/voice_gateway/extensions/brain-tools/index.ts, plus the gateway’s closed operation for it |
bun run test in catalog/pi/extensions/vulpine-tools (or bun test crates/voice_gateway/extensions/brain-tools/index.test.ts catalog/agents/brain-tools-loadouts.test.ts) |
| 2 | The receipt fields (pi_* only) |
TOOL_RECEIPT_FIELDS in catalog/pi/extensions/vulpine-tools/receipts.ts (the closed params/details keys), and a TOOL_EGRESS line when the tool reaches a fixed host |
the catalog lint (place 5) refuses a pi_* tool with no receipt field subset |
| 3 | The loadouts | the tool name in [tools] allowed_pi of catalog/agents/operator/.vulpine/loadout.toml AND of every per-client loadout a client binds (catalog/agents/operator/.vulpine/loadouts/laptop.toml, vigil.toml, …); the extension itself in the loadout’s extensions list (local:vulpine-tools, builtin:brain-tools). allowed_pi alone does nothing: the gateway spawns pi with --no-extensions and only the listed extensions |
the catalog lint (place 5): a registered tool no loadout allows, or a loadout naming a tool nothing registers |
| 4 | The gateway’s allow-list test | the exact allowed_pi array of loadout.toml, copied in crates/voice_gateway/src/loadout.rs (repository_voice_loadout_resolves_the_bundled_brain_tools); the gateway also caps each tool’s declared risk against the loadout’s tools.max_risk at bind |
cargo test -p vulpine-voice-gateway --lib loadout; the catalog lint flags the array drifting from loadout.toml |
| 5 | The catalog and the reference | the tool’s capability family (its domain capability and search tags, ADR 0050 §2) in FAMILIES of catalog/pi/extensions/vulpine-tools/catalog_provenance.ts; catalog/pi/tool-catalog.json, regenerated by bun run catalog in catalog/pi/extensions/vulpine-tools; then docs/reference/brain-tools.md, regenerated from the catalog by just docs-reference |
the tool-catalog hk step (bun catalog.ts --check, fast tier, every commit touching the extensions, the loadouts or loadout.rs) refuses a stale catalog or a lint error (a row no family covers is a capabilities_undeclared warning); the docs-reference hk step (tools/docs/docs_reference.py --check and docs_coverage.py --fail-on tool) refuses a stale reference page |
| 6 | The deploy | pi_*: the brain loads catalog/pi/extensions/vulpine-tools from the gateway host’s own checkout, so the commit reaches it by just mini-sync-checkout (a fast-forward and a gateway kickstart; it does not install packages, so run npm ci in the extension dir there when package.json changed). brain_*: this bundle reaches the runtime root by just deploy-brain-tools (built --target node, load-tested in Pi on the gateway host before install). An overlay roll carries neither |
the newest session trace’s brain_identity_bound names the loadout the client bound and its --tools list holds the new name; the call itself shows in the Pi session log |
Two traps beside the six. Every spawn inside a tool uses absolute paths, the interpreter included (/bin/sh), because
the gateway’s launchd PATH is minimal. And a receipt field the gateway adds must be added to the bundle’s reply
parser too, or the call reads as unavailable.
Deployment environment
Credentials and endpoints are deployment configuration. They are never model-visible tool arguments and are never committed.
Receiver MCP:
VULPINE_RECEIVER_MCP_URLVULPINE_RECEIVER_ACCESS_CLIENT_IDandVULPINE_RECEIVER_ACCESS_CLIENT_SECRET, required together for non-loopback endpoints. A literalhttp://127.0.0.1/...orhttp://[::1]/...deployment may omit both only when the receiver runs as a separate loopback-only, non-tunnelled service. Credentialed endpoints require HTTPS, may not contain URL userinfo, and reject redirects rather than forward Access headers to another origin.
Herdr Unix socket:
VULPINE_HERDR_SOCKET_PATH: required absolute path to the deployment-owned Herdr Unix-domain socket. The gateway launch environment supplies it, never Pi/model arguments or agent files.- The Gateway service account needs read/write permission on that socket. The socket directory must not be writable by the voice process.
- Transport is Node’s built-in
node:net: one newline-delimited JSON request per connection,{id,method,params}to{id,result}or{id,error}. Bounds: 10 seconds, 64 KiB transport, 32 KiB projected text/result. - Read tools use this socket directly. Mutation tools do not. Only the Gateway collects owned-pane attention, through
fixed, bounded Git metadata commands; linked-worktree Gitfiles fail closed. The Gateway sends
pane.focusonly after validated frontend approval. It never sends nativeagent.prompt.
Gateway mutation dispatch:
- The Gateway creates a per-brain private Unix socket and a random 64-hex token, and injects both into that Pi child
as
VULPINE_GATEWAY_MUTATION_SOCKET_PATHandVULPINE_GATEWAY_MUTATION_TOKEN. Neither is a model argument. - The extension sends only closed, operation-specific envelopes. The Gateway rejects any request whose fields do not match the active brain tool call.
- Vigil must advertise
herdr.pane.focus. The Gateway issues a 30-second, single-use challenge bound to the exact action, pane and session. Pi never confirms its own request; Vigil only returns the human decision.
Gateway Admin socket:
VULPINE_ADMIN_SOCKET_PATH: optional absolute path for the self-tools; defaults to~/.local/state/vulpine/admin/admin.sock.
Memento stdio MCP:
VULPINE_MEMENTO_ROOT: required absolute workspace root.VULPINE_MEMENTO_COMMAND: optional deployment-owned command path; defaults tomm.
Capture keys are fox9_ plus the SHA-256 of the complete Pi tool-call ID. Success requires an exact matching
receiver delivery ID. MCP handshakes and calls are bounded to ten seconds and propagate Pi cancellation. Memento stdio
messages are capped at 64 KiB and status text at 32 KiB. The Memento child inherits only the MCP SDK safe environment
allowlist plus MEMENTO_ROOT.
The Nix Gateway package bundles this extension and its MCP SDK dependencies into
share/foxline/extensions/brain-tools/index.js. The Gateway wrapper sets VULPINE_RUNTIME_ROOT, and persisted
config cannot redirect the bundled extension directory away from that immutable root.