@agent-compose/sdk 0.2.3 → 0.2.4

package/dist/processors/builtins.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Built-in processors — minimal set that exercises all three hooks and
+ * covers the most common gating needs. More can be authored by users; these
+ * exist as load-bearing examples and as defaults for common policies.
+ */
+import type { Processor } from "./processor.js";
+/**
+ * Reject any tool call whose name appears in `names`. The reason is returned
+ * to the model as the tool result, so the model can react and try a
+ * different approach.
+ *
+ * Dormant in runtimes that don't support pre-tool gating (current Claude CLI
+ * runtime). Becomes active when a runtime that wires `processToolCall` lands
+ * (candidate #1).
+ */
+export declare function denyTools(names: readonly string[]): Processor;
+/**
+ * Require the calling API key to carry every scope in `required`. Aborts the
+ * agent loop with a clear reason if any are missing — defence-in-depth on
+ * top of the server's per-call scope checks.
+ *
+ * Runs as `processInput` so the violation is caught before the model is
+ * invoked, not after work has happened.
+ */
+export declare function requireScope(required: readonly string[]): Processor;
+/**
+ * Redact substrings matching `pattern` from each emitted text/thinking
+ * message before downstream observability sees it. Useful for stripping
+ * accidental secret echoes (e.g. a model that pasted an env var into its
+ * reasoning).
+ *
+ * Tool result and tool use messages are passed through unchanged — those
+ * paths have their own redaction story (network policy + secret brokering).
+ */
+export declare function redactPattern(pattern: RegExp, replacement?: string): Processor;

package/dist/processors/index.d.ts

@@ -0,0 +1,4 @@
+export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, } from "./processor.js";
+export { Verdict } from "./processor.js";
+export { runProcessorChain } from "./runner.js";
+export { denyTools, requireScope, redactPattern, } from "./builtins.js";

package/dist/processors/processor.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Processor — typed pre/post pipeline around the agent loop.
+ *
+ * One generic shape across three hook points:
+ *
+ *   - processInput(prompt, ctx)     → before each iteration's model call
+ *   - processOutput(message, ctx)   → after each emitted message
+ *   - processToolCall(call, ctx)    → before each tool call (runtime-driven)
+ *
+ * Why this exists: the user's "pre-tool-use hook", "policy", "falsifier", and
+ * "classifier" requirements are all the same shape — a typed step around the
+ * agent loop with access to RequestContext, an abort channel, and the
+ * ability to mutate or reject. Inventing four parallel APIs is the smell;
+ * one Processor interface is the cure.
+ *
+ * Verdict semantics differ by hook:
+ *
+ *   processInput deny    → agent loop ends with WorkflowError(reason)
+ *   processOutput deny   → message dropped; loop continues
+ *   processToolCall deny → tool short-circuited; reason returned to the
+ *                          model as the tool result; loop continues
+ *
+ *   abort (any hook)     → whole agent loop ends with WorkflowError(reason)
+ *
+ * Composition: workflow-level processors run first, then agent-level. First
+ * non-`continue` verdict short-circuits the chain for that hook target.
+ *
+ * Built-ins live in ./builtins.ts; chain executor lives in ./runner.ts.
+ */
+import type { AgentMessage } from "../types/protocol.js";
+import type { RequestContext } from "../request-context/request-context.js";
+/** Proposed tool call. Mirrors the relevant fields of AgentMessageToolUse but
+ *  lives as its own type so runtime adapters (candidate #1) can populate it
+ *  from their internal call shape without coupling to the agent message protocol. */
+export interface ToolCall {
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string;
+}
+/** Per-hook context. Minimal by design — observability sinks and stream
+ *  writers are NOT shipped in v1; add when concrete need shows up. */
+export interface ProcessorContext {
+    /** Per-run typed bag (tenant identity + freeform). */
+    requestContext: RequestContext;
+    /** Parent-loop cancellation — long-running processors should pass to fetch/etc. */
+    abortSignal: AbortSignal;
+    /** How many times processors have triggered retry for this generation. */
+    retryCount: number;
+    /** Which agent loop triggered this hook. */
+    agentId: string;
+    /** Iteration of the agent loop (1-based). */
+    iteration: number;
+}
+/**
+ * Verdict returned by every processor method.
+ * `continue` carries the (possibly mutated) value forward.
+ * `deny` and `abort` short-circuit the chain; their loop-level effect is
+ * defined per hook (see file header).
+ */
+export type ProcessorVerdict<T> = {
+    kind: "continue";
+    value: T;
+} | {
+    kind: "deny";
+    reason: string;
+} | {
+    kind: "abort";
+    reason: string;
+};
+/** Construction helpers — keep call sites readable. */
+export declare const Verdict: {
+    readonly continue: <T>(value: T) => ProcessorVerdict<T>;
+    readonly deny: <T = never>(reason: string) => ProcessorVerdict<T>;
+    readonly abort: <T = never>(reason: string) => ProcessorVerdict<T>;
+};
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * A Processor implements zero or more of the three hook methods. Methods
+ * may be sync or async. Omit a method to opt out of that hook.
+ *
+ * Processors should be cheap and deterministic where possible — the chain
+ * runs sequentially and gating is order-sensitive.
+ */
+export interface Processor {
+    /** Stable name for logging / metrics. Defaults to constructor / class name. */
+    readonly name?: string;
+    processInput?(prompt: string, ctx: ProcessorContext): MaybePromise<ProcessorVerdict<string>>;
+    processOutput?(message: AgentMessage, ctx: ProcessorContext): MaybePromise<ProcessorVerdict<AgentMessage>>;
+    processToolCall?(call: ToolCall, ctx: ProcessorContext): MaybePromise<ProcessorVerdict<ToolCall>>;
+}
+export {};

