@studio-foundation/engine 0.3.0-beta.1

package/src/index.ts

@@ -0,0 +1,64 @@
+// Export barrel for @studio/engine
+
+// Main engine
+export { PipelineEngine } from './engine.js';
+export type { EngineConfig, RunInput } from './engine.js';
+
+// Events
+export { PipelineEventEmitter } from './events.js';
+export type {
+  EngineEvents,
+  PipelineEvent,
+  PipelineStartEvent,
+  PipelineCompleteEvent,
+  PipelineCancelledEvent,
+  StageStartEvent,
+  StageCompleteEvent,
+  StageRetryEvent,
+  ToolCallSummary,
+  TokenUsage,
+  GroupStartEvent,
+  GroupIterationEvent,
+  GroupFeedbackEvent,
+  GroupCompleteEvent,
+  StageContextEvent,
+  StagedToolCallStartEvent,
+  StagedToolCallCompleteEvent,
+} from './events.js';
+
+// State management
+export { deriveStageStatus } from './state/status-derivation.js';
+export { isValidTransition, transition } from './state/state-machine.js';
+export type { StageLifecycleState } from './state/state-machine.js';
+
+// Run store
+export { InMemoryRunStore, SQLiteRunStore, PgRunStore } from './state/run-store.js';
+export type { RunStore, AsyncRunStore, AnyRunStore } from './state/run-store.js';
+
+// Pipeline loaders
+export { loadPipeline, loadPipelineByName, parsePipelineYaml } from './pipeline/loader.js';
+export { loadAgentProfile, parseAgentYaml } from './pipeline/agent-loader.js';
+export { loadContract, parseContractYaml } from './pipeline/contract-loader.js';
+
+// Context propagation
+export {
+  createInitialContext,
+  addStageOutput,
+  getContextForStage,
+  setGroupFeedback,
+  clearGroupFeedback,
+} from './pipeline/context-propagation.js';
+export type { PipelineContext, PipelineInput, GroupFeedback } from './pipeline/context-propagation.js';
+
+// Contract validation
+export { validateOutput } from './pipeline/output-validator.js';
+export type { OutputValidationResult } from './pipeline/output-validator.js';
+export type { PostValidationResult } from './pipeline/post-validator.js';
+export { validateSchema } from '@studio-foundation/ralph';
+
+// Spawners
+export { DirectEngineSpawner } from './spawners/direct-engine-spawner.js';
+
+// Repo resolution
+export { resolveRepoPath, cloneRepo } from './repo-resolver.js';
+export type { RepoResolveOptions } from './repo-resolver.js';

