@agent-compose/sdk 0.5.9 → 0.7.0

package/dist/processors/ask-human.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Ask-human processor (ADR-0028).
+ *
+ * Makes "ask a human" a FIRST-CLASS agent affordance: when the agent calls the
+ * built-in `AskUserQuestion` tool, this short-circuits it into a SERVER pause
+ * (`requestPauseAndAwait`) — the run freezes (compute stops), the question +
+ * options land on the human's pause feed, and the human's answer comes back as
+ * the tool result. No `agentc pause` CLI for the model to remember, and no
+ * dependency on prompt discipline: the moment the agent asks, the run pauses.
+ *
+ * Loud by construction — the danger this fixes is a pause that SILENTLY doesn't
+ * happen (a stale in-sandbox CLI, a non-E2B substrate, an auth error) letting
+ * the agent proceed as if it had an answer:
+ *   - pause cannot be created (server reject) → `Verdict.abort` ENDS the agent
+ *     loop with a WorkflowError. The run fails loud; it never guesses an answer.
+ *   - pause expires / is cancelled → the tool result says NO answer came and to
+ *     not assume one.
+ *
+ * Lives in the shared `gateToolCall` chain, so one implementation covers every
+ * runtime (the Claude Agent SDK `PreToolUse` hook and the ACP permission path).
+ * No run credential in the env (local / non-sandbox) → no-op: `AskUserQuestion`
+ * passes through untouched so a dev invocation isn't hard-failed.
+ */
+import type { Processor } from "./processor.js";
+import type { GatePauseConnection } from "./gate-pause.js";
+/** The Claude built-in tool an agent uses to ask the user a question. */
+export declare const ASK_USER_QUESTION_TOOL = "AskUserQuestion";
+export declare function createAskHumanProcessor(opts?: {
+    connection?: GatePauseConnection;
+}): Processor;

package/dist/processors/ask-human.test.d.ts

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

package/dist/processors/gate-pause.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Gate-pause processor (ADR-0028).
+ *
+ * A pre-tool gate that, when its `policy` flags a tool call as needing human
+ * approval, pauses the run as a SERVER operation (`requestPauseAndAwait`) and
+ * blocks until a human answers — then allows or denies the tool.
+ *
+ * It pauses through the server pause API (`requestPauseAndAwait`), so the pause
+ * is a server operation no `try/catch` can swallow. It does NOT use today's
+ * `ctx.pause`, which still throws `PauseSignal` — exactly the swallowable path
+ * ADR-0028 supersedes for agents. (Routing `ctx.pause` itself through this same
+ * server pause is the natural unification — ADR-0028 open question — at which
+ * point "the pause API" and "ctx.pause" become one thing.) Because it lives in
+ * the shared `gateToolCall` chain, one implementation covers every runtime — the
+ * Claude Agent SDK `PreToolUse` hook and the ACP `session/request_permission`
+ * path both route through it.
+ *
+ * Opt-in: the workflow/agent supplies the `policy` (which may be a heuristic or
+ * an async classifier agent). The connection defaults to the run credential in
+ * the sandbox env; absent it (local / non-sandbox), the gate is a no-op and
+ * tool calls pass through untouched.
+ */
+import type { Processor, ProcessorContext, ToolCall } from "./processor.js";
+export interface GatePauseApproval {
+    /** Human-readable question shown on the approval UI. */
+    reason: string;
+    /** Decision options the human picks from. Defaults to Approve / Deny. */
+    options?: Array<{
+        id: string;
+        label: string;
+    }>;
+}
+/** Decide whether a tool call needs human approval. Return `false` to let it
+ *  through untouched, or an approval request to pause the run until a human
+ *  answers. May be async (e.g. a small classifier agent). */
+export type GatePausePolicy = (call: ToolCall, ctx: ProcessorContext) => (false | GatePauseApproval) | Promise<false | GatePauseApproval>;
+export interface GatePauseConnection {
+    baseUrl: string;
+    token: string;
+    runId: string;
+}
+export declare function createGatePauseProcessor(opts: {
+    policy: GatePausePolicy;
+    /** Override the server connection (defaults to the sandbox run-credential env). */
+    connection?: GatePauseConnection;
+}): Processor;

package/dist/processors/gate-pause.test.d.ts

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

package/dist/processors/index.d.ts

@@ -2,3 +2,6 @@ export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, } from ".
 export { Verdict } from "./processor.js";
 export { runProcessorChain } from "./runner.js";
 export { denyTools, humanApproval, requireScope, redactPattern, } from "./builtins.js";
+export { createGatePauseProcessor } from "./gate-pause.js";
+export type { GatePausePolicy, GatePauseApproval, GatePauseConnection } from "./gate-pause.js";
+export { createAskHumanProcessor, ASK_USER_QUESTION_TOOL } from "./ask-human.js";

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

@@ -34,6 +34,15 @@ export declare function shellQuote(value: string): string;
  *  route to JSONL exactly like a handshake error. Overridable via the env for
  *  ops tuning; defaults sane. */
 export declare const ACP_HANDSHAKE_TIMEOUT_MS: number;
+/** Idle deadline for a PROMPT TURN (distinct from the handshake gate above). A
+ *  turn is killed only if it goes fully SILENT for this long — the deadline is
+ *  re-armed on every streamed message, so a long, *streaming* turn never trips
+ *  it. This must be generous: a reasoning model (GLM, gpt-5-codex) can think for
+ *  tens of seconds between tool calls with no wire activity, which is NOT a hang.
+ *  The 10s handshake timeout was far too tight here and killed live GLM turns
+ *  mid-report. Only a genuinely wedged CLI (the Gemini-style hang) should trip
+ *  this. Overridable via the env for ops tuning. */
+export declare const ACP_TURN_IDLE_TIMEOUT_MS: number;
 /** Readiness gate for the LIVE ACP attempt. The duplex-stdin transport in
  *  `spawnAcpProcess` is now real (`commands.spawnDuplex` on the local provider),
  *  so the agent's `initialize` request bytes are delivered and the handshake can

package/dist/runtimes/cursor.d.ts

@@ -0,0 +1,9 @@
+import { type CliAgentSpec } from "./_cli-agent.js";
+export declare const cursorSpec: CliAgentSpec;
+export interface CursorRuntimeConfig {
+    /** Cursor model id; ACP mode ignores it (account default) — applies to the `-p` fallback. */
+    model?: string;
+}
+export declare function createCursorRuntime(config?: CursorRuntimeConfig): import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+export default _default;

package/dist/runtimes/droid.d.ts

@@ -0,0 +1,9 @@
+import { type CliAgentSpec } from "./_cli-agent.js";
+export declare const droidSpec: CliAgentSpec;
+export interface DroidRuntimeConfig {
+    /** `custom:<displayName>-<index>` matching the provisioned settings.json. */
+    model?: string;
+}
+export declare function createDroidRuntime(config?: DroidRuntimeConfig): import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+export default _default;