@agent-compose/sdk 0.8.3 → 0.8.5

package/dist/runtimes/_cli-agent.d.ts

@@ -60,6 +60,29 @@ export declare function runnerBusySentinelFragment(busyPath: string, tasksPath:
  *  `date +%s%3N` in the same exec, so host clock skew is irrelevant) is
  *  stale: three missed writes. */
 export declare const RUNNER_HEARTBEAT_STALE_MS: number;
+/** The sh fragment the heartbeat subshell runs each beat to rewrite the
+ *  pulse file: `<guest epoch ms>,<cpu jiffies>,<written bytes>,<procs>`
+ *  for every process in the runner's own session (the setsid tree — the
+ *  CLI, its foreground tool, their children). Comma-separated so the
+ *  probe can carry it as ONE whitespace-delimited field. Exported for
+ *  tests. */
+export declare function toolPulseFragment(pulsePath: string): string;
+/** One tool-run pulse sample, parsed off the probe's trailing field. */
+export interface TurnToolPulse {
+    /** Guest epoch ms when the sample was written. */
+    atMs: number;
+    /** Aggregate utime+stime jiffies across the runner's session. */
+    cpuJiffies: number;
+    /** Aggregate written bytes (wchar) across the runner's session. */
+    ioBytes: number;
+    /** Live processes in the session. */
+    procs: number;
+}
+/** Parse the pulse token (`at,cpu,io,procs`). Null on anything malformed —
+ *  evidence-absent, never an error. Exported for tests. */
+export declare function parseToolPulseToken(token: string): TurnToolPulse | null;
+/** Bound on the pulse token read (4 numeric fields + commas). */
+export declare const TOOL_PULSE_TOKEN_MAX_CHARS = 96;
 /** Watchdog cadence while a tail stream is attached. Each tick is one fresh
  *  short exec; a healthy stream makes every tick a no-op. */
 export declare const TAIL_WATCHDOG_INTERVAL_MS = 15000;
@@ -75,6 +98,33 @@ export declare const TAIL_ABANDON_AFTER_STREAM_DEATHS = 3;
  *  (envd HTTP, ~65ms RTT), consumed from the byte offset. Latency-tuned:
  *  this is the degraded path, correctness never depends on it being fast. */
 export declare const DURABLE_POLL_INTERVAL_MS = 1000;
+/** Consecutive provider-attested "sandbox gone" probe failures ⇒ dead. */
+export declare const PROBE_DEATH_GONE_STREAK = 3;
+/** Not-found evidence must also persist this long (guards a momentary
+ *  control-plane 404 blip from killing a live turn). */
+export declare const PROBE_DEATH_GONE_WINDOW_MS = 15000;
+/** Consecutive GENERIC probe-transport failures (timeouts, connection
+ *  faults) ⇒ dead — only together with the window below. */
+export declare const PROBE_DEATH_FAIL_STREAK = 20;
+/** …and the failure run must span at least this long with zero durable
+ *  evidence of any kind. */
+export declare const PROBE_DEATH_FAIL_WINDOW_MS = 120000;
+/** Provider evidence that the SANDBOX itself is gone — E2B's
+ *  SandboxNotFoundError / NotFoundError classes (matched by name so no
+ *  provider import rides in the runtime layer), or their messages after any
+ *  wrapping ("Paused sandbox X not found" was run 3's exact shape). */
+export declare function isSandboxGoneError(err: unknown): boolean;
+/** One probe-failure run's bookkeeping (reset to zeros on ANY evidence). */
+export interface ProbeDeathState {
+    /** Consecutive probe execs that THREW (no verdict at all). */
+    failStreak: number;
+    /** Consecutive throws that were provider "sandbox gone" evidence. */
+    goneStreak: number;
+    /** Wall-clock start of the current failure run (0 = no run). */
+    firstFailAtMs: number;
+}
+/** The death-door decision, pure for tests. Null = keep polling. */
+export declare function probeDeathVerdict(s: ProbeDeathState, nowMs: number): "dead-gone" | "dead-silent" | null;
 /** The claude CLI's stderr complaint when `--resume <id>` names a thread
  *  that does not exist on this machine (the 2026-08-18 split-brain
  *  forensic). When a nonzero exit's stderr carries it, the transport
@@ -99,6 +149,10 @@ export interface TurnProbeReading {
      *  sample yet, or a garbled token — evidence-absent, never an error.
      *  Telemetry-only: no liveness verdict may ever read it. */
     perf?: GuestPerfSample;
