@agent-compose/sdk 0.8.4 → 0.8.5

package/src/sandbox/registry.ts

@@ -6,7 +6,7 @@
  * at creation time.
  */
 
-import { SandboxNotFoundError, RateLimitError } from "e2b";
+import { SandboxNotFoundError, RateLimitError, NotFoundError } from "e2b";
 import pRetry from "p-retry";
 import type { FailedAttemptError } from "p-retry";
 import type { SandboxProvider } from "../types/sandbox.js";
@@ -45,6 +45,24 @@ function isTransientSandboxError(error: unknown): boolean {
     .test(message);
 }
 
+/** 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 function isSandboxSourceNotFoundError(error: unknown): boolean {
+  if (error instanceof NotFoundError) return true;
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  return /(?:template|snapshot)[^\n]{0,80}not[\s_-]?found|not[\s_-]?found[^\n]{0,80}(?:template|snapshot)/i
+    .test(message);
+}
+
 /** The ONE place the sandbox retry policy lives. Provisioning, reconnecting, and
  *  snapshotting all race with the sandbox being paused/reclaimed; this runs the call
  *  through p-retry's generic backoff, retrying ONLY the transient race (and failing

package/src/sandbox/sizes.ts

@@ -148,15 +148,21 @@ export 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 function e2bBaseTemplate(size: SandboxSize): string {
   return `agent-compose-base-${size}`;
 }
 
-/** 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 function e2bAgentEnvTemplate(size: SandboxSize): string {
   return `agent-env-${size}`;

package/src/sandbox.ts

@@ -65,6 +65,7 @@ export {
   reconnectSandbox,
   deleteSandboxSnapshot,
   snapshotResolves,
+  isSandboxSourceNotFoundError,
   getSandboxQuotas,
   listOwnedSandboxes,
   killSandboxById,

package/src/types/api-conversations.ts

@@ -430,6 +430,49 @@ export interface BackgroundWorkHeld {
   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;
+}
+
 // ── Session branch proposals (ADR-0053) ─────────────────────────────────────
 // Every cloud session works on its own factory-drive branch; the whole branch
 // is the unit of review, like a PR. Wire shapes mirror
@@ -511,11 +554,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
@@ -793,14 +834,6 @@ export interface SessionRebaseReport {
   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 {
@@ -1004,3 +1037,22 @@ 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/src/types/api-factory.ts

@@ -107,9 +107,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
@@ -132,6 +138,17 @@ 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;
+}
+
 // ── Factory-file search (wire shape mirrors routes/factory-files.ts) ────────
 
 /** Public "anyone with the link" state — the additive `public` field on file
@@ -381,6 +398,27 @@ 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. */
@@ -389,6 +427,26 @@ 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 {
@@ -515,6 +573,23 @@ 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;
@@ -524,3 +599,48 @@ 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/src/types/conversation-stream.ts

@@ -130,6 +130,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)
@@ -185,6 +194,19 @@ export interface ConversationSessionStatusEvent {
   at: number;
 }
 
+/** 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
@@ -195,7 +217,8 @@ export type ConversationStreamEvent =
   | ConversationReplayContinueEvent
   | ConversationTurnStateEvent
   | ConversationPresenceEvent
-  | ConversationSessionStatusEvent;
+  | ConversationSessionStatusEvent
+  | ConversationToolPulseEvent;
 
 /**
  * Fold one parsed SSE frame into a `ConversationStreamEvent`.

package/src/types/protocol.ts

@@ -147,6 +147,61 @@ 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
@@ -160,6 +215,60 @@ export interface AgentMessageHarnessNotice extends AgentMessageBase {
   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
@@ -173,7 +282,10 @@ export type AgentMessage =
   | AgentMessageUsageDelta
   | AgentMessagePlan
   | AgentMessageTaskNotification
-  | AgentMessageHarnessNotice;
+  | 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;