@purista/harness 1.0.0

package/dist/testing/fixtures/mcp/fake-http-server.js

@@ -0,0 +1,95 @@
+import { randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import * as z from 'zod/v4';
+export async function startFakeHttpMcpServer(options = {}) {
+    const transports = new Map();
+    const server = createServer(async (req, res) => {
+        if (!headersMatch(req, options.requiredHeaders ?? {})) {
+            res.writeHead(401, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: 'unauthorized' }));
+            return;
+        }
+        if (req.url !== '/mcp') {
+            res.writeHead(404).end();
+            return;
+        }
+        if (req.method === 'GET') {
+            res.writeHead(405, { allow: 'POST' }).end('Method Not Allowed');
+            return;
+        }
+        if (req.method !== 'POST' && req.method !== 'DELETE') {
+            res.writeHead(405, { allow: 'POST, DELETE' }).end('Method Not Allowed');
+            return;
+        }
+        await handleMcpRequest(req, res, transports);
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    if (!address || typeof address === 'string')
+        throw new Error('Fake MCP server did not bind to a TCP port.');
+    return {
+        url: `http://127.0.0.1:${address.port}/mcp`,
+        close: async () => {
+            await Promise.allSettled([...transports.values()].map((transport) => transport.close()));
+            await closeServer(server);
+        }
+    };
+}
+async function handleMcpRequest(req, res, transports) {
+    const parsedBody = req.method === 'POST' ? await readJson(req) : undefined;
+    const sessionId = req.headers['mcp-session-id'];
+    let transport = typeof sessionId === 'string' ? transports.get(sessionId) : undefined;
+    if (!transport && parsedBody !== undefined && isInitializeRequest(parsedBody)) {
+        transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            enableJsonResponse: true,
+            onsessioninitialized: (id) => { if (transport)
+                transports.set(id, transport); }
+        });
+        await createFakeMcpServer().connect(transport);
+    }
+    if (!transport) {
+        res.writeHead(400, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: 'missing or invalid MCP session' }));
+        return;
+    }
+    await transport.handleRequest(req, res, parsedBody);
+}
+function createFakeMcpServer() {
+    const server = new McpServer({ name: 'purista-fake-http-mcp', version: '0.0.0' });
+    server.registerTool('echo', {
+        description: 'Echoes a message as structured content.',
+        inputSchema: {
+            message: z.string(),
+            delayMs: z.number().optional()
+        },
+        outputSchema: {
+            echo: z.string()
+        }
+    }, async ({ message, delayMs }) => {
+        if (delayMs)
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        const structuredContent = { echo: message };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(structuredContent) }],
+            structuredContent
+        };
+    });
+    return server;
+}
+async function readJson(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    const raw = Buffer.concat(chunks).toString('utf8');
+    return raw ? JSON.parse(raw) : undefined;
+}
+function headersMatch(req, required) {
+    return Object.entries(required).every(([name, value]) => req.headers[name.toLowerCase()] === value);
+}
+function closeServer(server) {
+    return new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,8 @@
+export { FakeModelProvider } from './fakeModelProvider.js';
+export { adapterCapabilitiesContract, fakeCapabilityAdapter, type FakeCapabilityAdapter } from './capabilities.js';
+export { createInMemoryFeedbackRecorder } from './feedback.js';
+export { sandboxContract } from './sandboxContract.js';
+export { fakeSnapshotSandbox, sandboxSnapshotContract } from './sandboxSnapshot.js';
+export { stateStoreContract } from './stateStoreContract.js';
+/** Returns a fresh harness builder for tests. */
+export declare function makeHarness(): import("../harness/defineHarness.js").HarnessBuilder<{}>;

package/dist/testing/index.js

@@ -0,0 +1,11 @@
+import { defineHarness } from '../harness/defineHarness.js';
+export { FakeModelProvider } from './fakeModelProvider.js';
+export { adapterCapabilitiesContract, fakeCapabilityAdapter } from './capabilities.js';
+export { createInMemoryFeedbackRecorder } from './feedback.js';
+export { sandboxContract } from './sandboxContract.js';
+export { fakeSnapshotSandbox, sandboxSnapshotContract } from './sandboxSnapshot.js';
+export { stateStoreContract } from './stateStoreContract.js';
+/** Returns a fresh harness builder for tests. */
+export function makeHarness() {
+    return defineHarness();
+}

package/dist/testing/sandboxContract.d.ts

@@ -0,0 +1,4 @@
+import type { Sandbox } from '../sandbox/index.js';
+export declare function sandboxContract(make: () => Sandbox | Promise<Sandbox>, opts: {
+    executor: 'available' | 'unavailable';
+}): void;

package/dist/testing/sandboxContract.js

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import { OperationCancelledError, OperationTimeoutError, SandboxNoExecutorError } from '../errors/index.js';
+export function sandboxContract(make, opts) {
+    describe(`sandboxContract (${opts.executor})`, () => {
+        it('open returns expected executor', async () => {
+            const sb = await make();
+            const session = await sb.open({ sessionId: 's1', runId: 'r1' });
+            expect(session.executor).toBe(opts.executor);
+        });
+        it('read/write/list/stat/exists/remove roundtrip', async () => {
+            const sb = await make();
+            const session = await sb.open({ sessionId: 's1', runId: 'r1' });
+            await session.write('/workspace/a.txt', 'hello');
+            expect(await session.readText('/workspace/a.txt')).toBe('hello');
+            expect(await session.exists('/workspace/a.txt')).toBe(true);
+            const list = await session.list('/workspace');
+            expect(list.some((e) => e.path === '/workspace/a.txt')).toBe(true);
+            const stat = await session.stat('/workspace/a.txt');
+            expect(stat.kind).toBe('file');
+            await session.remove('/workspace/a.txt');
+            expect(await session.exists('/workspace/a.txt')).toBe(false);
+        });
+        it('mount works', async () => {
+            const sb = await make();
+            const session = await sb.open({ sessionId: 's1', runId: 'r1' });
+            await session.mount(new Map([['SKILL.md', 'abc']]), '/skills/foo');
+            expect(await session.readText('/skills/foo/SKILL.md')).toBe('abc');
+        });
+        it('rejects relative paths', async () => {
+            const sb = await make();
+            const session = await sb.open({ sessionId: 's1', runId: 'r1' });
+            await expect(session.write('relative.txt', 'x')).rejects.toThrow();
+        });
+        it('exec availability semantics', async () => {
+            const sb = await make();
+            const session = await sb.open({ sessionId: 's1', runId: 'r1' });
+            if (opts.executor === 'unavailable') {
+                await expect(session.exec('echo hi')).rejects.toBeInstanceOf(SandboxNoExecutorError);
+            }
+            else {
+                const result = await session.exec('echo hi');
+                expect(result.stdout).toBe('hi\n');
+                expect(result.stderr).toBe('');
+                expect(result.exitCode).toBe(0);
+                expect(result.durationSeconds).toBeGreaterThanOrEqual(0);
+            }
+        });
+        if (opts.executor === 'available') {
+            it('exec honors stdin, env, and cwd options', async () => {
+                const sb = await make();
+                const session = await sb.open({ sessionId: 's1', runId: 'r1' });
+                const result = await session.exec('printf "$GREETING:"; printf "$PWD"; printf ":"; cat', {
+                    cwd: '/workspace',
+                    env: { GREETING: 'hello' },
+                    stdin: 'input'
+                });
+                expect(result.stdout).toBe('hello:/workspace:input');
+                expect(result.exitCode).toBe(0);
+            });
+            it('exec honors timeoutMs', async () => {
+                const sb = await make();
+                const session = await sb.open({ sessionId: 's1', runId: 'r1' });
+                await expect(session.exec('sleep 1', { timeoutMs: 10 })).rejects.toBeInstanceOf(OperationTimeoutError);
+            });
+            it('exec honors pre-aborted signals', async () => {
+                const sb = await make();
+                const session = await sb.open({ sessionId: 's1', runId: 'r1' });
+                const controller = new AbortController();
+                controller.abort();
+                await expect(session.exec('echo hi', { signal: controller.signal })).rejects.toBeInstanceOf(OperationCancelledError);
+            });
+        }
+    });
+}

package/dist/testing/sandboxSnapshot.d.ts

@@ -0,0 +1,7 @@
+import type { HibernateCapableSandbox, ResumeCapableSandbox, Sandbox, SnapshotCapableSandbox } from '../sandbox/index.js';
+type SnapshotSandbox = Sandbox<readonly ['sandbox.fs', 'sandbox.snapshot', 'sandbox.resume', 'sandbox.hibernate']> & SnapshotCapableSandbox & ResumeCapableSandbox & HibernateCapableSandbox;
+/** Deterministic in-memory sandbox fixture that implements snapshot/resume/hibernate. */
+export declare function fakeSnapshotSandbox(): SnapshotSandbox;
+/** Contract tests for adapters that opt into sandbox snapshot/resume support. */
+export declare function sandboxSnapshotContract(make: () => SnapshotSandbox | Promise<SnapshotSandbox>): void;
+export {};

package/dist/testing/sandboxSnapshot.js

@@ -0,0 +1,201 @@
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { SandboxError, SandboxNoExecutorError } from '../errors/index.js';
+function now() { return new Date().toISOString(); }
+function cloneNode(node) {
+    return node.kind === 'file'
+        ? { kind: 'file', data: new Uint8Array(node.data), modifiedAt: node.modifiedAt }
+        : { kind: 'directory', modifiedAt: node.modifiedAt };
+}
+function cloneFs(fs) {
+    return new Map([...fs.entries()].map(([key, node]) => [key, cloneNode(node)]));
+}
+function normalizePath(input) {
+    if (!input.startsWith('/'))
+        throw new SandboxError('Invalid path', { reason: 'invalid_path' });
+    const normalized = path.posix.normalize(input);
+    if (!normalized.startsWith('/'))
+        throw new SandboxError('Invalid path', { reason: 'invalid_path' });
+    return normalized;
+}
+class FakeSnapshotSandboxSession {
+    sessionId;
+    runId;
+    executor = 'unavailable';
+    closed = false;
+    fs;
+    constructor(sessionId, runId, fs) {
+        this.sessionId = sessionId;
+        this.runId = runId;
+        this.fs = fs ? cloneFs(fs) : new Map([['/', { kind: 'directory', modifiedAt: now() }]]);
+    }
+    snapshotFs() {
+        this.assertOpen();
+        return cloneFs(this.fs);
+    }
+    assertOpen() {
+        if (this.closed)
+            throw new SandboxError('Sandbox session is closed.', { reason: 'session_closed' });
+    }
+    ensureParent(filePath) {
+        const parts = normalizePath(filePath).split('/').filter(Boolean);
+        let current = '/';
+        for (let i = 0; i < parts.length - 1; i += 1) {
+            current = current === '/' ? `/${parts[i]}` : `${current}/${parts[i]}`;
+            if (!this.fs.has(current))
+                this.fs.set(current, { kind: 'directory', modifiedAt: now() });
+        }
+    }
+    async read(filePath) {
+        this.assertOpen();
+        const node = this.fs.get(normalizePath(filePath));
+        if (!node || node.kind !== 'file')
+            throw new SandboxError('File not found', { reason: 'fs_failed' });
+        return new Uint8Array(node.data);
+    }
+    async readText(filePath) {
+        return new TextDecoder().decode(await this.read(filePath));
+    }
+    async write(filePath, data) {
+        this.assertOpen();
+        const p = normalizePath(filePath);
+        this.ensureParent(p);
+        const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : new Uint8Array(data);
+        this.fs.set(p, { kind: 'file', data: bytes, modifiedAt: now() });
+    }
+    async remove(filePath, opts) {
+        this.assertOpen();
+        const p = normalizePath(filePath);
+        if (opts?.recursive) {
+            for (const key of [...this.fs.keys()]) {
+                if (key === p || key.startsWith(`${p}/`))
+                    this.fs.delete(key);
+            }
+            return;
+        }
+        this.fs.delete(p);
+    }
+    async list(rootPath, opts) {
+        this.assertOpen();
+        const root = normalizePath(rootPath);
+        const out = [];
+        for (const [entryPath, node] of this.fs.entries()) {
+            if (entryPath === root)
+                continue;
+            if (!entryPath.startsWith(root === '/' ? '/' : `${root}/`))
+                continue;
+            const relative = root === '/' ? entryPath.slice(1) : entryPath.slice(root.length + 1);
+            if (!opts?.recursive && relative.includes('/'))
+                continue;
+            if (opts?.glob && !new RegExp(opts.glob.replaceAll('.', '\\.').replaceAll('*', '.*')).test(entryPath))
+                continue;
+            out.push({
+                name: entryPath.split('/').at(-1) ?? '',
+                path: entryPath,
+                kind: node.kind,
+                ...(node.kind === 'file' ? { size: node.data.byteLength } : {})
+            });
+        }
+        return out.sort((a, b) => a.path.localeCompare(b.path));
+    }
+    async stat(filePath) {
+        this.assertOpen();
+        const node = this.fs.get(normalizePath(filePath));
+        if (!node)
+            throw new SandboxError('Path not found', { reason: 'fs_failed' });
+        return { kind: node.kind, size: node.kind === 'file' ? node.data.byteLength : 0, modifiedAt: node.modifiedAt };
+    }
+    async exists(filePath) {
+        this.assertOpen();
+        return this.fs.has(normalizePath(filePath));
+    }
+    async mount(files, atPath) {
+        this.assertOpen();
+        const base = normalizePath(atPath);
+        for (const [rel, data] of files.entries()) {
+            const relNorm = rel.startsWith('/') ? rel.slice(1) : rel;
+            await this.write(`${base}/${relNorm}`, data);
+        }
+    }
+    async exec() {
+        this.assertOpen();
+        throw new SandboxNoExecutorError('Sandbox executor unavailable.', { session_id: this.sessionId });
+    }
+    async close() {
+        this.closed = true;
+    }
+}
+/** Deterministic in-memory sandbox fixture that implements snapshot/resume/hibernate. */
+export function fakeSnapshotSandbox() {
+    let nextSnapshot = 1;
+    const snapshots = new Map();
+    function assertFakeSession(session) {
+        if (!(session instanceof FakeSnapshotSandboxSession)) {
+            throw new SandboxError('Snapshot helper received an unknown session implementation.', { reason: 'invalid_session' });
+        }
+        return session;
+    }
+    return {
+        capabilities: ['sandbox.fs', 'sandbox.snapshot', 'sandbox.resume', 'sandbox.hibernate'],
+        async open(opts) {
+            return new FakeSnapshotSandboxSession(opts.sessionId, opts.runId);
+        },
+        async snapshot(session) {
+            const fakeSession = assertFakeSession(session);
+            const snapshotId = `snapshot_${nextSnapshot}`;
+            nextSnapshot += 1;
+            const metadata = { sessionId: fakeSession.sessionId, runId: fakeSession.runId };
+            snapshots.set(snapshotId, { fs: fakeSession.snapshotFs(), metadata });
+            return { snapshotId, metadata };
+        },
+        async resume(opts) {
+            const snapshot = snapshots.get(opts.snapshotId);
+            if (!snapshot) {
+                throw new SandboxError('Snapshot not found.', { reason: 'unknown_snapshot' });
+            }
+            return new FakeSnapshotSandboxSession(opts.sessionId, opts.runId, snapshot.fs);
+        },
+        async hibernate(session) {
+            const snapshot = await this.snapshot(session);
+            await session.close();
+            return snapshot;
+        }
+    };
+}
+/** Contract tests for adapters that opt into sandbox snapshot/resume support. */
+export function sandboxSnapshotContract(make) {
+    describe('sandboxSnapshotContract', () => {
+        it('creates snapshot ids', async () => {
+            const sandbox = await make();
+            const session = await sandbox.open({ sessionId: 'contract-s1', runId: 'contract-r1' });
+            await session.write('/workspace/a.txt', 'hello');
+            const snapshot = await sandbox.snapshot(session);
+            expect(snapshot.snapshotId).toEqual(expect.any(String));
+            expect(snapshot.snapshotId.length).toBeGreaterThan(0);
+        });
+        it('resumes a usable session from a snapshot', async () => {
+            const sandbox = await make();
+            const session = await sandbox.open({ sessionId: 'contract-s1', runId: 'contract-r1' });
+            await session.write('/workspace/a.txt', 'hello');
+            const snapshot = await sandbox.snapshot(session);
+            const resumed = await sandbox.resume({ snapshotId: snapshot.snapshotId, sessionId: 'contract-s2', runId: 'contract-r2' });
+            expect(await resumed.readText('/workspace/a.txt')).toBe('hello');
+            await resumed.write('/workspace/b.txt', 'world');
+            expect(await resumed.readText('/workspace/b.txt')).toBe('world');
+        });
+        it('throws SandboxError for unknown snapshots', async () => {
+            const sandbox = await make();
+            await expect(sandbox.resume({ snapshotId: 'snapshot_missing', sessionId: 'contract-s1', runId: 'contract-r1' }))
+                .rejects.toBeInstanceOf(SandboxError);
+        });
+        it('hibernates by snapshotting and closing the active session', async () => {
+            const sandbox = await make();
+            const session = await sandbox.open({ sessionId: 'contract-s1', runId: 'contract-r1' });
+            await session.write('/workspace/a.txt', 'hello');
+            const snapshot = await sandbox.hibernate(session);
+            await expect(session.readText('/workspace/a.txt')).rejects.toBeInstanceOf(SandboxError);
+            const resumed = await sandbox.resume({ snapshotId: snapshot.snapshotId, sessionId: 'contract-s2', runId: 'contract-r2' });
+            expect(await resumed.readText('/workspace/a.txt')).toBe('hello');
+        });
+    });
+}

package/dist/testing/stateStoreContract.d.ts

@@ -0,0 +1,2 @@
+import type { StateStore } from '../ports/state.js';
+export declare function stateStoreContract(make: () => StateStore | Promise<StateStore>): void;

package/dist/testing/stateStoreContract.js

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+import { StateError } from '../errors/index.js';
+const session = {
+    id: 'session_1',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    runCount: 0
+};
+const messages = [
+    { id: '01A', sessionId: session.id, role: 'user', content: 'a', timestamp: '2026-01-01T00:00:00.000Z' },
+    { id: '01B', sessionId: session.id, role: 'assistant', content: 'b', timestamp: '2026-01-01T00:00:01.000Z' },
+    { id: '01C', sessionId: session.id, role: 'assistant', content: 'c', timestamp: '2026-01-01T00:00:02.000Z' }
+];
+const [m1, m2, m3] = messages;
+const run = {
+    id: 'run_1',
+    sessionId: session.id,
+    kind: 'workflow',
+    target: 'wf',
+    startedAt: '2026-01-01T00:00:00.000Z',
+    status: 'running'
+};
+const event = {
+    id: '01EVT',
+    runId: run.id,
+    at: '2026-01-01T00:00:00.000Z',
+    type: 'run.started',
+    payload: { ok: true }
+};
+export function stateStoreContract(make) {
+    describe('stateStoreContract', () => {
+        it('getSession returns undefined for unknown id', async () => {
+            const store = await make();
+            await expect(store.getSession('missing')).resolves.toBeUndefined();
+        });
+        it('upsertSession and getSession round-trip', async () => {
+            const store = await make();
+            await store.upsertSession(session);
+            await expect(store.getSession(session.id)).resolves.toEqual(session);
+        });
+        it('appendMessages preserves order across calls', async () => {
+            const store = await make();
+            await store.appendMessages(session.id, [m1]);
+            await store.appendMessages(session.id, [m2, m3]);
+            await expect(store.listMessages(session.id)).resolves.toEqual(messages);
+        });
+        it('listMessages honors limit and before cursor', async () => {
+            const store = await make();
+            await store.appendMessages(session.id, messages);
+            await expect(store.listMessages(session.id, { limit: 2 })).resolves.toEqual([m2, m3]);
+            await expect(store.listMessages(session.id, { before: '01C' })).resolves.toEqual([m1, m2]);
+        });
+        it('clearMessages removes all messages', async () => {
+            const store = await make();
+            await store.appendMessages(session.id, messages);
+            await store.clearMessages(session.id);
+            await expect(store.listMessages(session.id)).resolves.toEqual([]);
+        });
+        it('createRun and getRun round-trip', async () => {
+            const store = await make();
+            await store.createRun(run);
+            await expect(store.getRun(run.id)).resolves.toEqual(run);
+        });
+        it('finishRun updates patch fields only', async () => {
+            const store = await make();
+            await store.createRun(run);
+            await store.finishRun(run.id, {
+                status: 'succeeded',
+                finishedAt: '2026-01-01T00:00:03.000Z',
+                output: { ok: true }
+            });
+            await expect(store.getRun(run.id)).resolves.toMatchObject({
+                id: run.id,
+                status: 'succeeded',
+                finishedAt: '2026-01-01T00:00:03.000Z',
+                output: { ok: true }
+            });
+        });
+        it('listRuns sorted descending by startedAt then id', async () => {
+            const store = await make();
+            await store.createRun(run);
+            await store.createRun({ ...run, id: 'run_2', startedAt: '2026-01-01T00:00:05.000Z' });
+            await store.createRun({ ...run, id: 'run_3', startedAt: '2026-01-01T00:00:05.000Z' });
+            await expect(store.listRuns(session.id)).resolves.toEqual([
+                expect.objectContaining({ id: 'run_3' }),
+                expect.objectContaining({ id: 'run_2' }),
+                expect.objectContaining({ id: 'run_1' })
+            ]);
+        });
+        it('appendEvents and listEvents round-trip with after cursor', async () => {
+            const store = await make();
+            await store.appendEvents(run.id, [event, { ...event, id: '01EVT2', payload: { ok: 2 } }]);
+            await expect(store.listEvents(run.id)).resolves.toHaveLength(2);
+            await expect(store.listEvents(run.id, { after: '01EVT' })).resolves.toEqual([
+                expect.objectContaining({ id: '01EVT2' })
+            ]);
+        });
+        it('duplicate message id throws StateError', async () => {
+            const store = await make();
+            await store.appendMessages(session.id, [m1]);
+            await expect(store.appendMessages(session.id, [m1])).rejects.toBeInstanceOf(StateError);
+        });
+        it('duplicate message ids in the same append batch throw StateError', async () => {
+            const store = await make();
+            await expect(store.appendMessages(session.id, [m1, { ...m1 }])).rejects.toBeInstanceOf(StateError);
+            await expect(store.listMessages(session.id)).resolves.toEqual([]);
+        });
+    });
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,9 @@
+import type { JsonValue } from '../models/json.js';
+import type { Message } from '../models/state.js';
+import type { BuiltinToolName } from '../harness/defineHarness.js';
+import type { ModelToolSpec } from '../ports/model-provider.js';
+import type { SandboxSession } from '../sandbox/index.js';
+export declare const BUILTIN_ALIAS_TO_CANONICAL: Record<string, BuiltinToolName>;
+export declare function getBuiltinToolSpecs(enabled: readonly BuiltinToolName[], session: SandboxSession): ModelToolSpec[];
+export declare function invokeBuiltinTool(nameOrAlias: string, input: unknown, session: SandboxSession, signal?: AbortSignal): Promise<JsonValue>;
+export declare function toToolErrorMessage(toolCallId: string, error: unknown): Message;

package/dist/tools/index.js

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+import { SandboxNoExecutorError, ToolNotFoundError, ValidationError, serializeError } from '../errors/index.js';
+export const BUILTIN_ALIAS_TO_CANONICAL = {
+    bash: 'bash', Bash: 'bash',
+    read: 'read', Read: 'read',
+    write: 'write', Write: 'write',
+    edit: 'edit', Edit: 'edit',
+    glob: 'glob', Glob: 'glob',
+    grep: 'grep', Grep: 'grep',
+    list: 'list', List: 'list', LS: 'list'
+};
+const schemas = {
+    bash: { input: z.object({ command: z.string().min(1), cwd: z.string().optional(), timeoutMs: z.number().int().positive().optional() }), output: z.object({ stdout: z.string(), stderr: z.string(), exitCode: z.number().int() }), description: 'Run a shell command in the sandbox. Returns stdout, stderr, exitCode.' },
+    read: { input: z.object({ path: z.string().min(1), encoding: z.literal('utf-8').default('utf-8') }), output: z.object({ content: z.string() }), description: 'Read a text file from the sandbox.' },
+    write: { input: z.object({ path: z.string().min(1), content: z.string() }), output: z.object({ bytesWritten: z.number().int().nonnegative() }), description: 'Write or overwrite a text file in the sandbox.' },
+    edit: { input: z.object({ path: z.string().min(1), old_string: z.string().min(1), new_string: z.string() }), output: z.object({ replaced: z.literal(1) }), description: 'Replace exactly one occurrence of old_string with new_string in the given file.' },
+    glob: { input: z.object({ pattern: z.string().min(1), root: z.string().default('/') }), output: z.object({ paths: z.array(z.string()) }), description: 'List files matching a glob pattern under root (recursive).' },
+    grep: { input: z.object({ pattern: z.string().min(1), path: z.string().default('/'), maxResults: z.number().int().positive().default(100) }), output: z.object({ matches: z.array(z.object({ path: z.string(), line: z.number().int(), text: z.string() })) }), description: 'Search file contents for a regex pattern. Returns matching lines with paths and line numbers.' },
+    list: { input: z.object({ path: z.string().min(1) }), output: z.object({ entries: z.array(z.object({ name: z.string(), kind: z.enum(['file', 'directory']), size: z.number().int().optional() })) }), description: 'List directory entries (non-recursive).' }
+};
+export function getBuiltinToolSpecs(enabled, session) {
+    return enabled.filter((name) => !(name === 'bash' && session.executor === 'unavailable')).map((name) => ({
+        name,
+        description: schemas[name].description,
+        parameters: z.toJSONSchema(schemas[name].input)
+    }));
+}
+export async function invokeBuiltinTool(nameOrAlias, input, session, signal) {
+    const canonical = BUILTIN_ALIAS_TO_CANONICAL[nameOrAlias];
+    if (!canonical)
+        throw new ToolNotFoundError('Built-in tool was not found.', { tool_id: nameOrAlias, where: 'model_response' });
+    const name = canonical;
+    try {
+        switch (name) {
+            case 'bash': {
+                if (session.executor === 'unavailable')
+                    throw new SandboxNoExecutorError('Sandbox executor unavailable.', { session_id: 'unknown' });
+                const parsed = schemas.bash.input.parse(input);
+                const res = await session.exec(parsed.command, {
+                    ...(parsed.cwd !== undefined ? { cwd: parsed.cwd } : {}),
+                    ...(parsed.timeoutMs !== undefined ? { timeoutMs: parsed.timeoutMs } : {}),
+                    ...(signal ? { signal } : {})
+                });
+                return schemas.bash.output.parse({ stdout: res.stdout, stderr: res.stderr, exitCode: res.exitCode });
+            }
+            case 'read': {
+                const parsed = schemas.read.input.parse(input);
+                return schemas.read.output.parse({ content: await session.readText(parsed.path, parsed.encoding) });
+            }
+            case 'write': {
+                const parsed = schemas.write.input.parse(input);
+                await session.write(parsed.path, parsed.content);
+                return schemas.write.output.parse({ bytesWritten: new TextEncoder().encode(parsed.content).byteLength });
+            }
+            case 'edit': {
+                const parsed = schemas.edit.input.parse(input);
+                const content = await session.readText(parsed.path);
+                const count = content.split(parsed.old_string).length - 1;
+                if (count !== 1)
+                    throw new ValidationError('edit requires exactly one match', { where: 'tool_input', issues: { path: parsed.path, matches: count } });
+                await session.write(parsed.path, content.replace(parsed.old_string, parsed.new_string));
+                return { replaced: 1 };
+            }
+            case 'glob': {
+                const parsed = schemas.glob.input.parse(input);
+                const files = await session.list(parsed.root, { recursive: true, glob: parsed.pattern });
+                return schemas.glob.output.parse({ paths: files.map((f) => f.path) });
+            }
+            case 'grep': {
+                const parsed = schemas.grep.input.parse(input);
+                let rx;
+                try {
+                    rx = new RegExp(parsed.pattern);
+                }
+                catch (error) {
+                    throw new ValidationError('grep pattern must be a valid regular expression', {
+                        where: 'tool_input',
+                        issues: [{ path: 'pattern', message: error instanceof Error ? error.message : 'Invalid regular expression' }]
+                    });
+                }
+                const entries = await session.list(parsed.path, { recursive: true });
+                const matches = [];
+                for (const entry of entries) {
+                    if (entry.kind !== 'file')
+                        continue;
+                    const lines = (await session.readText(entry.path)).split('\n');
+                    for (let i = 0; i < lines.length; i += 1) {
+                        const currentLine = lines[i];
+                        if (currentLine !== undefined && rx.test(currentLine))
+                            matches.push({ path: entry.path, line: i + 1, text: currentLine });
+                        if (matches.length >= parsed.maxResults)
+                            return schemas.grep.output.parse({ matches });
+                    }
+                }
+                return schemas.grep.output.parse({ matches });
+            }
+            case 'list': {
+                const parsed = schemas.list.input.parse(input);
+                const entries = await session.list(parsed.path);
+                return schemas.list.output.parse({
+                    entries: entries.map((entry) => ({ name: entry.name, kind: entry.kind, ...(entry.size !== undefined ? { size: entry.size } : {}) }))
+                });
+            }
+            default:
+                throw new ToolNotFoundError('Built-in tool was not found.', { tool_id: name, where: 'registry' });
+        }
+    }
+    catch (error) {
+        if (error instanceof z.ZodError)
+            throw new ValidationError('Tool input validation failed', { where: 'tool_input', issues: JSON.parse(JSON.stringify(error.issues)) });
+        throw error;
+    }
+}
+export function toToolErrorMessage(toolCallId, error) {
+    return {
+        id: `msg_${Date.now()}`,
+        sessionId: '',
+        role: 'tool',
+        content: '',
+        toolResults: [{ toolCallId, error: serializeError(error) }],
+        timestamp: new Date().toISOString()
+    };
+}

package/dist/tools/mcp/http.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedMcpHttpTool, McpTransportRunner } from './runner.js';
+export declare function createHttpMcpTransportRunner(config: ResolvedMcpHttpTool): McpTransportRunner;