> ## Documentation Index > Fetch the complete documentation index at: https://checkfu.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Events > Drive sessions, consume the ordered event log, resume live streams, and answer a parked run. Events are the durable truth of a [Session](/concepts/sessions-and-runs). Every persisted event has a globally unique ID and a monotonically increasing per-Session sequence number. Transcripts, traces, usage, and UI state are all projections of this log. ## Event envelope ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "evt_0123456789abcdef0123456789abcdef", "seq": 12, "schema_version": 45, "created_at": "2026-07-16T18:00:03.000Z", "type": "agent.message", "provenance": "narration", "presentation": { "canonical_type": "agent.message", "provenance": "narration", "known": true, "classification": "result", "visibility": "default", "coalescible": false, "notification": "new", "milestone": true, "terminal": false, "summary": "Agent message" }, "attested": true, "payload": { "content": "The repository contains three apps and one domain package." } } ``` Use `seq` for ordering within one Session. Use `id` to deduplicate at-least-once delivery across consumers. `schema_version` versions the envelope shape itself, independent of the dated wire version. Most current events, including the `agent.message` above, use v45; native `session.admitted` and native managed `run.created` events use v46. Version 46 is the highest supported envelope version, and Checkfu reads stored v1–v46 histories. ### Provenance `provenance` names **who witnessed** the fact. Every envelope returned by the list endpoint and the SSE stream carries exactly one of five values: | `provenance` | The fact was witnessed by | | ------------ | --------------------------------------------------------------------------------------- | | `wire` | the mandatory model gateway: model input and output observed at the plane boundary | | `exec` | the platform itself, watching a sandbox or tool operation | | `narration` | the Harness, accounting for its own activity (including connected-runtime observations) | | `human` | a person steering the Session: messages, interrupts, and decisions | | `platform` | the control plane, asserting a lifecycle or settlement fact | The `exec` lane is realized by one event type today, `exec.tool_invocation`, in the [event catalog](#event-catalog) below. Provenance is a read-side projection derived from the event type. It is never persisted, and it can never change sequence ordering, idempotency, settlement, retention, or replay. The stored log remains the truth. An event type the current classifier does not recognize arrives as `narration`, so new additive types stay readable by consumers that predate them. `narration` also remains the default display projection: a Harness's account of a turn is what you render, not the raw `wire` evidence beneath it. Connected-runtime narration may additionally carry `attested: true`. That literal means the Session verified the batch's detached Ed25519 signature against the runtime's registered current key before appending it. It strengthens the harness's self-report; it does not change its `narration` provenance into platform-witnessed `wire` or `exec` evidence. Unsigned connected batches remain valid and omit the field. ### Presentation `presentation` is a bounded product view derived from the canonical event and its provenance. It is never stored and never replaces `type`, `payload`, or `provenance`: | Field | Meaning | | ------------------------ | ---------------------------------------------------------------------------------------------- | | `classification` | `input`, `progress`, `question`, `decision`, `result`, `failure`, `lifecycle`, or `diagnostic` | | `visibility` | `default`, drill-down `detail`, or normally `hidden` | | `coalescible` | a consumer may replace an earlier progress rendering instead of adding a row | | `notification` | create `new`, `edit` an existing projection, or send `none` | | `milestone` / `terminal` | product significance and unconditional Session-terminal behavior | | `summary` | a bounded, content-free fallback label; read the canonical payload for authorized content | | `known` | whether this reader explicitly classified the exact type or open `span.*` family | Every closed current event has an explicit decision. Unknown future types still arrive with their canonical envelope and a conservative diagnostic presentation, so a product feed never drops evidence it does not yet understand. The SDK exposes the canonical iterator as `sessions.events.stream(...)`. When you want the ergonomic view, `streamPresented(...)` yields both values together: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} for await (const { event, presentation } of checkfu.sessions.events.streamPresented(sessionId)) { renderProductEvent(presentation) retainCanonicalEvent(event) } ``` ## Client drive events Post one of these bodies to `/v1/sessions/{id}/events`: * `user.message` * `user.interrupt` * `user.custom_tool_result` * `user.tool_confirmation` * `user.question_answer` * `user.define_outcome` Every human-authored drive event requires attribution: `authored_by` (the `PrincipalId` on whose behalf the event is authored) and `caused_by` (the cause; `{ "kind": "api" }` for a direct API call). An optional `surface_scope_id` may also be included. Managed [Harnesses](/concepts/harnesses-and-models) run asynchronously through a leased Runner and sandbox. (The quickstart's alpha echo harness happens to settle before the create call returns. Never depend on that; react to persisted events, not response timing.) `user.interrupt` succeeds while managed work is queued, actively running, or waiting on an outcome evaluation, Question, ActionApproval, or custom tool. Multiagent messages are asynchronous and never create a primary-thread wait. Interrupting an ActionApproval or custom-tool wait records the exact interrupted error result and returns the turn to idle without another model sample. A `user.message` posted while the Session's first Run is still queued or provisioning is accepted rather than rejected: it appends to the log immediately and is ordered for the next Run, so an application never has to wait for `running` before it can send input. `user.custom_tool_result` and `user.tool_confirmation` succeed only for the exact current `tool_use_id`; when `session_thread_id` is present they route through the primary Session to that child wait. `user.question_answer` succeeds only while the primary is waiting on the named Question. Sending a command in the wrong state, answering the wrong tool call or Question, or naming a wrong or stale child origin returns a conflict without advancing either thread. ### User message ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "type": "user.message", "payload": { "content": "Summarize the repository.", "attachments": [], "authored_by": "prin_0123456789abcdef0123456789abcdef", "caused_by": { "kind": "api" } } } ``` If Checkfu finds deceptive Unicode, the first request returns `400 validation.prompt_integrity_review_required` without appending an event. Its typed `error.review` contains the pinned analyzer version, normalized text, and exact findings, so API and SDK callers never need to reimplement Unicode analysis. Review that challenge, then resubmit the **original** content with one explicit choice: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "type": "user.message", "payload": { "content": "Review pаypal.com before continuing.", "prompt_integrity_disposition": "accepted_normalization", "authored_by": "prin_0123456789abcdef0123456789abcdef", "caused_by": { "kind": "api" } } } ``` Use `accepted_normalization` to let the server replace mixed-script confusables and remove bidirectional controls, or `preserved_original` to send the reviewed source exactly. Do not send the already-corrected string with a disposition: the server rejects a choice when its own analysis finds nothing, preventing consent from being replayed against changed text. The returned `user.message` contains the effective content and a server-authored `prompt_integrity` receipt. Requests with no findings omit both fields. Two more optional fields select delivery. `run_delivery: "next_run"` forces a message authored while a Run is running to begin the next Run instead of entering the current turn; omitting it takes native mid-Run delivery whenever that Run's recorded [capability set](/concepts/harness-extensions) realizes `mid_run_input: native`, and the next Run otherwise. Either way the harness's answer is durable: `run.input_delivered` records the acknowledgement, and the log — never response timing — decides which turn carried the message. `connected_runtime` belongs to connected Run admission; this route rejects a `user.message` carrying it with `400 validation.malformed`. ### Interrupt the current turn ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "type": "user.interrupt", "payload": { "authored_by": "prin_0123456789abcdef0123456789abcdef", "caused_by": { "kind": "api" } } } ``` Two optional fields narrow it. `target_event` names an API-authored `user.message` and fences cancellation to exactly that message: a still-queued next-Run control is retired without touching the current Run, and an already-promoted one interrupts only its own Run. An ID that names anything else is `400 validation.malformed`. `mode: "cooperative"` asks the running turn to drain instead of force-canceling it — finish the current tool, emit final consistent state, end cleanly — and is honored only when the Run's recorded capability set realizes `interrupt: cooperative`. An absent mode, a kill-only harness, a queued Run, and a targeted interrupt all keep the immediate `user.interrupt` → `run.canceled` → `session.status_idle` settlement. ### Return a custom tool result ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "type": "user.custom_tool_result", "payload": { "tool_use_id": "toolu_123", "result": { "approved": true }, "authored_by": "prin_0123456789abcdef0123456789abcdef", "caused_by": { "kind": "api" } } } ``` For a child wait, copy `session_thread_id` from the primary stream's `agent.tool_use` cross-post into the payload. Omit it only for a primary-thread call. Exact replay returns the same event; a conflicting result, wrong thread, or settled generation is refused. ### Confirm a tool action ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "type": "user.tool_confirmation", "payload": { "tool_use_id": "toolu_123", "result": "allow", "session_thread_id": "sthr_0123456789abcdef0123456789abcdef", "authored_by": "prin_0123456789abcdef0123456789abcdef", "caused_by": { "kind": "api" } } } ``` `result` is `allow` or `deny`; only `deny` may include a non-empty `deny_message`. This CMA-shaped event retains Checkfu's ActionApproval policy and responder-authority checks. Allowing a governed Custom tool emits `run.action_authorized` on the child but keeps it parked until the matching `user.custom_tool_result` arrives. ### Answer an agent question ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "type": "user.question_answer", "payload": { "question": "qst_0123456789abcdef0123456789abcdef", "answers": [{ "id": "target_branch", "values": ["main"] }], "authored_by": "prin_0123456789abcdef0123456789abcdef", "caused_by": { "kind": "api" } } } ``` A Question is ordinary input, not an [ActionApproval](/concepts/action-approvals): it grants no authority. `question` names the active Question, and `answers` must cover every item the matching `agent.question` requested, once each, honoring each item's `allow_multiple`. Partial, duplicate, and unknown item IDs are rejected. Textual answers cross the same deceptive-Unicode boundary as `user.message`: a flagged value returns `400 validation.prompt_integrity_review_required`, and the resubmission carries a payload-level `prompt_integrity_disposition` of `accepted_normalization` or `preserved_original`. ### Define an outcome ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "type": "user.define_outcome", "payload": { "description": "Write a release note for the completed change.", "rubric": "- explains user impact\n- cites verification evidence", "max_iterations": 3, "deliverables": ["/workspace/release-note.md"], "authored_by": "prin_0123456789abcdef0123456789abcdef", "caused_by": { "kind": "api" } } } ``` `user.define_outcome` starts an outcome-driven Run from a `pending` or `idle` Session. Only one outcome may remain nonterminal at a time. `max_iterations` is optional and must be between 1 and 20. `deliverables` is optional and accepts 1–32 absolute paths; a zero-data-retention Workspace rejects outcome definitions that request deliverables. ## Answering a parked run A Run does not fail when it needs something from you. It parks. This is the loop most integrations have to implement, and it is driven entirely by events. When a Run needs an answer it emits `run.requires_action` and the Session moves to `session.status_waiting`. The payload carries `run`, `attempt`, `cost`, and an `action` that discriminates on `kind`: | `action.kind` | Additional fields | How you answer | | -------------------- | ---------------------------------------- | -------------------------------------------------------------------------- | | `action_approval` | `approval`, `tool_use_id` | A reviewer responds through the ActionApprovals API. | | `custom_tool` | `tool_use_id` | Post `user.custom_tool_result` with the matching `tool_use_id`. | | `question` | `question`, `items[]` (no `tool_use_id`) | Post `user.question_answer` naming that Question and answering every item. | | `outcome_evaluation` | `outcome`, `iteration` | Nothing: the platform grades and resumes. | ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "type": "run.requires_action", "payload": { "run": "run_0123456789abcdef0123456789abcdef", "attempt": 1, "action": { "kind": "action_approval", "approval": "approval_0123456789abcdef0123456789abcdef", "tool_use_id": "toolu_123" }, "cost": { "tokens": 4120 } } } ``` A `question` wait is the one kind that also ends compute. The Runner releases custody at the yield and the Session moves through `waiting` to `paused`, so a Session can sit on an unanswered Question indefinitely without holding a sandbox. The parked Run stays in `requires_action` until an answer arrives; accepting one completes it and admits a fresh continuation Run that re-resolves mounts and receives the exact question and answers. Interrupting instead cancels the parked Run and returns the Session to `idle` with no continuation, so an unanswered Question cannot trap the Session. For an ActionApproval wait, `action_approval.pending` follows with the frozen decision context. A ToolInvocation ActionApproval carries the Connection, Tool identity, argument hash, and acting Principal: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "type": "action_approval.pending", "payload": { "approval": "approval_0123456789abcdef0123456789abcdef", "frozen_context": { "connection": "conn_0123456789abcdef0123456789abcdef", "tool": { "tool_source_id": "ts_0123456789abcdef0123456789abcdef", "name": "create_issue" }, "arg_hash": "sha256:9f2c1a4b7d3e5f6081920a3b4c5d6e7f8091a2b3c4d5e6f70819a2b3c4d5e6f7", "principal": "prin_0123456789abcdef0123456789abcdef" } } } ``` The ActionApproval **resource** exposes these same frozen facts under different names: `context_summary` and `arguments_hash` (see [ActionApprovals](/concepts/action-approvals)). Event consumers match on `frozen_context`/`arg_hash`; REST readers match on the resource names. A Custom-tool ActionApproval instead carries `kind: "custom_tool"` plus the exact Session, Run, tool-use ID, admitted AgentDefinition, logical harness tool, argument hash, and acting Principal. Its exact argument values remain in the preceding `agent.tool_use` event: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "type": "action_approval.pending", "payload": { "approval": "approval_0123456789abcdef0123456789abcdef", "frozen_context": { "kind": "custom_tool", "session": "sess_0123456789abcdef0123456789abcdef", "run": "run_0123456789abcdef0123456789abcdef", "tool_use_id": "toolu_123", "agent_definition": "agent_0123456789abcdef0123456789abcdef", "tool": "harness:create_issue", "arg_hash": "sha256:9f2c1a4b7d3e5f6081920a3b4c5d6e7f8091a2b3c4d5e6f70819a2b3c4d5e6f7", "principal": "prin_0123456789abcdef0123456789abcdef" } } } ``` Once a reviewer decides, `action_approval.resolved` records the decision (`approve` or `deny`), the `tool_use_id` it answers, who resolved it, and any reviewer instructions. Gateway decisions and Custom-tool denials emit `run.resumed` and create the normal continuation. A Custom-tool approval instead emits `run.action_authorized`; the same Run remains parked until the application submits its matching `user.custom_tool_result`. Key the wait loop off `run.requires_action`, not off `session.status_waiting`. The status event tells you the Session is parked; only the action payload tells you **what** it is parked on and which `tool_use_id` to answer. See [ActionApprovals](/concepts/action-approvals) for the review side of this flow. ## Event catalog Every event type the current contract can append. Consumers must tolerate unknown types: the catalog grows with the platform, and a new event type is not a breaking change. ### `user.*` * `user.message`: a human input; starts a turn (or steers a running one) * `user.interrupt`: ends work without making the Session terminal; optional `session_thread_id` targets one thread, while omission interrupts every non-archived thread * `user.custom_tool_result`: your app returning the result of a custom tool the Run parked on * `user.tool_confirmation`: allows or denies the exact current tool wait; optional `session_thread_id` routes a child confirmation through the primary Session * `user.question_answer`: a human answering one active `agent.question`, which admits a continuation Run * `user.define_outcome`: attaches a rubric-graded definition of done to the next turn ### `system.*` * `system.message`: mid-conversation system-privileged context appended *beside* the Agent's frozen system prompt, which it never replaces. Unlike a title or the metadata bag, the content is the point — an agent that cannot read it is not steered by it — so the text lives in the event and is retained content like a user message (up to 8,192 characters). No instruction changes and no release hash moves. It is admitted only from a control-plane role, never a runtime credential, and only where the admitted model route can carry a mid-conversation system turn ### `agent.*` * `agent.message`: the agent's reply text (`payload.content` is what you show users) * `agent.thinking`: reasoning content, when the harness surfaces it * `agent.tool_use`: the agent invoked a tool * `agent.tool_result`: what the tool returned * `agent.question`: a structured request for ordinary human input: one `question` ID and one to four uniquely identified `items`, each with bounded `options` and single- or multi-value semantics. Prose that reads like a question stays an ordinary `agent.message` * `agent.subagent_started` / `agent.subagent_completed`: a harness-internal subagent, observed but not governed * `agent.thread_message_sent`: one durable direction-relative send; carries bounded `content`, `to_session_thread_id`, and optional `to_agent_name` * `agent.thread_message_received`: the matching receiver-side fact; carries bounded `content`, `from_session_thread_id`, and optional `from_agent_name` ### `message.*` * `message.screened`: a delivery screen passed or withheld an outbound agent message; screens never rewrite content ### `flow_review.*` * `flow_review.requested`: one passive post-settlement review was frozen for an Automation-origin Turn * `flow_review.started`: the bounded evidence and one-attempt review lease were acquired * `flow_review.completed`: a cited typed report settled; it never changes the Outcome, delivery, or Session state * `flow_review.unavailable`: retained evidence or reviewer authority could not produce a report after the bounded policy ### `session.*` * `session.status_pending` … `session.status_canceled`: the ten status transitions, including compute-closed `session.status_reconciling`; see the [state machine](/reference/sessions#session-status) * `session.admitted`: admission settled, carrying the frozen release, requester, and (if installed) placement * `session.forked`: appended after the inherited source prefix as the forked Session's first new event. **Private alpha** for committed-head, exact-`at_event`, and live-Checkpoint forks. Its payload names `source_session`, `through_event`, `through_sequence`, the nullable target `checkpoint`, and `mode: "event_log_rebuild" | "checkpoint_clone"`. A Checkpoint fork preserves the inherited log prefix and independently clones the provider snapshot; it never copies a live Run, lease, wait, or ActionApproval. * `session.updated`: mount declarations changed at a turn boundary * `session.title_updated`: content-free `{ present }` marker for a material title projection change * `session.metadata_updated`: the correlation bag settles like a title — a content-free `{ pairs }` count of how many pairs the Session now carries. Keys and values are your text and never enter the log * `session.mounts_resolved`: the exact revisions and trees this Run received * `session.compacted`: context was compacted; the log itself is never rewritten * `session.context_condensed`: a context-window boundary was recorded; later conversation rebuilds serve an elision marker plus the tail after it, and each boundary also projects into the optional `condensations` array of `GET /v1/sessions/{id}/ledger` * `session.thread_created`: a governed child thread received its stable `sthr_*` identity * `session.thread_status_running`: a child thread began or resumed execution * `session.thread_status_idle`: a child thread yielded and remains addressable; its `stop_reason` is `end_turn`, `requires_action`, or `retries_exhausted` * `session.thread_status_rescheduled`: a bounded retry is pending for the same thread * `session.thread_status_terminated`: a child thread was archived or failed terminally * `session.delivery_ambiguous`: reserved by the built next-version Session delivery protocol for an outbound WebhookEndpoint POST whose acknowledgement may have been lost. The currently selected Session architecture does not emit it; the event names only structural delivery, endpoint, and event coordinates and is excluded from the webhook subscription catalog to prevent recursive delivery * `session.archived`: content-free marker that the Session left the working directory; its timestamp is the resource's `archived_at` (see [Archive a session](/reference/sessions#archive-a-session)) ### `watch.*` A [Watch](/reference/sessions#watches) is a Session-owned subscription to external provider state. * `watch.created` / `watch.updated` / `watch.removed`: the Watch's lifecycle, each naming the `watch` * `watch.woken`: a verified change in the watched state admitted an ordinary next Run; carries the `source_state_hash` that settled the wake * `watch.suppressed`: a hint that woke nothing, with `reason: duplicate | self_authored | stale_hint | unsafe_content` ### `memory.*` * `memory.mount_resolved`: which store, revision, and access level a Run mounted * `memory.accessed`: emitted once per store that sealed a writeback at settlement (its content-addressed base was read); pure-read-mount coverage is a pending revisit * `memory.change_checkpointed`: a settlement seal naming the changed paths written into the store's durable document surface, with content-addressed `base`/`new` tree digests (the versioned revision graph stays alpha behind `MEMORY_VERSIONED_SURFACE`, so these are digests, not graph revision IDs) * `memory.proposal_created` / `memory.proposal_resolved`: the shared-store review flow * `memory.curated`: a Dream landed curated content * `memory.redacted`: an erasure, recorded as history rather than hidden ### `project.*` * `project.writeback_captured`: the Session accepted one exact sealed changed manifest and entered compute-closed reconciliation * `project.writeback_started`: the compute-free reconciler acquired the durable publication generation * `project.writeback_no_changes`: a complete tree enumeration proved the mounted Project was unchanged * `project.writeback_succeeded`: the owned branch, pull request, exact frozen `base_revision`, published immutable `revision`, capture retirement, and—when D127-eligible—reused Watch settled * `project.writeback_conflicted`: the target, owned branch, or pull-request identity diverged; Checkfu did not force-push or retry over human work * `project.writeback_failed`: strict capture, authority, provider, or publication failed rather than silently dropping edits ### `model.*` * `model.routed`: which provider/model candidate answered this call * `model.usage_recorded`: the authoritative token receipt for one model call ### `wire.*` * `wire.call`: one gateway-witnessed model request and response, retained as evidence The event row carries no model bytes. It names the Run, attempt, request ID, binding, provider, model, and usage, plus typed references to the exact material: the admitted request body, each ordered request message, the response body, and the provider frames. Every reference is `{ source, content_digest, bytes }`, where `content_digest` is a `sha256:` digest, so repeated history resolves to objects that already exist and only an operator can [resolve one back to bytes](#resolve-retained-wire-content). `wire.call` is evidence, not display: it sits in the ordinary Session sequence and appears in exports at its original position, but the Harness's narration remains the conversational projection you render. A zero-data-retention Workspace constructs no wire evidence at all. The missing `wire.call` events *are* the visible capability difference. Retained wire bytes also carry a mandatory 30-day absolute retention ceiling, even where the Workspace's standard policy has no TTL at all; a shorter Workspace or `wire_frame` TTL still wins. After expiry the references remain structurally in the event, and resolving one returns `404`. ### `exec.*` * `exec.tool_invocation`: one governed ToolInvocation, settled and witnessed by the platform itself The payload is structural only: Run and attempt identities, `tool_invocation_id`, the associated resource identities and logical tool name, `execution_backend` (`builtin`, `executor`, or `connector`), `disposition`, an `argument_fingerprint` that hashes the canonical logical arguments rather than carrying them, and claim-to-settlement duration. `connector` means the pinned tool ran through the provider-neutral Integration Gateway; it does not identify the selected runtime adapter. No argument or result body ever appears, so unlike `wire.call` this event persists unchanged under zero data retention. `disposition` is `completed`, `denied`, or `indeterminate`. At most two `exec.tool_invocation` events exist for one `tool_invocation_id`: the settlement, plus at most one later corrective event carrying `upgrade: true`, which marks an already-settled outcome `indeterminate`. ### `run.*` * `run.created`: admission accepted work; carries the trigger * `run.started`: an executor actually began * `run.start_timed_out`: a claimed attempt missed its ready deadline and was requeued before it could start * `run.attempt_requeued`: a *started* attempt released its native Checkpoint and was replaced, without changing the customer-visible logical Run. `recovery` is one-based and the current aggregate admits exactly one, so this appears at most once per Run * `run.requires_action`: parked on an approval, custom tool, Question, or outcome evaluation (see `action.kind`) * `run.action_authorized`: a Custom-tool ActionApproval authorized customer execution; the same Run now awaits its exact application result * `run.resumed`: the awaited action arrived; a continuation is executing * `run.input_delivered`: the harness answered a steering `user.message` delivered into the running turn, naming that `event` and a `disposition` of `delivered`, `queued`, or `refused`. This record, not the transport acknowledgement, is the delivery authority: `delivered` and `queued` fence the message to this Run, and `refused` leaves it to be promoted into the next one * `run.lifecycle_hook`: one reviewed sandbox lifecycle-hook command settled — phase, ordinal, exit class, duration, the declared `on_failure`, and a bounded tail of its output; the event, not the Runner's memory, is the settlement authority, so a failed verification hook is recorded rather than passed silently * `run.completed` / `run.failed` / `run.canceled`: terminal settlement; the usage receipt keys off this event ### `action_approval.*` * `action_approval.pending`: a frozen call awaits a human decision * `action_approval.resolved`: the decision, responder, and any instructions ### `outcome.*` * `outcome.evaluation_started`: the grader began judging a settled revision * `outcome.evaluation_completed`: the verdict, one of five results, with rationale and cost ### `span.*` Telemetry adapters mint their own span names, so `span.` is an open family rather than a fixed list. Spans are best-effort telemetry and never carry enforcement meaning; a consumer that does not recognize a span type should ignore it. ## List persisted events ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} GET /v1/sessions/{id}/events?limit=100&page= ``` `limit` defaults to 100. Values greater than 1000 are capped at 1000; zero, negative, fractional, or nonnumeric values return `400 validation.malformed`. The response contains readable envelopes in `data`, content positions that cannot be produced in `unavailable`, and `next_page`. An unavailable entry names the original `seq`, content class, and `shredded` or `zdr` reason. A reviewed ZDR prompt may additionally expose only its analyzer version and author disposition, never the prompt, source digest, or findings. This endpoint budgets a page by owned-log positions, not only readable events. A page can therefore have an empty `data` array and non-empty `unavailable` array. Its cursor is the last processed per-Session sequence number; continue until `next_page` is `null`. ## Replay and follow over SSE ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} GET /v1/sessions/{id}/events/stream Accept: text/event-stream ``` On connection, the current alpha replays every persisted event after the cursor in internal pages and then stays live. Send the last processed sequence in `Last-Event-ID`, or pass the same cursor as `page`: ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --no-buffer \ "https://api.checkfu.com/v1/sessions/$CHECKFU_SESSION_ID/events/stream" \ --header "Authorization: Bearer $CHECKFU_API_KEY" \ --header "Checkfu-Version: 2026-08-27" \ --header "Last-Event-ID: 12" ``` ```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} // `lastEventId` is the last fully processed `seq`, the same value the // `Last-Event-ID` header carries. Omit it to start from the beginning of the // Session; the client reconnects and resumes from its own cursor either way. for await (const event of checkfu.sessions.events.stream(sessionId, { lastEventId: 12, })) { handle(event) } ``` `CHECKFU_API_KEY` and `CHECKFU_WORKSPACE_ID` come from [Get access](/reference/access); `CHECKFU_SESSION_ID` is the Session you are tailing. Reconnect after the connection closes or a network failure and provide the last fully processed sequence. Pull-driven backpressure keeps at most one internal page in flight for a stalled consumer; reconnecting from `Last-Event-ID` resumes from the durable log. The SDK rejects replayed or reordered durable sequences instead of yielding duplicates. If retention or ZDR leaves unreadable positions before the next readable event, the server emits a cursor-neutral `checkfu.cursor_gap` control frame. The SDK stops with `EventStreamCursorGapError`, whose `from`, `through`, and `next` fields identify the omitted range. Record or resolve that omission through the paged event ledger's `unavailable` entries before explicitly starting a new iterator from `through`; the SDK never skips evidence loss automatically. ### Opt in to live previews Repeat `event_deltas` to request best-effort previews for the currently running turn: ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} GET /v1/sessions/{id}/events/stream?event_deltas=agent.message&event_deltas=agent.thinking ``` The stream first replays durable events through the requested cursor, then may emit these additional frames while it follows live work: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} event: event_start data: {"type":"event_start","event":{"id":"evt_0123456789abcdef0123456789abcdef","type":"agent.message"}} event: event_delta data: {"type":"event_delta","event_id":"evt_0123456789abcdef0123456789abcdef","delta":{"type":"content_delta","content":"The repo","index":0}} ``` `agent.message` emits `event_start` followed by content deltas. `agent.thinking` emits `event_start` only; its content remains available in the final durable event when the harness provides it. If the corresponding observation commits, the `agent.message` or `agent.thinking` envelope uses the same event ID, so a client can replace its preview with the committed result. Preview frames carry no SSE `id:` line, no `seq`, and no `provenance`. They never advance `Last-Event-ID`, never appear in event lists or replay, and may be dropped for a disconnected or stalled consumer. A failed, interrupted, or lease-lost turn can leave a preview without a final event; discard unmatched previews when the turn settles. After a transparent SDK reconnect, the iterator yields `{ type: "preview_reset", reason: "reconnect" }`; clear every unmatched preview before applying subsequent frames. A non-SDK client clears them at its observable HTTP reconnect. Always render the final durable event as authoritative. A DeliveryScreen agent does not expose `agent.message` previews because content has not yet passed its release-pinned screen. ## Resolve retained wire content ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} GET /v1/sessions/{id}/events/{event_id}/content?digest=sha256: ``` Returns the exact retained bytes as `application/octet-stream`. This route is the only way wire material crosses HTTP, and it is deliberately narrow: the key must hold an `admin` or `root` role (anything else is `403 policy.denied`), and the digest must be one the named `wire.call` event actually references. A digest that the event does not name, or whose bytes have passed their retention ceiling, is `404`. There is no browsable index of retained content, and internal storage identifiers never appear on the wire. ## Next steps Handle disconnects, duplicates, and backpressure without losing or double-processing events. Fold the stream into named views: messages, tool calls, ActionApprovals, the subagent tree, and the context ledger.