@agent-compose/sdk 0.2.2 → 0.2.4

package/dist/workflows/invoke-child.d.ts

@@ -0,0 +1,10 @@
+import type { WorkflowCtx } from "../types/workflow.js";
+/**
+ * Build the public-API child workflow invoker used by legacy and sandboxed
+ * workflow execution. Provider-backed engines may inject a different
+ * implementation (Temporal child workflow, Inngest invoke, etc.).
+ */
+export declare function buildInvokeChild(runId: string, opts?: {
+    fallbackBaseUrl?: string;
+    defaultFactorySlug?: string;
+}): WorkflowCtx["invokeChild"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {
@@ -22,6 +22,12 @@
       "types": "./dist/runtimes/openai-desktop.d.ts",
       "import": "./dist/runtimes/openai-desktop.js",
       "default": "./dist/runtimes/openai-desktop.js"
+    },
+    "./runtimes/vercel": {
+      "bun": "./src/runtimes/vercel.ts",
+      "types": "./dist/runtimes/vercel.d.ts",
+      "import": "./dist/runtimes/vercel.js",
+      "default": "./dist/runtimes/vercel.js"
     }
   },
   "files": [
@@ -37,12 +43,12 @@
     "node": ">=20"
   },
   "scripts": {
-    "typecheck":      "tsc --noEmit",
-    "test":           "vitest run src/__tests__",
-    "build":          "bun run build:js && bun run build:types",
-    "build:js":       "bun build src/index.ts src/runtimes/openai-desktop.ts --outdir dist --target node --format esm --packages external",
-    "build:types":    "tsc -p tsconfig.build.json",
-    "clean":          "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run src",
+    "build": "bun run build:js && bun run build:types",
+    "build:js": "bun build src/index.ts src/runtimes/openai-desktop.ts src/runtimes/vercel.ts --outdir dist --target node --format esm --packages external",
+    "build:types": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
     "prepublishOnly": "bun run clean && bun run build"
   },
   "peerDependencies": {
@@ -50,17 +56,21 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.15",
-    "typescript":  "^5.8.0",
-    "vitest":      "^3.0.0"
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
   },
   "dependencies": {
-    "@e2b/desktop":    "^1.1.2",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.129",
+    "@babel/parser": "^7.29.3",
+    "@babel/types": "^7.29.0",
+    "@e2b/desktop": "^1.1.2",
     "@vercel/sandbox": "^1.10.0",
-    "e2b":             "^2.3.0",
-    "ofetch":          "^1.5.1",
-    "openai":          "^6.33.0",
-    "p-retry":         "^6.2.0",
-    "sharp":           "^0.34.5"
+    "ai": "^6.0.175",
+    "e2b": "^2.3.0",
+    "ofetch": "^1.5.1",
+    "openai": "^6.33.0",
+    "p-retry": "^6.2.0",
+    "sharp": "^0.34.5"
   },
   "publishConfig": {
     "access": "public"

package/src/agent/agent-loop.ts

@@ -7,11 +7,16 @@ import type { RuntimeOptions, ModelExecutionContract } from "../index.js";
 import { z } from "zod";
 import { AgentStatusSchema, parseAgentResponse } from "./protocol.js";
 import type { AgentStatus, AgentMessage } from "./protocol.js";
+import { randomUUID } from "node:crypto";
+import type { Processor, ProcessorContext } from "../processors/processor.js";
+import { runProcessorChain } from "../processors/runner.js";
+import { RequestContext } from "../request-context/request-context.js";
 
 export const DEFAULT_CLAUDE_MODEL = "claude-opus-4-7";
 
 const SAME_BLOCKER_ITERATIONS = 3;
 const STALL_ITERATIONS        = 3;
+const MESSAGE_PREVIEW_CHARS   = 400;
 
 export function parseAgentStatus(text: string): AgentStatus | null {
   const match = text.match(/<status>([\s\S]*?)<\/status>/);
@@ -24,86 +29,239 @@ export function parseAgentStatus(text: string): AgentStatus | null {
 
 const DEFAULT_ALLOWED_TOOLS = ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "WebFetch"];
 
-export interface AgentLoopResult {
+export interface AgentLoopResult<TResponse = unknown> {
+  agentId:     string;
+  label:       string;
   sessionId:   string;
   lastStatus:  AgentStatus | null;
   iterations:  number;
-  response?:   unknown;
+  response?:   TResponse;
 }
 
-export async function agentLoop(opts: {
+export type AgentMessageSummary =
+  | { type: "init"; sessionId: string }
+  | { type: "text"; text: string }
+  | { type: "thinking"; text: string }
+  | { type: "tool_use"; toolName: string; toolUseId: string; toolInputPreview: string }
+  | { type: "tool_result"; toolUseId: string; output: string; isError: boolean }
+  | { type: "usage"; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheCreationTokens: number; durationMs: number; numTurns: number }
+  | { type: "done"; sessionId: string }
+  | { type: "error"; text: string };
+
+function truncate(value: string): string {
+  return value.length > MESSAGE_PREVIEW_CHARS ? `${value.slice(0, MESSAGE_PREVIEW_CHARS)}…` : value;
+}
+
+function preview(value: unknown): string {
+  try {
+    return truncate(JSON.stringify(value));
+  } catch {
+    return truncate(String(value));
+  }
+}
+
+export function summarizeAgentMessage(msg: AgentMessage): AgentMessageSummary {
+  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) };
+  }
+}
+
+export type AgentLifecycleEvent =
+  | { event: "agent.spawned"; at: number; agentId: string; label: string; allowedTools?: string[] }
+  | { event: "agent.message"; at: number; agentId: string; label: string; iteration: number; message: AgentMessageSummary }
+  | { event: "agent.iteration"; at: number; agentId: string; label: string; iteration: number; status: AgentStatus | null }
+  | { event: "agent.settled"; at: number; agentId: string; label: string; outcome: "success" | "failed"; iterations: number; durationMs: number; failureReason?: string };
+
+export interface AgentLoopOpts<TResponse = unknown> {
+  agentId?: string;
   label?: string;
+  onAgentLifecycleEvent?: (event: AgentLifecycleEvent) => void;
   onIteration?: (iteration: number, status: AgentStatus | null) => void;
   turnsPerIteration?: number;
   maxIterations?: number;
   buildPrompt: (lastStatus: AgentStatus | null, iteration: number) => string;
   onAgentEvent?: (iteration: number, msg: AgentMessage) => void;
   allowedTools?: string[];
-  responseSchema?: z.ZodType<unknown>;
+  responseSchema?: z.ZodType<TResponse>;
   runtime?: (opts: RuntimeOptions) => ModelExecutionContract;
   cwd?: string;
-}): Promise<AgentLoopResult> {
-  const label              = opts.label ?? "[Agent Loop]";
+  /** Processor chain — see sdk/src/processors. Runs sequentially around
+   *  prompts and emitted messages. Tool-call gating is a no-op until a
+   *  runtime that exposes a pre-tool-use seam is wired (candidate #1). */
+  processors?: readonly Processor[];
+  /** Per-run typed bag — propagated to every processor as `ctx.requestContext`. */
+  requestContext?: RequestContext;
+}
+
+export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TResponse>): Promise<AgentLoopResult<TResponse>> {
+  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: number): ProcessorContext => ({
+    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,
+    label: logLabel,
     cwd:          opts.cwd,
+    processors,
+    requestContext,
+    agentId,
+    ...(opts.responseSchema ? { outputFormat: { type: "json_schema" as const, schema: z.toJSONSchema(opts.responseSchema) as Record<string, unknown> } } : {}),
   });
 
