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

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@studio-foundation/runner",
-  "version": "0.3.0-beta.1",
+  "version": "0.3.0-beta.6",
   "description": "Multi-provider LLM agent runner with tool execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "keywords": [
     "llm",
     "agent",
@@ -18,8 +21,8 @@
     "@modelcontextprotocol/sdk": "^1.26.0",
     "js-yaml": "^4.1.0",
     "openai": "^4.77.0",
-    "@studio-foundation/anonymizer": "0.3.0-beta.1",
-    "@studio-foundation/contracts": "0.3.0-beta.1"
+    "@studio-foundation/anonymizer": "0.3.0-beta.6",
+    "@studio-foundation/contracts": "0.3.0-beta.6"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/ARCHITECTURE.md

@@ -1,53 +0,0 @@
-# @studio-foundation/runner
-
-Agent runner multi-provider. Parle aux LLMs, exécute les tools, streame les tokens.
-
-## Concept
-
-`runAgent()` prend un `AgentConfig` + contexte, appelle le LLM, exécute les tool calls en boucle, retourne un `AgentRunResult` complet avec tous les tool calls trackés et l'usage de tokens.
-
-## Règles
-
-- Multi-provider : Anthropic, OpenAI, OpenAI Responses API, Mock — même interface `runAgent()`
-- CHAQUE tool call réel est tracké dans `AgentRunResult.tool_calls`
-- Le runner ne valide PAS — c'est le job de ralph
-- Le runner ne retry PAS — c'est le job de ralph
-- Les prompts sont assemblés ici (`prompt-builder.ts`) — le engine ne touche jamais aux prompts
-- Les tools sont enregistrés ici (`ToolRegistry`) — le engine ne sait pas ce qu'est `repo_manager-write_file`
-- Dépend UNIQUEMENT de `@studio-foundation/contracts`
-
-## Fichiers clés
-
-- `runner.ts` — `runAgent()` fonction principale, deux chemins : agent loop provider et chat completions standard
-- `prompt-builder.ts` — assemblage system prompt + skills + context + task
-- `providers/anthropic.ts` — Claude (prompt caching, 90% cost reduction sur retries)
-- `providers/openai.ts` — OpenAI chat completions
-- `providers/openai-responses.ts` — OpenAI Responses API (provider owns the loop)
-- `providers/mock.ts` — mock provider pour tests sans API keys
-- `providers/registry.ts` — `ProviderRegistry`, `createDefaultRegistry()`
-- `tools/tool-registry.ts` — `ToolRegistry` (register, lookup)
-- `tools/tool-executor.ts` — `ToolExecutor` (dispatch tool calls)
-- `tools/plugin-loader.ts` — charge les `.tool.yaml` plugins
-- `tools/builtin/repo-manager.ts` — `repo_manager-read_file`, `write_file`, `list_files`
-- `tools/builtin/shell.ts` — `shell-run_command`
-- `tools/builtin/search.ts` — `search-search_codebase`
-- `tools/builtin/git.ts` — `git-checkout`, `git-commit`, `git-push`, `git-pull`, `git-status`, `git-diff`
-- `tools/builtin/patch.ts` — `patch-apply_patch`
-- `tools/builtin/studio-run.ts` — `studio_run` (spawn sous-pipeline, requiert `RunSpawner`)
-- `tools/skills/skill-loader.ts` — charge les `.skill.md` files
-- `middleware/anonymization.ts` — `AnonymizationMiddleware` (wraps `@studio-foundation/anonymizer`)
-- `plugins/plugin-loader.ts` — charge les plugins Claude Code (`.mcp.json` + `skills/`)
-- `plugins/mcp-client.ts` — `MCPClient` (connexion aux serveurs MCP)
-- `integrations/integration-loader.ts` — charge les `.integration.yaml`
-
-## Hooks callbacks
-
-`RunnerCallbacks` (dans `@studio-foundation/contracts`) wire les hooks du engine vers le runner :
-
-- `onPreToolUse` — peut bloquer un tool call (`{ blocked: true }`)
-- `onPostToolUse` — peut injecter du feedback (`{ append_message: '...' }`)
-- `onToolCallStart/Complete`, `onAgentThinking/Progress/Token` — observabilité
-
-## Anti-pattern : LE THÉÂTRE
-
-Le problème fondamental : les agents génèrent du JSON décrivant des actions au lieu de FAIRE les actions (`tool_calls: 0`). Le runner DOIT tracker tous les tool calls réels. La validation du théâtre est dans ralph, mais le runner fournit les données.

