@agent-compose/sdk 0.5.9 → 0.7.0

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

@@ -19,7 +19,7 @@ import type { SandboxProvider } from "../types/sandbox.js";
  * that credentials are network-injected (never in the env). The live
  * "Connectors & access" section is appended per-run by `buildAgentContextDoc`.
  */
-export declare const AGENT_COMPOSE_MANUAL = "# Working inside an Agent Compose sandbox\n\nYou are an agent running in a per-run sandbox on the Agent Compose platform.\nUse the **`agentc` CLI** and the **`@agent-compose/sdk`** for everything below \u2014\ndo NOT hand-roll raw HTTP/curl calls against the platform API. The CLI is on\nyour PATH and already authenticated from the environment\n(`AGENT_COMPOSE_URL` / `AGENT_COMPOSE_API_KEY` / `AGENT_COMPOSE_FACTORY` are\ninjected for this run), so commands just work \u2014 no login, no keys to manage.\n\nThe `/ac:*` skills are installed as Claude Code slash commands (`/ac:invoke`,\n`/ac:events`, `/ac:logs`, `/ac:register`, \u2026) \u2014 reach for them too.\n\n## Files \u2014 your outputs persist by default\n\nYour working directory defaults to **`$AGENT_COMPOSE_RUN_DIR`** \u2014 a per-run\ndirectory on the shared factory drive\n(`$AGENT_COMPOSE_FACTORY_DIR/<workflow>/<version>/<run-id>/`) the platform\ncreates and attributes to this run. **Files you write here persist by\ndefault** \u2014 they show up in the dashboard's Files tab and the run's Artifacts\ncard, with no API calls to save them. The dir already exists and is writable.\n\nNeed throwaway scratch \u2014 heavy build output, package caches, temp files?\n`cd /tmp` (or any path outside `/factory`): anything off the factory drive is\nephemeral and discarded when the sandbox ends. In short: **stay in your working\ndir to keep something, `cd` out to throw it away.**\n\nThe whole shared drive is POSIX-mounted at `/factory`; the dashboard-visible\nroot is `$AGENT_COMPOSE_FACTORY_DIR` (`/factory/files`). Earlier versions and\nruns live in sibling dirs under\n`$AGENT_COMPOSE_FACTORY_DIR/$AGENT_COMPOSE_WORKFLOW/` \u2014 read them for prior\ncontext. Other workflows' dirs are present but not your concern.\n\n## Events \u2014 the factory timeline\n\nRecord something on the run/factory timeline (the dashboard renders these)\nwith the CLI \u2014 your run id is `$RUN_ID`:\n\n    agentc events send \"$RUN_ID\" <name> --summary \"<one line>\" [--body '<json>']\n\nNames like `note.created` / `brief.posted` surface in the Workbench;\n`agentc events list` reads them back. `/ac:events` is the skill equivalent.\n\n## Runs\n\n    agentc list                          # registered workflows  (/ac:list)\n    agentc logs \"$RUN_ID\"                # a run's logs           (/ac:logs)\n    agentc invoke <workflow> -i '<json>' # dispatch a workflow    (/ac:invoke)\n\n## Writing workflow / agent code \u2014 the SDK\n\n`@agent-compose/sdk` is installed in `/workspace` \u2014 import it from any script\nyou write there:\n\n    import { defineWorkflow, agent, AgentComposeClient } from \"@agent-compose/sdk\";\n\nUse `/ac:generate-workflow` / `/ac:generate-agent` to scaffold, then\n`agentc register <file.ts>` (or `/ac:register`).\n\n## Pausing to ask the human \u2014 `agentc pause`\n\nWhen you can't or shouldn't proceed without a human, run `agentc pause`, then\n**END YOUR TURN**:\n\n    agentc pause --reason \"Notion returned 401 \u2014 connect Notion to continue\" \\\n                 --option retry --option skip\n\n`agentc pause` does NOT block and does NOT print the answer. It records your\nquestion and returns immediately. The moment you end your turn, the run pauses\n(your sandbox is snapshotted and compute stops while the human decides) and the\nhuman's answer is delivered to you as your **next message** \u2014 you pick up\nexactly where you left off, with the answer in hand. So: ask, end your turn,\nand wait. Do NOT keep working, do NOT call more tools, and do NOT mark the task\ncomplete after pausing.\n\nReach for it the moment you hit \u2014 or foresee \u2014 any of these:\n- **A wall only a human can clear:** a 401/403, a missing credential, an\n  unconnected provider, a host the network refuses. Do NOT retry blindly or try\n  to work around it \u2014 pause and say what needs enabling.\n- **A durable or outward-facing action that needs sign-off:** registering a\n  workflow, deploying, sending email/messages, deleting or overwriting shared\n  data, spending money. Prepare everything, then pause for approval BEFORE you\n  commit it.\n- **A judgment call only the human can settle:** an under-specified request,\n  several valid paths, a conflict with existing state, missing input only they have.\n\nYou compose the `--reason` (the ask) yourself; pass `--option` choices when\nthere are clear ones, omit them for a free-form answer. Each agent pauses\nindependently \u2014 pausing doesn't stop the others.\n\n## Credentials\n\nConnector credentials (Google, GitHub, \u2026) are NEVER in your environment.\nThey're injected at the network layer when you call an allowed host \u2014 make the\nrequest **without** an Authorization header and the platform adds it. Don't try\nto read or exfiltrate tokens; they aren't here. The \"Connectors & access\"\nsection below (when present) lists exactly which providers this run can reach.\n\n## Tools in this environment\n\n- `agentc` \u2014 Agent Compose CLI (your primary interface; authed from env)\n- `@agent-compose/sdk` \u2014 installed in /workspace for writing workflows\n- `/ac:*` Claude Code skills \u2014 slash commands for the above\n- `archil` (factory drive), `rtk`, `bun`\n- A world-writable `/workspace` working directory";
+export declare const AGENT_COMPOSE_MANUAL = "# Working inside an Agent Compose sandbox\n\nYou are an agent running in a per-run sandbox on the Agent Compose platform.\nUse the **`agentc` CLI** and the **`@agent-compose/sdk`** for everything below \u2014\ndo NOT hand-roll raw HTTP/curl calls against the platform API. The CLI is on\nyour PATH and already authenticated from the environment\n(`AGENT_COMPOSE_URL` / `AGENT_COMPOSE_API_KEY` / `AGENT_COMPOSE_FACTORY` are\ninjected for this run), so commands just work \u2014 no login, no keys to manage.\n\nThe `/ac:*` skills are installed as Claude Code slash commands (`/ac:invoke`,\n`/ac:events`, `/ac:logs`, `/ac:register`, \u2026) \u2014 reach for them too.\n\n## Files \u2014 your outputs persist by default\n\nYour working directory defaults to **`$AGENT_COMPOSE_RUN_DIR`** \u2014 a per-run\ndirectory on the shared factory drive\n(`$AGENT_COMPOSE_FACTORY_DIR/<workflow>/<version>/<run-id>/`) the platform\ncreates and attributes to this run. **Files you write here persist by\ndefault** \u2014 they show up in the dashboard's Files tab and the run's Artifacts\ncard, with no API calls to save them. The dir already exists and is writable.\n\nNeed throwaway scratch \u2014 heavy build output, package caches, temp files?\n`cd /tmp` (or any path outside `/factory`): anything off the factory drive is\nephemeral and discarded when the sandbox ends. In short: **stay in your working\ndir to keep something, `cd` out to throw it away.**\n\nThe whole shared drive is POSIX-mounted at `/factory`; the dashboard-visible\nroot is `$AGENT_COMPOSE_FACTORY_DIR` (`/factory/files`). Earlier versions and\nruns live in sibling dirs under\n`$AGENT_COMPOSE_FACTORY_DIR/$AGENT_COMPOSE_WORKFLOW/` \u2014 read them for prior\ncontext. Other workflows' dirs are present but not your concern.\n\n## Events \u2014 the factory timeline\n\nRecord something on the run/factory timeline (the dashboard renders these)\nwith the CLI \u2014 your run id is `$RUN_ID`:\n\n    agentc events send \"$RUN_ID\" <name> --summary \"<one line>\" [--body '<json>']\n\nNames like `note.created` / `brief.posted` surface in the Workbench;\n`agentc events list` reads them back. `/ac:events` is the skill equivalent.\n\n## Runs\n\n    agentc list                          # registered workflows  (/ac:list)\n    agentc logs \"$RUN_ID\"                # a run's logs           (/ac:logs)\n    agentc invoke <workflow> -i '<json>' # dispatch a workflow    (/ac:invoke)\n\n## Writing workflow / agent code \u2014 the SDK\n\n`@agent-compose/sdk` is installed in `/workspace`. **To author a workflow,\nALWAYS run `/ac:generate-workflow`** (and `/ac:generate-agent` for an agent\nstep) instead of writing source from memory \u2014 the skill scaffolds the correct,\ncurrent shape. Then `agentc register <file.ts>` (or `/ac:register`).\n\nThe skill writes **step-form** (a builder of discrete, durable `.step()`s).\nNever write the legacy run-form (`defineWorkflow({ run(ctx, sandbox) { \u2026 } })`):\nit is one opaque step, so any failure or resume re-runs the whole body \u2014 and\n**pause does not work in run-form**.\n\n## Pausing to ask the human\n\nTo ask a human and get an answer back, use the **`AskUserQuestion`** tool if\nyou have it; otherwise run **`agentc pause`**:\n\n    agentc pause --reason \"Notion returned 401 \u2014 connect Notion to continue\" \\\n                 --option retry --option skip\n\n**Both BLOCK and hand you the answer inline.** While you wait, the run is\nsuspended \u2014 your sandbox is frozen and compute stops, so a pause is free while\nthe human decides. When they answer, the call RETURNS with their decision: the\n`AskUserQuestion` tool result, or `agentc pause`'s output\n(`\u25B6 Resumed. The human answered: \u2026`), carries it.\n\n**Then USE that answer to finish your work \u2014 do NOT end your turn.** This is NOT\nfire-and-forget, and the answer does NOT arrive in a later message: it comes\nback right where you called it, on the SAME turn. The shape is: ask \u2192 the call\nblocks \u2192 it returns the human's answer \u2192 you act on it and produce your result.\nNever end your turn before the call returns, never guess an answer, and never\nproceed without one.\n\nReach for it the moment you hit \u2014 or foresee \u2014 any of these:\n- **A wall only a human can clear:** a 401/403, a missing credential, an\n  unconnected provider, a host the network refuses. Do NOT retry blindly or try\n  to work around it \u2014 pause and say what needs enabling.\n- **A durable or outward-facing action that needs sign-off:** registering a\n  workflow, deploying, sending email/messages, deleting or overwriting shared\n  data, spending money. Prepare everything, then pause for approval BEFORE you\n  commit it.\n- **A judgment call only the human can settle:** an under-specified request,\n  several valid paths, a conflict with existing state, missing input only they have.\n\nYou compose the `--reason` (the ask) yourself; pass `--option` choices when\nthere are clear ones, omit them for a free-form answer. Each agent pauses\nindependently \u2014 pausing doesn't stop the others.\n\n## Credentials\n\nConnector credentials (Google, GitHub, \u2026) are NEVER in your environment.\nThey're injected at the network layer when you call an allowed host \u2014 make the\nrequest **without** an Authorization header and the platform adds it. Don't try\nto read or exfiltrate tokens; they aren't here. The \"Connectors & access\"\nsection below (when present) lists exactly which providers this run can reach.\n\n## Tools in this environment\n\n- `agentc` \u2014 Agent Compose CLI (your primary interface; authed from env)\n- `@agent-compose/sdk` \u2014 installed in /workspace for writing workflows\n- `/ac:*` Claude Code skills \u2014 slash commands for the above\n- `archil` (factory drive), `rtk`, `bun`\n- A world-writable `/workspace` working directory";
 /**
  * One connector this run can reach, as the agent should see it. Strictly
  * NON-SECRET — hosts, methods, paths, identity only. The access token is

package/dist/agent/agent-loop.d.ts

@@ -9,7 +9,6 @@ import type { Processor } from "../processors/processor.js";
 import { type BoundaryPauseFn } from "../pause/pause-core.js";
 import { RequestContext } from "../request-context/request-context.js";
 import { type SteerPayload } from "./steer-control.js";
-import { type LocalPauseRequest } from "./local-pause-request.js";
 export declare const DEFAULT_CLAUDE_MODEL = "claude-fable-5";
 export declare function parseAgentStatus(text: string): AgentStatus | null;
 export interface AgentLoopResult<TResponse = unknown> {
@@ -148,13 +147,6 @@ export interface AgentLoopOpts<TResponse = unknown> {
      *  The boundary consumes it once per check, and only when no steer is
      *  already staged. */
     consumeSteerPending?: () => SteerPayload | null;
