@haoyiyin/workflow 0.2.11 → 0.3.0

package/src/agents/dispatcher.ts

@@ -1,13 +1,14 @@
 /**
- * Subagent Dispatcher - Spawns isolated subagents to do all real work
+ * Subagent Dispatcher - Spawns isolated subagents with fresh context
  *
- * Constructs prompts from contracts, manages timeouts, validates outputs,
- * and collects results. Uses a pluggable executor backend so the dispatch
- * mechanism can be swapped (process, HTTP, in-process) without changing
- * the orchestration logic.
+ * Key principle: Each subagent gets ONLY the context it needs.
+ * - No history pollution from main agent
+ * - Minimal, focused prompts
+ * - Token budget enforcement
+ * - Resilient dispatch with circuit breaker and retry
  */
 
-import { nanoid } from 'nanoid';
+import { nanoid } from 'nanoid'
 import type {
   SubagentConfig,
   SubagentContract,
@@ -15,81 +16,70 @@ import type {
   SubagentArtifact,
   PermissionSet,
   SubagentRole,
-} from './types.js';
-import type { Logger } from '../types.js';
+} from './types.js'
+import { TokenBudget, BudgetExceededError } from './token-budget.js'
+import { ResilientDispatcher } from './resilience.js'
+import type { Logger } from '../types.js'
 
 // ---------------------------------------------------------------------------
-// Executor abstraction
+// Executor Types (re-exported for index.ts compatibility)
 // ---------------------------------------------------------------------------
 
 export interface ExecutorOptions {
-  id: string;
-  model?: string;
-  timeout?: number;
-  workDir?: string;
+  id: string
+  model?: string
+  timeout?: number
+  workDir?: string
 }
 
 export interface ExecutorResult {
-  output: string;
-  tokensUsed: number;
-  errors: string[];
+  output: string
+  tokensUsed: number
+  errors: string[]
 }
 
 export interface SubagentExecutor {
-  execute(prompt: string, options: ExecutorOptions): Promise<ExecutorResult>;
-  abort(id: string): Promise<void>;
+  execute(prompt: string, options: ExecutorOptions): Promise<ExecutorResult>
+  abort(id: string): Promise<void>
 }
 
-// ---------------------------------------------------------------------------
-// Default executor (process-based)
-// ---------------------------------------------------------------------------
-
 export interface ProcessExecutorConfig {
-  /** CLI command to invoke (default: "claude") */
-  command: string;
-  /** CLI arguments appended after the prompt */
-  args: string[];
-  /** Environment variables to forward */
-  env: Record<string, string>;
+  command: string
+  args: string[]
+  env: Record<string, string>
 }
 
 const DEFAULT_PROCESS_CONFIG: ProcessExecutorConfig = {
   command: 'claude',
   args: ['--print', '--output-format', 'json'],
   env: {},
-};
+}
 
 /**
  * Creates a SubagentExecutor that spawns a subprocess for each dispatch.
- *
- * The executor writes the prompt to a temp file, invokes the configured
- * CLI command with `--input-file`, collects stdout/stderr, and cleans up.
  */
 export function createProcessExecutor(
-  config: Partial<ProcessExecutorConfig> = {},
+  config: Partial<ProcessExecutorConfig> = {}
 ): SubagentExecutor {
   const resolved: ProcessExecutorConfig = {
     ...DEFAULT_PROCESS_CONFIG,
     ...config,
-  };
+  }
 
-  const active = new Map<
-    string,
-    ReturnType<typeof import('child_process').spawn>
-  >();
+  const active = new Map<string, ReturnType<typeof import('child_process').spawn>>()
 
   return {
     async execute(prompt: string, options: ExecutorOptions): Promise<ExecutorResult> {
-      const { spawn } = await import('child_process');
-      const { writeFile, mkdir, rm } = await import('fs/promises');
-      const { join } = await import('path');
-      const { tmpdir } = await import('os');
+      const { spawn } = await import('child_process')
+      const { writeFile, mkdir, rm } = await import('fs/promises')
+      const { join } = await import('path')
+      const { tmpdir } = await import('os')
 
-      const workDir = options.workDir ?? join(tmpdir(), `yi-subagent-${options.id}`);
-      await mkdir(workDir, { recursive: true });
+      const workDir = options.workDir ?? join(tmpdir(), `yi-subagent-${options.id}`)
+      await mkdir(workDir, { recursive: true })
 
-      const promptPath = join(workDir, 'prompt.md');
-      await writeFile(promptPath, prompt, 'utf-8');
+      const promptPath = join(workDir, 'prompt.md')
+      await writeFile(promptPath, prompt, 'utf-8')
 
       const child = spawn(
         resolved.command,
@@ -98,69 +88,68 @@ export function createProcessExecutor(
           env: { ...process.env, ...resolved.env },
           stdio: ['ignore', 'pipe', 'pipe'],
           timeout: options.timeout ? options.timeout * 1000 : undefined,
-        },
-      );
+        }
+      )
 
