pi-ptc-subagents 0.1.2 → 1.0.0

package/dist/index.d.ts

@@ -1,5 +1,466 @@
-import { ExtensionAPI, Skill } from "@earendil-works/pi-coding-agent";
+import { ExtensionAPI, Skill, truncateTail } from "@earendil-works/pi-coding-agent";
+import "@earendil-works/pi-ai";
 import { MessagePort, Worker } from "node:worker_threads";
+//#region src/runtime/ulid.d.ts
+/**
+ * Lexically-sortable identifier (26-char Crockford base32). Brand-only: the runtime value is a
+ * plain `string`, the brand is a compile-time distinction that keeps a taskId from being
+ * passed into a cursor slot.
+ */
+type ULID = string & {
+  readonly __brand: "ULID";
+};
+//#endregion
+//#region src/runtime/child-process-lifecycle.d.ts
+/**
+ * One line of the child's stdout, parsed as JSON. The child emits the events described
+ * in examples/extensions/subagent/index.ts (message_end, tool_result_end, error).
+ * Anything unparseable is dropped: the line is one event the host cannot interpret,
+ * and the run continues.
+ */
+interface ParsedAgentEvent {
+  type: string;
+  message?: {
+    role?: string;
+    content?: ReadonlyArray<{
+      type?: string;
+      text?: string;
+    }>;
+    usage?: {
+      input?: number;
+      output?: number;
+      cacheRead?: number;
+      cacheWrite?: number;
+      cost?: {
+        total?: number;
+      };
+    };
+    model?: string;
+    stopReason?: string;
+    errorMessage?: string;
+  };
+  message_text?: string;
+}
+/**
+ * Opaque per-handle state owned by the adapter that produced it. The dispatch code
+ * never reads `opaque` directly; it only hands the handle back to adapter methods
+ * (`kill`, `events`, `exit`, `stderr`).
+ */
+interface ChildHandle {
+  readonly id: ULID;
+  readonly opaque: unknown;
+}
+/**
+ * Spawn options shared by both adapters. `promptFile` / `sessionDir` / `sessionId` /
+ * `sessionName` are the R1 fields the background dispatch consumes (ADR-0022 §1/R1). The
+ * foreground `pi.dispatch` path passes only `cwd` / `env` / `signal` / `promptFile`.
+ */
+interface ChildSpawnOptions {
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  signal?: AbortSignal;
+  promptFile: string;
+  sessionDir?: string;
+  sessionId?: string;
+  sessionName?: string;
+}
+/** Process-exit shape the `close` event on `node:child_process.ChildProcess` produces. */
+interface ChildExitValue {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+}
+/**
+ * The lifecycle contract. Implementations:
+ *   - `RealChildProcessLifecycle` - wraps `node:child_process.spawn` (production).
+ *   - `MockChildProcessLifecycle` - in-memory queue + exit signal (tests).
+ */
+interface ChildProcessLifecycle {
+  /**
+   * Launch one child process. The first element of `argv` is the executable; the rest
+   * are forwarded as command-line arguments. Returns an opaque handle the caller uses
+   * to talk to the same child via the other methods.
+   *
+   * `opts.env` is the full environment for the child; the caller is responsible for
+   * merging anything the child needs (e.g. `PI_PTC_DEPTH`) on top of `process.env`.
+   */
+  spawn(argv: readonly string[], opts: ChildSpawnOptions): ChildHandle;
+  /**
+   * Send `signal` to the child iff it is still attached. Absorbs "process already gone"
+   * throws so callers can fire-and-forget on cancel. Mirrors `safeKill` below.
+   */
+  kill(handle: ChildHandle, signal: "SIGTERM" | "SIGKILL"): void;
+  /**
+   * Async iterator over the child's stdout events. Yields one `ParsedAgentEvent` per
+   * JSONL line. The iterator ends after the child closes; callers should `await` it
+   * fully before reading `exit()`.
+   */
+  events(handle: ChildHandle): AsyncIterable<ParsedAgentEvent>;
+  /**
+   * Resolve when the child closes, with `(code, signal)` matching `node:child_process`'s
+   * `close` event. A clean exit is `(0, null)`; a signal kill is `(null, <signal>)`;
+   * a spawn failure surfaces as `(null, null)` once the error event has propagated.
+   */
+  exit(handle: ChildHandle): Promise<ChildExitValue>;
+  /**
+   * Resolve with the accumulated stderr text once the child has closed. Returns `""`
+   * when the child wrote nothing. Spawn failures append a `[spawn-error] ...` marker
+   * (same convention as the pre-BG-03 dispatch code) so callers can distinguish a
+   * failed spawn from a clean non-zero exit.
+   */
+  stderr(handle: ChildHandle): Promise<string>;
+}
+//#endregion
+//#region src/runtime/task-storage.d.ts
+/**
+ * The 6-state TaskRecord status (ADR-0022 §2). `queued` is deliberately absent in v1
+ * (spawn-or-reject, no in-task queue; cap=8 rejects above the limit immediately).
+ */
+type TaskStatus = "running" | "stopping" | "succeeded" | "failed" | "canceled" | "lost";
+/** Origin of the spawn — `ptc-program` from a PTC run, `ptc-batch` from a future batch entry. */
+interface TaskSpawnSource {
+  kind: "ptc-program" | "ptc-batch";
+  /** Caller id (PTC run id for `ptc-program`; batch id for `ptc-batch`). */
+  callerId: string;
+}
+/**
+ * Session-level row tracking the lifecycle of one background child. 21 fields, exact shape from
+ * ADR-0022 §3. Optional fields are absent on records still `running` (e.g. `finishedAt` /
+ * `exitCode` / `outputRef` are written at transition time, not at spawn).
+ */
+interface TaskRecord {
+  id: ULID;
+  label: string;
+  agentName: string;
+  /** 0 = parent's direct, 1 = grandchild, etc. (ADR-0016 recursive section). */
+  depth: number;
+  status: TaskStatus;
+  /** ms epoch. */
+  createdAt: number;
+  startedAt: number;
+  finishedAt?: number;
+  durationMs?: number;
+  /** Last state transition ms epoch; used for cursor ordering of events. */
+  transitionAt: number;
+  /** `<sessionDir>/tasks/<id>/output.log` once the child has flushed any output. */
+  outputRef?: string;
+  outputBytes?: number;
+  /** ≤ 2 KB inline preview (Map+preview, ADR-0022 §3). */
+  outputPreview?: string;
+  stopReason?: string;
+  errorMessage?: string;
+  exitCode?: number;
+  spawnSource: TaskSpawnSource;
+  parentTaskId?: ULID;
+  /** `<sessionDir>/tasks/<id>.pi-*` session file (R1). */
+  sessionFile?: string;
+}
+/**
+ * Per-subscriber cursor for one TaskRecord (ADR-0022 §5). Cursor is per-subscriber (not per-task)
+ * because fork semantics differ from single-session semantics: a forked branch observes events
+ * from `max(parent, child)` cursor onwards, not from task creation.
+ */
+interface Subscription {
+  subscriberId: ULID;
+  taskId: ULID;
+  /** Monotonic ULID; advances on every event delivered. */
+  cursor: ULID;
+  status: "active" | "closed";
+  /** ms epoch. */
+  createdAt: number;
+}
+/**
+ * Append-only event in a subscription buffer. The `eventId` IS the cursor: monotonic ULID, the
+ * `loadEvents(since)` filter slices `[strictly-after since, ...]`. Schema fields beyond the
+ * cursor carry enough state for the renderer to emit `<bg-task-notification>` (ADR-0022 §7)
+ * without re-reading the TaskRecord.
+ */
+interface TaskEvent {
+  /** Cursor / event id; the loadEvents(since) filter. */
+  eventId: ULID;
+  subscriptionId: ULID;
+  taskId: ULID;
+  /**
+   * Emit key per ADR-0022 §2 + §8, e.g. `task:<id>:running`, `task:<id>:->canceled`,
+   * `task:<id>:->lost`. Storage layer treats this as an opaque string.
+   */
+  type: string;
+  status: TaskStatus;
+  /** ms epoch; matches `TaskRecord.transitionAt` at the moment of emission. */
+  transitionAtMs: number;
+  outputBytes?: number;
+  /** ≤ 2 KB inline preview (only present when `outputBytes <= 2048`). */
+  outputPreview?: string;
+}
+//#endregion
+//#region src/runtime/task-registry.d.ts
+/** Minimal structured logger seam (ADR-0022 implementation spec §12). */
+interface RegistryLogger {
+  info(msg: string): void;
+  warn(msg: string): void;
+}
+/**
+ * Thin, frozen, spawn-time projection of a TaskRecord (ADR-0022 §4). The program carries
+ * this; the registry stores the TaskRecord. The handle is *not* updated on transition.
+ */
+interface DispatchHandle {
+  taskId: ULID;
+  label: string;
+  status: "running";
+}
+/**
+ * Per-call dependencies for one registry command. `callerId` is also the subscriber id
+ * (ADR-0022 §5, "Subscriber == owner"); `clock` must be the injected time source.
+ */
+interface TransitionContext {
+  clock: () => number;
+  logger?: RegistryLogger;
+  callerId: string;
+}
+/**
+ * The three `lost` reasons ADR-0022 §8 keeps distinct in the TaskRecord's
+ * `errorMessage` field for auditability.
+ */
+type LostReason = "session_ended_while_running" | "user_killed_via_esc" | "lost_on_session_restart";
+/** All state mutations the TaskRegistry accepts (single-terminal-writer invariant, this file). */
+type TaskCommand = {
+  kind: "spawn";
+  parentTaskId?: ULID;
+  handle: DispatchHandle;
+  record: Omit<TaskRecord, "id" | "status" | "createdAt" | "transitionAt">;
+} | {
+  kind: "transition";
+  taskId: ULID;
+  to: TaskStatus;
+  reason?: string;
+  stopReason?: string;
+  errorMessage?: string;
+  exitCode?: number;
+  /**
+   * ADR-0022 §3: the child's captured-output projection written on the terminal
+   * transition. The BG-04 pump drains stdout, persists it through `OutputStorage`, and
+   * passes these three so `ptc_task_output` can find it.
+   */
+  outputRef?: string;
+  outputBytes?: number;
+  outputPreview?: string;
+} | {
+  kind: "stop";
+  taskId: ULID;
+  reason: string;
+} | {
+  kind: "reconcile-lost";
+  taskId: ULID;
+  reason: LostReason;
+} | {
+  kind: "resolve-exit";
+  taskId: ULID;
+  exitCode: number;
+  outputRef?: string;
+  outputBytes?: number;
+  outputPreview?: string;
+};
+/** Outcome of one successful command: the persisted record, emitted events, and cursor. */
+interface TransitionResult {
+  record: TaskRecord;
+  events: TaskEvent[];
+  /** The event id of the last emitted event; equal to the subscription's new cursor. */
+  cursor: ULID;
+  /**
+   * The status the record held *before* this command applied. Absent on `spawn` (there is no
+   * prior state); present on every transition/stop/resolve so a caller can report the source
+   * state without a second, racing read (ADR-0022 §8 late-arrival stop).
+   */
+  fromStatus?: TaskStatus;
+}
+/**
+ * In-process transition observer (issue #68 §1). Fired synchronously by
+ * {@link TaskRegistry.transition} **after** the new record and its event have been persisted,
+ * with the post-transition record and the emitted event. Observers are best-effort: a throwing
+ * observer is warned about and never corrupts the transition. Registration returns an
+ * idempotent unsubscribe.
+ */
+type TaskTransitionObserver = (record: TaskRecord, event: TaskEvent) => void;
+/** Read-side filter (ADR-0022 §3). `limit` defaults to 100; `orderBy` defaults to desc. */
+interface TaskQuery {
+  status?: TaskStatus[];
+  label?: string;
+  limit?: number;
+  orderBy?: "createdAt-asc" | "createdAt-desc";
+}
+/** The five-method lifecycle surface from the BG-02 brief. */
+interface TaskRegistry {
+  transition(command: TaskCommand, ctx: TransitionContext): Promise<TransitionResult>;
+  query(view: TaskQuery): Promise<TaskRecord[]>;
+  /**
+   * Load one TaskRecord by id; `null` when the id is unknown. The O(1) complement of `query`,
+   * used by the background pump to see whether a stop was requested before it writes the
+   * terminal transition (ADR-0022 §8).
+   */
+  get(taskId: ULID): Promise<TaskRecord | null>;
+  /**
+   * Subscribe to every successfully persisted state write (spawn included). Returns an
+   * idempotent unsubscribe. Observers run synchronously, in-process; see
+   * {@link TaskTransitionObserver} for the best-effort contract and single-writer ordering.
+   */
+  onTransition(observer: TaskTransitionObserver): () => void;
+  reconcileLostTasks(): Promise<TaskRecord[]>;
+}
+//#endregion
+//#region src/runtime/output-storage.d.ts
+/**
+ * The persistence seam for one task's captured output.
+ *
+ * `readOutput` returning `null` and `writeOutput` accepting any string are the whole contract;
+ * ordering, framing and truncation are the caller's job.
+ */
+interface OutputStorage {
+  /** Load the task's raw output; `null` when nothing has been written for that id. */
+  readOutput(taskId: ULID): Promise<string | null>;
+  /** Persist (insert-or-replace) the task's raw output. */
+  writeOutput(taskId: ULID, content: string): Promise<void>;
+  /**
+   * The stable path/ref the dispatcher records on `TaskRecord.outputRef`. It exists even before
+   * the first `writeOutput` (the ref is the record's address, not the file's existence).
+   */
+  outputRef(taskId: ULID): string;
+}
+//#endregion
+//#region src/runtime/dispatch.d.ts
+/**
+ * Per-run in-flight `pi.dispatch` counter (ADR-0016 §2 + ADR-0022 §9). The dispatcher's
+ * foreground gate owns the canonical counter today; this class is the small exported seam
+ * ADR-0022 §9 asks for so the background branch can hold a slot for a child's whole
+ * lifetime and release it only on the terminal transition — a background task keeps
+ * counting against `dispatchConcurrency` after `dispatch()` has already returned. The
+ * dispatcher can adopt this type without a behaviour change.
+ */
+declare class DispatchSlotCounter {
+  #private;
+  readonly limit: number;
+  constructor(limit: number);
+  /** Number of slots currently held. */
+  get active(): number;
+  /** Reserve one in-flight slot (optionally keyed by a per-task holder token); `false` means the cap is reached (hard reject, no queue). */
+  tryAcquire(holder?: string): boolean;
+  /**
+   * Release one slot; per-token idempotent (a late release for the same task is a no-op) and
+   * never negative. An anonymous release only frees an anonymous reservation.
+   */
+  release(holder?: string): void;
+}
+/**
+ * Injected dependencies for the background branch. The foreground path ignores this object
+ * entirely (it uses the module-level {@link DISPATCH_LIFECYCLE}); every field is optional so
+ * existing zero-argument call sites keep working. Tests pass an in-memory registry and a
+ * mock lifecycle so no real `pi` process is ever spawned.
+ */
+interface DispatchDeps {
+  /** Session-level TaskRegistry (ADR-0022 §3). Defaults to a lazy in-memory registry. */
+  taskRegistry?: TaskRegistry;
+  /** Child lifecycle for the background spawn. Defaults to the shared real adapter. */
+  lifecycle?: ChildProcessLifecycle;
+  /** Per-run in-flight counter shared with the dispatcher's foreground gate (ADR-0022 §9). */
+  slots?: DispatchSlotCounter;
+  /** Time source for TaskRecord stamps. Defaults to `Date.now`. */
+  clock?: () => number;
+  /** Logger for the background pump's failure path. Defaults to a `console.warn` logger. */
+  logger?: RegistryLogger;
+  /**
+   * ADR-0022 §3: where the pump persists a task's drained stdout. When present, the terminal
+   * transition records `outputRef` / `outputBytes` / `outputPreview` so `ptc_task_output`
+   * can dereference the bytes (BG-07).
+   */
+  outputStorage?: OutputStorage;
+}
+//#endregion
+//#region src/runtime/notification-pipeline.d.ts
+/** Idle-wake callback: one subscriber's pending events, delivered in cursor order. */
+type IdleWakeHandler = (subscriberId: ULID, events: TaskEvent[]) => void;
+/**
+ * The five-method pipeline surface (Ticket BG-05). The concrete class adds the
+ * dispatcher-facing `notifyIdle` wake trigger on top of this interface.
+ */
+interface NotificationPipeline {
+  /** Create (or return the existing) subscription for one (subscriberId, taskId) pair. */
+  subscribe(subscriberId: ULID, taskId: ULID, since?: ULID): Promise<Subscription>;
+  /** Read pending events strictly newer than the cursor, WITHOUT advancing the cursor. */
+  drainPending(subscriberId: ULID, taskId: ULID): Promise<TaskEvent[]>;
+  /** Advance the cursor to `untilCursor`; never moves backwards (idempotent). */
+  acknowledgeEvents(subscriberId: ULID, taskId: ULID, untilCursor: ULID): Promise<void>;
+  /** Register an idle-wake handler; handlers fire in registration order. */
+  onIdleWake(handler: IdleWakeHandler): void;
+  /** Count events strictly newer than the cursor. */
+  pendingCount(subscriberId: ULID, taskId: ULID): Promise<number>;
+}
+//#endregion
+//#region src/runtime/task-notification.d.ts
+/**
+ * One drained event joined to the TaskRecord it describes. The join is required: the event
+ * lacks `label` / `agentName` / `depth` / `durationMs` / `outputRef` (see the module
+ * note above), all of which the ADR-0022 §7 child element must carry.
+ */
+interface TaskNotificationItem {
+  event: TaskEvent;
+  record: TaskRecord;
+}
+//#endregion
+//#region src/runtime/background-runtime.d.ts
+/** Best-effort reporter for a bind failure; the index notifies the user from it. */
+type BackgroundBindReporter = (message: string) => void;
+/** One cursor to advance after a drained batch has actually been delivered. */
+interface NotificationAck {
+  subscriberId: ULID;
+  taskId: ULID;
+  cursor: ULID;
+  /**
+   * The concrete session pipeline this drain READ from, carried so the ack lands on the same
+   * session even if a rebind happens between the drain and the send (P1). Without it the ack goes
+   * through the stable proxy's *current* delegate and targets a session that never knew the
+   * subscription, leaving the original cursor unadvanced and re-delivering the batch.
+   */
+  sink: NotificationPipeline;
+}
+/**
+ * One drain: the events to render plus the cursors the caller acknowledges after a successful
+ * send. The split is what lets a failed send leave the cursor unadvanced (ADR-0022 §5/§6).
+ */
+interface NotificationDrain {
+  items: TaskNotificationItem[];
+  acks: readonly NotificationAck[];
+}
+/**
+ * The holder. `registry` / `outputStorage` / `pipeline` are stable objects safe to capture
+ * before any session exists; `bindSession` swaps the session delegate underneath them.
+ */
+interface BackgroundTaskRuntime {
+  readonly registry: TaskRegistry;
+  readonly outputStorage: OutputStorage;
+  readonly pipeline: NotificationPipeline;
+  readonly slots: DispatchSlotCounter;
+  readonly lifecycle: ChildProcessLifecycle;
+  /** Stable deps the two PTC tools hand to `runPtcProgram` (ADR-0022 §9). */
+  readonly dispatchDeps: DispatchDeps;
+  /** Session clock (`Date.now` unless injected); passed to `ptc_task_stop`. */
+  readonly clock: () => number;
+  /**
+   * (Re)bind to a session: build the session storage/registry/pipeline, swap the delegates, then
+   * reconcile. Returns the records marked `lost`. A bind failure (storage construction or the
+   * reconcile sweep) is reported via `reporter` and the logger, and leaves the previous delegate
+   * usable; it never rejects and never partially swaps.
+   */
+  bindSession(sessionDir: string | undefined, reporter?: BackgroundBindReporter): Promise<TaskRecord[]>;
+  /** Drain undelivered events for a subscriber as `{event, record}` pairs ready for the renderer. */
+  drainNotifications(subscriberId: ULID): Promise<NotificationDrain>;
+  /**
+   * Advance the subscription cursor for a drained batch. The caller invokes this ONLY after the
+   * batch's message was actually delivered (ADR-0022 §5/§6); a failed send leaves the cursor
+   * where it was so the next drain re-delivers the event.
+   */
+  acknowledgeNotifications(acks: readonly NotificationAck[]): Promise<void>;
+  /** Mark every non-terminal task lost (given reason) and release resources. */
+  shutdown(reason: LostReason): Promise<TaskRecord[]>;
+}
+//#endregion
 //#region src/mode/ptc-mode.d.ts
 /** The two surfaces this package exposes. `/ptc on` needs at least one of them active. */
 export declare const PTC_MODE_TOOL_NAMES: readonly string[];
