@agent-compose/sdk 0.5.0 → 0.5.2

package/dist/pause/__tests__/agent-loop-checkpoint.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pause/__tests__/checkpoint.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pause/__tests__/errors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pause/__tests__/manager.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pause/__tests__/pause-core.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pause/__tests__/state-dir.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pause/__tests__/wrappers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pause/checkpoint.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `ctx.checkpoint(name, fn)` — disk-backed memoise across pause-resume.
+ *
+ * First call: `fn()` runs, the result is atomically written to
+ * `/tmp/wf/state/checkpoints/<name>.json`. On any subsequent invocation
+ * of the same step body (e.g. after pause-resume re-enters the
+ * subprocess), the file exists in the restored sandbox; `fn` is NOT
+ * called, the recorded value is returned.
+ *
+ * Use for: large context loads, expensive deterministic transforms,
+ * idempotent-but-slow computations that you want to skip on resume.
+ *
+ * Do NOT use for: side effects with external systems (DB writes, HTTP
+ * POSTs, sending email). Those need `ctx.invokeChild(...)` — Temporal's
+ * exactly-once guarantee covers cross-process side effects; disk-backed
+ * memoisation is in-sandbox only and would silently retry on a sandbox
+ * recreation that lost the checkpoint file.
+ *
+ * See ADR-0006 §"`ctx.checkpoint(name, fn)` — disk-backed memoisation".
+ */
+/** Read-or-run-and-write helper. `name` is validated by the state-dir
+ *  layer (rejects path-escape attempts); `fn` is awaited if it returns
+ *  a Promise so sync and async callers compose identically. */
+export declare function checkpoint<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
+/** Bind user checkpoint names to a runner-owned namespace. The user's
+ *  `name` is still validated independently so a scope prefix cannot turn
+ *  an empty or path-escaping name into a valid filename. */
+export declare function scopedCheckpoint(scope: string): typeof checkpoint;

package/dist/pause/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * User-facing pause errors (ADR-0006 / ADR-0011).
+ *
+ * These are thrown into USER step/agent code when a pause cannot return a
+ * value — the caller can catch them. They are distinct from `PauseSignal`
+ * (the internal control-flow signal in `pause-core.ts` that unwinds the
+ * stack to `serveStep`): `PauseSignal` never reaches user code, these do.
+ *
+ * Each carries a stable `code` so the activity boundary and the dashboard
+ * can classify the failure without string-matching the message — the same
+ * pattern as `StepExecutionError` (`step-invocation/types.ts`).
+ *
+ * `target: ESNext` (sdk/tsconfig.json) makes `extends Error` + `instanceof`
+ * work without a manual prototype fix; `this.name = new.target.name` gives
+ * each subclass its own class name on the instance.
+ */
+/** Stable, machine-readable discriminator for each pause error. */
+export type PauseErrorCode = "pause_expired" | "pause_schema" | "pause_request";
+/** Base for every user-facing pause error. Not thrown directly. */
+export declare abstract class PauseError extends Error {
+    abstract readonly code: PauseErrorCode;
+    constructor(message: string);
+}
+/**
+ * The pause's TTL elapsed before it was resolved, and `onExpiry` was
+ * `{ mode: "throw" }` (the default). When `onExpiry` is
+ * `{ mode: "resolve", value }`, `ctx.pause` returns `value` instead of
+ * throwing this.
+ */
+export declare class PauseExpiredError extends PauseError {
+    readonly code = "pause_expired";
+    constructor(message?: string);
+}
+/**
+ * The resume payload failed the caller's `schema`. `issues` carries the
+ * validation detail for an in-sandbox `catch`; note only `message` survives
+ * the serveStep wire boundary, so do not rely on `issues` outside the
+ * throwing process.
+ */
+export declare class PauseSchemaError extends PauseError {
+    readonly code = "pause_schema";
+    readonly issues: unknown;
+    constructor(message: string, issues?: unknown);
+}
+/**
+ * The pause request itself is invalid before it can be emitted to the engine:
+ * empty reason, non-positive ttl, invalid kind, or a non-JSON payload.
+ */
+export declare class PauseRequestError extends PauseError {
+    readonly code = "pause_request";
+    constructor(message?: string);
+}

