@studio-foundation/engine 0.3.0-beta.1

package/tests/context-propagation.test.ts

@@ -0,0 +1,267 @@
+import { describe, it, expect } from 'vitest';
+import {
+  createInitialContext,
+  addStageOutput,
+  addStageToolResults,
+  getContextForStage,
+  setGroupFeedback,
+  clearGroupFeedback,
+  type GroupFeedback,
+} from '../src/pipeline/context-propagation.js';
+import type { StageDefinition, ToolCall } from '@studio-foundation/contracts';
+
+function makeStage(overrides: Partial<StageDefinition> = {}): StageDefinition {
+  return {
+    name: 'test-stage',
+    kind: 'analysis',
+    agent: 'analyst',
+    ...overrides,
+  } as StageDefinition;
+}
+
+describe('createInitialContext', () => {
+  it('creates context with input', () => {
+    const ctx = createInitialContext('Build a FAQ page');
+    expect(ctx.input).toBe('Build a FAQ page');
+    expect(ctx.stageOutputs.size).toBe(0);
+    expect(ctx.stageToolResults.size).toBe(0);
+  });
+
+  it('optionally includes repoPath', () => {
+    const ctx = createInitialContext('test', '/path/to/repo');
+    expect(ctx.repoPath).toBe('/path/to/repo');
+  });
+});
+
+describe('addStageOutput', () => {
+  it('adds stage output to context', () => {
+    const ctx = createInitialContext('test');
+    addStageOutput(ctx, 'brief-analysis', { summary: 'done' });
+
+    expect(ctx.stageOutputs.get('brief-analysis')).toEqual({ summary: 'done' });
+  });
+
+  it('accumulates multiple stage outputs', () => {
+    const ctx = createInitialContext('test');
+    addStageOutput(ctx, 'stage-1', { result: 'a' });
+    addStageOutput(ctx, 'stage-2', { result: 'b' });
+
+    expect(ctx.stageOutputs.size).toBe(2);
+    expect(ctx.stageOutputs.get('stage-1')).toEqual({ result: 'a' });
+    expect(ctx.stageOutputs.get('stage-2')).toEqual({ result: 'b' });
+  });
+});
+
+describe('structured input', () => {
+  it('passes structured input as YAML string in additional_context', () => {
+    const structuredInput = {
+      brief_summary: 'Add FAQ to About page',
+      target_page: 'src/pages/about.tsx',
+      acceptance_criteria: ['FAQ section appears', 'Accordion style'],
+    };
+    const context = createInitialContext(structuredInput);
+    const agentCtx = getContextForStage(context, {
+      name: 'test',
+      kind: 'analysis',
+      agent: 'test-agent',
+      context: { include: ['input'] },
+    });
+    // Structured input should be serialized as YAML in additional_context
+    expect(agentCtx.additional_context).toContain('brief_summary');
+    expect(agentCtx.additional_context).toContain('Add FAQ to About page');
+    expect(agentCtx.additional_context).toContain('target_page');
+  });
+
+  it('passes string input unchanged', () => {
+    const context = createInitialContext('Simple string input');
+    const agentCtx = getContextForStage(context, {
+      name: 'test',
+      kind: 'analysis',
+      agent: 'test-agent',
+      context: { include: ['input'] },
+    });
+    expect(agentCtx.additional_context).toBe('Simple string input');
+  });
+});
+
+describe('getContextForStage', () => {
+  it('with "input" includes user input as additional_context', () => {
+    const ctx = createInitialContext('Build a FAQ');
+    const stage = makeStage({ context: { include: ['input'] } });
+
+    const agentCtx = getContextForStage(ctx, stage);
+    expect(agentCtx.additional_context).toBe('Build a FAQ');
+  });
+
+  it('with "previous_stage_output" includes the last stage output', () => {
+    const ctx = createInitialContext('test');
+    addStageOutput(ctx, 'analysis', { summary: 'looks good' });
+    addStageOutput(ctx, 'planning', { steps: [1, 2, 3] });
+
+    const stage = makeStage({ context: { include: ['previous_stage_output'] } });
+    const agentCtx = getContextForStage(ctx, stage, 'planning');
+
+    expect(agentCtx.previous_outputs).toEqual({
+      planning: { steps: [1, 2, 3] },
+    });
+  });
+
+  it('with "all_stage_outputs" includes all accumulated outputs', () => {
+    const ctx = createInitialContext('test');
+    addStageOutput(ctx, 'stage-1', { result: 'a' });
+    addStageOutput(ctx, 'stage-2', { result: 'b' });
+
+    const stage = makeStage({ context: { include: ['all_stage_outputs'] } });
+    const agentCtx = getContextForStage(ctx, stage);
+
+    expect(agentCtx.previous_outputs).toEqual({
+      'stage-1': { result: 'a' },
+      'stage-2': { result: 'b' },
+    });
+  });
+
+  it('with "repo_files" sets repo_files to empty array (engine fills later)', () => {
+    const ctx = createInitialContext('test', '/repo');
+    const stage = makeStage({ context: { include: ['repo_files'] } });
+
+    const agentCtx = getContextForStage(ctx, stage);
+    expect(agentCtx.repo_files).toEqual([]);
+  });
+
+  it('defaults to "input" when no context.include specified', () => {
+    const ctx = createInitialContext('default input');
+    const stage = makeStage({});
+
+    const agentCtx = getContextForStage(ctx, stage);
+    expect(agentCtx.additional_context).toBe('default input');
+  });
+
+  it('combines multiple includes', () => {
+    const ctx = createInitialContext('user input');
+    addStageOutput(ctx, 'prev', { data: 42 });
+
+    const stage = makeStage({
+      context: { include: ['input', 'previous_stage_output', 'repo_files'] },
+    });
+    const agentCtx = getContextForStage(ctx, stage, 'prev');
+
+    expect(agentCtx.additional_context).toBe('user input');
+    expect(agentCtx.previous_outputs).toEqual({ prev: { data: 42 } });
+    expect(agentCtx.repo_files).toEqual([]);
+  });
+});
+
+describe('group feedback', () => {
+  it('setGroupFeedback adds feedback to context', () => {
+    const ctx = createInitialContext('test');
+    const feedback: GroupFeedback = {
+      iteration: 1,
+      max_iterations: 3,
+      rejection_reason: 'Missing error handling',
+    };
+    setGroupFeedback(ctx, feedback);
+    expect(ctx.groupFeedback).toEqual(feedback);
+  });
+
+  it('clearGroupFeedback removes feedback from context', () => {
+    const ctx = createInitialContext('test');
+    setGroupFeedback(ctx, {
+      iteration: 1,
+      max_iterations: 3,
+      rejection_reason: 'test',
+    });
+    clearGroupFeedback(ctx);
+    expect(ctx.groupFeedback).toBeUndefined();
+  });
+
+  it('getContextForStage populates group_feedback as dedicated field', () => {
+    const ctx = createInitialContext('Build a FAQ');
+    setGroupFeedback(ctx, {
+      iteration: 1,
+      max_iterations: 3,
+      rejection_reason: 'Props not passed to component',
+      rejection_details: ['Missing onClick handler', 'Wrong prop type'],
+    });
+
+    const stage = makeStage({
+      context: { include: ['input', 'group_feedback'] },
+    });
+    const agentCtx = getContextForStage(ctx, stage);
+
+    // Input goes to additional_context, feedback goes to dedicated field
+    expect(agentCtx.additional_context).toBe('Build a FAQ');
+    expect(agentCtx.group_feedback).toEqual({
+      iteration: 1,
+      max_iterations: 3,
+      rejection_reason: 'Props not passed to component',
+      rejection_details: ['Missing onClick handler', 'Wrong prop type'],
+    });
+  });
+
+  it('group_feedback is ignored when no feedback is set', () => {
+    const ctx = createInitialContext('Build a FAQ');
+    const stage = makeStage({
+      context: { include: ['input', 'group_feedback'] },
+    });
+    const agentCtx = getContextForStage(ctx, stage);
+
+    // Only input is present, no feedback
+    expect(agentCtx.additional_context).toBe('Build a FAQ');
+    expect(agentCtx.group_feedback).toBeUndefined();
+  });
+});
+
+describe('addStageToolResults', () => {
+  it('stores tool calls by stage name', () => {
+    const ctx = createInitialContext('test');
+    const toolCalls: ToolCall[] = [
+      { id: '1', name: 'search-search_codebase', arguments: { pattern: 'about' }, result: { matches: [] } },
+    ];
+    addStageToolResults(ctx, 'brief-analysis', toolCalls);
+    expect(ctx.stageToolResults.get('brief-analysis')).toEqual(toolCalls);
+  });
+
+  it('accumulates tool results across stages', () => {
+    const ctx = createInitialContext('test');
+    addStageToolResults(ctx, 'stage-1', [{ id: '1', name: 'tool-a', arguments: {}, result: 'r1' }]);
+    addStageToolResults(ctx, 'stage-2', [{ id: '2', name: 'tool-b', arguments: {}, result: 'r2' }]);
+    expect(ctx.stageToolResults.size).toBe(2);
+  });
+});
+
+describe('getContextForStage — previous_stage_tool_results', () => {
+  it('includes tool calls from the previous stage', () => {
+    const ctx = createInitialContext('test');
+    const toolCalls: ToolCall[] = [
+      { id: '1', name: 'search-search_codebase', arguments: { pattern: 'about' }, result: { matches: ['about.tsx'] } },
+    ];
+    addStageToolResults(ctx, 'brief-analysis', toolCalls);
+
+    const stage = makeStage({ context: { include: ['previous_stage_tool_results'] } });
+    const agentCtx = getContextForStage(ctx, stage, 'brief-analysis');
+
+    expect(agentCtx.previous_tool_results).toEqual({ 'brief-analysis': toolCalls });
+  });
+
+  it('returns empty when no previous stage tool results', () => {
+    const ctx = createInitialContext('test');
+    const stage = makeStage({ context: { include: ['previous_stage_tool_results'] } });
+    const agentCtx = getContextForStage(ctx, stage, 'nonexistent');
+    expect(agentCtx.previous_tool_results).toBeUndefined();
+  });
+});
+
+describe('getContextForStage — all_stage_tool_results', () => {
+  it('includes tool calls from all stages', () => {
+    const ctx = createInitialContext('test');
+    const tc1: ToolCall[] = [{ id: '1', name: 'tool-a', arguments: {}, result: 'r1' }];
+    const tc2: ToolCall[] = [{ id: '2', name: 'tool-b', arguments: {}, result: 'r2' }];
+    addStageToolResults(ctx, 'stage-1', tc1);
+    addStageToolResults(ctx, 'stage-2', tc2);
+
+    const stage = makeStage({ context: { include: ['all_stage_tool_results'] } });
+    const agentCtx = getContextForStage(ctx, stage);
+
+    expect(agentCtx.previous_tool_results).toEqual({ 'stage-1': tc1, 'stage-2': tc2 });
+  });
+});

