@studio-foundation/engine 0.3.0-beta.1 → 0.3.0-beta.6

package/src/pipeline/group-orchestrator.ts

@@ -1,483 +0,0 @@
-// GroupOrchestrator — extracted from PipelineEngine.runGroup/runGroupParallel/runGroupSequential()
-// Handles group-level orchestration: parallel and sequential iteration with feedback loops.
-
-import { randomUUID } from 'node:crypto';
-import type { StageGroup, StageRun, StageStatus } from '@studio-foundation/contracts';
-import {
-  addStageOutput,
-  addStageToolResults,
-  setGroupFeedback,
-  type PipelineContext,
-} from './context-propagation.js';
-import type { EngineEvents, PipelineEventEmitter } from '../events.js';
-import type { ToolRegistry, AnonymizationMiddleware } from '@studio-foundation/runner';
-import type { StageExecutor } from './stage-executor.js';
-import type { GroupResult, ProjectPaths, StageResult } from './types.js';
-
-export interface GroupOrchestratorConfig {
-  events?: EngineEvents;
-  emitter: PipelineEventEmitter;
-  stageExecutor: StageExecutor;
-}
-
-export class GroupOrchestrator {
-  constructor(private config: GroupOrchestratorConfig) {}
-
-  async run(
-    group: StageGroup,
-    context: PipelineContext,
-    stageOffset: number,
-    totalStages: number,
-    userInput: string | Record<string, unknown>,
-    paths: ProjectPaths,
-    toolRegistry: ToolRegistry | undefined,
-    runMiddleware?: AnonymizationMiddleware | null,
-    runId?: string,
-    signal?: AbortSignal,
-    skipSet?: Set<string>,
-    originalRunId?: string,
-  ): Promise<GroupResult> {
-    if (group.mode === 'parallel') {
-      return this.runParallel(group, context, stageOffset, totalStages, userInput, paths, toolRegistry, runMiddleware, runId, signal);
-    }
-    return this.runSequential(group, context, stageOffset, totalStages, userInput, paths, toolRegistry, runMiddleware, runId, signal, skipSet, originalRunId);
-  }
-
-  private async runParallel(
-    group: StageGroup,
-    context: PipelineContext,
-    stageOffset: number,
-    totalStages: number,
-    userInput: string | Record<string, unknown>,
-    paths: ProjectPaths,
-    toolRegistry: ToolRegistry | undefined,
-    runMiddleware?: AnonymizationMiddleware | null,
-    runId?: string,
-    signal?: AbortSignal,
-  ): Promise<GroupResult> {
-    let totalTokensDelta = 0;
-    let totalToolCallsDelta = 0;
-
-    this.config.events?.onGroupStart?.({
-      group_name: group.group,
-      max_iterations: group.max_iterations,
-      parallel: true,
-    });
-    this.config.emitter.emit({
-      type: 'group_start',
-      groupName: group.group,
-      maxIterations: group.max_iterations,
-    });
-
-    // Parallel groups run exactly one iteration
-    this.config.events?.onGroupIteration?.({
-      group_name: group.group,
-      iteration: 1,
-      max_iterations: group.max_iterations,
-    });
-    this.config.emitter.emit({
-      type: 'group_iteration',
-      groupName: group.group,
-      iteration: 1,
-      maxIterations: group.max_iterations,
-    });
-
-    if (signal?.aborted) {
-      this.config.events?.onGroupComplete?.({ group_name: group.group, iterations: 1, status: 'cancelled' });
-      this.config.emitter.emit({ type: 'group_complete', groupName: group.group, iterations: 1, status: 'cancelled' });
-      return { status: 'cancelled', stageRuns: [], stagesExecuted: group.stages.length, context, totalTokensDelta, totalToolCallsDelta };
-    }
-
-    // All parallel stages read the same pre-group context snapshot.
-    // previousStageName = the last stage before this group.
-    let previousStageName: string | undefined;
-    for (const [name] of context.stageOutputs) {
-      previousStageName = name;
-    }
-
-    // fail-fast: create a shared AbortController to cancel siblings on first failure
-    const groupAbort = (group.on_failure ?? 'fail-fast') === 'fail-fast'
-      ? new AbortController()
-      : null;
-    if (groupAbort && signal) {
-      signal.addEventListener('abort', () => groupAbort.abort(), { once: true });
-    }
-    const stageSignal = groupAbort?.signal ?? signal;
-
-    // Launch all stages concurrently
-    const settled = await Promise.allSettled(
-      group.stages.map(async (stage, i) => {
-        const result = await this.config.stageExecutor.execute(
-          stage,
-          context,
-          previousStageName,
-          userInput,
-          stageOffset + i,
-          totalStages,
-          paths,
-          toolRegistry,
-          runMiddleware,
-          runId,
-          stageSignal,
-        );
-        // fail-fast: abort remaining stages on first non-success
-        if (groupAbort && result.status !== 'success') {
-          groupAbort.abort();
-        }
-        return { stageName: stage.name, result };
-      }),
-    );
-
-    // Build result map keyed by stage name
-    const resultMap = new Map<string, StageResult>();
-    for (const s of settled) {
-      if (s.status === 'fulfilled') {
-        resultMap.set(s.value.stageName, s.value.result);
-      }
-    }
-
-    // Collect stage runs in definition order (deterministic output ordering)
-    const allStageRuns: StageRun[] = [];
-    for (const stage of group.stages) {
-      const result = resultMap.get(stage.name);
-      if (result) allStageRuns.push(result.stageRun);
-    }
-
-    // After building resultMap, accumulate token/tool call totals
-    for (const [, result] of resultMap) {
-      totalTokensDelta += result.tokensDelta ?? 0;
-      totalToolCallsDelta += result.toolCallsDelta ?? 0;
-    }
-
-    // Derive group status: cancelled > failed > success
-    // rejected treated as failed in parallel mode (no feedback loop)
-    let groupStatus: StageStatus = 'success';
-    for (const stage of group.stages) {
-      const result = resultMap.get(stage.name);
-      if (!result) { groupStatus = 'failed'; continue; }
-      if (result.status === 'cancelled' && groupStatus === 'success') groupStatus = 'cancelled';
-      if (result.status === 'failed' || result.status === 'rejected') groupStatus = 'failed';
-    }
-
-    // If every stage was skipped, the group is skipped (not success)
-    const allSkipped = group.stages.every(
-      (s) => resultMap.get(s.name)?.status === 'skipped',
-    );
-    if (allSkipped) groupStatus = 'skipped';
-
-    // Merge successful outputs into context in definition order (regardless of group status)
-    // This preserves observability for collect-all partial failures
-    for (const stage of group.stages) {
-      const result = resultMap.get(stage.name);
-      if (!result || result.status !== 'success') continue;
-      if (result.lastAgentOutput !== undefined) {
-        addStageOutput(context, stage.name, result.lastAgentOutput);
-      }
-      if (result.toolCalls?.length) {
-        addStageToolResults(context, stage.name, result.toolCalls);
-      }
-    }
-
-    this.config.events?.onGroupComplete?.({ group_name: group.group, iterations: 1, status: groupStatus });
-    this.config.emitter.emit({ type: 'group_complete', groupName: group.group, iterations: 1, status: groupStatus });
-
-    return {
-      status: groupStatus,
-      stageRuns: allStageRuns,
-      stagesExecuted: group.stages.length,
-      context,
-      totalTokensDelta,
-      totalToolCallsDelta,
-    };
-  }
-
-  private async runSequential(
-    group: StageGroup,
-    context: PipelineContext,
-    stageOffset: number,
-    totalStages: number,
-    userInput: string | Record<string, unknown>,
-    paths: ProjectPaths,
-    toolRegistry: ToolRegistry | undefined,
-    runMiddleware?: AnonymizationMiddleware | null,
-    runId?: string,
-    signal?: AbortSignal,
-    skipSet?: Set<string>,
-    originalRunId?: string,
-  ): Promise<GroupResult> {
-    const allStageRuns: StageRun[] = [];
-    let iteration = 0;
-    let totalTokensDelta = 0;
-    let totalToolCallsDelta = 0;
-
-    this.config.events?.onGroupStart?.({
-      group_name: group.group,
-      max_iterations: group.max_iterations,
-    });
-    this.config.emitter.emit({
-      type: 'group_start',
-      groupName: group.group,
-      maxIterations: group.max_iterations,
-    });
-
-    while (iteration < group.max_iterations) {
-      // Check cancellation before group iteration
-      if (signal?.aborted) {
-        this.config.events?.onGroupComplete?.({
-          group_name: group.group,
-          iterations: iteration,
-          status: 'cancelled',
-        });
-        this.config.emitter.emit({
-          type: 'group_complete',
-          groupName: group.group,
-          iterations: iteration,
-          status: 'cancelled',
-        });
-        return {
-          status: 'cancelled',
-          stageRuns: allStageRuns,
-          stagesExecuted: group.stages.length,
-          context,
-          totalTokensDelta,
-          totalToolCallsDelta,
-        };
-      }
-
-      iteration++;
-
-      this.config.events?.onGroupIteration?.({
-        group_name: group.group,
-        iteration,
-        max_iterations: group.max_iterations,
-      });
-      this.config.emitter.emit({
-        type: 'group_iteration',
-        groupName: group.group,
-        iteration,
-        maxIterations: group.max_iterations,
-      });
-
-      let groupSucceeded = true;
-      let anyStageExecuted = false;
-      let previousStageName: string | undefined;
-      // Find the last stage name before this group in the pipeline context
-      for (const [name] of context.stageOutputs) {
-        previousStageName = name;
-      }
-
-      for (let i = 0; i < group.stages.length; i++) {
-        if (signal?.aborted) break;
-
-        const stage = group.stages[i];
-        const stageNumber = stageOffset + i;
-
-        // On iteration 1 only, skip stages before resumeFromStage
-        if (iteration === 1 && skipSet?.has(stage.name)) {
-          const skippedReason = originalRunId
-            ? `resumed from run ${originalRunId}`
-            : 'resumed from prior run';
-          const skippedRun: StageRun = {
-            id: randomUUID(),
-            stage_name: stage.name,
-            status: 'skipped',
-            started_at: new Date().toISOString(),
-            completed_at: new Date().toISOString(),
-            tasks: [],
-            skipped_reason: skippedReason,
-          };
-          this.config.events?.onStageComplete?.({
-            stage_name: stage.name,
-            stage_index: stageNumber,
-            total_stages: totalStages,
-            status: 'skipped',
-            attempts: 0,
-            duration_ms: 0,
-            skipped_reason: skippedReason,
-          });
-          allStageRuns.push(skippedRun);
-          previousStageName = stage.name;
-          continue;
-        }
-
-        const result = await this.config.stageExecutor.execute(
-          stage,
-          context,
-          previousStageName,
-          userInput,
-          stageNumber,
-          totalStages,
-          paths,
-          toolRegistry,
-          runMiddleware,
-          runId,
-          signal,
-        );
-
-        allStageRuns.push(result.stageRun);
-        totalTokensDelta += result.tokensDelta ?? 0;
-        totalToolCallsDelta += result.toolCallsDelta ?? 0;
-        if (result.status !== 'skipped') anyStageExecuted = true;
-
-        // Cancelled → stop group
-        if (result.status === 'cancelled') {
-          this.config.events?.onGroupComplete?.({
-            group_name: group.group,
-            iterations: iteration,
-            status: 'cancelled',
-          });
-          this.config.emitter.emit({
-            type: 'group_complete',
-            groupName: group.group,
-            iterations: iteration,
-            status: 'cancelled',
-          });
-          return {
-            status: 'cancelled',
-            stageRuns: allStageRuns,
-            stagesExecuted: group.stages.length,
-            context,
-            totalTokensDelta,
-            totalToolCallsDelta,
-          };
-        }
-
-        // Technical failure → stop everything
-        if (result.status === 'failed') {
-          this.config.events?.onGroupComplete?.({
-            group_name: group.group,
-            iterations: iteration,
-            status: 'failed',
-          });
-          this.config.emitter.emit({
-            type: 'group_complete',
-            groupName: group.group,
-            iterations: iteration,
-            status: 'failed',
-          });
-          return {
-            status: 'failed',
-            stageRuns: allStageRuns,
-            stagesExecuted: group.stages.length,
-            context,
-            totalTokensDelta,
-            totalToolCallsDelta,
-          };
-        }
-
-        // Propagate output to context (will be cleared if we loop)
-        if (result.lastAgentOutput !== undefined) {
-          addStageOutput(context, stage.name, result.lastAgentOutput);
-        }
-        if (result.toolCalls && result.toolCalls.length > 0) {
-          addStageToolResults(context, stage.name, result.toolCalls);
-        }
-        previousStageName = stage.name;
-
-        // Last stage rejected → feedback loop
-        const isLastStage = i === group.stages.length - 1;
-        if (result.status === 'rejected' && isLastStage) {
-          groupSucceeded = false;
-
-          if (iteration < group.max_iterations) {
-            // Clear group stage outputs and tool results for next iteration
-            for (const gs of group.stages) {
-              context.stageOutputs.delete(gs.name);
-              context.stageToolResults.delete(gs.name);
-            }
-
-            // Set feedback for next iteration
-            setGroupFeedback(context, {
-              iteration,
-              max_iterations: group.max_iterations,
-              rejection_reason: result.postValidation?.rejection_reason || 'Rejected',
-              rejection_details: result.postValidation?.rejection_details,
-            });
-
-            this.config.events?.onGroupFeedback?.({
-              group_name: group.group,
-              iteration,
-              rejection_reason: result.postValidation?.rejection_reason || 'Rejected',
-              rejection_details: result.postValidation?.rejection_details || [],
-            });
-            this.config.emitter.emit({
-              type: 'group_feedback',
-              groupName: group.group,
-              iteration,
-              rejectionReason: result.postValidation?.rejection_reason || 'Rejected',
-            });
-          }
-
-          break; // Exit inner stage loop, retry group
-        }
-
-        // Non-gate stage rejected → stop
-        if (result.status === 'rejected') {
-          this.config.events?.onGroupComplete?.({
-            group_name: group.group,
-            iterations: iteration,
-            status: 'rejected',
-          });
-          this.config.emitter.emit({
-            type: 'group_complete',
-            groupName: group.group,
-            iterations: iteration,
-            status: 'rejected',
-          });
-          return {
-            status: 'rejected',
-            stageRuns: allStageRuns,
-            stagesExecuted: group.stages.length,
-            context,
-            totalTokensDelta,
-            totalToolCallsDelta,
-          };
-        }
-      }
-
-      if (groupSucceeded) {
-        const groupStatus = anyStageExecuted ? 'success' : 'skipped';
-        this.config.events?.onGroupComplete?.({
-          group_name: group.group,
-          iterations: iteration,
-          status: groupStatus,
-        });
-        this.config.emitter.emit({
-          type: 'group_complete',
-          groupName: group.group,
-          iterations: iteration,
-          status: groupStatus,
-        });
-        return {
-          status: groupStatus,
-          stageRuns: allStageRuns,
-          stagesExecuted: group.stages.length,
-          context,
-          totalTokensDelta,
-          totalToolCallsDelta,
-        };
-      }
-    }
-
-    // Max iterations exhausted
-    this.config.events?.onGroupComplete?.({
-      group_name: group.group,
-      iterations: iteration,
-      status: 'rejected',
-    });
-    this.config.emitter.emit({
-      type: 'group_complete',
-      groupName: group.group,
-      iterations: iteration,
-      status: 'rejected',
-    });
-    return {
-      status: 'rejected',
-      stageRuns: allStageRuns,
-      stagesExecuted: group.stages.length,
-      context,
-      totalTokensDelta,
-      totalToolCallsDelta,
-    };
-  }
-}