package/src/pipeline/agent-loader.test.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect } from 'vitest';
+import { parseAgentYaml } from './agent-loader.js';
+
+describe('parseAgentYaml', () => {
+  it('parses plugins field from agent YAML', () => {
+    const yaml = `
+name: code-reviewer
+provider: anthropic
+model: claude-sonnet-4-20250514
+plugins:
+  - code-review
+  - analysis
+tools:
+  - repo_manager-read_file
+`;
+    const result = parseAgentYaml(yaml);
+    expect(result.plugins).toEqual(['code-review', 'analysis']);
+  });
+
+  it('returns undefined plugins when not specified', () => {
+    const yaml = `
+name: analyst
+provider: anthropic
+model: claude-haiku-4-5-20251001
+`;
+    const result = parseAgentYaml(yaml);
+    expect(result.plugins).toBeUndefined();
+  });
+});
+
+describe('skill injection logic', () => {
+  it('appends skill content to system_prompt when plugins match', () => {
+    // Test the injection logic directly
+    const agent = parseAgentYaml(`
+name: test-agent
+provider: anthropic
+model: claude-haiku-4-5-20251001
+system_prompt: "You are a reviewer."
+plugins:
+  - code-review
+`);
+
+    // Simulate what engine does
+    const pluginSkills: Record<string, string[]> = {
+      'code-review': ['## Skill: review-guidelines\n\nAlways check for bugs.'],
+    };
+
+    if (agent.plugins?.length && pluginSkills) {
+      const skillChunks = agent.plugins.flatMap((p) => pluginSkills[p] ?? []);
+      if (skillChunks.length > 0) {
+        agent.system_prompt = `${agent.system_prompt ?? ''}\n\n${skillChunks.join('\n\n---\n\n')}`;
+      }
+    }
+
+    expect(agent.system_prompt).toContain('You are a reviewer.');
+    expect(agent.system_prompt).toContain('## Skill: review-guidelines');
+    expect(agent.system_prompt).toContain('Always check for bugs.');
+  });
+
+  it('does not modify system_prompt when no matching plugin skills', () => {
+    const agent = parseAgentYaml(`
+name: test-agent
+provider: anthropic
+model: claude-haiku-4-5-20251001
+system_prompt: "Original prompt."
+plugins:
+  - unknown-plugin
+`);
+
+    const pluginSkills: Record<string, string[]> = {
+      'code-review': ['## Skill: review-guidelines\n\nAlways check for bugs.'],
+    };
+
+    const originalPrompt = agent.system_prompt;
+    if (agent.plugins?.length && pluginSkills) {
+      const skillChunks = agent.plugins.flatMap((p) => pluginSkills[p] ?? []);
+      if (skillChunks.length > 0) {
+        agent.system_prompt = `${agent.system_prompt ?? ''}\n\n${skillChunks.join('\n\n---\n\n')}`;
+      }
+    }
+
+    expect(agent.system_prompt).toBe(originalPrompt);
+  });
+});
+
+describe('skills field parsing', () => {
+  it('parses skills field from agent YAML', () => {
+    const yaml = `
+name: coder
+provider: anthropic
+model: claude-sonnet-4-6
+skills:
+  - git-workflow
+  - code-conventions
+`;
+    const result = parseAgentYaml(yaml);
+    expect(result.skills).toEqual(['git-workflow', 'code-conventions']);
+  });
+
+  it('returns undefined skills when not specified', () => {
+    const yaml = `
+name: analyst
+provider: anthropic
+model: claude-haiku-4-5-20251001
+`;
+    const result = parseAgentYaml(yaml);
+    expect(result.skills).toBeUndefined();
+  });
+});
+
+describe('project skill injection logic', () => {
+  it('appends skill content to system_prompt for declared skills', () => {
+    const agent = parseAgentYaml(`
+name: coder
+provider: anthropic
+model: claude-sonnet-4-6
+system_prompt: "You are a developer."
+skills:
+  - git-workflow
+`);
+
+    // Simulate what engine does: format loaded skills and append to system_prompt
+    const loadedSkills = [{ name: 'git-workflow', content: '# Git Workflow\n\nAlways branch from main.' }];
+    if (agent.skills?.length && loadedSkills.length > 0) {
+      const skillChunks = loadedSkills.map((s) => `## Skill: ${s.name}\n\n${s.content}`);
+      agent.system_prompt = `${agent.system_prompt ?? ''}\n\n${skillChunks.join('\n\n---\n\n')}`;
+    }
+
+    expect(agent.system_prompt).toContain('You are a developer.');
+    expect(agent.system_prompt).toContain('## Skill: git-workflow');
+    expect(agent.system_prompt).toContain('Always branch from main.');
+  });
+
+  it('does not modify system_prompt when no skills declared', () => {
+    const agent = parseAgentYaml(`
+name: analyst
+provider: anthropic
+model: claude-sonnet-4-6
+system_prompt: "You are an analyst."
+`);
+
+    const originalPrompt = agent.system_prompt;
+    const loadedSkills: Array<{ name: string; content: string }> = [];
+    if (agent.skills?.length && loadedSkills.length > 0) {
+      const skillChunks = loadedSkills.map((s) => `## Skill: ${s.name}\n\n${s.content}`);
+      agent.system_prompt = `${agent.system_prompt ?? ''}\n\n${skillChunks.join('\n\n---\n\n')}`;
+    }
+
+    expect(agent.system_prompt).toBe(originalPrompt);
+  });
+});

package/src/pipeline/agent-loader.ts