@@ -344,6 +805,27 @@ interface PtcErrorShape {
   message: string;
   stack?: string;
 }
+/**
+ * One binding call the program made, as the dispatcher recorded it.
+ *
+ * Host-side only: this shape never crosses the wire — the existing `call` /
+ * `call-result` frames already carry every fact, and the host reconstructs the
+ * record at the seam where the facts are known (`SubCallTracker`,
+ * `src/runtime/sub-call-tracker.ts`). A snapshot reaches the renderer
+ * via `PtcToolDetails.subCalls`.
+ */
+type SubCallStatus = "running" | "ok" | "error" | "cancelled" | "rejected";
+interface SubCallRecord {
+  callId: number;
+  name: string;
+  args: unknown;
+  status: SubCallStatus;
+  startMs: number;
+  endMs?: number;
+  durationMs?: number;
+  resultSummary?: string;
+  errorMessage?: string;
+}
 //#endregion
 //#region src/tools/text.d.ts
 /** Hard cap for one rendered line; longer lines are truncated with `…`. */
@@ -389,6 +871,29 @@ interface BindingContext {
   depth: number;
   /** Maximum allowed depth; passed through to `pi.dispatch` for the depth check. */
   maxDispatchDepth: number;
+  /**
+   * ADR-0022 §5: the TaskRecord owner / subscription subscriber. The dispatcher threads the
+   * run id here so a background task's events are addressed to the spawning run.
+   */
+  callerId?: string;
+  /**
+   * ADR-0022 R1: the session dir a background child persists into. Threaded from the
+   * dispatcher (see `RunPtcProgramOptions.sessionDir`); when no dir is available the spawn
+   * keeps the foreground no-session shape.
+   */
+  sessionDir?: string;
+  /**
+   * ADR-0022 §3/reopen R-m12: this process's own background task id, when this run is inside a
+   * background child. Threaded from the dispatcher (see `RunPtcProgramOptions.parentTaskId`)
+   * and forwarded to `pi.dispatch` so a nested spawn records `TaskRecord.parentTaskId`.
+   */
+  parentTaskId?: ULID;
+  /**
+   * ADR-0022 §9: per-run dispatch dependencies. The dispatcher supplies the run's shared
+   * `DispatchSlotCounter` here; a host may also pass session-level deps (registry / lifecycle /
+   * output storage) so the binding's `dispatch()` call shares them.
+   */
+  dispatchDeps?: DispatchDeps;
 }
 interface Binding {
   readonly name: string;
@@ -519,8 +1024,28 @@ interface RunPtcProgramOptions {
    * to 0.
    */
   depth?: number;
+  /**
+   * ADR-0022 §3/reopen R-m12: this process's own background task id, when the run is inside a
+   * child spawned by `pi.dispatch({ background: true })`. The entrypoint reads it from
+   * `PI_PTC_TASK_ID` and threads it to the binding context so a nested spawn records
+   * `TaskRecord.parentTaskId`. Absent for a top-level session.
+   */
+  parentTaskId?: ULID;
   /** Identifier carried to the worker; generated when omitted. */
   runId?: string;
+  /**
+   * ADR-0022 R1: the session dir background children persist into, when the host has one.
+   * Threaded to the binding context so `pi.dispatch({ background: true })` can stamp the R1
+   * session flags; absent means the background spawn keeps the foreground no-session shape.
+   */
+  sessionDir?: string;
+  /**
+   * ADR-0022 §3/§9: session-level dispatch dependencies (TaskRegistry / OutputStorage /
+   * lifecycle / clock / logger). The dispatcher merges its per-run `DispatchSlotCounter`
+   * into this bag before handing it to the `pi.dispatch` binding, so background tasks count
+   * against this run's `dispatchConcurrency` for their whole lifetime.
+   */
+  dispatchDeps?: DispatchDeps;
   /**
    * Optional worker pool (ADR-0017). Absent = spawn a fresh worker and terminate it
    * at run end (the original cold-start path). Present = the dispatcher acquires a
@@ -529,6 +1054,18 @@ interface RunPtcProgramOptions {
    * `kind: workerExit`.
    */
   pool?: WorkerPool;
+  /**
+   * Called every time a sub-call starts or ends, so the caller can push a live partial result
+   * and have the tree visible while the run is in flight (ADR-0021 §4). Never called after the
+   * run settles — `finish` owns the terminal snapshot. Absent means "no live updates wanted"
+   * (direct library use, tests that only assert the terminal outcome).
+   *
+   * The argument is a **thunk**, not the snapshot itself: a wide `Promise.all` produces an
+   * event per call, and `snapshot()` copies every record. Building it eagerly would make N
+   * sequential calls cost O(N²) copies for pushes that the caller's throttle mostly drops.
+   * Call it only when a push is actually due.
+   */
+  onSubCallChange?: (snapshot: () => readonly SubCallRecord[]) => void;
 }
 /**
  * One image hoisted out of a successful binding result (DSH parity — see ADR-0014,
@@ -568,6 +1105,15 @@ interface PtcRunOutcome {
   images?: PtcImage[];
   /** Failure details; absent on success. */
   error?: PtcErrorShape;
+  /**
+   * One record per binding call the program made (ADR-0021).
+   *
+   * Present only when the dispatcher tracked sub-calls for the surface in question (always,
+   * post-ADR-0021 — the dispatcher wires `SubCallTracker` for every run). Order is host-side
+   * dispatch order; the renderer reads it as a point-in-time snapshot. Absent for runs that settled
+   * before the tracker was constructed (the pre-`Promise` abort and pool-acquire-failed paths).
+   */
+  subCalls?: readonly SubCallRecord[];
 }
 /**
  * Run one PTC program in a fresh worker and resolve with its outcome.
@@ -600,7 +1146,15 @@ export declare class TurnPools {
 }
 //#endregion
 //#region src/index.d.ts
-export default function ptcSubagents(pi: ExtensionAPI): void;
+/**
+ * Optional seams for the extension factory. Production calls `ptcSubagents(pi)`; tests may inject
+ * a pre-built background runtime (with a mock child lifecycle) so no real `pi` process is spawned.
+ */
+export interface PtcSubagentsOptions {
+  /** Use this session-scoped background runtime instead of constructing one. */
+  backgroundRuntime?: BackgroundTaskRuntime;
+}
+export default function ptcSubagents(pi: ExtensionAPI, options?: PtcSubagentsOptions): void;
 //#endregion
 export type { Binding, BindingContext, BindingTable, CreateBuiltinBindingsOptions, DefaultModeConfig, ModeBlockReason, ModeEntryDecision, ModeEntryInput, ModeHideStrategy, PersistedModeState, PtcConfig, PtcErrorKind, PtcErrorShape, PtcImage, PtcJsonValue, PtcModeState, PtcRunOutcome, PtcSurface, RunPtcProgramOptions, TurnPoolsOptions, WorkerPoolOptions, WorkerPoolStats, WorkerPoolWorkerOptions };
 //# sourceMappingURL=index.d.ts.map