-    /** Take-once read of a local `agentc pause` request this agent dropped in the
-     *  state dir during its turn (the CLI writes it; see local-pause-request.ts).
-     *  Returns the request (reason + offered options) or null. The loop turns it
-     *  into a staged self-pause the next boundary takes — the same snapshot-release
-     *  path as `needs_input`, but triggered by an explicit `agentc pause` call so
-     *  it is honored regardless of `mode`. */
-    consumeLocalPauseRequest?: () => LocalPauseRequest | null;
     /** PR 7: `auto` (autonomous, default) or `hitl` (can be steer-paused). The
      *  boundary is inert unless `hitl`. */
     mode?: "auto" | "hitl";

package/dist/agent/pause-client.d.ts

@@ -0,0 +1,50 @@
+/**
+ * In-sandbox pause client (ADR-0028). The single way an agent pauses its OWN
+ * run: `agentc pause` and the gate-pause processor both call
+ * `requestPauseAndAwait`, which drives the server pause API and blocks until a
+ * human resolves it.
+ *
+ * Create-then-poll, NOT a held connection:
+ *   1. POST /pauses creates the pending row. The server wakes the step
+ *      activity, which freezes the live VM in place (E2B native suspend). The
+ *      poll loop below is part of that frozen process — between polls it costs
+ *      ZERO compute while the run is parked.
+ *   2. GET /pauses/:id long-polls (each request a bounded ~5s server-side
+ *      LISTEN race) until the row is terminal, then returns the human's answer.
+ *
+ * There is no marker file and no exception threaded through workflow code — the
+ * pause is a server operation, so nothing a `try/catch` can swallow.
+ */
+export interface PauseDecision {
+    status: "resolved" | "expired" | "cancelled";
+    /** The human's answer (present on `resolved`). Caller-defined shape; the
+     *  dashboard sends `{ decision: string }`. Null on expiry/cancel. */
+    decision: unknown;
+}
+export interface RequestPauseOptions {
+    /** `AGENT_COMPOSE_URL` — the server base URL injected into the sandbox. */
+    baseUrl: string;
+    /** `AGENT_COMPOSE_RUN_TOKEN` — the run credential the agent already carries. */
+    token: string;
+    /** `RUN_ID`. */
+    runId: string;
+    /** Human-readable reason shown on the pause feed / approval UI. */
+    reason: string;
+    /** Optional pause TTL; the workflow auto-expires the pause after this. */
+    ttlMs?: number;
+    /** Optional decision options the human picks from (e.g. approve / deny). */
+    options?: Array<{
+        id: string;
+        label: string;
+    }>;
+    /** The action under review (e.g. the tool call), surfaced to the human. */
+    action?: Record<string, unknown>;
+    /** Optional second-key resume route. */
+    correlationKey?: string;
+    /** Abort the wait (the agent loop's signal). */
+    signal?: AbortSignal;
+}
+/** Inject a custom fetch (tests). Defaults to global fetch. */
+type FetchFn = typeof fetch;
+export declare function requestPauseAndAwait(opts: RequestPauseOptions, fetchImpl?: FetchFn): Promise<PauseDecision>;
+export {};