package/tests/direct-engine-spawner.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect, vi } from 'vitest';
+import { DirectEngineSpawner } from '../src/spawners/direct-engine-spawner.js';
+import type { EngineConfig } from '../src/engine.js';
+import type { PipelineRun } from '@studio-foundation/contracts';
+
+function makeSuccessRun(overrides?: Partial<PipelineRun>): PipelineRun {
+  return {
+    id: 'child-run-1',
+    pipeline_name: 'test-pipe',
+    status: 'success',
+    started_at: new Date().toISOString(),
+    stages: [
+      {
+        id: 's1',
+        stage_name: 'final',
+        status: 'success',
+        started_at: new Date().toISOString(),
+        tasks: [],
+        output: { answer: 42 },
+      },
+    ],
+    ...overrides,
+  };
+}
+
+// We mock PipelineEngine to avoid real execution
+vi.mock('../src/engine.js', () => ({
+  PipelineEngine: vi.fn(function () {
+    return { run: vi.fn() };
+  }),
+}));
+
+describe('DirectEngineSpawner', () => {
+  it('calls child engine.run() with correct args', async () => {
+    const { PipelineEngine } = await import('../src/engine.js');
+    const mockRun = vi.fn().mockResolvedValue(makeSuccessRun());
+    (PipelineEngine as any).mockImplementation(function () { return { run: mockRun }; });
+
+    const spawner = new DirectEngineSpawner({} as EngineConfig);
+    await spawner.spawnAndWait({
+      pipeline: 'recipe-developer',
+      input: { dish: 'pasta' },
+      parentRunId: 'parent-1',
+      depth: 1,
+    });
+
+    expect(mockRun).toHaveBeenCalledWith(
+      expect.objectContaining({
+        pipeline: 'recipe-developer',
+        input: { dish: 'pasta' },
+        parentRunId: 'parent-1',
+        depth: 1,
+      })
+    );
+  });
+
+  it('returns run_id, status, and last stage output on success', async () => {
+    const { PipelineEngine } = await import('../src/engine.js');
+    const successRun = makeSuccessRun();
+    (PipelineEngine as any).mockImplementation(function () { return {
+      run: vi.fn().mockResolvedValue(successRun),
+    }; });
+
+    const spawner = new DirectEngineSpawner({} as EngineConfig);
+    const result = await spawner.spawnAndWait({
+      pipeline: 'test',
+      input: {},
+      parentRunId: 'p1',
+      depth: 1,
+    });
+
+    expect(result.run_id).toBe('child-run-1');
+    expect(result.status).toBe('success');
+    expect(result.output).toEqual({ answer: 42 });
+  });
+
+  it('throws when child run fails', async () => {
+    const { PipelineEngine } = await import('../src/engine.js');
+    const failedRun = makeSuccessRun({ id: 'child-fail', status: 'failed', stages: [] });
+    (PipelineEngine as any).mockImplementation(function () { return {
+      run: vi.fn().mockResolvedValue(failedRun),
+    }; });
+
+    const spawner = new DirectEngineSpawner({} as EngineConfig);
+    await expect(
+      spawner.spawnAndWait({ pipeline: 'bad', input: {}, parentRunId: 'p1', depth: 1 })
+    ).rejects.toThrow('Child run child-fail failed');
+  });
+
+  it('throws when child run is rejected', async () => {
+    const { PipelineEngine } = await import('../src/engine.js');
+    const rejectedRun = makeSuccessRun({ id: 'child-rej', status: 'rejected', stages: [] });
+    (PipelineEngine as any).mockImplementation(function () { return {
+      run: vi.fn().mockResolvedValue(rejectedRun),
+    }; });
+
+    const spawner = new DirectEngineSpawner({} as EngineConfig);
+    await expect(
+      spawner.spawnAndWait({ pipeline: 'qa', input: {}, parentRunId: 'p1', depth: 1 })
+    ).rejects.toThrow('Child run child-rej rejected');
+  });
+});

