@agent-compose/sdk 0.2.3 → 0.2.4

package/src/sandbox.ts

@@ -11,9 +11,11 @@ import { spawn } from "node:child_process";
 import { Sandbox } from "e2b";
 import { Sandbox as Desktop } from "@e2b/desktop";
 import pRetry from "p-retry";
-import type { SandboxProvider, DesktopSandboxProvider } from "./types/sandbox.js";
+import type { SandboxProvider, DesktopSandboxProvider, SandboxCommandResult } from "./types/sandbox.js";
 
-export type { SandboxProvider, DesktopSandboxProvider } from "./types/sandbox.js";
+export type { SandboxProvider, DesktopSandboxProvider, SandboxCommandRunOptions, SandboxCommandResult } from "./types/sandbox.js";
+
+export type SandboxProviderName = "vercel" | "e2b" | "e2b-desktop";
 
 // Fleet-wide tag, NOT machine-scoped. Previously we embedded FLY_MACHINE_ID
 // so each replica scoped its own E2B sandboxes at boot, but that made
@@ -37,12 +39,25 @@ const VERCEL_VM_LIFETIME_WINDOW_MS = 6 * 60 * 60 * 1000;
  * firewall injects the specified headers before forwarding — credentials never
  * exist inside the VM. E2B ignores this field (future self-hosted mapping TBD).
  */