+  // Heads-up when a caller registers tool-call gating on a runtime that
+  // can't honour it. Better to surface this once at start than have users
+  // wonder why their `denyTools(...)` never fires.
+  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\n`,
+    );
+  }
+
   let lastSessionId          = "";
   let lastStatus: AgentStatus | null = null;
   let iterationsWithoutStatus = 0;
   let blockerStreak: { key: string; count: number } | null = 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 prompt = opts.buildPrompt(lastStatus, iteration);
-    process.stderr.write(`${label} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration} turns\n`);
+    const procCtx = buildProcCtx(iteration + 1);
+    const initialPrompt = opts.buildPrompt(lastStatus, iteration);
+
+    // processInput chain — deny ends the loop; abort ends the loop.
+    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;
+
+    // Progress, not an error — write to stdout so dashboards and
+    // log viewers don't visually flag it as a warning.
+    process.stdout.write(`${logLabel} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration} turns\n`);
 
     let responseText = "";
-    for await (const msg of client.sendMessage({ prompt, sessionId: iteration > 0 ? lastSessionId : undefined })) {
+    for await (const rawMsg of client.sendMessage({ prompt, sessionId: iteration > 0 ? lastSessionId : undefined, iteration: iteration + 1 })) {
+      // processOutput chain — deny drops the message from accumulation;
+      // abort ends the loop. Continue carries the (possibly mutated)
+      // message forward.
+      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}\n`);
+        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}`);
     }
-    process.stdout.write("\n");
+    // (No trailing newline here — the dashboard renders each stdout
+    // write as its own log row, so a bare "\n" produces an empty
+    // STDOUT row between agent iterations. The visual gap was meant
+    // for interactive TTYs and is just noise in structured logs.)
+    lastResponseText = responseText;
 
     let status = parseAgentStatus(responseText);
-    process.stderr.write(`\n${label} iteration ${iteration + 1} status: exit_signal=${status?.exit_signal ?? "(no status)"} blockers=${JSON.stringify(status?.blockers ?? [])}\n`);
+    // Parse the response once per iteration; both the schema fast path
+    // below and the exit-signal-driven validation a few lines down
+    // need the same parsed payload. `null` when there's no <response>
+    // block AND no top-level JSON object.
+    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 };
+        // Successful schema-validation is progress, not a warning.
+        process.stdout.write(`${logLabel} structured response validated after ${iteration + 1}/${maxIterations} iterations\n`);
+        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;
+    // Per-iteration status is informational progress. The presence
+    // of blockers in the JSON is just data — the operator decides
+    // whether to be alarmed by it. Writing to stderr made the line
+    // visually flag as a warning even on clean runs (blockers=[]).
+    process.stdout.write(`${logLabel} iteration ${iteration + 1} status: exit_signal=${status?.exit_signal ?? "(no status)"} blockers=${JSON.stringify(status?.blockers ?? [])}\n`);
     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: unknown = status;
+      let response: AgentStatus | TResponse = status;
       if (opts.responseSchema) {
-        const raw = parseAgentResponse(responseText);
-        if (raw === null) {
-          process.stderr.write(`\n${label} NO <response> BLOCK — response tail: ${responseText.slice(-400)}\n`);
+        if (rawResponse === null) {
+          process.stderr.write(`${logLabel} NO <response> BLOCK — response tail: ${responseText.slice(-400)}\n`);
           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 as object) });
+        // Status-merged validation — the schema may reference status
+        // fields (`exit_signal`, `blockers`, …) the agent emitted in a
+        // separate <status> block. Distinct from the fast path above,
+        // which validates the raw response alone.
+        const parsed = opts.responseSchema.safeParse({ ...status, ...(rawResponse as object) });
         if (!parsed.success) {
-          process.stderr.write(`\n${label} <response> SCHEMA FAILED: ${parsed.error.message}\nraw: ${JSON.stringify(raw).slice(0, 400)}\n`);
+          lastResponseValidationError = parsed.error.message;
+          process.stderr.write(`${logLabel} <response> SCHEMA FAILED: ${parsed.error.message}\nraw: ${JSON.stringify(rawResponse).slice(0, 400)}\n`);
           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\n`);