package/configs/agents/analyst.agent.yaml

@@ -1,31 +0,0 @@
-name: analyst
-version: 1.0.0
-description: Agent specialized in code analysis and understanding
-
-systemMessage: |
-  You are an expert code analyst that helps understand complex codebases.
-
-  When analyzing code:
-  - Identify key patterns and architectural decisions
-  - Highlight potential issues or improvements
-  - Explain complex logic clearly
-  - Trace data flow and dependencies
-  - Provide actionable insights
-
-  Use search and file reading tools to explore the codebase thoroughly.
-
-capabilities:
-  - code_analysis
-  - architecture_review
-  - dependency_tracing
-  - pattern_recognition
-  - documentation
-
-tools:
-  - repo_manager
-  - search
-  - shell
-
-parameters:
-  temperature: 0.5
-  maxTokens: 4096

package/configs/agents/code-generator.agent.yaml

@@ -1,31 +0,0 @@
-name: code-generator
-version: 1.0.0
-description: Agent specialized in generating and modifying code
-
-systemMessage: |
-  You are an expert software engineer that writes clean, efficient, and well-documented code.
-
-  When generating code:
-  - Follow best practices and conventions for the target language
-  - Include appropriate error handling
-  - Add clear comments and documentation
-  - Use modern language features appropriately
-  - Ensure code is production-ready
-
-  Use the available tools to read existing code, write new files, and search the codebase.
-
-capabilities:
-  - code_generation
-  - code_modification
-  - refactoring
-  - file_operations
-  - code_analysis
-
-tools:
-  - repo_manager
-  - search
-  - shell
-
-parameters:
-  temperature: 0.3
-  maxTokens: 4096

package/configs/agents/generic.agent.yaml

@@ -1,23 +0,0 @@
-name: generic
-version: 1.0.0
-description: General-purpose assistant agent
-
-systemMessage: |
-  You are a helpful assistant that can perform tasks using available tools.
-  Be concise and accurate in your responses.
-  Use tools when necessary to accomplish the user's goals.
-
-capabilities:
-  - general_qa
-  - file_operations
-  - command_execution
-  - code_search
-
-tools:
-  - repo_manager
-  - shell
-  - search
-
-parameters:
-  temperature: 0.7
-  maxTokens: 2048

package/src/__tests__/script-executor.test.ts

