@agent-compose/sdk 0.2.3 → 0.2.5

package/src/step-invocation/types.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 class StepExecutionError extends Error {
+  readonly kind:     StepInvocationError["kind"];
+  readonly exitCode: number | undefined;
+  constructor(error: StepInvocationError, stepLabel: string) {
+    super(`[${error.kind}] ${stepLabel}: ${error.message}`);
+    this.name     = "StepExecutionError";
+    this.kind     = error.kind;
+    this.exitCode = error.kind === "runner-exit" ? error.exitCode : undefined;
+  }
+}

package/src/tools/coding.ts

@@ -0,0 +1,126 @@
+import { z } from "zod";
+import { isAbsolute, join } from "node:path/posix";
+import type { SandboxProvider } from "../types/sandbox.js";
+
+function q(value: string): string {
+  return JSON.stringify(value);
+}
+
+function resolvePath(path: string, cwd?: string): string {
+  return cwd && !isAbsolute(path) ? join(cwd, path) : path;
+}
+
+async function readFile(sandbox: SandboxProvider, path: string, opts?: { offset?: number; limit?: number; cwd?: string }): Promise<string> {
+  const script = `
+const fs = require("fs");
+const path = process.argv[1];
+const offset = process.argv[2] ? Number(process.argv[2]) : 1;
+const limit = process.argv[3] ? Number(process.argv[3]) : 2000;
+const data = fs.readFileSync(path, "utf8");
+const lines = data.split(/\\r?\\n/);
+const start = Math.max(1, offset);
+const end = Math.min(lines.length, start + Math.max(0, limit) - 1);
+for (let i = start; i <= end; i++) console.log(String(i) + ": " + lines[i - 1]);
+`;
+  const args = [q(path), opts?.offset !== undefined ? String(opts.offset) : "", opts?.limit !== undefined ? String(opts.limit) : ""]
+    .filter(Boolean)
+    .map(q)
+    .join(" ");
+  const { stdout } = await sandbox.commands.run(`node -e ${q(script)} ${args}`, { cwd: opts?.cwd, timeoutMs: 30_000 });
+  return stdout;
+}
+
+async function readRawFile(sandbox: SandboxProvider, path: string, cwd?: string): Promise<string> {
+  const script = `const fs = require("fs"); process.stdout.write(fs.readFileSync(process.argv[1], "utf8"));`;
+  const { stdout } = await sandbox.commands.run(`node -e ${q(script)} ${q(path)}`, { cwd, timeoutMs: 30_000 });
+  return stdout;
+}
+
+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 const readTool: CodingTool<{
+  path: string;
+  offset?: number;
+  limit?: number;
+}> = {
+  name: "Read",
+  description: "Read a UTF-8 text file from the sandbox. Returns numbered lines. Use offset/limit for large files.",
+  inputSchema: z.object({
+    path: z.string().describe("File path to read. Relative paths resolve from the agent working directory."),
+    offset: z.number().int().positive().optional().describe("1-based line number to start at."),
+    limit: z.number().int().positive().max(5000).optional().describe("Maximum number of lines to return."),
+  }),
+  execute: ({ path, offset, limit }, ctx) => readFile(ctx.sandbox, path, { offset, limit, cwd: ctx.cwd }),
+};
+
+export const writeTool: CodingTool<{
+  path: string;
+  content: string;
+}> = {
+  name: "Write",
+  description: "Write UTF-8 content to a file in the sandbox, creating or replacing the file.",
+  inputSchema: z.object({
+    path: z.string().describe("File path to write. Relative paths resolve from the agent working directory."),
+    content: z.string().describe("Complete file contents to write."),
+  }),
+  execute: async ({ path, content }, ctx) => {
+    const target = resolvePath(path, ctx.cwd);
+    await ctx.sandbox.files.write(target, content);
+    return `Wrote ${content.length} bytes to ${target}`;
+  },
+};
+
+export const editTool: CodingTool<{
+  path: string;
+  oldString: string;
+  newString: string;
+  replaceAll?: boolean;
+}> = {
+  name: "Edit",
+  description: "Edit a text file by replacing an exact string. Fails if the old string is not found or is ambiguous without replaceAll.",
+  inputSchema: z.object({
+    path: z.string().describe("File path to edit. Relative paths resolve from the agent working directory."),
+    oldString: z.string().min(1).describe("Exact text to replace."),
+    newString: z.string().describe("Replacement text."),
+    replaceAll: z.boolean().optional().describe("Replace every occurrence instead of requiring exactly one match."),
+  }),
+  execute: async ({ path, oldString, newString, replaceAll }, ctx) => {
+    const target = resolvePath(path, ctx.cwd);
+    const before = await readRawFile(ctx.sandbox, target, ctx.cwd);
+    const count = before.split(oldString).length - 1;
+    if (count === 0) throw new Error(`Edit failed: oldString not found in ${target}`);
+    if (!replaceAll && count !== 1) throw new Error(`Edit failed: oldString occurs ${count} times in ${target}; set replaceAll=true or make oldString more specific`);
+    const after = replaceAll ? before.split(oldString).join(newString) : before.replace(oldString, newString);
+    await ctx.sandbox.files.write(target, after);
+    return `Edited ${target}: replaced ${replaceAll ? count : 1} occurrence${(replaceAll ? count : 1) === 1 ? "" : "s"}`;
+  },
+};
+
+export const bashTool: CodingTool<{
+  command: string;
+  timeoutMs?: number;
+  cwd?: string;
+}> = {
+  name: "Bash",
+  description: "Run a shell command in the sandbox. Use for file discovery/search (e.g. globbing/grep via shell commands), tests, builds, and package commands.",
+  inputSchema: z.object({
+    command: z.string().min(1).describe("Shell command to execute."),
+    timeoutMs: z.number().int().positive().max(3_600_000).optional().describe("Timeout in milliseconds."),
+    cwd: z.string().optional().describe("Optional command working directory. Defaults to the agent working directory."),
+  }),
+  execute: async ({ command, timeoutMs, cwd }, ctx) => {
+    const result = await ctx.sandbox.commands.run(command, {
+      cwd: cwd ?? ctx.cwd,
+      timeoutMs: timeoutMs ?? 120_000,
+    });
+    if (result.exitCode !== 0) throw new Error(`Command failed with exit code ${result.exitCode}${result.stdout ? `\n${result.stdout}` : ""}`);
+    return result.stdout;
+  },
+};
+
+export const codingTools = [readTool, writeTool, editTool, bashTool] as const;

