@esankhan3/anvil-agent-core 0.1.2 → 0.3.0

package/dist/__tests__/fetch-pool.integration.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Integration test — proves the heal-on-failure fix actually works.
+ *
+ * Without the fix, a poisoned pool fails every subsequent fetch with the
+ * same TypeError until the process restarts. With the fix:
+ *   - call 1 succeeds against a live server
+ *   - server dies → call 2 fails (TypeError: fetch failed)
+ *   - recycleFetchPoolOnFailure() runs
+ *   - server comes back → call 3 succeeds against the healed pool
+ *
+ * This is the test the plan in docs/FETCH-POOL-MANAGEMENT-PLAN.md §6.2
+ * specifies as the canary for the entire fix.
+ */
+export {};
+//# sourceMappingURL=fetch-pool.integration.test.d.ts.map

package/dist/__tests__/fetch-pool.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-pool.integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/fetch-pool.integration.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/__tests__/fetch-pool.integration.test.js

@@ -0,0 +1,109 @@
+/**
+ * Integration test — proves the heal-on-failure fix actually works.
+ *
+ * Without the fix, a poisoned pool fails every subsequent fetch with the
+ * same TypeError until the process restarts. With the fix:
+ *   - call 1 succeeds against a live server
+ *   - server dies → call 2 fails (TypeError: fetch failed)
+ *   - recycleFetchPoolOnFailure() runs
+ *   - server comes back → call 3 succeeds against the healed pool
+ *
+ * This is the test the plan in docs/FETCH-POOL-MANAGEMENT-PLAN.md §6.2
+ * specifies as the canary for the entire fix.
+ */
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { getFetchPool, recycleFetchPoolOnFailure, getPoolMetrics, resetAllPools, } from '../fetch-pool.js';
+describe('fetch-pool integration — heal-on-failure end-to-end', () => {
+    let server = null;
+    let port = 0;
+    async function startServer() {
+        server = http.createServer((req, res) => {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, path: req.url }));
+        });
+        await new Promise((resolve) => {
+            server.listen(port, '127.0.0.1', () => {
+                port = server.address().port;
+                resolve();
+            });
+        });
+    }
+    async function stopServer() {
+        if (!server)
+            return;
+        await new Promise((resolve) => {
+            server.close(() => resolve());
+            // Force-close any sockets the pool may be holding so the close()
+            // callback fires promptly.
+            server.closeAllConnections?.();
+        });
+        server = null;
+    }
+    before(async () => {
+        await startServer();
+    });
+    beforeEach(async () => {
+        await resetAllPools();
+    });
+    after(async () => {
+        await stopServer();
+        await resetAllPools();
+    });
+    it('healed pool succeeds after a network failure poisons the old pool', async () => {
+        const url = `http://127.0.0.1:${port}/v1/messages`;
+        // 1. First call succeeds against a live server.
+        const r1 = await fetch(url, {
+            // @ts-expect-error — undici dispatcher accepted by Node fetch at runtime
+            dispatcher: getFetchPool('anthropic'),
+        });
+        assert.strictEqual(r1.status, 200);
+        await r1.text();
+        // 2. Kill the server. The pool now holds zombie sockets pointed at a
+        //    dead listener — every subsequent fetch through the SAME dispatcher
+        //    fails with `TypeError: fetch failed`.
+        await stopServer();
+        let caught = null;
+        try {
+            await fetch(url, {
+                // @ts-expect-error — undici dispatcher accepted by Node fetch at runtime
+                dispatcher: getFetchPool('anthropic'),
+            });
+        }
+        catch (err) {
+            caught = err;
+        }
+        assert.ok(caught instanceof Error, 'expected fetch to throw with server down');
+        assert.match(caught.message + ' ' + (caught.cause instanceof Error ? caught.cause.message : ''), /fetch failed|ECONNREFUSED|ECONNRESET|socket/i);
+        // 3. Recycle the pool — this is what the adapter's catch block does
+        //    in production.
+        await recycleFetchPoolOnFailure('anthropic', caught);
+        const metrics = getPoolMetrics().find((m) => m.provider === 'anthropic');
+        assert.strictEqual(metrics?.recycleCount, 1, 'pool should have been recycled');
+        // 4. Bring the server back on the same port.
+        await startServer();
+        // 5. The next fetch must succeed. Without the recycle, the same zombie
+        //    socket would be re-used and this would fail again.
+        const r3 = await fetch(url, {
+            // @ts-expect-error — undici dispatcher accepted by Node fetch at runtime
+            dispatcher: getFetchPool('anthropic'),
+        });
+        assert.strictEqual(r3.status, 200, 'healed pool must serve the next request');
+        const body = (await r3.json());
+        assert.strictEqual(body.ok, true);
+    });
+    it('one provider failing does not recycle a sibling provider', async () => {
+        // Touch both pools so they exist.
+        getFetchPool('anthropic');
+        getFetchPool('gemini');
+        // Poison only one.
+        await recycleFetchPoolOnFailure('anthropic', new TypeError('fetch failed'));
+        const metrics = getPoolMetrics();
+        const anthropic = metrics.find((m) => m.provider === 'anthropic');
+        const gemini = metrics.find((m) => m.provider === 'gemini');
+        assert.strictEqual(anthropic?.recycleCount, 1);
+        assert.strictEqual(gemini?.recycleCount, 0, 'sibling provider must be untouched');
+    });
+});
+//# sourceMappingURL=fetch-pool.integration.test.js.map

