Events

Kraft records what happens to a work item as a list of events, its timeline. This page lists every event type, grouped as the contents list shows, and the notification webhook that sends them.

Every event has these fields:

Before 2.0, an event carried no node_id of its own. The upgrade filled it only from a payload's node_id or node key, so a gate's older events in an upgraded database keep null: they named their node under gate.

Read the events with kraft view events:

The tables list each type and the payload fields you are most likely to use. A payload can carry more fields than these. Event types and payloads are not a stable interface: a release can add, rename or reshape them.

Work item

work_item_archived

work_item_needs_human

This is the event behind stop_reason in kraft view show --json, and behind "why did it stop" on the board. Its fields:

Stop kinds

kind is also the value stop.kind takes on the HTTP API. Why did my item stop? gives each stop's fix.

stop.kind takes three more values. They come from the item's status, not from this event:

The facts field

What facts carries depends on the stop:

On an infra stop, cause is one of:

• crash: the executor task crashed.
• stranded: a claim that no walk took over.
• ci_infra: CI infrastructure failed and retrying did not recover it.
• git: the worktree refresh failed.
• forge_auth: the forge refused the credential.
• forge_unreachable: the forge could not be reached.

For forge_auth and forge_unreachable, the git or forge error says so. A forge task's own failure carries one of these two the same way, on its failed stop, or on its infra one in a node with a fix loop. Other infra stops name no cause.

Chain and nodes

sweep_failed

Kraft could not commit the work because:

• the commit failed;
• the worktree was not on the item's branch;
• the worktree held a git operation Kraft did not start; or
• the worktree held a repository Kraft did not create.

sweep_left_out

After an agent task, Kraft commits the work the task left, but not the installs the repo's setup made. The event names the paths it left out. It is written only when that set differs from the item's last sweep_left_out, not after every task.

Kraft leaves out:

• a lockfile the repo's setup command wrote and nobody changed since (uv sync in a repo that commits no uv.lock);
• a virtualenv or node_modules the repo does not ignore. A node_modules the setup command made counts whatever is in it: bun leaves no marker.

Kraft commits, as the agent's work:

• a lockfile the agent writes, or an edit it makes to the setup's;
• a node_modules the setup did not make with no package manager's marker in it (.package-lock.json, .modules.yaml, .pnpm, .yarn-integrity, .yarn-state.yml), even beside a package.json;
• a pyvenv.cfg with no python beside it.

Gates and review

by is human (the board or the kraft command), assistant (an agent through the MCP server), agent (a Kraft worker, such as a gate's review agent) or kraft (Kraft itself).

Agent sessions

Caps, budgets and limits

Escalation

Forge, CI and waits

Sandbox

A workspace item records one sandbox_branch_not_synced for each repository whose branch did not move, and its reason names that repository.

Settings changed

Before 2.0, a chain was a chain template. chain_template_changed, and the chain_template key of work_item_created, keep that name, and both hold chain ids.

Reading events as they happen

WS /api/ws/events

Streams every work item's events as they are stored. The board and kraft view watch read it. Unlike GET /api/work-items/{id}/events, it is not limited to one item. It first replays the stored events after after_seq, then sends each new event once, with none lost or repeated between the two.

Each frame is one JSON text message. An event frame has the fields in the table above, {seq, work_item_id, type, payload, node_id, created_at}. A live message has {"frame": "live", "type", "payload", "created_at"} and no seq.

A client authenticates as for the HTTP routes: who may call. A peer on this machine needs nothing while Kraft is bound to loopback. Otherwise send the MCP bearer token as Authorization: Bearer <token>, or the session cookie from the login page. The trigger token is not accepted. The Host and Origin rules of the HTTP routes apply too.

A refused connection closes before it is accepted, so a real client sees the handshake fail with HTTP 403, not a close frame. A test client reports it as close code 1008. The causes are no valid credential, a remote caller while no password is set, a Host that is not allowed, and an Origin from another site.

Live messages

A client of WS /api/ws/events that connects with live=1 also receives messages that are not events. They are {"frame": "live", "type", "payload", "created_at"}, have no seq, are sent once to whoever is connected and are neither stored nor replayed after a reconnect. A client that does not ask for them never sees one.

Notifications

notify.yaml sends an HTTP POST to a webhook when an event you name happens. Set it on the Settings screen, or edit the file:

enabled: true
url: https://hooks.example.com/abc123   # a secret; Kraft never shows it back
base_url: https://kraft.example.com     # where links in the message point
events: [gate_requested, work_item_needs_human]

notify.yaml lists the fields, and what events accepts. Get notified when an item needs you sets it up.

The body is JSON:

{
  "work_item_id": "<work-item-id>",
  "title": "Fix the flaky login test",
  "type": "gate_requested",
  "gate": "spec_approval",
  "url": "https://kraft.example.com/work-items/<work-item-id>"
}

gate is null for an event that is not about a gate.

• Kraft sends at most one message per work item every 10 seconds. A second matching event in that window sends nothing.
• A send that times out after 5 seconds, errors, or gets a status of 400 or more is tried once more after 2 seconds. If that fails too, Kraft records a notification_failed event on the item.
• Events that happen while the server is down send nothing when it comes back.
• The Settings screen's Send a test posts "type": "test" with a nullwork_item_id and gate.

Related

• Why did my item stop?: each stop's reason and its fix.
• Work item statuses: the statuses the events move an item between.
• Budget, events, diff and documents: reading a work item's events over HTTP, paged forward or backward. The WebSocket is WS /api/ws/events above.
• Inbound triggers: the other direction, starting a chain from outside.