package/tests/e2e/feature-v5.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { join } from 'node:path';
+
+// Feature-builder E2E test
+// "Add FAQ to About page" — this is THE test that must pass 10/10
+//
+// Requires:
+// - API key (ANTHROPIC_API_KEY)
+// - A test repo to modify
+// - All pipeline infrastructure running
+//
+// Unskip when everything is fully connected
+
+describe.skip('feature-builder E2E', () => {
+  const ROOT = join(import.meta.dirname, '..', '..');
+
+  it('should add FAQ section to About page', async () => {
+    const { PipelineEngine } = await import('../../src/engine.js');
+    const { InMemoryRunStore } = await import('../../src/state/run-store.js');
+    const { ToolRegistry, createRepoManagerTools, createShellTools, createSearchTools } = await import('@studio-foundation/runner');
+    const { createDefaultRegistry } = await import('@studio-foundation/runner');
+
+    // Setup tools
+    const toolRegistry = new ToolRegistry();
+    const testRepoPath = '/tmp/studio-test-repo'; // TODO: create temp repo
+    for (const tool of createRepoManagerTools(testRepoPath)) {
+      toolRegistry.register(tool);
+    }
+    for (const tool of createShellTools(testRepoPath)) {
+      toolRegistry.register(tool);
+    }
+    for (const tool of createSearchTools(testRepoPath)) {
+      toolRegistry.register(tool);
+    }
+
+    const providerRegistry = createDefaultRegistry({
+      anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! },
+    });
+
+    const engine = new PipelineEngine({
+      configsDir: join(ROOT, 'configs'),
+      repoPath: testRepoPath,
+      providerRegistry,
+      toolRegistry,
+      db: new InMemoryRunStore(),
+    });
+
+    const result = await engine.run({
+      pipeline: 'software/feature-builder',
+      input: 'Add a FAQ section to the About page',
+    });
+
+    expect(result.status).toBe('success');
+    expect(result.stages).toHaveLength(4);
+    expect(result.stages.every(s => s.status === 'success')).toBe(true);
+  });
+});

