@sema-agent/core 7.6.0 → 7.6.1

package/dist/core/task-event.d.ts

@@ -0,0 +1,910 @@
+/**
+ * The WIRE frames: the `TaskEvent` union every consumer switches on, and every satellite it
+ * discriminates with — the per-message identity envelope, the brain-status phases and retry classes,
+ * the tool activity beat, the human-input source/delivery words, the delegation task type, the
+ * human-input projection and the compaction outcome. This is the file a change to a frame touches, and
+ * nothing else. Layer 0 vocabulary; `types.ts` re-exports every name below, so no consumer's import
+ * changes.
+ */
+import type { ActorAssertion } from "../internal/llm.js";
+import type { TaskResult } from "./task-result.js";
+import type { TaskNotificationPayload } from "./task-notification.js";
+/**
+ * Identity fields carried by every CONTENT event of a task stream (design/99 §E2 — lightweight message
+ * identity). Both are OPTIONAL and ADDITIVE; a consumer that ignores them is unchanged.
+ *
+ * - `eventId` — a core-minted, time-sortable (uuidv7) unique id stamped on each emitted content event. Gives
+ *   a live UI a stable handle to correlate/dedup streamed events and to map its own client-side message ids
+ *   back to a core anchor. (The durable-anchor mapping for resume-at — which eventIds are restartable
+ *   transcript positions — is finalized by the E18 `resumeAt` seam; this field is the stable handle it builds on.)
+ * - `parentToolCallId` — present ONLY when this task runs as a sub-agent spawned under a parent task's tool
+ *   call (threaded via the trusted `RunInternals.parentToolCallId`, sourced from the spawning tool's
+ *   `ToolExecuteContext.toolCallId`). Lets a consumer attribute streamed content to the delegation subtree it
+ *   belongs to WITHOUT core physically merging the child stream into the parent (the child's RESULT still
+ *   re-enters the parent MODEL context only through the `delimitUntrusted` fence — observability threading and
+ *   model-context isolation are kept separate, so prompt-cache and the injection boundary are untouched).
+ */
+export interface TaskEventIdentity {
+    eventId?: string;
+    parentToolCallId?: string;
+    /**
+     * design/122 S2 (the `WorkflowRun.sourceTaskId` family, NOT a second `taskId` — that
+     * field already exists on `task_progress` and a duplicate would bite consumers) — the ORIGINATING task's
+     * canonical id (`spec.taskId ?? sessionId`), stamped ONLY on the content events of a task running AS A
+     * SUB-AGENT (same condition as {@link parentToolCallId}). A consumer of the C1 forward channel
+     * (`forwardSubagentEvents`) can key a child's content events by the child task directly, without an
+     * alias table. A TOP-LEVEL task's own events carry NO `sourceTaskId` (absent = the consumer's current
+     * task). Additive; a consumer that ignores it is unchanged.
+     */
+    sourceTaskId?: string;
+    /**
+     * design/151 S2 (MED-10 live-tail) — the BACKGROUND agent's `a*` registry
+     * handle, stamped on every event a background child's lane forwards up the host `onForwardEvent`
+     * channel (content deltas, tool events, progress). THE live-tail routing key: a serving layer
+     * pipes "what is agent aXX doing right now" straight off the host forward stream — no uuid→a*
+     * alias table (the BCE spawn frame's sessionId mapping) needed. Sync/steer children carry NO tag
+     * (no a* row exists); `wa*` workflow rows stay on their own observer lane. Additive; a consumer
+     * that ignores it is unchanged.
+     * NESTED bg-in-bg (server[1523] 对等复审 4a): each background boundary OVERWRITES the tag as the
+     * frame crosses it — on the HOST wire, the whole subtree's frames carry the OUTERMOST a* handle
+     * (the host-addressable row). Per-frame nesting attribution rides `parentToolCallId`, never this
+     * field; a consumer splitting an outer stream into per-descendant views keys on that.
+     */
+    bgAgentId?: string;
+}
+/**
+ * design/99 §E3/§E10 — a BRAIN-LAYER liveness phase, surfaced so a UI can show why a
+ * turn is stalled (the brain otherwise absorbs these silently in its connect/retry loop). The PHASE
+ * itself is provider-NEUTRAL — a graduated bucket this engine mints, never a provider taxonomy or a
+ * `stop_reason`. The one provider-stated number that does cross this channel is the failing attempt's
+ * HTTP status, and it travels on its own named seat ({@link BrainStatus.errorStatus}) in the retry
+ * context only; the phase and the {@link BrainStatus.detail} hint stay free of it.
+ * A CLOSED union (type-safe) covering the core brain layer; a deployment that surfaces its OWN states
+ * (e.g. E25 token-refresh `authenticating`) does so on its own channel, not by widening this.
+ */
+export type BrainStatusPhase = "rate_limited" | "retrying" | "reconnecting" | "circuit_open"
+/**
+ * RB-420-c — TERMINAL frames closing a retry sequence. Without them a consumer that rendered a
+ * `rate_limited`/`retrying`/`reconnecting` frame has nothing telling it the wait is over, so the
+ * warning row stays pinned until the next unrelated event. Exactly one terminal frame is emitted,
+ * and only for a call that actually waited (a retry wait, or a `waiting_first_token` trail —
+ * #530): `recovered` = the call was served after the wait (a later attempt, or the first token
+ * finally arriving), `gave_up` = the retry budget ran out (or the call was cancelled) and a
+ * terminal error follows.
+ * Both mean the same thing to a renderer — stop showing the retry state.
+ */
+ | "recovered" | "gave_up"
+/**
+ * #530 — the first-token WAIT, before any failure: a first-token watchdog is armed
+ * (`firstTokenTimeoutMs > 0`) and nothing has arrived yet. Emitted once the wait has lasted
+ * `WAITING_FIRST_TOKEN_AFTER_MS` and re-emitted every `WAITING_FIRST_TOKEN_EVERY_MS` while it goes
+ * on, carrying {@link BrainStatus.elapsedMs} and {@link BrainStatus.timeoutMs}; never carries a
+ * retry countdown (`retryInMs`/`retryAtMs` — no wait is being announced, a wait is being
+ * OBSERVED). CLOSED like a retry trail: once a wait frame went out, the call's terminal frame
+ * follows — `recovered` when the call went on to be served (the first token arrived, on this
+ * attempt or a later one), `gave_up` when it failed for good — so a renderer that pinned the row
+ * has its "stop" signal. No frame at all when no watchdog is armed.
+ */
+ | "waiting_first_token";
+/**
+ * WHY a retry wait is happening, as a closed, provider-NEUTRAL bucket — the companion to
+ * {@link BrainStatusPhase}, which says what the brain is doing about it. A consumer rendering an
+ * unattended progress line ("no answer for three minutes") needs the reason, and until this existed the
+ * only carriers of it were the HTTP status and the syscall code, neither of which crossed this channel
+ * at the time. (The status has since gained its own seat, {@link BrainStatus.errorStatus}; this bucket
+ * remains the reason a consumer RENDERS, and it is the only carrier for the transport classes, which
+ * have no status at all.) Values are about the SHAPE of the failure, never its provider taxonomy:
+ *  - `connect_refused` — the attempt got a definite negative about the target itself (nothing accepts
+ *    at that address, or the name has no address). This is the class the SHORT retry lane serves.
+ *  - `transport`      — any other transport-level failure: a connect timeout, a reset, a mid-stream
+ *    tear, a stalled stream. No verdict about the target; the full ladder applies.
+ *  - `rate_limit`     — the provider asked the caller to slow down.
+ *  - `server`         — the provider reported a failure on its own side.
+ *  - `http`           — a response the status predicate calls terminal, retried anyway because the
+ *    provider's own explicit retry verdict said to.
+ *  - `output_cap`     — not a failure of the connection at all: the request is being re-sent with a
+ *    lowered output cap after the provider reported the context limit exceeded (no backoff).
+ */
+export type BrainRetryErrClass = "connect_refused" | "transport" | "rate_limit" | "server" | "http" | "output_cap";
+/** design/99 §E3/§E10 — the payload of a {@link TaskEvent} `status` event (and the brain→runner signal). */
+export interface BrainStatus {
+    phase: BrainStatusPhase;
+    /** Optional neutral, human-readable hint. Stays free of provider/HTTP detail even now that
+     *  {@link errorStatus} exists: the machine-readable status has its own seat, and interpolating it
+     *  into the prose too would make one fact travel in two spellings a consumer has to reconcile.
+     *  (CC parity: its own retry banner renders a TRANSLATED sentence — "No response from API",
+     *  "Connection dropped" — while the raw status rides the structured key beside it.) */
+    detail?: string;
+    /** Seconds until the brain's next retry attempt (from the honored backoff / `Retry-After`), when known. */
+    retryInSec?: number;
+    /** RB-420-c — millisecond precision of {@link retryInSec}, for a client that renders a countdown.
+     *  A wait longer than the re-announce slice is re-emitted with the REMAINING time, so a consumer
+     *  that simply overwrites its row always shows a live number instead of a stale one. */
+    retryInMs?: number;
+    /**
+     * The WALL-CLOCK instant the announced wait is expected to end — `Date.now() + retryInMs`, read at
+     * the moment the frame is emitted, in the EMITTING core process's clock. Stamped centrally at the
+     * one emit point, so the invariant is total: present exactly when {@link retryInMs} is present, and
+     * absent on every frame that announces no wait (`recovered` / `gave_up`, and the immediate
+     * output-cap re-send, which takes no backoff).
+     *
+     * WHY IT IS PRODUCED HERE rather than derived by the consumer: `Date.now() + retryInMs` is only
+     * correct for a reader that received the frame instantly. A consumer several process hops away
+     * (serving layer → client) recomputes a deadline already shifted by the transit, so a countdown
+     * built that way restarts on every re-announced slice instead of converging. The producer is the
+     * only party that can state the instant, so it does.
+     *
+     * CLOCK DOMAIN, stated to remove the ambiguity: WALL CLOCK (`Date.now()`, epoch ms), NOT a
+     * monotonic reading. A consumer must not compare it against its own monotonic timers, and must
+     * treat it as approximate across a clock adjustment or a machine boundary — {@link retryInMs} stays
+     * the authoritative RELATIVE quantity, and this seat is the absolute convenience derived from it.
+     */
+    retryAtMs?: number;
+    /** #530 — on a `waiting_first_token` frame: how long the first token has been awaited, ms, at the
+     *  moment the frame is emitted (the emitting process's clock; approximate across a hop). Absent on
+     *  every other phase. */
+    elapsedMs?: number;
+    /** #530 — on a `waiting_first_token` frame: the armed first-token watchdog, ms — the wait's ceiling,
+     *  so a consumer can render "45s of 120s". Absent on every other phase. */
+    timeoutMs?: number;
+    /** RB-420-c — 1-based index of the attempt that just failed (the wait precedes attempt `attempt + 1`);
+     *  same numbering as the `brain.retry` telemetry frame. Absent on frames that are not a retry wait. */
+    attempt?: number;
+    /** RB-420-c — the retry budget of THIS lane, so a consumer can render "attempt 3 of 10". Lane, not
+     *  engine: a failure class served by a shorter ladder reports that ladder's budget, so the fraction a
+     *  consumer renders is the one actually in force rather than the engine-wide ceiling. */
+    maxRetries?: number;
+    /** Why this wait is happening ({@link BrainRetryErrClass}). Present on retry-wait frames whose cause
+     *  the engine classified; absent on frames that are not a retry wait (`recovered`/`gave_up`) and on a
+     *  `circuit_open` fast-fail, which is a local verdict rather than an observed failure. */
+    errClass?: BrainRetryErrClass;
+    /**
+     * #506 ㋑ — the HTTP status of the attempt that just failed, on the frame announcing the RETRY of it.
+     * The one provider-stated number this channel carries; everything else about the failure still
+     * crosses as the engine's own graduated buckets ({@link phase} / {@link errClass}).
+     *
+     * WHY IT IS HERE AT ALL, given the channel spent its life refusing it: a UI that must tell an
+     * operator whether to wait or to go fix something needs the status, and the two neutral buckets
+     * cannot supply it — `rate_limit` covers a 429 the provider will clear on its own AND a 429 that
+     * means the account is out of quota, and `server` covers a 500 alongside a 503 behind a load
+     * balancer. CC states the same number on the same occasion (`system/api_retry.error_status`, read
+     * off `APIError.status`), so a serving layer forwarding this frame no longer has to choose between
+     * matching CC's payload and honoring this channel's contract.
+     *
+     * PRESENCE — an api_retry context whose attempt got a response that NAMES the failure, and nothing
+     * else. Present on the connect-ladder retry wait (`rate_limited` / `retrying` / `reconnecting` when
+     * a response came back) and on the output-cap re-send (the provider's own 400). ABSENT — never
+     * zeroed, never null — for:
+     *   · a transport failure (`connect_refused` / `transport` at the connect leg): no response existed,
+     *     so no status was ever stated. This is the arm CC spells as an explicit `null`; here it is
+     *     absence, for the same reason every other seat on this interface uses absence, and the fact is
+     *     still TOTAL rather than guessable — {@link errClass} names those two classes by construction.
+     *   · a mid-stream tear (tiers B/C): its response's own status was a SUCCESS, and a status that
+     *     failed nothing must not be published as the cause of a retry.
+     *   · a `circuit_open` fast-fail: a local verdict, nothing was sent, nobody answered.
+     *   · the terminal `recovered` / `gave_up` frames: they announce no attempt.
+     * Same "only a status that names the failure travels" predicate as the assistant frame's
+     * {@link AssistantMessage.apiErrorStatus} (one helper, both sites) — a 2xx never travels here either,
+     * which is reachable on this path via a provider's own `x-should-retry` verdict on a success status.
+     *
+     * OPTIONAL, not CC's nullable-REQUIRED, and the difference is CC's own: CC dedicates a whole message
+     * (`system/api_retry`) to the retry occasion and can therefore require the key on it, while this
+     * interface is ONE shape shared by every phase — the same geometry as CC's shared
+     * `control_request_progress` frame, where CC itself makes the key optional.
+     */
+    errorStatus?: number;
+}
+/**
+ * design/97 CORE-8 (③): one lightweight TOOL-ACTIVITY beat surfaced from a running task, for a per-agent live
+ * "last N tool calls" drill-down. A trusted run-scoped sink ({@link RunInternals.onActivity}) receives one at
+ * each tool start + end. Structural (name/phase/ids) + a SHORT redacted primary `arg` for display — NOT the full
+ * ARGS or OUTPUT (those carry untrusted/host data; the workflow layer surfaces redacted prompt/output separately).
+ */
+export interface ToolActivity {
+    phase: "start" | "end";
+    toolCallId: string;
+    toolName: string;
+    /** wall-clock stamp (epoch ms, `Date.now` read at the emitting Runner where the frame is
+     *  minted). Carried on BOTH beats: the `start` beat stamps the moment the tool call began, the `end`
+     *  beat the moment it settled — so a consumer derives per-call duration (`end.at − start.at`) and
+     *  inter-call idle (an `end.at` → the NEXT `start.at`). Additive/optional: frames recorded by older
+     *  producers simply lack it (a consumer must treat absence as "unknown", never as 0). */
+    at?: number;
+    /** design/99 MF-W: a SHORT primary-arg summary for the monitor's `Read(path)` / `Bash(grep …)` display — the
+     *  single most salient input ABBREVIATED (command→name, path→basename, url→origin+path) + SECRET-SCRUBBED +
+     *  truncated (~80 code points). Set on `phase: "start"`. NOT the full args object, and NOT `redactHostLeaks`
+     *  (that over-redacts the path the monitor needs); the abbreviation + scrub is the leak boundary since the value
+     *  is persisted + SSE-forwarded. See `primaryActivityArg`. */
+    arg?: string;
+    /** Set on `phase: "end"` — whether the tool call errored. */
+    isError?: boolean;
+}
+/**
+ * design/171 §5.2/§6.2 — which carrier a piece of human input arrived on. `"external"` = the
+ * notify() event lane; `"system"` = NOT human input (machine-authored text riding a human-input
+ * code path) — the speaker projection is a guaranteed no-op for it.
+ */
+export type HumanInputSource = "objective" | "steer" | "next_turn" | "wake" | "external" | "system";
+/** design/171 §6.2 — how a human input was disposed of when its event was emitted:
+ *  `"applied"` = delivered into a model turn; `"queued"` = accepted, awaiting the next turn
+ *  boundary; `"parked_for_wake"` = parked for the session's next run (torn-down lane);
+ *  `"blocked"` (design/373 §4.3, additive — closed-set add, consumers named in the ship post) =
+ *  a PARKED entry was withheld at resume redelivery — the screen runs on EVERY resume kind that
+ *  drains parked steers (policy_ask / dry_run_review / plan_review / resource_limit, wake
+ *  included) — by the deployment's `userPromptSubmit` screen (block verdict, or a fail-closed
+ *  non-answer/crash): the row was consumed, the frame never reached the model, and the sibling
+ *  `steering.parked_input_blocked` notice names the same inputId — "park 时收下、redeliver 时被筛"
+ *  is auditable, never a silent disappearance. */
+export type HumanInputDelivery = "applied" | "queued" | "parked_for_wake" | "blocked";
+/**
+ * The fleet-task kinds a DELEGATED run can honestly claim, derived from (never a second spelling of)
+ * {@link TaskNotificationPayload}'s `task_type` vocabulary — the same axis a consumer already keys
+ * notifications on. The other members of that union name non-agent lanes (a background shell command,
+ * a monitor, an externally-produced notification), which no delegated run is; deriving rather than
+ * re-listing is what keeps the two faces from drifting into two vocabularies.
+ */
+export type DelegationTaskType = Extract<TaskNotificationPayload["task_type"], "background_agent" | "workflow">;
+/** Streaming events surfaced from a running task (for live UIs). */
+export type TaskEvent = ({
+    type: "text_delta";
+    delta: string;
+} & TaskEventIdentity) | ({
+    /**
+     * #447 — the assistant's streaming PROSE SEGMENT is COMPLETE: the model closed the text content
+     * block whose bytes just streamed as `text_delta`s. This is the explicit segment boundary a
+     * REMOTE consumer needs so it never has to guess segment ends from wire silence (the idle-flush
+     * heuristic this retires cut one slow-model reply into N fragments). CC-aligned: CC's agent
+     * stream yields each finished content block as its own assistant-message unit at the provider's
+     * `content_block_stop` — block completion IS the segmentation signal there; a single-process
+     * consumer reads it off the provider stream natively, and this event is that same boundary
+     * surfaced on the TaskEvent wire (CC pays the byte cost of re-carrying the block at the stop;
+     * so does this event's `content`).
+     *
+     * `content` = the authoritative FULL text of the completed segment (byte-equal to that
+     * segment's accumulated deltas, from the brain's own accumulation) — a consumer commits the
+     * segment from it instead of trusting its own delta stitching. UNTRUSTED model output for
+     * display only, same contract as `text_delta`. Emitted only for a segment that holds bytes: an
+     * empty text block closes silently (a boundary with no segment would render phantom rows).
+     *
+     * Additive + ignorable. HONEST ABSENCE: the frame exists only when the serving Brain reports
+     * block ends (`text_end` on its event stream — all three first-party brains do; a custom brain
+     * that never emits them yields a wire without this frame). A consumer treats per-segment
+     * presence as the signal and falls back to its own heuristic only on streams that carry none —
+     * absence is "unreported", never "the segment did not end".
+     */
+    type: "text_end";
+    content: string;
+} & TaskEventIdentity) | ({
+    type: "reasoning_delta";
+    delta: string;
+} & TaskEventIdentity) | ({
+    type: "tool_start";
+    toolCallId: string;
+    toolName: string; /** {@link ToolSpec.label} when distinct from `toolName` (design/71 liveness); omitted otherwise. */
+    label?: string;
+    args: unknown;
+} & TaskEventIdentity) | ({
+    type: "tool_end";
+    toolCallId: string;
+    toolName: string;
+    /** {@link ToolSpec.label} when distinct from `toolName` (design/71 liveness); omitted otherwise. */
+    label?: string;
+    isError: boolean;
+    /**
+     * design/99 §E1 — the tool's MODEL-FACING result content, surfaced for a live UI
+     * that renders tool output. It is the harness `AgentToolResult.content` the mapper already produced
+     * (previously dropped here); the internal `details` payload is NOT exposed (e.g. a sub-agent tool's
+     * `details` is the entire child `TaskResult`).
+     *
+     * **Type is `unknown` and intentionally non-uniform** — within size it passes through AS-IS to keep
+     * structure a UI wants (a `string`, or `(TextContent|ImageContent)[]` blocks); when the serialized body
+     * exceeds the core size cap it degrades to a single TRUNCATED STRING (see {@link truncated}). A consumer
+     * must handle both shapes.
+     *
+     * **UNTRUSTED RAW + for OBSERVABILITY ONLY**: it is external tool output (file reads, shell stderr, API
+     * bodies) and may carry secrets/paths/PII — core bounds only its SIZE; a consumer MUST redact and MAY
+     * further bound before it persists or displays it (same contract as `tool_start.args`). It is for a live
+     * UI / trace, NOT for re-feeding to a model: a truncated body would mislead an LLM, and the model already
+     * has the full, untruncated result in its own context — build model prompts from the session, never by
+     * replaying this field. Absent when the tool produced no content body.
+     */
+    output?: unknown;
+    /**
+     * design/116 (b) — the tool's CC-shaped `toolUseResult` facts (`details.type` ∈ the known card
+     * set: edit/create/update/bash/text/grep/glob/notebook-edit/notebook/file_unchanged/mcp/image/
+     * document/worktree/todo/task/task-list/task-output/task-stop/agent/fork/workflow-run/web-fetch/
+     * web-search/cron-create/cron-delete/cron-list/tool-search/repo-map/monitor-start/
+     * enter-plan-mode/exit-plan-mode/report-findings/schedule-wakeup/send-message/agent-transcript/
+     * a2a/path_not_in_root/readonly_out_of_root), surfaced on the live wire so a CC-faithful shell
+     * renders rich cards (red/green diff, stdout panes, file cards) without re-parsing the
+     * model-facing string. Absent when the tool carries no card shape or when the serialized card
+     * exceeds the size bound (omitted whole; a consumer falls back to `output`).
+     * UNTRUSTED RAW like {@link output}: a consumer MUST redact before persisting or forwarding.
+     *
+     * **The card set is a two-way contract** (structured-card audit, 2026-08-05): every entry has a tool
+     * that mints it and every minted card is registered, so a consumer switching on `details.type`
+     * gets neither a promise nothing keeps nor a card it was never told about. That pass ADDED
+     * report-findings / schedule-wakeup / send-message / agent-transcript / a2a / document /
+     * readonly_out_of_root and the completed **agent** shape (see below); it REMOVED multiedit /
+     * memory-saved / memory-recall, three words with no producer anywhere in core (a batch MultiEdit
+     * replay mints `type:"edit"` with an `edits[]` array; core mounts no memory tool at all).
+     *
+     * **Leak boundary**: the allowlist gates by `type`, so what rides is whatever the minting tool put
+     * in the object — which makes each mint site responsible for its own field set. The Agent family's
+     * completed card is therefore built from an EXPLICIT whitelist rather than a child-`TaskResult`
+     * spread: a `TaskResult` can carry `checkpointToken` (the resume CAPABILITY) on the
+     * `unexpected.suspended` terminal, and that field, with `checkpointGate`, never leaves the process.
+     *
+     * **双面契约(CC 2.1.207 @765495 成文,`tool_use_result` describe;CC207-CORE-SWEEP P2-3)** — a tool
+     * result has TWO faces that never substitute for each other:
+     * - **模型面** = {@link output} / the tool_result text: the string the MODEL reads. It may carry
+     *   model-directed framing — e.g. a delegation tool's trailer (agentId / usage lines the model uses to
+     *   address SendMessage or budget itself). That framing is FOR THE MODEL; it is not a host data format.
+     * - **宿主面** = this field: the tool's structured Output object, per-tool shaped, keyed by the matching
+     *   tool call's name. For a delegation/Agent-family tool the completed shape is the subagent's final
+     *   report WITHOUT the model-directed trailer, plus run totals (CC names it `AgentToolCompletedOutput`).
+     *   Both Agent shapes ride `type:"agent"` and are told apart by `status`: `"async_launched"` is the
+     *   background launch RECEIPT (task_id / description / prompt), any other value is the completed
+     *   landing report (`result` / `stats` / `resolvedModel` / `toolStats` / kept `worktreePath` /
+     *   failure attribution). Branch on `status`, never on which keys happen to be present. (Until
+     *   2026-08-05 only the receipt actually arrived — the completed delivery carried no `type` and was
+     *   dropped by the allowlist, so this paragraph described something a host could not observe.)
+     * A host/shell MUST render from `structured` and MUST NOT parse the model-facing text back into data
+     * (trailer wording is model-audience prose and may change without notice); symmetrically, core never
+     * strips the trailer from the model face just because the structured face exists — the model still needs
+     * it in-context. When `structured` is absent, the honest fallback is to display `output` as opaque text,
+     * not to scrape it.
+     */
+    structured?: unknown;
+    /**
+     * Present iff {@link isError} is true AND the harness result's `details` carried a string
+     * discriminator — read as `details.code` first, falling back to `details.errorKind` (each must be
+     * a string; `code` wins when both are present, as the deliberate tool-chosen spelling). The
+     * `errorKind` leg is what makes a LOOP-THROWN error's frame classifiable: the loop's thrown-error
+     * fold and the resume legs write the discriminator under that name. Lifted so a consumer never
+     * has to parse the (contract-stable) result text. Engine-minted vocabulary today includes
+     * `"tool.not_found"` (unknown tool name), `"gate.parked"` (an abort short-circuit contaminated
+     * this call because a durable gate parked the batch — the "Operation aborted" family), and, for a
+     * failed MCP tool call, the MCP failure class — see {@link import("./mcp-failure.js").McpFailure.kind}
+     * for the words (the same closed set the per-server status and the wiring manifest's `mcp[]` carry;
+     * this frame only transports it). Additive: absent on error frames minted before this field
+     * existed, and on error results whose details carry no string discriminator under either name.
+     */
+    errorCode?: string;
+    /**
+     * @contract tool_end.delivered — WHETHER THE REQUEST REACHED ITS SERVER, when this frame closes a
+     * failed call whose result carried the MCP failure record: the closed
+     * {@link import("./mcp-failure.js").McpDelivered} (`"yes"` / `"no"` / `"unknown"`), lifted from
+     * `details.delivered` beside {@link errorCode} and read TOGETHER with it — the same `errorCode`
+     * (`connection_closed`) is safe to retry at `"no"` (nothing was sent) and must be verified first at
+     * `"unknown"` (the request may have executed). The meaning of each word is owned by
+     * {@link import("./mcp-failure.js").McpFailure.delivered}; this frame only transports it. Screened
+     * against the closed set (an out-of-vocabulary value is not lifted) and never derived from the
+     * code or the text. ABSENT on every frame whose result carried no such verdict — every executed
+     * call and every non-MCP failure — and a consumer must not read a semantic out of the absence.
+     */
+    delivered?: import("./mcp-failure.js").McpDelivered;
+    /**
+     * WHICH call the gate was holding, when this frame is a park-contamination frame — the tool call
+     * id of the gated call. Three conditions, ALL required: `errorCode === "gate.parked"`, the run is
+     * tearing down behind a committed park, and that park binds a tool call at all.
+     *
+     * **WHERE IT COMES FROM — never lifted from the result**, and deliberately unlike its neighbour
+     * {@link errorCode}: that one IS the result's own `details.code`, i.e. tool-authored, because a
+     * tool classifying its own failure is bounded self-description. This field is an assertion about a
+     * DIFFERENT call, so a tool able to author it could point an approval UI at a call nobody is
+     * holding. It is therefore engine-minted — read from the run's committed park holder and handed to
+     * the frame projection as a parameter, the same posture (and the same reason) as {@link settledBy}.
+     * `errorCode` only participates in selecting WHETHER the id is placed; it never supplies the
+     * value, and on its own it is not enough — the run must also be aborting behind a real park, which
+     * is why a tool declaring `gate.parked` on its own failure cannot conjure this field.
+     *
+     * Why it is on the frame: a durable gate parks ONE call and the loop then short-circuits every
+     * sibling in the batch with an identical "Operation aborted" body, so `gate.parked` alone says
+     * "something parked this batch" without saying WHAT. A consumer wanting to render "waiting on
+     * <the gated call>" beside the collateral frames otherwise has to re-derive the pair from batch
+     * adjacency and timing — an inference that is wrong exactly when it matters (a batch with more
+     * than one ask candidate, a reordered stream).
+     *
+     * ONLY EVER STRUCTURALLY PROVEN, never guessed: the id is read off the committed checkpoint's
+     * pending tool call, so it is the same value the checkpoint parks on and the same value the
+     * decide/resume lane answers about. It is therefore ABSENT — not approximated — for the park
+     * kinds that hold no call (a resource-limit slice, a plan review), and absent for every abort
+     * that is not a gate park at all (user interrupt, timeout, walltime): those frames are
+     * byte-unchanged. Absence means "core cannot prove a causal call", never "there wasn't one".
+     */
+    gatedCallId?: string;
+    /**
+     * The gate's record of the pass that admitted or refused this call, when the call went through the
+     * tool gate at all ({@link import("./gate-outcome.js").GateOutcome}): `disposition` (allowed, or
+     * denied by which LAYER), `settlement` (how the ask this pass consumed ENDED — a person's yes or
+     * no with the channel's attribution and, on a bare "no", no note; a window that elapsed and whose;
+     * nobody reachable; the wait aborted…) and `origin` (who ASKED). It is the SAME object the
+     * `permissionDenied` observer received and the engine's per-call sideband recorded — one mint, three
+     * faces — so a renderer never branches on prose to tell "a person refused" from "the window closed".
+     *
+     * WHERE IT COMES FROM — never inferred here: the gate mints it at its exit, the decide lane mints it
+     * from the host's decision facts joined with the row's persisted origin. Core does not derive it
+     * from `isError`, from the result, or from anything a tool or a post-tool hook can write.
+     *
+     * ABSENT on every frame of a call the gate never saw (a tool call on an unarmed gate, a deferred
+     * re-issue, a reconcile-recovered orphan). A gated call's frame ALWAYS carries it — an absence is
+     * not a fact about the call, and a consumer must not read one out of it.
+     */
+    gate?: import("./gate-outcome.js").GateOutcome;
+    /**
+     * design/99 §E1 — `true` when {@link output} was SIZE-bounded by core (the full body exceeded the cap and
+     * was degraded to a truncated string). Lets a consumer detect truncation programmatically instead of
+     * parsing the `…[+N chars truncated]` marker out of the string. Absent/false = `output` is the complete
+     * content body. (The full untruncated result still lives in the model's context / `ToolResultStore`.)
+     */
+    truncated?: boolean;
+    /**
+     * RB-210 — present iff {@link truncated}: the TRUE original size (characters) of
+     * the content this event's {@link output} was degraded from — for a string result, the string's own
+     * length; for a non-string result (a blocks array), the SUM of each block's own true size (a text
+     * block's `.text.length`; an image/document block's `.data.length`, i.e. its base64 payload) — never
+     * `JSON.stringify(content).length`, which is polluted by two different kinds of noise: structural
+     * overhead (field-name/punctuation bytes that aren't content at all) AND, for text containing quotes/
+     * backslashes/control characters, escape inflation (the same class of bug this field was created to
+     * fix in the first place — a real result: 17298 reported vs 13696 true content characters — reappearing
+     * in a subtler form if the true count were ever taken from the serialized form instead of the blocks).
+     *
+     * **Not always arithmetically tied to the marker's own `N`**: the marker counts how much MORE of the
+     * shown raw-text rendering exists beyond the cut point; `totalChars` counts the true size of the
+     * ORIGINAL value, which for mixed content includes non-text blocks (e.g. an inlined image) that
+     * `output` never renders as text at all. The two can legitimately diverge — `totalChars` may run far
+     * ahead of the cap plus the marker's `N` — and that gap is itself the honest signal that non-text bulk
+     * was dropped, not an inconsistency to paper over.
+     */
+    totalChars?: number;
+} & TaskEventIdentity) | ({
+    /**
+     * RB-126 — context occupancy at a compaction boundary, emitted on EVERY
+     * boundary (not only when a compaction fires). The three numbers are the engine's own trigger
+     * inputs, verbatim: `usedTokens > compactAtTokens` IS the predicate `shouldCompact` evaluates, so a
+     * consumer's "context is N% full" indicator and the moment compaction actually fires can never
+     * disagree. Re-deriving the numerator downstream is precisely what this exists to prevent.
+     *
+     * Deliberately NOT a field on `turn_end`: the boundary check runs AFTER that event, over the
+     * post-flush message set, so a value attached there would be a different (earlier) measurement
+     * wearing the same name. `windowTokens` is the AUTOCOMPACT window — a model declaring
+     * `autoCompactTokens` keeps a LARGER physical request window — so do not present it as "the
+     * model's context size".
+     */
+    type: "context_usage";
+    usedTokens: number;
+    windowTokens: number;
+    compactAtTokens: number;
+} & TaskEventIdentity) | ({
+    type: "turn_end";
+    /**
+     * Per-turn token usage + cost (the turn that just ended), for live per-turn accounting / a trace UI
+     * (service [41]). Re-priced in core from injected pricing (authoritative, like `TaskResult.stats`).
+     * Absent only if the turn produced no assistant usage.
+     *
+     * RB-457-a: `inputTokens` is the cache-MISS count (Anthropic-protocol shape, matches
+     * `stats.promptTokens` / the tracer's `brain.call.promptTokens`); `totalInputTokens` is the
+     * cache-INCLUSIVE total (`inputTokens + cacheReadTokens + cacheWriteTokens`) that cost is computed
+     * from. Sum `totalInputTokens` for context/window/spend views; read `inputTokens` only where the
+     * protocol's `input_tokens` is meant. Up to 2.13.x `inputTokens` carried the total.
+     */
+    usage?: {
+        /** Cache-MISS input tokens for this turn (the Anthropic protocol's `input_tokens` meaning;
+         *  matches `stats.promptTokens` / `brain.call.promptTokens`). **Up to 2.13.x this field
+         *  carried the cache-INCLUSIVE total** (RB-457-a, BREAKING at 3.0.0) — that value now lives
+         *  in `totalInputTokens`. Read this only where the protocol's `input_tokens` is meant. */
+        inputTokens: number;
+        /** Cache-INCLUSIVE input total for this turn (`inputTokens + cacheReadTokens +
+         *  cacheWriteTokens`) — what cost is computed from. Sum THIS for context/window/spend
+         *  views; it equals what `inputTokens` carried up to 2.13.x. */
+        totalInputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        costMicroUsd: number;
+    };
+    /** TB 尸检 T1-5: set when the turn ended WITHOUT a provider usage frame (e.g. a degenerate-repetition
+     *  cutoff cancelled the stream before usage arrived). Consumers must treat the missing usage as
+     *  UNKNOWN — not zero (the provider still served the request; `stats` under-counts it honestly rather
+     *  than polluting the single-source accounting with an estimate). */
+    usageMissing?: true;
+    /** TB telemetry B1: the NORMALIZED finish reason of the turn's LAST model call —
+     *  the engine's `AssistantMessage.stopReason` (`StopReason`: `"stop"`/`"length"`/`"toolUse"`/
+     *  `"error"`/`"aborted"`). This is post-normalization: e.g. Anthropic `end_turn`/`stop_sequence`
+     *  both fold to `"stop"`, `max_tokens`→`"length"`; the raw provider reason is NOT preserved here.
+     *  The machine signal for "was this turn cut by max_tokens" (`"length"`) — previously stream+trace
+     *  double-blind, which made P1 cap-binding unjudgeable from artifacts. Absent when the turn produced
+     *  no assistant message. Typed `string` (not the internal `StopReason`) to keep the engine's union
+     *  private, but the value set is exactly those five tokens. */
+    stopReason?: string;
+} & TaskEventIdentity) | ({
+    /** design/99 MF-18: a compaction boundary (or, since design/119 #1, mid-turn when the prompt-too-long recovery force-compacts between a failed request and its retry). `trigger` = what caused it: `"auto"` (the context-threshold
+     *  auto-compaction), `"manual"` (the `TaskStream.compact` / `/compact` path), or `"forced"` (RB-398-b
+     *  the prompt-too-long recovery and trim-pressure lanes — compaction was not optional; the
+     *  hook layer's `PreCompactContext.trigger` always had this third state and the wire now carries the
+     *  SAME value the hooks saw instead of flattening it to `"auto"`. Additive value space — a consumer
+     *  switching on auto/manual keeps its exact old behavior). `tokensBefore` = the
+     *  pre-compaction context size. CC parity = `SDKCompactBoundary{trigger, pre_tokens, preserved_segment}`. */
+    type: "compacted";
+    trigger: "auto" | "manual" | "forced";
+    tokensBefore: number;
+    /** TB telemetry B4: post-compaction context size in the TRIGGER-GATE coordinate
+     *  (`postTriggerTokens` = estimate + anchor-less overhead). Pairs with {@link triggerTokensBefore}
+     *  — NOT with `tokensBefore` (which is the CC `pre_tokens` value in prepareCompaction's coordinate,
+     *  lacking the overhead term; subtracting across the two coordinates would mis-state the delta,
+     *  the audit-B-1 / P-13 class). Absent when the post measurement failed (best-effort, never fails a
+     *  successful compaction). */
+    tokensAfter?: number;
+    /** TB telemetry B4: pre-compaction size in the SAME trigger-gate coordinate as {@link tokensAfter}
+     *  (`triggerTokens` — the exact quantity the compaction gate compared). `triggerTokensBefore −
+     *  tokensAfter` is the self-consistent freed delta. Absent on the legacy emitter. */
+    triggerTokensBefore?: number;
+    /** TB telemetry B4: wall time of the whole compaction pass (summary call included) — what the
+     *  boundary pause actually cost. Absent on legacy emitters. */
+    durationMs?: number;
+    /** CC `SDKCompactBoundary.preserved_segment` parity: `firstKeptEntryId` is the session-tree entry id where
+     *  the surviving KEPT TAIL begins after this compaction. A consumer maps it to a wire message via the
+     *  `entryId` carried on `message_committed` (message-identity Phase 1) — render the compaction divider just
+     *  before that message + relink the preserved tail. (The eventId↔entryId side map service keeps for resumeAt
+     *  also resolves it, but is no longer required.) Absent on a compaction that reported no kept-tail floor. */
+    preserved_segment?: {
+        firstKeptEntryId: string;
+    };
+    /** CC post-compact file-restore parity (2026-07-03): the working files the engine
+     *  re-read into the summary (attachWorkingFiles), attachment order. A shell renders CC's
+     *  `Read {path} (…)` cards under the compaction divider from this. Absent when the feature is
+     *  off or nothing was attached. `truncated` = the content was clipped at the per-file cap. */
+    attachedFiles?: Array<{
+        path: string;
+        chars: number;
+        truncated: boolean;
+    }>;
+    /** design/145 §3 (additive): this compaction's summary call FELL BACK from the independent
+     *  `compactionModel` to the main model — the small window would have truncated more than
+     *  `compaction.clampTolerance` of the conversation. Mirror of `compaction.model_fallback`. */
+    modelFallback?: true;
+    /** design/145 §3 (additive): why the fallback happened ("window" is the only reason today). */
+    fallbackReason?: "window";
+    /** design/145 §3 (additive): the summary INPUT was clamp-truncated on the compaction model by
+     *  this ratio (0..1) — set when the budget gate denied the fallback, or when the
+     *  truncation stayed within tolerance (bounded loss, disclosed either way). */
+    clampedRatio?: number;
+    /** design/145 §3 (additive): "budget" = the gate that denied the fallback;
+     *  "tolerance" = within-`clampTolerance` ordinary truncation. */
+    clampReason?: "budget" | "tolerance";
+    /** 压缩子阶段遥测 (1.283 批 G / design/145 §6 正交后续批, additive): sub-phase wall-time split
+     *  of THIS pass, mirrored 1:1 from `maybeCompact().phaseDurations` (single source: the
+     *  `compaction.phase_timings` trace frame minus its envelope). Invariant: prepareMs +
+     *  (summaryMs ?? 0) + persistMs === {@link durationMs} (exact tiling; `summaryMs` absent on a
+     *  provider-reuse pass — no summary LLM call happened). Absent on legacy emitters. */
+    phaseDurations?: import("./auto-compaction.js").CompactionPhaseDurations;
+} & TaskEventIdentity) | ({
+    /**
+     * RB-398-b④: a compaction pass concluded WITHOUT landing — the non-landing outcomes
+     * used to exist only as `compaction.*` trace frames, so a stream-only consumer watched a
+     * context quietly stop being managed (breaker opens, rapid-refill disable, hook blocks —
+     * all invisible). One lightweight additive event, emitted at the same sites as the trace
+     * frames; the SUCCESS outcome stays on the `compacted` event (this event never carries it,
+     * so a consumer treating `compacted` as the only success signal is unchanged).
+     * `outcome` reuses the {@link CompactOutcome} vocabulary plus `"suppressed"` (over-threshold
+     * pass suppressed by the anti-thrash floor — a state manual compact can never reach, hence
+     * outside `CompactOutcome`):
+     * - `"failed"` — a burned summary attempt failed, or the open breaker drained a manual
+     *   request without an attempt (`reason` says which).
+     * - `"blocked"` — a `preCompact` hook deliberately blocked the pass.
+     * - `"suppressed"` — wanted to fire, held under the §25.2 anti-thrash floor.
+     * - `"noop"` — the pass ran but found nothing to compact (no valid cut point/empty history).
+     * - `"disabled"` — an explicit (manual/forced) request was refused because compaction is off,
+     *   or the rapid-refill breaker disabled compaction mid-task (`reason` says which). A spec
+     *   that statically disables compaction does NOT produce one of these per boundary (that
+     *   would be per-boundary noise about a static configuration, not a state change).
+     * - `"mooted"` — a manual request was processed but no boundary could serve it (dying loop /
+     *   caller cancel).
+     */
+    type: "compaction_outcome";
+    outcome: Exclude<CompactOutcome, "compacted"> | "suppressed";
+    /** Same three-state vocabulary (and the same value) the pass handed the `preCompact` hook. */
+    trigger: "auto" | "manual" | "forced";
+    /** Optional human-readable detail (mirrors the trace frame's reason where one exists). */
+    reason?: string;
+} & TaskEventIdentity) | ({
+    /**
+     * TB telemetry B3: the engine injected a SYSTEM steering message (a deadline nudge
+     * or the design/130 P2 graceful-finalize instruction) into the model's next turn. Previously these
+     * went through `harness.steer()` with no stream echo — a consumer literally could not tell whether
+     * the finalize fired (the refute-130 attribution blind spot). Echo only; the model-facing message
+     * is unchanged. `preview` is the injected text clipped to a display bound.
+     *
+     * design/133 (LOW-11/F11): the turn-boundary attachment producers ride the same echo — sources
+     * `todo_reminder` / `task_reminder` / `changed_files` / `plan_mode` and the G1/续批 members
+     * `background_tasks` / `tools_delta` / `agent_listing` / `skills_listing` / `mcp_instructions`
+     * (one event per attachment; a multi-attachment boundary still coalesces into ONE steer message
+     * on the model lane). [c209-C]: the listing family's FIRST-FRAME deliveries (initial roster /
+     * `<skills>` block riding the first user message, not a steer) emit the same echo frames.
+     *
+     * `git_status` (env-tail migration, additive member): the git-status frame — the turn-dynamic
+     * git facts' carrier since they left the system prompt. Emitted at the frame's append RECEIPT
+     * (first-frame / resume-continuation / compaction re-assert deliveries alike). Its `preview`
+     * is a CONSTANT wording on purpose (never frame bytes): branch names and status text are
+     * repo-controlled and must not enter the event telemetry plane through this echo.
+     */
+    type: "steering_injected";
+    source: "limit_approach" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "total_tokens_reminder" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools" | "final_verification" | "git_status";
+    preview: string;
+} & TaskEventIdentity) | ({
+    /**
+     * design/121 (CC 198 `<new-diagnostics>` parity): NEW LSP diagnostics that appeared after the
+     * agent's edits, drained at a turn boundary. The SAME data was injected into the model as a
+     * `<new-diagnostics>` context message; this frame is the shell's render source (CC's collapsed
+     * `Found N new diagnostic issues in M files (ctrl+o to expand)` row). UNTRUSTED RAW (language-
+     * server output over workspace files) — a consumer redacts/bounds before persisting (§E1).
+     */
+    type: "diagnostics";
+    files: Array<{
+        uri: string;
+        diagnostics: Array<{
+            message: string;
+            /** LSP severity: 1=Error 2=Warning 3=Information 4=Hint. */
+            severity?: number;
+            range?: {
+                start: {
+                    line: number;
+                    character: number;
+                };
+                end?: {
+                    line: number;
+                    character: number;
+                };
+            };
+            code?: string | number;
+            source?: string;
+        }>;
+    }>;
+    isNew: true;
+} & TaskEventIdentity) | ({
+    /**
+     * message-identity Phase 1 (the CC `SDKCompactBoundary` parity enabler): a persisted session-tree entry was
+     * just COMMITTED for a RENDERABLE message the consumer has already streamed. `entryId` = `SessionTreeEntry.id`
+     * (uuidv7, persisted, replica-stable) — the SAME id space as `compacted.preserved_segment.firstKeptEntryId`,
+     * E18 `resumeAt`, and the design/381 `rewindFilesTo`. `role` + (for a tool result) `toolCallId` let a consumer bind it to
+     * the message it rendered: a tool result by its `toolCallId`; an assistant/user message by stream order (this
+     * is the terminal boundary for the content just streamed, after its deltas and before its tool results). A
+     * consumer builds its own `entryId → message` map from these to resolve `preserved_segment` WITHOUT the
+     * eventId↔entryId side map. Terminal per-message boundary; additive + ignorable. ABSENT for a message that did
+     * not persist (an empty-failure assistant) and for non-message entries (a compaction summary / model_change —
+     * never a `message_committed`). The engine still holds no eventId→entryId map (the deployment owns it); this
+     * only pushes the persisted id onto the wire, the constitution's primitive/profile split (cf. §E2 `eventId`).
+     */
+    type: "message_committed";
+    entryId: string;
+    role: "user" | "assistant" | "toolResult";
+    /** Present iff `role === "toolResult"`: the exact join key to the `tool_start`/`tool_end` already rendered. */
+    toolCallId?: string;
+} & TaskEventIdentity) | ({
+    /**
+     * design/171 §5.5/§6.2 — the human-input LIFECYCLE arm: one frame per human input this run
+     * accepts (WHO fed the run WHAT, per carrier). Additive + ignorable like its siblings.
+     * Deliberately NOT folded into `message_committed`: that event only fires for messages that
+     * PERSISTED, while a human input's lifecycle (queued / parked) exists before — and sometimes
+     * without — a committed message. Constructed via `buildHumanInputEvent` (mints the inputId,
+     * materializes no absent optional keys); `HumanInputEvent` is the Extract-derived alias.
+     *
+     * Attribution semantics are THREE-VALUED, never collapsed:
+     *  - `actor` ABSENT ⇒ the caller supplied none (anonymous — every pre-171 caller);
+     *  - `actor.hostAsserted === false` ⇒ an UNVERIFIED self-claim the host chose to carry;
+     *  - an OLD event stream that predates this arm simply has no `human_input` frames at all —
+     *    a consumer distinguishes "attribution unknowable (pre-arm producer)" by the emitting
+     *    core's version, never by guessing from field absence on some other event.
+     */
+    type: "human_input";
+    /** Correlation/idempotency key. Caller-supplied when the ingress already minted a message id
+     *  (the parked-steer queue's `inputId` is THE same key); a uuidv7 otherwise. */
+    inputId: string;
+    /** Ordinal of this input among the run leg's accepted human inputs (1-based, drain order for
+     *  parked entries). Leg-scoped: a resumed leg restarts at 1 — `inputId` is the global key and
+     *  stream order the global order; a serving layer needing a session-global ordinal mints its
+     *  own. */
+    sessionSeq: number;
+    /** Which concrete carrier accepted the input. OPEN set — a serving layer self-reports its own
+     *  carriers (question note / elicitation / decide reason / …) through the same arm; the
+     *  core's five report their {@link HumanInputSource} name. */
+    carrier: string;
+    source: HumanInputSource;
+    /** Who asserted the actor's identity (Slack app id, SSO IdP …) — mirrored from `actor.issuer`
+     *  or supplied alone when the host can name its ingress but not the subject. */
+    issuer?: string;
+    actor?: ActorAssertion;
+    delivery: HumanInputDelivery;
+    /** Plaintext principal correlation key (deliberately not hashed — the audit consumer joins
+     *  on it). */
+    principal?: string;
+    /** The persisted session-tree entry the input landed as, WHEN the emitter knows it (a
+     *  serving layer replaying the ledger); the core's live emissions precede the commit and
+     *  omit it — consumers there join via `message_committed` + stream order. */
+    entryId?: string;
+} & TaskEventIdentity) | ({
+    /**
+     * design/99 §E3/§E10 — a live BRAIN-LAYER status the brain would otherwise absorb
+     * silently (a 429 rate-limit / a 5xx or network retry / a reconnect / an open circuit breaker). Emitted
+     * the moment the brain decides to wait/retry, carrying the graduated {@link BrainStatusPhase} + an
+     * optional `retryInSec` so a UI can show "rate limited, retrying in Ns". EPHEMERAL — a pure liveness
+     * signal, never persisted or replayed on resume. The phase and the hint are provider-neutral (no
+     * provider taxonomy, no `stop_reason`); the failing attempt's HTTP status rides its own seat in the
+     * retry context only — see {@link BrainStatus.errorStatus}.
+     * SCOPE: reflects THIS task's own (top-level) brain calls. A delegated sub-agent's brain liveness routes
+     * to the SUB-AGENT's own stream (isolated, like every child event — §E2); a background internal brain
+     * call (memory recall/consolidation) is intentionally not surfaced.
+     */
+    type: "status";
+} & BrainStatus & TaskEventIdentity) | ({
+    /**
+     * design/115 P2 core slice — SDK-side projection of a background task terminal notification. The model-facing
+     * projection is the sibling `<task-notification>` XML injected through the runner's system-injection lane when
+     * the originating harness is still running; durable idle wake/resume is a deployment transport concern.
+     */
+    type: "task_notification";
+    notification: TaskNotificationPayload;
+    /** design/373 §3.6 — the frame's injection tier as DELIVERED (additive; consumers tolerate
+     *  absence): on the live lane, the tier the routing used (`next`/`now` → steer lane, `later`
+     *  → followUp lane); on the turn-open redelivery lane, the tier the park CARRIED. ABSENT is a
+     *  fact, not a default: a pre-373 producer event, or a parked record whose tier was not
+     *  carried (the terminal sweep's re-pend) — never read absence as `"later"`. */
+    priority?: import("./task-notification.js").SystemInjectionPriority;
+} & TaskEventIdentity) | ({
+    /**
+     * design/99 MF-10 — a SUBAGENT PROGRESS TICK: the delegated sub-run's usage ACCRUING
+     * over time, emitted at each turn boundary WHILE it runs, so a parent UI animates the Task card's rollup
+     * (tokens/tool-uses climbing). Emitted ONLY for a subagent (a task with `parentToolCallId`); a top-level
+     * run's own usage is the consumer's own. `status:"running"` mid-run; the terminal usage is the `done` result.
+     * Live/ephemeral — NOT persisted (a resumable trace re-derives usage from the result), like `status`.
+     * Maps to CC `SDKTaskProgress` (camelCase here → snake_case `task_id`/`total_tokens`/`tool_uses`/`duration_ms`
+     * at the SDK/service projection, the same convention as `toolCallId`→`tool_use_id`).
+     */
+    type: "task_progress";
+    taskId: string;
+    /**
+     * The FLEET-task kind of the run this tick reports on — the type discriminator a consumer needs
+     * when it folds progress ticks and task notifications into one ledger. Without it the only
+     * available test is "it appeared on the fleet stream, therefore it is an agent", and that
+     * inference has already minted an agent-shaped row for a task that was a background shell
+     * command. Drawn from {@link TaskNotificationPayload}'s `task_type` vocabulary (no second
+     * spelling of one axis) and narrowed to the members a progress tick can honestly claim.
+     *
+     * Present on every tick from a run that HAS a fleet row: `"background_agent"` for a background
+     * delegation child (its registry `a*` row) and `"workflow"` for a workflow-spawned agent (its
+     * `wa*` read-face row) — the latter alongside, not in place of, {@link workflowRunId}, which
+     * names the owning RUN while this names the KIND. ABSENT is a fact, not missing data: a
+     * SYNCHRONOUS delegated child has no fleet row at all. Additive — tolerate absence, and never
+     * read absence as "not an agent".
+     */
+    taskType?: DelegationTaskType;
+    /**
+     * #258 — the registry row's STOP-CYCLE generation this tick reports from (fresh
+     * spawn = 1, every launched revival bumps it), the same counter `TaskNotificationPayload.seq`
+     * and `BackgroundChildEvent.seq` already speak — one axis, not a third spelling. It answers
+     * the one question a fleet consumer cannot otherwise decide when a frame arrives late: "late
+     * first frame of the cycle I know (same value), or a revived run I have not folded yet
+     * (higher value)?" Advisory observation, stamped at spawn/revive from the registry's own
+     * counter; the settle-time ledger stays the authority. ABSENT is a fact, not a gap: a run
+     * with no `a*` registry row (a SYNCHRONOUS delegated child, a workflow `wa*` agent, a
+     * top-level run) has no generation concept, and absence must never be read as "cycle 1".
+     */
+    seq?: number;
+    /** Workflow-lane self-identification (field-proven: the SSE-forwarded tick of a
+     *  WORKFLOW child previously carried a bare uuid with no workflow identity — indistinguishable
+     *  from an unknown nested subagent; the fleet lane had `wa*`+workflowRunId but this lane had
+     *  nothing). Present iff the tick bubbled out of a workflow-spawned agent. Additive. */
+    workflowRunId?: string;
+    /** the workflow agent's display label (opts.label / auto `agent-N`), riding with
+     *  {@link workflowRunId} for the same self-identification. Additive. */
+    workflowAgentLabel?: string;
+    /** design/99 (nested-subagent live tree): the spawning run's taskId — present on a DEEPER-than-1 subagent tick
+     *  (a subagent spawned by another subagent), forwarded via `RunInternals.onForwardEvent` so a UI nests the
+     *  node directly (this.taskId under parentTaskId) without mapping `parentToolCallId` → owner. The top-level
+     *  run is known to the consumer; its direct children carry the top's taskId here. Absent on a top-level tick. */
+    parentTaskId?: string;
+    /** design/99 BC-2 (Service AI [§I]): a short, single-line HUMAN display name for the subagent — its explicit
+     *  `taskName` or the selected agent-type. So a Fleet child row shows a readable label instead of the raw
+     *  `taskId` (the stable row identity stays the taskId). ABSENT when the subagent carries neither a taskName
+     *  nor an agent-type — the child then keeps its taskId (NOT the raw objective, which could leak a delegated
+     *  secret to a progress-scoped consumer — dual-review Q2). Sanitized (control-char-stripped, length-capped). */
+    name?: string;
+    /**
+     * The model this sub-run was PREPARED with — the resolved id, read off the leg's prepared model
+     * at the mint, so it is the same value `TaskResult.model` and the `task.start` trace frame carry.
+     * (`task.end` reports the run's totals and has never named a model; there is nothing to join to
+     * there.)
+     *
+     * Why it rides the live lane at all: a delegation may name a tier word (`"sonnet"`), an agent
+     * definition's model, or NOTHING (inherit the caller's current model, or fall to the `subagent`
+     * role) — every one of those resolves somewhere the consumer cannot see, so a shell badging a
+     * running child previously had only the REQUESTED word (or nothing) to render, which is a
+     * different claim from what the child runs on. This is the resolved answer, not the request.
+     *
+     * PREPARED, deliberately, and NOT "whatever is serving this turn" — stated in the first sentence
+     * because the difference is observable. A mid-run DEGRADE switch (`spec.limits.degrade`) or a
+     * gateway re-route moves the serving model without rewriting this field, exactly as
+     * `TaskResult.model` behaves; the switch is announced on its own channel (`TaskResult.degraded`),
+     * and the per-call served id lives on the brain-call telemetry. One name, one meaning, across the
+     * three faces that use it — at the cost of being the leg's declared model rather than a live one.
+     *
+     * Present on every tick this build mints (the frame family is subagent-only by construction, so
+     * there is no lane where a leg has no prepared model). Declared optional for the ordinary reason:
+     * a consumer folding frames from a pre-key producer must keep compiling, and absence there means
+     * "this producer did not state it", never "no model".
+     */
+    model?: string;
+    /** The child's most recent tool intent as one human line ("Bash npm test",
+     *  "Edit src/x.ts") — the SAME source/value as the registry sink tick's `currentAction` (residual
+     *  observability, lane B), attached to the FORWARDED frame because every client wire projects this
+     *  TaskEvent, not the sink (a deployment's projection legs otherwise see a permanently-absent field).
+     *  UNTRUSTED display hint — redact at the projection boundary. Absent until the child runs a tool. */
+    currentAction?: string;
+    usage: {
+        totalTokens: number;
+        toolUses: number;
+        durationMs: number;
+    };
+    /** Per-turn ticks are `"running"`. ONE final tick fires at the sub-run's settle with the
+     *  terminal face (`"completed"` | `"failed"` — timeout/blocked fold to failed; a suspended durable
+     *  pause emits no terminal tick), so a uuid-lane consumer sees the row finish instead of a bare
+     *  removal after the last running beat. Additive value space — a consumer switching on "running"
+     *  keeps its exact old behavior. */
+    status: "running" | "completed" | "failed";
+} & TaskEventIdentity) | ({
+    /**
+     * design/99 §E13 — the task's tracked working directory CHANGED mid-run (a `bash`
+     * `cd` moved it). Emitted live after the tool that moved it, carrying the new logical cwd, so a shell UI
+     * can update its prompt/path display. The tracked cwd is the RAW logical path (a `cd` through a symlink
+     * reports the raw path navigated, not the resolved target). Only fires when a real shell is mounted
+     * (absent under `handsReadOnly` / no-exec). The initial cwd is NOT announced (it is the known root); only
+     * subsequent changes are. A live observability signal — not persisted, and the tracked cwd RESETS to the
+     * root across a suspend/resume (the per-leg execution cwd is not durable today — a pre-existing limitation
+     * tracked with the E18/E19 execution-state durability work); within a leg, every `cd` move is reported.
+     */
+    type: "workspace_changed";
+    cwd: string;
+} & TaskEventIdentity) | ({
+    /**
+     * design/173 §2.4/§8.1 — this leg's EFFECTIVE wiring manifest: the machine-readable
+     * disclosure of how the run is assembled around the optional human-interaction seams
+     * (ask/question/elicit/park/durability/fleet/governance). Emitted ONCE PER PREPARED LEG
+     * (root/child/resume each get their own — per-leg assembly genuinely differs, e.g. the
+     * engine-stripped background lanes), after prepare and BEFORE the leg's first model/tool
+     * interaction; leg identity rides {@link TaskEventIdentity} plus `manifest.leg.kind`.
+     *
+     * DISCLOSURE, not verification (§0 guarantee boundary): seam presence/shape as facts —
+     * liveness (does the callback actually reach a human) is a round-trip probe's job.
+     * HOST/OPERATOR plane: the manifest never enters model context, and the `governance`
+     * section carries `audience: "operator"` — a serving layer forwarding this stream to a
+     * multi-tenant/shared consumer MUST project that section for operators only (its default,
+     * when it does no projection, is to not disclose the section). Additive: a consumer that
+     * ignores unknown event types is unchanged; consumers of the manifest itself must ignore
+     * unknown FIELDS (`schemaVersion` bumps only on a semantic break).
+     */
+    type: "wiring_manifest";
+    manifest: import("./wiring-manifest.js").WiringManifest;
+} & TaskEventIdentity) | {
+    type: "done";
+    result: TaskResult;
+};
+/** design/171 §6.2 — the `human_input` arm as a named type (Extract-derived: ONE source, the union
+ *  above — never a hand-copied second shape). What `buildHumanInputEvent` returns. */
+export type HumanInputEvent = Extract<TaskEvent, {
+    type: "human_input";
+}>;
+/**
+ * Outcome of a manual {@link TaskStream.compact} request (the enum names align with
+ * the diagnosis decision tree's drain exits, so a consumer can tell "202 processed" states apart):
+ * - `"compacted"` — a compaction landed at the boundary (the `compacted{trigger:"manual"}` event fired).
+ * - `"failed"` — the attempt ran and threw (summarizer failure / empty summary / oversized summary;
+ *   `compaction.failed` trace frame + `Runner.onError(phase:"compaction")`), or the §17.4 breaker was
+ *   already open so the request was drained without an attempt (`compaction.failed` frame, no attempt).
+ * - `"mooted"` — the request was processed but the run could no longer compact (dying loop: abort /
+ *   durable suspend / plan review in flight), or the task settled before any boundary arrived.
+ * - `"noop"` — the attempt ran but there was nothing to compact (no valid cut point / empty history).
+ * - `"blocked"` — a `preCompact` hook deliberately blocked this compaction (not a failure).
+ * - `"disabled"` — compaction is disabled by the task spec (`compaction.enabled: false`).
+ */
+export type CompactOutcome = "compacted" | "failed" | "mooted" | "noop" | "blocked" | "disabled";