package/src/pipeline/hook-executor.test.ts

@@ -1,121 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { renderHookCommand, runStageHook, runToolHook } from './hook-executor.js';
-
-describe('renderHookCommand', () => {
-  it('substitutes {{tool.argName}} with tool argument value', () => {
-    const result = renderHookCommand(
-      'npx prettier --write {{tool.path}}',
-      { path: '/tmp/foo.ts' }
-    );
-    expect(result).toBe('npx prettier --write /tmp/foo.ts');
-  });
-
-  it('returns empty string for missing tool argument', () => {
-    const result = renderHookCommand('do something {{tool.missing}}', {});
-    expect(result).toBe('do something ');
-  });
-
-  it('substitutes multiple occurrences of the same placeholder', () => {
-    const result = renderHookCommand('cp {{tool.src}} {{tool.dst}}', { src: 'a.ts', dst: 'b.ts' });
-    expect(result).toBe('cp a.ts b.ts');
-  });
-
-  it('leaves non-tool placeholders unchanged', () => {
-    const result = renderHookCommand('echo {{other}}', { other: 'x' });
-    // {{other}} is not a {{tool.*}} pattern — left as-is
-    expect(result).toBe('echo {{other}}');
-  });
-
-  it('substitutes {{output.field}} with value from outputContext', () => {
-    const result = renderHookCommand(
-      'npx eslint {{output.files_changed}}',
-      {},
-      { files_changed: 'src/foo.ts' }
-    );
-    expect(result).toBe('npx eslint src/foo.ts');
-  });
-
-  it('space-joins array values from outputContext', () => {
-    const result = renderHookCommand(
-      'npx eslint {{output.files_changed}}',
-      {},
-      { files_changed: ['src/foo.ts', 'src/bar.ts'] }
-    );
-    expect(result).toBe('npx eslint src/foo.ts src/bar.ts');
-  });
-
-  it('returns empty string for missing output field', () => {
-    const result = renderHookCommand(
-      'npx eslint {{output.missing}}',
-      {},
-      {}
-    );
-    expect(result).toBe('npx eslint ');
-  });
-
-  it('handles mixed {{tool.*}} and {{output.*}} in same command', () => {
-    const result = renderHookCommand(
-      'run {{tool.script}} on {{output.files_changed}}',
-      { script: 'check.sh' },
-      { files_changed: 'src/foo.ts' }
-    );
-    expect(result).toBe('run check.sh on src/foo.ts');
-  });
-
-  it('leaves {{tool.*}} unchanged when outputContext not provided', () => {
-    const result = renderHookCommand('echo {{tool.path}}', { path: 'x.ts' });
-    expect(result).toBe('echo x.ts');
-  });
-});
-
-describe('runStageHook', () => {
-  it('returns success with stdout when command exits 0', async () => {
-    const result = await runStageHook(
-      { command: 'echo hello', on_failure: 'warn' },
-      '/tmp'
-    );
-    expect(result.success).toBe(true);
-    expect(result.stdout).toBe('hello');
-    expect(result.stderr).toBe('');
-  });
-
-  it('returns failure with stderr when command exits non-zero', async () => {
-    const result = await runStageHook(
-      { command: 'sh -c "echo boom >&2; exit 1"', on_failure: 'warn' },
-      '/tmp'
-    );
-    expect(result.success).toBe(false);
-    expect(result.stderr).toContain('boom');
-  });
-
-  it('resolves {{output.files_changed}} from outputContext in command', async () => {
-    const result = await runStageHook(
-      { command: 'echo {{output.files_changed}}', on_failure: 'warn' },
-      '/tmp',
-      { files_changed: ['src/foo.ts', 'src/bar.ts'] }
-    );
-    expect(result.success).toBe(true);
-    expect(result.stdout).toBe('src/foo.ts src/bar.ts');
-  });
-});
-
-describe('runToolHook', () => {
-  it('renders template and executes command', async () => {
-    const result = await runToolHook(
-      { matcher: 'repo_manager-write_file', command: 'echo {{tool.path}}', on_failure: 'warn' },
-      { path: '/tmp/test.ts' },
-      '/tmp'
-    );
-    expect(result.success).toBe(true);
-    expect(result.stdout).toBe('/tmp/test.ts');
-  });
-
-  it('returns failure when rendered command exits non-zero', async () => {
-    const result = await runToolHook(
-      { matcher: 'any-tool', command: 'exit 1', on_failure: 'warn' },
-      {},
-      '/tmp'
-    );
-    expect(result.success).toBe(false);
-  });
-});