-      active.set(options.id, child);
+      active.set(options.id, child)
 
-      const outputChunks: Buffer[] = [];
-      const errorChunks: Buffer[] = [];
+      const outputChunks: Buffer[] = []
+      const errorChunks: Buffer[] = []
 
-      child.stdout?.on('data', (chunk: Buffer) => outputChunks.push(chunk));
-      child.stderr?.on('data', (chunk: Buffer) => errorChunks.push(chunk));
+      child.stdout?.on('data', (chunk: Buffer) => outputChunks.push(chunk))
+      child.stderr?.on('data', (chunk: Buffer) => errorChunks.push(chunk))
 
       try {
         const exitCode = await new Promise<number | null>((resolve, reject) => {
-          child.on('close', resolve);
-          child.on('error', reject);
-        });
+          child.on('close', resolve)
+          child.on('error', reject)
+        })
 
-        active.delete(options.id);
+        active.delete(options.id)
 
-        const stdout = Buffer.concat(outputChunks).toString('utf-8').trim();
-        const stderr = Buffer.concat(errorChunks).toString('utf-8').trim();
+        const stdout = Buffer.concat(outputChunks).toString('utf-8').trim()
+        const stderr = Buffer.concat(errorChunks).toString('utf-8').trim()
 
-        const errors: string[] = [];
+        const errors: string[] = []
         if (exitCode !== 0) {
-          errors.push(`Subprocess exited with code ${exitCode}`);
+          errors.push(`Subprocess exited with code ${exitCode}`)
         }
         if (stderr) {
-          errors.push(stderr);
+          errors.push(stderr)
         }
 
-        // Best-effort cleanup
-        await rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+        await rm(workDir, { recursive: true, force: true }).catch(() => undefined)
 
-        // Rough token estimate: ~4 chars per token
-        const tokensUsed = Math.ceil((prompt.length + stdout.length) / 4);
+        const tokensUsed = Math.ceil((prompt.length + stdout.length) / 4)
 
-        return { output: stdout, tokensUsed, errors };
+        return { output: stdout, tokensUsed, errors }
       } catch (err) {
-        active.delete(options.id);
-        await rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+        active.delete(options.id)
+        await rm(workDir, { recursive: true, force: true }).catch(() => undefined)
         return {
           output: '',
           tokensUsed: Math.ceil(prompt.length / 4),
           errors: [String(err)],
-        };
+        }
       }
     },
 
     async abort(id: string): Promise<void> {
-      const child = active.get(id);
+      const child = active.get(id)
       if (child) {
-        child.kill('SIGTERM');
-        active.delete(id);
+        child.kill('SIGTERM')
+        active.delete(id)
       }
     },
-  };
+  }
 }
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-const DEFAULT_TIMEOUT_SECONDS = 300;
+const DEFAULT_TIMEOUT_SECONDS = 300
+const DEFAULT_TOKEN_BUDGET = 32000
 
 // ---------------------------------------------------------------------------
 // Role-specific system instructions
@@ -183,7 +172,7 @@ const ROLE_INSTRUCTIONS: Record<SubagentRole, string> = {
     'You are a GENERAL subagent. Complete the assigned task within your permissions.',
   researcher:
     'You are a RESEARCHER subagent. Your job is to research topics and provide findings.',
-};
+}
 
 const PERMISSION_LABELS: Record<keyof PermissionSet, string> = {
   readFiles: 'Read Files',
@@ -191,21 +180,41 @@ const PERMISSION_LABELS: Record<keyof PermissionSet, string> = {
   runCommands: 'Run Commands',
   writeFiles: 'Write Files',
   gitOperations: 'Git Operations',
-};
+}
 
 // ---------------------------------------------------------------------------
 // Subagent Dispatcher
 // ---------------------------------------------------------------------------
 