package/dist/index.d.ts

@@ -23,8 +23,8 @@ export type { WorkflowPlan, WorkflowStepPlan } from "./types/workflow-plan.js";
 export type { BaseExecutionContext, InvokeChild } from "./types/execution-context.js";
 export { RequestContext, ReservedKeyError, NonSerialisableValueError, AC_RESERVED_PREFIX, AC_TEAM_ID, AC_RUN_ID, AC_WORKFLOW_ID, AC_FACTORY_ID, AC_API_KEY_SCOPES, AC_PARENT_RUN_ID, AC_ABORT_SIGNAL, } from "./request-context/index.js";
 export type { RequestContextReserved, RequestContextWire, } from "./request-context/index.js";
-export { Verdict, runProcessorChain, denyTools, humanApproval, requireScope, redactPattern, } from "./processors/index.js";
-export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, } from "./processors/index.js";
+export { Verdict, runProcessorChain, denyTools, humanApproval, requireScope, redactPattern, createGatePauseProcessor, createAskHumanProcessor, ASK_USER_QUESTION_TOOL, } from "./processors/index.js";
+export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, GatePausePolicy, GatePauseApproval, GatePauseConnection, } from "./processors/index.js";
 export type { AgentMessage, AgentMessageInit, AgentMessageText, AgentMessageThinking, AgentMessageToolUse, AgentMessageToolResult, AgentMessageDone, AgentMessageError, AgentMessageUsage, AgentStatus, } from "./types/protocol.js";
 export type { SandboxProvider, DesktopSandboxProvider, } from "./types/sandbox.js";
 export { AgentComposeClient } from "./client.js";