package/src/pipeline/hook-executor.ts

@@ -1,87 +0,0 @@
-// Hook executor — runs shell commands at lifecycle points within a stage
-// Mirrors startup-executor.ts but with on_failure semantics and tool arg templates
-
-import { exec } from 'node:child_process';
-import { promisify } from 'node:util';
-import type { StageHookDef, ToolHookDef } from '@studio-foundation/contracts';
-
-const execAsync = promisify(exec);
-const HOOK_TIMEOUT_MS = 30_000;
-
-export interface HookResult {
-  success: boolean;
-  stdout: string;
-  stderr: string;
-}
-
-/**
- * Renders {{tool.argName}} and {{output.field}} placeholders.
- * Arrays in outputContext are space-joined for CLI argument passing.
- * Unknown keys → empty string.
- *
- * Note: values are substituted verbatim into the command string.
- * Hook commands are authored by pipeline owners (trusted), not end users.
- * Do not use with untrusted input sources.
- */
-export function renderHookCommand(
-  command: string,
-  toolArgs: Record<string, unknown>,
-  outputContext: Record<string, unknown> = {}
-): string {
-  return command
-    .replace(
-      /\{\{tool\.(\w+)\}\}/g,
-      (_, key: string) => (toolArgs[key] !== undefined ? String(toolArgs[key]) : '')
-    )
-    .replace(/\{\{output\.(\w+)\}\}/g, (_, key: string) => {
-      const val = outputContext[key];
-      if (val === undefined) return '';
-      if (Array.isArray(val)) return val.join(' ');
-      return String(val);
-    });
-}
-
-/**
- * Run a stage-level hook command (on_stage_start, on_stage_complete).
- * outputContext provides {{output.<field>}} substitution values.
- * on_stage_start hooks omit outputContext (no output available before the stage runs).
- */
-export async function runStageHook(
-  hook: StageHookDef,
-  cwd: string,
-  outputContext: Record<string, unknown> = {}
-): Promise<HookResult> {
-  const command = renderHookCommand(hook.command, {}, outputContext);
-  return execHook(command, cwd);
-}
-
-/**
- * Run a tool-level hook command (pre_tool_use, post_tool_use).
- * The command may reference tool arguments via {{tool.argName}}.
- */
-export async function runToolHook(
-  hook: ToolHookDef,
-  toolArgs: Record<string, unknown>,
-  cwd: string
-): Promise<HookResult> {
-  const command = renderHookCommand(hook.command, toolArgs);
-  return execHook(command, cwd);
-}
-
-async function execHook(command: string, cwd: string): Promise<HookResult> {
-  try {
-    const { stdout, stderr } = await execAsync(command, {
-      cwd,
-      timeout: HOOK_TIMEOUT_MS,
-      maxBuffer: 1024 * 1024 * 10,
-    });
-    return { success: true, stdout: stdout.trim(), stderr: stderr.trim() };
-  } catch (err: unknown) {
-    const e = err as { stdout?: string; stderr?: string };
-    return {
-      success: false,
-      stdout: e.stdout?.trim() ?? '',
-      stderr: e.stderr?.trim() ?? String(err),
-    };
-  }
-}