@studio-foundation/engine 0.3.0-beta.1

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

@@ -0,0 +1,108 @@
+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

@@ -0,0 +1,125 @@
+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/db/client.ts

@@ -0,0 +1,5 @@
+// Database client — re-exports from run-store
+// Kept for backward compatibility with the barrel structure
+
+export { SQLiteRunStore, InMemoryRunStore, PgRunStore } from '../state/run-store.js';
+export type { RunStore, AsyncRunStore, AnyRunStore } from '../state/run-store.js';

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

@@ -0,0 +1,175 @@
+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' });
+  });
+});