+    /** Latest tool-run pulse (the `.pulse` token field, 2026-08-29), when the
+     *  guest wrote one AND it parsed clean. Telemetry-only, same rule as
+     *  `perf`: no liveness verdict may ever read it. */
+    pulse?: TurnToolPulse;
 }
 /** The probe exec: one line, six fields, always exit 0 — faults surface as
  *  parse failures, not exec failures. Reads the guest's own clock in the
@@ -112,6 +166,7 @@ export declare function turnLivenessProbeCommand(paths: {
     perfPath: string;
     pid: number;
     sentinel: string;
+    pulsePath?: string;
 }): string;
 /** Parse the probe's line. Null = unusable output (a wedged or faulted exec)
  *  — the caller treats that as "probe-failed", never as a verdict. The
@@ -149,6 +204,18 @@ export declare function streamInputFeederFragment(paths: {
     deliveredPath: string;
     outPath: string;
 }): string;
+/** The instructional envelope around a user message delivered INTO a
+ *  running turn. Claude Code's own interactive harness wraps queued
+ *  mid-turn input with an explicit "address this as you continue"
+ *  instruction; a bare `--input-format stream-json` line carries no such
+ *  framing, so an injected message reads like any other transcript text
+ *  and the model tends to continue its work narration without
+ *  acknowledging it. Every mid-turn inject producer (the runner's
+ *  `injectUserMessage` and the workflow lane's `deliverInjectedMessage`
+ *  activity) MUST wrap through here — the wrapper rides only the wire to
+ *  the model; the stored conversation row keeps the user's raw text.
+ *  The text is pinned by tests: change it deliberately or not at all. */
+export declare function wrapMidTurnUserMessage(text: string): string;
 /** The one delivery-ack exec `injectUserMessage` runs: append the message
  *  line to the durable inbox, then wait for the feeder's delivered counter
  *  to cover it. Exit 0 = delivered into the CLI's stdin pre-result; 4 = the
@@ -455,6 +522,16 @@ export interface CliAgentSpec {
         /** Serialise one mid-turn user message into ONE stdin line. No
          *  trailing newline. */
         messageLine(text: string): string;