-      return { sessionId: lastSessionId, lastStatus: status, iterations: iteration + 1, response };
+      // Settled successfully — progress, not a warning.
+      process.stdout.write(`${logLabel} done after ${iteration + 1}/${maxIterations} iterations\n`);
+      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: response as TResponse };
     }
 
     if (!status) {
       if (++iterationsWithoutStatus >= STALL_ITERATIONS)
-        throw new Error(`${label} stalled: no <status> block after ${iterationsWithoutStatus} iterations`);
+        throw new Error(`${logLabel} stalled: no <status> block after ${iterationsWithoutStatus} iterations`);
     } else {
       iterationsWithoutStatus = 0;
     }
@@ -112,7 +270,7 @@ export async function agentLoop(opts: {
       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]}"`);
+          throw new Error(`${logLabel} circuit break: same blocker repeated ${blockerStreak.count}x — "${status.blockers[0]}"`);
       } else {
         blockerStreak = { key, count: 1 };
       }
@@ -121,11 +279,24 @@ export async function agentLoop(opts: {
     }
 
     if (iteration + 1 < maxIterations)
-      process.stderr.write(`${label} continuing to iteration ${iteration + 2}/${maxIterations}\n`);
+      // Loop continuation — progress.
+      process.stdout.write(`${logLabel} continuing to iteration ${iteration + 2}/${maxIterations}\n`);
   }
 
   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\n`);
-  return { sessionId: lastSessionId, lastStatus, iterations: maxIterations };
+    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\n`);
+  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: string): unknown {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) return null;
+  try { return JSON.parse(trimmed); }
+  catch { return null; }
 }