@@ -47,6 +47,15 @@ export { default as codexRuntime } from "./runtimes/codex.js";
 export { createAmpRuntime } from "./runtimes/amp.js";
 export type { AmpRuntimeConfig } from "./runtimes/amp.js";
 export { default as ampRuntime } from "./runtimes/amp.js";
+export { createOpencodeRuntime, opencodeSpec } from "./runtimes/opencode.js";
+export type { OpencodeRuntimeConfig } from "./runtimes/opencode.js";
+export { default as opencodeRuntime } from "./runtimes/opencode.js";
+export { createCursorRuntime, cursorSpec } from "./runtimes/cursor.js";
+export type { CursorRuntimeConfig } from "./runtimes/cursor.js";
+export { default as cursorRuntime } from "./runtimes/cursor.js";
+export { createDroidRuntime, droidSpec } from "./runtimes/droid.js";
+export type { DroidRuntimeConfig } from "./runtimes/droid.js";
+export { default as droidRuntime } from "./runtimes/droid.js";
 export { bashTool, codingTools, editTool, readTool, writeTool } from "./tools/index.js";
 export type { CodingTool } from "./tools/index.js";
 export type { RunEvent } from "./types/events.js";
@@ -59,14 +68,14 @@ export type { WorkflowResult, RunWorkflowOptions, EngineSubsystem } from "./work
 export { buildInvokeChild } from "./workflows/invoke-child.js";
 export { defineStep, isWorkflow, runWorkflowSteps, runWorkflowSingleStep, StepValidationError, WorkflowInputValidationError, WorkflowOutputValidationError, } from "./workflow-steps/index.js";
 export type { Step, StepContext, StepRunResult, Workflow, DefineStepOpts, StepWorkflowDefinition, WorkflowBuilder, RunWorkflowStepsOpts, RunWorkflowStepsResult, RunWorkflowSingleStepOpts, RunWorkflowSingleStepResult, StepObservability, SubStepEvent, } from "./workflow-steps/index.js";
