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

Hooks

Proposed (ADR 0059): lifecycle hooks; a boundary (session.start.after and session.end.after live with the built-in admin_receipt; invocation.arm.after, brain.turn.settled.after and readiness.changed.after proposed) hands a typed event with ids, closed reasons and ms only to consumers the user supplies as hook_consumer Catalog entries (script on stdin, signed webhook; herdr plugin and pi extension later), registered under [lifecycle.observe]; one non-blocking enqueue at the commit, a deadline per delivery, at most once, one receipt per attempt with a closed disposition; Gate and Mutate only after the authority review.

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

hooks.v1 — a lifecycle boundary’s typed event, from the subsystem that commits it to a consumer the user supplies

  • Status: accepted, version 1.0 (ADR 0059 §3). Live: the two session boundaries, the built-in admin_receipt and the Catalog kinds script and webhook. Not built: the proposed boundaries, herdr_plugin, pi_extension, a digest pin on a consumer entry, and https webhooks.
  • Scope: a boundary is a named transition that one subsystem commits. After the commit, the subsystem hands a typed event to each consumer and records one receipt per attempt. A consumer never changes, delays or reorders the transition it observes.
  • The plugin point: a hook_consumer Catalog entry and one line in a loadout’s [lifecycle.observe].

Classes

class when it runs what it may return v1
observe after the commit nothing (its exit status or HTTP status is recorded only) yes
gate before the commit, under a fail-closed deadline allow, refuse {reason} or abstain; it can only narrow not built
mutate after the commit, as its own owned effect a settlement and a cleanup receipt not built

Boundaries

A boundary id is <scope>.<transition>.<before|after>. The list is closed and grows only by a minor version. Only the two live rows fire; a loadout or a manifest that names a proposed row is refused.

boundary class owner fires when payload state
session.start.after observe the voice connection the initial session_started was sent with the session’s resources committed ids only live (admin_receipt, script, webhook)
session.end.after observe the voice connection a client’s end_session closed with outcome succeeded and session_ended was sent ids only live (admin_receipt, script, webhook)
invocation.arm.after observe TurnManager an arm was admitted (the detection or the STT alias), after one arm-transition owner exists armed_request_id, source proposed
brain.turn.settled.after observe the gateway’s brain turn the turn’s brain ownership was released or quarantined turn_id, terminal, legs_ms proposed
readiness.changed.after observe each readiness owner a readiness transition owner, state, reason, generation proposed
session.start.before gate the voice connection after the request is validated, before composition is resolved ids only proposed

A transport loss, a gateway stop, a radio rotation, the spoken restart and a model rebind do not fire session.end.after.

The event (to a consumer)

One JSON object, at most 4 KiB:

{
  "schema": "vulpine.hooks/v1",
  "version": "1.0",
  "boundary": "session.end.after",
  "class": "observe",
  "delivery_id": "6f1c0a52-4a43-4f0e-9d0b-0d8a2b1e5c11",
  "invocation_id": "b0e8f3a4-1c2d-4e5f-8a9b-0c1d2e3f4a5b",
  "owner_component": "gateway.observe.session_end",
  "occurred_at_ms": 1793480000000,
  "sequence": 42,
  "session_id": "3d9b7c1e-2f4a-4b6c-8d0e-1f2a3b4c5d6e",
  "continuity_id": "operator:laptop:7",
  "reason": "end_session",
  "payload": {}
}
field type rule
schema string always vulpine.hooks/v1
version string the minor the gateway speaks (1.0); a consumer ignores fields it does not know
boundary string one row of the table above
class string observe in v1
delivery_id uuid unique per attempt; also the webhook’s webhook-id
invocation_id uuid one per boundary firing, shared by every consumer of it
owner_component string the trace component of the owner
occurred_at_ms integer the commit’s wall time, unix ms
sequence integer monotonic per consumer within one gateway process; a gap means a drop
session_id, continuity_id, armed_request_id, turn_id, output_generation string, optional present only when the boundary has that identity, never empty
reason string, optional the boundary’s closed reason enum (end_session on session.end.after)
payload object the boundary’s typed payload, ids, closed values and ms only

An event never carries words, transcripts, prompts, brain output, file paths, raw audio, credentials, the owner’s capability or lease, the loadout’s source, or a household name.

Consumer kinds

kind how it is called its answer v1
admin_receipt built-in: one bounded row in the Admin Events store, one try_lock attempt none live
script the entry’s executable, a clean environment (PATH=/usr/bin:/bin, VULPINE_HOOK_STATE_DIR naming its own folder in the gateway’s state folder, and its one named secret); the event as one line on stdin, then stdin closes; cwd is the entry’s root; its own process group, killed whole at the deadline the exit status, recorded (0 is delivered); stdout and stderr are read up to 4 KiB for the receipt’s diagnostics and never parsed built
webhook one POST of the event over http to the manifest’s URL (loopback, or a host on the gateway’s [hooks] webhook_hosts list, which needs network declared), signed with Standard Webhooks (webhook-id is the delivery_id, webhook-timestamp, webhook-signature), the whsec_ secret read at delivery from the environment variable secret_env names the HTTP status: 2xx is delivered built
herdr_plugin one action of a linked herdr plugin, as a gateway-owned operation (ADR 0012) the operation’s receipt not built
pi_extension an event to the session’s own Pi extensions over the RPC stream none not built

