@agent-compose/sdk 0.8.4 → 0.8.6

package/src/types/protocol.ts

@@ -74,6 +74,22 @@ export interface AgentMessageError extends AgentMessageBase {
   text: string;
 }
 
+/** One model's share of a harness's turn-end report (claude-code
+ *  `result.modelUsage[<model>]`): the same four token classes as the turn
+ *  totals, plus what the harness reports beside them. `costUsd` is the
+ *  harness's OWN estimate at its price table — never a bill. Fields the
+ *  harness did not report are absent, never zeroed. */
+export interface AgentMessageModelUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+  /** Thinking tokens, already counted inside `outputTokens`. */
+  thinkingTokens?: number;
+  webSearchRequests?: number;
+  costUsd?: number;
+}
+
 export interface AgentMessageUsage extends AgentMessageBase {
   type: "usage";
   inputTokens: number;
@@ -82,6 +98,54 @@ export interface AgentMessageUsage extends AgentMessageBase {
   cacheCreationTokens: number;
   durationMs: number;
   numTurns: number;
+  /** Reasoning tokens, already counted inside `outputTokens` (codex
+   *  `turn.completed.usage.reasoning_output_tokens`). Absent when the
+   *  harness reports no such class. */
+  reasoningOutputTokens?: number;
+  /** Per-model totals the harness reported beside the turn totals
+   *  (claude-code `result.modelUsage`): every model the query pipeline
+   *  called — main loop, subagents, compaction. As the CLI reports them:
+   *  CUMULATIVE for the guest session (a streaming-input or resumed
+   *  session carries its earlier turns), so a per-turn share is the
+   *  difference from the previous report of the same session. Absent when
+   *  the harness reports none. */
+  byModel?: Record<string, AgentMessageModelUsage>;
+  /** The harness's own cost estimate for the same scope as `byModel`
+   *  (claude-code `result.total_cost_usd`): list-price arithmetic, an
+   *  estimate and never a billing statement. */
+  costUsd?: number;
+}
+
+/** The harness's reading of the account's PLAN LIMITS (claude-code
+ *  `rate_limit_event`, emitted whenever its rate-limit information changes
+ *  — subscription-funded sessions only; the headers it reads exist for
+ *  claude.ai plans). `status` is the verdict for the request just made:
+ *  `rejected` means the plan's wall, with `resetsAt` the authoritative
+ *  reset. `window` names which window the verdict speaks for (the CLI's
+ *  `rateLimitType`: five_hour, seven_day, seven_day_opus, …). `utilization`
+ *  is carried only once a window crosses a warning threshold (the CLI omits
+ *  it while plainly allowed), as the CLI reports it — a 0..1 fraction of
+ *  the window. Everything the event did not carry is absent; nothing is
+ *  invented. Additive kind: existing producers never emit it. */
+export interface AgentMessagePlanLimits extends AgentMessageBase {
+  type: "plan_limits";
+  status: "allowed" | "allowed_warning" | "rejected";
+  window?: string;
+  /** ISO time the named window resets. */
+  resetsAt?: string;
+  utilization?: number;
+  /** The warning threshold the window crossed (as the CLI reports it). */
+  surpassedThreshold?: number;
+  /** The plan's extra-usage (overage) lane, when the event spoke of it. */
+  overage?: {
+    status?: "allowed" | "allowed_warning" | "rejected";
+    resetsAt?: string;
+    disabledReason?: string;
+    inUse?: boolean;
+  };
+  /** Which spend limit blocked the request when not the member's own cap. */
+  limitScope?: string;
+  errorCode?: string;
 }
 
 /** LIVE-ONLY incremental usage off the harness's raw provider stream — the
@@ -114,7 +178,8 @@ export interface AgentMessagePlan extends AgentMessageBase {
   type: "plan";
   entries: {
     content: string;
-    priority: "high" | "medium" | "low";
+    /** ACP names one; codex's `--json` plan names none. */
+    priority?: "high" | "medium" | "low";
     status: "pending" | "in_progress" | "completed";
   }[];
 }
@@ -147,6 +212,61 @@ export interface AgentMessageTaskNotification extends AgentMessageBase {
   usage?: { tokens?: number; toolUses?: number; durationMs?: number };
 }
 
