Events

Hankweave reports everything that happens during a run as a stream of typed events. Each event records one fact: a codon started, a tool returned a result, a sentinel fired, a rollback completed. Clients receive these events over the WebSocket, journaled categories are appended to disk, and sentinels subscribe to a filtered subset of the same stream.

This page is the lookup catalog for that stream. It lists all 36 server event types with their payload fields, explains the four categories that determine where each event goes, shows representative envelope shapes, and covers the boundaries that most often surprise consumers: which events are journaled, which reach sentinels, and why client commands are not events at all.

Every event type in one table#

Events record codon execution and agent activity. A codon is one agent task; a rig prepares its workspace and runs setup commands. A sentinel observes the events routed to it. Those three terms appear throughout the payload fields below.

Read the table as follows. The id column is the dot-separated event type literal, the value that appears in the envelope's type field. category is one of server-state, agentic-backbone, sentinel, or connection-state; the next section explains what each category implies. journaled and sentinelRouted are booleans describing the two routing decisions covered later on this page. In payloadFields, a trailing ? marks an optional Zod field. The receipts column points at the schema definitions and emission sites in the shipped source.

Every event envelope has id, an ISO 8601 timestamp, a literal type, and an event-specific data object carrying the payload fields listed here.

Two payload shapes in the table deserve a closer look. The file.updated row lists path, filename, action, sha256, bytes and source – six fields and no inline content; the file-level payload contract version is EVENT_SCHEMA_VERSION = 2. source is { kind: "tool_use", toolUseId } for a file the agent wrote, or { kind: "codon-start" } for one present when the codon started. The assistant.action row shows toolName? and toolUseId?, but the wire schema refines the base shape: when action is "tool_use", toolUseId must be a non-empty string and toolName must be present. Those two fields are the join keys to tool.result.toolUseId and file.updated.source.toolUseId. For thinking and message actions, both may be absent.

Per-event introduction markers are not present in this catalog. Adding them requires comparing serverEventSchema across tagged releases.

How events are categorized#

Category membership is inferred at runtime from set membership, rather than stored as an explicit event field. Compile-time checks require every member of the event union to belong to exactly one category. The category matters because it sets the defaults for journaling and sentinel routing, so it is the first thing to check when an event does not appear where you expected it.

Server-state events track the execution lifecycle: codon start, completion, and extension; rollback; budgets; state and checkpoints; errors and information; idle state; loop iteration completion; and archive operations. There are 20 types, with category defaults journaled: true and sentinelRouted: true.

Agentic-backbone events capture what the agent actually does: assistant actions, tool results, file and filetree updates, rig setup completion or failure, and rig output. There are 7 types, with both category defaults set to true. Two volume limits apply here: rig.output is throttled to at most one event per second per stream and each line is truncated to 500 characters, and the default toolResultTruncateLength for tool.result content is 2500 characters.

Sentinel events cover loaded, triggered, output, error, and unloaded states. There are 5 types. They default to journaled: true and sentinelRouted: false, so they remain available for audit without being fed back to sentinels.

Connection-state events are client-specific and ephemeral: server.ready for the connecting client after the handshake, pong responses to ping and ping.broadcast, and history.batch chunks during history synchronization. There are 4 types, with both category defaults set to false; the fourth, incomplete.codon, is declared in the schema and rendered by the terminal UI but never emitted, so a client never receives one.

The generated table above is the lookup for each event's payload fields. Two non-obvious shapes are worth knowing before you write a consumer. codon.completed.budgetExceeded is {currency, limit, used} and is set whenever a budget cap tripped during the codon, on completed and failed codons alike: under the default onExceeded: "complete" the event still has success: true, while under "fail" it has success: false with a Budget exceeded: … failure reason. loop.iteration.completed.terminationReason is optional: the runtime sets it only on a loop's final iteration and only to context_exceeded or iteration_limit; sentinel_skip and failure are allowed by the schema enum but never sent.

The examples below show one representative envelope per category. Values are placeholders, and optional fields are omitted; the data object is where the per-event payload fields from the table live.

Server-state – state.transition

{
  "id": "<event id>",
  "timestamp": "<ISO 8601 timestamp>",
  "type": "state.transition",
  "data": {
    "transitionType": "<transition type>",
    "runId": "<run id>",
    "codonId": "<codon id>",
    "transition": "<transition>",
    "resultingState": "<resulting state>"
  }
}

Agentic-backbone – assistant.action

{
  "id": "<event id>",
  "timestamp": "<ISO 8601 timestamp>",
  "type": "assistant.action",
  "data": {
    "codonId": "<codon id>",
    "action": "<action>",
    "content": "<content>"
  }
}

Sentinel – sentinel.output

{
  "id": "<event id>",
  "timestamp": "<ISO 8601 timestamp>",
  "type": "sentinel.output",
  "data": {
    "sentinelId": "<sentinel id>",
    "codonId": "<codon id>",
    "triggerNumber": "<trigger number>",
    "outputType": "<output type>",
    "content": "<content>",
    "cost": "<cost>",
    "tokens": "<tokens>",
    "eventCount": "<event count>"
  }
}

Connection-state – pong

{
  "id": "<event id>",
  "timestamp": "<ISO 8601 timestamp>",
  "type": "pong",
  "data": {
    "message": "<message>",
    "timestamp": "<ISO 8601 timestamp>"
  }
}