package/dist/__tests__/fetch-pool.integration.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-pool.integration.test.js","sourceRoot":"","sources":["../../src/__tests__/fetch-pool.integration.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/fetch-pool.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Unit tests for fetch-pool — per-provider dispatcher with heal-on-failure.
+ *
+ * Covers the eight contracts from FETCH-POOL-MANAGEMENT-PLAN.md §6.1:
+ *   a) Lazy construction returns a stable instance per provider
+ *   b) Per-provider isolation — different providers get different agents
+ *   c) Bounded options applied at construction
+ *   d) Recycle on poisoned-error pattern swaps the agent
+ *   e) No recycle on non-poisoned errors (e.g. 400, 401, 503)
+ *   f) Concurrent recycles coalesce to one bump
+ *   g) Metrics shape is well-formed
+ *   h) resetAllPools clears state cleanly
+ */
+export {};
+//# sourceMappingURL=fetch-pool.test.d.ts.map

package/dist/__tests__/fetch-pool.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-pool.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/fetch-pool.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/__tests__/fetch-pool.test.js

@@ -0,0 +1,115 @@
+/**
+ * Unit tests for fetch-pool — per-provider dispatcher with heal-on-failure.
+ *
+ * Covers the eight contracts from FETCH-POOL-MANAGEMENT-PLAN.md §6.1:
+ *   a) Lazy construction returns a stable instance per provider
+ *   b) Per-provider isolation — different providers get different agents
+ *   c) Bounded options applied at construction
+ *   d) Recycle on poisoned-error pattern swaps the agent
+ *   e) No recycle on non-poisoned errors (e.g. 400, 401, 503)
+ *   f) Concurrent recycles coalesce to one bump
+ *   g) Metrics shape is well-formed
+ *   h) resetAllPools clears state cleanly
+ */
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { Agent } from 'undici';
+import { getFetchPool, recycleFetchPoolOnFailure, getPoolMetrics, resetAllPools, } from '../fetch-pool.js';
+describe('fetch-pool', () => {
+    beforeEach(async () => {
+        await resetAllPools();
+    });
+    it('a) lazy construction returns the same Agent on repeat calls', () => {
+        const a1 = getFetchPool('anthropic');
+        const a2 = getFetchPool('anthropic');
+        assert.ok(a1 instanceof Agent);
+        assert.strictEqual(a1, a2, 'second call should return same instance');
+    });
+    it('b) per-provider isolation — separate Agents per provider', () => {
+        const anthropic = getFetchPool('anthropic');
+        const gemini = getFetchPool('gemini');
+        const opencode = getFetchPool('opencode');
+        assert.notStrictEqual(anthropic, gemini);
+        assert.notStrictEqual(anthropic, opencode);
+        assert.notStrictEqual(gemini, opencode);
+    });
+    it('c) constructed Agent is bounded — close() resolves without hanging', async () => {
+        // Indirect bounded-keep-alive test: a fresh pool with no in-flight work
+        // closes synchronously-ish. If construction picked up unbounded defaults,
+        // tests for d/f would intermittently hang on the close() inside recycle.
+        const agent = getFetchPool('openai');
+        const closed = agent.close();
+        await Promise.race([
+            closed,
+            new Promise((_, reject) => setTimeout(() => reject(new Error('close hung beyond 500ms')), 500)),
+        ]);
+    });
+    it('d) recycle swaps the Agent when the error matches a poisoned pattern', async () => {
+        const before = getFetchPool('opencode');
+        await recycleFetchPoolOnFailure('opencode', new TypeError('fetch failed'));
+        const after = getFetchPool('opencode');
+        assert.notStrictEqual(after, before, 'agent should have been swapped');
+        const metrics = getPoolMetrics().find((m) => m.provider === 'opencode');
+        assert.ok(metrics);
+        assert.strictEqual(metrics.recycleCount, 1);
+        assert.ok(metrics.lastRecycleAt);
+        assert.match(metrics.lastRecycleReason ?? '', /fetch failed/);
+    });
+    it('e) does not recycle on non-poisoned errors (real upstream status)', async () => {
+        const before = getFetchPool('gemini');
+        await recycleFetchPoolOnFailure('gemini', new Error('400 Bad Request'));
+        await recycleFetchPoolOnFailure('gemini', new Error('503 Service Unavailable'));
+        await recycleFetchPoolOnFailure('gemini', new Error('quota exceeded'));
+        const after = getFetchPool('gemini');
+        assert.strictEqual(after, before, 'agent must not change on non-network errors');
+        const metrics = getPoolMetrics().find((m) => m.provider === 'gemini');
+        assert.strictEqual(metrics?.recycleCount, 0);
+    });
+    it('f) concurrent recycles coalesce — recycleCount increments once', async () => {
+        getFetchPool('ollama');
+        const err = new TypeError('fetch failed');
+        const all = await Promise.all(Array.from({ length: 10 }, () => recycleFetchPoolOnFailure('ollama', err)));
+        assert.strictEqual(all.length, 10);
+        const metrics = getPoolMetrics().find((m) => m.provider === 'ollama');
+        assert.strictEqual(metrics?.recycleCount, 1, 'must coalesce to one recycle');
+    });
+    it('g) getPoolMetrics returns well-shaped entries', async () => {
+        getFetchPool('anthropic');
+        getFetchPool('openrouter');
+        const metrics = getPoolMetrics();
+        assert.ok(Array.isArray(metrics));
+        assert.strictEqual(metrics.length, 2);
+        for (const m of metrics) {
+            assert.ok(['anthropic', 'openrouter'].includes(m.provider));
+            assert.strictEqual(typeof m.createdAt, 'string');
+            assert.match(m.createdAt, /\dT\d/, 'ISO timestamp');
+            assert.strictEqual(typeof m.recycleCount, 'number');
+            assert.strictEqual(typeof m.active, 'boolean');
+            assert.strictEqual(m.active, true, 'idle pool is active');
+        }
+    });
+    it('h) resetAllPools drops all state', async () => {
+        getFetchPool('anthropic');
+        getFetchPool('gemini');
+        assert.strictEqual(getPoolMetrics().length, 2);
+        await resetAllPools();
+        assert.strictEqual(getPoolMetrics().length, 0);
+        // Subsequent get reconstructs cleanly
+        const fresh = getFetchPool('anthropic');
+        assert.ok(fresh instanceof Agent);
+        assert.strictEqual(getPoolMetrics().length, 1);
+    });
+    it('recycle reads ECONNRESET from err.cause', async () => {
+        const before = getFetchPool('anthropic');
+        // Node's fetch wraps the underlying socket error in `.cause`.
+        const err = new TypeError('fetch failed', {
+            cause: new Error('read ECONNRESET'),
+        });
+        await recycleFetchPoolOnFailure('anthropic', err);
+        const after = getFetchPool('anthropic');
+        assert.notStrictEqual(after, before);
+        const m = getPoolMetrics().find((p) => p.provider === 'anthropic');
+        assert.strictEqual(m?.recycleCount, 1);
+    });
+});
+//# sourceMappingURL=fetch-pool.test.js.map