package/tests/events.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from 'vitest';
+import type { StageRetryEvent, StagedToolCallStartEvent, StagedToolCallCompleteEvent } from '../src/events.js';
+
+describe('StageRetryEvent', () => {
+  it('includes max_attempts field', () => {
+    const event: StageRetryEvent = {
+      stage: 'code-generation',
+      attempt: 2,
+      failures: ['missing field: summary'],
+      max_attempts: 3,
+    };
+    expect(event.max_attempts).toBe(3);
+  });
+
+  it('includes optional agent_output_raw and tool_calls_count', () => {
+    const event: StageRetryEvent = {
+      stage: 'code-generation',
+      attempt: 1,
+      failures: ['validation failed'],
+      max_attempts: 5,
+      agent_output_raw: '{"summary": "incomplete"}',
+      tool_calls_count: 3,
+    };
+    expect(event.agent_output_raw).toBe('{"summary": "incomplete"}');
+    expect(event.tool_calls_count).toBe(3);
+  });
+});
+
+describe('StagedToolCallStartEvent', () => {
+  it('includes stage, tool, and params fields', () => {
+    const event: StagedToolCallStartEvent = {
+      stage: 'code-generation',
+      tool: 'repo_manager-write_file',
+      params: { path: 'src/foo.ts' },
+      timestamp: 1700000000000,
+    };
+    expect(event.stage).toBe('code-generation');
+    expect(event.tool).toBe('repo_manager-write_file');
+    expect(event.params).toEqual({ path: 'src/foo.ts' });
+  });
+});
+
+describe('StagedToolCallCompleteEvent', () => {
+  it('includes stage, tool, result, and duration_ms fields', () => {
+    const event: StagedToolCallCompleteEvent = {
+      stage: 'code-generation',
+      tool: 'repo_manager-write_file',
+      result: 'written',
+      duration_ms: 120,
+      timestamp: 1700000000000,
+    };
+    expect(event.stage).toBe('code-generation');
+    expect(event.tool).toBe('repo_manager-write_file');
+    expect(event.duration_ms).toBe(120);
+  });
+});