+export interface SubagentDispatcherConfig {
+  logger: Logger
+  tokenBudget?: { limit: number; warningThreshold: number }
+  resilience?: {
+    circuitBreaker?: { failureThreshold?: number; successThreshold?: number; timeout?: number }
+    retryPolicy?: { maxRetries?: number; baseDelay?: number; maxDelay?: number }
+  }
+}
+
+export interface DispatchConfig {
+  config: SubagentConfig
+  contract: SubagentContract
+  fallback?: () => unknown
+}
+
 export class SubagentDispatcher {
-  private readonly executor: SubagentExecutor;
-  private readonly logger: Logger;
-  private readonly activeIds: Set<string>;
-
-  constructor(executor: SubagentExecutor, logger: Logger) {
-    this.executor = executor;
-    this.logger = logger;
-    this.activeIds = new Set();
+  private readonly logger: Logger
+  private readonly tokenBudget: TokenBudget
+  private readonly resilientDispatcher: ResilientDispatcher
+  private readonly activeIds: Set<string>
+
+  constructor(config: SubagentDispatcherConfig) {
+    this.logger = config.logger
+    this.tokenBudget = new TokenBudget(config.tokenBudget)
+    this.resilientDispatcher = new ResilientDispatcher({
+      circuitBreaker: config.resilience?.circuitBreaker,
+      retryPolicy: config.resilience?.retryPolicy,
+    })
+    this.activeIds = new Set()
   }
 
   // -----------------------------------------------------------------------
@@ -213,70 +222,72 @@ export class SubagentDispatcher {
   // -----------------------------------------------------------------------
 
   /**
-   * Dispatch a single subagent with the given config and contract.
+   * Dispatch a single subagent with fresh context.
    *
-   * Constructs a structured prompt from the contract, sends it to the
-   * executor, validates the output against the optional output schema,
-   * and returns a typed SubagentResult.
+   * Steps:
+   * 1. Check token budget
+   * 2. Build fresh prompt (no history pollution)
+   * 3. Spawn subagent via resilient dispatcher
+   * 4. Parse and validate output
+   * 5. Return structured result
    */
-  async dispatch(
-    config: SubagentConfig,
-    contract: SubagentContract,
-  ): Promise<SubagentResult> {
-    const id = nanoid();
-    const startTime = Date.now();
-    const timeoutSeconds = config.timeout ?? DEFAULT_TIMEOUT_SECONDS;
-
-    this.activeIds.add(id);
-    this.logger.info(`[Dispatcher] Dispatching ${id} (role=${config.role})`);
+  async dispatch(config: SubagentConfig, contract: SubagentContract): Promise<SubagentResult> {
+    const id = nanoid()
+    const startTime = Date.now()
+    const timeoutSeconds = config.timeout ?? DEFAULT_TIMEOUT_SECONDS
+
+    this.activeIds.add(id)
+    this.logger.info(`[Dispatcher] Dispatching ${id} (role=${config.role})`)
+
+    // Check token budget
+    const prompt = this.buildFreshPrompt(config, contract)
+    const estimatedTokens = TokenBudget.estimateTokens(prompt)
+
+    if (!this.tokenBudget.canAfford(estimatedTokens)) {
+      this.activeIds.delete(id)
+      throw new BudgetExceededError(
+        `Cannot afford ${estimatedTokens} tokens. Remaining: ${this.tokenBudget.getRemaining()}`
+      )
+    }
 
     try {
-      const prompt = this.buildPrompt(config, contract);
-
-      const executorResult = await this.withTimeout(
-        this.executor.execute(prompt, {
-          id,
-          model: config.model,
-          timeout: timeoutSeconds,
-        }),
-        timeoutSeconds * 1000,
-        id,
-      );
-
-      const duration = Date.now() - startTime;
-
-      const validationErrors = this.validateOutput(
-        executorResult.output,
-        contract.outputSchema,
-      );
-
-      const allErrors = [...executorResult.errors, ...validationErrors];
-      const status: SubagentResult['status'] =
-        allErrors.length > 0 ? 'failure' : 'success';
+      // Execute via resilient dispatcher (handles circuit breaker + retry)
+      const result = await this.resilientDispatcher.dispatch<SubagentResult>(
+        async () => {
+          return await this.executeSubagent(id, config, contract, prompt, timeoutSeconds)
+        },
+        {
+          fallback: () => ({
+            id,
+            role: config.role,
+            status: 'failure',
+            output: '',
+            artifacts: [],
+            tokensUsed: 0,
+            duration: Date.now() - startTime,
+            errors: ['Fallback executed due to circuit breaker or retry exhaustion'],
+          }),
+        }
+      )
 
-      const artifacts = extractArtifacts(executorResult.output);
+      // Record actual token usage
+      this.tokenBudget.recordUsage(result.tokensUsed || estimatedTokens)
 
+      const duration = Date.now() - startTime
       this.logger.info(
-        `[Dispatcher] Subagent ${id} completed: status=${status} duration=${duration}ms tokens=${executorResult.tokensUsed}`,
-      );
+        `[Dispatcher] Subagent ${id} completed: status=${result.status} duration=${duration}ms tokens=${result.tokensUsed || estimatedTokens}`
+      )
 
       return {
-        id,
-        role: config.role,
-        status,
-        output: executorResult.output,
-        artifacts,
-        tokensUsed: executorResult.tokensUsed,
+        ...result,
         duration,
-        errors: allErrors,
-      };
+      }
     } catch (error) {
-      const duration = Date.now() - startTime;
-      const errorMessage =
-        error instanceof Error ? error.message : String(error);
-      const isTimeout = errorMessage.includes('timed out');
+      const duration = Date.now() - startTime
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      const isTimeout = errorMessage.includes('timed out') || errorMessage.includes('Timeout')
 
-      this.logger.error(`[Dispatcher] Subagent ${id} failed: ${errorMessage}`);
+      this.logger.error(`[Dispatcher] Subagent ${id} failed: ${errorMessage}`)
 
       return {
         id,
@@ -284,227 +295,221 @@ export class SubagentDispatcher {
         status: isTimeout ? 'timeout' : 'failure',
         output: '',
         artifacts: [],
-        tokensUsed: 0,
+        tokensUsed: estimatedTokens,
         duration,
         errors: [errorMessage],
-      };
+      }
     } finally {
-      this.activeIds.delete(id);
+      this.activeIds.delete(id)
     }
   }
 
   /**
    * Dispatch multiple subagents in parallel.
    *
-   * All subagents run concurrently. Use when tasks are independent
-   * of each other (e.g. exploring multiple directories at once).
+   * Each subagent receives ONLY its own contract - no shared context pollution.
+   * Results are returned in the same order as configs.
    */
-  async dispatchParallel(
-    configs: readonly SubagentConfig[],
-    contracts: readonly SubagentContract[],
-  ): Promise<SubagentResult[]> {
-    if (configs.length !== contracts.length) {
-      throw new Error(
-        `configs.length (${configs.length}) must equal contracts.length (${contracts.length})`,
-      );
+  async dispatchParallel(configs: DispatchConfig[]): Promise<SubagentResult[]> {
+    this.logger.info(`[Dispatcher] Dispatching ${configs.length} subagents in parallel`)
+
+    // Check total budget before dispatching
+    const totalEstimatedTokens = configs.reduce((sum, { contract }) => {
+      const prompt = this.buildFreshPrompt({ role: 'general' }, contract)
+      return sum + TokenBudget.estimateTokens(prompt)
+    }, 0)
+
+    if (!this.tokenBudget.canAfford(totalEstimatedTokens)) {
+      throw new BudgetExceededError(
+        `Parallel dispatch requires ${totalEstimatedTokens} tokens. Remaining: ${this.tokenBudget.getRemaining()}`
+      )
     }
 
-    this.logger.info(
-      `[Dispatcher] Dispatching ${configs.length} subagents in parallel`,
-    );
+    // Dispatch all in parallel
+    const promises = configs.map(({ config, contract }) =>
+      this.dispatch(config, contract).catch((error) => {
+        const errorMessage = error instanceof Error ? error.message : String(error)
+        return {
+          id: nanoid(),
+          role: config.role,
+          status: 'failure' as const,
+          output: '',
+          artifacts: [],
+          tokensUsed: 0,
+          duration: 0,
+          errors: [errorMessage],
+        }
+      })
+    )
 
-    const pairs = configs.map((config, i) => ({ config, contract: contracts[i] }));
-    const results = await Promise.all(
-      pairs.map(({ config, contract }) => this.dispatch(config, contract)),
-    );
+    const results = await Promise.all(promises)
 
     const counts = {
       success: results.filter((r) => r.status === 'success').length,
       failure: results.filter((r) => r.status === 'failure').length,
       timeout: results.filter((r) => r.status === 'timeout').length,
-    };
+    }
 
     this.logger.info(
-      `[Dispatcher] Parallel batch complete: ${counts.success} success, ${counts.failure} failure, ${counts.timeout} timeout`,
-    );
+      `[Dispatcher] Parallel batch complete: ${counts.success} success, ${counts.failure} failure, ${counts.timeout} timeout`
+    )
 
-    return results;
+    return results
   }
 
   /**
-   * Dispatch multiple subagents sequentially.
-   *
-   * Each subagent receives the output of all previous subagents as
-   * additional context. The pipeline stops early if a subagent fails
-   * or times out. Use when tasks form a pipeline (e.g. explore ->
-   * implement -> review -> verify).
+   * Get current health status including token usage and circuit state
    */
-  async dispatchSequential(
-    configs: readonly SubagentConfig[],
-    contracts: readonly SubagentContract[],
-  ): Promise<SubagentResult[]> {
-    if (configs.length !== contracts.length) {
-      throw new Error(
-        `configs.length (${configs.length}) must equal contracts.length (${contracts.length})`,
-      );
+  getHealth(): {
+    tokenUsage: { used: number; limit: number; percentage: number; remaining: number }
+    circuitState: string
+    activeSubagents: number
+  } {
+    const resilientHealth = this.resilientDispatcher.getHealth()
+    const tokenUsage = this.tokenBudget.getUsage()
+
+    return {
+      tokenUsage: {
+        ...tokenUsage,
+        remaining: this.tokenBudget.getRemaining(),
+      },
+      circuitState: resilientHealth.circuitState,
+      activeSubagents: this.activeIds.size,
     }
-
-    this.logger.info(
-      `[Dispatcher] Dispatching ${configs.length} subagents sequentially`,
-    );
-
-    const results: SubagentResult[] = [];
-
-    for (let i = 0; i < configs.length; i++) {
-      const augmentedContract = augmentWithPreviousResults(
-        contracts[i],
-        results,
-      );
-      const result = await this.dispatch(configs[i], augmentedContract);
-      results.push(result);
-
-      if (result.status === 'failure' || result.status === 'timeout') {
-        this.logger.warn(
-          `[Dispatcher] Stopping sequential pipeline at index ${i} (${result.status})`,
-        );
-        break;
-      }
-    }
-
-    return results;
   }
 
   /**
-   * Abort a running subagent by its ID.
+   * Reset token budget (for testing or new milestone)
    */
-  async abort(id: string): Promise<void> {
-    if (!this.activeIds.has(id)) {
-      this.logger.warn(`[Dispatcher] Cannot abort ${id}: not active`);
-      return;
-    }
-    await this.executor.abort(id);
-    this.activeIds.delete(id);
-    this.logger.info(`[Dispatcher] Aborted subagent ${id}`);
+  resetBudget(): void {
+    this.tokenBudget.reset()
+    this.logger.info('[Dispatcher] Token budget reset')
   }
 
   // -----------------------------------------------------------------------
-  // Prompt construction
+  // Prompt construction - FRESH CONTEXT ONLY
   // -----------------------------------------------------------------------
 
   /**
-   * Build a structured subagent prompt from config and contract.
+   * Build a fresh prompt with ONLY necessary context.
    *
-   * The prompt follows the Claude Code agent tool pattern: explicit
-   * permissions, owned/read file scopes, isolation instructions,
-   * token budget, output format requirements, and the task itself.
+   * Excludes:
+   * - Main agent conversation history
+     * - Previous subagent outputs (unless explicitly passed)
+   * - Internal reasoning
+   *
+   * Includes:
+   * - Role instruction
+   * - Permissions
+   * - File scope
+   * - Token budget
+   * - Output schema
+   * - Task description
    */
-  private buildPrompt(
-    config: SubagentConfig,
-    contract: SubagentContract,
-  ): string {
-    const sections: string[] = [];
+  private buildFreshPrompt(config: SubagentConfig, contract: SubagentContract): string {
+    const sections: string[] = []
 
-    sections.push(buildRoleHeader(config.role));
-    sections.push(buildPermissionsBlock(contract.permissions));
-    sections.push(buildFileScopeBlock(contract.owns, contract.reads));
+    sections.push(buildRoleHeader(config.role))
+    sections.push(buildPermissionsBlock(contract.permissions))
+    sections.push(buildFileScopeBlock(contract.owns, contract.reads))
 
     if (config.isolation === 'worktree') {
-      sections.push(buildIsolationBlock());
+      sections.push(buildIsolationBlock())
     }
 
-    sections.push(buildBudgetBlock(config.tokenBudget));
-    sections.push(buildOutputSchemaBlock(contract.outputSchema));
-    sections.push(buildTaskBlock(contract.prompt));
+    sections.push(buildBudgetBlock(config.tokenBudget))
+    sections.push(buildOutputSchemaBlock(contract.outputSchema))
+    sections.push(buildTaskBlock(contract.prompt))
 
-    return sections.join('\n\n---\n\n');
+    return sections.join('\n\n---\n\n')
   }
 
   // -----------------------------------------------------------------------
-  // Timeout handling
+  // Subagent execution
   // -----------------------------------------------------------------------
 
   /**
-   * Wraps a promise with a timeout. If the timeout fires first the
-   * subagent is aborted and the promise rejects.
+   * Execute a subagent process.
+   * This is the actual implementation that the resilient dispatcher wraps.
    */
-  private withTimeout<T>(
-    promise: Promise<T>,
-    timeoutMs: number,
+  private async executeSubagent(
     id: string,
-  ): Promise<T> {
-    if (timeoutMs <= 0 || !Number.isFinite(timeoutMs)) {
-      return promise;
-    }
+    config: SubagentConfig,
+    contract: SubagentContract,
+    prompt: string,
+    timeoutSeconds: number
+  ): Promise<SubagentResult> {
+    const { spawn } = await import('child_process')
+    const { writeFile, mkdir, rm } = await import('fs/promises')
+    const { join } = await import('path')
+    const { tmpdir } = await import('os')
 
-    return new Promise<T>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.executor.abort(id).catch(() => undefined);
-        reject(new Error(`Subagent ${id} timed out after ${timeoutMs}ms`));
-      }, timeoutMs);
+    const workDir = join(tmpdir(), `yi-subagent-${id}`)
+    await mkdir(workDir, { recursive: true })
 
-      promise
-        .then((result) => {
-          clearTimeout(timer);
-          resolve(result);
-        })
-        .catch((error) => {
-          clearTimeout(timer);
-          reject(error);
-        });
-    });
-  }
+    const promptPath = join(workDir, 'prompt.md')
+    await writeFile(promptPath, prompt, 'utf-8')
 
-  // -----------------------------------------------------------------------
-  // Output validation
-  // -----------------------------------------------------------------------
+    return new Promise((resolve, reject) => {
+      const child = spawn(
+        'claude',
+        ['--print', '--output-format', 'json', '--input-file', promptPath],
+        {
+          env: { ...process.env, CLAUDE_SUBAGENT: '1' },
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: timeoutSeconds * 1000,
+        }
+      )
 
-  /**
-   * Validate subagent output against an optional schema.
-   * The schema is a Record<string, unknown> where values are type strings
-   * like "string", "number", "boolean", "object".
-   *
-   * Returns an array of validation error messages (empty = valid).
-   */
-  private validateOutput(
-    output: string,
-    schema?: Record<string, unknown>,
-  ): string[] {
-    if (!schema || Object.keys(schema).length === 0) {
-      return [];
-    }
+      const outputChunks: Buffer[] = []
+      const errorChunks: Buffer[] = []
 
-    // Try to extract a JSON block from the output
-    const jsonMatch = output.match(/```json\s*([\s\S]*?)\s*```/);
-    const jsonText = jsonMatch ? jsonMatch[1].trim() : output.trim();
+      child.stdout?.on('data', (chunk: Buffer) => outputChunks.push(chunk))
+      child.stderr?.on('data', (chunk: Buffer) => errorChunks.push(chunk))
 
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(jsonText);
-    } catch {
-      return ['Output is not valid JSON'];
-    }
+      child.on('close', async (exitCode) => {
+        // Cleanup
+        await rm(workDir, { recursive: true, force: true }).catch(() => undefined)
 
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-      return ['Output must be a JSON object'];
-    }
+        const stdout = Buffer.concat(outputChunks).toString('utf-8').trim()
+        const stderr = Buffer.concat(errorChunks).toString('utf-8').trim()
 
-    const obj = parsed as Record<string, unknown>;
-    const errors: string[] = [];
+        const errors: string[] = []
+        if (exitCode !== 0) {
+          errors.push(`Subprocess exited with code ${exitCode}`)
+        }
+        if (stderr) {
+          errors.push(stderr)
+        }
 
-    for (const [key, expectedType] of Object.entries(schema)) {
-      if (!(key in obj)) {
-        errors.push(`Missing required field: "${key}"`);
-        continue;
-      }
-      const actualType = typeof obj[key];
-      if (actualType !== expectedType) {
-        errors.push(
-          `Field "${key}": expected type ${String(expectedType)}, got ${actualType}`,
-        );
-      }
-    }
+        // Parse output and validate
+        const tokensUsed = Math.ceil((prompt.length + stdout.length) / 4)
+        const artifacts = extractArtifacts(stdout)
+        const status: SubagentResult['status'] = errors.length > 0 ? 'failure' : 'success'
 
-    return errors;
+        // Validate against schema if provided
+        const validationErrors = validateOutput(stdout, contract.outputSchema)
+        if (validationErrors.length > 0) {
+          errors.push(...validationErrors)
+        }
+
+        resolve({
+          id,
+          role: config.role,
+          status: validationErrors.length > 0 ? 'failure' : status,
+          output: stdout,
+          artifacts,
+          tokensUsed,
+          duration: 0, // Will be set by caller
+          errors: [...errors, ...validationErrors],
+        })
+      })
+
+      child.on('error', async (error) => {
+        await rm(workDir, { recursive: true, force: true }).catch(() => undefined)
+        reject(error)
+      })
+    })
   }
 }
 