package/dist/processors/processor.test.d.ts

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

package/dist/processors/runner.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Processor chain runner — sequentially applies a list of processors to a
+ * value at one hook point, threading the (possibly mutated) value through
+ * each step. First non-`continue` verdict short-circuits the rest of the
+ * chain for that target.
+ *
+ * The chain is hook-agnostic: caller passes a `select` function that picks
+ * the relevant method off each Processor. Returns the final verdict — the
+ * agent loop interprets it per-hook semantics.
+ */
+import type { Processor, ProcessorContext, ProcessorVerdict } from "./processor.js";
+type HookSelector<T> = (p: Processor) => ((value: T, ctx: ProcessorContext) => ProcessorVerdict<T> | Promise<ProcessorVerdict<T>>) | undefined;
+/**
+ * Run a chain of processors against `initial`. Skips processors that don't
+ * implement the selected hook. Returns the final verdict; for `continue`
+ * the `value` is the threaded-through (possibly mutated) result.
+ */
+export declare function runProcessorChain<T>(processors: readonly Processor[], selectHook: HookSelector<T>, initial: T, ctx: ProcessorContext): Promise<ProcessorVerdict<T>>;
+export {};

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

@@ -0,0 +1,2 @@
+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.js";
+export type { RequestContextReserved, RequestContextWire, } from "./request-context.js";

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