package/tests/fixtures/agents/test-agent.agent.yaml

@@ -0,0 +1,5 @@
+
+name: test-agent
+provider: anthropic
+model: claude-sonnet-4-20250514
+temperature: 0.3

package/tests/fixtures/contracts/code-gen.contract.yaml

@@ -0,0 +1,6 @@
+
+name: code-gen
+version: 1
+schema:
+  required_fields:
+    - files_changed

package/tests/fixtures/contracts/qa-gate.contract.yaml

@@ -0,0 +1,15 @@
+
+name: qa-gate
+version: 1
+schema:
+  required_fields:
+    - status
+    - issues
+post_validation:
+  rejection_detection:
+    field: status
+    approved_values:
+      - approved
+      - pass
+    details_field: issues
+    summary_field: summary

package/tests/fixtures/contracts/test-contract.contract.yaml

@@ -0,0 +1,6 @@
+
+name: test-contract
+version: 1
+schema:
+  required_fields:
+    - summary

package/tests/fixtures/pipelines/group-test.pipeline.yaml

@@ -0,0 +1,40 @@
+
+name: group-test
+description: Test pipeline with a feedback loop group
+version: 2
+stages:
+  - name: analysis
+    kind: analysis
+    agent: test-agent
+    ralph:
+      max_attempts: 1
+      retry_strategy: none
+    context:
+      include:
+        - input
+  - group: impl-review
+    max_iterations: 3
+    stages:
+      - name: code-gen
+        kind: code_generation
+        agent: test-agent
+        contract: code-gen
+        ralph:
+          max_attempts: 1
+          retry_strategy: none
+        context:
+          include:
+            - input
+            - all_stage_outputs
+            - group_feedback
+      - name: qa-review
+        kind: qa
+        agent: test-agent
+        contract: qa-gate
+        ralph:
+          max_attempts: 1
+          retry_strategy: none
+        context:
+          include:
+            - input
+            - all_stage_outputs

