@purista/harness 1.2.5 → 1.5.0

package/dist/testing/loggerContract.js

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+const LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
+const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+function capturedRecords(logger) {
+    const records = logger.records;
+    return Array.isArray(records) ? records : undefined;
+}
+/**
+ * Shared contract for `Logger` implementations.
+ *
+ * Record-shape assertions require a capturing logger that exposes its emitted
+ * records via a `records` array (e.g. `FakeLogger`); non-capturing loggers are
+ * verified for the behavioral contract only.
+ */
+export function loggerContract(make) {
+    describe('loggerContract', () => {
+        it('exposes every level method and none of them throw', () => {
+            const logger = make();
+            for (const level of LEVELS) {
+                expect(typeof logger[level]).toBe('function');
+                expect(() => logger[level](`${level} message`, { level })).not.toThrow();
+            }
+        });
+        it('child(bindings) returns a logger with the full level surface', () => {
+            const logger = make();
+            const child = logger.child({ component: 'contract' });
+            for (const level of LEVELS) {
+                expect(typeof child[level]).toBe('function');
+            }
+            expect(() => child.info('child message')).not.toThrow();
+        });
+        it('emits one record per level with an RFC3339 time when records are capturable', () => {
+            const logger = make();
+            const records = capturedRecords(logger);
+            if (!records)
+                return;
+            records.length = 0;
+            for (const level of LEVELS) {
+                logger[level](`${level} message`);
+            }
+            expect(records).toHaveLength(LEVELS.length);
+            for (const [index, level] of LEVELS.entries()) {
+                expect(records[index]?.level).toBe(level);
+                expect(records[index]?.msg).toBe(`${level} message`);
+                expect(String(records[index]?.time)).toMatch(RFC3339);
+            }
+        });
+        it('child bindings merge with and shadow parent bindings when records are capturable', () => {
+            const logger = make();
+            const records = capturedRecords(logger);
+            if (!records)
+                return;
+            const parent = logger.child({ scope: 'parent', keep: true });
+            const child = parent.child({ scope: 'child' });
+            const childRecords = capturedRecords(child) ?? records;
+            childRecords.length = 0;
+            child.info('bound message');
+            expect(childRecords).toHaveLength(1);
+            expect(childRecords[0]?.bindings).toMatchObject({ scope: 'child', keep: true });
+        });
+    });
+}

package/dist/testing/modelProviderContract.d.ts

@@ -0,0 +1,12 @@
+import type { ModelCapability, ModelProvider } from '../ports/model-provider.js';
+/**
+ * Shared provider contract for `ModelProvider` implementations.
+ *
+ * `make()` must return a provider wired to an offline (fake/mock) client whose
+ * scripted responses satisfy the requested capabilities: text content for
+ * `text`/`text_stream` and a JSON object matching `{ ok: boolean }` for
+ * `object`/`object_stream`.
+ */
+export declare function modelProviderContract(make: () => ModelProvider, opts: {
+    capabilities: ModelCapability[];
+}): void;

package/dist/testing/modelProviderContract.js