@@ -0,0 +1,159 @@
+/**
+ * RequestContext — one typed bag carrying tenant identity + freeform
+ * per-run state across the boundary between server, dispatch, runner,
+ * workflow body, agent loop, and (future) processors.
+ *
+ * Two halves:
+ *
+ *   - **Reserved keys** are tenant identity + run identity. They are
+ *     authoritative once the server's auth middleware sets them and
+ *     CANNOT be mutated downstream — `set()` on a reserved key throws.
+ *     This is the same multi-tenancy hijack defence we apply at the RLS
+ *     layer: the runner never gets to claim a different `teamId`.
+ *
+ *   - **Freeform user namespace** is plain `set/get/has/delete` for any
+ *     JSON-serialisable values the caller wants to thread through. Used
+ *     by application code (workflows, processors) for their own state.
+ *
+ * Reserved-key authority:
+ *
+ *   ac__teamId        server (auth middleware)
+ *   ac__runId         server (dispatch)
+ *   ac__workflowId    server (dispatch)
+ *   ac__factoryId     server (auth)            -- nullable
+ *   ac__apiKeyScopes  server (auth)
+ *   ac__parentRunId   server (dispatch)        -- nullable
+ *   ac__abortSignal   runner (per-process)     -- not serialised
+ *
+ * Cross-process flow (server → runner):
+ *
+ *   1. Server constructs `RequestContext` at the auth boundary using the
+ *      reserved key authorities listed above.
+ *   2. `serialise()` → JSON shape `{ reserved, user }` (abortSignal stripped).
+ *   3. Dispatch hands the JSON to the runner sandbox via env (or future
+ *      transport).
+ *   4. Runner calls `RequestContext.deserialise(json)` and attaches its
+ *      own `AbortSignal`. Reserved keys are re-frozen on materialisation.
+ *
+ * `invokeChild` propagation: only reserved keys flow to the child; freeform
+ * is per-run by design (cross-run state must be explicit via `input`).
+ */
+/** 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";
+export declare const AC_RUN_ID: "ac__runId";
+export declare const AC_WORKFLOW_ID: "ac__workflowId";
+export declare const AC_FACTORY_ID: "ac__factoryId";
+export declare const AC_API_KEY_SCOPES: "ac__apiKeyScopes";
+export declare const AC_PARENT_RUN_ID: "ac__parentRunId";
+export declare const AC_ABORT_SIGNAL: "ac__abortSignal";
+/** Reserved keys, as a runtime set for guardrails. Includes all keys above. */
+declare const RESERVED_KEYS: ReadonlySet<string>;
+/** Reserved keys that cross the dispatch boundary as JSON. Excludes `abortSignal`. */
+declare const SERIALISABLE_RESERVED_KEYS: ReadonlySet<string>;
+/**
+ * Required reserved values to construct a context. `factoryId` and
+ * `parentRunId` are nullable (factory-scoped key absent → null; root run → null).
+ * `abortSignal` is optional and runner-set; not serialised.
+ */
+export interface RequestContextReserved {
+    teamId: string;
+    runId: string;
+    workflowId: string;
+    factoryId: string | null;
+    apiKeyScopes: readonly string[];
+    parentRunId: string | null;
+    abortSignal?: AbortSignal;
+}
+/** Wire shape for crossing the dispatch boundary. `abortSignal` is stripped. */
+export interface RequestContextWire {
+    reserved: {
+        teamId: string;
+        runId: string;
+        workflowId: string;
+        factoryId: string | null;
+        apiKeyScopes: readonly string[];
+        parentRunId: string | null;
+    };
+    user: Record<string, unknown>;
+}
+/** Thrown when a caller tries to `set` or `delete` a reserved key downstream. */
+export declare class ReservedKeyError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+/** Thrown when freeform `set` receives a non-JSON-serialisable value. */
+export declare class NonSerialisableValueError extends Error {
+    constructor(key: string, cause: unknown);
+}
+/**
+ * Per-run request context. Construct via `RequestContext.fromReserved(...)`
+ * at the auth boundary; downstream code receives an instance and calls
+ * `.get` / `.set` on it.
+ *
+ * Type parameter `U` lets callers narrow the freeform user namespace shape
+ * for `.get`/`.set` typing — defaults to `unknown` (truly freeform).
+ */
+export declare class RequestContext<U extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly reserved;
+    private readonly user;
+    private constructor();
+    /**
+     * Build a context at the auth/dispatch boundary. Callers (server auth
+     * middleware, dispatch) own the reserved values and pass them in once.
+     */
+    static fromReserved(reserved: RequestContextReserved): RequestContext;
+    /**
+     * Materialise from the wire shape produced by `serialise()`.
+     * Used by the runner after receiving the JSON via env. The runner attaches
+     * its own `AbortSignal` separately via `withAbortSignal()`.
+     */
+    static deserialise(wire: RequestContextWire): RequestContext;
+    /**
+     * Return a new instance with the given abort signal attached. Used by the
+     * runner once it owns a per-process signal.
+     */
+    withAbortSignal(signal: AbortSignal): RequestContext;
+    get teamId(): string;
+    get runId(): string;
+    get workflowId(): string;
+    get factoryId(): string | null;
+    get apiKeyScopes(): readonly string[];
+    get parentRunId(): string | null;
+    get abortSignal(): AbortSignal | undefined;
+    /** True if the calling key has the given scope. Read-only convenience. */
+    hasScope(scope: string): boolean;
+    /**
+     * Set a freeform key. Throws `ReservedKeyError` if `key` collides with the
+     * reserved namespace, and `NonSerialisableValueError` if `value` cannot be
+     * JSON-serialised (so cross-process behaviour matches in-process behaviour).
+     */
+    set<K extends keyof U & string>(key: K, value: U[K]): void;
+    set(key: string, value: unknown): void;
+    get<K extends keyof U & string>(key: K): U[K] | undefined;
+    get(key: string): unknown;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    /** Iterate freeform entries only. Reserved keys are not iterable. */
+    entries(): IterableIterator<[string, unknown]>;
+    /**
+     * Produce the wire shape for crossing the dispatch boundary. `abortSignal`
+     * is stripped; freeform values are passed through (they were validated as
+     * JSON-serialisable on `set`).
+     */
+    serialise(): RequestContextWire;
+    /**
+     * Build a child context for an `invokeChild` call: reserved keys propagate
+     * (with `parentRunId` rewritten to the parent's `runId` and `runId`/`workflowId`
+     * supplied by the caller for the child run); freeform DOES NOT propagate.
+     *
+     * Used server-side when dispatch resolves a child invocation; the freeform
+     * namespace is intentionally per-run to keep cross-run state explicit.
+     */
+    forChild(opts: {
+        runId: string;
+        workflowId: string;
+    }): RequestContext;
+}
+/** Re-export reserved key set for callers that need to filter env or headers. */
+export { SERIALISABLE_RESERVED_KEYS, RESERVED_KEYS };

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

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