package/dist/__tests__/fetch-pool.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-pool.test.js","sourceRoot":"","sources":["../../src/__tests__/fetch-pool.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/mcp-merged-executor.test.d.ts

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

package/dist/__tests__/mcp-merged-executor.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-merged-executor.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/mcp-merged-executor.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/mcp-merged-executor.test.js

@@ -0,0 +1,221 @@
+/**
+ * End-to-end tests for `MergedToolExecutor` driving the official MCP TS SDK
+ * over an in-process transport. Validates:
+ *   - tool merging (builtin + MCP)
+ *   - exact-name + per-server glob allowlists
+ *   - destructive-tool guard under glob
+ *   - dispatch routing builtin vs MCP
+ *   - flattening of `content[]` array results
+ *   - cancellation propagation
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { McpAgentClient } from '../mcp/client.js';
+import { McpClientPool } from '../mcp/pool.js';
+import { MergedToolExecutor } from '../mcp/merged-executor.js';
+import { BuiltinToolExecutor } from '../tools/builtin.js';
+/**
+ * Spin up an MCP server in-process and return a connected `McpAgentClient`
+ * wired through `InMemoryTransport`. The official SDK handles the protocol;
+ * the test only cares about the tool surface.
+ */
+async function makeInMemoryMcpClient(opts) {
+    const server = new Server({ name: `test-${opts.name}`, version: '0.0.1' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: opts.tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema ?? { type: 'object' },
+            ...(t.annotations ? { annotations: t.annotations } : {}),
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const tool = opts.tools.find((t) => t.name === req.params.name);
+        if (!tool) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `unknown tool ${req.params.name}` }],
+            };
+        }
+        const result = tool.onCall?.(req.params.arguments ?? {}) ?? {
+            content: [{ type: 'text', text: 'ok' }],
+        };
+        return result;
+    });
+    const [clientT, serverT] = InMemoryTransport.createLinkedPair();
+    await server.connect(serverT);
+    // Construct a client and inject the linked transport, bypassing connect().
+    const client = new McpAgentClient({ name: opts.name, transport: 'stdio', command: 'noop' });
+    // Test seam: swap the SDK Client's transport for our in-memory one.
+    // The McpAgentClient holds the SDK Client in a private field; we
+    // bypass the type with a controlled cast.
+    await client.client.connect(clientT);
+    client.connected = true;
+    return client;
+}
+function workdir() {
+    const dir = mkdtempSync(join(tmpdir(), 'merged-exec-'));
+    return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+// ── Tests ───────────────────────────────────────────────────────────────
+describe('MergedToolExecutor — schema merging', () => {
+    it('merges builtin + MCP tools and namespaces MCP entries as mcp__<server>__<tool>', async () => {
+        const client = await makeInMemoryMcpClient({
+            name: 'gh',
+            tools: [{ name: 'list_issues', description: 'list', annotations: { readOnlyHint: true } }],
+        });
+        const pool = new McpClientPool({ servers: [client.config] });
+        // Bypass pool.discoverTools' loader by stuffing the client directly.
+        pool.clients.set('gh', client);
+        const builtin = new BuiltinToolExecutor({
+            allowedTools: ['read_file', 'mcp__gh__list_issues'],
+        });
+        const exec = new MergedToolExecutor({
+            builtin,
+            pool,
+            allowedTools: ['read_file', 'mcp__gh__list_issues'],
+        });
+        await exec.prime();
+        const names = exec.listSchemas().map((s) => s.name).sort();
+        assert.deepEqual(names, ['mcp__gh__list_issues', 'read_file']);
+        await client.close();
+        await pool.close();
+    });
+    it('per-server glob allows read-only MCP tools but hides destructive ones', async () => {
+        const client = await makeInMemoryMcpClient({
+            name: 'fs',
+            tools: [
+                { name: 'read', description: 'read', annotations: { readOnlyHint: true } },
+                { name: 'delete', description: 'delete', annotations: { destructiveHint: true } },
+            ],
+        });
+        const pool = new McpClientPool({ servers: [client.config] });
+        pool.clients.set('fs', client);
+        const builtin = new BuiltinToolExecutor({ allowedTools: ['read_file', 'mcp__fs__*'] });
+        const exec = new MergedToolExecutor({
+            builtin,
+            pool,
+            allowedTools: ['read_file', 'mcp__fs__*'],
+        });
+        await exec.prime();
+        const names = exec.listSchemas().map((s) => s.name).sort();
+        assert.ok(names.includes('mcp__fs__read'), 'glob admits read-only MCP tool');
+        assert.ok(!names.includes('mcp__fs__delete'), 'glob hides destructive MCP tool');
+        await client.close();
+        await pool.close();
+    });
+    it('exact-name allowance admits destructive MCP tools', async () => {
+        const client = await makeInMemoryMcpClient({
+            name: 'fs',
+            tools: [{ name: 'delete', description: 'd', annotations: { destructiveHint: true } }],
+        });
+        const pool = new McpClientPool({ servers: [client.config] });
+        pool.clients.set('fs', client);
+        const exec = new MergedToolExecutor({
+            builtin: new BuiltinToolExecutor({ allowedTools: ['mcp__fs__delete'] }),
+            pool,
+            allowedTools: ['mcp__fs__delete'],
+        });
+        await exec.prime();
+        const names = exec.listSchemas().map((s) => s.name);
+        assert.deepEqual(names, ['mcp__fs__delete']);
+        await client.close();
+        await pool.close();
+    });
+});
+describe('MergedToolExecutor — dispatch', () => {
+    it('routes mcp__* calls to the pool and flattens text content[] into a string', async () => {
+        const client = await makeInMemoryMcpClient({
+            name: 'echo',
+            tools: [{
+                    name: 'say',
+                    description: 'echo',
+                    onCall: (args) => ({
+                        content: [
+                            { type: 'text', text: `you said: ${args.msg ?? '?'}` },
+                            { type: 'text', text: 'and a second line' },
+                        ],
+                    }),
+                }],
+        });
+        const pool = new McpClientPool({ servers: [client.config] });
+        pool.clients.set('echo', client);
+        const exec = new MergedToolExecutor({
+            builtin: new BuiltinToolExecutor({ allowedTools: ['mcp__echo__say'] }),
+            pool,
+            allowedTools: ['mcp__echo__say'],
+        });
+        await exec.prime();
+        const { dir, cleanup } = workdir();
+        try {
+            const ctrl = new AbortController();
+            const result = await exec.execute({ id: '1', name: 'mcp__echo__say', arguments: { msg: 'hi' } }, { workingDir: dir, abortSignal: ctrl.signal });
+            assert.equal(result.isError, false);
+            assert.match(result.content, /you said: hi/);
+            assert.match(result.content, /second line/);
+        }
+        finally {
+            cleanup();
+            await client.close();
+            await pool.close();
+        }
+    });
+    it('routes builtin names to BuiltinToolExecutor untouched', async () => {
+        const pool = new McpClientPool({ servers: [] });
+        const exec = new MergedToolExecutor({
+            builtin: new BuiltinToolExecutor({ allowedTools: ['list'] }),
+            pool,
+            allowedTools: ['list'],
+        });
+        const { dir, cleanup } = workdir();
+        try {
+            const ctrl = new AbortController();
+            const result = await exec.execute({ id: '1', name: 'list', arguments: {} }, { workingDir: dir, abortSignal: ctrl.signal });
+            assert.equal(result.isError, false);
+        }
+        finally {
+            cleanup();
+            await pool.close();
+        }
+    });
+    it('rejects disallowed MCP names at exec with isError=true', async () => {
+        const pool = new McpClientPool({ servers: [] });
+        const exec = new MergedToolExecutor({
+            builtin: new BuiltinToolExecutor({ allowedTools: ['read_file'] }),
+            pool,
+            allowedTools: ['read_file'],
+        });
+        const { dir, cleanup } = workdir();
+        try {
+            const ctrl = new AbortController();
+            const result = await exec.execute({ id: '1', name: 'mcp__rogue__do_anything', arguments: {} }, { workingDir: dir, abortSignal: ctrl.signal });
+            assert.equal(result.isError, true);
+            assert.match(result.content, /not permitted/);
+        }
+        finally {
+            cleanup();
+            await pool.close();
+        }
+    });
+});
+describe('McpClientPool — failure isolation', () => {
+    it('records connect failures in `failures` without crashing the pool', async () => {
+        // Construct a pool with one bogus server config that will fail at connect.
+        const pool = new McpClientPool({
+            servers: [{ name: 'broken', transport: 'stdio', command: '/no/such/command' }],
+            connectTimeoutMs: 1000,
+        });
+        const tools = await pool.discoverTools();
+        assert.deepEqual(tools, []);
+        assert.equal(pool.failures.length, 1);
+        assert.equal(pool.failures[0].server, 'broken');
+        await pool.close();
+    });
+});
+//# sourceMappingURL=mcp-merged-executor.test.js.map

package/dist/__tests__/mcp-merged-executor.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-merged-executor.test.js","sourceRoot":"","sources":["../../src/__tests__/mcp-merged-executor.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/mcp.test.js

@@ -270,7 +270,13 @@ class FakeMcpClient {
     async listTools() {
         if (this.throwOnList)
             throw new Error('boom');
-        return this.tools;
+        return this.tools.map((t) => ({
+            name: t.name,
+            bareName: t.name.includes('__') ? t.name.split('__').slice(2).join('__') : t.name,
+            serverName: this.config.name,
+            schema: t,
+            annotations: {},
+        }));
     }
 }
 function asClient(c) {
@@ -282,13 +288,13 @@ describe('buildAgentToolset', () => {
             { name: 'fs.read', description: 'read', inputSchema: {} },
         ];
         const ghClient = new FakeMcpClient('github', [
-            { name: 'github/list_issues', description: 'list', inputSchema: {} },
+            { name: 'mcp__github__list_issues', description: 'list', inputSchema: {} },
         ]);
         const ts = await buildAgentToolset(builtIn, [asClient(ghClient)]);
         assert.equal(ts.tools.length, 2);
-        assert.deepEqual(ts.tools.map((t) => t.name).sort(), ['fs.read', 'github/list_issues']);
+        assert.deepEqual(ts.tools.map((t) => t.name).sort(), ['fs.read', 'mcp__github__list_issues']);
         assert.equal(ts.mcpDispatch.size, 1);
-        assert.equal(ts.mcpDispatch.get('github/list_issues'), asClient(ghClient));
+        assert.equal(ts.mcpDispatch.get('mcp__github__list_issues'), asClient(ghClient));
         assert.equal(ts.mcpDispatch.has('fs.read'), false);
     });
     it('drops collisions with built-ins (warns)', async () => {
@@ -297,22 +303,22 @@ describe('buildAgentToolset', () => {
         ];
         const dup = new FakeMcpClient('weird', [
             { name: 'fs.read', description: 'mcp dup', inputSchema: {} },
-            { name: 'weird/ok', description: 'fine', inputSchema: {} },
+            { name: 'mcp__weird__ok', description: 'fine', inputSchema: {} },
         ]);
         const { result, captured } = await captureStderrAsync(() => buildAgentToolset(builtIn, [asClient(dup)]));
         assert.equal(result.tools.length, 2);
         assert.equal(result.mcpDispatch.has('fs.read'), false);
-        assert.equal(result.mcpDispatch.has('weird/ok'), true);
+        assert.equal(result.mcpDispatch.has('mcp__weird__ok'), true);
         assert.ok(captured.includes('collision "fs.read"'));
     });
     it('isolates listTools failures: one bad server does not kill others', async () => {
         const good = new FakeMcpClient('good', [
-            { name: 'good/ping', description: 'p', inputSchema: {} },
+            { name: 'mcp__good__ping', description: 'p', inputSchema: {} },
         ]);
         const bad = new FakeMcpClient('bad', [], /* throwOnList */ true);
         const { result, captured } = await captureStderrAsync(() => buildAgentToolset([], [asClient(bad), asClient(good)]));
         assert.equal(result.tools.length, 1);
-        assert.equal(result.tools[0].name, 'good/ping');
+        assert.equal(result.tools[0].name, 'mcp__good__ping');
         assert.ok(captured.includes('"bad" listTools failed'));
     });
 });