+/** One entry of a harness workflow's live progress feed — the
+ *  `workflow_progress` array claude-code's `system`/`task_progress` events
+ *  carry for its in-harness Workflow tool (the dynamic-workflow
+ *  orchestrator). `phase` entries are the script's declared phases (seeded
+ *  up front, 1-based `index`); `agent` entries are the spawned workflow
+ *  agents, updated in place as they queue → run → settle. Preview text the
+ *  harness includes (prompt/result previews) is internal plumbing and is
+ *  deliberately NOT forwarded — same rule as task notifications. */
+export type WorkflowProgressEntry =
+  | { kind: "phase"; index: number; title: string }
+  | {
+      kind: "agent"; index: number; label: string;
+      /** Lifecycle: `start` (spawned) / `progress` (heartbeat) are live;
+       *  `done` / `error` are settled. Verbatim from the harness. */
+      state: "start" | "progress" | "done" | "error";
+      phaseIndex?: number; phaseTitle?: string;
+      model?: string; agentId?: string;
+      /** Self-reported usage so far (cumulative for this agent). */
+      tokens?: number; toolCalls?: number; durationMs?: number;
+      /** Epoch ms the agent actually started (for live elapsed). */
+      startedAt?: number;
+      /** The failure message when `state: "error"`, clamped. */
+      error?: string;
+      /** Replayed from a resume cache — settled instantly, no fresh spend. */
+      cached?: true;
+      /** Skipped by the user (workflow dialog) — an error state that is
+       *  not a failure. */
+      skipped?: true;
+    };
+
+/** LIVE progress of a harness BACKGROUND task (claude-code
+ *  `system`/`task_progress`). For the in-harness Workflow tool the message
+ *  carries the CUMULATIVE `workflow_progress` entry array (the harness
+ *  re-sends the whole picture: state changes immediately, heartbeats
+ *  throttled ~10s), so a consumer treats the latest message as
+ *  authoritative per entry `(kind, index)`. A plain background AGENT task
+ *  (Task tool, run_in_background) heartbeats on the same event with NO
+ *  workflow entries — forwarded with `workflow: []` as liveness evidence
+ *  so the platform can declare the running task as session background
+ *  work; its completion evidence rides `task_notification`. `toolUseId`
+ *  names the spawning call — the correlation key to its card. Additive
+ *  kind: existing producers never emit it. */
+export interface AgentMessageTaskProgress extends AgentMessageBase {
+  type: "task_progress";
+  /** The harness's background task id. */
+  taskId: string;
+  /** The SPAWNING Workflow/Task call's tool_use id, when carried. */
+  toolUseId?: string;
+  /** The task's cumulative usage totals so far. */
+  usage?: { tokens?: number; toolUses?: number; durationMs?: number };
+  /** The cumulative workflow progress entries — EMPTY for a plain
+   *  background Agent-task heartbeat (only Workflow tasks carry entries). */
+  workflow: WorkflowProgressEntry[];
+}
+
 /** HARNESS-authored notice text — content the CLI composed itself rather
  *  than the model speaking: slash-command stdout, model/skills advisories,
  *  queued-input notes. claude-code marks these structurally (assistant
@@ -160,6 +280,60 @@ export interface AgentMessageHarnessNotice extends AgentMessageBase {
   text: string;
 }
 
+/** Context-compaction lifecycle — the harness summarizing its own
+ *  conversation to reclaim context. Mapped 1:1 from claude-code's wire
+ *  (verified live on 2.1.212, the baked sandbox pin, and 2.1.241 — both
+ *  emit the identical shapes, `/compact` and auto alike):
+ *
+ *    `system`/`status` `{status:"compacting"}`            → phase "start"
+ *    `system`/`status` `{status:null, compact_result,     → phase "settled"
+ *                        compact_error?}`
+ *    `system`/`compact_boundary` `{compact_metadata:      → phase "boundary"
+ *      {trigger, pre_tokens, post_tokens,
+ *       cumulative_dropped_tokens, duration_ms, …}}`
+ *
+ *  Order on the wire: start → settled → (fresh init) → boundary → the
+ *  continuation summary as a SYNTHETIC user message (never forwarded — it
+ *  quotes conversation content verbatim). "boundary" only follows a
+ *  successful settle and only on the turn the compaction ran (verified: it
+ *  does NOT replay on later resumes). A compaction can span MINUTES of
+ *  otherwise-silent stream — the whole point of forwarding it is that
+ *  downstream can show the silence as work (the 2026-08-23 dead-air
+ *  incident: 94% auto-compact read as a dead session). Additive kind:
+ *  existing producers never emit it. */
+export interface AgentMessageCompaction extends AgentMessageBase {
+  type: "compaction";
+  phase: "start" | "settled" | "boundary";
+  /** settled: how it ended. Absent on start/boundary (a boundary IS a
+   *  success by construction — the harness only emits it after one). */
+  result?: "success" | "failed";
+  /** settled+failed: the harness's own reason, clamped. */
+  error?: string;
+  /** boundary: what initiated the compaction. */
+  trigger?: "auto" | "manual";
+  /** boundary: context tokens before / after, dropped total, wall time. */
+  preTokens?: number;
+  postTokens?: number;
+  droppedTokens?: number;
+  durationMs?: number;
+}
+
+/** A user-role message landing INSIDE a subagent's thread — the delivered
+ *  form of a steer (the parent's `SendMessage` to a RUNNING child, queued
+ *  "for delivery at its next tool round") or any other message the harness
+ *  folds into a child's conversation mid-flight. Emitted ONLY with sidechain
+ *  attribution: `parentToolUseId` (the spawning Agent/Task call's tool_use
+ *  id) is REQUIRED — an unattributed user event is the parent's own prompt
+ *  echo, which stays unmapped as before. Lets renderers show the steer as a
+ *  user-role message inside the child's mini-session instead of leaving it
+ *  an opaque SendMessage tool call on the parent only (task #97, owner
+ *  directive 2026-08-27). Additive kind: existing producers never emit it. */
+export interface AgentMessageSubagentUserMessage extends AgentMessageBase {
+  type: "subagent_user_message";
+  text: string;
+  parentToolUseId: string;
+}
+
 export type AgentMessage =
   | AgentMessageInit
   | AgentMessageText