package/dist/pause/manager.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Local pause/resume manager.
+ *
+ * This module owns the SDK-local state machine that makes a re-entered
+ * runner subprocess pick up agent work correctly. It deliberately does not
+ * know about Temporal, Postgres, HTTP resume routes, or dashboard feeds.
+ * Those layers own durable wait/audit state; this layer owns only the
+ * `/tmp/wf/state` files captured by sandbox snapshots.
+ */
+import type { AgentStatus } from "../types/protocol.js";
+import type { ModelExecutionContract } from "../types/runtime.js";
+export interface AgentLoopProgressState {
+    iteration: number;
+    completedIterations: number;
+    lastSessionId: string;
+    lastStatus: AgentStatus | null;
+    lastResponseText: string;
+    lastResponseValidationError: string;
+    iterationsWithoutStatus: number;
+    blockerStreak: {
+        key: string;
+        count: number;
+    } | null;
+    /** PR 7 steer-pause intent — see RunningAgentLoopStateSchema. Optional so the
+     *  loop can omit it until it wires steer (the schema defaults it to null). */
+    pendingSteerPause?: {
+        reason: string;
+        correlationKey: string | null;
+        at: number;
+    } | null;
+}
+export interface SettledAgentLoopResult<TResponse = unknown> {
+    sessionId: string;
+    lastStatus: AgentStatus | null;
+    iterations: number;
+    response?: TResponse;
+}
+export type AgentLoopRestore<TResponse = unknown> = {
+    kind: "fresh";
+} | {
+    kind: "invalid";
+    error: string;
+} | {
+    kind: "running";
+    state: AgentLoopProgressState;
+} | {
+    kind: "settled";
+    result: SettledAgentLoopResult<TResponse>;
+};
+/**
+ * Coordinates the agent-loop files in `/tmp/wf/state`.
+ *
+ * Raw filesystem safety lives in `state-dir.ts`; runtime blob shape lives in
+ * each runtime adapter. `PauseManager` is the seam that binds those two to
+ * the agent-loop state machine.
+ */
+export declare class PauseManager {
+    private readonly agentId;
+    constructor(agentId: string);
+    restoreAgentLoop<TResponse = unknown>(runtime: ModelExecutionContract): Promise<AgentLoopRestore<TResponse>>;
+    saveRunningAgentLoop(state: AgentLoopProgressState, runtime: ModelExecutionContract): Promise<void>;
+    saveSettledAgentLoop<TResponse = unknown>(result: SettledAgentLoopResult<TResponse>): Promise<void>;
+}