package/tests/fixtures/pipelines/simple.pipeline.yaml

@@ -0,0 +1,15 @@
+
+name: simple
+description: Simple test pipeline
+version: 1
+stages:
+  - name: analysis
+    kind: analysis
+    agent: test-agent
+    contract: test-contract
+    ralph:
+      max_attempts: 2
+      retry_strategy: none
+    context:
+      include:
+        - input

package/tests/fixtures/pipelines/two-stage.pipeline.yaml

@@ -0,0 +1,24 @@
+
+name: two-stage
+description: Two stage pipeline
+version: 1
+stages:
+  - name: stage-1
+    kind: analysis
+    agent: test-agent
+    ralph:
+      max_attempts: 1
+      retry_strategy: none
+    context:
+      include:
+        - input
+  - name: stage-2
+    kind: planning
+    agent: test-agent
+    ralph:
+      max_attempts: 1
+      retry_strategy: none
+    context:
+      include:
+        - input
+        - previous_stage_output

package/tests/fixtures/software/pipelines/feature-builder.pipeline.yaml

@@ -0,0 +1,75 @@
+name: feature-builder
+description: Build a feature from a user description
+version: 2
+
+repo:
+  url: https://github.com/arianeguay/pipelines-test-repo
+  branch: main
+
+stages:
+  - name: brief-analysis
+    kind: analysis
+    agent: analyst
+    contract: brief-analysis
+    ralph:
+      max_attempts: 3
+      retry_strategy: exponential
+      max_tool_calls: 5
+    context:
+      include:
+        - input
+
+  - name: implementation-plan
+    kind: planning
+    agent: analyst
+    contract: implementation-plan
+    ralph:
+      max_attempts: 3
+      retry_strategy: exponential
+      max_tool_calls: 5
+    context:
+      include:
+        - input
+        - previous_stage_output
+
+  - group: implementation-review
+    max_iterations: 3
+    stages:
+      - name: code-generation
+        kind: code_generation
+        agent: coder
+        contract: code-generation
+        hooks:
+          on_stage_complete:
+            - command: "npx tsc --noEmit"
+              on_failure: reject
+            - command: "npx eslint --rule 'no-empty: error' --rule 'no-unused-vars: warn' {{output.files_changed}}"
+              on_failure: reject
+        ralph:
+          max_attempts: 5
+          retry_strategy: exponential
+          max_tool_calls: 200
+        tools:
+          required:
+            - repo_manager-write_file
+        context:
+          include:
+            - input
+            - all_stage_outputs
+            - repo_files
+            - group_feedback
+          packs:
+            - example-conventions
+
+      - name: qa-review
+        kind: qa
+        agent: analyst
+        contract: qa-review
+        ralph:
+          max_attempts: 3
+          retry_strategy: exponential
+          max_tool_calls: 5
+        context:
+          include:
+            - input
+            - all_stage_outputs

package/tests/fixtures/test-project/agents/test-agent.agent.yaml

@@ -0,0 +1,5 @@
+
+name: test-agent
+provider: anthropic
+model: claude-sonnet-4-20250514
+temperature: 0.3

package/tests/fixtures/test-project/contracts/basic-result.contract.yaml

@@ -0,0 +1,6 @@
+
+name: basic-result
+version: 1
+schema:
+  required_fields:
+    - result