package/src/agent/run-agent.ts

@@ -1,10 +1,9 @@
 /**
- * runAgent — canonical entry point for embedding an LLM agent inside a
+ * agent — canonical entry point for embedding an LLM agent inside a
  * workflow. The workflow's `run()` body calls it; the loop executes
  * against the runner's own VM.
  *
  * Glue packaged so workflows don't duplicate it:
- *   - Inject `{{VAR}}` placeholders into the prompt template.
  *   - Strip the `--- frontmatter ---` header authors use for IDE hints.
  *   - Append PROTOCOL_SUFFIX (status/response format instructions).
  *   - Append a response-format appendix when `responseSchema` is set.
@@ -13,11 +12,13 @@
 
 import { z } from "zod";
 import { agentLoop } from "./agent-loop.js";
-import type { AgentLoopResult } from "./agent-loop.js";
+import type { AgentLifecycleEvent, AgentLoopResult } from "./agent-loop.js";
 import type { AgentMessage, AgentStatus } from "../types/protocol.js";
 import type { AgentRuntime, RuntimeOptions } from "../types/runtime.js";
 import type { SandboxProvider } from "../types/sandbox.js";
 import type { AgentBudget } from "../types/workflow.js";
+import type { Processor } from "../processors/processor.js";
+import { RequestContext } from "../request-context/request-context.js";
 import PROTOCOL_SUFFIX_RAW from "./protocol-suffix.md" with { type: "text" };
 
 const PROTOCOL_SUFFIX = stripFrontmatter(PROTOCOL_SUFFIX_RAW);
@@ -28,10 +29,6 @@ function stripFrontmatter(content: string): string {
   return end === -1 ? content : content.slice(end + 4).trimStart();
 }
 
-function inject(template: string, vars: Record<string, string>): string {
-  return Object.entries(vars).reduce((t, [k, v]) => t.replaceAll(`{{${k}}}`, v), template);
-}
-
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function zodTypeName(schema: any): string {
   if (schema instanceof z.ZodString)   return "string";
@@ -74,7 +71,9 @@ function buildResponseFormatAppendix(schema: z.ZodType<any>): string {
   return [...header, ...body].join("\n");
 }
 
-export interface RunAgentOpts<T = unknown> {
+export interface AgentOpts<T = unknown> {
+  /** Stable system identity for this agent loop. Generated when omitted. */
+  agentId?: string;
   /** Sandbox the runtime executes commands against. Inside a workflow,
    *  always pass `ctx.sandbox` — a pre-constructed local provider for
    *  the runner's own VM. Exposed as a parameter so tests and non-workflow
@@ -82,12 +81,9 @@ export interface RunAgentOpts<T = unknown> {
   sandbox: SandboxProvider;
   /** Runtime definition from `createClaudeRuntime({...})` (or custom). */
   runtime: AgentRuntime;
-  /** Prompt template. Authors can include YAML-style `--- frontmatter ---`
+  /** Prompt text. Authors can include YAML-style `--- frontmatter ---`
    *  at the top for IDE hints; it's stripped before the model sees it. */
   prompt: string;