+        /** Serialise ONE in-band interrupt control line (claude: a stream-json
+         *  `control_request` with subtype "interrupt") — the ESC equivalent.
+         *  The CLI's control layer handles these immediately, MID-STEP
+         *  included: the running tool call aborts (its tool_result records the
+         *  harness's own rejection text), the run ends with an
+         *  `error_during_execution` result within ~100ms, and the session file
+         *  stays `--resume`-able with the whole turn context. Verified live
+         *  against claude 2.1.236. Absent → the runtime has no in-band
+         *  interrupt; callers fall back to kill semantics. */
+        interruptLine?(requestId: string): string;
     };
 }
 export declare class CliAgentRunner implements ModelExecutionContract {
@@ -515,6 +592,22 @@ export declare class CliAgentRunner implements ModelExecutionContract {
      *  answers "unsupported" and the caller leaves the message owed. `chain`
      *  serializes appends so each delivery targets a deterministic line count. */
     private turnInject;
+    /** The CURRENT turn's detached-runner wrapper pid (the setsid group
+     *  leader echoed by the launch / recovered from the durable pidfile) —
+     *  durable-transport turns only. Null between turns and on transports
+     *  without a detached guest. See the contract doc (types/runtime.ts). */
+    private turnPid;
+    /** Advisory guest-pid identity for the live turn's runner tree — see the
+     *  contract doc (types/runtime.ts). Never a liveness verdict. */
+    currentRunnerPid(): number | null;
+    /** Safe-to-persist durable byte offset — end of the last line whose
+     *  messages have ALL been yielded (boot-time turn adoption; contract in
+     *  types/runtime.ts). One line behind the parse cursor by design. */
+    private turnConsumedOffset;
+    /** End offset of the line currently being yielded from — promoted to
+     *  `turnConsumedOffset` when the NEXT line is pulled (or at stream end). */
+    private turnPendingLineEnd;
+    currentTurnDurableOffset(): number | null;
     /** Deliver one user message INTO the live turn — see the contract doc
      *  (types/runtime.ts). Appends a stream-input line to the turn's durable
      *  inbox and waits for the in-guest feeder's delivered-counter ack; only
@@ -524,6 +617,31 @@ export declare class CliAgentRunner implements ModelExecutionContract {
      *  the appended line may still be read when the current step finishes,
      *  but it was NOT seen yet. Never throws. */
     injectUserMessage(text: string): Promise<"delivered" | "pending" | "closed" | "unsupported">;
+    /** Request an in-band step interrupt of the LIVE turn — the ESC
+     *  equivalent; see the contract doc (types/runtime.ts). Appends the
+     *  spec's interrupt control line to the turn's durable inbox; the guest
+     *  feeder forwards it into the CLI's stdin, whose control layer handles
+     *  it immediately — MID-STEP included, unlike queued user messages (the
+     *  inject "pending" wall applies to turn-loop consumption, not the
+     *  control layer). Only "delivered" means the control line reached the
+     *  CLI's stdin; callers escalate anything else to kill semantics. Never
+     *  throws. */
+    interruptTurn(): Promise<"delivered" | "pending" | "closed" | "unsupported">;
+    /** The one durable append+ack path both mid-turn producers share
+     *  (`injectUserMessage`'s enveloped message line, `interruptTurn`'s raw
+     *  control line). Serialized on the inject chain so every append targets
+     *  a deterministic inbox line count. */
+    private appendTurnStreamLine;
+    /** The most recent probe reading's tool-run pulse (2026-08-29), plus the
+     *  guest clock it was read against — telemetry only, refreshed by each
+     *  `probeTurnLiveness` call. Null between turns / before any probe. */
+    private lastTurnPulse;
+    /** Peek the newest tool-run pulse the durable probe carried — the
+     *  executor's evidence ticker reads it AFTER its liveness check to fan
+     *  the tool-progress fact to clients. Never probes on its own. */
+    peekTurnPulse(): (TurnToolPulse & {
+        guestNowMs: number;
+    }) | null;
     /** Durable three-valued liveness for the current turn — see the contract
      *  doc (types/runtime.ts). Never throws; never blocks past the probe's
      *  explicit exec timeout. */

package/dist/runtimes/claude-code.d.ts

@@ -33,7 +33,7 @@
  *     sessions this is the gateway-minted session virtual key pointed at the
  *     token-metering gateway's Anthropic passthrough (ADR-0039).
  */
-import type { AgentMessageTaskNotification } from "../index.js";
+import type { AgentMessage, AgentMessageCompaction, AgentMessageTaskNotification, AgentMessageTaskProgress } from "../index.js";
 import { type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
 /** Pinned Claude Code ACP adapter (Zed's npm shim — `claude` has no native
  *  ACP mode). Pinned EXACT, not a range: the adapter's README warns of
@@ -46,12 +46,42 @@ export declare const CLAUDE_CODE_ACP_ADAPTER = "@zed-industries/claude-code-acp@
  *  is skipped, absent fields stay absent, everything is clamped. Exported
  *  for tests. */
 export declare function parseTaskNotifications(text: string, timestamp: string): AgentMessageTaskNotification[];
+/** One user-role TEXT blob from the stream, mapped with sidechain awareness.
+ *  Task-notification blocks parse into structure wherever they appear (their
+ *  arrival side is resume-dependent — see the transport notes above). What
+ *  remains is then split by attribution: TOP-LEVEL text (no parent id) stays
+ *  unmapped exactly as before — prompt echoes and system reminders are not
+ *  agent output. SIDECHAIN text (parent id present) is a message landing in
+ *  a child subagent's thread — a delivered SendMessage steer — and forwards
+ *  as `subagent_user_message`, except harness plumbing (`<system-reminder>`
+ *  wrappers the CLI injects into child threads), which no renderer should
+ *  see. Exported for tests. */
+export declare function sidechainAwareUserText(text: string, parentToolUseId: string | undefined, timestamp: string): AgentMessage[];
 /** One `system`/`task_notification` stream-json event mapped onto the same
  *  structured message the XML parse produces, or null when the event names
  *  no task id. Pure and tolerant over untrusted harness JSON: absent fields
  *  stay absent, everything is clamped; `output_file` (internal plumbing) is
  *  deliberately not forwarded. Exported for tests. */
 export declare function parseSystemTaskNotification(p: Record<string, unknown>, timestamp: string): AgentMessageTaskNotification | null;
+/** One `system`/`task_progress` event mapped onto the structured progress
+ *  message, or null only when it names no task. Workflow tasks carry the
+ *  cumulative `workflow_progress` entries; a plain background Agent-task
+ *  heartbeat (no workflow entries — verified live on 2.1.241, ~10s cadence
+ *  while the task runs) forwards with `workflow: []` so the platform can
+ *  DECLARE the running task as session background work (the delegation-
+ *  survives-the-human contract: parks, user interrupts, and supersedes all
+ *  read the declared-children registry). Completion evidence still rides
+ *  `task_notification`. Pure and tolerant over untrusted harness JSON:
+ *  malformed entries are skipped, everything is clamped (phases keep the
+ *  FIRST 32 — they are seeded up front; agents keep the LAST 128 — late
+ *  spawns matter more than a long-settled prefix). Exported for tests. */
+export declare function parseSystemTaskProgress(p: Record<string, unknown>, timestamp: string): AgentMessageTaskProgress | null;
+/** One `system` event of the compaction family mapped onto the structured
+ *  lifecycle message, or null when the event is not compaction-shaped (a
+ *  plain `status` event with neither the compacting status nor a
+ *  compact_result stays unmapped). Pure and tolerant over untrusted harness
+ *  JSON. Exported for tests. */
+export declare function parseSystemCompaction(p: Record<string, unknown>, timestamp: string): AgentMessageCompaction | null;
 /** Claude Code's real reasoning knob is its own `--effort <level>` flag
  *  (low|medium|high|xhigh|max — verified against `claude -p --help`). The
  *  CliReasoningEffort union IS the CLI's vocabulary, so the level rides the

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

@@ -3,11 +3,35 @@
  *
  * Works against DesktopSandboxProvider — no E2B SDK dependency here.
  * The action→screenshot loop runs until the model emits text, then yields it.
+ *
+ * COORDINATE SPACES (incident note). Every screenshot is downscaled to the
+ * model's DISPLAY geometry (1024×720) before it is sent, so the model emits
+ * coordinates in the SCALED screenshot's space — never the real desktop's.
+ * An earlier revision executed those coordinates against the real desktop
+ * using hardcoded real-geometry constants, so on any sandbox whose actual
+ * geometry differed, every click landed in the wrong place. The provider has
+ * no geometry call, so the real geometry is read from each screenshot buffer
+ * itself (sharp metadata), and the resulting per-capture `CaptureScale` maps
+ * the model's coordinates back onto the exact frame it saw. The old constants
+ * survive ONLY as a fallback for the metadata-missing case.
  */
 import type { DesktopSandboxProvider, AgentMessage, ModelExecutionContract, RuntimeOptions } from "../index.js";
 export interface OpenAIDesktopRunnerOptions extends RuntimeOptions {
     openaiKey: string;
 }
+/** One model-emitted desktop action. Coordinates arrive in DISPLAY (model)
+ *  space and are rescaled through the CURRENT capture's `CaptureScale`
+ *  before dispatch. Exported so tests can type their fixtures. */
+export interface ComputerAction {
+    type: string;
+    coordinate?: [number, number];
+    startCoordinate?: [number, number];
+    endCoordinate?: [number, number];
+    text?: string;
+    key?: string;
+    direction?: string;
+    ticks?: number;
+}
 export declare class OpenAIDesktopRunner implements ModelExecutionContract {
     private sandbox;
     readonly kind = "openai-desktop";
@@ -20,5 +44,31 @@ export declare class OpenAIDesktopRunner implements ModelExecutionContract {
         sessionId?: string;
     }): AsyncGenerator<AgentMessage>;
 }
+/** Real-desktop pixels per model-DISPLAY pixel, derived from ONE capture.
+ *  Coordinates the model emits against that capture are multiplied by these
+ *  factors (and rounded) before touching the provider. */
+export interface CaptureScale {
+    scaleX: number;
+    scaleY: number;
+}
+/** One captured frame: the model-facing image plus the scale that maps the
+ *  model's coordinates back onto this frame's real desktop. */
+export interface ScaledCapture {
+    /** Base64 PNG resized to DISPLAY_WIDTH×DISPLAY_HEIGHT (fit "fill"). */
+    b64: string;
+    scale: CaptureScale;
+}
+/** Derive a capture's scale from its real pixel dimensions. The constants
+ *  are a FALLBACK only — used when sharp cannot read the frame's metadata;
+ *  a real dimension always wins. */
+export declare function scaleFromDimensions(width: number | undefined, height: number | undefined): CaptureScale;
+/** Capture one frame: read the REAL geometry from the raw screenshot's own
+ *  metadata, downscale to the model's DISPLAY geometry, and return both the
+ *  image and the scale that maps model coordinates back onto this frame. */
+export declare function captureScaledScreenshot(sandbox: DesktopSandboxProvider): Promise<ScaledCapture>;
+/** Dispatch one model action against the provider, mapping every coordinate
+ *  through the CURRENT capture's scale. Non-coordinate payloads — scroll
+ *  deltas (ticks), typed text, key chords — pass through untouched. */
+export declare function executeAction(sandbox: DesktopSandboxProvider, action: ComputerAction, scale: CaptureScale): Promise<void>;
 declare const _default: import("../index.js").AgentRuntime<DesktopSandboxProvider>;
 export default _default;