feat(agents): script mode — code-shaped orchestration for agents (#4239)

Add ScriptPlanner and ScriptRunner for agent orchestration via JavaScript scripts in QuickJS sandbox. Scripts can express loops, budget-scaled fan-out, dedup, and early exit — patterns a static DAG cannot.

Author: georgi

packages/agents/CLAUDE.md

@@ -260,6 +260,53 @@ const agent = new Agent({
 | `DEFAULT_MAX_STEPS` | 50 | `task-executor.ts` |
 | `MAX_RETRIES` (planning) | 3 | `task-planner.ts` |
 
+## Script Mode (code-shaped orchestration)
+
+The third planning mode next to `TaskPlan` and the graph planner: the LLM
+authors a JavaScript *orchestration script* (`ScriptPlanner`), and
+`ScriptRunner` executes it in the QuickJS sandbox. Every `agent()` call in the
+script runs a real `StepExecutor` sub-agent on the host. A script expresses
+what a static DAG cannot — loops until a condition holds, budget-scaled
+fan-out, dedup between rounds, early exit.
+
+```typescript
+const agent = new Agent({
+  name: "researcher",
+  objective: "Find and verify 5 claims about X",
+  provider, model,
+  useScriptPlanner: true,          // LLM writes the script
+  // script: "...",                // or supply one directly (skips planning)
+  maxConcurrentAgents: 8,          // semaphore over concurrent agent() calls
+  maxAgentCalls: 100               // lifetime cap per run
+});
+```
+
+Guest API (see `SCRIPT_PRELUDE` in `script-runner.ts`):
+
+| Primitive | Behavior |
+|---|---|
+| `await agent(prompt, opts?)` | Run a sub-agent. `opts.schema` → structured result via `finish_step`; `opts.tools` restricts the toolset; `opts.label` names progress events. Throws on failure. |
+| `await parallel(thunks)` | Concurrent thunks; a failure resolves to `null` instead of rejecting the batch. |
+| `await pipeline(items, ...stages)` | Each item flows through all stages independently (no barrier). Stages receive `(prev, originalItem, index)`. |
+| `log(message)` | Emits a `log_update` to the host event stream. |
+| `budget` | `maxAgentCalls`, `agentCalls()`, `remainingCalls()`, `await spentUsd()`. |
+| `inputs` | Caller-supplied inputs object. |
+
+The script's `return` value becomes `agent.getResults()`. Sub-agents share
+`context.memory` as usual, and concurrency is bounded host-side by a semaphore
+(`maxConcurrentAgents`, default 8) plus a lifetime call cap (`maxAgentCalls`,
+default 100) — calls past the cap fail with a budget error the script can
+handle (`budget.remainingCalls()` guards loops). Script failures (syntax
+error, uncaught exception, wall-clock timeout — default 60 min including
+sub-agent time) throw from `Agent.execute`.
+
+Host bridges never reject (the QuickJS handle-leak rule from
+`js-sandbox.ts` applies): `__runAgent` resolves `{ok, result|error}` envelopes
+and the guest `agent()` re-throws.
+
+Tests: `tests/script-runner.test.ts`, `tests/script-planner.test.ts`,
+`tests/agent-script-mode.test.ts`.
+
 ## Observing LLM Steps and Planning
 
 ### Execution Tree (CLI)

packages/agents/src/agent.ts

@@ -32,6 +32,8 @@ import { ParallelTaskExecutor } from "./parallel-task-executor.js";
 import { CompilerAgent } from "./compiler-agent.js";
 import { GraphPlanner } from "./graph-planner.js";
 import { AgentWorkflowRunner } from "./agent-workflow-runner.js";
+import { ScriptPlanner } from "./script-planner.js";
+import { ScriptRunner } from "./script-runner.js";
 import type { Tool } from "./tools/base-tool.js";
 import { gateTools } from "./tools/tool-permissions.js";
 import {
@@ -262,6 +264,24 @@ export interface AgentOptions {
    * graph executed by {@link AgentWorkflowRunner}.
    */
   useGraphPlanner?: boolean;
+  /**
+   * Use the script planner: the LLM authors a JavaScript orchestration
+   * script (loops, conditionals, budget-scaled fan-out) instead of a
+   * TaskPlan, and {@link ScriptRunner} executes it deterministically in the
+   * QuickJS sandbox — every `agent()` call in the script runs a real
+   * sub-agent. Takes precedence over {@link useGraphPlanner}.
+   */
+  useScriptPlanner?: boolean;
+  /**
+   * Pre-authored orchestration script. Skips planning entirely and runs the
+   * script directly (implies script mode). See {@link ScriptRunner} for the
+   * script API.
+   */
+  script?: string;
+  /** Script mode: concurrent `agent()` calls beyond this queue. Default 8. */
+  maxConcurrentAgents?: number;
+  /** Script mode: lifetime `agent()` call cap per run. Default 100. */
+  maxAgentCalls?: number;
   /** Node registry required when {@link useGraphPlanner} is true. */
   registry?: NodeRegistry;
   /**
@@ -339,6 +359,10 @@ export class Agent {
   private readonly autoPersistMemory: boolean;
   private readonly synthesizeRecall: boolean;
   private readonly useGraphPlanner: boolean;
+  private readonly useScriptPlanner: boolean;
+  private readonly script?: string;
+  private readonly maxConcurrentAgents?: number;
+  private readonly maxAgentCalls?: number;
   private readonly registry?: NodeRegistry;
   private readonly providers?: Record<string, BaseProvider>;
   private readonly securityMonitorEnabled: boolean;
@@ -374,6 +398,10 @@ export class Agent {
     this.autoPersistMemory = opts.autoPersistMemory === true;
     this.synthesizeRecall = opts.synthesizeRecall ?? true;
     this.useGraphPlanner = opts.useGraphPlanner === true;
+    this.useScriptPlanner = opts.useScriptPlanner === true;
+    this.script = opts.script;
+    this.maxConcurrentAgents = opts.maxConcurrentAgents;
+    this.maxAgentCalls = opts.maxAgentCalls;
     this.registry = opts.registry;
     this.providers = opts.providers;
     this.securityMonitorEnabled = opts.securityMonitor?.enabled === true;
@@ -654,6 +682,17 @@ export class Agent {
       return;
     }
 
+    // Script mode: LLM-authored (or pre-authored) orchestration script,
+    // executed deterministically by ScriptRunner.
+    if (this.script || this.useScriptPlanner) {
+      yield* this.executeScriptPlan(
+        context,
+        mergedSystemPrompt,
+        effectiveObjective
+      );
+      return;
+    }
+
     // Graph-native planner: build DAG of nodes directly.
     if (this.useGraphPlanner && this.registry) {
       yield* this.executeGraphPlan(context, mergedSystemPrompt);
@@ -910,6 +949,66 @@ export class Agent {
     }
   }
 
+  /**
+   * Script mode: obtain an orchestration script (pre-authored via the
+   * `script` option, otherwise written by ScriptPlanner) and execute it with
+   * ScriptRunner. The script's return value becomes the agent result.
+   */
+  private async *executeScriptPlan(
+    context: ProcessingContext,
+    systemPrompt: string | undefined,
+    objective: string
+  ): AsyncGenerator<ProcessingMessage> {
+    let script = this.script ?? null;
+
+    if (!script) {
+      log.info("Script planning phase started", { name: this.name });
+      const planner = new ScriptPlanner({
+        provider: this.provider,
+        model: this.planningModel,
+        tools: this.tools,
+        systemPrompt,
+        outputSchema: this.outputSchema,
+        inputs: this.inputs
+      });
+      const planGen = planner.plan(objective, context);
+      let planResult = await planGen.next();
+      while (!planResult.done) {
+        yield planResult.value;
+        planResult = await planGen.next();
+      }
+      script = planResult.value;
+      if (!script) {
+        throw new Error(
+          "ScriptPlanner failed to produce an orchestration script."
+        );
+      }
+    }
+
+    const runner = new ScriptRunner({
+      provider: this.provider,
+      model: this.model,
+      context,
+      tools: this.buildExecutorTools(),
+      systemPrompt,
+      inputs: this.inputs,
+      maxStepIterations: this.maxStepIterations,
+      maxConcurrentAgents: this.maxConcurrentAgents,
+      maxAgentCalls: this.maxAgentCalls
+    });
+
+    const runGen = runner.execute(script);
+    let next = await runGen.next();
+    while (!next.done) {
+      yield next.value;
+      next = await runGen.next();
+    }
+    this.results = next.value ?? null;
+
+    log.info("Agent completed", { name: this.name });
+    this.persistAgentRunMemory();
+  }
+
   /**
    * Graph-native plan: build a DAG of nodes via GraphPlanner, then execute it
    * with AgentWorkflowRunner.

packages/agents/src/index.ts

@@ -344,6 +344,17 @@ export type { ParallelTaskExecutorOptions } from "./parallel-task-executor.js";
 export { CompilerAgent } from "./compiler-agent.js";
 export type { CompilerAgentOptions } from "./compiler-agent.js";
 
+// Script-mode planning & execution (code-shaped orchestration)
+export { ScriptPlanner, validateScript } from "./script-planner.js";
+export type { ScriptPlannerOptions } from "./script-planner.js";
+export {
+  ScriptRunner,
+  SCRIPT_RESERVED_NAMES,
+  DEFAULT_MAX_CONCURRENT_AGENTS,
+  DEFAULT_MAX_AGENT_CALLS
+} from "./script-runner.js";
+export type { ScriptRunnerOptions } from "./script-runner.js";
+
 // Graph-native planning & execution
 export { GraphBuilder, AGENT_STEP_NODE_TYPE } from "./graph-builder.js";
 export { GraphPlanner } from "./graph-planner.js";