@quintinshaw/pi-dynamic-workflows 1.7.1 → 1.8.0

package/README.md

@@ -98,6 +98,7 @@ return { inventory, summary }
 | `parallel(thunks)` | Run an array of `() => agent(...)` thunks concurrently. Results returned in input order. |
 | `pipeline(items, ...stages)` | Fan items out through sequential stages. Each stage receives `(prev, original, index)`. |
 | `phase(title)` | Mark the current phase for the live progress view. |
+| `workflow(name, args)` | Run a saved workflow inline and return its result (one level deep; shares the global caps). |
 | `log(message)` | Append a workflow-level log line. |
 | `args` | Optional JSON value passed via the tool's `args` parameter. |
 | `budget` | `{ total, spent(), remaining() }` token-budget tracker. |
@@ -149,18 +150,13 @@ Scripts run inside a Node `vm` sandbox. Intentionally unavailable: `Date.now()`,
 - **`/workflows` command** — list, inspect, stop, pause, **resume**, and remove background runs; runs started with `background: true` are reachable from the command
 - **Bundled `/deep-research` & `/adversarial-review`** — `/deep-research` runs real web searches (via built-in `web_search` / `web_fetch` tools), extracts claims, cross-checks them across sources, and reports only what survived; `/adversarial-review` investigates a task then has independent skeptics try to refute each finding, keeping only those that clear an agreement threshold
 - **Saved workflows as `/<name>`** — save a run's script with `/workflows save <name>` and it becomes a reusable slash command; arguments are parsed (`key=value` and positionals) and passed through as `args`
+- **Nested `workflow()`** — call `await workflow('saved-name', args)` inside a script to run a saved workflow inline; nesting is one level deep and shares the parent's concurrency limiter, agent counter, and token budget so the global caps hold
 - **Resume** — each agent result is journaled by a deterministic call index; resuming replays the unchanged prefix from cache (no re-run, no tokens) and runs only new or edited calls live
 - **Worktree isolation** — `isolation: "worktree"` runs an agent in its own git worktree on a throwaway branch, so parallel agents can edit the same files without conflict; the worktree is torn down after (results are not auto-merged), and it falls back to a logged no-op outside a git repo
 - **Safety limits** — 1000-agent cap (`maxAgents`), per-agent timeout (`agentTimeoutMs`), recoverable-vs-fatal error classification
 - **Live progress + token/cost display**, `Esc` to abort
 - **Log persistence** to `.pi/workflows/runs/`
 