@@ -348,21 +354,21 @@ describe('McpAgentClient routing', () => {
         c.client = fake;
         c.connected = true;
     }
-    it('namespaces tools as `<server>/<tool>` in listTools()', async () => {
+    it('namespaces tools as `mcp__<server>__<tool>` in listTools()', async () => {
         const client = new McpAgentClient({ name: 'fs', transport: 'stdio', command: 'noop' });
         const fake = makeFakeSdkClient();
         injectFakeClient(client, fake);
         const tools = await client.listTools();
-        assert.deepEqual(tools.map((t) => t.name), ['fs/read_file', 'fs/write_file']);
-        // descriptions + inputSchema preserved, only name namespaced
-        assert.equal(tools[0].description, 'read');
-        assert.deepEqual(tools[0].inputSchema, { type: 'object' });
+        assert.deepEqual(tools.map((t) => t.name), ['mcp__fs__read_file', 'mcp__fs__write_file']);
+        // descriptions decorated with server tag + read-only heuristic; schema preserved
+        assert.match(tools[0].schema.description, /\(via fs MCP/);
+        assert.deepEqual(tools[0].schema.inputSchema, { type: 'object' });
     });
-    it('callTool strips the `<server>/` prefix before forwarding to SDK', async () => {
+    it('callTool strips the namespacing prefix before forwarding to SDK', async () => {
         const client = new McpAgentClient({ name: 'gh', transport: 'stdio', command: 'noop' });
         const fake = makeFakeSdkClient();
         injectFakeClient(client, fake);
-        await client.callTool('gh/list_issues', { repo: 'owner/repo' });
+        await client.callTool('mcp__gh__list_issues', { repo: 'owner/repo' });
         assert.equal(fake.calls.length, 1);
         assert.equal(fake.calls[0].params.name, 'list_issues');
         assert.deepEqual(fake.calls[0].params.arguments, { repo: 'owner/repo' });