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 are easy to get wrong: 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 0.10.0 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.

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, history.batch chunks during history synchronization, and the schema-defined incomplete.codon. There are 4 types, with both category defaults set to false.

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 may be {currency, limit, used}, and loop.iteration.completed.terminationReason takes the values iteration_limit, context_exceeded, sentinel_skip, or failure.

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 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. Journal storage, query APIs, storage backends, and the distinction between the journal and the WebSocket log belong to integrate/event-journal.

## Routing summary (journaled / sentinelRouted)

| category | journaled | sentinelRouted |
|---|---|---|
| server-state | true | true |
| agentic-backbone | true | true |
| sentinel | true | false |
| connection-state | false | false |

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 0.10.0 server source.

Two 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 at run end before RunCompleted or RunFailed, so terminal-event watchers receive it first; its payload fields are ceiling, allocation, rows, and totals.

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.

 *
 * 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 same spelling uses a hyphen, not the old underscore form completing_sentinels.

The state can also appear in failedDuring when checkpoint creation fails during that phase. failedDuring is a snapshot field on a failed codon and has five values: preparing, starting, initializing, running, and completing-sentinels. Keep the three related concepts distinct: StateTransition is a separate event-driven persistence layer with 14 transition types, CodonStatus is the codon lifecycle, and failedDuring is a snapshot field on a failed codon.

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 catalog above has 36 server events; the exported client-command type definition has 13 command types:

• codon.start
• codon.next
• codon.skip
• codon.redo
• codon.forceStop
• server.shutdown
• checkpoint.list
• rollback.toCheckpoint
• rollback.toCodon
• rollback.toLastSuccess
• ping
• ping.broadcast
• history.sync

These commands are documented at integrate/protocol, not in this event catalog. Commands travel from the client to the server over the WebSocket and are never written to the event journal; journaled events are appended to .hankweave/events/events.jsonl.

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. The terminal UI also constructs synthetic local copies for its display; those client-side values are not server events and are excluded from this catalog.

server.force_shutdown is parsed in command-schemas.ts and included in the runtime's read-only allowlist, but it is absent from the exported clientCommandSchema union. This source contradiction is a release-integrity note, not an additional event row; this page does not infer whether a client may send it.

Where related topics live#

• Event journal – journal storage and queries.
• 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 and process outcomes.