@@ -1,180 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import * as cp from 'node:child_process';
-import * as fs from 'node:fs';
-import { EventEmitter } from 'node:events';
-
-// Mock child_process and fs before importing the module under test
-vi.mock('node:child_process');
-vi.mock('node:fs');
-
-import { runScript } from '../script-executor.js';
-import type { AgentContext } from '../prompt-builder.js';
-
-function makeContext(overrides?: Partial<AgentContext>): AgentContext {
-  return {
-    input: 'test input',
-    ...overrides,
-  } as AgentContext;
-}
-
-function makeSpawnMock(opts: {
-  stdout?: string;
-  stderr?: string;
-  exitCode?: number;
-  errorEvent?: Error;
-}) {
-  const proc = new EventEmitter() as ReturnType<typeof cp.spawn>;
-  (proc as any).stdout = new EventEmitter();
-  (proc as any).stderr = new EventEmitter();
-  (proc as any).stdin = { write: vi.fn(), end: vi.fn() };
-  (proc as any).kill = vi.fn();
-
-  vi.mocked(cp.spawn).mockReturnValue(proc as any);
-
-  // Simulate async process lifecycle
-  setTimeout(() => {
-    if (opts.errorEvent) {
-      proc.emit('error', opts.errorEvent);
-      return;
-    }
-    if (opts.stdout) (proc as any).stdout.emit('data', Buffer.from(opts.stdout));
-    if (opts.stderr) (proc as any).stderr.emit('data', Buffer.from(opts.stderr));
-    proc.emit('close', opts.exitCode ?? 0);
-  }, 10);
-
-  return proc;
-}
-
-beforeEach(() => {
-  vi.mocked(fs.existsSync).mockReturnValue(false);
-  vi.clearAllMocks();
-});
-
-describe('runScript', () => {
-  it('parses stdout JSON and returns output on exit 0', async () => {
-    const output = { result: 'ok', count: 42 };
-    makeSpawnMock({ stdout: JSON.stringify(output), exitCode: 0 });
-
-    const result = await runScript({
-      scriptPath: 'scripts/parse.py',
-      runtime: 'python',
-      context: makeContext(),
-    });
-
-    expect(result.output).toEqual(output);
-    expect(result.tool_calls).toEqual([]);
-    expect(result.tool_calls_count).toBe(0);
-    expect(result.error).toBeUndefined();
-    expect(result.duration_ms).toBeGreaterThanOrEqual(0);
-  });
-
-  it('sets error when script exits with non-zero code', async () => {
-    makeSpawnMock({ stdout: '', stderr: 'FileNotFoundError', exitCode: 1 });
-
-    const result = await runScript({
-      scriptPath: 'scripts/parse.py',
-      runtime: 'python',
-      context: makeContext(),
-    });
-
-    expect(result.output).toBeNull();
-    expect(result.error).toMatch(/exited with code 1/);
-    expect(result.error).toMatch(/FileNotFoundError/);
-  });
-
-  it('sets error when stdout is not valid JSON', async () => {
-    makeSpawnMock({ stdout: 'not json at all', exitCode: 0 });
-
-    const result = await runScript({
-      scriptPath: 'scripts/parse.py',
-      runtime: 'python',
-      context: makeContext(),
-    });
-
-    expect(result.output).toBeNull();
-    expect(result.error).toMatch(/not valid JSON/);
-    expect(result.error).toMatch(/not json at all/);
-  });
-
-  it('sets error on process spawn error', async () => {
-    const proc = new EventEmitter() as ReturnType<typeof cp.spawn>;
-    (proc as any).stdout = new EventEmitter();
-    (proc as any).stderr = new EventEmitter();
-    (proc as any).stdin = { write: vi.fn(), end: vi.fn() };
-    vi.mocked(cp.spawn).mockReturnValue(proc as any);
-    setTimeout(() => proc.emit('error', new Error('ENOENT: python3 not found')), 10);
-
-    const result = await runScript({
-      scriptPath: 'scripts/parse.py',
-      runtime: 'python',
-      context: makeContext(),
-    });
-
-    expect(result.error).toMatch(/process error/);
-    expect(result.error).toMatch(/ENOENT/);
-  });
-
-  it('uses python3 command for python runtime', async () => {
-    makeSpawnMock({ stdout: '{}', exitCode: 0 });
-
-    await runScript({ scriptPath: 'scripts/parse.py', runtime: 'python', context: makeContext() });
-
-    expect(vi.mocked(cp.spawn)).toHaveBeenCalledWith(
-      'python3',
-      ['scripts/parse.py'],
-      expect.objectContaining({ stdio: ['pipe', 'pipe', 'pipe'] }),
-    );
-  });
-
-  it('uses node command for node runtime', async () => {
-    makeSpawnMock({ stdout: '{}', exitCode: 0 });
-
-    await runScript({ scriptPath: 'scripts/parse.js', runtime: 'node', context: makeContext() });
-
-    expect(vi.mocked(cp.spawn)).toHaveBeenCalledWith('node', ['scripts/parse.js'], expect.anything());
-  });
-
-  it('uses sh command for shell runtime', async () => {
-    makeSpawnMock({ stdout: '{}', exitCode: 0 });
-
-    await runScript({ scriptPath: 'scripts/run.sh', runtime: 'shell', context: makeContext() });
-
-    expect(vi.mocked(cp.spawn)).toHaveBeenCalledWith('sh', ['scripts/run.sh'], expect.anything());
-  });
-
-  it('activates venv when venv/ directory exists', async () => {
-    vi.mocked(fs.existsSync).mockImplementation((p) => String(p).endsWith('venv'));
-    makeSpawnMock({ stdout: '{}', exitCode: 0 });
-
-    await runScript({
-      scriptPath: 'scripts/parse.py',
-      runtime: 'python',
-      context: makeContext(),
-      cwd: '/project',
-    });
-
-    const spawnCall = vi.mocked(cp.spawn).mock.calls[0];
-    const spawnEnv = (spawnCall[2] as any).env;
-    expect(spawnEnv.VIRTUAL_ENV).toBe('/project/venv');
-    expect(spawnEnv.PATH).toContain('/project/venv/bin');
-  });
-
-  it('writes context JSON to stdin', async () => {
-    const stdinMock = { write: vi.fn(), end: vi.fn() };
-    const proc = new EventEmitter() as ReturnType<typeof cp.spawn>;
-    (proc as any).stdout = new EventEmitter();
-    (proc as any).stderr = new EventEmitter();
-    (proc as any).stdin = stdinMock;
-    vi.mocked(cp.spawn).mockReturnValue(proc as any);
-    setTimeout(() => {
-      (proc as any).stdout.emit('data', Buffer.from('{"ok":true}'));
-      proc.emit('close', 0);
-    }, 10);
-
-    const ctx = makeContext({ additional_context: 'hello world' });
-    await runScript({ scriptPath: 'scripts/parse.py', runtime: 'python', context: ctx });
-
-    expect(stdinMock.write).toHaveBeenCalledWith(JSON.stringify(ctx));
-    expect(stdinMock.end).toHaveBeenCalled();
-  });
-});