@@ -171,9 +345,13 @@ export type AgentMessage =
   | AgentMessageError
   | AgentMessageUsage
   | AgentMessageUsageDelta
+  | AgentMessagePlanLimits
   | AgentMessagePlan
   | AgentMessageTaskNotification
-  | AgentMessageHarnessNotice;
+  | AgentMessageTaskProgress
+  | AgentMessageHarnessNotice
+  | AgentMessageCompaction
+  | AgentMessageSubagentUserMessage;
 
 /** Status block the agent emits to signal iteration completion or blockers. */
 export interface AgentStatus {

package/src/types/runtime.ts

@@ -94,6 +94,16 @@ export interface RuntimeOptions {
    *  Absent ⇒ nothing extra is sourced. Must be a plain absolute path — no
    *  quotes, no `..`; the runtime validates and drops anything else. */
   credEnvFile?: string;
+  /** Durable launch report (boot-time turn adoption): called by the durable
+   *  detached transport the moment its in-guest runner exists — with the
+   *  guest prompt path (every durable file derives from it), the exit
+   *  sentinel string, and the detached wrapper's pid. The caller stamps
+   *  these on the turn row so a SUCCESSOR process (a deploy roll's new
+   *  server) can re-attach to the runner's durable `.out` without this
+   *  process's memory. Fired once per detached launch (a retry with a fresh
+   *  runner fires again with the new paths); never on transports without
+   *  durable files. Must not throw — the transport calls it inline. */
+  onDetachedLaunch?: (info: { promptPath: string; sentinel: string; pid: number }) => void;
 }
 
 /** Three-valued liveness verdict for a runtime's CURRENT turn, read from
@@ -182,6 +192,21 @@ export interface ModelExecutionContract {
    * fallback probe it already had; null is never a verdict.
    */
   probeTurnLiveness?(): Promise<RunnerLivenessVerdict | null>;
+  /**
+   * TELEMETRY, NEVER A VERDICT (tool-run pulse, 2026-08-29): the newest
+   * tool-run pulse the durable liveness probe carried — the guest
+   * heartbeat's sample of the runner's own session (aggregate CPU jiffies,
+   * written bytes, live process count) plus the guest clock it was read
+   * against. The executor's evidence ticker peeks it AFTER its liveness
+   * check and compares successive samples: counters ADVANCING is proof a
+   * long silent foreground tool is working, fanned to clients as a live
+   * `tool_pulse` frame. Never probes on its own; null before any probe or
+   * on a transport without the pulse file. No liveness decision may ever
+   * read it.
+   */
+  peekTurnPulse?(): {
+    atMs: number; cpuJiffies: number; ioBytes: number; procs: number; guestNowMs: number;
+  } | null;
   /**
    * DOORBELL, NEVER A VERDICT (exit-event push, v0.10.43): wake the current
    * turn's durable watchdog NOW so it runs its normal verification pass —
@@ -231,7 +256,51 @@ export interface ModelExecutionContract {
    *     phase, a spec/transport without stream input, ACP path).
    * Calls are serialized per turn; never throws.
    */
-  injectUserMessage?(text: string): Promise<"delivered" | "pending" | "closed" | "unsupported">;
+  injectUserMessage?(
+    text: string,
+    /** Who the message speaks for when it is not the session user
+     *  (MidTurnEnvelopeOptions): a relayed person, named, or the thread
+     *  agent that owns this worker. */
+    opts?: { relayedFrom?: string | null; fromOwnerAgent?: boolean },
+  ): Promise<"delivered" | "pending" | "closed" | "unsupported">;
+  /**
+   * Request an in-band STEP INTERRUPT of the currently running turn — the
+   * ESC equivalent. Where `injectUserMessage` queues content for the turn
+   * loop's next boundary, this rides the same durable inbox but carries a
+   * control line the CLI handles immediately, mid-step included: the
+   * running tool call aborts, the run ends within ~100ms, and the guest
+   * session stays resumable with the whole turn context (verified live
+   * against claude 2.1.236). Verdicts mirror `injectUserMessage`; only
+   * "delivered" means the CLI got the control line — callers escalate
+   * anything else (and "unsupported": no stream-input turn, or a runtime
+   * with no in-band interrupt, e.g. codex) to kill semantics, which stay
+   * honest because thread stores are durable and the successor turn
+   * resumes them. Never throws.
+   */
+  interruptTurn?(): Promise<"delivered" | "pending" | "closed" | "unsupported">;
+  /**
+   * Guest pid of the CURRENT turn's detached runner wrapper (the setsid
+   * process-group leader recorded at launch), or null when no detached
+   * durable-transport runner is live (boot phase, ACP path, single-exec
+   * transports). Advisory identity, NEVER a liveness verdict: the platform
+   * reads it to DECLARE harness-reported background work (an in-harness
+   * Workflow task) against the process tree that hosts it, so the park
+   * machinery can verify the tree from `/proc/<pid>` later. Runtimes
+   * without a detached guest simply omit the method.
+   */
+  currentRunnerPid?(): number | null;
+  /**
+   * Durable byte offset of the CURRENT turn's `.out` file just past the
+   * last line whose messages have ALL been yielded to the consumer — the
+   * safe harvest watermark for boot-time turn adoption. Null when no
+   * durable-transport turn is live, or before the first line completes.
+   * The contract is deliberately one line BEHIND the parse cursor: a
+   * caller that persists parts after each yielded message may stamp this
+   * offset at any time and a successor re-parses AT MOST the line whose
+   * parts were mid-persist (the same crash window the workflow tailer's
+   * flush-before-advance ordering accepts). Advisory, never a verdict.
+   */
+  currentTurnDurableOffset?(): number | null;
   sendMessage(opts: {
     prompt: string;
     sessionId?: string;
@@ -253,7 +322,7 @@ export interface ModelExecutionContract {
  * The sandbox provider (e.g. "vercel", "e2b") is an infrastructure concern
  * configured via SANDBOX_PROVIDER — not part of the runtime definition.
  * For non-sandbox agents (API calls, etc.) make the call directly in the workflow;
- * spawnAgent is a sandbox concept.
+ * `agent()` is a sandbox concept.
  */
 export interface AgentRuntime<S extends SandboxProvider = SandboxProvider> {
   create(sandbox: S, opts: RuntimeOptions): ModelExecutionContract;

package/src/types/sandbox-environment.ts

@@ -79,8 +79,7 @@ export function defineSandboxEnvironment(
     snapshots: env.snapshots ?? { saveLatest: true },
     // Mark this as an environment build so the server skips the /factory mount
     // for its runs — an env build builds a platform image and never touches the
-    // shared drive; baking a live Archil mount into its snapshot breaks the
-    // re-mount of every workflow that later boots from it (#13).
+    // shared drive, so no live drive mount bakes into its snapshot (#13).
     environmentBuild: true,
   })
     .step({

package/src/types/workflow-metadata.ts

@@ -234,10 +234,8 @@ export interface WorkflowMetadata {
    *  BUILD — a setup-only workflow whose job is to leave its VM configured and
    *  snapshot it (base-env / agent-env). Environment builds build a platform
    *  IMAGE and never use the shared factory drive, so the server SKIPS mounting
-   *  /factory for them: a live Archil mount baked into the captured snapshot
-   *  fails the NEXT boot's re-mount ("an older Archil process is still running
-   *  for this mountpoint"), degrading /factory for every workflow booting from
-   *  that snapshot. Absent on ordinary workflows — which mount /factory exactly
+   *  /factory for them and no live drive mount bakes into the captured
+   *  snapshot. Absent on ordinary workflows — which mount /factory exactly
    *  as before. Optional + additive: an ABSENT flag contributes nothing to the
    *  canonical metadata hash (frozen-metadata rule), so existing workflows are
    *  not forced to re-register. */

package/src/types/workflow-plan.ts

@@ -5,9 +5,7 @@
  * dispatch time. The CLI/bundler inspects the bundled module in the user's
  * environment and sends this compact plan as metadata.
  *
- * Every workflow has a step plan. Legacy `defineWorkflow({ run })`
- * workflows are wrapped at the SDK boundary as a single-step compiled
- * workflow (step name = "run"); the bundler sees the same shape regardless.
+ * Every workflow has a step plan.
  */
 
 /** One artifact a step promises to produce — mirrors `StepDeliverable`,

package/src/utils/bundler.ts

@@ -34,7 +34,8 @@
  */
 
 import { createHash } from "node:crypto";
-import { dirname } from "node:path";
+import { realpathSync } from "node:fs";
+import { dirname, join, resolve as resolvePath, sep } from "node:path";
 import { parse as babelParse } from "@babel/parser";
 import type { File, ExportDefaultDeclaration, CallExpression, Expression, Statement } from "@babel/types";
 import { importSourceModule } from "./source-loader.js";
@@ -194,38 +195,107 @@ interface BunPluginBuild {
   ): void;
 }
 
-/** Anchored regex over the alias table — the plugin filter. Specifiers are
- *  literal package names, but escape anyway so a future entry with a `.`
- *  or `+` can't widen the filter. */
+/**
+ * The packages the PLATFORM provides to every workflow source — the SDK and
+ * its zod peer — which therefore resolve from the platform's own install
+ * roots when the source file's directory has no node_modules of its own.
+ * The live incident (2026-09-20, a claude-code session at the drive root):
+ * `agentc invoke --source /factory/files/wf.ts` died with `Could not
+ * resolve "@agent-compose/sdk", "zod"` because Bun walked up from
+ * /factory/files and found nothing, while the baked SDK sat in
+ * /workspace/node_modules the whole time (infra/e2b-template/template.ts —
+ * "SDK into /workspace/node_modules so any script written under /workspace
+ * can import it"). A workflow's OWN third-party deps still have to be
+ * installed beside the source; only these two are platform-resolved.
+ */
+export const PLATFORM_RESOLVED_PACKAGES: readonly string[] = [SDK_PACKAGE, "zod"];
+
+/** Env override for the fallback roots (colon-separated, tried first) — the
+ *  test seam, and an ops knob for a sandbox image that plants the SDK
+ *  elsewhere. */
+export const SDK_FALLBACK_ROOTS_ENV = "AGENT_COMPOSE_SDK_FALLBACK_ROOTS";
+
+/** Where the platform SDK lives when the source's own walk-up finds nothing:
+ *  the env override's roots, the sandbox's baked /workspace install, then
+ *  the bundling process's cwd (the CLI's own resolution context). Exported
+ *  for the unit test. */
+export function sdkFallbackRoots(env: Record<string, string | undefined> = process.env): string[] {
+  const fromEnv = (env[SDK_FALLBACK_ROOTS_ENV] ?? "")
+    .split(":")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  const roots = [...fromEnv, "/workspace", process.cwd()];
+  return roots.filter((r, i) => roots.indexOf(r) === i);
+}
+
+/** Anchored regex over the alias table PLUS the platform-resolved packages
+ *  — the plugin filter. Specifiers are literal package names, but escape
+ *  anyway so a future entry with a `.` or `+` can't widen the filter. */
 function aliasFilter(): RegExp {
-  const alternation = SDK_SPECIFIER_ALIASES
+  const alternation = [...SDK_SPECIFIER_ALIASES, ...PLATFORM_RESOLVED_PACKAGES]
     .map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
     .join("|");
   return new RegExp(`^(?:${alternation})$`);
 }
 
 /**
- * The TOLERATE layer: a Bun resolve plugin that maps every known near-miss
- * specifier onto the real SDK. Resolution goes through Bun's own resolver
- * from the importing file's directory, so the alias lands on exactly the
+ * The TOLERATE layer: a Bun resolve plugin that (a) maps every known
+ * near-miss specifier onto the real SDK and (b) resolves the platform's own
+ * packages from the platform's install roots when the importing file's
+ * directory can't. Resolution goes through Bun's own resolver from the
+ * importing file's directory FIRST, so the alias lands on exactly the
  * `@agent-compose/sdk` the build would have used had the source spelled it
- * correctly. When the real SDK can't be resolved either, the plugin declines
- * and Bun's failure flows into `explainBundleFailure` below.
+ * correctly and a source that ships its own node_modules is untouched; only
+ * when that fails do the fallback roots (`sdkFallbackRoots`) get a turn, and
+ * `zod` additionally resolves from beside the SDK that was found (its
+ * peer, hoisted or nested). When nothing resolves, the plugin declines and
+ * Bun's failure flows into `explainBundleFailure` below.
  */
 function sdkAliasPlugin(bun: BunSurface): { name: string; setup(build: BunPluginBuild): void } {
+  // A resolution counts ONLY when it lands in a node_modules on `from`'s own
+  // walk-up (through symlinks — a workspace link's realpath is compared
+  // against the link's realpath). Bun's resolver otherwise "succeeds" via
+  // its global install cache (~/.bun/install/cache/<pkg>@<ver>/…), a bare
+  // package whose own dependencies are NOT installed — the build then dies
+  // on the SDK's deps ("Could not resolve @babel/parser, ai, e2b, …"), a
+  // far more confusing failure than the honest fallback below.
+  const tryResolve = (specifier: string, from: string): string | null => {
+    let resolved: string;
+    try { resolved = realpathSync(bun.resolveSync(specifier, from)); } catch { return null; }
+    let dir = resolvePath(from);
+    for (;;) {
+      try {
+        const real = realpathSync(join(dir, "node_modules", specifier));
+        if (resolved === real || resolved.startsWith(real + sep)) return resolved;
+      } catch { /* no node_modules/<specifier> at this level */ }
+      const parent = dirname(dir);
+      if (parent === dir) return null;
+      dir = parent;
+    }
+  };
   return {
     name: "agent-compose-sdk-alias",
     setup(build) {
       build.onResolve({ filter: aliasFilter() }, (args) => {
-        const target = resolveSdkAlias(args.path);
+        const target = resolveSdkAlias(args.path)
+          ?? (PLATFORM_RESOLVED_PACKAGES.includes(args.path) ? args.path : null);
         if (!target) return undefined;
         // `importer` is the importing FILE, `resolveDir` already a directory.
         const from = args.importer ? dirname(args.importer) : args.resolveDir;
-        try {
-          return { path: bun.resolveSync(target, from && from.length > 0 ? from : process.cwd()) };
-        } catch {
-          return undefined;
+        const own = tryResolve(target, from && from.length > 0 ? from : process.cwd());
+        if (own) return { path: own };
+        for (const root of sdkFallbackRoots()) {
+          const hit = tryResolve(target, root);
+          if (hit) return { path: hit };
+          // zod is the SDK's peer: a root that holds the SDK resolves zod
+          // from the SDK's own directory even when it isn't hoisted.
+          if (target !== SDK_PACKAGE) {
+            const sdk = tryResolve(SDK_PACKAGE, root);
+            const beside = sdk ? tryResolve(target, dirname(sdk)) : null;
+            if (beside) return { path: beside };
+          }
         }
+        return undefined;
       });
     },
   };
@@ -557,10 +627,9 @@ export async function bundleWorkflow(
   // schemas → compact JSON-Schema-shaped descriptions carried in
   // template metadata. Used by the dashboard's "Registered" panel to
   // render schema tables and (eventually) client-side validation in
-  // the playground. Run-form workflows stamp `z.unknown()` for both
-  // — `extractIOSchema` filters those down to undefined so the
-  // dashboard renders the "no declared schema" empty state instead
-  // of a meaningless empty table.
+  // the playground. `extractIOSchema` filters a `z.unknown()` schema
+  // down to undefined so the dashboard renders the "no declared
+  // schema" empty state instead of a meaningless empty table.
   const inputSchema  = extractIOSchema(workflow.input);
   const outputSchema = extractIOSchema(workflow.output);
 

package/src/workflow-steps/observability.ts

@@ -78,9 +78,8 @@ const LIVE_EMIT_DRAIN_TIMEOUT_MS = 1_500;
  * this instance. After the step finishes, the engine calls `snapshot()`
  * to extract the bundle for transport.
  *
- * Metadata writes merge (later keys win) — matches the legacy
- * `mergeRunMetadata` semantics so authors don't see a behaviour change
- * across migrations.
+ * Metadata writes merge (later keys win), as the server's run-metadata
+ * merge does.
  */
 export class StepObservabilityCollector {
   private metadata: Record<string, unknown> = {};

package/src/workflow-steps/runner.ts

@@ -6,7 +6,6 @@
  *   2. For each step:
  *      a. Optionally check `getCachedOutput(stepIndex, step.name)` — if a
  *         previous run completed this step, skip and reuse its output.
- *         (Phase 1b uses this for crash recovery.)
  *      b. Validate current input against `step.input`.
  *      c. Call `step.run({ input, ... })`.
  *      d. Validate return value against `step.output`.
@@ -17,9 +16,10 @@
  * Errors during any step bubble through `onStepFailed` and re-throw so the
  * caller can decide whether to mark the run failed.
  *
- * The cache + completion hooks are injection points — a sandbox engine
- * adapter (Phase 1c) wires them to `workflow_step_runs` rows. The default
- * is an in-process map for tests.
+ * The cache + completion hooks are injection points; without a cache every
+ * step runs. The platform's sandbox path does not walk the chain here: the
+ * Temporal `executeStep` activity runs one step per runner subprocess via
+ * `runWorkflowSingleStep` below.
  */
 
 import { z } from "zod";
@@ -76,13 +76,10 @@ export interface RunWorkflowStepsOpts<TInput, TOutput> {
   /**
    * Crash-recovery hook. Called before a step executes. Return the cached
    * output to skip execution; return undefined to run the step.
-   *
-   * Phase 1b implementations will look up `workflow_step_runs` rows for
-   * (runId, stepIndex, stepName) and return completed step outputs here.
    * Default: always undefined (no caching).
    */
   getCachedOutput?(stepIndex: number, stepName: string): unknown | undefined | Promise<unknown | undefined>;
-  /** Fire after a step's `execute` and output validation succeed. */
+  /** Fire after a step's `run` and output validation succeed. */
   onStepCompleted?(stepIndex: number, stepName: string, output: unknown, durationMs: number): void | Promise<void>;
   /** Fire when a step throws or fails validation. The error is re-thrown after this returns. */
   onStepFailed?(stepIndex: number, stepName: string, error: Error, durationMs: number): void | Promise<void>;

package/src/workflow-steps/types.ts

@@ -6,9 +6,8 @@
  *
  * Why: durable suspend/resume requires step boundaries to be addressable as
  * data, not opaque async-function bodies. Each step's input + output is
- * serialisable JSON so engine adapters (in-process, sandbox, future
- * Inngest/Temporal) can record completion and replay from the last
- * completed step.
+ * serialisable JSON so the durable engine (Temporal, one activity per step)
+ * can record completion and replay from the last completed step.
  */
 
 import type { z } from "zod";
@@ -18,7 +17,7 @@ import type { WorkflowMetadata } from "../types/workflow-metadata.js";
 import type { StepObservability } from "./observability.js";
 
 /**
- * Per-step execution context. Threaded into every step's `execute(...)` so
+ * Per-step execution context. Threaded into every step's `run(...)` so
  * the step can read tenant identity and run identity, log progress, and
  * invoke sandbox commands.
  *
@@ -33,9 +32,9 @@ export interface StepContext<TInput = unknown> extends BaseExecutionContext {
   abortSignal: AbortSignal;
   /**
    * Merge key-value metadata onto the run record. Buffered during the
-   * step and flushed when the step completes; the durable engine writes
-   * it via the same `mergeRunMetadata` path the legacy runner used, so
-   * the dashboard sees the same shape. Later keys win.
+   * step and flushed when the step completes; the durable engine merges
+   * it into the run's metadata (`persistStepObservability`). Later keys
+   * win.
    */
   setMetadata(data: Record<string, unknown>): Promise<void>;
   /**
@@ -98,9 +97,8 @@ export interface Step<TInput, TOutput> {
 }
 
 /**
- * The result of running one step. Engine adapters persist these into the
- * `workflow_step_runs` table (Phase 1b) so subsequent runs can skip
- * completed steps. `observability` carries the snapshot of
+ * The result of running one step, as `runWorkflowSteps` reports it per
+ * step. `observability` carries the snapshot of
  * `ctx.setMetadata` / `ctx.step` / `ctx.agentEvents` recorded during
  * the step; undefined when no hooks were used.
  */

package/src/workflow-steps/workflow.ts

@@ -16,7 +16,8 @@
  * matches the final step's `output` schema.
  *
  * Workflows-as-data — the result is consumable by any engine adapter
- * (in-process today; sandbox + Inngest/Temporal in future PRs).
+ * (in-process `runWorkflow`; the sandbox runner one step at a time under
+ * Temporal).
  */
 
 import type { z } from "zod";

package/src/workflows/engine.ts

@@ -6,7 +6,7 @@
  * runner.
  *
  * Errors classified into `WorkflowError` (user code threw) vs `EngineError`
- * (platform problem) for the runner harness to surface upstream.
+ * (platform problem).
  */
 
 import type { WorkflowHooks } from "../types/workflow.js";
@@ -53,7 +53,7 @@ export class EngineError extends Error {
   }
 }
 
-/** Classify any thrown value into the wire-level `kind` expected by `/fail`. */
+/** Classify any thrown value as a `workflow` or an `engine` failure. */
 export function classifyError(err: unknown): "workflow" | "engine" {
   if (err instanceof WorkflowError) return "workflow";
   if (err instanceof EngineError)   return "engine";
@@ -92,9 +92,7 @@ export interface RunWorkflowOptions {
   onStepStarted?:   RunWorkflowStepsOpts<unknown, unknown>["onStepStarted"];
   onStepCompleted?: RunWorkflowStepsOpts<unknown, unknown>["onStepCompleted"];
   onStepFailed?:    RunWorkflowStepsOpts<unknown, unknown>["onStepFailed"];
-  /** Provider-specific child workflow invocation. Temporal/Inngest providers
-   *  inject their native child-workflow primitive; the LocalProvider injects
-   *  the public Agent Compose API client. */
+  /** Child workflow invocation. Unset, a step's `invokeChild` throws. */
   invokeChild?:     InvokeChild;
 }