package/dist/pause/pause-core.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `pause-core` — the engine behind `ctx.pause` (ADR-0006 / ADR-0011 PR 6).
+ *
+ * How a pause works (and why this shape):
+ *
+ *   First reach (fresh):  read `pauses/<pauseId>.json` → absent/unresolved →
+ *     write the placeholder record and `throw new PauseSignal(...)`. The
+ *     exception unwinds the step body to `serveStep`, which emits the
+ *     `__AC_STEP_PAUSE__` sentinel and exits 0. The engine snapshots, inserts
+ *     a `run_pauses` row keyed by `pauseId`, and waits durably.
+ *
+ *   Re-entry (resolved): the engine has written the resolution onto the same
+ *     file. The runner re-runs the step body from the top in a fresh
+ *     subprocess; the SAME `ctx.pause` call recomputes the SAME `pauseId`,
+ *     reads the file, and returns the resume payload (or applies `onExpiry`).
+ *
+ * The whole thing hinges on `pauseId` being recomputed identically across the
+ * exit/re-enter boundary, with NO surviving in-process state. So `pauseId` is
+ * a **deterministic UUIDv5** of a stable coordinate — never random. UUIDv5
+ * (not a free-form string) because `run_pauses.id` is a `uuid` PRIMARY KEY.
+ *
+ * `PauseSignal` is internal control flow, NOT a user-facing error — `serveStep`
+ * and the agent loop must let it propagate (the user-facing `Pause*Error` classes in
+ * `errors.ts` are the ones user code catches). It deliberately does not extend
+ * `Error`, so a stray `catch (e) { if (e instanceof Error) … }` cannot quietly
+ * absorb it; callers add explicit `instanceof PauseSignal` re-throw guards.
+ *
+ * Runs in the runner subprocess (may use `node:crypto`), never in the Temporal
+ * workflow VM.
+ */
+import type { z } from "zod";
+import { type StepPauseRequest } from "../step-invocation/types.js";
+import type { StepObservability } from "../workflow-steps/observability.js";
+/** Public `ctx.pause` argument shape (ADR-0006 §"SDK surface"). `schema` and
+ *  `onExpiry` are SDK-local — consumed here, never sent on the wire. The wire
+ *  `kind` is NOT a public field: a raw `ctx.pause` is always `kind: "custom"`;
+ *  `decision`/`sleep`/`event` come only from the wrappers. */
+export interface PauseRequest<T = unknown> {
+    reason: string;
+    payload?: Record<string, unknown>;
+    schema?: z.ZodType<T>;
+    ttlMs?: number;
+    onExpiry?: {
+        mode: "throw";
+    } | {
+        mode: "resolve";
+        value: T;
+    };
+    correlationKey?: string;
+    snapshot?: boolean;
+}
+/** The coordinate that makes `pauseId` deterministic + re-entry-stable. */
+export interface PauseCoordinate {
+    runId: string;
+    stepIndex: number;
+    /** Present when the pause fires inside an agent loop (PR 7 steer-pause).
+     *  Pins the id to the loop boundary (agentId + iteration) so it stays stable
+     *  across the loop's iteration-skipping on resume — a bare per-step ordinal
+     *  desyncs because completed iterations don't re-run, landing the ordinal at
+     *  a different value. Step-body pauses leave it absent (the `:bare` form). */
+    agentScope?: {
+        agentId: string;
+        iteration: number;
+    };
+}
+/** Realm-global brand so `isPauseSignal` recognises a PauseSignal thrown by a
+ *  DIFFERENT SDK instance. A bundled workflow inlines its own SDK copy (its
+ *  `agent()` steer-pause throws the bundle's `PauseSignal`), but the runner
+ *  catches with its own class — a plain `instanceof` is false across that
+ *  boundary, so the pause was mis-classified as a step failure and no
+ *  `run_pauses` row was written. `ctx.pause` avoided this only because its
+ *  signal is runner-thrown. `Symbol.for` is shared across the realm, so the
+ *  brand survives the instance split. */
+declare const PAUSE_SIGNAL_BRAND: unique symbol;
+/**
+ * Internal control-flow signal thrown by `corePause` on a fresh pause.
+ * Caught by `serveStep` (emits the sentinel + exits) and re-thrown past every
+ * intermediate catch. NOT an `Error` and NOT user-facing.
+ */
+export declare class PauseSignal {
+    readonly pauseId: string;
+    readonly pauseRequest: StepPauseRequest;
+    readonly observability?: StepObservability | undefined;
+    readonly [PAUSE_SIGNAL_BRAND]: true;
+    constructor(pauseId: string, pauseRequest: StepPauseRequest, observability?: StepObservability | undefined);
+}
+/** Cross-instance-safe `PauseSignal` check. Use this instead of
+ *  `err instanceof PauseSignal` anywhere a signal may have been thrown by a
+ *  different SDK instance (the runner catching a bundled workflow's signal). */
+export declare function isPauseSignal(err: unknown): err is PauseSignal;
+/** Wipe the ordinal counters. Called by the runner at first-boot alongside
+ *  `resetStateDir()`; a fresh module load already starts empty, so this is
+ *  belt-and-braces for any in-process reuse. */
+export declare function resetPauseOrdinals(): void;
+/**
+ * The body of `ctx.pause`. On a fresh pause it throws `PauseSignal`; on
+ * re-entry it returns the resume payload (or applies `onExpiry` / throws
+ * `PauseSchemaError`). See the module header.
+ */
+export declare function corePause<T = unknown>(req: PauseRequest<T>, coord: PauseCoordinate, kind?: StepPauseRequest["kind"]): Promise<T>;
+export {};

