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

package/src/__tests__/engine.conditions.test.ts

@@ -1,186 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { resolve } from 'node:path';
-import { PipelineEngine } from '../engine.js';
-import type { PipelineDefinition } from '@studio-foundation/contracts';
-
-// Mock the runner so we can inspect which stages actually ran
-vi.mock('@studio-foundation/runner', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('@studio-foundation/runner')>();
-  return {
-    ...actual,
-    runScript: vi.fn(),
-  };
-});
-
-import { runScript } from '@studio-foundation/runner';
-
-const FIXTURES_DIR = resolve(__dirname, '__fixtures__/script-stage');
-
-function makeEngine() {
-  return new PipelineEngine({
-    configsDir: FIXTURES_DIR,
-    providerRegistry: {} as any,
-  });
-}
-
-function mockScriptSuccess(output: Record<string, unknown> = { result: 'ok' }) {
-  vi.mocked(runScript).mockResolvedValue({
-    output,
-    tool_calls: [],
-    tool_calls_count: 0,
-    duration_ms: 10,
-  });
-}
-
-describe('engine — stage conditions', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('skips a stage when input condition is false', async () => {
-    mockScriptSuccess();
-
-    const pipeline: PipelineDefinition = {
-      name: 'test-conditions',
-      description: 'test',
-      version: 1,
-      stages: [
-        {
-          name: 'always-runs',
-          executor: 'script',
-          script: 'scripts/parse.py',
-          runtime: 'shell',
-        },
-        {
-          name: 'conditional-stage',
-          executor: 'script',
-          script: 'scripts/parse.py',
-          runtime: 'shell',
-          condition: 'input.meals_count >= 6',
-        },
-      ],
-    };
-
-    const engine = makeEngine();
-    const result = await engine.run({
-      pipelineDef: pipeline,
-      input: { meals_count: 3 },  // condition is false — stage should skip
-    });
-
-    expect(result.status).toBe('success');
-    expect(result.stages).toHaveLength(2);
-    expect(result.stages[0]?.status).toBe('success');
-    expect(result.stages[1]?.status).toBe('skipped');
-    // Script was only called once (for always-runs, not conditional-stage)
-    expect(vi.mocked(runScript)).toHaveBeenCalledTimes(1);
-  });
-
-  it('runs a stage when input condition is true', async () => {
-    mockScriptSuccess();
-
-    const pipeline: PipelineDefinition = {
-      name: 'test-conditions-true',
-      description: 'test',
-      version: 1,
-      stages: [
-        {
-          name: 'conditional-stage',
-          executor: 'script',
-          script: 'scripts/parse.py',
-          runtime: 'shell',
-          condition: 'input.meals_count >= 6',
-        },
-      ],
-    };
-
-    const engine = makeEngine();
-    const result = await engine.run({
-      pipelineDef: pipeline,
-      input: { meals_count: 7 },  // condition is true — stage should run
-    });
-
-    expect(result.status).toBe('success');
-    expect(result.stages[0]?.status).toBe('success');
-    expect(vi.mocked(runScript)).toHaveBeenCalledTimes(1);
-  });
-
-  it('skips a stage based on previous stage output', async () => {
-    // First call returns extraction result, second call would be entity-resolution
-    vi.mocked(runScript).mockResolvedValueOnce({
-      output: { counts: { OTHER: 0, PERSON: 2 } },
-      tool_calls: [],
-      tool_calls_count: 0,
-      duration_ms: 10,
-    });
-
-    const pipeline: PipelineDefinition = {
-      name: 'test-conditions-stage-output',
-      description: 'test',
-      version: 1,
-      stages: [
-        {
-          name: 'entity-extraction',
-          executor: 'script',
-          script: 'scripts/extract.py',
-          runtime: 'shell',
-          context: { include: ['input'] },
-        },
-        {
-          name: 'entity-resolution-OTHER',
-          executor: 'script',
-          script: 'scripts/resolve.py',
-          runtime: 'shell',
-          condition: 'stages.entity-extraction.output.counts.OTHER > 0',
-          context: { include: ['all_stage_outputs'] },
-        },
-      ],
-    };
-
-    const engine = makeEngine();
-    const result = await engine.run({
-      pipelineDef: pipeline,
-      input: 'extract entities',
-    });
-
-    expect(result.status).toBe('success');
-    expect(result.stages[0]?.status).toBe('success');
-    expect(result.stages[1]?.status).toBe('skipped');  // counts.OTHER is 0
-    expect(vi.mocked(runScript)).toHaveBeenCalledTimes(1);  // only extraction ran
-  });
-
-  it('pipeline continues after skipped stage', async () => {
-    mockScriptSuccess({ final: 'result' });
-
-    const pipeline: PipelineDefinition = {
-      name: 'test-skip-continues',
-      description: 'test',
-      version: 1,
-      stages: [
-        {
-          name: 'skipped-stage',
-          executor: 'script',
-          script: 'scripts/parse.py',
-          runtime: 'shell',
-          condition: 'input.run_optional >= 1',
-        },
-        {
-          name: 'final-stage',
-          executor: 'script',
-          script: 'scripts/finalize.py',
-          runtime: 'shell',
-        },
-      ],
-    };
-
-    const engine = makeEngine();
-    const result = await engine.run({
-      pipelineDef: pipeline,
-      input: { run_optional: 0 },
-    });
-
-    expect(result.status).toBe('success');
-    expect(result.stages[0]?.status).toBe('skipped');
-    expect(result.stages[1]?.status).toBe('success');
-    expect(vi.mocked(runScript)).toHaveBeenCalledTimes(1);  // only final-stage
-  });
-});