@@ -0,0 +1,39 @@
+// Load agent profiles from YAML files
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import * as yaml from 'js-yaml';
+import type { AgentConfig } from '@studio-foundation/contracts';
+
+export async function loadAgentProfile(
+  name: string,
+  agentsDir: string
+): Promise<AgentConfig> {
+  const path = join(agentsDir, `${name}.agent.yaml`);
+
+  let content: string;
+  try {
+    content = await readFile(path, 'utf-8');
+  } catch (err) {
+    throw new Error(`Failed to load agent profile '${name}' at ${path}: ${(err as Error).message}`);
+  }
+
+  return parseAgentYaml(content, path);
+}
+
+export function parseAgentYaml(yamlContent: string, sourcePath?: string): AgentConfig {
+  const parsed = yaml.load(yamlContent) as Record<string, unknown>;
+  const context = sourcePath ? ` (from ${sourcePath})` : '';
+
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error(`Invalid agent YAML: expected an object${context}`);
+  }
+
+  if (!parsed.name || typeof parsed.name !== 'string') {
+    throw new Error(`Agent config missing required field 'name'${context}`);
+  }
+
+  // provider and model are optional — defaults are applied at execution time
+
+  return parsed as unknown as AgentConfig;
+}

package/src/pipeline/condition-evaluator.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from 'vitest';
+import { evaluateCondition } from './condition-evaluator.js';
+
+const makeContext = (
+  input: Record<string, unknown> | string = {},
+  stageOutputs: Map<string, unknown> = new Map(),
+) => ({ input, stageOutputs });
+
+describe('evaluateCondition — input namespace', () => {
+  it('returns true when input field equals condition value (>=)', () => {
+    const ctx = makeContext({ meals_count: 6 });
+    expect(evaluateCondition('input.meals_count >= 6', ctx)).toBe(true);
+  });
+
+  it('returns false when input field is below threshold', () => {
+    const ctx = makeContext({ meals_count: 5 });
+    expect(evaluateCondition('input.meals_count >= 6', ctx)).toBe(false);
+  });
+
+  it('returns true for strict greater than when value exceeds', () => {
+    const ctx = makeContext({ meals_count: 7 });
+    expect(evaluateCondition('input.meals_count > 6', ctx)).toBe(true);
+  });
+
+  it('returns false for strict greater than when value equals threshold', () => {
+    const ctx = makeContext({ meals_count: 6 });
+    expect(evaluateCondition('input.meals_count > 6', ctx)).toBe(false);
+  });
+
+  it('returns true for less than', () => {
+    const ctx = makeContext({ priority: 2 });
+    expect(evaluateCondition('input.priority < 3', ctx)).toBe(true);
+  });
+
+  it('returns true for less than or equal', () => {
+    const ctx = makeContext({ priority: 3 });
+    expect(evaluateCondition('input.priority <= 3', ctx)).toBe(true);
+  });
+
+  it('returns true for == equality', () => {
+    const ctx = makeContext({ mode: 'fast' });
+    expect(evaluateCondition("input.mode == fast", ctx)).toBe(true);
+  });
+
+  it('returns true for === strict equality with number', () => {
+    const ctx = makeContext({ count: 0 });
+    expect(evaluateCondition('input.count === 0', ctx)).toBe(true);
+  });
+
+  it('returns true for != inequality', () => {
+    const ctx = makeContext({ mode: 'slow' });
+    expect(evaluateCondition("input.mode != fast", ctx)).toBe(true);
+  });
+
+  it('returns true for !== strict inequality', () => {
+    const ctx = makeContext({ count: 1 });
+    expect(evaluateCondition('input.count !== 0', ctx)).toBe(true);
+  });
+
+  it('returns false when input field is missing', () => {
+    const ctx = makeContext({ other_field: 5 });
+    expect(evaluateCondition('input.meals_count >= 6', ctx)).toBe(false);
+  });
+
+  it('returns false when input is a string (not an object)', () => {
+    const ctx = makeContext('plain string input');
+    expect(evaluateCondition('input.meals_count >= 6', ctx)).toBe(false);
+  });
+
+  it('supports nested field paths', () => {
+    const ctx = makeContext({ config: { threshold: 10 } });
+    expect(evaluateCondition('input.config.threshold > 5', ctx)).toBe(true);
+  });
+});
+
+describe('evaluateCondition — stages namespace', () => {
+  const stageOutputs = new Map<string, unknown>([
+    ['entity-extraction', { counts: { OTHER: 3, PERSON: 1 }, total: 4 }],
+    ['stage-with-zero', { count: 0 }],
+    ['analysis', { score: 0.85 }],
+  ]);
+
+  it('returns true when stage output field is above threshold', () => {
+    const ctx = makeContext({}, stageOutputs);
+    expect(evaluateCondition('stages.entity-extraction.output.counts.OTHER > 0', ctx)).toBe(true);
+  });
+
+  it('returns false when stage output field is zero', () => {
+    const ctx = makeContext({}, stageOutputs);
+    expect(evaluateCondition('stages.stage-with-zero.output.count > 0', ctx)).toBe(false);
+  });
+
+  it('supports stage names with hyphens', () => {
+    const ctx = makeContext({}, stageOutputs);
+    expect(evaluateCondition('stages.entity-extraction.output.total >= 3', ctx)).toBe(true);
+  });
+
+  it('returns false when stage does not exist in outputs', () => {
+    const ctx = makeContext({}, stageOutputs);
+    expect(evaluateCondition('stages.nonexistent.output.count > 0', ctx)).toBe(false);
+  });
+
+  it('returns false when nested field path does not exist', () => {
+    const ctx = makeContext({}, stageOutputs);
+    expect(evaluateCondition('stages.entity-extraction.output.missing.deep > 0', ctx)).toBe(false);
+  });
+
+  it('supports float comparisons', () => {
+    const ctx = makeContext({}, stageOutputs);
+    expect(evaluateCondition('stages.analysis.output.score >= 0.8', ctx)).toBe(true);
+  });
+});
+
+describe('evaluateCondition — edge cases', () => {
+  it('returns false for an unparseable expression (no operator)', () => {
+    const ctx = makeContext({ x: 1 });
+    expect(evaluateCondition('input.x', ctx)).toBe(false);
+  });
+
+  it('handles whitespace around operator', () => {
+    const ctx = makeContext({ n: 5 });
+    expect(evaluateCondition('input.n   >=   5', ctx)).toBe(true);
+  });
+
+  it('>=6 is treated correctly (no space before value)', () => {
+    const ctx = makeContext({ n: 6 });
+    expect(evaluateCondition('input.n >= 6', ctx)).toBe(true);
+  });
+});