-export { invokeStep, serveStep, parseStepResult, buildStepEnvs, StepExecutionError, STEP_RESULT_PREFIX, STEP_PAUSE_PREFIX, STEP_ENV, RUNNER_BUNDLE_PATH, RUNNER_COMMAND, stepInputPath, requestContextPath, } from "./step-invocation/index.js";
+export { invokeStep, launchStep, reconnectStep, serveStep, parseStepResult, buildStepEnvs, StepExecutionError, STEP_RESULT_PREFIX, STEP_PAUSE_PREFIX, STEP_ENV, RUNNER_BUNDLE_PATH, RUNNER_COMMAND, stepInputPath, requestContextPath, } from "./step-invocation/index.js";
 export { PauseError, PauseExpiredError, PauseSchemaError, PauseRequestError, } from "./pause/errors.js";
 export type { PauseErrorCode } from "./pause/errors.js";
 export type { PauseRequest } from "./pause/pause-core.js";
 export type { WaitForEventRequest } from "./pause/wrappers.js";
-export { writeLocalPauseRequest, consumeLocalPauseRequest } from "./agent/local-pause-request.js";
-export type { LocalPauseRequest, PauseOption } from "./agent/local-pause-request.js";
-export type { StepRequest, StepResult, StepInvocationError, StepPauseRequest, StepHandler, StepHandlerResult, ServeStepRequest, } from "./step-invocation/index.js";
+export { requestPauseAndAwait } from "./agent/pause-client.js";
+export type { PauseDecision, RequestPauseOptions } from "./agent/pause-client.js";
+export type { StepRequest, StepResult, StepInvocationError, StepPauseRequest, StepHandler, StepHandlerResult, ServeStepRequest, RunningStep, InvokeStepOptions, } from "./step-invocation/index.js";
 export { agentLoop, parseAgentStatus, DEFAULT_CLAUDE_MODEL } from "./agent/agent-loop.js";
 export type { AgentLifecycleEvent, AgentLoopOpts, AgentLoopResult } from "./agent/agent-loop.js";
 export { agent } from "./agent/run-agent.js";