@agent-compose/sdk 0.8.3 → 0.8.5

package/src/types/protocol.ts

@@ -147,6 +147,128 @@ export interface AgentMessageTaskNotification extends AgentMessageBase {
   usage?: { tokens?: number; toolUses?: number; durationMs?: number };
 }
 
+/** 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
@@ -159,7 +281,11 @@ export type AgentMessage =
   | AgentMessageUsage
   | AgentMessageUsageDelta
   | AgentMessagePlan
-  | AgentMessageTaskNotification;
+  | AgentMessageTaskNotification
+  | AgentMessageTaskProgress
+  | AgentMessageHarnessNotice
+  | AgentMessageCompaction
+  | AgentMessageSubagentUserMessage;
 
 /** Status block the agent emits to signal iteration completion or blockers. */
 export interface AgentStatus {

package/src/types/runtime.ts

@@ -94,6 +94,16 @@ export interface RuntimeOptions {
    *  Absent ⇒ nothing extra is sourced. Must be a plain absolute path — no
    *  quotes, no `..`; the runtime validates and drops anything else. */
   credEnvFile?: string;
+  /** Durable launch report (boot-time turn adoption): called by the durable
+   *  detached transport the moment its in-guest runner exists — with the
+   *  guest prompt path (every durable file derives from it), the exit
+   *  sentinel string, and the detached wrapper's pid. The caller stamps
+   *  these on the turn row so a SUCCESSOR process (a deploy roll's new
+   *  server) can re-attach to the runner's durable `.out` without this
+   *  process's memory. Fired once per detached launch (a retry with a fresh
+   *  runner fires again with the new paths); never on transports without
+   *  durable files. Must not throw — the transport calls it inline. */
+  onDetachedLaunch?: (info: { promptPath: string; sentinel: string; pid: number }) => void;
 }
 
 /** Three-valued liveness verdict for a runtime's CURRENT turn, read from
@@ -182,6 +192,21 @@ export interface ModelExecutionContract {
    * fallback probe it already had; null is never a verdict.
    */
   probeTurnLiveness?(): Promise<RunnerLivenessVerdict | null>;
+  /**
+   * TELEMETRY, NEVER A VERDICT (tool-run pulse, 2026-08-29): the newest
+   * tool-run pulse the durable liveness probe carried — the guest
+   * heartbeat's sample of the runner's own session (aggregate CPU jiffies,
+   * written bytes, live process count) plus the guest clock it was read
+   * against. The executor's evidence ticker peeks it AFTER its liveness
+   * check and compares successive samples: counters ADVANCING is proof a
+   * long silent foreground tool is working, fanned to clients as a live
+   * `tool_pulse` frame. Never probes on its own; null before any probe or
+   * on a transport without the pulse file. No liveness decision may ever
+   * read it.
+   */
+  peekTurnPulse?(): {
+    atMs: number; cpuJiffies: number; ioBytes: number; procs: number; guestNowMs: number;
+  } | null;
   /**
    * DOORBELL, NEVER A VERDICT (exit-event push, v0.10.43): wake the current
    * turn's durable watchdog NOW so it runs its normal verification pass —
@@ -232,6 +257,44 @@ export interface ModelExecutionContract {
    * Calls are serialized per turn; never throws.
    */
   injectUserMessage?(text: string): Promise<"delivered" | "pending" | "closed" | "unsupported">;
+  /**
+   * Request an in-band STEP INTERRUPT of the currently running turn — the
+   * ESC equivalent. Where `injectUserMessage` queues content for the turn
+   * loop's next boundary, this rides the same durable inbox but carries a
+   * control line the CLI handles immediately, mid-step included: the
+   * running tool call aborts, the run ends within ~100ms, and the guest
+   * session stays resumable with the whole turn context (verified live
+   * against claude 2.1.236). Verdicts mirror `injectUserMessage`; only
+   * "delivered" means the CLI got the control line — callers escalate
+   * anything else (and "unsupported": no stream-input turn, or a runtime
+   * with no in-band interrupt, e.g. codex) to kill semantics, which stay
+   * honest because thread stores are durable and the successor turn
+   * resumes them. Never throws.
+   */
+  interruptTurn?(): Promise<"delivered" | "pending" | "closed" | "unsupported">;
+  /**
+   * Guest pid of the CURRENT turn's detached runner wrapper (the setsid
+   * process-group leader recorded at launch), or null when no detached
+   * durable-transport runner is live (boot phase, ACP path, single-exec
+   * transports). Advisory identity, NEVER a liveness verdict: the platform
+   * reads it to DECLARE harness-reported background work (an in-harness
+   * Workflow task) against the process tree that hosts it, so the park
+   * machinery can verify the tree from `/proc/<pid>` later. Runtimes
+   * without a detached guest simply omit the method.
+   */
+  currentRunnerPid?(): number | null;
+  /**
+   * Durable byte offset of the CURRENT turn's `.out` file just past the
+   * last line whose messages have ALL been yielded to the consumer — the
+   * safe harvest watermark for boot-time turn adoption. Null when no
+   * durable-transport turn is live, or before the first line completes.
+   * The contract is deliberately one line BEHIND the parse cursor: a
+   * caller that persists parts after each yielded message may stamp this
+   * offset at any time and a successor re-parses AT MOST the line whose
+   * parts were mid-persist (the same crash window the workflow tailer's
+   * flush-before-advance ordering accepts). Advisory, never a verdict.
+   */
+  currentTurnDurableOffset?(): number | null;
   sendMessage(opts: {
     prompt: string;
     sessionId?: string;