@@ -0,0 +1,222 @@
+import { describe, expect, it } from 'vitest';
+import { OperationCancelledError } from '../errors/index.js';
+const FINISH_REASONS = [
+    'stop',
+    'length',
+    'context_limit',
+    'tool_calls',
+    'content_filter',
+    'refusal',
+    'pause',
+    'malformed',
+    'cancelled',
+    'error'
+];
+const METHOD_BY_CAPABILITY = {
+    text: 'text',
+    text_stream: 'textStream',
+    object: 'object',
+    object_stream: 'objectStream',
+    embeddings: 'embed',
+    rerank: 'rerank'
+};
+const CONTRACT_SCHEMA = {
+    type: 'object',
+    required: ['ok'],
+    properties: { ok: { type: 'boolean' } }
+};
+function signal() {
+    return new AbortController().signal;
+}
+function abortedSignal() {
+    const controller = new AbortController();
+    controller.abort();
+    return controller.signal;
+}
+/**
+ * Pre-aborted signals must reject. `BaseModelProvider` currently rethrows the
+ * raw abort reason at the entry point (before error normalization), so both
+ * the normalized `OperationCancelledError` and a raw `AbortError` satisfy the
+ * contract; mid-flight aborts always normalize to `OperationCancelledError`.
+ */
+function expectAbortRejection(error) {
+    return error instanceof OperationCancelledError || (error instanceof Error && error.name === 'AbortError');
+}
+function expectUsage(usage) {
+    expect(usage.inputTokens).toBeGreaterThanOrEqual(0);
+    expect(usage.outputTokens).toBeGreaterThanOrEqual(0);
+    expect(usage.totalTokens).toBeGreaterThanOrEqual(0);
+}
+function expectOutcome(outcome, finishReason) {
+    if (!outcome)
+        return;
+    expect(outcome.finishReason).toBe(finishReason);
+    if (outcome.providerFinishReason !== undefined) {
+        expect(typeof outcome.providerFinishReason).toBe('string');
+    }
+    if (outcome.retryKind !== undefined) {
+        expect(['none', 'active', 'deferred']).toContain(outcome.retryKind);
+    }
+}
+/**
+ * Shared provider contract for `ModelProvider` implementations.
+ *
+ * `make()` must return a provider wired to an offline (fake/mock) client whose
+ * scripted responses satisfy the requested capabilities: text content for
+ * `text`/`text_stream` and a JSON object matching `{ ok: boolean }` for
+ * `object`/`object_stream`.
+ */
+export function modelProviderContract(make, opts) {
+    const operations = opts.capabilities.filter((capability) => capability in METHOD_BY_CAPABILITY);
+    const has = (capability) => operations.includes(capability);
+    describe('modelProviderContract', () => {
+        it('reports stable provider identifiers', () => {
+            const provider = make();
+            expect(typeof provider.id).toBe('string');
+            expect(provider.id.length).toBeGreaterThan(0);
+            expect(typeof provider.genAiSystem).toBe('string');
+            expect(provider.genAiSystem.length).toBeGreaterThan(0);
+        });
+        it('implements a method for each claimed operation capability', () => {
+            const provider = make();
+            for (const capability of operations) {
+                expect(typeof provider[METHOD_BY_CAPABILITY[capability]]).toBe('function');
+            }
+        });
+        if (has('text')) {
+            it('text returns normalized content, usage, finish reason, and outcome shape', async () => {
+                const provider = make();
+                const response = await provider.text({
+                    model: 'contract-model',
+                    messages: [{ role: 'user', content: 'contract' }],
+                    signal: signal()
+                });
+                expect(typeof response.content).toBe('string');
+                expectUsage(response.usage);
+                expect(FINISH_REASONS).toContain(response.finishReason);
+                expectOutcome(response.outcome, response.finishReason);
+            });
+            it('text rejects an already-aborted signal with a cancellation error', async () => {
+                const provider = make();
+                await expect(provider.text({
+                    model: 'contract-model',
+                    messages: [{ role: 'user', content: 'contract' }],
+                    signal: abortedSignal()
+                })).rejects.toSatisfy(expectAbortRejection);
+            });
+        }
+        if (has('text_stream')) {
+            it('textStream yields valid chunk kinds and exactly one trailing finish', async () => {
+                const provider = make();
+                const chunks = [];
+                for await (const chunk of provider.textStream({
+                    model: 'contract-model',
+                    messages: [{ role: 'user', content: 'contract' }],
+                    signal: signal()
+                })) {
+                    chunks.push(chunk);
+                }
+                expect(chunks.length).toBeGreaterThan(0);
+                for (const chunk of chunks) {
+                    expect(['delta', 'tool_call', 'finish']).toContain(chunk.kind);
+                }
+                const finishes = chunks.filter((chunk) => chunk.kind === 'finish');
+                expect(finishes).toHaveLength(1);
+                const finish = chunks.at(-1);
+                expect(finish?.kind).toBe('finish');
+                if (finish?.kind === 'finish') {
+                    expectUsage(finish.usage);
+                    expect(FINISH_REASONS).toContain(finish.finishReason);
+                    expectOutcome(finish.outcome, finish.finishReason);
+                }
+            });
+        }
+        if (has('object')) {
+            it('object returns the structured object with normalized usage and outcome shape', async () => {
+                const provider = make();
+                const response = await provider.object({
+                    model: 'contract-model',
+                    messages: [{ role: 'user', content: 'contract' }],
+                    schema: CONTRACT_SCHEMA,
+                    signal: signal()
+                });
+                expect(response.object).not.toBeUndefined();
+                expectUsage(response.usage);
+                expect(FINISH_REASONS).toContain(response.finishReason);
+                expectOutcome(response.outcome, response.finishReason);
+            });
+            it('object rejects an already-aborted signal with a cancellation error', async () => {
+                const provider = make();
+                await expect(provider.object({
+                    model: 'contract-model',
+                    messages: [{ role: 'user', content: 'contract' }],
+                    schema: CONTRACT_SCHEMA,
+                    signal: abortedSignal()
+                })).rejects.toSatisfy(expectAbortRejection);
+            });
+        }
+        if (has('object_stream')) {
+            it('objectStream yields valid chunk kinds and a final object', async () => {
+                const provider = make();
+                const chunks = [];
+                for await (const chunk of provider.objectStream({
+                    model: 'contract-model',
+                    messages: [{ role: 'user', content: 'contract' }],
+                    schema: CONTRACT_SCHEMA,
+                    signal: signal()
+                })) {
+                    chunks.push(chunk);
+                }
+                expect(chunks.length).toBeGreaterThan(0);
+                for (const chunk of chunks) {
+                    expect(['partial', 'delta', 'tool_call', 'finish']).toContain(chunk.kind);
+                }
+                const finish = chunks.at(-1);
+                expect(finish?.kind).toBe('finish');
+                if (finish?.kind === 'finish') {
+                    expect(finish.object).not.toBeUndefined();
+                    expectUsage(finish.usage);
+                    expect(FINISH_REASONS).toContain(finish.finishReason);
+                    expectOutcome(finish.outcome, finish.finishReason);
+                }
+            });
+        }
+        if (has('embeddings')) {
+            it('embed returns one embedding per input', async () => {
+                const provider = make();
+                const response = await provider.embed({
+                    model: 'contract-model',
+                    input: ['alpha', 'beta'],
+                    signal: signal()
+                });
+                expect(response.embeddings).toHaveLength(2);
+                for (const [index, embedding] of response.embeddings.entries()) {
+                    expect(embedding.index).toBe(index);
+                    expect(embedding.vector.length).toBeGreaterThan(0);
+                }
+                expectUsage(response.usage);
+            });
+        }
+        if (has('rerank')) {
+            it('rerank returns scores referencing submitted documents, sorted descending', async () => {
+                const provider = make();
+                const documents = [
+                    { id: 'doc-1', text: 'alpha' },
+                    { id: 'doc-2', text: 'beta' }
+                ];
+                const response = await provider.rerank({
+                    model: 'contract-model',
+                    query: 'contract',
+                    documents,
+                    signal: signal()
+                });
+                const ids = documents.map((document) => document.id);
+                for (const result of response.results) {
+                    expect(ids).toContain(result.id);
+                }
+                const scores = response.results.map((result) => result.score);
+                expect([...scores].sort((a, b) => b - a)).toEqual(scores);
+            });
+        }
+    });
+}