package/dist/pause/state-dir.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Pause state directory — durable per-agent / per-checkpoint / per-pause
+ * blobs the sandbox snapshot carries across pause-resume.
+ *
+ * Layout under `/tmp/wf/state/`:
+ *
+ *   agent-<agentInstanceId>.json     ← agent loop state (iteration, messages, processor cursor)
+ *   runtime-<agentInstanceId>.json   ← runtime-private blob (opaque to the loop)
+ *   checkpoints/<name>.json          ← user `ctx.checkpoint(name, fn)` memoised values
+ *   pauses/<pauseId>.json            ← pause records (request + resume payload once available)
+ *
+ * Atomic writes (write-tmp → fsync → rename) so a mid-write `sandbox.snapshot()`
+ * cannot capture partial state. Most read helpers return `null` on missing-file
+ * rather than throwing — callers branch on presence to distinguish "first
+ * run" from "post-resume restore". User checkpoints use an explicit
+ * found/value result because `null` is a valid memoised value.
+ *
+ * The state-dir layout is treated as wire protocol between the SDK
+ * runner (writer) and the SDK on the next subprocess invocation (reader).
+ * Changing a filename or shape is a breaking change to pause resumption
+ * for any in-flight paused workflow. See ADR-0006.
+ */
+/** Root of the pause state-dir. Defaults to `/tmp/wf/state` — the
+ *  canonical location inside the sandbox. Tests and non-`/tmp`-writable
+ *  environments can override via `AGENT_COMPOSE_STATE_DIR`.
+ *
+ *  Read at CALL TIME, not module load. An earlier draft cached it on
+ *  first import, but that turned out to be test-ordering-fragile: once
+ *  any test imported state-dir (directly or transitively via
+ *  agent-loop) the path got locked to whatever env was set at that
+ *  instant, and a later test setting `AGENT_COMPOSE_STATE_DIR` would
+ *  silently write to the cached path instead. Reading the env each
+ *  call costs nothing measurable next to the fsync. */
+export declare function getStateDir(): string;
+export declare function assertSafeCheckpointName(name: string): void;
+export type CheckpointRead<T> = {
+    found: true;
+    value: T;
+} | {
+    found: false;
+};
+export declare function readAgentState<T = unknown>(agentInstanceId: string): Promise<T | null>;
+export declare function writeAgentState(agentInstanceId: string, state: unknown): Promise<void>;
+export declare function readRuntimeCheckpoint<T = unknown>(agentInstanceId: string): Promise<T | null>;
+export declare function writeRuntimeCheckpoint(agentInstanceId: string, blob: unknown): Promise<void>;
+export declare function readCheckpoint<T = unknown>(name: string): Promise<CheckpointRead<T>>;
+export declare function writeCheckpoint(name: string, value: unknown): Promise<void>;
+/** The `pauses/<pauseId>.json` file — the only durable handoff between the
+ *  paused subprocess and the resumed one.
+ *
+ *  Written twice in two execution contexts:
+ *  - At pause time the runner writes the placeholder `{ pauseId, request }`
+ *    (no `resolved`). The snapshot captures it.
+ *  - At resume time the engine activity writes the resolution — usually
+ *    merged on top of the placeholder, but snapshotless pauses may only have
+ *    `{ resolved: true, resumePayload, expired }` in a fresh sandbox. Those
+ *    three resolution fields are always present together so the byte shape
+ *    distinguishes a real resume (`expired:false`) from a TTL expiry
+ *    (`expired:true`) from an unresolved placeholder (`resolved` absent).
+ *
+ *  `corePause` reads it on re-entry: `resolved !== true` ⇒ still my own
+ *  placeholder, pause again; `expired` ⇒ apply `onExpiry`; else return
+ *  `resumePayload`. */
+export interface PauseRecord {
+    pauseId: string;
+    request: unknown;
+    /** Set true once the engine has written the resolution (resume or expiry). */
+    resolved?: boolean;
+    /** Value to return from `ctx.pause` on a real resume; null for expiry. */
+    resumePayload?: unknown;
+    /** True when the resolution is a TTL expiry, not a caller-driven resume. */
+    expired?: boolean;
+}
+export declare function readPauseRecord(pauseId: string): Promise<PauseRecord | null>;
+export declare function writePauseRecord(record: PauseRecord): Promise<void>;
+/** Wipe the entire state directory. Used by the runner at first-boot
+ *  (no pauseId in env) so a freshly-dispatched run never inherits state
+ *  from a prior dispatch that shared the sandbox snapshot template.
+ *  No-op when the directory doesn't exist. */
+export declare function resetStateDir(): Promise<void>;

