@agent-compose/sdk 0.2.2 → 0.2.4

package/dist/runtimes/openai-desktop.js

@@ -17,24 +17,1423 @@ var __toESM = (mod, isNodeMode, target) => {
 };
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
+// src/runtimes/vercel.ts
+import { streamText, stepCountIs, tool } from "ai";
+
 // src/types/runtime.ts
 function defineRuntime(pkg) {
   if (typeof pkg.create !== "function")
     throw new Error("defineRuntime: 'create' is required");
   return pkg;
 }
-// src/types/workflow.ts
-function defineWorkflow(def) {
-  return Object.assign(def.run, {
-    networkPolicy: def.networkPolicy,
-    placeholders: def.placeholders,
-    snapshot: def.snapshot,
-    saveSnapshot: def.saveSnapshot
+
+// src/tools/coding.ts
+import { z } from "zod";
+import { isAbsolute, join } from "node:path/posix";
+function q(value) {
+  return JSON.stringify(value);
+}
+function resolvePath(path, cwd) {
+  return cwd && !isAbsolute(path) ? join(cwd, path) : path;
+}
+async function readFile(sandbox, path, opts) {
+  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: 30000 });
+  return stdout;
+}
+async function readRawFile(sandbox, path, cwd) {
+  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: 30000 });
+  return stdout;
+}
+var readTool = {
+  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 })
+};
+var writeTool = {
+  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}`;
+  }
+};
+var editTool = {
+  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"}`;
+  }
+};
+var bashTool = {
+  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(3600000).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 ?? 120000
+    });
+    if (result.exitCode !== 0)
+      throw new Error(`Command failed with exit code ${result.exitCode}${result.stdout ? `
+${result.stdout}` : ""}`);
+    return result.stdout;
+  }
+};
+var codingTools = [readTool, writeTool, editTool, bashTool];
+// src/processors/runner.ts
+async function runProcessorChain(processors, selectHook, initial, ctx) {
+  let current = initial;
+  for (const p of processors) {
+    const fn = selectHook(p);
+    if (!fn)
+      continue;
+    const verdict = await fn.call(p, current, ctx);
+    if (verdict.kind !== "continue")
+      return verdict;
+    current = verdict.value;
+  }
+  return { kind: "continue", value: current };
+}
+
+// src/request-context/request-context.ts
+var AC_RESERVED_PREFIX = "ac__";
+var AC_TEAM_ID = "ac__teamId";
+var AC_RUN_ID = "ac__runId";
+var AC_WORKFLOW_ID = "ac__workflowId";
+var AC_FACTORY_ID = "ac__factoryId";
+var AC_API_KEY_SCOPES = "ac__apiKeyScopes";
+var AC_PARENT_RUN_ID = "ac__parentRunId";
+var AC_ABORT_SIGNAL = "ac__abortSignal";
+var RESERVED_KEYS = new Set([
+  AC_TEAM_ID,
+  AC_RUN_ID,
+  AC_WORKFLOW_ID,
+  AC_FACTORY_ID,
+  AC_API_KEY_SCOPES,
+  AC_PARENT_RUN_ID,
+  AC_ABORT_SIGNAL
+]);
+var SERIALISABLE_RESERVED_KEYS = new Set([
+  AC_TEAM_ID,
+  AC_RUN_ID,
+  AC_WORKFLOW_ID,
+  AC_FACTORY_ID,
+  AC_API_KEY_SCOPES,
+  AC_PARENT_RUN_ID
+]);
+
+class ReservedKeyError extends Error {
+  key;
+  constructor(key) {
+    super(`request-context: "${key}" is reserved and cannot be mutated downstream`);
+    this.name = "ReservedKeyError";
+    this.key = key;
+  }
+}
+
+class NonSerialisableValueError extends Error {
+  constructor(key, cause) {
+    super(`request-context: value for "${key}" is not JSON-serialisable`, { cause });
+    this.name = "NonSerialisableValueError";
+  }
+}
+function assertJsonSerialisable(key, value, seen = new WeakSet) {
+  if (value === null)
+    return;
+  const type = typeof value;
+  if (type === "string" || type === "boolean")
+    return;
+  if (type === "number") {
+    if (Number.isFinite(value))
+      return;
+    throw new NonSerialisableValueError(key, new TypeError("non-finite numbers are not JSON-serialisable"));
+  }
+  if (type !== "object") {
+    throw new NonSerialisableValueError(key, new TypeError(`${type} is not JSON-serialisable`));
+  }
+  const objectValue = value;
+  if (seen.has(objectValue)) {
+    throw new NonSerialisableValueError(key, new TypeError("cyclic values are not JSON-serialisable"));
+  }
+  seen.add(objectValue);
+  if (Array.isArray(value)) {
+    for (const item of value)
+      assertJsonSerialisable(key, item, seen);
+    return;
+  }
+  if (Object.getPrototypeOf(objectValue) !== Object.prototype) {
+    throw new NonSerialisableValueError(key, new TypeError("only plain objects are JSON-serialisable"));
+  }
+  for (const item of Object.values(objectValue))
+    assertJsonSerialisable(key, item, seen);
+}
+
+class RequestContext {
+  reserved;
+  user;
+  constructor(reserved, user) {
+    this.reserved = Object.freeze({
+      ...reserved,
+      apiKeyScopes: Object.freeze([...reserved.apiKeyScopes])
+    });
+    this.user = user;
+  }
+  static fromReserved(reserved) {
+    return new RequestContext(reserved, new Map);
+  }
+  static deserialise(wire) {
+    const ctx = new RequestContext({ ...wire.reserved, abortSignal: undefined }, new Map(Object.entries(wire.user)));
+    return ctx;
+  }
+  withAbortSignal(signal) {
+    return new RequestContext({ ...this.reserved, abortSignal: signal }, new Map(this.user));
+  }
+  get teamId() {
+    return this.reserved.teamId;
+  }
+  get runId() {
+    return this.reserved.runId;
+  }
+  get workflowId() {
+    return this.reserved.workflowId;
+  }
+  get factoryId() {
+    return this.reserved.factoryId;
+  }
+  get apiKeyScopes() {
+    return this.reserved.apiKeyScopes;
+  }
+  get parentRunId() {
+    return this.reserved.parentRunId;
+  }
+  get abortSignal() {
+    return this.reserved.abortSignal;
+  }
+  hasScope(scope) {
+    return this.reserved.apiKeyScopes.includes(scope);
+  }
+  set(key, value) {
+    if (RESERVED_KEYS.has(key) || key.startsWith(AC_RESERVED_PREFIX)) {
+      throw new ReservedKeyError(key);
+    }
+    assertJsonSerialisable(key, value);
+    this.user.set(key, value);
+  }
+  get(key) {
+    return this.user.get(key);
+  }
+  has(key) {
+    return this.user.has(key);
+  }
+  delete(key) {
+    if (RESERVED_KEYS.has(key) || key.startsWith(AC_RESERVED_PREFIX)) {
+      throw new ReservedKeyError(key);
+    }
+    return this.user.delete(key);
+  }
+  entries() {
+    return this.user.entries();
+  }
+  serialise() {
+    return {
+      reserved: {
+        teamId: this.reserved.teamId,
+        runId: this.reserved.runId,
+        workflowId: this.reserved.workflowId,
+        factoryId: this.reserved.factoryId,
+        apiKeyScopes: [...this.reserved.apiKeyScopes],
+        parentRunId: this.reserved.parentRunId
+      },
+      user: Object.fromEntries(this.user)
+    };
+  }
+  forChild(opts) {
+    return RequestContext.fromReserved({
+      teamId: this.reserved.teamId,
+      runId: opts.runId,
+      workflowId: opts.workflowId,
+      factoryId: this.reserved.factoryId,
+      apiKeyScopes: this.reserved.apiKeyScopes,
+      parentRunId: this.reserved.runId
+    });
+  }
+}
+
+// src/utils/errors.ts
+function formatError(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/runtimes/vercel.ts
+function now() {
+  return new Date().toISOString();
+}
+function serialiseOutput(value) {
+  return typeof value === "string" ? value : JSON.stringify(value ?? "");
+}
+function toAgentMessages(part) {
+  const ts = now();
+  switch (part.type) {
+    case "text-delta":
+    case "text":
+      return [{ type: "text", text: String(part.text ?? ""), timestamp: ts }];
+    case "reasoning-delta":
+    case "reasoning":
+      return [{ type: "thinking", text: String(part.text ?? ""), timestamp: ts }];
+    case "tool-call":
+      return [{
+        type: "tool_use",
+        toolName: String(part.toolName ?? ""),
+        toolInput: part.input ?? {},
+        toolUseId: String(part.toolCallId ?? ""),
+        timestamp: ts
+      }];
+    case "tool-result":
+      return [{
+        type: "tool_result",
+        toolUseId: String(part.toolCallId ?? ""),
+        output: serialiseOutput(part.output),
+        isError: false,
+        timestamp: ts
+      }];
+    case "tool-error":
+      return [{
+        type: "tool_result",
+        toolUseId: String(part.toolCallId ?? ""),
+        output: formatError(part.error),
+        isError: true,
+        timestamp: ts
+      }];
+    case "error":
+      return [{ type: "error", text: formatError(part.error), timestamp: ts }];
+    default:
+      return [];
+  }
+}
+
+class VercelRunner {
+  sandbox;
+  options;
+  config;
+  supportsToolCallProcessor = true;
+  tools;
+  messages = [];
+  constructor(sandbox, options, config) {
+    this.sandbox = sandbox;
+    this.options = options;
+    this.config = config;
+    this.tools = config.tools ?? codingTools;
+  }
+  async gateToolCall(call, ctx) {
+    const verdict = await runProcessorChain(this.options.processors ?? [], (p) => p.processToolCall, call, ctx);
+    if (verdict.kind === "continue")
+      return { kind: "allow", call: verdict.value };
+    return verdict;
+  }
+  buildTools(iteration, signal) {
+    const set = {};
+    for (const t of this.tools) {
+      if (this.options.allowedTools && !this.options.allowedTools.includes(t.name))
+        continue;
+      set[t.name] = tool({
+        description: t.description,
+        inputSchema: t.inputSchema,
+        execute: async (input, execOpts) => {
+          const call = {
+            toolName: t.name,
+            toolInput: input,
+            toolUseId: execOpts.toolCallId ?? `${t.name}-${Date.now()}`
+          };
+          const requestContext = this.options.requestContext ?? RequestContext.fromReserved({
+            teamId: "",
+            runId: "",
+            workflowId: "",
+            factoryId: null,
+            apiKeyScopes: [],
+            parentRunId: null
+          });
+          const gate = await this.gateToolCall(call, {
+            requestContext,
+            abortSignal: execOpts.abortSignal ?? signal ?? new AbortController().signal,
+            retryCount: 0,
+            agentId: this.options.agentId ?? "agent",
+            iteration
+          });
+          if (gate.kind === "deny")
+            return gate.reason;
+          if (gate.kind === "abort")
+            throw new Error(gate.reason);
+          return t.execute(gate.call.toolInput, {
+            sandbox: this.sandbox,
+            cwd: this.options.cwd,
+            abortSignal: execOpts.abortSignal ?? signal
+          });
+        }
+      });
+    }
+    return set;
+  }
+  async* sendMessage(opts) {
+    const sessionId = opts.sessionId ?? `vercel-${Date.now()}`;
+    yield { type: "init", sessionId, timestamp: now() };
+    const inputMessages = [...this.messages, { role: "user", content: opts.prompt }];
+    const result = streamText({
+      model: this.config.model,
+      ...this.config.system ? { system: this.config.system } : {},
+      messages: inputMessages,
+      tools: this.buildTools(opts.iteration ?? 1, opts.signal),
+      stopWhen: stepCountIs(this.options.maxTurns ?? 40),
+      abortSignal: opts.signal
+    });
+    try {
+      for await (const part of result.fullStream) {
+        for (const msg of toAgentMessages(part))
+          yield msg;
+      }
+      const response = await result.response;
+      const responseMessages = response.messages;
+      if (responseMessages) {
+        this.messages.length = 0;
+        this.messages.push(...responseMessages);
+      }
+      let usage;
+      try {
+        usage = await result.usage;
+      } catch {
+        usage = undefined;
+      }
+      if (usage) {
+        yield {
+          type: "usage",
+          inputTokens: usage.inputTokens ?? 0,
+          outputTokens: usage.outputTokens ?? 0,
+          cacheReadTokens: usage.inputTokenDetails?.cacheReadTokens ?? 0,
+          cacheCreationTokens: usage.inputTokenDetails?.cacheWriteTokens ?? 0,
+          durationMs: 0,
+          numTurns: opts.iteration ?? 1,
+          timestamp: now()
+        };
+      }
+    } catch (err) {
+      yield { type: "error", text: formatError(err), timestamp: now() };
+      return;
+    }
+    yield { type: "done", sessionId, timestamp: now() };
+  }
+}
+function createVercelRuntime(config) {
+  return defineRuntime({
+    create: (sandbox, opts) => new VercelRunner(sandbox, opts, config)
+  });
+}
+// src/types/workflow.ts
+import { z as z2 } from "zod";
+
+// src/workflow-steps/types.ts
+var WORKFLOW_BRAND = Symbol.for("@agent-compose/sdk.Workflow");
+
+// src/types/workflow-metadata.ts
+function extractMetadata(source) {
+  const out = {};
+  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);
+}
+function freezeMetadataValue(value) {
+  if (value === null || typeof value !== "object")
+    return value;
+  if (Array.isArray(value)) {
+    for (const v of value)
+      freezeMetadataValue(v);
+    return Object.freeze(value);
+  }
+  for (const v of Object.values(value)) {
+    freezeMetadataValue(v);
+  }
+  return Object.freeze(value);
+}
+
+// src/workflow-steps/workflow.ts
+function createStepWorkflow(opts) {
+  if (!opts.id)
+    throw new Error("defineWorkflow: 'id' is required for step-based workflows");
+  const build = (steps) => ({
+    step(step) {
+      return build([...steps, step]);
+    },
+    build() {
+      if (steps.length === 0) {
+        throw new Error(`defineWorkflow("${opts.id}").build: no steps registered — add at least one with .step(step)`);
+      }
+      const finalStep = steps[steps.length - 1];
+      if (finalStep.output !== opts.output) {
+        throw new Error(`defineWorkflow("${opts.id}").build: final step "${finalStep.name}" output schema is not the same Zod schema instance as the workflow's declared output schema. ` + `Pass the same schema reference to both the final step and defineWorkflow.`);
+      }
+      const workflow = {
+        id: opts.id,
+        input: opts.input,
+        output: opts.output,
+        steps: Object.freeze([...steps]),
+        metadata: extractMetadata(opts)
+      };
+      Object.defineProperty(workflow, WORKFLOW_BRAND, { value: true, enumerable: false });
+      return Object.freeze(workflow);
+    }
+  });
+  return build([]);
+}
+function isWorkflow(value) {
+  return typeof value === "object" && value !== null && value[WORKFLOW_BRAND] === true;
+}
+
+// src/types/workflow.ts
+function compileRunForm(def, metadata) {
+  const unknownSchema = z2.unknown();
+  const step = {
+    name: "run",
+    input: unknownSchema,
+    output: unknownSchema,
+    run: async (stepCtx) => {
+      const workflowCtx = {
+        input: stepCtx.input,
+        run: stepCtx.run,
+        requestContext: stepCtx.requestContext,
+        invokeChild: stepCtx.invokeChild,
+        setMetadata: stepCtx.setMetadata,
+        step: stepCtx.step,
+        agentEvents: stepCtx.agentEvents,
+        processors: metadata.processors ?? []
+      };
+      const sandbox = stepCtx.sandbox;
+      if (!sandbox)
+        throw new Error("legacy run-form workflow requires a sandbox in StepContext");
+      return def.run(workflowCtx, sandbox);
+    }
+  };
+  const workflow = {
+    id: "@run-form",
+    input: unknownSchema,
+    output: unknownSchema,
+    steps: Object.freeze([step]),
+    metadata
+  };
+  Object.defineProperty(workflow, WORKFLOW_BRAND, { value: true, enumerable: false });
+  return Object.freeze(workflow);
+}
+function defineWorkflow(def) {
+  if ("run" in def)
+    return compileRunForm(def, extractMetadata(def));
+  return createStepWorkflow(def);
+}
+// src/types/sandbox-environment.ts
+function defineSandboxEnvironment(env) {
+  if (typeof env.setup !== "function") {
+    throw new Error(`defineSandboxEnvironment(${env.name}): 'setup' must be a function`);
+  }
+  return defineWorkflow({
+    saveSnapshot: env.saveSnapshot ?? true,
+    run: async (_ctx, sandbox) => env.setup(sandbox)
+  });
+}
+// src/processors/processor.ts
+var Verdict = {
+  continue: (value) => ({ kind: "continue", value }),
+  deny: (reason) => ({ kind: "deny", reason }),
+  abort: (reason) => ({ kind: "abort", reason })
+};
+// src/processors/builtins.ts
+function denyTools(names) {
+  const banned = new Set(names);
+  return {
+    name: "denyTools",
+    processToolCall: (call) => banned.has(call.toolName) ? Verdict.deny(`tool "${call.toolName}" is denied by policy`) : Verdict.continue(call)
+  };
+}
+function requireScope(required) {
+  return {
+    name: "requireScope",
+    processInput: (prompt, ctx) => {
+      const missing = required.filter((s) => !ctx.requestContext.hasScope(s));
+      return missing.length === 0 ? Verdict.continue(prompt) : Verdict.abort(`API key is missing required scopes: ${missing.join(", ")}`);
+    }
+  };
+}
+function redactPattern(pattern, replacement = "[REDACTED]") {
+  return {
+    name: "redactPattern",
+    processOutput: (message) => {
+      if (message.type === "text" || message.type === "thinking") {
+        const redacted = message.text.replace(pattern, replacement);
+        if (redacted !== message.text) {
+          return Verdict.continue({ ...message, text: redacted });
+        }
+      }
+      return Verdict.continue(message);
+    }
+  };
+}
+// src/client.ts
+import { ofetch } from "ofetch";
+
+// src/errors.ts
+class AgentComposeError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "AgentComposeError";
+  }
+}
+
+// src/sse.ts
+async function* parseSseStream(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder;
+  let buffer = "";
+  let event = "";
+  let seq = 0;
+  let dataLines = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split(`
+`);
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line.startsWith("id:")) {
+          seq = Number(line.slice(3).trim());
+          continue;
+        }
+        if (line.startsWith("event:")) {
+          event = line.slice(6).trim();
+          continue;
+        }
+        if (line.startsWith("data:")) {
+          dataLines.push(line.slice(5).trim());
+          continue;
+        }
+        if (line === "" && dataLines.length > 0) {
+          try {
+            const data = JSON.parse(dataLines.join(`
+`));
+            yield { id: seq, event, data };
+          } catch {}
+          event = "";
+          seq = 0;
+          dataLines = [];
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/client.ts
+var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var DEFAULT_FACTORY = "default";
+function detectAmbientParentRunId() {
+  const envRunId = typeof process !== "undefined" ? process.env?.RUN_ID : undefined;
+  return envRunId && UUID_REGEX.test(envRunId) ? envRunId : null;
+}
+function templatePath(factorySlug, ...rest) {
+  const tail = rest.length > 0 ? "/" + rest.map(encodeURIComponent).join("/") : "";
+  return `/api/v1/factories/${encodeURIComponent(factorySlug)}/templates${tail}`;
+}
+
+class AgentComposeClient {
+  fetch;
+  baseUrl;
+  apiKey;
+  constructor(baseUrl, apiKey) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.apiKey = apiKey;
+    this.fetch = ofetch.create({
+      baseURL: this.baseUrl,
+      headers: { Authorization: `Bearer ${apiKey}` },
+      async onResponseError({ response }) {
+        const body = response._data;
+        throw new AgentComposeError(response.status, body?.error ?? response.statusText);
+      }
+    });
+  }
+  register(payload) {
+    const { factorySlug = DEFAULT_FACTORY, ...body } = payload;
+    return this.fetch(templatePath(factorySlug), { method: "POST", body });
+  }
+  invoke(name, input, opts) {
+    const parentRunId = opts?.parentRunId === undefined ? detectAmbientParentRunId() : opts.parentRunId;
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(templatePath(factorySlug, name, "invoke"), {
+      method: "POST",
+      body: {
+        input,
+        ...opts?.snapshot !== undefined ? { snapshot: opts.snapshot } : {},
+        ...opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {},
+        ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
+        ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {},
+        ...parentRunId ? { parentRunId } : {},
+        ...opts?.agentId ? { agentId: opts.agentId } : {}
+      }
+    });
+  }
+  async invokeAndWait(name, input, opts) {
+    const timeoutMs = opts?.timeoutMs ?? 30 * 60 * 1000;
+    const pollMs = opts?.pollIntervalMs ?? 1000;
+    const { id: runId } = await this.invoke(name, input, opts);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const status = await this.getStatus(runId);
+      if (status.status === "success" || status.status === "failed" || status.status === "abandoned") {
+        return status;
+      }
+      await new Promise((r) => setTimeout(r, pollMs));
+    }
+    throw new AgentComposeError(504, `invokeAndWait: run ${runId} did not settle within ${timeoutMs}ms`);
+  }
+  async listSnapshots(opts) {
+    const q2 = new URLSearchParams;
+    if (opts?.workflow)
+      q2.set("workflow", opts.workflow);
+    if (opts?.limit != null)
+      q2.set("limit", String(opts.limit));
+    const body = await this.fetch(`/api/v1/snapshots${q2.toString() ? `?${q2}` : ""}`);
+    return body.data;
+  }
+  deleteSnapshot(runId) {
+    return this.fetch(`/api/v1/workflows/${runId}/snapshot`, { method: "DELETE" });
+  }
+  getStatus(runId) {
+    return this.fetch(`/api/v1/workflows/${runId}/status`);
+  }
+  getRun(runId) {
+    return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}`);
+  }
+  async getRunTimeline(runId, opts) {
+    const q2 = new URLSearchParams;
+    if (opts?.limit !== undefined)
+      q2.set("limit", String(opts.limit));
+    if (opts?.offset !== undefined)
+      q2.set("offset", String(opts.offset));
+    const body = await this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/timeline${q2.toString() ? `?${q2}` : ""}`);
+    return body.events;
+  }
+  async reportEvent(runId, input) {
+    const body = {
+      ...input,
+      ...input.timestamp instanceof Date ? { timestamp: input.timestamp.toISOString() } : {}
+    };
+    const response = await this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/events`, {
+      method: "POST",
+      body
+    });
+    return response.event;
+  }
+  async listRunEvents(runId) {
+    const body = await this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/events`);
+    return body.events;
+  }
+  async listFactoryEvents(opts) {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const q2 = new URLSearchParams;
+    if (opts?.limit != null)
+      q2.set("limit", String(opts.limit));
+    if (opts?.name)
+      q2.set("name", opts.name);
+    if (opts?.from)
+      q2.set("from", opts.from);
+    if (opts?.before)
+      q2.set("before", opts.before);
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/events${q2.toString() ? `?${q2}` : ""}`);
+  }
+  async listRunLogs(runId, opts) {
+    const q2 = new URLSearchParams;
+    if (opts?.afterId !== undefined)
+      q2.set("afterId", String(opts.afterId));
+    if (opts?.limit !== undefined)
+      q2.set("limit", String(opts.limit));
+    if (opts?.direction !== undefined)
+      q2.set("direction", opts.direction);
+    const body = await this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/logs${q2.toString() ? `?${q2}` : ""}`);
+    return body.logs;
+  }
+  async listTemplates(opts) {
+    const path = opts?.factorySlug ? templatePath(opts.factorySlug) : "/api/v1/templates";
+    const body = await this.fetch(path);
+    return body.templates;
+  }
+  async listFactories() {
+    const body = await this.fetch("/api/v1/factories");
+    return body.factories;
+  }
+  createFactory(payload) {
+    return this.fetch("/api/v1/factories", { method: "POST", body: payload });
+  }
+  getFactory(slug) {
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}`);
+  }
+  updateFactory(slug, updates) {
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}`, { method: "PATCH", body: updates });
+  }
+  deleteFactory(slug) {
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}`, { method: "DELETE" });
+  }
+  setSecret(workflowName, key, value, opts) {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(templatePath(factorySlug, workflowName, "secrets"), {
+      method: "POST",
+      body: { key, value }
+    });
+  }
+  async listSecrets(workflowName, opts) {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const body = await this.fetch(templatePath(factorySlug, workflowName, "secrets"));
+    return body.secrets.map((s) => ({ key: s.secretKey, createdAt: s.createdAt, updatedAt: s.updatedAt }));
+  }
+  deleteSecret(workflowName, key, opts) {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(templatePath(factorySlug, workflowName, "secrets", key), { method: "DELETE" });
+  }
+  createApiKey(input) {
+    return this.fetch("/api-keys", { method: "POST", body: input });
+  }
+  async listApiKeys() {
+    const body = await this.fetch("/api-keys");
+    return body.data;
+  }
+  getUsage(from, to) {
+    const qs = `?from=${encodeURIComponent(from.toISOString())}&to=${encodeURIComponent(to.toISOString())}`;
+    return this.fetch(`/api/v1/usage${qs}`);
+  }
+  cancelRun(runId) {
+    return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/cancel`, { method: "POST" });
+  }
+  async* streamRunLogs(runId, opts) {
+    const headers = { Authorization: `Bearer ${this.apiKey}` };
+    if (opts?.lastEventId && opts.lastEventId > 0) {
+      headers["Last-Event-ID"] = String(opts.lastEventId);
+    }
+    const res = await fetch(`${this.baseUrl}/api/v1/workflows/${encodeURIComponent(runId)}/stream`, {
+      headers,
+      ...opts?.signal ? { signal: opts.signal } : {}
+    });
+    if (!res.ok || !res.body) {
+      let message = res.statusText;
+      try {
+        const body = await res.json();
+        if (body.error)
+          message = body.error;
+      } catch {}
+      throw new AgentComposeError(res.status, message);
+    }
+    for await (const ev of parseSseStream(res.body)) {
+      yield ev.data;
+    }
+  }
+}
+// src/utils/discovery.ts
+function discoverRuntimeName(source) {
+  return source.match(/runtime:\s*["']([^"']+)["']/)?.[1] ?? null;
+}
+// src/utils/bundler.ts
+import { createHash } from "node:crypto";
+import { parse as babelParse } from "@babel/parser";
+
+// src/utils/source-loader.ts
+import { dirname } from "path";
+import { writeFile, rm, mkdir } from "node:fs/promises";
+var TMP_DIR = process.env.TMP_DIR ?? "/tmp/agent-compose";
+var LATEST_VERSION = "$LATEST";
+async function importSourceModule(source, tmpPath) {
+  await mkdir(dirname(tmpPath), { recursive: true });
+  await writeFile(tmpPath, source, "utf8");
+  const mod = await import(tmpPath);
+  const cleanup = () => rm(tmpPath, { force: true });
+  return { mod, cleanup };
+}
+
+// src/types/workflow-plan.ts
+function workflowPlan(steps) {
+  return { steps };
+}
+
+// src/utils/bundler.ts
+var BUNDLER_VERSION = 1;
+
+class WorkflowSourceValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WorkflowSourceValidationError";
+  }
+}
+async function bundle(path, label) {
+  const bun = globalThis;
+  if (!bun.Bun?.build)
+    throw new Error("bundleWorkflow requires the Bun runtime (Bun.build)");
+  const result = await bun.Bun.build({ entrypoints: [path], format: "esm", target: "node" });
+  if (!result.success) {
+    throw new Error(`Failed to bundle ${label}:
+${result.logs.map((l) => l.message).join(`
+`)}`);
+  }
+  return result.outputs[0].text();
+}
+async function extractFromBundle(source, label, pick) {
+  const tmpPath = `/tmp/agentc-${label}-${Date.now()}-${Math.random().toString(36).slice(2)}.js`;
+  try {
+    const loaded = await importSourceModule(source, tmpPath);
+    try {
+      return pick(loaded.mod.default);
+    } finally {
+      await loaded.cleanup();
+    }
+  } catch {
+    return;
+  }
+}
+var DEFINE_WORKFLOW_CALLEE = /^defineWorkflow\d*$/;
+function isDefineWorkflowCall(node) {
+  if (node.callee.type === "Identifier") {
+    return DEFINE_WORKFLOW_CALLEE.test(node.callee.name);
+  }
+  if (node.callee.type === "MemberExpression" && node.callee.object.type === "CallExpression") {
+    return isDefineWorkflowCall(node.callee.object);
+  }
+  return false;
+}
+function assertDefaultExportIsDefineWorkflow(source, label) {
+  let ast;
+  try {
+    ast = babelParse(source, {
+      sourceType: "module",
+      plugins: [],
+      errorRecovery: false
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new WorkflowSourceValidationError(`Bundled workflow ${label} failed to parse as JavaScript: ${msg}. ` + `If you registered raw .ts source, switch to \`agentc register <file.ts>\` so the source is bundled first.`);
+  }
+  const defaultExpr = findDefaultExportExpression(ast.program.body);
+  if (!defaultExpr) {
+    throw new WorkflowSourceValidationError(`Bundled workflow ${label} has no default export. ` + `Use \`export default defineWorkflow({ run: ... })\`.`);
+  }
+  if (defaultExpr.type !== "CallExpression" || !isDefineWorkflowCall(defaultExpr)) {
+    throw new WorkflowSourceValidationError(`Bundled workflow ${label} default export must be a \`defineWorkflow({...})\` call ` + `(or a \`defineWorkflow(...).step(...).build()\` chain). ` + `Got: ${defaultExpr.type}. Wrap your workflow with \`defineWorkflow\` from "@agent-compose/sdk".`);
+  }
+}
+function findDefaultExportExpression(body) {
+  const defaultDecl = body.find((node) => node.type === "ExportDefaultDeclaration");
+  if (defaultDecl) {
+    return defaultDecl.declaration;
+  }
+  const exportNamed = body.find((node) => node.type === "ExportNamedDeclaration" && node.specifiers.some((spec2) => spec2.type === "ExportSpecifier" && spec2.exported.type === "Identifier" && spec2.exported.name === "default"));
+  if (!exportNamed || exportNamed.type !== "ExportNamedDeclaration")
+    return null;
+  const spec = exportNamed.specifiers.find((s) => s.type === "ExportSpecifier" && s.exported.type === "Identifier" && s.exported.name === "default");
+  if (!spec || spec.type !== "ExportSpecifier" || spec.local.type !== "Identifier")
+    return null;
+  const localName = spec.local.name;
+  for (const stmt of body) {
+    if (stmt.type !== "VariableDeclaration")
+      continue;
+    for (const decl of stmt.declarations) {
+      if (decl.id.type === "Identifier" && decl.id.name === localName && decl.init && decl.init.type !== "TSSatisfiesExpression") {
+        return decl.init;
+      }
+    }
+  }
+  return null;
+}
+function sha256(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+async function bundleWorkflow(workflowPath, overrides) {
+  const label = `"${workflowPath}"`;
+  const source = await bundle(workflowPath, `workflow ${label}`);
+  assertDefaultExportIsDefineWorkflow(source, label);
+  const workflow = await extractFromBundle(source, "workflow", (wf) => isWorkflow(wf) ? wf : undefined);
+  if (!workflow) {
+    throw new WorkflowSourceValidationError(`Bundled workflow ${label} default export is not a Workflow. ` + `Wrap your workflow with \`defineWorkflow\` from "@agent-compose/sdk" — ` + `raw \`export default async function\` is no longer supported.`);
+  }
+  const { metadata } = workflow;
+  const plan = workflowPlan(workflow.steps.map((step, index) => ({ index, name: step.name })));
+  const manifest = {
+    definitionBrand: true,
+    sourceHash: sha256(source),
+    bundlerVersion: BUNDLER_VERSION
+  };
+  return {
+    source,
+    manifest,
+    workflowPlan: plan,
+    networkPolicy: overrides?.networkPolicy ?? metadata.networkPolicy,
+    placeholders: overrides?.placeholders ?? metadata.placeholders,
+    ...metadata.snapshot !== undefined ? { snapshot: metadata.snapshot } : {},
+    ...metadata.saveSnapshot !== undefined ? { saveSnapshot: metadata.saveSnapshot } : {},
+    ...metadata.memory !== undefined ? { memory: metadata.memory } : {}
+  };
+}
+// src/utils/schemas.ts
+import { z as z3 } from "zod";
+var AgentStatusSchema = z3.object({
+  summary: z3.string(),
+  completed: z3.array(z3.string()),
+  blockers: z3.array(z3.string()),
+  exit_signal: z3.boolean()
+});
+// src/runtimes/claude.ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+// src/agent/agent-loop.ts
+import { z as z5 } from "zod";
+
+// src/agent/protocol.ts
+import { z as z4 } from "zod";
+var AgentMessageSchema = z4.object({
+  type: z4.enum(["init", "text", "thinking", "tool_use", "tool_result", "done", "error", "usage"]),
+  timestamp: z4.string()
+}).passthrough();
+function parseAgentResponse(text) {
+  const match = text.match(/<response>([\s\S]*?)<\/response>/);
+  if (!match)
+    return null;
+  try {
+    return JSON.parse(match[1].trim());
+  } catch {
+    return null;
+  }
+}
+
+// src/agent/agent-loop.ts
+import { randomUUID } from "node:crypto";
+var DEFAULT_CLAUDE_MODEL = "claude-opus-4-7";
+var SAME_BLOCKER_ITERATIONS = 3;
+var STALL_ITERATIONS = 3;
+var MESSAGE_PREVIEW_CHARS = 400;
+function parseAgentStatus(text) {
+  const match = text.match(/<status>([\s\S]*?)<\/status>/);
+  if (!match)
+    return null;
+  try {
+    const result = AgentStatusSchema.safeParse(JSON.parse(match[1].trim()));
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}
+var DEFAULT_ALLOWED_TOOLS = ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "WebFetch"];
+function truncate(value) {
+  return value.length > MESSAGE_PREVIEW_CHARS ? `${value.slice(0, MESSAGE_PREVIEW_CHARS)}…` : value;
+}
+function preview(value) {
+  try {
+    return truncate(JSON.stringify(value));
+  } catch {
+    return truncate(String(value));
+  }
+}
+function summarizeAgentMessage(msg) {
+  switch (msg.type) {
+    case "init":
+      return { type: "init", sessionId: msg.sessionId };
+    case "text":
+      return { type: "text", text: msg.text };
+    case "thinking":
+      return { type: "thinking", text: msg.text };
+    case "tool_use":
+      return { type: "tool_use", toolName: msg.toolName, toolUseId: msg.toolUseId, toolInputPreview: preview(msg.toolInput) };
+    case "tool_result":
+      return { type: "tool_result", toolUseId: msg.toolUseId, output: truncate(msg.output), isError: msg.isError };
+    case "usage":
+      return {
+        type: "usage",
+        inputTokens: msg.inputTokens,
+        outputTokens: msg.outputTokens,
+        cacheReadTokens: msg.cacheReadTokens,
+        cacheCreationTokens: msg.cacheCreationTokens,
+        durationMs: msg.durationMs,
+        numTurns: msg.numTurns
+      };
+    case "done":
+      return { type: "done", sessionId: msg.sessionId };
+    case "error":
+      return { type: "error", text: truncate(msg.text) };
+  }
+}
+async function agentLoop(opts) {
+  const agentId = opts.agentId ?? randomUUID();
+  const label = opts.label ?? "agent";
+  const logLabel = opts.label ?? "[Agent Loop]";
+  const startedAt = Date.now();
+  const turnsPerIteration = opts.turnsPerIteration ?? 40;
+  const maxIterations = opts.maxIterations ?? 8;
+  const processors = opts.processors ?? [];
+  const requestContext = opts.requestContext ?? RequestContext.fromReserved({
+    teamId: "",
+    runId: "",
+    workflowId: "",
+    factoryId: null,
+    apiKeyScopes: [],
+    parentRunId: null
+  });
+  const loopAbort = new AbortController;
+  const buildProcCtx = (iteration) => ({
+    requestContext,
+    abortSignal: loopAbort.signal,
+    retryCount: 0,
+    agentId,
+    iteration
+  });
+  if (!opts.runtime)
+    throw new Error("agentLoop: opts.runtime is required");
+  const client = opts.runtime({
+    maxTurns: turnsPerIteration,
+    allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
+    label: logLabel,
+    cwd: opts.cwd,
+    processors,
+    requestContext,
+    agentId,
+    ...opts.responseSchema ? { outputFormat: { type: "json_schema", schema: z5.toJSONSchema(opts.responseSchema) } } : {}
+  });
+  if (processors.some((p) => p.processToolCall) && !client.supportsToolCallProcessor) {
+    process.stderr.write(`${logLabel} processToolCall registered but runtime does not support pre-tool-use gating — hook is dormant
+`);
+  }
+  let lastSessionId = "";
+  let lastStatus = null;
+  let iterationsWithoutStatus = 0;
+  let blockerStreak = null;
+  let completedIterations = 0;
+  let lastResponseText = "";
+  let lastResponseValidationError = "";
+  opts.onAgentLifecycleEvent?.({ event: "agent.spawned", at: startedAt, agentId, label, allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS });
+  try {
+    for (let iteration = 0;iteration < maxIterations; iteration++) {
+      const procCtx = buildProcCtx(iteration + 1);
+      const initialPrompt = opts.buildPrompt(lastStatus, iteration);
+      const inputVerdict = await runProcessorChain(processors, (p) => p.processInput, initialPrompt, procCtx);
+      if (inputVerdict.kind !== "continue") {
+        loopAbort.abort();
+        throw new Error(`${logLabel} input ${inputVerdict.kind === "deny" ? "rejected" : "aborted"}: ${inputVerdict.reason}`);
+      }
+      const prompt = inputVerdict.value;
+      process.stdout.write(`${logLabel} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration} turns
+`);
+      let responseText = "";
+      for await (const rawMsg of client.sendMessage({ prompt, sessionId: iteration > 0 ? lastSessionId : undefined, iteration: iteration + 1 })) {
+        const outputVerdict = await runProcessorChain(processors, (p) => p.processOutput, rawMsg, procCtx);
+        if (outputVerdict.kind === "abort") {
+          loopAbort.abort();
+          throw new Error(`${logLabel} output aborted: ${outputVerdict.reason}`);
+        }
+        if (outputVerdict.kind === "deny") {
+          process.stderr.write(`${logLabel} message dropped by processor: ${outputVerdict.reason}
+`);
+          continue;
+        }
+        const msg = outputVerdict.value;
+        opts.onAgentEvent?.(iteration, msg);
+        opts.onAgentLifecycleEvent?.({ event: "agent.message", at: Date.now(), agentId, label, iteration: iteration + 1, message: summarizeAgentMessage(msg) });
+        if (msg.type === "init")
+          lastSessionId = msg.sessionId;
+        if (msg.type === "text")
+          responseText += msg.text;
+        if (msg.type === "error")
+          throw new Error(`Agent error: ${msg.text}`);
+      }
+      lastResponseText = responseText;
+      let status = parseAgentStatus(responseText);
+      const rawResponse = opts.responseSchema ? parseAgentResponse(responseText) ?? parseRawJsonResponse(responseText) : null;
+      if (opts.responseSchema && rawResponse !== null) {
+        const parsed = opts.responseSchema.safeParse(rawResponse);
+        if (parsed.success) {
+          const successStatus = status ?? { summary: "structured response completed", completed: [], blockers: [], exit_signal: true };
+          process.stdout.write(`${logLabel} structured response validated after ${iteration + 1}/${maxIterations} iterations
+`);
+          opts.onAgentLifecycleEvent?.({ event: "agent.settled", at: Date.now(), agentId, label, outcome: "success", iterations: iteration + 1, durationMs: Date.now() - startedAt });
+          return { agentId, label, sessionId: lastSessionId, lastStatus: successStatus, iterations: iteration + 1, response: parsed.data };
+        }
+        lastResponseValidationError = parsed.error.message;
+      }
+      completedIterations = iteration + 1;
+      process.stdout.write(`${logLabel} iteration ${iteration + 1} status: exit_signal=${status?.exit_signal ?? "(no status)"} blockers=${JSON.stringify(status?.blockers ?? [])}
+`);
+      lastStatus = status ?? lastStatus;
+      opts.onIteration?.(iteration + 1, status);
+      opts.onAgentLifecycleEvent?.({ event: "agent.iteration", at: Date.now(), agentId, label, iteration: iteration + 1, status });
+      if (status?.exit_signal && (status.blockers?.length ?? 0) === 0) {
+        let response = status;
+        if (opts.responseSchema) {
+          if (rawResponse === null) {
+            process.stderr.write(`${logLabel} NO <response> BLOCK — response tail: ${responseText.slice(-400)}
+`);
+            status = { ...status, exit_signal: false, blockers: ["No <response> block found — emit a <response> block with the required JSON fields before setting exit_signal: true"] };
+            opts.onIteration?.(iteration + 1, status);
+            continue;
+          }
+          const parsed = opts.responseSchema.safeParse({ ...status, ...rawResponse });
+          if (!parsed.success) {
+            lastResponseValidationError = parsed.error.message;
+            process.stderr.write(`${logLabel} <response> SCHEMA FAILED: ${parsed.error.message}
+raw: ${JSON.stringify(rawResponse).slice(0, 400)}
+`);
+            status = { ...status, exit_signal: false, blockers: [`<response> schema validation failed: ${parsed.error.message}`] };
+            opts.onIteration?.(iteration + 1, status);
+            continue;
+          }
+          response = parsed.data;
+        }
+        process.stdout.write(`${logLabel} done after ${iteration + 1}/${maxIterations} iterations
+`);
+        opts.onAgentLifecycleEvent?.({ event: "agent.settled", at: Date.now(), agentId, label, outcome: "success", iterations: iteration + 1, durationMs: Date.now() - startedAt });
+        return { agentId, label, sessionId: lastSessionId, lastStatus: status, iterations: iteration + 1, response };
+      }
+      if (!status) {
+        if (++iterationsWithoutStatus >= STALL_ITERATIONS)
+          throw new Error(`${logLabel} stalled: no <status> block after ${iterationsWithoutStatus} iterations`);
+      } else {
+        iterationsWithoutStatus = 0;
+      }
+      if (status?.blockers?.length) {
+        const key = status.blockers.join("|");
+        if (blockerStreak !== null && blockerStreak.key === key) {
+          if (++blockerStreak.count >= SAME_BLOCKER_ITERATIONS)
+            throw new Error(`${logLabel} circuit break: same blocker repeated ${blockerStreak.count}x — "${status.blockers[0]}"`);
+        } else {
+          blockerStreak = { key, count: 1 };
+        }
+      } else {
+        blockerStreak = null;
+      }
+      if (iteration + 1 < maxIterations)
+        process.stdout.write(`${logLabel} continuing to iteration ${iteration + 2}/${maxIterations}
+`);
+    }
+    if (opts.responseSchema)
+      throw new Error(`${logLabel} did not produce a valid <response> after ${maxIterations} iterations${lastResponseValidationError ? `: ${lastResponseValidationError}` : ""}. Response tail: ${lastResponseText.slice(-600)}`);
+    process.stderr.write(`${logLabel} exhausted ${maxIterations} iterations, proceeding with available work
+`);
+    opts.onAgentLifecycleEvent?.({ event: "agent.settled", at: Date.now(), agentId, label, outcome: "success", iterations: maxIterations, durationMs: Date.now() - startedAt });
+    return { agentId, label, sessionId: lastSessionId, lastStatus, iterations: maxIterations };
+  } catch (err) {
+    opts.onAgentLifecycleEvent?.({ event: "agent.settled", at: Date.now(), agentId, label, outcome: "failed", iterations: completedIterations, durationMs: Date.now() - startedAt, failureReason: err instanceof Error ? err.message : String(err) });
+    throw err;
+  }
+}
+function parseRawJsonResponse(text) {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}"))
+    return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+// src/runtimes/claude.ts
+function now2() {
+  return new Date().toISOString();
+}
+function translateMessage(message) {
+  const ts = now2();
+  const msgs = [];
+  if (message.type === "system" && message.subtype === "init") {
+    msgs.push({ type: "init", sessionId: String(message.session_id ?? ""), timestamp: ts });
+    return msgs;
+  }
+  if (message.type === "assistant") {
+    const raw = message.message;
+    for (const block of raw?.content ?? []) {
+      const b = block;
+      if (b.type === "text")
+        msgs.push({ type: "text", text: String(b.text ?? ""), timestamp: ts });
+      if (b.type === "thinking")
+        msgs.push({ type: "thinking", text: String(b.thinking ?? ""), timestamp: ts });
+      if (b.type === "tool_use")
+        msgs.push({ type: "tool_use", toolName: String(b.name ?? ""), toolInput: b.input ?? {}, toolUseId: String(b.id ?? ""), timestamp: ts });
+    }
+    return msgs;
+  }
+  if (message.type === "user") {
+    const raw = message.message;
+    for (const block of raw?.content ?? []) {
+      const b = block;
+      if (b.type === "tool_result")
+        msgs.push({ type: "tool_result", toolUseId: String(b.tool_use_id ?? ""), output: typeof b.content === "string" ? b.content : JSON.stringify(b.content ?? ""), isError: Boolean(b.is_error), timestamp: ts });
+    }
+    return msgs;
+  }
+  if (message.type === "result") {
+    if (typeof message.result === "string" && message.result.trim()) {
+      msgs.push({ type: "text", text: message.result, timestamp: ts });
+    }
+    const usage = message.usage;
+    if (usage)
+      msgs.push({
+        type: "usage",
+        inputTokens: usage.input_tokens ?? 0,
+        outputTokens: usage.output_tokens ?? 0,
+        cacheReadTokens: usage.cache_read_input_tokens ?? 0,
+        cacheCreationTokens: usage.cache_creation_input_tokens ?? 0,
+        durationMs: Number(message.duration_ms ?? 0),
+        numTurns: Number(message.num_turns ?? 0),
+        timestamp: ts
+      });
+    if (message.is_error || message.subtype === "error_during_execution") {
+      msgs.push({ type: "error", text: formatError(message.error ?? message.result ?? message.message), timestamp: ts });
+    } else {
+      msgs.push({ type: "done", sessionId: String(message.session_id ?? ""), timestamp: ts });
+    }
+  }
+  return msgs;
+}
+
+class ClaudeRunner {
+  options;
+  config;
+  supportsToolCallProcessor = true;
+  constructor(_sandbox, options = {}, config = {}) {
+    this.options = options;
+    this.config = config;
+  }
+  async gateToolCall(call, ctx) {
+    const verdict = await runProcessorChain(this.options.processors ?? [], (p) => p.processToolCall, call, ctx);
+    if (verdict.kind === "continue")
+      return { kind: "allow", call: verdict.value };
+    return verdict;
+  }
+  async* sendMessage(opts) {
+    const requestContext = this.options.requestContext ?? RequestContext.fromReserved({
+      teamId: "",
+      runId: "",
+      workflowId: "",
+      factoryId: null,
+      apiKeyScopes: [],
+      parentRunId: null
+    });
+    const preToolHook = async (input, toolUseId, { signal }) => {
+      const pre = input;
+      const call = {
+        toolName: pre.tool_name,
+        toolInput: pre.tool_input ?? {},
+        toolUseId: toolUseId ?? `${pre.tool_name}-${Date.now()}`
+      };
+      const gate = await this.gateToolCall(call, {
+        requestContext,
+        abortSignal: signal ?? opts.signal ?? new AbortController().signal,
+        retryCount: 0,
+        agentId: this.options.agentId ?? "agent",
+        iteration: opts.iteration ?? 1
+      });
+      if (gate.kind === "allow")
+        return { hookSpecificOutput: { hookEventName: pre.hook_event_name, permissionDecision: "allow", updatedInput: gate.call.toolInput } };
+      if (gate.kind === "deny")
+        return { hookSpecificOutput: { hookEventName: pre.hook_event_name, permissionDecision: "deny", permissionDecisionReason: gate.reason } };
+      return { continue: false, systemMessage: gate.reason };
+    };
+    try {
+      let emittedAssistantText = false;
+      for await (const message of query({
+        prompt: opts.prompt,
+        options: {
+          tools: this.options.allowedTools,
+          allowedTools: this.options.allowedTools,
+          maxTurns: this.options.maxTurns,
+          model: this.config.model ?? this.options.model ?? DEFAULT_CLAUDE_MODEL,
+          outputFormat: this.options.outputFormat,
+          thinking: this.config.thinking,
+          effort: this.config.effort,
+          cwd: this.options.cwd,
+          env: { ...process.env, ...this.config.env ?? {} },
+          pathToClaudeCodeExecutable: this.config.pathToClaudeCodeExecutable ?? process.env.CLAUDE_CODE_EXECUTABLE ?? "claude",
+          ...this.config.claudeMdContent ? { systemPrompt: { type: "preset", preset: "claude_code", append: this.config.claudeMdContent } } : {},
+          resume: opts.sessionId,
+          mcpServers: this.config.mcpServers,
+          permissionMode: "acceptEdits",
+          hooks: { PreToolUse: [{ hooks: [preToolHook] }] }
+        }
+      })) {
+        const raw = message;
+        const translated = translateMessage(raw);
+        for (const msg of translated) {
+          if (raw.type === "result" && msg.type === "text" && emittedAssistantText)
+            continue;
+          if (msg.type === "text" && raw.type === "assistant")
+            emittedAssistantText = true;
+          yield msg;
+        }
+      }
+    } catch (err) {
+      yield { type: "error", text: formatError(err), timestamp: now2() };
+    }
+  }
+}
+function createClaudeRuntime(config = {}) {
+  return defineRuntime({
+    create: (sandbox, opts) => new ClaudeRunner(sandbox, opts, config)
   });
 }
+var claude_default = createClaudeRuntime();
 // src/sandbox.ts
 import { promises as fs } from "node:fs";
-import { dirname } from "node:path";
+import { dirname as dirname2 } from "node:path";
 import { spawn } from "node:child_process";
 import { Sandbox } from "e2b";
 import { Sandbox as Desktop } from "@e2b/desktop";
@@ -42,7 +1441,16 @@ import pRetry from "p-retry";
 var AGENT_COMPOSE_TAG = process.env.AGENT_COMPOSE_TAG ?? `agent-compose-${process.env.AGENT_COMPOSE_ENV ?? "dev"}`;
 var VERCEL_VM_LIFETIME_WINDOW_MS = 6 * 60 * 60 * 1000;
 function makeSandboxProvider(sb) {
-  return { sandboxId: sb.sandboxId, commands: sb.commands, files: sb.files, kill: () => sb.kill() };
+  return {
+    sandboxId: sb.sandboxId,
+    commands: sb.commands,
+    files: {
+      async write(path, content) {
+        await sb.files.write(path, content);
+      }
+    },
+    kill: () => sb.kill()
+  };
 }
 function makeDesktopSandboxProvider(sb) {
   return {
@@ -105,7 +1513,7 @@ function makeVercelSandboxProvider(sb, globalEnvs) {
     commands: {
       async run(cmd, opts) {
         if (opts?.background) {
-          sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts.cwd, env: mergeEnvs(opts.envs), detached: true }).catch(() => {});
+          sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts.cwd, env: mergeEnvs(opts.envs), detached: true }).catch((err) => console.error(`[sandbox] background command failed: ${err instanceof Error ? err.message : String(err)}`));
           return { exitCode: 0, stdout: "" };
         }
         const signal = opts?.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined;
@@ -168,7 +1576,7 @@ function makeLocalSandboxProvider() {
     },
     files: {
       async write(path, content) {
-        await fs.mkdir(dirname(path), { recursive: true });
+        await fs.mkdir(dirname2(path), { recursive: true });
         await fs.writeFile(path, content);
       }
     },
@@ -239,7 +1647,7 @@ var SANDBOX_PROVIDERS = {
         sandboxes.push(...await paginator.nextItems());
       if (sandboxes.length === 0)
         return;
-      await Promise.all(sandboxes.map((s) => Sandbox.kill(s.sandboxId).catch(() => {})));
+      await Promise.all(sandboxes.map((s) => Sandbox.kill(s.sandboxId)));
       console.info(`[sandbox] killed ${sandboxes.length} stale E2B sandboxes (tag: ${AGENT_COMPOSE_TAG})`);
     },
     getActiveCount: async () => (await SANDBOX_PROVIDERS.e2b.listOwned({})).length,
@@ -326,722 +1734,235 @@ async function listOwnedSandboxes() {
       out[name] = err instanceof Error ? err : new Error(String(err));
     }
   }));
-  return out;
-}
-async function killSandboxById(provider, sandboxId) {
-  const def = SANDBOX_PROVIDERS[provider];
-  if (!def?.reconnect)
-    throw new Error(`Provider "${provider}" does not support reconnect (required for kill-by-id)`);
-  const sb = await def.reconnect(sandboxId);
-  await sb.kill();
-}
-async function killAllSandboxes(onError) {
-  await Promise.allSettled(Object.entries(SANDBOX_PROVIDERS).filter(([, def]) => def.killAll).map(([name, def]) => {
-    const env = Object.fromEntries(Object.keys(def.requiredEnv).map((k) => [k, process.env[k] ?? ""]));
-    if (Object.keys(def.requiredEnv).some((k) => !process.env[k]))
-      return Promise.resolve();
-    return def.killAll(env).catch((err) => onError?.(name, err));
-  }));
-}
-
-// src/types/sandbox-environment.ts
-function defineSandboxEnvironment(env) {
-  if (typeof env.setup !== "function") {
-    throw new Error(`defineSandboxEnvironment(${env.name}): 'setup' must be a function`);
-  }
-  return defineWorkflow({
-    saveSnapshot: env.saveSnapshot ?? true,
-    run: () => env.setup(makeLocalSandboxProvider())
-  });
-}
-// src/client.ts
-import { ofetch } from "ofetch";
-
-// src/errors.ts
-class AgentComposeError extends Error {
-  status;
-  constructor(status, message) {
-    super(message);
-    this.status = status;
-    this.name = "AgentComposeError";
-  }
-}
-
-// src/sse.ts
-async function* parseSseStream(body) {
-  const reader = body.getReader();
-  const decoder = new TextDecoder;
-  let buffer = "";
-  let event = "";
-  let seq = 0;
-  let dataLines = [];
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done)
-        break;
-      buffer += decoder.decode(value, { stream: true });
-      const lines = buffer.split(`
-`);
-      buffer = lines.pop() ?? "";
-      for (const line of lines) {
-        if (line.startsWith("id:")) {
-          seq = Number(line.slice(3).trim());
-          continue;
-        }
-        if (line.startsWith("event:")) {
-          event = line.slice(6).trim();
-          continue;
-        }
-        if (line.startsWith("data:")) {
-          dataLines.push(line.slice(5).trim());
-          continue;
-        }
-        if (line === "" && dataLines.length > 0) {
-          try {
-            const data = JSON.parse(dataLines.join(`
-`));
-            yield { id: seq, event, data };
-          } catch {}
-          event = "";
-          seq = 0;
-          dataLines = [];
-        }
-      }
-    }
-  } finally {
-    reader.releaseLock();
-  }
-}
-
-// src/client.ts
-var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-var DEFAULT_FACTORY = "default";
-function detectAmbientParentRunId() {
-  const envRunId = typeof process !== "undefined" ? process.env?.RUN_ID : undefined;
-  return envRunId && UUID_REGEX.test(envRunId) ? envRunId : null;
-}
-function templatePath(factorySlug, ...rest) {
-  const tail = rest.length > 0 ? "/" + rest.map(encodeURIComponent).join("/") : "";
-  return `/api/v1/factories/${encodeURIComponent(factorySlug)}/templates${tail}`;
-}
-
-class AgentComposeClient {
-  fetch;
-  baseUrl;
-  apiKey;
-  constructor(baseUrl, apiKey) {
-    this.baseUrl = baseUrl.replace(/\/$/, "");
-    this.apiKey = apiKey;
-    this.fetch = ofetch.create({
-      baseURL: this.baseUrl,
-      headers: { Authorization: `Bearer ${apiKey}` },
-      async onResponseError({ response }) {
-        const body = response._data;
-        throw new AgentComposeError(response.status, body?.error ?? response.statusText);
-      }
-    });
-  }
-  register(payload) {
-    const { factorySlug = DEFAULT_FACTORY, ...body } = payload;
-    return this.fetch(templatePath(factorySlug), { method: "POST", body });
-  }
-  invoke(name, input, opts) {
-    const parentRunId = opts?.parentRunId === undefined ? detectAmbientParentRunId() : opts.parentRunId;
-    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
-    return this.fetch(templatePath(factorySlug, name, "invoke"), {
-      method: "POST",
-      body: {
-        input,
-        ...opts?.snapshot !== undefined ? { snapshot: opts.snapshot } : {},
-        ...opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {},
-        ...parentRunId ? { parentRunId } : {},
-        ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
-        ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {}
-      }
-    });
-  }
-  async invokeAndWait(name, input, opts) {
-    const timeoutMs = opts?.timeoutMs ?? 30 * 60 * 1000;
-    const pollMs = opts?.pollIntervalMs ?? 1000;
-    const { id: runId } = await this.invoke(name, input, {
-      ...opts?.snapshot !== undefined ? { snapshot: opts.snapshot } : {},
-      ...opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {},
-      ...opts?.parentRunId !== undefined ? { parentRunId: opts.parentRunId } : {},
-      ...opts?.factorySlug !== undefined ? { factorySlug: opts.factorySlug } : {},
-      ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
-      ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {}
-    });
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-      const status = await this.getStatus(runId);
-      if (status.status === "success" || status.status === "failed" || status.status === "abandoned") {
-        return status;
-      }
-      await new Promise((r) => setTimeout(r, pollMs));
-    }
-    throw new AgentComposeError(504, `invokeAndWait: run ${runId} did not settle within ${timeoutMs}ms`);
-  }
-  async listSnapshots(opts) {
-    const q = new URLSearchParams;
-    if (opts?.workflow)
-      q.set("workflow", opts.workflow);
-    if (opts?.limit != null)
-      q.set("limit", String(opts.limit));
-    const body = await this.fetch(`/api/v1/snapshots${q.toString() ? `?${q}` : ""}`);
-    return body.data;
-  }
-  deleteSnapshot(runId) {
-    return this.fetch(`/api/v1/workflows/${runId}/snapshot`, { method: "DELETE" });
-  }
-  getStatus(runId) {
-    return this.fetch(`/api/v1/workflows/${runId}/status`);
-  }
-  async listTemplates(opts) {
-    const path = opts?.factorySlug ? templatePath(opts.factorySlug) : "/api/v1/templates";
-    const body = await this.fetch(path);
-    return body.templates;
-  }
-  async listFactories() {
-    const body = await this.fetch("/api/v1/factories");
-    return body.factories;
-  }
-  createFactory(payload) {
-    return this.fetch("/api/v1/factories", { method: "POST", body: payload });
-  }
-  getFactory(slug) {
-    return this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}`);
-  }
-  updateFactory(slug, updates) {
-    return this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}`, { method: "PATCH", body: updates });
-  }
-  deleteFactory(slug) {
-    return this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}`, { method: "DELETE" });
-  }
-  setSecret(workflowName, key, value, opts) {
-    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
-    return this.fetch(templatePath(factorySlug, workflowName, "secrets"), {
-      method: "POST",
-      body: { key, value }
-    });
-  }
-  async listSecrets(workflowName, opts) {
-    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
-    const body = await this.fetch(templatePath(factorySlug, workflowName, "secrets"));
-    return body.secrets.map((s) => ({ key: s.secretKey, createdAt: s.createdAt, updatedAt: s.updatedAt }));
-  }
-  deleteSecret(workflowName, key, opts) {
-    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
-    return this.fetch(templatePath(factorySlug, workflowName, "secrets", key), { method: "DELETE" });
-  }
-  createApiKey(input) {
-    return this.fetch("/api-keys", { method: "POST", body: input });
-  }
-  async listApiKeys() {
-    const body = await this.fetch("/api-keys");
-    return body.data;
-  }
-  getUsage(from, to) {
-    const qs = `?from=${encodeURIComponent(from.toISOString())}&to=${encodeURIComponent(to.toISOString())}`;
-    return this.fetch(`/api/v1/usage${qs}`);
-  }
-  cancelRun(runId) {
-    return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/cancel`, { method: "POST" });
-  }
-  async* streamRunLogs(runId, opts) {
-    const headers = { Authorization: `Bearer ${this.apiKey}` };
-    if (opts?.lastEventId && opts.lastEventId > 0) {
-      headers["Last-Event-ID"] = String(opts.lastEventId);
-    }
-    const res = await fetch(`${this.baseUrl}/api/v1/workflows/${encodeURIComponent(runId)}/stream`, {
-      headers,
-      ...opts?.signal ? { signal: opts.signal } : {}
-    });
-    if (!res.ok || !res.body) {
-      let message = res.statusText;
-      try {
-        const body = await res.json();
-        if (body.error)
-          message = body.error;
-      } catch {}
-      throw new AgentComposeError(res.status, message);
-    }
-    for await (const ev of parseSseStream(res.body)) {
-      yield ev.data;
-    }
-  }
-}
-// src/utils/errors.ts
-function formatError(err) {
-  return err instanceof Error ? err.message : String(err);
-}
-// src/utils/discovery.ts
-function discoverRuntimeName(source) {
-  return source.match(/runtime:\s*["']([^"']+)["']/)?.[1] ?? null;
+  return out;
 }