package/src/index.ts

@@ -1,68 +0,0 @@
-/**
- * @studio/runner - Multi-provider LLM agent runner with tool execution
- */
-
-// Main runner function
-export { runAgent } from './runner.js';
-export type { RunAgentConfig, AgentRunResult } from './runner.js';
-
-// Script executor
-export { runScript } from './script-executor.js';
-export type { ScriptExecutorConfig } from './script-executor.js';
-
-// Prompt builder
-export { buildPrompt } from './prompt-builder.js';
-export type {
-  TaskInput,
-  AgentContext,
-  GroupFeedbackContext,
-  ExecutionContext,
-  PromptBuildConfig
-} from './prompt-builder.js';
-
-// Providers
-export type { Provider, AgentLoopProvider, AgentLoopResult } from './providers/provider.js';
-export { isAgentLoopProvider } from './providers/provider.js';
-export { OpenAIProvider } from './providers/openai.js';
-export { OpenAIResponsesProvider } from './providers/openai-responses.js';
-export { AnthropicProvider } from './providers/anthropic.js';
-export { OllamaProvider } from './providers/ollama.js';
-export { ProviderRegistry, createDefaultRegistry } from './providers/registry.js';
-export { MockProvider } from './providers/mock.js';
-export type { MockStageConfig } from './providers/mock.js';
-
-// Tools
-export { ToolRegistry } from './tools/tool-registry.js';
-export { ToolExecutor } from './tools/tool-executor.js';
-export type { Tool, ToolResult } from './tools/tool-registry.js';
-
-// Builtin tools
-export { createRepoManagerTools } from './tools/builtin/repo-manager.js';
-export { createShellTools } from './tools/builtin/shell.js';
-export { createSearchTools } from './tools/builtin/search.js';
-export { createPatchTools } from './tools/builtin/patch.js';
-export { createGitTools } from './tools/builtin/git.js';
-export { createStudioRunTool, STUDIO_RUN_PROMPT_SNIPPET } from './tools/builtin/studio-run.js';
-export { createWebSearchTools, WEB_SEARCH_PROMPT_SNIPPET } from './tools/builtin/web-search.js';
-
-export { loadProjectTools, listAvailableToolTemplates, getBundledToolTemplate, BUILTIN_TOOL_NAMES } from './tools/plugin-loader.js';
-export type { LoadedPlugin } from './tools/plugin-loader.js';
-
-// Anonymization middleware
-export { AnonymizationMiddleware } from './middleware/anonymization.js';
-export type { AnonymizerOptions } from '@studio-foundation/anonymizer';
-
-// Plugin system (Claude Code plugin compatibility)
-export { loadPlugins, MCPClient, StudioOAuthProvider } from './plugins/index.js';
-export type { PluginManifest, MCPServerDef, SkillContent } from './plugins/index.js';
-
-// Skill loader
-export { loadSkills, loadSkill, validateSkillManifest } from './tools/skills/skill-loader.js';
-export type { SkillManifest } from './tools/skills/skill-loader.js';
-
-// Integration plugin system
-export {
-  getBundledIntegrationTemplate,
-  listAvailableIntegrationTemplates,
-  loadProjectIntegrations,
-} from './integrations/integration-loader.js';

