@agent-compose/sdk 0.8.3 → 0.8.5

package/dist/runtimes/openai-desktop.test.d.ts

@@ -0,0 +1,20 @@
+/**
+ * openai-desktop runner spec — coordinate spaces (the incident pin).
+ *
+ * The model sees every screenshot downscaled to DISPLAY (1024×720) and emits
+ * coordinates in THAT space; the runner must map them back through EACH
+ * capture's REAL geometry — read from the screenshot buffer itself — before
+ * touching the provider. Pinned here:
+ *
+ *   - captureScaledScreenshot derives scaleX/scaleY from the frame's own
+ *     pixel dimensions, and two frames of differing geometry yield differing
+ *     scales (the fixed-constants regression);
+ *   - the legacy 1280×800 constants apply ONLY as a fallback when a frame's
+ *     metadata carries no dimensions;
+ *   - click/double/right/middle/move and BOTH drag endpoints scale; typed
+ *     text, key chords, and scroll tick counts pass through untouched;
+ *   - the sendMessage loop applies the CURRENT capture's scale to the calls
+ *     the model made against that capture, and refreshes the scale with
+ *     every new frame it sends back.
+ */
+export {};

package/dist/runtimes/tool-pulse.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tool-run pulse (child-telemetry contract, 2026-08-29) — the guest
+ * heartbeat's sample of the runner's own session, carried as the durable
+ * probe's trailing field. Pins:
+ *
+ *   1. the pulse token round-trips through the probe line (7th field),
+ *      and its absence (`-`, old guests) parses evidence-absent;
+ *   2. parseToolPulseToken rejects everything malformed — never a guess;
+ *   3. the probe command with a pulsePath reads it with the char
+ *      whitelist; without one it emits the `-` placeholder (the shape
+ *      stays 7 fields either way);
+ *   4. the heartbeat fragment writes the pulse file and never breaks the
+ *      beat on a guest without procps (`ps` failing degrades quiet);
+ *   5. a 5-field (pre-perf) and 6-field (pre-pulse) probe line still
+ *      parse — old guests are evidence-absent, never errors.
+ */
+export {};

package/dist/sandbox/devbox.d.ts

@@ -5,13 +5,13 @@
  * This module is the SINGLE SOURCE for the machine's template identity: the
  * recipe lives in `infra/e2b-template/devbox.ts`, `infra/e2b-template/build.ts`
  * bakes it under the alias below, and the server imports the alias from here to
- * provision a machine (exactly how `e2bBaseTemplate` reaches the E2B provider —
- * a stable ALIAS, never a snapshot id, so the same string resolves in whichever
- * E2B account a deployment uses).
+ * provision a machine (exactly how `e2bAgentEnvTemplate` reaches the E2B
+ * provider — a stable ALIAS, never a snapshot id, so the same string resolves
+ * in whichever E2B account a deployment uses).
  *
  * Interactive only. Workflow RUNS never execute on a devbox (ADR-0038 §2.6):
- * runs boot the clean per-size `agent-compose-base-<size>` / `agent-env-<size>`
- * templates so reproducibility never inherits hand-configured drift.
+ * runs boot the clean per-size `agent-env-<size>` template (the same image
+ * sessions boot) so reproducibility never inherits hand-configured drift.
  */
 /** Stable E2B template ALIAS for the per-member desktop machine. Baked by
  *  `infra/e2b-template/build.ts` from `infra/e2b-template/devbox.ts`; CI rebakes

package/dist/sandbox/registry.d.ts

@@ -9,6 +9,18 @@ import type { SandboxProvider } from "../types/sandbox.js";
 import type { SandboxCreateOpts, SandboxProviderDef, OwnedSandbox } from "./provider-def.js";
 export type SandboxProviderName = "vercel" | "e2b" | "e2b-desktop";
 export declare const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef>;
+/** Did a CREATE fail because its create SOURCE (template alias / snapshot id)
+ *  does not resolve on the provider — vs any other create fault? The server's
+ *  recovery-boot fall-through keys on this: a ring snapshot licensed on an
+ *  INDETERMINATE existence probe that turns out to be gone must fall through
+ *  the ring toward the base image, while every other create fault (quota,
+ *  auth, 5xx, network) must propagate — falling through on those would trade
+ *  a still-recoverable machine state for a base boot. E2B maps the create-
+ *  time 404 ("template not found") to its typed `NotFoundError`; the message
+ *  match is the fallback for untyped transports (Vercel). Lives in the SDK
+ *  because the server holds its OWN `e2b` module instance — an `instanceof`
+ *  against the class from the wrong copy is always false. */
+export declare function isSandboxSourceNotFoundError(error: unknown): boolean;
 /** Provision a sandbox for the named provider. */
 export declare function createSandbox(provider: SandboxProviderName, opts: SandboxCreateOpts): Promise<SandboxProvider>;
 /** Reconnect to an existing sandbox by provider + provider-native sandbox ID. */

