@agent-compose/sdk 0.2.2 → 0.2.4

package/dist/step-invocation/invoker.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Server-side half of StepInvocation. The Temporal `executeStep` activity
+ * (and any future durable engine's equivalent) calls `invokeStep(...)` to
+ * run one step inside an existing runner sandbox.
+ *
+ * Owns:
+ *   - per-invocation result token (protocol hygiene — keeps user-side
+ *     stdout from accidentally contaminating the result channel)
+ *   - input + request-context file writes
+ *   - env stamping
+ *   - sandbox.commands.run with the runner command
+ *   - tokenised stdout sentinel parse
+ *   - failure-mode classification (protocol / user-step / runner-exit)
+ *
+ * Caller owns:
+ *   - reconnecting to the runner sandbox (per-team, per-run)
+ *   - turning a kinded error into the activity's exception shape
+ *
+ * No timeout: Temporal's startToCloseTimeout already bounds the activity.
+ * `sandbox.commands.run({ timeoutMs: 0 })` lets the runner consume that
+ * full window before the activity times out and Temporal kills the call.
+ */
+import type { SandboxProvider } from "../types/sandbox.js";
+import type { StepRequest, StepResult } from "./types.js";
+export { RUNNER_COMMAND } from "./protocol.js";
+/** Build the env map for one step invocation. Pure function; tests use it
+ *  to assert the env shape (and to assert that no server-held credentials
+ *  leak in) without spawning a sandbox. */
+export declare function buildStepEnvs(args: {
+    runId: string;
+    stepIndex: number;
+    resultToken: string;
+}): Record<string, string>;
+/** Scan the runner's stdout for the tokenised sentinel line and return a
+ *  classified result. Returns `null` when no sentinel is present — the
+ *  caller distinguishes that case from a parsed `{ ok: false }` payload
+ *  using exit code (see `invokeStep`). Pure function for testability.
+ *
+ *  Failure classification is taken from the runner's `kind` field on the
+ *  payload (the runner separates setup/protocol failures from handler
+ *  throws). If `kind` is missing or unknown, treat as `protocol` —
+ *  that's a malformed payload, which by definition is a wire violation. */
+export declare function parseStepResult<TOutput = unknown>(stdout: string, resultToken: string): StepResult<TOutput> | null;
+/**
+ * Run one step inside the given sandbox. The full ceremony is here so the
+ * caller body is "reconnect sandbox → invokeStep → narrow result". A
+ * stdout line that happens to start with the sentinel prefix but carries
+ * a different token is ignored — the per-invocation token guarantees the
+ * result channel can't be contaminated by user `console.log` output or
+ * by any dep that logs a JSON-shaped line.
+ */
+export interface InvokeStepOptions {
+    envs?: Record<string, string>;
+    /** Live stdout / stderr from the runner subprocess, line-by-line. Called
+     *  from inside `sandbox.commands.run` as chunks arrive. The sentinel line
+     *  carrying the protocol result token is filtered out before delivery so
+     *  callers only see user-visible runtime output.
+     *
+     *  Callbacks are invoked synchronously from the sandbox stream loop — keep
+     *  them cheap (e.g. push to an in-memory array). Persisting / shipping is
+     *  the caller's job; the activity batches and inserts at step completion. */
+    onStdout?: (line: string) => void;
+    onStderr?: (line: string) => void;
+}
+export declare function invokeStep<TOutput = unknown>(sandbox: SandboxProvider, request: StepRequest, opts?: InvokeStepOptions): Promise<StepResult<TOutput>>;

package/dist/step-invocation/protocol.d.ts

@@ -0,0 +1,44 @@
+/**
+ * StepInvocation — wire protocol between server-side activity (the
+ * invoker) and runner-side step server. Both halves consume these
+ * constants so the format is single-sourced; changing it is one diff.
+ *
+ * The protocol carries one workflow step's input/output across an OS
+ * process boundary (server's Temporal worker process → runner sandbox
+ * subprocess). It deliberately does not depend on Temporal — a future
+ * Inngest provider can reuse the same wire.
+ */
+/** Sentinel that prefixes the step result on the runner's stdout. The
+ *  invoker scans for `<prefix><token>:<json>` so any user `console.log`
+ *  with the same prefix but a wrong token is rejected. */
+export declare const STEP_RESULT_PREFIX = "__AC_STEP_RESULT__";
+/** Build the line prefix the runner emits and the invoker scans for. The
+ *  runner-side serveStep writes `<prefix><token>:<json>\n`; the invoker's
+ *  result parser AND the stdout line splitter both match on this exact
+ *  prefix so a future change can't make them drift (review found a
+ *  separator mismatch that leaked the sentinel into captured logs). */
+export declare function stepResultLinePrefix(token: string): string;
+/** Sandbox-side path where dispatch writes the compiled runner bundle.
+ *  Both modes (full-mode `dispatch.ts` and step-mode `invokeStep`) spawn
+ *  the runner from this path; single source of truth. */
+export declare const RUNNER_BUNDLE_PATH = "/tmp/runner.bundle.js";
+/** Command the invoker (and dispatch) spawns inside the sandbox. */
+export declare const RUNNER_COMMAND = "node /tmp/runner.bundle.js";
+/** Names of the env vars the invoker stamps onto the runner subprocess.
+ *  The runner's serveStep reads from these. Centralising the names lets
+ *  tests assert the env shape without duplicating string literals. */
+export declare const STEP_ENV: {
+    readonly RUN_ID: "RUN_ID";
+    readonly STEP_MODE: "AC_STEP_MODE";
+    readonly STEP_INDEX: "AC_STEP_INDEX";
+    readonly STEP_INPUT_PATH: "AC_STEP_INPUT_PATH";
+    readonly REQUEST_CONTEXT_PATH: "AC_REQUEST_CONTEXT_PATH";
+    readonly STEP_RESULT_TOKEN: "AC_STEP_RESULT_TOKEN";
+};
+/** Sandbox-side path where the invoker writes the JSON-encoded step input.
+ *  The serveStep reads from this exact path; both halves use this helper. */
+export declare function stepInputPath(stepIndex: number): string;
+/** Sandbox-side path where the invoker writes the JSON-encoded request
+ *  context. The serveStep reads from this exact path; both halves use
+ *  this helper. */
+export declare function requestContextPath(stepIndex: number): string;

package/dist/step-invocation/server.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Runner-side half of StepInvocation. The worker's runner.ts in step
+ * mode calls `serveStep(handler)` — read the input + request context
+ * from env-pointed files, run the user handler, emit the tokenised
+ * sentinel result line on stdout, exit with the right code.
+ *
+ * Owns:
+ *   - reading inputs from the env-pointed JSON files
+ *   - parse-error handling (protocol-violating env or malformed file)
+ *   - tokenised sentinel emission (matched by the invoker's parser)
+ *   - awaited stdout flush before process.exit (Linux pipes can drop
+ *     unflushed bytes when the writer exits)
+ *   - exit codes (0 on success, 1 on any failure)
+ *
+ * Handler owns:
+ *   - what to do with the input (load the compiled workflow, run the
+ *     step, return the output)
+ *
+ * `serveStep` never returns — it always exits the process. The return
+ * type is `Promise<never>` so callers can `await serveStep(...)` and
+ * trust nothing runs after.
+ */
+import type { RequestContextWire } from "../request-context/request-context.js";
+import type { StepObservability } from "../workflow-steps/observability.js";
+/** What the handler receives. The serveStep already parsed the input
+ *  and request context from their JSON files. */
+export interface ServeStepRequest<TInput = unknown> {
+    runId: string;
+    stepIndex: number;
+    input: TInput;
+    requestContext: RequestContextWire;
+}
+/** What the handler returns. `observability` is the buffered snapshot
+ *  of `ctx.setMetadata` / `ctx.step` / `ctx.agentEvents` recorded during
+ *  the step; serveStep forwards it on the wire and the activity persists
+ *  it. Undefined for handlers that don't use the hooks. */
+export interface StepHandlerResult<TOutput = unknown> {
+    output: TOutput;
+    observability?: StepObservability;
+}
+/** User handler signature: take parsed step request, return the step
+ *  output (and optional observability bundle). Throwing turns into
+ *  `{ ok: false, kind: "user-step", error: <message> }` on the wire. */
+export type StepHandler<TInput = unknown, TOutput = unknown> = (request: ServeStepRequest<TInput>) => Promise<StepHandlerResult<TOutput>>;
+/**
+ * Read step input + request context, invoke `handler`, emit the result,
+ * exit. `Promise<never>` because every code path ends in `process.exit`.
+ *
+ * Two distinct phases under separate try/catch:
+ *   1. Setup — read envs, parse the input + context files. Failures
+ *      here mean the wire is broken (server bug); they emit
+ *      `{ok:false, kind:"protocol"}`.
+ *   2. Handler — call the user-supplied step body. Failures here are
+ *      user code throwing; they emit `{ok:false, kind:"user-step"}`.
+ *
+ * Between the two phases, step-invocation transport envs are scrubbed
+ * from process.env so user code (including any workflow module imported
+ * inside the handler) cannot read AC_STEP_RESULT_TOKEN — that keeps the
+ * result channel uncorruptible by stdout output from anywhere in the
+ * workflow's dep tree. RUN_ID remains available to match full-mode
+ * runner behaviour.
+ */
+export declare function serveStep<TInput, TOutput>(handler: StepHandler<TInput, TOutput>): Promise<never>;

package/dist/step-invocation/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * StepInvocation public types — what callers (the activity) get back, and
+ * the discriminated error union that classifies failure modes.
+ */
+import type { RequestContextWire } from "../request-context/request-context.js";
+import type { StepObservability } from "../workflow-steps/observability.js";
+/** What the invoker needs to drive one step invocation. The step's
+ *  human-readable name is *not* on here — `invokeStep` doesn't need it
+ *  (the result token isolates the result channel from stdout traffic;
+ *  run id is enough for message attribution). Callers attach step name
+ *  to thrown errors at their layer (see `StepExecutionError`). */
+export interface StepRequest<TInput = unknown> {
+    runId: string;
+    stepIndex: number;
+    input: TInput;
+    requestContext: RequestContextWire;
+}
+/**
+ * Outcome of one step invocation. Successful runs carry the step's output;
+ * failed runs carry a kinded error so the caller can distinguish "user
+ * code threw" from "runner crashed before emitting" from "wire protocol
+ * violation". The dashboard surfaces the kind to operators; the activity
+ * uses the kind to pick a useful failRun reason.
+ */
+export type StepResult<TOutput = unknown> = {
+    ok: true;
+    output: TOutput;
+    observability?: StepObservability;
+} | {
+    ok: false;
+    error: StepInvocationError;
+};
+/**
+ * Discriminated error union.
+ *
+ * - `protocol` — the runner did not emit a tokenised sentinel line, OR the
+ *   sentinel JSON was malformed. This is a runner-side bug or a sandbox
+ *   provider that swallowed stdout. Surface it loudly; do not blame user
+ *   code.
+ *
+ * - `user-step` — the step body threw. The runner caught it and emitted
+ *   `{ ok: false, error: <user message> }`. The message is the user's
+ *   to read.
+ *
+ * - `runner-exit` — the runner subprocess exited non-zero before emitting
+ *   any sentinel. Out-of-memory, SIGKILL from sandbox lifetime cap,
+ *   bundler crash, etc. Distinct from `protocol` because exit code is
+ *   meaningful evidence.
+ */
+export type StepInvocationError = {
+    kind: "protocol";
+    message: string;
+} | {
+    kind: "user-step";
+    message: string;
+} | {
+    kind: "runner-exit";
+    message: string;
+    exitCode: number;
+};
+/**
+ * Error thrown by the activity (or any caller) to surface a step failure
+ * with its kind preserved. The Temporal activity boundary serialises
+ * `message` to `failRun`, so the message is prefixed with `[<kind>]` —
+ * dashboard / log consumers can parse the prefix without losing the
+ * structured shape carried on the instance itself.
+ */
+export declare class StepExecutionError extends Error {
+    readonly kind: StepInvocationError["kind"];
+    readonly exitCode: number | undefined;
+    constructor(error: StepInvocationError, stepLabel: string);
+}

package/dist/tools/coding.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import type { SandboxProvider } from "../types/sandbox.js";
+export interface CodingTool<TInput extends Record<string, unknown> = Record<string, unknown>> {
+    name: string;
+    description: string;
+    inputSchema: z.ZodType<TInput>;
+    execute(input: TInput, ctx: {
+        sandbox: SandboxProvider;
+        cwd?: string;
+        abortSignal?: AbortSignal;
+    }): Promise<string>;
+}
+export declare const readTool: CodingTool<{
+    path: string;
+    offset?: number;
+    limit?: number;
+}>;
+export declare const writeTool: CodingTool<{
+    path: string;
+    content: string;
+}>;
+export declare const editTool: CodingTool<{
+    path: string;
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean;
+}>;
+export declare const bashTool: CodingTool<{
+    command: string;
+    timeoutMs?: number;
+    cwd?: string;
+}>;
+export declare const codingTools: readonly [CodingTool<{
+    path: string;
+    offset?: number;
+    limit?: number;
+}>, CodingTool<{
+    path: string;
+    content: string;
+}>, CodingTool<{
+    path: string;
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean;
+}>, CodingTool<{
+    command: string;
+    timeoutMs?: number;
+    cwd?: string;
+}>];

package/dist/tools/coding.test.d.ts

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

package/dist/tools/index.d.ts

@@ -0,0 +1,2 @@
+export { bashTool, codingTools, editTool, readTool, writeTool, } from "./coding.js";
+export type { CodingTool } from "./coding.js";

package/dist/types/events.d.ts

@@ -8,6 +8,42 @@
  * The `event` field doubles as the SSE `event:` name.
  */
 export type RunEvent = {
+    event: "agent.spawned";
+    runId: string;
+    at: number;
+    seq?: number;
+    agentId: string;
+    label: string;
+} | {
+    event: "agent.message";
+    runId: string;
+    at: number;
+    seq?: number;
+    agentId: string;
+    label: string;
+    iteration: number;
+    message: unknown;
+} | {
+    event: "agent.iteration";
+    runId: string;
+    at: number;
+    seq?: number;
+    agentId: string;
+    label: string;
+    iteration: number;
+    status: unknown;
+} | {
+    event: "agent.settled";
+    runId: string;
+    at: number;
+    seq?: number;
+    agentId: string;
+    label: string;
+    outcome: "success" | "failed";
+    iterations: number;
+    durationMs: number;
+    failureReason?: string;
+} | {
     event: "agent_event";
     runId: string;
     at: number;

package/dist/types/execution-context.d.ts

@@ -0,0 +1,22 @@
+/** Shared execution context capabilities for workflow functions and steps. */
+import type { InvokeAndWaitOptions, RunStatus } from "../client.js";
+import type { RequestContext } from "../request-context/request-context.js";
+import type { SandboxProvider } from "./sandbox.js";
+/** The identity of this workflow run. */
+export interface WorkflowRun {
+    id: string;
+}
+export interface InvokeChild {
+    <TOutput = unknown>(name: string, input?: Record<string, unknown>, opts?: Omit<InvokeAndWaitOptions, "parentRunId">): Promise<RunStatus<TOutput>>;
+}
+/** Capabilities shared by legacy workflow ctx and step ctx. */
+export interface BaseExecutionContext {
+    run: WorkflowRun;
+    requestContext: RequestContext;
+    /** Present when the engine executes inside a sandbox-backed workspace. */
+    sandbox?: SandboxProvider;
+    /** Persist key-value metadata on the run record when the engine supports it. */
+    setMetadata?: (data: Record<string, unknown>) => Promise<void>;
+    /** Invoke another registered workflow and wait for it to settle. */
+    invokeChild: InvokeChild;
+}

package/dist/types/runtime.d.ts

@@ -3,6 +3,8 @@
  */
 import type { SandboxProvider } from "./sandbox.js";
 import type { AgentMessage } from "./protocol.js";
+import type { Processor, ProcessorContext, ToolCall } from "../processors/processor.js";
+import type { RequestContext } from "../request-context/request-context.js";
 /** Configuration for a single MCP server. */
 export interface McpServerConfig {
     command: string;
@@ -18,15 +20,45 @@ export interface RuntimeOptions {
     label?: string;
     /** Working directory — the claude CLI process starts here so relative paths work correctly. */
     cwd?: string;
+    /** Processor chain registered by workflow/agent code. Runtime adapters that
+     *  own tool execution should call `processToolCall` before the tool runs. */
+    processors?: readonly Processor[];
+    /** Per-run typed bag threaded into processor contexts. */
+    requestContext?: RequestContext;
+    /** Agent id and label for processor context / adapter logs. */
+    agentId?: string;
+    iteration?: number;
+    /** Optional JSON schema for runtimes with native structured-output support. */
+    outputFormat?: {
+        type: "json_schema";
+        schema: Record<string, unknown>;
+    };
 }
+/** Runtime-normalized result of running pre-tool processors. */
+export type ToolCallGateResult = {
+    kind: "allow";
+    call: ToolCall;
+} | {
+    kind: "deny";
+    reason: string;
+} | {
+    kind: "abort";
+    reason: string;
+};
 /**
  * The execution contract every runtime must satisfy.
  * Given a prompt, yield a stream of agent events.
  */
 export interface ModelExecutionContract {
+    /** True when this runtime can run `processToolCall` before tool execution. */
+    supportsToolCallProcessor?: boolean;
+    /** Runtime-owned pre-tool gate. Adapters call the shared processor chain
+     *  through this seam; the agent loop stays SDK-agnostic. */
+    gateToolCall?(call: ToolCall, ctx: ProcessorContext): Promise<ToolCallGateResult>;
     sendMessage(opts: {
         prompt: string;
         sessionId?: string;
+        iteration?: number;
         signal?: AbortSignal;
     }): AsyncGenerator<AgentMessage>;
 }

package/dist/types/sandbox-environment.d.ts

@@ -36,7 +36,7 @@
  * ```
  */
 import type { SandboxProvider } from "./sandbox.js";
-import type { WorkflowFn } from "./workflow.js";
+import type { Workflow } from "../workflow-steps/types.js";
 export interface SandboxEnvironmentDefinition {
     name: string;
     description?: string;
@@ -46,4 +46,7 @@ export interface SandboxEnvironmentDefinition {
      *  be referenced as the `snapshot` field on another workflow). */
     saveSnapshot?: boolean;
 }
-export declare function defineSandboxEnvironment(env: SandboxEnvironmentDefinition): WorkflowFn<void>;
+/** Sugar over `defineWorkflow` for setup-only workflows that exist to
+ *  capture a snapshot. The workflow takes no meaningful input and returns
+ *  nothing — its value is the side effect on the sandbox VM. */
+export declare function defineSandboxEnvironment(env: SandboxEnvironmentDefinition): Workflow<Record<string, unknown>, void>;

package/dist/types/sandbox.d.ts

@@ -3,25 +3,27 @@
  * Provider-agnostic: E2B, Vercel, Docker, or any other backend implements this.
  */
 /** Base compute interface — pure I/O, no filesystem path or git concerns. */
+export interface SandboxCommandRunOptions {
+    cwd?: string;
+    timeoutMs?: number;
+    envs?: Record<string, string>;
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+    background?: boolean;
+}
+export interface SandboxCommandResult {
+    exitCode: number;
+    stdout: string;
+}
 export interface SandboxProvider {
     sandboxId: string;
     /** Working directory for the agent process. Set by onStart after environment setup. */
     cwd?: string;
     commands: {
-        run(cmd: string, opts?: {
-            cwd?: string;
-            timeoutMs?: number;
-            envs?: Record<string, string>;
-            onStdout?: (data: string) => void;
-            onStderr?: (data: string) => void;
-            background?: boolean;
-        }): Promise<{
-            exitCode: number;
-            stdout: string;
-        }>;
+        run(cmd: string, opts?: SandboxCommandRunOptions): Promise<SandboxCommandResult>;
     };
     files: {
-        write(path: string, content: string): Promise<unknown>;
+        write(path: string, content: string): Promise<void>;
     };
     kill(): Promise<void>;
     /** Capture the running sandbox's state as a reusable snapshot. Vercel

package/dist/types/workflow-metadata.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `WorkflowMetadata` — server-readable declarations that ride on every
+ * `Workflow` as `workflow.metadata`. Owned here (not in `types/workflow.ts`)
+ * because both that file and `workflow-steps/workflow.ts` need the type +
+ * helper; co-locating them in `types/workflow.ts` introduced a runtime
+ * import cycle.
+ *
+ * Keep this module free of value imports from `types/workflow.ts` or
+ * `workflow-steps/workflow.ts` — it is the cycle-break point.
+ */
+import type { SandboxNetworkPolicy } from "../sandbox.js";
+import type { Processor } from "../processors/processor.js";
+/**
+ * Workflow-level metadata read by the server at registration. Lives on
+ * every `Workflow` as `workflow.metadata`, regardless of which form of
+ * `defineWorkflow` produced it.
+ *
+ * The bundler reads these from the default export at registration time
+ * and forwards them to the server's POST /api/v1/templates payload.
+ */
+/** Server-side knob for whether/how a Workflow Memory agent should run
+ *  after this workflow completes. `"default"` runs the built-in extractor;
+ *  `false` disables; an object names a custom memory workflow to dispatch. */
+export type WorkflowMemoryConfig = "default" | false | {
+    workflow: string;
+};
+export interface WorkflowMetadata {
+    networkPolicy?: SandboxNetworkPolicy;
+    placeholders?: Record<string, string>;
+    snapshot?: string;
+    saveSnapshot?: boolean;
+    processors?: readonly Processor[];
+    memory?: WorkflowMemoryConfig;
+}
+/**
+ * Pull the server-readable declarations off a source object (run-form
+ * `WorkflowDefinition` or step-form `StepWorkflowDefinition`) into a
+ * single `WorkflowMetadata` bag. Undefined fields are omitted so the
+ * canonical metadata hash (server-side) is stable across re-registers
+ * that left a field unspecified.
+ *
+ * Returns a frozen bag — see `freezeMetadataValue` for the depth. The
+ * workflow object is meant to be immutable after `defineWorkflow` returns;
+ * the bundler reads `metadata` directly and any mutation between
+ * construction and bundling would diverge the canonical metadata hash
+ * from what the author declared.
+ *
+ * Accepts any source that overlaps `WorkflowMetadata` in field shape —
+ * both definition types are supersets of it.
+ */
+export declare function extractMetadata(source: Partial<WorkflowMetadata>): WorkflowMetadata;

package/dist/types/workflow-plan.d.ts

@@ -0,0 +1,19 @@
+/**
+ * WorkflowPlan — provider-neutral execution shape extracted at registration.
+ *
+ * The server must not execute user workflow source to discover shape at
+ * dispatch time. The CLI/bundler inspects the bundled module in the user's
+ * environment and sends this compact plan as metadata.
+ *
+ * Every workflow has a step plan. Legacy `defineWorkflow({ run })`
+ * workflows are wrapped at the SDK boundary as a single-step compiled
+ * workflow (step name = "run"); the bundler sees the same shape regardless.
+ */
+export interface WorkflowStepPlan {
+    index: number;
+    name: string;
+}
+export interface WorkflowPlan {
+    steps: WorkflowStepPlan[];
+}
+export declare function workflowPlan(steps: WorkflowStepPlan[]): WorkflowPlan;