package/src/__tests__/engine.resume.test.ts

@@ -1,108 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { PipelineEngine } from '../engine.js';
-import type { PipelineDefinition } from '@studio-foundation/contracts';
-
-vi.mock('@studio-foundation/runner', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('@studio-foundation/runner')>();
-  return {
-    ...actual,
-    runScript: vi.fn(),
-  };
-});
-
-import { runScript } from '@studio-foundation/runner';
-
-function makeEngine() {
-  return new PipelineEngine({
-    configsDir: '/tmp',
-    providerRegistry: {} as any,
-  });
-}
-
-function mockScriptSuccess(output: Record<string, unknown> = { result: 'ok' }) {
-  vi.mocked(runScript).mockResolvedValue({
-    output,
-    tool_calls: [],
-    tool_calls_count: 0,
-    duration_ms: 10,
-  });
-}
-
-describe('engine — resume from stage', () => {
-  beforeEach(() => vi.clearAllMocks());
-
-  const pipeline: PipelineDefinition = {
-    name: 'test-resume',
-    description: 'test',
-    version: 1,
-    stages: [
-      { name: 'stage-a', executor: 'script', script: 'x.py', runtime: 'shell' },
-      { name: 'stage-b', executor: 'script', script: 'x.py', runtime: 'shell' },
-      { name: 'stage-c', executor: 'script', script: 'x.py', runtime: 'shell' },
-    ],
-  };
-
-  it('skips stages before resumeFromStage and marks them skipped', async () => {
-    mockScriptSuccess({ result: 'c-result' });
-
-    const engine = makeEngine();
-    const result = await engine.run({
-      pipelineDef: pipeline,
-      input: { x: 1 },
-      resumeFromStage: 'stage-c',
-      priorStageOutputs: new Map([
-        ['stage-a', { result: 'a-cached' }],
-        ['stage-b', { result: 'b-cached' }],
-      ]),
-      originalRunId: 'abc12345',
-    });
-
-    expect(result.status).toBe('success');
-    expect(result.stages).toHaveLength(3);
-    expect(result.stages[0]?.stage_name).toBe('stage-a');
-    expect(result.stages[0]?.status).toBe('skipped');
-    expect(result.stages[0]?.skipped_reason).toContain('abc12345');
-    expect(result.stages[1]?.stage_name).toBe('stage-b');
-    expect(result.stages[1]?.status).toBe('skipped');
-    expect(result.stages[2]?.stage_name).toBe('stage-c');
-    expect(result.stages[2]?.status).toBe('success');
-    // Only stage-c was actually executed
-    expect(vi.mocked(runScript)).toHaveBeenCalledTimes(1);
-  });
-
-  it('pre-populates context so resumed stage can access prior outputs', async () => {
-    mockScriptSuccess({ result: 'ok' });
-
-    const engine = makeEngine();
-    const result = await engine.run({
-      pipelineDef: {
-        ...pipeline,
-        stages: [
-          { name: 'stage-a', executor: 'script', script: 'x.py', runtime: 'shell' },
-          { name: 'stage-b', executor: 'script', script: 'x.py', runtime: 'shell' },
-        ],
-      },
-      input: { x: 1 },
-      resumeFromStage: 'stage-b',
-      priorStageOutputs: new Map([['stage-a', { result: 'a-cached' }]]),
-    });
-
-    // stage-b ran successfully (prior context was pre-populated, no crash)
-    expect(result.status).toBe('success');
-    expect(result.stages).toHaveLength(2);
-    expect(result.stages[0]?.status).toBe('skipped');
-    expect(result.stages[1]?.status).toBe('success');
-  });
-
-  it('throws if resumeFromStage is not found in pipeline', async () => {
-    const engine = makeEngine();
-    await expect(
-      engine.run({
-        pipelineDef: pipeline,
-        input: {},
-        resumeFromStage: 'nonexistent-stage',
-        priorStageOutputs: new Map(),
-      })
-    ).rejects.toThrow(/not found/i);
-  });
-});

