@studio-foundation/runner 0.3.0-beta.1

package/dist/utils/race-signal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"race-signal.js","sourceRoot":"","sources":["../../src/utils/race-signal.ts"],"names":[],"mappings":";;AAIA,gCAYC;AAhBD;;;GAGG;AACH,SAAgB,UAAU,CAAI,OAAmB,EAAE,MAAoB;IACrE,IAAI,CAAC,MAAM;QAAE,OAAO,OAAO,CAAC;IAC5B,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;IAErF,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;QACxE,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAE1D,OAAO;aACJ,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aAC1E,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChF,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/race-signal.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=race-signal.test.d.ts.map

package/dist/utils/race-signal.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"race-signal.test.d.ts","sourceRoot":"","sources":["../../src/utils/race-signal.test.ts"],"names":[],"mappings":""}

package/dist/utils/race-signal.test.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const race_signal_js_1 = require("./race-signal.js");
+(0, vitest_1.describe)('raceSignal', () => {
+    (0, vitest_1.it)('resolves normally when no signal provided', async () => {
+        const result = await (0, race_signal_js_1.raceSignal)(Promise.resolve(42));
+        (0, vitest_1.expect)(result).toBe(42);
+    });
+    (0, vitest_1.it)('resolves normally when signal is not aborted', async () => {
+        const controller = new AbortController();
+        const result = await (0, race_signal_js_1.raceSignal)(Promise.resolve('hello'), controller.signal);
+        (0, vitest_1.expect)(result).toBe('hello');
+    });
+    (0, vitest_1.it)('rejects immediately if signal is already aborted', async () => {
+        const controller = new AbortController();
+        controller.abort();
+        await (0, vitest_1.expect)((0, race_signal_js_1.raceSignal)(new Promise(() => { }), controller.signal))
+            .rejects.toThrow('Aborted');
+    });
+    (0, vitest_1.it)('rejects when signal fires after creation', async () => {
+        const controller = new AbortController();
+        // A promise that never resolves on its own
+        const hanging = new Promise(() => { });
+        const raced = (0, race_signal_js_1.raceSignal)(hanging, controller.signal);
+        controller.abort();
+        await (0, vitest_1.expect)(raced).rejects.toThrow('Aborted');
+    });
+    (0, vitest_1.it)('resolves if promise resolves before signal fires', async () => {
+        const controller = new AbortController();
+        const result = await (0, race_signal_js_1.raceSignal)(Promise.resolve(99), controller.signal);
+        // Abort after the fact — should not cause rejection
+        controller.abort();
+        (0, vitest_1.expect)(result).toBe(99);
+    });
+    (0, vitest_1.it)('thrown error name is AbortError', async () => {
+        const controller = new AbortController();
+        controller.abort();
+        try {
+            await (0, race_signal_js_1.raceSignal)(new Promise(() => { }), controller.signal);
+        }
+        catch (e) {
+            (0, vitest_1.expect)(e).toBeInstanceOf(DOMException);
+            (0, vitest_1.expect)(e.name).toBe('AbortError');
+        }
+    });
+});
+//# sourceMappingURL=race-signal.test.js.map

package/dist/utils/race-signal.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"race-signal.test.js","sourceRoot":"","sources":["../../src/utils/race-signal.test.ts"],"names":[],"mappings":";;AAAA,mCAA8C;AAC9C,qDAA8C;AAE9C,IAAA,iBAAQ,EAAC,YAAY,EAAE,GAAG,EAAE;IAC1B,IAAA,WAAE,EAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;QACzD,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAU,EAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;QACrD,IAAA,eAAM,EAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,8CAA8C,EAAE,KAAK,IAAI,EAAE;QAC5D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAU,EAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;QAC7E,IAAA,eAAM,EAAC,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,kDAAkD,EAAE,KAAK,IAAI,EAAE;QAChE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,UAAU,CAAC,KAAK,EAAE,CAAC;QACnB,MAAM,IAAA,eAAM,EAAC,IAAA,2BAAU,EAAC,IAAI,OAAO,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;aAC/D,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;QACxD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,2CAA2C;QAC3C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAQ,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC7C,MAAM,KAAK,GAAG,IAAA,2BAAU,EAAC,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;QACrD,UAAU,CAAC,KAAK,EAAE,CAAC;QACnB,MAAM,IAAA,eAAM,EAAC,KAAK,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,kDAAkD,EAAE,KAAK,IAAI,EAAE;QAChE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAU,EAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;QACxE,oDAAoD;QACpD,UAAU,CAAC,KAAK,EAAE,CAAC;QACnB,IAAA,eAAM,EAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,iCAAiC,EAAE,KAAK,IAAI,EAAE;QAC/C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,UAAU,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,IAAA,2BAAU,EAAC,IAAI,OAAO,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;QAC7D,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAA,eAAM,EAAC,CAAC,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;YACvC,IAAA,eAAM,EAAE,CAAkB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACtD,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@studio-foundation/runner",
+  "version": "0.3.0-beta.1",
+  "description": "Multi-provider LLM agent runner with tool execution",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "llm",
+    "agent",
+    "tools",
+    "openai",
+    "anthropic"
+  ],
+  "author": "Ariane Guay",
+  "license": "AGPL-3.0-only",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.33.1",
+    "@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"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.2.3",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}

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

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

@@ -0,0 +1,68 @@
+/**
+ * @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

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

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

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

@@ -0,0 +1,4 @@
+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';