-// src/utils/source-loader.ts
-import { dirname as dirname2 } from "path";
-import { writeFile, unlink, mkdir } from "node:fs/promises";
-var TMP_DIR = process.env.TMP_DIR ?? "/tmp/agent-compose";
-var LATEST_VERSION = "$LATEST";
-async function importSourceModule(source, tmpPath) {
-  await mkdir(dirname2(tmpPath), { recursive: true });
-  await writeFile(tmpPath, source, "utf8");
-  const mod = await import(tmpPath);
-  const cleanup = () => unlink(tmpPath).catch(() => {});
-  return { mod, cleanup };
+async function killSandboxById(provider, sandboxId) {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def?.reconnect)
+    throw new Error(`Provider "${provider}" does not support reconnect (required for kill-by-id)`);
+  const sb = await def.reconnect(sandboxId);
+  await sb.kill();
 }
-
-// src/utils/bundler.ts
-async function bundle(path, label) {
-  const bun = globalThis;
-  if (!bun.Bun?.build)
-    throw new Error("bundleWorkflow requires the Bun runtime (Bun.build)");
-  const result = await bun.Bun.build({ entrypoints: [path], format: "esm", target: "bun" });
-  if (!result.success) {
-    throw new Error(`Failed to bundle ${label}:
-${result.logs.map((l) => l.message).join(`
-`)}`);
-  }
-  return result.outputs[0].text();
+async function killAllSandboxes(onError) {
+  await Promise.allSettled(Object.entries(SANDBOX_PROVIDERS).filter(([, def]) => def.killAll).map(([name, def]) => {
+    const env = Object.fromEntries(Object.keys(def.requiredEnv).map((k) => [k, process.env[k] ?? ""]));
+    if (Object.keys(def.requiredEnv).some((k) => !process.env[k]))
+      return Promise.resolve();
+    return def.killAll(env).catch((err) => onError?.(name, err));
+  }));
 }
-async function extractFromBundle(source, label, pick) {
-  const tmpPath = `/tmp/agentc-${label}-${Date.now()}-${Math.random().toString(36).slice(2)}.js`;
-  try {
-    const loaded = await importSourceModule(source, tmpPath);
+// src/workflow-steps/observability.ts
+class StepObservabilityCollector {
+  metadata = {};
+  events = [];
+  subSteps = [];
+  setMetadata = async (data) => {
+    Object.assign(this.metadata, data);
+  };
+  step = async (name, fn) => {
+    const startedAt = Date.now();
     try {
-      return pick(loaded.mod.default);
-    } finally {
-      await loaded.cleanup();
+      const result = await fn();
+      this.subSteps.push({
+        name,
+        startedAt,
+        durationMs: Date.now() - startedAt,
+        status: "completed"
+      });
+      return result;
+    } catch (err) {
+      this.subSteps.push({
+        name,
+        startedAt,
+        durationMs: Date.now() - startedAt,
+        status: "failed",
+        error: err instanceof Error ? err.message : String(err)
+      });
+      throw err;
     }
-  } catch {
-    return;
-  }
-}
-async function bundleWorkflow(workflowPath, overrides) {
-  const source = await bundle(workflowPath, `workflow "${workflowPath}"`);
-  const wfBits = await extractFromBundle(source, "workflow", (wf) => wf ? {
-    networkPolicy: wf.networkPolicy,
-    placeholders: wf.placeholders,
-    snapshot: wf.snapshot,
-    saveSnapshot: wf.saveSnapshot
-  } : undefined);
-  const { networkPolicy, placeholders, snapshot, saveSnapshot } = wfBits ?? {};
-  return {
-    source,
-    networkPolicy: overrides?.networkPolicy ?? networkPolicy,
-    placeholders: overrides?.placeholders ?? placeholders,
-    ...snapshot !== undefined ? { snapshot } : {},
-    ...saveSnapshot !== undefined ? { saveSnapshot } : {}
   };
-}
-// src/utils/schemas.ts
-import { z } from "zod";
-var AgentStatusSchema = z.object({
-  summary: z.string(),
-  completed: z.array(z.string()),
-  blockers: z.array(z.string()),
-  exit_signal: z.boolean()
-});
-// src/agent/protocol.ts
-import { z as z2 } from "zod";
-var AgentMessageSchema = z2.object({
-  type: z2.enum(["init", "text", "thinking", "tool_use", "tool_result", "done", "error", "usage"]),
-  timestamp: z2.string()
-}).passthrough();
-function parseAgentResponse(text) {
-  const match = text.match(/<response>([\s\S]*?)<\/response>/);
-  if (!match)
-    return null;
-  try {
-    return JSON.parse(match[1].trim());
-  } catch {
-    return null;
+  agentEvents = {
+    emit: (event) => {
+      this.events.push(event);
+    }
+  };
+  snapshot() {
+    const hasMetadata = Object.keys(this.metadata).length > 0;
+    const hasEvents = this.events.length > 0;
+    const hasSubSteps = this.subSteps.length > 0;
+    if (!hasMetadata && !hasEvents && !hasSubSteps)
+      return;
+    const result = {};
+    if (hasMetadata)
+      result.metadata = { ...this.metadata };
+    if (hasEvents)
+      result.events = [...this.events];
+    if (hasSubSteps)
+      result.subSteps = [...this.subSteps];
+    return result;
   }
 }
 
-// src/agent/agent-loop.ts
-var DEFAULT_CLAUDE_MODEL = "claude-opus-4-7";
-var SAME_BLOCKER_ITERATIONS = 3;
-var STALL_ITERATIONS = 3;
-function parseAgentStatus(text) {
-  const match = text.match(/<status>([\s\S]*?)<\/status>/);
-  if (!match)
-    return null;
-  try {
-    const result = AgentStatusSchema.safeParse(JSON.parse(match[1].trim()));
-    return result.success ? result.data : null;
-  } catch {
-    return null;
+// src/workflow-steps/runner.ts
+class StepValidationError extends Error {
+  stepName;
+  side;
+  kind = "step-validation";
+  constructor(stepName, side, cause) {
+    super(`Step "${stepName}" ${side} failed schema validation: ${cause.message}`);
+    this.stepName = stepName;
+    this.side = side;
+    this.name = "StepValidationError";
+    this.cause = cause;
   }
 }
-var DEFAULT_ALLOWED_TOOLS = ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "WebFetch"];
-async function agentLoop(opts) {
-  const label = opts.label ?? "[Agent Loop]";
-  const turnsPerIteration = opts.turnsPerIteration ?? 40;
-  const maxIterations = opts.maxIterations ?? 8;
-  if (!opts.runtime)
-    throw new Error("agentLoop: opts.runtime is required");
-  const client = opts.runtime({
-    maxTurns: turnsPerIteration,
-    allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
-    label,
-    cwd: opts.cwd
-  });
-  let lastSessionId = "";
-  let lastStatus = null;
-  let iterationsWithoutStatus = 0;
-  let blockerStreak = null;
-  for (let iteration = 0;iteration < maxIterations; iteration++) {
-    const prompt = opts.buildPrompt(lastStatus, iteration);
-    process.stderr.write(`${label} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration} turns
-`);
-    let responseText = "";
-    for await (const msg of client.sendMessage({ prompt, sessionId: iteration > 0 ? lastSessionId : undefined })) {
-      opts.onAgentEvent?.(iteration, msg);
-      if (msg.type === "init")
-        lastSessionId = msg.sessionId;
-      if (msg.type === "text")
-        responseText += msg.text;
-      if (msg.type === "error")
-        throw new Error(`Agent error: ${msg.text}`);
-    }
-    process.stdout.write(`
-`);
-    let status = parseAgentStatus(responseText);
-    process.stderr.write(`
-${label} iteration ${iteration + 1} status: exit_signal=${status?.exit_signal ?? "(no status)"} blockers=${JSON.stringify(status?.blockers ?? [])}
-`);
-    lastStatus = status ?? lastStatus;
-    opts.onIteration?.(iteration + 1, status);
-    if (status?.exit_signal && (status.blockers?.length ?? 0) === 0) {
-      let response = status;
-      if (opts.responseSchema) {
-        const raw = parseAgentResponse(responseText);
-        if (raw === null) {
-          process.stderr.write(`
-${label} NO <response> BLOCK — response tail: ${responseText.slice(-400)}
-`);
-          status = { ...status, exit_signal: false, blockers: ["No <response> block found — emit a <response> block with the required JSON fields before setting exit_signal: true"] };
-          opts.onIteration?.(iteration + 1, status);
-          continue;
-        }
-        const parsed = opts.responseSchema.safeParse({ ...status, ...raw });
-        if (!parsed.success) {
-          process.stderr.write(`
-${label} <response> SCHEMA FAILED: ${parsed.error.message}
-raw: ${JSON.stringify(raw).slice(0, 400)}
-`);
-          status = { ...status, exit_signal: false, blockers: [`<response> schema validation failed: ${parsed.error.message}`] };
-          opts.onIteration?.(iteration + 1, status);
-          continue;
-        }
-        response = parsed.data;
-      }
-      process.stderr.write(`${label} done after ${iteration + 1}/${maxIterations} iterations
-`);
-      return { sessionId: lastSessionId, lastStatus: status, iterations: iteration + 1, response };
-    }
-    if (!status) {
-      if (++iterationsWithoutStatus >= STALL_ITERATIONS)
-        throw new Error(`${label} stalled: no <status> block after ${iterationsWithoutStatus} iterations`);
-    } else {
-      iterationsWithoutStatus = 0;
-    }
-    if (status?.blockers?.length) {
-      const key = status.blockers.join("|");
-      if (blockerStreak !== null && blockerStreak.key === key) {
-        if (++blockerStreak.count >= SAME_BLOCKER_ITERATIONS)
-          throw new Error(`${label} circuit break: same blocker repeated ${blockerStreak.count}x — "${status.blockers[0]}"`);
-      } else {
-        blockerStreak = { key, count: 1 };
-      }
-    } else {
-      blockerStreak = null;
-    }
-    if (iteration + 1 < maxIterations)
-      process.stderr.write(`${label} continuing to iteration ${iteration + 2}/${maxIterations}
-`);
+
+class WorkflowInputValidationError extends Error {
+  workflowId;
+  kind = "workflow-input-validation";
+  constructor(workflowId, cause) {
+    super(`Workflow "${workflowId}" input failed schema validation: ${cause.message}`);
+    this.workflowId = workflowId;
+    this.name = "WorkflowInputValidationError";
+    this.cause = cause;
   }
-  if (opts.responseSchema)
-    throw new Error(`${label} did not produce a valid <response> after ${maxIterations} iterations`);
-  process.stderr.write(`${label} exhausted ${maxIterations} iterations, proceeding with available work
-`);
-  return { sessionId: lastSessionId, lastStatus, iterations: maxIterations };
 }
 
-// src/runtimes/claude.ts
-var NO_TIMEOUT = 0;
-function translateEvent(event) {
-  const msgs = [];
-  const ts = new Date().toISOString();
-  if (event.type === "system" && event.subtype === "init") {
-    msgs.push({ type: "init", sessionId: String(event.session_id ?? ""), timestamp: ts });
-    return msgs;
-  }
-  if (event.type === "assistant") {
-    const message = event.message;
-    for (const block of message?.content ?? []) {
-      const b = block;
-      if (b.type === "text")
-        msgs.push({ type: "text", text: String(b.text ?? ""), timestamp: ts });
-      if (b.type === "thinking")
-        msgs.push({ type: "thinking", text: String(b.thinking ?? ""), timestamp: ts });
-      if (b.type === "tool_use")
-        msgs.push({ type: "tool_use", toolName: String(b.name ?? ""), toolInput: b.input ?? {}, toolUseId: String(b.id ?? ""), timestamp: ts });
-    }
-    return msgs;
-  }
-  if (event.type === "user") {
-    const message = event.message;
-    for (const block of message?.content ?? []) {
-      const b = block;
-      if (b.type === "tool_result") {
-        const raw = b.content;
-        msgs.push({ type: "tool_result", toolUseId: String(b.tool_use_id ?? ""), output: typeof raw === "string" ? raw : JSON.stringify(raw ?? ""), isError: Boolean(b.is_error), timestamp: ts });
-      }
-    }
-    return msgs;
+class WorkflowOutputValidationError extends Error {
+  workflowId;
+  kind = "workflow-output-validation";
+  constructor(workflowId, cause) {
+    super(`Workflow "${workflowId}" output failed schema validation: ${cause.message}`);
+    this.workflowId = workflowId;
+    this.name = "WorkflowOutputValidationError";
+    this.cause = cause;
   }
-  if (event.type === "result") {
-    const usage = event.usage;
-    if (usage) {
-      msgs.push({ type: "usage", inputTokens: usage.input_tokens ?? 0, outputTokens: usage.output_tokens ?? 0, cacheReadTokens: usage.cache_read_input_tokens ?? 0, cacheCreationTokens: usage.cache_creation_input_tokens ?? 0, durationMs: Number(event.duration_ms ?? 0), numTurns: Number(event.num_turns ?? 0), timestamp: ts });
-    }
-    if (event.is_error || event.subtype === "error_during_execution") {
-      const raw = event.error ?? event.result ?? event.message;
-      msgs.push({ type: "error", text: raw == null ? "Unknown error" : typeof raw === "object" ? JSON.stringify(raw) : String(raw), timestamp: ts });
-    } else {
-      msgs.push({ type: "done", sessionId: String(event.session_id ?? ""), timestamp: ts });
-    }
-    return msgs;
-  }
-  return msgs;
 }
-
-class ClaudeRunner {
-  sandbox;
-  options;
-  claudeMdContent;
-  configEnv;
-  configModel;
-  configMcpServers;
-  claudeMdWritten = false;
-  homeDir = null;
-  label;
-  constructor(sandbox, options = {}, claudeMdContent = "", configEnv = {}, configModel, configMcpServers) {
-    this.sandbox = sandbox;
-    this.options = options;
-    this.claudeMdContent = claudeMdContent;
-    this.configEnv = configEnv;
-    this.configModel = configModel;
-    this.configMcpServers = configMcpServers;
-    this.label = options.label ?? "[Agent]";
-  }
-  async getHomeDir() {
-    if (!this.homeDir) {
-      const { stdout } = await this.sandbox.commands.run("echo $HOME", { timeoutMs: 30000 });
-      this.homeDir = stdout.trim() || "/home/user";
-    }
-    return this.homeDir;
+async function runWorkflowSingleStep(opts) {
+  const step = opts.workflow.steps[opts.stepIndex];
+  if (!step)
+    throw new Error(`Step index ${opts.stepIndex} not found in workflow "${opts.workflow.id}"`);
+  const parsedInput = step.input.safeParse(opts.input);
+  if (!parsedInput.success)
+    throw new StepValidationError(step.name, "input", parsedInput.error);
+  const collector = new StepObservabilityCollector;
+  const stepCtx = {
+    input: parsedInput.data,
+    requestContext: opts.requestContext,
+    run: opts.run,
+    ...opts.sandbox ? { sandbox: opts.sandbox } : {},
+    stepName: step.name,
+    abortSignal: opts.abortSignal ?? new AbortController().signal,
+    invokeChild: opts.invokeChild ?? (() => {
+      throw new Error("StepContext.invokeChild is not configured for this workflow engine");
+    }),
+    setMetadata: collector.setMetadata,
+    step: collector.step,
+    agentEvents: collector.agentEvents
+  };
+  const output = await step.run(stepCtx);
+  const parsedOutput = step.output.safeParse(output);
+  if (!parsedOutput.success)
+    throw new StepValidationError(step.name, "output", parsedOutput.error);
+  const observability = collector.snapshot();
+  return observability === undefined ? { output: parsedOutput.data } : { output: parsedOutput.data, observability };
+}
+async function runWorkflowSteps(opts) {
+  const { workflow, run, requestContext } = opts;
+  const abortSignal = opts.abortSignal ?? new AbortController().signal;
+  const invokeChild = opts.invokeChild ?? (() => {
+    throw new Error("StepContext.invokeChild is not configured for this workflow engine");
+  });
+  const parsedInput = workflow.input.safeParse(opts.input);
+  if (!parsedInput.success) {
+    throw new WorkflowInputValidationError(workflow.id, parsedInput.error);
   }
-  async deployGlobalConfig() {
-    if (this.claudeMdWritten)
-      return;
-    const home = await this.getHomeDir();
-    await this.sandbox.commands.run(`mkdir -p "${home}/.claude" && find "${home}/.claude" -name "*.json" -not -name "CLAUDE.md" -delete 2>/dev/null || true`, { timeoutMs: 5000 });
-    await this.sandbox.files.write(`${home}/.claude/CLAUDE.md`, this.claudeMdContent);
-    if (Object.keys(this.configEnv).length) {
-      const settings = JSON.stringify({ env: this.configEnv });
-      const b64 = Buffer.from(settings).toString("base64");
-      await this.sandbox.commands.run(`echo "${b64}" | base64 -d > "${home}/.claude/settings.json"`, { timeoutMs: 5000 });
+  let current = parsedInput.data;
+  const stepResults = [];
+  for (let i = 0;i < workflow.steps.length; i++) {
+    const step = workflow.steps[i];
+    const cached = opts.getCachedOutput ? await opts.getCachedOutput(i, step.name) : undefined;
+    if (cached !== undefined) {
+      const parsedCached = step.output.safeParse(cached);
+      if (!parsedCached.success) {
+        throw new StepValidationError(step.name, "output", parsedCached.error);
+      }
+      current = parsedCached.data;
+      stepResults.push({ name: step.name, status: "completed", output: parsedCached.data, durationMs: 0 });
+      continue;
     }
-    const mcpServers = this.configMcpServers;
-    if (mcpServers && Object.keys(mcpServers).length) {
-      const b64 = Buffer.from(JSON.stringify({ mcpServers })).toString("base64");
-      await this.sandbox.commands.run(`echo "${b64}" | base64 -d > "${home}/.claude.json"`, { timeoutMs: 5000 });
-      process.stderr.write(`${this.label}[mcp] wrote ${Object.keys(mcpServers).join(",")} to ~/.claude.json
-`);
+    await opts.onStepStarted?.(i, step.name);
+    const parsedStepInput = step.input.safeParse(current);
+    if (!parsedStepInput.success) {
+      const err = new StepValidationError(step.name, "input", parsedStepInput.error);
+      await opts.onStepFailed?.(i, step.name, err, 0);
+      throw err;
     }
-    const placeholderB64 = Buffer.from("x-access-token:placeholder").toString("base64");
-    await this.sandbox.commands.run([
-      `git config --global core.askPass ""`,
-      `git config --global credential.interactive false`,
-      `git config --global credential.helper ""`,
-      `git config --global "http.https://github.com/.extraHeader" "Authorization: Basic ${placeholderB64}"`
-    ].join(" && "), { timeoutMs: 5000 }).catch((e) => console.warn(`${this.label}[init] git config failed (non-fatal): ${formatError(e)}`));
+    const collector = new StepObservabilityCollector;
+    const stepCtx = {
+      input: parsedStepInput.data,
+      requestContext,
+      run,
+      ...opts.sandbox ? { sandbox: opts.sandbox } : {},
+      stepName: step.name,
+      abortSignal,
+      invokeChild,
+      setMetadata: collector.setMetadata,
+      step: collector.step,
+      agentEvents: collector.agentEvents
+    };
+    const startedAt = Date.now();
+    let output;
     try {
-      await this.sandbox.commands.run("rtk init --global --hook-only --auto-patch", { timeoutMs: 1e4 });
-    } catch {
-      console.warn("[Transport] rtk init failed (non-fatal) — token compression disabled");
-    }
-    this.claudeMdWritten = true;
-  }
-  async* _runCli(cmd, label, signal) {
-    const queue = [];
-    let notify = null;
-    function enqueue(items) {
-      queue.push(...items);
-      notify?.();
-      notify = null;
-    }
-    let lineBuffer = "";
-    let stderrBuffer = "";
-    const maxTurns = this.options.maxTurns ?? 40;
-    function handleStdout(data) {
-      lineBuffer += data;
-      const lines = lineBuffer.split(`
-`);
-      lineBuffer = lines.pop() ?? "";
-      for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed)
-          continue;
-        try {
-          const event = JSON.parse(trimmed);
-          if (event.type === "assistant") {
-            const content = event.message?.content ?? [];
-            for (const block of content) {
-              const b = block;
-              if (b.type === "text")
-                process.stdout.write(".");
-              if (b.type === "tool_use")
-                process.stderr.write(`
-${label} ${b.name}(${JSON.stringify(b.input).slice(0, 80)})`);
-            }
-          } else if (event.type === "result") {
-            process.stderr.write(`
-${label}[result:${event.num_turns}/${maxTurns}/${event.subtype}]
-`);
-          } else if (event.type === "system") {
-            const ev = event;
-            const mcpSrvs = ev.mcp_servers ?? [];
-            const mcpStr = mcpSrvs.length ? ` mcp=[${mcpSrvs.map((s) => `${s.name}:${s.status}`).join(",")}]` : " mcp=[]";
-            process.stderr.write(`
-${label}[init:${ev.session_id}]${mcpStr}
-`);
-          }
-          enqueue(translateEvent(event));
-        } catch {}
-      }
+      output = await step.run(stepCtx);
+    } catch (err) {
+      const wrapped = err instanceof Error ? err : new Error(String(err));
+      const durationMs2 = Date.now() - startedAt;
+      const observability2 = collector.snapshot();
+      stepResults.push({
+        name: step.name,
+        status: "failed",
+        error: wrapped.message,
+        durationMs: durationMs2,
+        ...observability2 ? { observability: observability2 } : {}
+      });
+      await opts.onStepFailed?.(i, step.name, wrapped, durationMs2);
+      throw wrapped;
     }
-    process.stderr.write(`${label}[cwd:${this.options.cwd ?? "(none)"}]
-`);
-    const runPromise = this.sandbox.commands.run(cmd, {
-      cwd: this.options.cwd,
-      timeoutMs: NO_TIMEOUT,
-      onStdout: handleStdout,
-      onStderr: (data) => {
-        stderrBuffer += data;
-        process.stderr.write(`${label}[stderr] ${data.trimEnd()}
-`);
-      }
-    });
-    runPromise.catch((err) => {
-      const e = err;
-      if (e && typeof e === "object" && "exitCode" in e)
-        process.stderr.write(`${label}[transport] command failed — exitCode=${e.exitCode} error=${JSON.stringify(e.error)} stdout_tail=${String(e.stdout ?? "").slice(-200)} stderr_tail=${String(e.stderr ?? "").slice(-200)}
-`);
-      queue.push({ sentinel: "error", text: stderrBuffer.trim() ? `Agent process failed: ${formatError(err)}
-
-${stderrBuffer.trim()}` : `Agent process failed: ${formatError(err)}` });
-    }).finally(() => {
-      if (lineBuffer.trim()) {
-        try {
-          enqueue(translateEvent(JSON.parse(lineBuffer.trim())));
-        } catch {}
-      }
-      queue.push(null);
-      notify?.();
-      notify = null;
-    });
-    while (true) {
-      while (queue.length > 0) {
-        const item = queue.shift();
-        if (item === null)
-          return;
-        if ("sentinel" in item) {
-          yield { type: "error", text: item.text, timestamp: new Date().toISOString() };
-          return;
-        }
-        if (signal?.aborted)
-          return;
-        const msg = item;
-        yield msg.type === "error" && stderrBuffer.trim() && !msg.text.includes(stderrBuffer.trim()) ? { ...msg, text: `${msg.text}
-
-${stderrBuffer.trim()}` } : msg;
-      }
-      await new Promise((r) => {
-        notify = r;
+    const parsedOutput = step.output.safeParse(output);
+    if (!parsedOutput.success) {
+      const err = new StepValidationError(step.name, "output", parsedOutput.error);
+      const durationMs2 = Date.now() - startedAt;
+      const observability2 = collector.snapshot();
+      stepResults.push({
+        name: step.name,
+        status: "failed",
+        error: err.message,
+        durationMs: durationMs2,
+        ...observability2 ? { observability: observability2 } : {}
       });
+      await opts.onStepFailed?.(i, step.name, err, durationMs2);
+      throw err;
     }
+    const durationMs = Date.now() - startedAt;
+    current = parsedOutput.data;
+    const observability = collector.snapshot();
+    stepResults.push({
+      name: step.name,
+      status: "completed",
+      output: parsedOutput.data,
+      durationMs,
+      ...observability ? { observability } : {}
+    });
+    await opts.onStepCompleted?.(i, step.name, parsedOutput.data, durationMs);
   }
-  async* sendMessage(opts) {
-    await this.deployGlobalConfig();
-    if (opts.sessionId) {
-      await this.sandbox.commands.run(`pkill -x claude 2>/dev/null || true`, { timeoutMs: 1e4 });
-    }
-    const maxTurns = this.options.maxTurns ?? 40;
-    const model = this.configModel ?? this.options.model ?? DEFAULT_CLAUDE_MODEL;
-    const label = this.label;
-    const promptFile = `/tmp/agent-prompt-${Date.now()}.txt`;
-    await this.sandbox.files.write(promptFile, opts.prompt);
-    const hasMcp = this.configMcpServers && Object.keys(this.configMcpServers).length > 0;
-    const allowedToolsFlag = !hasMcp && this.options.allowedTools?.length ? ["--allowedTools", this.options.allowedTools.join(",")] : [];
-    const buildCmd = (sessionId) => [
-      "claude",
-      "--dangerously-skip-permissions",
-      "--verbose",
-      "--output-format",
-      "stream-json",
-      "--max-turns",
-      String(maxTurns),
-      "--model",
-      model,
-      ...allowedToolsFlag,
-      ...sessionId ? ["--resume", sessionId] : [],
-      "-p",
-      `"$(cat ${promptFile})"`
-    ].join(" ");
-    const MAX_529_RETRIES = 5;
-    const BACKOFF_MS = [60000, 120000, 240000, 480000, 600000];
-    let resumeSessionId = opts.sessionId;
-    for (let attempt = 0;attempt <= MAX_529_RETRIES; attempt++) {
-      let got529 = false;
-      let newSession = "";
-      for await (const msg of this._runCli(buildCmd(resumeSessionId), label, opts.signal)) {
-        if (msg.type === "init")
-          newSession = msg.sessionId;
-        if (msg.type === "error" && msg.text.includes("529")) {
-          got529 = true;
-          break;
-        }
-        yield msg;
-        if (msg.type === "done" || msg.type === "error")
-          return;
-      }
-      if (!got529)
-        return;
-      if (attempt === MAX_529_RETRIES) {
-        yield { type: "error", text: "Agent process failed: Repeated 529 Overloaded errors — all retries exhausted", timestamp: new Date().toISOString() };
-        return;
-      }
-      if (newSession)
-        resumeSessionId = newSession;
-      const wait = BACKOFF_MS[attempt];
-      process.stderr.write(`
-${label}[529] Overloaded — resuming in ${wait / 1000}s (attempt ${attempt + 1}/${MAX_529_RETRIES})${resumeSessionId ? " with session resume" : ""}
-`);
-      await new Promise((r) => setTimeout(r, wait));
-    }
+  const parsedFinal = workflow.output.safeParse(current);
+  if (!parsedFinal.success) {
+    throw new WorkflowOutputValidationError(workflow.id, parsedFinal.error);
   }
+  return { output: parsedFinal.data, steps: stepResults };
 }
-function createClaudeRuntime(config = {}) {
-  return defineRuntime({
-    create: (sandbox, opts) => new ClaudeRunner(sandbox, opts, config.claudeMdContent ?? "", config.env ?? {}, config.model, config.mcpServers)
-  });
-}
-var claude_default = createClaudeRuntime();
+
 // src/workflows/engine.ts
 class WorkflowError extends Error {
   kind = "workflow";
@@ -1071,41 +1992,288 @@ function parseNameVersion(ref) {
   const atIdx = ref.lastIndexOf("@");
   return atIdx > 0 ? { name: ref.slice(0, atIdx), version: ref.slice(atIdx + 1) } : { name: ref, version: undefined };
 }
+function defaultRequestContext(runId, workflowId = "") {
+  return RequestContext.fromReserved({
+    teamId: "",
+    runId,
+    workflowId,
+    factoryId: null,
+    apiKeyScopes: [],
+    parentRunId: null
+  });
+}
 async function runWorkflow(wf, ctx, opts) {
   const hooks = opts?.hooks ?? {};
-  const setMetadata = opts?.setMetadata ?? (async () => {});
+  const requestContext = opts?.requestContext ?? defaultRequestContext(ctx.run.id, wf.id);
   const sandbox = makeLocalSandboxProvider();
-  let workflowErr;
-  let wfOutput;
+  const invokeChild = opts?.invokeChild ?? (() => {
+    throw new Error("StepContext.invokeChild is not configured for this workflow engine");
+  });
   try {
-    wfOutput = await wf({
-      ...ctx,
-      setMetadata,
-      step: async (name, fn) => {
-        const startedAt = Date.now();
+    const result = await runWorkflowSteps({
+      workflow: wf,
+      input: ctx.input,
+      run: ctx.run,
+      requestContext,
+      sandbox,
+      invokeChild,
+      ...opts?.getCachedOutput ? { getCachedOutput: opts.getCachedOutput } : {},
+      onStepStarted: async (idx, name) => {
         hooks.onStepStart?.(name);
-        try {
-          const r = await fn();
-          hooks.onStepComplete?.(name, Date.now() - startedAt);
-          return r;
-        } catch (err) {
-          hooks.onStepFail?.(name, Date.now() - startedAt, formatError(err));
-          throw err;
+        await opts?.onStepStarted?.(idx, name);
+      },
+      onStepCompleted: async (idx, name, output, durationMs) => {
+        hooks.onStepComplete?.(name, durationMs);
+        await opts?.onStepCompleted?.(idx, name, output, durationMs);
+      },
+      onStepFailed: async (idx, name, err, durationMs) => {
+        hooks.onStepFail?.(name, durationMs, formatError(err));
+        await opts?.onStepFailed?.(idx, name, err, durationMs);
+      }
+    });
+    return { response: result.output ?? null };
+  } catch (err) {
+    if (err instanceof WorkflowError)
+      throw err;
+    throw new WorkflowError(formatError(err), { cause: err });
+  }
+}
+// src/workflows/invoke-child.ts
+function buildInvokeChild(runId, opts = {}) {
+  let childClient = null;
+  const getChildClient = () => {
+    if (childClient)
+      return childClient;
+    const baseUrl = process.env.AGENT_COMPOSE_URL ?? opts.fallbackBaseUrl;
+    const apiKey = process.env.AGENT_COMPOSE_API_KEY;
+    if (!baseUrl || !apiKey) {
+      throw new Error("ctx.invokeChild requires AGENT_COMPOSE_URL and AGENT_COMPOSE_API_KEY");
+    }
+    childClient = new AgentComposeClient(baseUrl, apiKey);
+    return childClient;
+  };
+  return (name, input, childOpts) => getChildClient().invokeAndWait(name, input, {
+    ...childOpts,
+    parentRunId: runId,
+    factorySlug: childOpts?.factorySlug ?? opts.defaultFactorySlug ?? process.env.AGENT_COMPOSE_FACTORY_SLUG ?? "default"
+  });
+}
+// src/workflow-steps/step.ts
+function defineStep(opts) {
+  if (!opts.name)
+    throw new Error("defineStep: 'name' is required");
+  return {
+    name: opts.name,
+    input: opts.input,
+    output: opts.output,
+    run: opts.run
+  };
+}
+// src/step-invocation/protocol.ts
+var STEP_RESULT_PREFIX = "__AC_STEP_RESULT__";
+function stepResultLinePrefix(token) {
+  return `${STEP_RESULT_PREFIX}${token}:`;
+}
+var RUNNER_BUNDLE_PATH = "/tmp/runner.bundle.js";
+var RUNNER_COMMAND = `node ${RUNNER_BUNDLE_PATH}`;
+var STEP_ENV = {
+  RUN_ID: "RUN_ID",
+  STEP_MODE: "AC_STEP_MODE",
+  STEP_INDEX: "AC_STEP_INDEX",
+  STEP_INPUT_PATH: "AC_STEP_INPUT_PATH",
+  REQUEST_CONTEXT_PATH: "AC_REQUEST_CONTEXT_PATH",
+  STEP_RESULT_TOKEN: "AC_STEP_RESULT_TOKEN"
+};
+function stepInputPath(stepIndex) {
+  return `/tmp/wf/step-input-${stepIndex}.json`;
+}
+function requestContextPath(stepIndex) {
+  return `/tmp/wf/request-context-${stepIndex}.json`;
+}
+// src/step-invocation/invoker.ts
+import { randomBytes } from "node:crypto";
+function buildStepEnvs(args) {
+  return {
+    [STEP_ENV.RUN_ID]: args.runId,
+    [STEP_ENV.STEP_MODE]: "1",
+    [STEP_ENV.STEP_INDEX]: String(args.stepIndex),
+    [STEP_ENV.STEP_INPUT_PATH]: stepInputPath(args.stepIndex),
+    [STEP_ENV.REQUEST_CONTEXT_PATH]: requestContextPath(args.stepIndex),
+    [STEP_ENV.STEP_RESULT_TOKEN]: args.resultToken
+  };
+}
+function parseStepResult(stdout, resultToken) {
+  const prefix = stepResultLinePrefix(resultToken);
+  const line = stdout.split(/\r?\n/).find((l) => l.startsWith(prefix));
+  if (!line)
+    return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(line.slice(prefix.length));
+  } catch {
+    return { ok: false, error: { kind: "protocol", message: "step result JSON parse failed" } };
+  }
+  if (parsed.ok) {
+    return parsed.observability ? { ok: true, output: parsed.output, observability: parsed.observability } : { ok: true, output: parsed.output };
+  }
+  const kind = parsed.kind === "user-step" ? "user-step" : "protocol";
+  const baseMessage = parsed.error ?? "step body failed without a message";
+  const message = parsed.kind && parsed.kind !== "user-step" && parsed.kind !== "protocol" ? `(unknown kind "${parsed.kind}") ${baseMessage}` : baseMessage;
+  return { ok: false, error: { kind, message } };
+}
+async function invokeStep(sandbox, request, opts) {
+  const resultToken = randomBytes(16).toString("hex");
+  await Promise.all([
+    sandbox.files.write(stepInputPath(request.stepIndex), JSON.stringify(request.input)),
+    sandbox.files.write(requestContextPath(request.stepIndex), JSON.stringify(request.requestContext))
+  ]);
+  const envs = {
+    ...opts?.envs ?? {},
+    ...buildStepEnvs({
+      runId: request.runId,
+      stepIndex: request.stepIndex,
+      resultToken
+    })
+  };
+  const sentinelPrefix = stepResultLinePrefix(resultToken);
+  const makeLineSplitter = (sink, filterSentinel) => {
+    if (!sink)
+      return { onChunk: undefined, flush: () => {} };
+    let buf = "";
+    return {
+      onChunk: (chunk) => {
+        buf += chunk;
+        let nl;
+        while ((nl = buf.indexOf(`
+`)) !== -1) {
+          const line = buf.slice(0, nl);
+          buf = buf.slice(nl + 1);
+          if (filterSentinel && line.startsWith(sentinelPrefix))
+            continue;
+          sink(line);
         }
+      },
+      flush: () => {
+        if (buf.length === 0)
+          return;
+        const line = buf;
+        buf = "";
+        if (filterSentinel && line.startsWith(sentinelPrefix))
+          return;
+        sink(line);
+      }
+    };
+  };
+  const stdoutSplitter = makeLineSplitter(opts?.onStdout, true);
+  const stderrSplitter = makeLineSplitter(opts?.onStderr, false);
+  const result = await sandbox.commands.run(RUNNER_COMMAND, {
+    envs,
+    timeoutMs: 0,
+    ...stdoutSplitter.onChunk ? { onStdout: stdoutSplitter.onChunk } : {},
+    ...stderrSplitter.onChunk ? { onStderr: stderrSplitter.onChunk } : {}
+  });
+  stdoutSplitter.flush();
+  stderrSplitter.flush();
+  const parsed = parseStepResult(result.stdout, resultToken);
+  if (parsed)
+    return parsed;
+  if (result.exitCode !== 0) {
+    return {
+      ok: false,
+      error: {
+        kind: "runner-exit",
+        message: `runner subprocess exited ${result.exitCode} before emitting a step result`,
+        exitCode: result.exitCode
       }
-    }, sandbox);
+    };
+  }
+  return {
+    ok: false,
+    error: { kind: "protocol", message: "no tokenised step result found on stdout" }
+  };
+}
+// src/step-invocation/server.ts
+import { readFileSync } from "node:fs";
+function emitResult(token, payload) {
+  return new Promise((resolve, reject) => {
+    const line = `${STEP_RESULT_PREFIX}${token}:${JSON.stringify(payload)}
+`;
+    process.stdout.write(line, (err) => {
+      if (err)
+        reject(err);
+      else
+        resolve();
+    });
+  });
+}
+function scrubProtocolEnvs() {
+  for (const key of [
+    STEP_ENV.STEP_MODE,
+    STEP_ENV.STEP_INDEX,
+    STEP_ENV.STEP_INPUT_PATH,
+    STEP_ENV.REQUEST_CONTEXT_PATH,
+    STEP_ENV.STEP_RESULT_TOKEN
+  ]) {
+    delete process.env[key];
+  }
+}
+async function serveStep(handler) {
+  const token = process.env[STEP_ENV.STEP_RESULT_TOKEN];
+  if (!token) {
+    process.stderr.write(`[step-server] missing ${STEP_ENV.STEP_RESULT_TOKEN}
+`);
+    process.exit(1);
+  }
+  let exitCode = 0;
+  let payload;
+  let setupResult;
+  try {
+    const runId = process.env[STEP_ENV.RUN_ID];
+    const stepIndexEnv = process.env[STEP_ENV.STEP_INDEX];
+    const inputPath = process.env[STEP_ENV.STEP_INPUT_PATH];
+    const ctxPath = process.env[STEP_ENV.REQUEST_CONTEXT_PATH];
+    const stepIndex = stepIndexEnv === undefined ? Number.NaN : Number(stepIndexEnv);
+    if (!runId || !inputPath || !ctxPath || !Number.isFinite(stepIndex)) {
+      throw new Error(`step-server missing required env: ${[
+        !runId && STEP_ENV.RUN_ID,
+        !Number.isFinite(stepIndex) && STEP_ENV.STEP_INDEX,
+        !inputPath && STEP_ENV.STEP_INPUT_PATH,
+        !ctxPath && STEP_ENV.REQUEST_CONTEXT_PATH
+      ].filter(Boolean).join(", ")}`);
+    }
+    const input = JSON.parse(readFileSync(inputPath, "utf8"));
+    const requestContext = JSON.parse(readFileSync(ctxPath, "utf8"));
+    setupResult = { runId, stepIndex, input, requestContext };
   } catch (err) {
-    workflowErr = err;
+    exitCode = 1;
+    payload = { ok: false, kind: "protocol", error: err instanceof Error ? err.message : String(err) };
+  }
+  if (setupResult) {
+    scrubProtocolEnvs();
+    try {
+      const { output, observability } = await handler(setupResult);
+      payload = observability ? { ok: true, output, observability } : { ok: true, output };
+    } catch (err) {
+      exitCode = 1;
+      payload = { ok: false, kind: "user-step", error: err instanceof Error ? err.message : String(err) };
+    }
   }
-  if (workflowErr !== undefined) {
-    if (workflowErr instanceof WorkflowError)
-      throw workflowErr;
-    throw new WorkflowError(formatError(workflowErr), { cause: workflowErr });
+  await emitResult(token, payload);
+  process.exit(exitCode);
+}
+// src/step-invocation/types.ts
+class StepExecutionError extends Error {
+  kind;
+  exitCode;
+  constructor(error, stepLabel) {
+    super(`[${error.kind}] ${stepLabel}: ${error.message}`);
+    this.name = "StepExecutionError";
+    this.kind = error.kind;
+    this.exitCode = error.kind === "runner-exit" ? error.exitCode : undefined;
   }
-  return { response: wfOutput ?? null };
 }
 // src/agent/run-agent.ts
-import { z as z3 } from "zod";
+import { z as z6 } from "zod";
 
 // src/agent/protocol-suffix.md
 var protocol_suffix_default = '## Status Signal\n\nWhen you have finished your work or are blocked, emit a `<status>` block at the end of your response:\n\n```json\n<status>\n{\n  "summary": "one sentence describing what was done or what is blocking",\n  "completed": ["each acceptance criterion that is now fully met"],\n  "blockers": [],\n  "changed_files": ["relative/path/to/file"],\n  "tests_run": true,\n  "exit_signal": true\n}\n</status>\n```\n\n**Field semantics:**\n- `summary`: one sentence — what was accomplished or what is blocking\n- `completed`: acceptance criteria items that are fully done — be specific\n- `blockers`: non-empty when `exit_signal: false` — describe the exact obstacle\n- `changed_files`: relative paths of files you created or modified\n- `tests_run`: `true` if you ran any test suite (pass or fail); `false` if no tests exist or you skipped them\n- `exit_signal: true` — set when ALL acceptance criteria are met and no blockers remain\n- `exit_signal: false` — set when blocked or unfinished; `blockers` must be non-empty\n\n**If you are still actively working** and have not reached a natural stopping point, do NOT emit a `<status>` block — just keep working.\n\n**Example (done):**\n\n```json\n<status>\n{\n  "summary": "Added input validation middleware to /api/tasks with tests",\n  "completed": ["POST /api/tasks validates required fields", "Returns 400 with details on invalid input", "Unit tests passing"],\n  "blockers": [],\n  "changed_files": ["src/middleware/validate.ts", "src/routes/tasks.ts", "tests/validate.test.ts"],\n  "tests_run": true,\n  "exit_signal": true\n}\n</status>\n```\n\n**Example (blocked):**\n\n```json\n<status>\n{\n  "summary": "Implemented middleware but tests are failing due to module resolution",\n  "completed": ["Middleware created and wired into route"],\n  "blockers": ["Tests fail: cannot resolve import \'./validate\' — module resolution config unclear"],\n  "changed_files": ["src/middleware/validate.ts"],\n  "tests_run": true,\n  "exit_signal": false\n}\n</status>\n```\n';
@@ -1119,33 +2287,30 @@ function stripFrontmatter(content) {
 ---`, 3);
   return end === -1 ? content : content.slice(end + 4).trimStart();
 }
-function inject(template, vars) {
-  return Object.entries(vars).reduce((t, [k, v]) => t.replaceAll(`{{${k}}}`, v), template);
-}
 function zodTypeName(schema) {
-  if (schema instanceof z3.ZodString)
+  if (schema instanceof z6.ZodString)
     return "string";
-  if (schema instanceof z3.ZodNumber)
+  if (schema instanceof z6.ZodNumber)
     return "number";
-  if (schema instanceof z3.ZodBoolean)
+  if (schema instanceof z6.ZodBoolean)
     return "boolean";
-  if (schema instanceof z3.ZodArray)
+  if (schema instanceof z6.ZodArray)
     return `${zodTypeName(schema.element)}[]`;
-  if (schema instanceof z3.ZodEnum)
+  if (schema instanceof z6.ZodEnum)
     return schema.options.map((o) => `"${o}"`).join(" | ");
-  if (schema instanceof z3.ZodOptional)
+  if (schema instanceof z6.ZodOptional)
     return `${zodTypeName(schema.unwrap())} (optional)`;
-  if (schema instanceof z3.ZodNullable)
+  if (schema instanceof z6.ZodNullable)
     return `${zodTypeName(schema.unwrap())} | null`;
-  if (schema instanceof z3.ZodLiteral)
+  if (schema instanceof z6.ZodLiteral)
     return `"${String(schema.value)}"`;
-  if (schema instanceof z3.ZodObject)
+  if (schema instanceof z6.ZodObject)
     return "object";
   return "any";
 }
 function buildResponseFormatAppendix(schema) {
   const header = ["## Response Format", "", "When you emit `exit_signal: true` in your `<status>` block, also include a `<response>` block containing JSON immediately after `<status>`:", ""];
-  const shape = schema instanceof z3.ZodObject ? schema.shape : null;
+  const shape = schema instanceof z6.ZodObject ? schema.shape : null;
   const body = shape ? (() => {
     const entries = Object.entries(shape);
     const example = Object.fromEntries(entries.map(([k, v]) => [k, `<${zodTypeName(v)}>`]));
@@ -1170,11 +2335,11 @@ function buildResponseFormatAppendix(schema) {
   return [...header, ...body].join(`
 `);
 }
-async function runAgent(opts) {
+async function agent(opts) {
   const workingDir = opts.workingDir ?? "";
-  const promptVars = { WORKING_DIR: workingDir, DIFF_BASE: "HEAD~1", ...opts.promptVars };
   return agentLoop({
     runtime: (runtimeOpts) => opts.runtime.create(opts.sandbox, runtimeOpts),
+    ...opts.agentId !== undefined ? { agentId: opts.agentId } : {},
     ...opts.label !== undefined ? { label: opts.label } : {},
     ...opts.budget?.turnsPerIteration !== undefined ? { turnsPerIteration: opts.budget.turnsPerIteration } : {},
     ...opts.budget?.maxIterations !== undefined ? { maxIterations: opts.budget.maxIterations } : {},
@@ -1184,7 +2349,7 @@ async function runAgent(opts) {
     buildPrompt: (_lastStatus, iteration) => {
       if (iteration > 0)
         return PROTOCOL_SUFFIX;
-      const base = inject(stripFrontmatter(opts.prompt), promptVars);
+      const base = stripFrontmatter(opts.prompt);
       return opts.responseSchema ? `${base}
 
 ${PROTOCOL_SUFFIX}
@@ -1193,8 +2358,20 @@ ${buildResponseFormatAppendix(opts.responseSchema)}` : `${base}
 
 ${PROTOCOL_SUFFIX}`;
     },
+    ...opts.events ? { onAgentLifecycleEvent: (event) => {
+      opts.events?.emit(event);
+    } } : {},
     ...opts.onAgentEvent ? { onAgentEvent: opts.onAgentEvent } : {},
-    ...opts.onIteration ? { onIteration: opts.onIteration } : {}
+    ...opts.onIteration ? { onIteration: opts.onIteration } : {},
+    ...opts.processors?.length ? { processors: opts.processors } : {},
+    requestContext: opts.requestContext ?? RequestContext.fromReserved({
+      teamId: "",
+      runId: "",
+      workflowId: "",
+      factoryId: null,
+      apiKeyScopes: [],
+      parentRunId: null
+    })
   });
 }
 // src/runtimes/openai-desktop.ts