package/dist/testing/recordEvents.d.ts

@@ -0,0 +1,3 @@
+import type { RunEvent } from '../harness/defineHarness.js';
+/** Collects every event from a run-event stream into an array. */
+export declare function recordEvents(iter: AsyncIterable<RunEvent>): Promise<RunEvent[]>;

package/dist/testing/recordEvents.js

@@ -0,0 +1,8 @@
+/** Collects every event from a run-event stream into an array. */
+export async function recordEvents(iter) {
+    const events = [];
+    for await (const event of iter) {
+        events.push(event);
+    }
+    return events;
+}

package/dist/testing/stateStoreContract.js

@@ -95,6 +95,33 @@ export function stateStoreContract(make) {
                 expect.objectContaining({ id: '01EVT2' })
             ]);
         });
+        it('replaceMessages atomically replaces the history when supported', async () => {
+            const store = await make();
+            if (!store.replaceMessages)
+                return;
+            await store.appendMessages(session.id, [m1]);
+            await store.replaceMessages(session.id, [m2, m3]);
+            await expect(store.listMessages(session.id)).resolves.toEqual([m2, m3]);
+        });
+        it('getRun returns undefined for an unknown id', async () => {
+            const store = await make();
+            await expect(store.getRun('missing')).resolves.toBeUndefined();
+        });
+        it('listRuns honors limit', async () => {
+            const store = await make();
+            await store.createRun(run);
+            await store.createRun({ ...run, id: 'run_2', startedAt: '2026-01-01T00:00:05.000Z' });
+            await expect(store.listRuns(session.id, { limit: 1 })).resolves.toEqual([
+                expect.objectContaining({ id: 'run_2' })
+            ]);
+        });
+        it('listEvents honors limit', async () => {
+            const store = await make();
+            await store.appendEvents(run.id, [event, { ...event, id: '01EVT2' }]);
+            await expect(store.listEvents(run.id, { limit: 1 })).resolves.toEqual([
+                expect.objectContaining({ id: '01EVT' })
+            ]);
+        });
         it('duplicate message id throws StateError', async () => {
             const store = await make();
             await store.appendMessages(session.id, [m1]);

package/dist/tools/index.js

@@ -6,6 +6,18 @@ export const BUILTIN_TOOL_NAMES = ['bash', 'read', 'write', 'edit', 'glob', 'gre
 /** Per-file and total byte caps for the built-in `grep` read-and-match fallback. */
 const GREP_MAX_FILE_BYTES = 2_000_000;
 const GREP_MAX_TOTAL_BYTES = 50_000_000;
+/** Maximum accepted length for a model-supplied `grep` pattern. */
+const GREP_MAX_PATTERN_LENGTH = 1_000;
+/**
+ * Matches a quantified group whose (paren-free) body contains an unbounded
+ * quantifier — the classic catastrophic-backtracking shapes such as `(x+)+`,
+ * `(x*)*`, or `(a+b){2,}`. The check is intentionally syntactic and
+ * conservative. Residual risk: ambiguous alternations like `(a|a)+` and
+ * quantifiers nested deeper than one group level still pass; the byte caps
+ * above bound the scanned input but cannot prevent a stalled event loop for
+ * adversarial patterns beyond this check.
+ */
+const GREP_NESTED_UNBOUNDED_QUANTIFIER = /\((?:[^()\\]|\\.)*(?:[*+]|\{\d+,\})(?:[^()\\]|\\.)*\)(?:[*+]|\{\d+,\})/;
 export const BUILTIN_ALIAS_TO_CANONICAL = {
     bash: 'bash', Bash: 'bash',
     read: 'read', Read: 'read',
@@ -64,7 +76,8 @@ export async function invokeBuiltinTool(nameOrAlias, input, session, signal) {
                 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));
+                // Replacer function so `$&`, `$$`, `` $` `` etc. in new_string are written literally.
+                await session.write(parsed.path, content.replace(parsed.old_string, () => parsed.new_string));
                 return { replaced: 1 };
             }
             case 'glob': {
@@ -74,6 +87,18 @@ export async function invokeBuiltinTool(nameOrAlias, input, session, signal) {
             }
             case 'grep': {
                 const parsed = schemas.grep.input.parse(input);
+                if (parsed.pattern.length > GREP_MAX_PATTERN_LENGTH) {
+                    throw new ValidationError('grep pattern exceeds the maximum supported length', {
+                        where: 'tool_input',
+                        issues: [{ path: 'pattern', message: `Pattern must be at most ${GREP_MAX_PATTERN_LENGTH} characters.` }]
+                    });
+                }
+                if (GREP_NESTED_UNBOUNDED_QUANTIFIER.test(parsed.pattern)) {
+                    throw new ValidationError('grep pattern contains a nested unbounded quantifier', {
+                        where: 'tool_input',
+                        issues: [{ path: 'pattern', message: 'Patterns like (x+)+ can cause catastrophic backtracking and are rejected.' }]
+                    });
+                }
                 let rx;
                 try {
                     rx = new RegExp(parsed.pattern);

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

@@ -1,2 +1,4 @@
 import type { ResolvedMcpHttpTool, McpTransportRunner } from './runner.js';
 export declare function createHttpMcpTransportRunner(config: ResolvedMcpHttpTool): McpTransportRunner;
+/** Exported for tests. Extracts an HTTP status from structured fields or explicit status phrasing only. */
+export declare function statusFromError(error: unknown): number | undefined;

package/dist/tools/mcp/http.js

@@ -3,24 +3,32 @@ import { withMcpTimeout } from './runner.js';
 export function createHttpMcpTransportRunner(config) {
     let connected;
     async function connect(options) {
-        connected ??= (async () => {
-            const [{ Client }, { StreamableHTTPClientTransport }] = await Promise.all([
-                import('@modelcontextprotocol/sdk/client/index.js'),
-                import('@modelcontextprotocol/sdk/client/streamableHttp.js')
-            ]);
-            const transport = new StreamableHTTPClientTransport(new URL(config.url), {
-                requestInit: { headers: buildHeaders(config.headers, config.auth) }
+        if (!connected) {
+            const promise = (async () => {
+                const [{ Client }, { StreamableHTTPClientTransport }] = await Promise.all([
+                    import('@modelcontextprotocol/sdk/client/index.js'),
+                    import('@modelcontextprotocol/sdk/client/streamableHttp.js')
+                ]);
+                const transport = new StreamableHTTPClientTransport(new URL(config.url), {
+                    requestInit: { headers: buildHeaders(config.headers, config.auth) }
+                });
+                const client = new Client({ name: `purista-harness-${config.localToolId}`, version: '0.0.0' });
+                try {
+                    await client.connect(transport, toSdkOptions(options));
+                }
+                catch (error) {
+                    throw mapHttpError(config, 'connect', error);
+                }
+                return { client, transport };
+            })();
+            // Never cache a rejected connection (import or connect failure); the
+            // next call must retry from scratch.
+            void promise.catch(() => {
+                if (connected === promise)
+                    connected = undefined;
             });
-            const client = new Client({ name: `purista-harness-${config.localToolId}`, version: '0.0.0' });
-            try {
-                await client.connect(transport, toSdkOptions(options));
-            }
-            catch (error) {
-                connected = undefined;
-                throw mapHttpError(config, 'connect', error);
-            }
-            return { client, transport };
-        })();
+            connected = promise;
+        }
         return connected;
     }
     return {
@@ -53,8 +61,10 @@ export function createHttpMcpTransportRunner(config) {
                 return;
             const current = await connected.catch(() => undefined);
             connected = undefined;
-            await current?.transport.close();
-            await current?.client.close();
+            if (!current)
+                return;
+            // Client first per SDK guidance; close both even when one throws.
+            await Promise.allSettled([current.client.close(), current.transport.close()]);
         }
     };
 }
@@ -87,7 +97,8 @@ function mapHttpError(config, phase, error) {
     }
     return new McpProtocolError('MCP HTTP transport failed.', { tool_id: config.localToolId, transport: 'http', phase }, error);
 }
-function statusFromError(error) {
+/** Exported for tests. Extracts an HTTP status from structured fields or explicit status phrasing only. */
+export function statusFromError(error) {
     if (typeof error === 'object' && error !== null) {
         const maybe = error;
         if (typeof maybe.status === 'number')
@@ -101,7 +112,9 @@ function statusFromError(error) {
     if (error instanceof Error) {
         if (/unauthorized/i.test(error.message))
             return 401;
-        const match = /\b(401|403|4\d\d|5\d\d)\b/.exec(error.message);
+        // Only trust explicit "HTTP 503" / "status: 503" phrasing — a bare number
+        // in a message (e.g. "took 401ms") must not classify as an HTTP status.
+        const match = /HTTP (\d{3})/.exec(error.message) ?? /status[: ] ?(\d{3})/i.exec(error.message);
         if (match?.[1])
             return Number(match[1]);
     }

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

@@ -12,6 +12,8 @@ export interface ResolvedMcpTool {
     upstreamToolName: string;
     timeoutMs: number;
     serverKey: string;
+    /** Sandbox binding key (session id) used to evict session-scoped runners. */
+    sandboxKey?: string;
     inputAdapter?: (input: unknown) => unknown;
     outputAdapter?: (output: unknown) => unknown;
 }
@@ -49,6 +51,8 @@ export interface McpTransportRunner {
 }
 export interface McpRunnerRegistry {
     getRunner(config: ResolvedMcpToolConfig): McpTransportRunner;
+    /** Closes and evicts every runner bound to the given sandbox key (e.g. when a session closes). */
+    closeForSandboxKey(sandboxKey: string): Promise<void>;
     close(): Promise<void>;
 }
 export interface McpFacadeContext {

package/dist/tools/mcp/runner.js

@@ -3,23 +3,39 @@ import { assertMcpJsonSchema, validateMcpJsonSchema } from './schema.js';
 const discoveredCache = new WeakMap();
 export async function getMcpToolSpecs(tools, allowlist, ctx = {}) {
     const allowed = new Set(allowlist);
-    const registry = ctx.registry ?? createMcpRunnerRegistry();
-    const specs = await Promise.all(Object.entries(tools).map(async ([toolId, tool]) => {
-        if (!allowed.has(toolId) || !isMcpToolDefinition(tool))
-            return undefined;
-        const config = resolveMcpTool(toolId, tool, ctx);
-        return getResolvedModelToolSpec(config, registry.getRunner(config), ctx.signal, ctx.warn);
-    }));
-    return specs.filter((spec) => spec !== undefined);
+    // An ad-hoc registry can spawn persistent server processes; it must be
+    // closed before returning so direct library callers do not leak processes.
+    const localRegistry = ctx.registry ? undefined : createMcpRunnerRegistry();
+    const registry = ctx.registry ?? localRegistry;
+    try {
+        const specs = await Promise.all(Object.entries(tools).map(async ([toolId, tool]) => {
+            if (!allowed.has(toolId) || !isMcpToolDefinition(tool))
+                return undefined;
+            const config = resolveMcpTool(toolId, tool, ctx);
+            return getResolvedModelToolSpec(config, registry.getRunner(config), ctx.signal, ctx.warn);
+        }));
+        return specs.filter((spec) => spec !== undefined);
+    }
+    finally {
+        await localRegistry?.close();
+    }
 }
 export async function invokeMcpTool(first, second, input, fourth) {
     if (typeof first === 'string') {
         if (!isMcpToolDefinition(second))
             throw new ToolNotFoundError('Tool is not an MCP tool.', { tool_id: first, where: 'registry' });
         const ctx = isAbortSignal(fourth) ? { signal: fourth } : fourth ?? {};
-        const registry = ctx.registry ?? createMcpRunnerRegistry();
+        // An ad-hoc registry can spawn persistent server processes; it must be
+        // closed before returning so direct library callers do not leak processes.
+        const localRegistry = ctx.registry ? undefined : createMcpRunnerRegistry();
+        const registry = ctx.registry ?? localRegistry;
         const config = resolveMcpTool(first, second, ctx);
-        return invokeResolvedMcpTool(config, registry.getRunner(config), input, ctx.signal, ctx.warn);
+        try {
+            return await invokeResolvedMcpTool(config, registry.getRunner(config), input, ctx.signal, ctx.warn);
+        }
+        finally {
+            await localRegistry?.close();
+        }
     }
     return invokeResolvedMcpTool(first, second, input, isAbortSignal(fourth) ? fourth : fourth?.signal, isAbortSignal(fourth) ? undefined : fourth?.warn);
 }
@@ -30,18 +46,32 @@ export function createMcpRunnerRegistry() {
     const runners = new Map();
     return {
         getRunner(config) {
-            const existing = runners.get(config.localToolId);
+            // Keyed by serverKey: a stdio runner binds a concrete sandbox session, so
+            // two sessions must never share one runner even for the same tool id.
+            const key = config.serverKey || config.localToolId;
+            const existing = runners.get(key);
             if (existing)
-                return existing;
+                return existing.runner;
             const runner = config.kind === 'mcp_stdio'
                 ? createDynamicStdioRunner(config)
                 : createDynamicHttpRunner(config);
-            runners.set(config.localToolId, runner);
+            runners.set(key, { runner, ...(config.sandboxKey !== undefined ? { sandboxKey: config.sandboxKey } : {}) });
             return runner;
         },
+        async closeForSandboxKey(sandboxKey) {
+            const evicted = [];
+            for (const [key, entry] of runners) {
+                if (entry.sandboxKey === sandboxKey) {
+                    runners.delete(key);
+                    evicted.push(entry.runner);
+                }
+            }
+            await Promise.all(evicted.map((runner) => runner.close()));
+        },
         async close() {
-            await Promise.all([...runners.values()].map((runner) => runner.close()));
+            const open = [...runners.values()].map((entry) => entry.runner);
             runners.clear();
+            await Promise.all(open.map((runner) => runner.close()));
         }
     };
 }
@@ -73,7 +103,7 @@ async function invokeResolvedMcpTool(config, runner, input, signal, warn) {
     const validatedInput = validateMcpJsonSchema({ toolId: config.localToolId, where: 'mcp_input', schema: tool.inputSchema, value: adaptedInput, ...(warn ? { warn } : {}) });
     const result = await runner.callTool(config.upstreamToolName, validatedInput, { ...(signal ? { signal } : {}), timeoutMs: config.timeoutMs });
     if (isRecord(result) && result.isError === true) {
-        throw new ToolError('MCP tool returned an error.', { tool_id: config.localToolId, tool_kind: config.kind });
+        throw new ToolError(`MCP tool returned an error.${describeMcpErrorResult(result)}`, { tool_id: config.localToolId, tool_kind: config.kind });
     }
     const normalized = normalizeMcpOutput(result);
     const validatedOutput = tool.outputSchema
@@ -128,6 +158,7 @@ function resolveMcpTool(toolId, tool, ctx) {
             ...base,
             kind: 'mcp_stdio',
             serverKey: `${toolId}:${ctx.sandboxKey ?? 'sandbox'}`,
+            sandboxKey: ctx.sandboxKey ?? 'sandbox',
             command: tool.command,
             ...(tool.args ? { args: tool.args } : {}),
             ...(tool.env ? { env: tool.env } : {}),
@@ -148,25 +179,48 @@ export function isMcpToolDefinition(tool) {
 }
 function createDynamicStdioRunner(config) {
     let runnerPromise;
-    return dynamicRunner(() => {
-        runnerPromise ??= import('./stdio.js').then((module) => module.createStdioMcpTransportRunner(config));
+    const runner = dynamicRunner(() => {
+        runnerPromise ??= import('./stdio.js').then((module) => module.createStdioMcpTransportRunner(config, {
+            // A respawned server may expose a different tool list; drop the memoized
+            // discovery whenever the persistent server process is discarded.
+            onReset: () => { discoveredCache.delete(runner); }
+        }));
         return runnerPromise;
-    });
+    }, () => runnerPromise);
+    return runner;
 }
 function createDynamicHttpRunner(config) {
     let runnerPromise;
     return dynamicRunner(() => {
         runnerPromise ??= import('./http.js').then((module) => module.createHttpMcpTransportRunner(config));
         return runnerPromise;
-    });
+    }, () => runnerPromise);
 }
-function dynamicRunner(load) {
+function dynamicRunner(load, peek) {
     return {
         async listTools(options) { return (await load()).listTools(options); },
         async callTool(name, input, options) { return (await load()).callTool(name, input, options); },
-        async close() { await (await load()).close(); }
+        async close() {
+            // Never trigger a fresh transport load just to close it, and never let
+            // an earlier load failure escape from registry shutdown.
+            const pending = peek();
+            if (!pending)
+                return;
+            const loaded = await pending.catch(() => undefined);
+            await loaded?.close();
+        }
     };
 }
+/** Renders a short, truncated description of an MCP `isError` result for error messages. */
+function describeMcpErrorResult(result) {
+    const normalized = normalizeMcpOutput(result);
+    if (normalized === null)
+        return '';
+    const text = typeof normalized === 'string' ? normalized : JSON.stringify(normalized);
+    if (!text)
+        return '';
+    return ` ${text.slice(0, 512)}${text.length > 512 ? '…' : ''}`;
+}
 function normalizeContentBlock(block) {
     if (!isRecord(block))
         return null;