+export interface SandboxNetworkHeaderTransform {
+  headers?: Record<string, string>;
+}
+
+export interface SandboxNetworkAllowRule {
+  transform?: SandboxNetworkHeaderTransform[];
+}
+
+export interface SandboxNetworkSubnetPolicy {
+  allow?: string[];
+  deny?: string[];
+}
+
 export type SandboxNetworkPolicy =
   | "allow-all"
   | "deny-all"
   | {
-      allow?: string[] | Record<string, Array<{ transform?: Array<{ headers?: Record<string, string> }> }>>;
-      subnets?: { allow?: string[]; deny?: string[] };
+      allow?: string[] | Record<string, SandboxNetworkAllowRule[]>;
+      subnets?: SandboxNetworkSubnetPolicy;
     };
 
 export interface SandboxCreateOpts {
@@ -103,7 +118,14 @@ interface SandboxProviderDef {
 // ── E2B helpers ───────────────────────────────────────────────────────────────
 
 export function makeSandboxProvider(sb: Sandbox | Desktop): SandboxProvider {
-  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(),
+  };
 }
 
 export function makeDesktopSandboxProvider(sb: Desktop): DesktopSandboxProvider {
@@ -126,14 +148,19 @@ export function makeDesktopSandboxProvider(sb: Desktop): DesktopSandboxProvider
 
 type SseEvent = { type: string; data?: string; exitCode?: number };
 
+export interface ParseSseExecStreamOptions {
+  onStdout?: (data: string) => void;
+  onStderr?: (data: string) => void;
+}
+
 /**
  * Parse an SSE exec stream from a ReadableStream.
  * Used by the agent sandbox broker in runner.ts.
  */
 export async function parseSseExecStream(
   body: ReadableStream<Uint8Array>,
-  opts?: { onStdout?: (d: string) => void; onStderr?: (d: string) => void },
-): Promise<{ exitCode: number; stdout: string }> {
+  opts?: ParseSseExecStreamOptions,
+): Promise<SandboxCommandResult> {
   let stdout = "", exitCode = 0, exited = false;
   const reader = body.getReader(), decoder = new TextDecoder();
   let buf = "";
@@ -175,7 +202,8 @@ function makeVercelSandboxProvider(sb: any, globalEnvs?: Record<string, string>)
       async run(cmd, opts) {
         if (opts?.background) {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          void (sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts.cwd, env: mergeEnvs(opts.envs), detached: true }) as Promise<any>).catch(() => {});
+          void (sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts.cwd, env: mergeEnvs(opts.envs), detached: true }) as Promise<any>)
+            .catch((err: unknown) => 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;
@@ -334,7 +362,7 @@ const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef> = {
       const sandboxes = [];
       while (paginator.hasNext) 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,
@@ -364,7 +392,7 @@ const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef> = {
 };
 
 /** Provision a sandbox for the named provider. */
-export async function createSandbox(provider: string, opts: SandboxCreateOpts): Promise<SandboxProvider> {
+export async function createSandbox(provider: SandboxProviderName, opts: SandboxCreateOpts): Promise<SandboxProvider> {
   const def = SANDBOX_PROVIDERS[provider];
   if (!def) throw new Error(`Unknown sandbox provider: "${provider}". Known: ${Object.keys(SANDBOX_PROVIDERS).join(", ")}`);
   const missing = Object.entries(def.requiredEnv)
@@ -375,14 +403,14 @@ export async function createSandbox(provider: string, opts: SandboxCreateOpts):
 }
 
 /** Reconnect to an existing sandbox by provider + provider-native sandbox ID. */
-export async function reconnectSandbox(provider: string, sandboxId: string): Promise<SandboxProvider> {
+export async function reconnectSandbox(provider: SandboxProviderName, sandboxId: string): Promise<SandboxProvider> {
   const def = SANDBOX_PROVIDERS[provider];
   if (!def?.reconnect) throw new Error(`Provider "${provider}" does not support reconnect`);
   return def.reconnect(sandboxId);
 }
 
 /** Delete a snapshot by id on the named provider. No live sandbox needed. */
-export async function deleteSandboxSnapshot(provider: string, snapshotId: string): Promise<void> {
+export async function deleteSandboxSnapshot(provider: SandboxProviderName, snapshotId: string): Promise<void> {
   const def = SANDBOX_PROVIDERS[provider];
   if (!def?.deleteSnapshot) throw new Error(`Provider "${provider}" does not support deleteSnapshot`);
   const missing = Object.entries(def.requiredEnv)
@@ -398,10 +426,12 @@ export async function deleteSandboxSnapshot(provider: string, snapshotId: string
  * `getActiveCount`. Errors are surfaced per-provider so one flaky provider
  * doesn't silence the rest.
  */
-export async function getSandboxQuotas(): Promise<Record<string, number | Error>> {
-  const out: Record<string, number | Error> = {};
+export type SandboxQuotaResult = Partial<Record<SandboxProviderName, number | Error>>;
+
+export async function getSandboxQuotas(): Promise<SandboxQuotaResult> {
+  const out: SandboxQuotaResult = {};
   await Promise.all(
-    Object.entries(SANDBOX_PROVIDERS).map(async ([name, def]) => {
+    (Object.entries(SANDBOX_PROVIDERS) as Array<[SandboxProviderName, SandboxProviderDef]>).map(async ([name, def]) => {
       if (!def.getActiveCount) return;
       if (Object.keys(def.requiredEnv).some(k => !process.env[k])) return;
       const env = Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k]!]));
@@ -418,10 +448,12 @@ export async function getSandboxQuotas(): Promise<Record<string, number | Error>
  * or missing env are skipped. Errors propagate per-provider so one flaky
  * provider doesn't silence the rest.
  */
-export async function listOwnedSandboxes(): Promise<Record<string, OwnedSandbox[] | Error>> {
-  const out: Record<string, OwnedSandbox[] | Error> = {};
+export type OwnedSandboxResult = Partial<Record<SandboxProviderName, OwnedSandbox[] | Error>>;
+
+export async function listOwnedSandboxes(): Promise<OwnedSandboxResult> {
+  const out: OwnedSandboxResult = {};
   await Promise.all(
-    Object.entries(SANDBOX_PROVIDERS).map(async ([name, def]) => {
+    (Object.entries(SANDBOX_PROVIDERS) as Array<[SandboxProviderName, SandboxProviderDef]>).map(async ([name, def]) => {
       if (!def.listOwned) return;
       if (Object.keys(def.requiredEnv).some(k => !process.env[k])) return;
       const env = Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k]!]));
@@ -433,7 +465,7 @@ export async function listOwnedSandboxes(): Promise<Record<string, OwnedSandbox[
 }
 
 /** Kill a sandbox by provider + native ID. Used by the orphan reconciler. */
-export async function killSandboxById(provider: string, sandboxId: string): Promise<void> {
+export async function killSandboxById(provider: SandboxProviderName, sandboxId: string): Promise<void> {
   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);
@@ -442,10 +474,10 @@ export async function killSandboxById(provider: string, sandboxId: string): Prom
 
 /** Kill all sandboxes across all registered providers. Call at startup to clean up after crashes. */
 export async function killAllSandboxes(
-  onError?: (provider: string, err: unknown) => void,
+  onError?: (provider: SandboxProviderName, err: unknown) => void,
 ): Promise<void> {
   await Promise.allSettled(
-    Object.entries(SANDBOX_PROVIDERS)
+    (Object.entries(SANDBOX_PROVIDERS) as Array<[SandboxProviderName, SandboxProviderDef]>)
       .filter(([, def]) => def.killAll)
       .map(([name, def]) => {
         const env = Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k] ?? ""]));

package/src/step-invocation/index.ts

@@ -0,0 +1,33 @@
+/**
+ * StepInvocation — cross-process protocol that lets a server-side
+ * activity (Temporal `executeStep`, future Inngest equivalent) drive
+ * one workflow step inside an existing runner sandbox.
+ *
+ * Two halves, single source of truth for the wire:
+ *
+ *   - `invokeStep(sandbox, request)` — server side. Writes input +
+ *     request context, mints a token, builds envs, spawns the runner,
+ *     parses the tokenised stdout sentinel, returns a kinded `StepResult`.
+ *
+ *   - `serveStep(handler)` — runner side. Reads input + request context
+ *     from env-pointed files, runs the handler, emits the tokenised
+ *     sentinel result line, exits with the right code.
+ *
+ * The protocol is intentionally narrow: one input file + one context
+ * file + one tokenised stdout result line. Easy to reason about, easy
+ * to test in isolation.
+ */
+
+export {
+  STEP_RESULT_PREFIX,
+  STEP_ENV,
+  RUNNER_BUNDLE_PATH,
+  RUNNER_COMMAND,
+  stepInputPath,
+  requestContextPath,
+} from "./protocol.js";
+export { invokeStep, parseStepResult, buildStepEnvs } from "./invoker.js";
+export { serveStep } from "./server.js";
+export type { StepHandler, ServeStepRequest, StepHandlerResult } from "./server.js";
+export { StepExecutionError } from "./types.js";
+export type { StepRequest, StepResult, StepInvocationError } from "./types.js";

package/src/step-invocation/invoker.ts

@@ -0,0 +1,204 @@
+/**
+ * Server-side half of StepInvocation. The Temporal `executeStep` activity
+ * (and any future durable engine's equivalent) calls `invokeStep(...)` to
+ * run one step inside an existing runner sandbox.
+ *
+ * Owns:
+ *   - per-invocation result token (protocol hygiene — keeps user-side
+ *     stdout from accidentally contaminating the result channel)
+ *   - input + request-context file writes
+ *   - env stamping
+ *   - sandbox.commands.run with the runner command
+ *   - tokenised stdout sentinel parse
+ *   - failure-mode classification (protocol / user-step / runner-exit)
+ *
+ * Caller owns:
+ *   - reconnecting to the runner sandbox (per-team, per-run)
+ *   - turning a kinded error into the activity's exception shape
+ *
+ * No timeout: Temporal's startToCloseTimeout already bounds the activity.
+ * `sandbox.commands.run({ timeoutMs: 0 })` lets the runner consume that
+ * full window before the activity times out and Temporal kills the call.
+ */
+
+import { randomBytes } from "node:crypto";
+import type { SandboxProvider } from "../types/sandbox.js";
+import { RUNNER_COMMAND, STEP_ENV, stepResultLinePrefix, requestContextPath, stepInputPath } from "./protocol.js";
+import type { StepRequest, StepResult } from "./types.js";
+
+export { RUNNER_COMMAND } from "./protocol.js";
+
+/** Build the env map for one step invocation. Pure function; tests use it
+ *  to assert the env shape (and to assert that no server-held credentials
+ *  leak in) without spawning a sandbox. */
+export function buildStepEnvs(args: {
+  runId:       string;
+  stepIndex:   number;
+  resultToken: string;
+}): Record<string, string> {
+  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,
+  };
+}
+
+/** Scan the runner's stdout for the tokenised sentinel line and return a
+ *  classified result. Returns `null` when no sentinel is present — the
+ *  caller distinguishes that case from a parsed `{ ok: false }` payload
+ *  using exit code (see `invokeStep`). Pure function for testability.
+ *
+ *  Failure classification is taken from the runner's `kind` field on the
+ *  payload (the runner separates setup/protocol failures from handler
+ *  throws). If `kind` is missing or unknown, treat as `protocol` —
+ *  that's a malformed payload, which by definition is a wire violation. */
+export function parseStepResult<TOutput = unknown>(
+  stdout:      string,
+  resultToken: string,
+): StepResult<TOutput> | null {
+  const prefix = stepResultLinePrefix(resultToken);
+  const line = stdout.split(/\r?\n/).find((l) => l.startsWith(prefix));
+  if (!line) return null;
+  let parsed: {
+    ok:             boolean;
+    output?:        unknown;
+    kind?:          string;
+    error?:         string;
+    observability?: import("../workflow-steps/observability.js").StepObservability;
+  };
+  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 as TOutput, observability: parsed.observability }
+      : { ok: true, output: parsed.output as TOutput };
+  }
+  const kind: "protocol" | "user-step" = parsed.kind === "user-step" ? "user-step" : "protocol";
+  const baseMessage = parsed.error ?? "step body failed without a message";
+  // An unknown kind value means the runner emitted something this invoker
+  // doesn't recognise — most likely a version-skew deploy. Preserve the
+  // original kind string in the message so operators see the actual value
+  // instead of silently re-classifying it as "protocol".
+  const message = parsed.kind && parsed.kind !== "user-step" && parsed.kind !== "protocol"
+    ? `(unknown kind "${parsed.kind}") ${baseMessage}`
+    : baseMessage;
+  return { ok: false, error: { kind, message } };
+}
+
+/**
+ * Run one step inside the given sandbox. The full ceremony is here so the
+ * caller body is "reconnect sandbox → invokeStep → narrow result". A
+ * stdout line that happens to start with the sentinel prefix but carries
+ * a different token is ignored — the per-invocation token guarantees the
+ * result channel can't be contaminated by user `console.log` output or
+ * by any dep that logs a JSON-shaped line.
+ */
+export interface InvokeStepOptions {
+  envs?: Record<string, string>;
+  /** Live stdout / stderr from the runner subprocess, line-by-line. Called
+   *  from inside `sandbox.commands.run` as chunks arrive. The sentinel line
+   *  carrying the protocol result token is filtered out before delivery so
+   *  callers only see user-visible runtime output.
+   *
+   *  Callbacks are invoked synchronously from the sandbox stream loop — keep
+   *  them cheap (e.g. push to an in-memory array). Persisting / shipping is
+   *  the caller's job; the activity batches and inserts at step completion. */
+  onStdout?: (line: string) => void;
+  onStderr?: (line: string) => void;
+}
+
+export async function invokeStep<TOutput = unknown>(
+  sandbox: SandboxProvider,
+  request: StepRequest,
+  opts?: InvokeStepOptions,
+): Promise<StepResult<TOutput>> {
+  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,
+    }),
+  };
+
+  // The sandbox emits stdout as raw chunks, not lines. Buffer between
+  // emissions so a `console.log` split across two chunks (or a partial
+  // trailing line) is delivered to onStdout/onStderr as one logical line.
+  // The sentinel line (carrying `resultToken`) is filtered out so callers
+  // never see protocol bytes in user-log capture. The prefix is built
+  // from `stepResultLinePrefix` — the same helper `parseStepResult` uses,
+  // so the filter and the parser can't drift.
+  const sentinelPrefix = stepResultLinePrefix(resultToken);
+  const makeLineSplitter = (sink: ((line: string) => void) | undefined, filterSentinel: boolean) => {
+    if (!sink) return { onChunk: undefined, flush: () => {} };
+    let buf = "";
+    return {
+      onChunk: (chunk: string) => {
+        buf += chunk;
+        let nl;
+        while ((nl = buf.indexOf("\n")) !== -1) {
+          const line = buf.slice(0, nl);
+          buf = buf.slice(nl + 1);
+          if (filterSentinel && line.startsWith(sentinelPrefix)) continue;
+          sink(line);
+        }
+      },
+      // Drain any remaining buffered output that ended without a newline.
+      // Called after `sandbox.commands.run` resolves so a runner that
+      // exits with `process.stdout.write("final")` (no trailing \n)
+      // doesn't silently drop its last 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<TOutput>(result.stdout, resultToken);
+  if (parsed) return parsed;
+
+  // No tokenised sentinel on stdout. Distinguish "runner exited badly
+  // before emitting" (runner-exit) from "runner exited cleanly but didn't
+  // speak the protocol" (protocol) — the exit code is the evidence.
+  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,
+      },
+    };
+  }
+  return {
+    ok: false,
+    error: { kind: "protocol", message: "no tokenised step result found on stdout" },
+  };
+}

package/src/step-invocation/protocol.ts

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

package/src/step-invocation/server.ts

@@ -0,0 +1,184 @@
+/**
+ * Runner-side half of StepInvocation. The worker's runner.ts in step
+ * mode calls `serveStep(handler)` — read the input + request context
+ * from env-pointed files, run the user handler, emit the tokenised
+ * sentinel result line on stdout, exit with the right code.
+ *
+ * Owns:
+ *   - reading inputs from the env-pointed JSON files
+ *   - parse-error handling (protocol-violating env or malformed file)
+ *   - tokenised sentinel emission (matched by the invoker's parser)
+ *   - awaited stdout flush before process.exit (Linux pipes can drop
+ *     unflushed bytes when the writer exits)
+ *   - exit codes (0 on success, 1 on any failure)
+ *
+ * Handler owns:
+ *   - what to do with the input (load the compiled workflow, run the
+ *     step, return the output)
+ *
+ * `serveStep` never returns — it always exits the process. The return
+ * type is `Promise<never>` so callers can `await serveStep(...)` and
+ * trust nothing runs after.
+ */
+
+import { readFileSync } from "node:fs";
+import type { RequestContextWire } from "../request-context/request-context.js";
+import type { StepObservability } from "../workflow-steps/observability.js";
+import { STEP_ENV, STEP_RESULT_PREFIX } from "./protocol.js";
+
+/** What the handler receives. The serveStep already parsed the input
+ *  and request context from their JSON files. */
+export interface ServeStepRequest<TInput = unknown> {
+  runId:          string;
+  stepIndex:      number;
+  input:          TInput;
+  requestContext: RequestContextWire;
+}
+
+/** What the handler returns. `observability` is the buffered snapshot
+ *  of `ctx.setMetadata` / `ctx.step` / `ctx.agentEvents` recorded during
+ *  the step; serveStep forwards it on the wire and the activity persists
+ *  it. Undefined for handlers that don't use the hooks. */
+export interface StepHandlerResult<TOutput = unknown> {
+  output:         TOutput;
+  observability?: StepObservability;
+}
+
+/** User handler signature: take parsed step request, return the step
+ *  output (and optional observability bundle). Throwing turns into
+ *  `{ ok: false, kind: "user-step", error: <message> }` on the wire. */
+export type StepHandler<TInput = unknown, TOutput = unknown> =
+  (request: ServeStepRequest<TInput>) => Promise<StepHandlerResult<TOutput>>;
+
+/** Wire payload shape. Failure carries the `kind` so the invoker can
+ *  classify "setup/protocol problem on the runner side" (e.g. malformed
+ *  request-context JSON) separately from "the user handler threw".
+ *  `observability` rides along on success so the activity can persist
+ *  it without a second round-trip. */
+type SentinelPayload =
+  | { ok: true;  output: unknown; observability?: StepObservability }
+  | { ok: false; kind: "user-step" | "protocol"; error: string };
+
+/** Emit one tokenised sentinel line and resolve only after the kernel
+ *  has accepted the bytes. Awaited flush is critical: process.exit()
+ *  immediately after a non-awaited write can drop the data on Linux
+ *  pipes, leaving the invoker with empty stdout and the runner-exit
+ *  classification pointing at the wrong thing. */
+function emitResult(token: string, payload: SentinelPayload): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const line = `${STEP_RESULT_PREFIX}${token}:${JSON.stringify(payload)}\n`;
+    process.stdout.write(line, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}
+
+/** Delete step-invocation transport envs so the user's workflow code
+ *  (loaded inside the handler) can't read them. Matters most for
+ *  AC_STEP_RESULT_TOKEN: if it stayed in env, a `console.log` from a dep
+ *  that happens to include the token could emit a line indistinguishable
+ *  from a real result and win `.find()` in the invoker. Scrubbing keeps
+ *  the result channel uncorruptible by stdout traffic from anywhere in
+ *  the workflow's dep tree. RUN_ID is intentionally preserved because it
+ *  is part of the runner's public workflow environment in both modes. */
+function scrubProtocolEnvs(): void {
+  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];
+  }
+}
+
+/**
+ * Read step input + request context, invoke `handler`, emit the result,
+ * exit. `Promise<never>` because every code path ends in `process.exit`.
+ *
+ * Two distinct phases under separate try/catch:
+ *   1. Setup — read envs, parse the input + context files. Failures
+ *      here mean the wire is broken (server bug); they emit
+ *      `{ok:false, kind:"protocol"}`.
+ *   2. Handler — call the user-supplied step body. Failures here are
+ *      user code throwing; they emit `{ok:false, kind:"user-step"}`.
+ *
+ * Between the two phases, step-invocation transport envs are scrubbed
+ * from process.env so user code (including any workflow module imported
+ * inside the handler) cannot read AC_STEP_RESULT_TOKEN — that keeps the
+ * result channel uncorruptible by stdout output from anywhere in the
+ * workflow's dep tree. RUN_ID remains available to match full-mode
+ * runner behaviour.
+ */
+export async function serveStep<TInput, TOutput>(
+  handler: StepHandler<TInput, TOutput>,
+): Promise<never> {
+  const token = process.env[STEP_ENV.STEP_RESULT_TOKEN];
+  if (!token) {
+    // Without a token we cannot emit a result the invoker will accept.
+    // Fail loudly on stderr so the runner-exit path on the activity
+    // side has a useful breadcrumb.
+    process.stderr.write(`[step-server] missing ${STEP_ENV.STEP_RESULT_TOKEN}\n`);
+    process.exit(1);
+  }
+
+  // process.exit is intentionally outside the try/catch — a real failure
+  // (or a test-time mock that throws an exit sentinel) must not be caught
+  // and re-emitted as a step failure.
+  let exitCode = 0;
+  let payload!: SentinelPayload;
+
+  let setupResult: { runId: string; stepIndex: number; input: TInput; requestContext: RequestContextWire } | undefined;
+  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")) as TInput;
+    // RequestContextWire parsing is loose here on purpose — the wire is
+    // server-controlled, malformed shape is a server bug, and we want a
+    // useful failure reason in `failRun`. Strict validation belongs at
+    // the workflow-level RequestContext.parse boundary, not here.
+    const requestContext = JSON.parse(readFileSync(ctxPath, "utf8")) as RequestContextWire;
+
+    setupResult = { runId, stepIndex, input, requestContext };
+  } catch (err) {
+    exitCode = 1;
+    payload  = { ok: false, kind: "protocol", error: err instanceof Error ? err.message : String(err) };
+  }
+
+  if (setupResult) {
+    // Scrub protocol envs BEFORE user code runs. After this point the
+    // transport-only process.env[STEP_ENV.*] reads return undefined, so a
+    // workflow dependency cannot read AC_STEP_RESULT_TOKEN and accidentally
+    // emit a stdout line that the invoker would accept as a real result.
+    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) };
+    }
+  }
+
+  await emitResult(token, payload);
+  process.exit(exitCode);
+}