-  /** Substitution map for `{{VAR}}` placeholders in the prompt. `WORKING_DIR`
-   *  and `DIFF_BASE` auto-populate from `opts.workingDir` unless overridden. */
-  promptVars?: Record<string, string>;
   /** `cwd` forwarded to the runtime — every shell command runs here. */
   workingDir?: string;
   /** Tools the model may use. Defaults to a safe kitchen-sink set inside
@@ -101,12 +97,35 @@ export interface RunAgentOpts<T = unknown> {
   responseSchema?: z.ZodType<T>;
   /** Label prefix for runtime stderr ("[sbid][agent]" by default). */
   label?: string;
+  /** Lifecycle event sink from workflow ctx. Emits agent.spawned / iteration / settled. */
+  events?: { emit: (event: AgentLifecycleEvent) => void | Promise<void> };
   /** Per-message event callback — wire this to your workflow's event
    *  telemetry if you want per-tool-call observability. */
   onAgentEvent?: (iteration: number, msg: AgentMessage) => void;
   /** Per-iteration status callback — fires after each model turn with the
    *  parsed `<status>` block (or null if the model didn't emit one). */
   onIteration?: (iteration: number, status: AgentStatus | null) => void;
+  /**
+   * Processors run as a typed pre/post pipeline around the agent loop:
+   *   - processInput before each iteration's prompt is sent
+   *   - processOutput on each emitted message
+   *   - processToolCall before each tool call (runtime-driven; dormant
+   *     until a runtime that supports pre-tool gating is wired in)
+   *
+   * Common pattern with workflow-level defaults:
+   *   agent({ processors: [...ctx.processors, mySpecific], ... })
+   */
+  processors?: readonly Processor[];
+  /**
+   * Per-run request context. Passed through to processors as
+   * `ctx.requestContext`; carries tenant identity (teamId, factoryId, scopes)
+   * and the freeform user namespace.
+   *
+   * Inside a workflow, pass `ctx.requestContext`. Tests/non-workflow callers
+   * can omit; a degenerate context is synthesised so processors that don't
+   * read identity (e.g. redactPattern) still work.
+   */
+  requestContext?: RequestContext;
 }
 
 /**
@@ -114,12 +133,12 @@ export interface RunAgentOpts<T = unknown> {
  * `AgentLoopResult`, including `response` when a `responseSchema` was
  * supplied and the model validated against it.
  */
-export async function runAgent<T = unknown>(opts: RunAgentOpts<T>): Promise<AgentLoopResult> {
+export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopResult<T>> {
   const workingDir = opts.workingDir ?? "";
-  const promptVars = { WORKING_DIR: workingDir, DIFF_BASE: "HEAD~1", ...opts.promptVars };
 
   return agentLoop({
     runtime: (runtimeOpts: RuntimeOptions) => 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 }     : {}),
@@ -130,12 +149,18 @@ export async function runAgent<T = unknown>(opts: RunAgentOpts<T>): Promise<Agen
       // Mid-loop: session resumes via --resume, model has history; only the
       // protocol suffix is needed so tool-use + status block grammar stays fresh.
       if (iteration > 0) return PROTOCOL_SUFFIX;
-      const base = inject(stripFrontmatter(opts.prompt), promptVars);
+      const base = stripFrontmatter(opts.prompt);
       return opts.responseSchema
         ? `${base}\n\n${PROTOCOL_SUFFIX}\n\n${buildResponseFormatAppendix(opts.responseSchema)}`
         : `${base}\n\n${PROTOCOL_SUFFIX}`;
     },
+    ...(opts.events ? { onAgentLifecycleEvent: (event: AgentLifecycleEvent) => { void opts.events?.emit(event); } } : {}),
     ...(opts.onAgentEvent ? { onAgentEvent: opts.onAgentEvent } : {}),
     ...(opts.onIteration  ? { onIteration:  opts.onIteration  } : {}),
+    ...(opts.processors?.length ? { processors: opts.processors } : {}),
+    requestContext: opts.requestContext ?? RequestContext.fromReserved({
+      teamId: "", runId: "", workflowId: "",
+      factoryId: null, apiKeyScopes: [], parentRunId: null,
+    }),
   });
 }