@@ -513,45 +518,42 @@ export class SubagentDispatcher {
 // ---------------------------------------------------------------------------
 
 function buildRoleHeader(role: SubagentRole): string {
-  const instruction = ROLE_INSTRUCTIONS[role] ?? ROLE_INSTRUCTIONS.general;
-  return `# Role: ${role}\n\n${instruction}`;
+  const instruction = ROLE_INSTRUCTIONS[role] ?? ROLE_INSTRUCTIONS.general
+  return `# Role: ${role}\n\n${instruction}`
 }
 
 function buildPermissionsBlock(permissions: PermissionSet): string {
-  const lines: string[] = ['## Permissions'];
+  const lines: string[] = ['## Permissions']
   for (const key of Object.keys(permissions) as (keyof PermissionSet)[]) {
-    const label = PERMISSION_LABELS[key];
-    const allowed = permissions[key] ? 'ALLOWED' : 'DENIED';
-    lines.push(`- ${label}: ${allowed}`);
+    const label = PERMISSION_LABELS[key]
+    const allowed = permissions[key] ? 'ALLOWED' : 'DENIED'
+    lines.push(`- ${label}: ${allowed}`)
   }
-  return lines.join('\n');
+  return lines.join('\n')
 }
 
-function buildFileScopeBlock(
-  owns: readonly string[],
-  reads: readonly string[],
-): string {
-  const lines: string[] = ['## File Scope'];
+function buildFileScopeBlock(owns: readonly string[], reads: readonly string[]): string {
+  const lines: string[] = ['## File Scope']
 
-  lines.push('\n### Owned Files (may modify)');
+  lines.push('\n### Owned Files (may modify)')
   if (owns.length === 0) {
-    lines.push('- None');
+    lines.push('- None')
   } else {
     for (const file of owns) {
-      lines.push(`- ${file}`);
+      lines.push(`- ${file}`)
     }
   }
 
-  lines.push('\n### Read-only Files');
+  lines.push('\n### Read-only Files')
   if (reads.length === 0) {
-    lines.push('- None');
+    lines.push('- None')
   } else {
     for (const file of reads) {
-      lines.push(`- ${file}`);
+      lines.push(`- ${file}`)
     }
   }
 
-  return lines.join('\n');
+  return lines.join('\n')
 }
 
 function buildIsolationBlock(): string {
@@ -564,33 +566,33 @@ function buildIsolationBlock(): string {
     '- Run tests within the worktree',
     '- Commit your changes before exiting',
     '- Never modify files outside the worktree',
-  ].join('\n');
+  ].join('\n')
 }
 
 function buildBudgetBlock(tokenBudget?: number): string {
-  const budget = tokenBudget ?? 32000;
+  const budget = tokenBudget ?? DEFAULT_TOKEN_BUDGET
   return [
     '## Token Budget',
     '',
     `You have a budget of **${budget.toLocaleString()} tokens**.`,
     'Stay within this limit. Be concise. Prefer essential information.',
-  ].join('\n');
+  ].join('\n')
 }
 
 function buildOutputSchemaBlock(schema?: Record<string, unknown>): string {
   if (!schema || Object.keys(schema).length === 0) {
-    return '## Output Format\n\nProvide your response as plain text or markdown.';
+    return '## Output Format\n\nProvide your response as plain text or markdown.'
   }
 
-  const keys = Object.keys(schema);
+  const keys = Object.keys(schema)
   const lines: string[] = [
     '## Required Output Format',
     '',
     'Your response MUST be a JSON object with these fields:',
-  ];
+  ]
 
   for (const key of keys) {
-    lines.push(`- \`${key}\`: ${String(schema[key])}`);
+    lines.push(`- \`${key}\`: ${String(schema[key])}`)
   }
 
   lines.push(
@@ -599,60 +601,84 @@ function buildOutputSchemaBlock(schema?: Record<string, unknown>): string {
     '',
     '```json',
     `{ ${keys.map((k) => `"${k}": ...`).join(', ')} }`,
-    '```',
-  );
+    '```'
+  )
 