package/src/__tests__/engine.script-stage.test.ts

@@ -1,125 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { resolve } from 'node:path';
-import { PipelineEngine } from '../engine.js';
-import type { PipelineDefinition } from '@studio-foundation/contracts';
-
-// Mock runScript from runner to avoid real subprocess spawning
-vi.mock('@studio-foundation/runner', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('@studio-foundation/runner')>();
-  return {
-    ...actual,
-    runScript: vi.fn(),
-  };
-});
-
-import { runScript } from '@studio-foundation/runner';
-
-const FIXTURES_DIR = resolve(__dirname, '__fixtures__/script-stage');
-
-const SCRIPT_PIPELINE: PipelineDefinition = {
-  name: 'test-script-pipeline',
-  description: 'Test pipeline with script stage',
-  version: 1,
-  stages: [
-    {
-      name: 'epub-ingestion',
-      executor: 'script',
-      script: 'scripts/parse.py',
-      runtime: 'python',
-      contract: 'book-context',
-    },
-  ],
-};
-
-function makeEngine() {
-  return new PipelineEngine({
-    configsDir: FIXTURES_DIR,
-    providerRegistry: {} as any,
-  });
-}
-
-describe('engine — script stage execution', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('executes a script stage and returns success when output matches contract', async () => {
-    vi.mocked(runScript).mockResolvedValue({
-      output: { title: 'My Book', chapters: 3 },
-      tool_calls: [],
-      tool_calls_count: 0,
-      duration_ms: 50,
-    });
-
-    const engine = makeEngine();
-    const result = await engine.run({
-      pipelineDef: SCRIPT_PIPELINE,
-      userInput: 'parse book.epub',
-    });
-
-    expect(result.status).toBe('success');
-    expect(result.stages[0]?.status).toBe('success');
-    expect(result.stages[0]?.output).toEqual({ title: 'My Book', chapters: 3 });
-    expect(vi.mocked(runScript)).toHaveBeenCalledTimes(1);
-    expect(vi.mocked(runScript)).toHaveBeenCalledWith(
-      expect.objectContaining({
-        scriptPath: 'scripts/parse.py',
-        runtime: 'python',
-      }),
-    );
-  });
-
-  it('retries on script error (runScript returns error field)', async () => {
-    const scriptError = {
-      output: null,
-      tool_calls: [],
-      tool_calls_count: 0,
-      duration_ms: 10,
-      error: 'Script exited with code 1: parse error',
-    };
-    vi.mocked(runScript)
-      .mockResolvedValueOnce(scriptError)
-      .mockResolvedValueOnce(scriptError)
-      .mockResolvedValue({
-        output: { title: 'My Book', chapters: 3 },
-        tool_calls: [],
-        tool_calls_count: 0,
-        duration_ms: 50,
-      });
-
-    const engine = makeEngine();
-    const result = await engine.run({
-      pipelineDef: {
-        ...SCRIPT_PIPELINE,
-        stages: [{ ...SCRIPT_PIPELINE.stages[0], ralph: { max_attempts: 3, retry_strategy: 'none' } }],
-      },
-      userInput: 'parse book.epub',
-    });
-
-    expect(result.status).toBe('success');
-    expect(vi.mocked(runScript)).toHaveBeenCalledTimes(3);
-  });
-
-  it('fails stage after exhausting max_attempts', async () => {
-    vi.mocked(runScript).mockResolvedValue({
-      output: null,
-      tool_calls: [],
-      tool_calls_count: 0,
-      duration_ms: 10,
-      error: 'Script exited with code 1: always failing',
-    });
-
-    const engine = makeEngine();
-    const result = await engine.run({
-      pipelineDef: {
-        ...SCRIPT_PIPELINE,
-        stages: [{ ...SCRIPT_PIPELINE.stages[0], ralph: { max_attempts: 2, retry_strategy: 'none' } }],
-      },
-      userInput: 'parse book.epub',
-    });
-
-    expect(result.status).toBe('failed');
-    expect(result.stages[0]?.status).toBe('failed');
-    expect(vi.mocked(runScript)).toHaveBeenCalledTimes(2);
-  });
-});