package/dist/sandbox/sizes.d.ts

@@ -138,12 +138,18 @@ export declare function sandboxSizeLabel(size: SandboxSize): string;
 /** Stable E2B template ALIAS for the platform base at a given size
  *  (`agent-compose-base-<size>`). Aliases — not snapshot ids — so the refs are
  *  multi-account-clean: the same string resolves in any E2B account that built
- *  the templates. Built by `infra/e2b-template/build.ts`; the E2B provider
- *  boots this when a run on E2B declares no explicit `bootFrom`/template. */
+ *  the templates. Built by `infra/e2b-template/build.ts`. An EXPLICIT
+ *  `bootFrom`/template target only — nothing boots it by default: template-less
+ *  E2B creates resolve `e2bAgentEnvTemplate` (the session-identical image)
+ *  instead, so the run and session lanes can never diverge on baked tooling. */
 export declare function e2bBaseTemplate(size: SandboxSize): string;
-/** Stable E2B template ALIAS for the agent runtime (base + claude binary) at a
- *  given size (`agent-env-<size>`). The agent default templates boot from this
- *  via `bootFrom: { snapshotId: e2bAgentEnvTemplate(size) }`. Multi-account-clean
+/** Stable E2B template ALIAS for the agent runtime (base + claude binary +
+ *  dev toolbelt + session desktop) at a given size (`agent-env-<size>`).
+ *  THE default E2B boot image, both lanes: every cloud SESSION boots it
+ *  (server/src/sandbox/persistent.ts), and every template-less E2B workflow
+ *  RUN boots it too (the e2b provider's size-matched default). The agent
+ *  default templates boot from this via
+ *  `bootFrom: { snapshotId: e2bAgentEnvTemplate(size) }`. Multi-account-clean
  *  for the same reason as `e2bBaseTemplate`. */
 export declare function e2bAgentEnvTemplate(size: SandboxSize): string;
 /** Is `id` one of the platform-managed E2B template aliases — a

package/dist/sandbox.d.ts

@@ -20,9 +20,9 @@ export { AGENT_COMPOSE_TAG } from "./sandbox/provider-def.js";
 export type { SandboxCreateOpts, OwnedSandbox } from "./sandbox/provider-def.js";
 export { parseSseExecStream } from "./sandbox/exec-stream.js";
 export type { ParseSseExecStreamOptions } from "./sandbox/exec-stream.js";
-export { makeSandboxProvider } from "./sandbox/providers/e2b.js";
+export { makeSandboxProvider, e2bMaxSandboxMs } from "./sandbox/providers/e2b.js";
 export { makeDesktopSandboxProvider } from "./sandbox/providers/desktop.js";
 export { VERCEL_MAX_TAGS, buildVercelTags } from "./sandbox/providers/vercel.js";
 export { makeLocalSandboxProvider } from "./sandbox/providers/local.js";
-export { SANDBOX_PROVIDERS, createSandbox, reconnectSandbox, deleteSandboxSnapshot, snapshotResolves, getSandboxQuotas, listOwnedSandboxes, killSandboxById, killAllSandboxes, } from "./sandbox/registry.js";
+export { SANDBOX_PROVIDERS, createSandbox, reconnectSandbox, deleteSandboxSnapshot, snapshotResolves, isSandboxSourceNotFoundError, getSandboxQuotas, listOwnedSandboxes, killSandboxById, killAllSandboxes, } from "./sandbox/registry.js";
 export type { SandboxProviderName, SandboxQuotaResult, OwnedSandboxResult } from "./sandbox/registry.js";

package/dist/step-invocation/types.d.ts

@@ -54,10 +54,10 @@ export type StepResult<TOutput = unknown> = {
 export declare const StepPauseRequestSchema: z.ZodObject<{
     reason: z.ZodString;
     kind: z.ZodEnum<{
+        event: "event";
         custom: "custom";
         decision: "decision";
         sleep: "sleep";
-        event: "event";
     }>;
     payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     ttlMs: z.ZodOptional<z.ZodNumber>;

package/dist/types/api-conversations.d.ts

@@ -432,6 +432,48 @@ export interface BackgroundWorkHeld {
     /** ISO timestamp the lease now runs to. */
     leaseUntil: string;
 }