Note that the sentinel and connection-state envelopes have the same outer shape as the others. The category differences are in routing, not in structure.

Which events are journaled#

A journaled event is appended, while a run is live, to <execution>/.hankweave/events/events.jsonl as one JSON object per JSONL line. Appends are serialized in emission order; the journal is not timestamp-sorted. EventJournal.append() rejects non-journaled categories. A finished run may leave that plain journal or a dieted form, and the file-level eventSchemaVersion is recorded in events.meta.json while the journal is live and in journal.meta.json after a diet; the format, sidecar and diet contract belong to integrate/event-journal.

## Routing summary (journaled / sentinelRouted)

| category | journaled | sentinelRouted | member array |
|---|---|---|---|
| server-state | true | true | `schemas/event-schemas.ts:1073-1094` |
| agentic-backbone | true | true | `schemas/event-schemas.ts:1099-1107` |
| sentinel | true | false | `schemas/event-schemas.ts:1112-1118` |
| connection-state | false | false | `schemas/event-schemas.ts:1123-1128` |

The summary table shows the category defaults: server-state, agentic-backbone, and sentinel events are journaled; connection-state events are not. Three cases sit outside the plain defaults. An error with a target client is sent to that client and bypasses the journal; the broadcast form remains a journaled server-state event. history.batch bypasses emit() and is sent directly to a client. incomplete.codon has no construction site in the shipped server source.

Three journaled events deserve attention when you consume the journal. state.transition records every StateManager transition and is the audit trail for state-machine changes; its transition type has 14 values, from RunStarted through SentinelStatesUpdated. budget.summary is emitted only from a graceful shutdown, only when a budget is configured and the run is still current, and it precedes that shutdown's RunCompleted or RunFailed; a run failed by a codon or output-copy failure, or ended by a force shutdown, ends with no budget.summary. And file.updated no longer fires for reads: only Write, Edit and MultiEdit are watched, so a read no longer emits a file.updated with action "modified".

Which events reach sentinels#

server-state and agentic-backbone events reach sentinels; sentinel and connection-state events do not. setupSentinelEventRouting() forwards only the first two categories to sentinelManager.handleEvent. Sentinel lifecycle events are excluded so a sentinel does not observe its own lifecycle events, and connection-state events are excluded because they are client-specific. The sentinelRouted column in the catalog records this filter's result; it describes the sentinel feed, not client delivery.

See Sentinels, Sentinel configuration, and Protocol for the observer and transport contracts.

Codon lifecycle#

Many of the server-state events report a codon moving through its lifecycle, so the canonical states are reproduced here from the source.

/**
 * Codon execution status progression.
 *
 * Normal flow: preparing → starting → initializing → running → completing-sentinels → completed
 * Can skip to "failed" or "skipped" from any non-terminal state.
 *
 * Intent: Track granular progress for better crash recovery and user feedback.
 */
export type CodonStatus =
  | "preparing" // Rig setup running (copy files, run commands)
  | "starting" // Spawning Claude process
  | "initializing" // Process started, waiting for session ID
  | "running" // Claude is working (have session ID)
  | "completing-sentinels" // Completing sentinel work (draining queues)
  | "completed" // Success - terminal state
  | "failed" // Failed - terminal state
  | "skipped"; // User skipped - terminal state

The codon lifecycle has eight values: preparing, starting, initializing, running, completing-sentinels, completed, failed, and skipped. Its normal flow is preparing → starting → initializing → running → completing-sentinels → completed. completing-sentinels drains sentinel queues after the agent process exits and before the codon is marked terminal. The spelling uses a hyphen, not the underscore form completing_sentinels carried by some older documentation.

Three related concepts are often conflated. StateTransition is a separate event-driven persistence layer with 14 transition types; CodonStatus is the codon lifecycle above; failedDuring is a snapshot field on a failed codon with five values: preparing, starting, initializing, running, and completing-sentinels.

failedDuring: "completing-sentinels" is written only when a failure reads the live status during the sentinel drain: a force stop (exit code -1) or crash recovery of a run left in that phase. When checkpoint creation fails, the recorded value comes from a codon record read before the move to completing-sentinels, so it holds the earlier status, normally running. The comment in the state-types source that says a checkpoint failure can record completing-sentinels does not match the code.

See Codons, Execution flow, and State file.

Commands are not events#

A client command travels from a client to the server; an event travels from the server to clients. The command catalog – 14 commands, including server.force_shutdown – is owned by integrate/protocol, and this page catalogs only the 36 server events. Commands travel over the WebSocket and are never written to the event journal; journaled events are appended to the journal a run writes while it runs.

One name appears on both sides and causes real confusion. The checkpoint.list command requests a list; the checkpoint.list server event carries runId, checkpoints, and currentBranch in response. Only the server constructs the event: the runtime emits it in reply to the command, and the terminal UI sends the command without building an event of its own.

Where related topics live#

• Event journal – journal storage, queries, and the dieted form.
• Protocol – client commands, connection framing, and event transport.
• Client and exported types – client-facing package types.
• Sentinels – the observer model.
• Execution flow – codon lifecycle context.
• State file – persisted state shapes.
• Execution directory – runtime paths.
• Runbook – operational recovery and inspection.
• Errors and exit codes – failure classification, failureReason, and process outcomes.