@agent-compose/sdk 0.8.5 → 0.8.7

package/src/types/api-runs.ts

@@ -97,6 +97,11 @@ export interface InvokeInlineAndWaitOptions extends InvokeInlineOptions {
 
 export interface InvokeResult {
   id: string;
+  /** The run is PARKED for its funding plan's reset: the person whose plan
+   *  pays for it has every plan out, so nothing runs until `until`, when it
+   *  starts by itself; `text` is the one line to pass on. Absent for a run
+   *  that boots now. */
+  hold?: { until: string; text: string };
 }
 
 export interface StreamRunLogsOptions {
@@ -334,6 +339,74 @@ export interface ListRunsOptions {
   limit?: number;
 }
 
+/** What started a run (`GET /factories/:slug/workflow-activity*`), read off
+ *  the dispatch stamps: a schedule's tick, a thread's scripted check, the
+ *  chat an agent's turn dispatched it from, the person who invoked it from
+ *  the dashboard, or the API key (the CLI, a script). */
+export type RunStartedBy =
+  | { kind: "schedule"; name: string | null }
+  | { kind: "check" }
+  | { kind: "chat"; conversationId: string; title: string | null }
+  | { kind: "person"; userId: string; name: string; image: string | null; avatarUrl: string | null }
+  | { kind: "key"; name: string }
+  | { kind: "unknown" };
+
+/** One run in a space's workflow activity: the runs list's summary plus
+ *  what started it. */
+export interface WorkflowActivityRun extends RunListEntry {
+  finalSummary: string | null;
+  /** Structured return value from the workflow, when it completed. */
+  output: unknown;
+  startedBy: RunStartedBy;
+}
+
+/** One stack in a space's workflow activity: a workflow that has run there
+ *  and its latest run. */
+export interface WorkflowActivityHead {
+  workflow: string;
+  latestRun: WorkflowActivityRun;
+}
+
+export interface ListWorkflowActivityOptions {
+  /** Factory the runs live in. Defaults to "default". */
+  factorySlug?: string;
+  /** Stacks per page (1–50, server default 20). */
+  limit?: number;
+  /** The previous page's `nextCursor`. */
+  cursor?: string;
+  /** A search (at most 100 characters): every run whose workflow name,
+   *  title, failure or summary contains it, without case — reaching past
+   *  the last 90 days the listing shows without one. */
+  q?: string;
+}
+
+export interface ListWorkflowRunsOptions {
+  /** Factory the runs live in. Defaults to "default". */
+  factorySlug?: string;
+  /** The registered workflow name, exactly. */
+  workflow: string;
+  /** Runs per page (1–50, server default 10). */
+  limit?: number;
+  /** The previous page's `nextCursor`. */
+  cursor?: string;
+  /** A search (at most 100 characters): the workflow's runs whose title,
+   *  failure or summary contains it, without case — reaching past the last
+   *  90 days the listing shows without one. */
+  q?: string;
+}
+
+export interface WorkflowActivityPage {
+  workflows: WorkflowActivityHead[];
+  hasMore: boolean;
+  nextCursor: string | null;
+}
+
+export interface WorkflowRunsPage {
+  runs: WorkflowActivityRun[];
+  hasMore: boolean;
+  nextCursor: string | null;
+}
+
 export interface TimelineEvent {
   kind: string;
   at: string;

package/src/types/api-scopes.ts

@@ -36,9 +36,10 @@ export type DocumentCapability = "read" | "write";
 export type TemplateCapability = "read" | "write" | "invoke" | "see_runs";
 
 /** One grant on an artifact scope. `team`/`user` are the editable tiers
- *  carried on a PUT (full-replace); `session`/`project` are DERIVED,
- *  read-only arms that appear only on READ payloads (the routes that manage
- *  them own their mutation — a scope PUT rejects them, 400 `invalid_principal`).
+ *  carried on a PUT (full-replace); `session`/`project`/`conversation`/
+ *  `worker` are DERIVED, read-only arms that appear only on READ payloads
+ *  (the routes that manage them own their mutation — a scope PUT rejects
+ *  them, 400 `invalid_principal`).
  *
  *  Session and project grants carry FIXED capabilities `['read','write']`:
  *  the fs-gateway is concealment-only (no read/write dimension at the mount),
@@ -58,6 +59,30 @@ export type ScopeGrant =
        *  being a project member (share implies unshare). Null only for
        *  transitional/legacy rows. */
       projectObjectId: string | null;
+      /** The people in the project: the row's reach. */
+      memberCount: number;
+      capabilities: string[];
+    }
+  /** A chat's grant (scope-at-birth, documents): reach derives LIVE from the
+   *  chat's tier and member rows. `memberCount` is null for a public channel,
+   *  whose audience is the whole team rather than its member rows. */
+  | {
+      principal: "conversation";
+      conversationId: string;
+      conversationTitle: string | null;
+      memberCount: number | null;
+      capabilities: string[];
+    }
+  /** The grant a chat's WORKER session holds on what it wrote: not a group
+   *  of people. The readers of the chat it works for (`chatId`) reach the
+   *  file through it while the worker's project boundary holds. `title` is
+   *  the work's (the session's) title. */
+  | {
+      principal: "worker";
+      conversationId: string;
+      title: string | null;
+      chatId: string;
+      chatTitle: string | null;
       capabilities: string[];
     };
 
@@ -71,6 +96,10 @@ export interface ArtifactScope {
   /** Templates only — the owning conversation binding (a grant source:
    *  members of that conversation reach the template via their role). */
   conversationId?: string | null;
+  /** Documents only — born of a shared chat's work (Ivy's publish, a
+   *  worker's output for a chat). Such a document is shared by the people
+   *  who can edit it, whoever its owner is; so is one with no owner. */
+  bornOfChatWork?: boolean;
   grants: ScopeGrant[];
 }
 

package/src/types/conversation-stream.ts

@@ -130,6 +130,11 @@ export interface ConversationTurnStateEvent {
   pendingCount: number;
   at: number;
   partial: true;
+  /** The running turn is WRITING words that will be sent — the typing
+   *  indicator's one signal (a running turn that thinks, calls tools,
+   *  reacts or notes is not writing). Absent when the emitter cannot know;
+   *  consumers inherit their previous frame's value, and `idle` resets it. */
+  writing?: boolean;
   /** When the open turn started (ms) — carried by the connect-time
    *  snapshot frame only; absent on live transition frames. */
   startedAt?: number | null;

package/src/types/execution-context.ts

@@ -1,4 +1,4 @@
-/** Shared execution context capabilities for workflow functions and steps. */
+/** Shared execution context capabilities for workflow steps. */
 
 import type { InvokeAndWaitOptions, RunStatus } from "./api-runs.js";
 import type { RequestContext } from "../request-context/request-context.js";

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";
   }[];
 }
@@ -269,6 +334,28 @@ export interface AgentMessageSubagentUserMessage extends AgentMessageBase {
   parentToolUseId: string;
 }
 
+/** The harness's OWN report of the model it is running — never the
+ *  platform's configuration (owner 2026-10-06: "It's very difficult to
+ *  tell which model did this work"). claude-code names it twice: once on
+ *  `system`/`init` (`model`, the session's resolved model) and on every
+ *  top-level `assistant` event (`message.model`, the id the API answered
+ *  with — the truth after a `/model` switch or a fallback; `<synthetic>`
+ *  is the harness's own voice and names none; a subagent's events name the
+ *  subagent's model, not the worker's, and are left out). The normaliser
+ *  emits one report per naming, so a consumer that stamps the turn's
+ *  models dedupes in order of first appearance and keeps every distinct
+ *  id (a mid-turn switch records both). codex's `exec --json` events and
+ *  opencode's `run --format json` lines carry no model at all (verified
+ *  against both sources, 2026-10-06): those harnesses emit none, and the
+ *  record stays honestly empty. Additive kind: existing producers never
+ *  emit it. */
+export interface AgentMessageModelReport extends AgentMessageBase {
+  type: "model_report";
+  /** The model id as the harness reports it, minus claude-code's
+   *  `[1m]`-style context-window marker (runtimes/_reported-model.ts). */
+  model: string;
+}
+
 export type AgentMessage =
   | AgentMessageInit
   | AgentMessageText
@@ -280,12 +367,14 @@ export type AgentMessage =
   | AgentMessageError
   | AgentMessageUsage
   | AgentMessageUsageDelta
+  | AgentMessagePlanLimits
   | AgentMessagePlan
   | AgentMessageTaskNotification
   | AgentMessageTaskProgress
   | AgentMessageHarnessNotice
   | AgentMessageCompaction
-  | AgentMessageSubagentUserMessage;
+  | AgentMessageSubagentUserMessage
+  | AgentMessageModelReport;
 
 /** Status block the agent emits to signal iteration completion or blockers. */
 export interface AgentStatus {

package/src/types/runtime.ts

@@ -256,7 +256,13 @@ 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
@@ -316,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;
 }
 

package/src/workflows/invoke-child.ts

@@ -28,8 +28,8 @@ export function deriveInvokeChildIdempotencyKey(parentRunId: string, childName:
 }
 
 /**
- * Build the public-API child workflow invoker used by legacy and sandboxed
- * workflow execution. Provider-backed engines may inject a different
+ * Build the public-API child workflow invoker used by sandboxed workflow
+ * execution (the step runner). Provider-backed engines may inject a different
  * implementation (Temporal child workflow, Inngest invoke, etc.).
  */
 export function buildInvokeChild(