@haoyiyin/workflow 0.2.0 → 0.2.3

package/src/agents/dispatcher.ts

@@ -0,0 +1,680 @@
+/**
+ * Subagent Dispatcher - Spawns isolated subagents to do all real work
+ *
+ * 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.
+ */
+
+import { nanoid } from 'nanoid';
+import type {
+  SubagentConfig,
+  SubagentContract,
+  SubagentResult,
+  SubagentArtifact,
+  PermissionSet,
+  SubagentRole,
+} from './types.js';
+import type { Logger } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Executor abstraction
+// ---------------------------------------------------------------------------
+
+export interface ExecutorOptions {
+  id: string;
+  model?: string;
+  timeout?: number;
+  workDir?: string;
+}
+
+export interface ExecutorResult {
+  output: string;
+  tokensUsed: number;
+  errors: string[];
+}
+
+export interface SubagentExecutor {
+  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>;
+}
+
+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> = {},
+): SubagentExecutor {
+  const resolved: ProcessExecutorConfig = {
+    ...DEFAULT_PROCESS_CONFIG,
+    ...config,
+  };
+
+  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 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 child = spawn(
+        resolved.command,
+        [...resolved.args, '--input-file', promptPath],
+        {
+          env: { ...process.env, ...resolved.env },
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: options.timeout ? options.timeout * 1000 : undefined,
+        },
+      );
+
+      active.set(options.id, child);
+
+      const outputChunks: Buffer[] = [];
+      const errorChunks: Buffer[] = [];
+
+      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);
+        });
+
+        active.delete(options.id);
+
+        const stdout = Buffer.concat(outputChunks).toString('utf-8').trim();
+        const stderr = Buffer.concat(errorChunks).toString('utf-8').trim();
+
+        const errors: string[] = [];
+        if (exitCode !== 0) {
+          errors.push(`Subprocess exited with code ${exitCode}`);
+        }
+        if (stderr) {
+          errors.push(stderr);
+        }
+
+        // Best-effort cleanup
+        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);
+
+        return { output: stdout, tokensUsed, errors };
+      } catch (err) {
+        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);
+      if (child) {
+        child.kill('SIGTERM');
+        active.delete(id);
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TIMEOUT_SECONDS = 300;
+
+// ---------------------------------------------------------------------------
+// Role-specific system instructions
+// ---------------------------------------------------------------------------
+
+const ROLE_INSTRUCTIONS: Record<SubagentRole, string> = {
+  explorer:
+    'You are an EXPLORER subagent. Your job is to search and read the codebase. You CANNOT write or modify any files.',
+  implementer:
+    'You are an IMPLEMENTER subagent. Your job is to write code, run tests, and verify your changes compile and pass.',
+  reviewer:
+    'You are a REVIEWER subagent. Your job is to read code changes and produce a structured review report. You CANNOT write files.',
+  planner:
+    'You are a PLANNER subagent. Your job is to analyse requirements and create implementation plans.',
+  debugger:
+    'You are a DEBUGGER subagent. Your job is to analyse failures, identify root causes, and propose fixes.',
+  verifier:
+    'You are a VERIFIER subagent. Your job is to verify that implemented changes satisfy the original requirements. You CANNOT write files.',
+  general:
+    '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',
+  searchCode: 'Search Code',
+  runCommands: 'Run Commands',
+  writeFiles: 'Write Files',
+  gitOperations: 'Git Operations',
+};
+
+// ---------------------------------------------------------------------------
+// Subagent Dispatcher
+// ---------------------------------------------------------------------------
+
+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();
+  }
+
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+
+  /**
+   * Dispatch a single subagent with the given config and contract.
+   *
+   * 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.
+   */
+  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})`);
+
+    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';
+
+      const artifacts = extractArtifacts(executorResult.output);
+
+      this.logger.info(
+        `[Dispatcher] Subagent ${id} completed: status=${status} duration=${duration}ms tokens=${executorResult.tokensUsed}`,
+      );
+
+      return {
+        id,
+        role: config.role,
+        status,
+        output: executorResult.output,
+        artifacts,
+        tokensUsed: executorResult.tokensUsed,
+        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');
+
+      this.logger.error(`[Dispatcher] Subagent ${id} failed: ${errorMessage}`);
+
+      return {
+        id,
+        role: config.role,
+        status: isTimeout ? 'timeout' : 'failure',
+        output: '',
+        artifacts: [],
+        tokensUsed: 0,
+        duration,
+        errors: [errorMessage],
+      };
+    } finally {
+      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).
+   */
+  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})`,
+      );
+    }
+
+    this.logger.info(
+      `[Dispatcher] Dispatching ${configs.length} subagents in parallel`,
+    );
+
+    const pairs = configs.map((config, i) => ({ config, contract: contracts[i] }));
+    const results = await Promise.all(
+      pairs.map(({ config, contract }) => this.dispatch(config, contract)),
+    );
+
+    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`,
+    );
+
+    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).
+   */
+  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})`,
+      );
+    }
+
+    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.
+   */
+  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}`);
+  }
+
+  // -----------------------------------------------------------------------
+  // Prompt construction
+  // -----------------------------------------------------------------------
+
+  /**
+   * Build a structured subagent prompt from config and contract.
+   *
+   * 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.
+   */
+  private buildPrompt(
+    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));
+
+    if (config.isolation === 'worktree') {
+      sections.push(buildIsolationBlock());
+    }
+
+    sections.push(buildBudgetBlock(config.tokenBudget));
+    sections.push(buildOutputSchemaBlock(contract.outputSchema));
+    sections.push(buildTaskBlock(contract.prompt));
+
+    return sections.join('\n\n---\n\n');
+  }
+
+  // -----------------------------------------------------------------------
+  // Timeout handling
+  // -----------------------------------------------------------------------
+
+  /**
+   * Wraps a promise with a timeout. If the timeout fires first the
+   * subagent is aborted and the promise rejects.
+   */
+  private withTimeout<T>(
+    promise: Promise<T>,
+    timeoutMs: number,
+    id: string,
+  ): Promise<T> {
+    if (timeoutMs <= 0 || !Number.isFinite(timeoutMs)) {
+      return promise;
+    }
+
+    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);
+
+      promise
+        .then((result) => {
+          clearTimeout(timer);
+          resolve(result);
+        })
+        .catch((error) => {
+          clearTimeout(timer);
+          reject(error);
+        });
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  // Output validation
+  // -----------------------------------------------------------------------
+
+  /**
+   * 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 [];
+    }
+
+    // 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();
+
+    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;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Prompt builder helpers (pure functions)
+// ---------------------------------------------------------------------------
+
+function buildRoleHeader(role: SubagentRole): string {
+  const instruction = ROLE_INSTRUCTIONS[role] ?? ROLE_INSTRUCTIONS.general;
+  return `# Role: ${role}\n\n${instruction}`;
+}
+
+function buildPermissionsBlock(permissions: PermissionSet): string {
+  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}`);
+  }
+  return lines.join('\n');
+}
+
+function buildFileScopeBlock(
+  owns: readonly string[],
+  reads: readonly string[],
+): string {
+  const lines: string[] = ['## File Scope'];
+
+  lines.push('\n### Owned Files (may modify)');
+  if (owns.length === 0) {
+    lines.push('- None');
+  } else {
+    for (const file of owns) {
+      lines.push(`- ${file}`);
+    }
+  }
+
+  lines.push('\n### Read-only Files');
+  if (reads.length === 0) {
+    lines.push('- None');
+  } else {
+    for (const file of reads) {
+      lines.push(`- ${file}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function buildIsolationBlock(): string {
+  return [
+    '## Isolation: Worktree',
+    '',
+    'You are running in an isolated git worktree. All changes you make are',
+    'contained within this worktree. You MUST:',
+    '- Create and modify files only within the worktree',
+    '- Run tests within the worktree',
+    '- Commit your changes before exiting',
+    '- Never modify files outside the worktree',
+  ].join('\n');
+}
+
+function buildBudgetBlock(tokenBudget?: number): string {
+  const budget = tokenBudget ?? 32000;
+  return [
+    '## Token Budget',
+    '',
+    `You have a budget of **${budget.toLocaleString()} tokens**.`,
+    'Stay within this limit. Be concise. Prefer essential information.',
+  ].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.';
+  }
+
+  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(
+    '',
+    'Wrap your output in a fenced JSON block:',
+    '',
+    '```json',
+    `{ ${keys.map((k) => `"${k}": ...`).join(', ')} }`,
+    '```',
+  );
+
+  return lines.join('\n');
+}
+
+function buildTaskBlock(prompt: string): string {
+  return `## Task\n\n${prompt}`;
+}
+
+/**
+ * Augment a contract with output from previous subagents.
+ * Used by dispatchSequential to provide pipeline context.
+ */
+function augmentWithPreviousResults(
+  contract: SubagentContract,
+  previousResults: readonly SubagentResult[],
+): SubagentContract {
+  if (previousResults.length === 0) {
+    return contract;
+  }
+
+  const context = previousResults
+    .map(
+      (r) =>
+        `### Previous Subagent (role=${r.role}, status=${r.status})\n\n${r.output || '(no output)'}`,
+    )
+    .join('\n\n');
+
+  return {
+    ...contract,
+    prompt: `${contract.prompt}\n\n## Context from Previous Steps\n\n${context}`,
+  };
+}
+
+/**
+ * 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 jsonBlocks = output.matchAll(/```json\s*([\s\S]*?)\s*```/g);
+  for (const match of jsonBlocks) {
+    artifacts.push({ type: 'report', content: match[1].trim() });
+  }
+
+  const diffBlocks = output.matchAll(/```diff\s*([\s\S]*?)\s*```/g);
+  for (const match of diffBlocks) {
+    artifacts.push({ type: 'diff', content: match[1].trim() });
+  }
+
+  return artifacts;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export interface DispatcherOptions {
+  executor?: SubagentExecutor;
+  processConfig?: Partial<ProcessExecutorConfig>;
+}
+
+/**
+ * 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);
+}