-  return lines.join('\n');
+  return lines.join('\n')
 }
 
 function buildTaskBlock(prompt: string): string {
-  return `## Task\n\n${prompt}`;
+  return `## Task\n\n${prompt}`
 }
 
+// ---------------------------------------------------------------------------
+// Output validation
+// ---------------------------------------------------------------------------
+
 /**
- * Augment a contract with output from previous subagents.
- * Used by dispatchSequential to provide pipeline context.
+ * Validate subagent output against an optional schema.
+ * Returns an array of validation error messages (empty = valid).
  */
-function augmentWithPreviousResults(
-  contract: SubagentContract,
-  previousResults: readonly SubagentResult[],
-): SubagentContract {
-  if (previousResults.length === 0) {
-    return contract;
+function validateOutput(output: string, schema?: Record<string, unknown>): string[] {
+  if (!schema || Object.keys(schema).length === 0) {
+    return []
   }
 
-  const context = previousResults
-    .map(
-      (r) =>
-        `### Previous Subagent (role=${r.role}, status=${r.status})\n\n${r.output || '(no output)'}`,
-    )
-    .join('\n\n');
+  // Try to extract a JSON block from the output
+  const jsonMatch = output.match(/```json\s*([\s\S]*?)\s*```/)
+  const jsonText = jsonMatch ? jsonMatch[1].trim() : output.trim()
 
-  return {
-    ...contract,
-    prompt: `${contract.prompt}\n\n## Context from Previous Steps\n\n${context}`,
-  };
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(jsonText)
+  } catch {
+    return ['Output is not valid JSON']
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return ['Output must be a JSON object']
+  }
+
+  const obj = parsed as Record<string, unknown>
+  const errors: string[] = []
+
+  for (const [key, expectedType] of Object.entries(schema)) {
+    if (!(key in obj)) {
+      errors.push(`Missing required field: "${key}"`)
+      continue
+    }
+    const actualType = typeof obj[key]
+    if (actualType !== expectedType) {
+      errors.push(`Field "${key}": expected type ${String(expectedType)}, got ${actualType}`)
+    }
+  }
+
+  return errors
 }
 
+// ---------------------------------------------------------------------------
+// Artifact extraction
+// ---------------------------------------------------------------------------
+
 /**
  * Extract structured artifacts from subagent output text.
  * Recognises fenced code blocks (JSON, diff) and converts them
  * to SubagentArtifact records.
  */
 function extractArtifacts(output: string): SubagentArtifact[] {
-  const artifacts: SubagentArtifact[] = [];
+  const artifacts: SubagentArtifact[] = []
 
-  const jsonBlocks = output.matchAll(/```json\s*([\s\S]*?)\s*```/g);
+  const jsonBlocks = output.matchAll(/```json\s*([\s\S]*?)\s*```/g)
   for (const match of jsonBlocks) {
-    artifacts.push({ type: 'report', content: match[1].trim() });
+    artifacts.push({ type: 'report', content: match[1].trim() })
   }
 
-  const diffBlocks = output.matchAll(/```diff\s*([\s\S]*?)\s*```/g);
+  const diffBlocks = output.matchAll(/```diff\s*([\s\S]*?)\s*```/g)
   for (const match of diffBlocks) {
-    artifacts.push({ type: 'diff', content: match[1].trim() });
+    artifacts.push({ type: 'diff', content: match[1].trim() })
   }
 
-  return artifacts;
+  return artifacts
 }
 
 // ---------------------------------------------------------------------------
@@ -660,21 +686,20 @@ function extractArtifacts(output: string): SubagentArtifact[] {
 // ---------------------------------------------------------------------------
 
 export interface DispatcherOptions {
-  executor?: SubagentExecutor;
-  processConfig?: Partial<ProcessExecutorConfig>;
+  logger: Logger
+  tokenBudget?: { limit: number; warningThreshold: number }
+  resilience?: {
+    circuitBreaker?: { failureThreshold?: number; successThreshold?: number; timeout?: number }
+    retryPolicy?: { maxRetries?: number; baseDelay?: number; maxDelay?: number }
+  }
 }
 
 /**
  * Create a SubagentDispatcher with sensible defaults.
- *
- * If no executor is provided, a process-based executor is created
- * using `createProcessExecutor` which spawns a CLI command.
  */
-export function createDispatcher(
-  logger: Logger,
-  options: DispatcherOptions = {},
-): SubagentDispatcher {
-  const executor =
-    options.executor ?? createProcessExecutor(options.processConfig);
-  return new SubagentDispatcher(executor, logger);
+export function createDispatcher(options: DispatcherOptions): SubagentDispatcher {
+  return new SubagentDispatcher(options)
 }
+
+// Re-export for convenience
+export { TokenBudget, BudgetExceededError, ResilientDispatcher }