package/src/pipeline/condition-evaluator.ts

@@ -0,0 +1,121 @@
+// Secure condition evaluator — no eval(), no external dependencies.
+// Supported syntax:
+//   input.<field.path>                      compared to a literal
+//   stages.<stage-name>.output.<field.path> compared to a literal
+// Operators: ===, !==, >=, <=, ==, !=, >, <
+// Returns false for any undefined/invalid path (skip-safe).
+
+import type { PipelineInput } from './context-propagation.js';
+
+// Longest-first to avoid '>' matching inside '>='
+const OPERATORS = ['===', '!==', '>=', '<=', '==', '!=', '>', '<'] as const;
+type Operator = typeof OPERATORS[number];
+
+export function evaluateCondition(
+  condition: string,
+  context: { input: PipelineInput; stageOutputs: Map<string, unknown> },
+): boolean {
+  const trimmed = condition.trim();
+
+  // Find operator (longest-first)
+  let operator: Operator | undefined;
+  let lhsStr = '';
+  let rhsStr = '';
+
+  for (const op of OPERATORS) {
+    const idx = trimmed.indexOf(op);
+    if (idx !== -1) {
+      operator = op;
+      lhsStr = trimmed.slice(0, idx).trim();
+      rhsStr = trimmed.slice(idx + op.length).trim();
+      break;
+    }
+  }
+
+  if (!operator || !lhsStr || !rhsStr) return false;
+
+  const lhsValue = resolveLhs(lhsStr, context);
+  if (lhsValue === undefined) return false;
+
+  const rhsValue = parseRhs(rhsStr);
+  return compare(lhsValue, operator, rhsValue);
+}
+
+function resolveLhs(
+  lhs: string,
+  context: { input: PipelineInput; stageOutputs: Map<string, unknown> },
+): unknown {
+  if (lhs.startsWith('input.')) {
+    const fieldPath = lhs.slice('input.'.length);
+    if (typeof context.input !== 'object' || context.input === null) return undefined;
+    return traversePath(context.input as Record<string, unknown>, fieldPath);
+  }
+
+  if (lhs.startsWith('stages.')) {
+    // Format: stages.<stage-name>.output.<field.path>
+    // Stage names can contain hyphens — split on first '.output.' occurrence
+    const rest = lhs.slice('stages.'.length);
+    const outputMarker = '.output.';
+    const markerIdx = rest.indexOf(outputMarker);
+    if (markerIdx === -1) return undefined;
+
+    const stageName = rest.slice(0, markerIdx);
+    const fieldPath = rest.slice(markerIdx + outputMarker.length);
+
+    const stageOutput = context.stageOutputs.get(stageName);
+    if (stageOutput === undefined || stageOutput === null) return undefined;
+
+    return traversePath(stageOutput as Record<string, unknown>, fieldPath);
+  }
+
+  return undefined;
+}
+
+function traversePath(obj: Record<string, unknown>, path: string): unknown {
+  const parts = path.split('.');
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+function parseRhs(rhs: string): unknown {
+  // Number (int or float, optional leading minus)
+  if (/^-?\d+(\.\d+)?$/.test(rhs)) return Number(rhs);
+  // Boolean
+  if (rhs === 'true') return true;
+  if (rhs === 'false') return false;
+  // Quoted string
+  if ((rhs.startsWith('"') && rhs.endsWith('"')) || (rhs.startsWith("'") && rhs.endsWith("'"))) {
+    return rhs.slice(1, -1);
+  }
+  // Plain string (e.g. input.mode == fast)
+  return rhs;
+}
+
+function compare(lhs: unknown, op: Operator, rhs: unknown): boolean {
+  // Coerce lhs to number if rhs is a number and lhs is a string
+  let lhsCoerced: unknown = lhs;
+  if (typeof rhs === 'number' && typeof lhs === 'string') {
+    const n = Number(lhs);
+    if (!isNaN(n)) lhsCoerced = n;
+  }
+
+  switch (op) {
+    case '>':   return typeof lhsCoerced === 'number' && typeof rhs === 'number' && lhsCoerced > rhs;
+    case '>=':  return typeof lhsCoerced === 'number' && typeof rhs === 'number' && lhsCoerced >= rhs;
+    case '<':   return typeof lhsCoerced === 'number' && typeof rhs === 'number' && lhsCoerced < rhs;
+    case '<=':  return typeof lhsCoerced === 'number' && typeof rhs === 'number' && lhsCoerced <= rhs;
+    // eslint-disable-next-line eqeqeq
+    case '==':  return lhsCoerced == rhs;
+    case '===': return lhsCoerced === rhs;
+    // eslint-disable-next-line eqeqeq
+    case '!=':  return lhsCoerced != rhs;
+    case '!==': return lhsCoerced !== rhs;
+    default:    return false;
+  }
+}

package/src/pipeline/context-pack-loader.ts

@@ -0,0 +1,63 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import type { ContextPackDefinition, ResolvedContextPack } from '@studio-foundation/contracts';
+
+export async function loadContextPacks(
+  packNames: string[],
+  projectConfigPath: string,
+  workspacePath?: string,
+): Promise<ResolvedContextPack[]> {
+  if (packNames.length === 0) return [];
+
+  const packsDir = path.join(projectConfigPath, 'context-packs');
+  const results: ResolvedContextPack[] = [];
+
+  for (const packName of packNames) {
+    const packFile = path.join(packsDir, `${packName}.yaml`);
+
+    let rawContent: string;
+    try {
+      rawContent = await fs.readFile(packFile, 'utf-8');
+    } catch {
+      throw new Error(`Context pack "${packName}" not found at ${packFile}`);
+    }
+
+    const definition = yaml.load(rawContent) as ContextPackDefinition;
+    const sections: Array<{ title: string; content: string }> = [];
+
+    // File sections first (in YAML order)
+    if (definition.files?.length) {
+      if (!workspacePath) {
+        throw new Error(
+          `Context pack "${packName}" references files but workspace is not configured`,
+        );
+      }
+      for (const fileRef of definition.files) {
+        const filePath = path.join(workspacePath, fileRef.path);
+        let content: string;
+        try {
+          content = await fs.readFile(filePath, 'utf-8');
+        } catch {
+          throw new Error(`File "${fileRef.path}" not found in workspace at ${filePath}`);
+        }
+        sections.push({ title: fileRef.path, content });
+      }
+    }
+
+    // Inline sections after (in YAML order)
+    if (definition.inline?.length) {
+      for (const inline of definition.inline) {
+        sections.push({ title: inline.title, content: inline.content });
+      }
+    }
+
+    results.push({
+      name: definition.name,
+      ...(definition.description !== undefined && { description: definition.description }),
+      sections,
+    });
+  }
+
+  return results;
+}