package/src/integrations/integration-loader.test.ts

@@ -1,88 +0,0 @@
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-import {
-  getBundledIntegrationTemplate,
-  listAvailableIntegrationTemplates,
-  loadProjectIntegrations,
-} from './integration-loader.js';
-
-let tmpDir: string;
-
-beforeAll(async () => {
-  tmpDir = await mkdtemp(join(tmpdir(), 'studio-integration-loader-test-'));
-});
-
-afterAll(async () => {
-  await rm(tmpDir, { recursive: true, force: true });
-});
-
-describe('getBundledIntegrationTemplate', () => {
-  it('returns YAML content for a known bundled integration', async () => {
-    const content = await getBundledIntegrationTemplate('linear');
-    expect(content).not.toBeNull();
-    expect(content).toContain('name: linear');
-  });
-
-  it('returns null for unknown integration name', async () => {
-    const content = await getBundledIntegrationTemplate('doesnotexist');
-    expect(content).toBeNull();
-  });
-});
-
-describe('listAvailableIntegrationTemplates', () => {
-  it('returns at least linear, slack, webhook', async () => {
-    const templates = await listAvailableIntegrationTemplates();
-    const names = templates.map(t => t.name);
-    expect(names).toContain('linear');
-    expect(names).toContain('slack');
-    expect(names).toContain('webhook');
-  });
-
-  it('each entry has name and description', async () => {
-    const templates = await listAvailableIntegrationTemplates();
-    for (const t of templates) {
-      expect(typeof t.name).toBe('string');
-      expect(typeof t.description).toBe('string');
-    }
-  });
-});
-
-describe('loadProjectIntegrations', () => {
-  it('returns empty array when directory does not exist', async () => {
-    const result = await loadProjectIntegrations('/nonexistent/path');
-    expect(result).toEqual([]);
-  });
-
-  it('loads valid .integration.yaml files', async () => {
-    const intDir = join(tmpDir, 'integrations');
-    await mkdir(intDir, { recursive: true });
-    await writeFile(join(intDir, 'test.integration.yaml'), `
-name: test
-version: 1
-description: "Test integration"
-config:
-  required:
-    - TEST_API_KEY
-test:
-  type: http
-  endpoint: https://api.test.com/health
-  expect:
-    status: 200
-`);
-    const result = await loadProjectIntegrations(intDir);
-    expect(result).toHaveLength(1);
-    expect(result[0]!.name).toBe('test');
-    expect(result[0]!.config?.required).toEqual(['TEST_API_KEY']);
-  });
-
-  it('ignores non-.integration.yaml files', async () => {
-    const intDir = join(tmpDir, 'integrations-mixed');
-    await mkdir(intDir, { recursive: true });
-    await writeFile(join(intDir, 'readme.txt'), 'hello');
-    await writeFile(join(intDir, 'other.yaml'), 'name: other\nversion: 1');
-    const result = await loadProjectIntegrations(intDir);
-    expect(result).toHaveLength(0);
-  });
-});

package/src/integrations/integration-loader.ts