-## Roadmap
-
-Tracked toward closer parity with Claude Code dynamic workflows:
-
-- **Nested `workflow()`** to compose saved workflows inline
-
 ## How it works
 
 ```text

package/dist/index.d.ts

@@ -21,7 +21,7 @@ export { parseCommandArgs, registerAllSavedWorkflows, registerSavedWorkflow, } f
 export type { StructuredOutputCapture, StructuredOutputToolOptions } from "./structured-output.js";
 export { createStructuredOutputTool } from "./structured-output.js";
 export { createWebFetchTool, createWebSearchTool, createWebTools } from "./web-tools.js";
-export type { AgentOptions, JournalEntry, WorkflowMeta, WorkflowMetaPhase, WorkflowRunOptions, WorkflowRunResult, } from "./workflow.js";
+export type { AgentOptions, JournalEntry, SharedRuntime, WorkflowMeta, WorkflowMetaPhase, WorkflowRunOptions, WorkflowRunResult, } from "./workflow.js";
 export { parseWorkflowScript, runWorkflow } from "./workflow.js";
 export { registerWorkflowCommands } from "./workflow-commands.js";
 export type { ManagedRun, WorkflowManagerOptions } from "./workflow-manager.js";

package/dist/workflow-manager.d.ts

@@ -23,12 +23,15 @@ export interface ManagedRun {
 export interface WorkflowManagerOptions {
     cwd?: string;
     concurrency?: number;
+    /** Resolve a saved-workflow name to its script, enabling nested `workflow('name')`. */
+    loadSavedWorkflow?: (name: string) => string | undefined;
 }
 export declare class WorkflowManager extends EventEmitter {
     private runs;
     private persistence;
     private cwd;
     private concurrency;
+    private loadSavedWorkflow?;
     constructor(options?: WorkflowManagerOptions);
     /**
      * Start a workflow in the background.

package/dist/workflow-manager.js

@@ -10,10 +10,12 @@ export class WorkflowManager extends EventEmitter {
     persistence;
     cwd;
     concurrency;
+    loadSavedWorkflow;
     constructor(options = {}) {
         super();
         this.cwd = options.cwd ?? process.cwd();
         this.concurrency = options.concurrency ?? 8;
+        this.loadSavedWorkflow = options.loadSavedWorkflow;
         this.persistence = createRunPersistence(this.cwd);
     }
     /**
@@ -99,6 +101,7 @@ export class WorkflowManager extends EventEmitter {
                 args,
                 signal: managed.controller.signal,
                 concurrency: this.concurrency,
+                loadSavedWorkflow: this.loadSavedWorkflow,
                 resumeJournal,
                 resumeFromRunId: resumeJournal ? managed.runId : undefined,
                 onAgentJournal: (entry) => {

package/dist/workflow-tool.js

@@ -27,8 +27,9 @@ const workflowToolSchema = Type.Object({
     })),
 });
 export function createWorkflowTool(options = {}) {
+    const storage = options.storage ?? createWorkflowStorage(options.cwd ?? process.cwd());
     const manager = options.manager ?? new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
-    const _storage = options.storage ?? createWorkflowStorage(options.cwd ?? process.cwd());
+    const loadSavedWorkflow = (name) => storage.load(name)?.script;
     return defineTool({
         name: "workflow",
         label: "Workflow",
@@ -52,6 +53,7 @@ export function createWorkflowTool(options = {}) {
             "For workflow, if agent() needs machine-readable output, pass a plain JSON Schema via opts.schema; agent() will return the validated object. Use JSON Schema syntax, not TypeScript or TypeBox constructors.",
             "For workflow, do not assume the parent assistant has repository code context inside subagents; include enough task context and relevant paths in each agent prompt.",
             "For workflow, set background: true to run asynchronously. The workflow will return immediately with a run ID that can be used to check status later.",
+            "For workflow, you may call `await workflow('saved-name', argsObject)` to run a saved workflow inline and use its result; nesting is one level deep only, and the global 16-concurrent / 1000-total caps hold across the nesting.",
         ],
         parameters: workflowToolSchema,
         prepareArguments(args) {
@@ -100,6 +102,7 @@ export function createWorkflowTool(options = {}) {
                     concurrency: options.concurrency,
                     maxAgents: params.maxAgents,
                     agentTimeoutMs: params.agentTimeoutMs,
+                    loadSavedWorkflow,
                     onLog(message) {
                         snapshot.logs.push(message);
                         update();

package/dist/workflow.d.ts

@@ -18,6 +18,23 @@ export interface JournalEntry {
     hash: string;
     result: unknown;
 }
+/**
+ * Global resources shared across a run and any workflow() nested inside it, so
+ * the 16-concurrent / 1000-total caps and the token budget hold across nesting
+ * instead of each level getting its own limiter and counters.
+ */
+export interface SharedRuntime {
+    limiter: <T>(fn: () => Promise<T>) => Promise<T>;
+    agentCount: number;
+    spent: number;
+    tokenUsage: {
+        input: number;
+        output: number;
+        total: number;
+        cost: number;
+    };
+    depth: number;
+}
 export interface WorkflowRunOptions extends WorkflowAgentOptions {
     args?: unknown;
     agent?: Pick<WorkflowAgent, "run">;
@@ -38,6 +55,10 @@ export interface WorkflowRunOptions extends WorkflowAgentOptions {
     resumeFromRunId?: string;
     /** Called after each live agent completes so the caller can persist the journal. */
     onAgentJournal?: (entry: JournalEntry) => void;
+    /** Internal: shared runtime inherited by a nested workflow() call. */
+    sharedRuntime?: SharedRuntime;
+    /** Resolve a saved-workflow name to its script, enabling `workflow('name', args)`. */
+    loadSavedWorkflow?: (name: string) => string | undefined;
     onLog?: (message: string) => void;
     onPhase?: (title: string) => void;
     onAgentStart?: (event: {

package/dist/workflow.js

@@ -27,14 +27,19 @@ export async function runWorkflow(script, options = {}) {
     const state = {
         logs: [],
         phases: [],
-        agentCount: 0,
         callSeq: 0,
-        spent: 0,
-        tokenUsage: { input: 0, output: 0, total: 0, cost: 0 },
     };
     const agentRunner = options.agent ?? new WorkflowAgent(options);
     const concurrency = Math.max(1, Math.min(options.concurrency ?? Math.max(1, (globalThis.navigator?.hardwareConcurrency ?? 8) - 2), MAX_CONCURRENCY));
-    const limiter = createLimiter(concurrency);
+    // Global caps + budget are shared with any nested workflow() so they hold across nesting.
+    const shared = options.sharedRuntime ?? {
+        limiter: createLimiter(concurrency),
+        agentCount: 0,
+        spent: 0,
+        tokenUsage: { input: 0, output: 0, total: 0, cost: 0 },
+        depth: 0,
+    };
+    const limiter = shared.limiter;
     const log = (message) => {
         const text = String(message);
         state.logs.push(text);
@@ -48,8 +53,8 @@ export async function runWorkflow(script, options = {}) {
     };
     const budget = Object.freeze({
         total: options.tokenBudget ?? null,
-        spent: () => state.spent,
-        remaining: () => (options.tokenBudget == null ? Infinity : Math.max(0, options.tokenBudget - state.spent)),
+        spent: () => shared.spent,
+        remaining: () => (options.tokenBudget == null ? Infinity : Math.max(0, options.tokenBudget - shared.spent)),
     });
     const throwIfAborted = () => {
         if (options.signal?.aborted) {
@@ -59,7 +64,7 @@ export async function runWorkflow(script, options = {}) {
     const agent = async (prompt, agentOptions = {}) => {
         throwIfAborted();
         // Check agent limit
-        if (state.agentCount >= maxAgents) {
+        if (shared.agentCount >= maxAgents) {
             throw new WorkflowError(`Agent limit exceeded (${maxAgents}). Use maxAgents option to increase the limit.`, WorkflowErrorCode.AGENT_LIMIT_EXCEEDED, { recoverable: false });
         }
         if (budget.total !== null && budget.remaining() <= 0) {
@@ -79,15 +84,15 @@ export async function runWorkflow(script, options = {}) {
         // consuming a concurrency slot, tokens, or a real subagent run.
         const cached = options.resumeJournal?.get(callIndex);
         if (cached && cached.hash === callHash) {
-            state.agentCount++;
-            const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
+            shared.agentCount++;
+            const label = requestedLabel || defaultAgentLabel(assignedPhase, shared.agentCount);
             options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: modelSpec });
             options.onAgentEnd?.({ label, phase: assignedPhase, result: cached.result, tokens: 0 });
             return cached.result;
         }
         return limiter(async () => {
-            state.agentCount++;
-            const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
+            shared.agentCount++;
+            const label = requestedLabel || defaultAgentLabel(assignedPhase, shared.agentCount);
             const timeout = agentOptions.timeoutMs ?? agentTimeoutMs;
             options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: modelSpec });
             // Optional per-agent worktree isolation (deterministic name -> stable resume keys).
@@ -104,12 +109,12 @@ export async function runWorkflow(script, options = {}) {
             const recordTokens = (result) => {
                 const tokens = usage && usage.total > 0 ? usage.total : estimateTokens(result) + estimateTokens(prompt);
                 if (usage) {
-                    state.tokenUsage.input += usage.input;
-                    state.tokenUsage.output += usage.output;
-                    state.tokenUsage.cost += usage.cost;
+                    shared.tokenUsage.input += usage.input;
+                    shared.tokenUsage.output += usage.output;
+                    shared.tokenUsage.cost += usage.cost;
                 }
-                state.tokenUsage.total += tokens;
-                state.spent += tokens;
+                shared.tokenUsage.total += tokens;
+                shared.spent += tokens;
                 return tokens;
             };
             try {
@@ -198,10 +203,40 @@ export async function runWorkflow(script, options = {}) {
             return value;
         }));
     };
+    // Nested workflow(): run a saved workflow (or a raw script) inline, sharing this
+    // run's limiter/counters/budget so the global caps hold. One level deep only.
+    const workflowFn = async (nameOrScript, childArgs) => {
+        throwIfAborted();
+        if (shared.depth >= 1) {
+            throw new WorkflowError("workflow() can nest only one level deep", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+                recoverable: false,
+            });
+        }
+        const resolved = options.loadSavedWorkflow?.(String(nameOrScript));
+        const childScript = resolved ?? String(nameOrScript);
+        shared.depth++;
+        try {
+            const child = await runWorkflow(childScript, {
+                ...options,
+                args: childArgs,
+                sharedRuntime: shared,
+                // A nested run is its own script; never reuse the parent's resume journal.
+                resumeJournal: undefined,
+                resumeFromRunId: undefined,
+                runId: `${runId}-nested${shared.depth}`,
+                persistLogs: false,
+            });
+            return child.result;
+        }
+        finally {
+            shared.depth--;
+        }
+    };
     const context = vm.createContext({
         agent,
         parallel,
         pipeline,
+        workflow: workflowFn,
         log,
         phase,
         args: options.args,
@@ -233,16 +268,16 @@ export async function runWorkflow(script, options = {}) {
         log(`Logs persisted to ${logFile}`);
     }
     // Emit final token usage
-    options.onTokenUsage?.(state.tokenUsage);
+    options.onTokenUsage?.(shared.tokenUsage);
     return {
         meta,
         result: result,
         logs: state.logs,
         phases: state.phases,
-        agentCount: state.agentCount,
+        agentCount: shared.agentCount,
         durationMs: Date.now() - started,
         runId,
-        tokenUsage: state.tokenUsage,
+        tokenUsage: shared.tokenUsage,
     };
 }
 export function parseWorkflowScript(script) {

package/extensions/workflow.ts

@@ -12,8 +12,8 @@ export default function extension(pi: ExtensionAPI) {
   // Single manager/storage shared by the workflow tool and the /workflows command,
   // so background runs started by the tool are reachable from the command.
   const cwd = process.cwd();
-  const manager = new WorkflowManager({ cwd });
   const storage = createWorkflowStorage(cwd);
+  const manager = new WorkflowManager({ cwd, loadSavedWorkflow: (name) => storage.load(name)?.script });
 
   const workflowTool = createWorkflowTool({ cwd, manager, storage });
   pi.registerTool(workflowTool);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quintinshaw/pi-dynamic-workflows",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Claude-Code-style dynamic workflow orchestration for Pi.",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -49,6 +49,7 @@ export { createWebFetchTool, createWebSearchTool, createWebTools } from "./web-t
 export type {
   AgentOptions,
   JournalEntry,
+  SharedRuntime,
   WorkflowMeta,
   WorkflowMetaPhase,
   WorkflowRunOptions,

package/src/workflow-manager.ts

@@ -32,6 +32,8 @@ export interface ManagedRun {
 export interface WorkflowManagerOptions {
   cwd?: string;
   concurrency?: number;
+  /** Resolve a saved-workflow name to its script, enabling nested `workflow('name')`. */
+  loadSavedWorkflow?: (name: string) => string | undefined;
 }
 
 export class WorkflowManager extends EventEmitter {
@@ -39,11 +41,13 @@ export class WorkflowManager extends EventEmitter {
   private persistence: RunPersistence;
   private cwd: string;
   private concurrency: number;
+  private loadSavedWorkflow?: (name: string) => string | undefined;
 
   constructor(options: WorkflowManagerOptions = {}) {
     super();
     this.cwd = options.cwd ?? process.cwd();
     this.concurrency = options.concurrency ?? 8;
+    this.loadSavedWorkflow = options.loadSavedWorkflow;
     this.persistence = createRunPersistence(this.cwd);
   }
 
@@ -144,6 +148,7 @@ export class WorkflowManager extends EventEmitter {
         args,
         signal: managed.controller.signal,
         concurrency: this.concurrency,
+        loadSavedWorkflow: this.loadSavedWorkflow,
         resumeJournal,
         resumeFromRunId: resumeJournal ? managed.runId : undefined,
         onAgentJournal: (entry) => {

package/src/workflow-tool.ts

@@ -61,8 +61,9 @@ export interface WorkflowToolOptions {
 }
 
 export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefinition<typeof workflowToolSchema, any> {
+  const storage = options.storage ?? createWorkflowStorage(options.cwd ?? process.cwd());
   const manager = options.manager ?? new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
-  const _storage = options.storage ?? createWorkflowStorage(options.cwd ?? process.cwd());
+  const loadSavedWorkflow = (name: string) => storage.load(name)?.script;
 
   return defineTool({
     name: "workflow",
@@ -88,6 +89,7 @@ export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefin
       "For workflow, if agent() needs machine-readable output, pass a plain JSON Schema via opts.schema; agent() will return the validated object. Use JSON Schema syntax, not TypeScript or TypeBox constructors.",
       "For workflow, do not assume the parent assistant has repository code context inside subagents; include enough task context and relevant paths in each agent prompt.",
       "For workflow, set background: true to run asynchronously. The workflow will return immediately with a run ID that can be used to check status later.",
+      "For workflow, you may call `await workflow('saved-name', argsObject)` to run a saved workflow inline and use its result; nesting is one level deep only, and the global 16-concurrent / 1000-total caps hold across the nesting.",
     ],
     parameters: workflowToolSchema,
     prepareArguments(args) {
@@ -140,6 +142,7 @@ export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefin
           concurrency: options.concurrency,
           maxAgents: params.maxAgents,
           agentTimeoutMs: params.agentTimeoutMs,
+          loadSavedWorkflow,
           onLog(message) {
             snapshot.logs.push(message);
             update();

package/src/workflow.ts

@@ -32,6 +32,19 @@ export interface JournalEntry {
   result: unknown;
 }
 
+/**
+ * Global resources shared across a run and any workflow() nested inside it, so
+ * the 16-concurrent / 1000-total caps and the token budget hold across nesting
+ * instead of each level getting its own limiter and counters.
+ */
+export interface SharedRuntime {
+  limiter: <T>(fn: () => Promise<T>) => Promise<T>;
+  agentCount: number;
+  spent: number;
+  tokenUsage: { input: number; output: number; total: number; cost: number };
+  depth: number;
+}
+
 export interface WorkflowRunOptions extends WorkflowAgentOptions {
   args?: unknown;
   agent?: Pick<WorkflowAgent, "run">;
@@ -52,6 +65,10 @@ export interface WorkflowRunOptions extends WorkflowAgentOptions {
   resumeFromRunId?: string;
   /** Called after each live agent completes so the caller can persist the journal. */
   onAgentJournal?: (entry: JournalEntry) => void;
+  /** Internal: shared runtime inherited by a nested workflow() call. */
+  sharedRuntime?: SharedRuntime;
+  /** Resolve a saved-workflow name to its script, enabling `workflow('name', args)`. */
+  loadSavedWorkflow?: (name: string) => string | undefined;
   onLog?: (message: string) => void;
   onPhase?: (title: string) => void;
   onAgentStart?: (event: { label: string; phase?: string; prompt: string; model?: string }) => void;
@@ -90,16 +107,8 @@ interface RuntimeState {
   currentPhase?: string;
   logs: string[];
   phases: string[];
-  agentCount: number;
   /** Monotonic, assigned at lexical agent() call time — the stable resume key. */
   callSeq: number;
-  spent: number;
-  tokenUsage: {
-    input: number;
-    output: number;
-    total: number;
-    cost: number;
-  };
 }
 
 type AnyNode = Node & { [key: string]: any; start: number; end: number };
@@ -130,10 +139,7 @@ export async function runWorkflow<T = unknown>(
   const state: RuntimeState = {
     logs: [],
     phases: [],
-    agentCount: 0,
     callSeq: 0,
-    spent: 0,
-    tokenUsage: { input: 0, output: 0, total: 0, cost: 0 },
   };
 
   const agentRunner = options.agent ?? new WorkflowAgent(options);
@@ -141,7 +147,15 @@ export async function runWorkflow<T = unknown>(
     1,
     Math.min(options.concurrency ?? Math.max(1, (globalThis.navigator?.hardwareConcurrency ?? 8) - 2), MAX_CONCURRENCY),
   );
-  const limiter = createLimiter(concurrency);
+  // Global caps + budget are shared with any nested workflow() so they hold across nesting.
+  const shared: SharedRuntime = options.sharedRuntime ?? {
+    limiter: createLimiter(concurrency),
+    agentCount: 0,
+    spent: 0,
+    tokenUsage: { input: 0, output: 0, total: 0, cost: 0 },
+    depth: 0,
+  };
+  const limiter = shared.limiter;
 
   const log = (message: string) => {
     const text = String(message);
@@ -157,8 +171,8 @@ export async function runWorkflow<T = unknown>(
 
   const budget = Object.freeze({
     total: options.tokenBudget ?? null,
-    spent: () => state.spent,
-    remaining: () => (options.tokenBudget == null ? Infinity : Math.max(0, options.tokenBudget - state.spent)),
+    spent: () => shared.spent,
+    remaining: () => (options.tokenBudget == null ? Infinity : Math.max(0, options.tokenBudget - shared.spent)),
   });
 
   const throwIfAborted = () => {
@@ -171,7 +185,7 @@ export async function runWorkflow<T = unknown>(
     throwIfAborted();
 
     // Check agent limit
-    if (state.agentCount >= maxAgents) {
+    if (shared.agentCount >= maxAgents) {
       throw new WorkflowError(
         `Agent limit exceeded (${maxAgents}). Use maxAgents option to increase the limit.`,
         WorkflowErrorCode.AGENT_LIMIT_EXCEEDED,
@@ -199,16 +213,16 @@ export async function runWorkflow<T = unknown>(
     // consuming a concurrency slot, tokens, or a real subagent run.
     const cached = options.resumeJournal?.get(callIndex);
     if (cached && cached.hash === callHash) {
-      state.agentCount++;
-      const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
+      shared.agentCount++;
+      const label = requestedLabel || defaultAgentLabel(assignedPhase, shared.agentCount);
       options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: modelSpec });
       options.onAgentEnd?.({ label, phase: assignedPhase, result: cached.result, tokens: 0 });
       return cached.result;
     }
 
     return limiter(async () => {
-      state.agentCount++;
-      const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
+      shared.agentCount++;
+      const label = requestedLabel || defaultAgentLabel(assignedPhase, shared.agentCount);
       const timeout = agentOptions.timeoutMs ?? agentTimeoutMs;
 
       options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: modelSpec });
@@ -227,12 +241,12 @@ export async function runWorkflow<T = unknown>(
       const recordTokens = (result: unknown): number => {
         const tokens = usage && usage.total > 0 ? usage.total : estimateTokens(result) + estimateTokens(prompt);
         if (usage) {
-          state.tokenUsage.input += usage.input;
-          state.tokenUsage.output += usage.output;
-          state.tokenUsage.cost += usage.cost;
+          shared.tokenUsage.input += usage.input;
+          shared.tokenUsage.output += usage.output;
+          shared.tokenUsage.cost += usage.cost;
         }
-        state.tokenUsage.total += tokens;
-        state.spent += tokens;
+        shared.tokenUsage.total += tokens;
+        shared.spent += tokens;
         return tokens;
       };
 
@@ -331,10 +345,40 @@ export async function runWorkflow<T = unknown>(
     );
   };
 
+  // Nested workflow(): run a saved workflow (or a raw script) inline, sharing this
+  // run's limiter/counters/budget so the global caps hold. One level deep only.
+  const workflowFn = async (nameOrScript: string, childArgs?: unknown) => {
+    throwIfAborted();
+    if (shared.depth >= 1) {
+      throw new WorkflowError("workflow() can nest only one level deep", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+        recoverable: false,
+      });
+    }
+    const resolved = options.loadSavedWorkflow?.(String(nameOrScript));
+    const childScript = resolved ?? String(nameOrScript);
+    shared.depth++;
+    try {
+      const child = await runWorkflow(childScript, {
+        ...options,
+        args: childArgs,
+        sharedRuntime: shared,
+        // A nested run is its own script; never reuse the parent's resume journal.
+        resumeJournal: undefined,
+        resumeFromRunId: undefined,
+        runId: `${runId}-nested${shared.depth}`,
+        persistLogs: false,
+      });
+      return child.result;
+    } finally {
+      shared.depth--;
+    }
+  };
+
   const context = vm.createContext({
     agent,
     parallel,
     pipeline,
+    workflow: workflowFn,
     log,
     phase,
     args: options.args,
@@ -369,17 +413,17 @@ export async function runWorkflow<T = unknown>(
   }
 
   // Emit final token usage
-  options.onTokenUsage?.(state.tokenUsage);
+  options.onTokenUsage?.(shared.tokenUsage);
 
   return {
     meta,
     result: result as T,
     logs: state.logs,
     phases: state.phases,
-    agentCount: state.agentCount,
+    agentCount: shared.agentCount,
     durationMs: Date.now() - started,
     runId,
-    tokenUsage: state.tokenUsage,
+    tokenUsage: shared.tokenUsage,
   };
 }