package/dist/runtimes/claude.d.ts

@@ -1,63 +1,40 @@
-/**
- * Claude CLI runtime — drives agents via the Claude CLI inside a sandbox.
- *
- * Works with any SandboxProvider (E2B, Vercel, etc.) — the provider is
- * selected via SANDBOX_PROVIDER env var, not the runtime definition.
- *
- * Usage:
- *   import { createClaudeRuntime } from "@agent-compose/sdk";
- *   export default createClaudeRuntime({ claudeMdContent: "..." }); // optional global instructions
- */
-import type { SandboxProvider, AgentMessage, ModelExecutionContract, RuntimeOptions } from "../index.js";
-export declare class ClaudeRunner implements ModelExecutionContract {
-    private sandbox;
-    private options;
-    private claudeMdContent;
-    private configEnv;
-    private configModel?;
-    private configMcpServers?;
-    private claudeMdWritten;
-    private homeDir;
-    private label;
-    constructor(sandbox: SandboxProvider, options?: RuntimeOptions, claudeMdContent?: string, configEnv?: Record<string, string>, configModel?: string | undefined, configMcpServers?: Record<string, {
-        command: string;
-        args?: string[];
-        env?: Record<string, string>;
-    }> | undefined);
-    private getHomeDir;
-    private deployGlobalConfig;
-    /** Stream one CLI invocation, yielding AgentMessages. Resolves when the process exits. */
-    private _runCli;
-    sendMessage(opts: {
-        prompt: string;
-        sessionId?: string;
-        signal?: AbortSignal;
-    }): AsyncGenerator<AgentMessage>;
-}
+/** Claude Agent SDK runtime — replaces the old Claude CLI subprocess runtime. */
+import { type ThinkingConfig } from "@anthropic-ai/claude-agent-sdk";
+import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider, ToolCallGateResult } from "../index.js";
+import type { ProcessorContext, ToolCall } from "../processors/processor.js";
 export interface ClaudeRuntimeConfig {
-    /** Global instructions written to ~/.claude/CLAUDE.md in every sandbox. */
+    /** Global instructions appended to the Claude Code system prompt. */
     claudeMdContent?: string;
-    /**
-     * Environment variables set before each CLI invocation.
-     * Use to configure API provider routing (e.g. OpenRouter):
-     *   env: { ANTHROPIC_BASE_URL: "https://openrouter.ai/api", ANTHROPIC_AUTH_TOKEN: "$OPENROUTER_API_KEY", ANTHROPIC_API_KEY: "" }
-     */
+    /** Env overrides for Agent SDK provider routing. */
     env?: Record<string, string>;
-    /** Model to use (e.g. "claude-opus-4-6", "anthropic/claude-sonnet-4-6"). */
+    /** Model to use. Defaults to DEFAULT_CLAUDE_MODEL. */
     model?: string;
-    /** MCP servers to configure in the sandbox. Written to ~/.claude.json before the first iteration. */
+    /** MCP servers to configure for the Agent SDK. */
     mcpServers?: Record<string, {
         command: string;
         args?: string[];
         env?: Record<string, string>;
     }>;
+    /** Claude Code executable. Defaults to `claude` from PATH inside the sandbox. */
+    pathToClaudeCodeExecutable?: string;
+    /** Controls Claude's extended thinking behavior when supported by the model. */
+    thinking?: ThinkingConfig;
+    /** Reasoning effort hint for models that support adaptive thinking. */
+    effort?: "low" | "medium" | "high" | "xhigh" | "max";
+}
+export declare class ClaudeRunner implements ModelExecutionContract {
+    private readonly options;
+    private readonly config;
+    supportsToolCallProcessor: boolean;
+    constructor(_sandbox: SandboxProvider, options?: RuntimeOptions, config?: ClaudeRuntimeConfig);
+    gateToolCall(call: ToolCall, ctx: ProcessorContext): Promise<ToolCallGateResult>;
+    sendMessage(opts: {
+        prompt: string;
+        sessionId?: string;
+        iteration?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<AgentMessage>;
 }
-/**
- * Create a Claude CLI runtime.
- *
- * Encapsulates everything about how the Claude CLI runs in a sandbox:
- * API provider routing, MCP server configuration, and global instructions.
- */
 export declare function createClaudeRuntime(config?: ClaudeRuntimeConfig): import("../index.js").AgentRuntime<SandboxProvider>;
 declare const _default: import("../index.js").AgentRuntime<SandboxProvider>;
 export default _default;