package/src/tools/index.ts

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

package/src/types/events.ts

@@ -8,6 +8,46 @@
  * 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;

package/src/types/execution-context.ts

@@ -0,0 +1,30 @@
+/** 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/src/types/runtime.ts

@@ -4,6 +4,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 {
@@ -21,16 +23,38 @@ 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/src/types/sandbox-environment.ts

@@ -37,9 +37,8 @@
  */
 
 import type { SandboxProvider } from "./sandbox.js";
-import { makeLocalSandboxProvider } from "../sandbox.js";
 import { defineWorkflow } from "./workflow.js";
-import type { WorkflowFn } from "./workflow.js";
+import type { Workflow } from "../workflow-steps/types.js";
 
 export interface SandboxEnvironmentDefinition {
   name: string;
@@ -51,14 +50,17 @@ export interface SandboxEnvironmentDefinition {
   saveSnapshot?: boolean;
 }
 
+/** 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 function defineSandboxEnvironment(
   env: SandboxEnvironmentDefinition,
-): WorkflowFn<void> {
+): Workflow<Record<string, unknown>, void> {
   if (typeof env.setup !== "function") {
     throw new Error(`defineSandboxEnvironment(${env.name}): 'setup' must be a function`);
   }
-  return defineWorkflow({
+  return defineWorkflow<void, Record<string, unknown>>({
     saveSnapshot: env.saveSnapshot ?? true,
-    run: () => env.setup(makeLocalSandboxProvider()),
+    run: async (_ctx, sandbox) => env.setup(sandbox),
   });
 }

package/src/types/sandbox.ts

@@ -4,25 +4,29 @@
  */
 
 /** 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/src/types/workflow-metadata.ts

@@ -0,0 +1,84 @@
+/**
+ * `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 function extractMetadata(source: Partial<WorkflowMetadata>): WorkflowMetadata {
+  const out: WorkflowMetadata = {};
+  if (source.networkPolicy !== undefined) out.networkPolicy = freezeMetadataValue(source.networkPolicy);
+  if (source.placeholders  !== undefined) out.placeholders  = Object.freeze({ ...source.placeholders });
+  if (source.snapshot      !== undefined) out.snapshot      = source.snapshot;
+  if (source.saveSnapshot  !== undefined) out.saveSnapshot  = source.saveSnapshot;
+  if (source.processors    !== undefined) out.processors    = Object.freeze([...source.processors]);
+  if (source.memory        !== undefined) out.memory        = typeof source.memory === "object" && source.memory !== null
+    ? Object.freeze({ ...source.memory })
+    : source.memory;
+  return Object.freeze(out);
+}
+
+/**
+ * Recursively freeze plain-data values (the network-policy shape). The
+ * policy is JSON-serializable — strings, arrays, plain objects — so a
+ * depth-first freeze is safe. We mutate the original (no clone) because
+ * the user already handed it to `defineWorkflow`; if they keep a sibling
+ * reference and mutate it later, they're modifying state they explicitly
+ * handed off. The freeze makes that intent enforced rather than implicit.
+ */
+function freezeMetadataValue<T>(value: T): T {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) {
+    for (const v of value) freezeMetadataValue(v);
+    return Object.freeze(value) as T;
+  }
+  for (const v of Object.values(value as Record<string, unknown>)) {
+    freezeMetadataValue(v);
+  }
+  return Object.freeze(value) as T;
+}

package/src/types/workflow-plan.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 function workflowPlan(steps: WorkflowStepPlan[]): WorkflowPlan {
+  return { steps };
+}