The manifest (hook_consumer Catalog entry)

# <catalog root>/hooks/porch-light/consumer.toml
id = "porch-light"
kind = "webhook"
hooks = ">= 1.0, < 2"                      # the contract range it speaks
boundaries = ["session.end.after"]
url = "http://127.0.0.1:8123/api/webhook/fox9-listening"
secret_env = "VULPINE_HOOK_PORCH_LIGHT_SECRET"
deadline_ms = 2000                         # the default; 1 to 10000
capabilities = ["house"]                   # ADR 0050 §2's closed set

Every field is closed: an unknown field refuses the manifest. The entry lives at catalog/hooks/<id>/consumer.toml under the runtime root, and its id matches its folder. boundaries lists at least one live boundary. A webhook needs url and secret_env. A script has command = "bin/on-event", a file inside the entry, in place of url; its secret_env is optional. capabilities takes values from the closed set network, files, write, house, messaging, agents, screen and memory. Installing an entry binds nothing. This build does not pin an entry by digest.

Registration

The loadout binds consumers to boundaries. The single-value form is valid:

[lifecycle.observe]
"session.start.after" = "admin_receipt"
"session.end.after" = ["admin_receipt", "catalog:porch-light"]

A consumer is admin_receipt or catalog:<id>. A boundary lists one to 4 consumers, each once. They are enqueued in the listed order and run independently. An absent boundary has no consumers.

Each Catalog consumer is admitted, and its delivery worker started, when a session binds. [hooks] user_consumers (default true) is the master switch: when false, no Catalog consumer is admitted or fires, and a loadout that names one still binds. The Admin’s Hook consumers card has a switch per consumer, kept in <state>/hook-consumers.json. It applies at once: a switched-off consumer’s attempts are dropped_unavailable.

Delivery

  • At the commit. The owner captures the boundary’s identity and makes one non-blocking enqueue per consumer onto that consumer’s bounded queue (capacity 64). It never awaits, never takes a contended lock, and never spawns on the connection task. The target cost is under 0.05 ms.
  • The identity. After the publication, the connection compares the identity it captured at the commit with its current one, then enqueues. A changed identity is dropped_invalid and nothing is enqueued.
  • The worker. A delivery worker per consumer runs the consumer and enforces deadline_ms. A script that outlives it is killed with its process group (timed_out). A webhook that does not answer in time is timed_out.
  • At most once. v1 has no retry. A consumer that needs every event reads sequence and treats a gap as a drop.

The receipt

One per attempt, in the trace (one hook_delivery row in the gateway’s hooks.jsonl trace) and the Admin (counts by disposition and the newest eight per consumer), never with the payload:

field values
delivery_id, invocation_id, boundary, consumer as in the event
disposition delivered, dropped_busy (queue full), dropped_invalid (identity changed or the event failed its own bounds), dropped_unavailable (consumer off, missing or unqualified), timed_out, failed (non-zero exit, non-2xx, connection error), rejected_store (admin_receipt only)
ms wall time of the attempt
detail at most 256 characters of diagnostics, no payload

Errors

The loadout parse refuses an unknown boundary, a consumer name that is neither admin_receipt nor catalog:<id>, an empty list, a consumer listed twice, and more than 4 consumers (too_many_consumers).

A Catalog consumer is admitted when a session binds. Its refusal names one reason: unknown_consumer (no such entry), boundary_not_declared, contract_unsupported, capability_undeclared (a webhook off loopback without network), manifest_invalid or transport_not_allowed (not http, or a host off loopback that [hooks] webhook_hosts does not list). Each refuses the bind as loadout_resolution_failed. A delivery’s failure is a receipt and never an error of the session.

The sample

catalog/hooks/session-log is a script consumer on both live boundaries: bin/on-event appends each event line to session-log.jsonl in VULPINE_HOOK_STATE_DIR. A loadout turns it on with "session.start.after" = ["admin_receipt", "catalog:session-log"] and the same for "session.end.after". The Admin’s Hook consumers card shows its deliveries and switches it off.

Compatibility

Versioned under ADR 0059 §5. A minor may add a boundary, a consumer kind, an optional event field or a reason value, and may widen a bound. It never removes or renames a boundary or a field, never changes when a boundary fires, and never adds a required field. A deprecated boundary keeps firing for two minor releases or 90 days, whichever is longer.

Was this page helpful?