@@ -1,68 +0,0 @@
-// runner/src/integrations/integration-loader.ts
-import { readdir, readFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-import yaml from 'js-yaml';
-import type { IntegrationPluginDef } from '@studio-foundation/contracts';
-
-const BUNDLED_INTEGRATION_TEMPLATES_DIR = resolve(
-  __dirname,
-  '../../templates/integrations'
-);
-
-/**
- * Return the raw YAML content of a bundled integration template by name.
- * Returns null if the integration does not exist in the bundled registry.
- */
-export async function getBundledIntegrationTemplate(name: string): Promise<string | null> {
-  const filePath = resolve(BUNDLED_INTEGRATION_TEMPLATES_DIR, `${name}.integration.yaml`);
-  try {
-    return await readFile(filePath, 'utf-8');
-  } catch {
-    return null;
-  }
-}
-
-/**
- * List all integration plugins available for installation from the bundled registry.
- * Returns an array of { name, description } objects.
- */
-export async function listAvailableIntegrationTemplates(): Promise<{ name: string; description: string }[]> {
-  let files: string[];
-  try {
-    files = (await readdir(BUNDLED_INTEGRATION_TEMPLATES_DIR))
-      .filter(f => f.endsWith('.integration.yaml'))
-      .sort();
-  } catch {
-    return [];
-  }
-  const result: { name: string; description: string }[] = [];
-  for (const file of files) {
-    const content = await readFile(resolve(BUNDLED_INTEGRATION_TEMPLATES_DIR, file), 'utf-8');
-    const def = yaml.load(content) as IntegrationPluginDef;
-    result.push({ name: file.replace('.integration.yaml', ''), description: def.description ?? '' });
-  }
-  return result;
-}
-
-/**
- * Load all `.integration.yaml` files from a project's integrations directory.
- * Returns an empty array if the directory does not exist.
- */
-export async function loadProjectIntegrations(integrationsDir: string): Promise<IntegrationPluginDef[]> {
-  if (!existsSync(integrationsDir)) return [];
-
-  let files: string[];
-  try {
-    files = (await readdir(integrationsDir)).filter(f => f.endsWith('.integration.yaml'));
-  } catch {
-    return [];
-  }
-
-  const result: IntegrationPluginDef[] = [];
-  for (const file of files.sort()) {
-    const content = await readFile(resolve(integrationsDir, file), 'utf-8');
-    result.push(yaml.load(content) as IntegrationPluginDef);
-  }
-  return result;
-}

package/src/middleware/anonymization.ts

@@ -1,38 +0,0 @@
-import { anonymize, deanonymize } from '@studio-foundation/anonymizer';
-import type { AnonymizerOptions } from '@studio-foundation/anonymizer';
-
-/**
- * Stateful middleware that anonymizes text before sending to LLM
- * and deanonymizes text after receiving from LLM.
- * Accumulates the keymap across calls for cross-call consistency.
- */
-export class AnonymizationMiddleware {
-  private keymap: Record<string, string> = {};
-  private options?: Omit<AnonymizerOptions, 'seedKeymap'>;
-
-  constructor(options?: Omit<AnonymizerOptions, 'seedKeymap'>) {
-    this.options = options;
-  }
-
-  /**
-   * Anonymize text. Accumulated keymap grows with each call.
-   * Same PII value always gets the same token (guaranteed by seedKeymap).
-   */
-  anonymize(text: string): string {
-    const result = anonymize(text, { ...this.options, seedKeymap: this.keymap });
-    // result.keymap is the full accumulated keymap (seed + new entries)
-    this.keymap = result.keymap;
-    return result.text;
-  }
-
-  /**
-   * Deanonymize text using accumulated keymap.
-   */
-  deanonymize(text: string): string {
-    return deanonymize(text, this.keymap);
-  }
-
-  getKeymap(): Record<string, string> {
-    return { ...this.keymap };
-  }
-}

package/src/plugins/index.ts

@@ -1,4 +0,0 @@
-export { loadPlugins } from './plugin-loader.js';
-export type { PluginManifest, MCPServerDef, SkillContent } from './plugin-loader.js';
-export { MCPClient } from './mcp-client.js';
-export { StudioOAuthProvider } from './oauth-provider.js';