+/** One background CHILD declared beside the busy lease (task #63): a
+ *  detached process, by pid, with its durable journal/log file — what lets
+ *  the platform VERIFY the work (`/proc/<pid>` + journal mtime) and
+ *  reattach it after a park instead of losing it. */
+export interface BackgroundWorkChildDecl {
+    pid: number;
+    /** Absolute guest-side path to the child's own durable output/journal
+     *  file — its mtime is the progress evidence. */
+    journalPath?: string;
+    label?: string;
+}
+/** Outcome of requesting one machine size up
+ *  (`POST /conversations/:id/machine/request-upsize` — task #110, the
+ *  auto-resize policy's agent door). The platform arbitrates: within the
+ *  team's daily cap the upsize is auto-granted (and lands immediately when
+ *  no turn/background work holds the machine); past it a human approval
+ *  card is posted. Wire shape mirrors
+ *  server/src/sandbox/session-auto-resize.ts `UpsizeRequestOutcome`. */
+export interface MachineUpsizeOutcome {
+    /** "executed" (landed now), "granted" (lands when the work settles),
+     *  "pending_approval" (a card awaits the owner). Refusals arrive as HTTP
+     *  errors carrying `code`. */
+    outcome: "executed" | "granted" | "pending_approval";
+    /** The size the grant/card names (e.g. "4vcpu-8gb"). */
+    size: string;
+    approvalId: string;
+    /** One human-readable line the CLI can print verbatim. */
+    message: string;
+}
+/** The session's background-work status
+ *  (`GET /conversations/:id/background-work`). */
+export interface BackgroundWorkStatus {
+    /** ISO deadline of the live lease, or null (no lease held). */
+    leaseUntil: string | null;
+    /** The declared children (each with its server-stamped `declaredAt`). */
+    children: Array<BackgroundWorkChildDecl & {
+        declaredAt: string;
+    }>;
+    /** Non-null when a mid-work park froze declared children and the session
+     *  still owes its conversation a status report (ISO park instant). */
+    frozenAt: string | null;
+}
 /** One changed file on a session's drive branch relative to `main`. */
 export interface SessionFileChange {
     /** Factory-relative path. */
@@ -510,11 +552,9 @@ export interface SessionChangeSet {
      *  (hard cap 2; a manual re-review resets it). */
     reviewAutoFollowup?: boolean;
     reviewAutoRounds?: number;
-    /** The OPT-IN main-advance auto-rebase reflex (additive — absent on
-     *  older servers; default OFF): armed ⇒ when main moves and a preflight
-     *  proves the fold clean, the platform rebases this session's branch
-     *  from main headlessly. Toggled via `setSessionAutoRebase`. */
-    autoRebaseFromMain?: boolean;
+    /** The session's selectable cap on automatic follow-up rounds (additive
+     *  — absent on older servers; default 2, range 1..5). */
+    reviewAutoRoundsMax?: number;
     /** STRUCTURED review suggestions beside the notes (additive — absent on
      *  older servers): individually actionable {id, path, title, rationale,
      *  patch} entries the review session wrote back, status-stamped
@@ -801,13 +841,6 @@ export interface SessionRebaseReport {
      *  skipped whole (an unlisted conflicted path must never be overwritten). */
     foldSkipped?: boolean;
 }
-/** Result of `POST /conversations/:id/changes/autorebase` — the opt-in
- *  main-advance auto-rebase reflex's new state. */
-export interface SessionAutoRebaseState {
-    object: "session_autorebase";
-    conversationId: string;
-    autoRebaseFromMain: boolean;
-}
 /** The sender's page stamp (HUD bar sends) — persisted server-side, never
  *  echoed back on the wire. Mirrors the server's `PageContext` schema. */
 export interface ConversationPageContext {
@@ -996,3 +1029,43 @@ export interface StreamConversationOptions {
     lastEventId?: number;
     signal?: AbortSignal;
 }
+/** Shared chat creation includes its own Ivy unless explicitly disabled. */
+export interface CreateChatInput {
+    title?: string;
+    visibility: "shared";
+    access?: "public" | "private";
+    memberIds?: string[];
+    includeIvy?: boolean;
+}
+export interface ChannelIvyState {
+    projects: Array<{
+        id: string;
+        name: string;
+    }>;
+    agent: AgentListRow | null;
+    enabled: boolean;
+    agentId: string | null;
+    canManage: boolean;
+    nextReviewAt: string | null;
+    work: Array<{
+        id: string;
+        title: string;
+        status: string;
+        evidence: string;
+        nextAction: string;
+        waitingOn: string | null;
+        reviewAt: string | null;
+    }>;
+}
+export interface ProjectIvyConnection {
+    id: string;
+    teamId: string;
+    projectId: string;
+    provider: "github";
+    installationId: string;
+    accountLogin: string;
+    repositories: string[];
+    allowWrites: boolean;
+    configuredBy: string | null;
+    updatedAt: string;
+}

package/dist/types/api-factory.d.ts

@@ -100,9 +100,15 @@ export interface RegisterWorkflowInput {
 export interface TemplateRow {
     name: string;
     version: string;
-    factorySlug: string;
+    /** Owning factory's slug. `null` on platform-published rows — a published
+     *  default belongs to no single factory and is invokable via any slug. */
+    factorySlug: string | null;
     /** Share scope (ADR-0045) — `null` = unscoped/grandfathered team tier. */
     scope: ArtifactScope | null;
+    /** `factory` = registered in a factory of the caller's team; `published` =
+     *  platform default (team-wide read+invoke in EVERY factory, never write;
+     *  fork it to edit under a new name). Optional: older servers omit it. */
+    origin?: "factory" | "published";
 }
 /** Template detail (`GET /factories/:slug/templates/:name`) — the typed
  *  subset the SDK pins; the route returns additional registration fields
@@ -122,6 +128,16 @@ export interface TemplateDetail {
 export interface ListTemplatesOptions {
     factorySlug?: string;
 }
+/** One team connector grant, as `GET /api/v1/connectors` returns it (wire
+ *  shape verbatim — snake_case). The typed subset the SDK pins; additional
+ *  fields flow through untyped. */
+export interface ConnectorGrantSummary {
+    id: string;
+    provider: string;
+    external_account_label: string | null;
+    status: "active" | "revoked" | "reauth_required";
+    connected_by_user_id: string;
+}
 /** Public "anyone with the link" state — the additive `public` field on file
  *  rows (list/ls/search). The token is the whole capability, so an enabled
  *  row carries it ONLY for viewers holding the document's share authority
@@ -352,6 +368,24 @@ export interface SessionSecretRequestCreated {
     requestId: string;
     url: string;
     expiresAt: string;
+    /** True = a standing auto-approve set already filled the request at the
+     *  mint — nothing is pending; source the session env now. */
+    autoApproved?: boolean;
+}
+/** What KIND of credential a vault request asks for (advisory): the vault
+ *  page leads with the user's MATCHING standing entries. */
+export type VaultRequestKind = "login" | "password" | "api_key" | "payment_card" | "env_file" | "note" | "other";
+/** One STANDING vault entry usable for a session (the catalog read,
+ *  2026-08-31) — labels, kinds, and field NAMES only; values are write-only
+ *  and never on this wire. */
+export interface VaultCatalogEntry {
+    label: string;
+    kind: string;
+    fieldKeys: string[];
+    via: "owner" | "member" | "project";
+    ownerName: string | null;
+    projectName: string | null;
+    lastUsedAt: string | null;
 }
 /** A vault link's polled status. */
 export interface SessionSecretRequestStatus {
@@ -359,6 +393,25 @@ export interface SessionSecretRequestStatus {
     status: "pending" | "fulfilled" | "cancelled" | "expired";
     keys: string[];
     expiresAt: string;
+    /** Cancellation attribution (task #111) — present on cancelled rows:
+     *  who ended the ask ('human' = denied; 'agent' = withdrawn) and why. */
+    cancelledVia?: "human" | "agent";
+    cancelReason?: string | null;
+    /** The denying human's display name (best-effort; 'human' via only). */
+    deniedByName?: string | null;
+    /** Newest USER message in the session SINCE the mint (pending rows only)
+     *  — the chat-interrupt probe: the human may be answering in chat while
+     *  the agent blocks on --wait. */
+    userMessageAt?: string;
+}
+/** One OPEN vault request, as the list endpoint returns it — receipts
+ *  only (keys + reason + clocks), never values. */
+export interface SessionSecretRequestSummary {
+    requestId: string;
+    keys: string[];
+    reason: string | null;
+    expiresAt: string;
+    createdAt: string;
 }
 export interface CreateApiKeyInput {
     name?: string;
@@ -480,6 +533,21 @@ export interface DriveRepoLink {
  *  auto-unlink; capped at 100 branches). Explicit `trackedBranches`:
  *  index 0 is the PRIMARY and keeps the plain placement; every additional
  *  branch lands at the sibling `dirPrefix@<sanitized-branch>` placement. */
+/** POST /factories/:slug/repo-links/native — a repo whose origin IS the
+ *  platform git plane (no GitHub side). `name` is ONE segment of GitHub's
+ *  repo alphabet; `dirPrefix` defaults to `repos/<name>`. */
+export interface CreateNativeRepoInput {
+    name: string;
+    dirPrefix?: string;
+}
+export interface CreateNativeRepoResult {
+    link: DriveRepoLink;
+    /** Stock-git clone/push URL on the platform origin (credentials are
+     *  minted per operation by `agentc repos git-credential --link`). */
+    repoUrl: string;
+    /** The CLI one-liner: `agentc repos clone <id> --via origin`. */
+    cloneCommand: string;
+}
 export interface CreateDriveRepoLinkInput {
     dirPrefix: string;
     repoFullName: string;
@@ -489,3 +557,45 @@ export interface CreateDriveRepoLinkInput {
     /** Two-way sync ("push-out") — defaults to TRUE for new links. */
     pushOut?: boolean;
 }
+/** A retained merge conflict. Resolution edits a live session branch;
+ * publication still goes through its normal merge and approval gates. */
+/** A project-scoped secret's METADATA (scoped-secrets spec §4.1) — names
+ * only; values are write-only. Reaches SESSIONS linked into the project whose
+ * owner is a live member; workflow runs never receive project secrets. */
+export interface ProjectSecretMeta {
+    id: string;
+    projectId: string;
+    secretKey: string;
+    createdBy: string | null;
+    delivery: "injected" | "brokered";
+    brokerHost: string | null;
+    brokerHeaderName: string | null;
+    brokerHeaderScheme: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+}
+export interface ProjectSecretList {
+    secrets: ProjectSecretMeta[];
+    tier: "project";
+    audience: "sessions";
+}
+export interface FactoryFileConflict {
+    id: string;
+    path: string;
+    conversationId: string | null;
+    runId: string | null;
+    runLabel: string | null;
+    reason: "same_region" | "binary" | "delete_vs_edit";
+    oursHash: string | null;
+    theirsHash: string | null;
+    baseHash: string | null;
+    status: string;
+    createdAt: string;
+    resolvesTo: "branch" | "main";
+}
+export interface FactoryFileConflictList {
+    object: "list";
+    data: FactoryFileConflict[];
+    has_more: boolean;
+    next_cursor: string | null;
+}

package/dist/types/conversation-stream.d.ts

@@ -119,6 +119,15 @@ export interface ConversationTurnStateEvent {
     pendingCount: number;
     at: number;
     partial: true;
+    /** When the open turn started (ms) — carried by the connect-time
+     *  snapshot frame only; absent on live transition frames. */
+    startedAt?: number | null;
+    /** The session holds a live background-work lease (snapshot frames
+     *  only). */
+    leaseHeld?: boolean;
+    /** The open turn is blocked on a HUMAN ask — an open vault/secret
+     *  request or approval (snapshot frames only). */
+    blockedOnAsk?: "secrets" | "approval" | null;
 }
 /** One attached surface (a dashboard tab, an `agentc session` TUI process)
  *  as carried on a `presence` beat. Clients key the roster on `clientId` —
@@ -169,7 +178,19 @@ export interface ConversationSessionStatusEvent {
     state: "running" | "idle";
     at: number;
 }
-export type ConversationStreamEvent = ConversationPartEvent | ConversationPartPartialEvent | ConversationMessageDoneEvent | ConversationErrorEvent | ConversationReactionEvent | ConversationMessageDeletedEvent | ConversationReplayContinueEvent | ConversationTurnStateEvent | ConversationPresenceEvent | ConversationSessionStatusEvent;
+/** Live-only tool-run pulse (2026-08-29): the running turn's guest session
+ *  PROVED progress (CPU/output counters advanced between heartbeat pulse
+ *  samples) while the stream was otherwise silent — a long foreground tool
+ *  (`bun install`) is working. Emitted at the executor's evidence-tick
+ *  cadence, only on proof; carries no output content. Same contract as
+ *  `turn_state`: never persisted, never advances `Last-Event-ID`. */
+export interface ConversationToolPulseEvent {
+    event: "tool_pulse";
+    conversationId: string;
+    advancing: true;
+    at: number;
+}
+export type ConversationStreamEvent = ConversationPartEvent | ConversationPartPartialEvent | ConversationMessageDoneEvent | ConversationErrorEvent | ConversationReactionEvent | ConversationMessageDeletedEvent | ConversationReplayContinueEvent | ConversationTurnStateEvent | ConversationPresenceEvent | ConversationSessionStatusEvent | ConversationToolPulseEvent;
 /**
  * Fold one parsed SSE frame into a `ConversationStreamEvent`.
  *

package/dist/types/protocol.d.ts

@@ -144,7 +144,136 @@ export interface AgentMessageTaskNotification extends AgentMessageBase {
         durationMs?: number;
     };
 }
-export type AgentMessage = AgentMessageInit | AgentMessageText | AgentMessageTextDelta | AgentMessageThinking | AgentMessageToolUse | AgentMessageToolResult | AgentMessageDone | AgentMessageError | AgentMessageUsage | AgentMessageUsageDelta | AgentMessagePlan | AgentMessageTaskNotification;
+/** One entry of a harness workflow's live progress feed — the
+ *  `workflow_progress` array claude-code's `system`/`task_progress` events
+ *  carry for its in-harness Workflow tool (the dynamic-workflow
+ *  orchestrator). `phase` entries are the script's declared phases (seeded
+ *  up front, 1-based `index`); `agent` entries are the spawned workflow
+ *  agents, updated in place as they queue → run → settle. Preview text the
+ *  harness includes (prompt/result previews) is internal plumbing and is
+ *  deliberately NOT forwarded — same rule as task notifications. */
+export type WorkflowProgressEntry = {
+    kind: "phase";
+    index: number;
+    title: string;
+} | {
+    kind: "agent";
+    index: number;
+    label: string;
+    /** Lifecycle: `start` (spawned) / `progress` (heartbeat) are live;
+     *  `done` / `error` are settled. Verbatim from the harness. */
+    state: "start" | "progress" | "done" | "error";
+    phaseIndex?: number;
+    phaseTitle?: string;
+    model?: string;
+    agentId?: string;
+    /** Self-reported usage so far (cumulative for this agent). */
+    tokens?: number;
+    toolCalls?: number;
+    durationMs?: number;
+    /** Epoch ms the agent actually started (for live elapsed). */
+    startedAt?: number;
+    /** The failure message when `state: "error"`, clamped. */
+    error?: string;
+    /** Replayed from a resume cache — settled instantly, no fresh spend. */
+    cached?: true;
+    /** Skipped by the user (workflow dialog) — an error state that is
+     *  not a failure. */
+    skipped?: true;
+};
+/** LIVE progress of a harness BACKGROUND task (claude-code
+ *  `system`/`task_progress`). For the in-harness Workflow tool the message
+ *  carries the CUMULATIVE `workflow_progress` entry array (the harness
+ *  re-sends the whole picture: state changes immediately, heartbeats
+ *  throttled ~10s), so a consumer treats the latest message as
+ *  authoritative per entry `(kind, index)`. A plain background AGENT task
+ *  (Task tool, run_in_background) heartbeats on the same event with NO
+ *  workflow entries — forwarded with `workflow: []` as liveness evidence
+ *  so the platform can declare the running task as session background
+ *  work; its completion evidence rides `task_notification`. `toolUseId`
+ *  names the spawning call — the correlation key to its card. Additive
+ *  kind: existing producers never emit it. */
+export interface AgentMessageTaskProgress extends AgentMessageBase {
+    type: "task_progress";
+    /** The harness's background task id. */
+    taskId: string;
+    /** The SPAWNING Workflow/Task call's tool_use id, when carried. */
+    toolUseId?: string;
+    /** The task's cumulative usage totals so far. */
+    usage?: {
+        tokens?: number;
+        toolUses?: number;
+        durationMs?: number;
+    };
+    /** The cumulative workflow progress entries — EMPTY for a plain
+     *  background Agent-task heartbeat (only Workflow tasks carry entries). */
+    workflow: WorkflowProgressEntry[];
+}
+/** HARNESS-authored notice text — content the CLI composed itself rather
+ *  than the model speaking: slash-command stdout, model/skills advisories,
+ *  queued-input notes. claude-code marks these structurally (assistant
+ *  events whose `message.model` is `"<synthetic>"`), and the normaliser
+ *  forwards them under this kind so downstream persists them as collapsed
+ *  system notices instead of agent prose (the 2026-08-22 "(session model)"
+ *  / skills-reminder leak: harness plumbing rendered as message content).
+ *  Additive kind: existing producers never emit it. */
+export interface AgentMessageHarnessNotice extends AgentMessageBase {
+    type: "harness_notice";
+    text: string;
+}
+/** Context-compaction lifecycle — the harness summarizing its own
+ *  conversation to reclaim context. Mapped 1:1 from claude-code's wire
+ *  (verified live on 2.1.212, the baked sandbox pin, and 2.1.241 — both
+ *  emit the identical shapes, `/compact` and auto alike):
+ *
+ *    `system`/`status` `{status:"compacting"}`            → phase "start"
+ *    `system`/`status` `{status:null, compact_result,     → phase "settled"
+ *                        compact_error?}`
+ *    `system`/`compact_boundary` `{compact_metadata:      → phase "boundary"
+ *      {trigger, pre_tokens, post_tokens,
+ *       cumulative_dropped_tokens, duration_ms, …}}`
+ *
+ *  Order on the wire: start → settled → (fresh init) → boundary → the
+ *  continuation summary as a SYNTHETIC user message (never forwarded — it
+ *  quotes conversation content verbatim). "boundary" only follows a
+ *  successful settle and only on the turn the compaction ran (verified: it
+ *  does NOT replay on later resumes). A compaction can span MINUTES of
+ *  otherwise-silent stream — the whole point of forwarding it is that
+ *  downstream can show the silence as work (the 2026-08-23 dead-air
+ *  incident: 94% auto-compact read as a dead session). Additive kind:
+ *  existing producers never emit it. */
+export interface AgentMessageCompaction extends AgentMessageBase {
+    type: "compaction";
+    phase: "start" | "settled" | "boundary";
+    /** settled: how it ended. Absent on start/boundary (a boundary IS a
+     *  success by construction — the harness only emits it after one). */
+    result?: "success" | "failed";
+    /** settled+failed: the harness's own reason, clamped. */
+    error?: string;
+    /** boundary: what initiated the compaction. */
+    trigger?: "auto" | "manual";
+    /** boundary: context tokens before / after, dropped total, wall time. */
+    preTokens?: number;
+    postTokens?: number;
+    droppedTokens?: number;
+    durationMs?: number;
+}
+/** A user-role message landing INSIDE a subagent's thread — the delivered
+ *  form of a steer (the parent's `SendMessage` to a RUNNING child, queued
+ *  "for delivery at its next tool round") or any other message the harness
+ *  folds into a child's conversation mid-flight. Emitted ONLY with sidechain
+ *  attribution: `parentToolUseId` (the spawning Agent/Task call's tool_use
+ *  id) is REQUIRED — an unattributed user event is the parent's own prompt
+ *  echo, which stays unmapped as before. Lets renderers show the steer as a
+ *  user-role message inside the child's mini-session instead of leaving it
+ *  an opaque SendMessage tool call on the parent only (task #97, owner
+ *  directive 2026-08-27). Additive kind: existing producers never emit it. */
+export interface AgentMessageSubagentUserMessage extends AgentMessageBase {
+    type: "subagent_user_message";
+    text: string;
+    parentToolUseId: string;
+}
+export type AgentMessage = AgentMessageInit | AgentMessageText | AgentMessageTextDelta | AgentMessageThinking | AgentMessageToolUse | AgentMessageToolResult | AgentMessageDone | AgentMessageError | AgentMessageUsage | AgentMessageUsageDelta | AgentMessagePlan | AgentMessageTaskNotification | AgentMessageTaskProgress | AgentMessageHarnessNotice | AgentMessageCompaction | AgentMessageSubagentUserMessage;
 /** Status block the agent emits to signal iteration completion or blockers. */
 export interface AgentStatus {
     summary: string;