package/dist/pause/wrappers.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The three opinionated pause wrappers (ADR-0006 §"SDK surface"), each a thin
+ * closure over `ctx.pause`:
+ *
+ *   - `requestDecision` — pause for a typed human/agent decision (schema required).
+ *   - `sleep`           — a lightweight timed pause; resolves on its own TTL,
+ *                         skips the snapshot, returns void.
+ *   - `waitForEvent`    — pause until an event resumes by correlation key.
+ *
+ * Built from a `PauseFn` so the wrapper logic lives in one place and the step
+ * runner just spreads them onto the context next to `pause`.
+ */
+import type { z } from "zod";
+import type { StepPauseRequest } from "../step-invocation/types.js";
+import type { PauseRequest } from "./pause-core.js";
+/** The public `ctx.pause` callable (always `kind: "custom"`). */
+export type PauseFn = <T = unknown>(req: PauseRequest<T>) => Promise<T>;
+/** Internal: pause with an explicit wire `kind`. The wrappers stamp
+ *  `decision`/`sleep`/`event` through this; the public `ctx.pause` is always
+ *  `custom` and never exposes it. */
+export type KindedPauseFn = <T = unknown>(req: PauseRequest<T>, kind: StepPauseRequest["kind"]) => Promise<T>;
+export interface RequestDecisionRequest<T> {
+    reason: string;
+    payload?: Record<string, unknown>;
+    /** Required — a decision is always validated against a shape. */
+    schema: z.ZodType<T>;
+    ttlMs?: number;
+}
+export interface WaitForEventRequest<T> {
+    reason: string;
+    /** Required — the by-key resume route targets this. */
+    correlationKey: string;
+    schema?: z.ZodType<T>;
+    ttlMs?: number;
+}
+export interface PauseWrappers {
+    requestDecision<T>(req: RequestDecisionRequest<T>): Promise<T>;
+    sleep(durationMs: number): Promise<void>;
+    waitForEvent<T = unknown>(req: WaitForEventRequest<T>): Promise<T>;
+}
+export declare function buildPauseWrappers(pause: KindedPauseFn): PauseWrappers;

package/dist/request-context/request-context.d.ts

@@ -38,6 +38,7 @@
  * `invokeChild` propagation: only reserved keys flow to the child; freeform
  * is per-run by design (cross-run state must be explicit via `input`).
  */
+import { z } from "zod";
 /** Reserved key namespace prefix — anything starting with this is platform-owned. */
 export declare const AC_RESERVED_PREFIX = "ac__";
 export declare const AC_TEAM_ID: "ac__teamId";
@@ -77,6 +78,17 @@ export interface RequestContextWire {
     };
     user: Record<string, unknown>;
 }
+export declare const RequestContextWireSchema: z.ZodObject<{
+    reserved: z.ZodObject<{
+        teamId: z.ZodString;
+        runId: z.ZodString;
+        workflowId: z.ZodString;
+        factoryId: z.ZodNullable<z.ZodString>;
+        apiKeyScopes: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+        parentRunId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    user: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
 /** Thrown when a caller tries to `set` or `delete` a reserved key downstream. */
 export declare class ReservedKeyError extends Error {
     readonly key: string;

package/dist/runtimes/claude.d.ts

@@ -26,13 +26,19 @@ export declare class ClaudeRunner implements ModelExecutionContract {
     private readonly options;
     private readonly config;
     supportsToolCallProcessor: boolean;
+    readonly kind = "claude";
     constructor(_sandbox: SandboxProvider, options?: RuntimeOptions, config?: ClaudeRuntimeConfig);
+    get model(): string;
     gateToolCall(call: ToolCall, ctx: ProcessorContext): Promise<ToolCallGateResult>;
     sendMessage(opts: {
         prompt: string;
         sessionId?: string;
         iteration?: number;
         signal?: AbortSignal;
+        inboxStream?: AsyncIterable<{
+            text: string;
+            senderName?: string | null;
+        }>;
     }): AsyncGenerator<AgentMessage>;
 }
 export declare function createClaudeRuntime(config?: ClaudeRuntimeConfig): import("../index.js").AgentRuntime<SandboxProvider>;

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

@@ -10,6 +10,8 @@ export interface OpenAIDesktopRunnerOptions extends RuntimeOptions {
 }
 export declare class OpenAIDesktopRunner implements ModelExecutionContract {
     private sandbox;
+    readonly kind = "openai-desktop";
+    readonly model = "computer-use-preview";
     private openai;
     private label;
     constructor(sandbox: DesktopSandboxProvider, opts: OpenAIDesktopRunnerOptions);