package/src/engine.context-event.test.ts

@@ -1,175 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { mkdtemp, mkdir, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-import { PipelineEngine } from './engine.js';
-import { createDefaultRegistry, ToolRegistry, MockProvider } from '@studio-foundation/runner';
-import type { StageContextEvent } from './events.js';
-
-async function makeTestDirs(): Promise<{ configsDir: string }> {
-  const base = await mkdtemp(join(tmpdir(), 'studio-ctx-test-'));
-  const configsDir = join(base, '.studio');
-  await mkdir(join(configsDir, 'pipelines'), { recursive: true });
-  await mkdir(join(configsDir, 'agents'), { recursive: true });
-  await mkdir(join(configsDir, 'contracts'), { recursive: true });
-
-  await writeFile(
-    join(configsDir, 'pipelines', 'test-pipe.pipeline.yaml'),
-    `
-name: test-pipe
-description: test
-version: 1
-stages:
-  - name: my-stage
-    kind: analysis
-    agent: analyst
-    contract: stage-contract
-    context:
-      include: [input]
-`
-  );
-
-  await writeFile(
-    join(configsDir, 'agents', 'analyst.agent.yaml'),
-    `
-name: analyst
-provider: mock
-model: mock
-system_prompt: "You are an analyst."
-`
-  );
-
-  await writeFile(
-    join(configsDir, 'contracts', 'stage-contract.contract.yaml'),
-    `
-name: stage-contract
-version: 1
-schema:
-  required_fields:
-    - summary
-`
-  );
-
-  return { configsDir };
-}
-
-// MockProvider keys on contract_name (= stage_contract). Use this in all tests.
-const MOCK_STAGE_KEY = 'stage-contract';
-
-describe('PipelineEngine — onStageContext event', () => {
-  it('emits onStageContext once per stage', async () => {
-    const { configsDir } = await makeTestDirs();
-
-    const mockStages = new Map([
-      [MOCK_STAGE_KEY, { output: { summary: 'done' }, tool_calls: [] }],
-    ]);
-    const mockProvider = new MockProvider(mockStages);
-    const providerRegistry = createDefaultRegistry({});
-    providerRegistry.register(mockProvider);
-    const toolRegistry = new ToolRegistry();
-
-    const received: StageContextEvent[] = [];
-
-    const engine = new PipelineEngine(
-      { configsDir, providerRegistry, toolRegistry },
-      { onStageContext: (e) => received.push(e) }
-    );
-
-    await engine.run({ pipeline: 'test-pipe', input: 'test input' });
-
-    expect(received).toHaveLength(1);
-    expect(received[0].stage).toBe('my-stage');
-    expect(received[0].run_id).toMatch(/^[0-9a-f-]{36}$/); // uuid
-    expect(received[0].context_keys.input).toBe('test input'.length);
-  });
-
-  it('includes no context_content by default (DEBUG unset)', async () => {
-    const { configsDir } = await makeTestDirs();
-    delete process.env.DEBUG;
-
-    const mockProvider = new MockProvider(
-      new Map([[MOCK_STAGE_KEY, { output: { summary: 'done' }, tool_calls: [] }]])
-    );
-    const providerRegistry = createDefaultRegistry({});
-    providerRegistry.register(mockProvider);
-
-    const received: StageContextEvent[] = [];
-    const engine = new PipelineEngine(
-      { configsDir, providerRegistry, toolRegistry: new ToolRegistry() },
-      { onStageContext: (e) => received.push(e) }
-    );
-
-    await engine.run({ pipeline: 'test-pipe', input: 'hello' });
-
-    expect(received[0].context_content).toBeUndefined();
-    expect(received[0].system_prompt).toBeUndefined();
-  });
-
-  it('includes context_content when DEBUG=studio:context', async () => {
-    const { configsDir } = await makeTestDirs();
-    process.env.DEBUG = 'studio:context';
-
-    const mockProvider = new MockProvider(
-      new Map([[MOCK_STAGE_KEY, { output: { summary: 'done' }, tool_calls: [] }]])
-    );
-    const providerRegistry = createDefaultRegistry({});
-    providerRegistry.register(mockProvider);
-
-    const received: StageContextEvent[] = [];
-    const engine = new PipelineEngine(
-      { configsDir, providerRegistry, toolRegistry: new ToolRegistry() },
-      { onStageContext: (e) => received.push(e) }
-    );
-
-    await engine.run({ pipeline: 'test-pipe', input: 'hello' });
-
-    expect(received[0].context_content).toBeDefined();
-    expect(received[0].context_content?.input).toBe('hello');
-    expect(received[0].system_prompt).toBeUndefined();
-
-    delete process.env.DEBUG;
-  });
-
-  it('includes system_prompt when DEBUG=studio:context:verbose', async () => {
-    const { configsDir } = await makeTestDirs();
-    process.env.DEBUG = 'studio:context:verbose';
-
-    const mockProvider = new MockProvider(
-      new Map([[MOCK_STAGE_KEY, { output: { summary: 'done' }, tool_calls: [] }]])
-    );
-    const providerRegistry = createDefaultRegistry({});
-    providerRegistry.register(mockProvider);
-
-    const received: StageContextEvent[] = [];
-    const engine = new PipelineEngine(
-      { configsDir, providerRegistry, toolRegistry: new ToolRegistry() },
-      { onStageContext: (e) => received.push(e) }
-    );
-
-    await engine.run({ pipeline: 'test-pipe', input: 'hello' });
-
-    expect(received[0].context_content).toBeDefined(); // verbose implies context
-    expect(received[0].system_prompt).toBe('You are an analyst.');
-
-    delete process.env.DEBUG;
-  });
-
-  it('does not call handler at all when onStageContext is not registered', async () => {
-    const { configsDir } = await makeTestDirs();
-
-    const mockProvider = new MockProvider(
-      new Map([[MOCK_STAGE_KEY, { output: { summary: 'done' }, tool_calls: [] }]])
-    );
-    const providerRegistry = createDefaultRegistry({});
-    providerRegistry.register(mockProvider);
-
-    // No onStageContext handler
-    const engine = new PipelineEngine(
-      { configsDir, providerRegistry, toolRegistry: new ToolRegistry() },
-      { onStageComplete: vi.fn() } // some other handler but not onStageContext
-    );
-
-    // Should not throw
-    await engine.run({ pipeline: 'test-pipe', input: 'hello' });
-  });
-});