@animalabs/agent-framework 0.5.7 → 0.6.2

package/dist/test/mcpl-reconnect-reregistration.test.js

@@ -0,0 +1,181 @@
+/**
+ * MCPL auto-reconnect must RE-REGISTER the server, not just refresh tools.
+ *
+ * Before the fix, the 'close' handler removed the server from the
+ * FeatureSetManager (and destroyed its checkpoint trees), while the
+ * 'reconnect' handler only re-listed tools. Result: after any transient
+ * crash + successful reconnect, validateInbound threw "Unknown server"
+ * forever — every push event and inference request rejected until a full
+ * host restart — and the server's durable checkpoint state was gone.
+ *
+ * These tests exercise the framework's wireMcplEvents close/reconnect
+ * handlers with the REAL FeatureSetManager / CheckpointManager / PushHandler
+ * and a fake connection (EventEmitter), asserting:
+ *   1. a push event after close→reconnect is ACCEPTED again;
+ *   2. checkpoint state SURVIVES any close (transient OR clean shutdown);
+ *   3. checkpoint state is destroyed only via disconnectMcplServer (explicit
+ *      permanent removal), never by the close handler.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { AgentFramework } from '../src/framework.js';
+import { FeatureSetManager } from '../src/mcpl/feature-set-manager.js';
+import { ScopeManager } from '../src/mcpl/scope-manager.js';
+import { CheckpointManager } from '../src/mcpl/checkpoint-manager.js';
+import { PushHandler } from '../src/mcpl/push-handler.js';
+/** In-memory JsStore stub — CheckpointManager only needs the state-slot API. */
+function makeStoreStub() {
+    const slots = new Map();
+    return {
+        slots,
+        registerState: (_opts) => { },
+        setStateJson: (id, value) => { slots.set(id, structuredClone(value)); },
+        getStateJson: (id) => slots.get(id) ?? null,
+    };
+}
+const CAPABILITIES = {
+    version: '0.4',
+    featureSets: {
+        chat: { description: 'chat events', uses: ['pushEvents'] },
+        mem: { description: 'stateful memory', uses: ['tools'], hostState: true, rollback: true },
+    },
+};
+class FakeConnection extends EventEmitter {
+    id;
+    capabilities = CAPABILITIES;
+    willReconnect = true;
+    featureSetUpdates = [];
+    constructor(id) {
+        super();
+        this.id = id;
+    }
+    sendFeatureSetsUpdate(params) {
+        this.featureSetUpdates.push(params);
+    }
+}
+function makeHarness() {
+    const store = makeStoreStub();
+    const traces = [];
+    const pushed = [];
+    const fw = Object.create(AgentFramework.prototype);
+    fw.traceListeners = [];
+    fw.consecutiveInferenceFailures = new Map();
+    fw.exhaustionRewinds = new Map();
+    fw.agents = new Map();
+    fw.mcplTools = [];
+    fw.mcplToolRefreshInFlight = false;
+    fw.mcplToolRefreshPending = false;
+    fw.mcplServerRegistry = null; // handleToolsListChanged no-ops without it
+    fw.channelRegistry = null;
+    fw.inferenceRouter = null;
+    fw.eventGate = null;
+    fw.featureSetManager = new FeatureSetManager();
+    fw.scopeManager = new ScopeManager();
+    fw.checkpointManager = new CheckpointManager(store, (e) => traces.push(e));
+    fw.pushHandler = new PushHandler(fw.featureSetManager, (e) => pushed.push(e), (e) => traces.push(e));
+    const config = {
+        id: 'srv',
+        command: 'unused',
+        enabledFeatureSets: ['chat', 'mem'],
+        reconnect: true,
+    };
+    fw.mcplServerConfigs = new Map([[config.id, config]]);
+    const connection = new FakeConnection('srv');
+    fw.wireMcplEvents(connection);
+    fw.registerMcplServerFeatures(config, connection);
+    const sendPush = (eventId) => {
+        let result;
+        connection.emit('push-event', {
+            featureSet: 'chat',
+            eventId,
+            timestamp: new Date().toISOString(),
+            payload: { content: [{ type: 'text', text: 'hello' }] },
+        }, {
+            respond: (r) => { result = r; },
+            respondError: () => { assert.fail('push responded with a JSON-RPC error'); },
+        });
+        assert.ok(result, 'push handler must respond synchronously');
+        return result;
+    };
+    return { fw, store, connection, config, sendPush, pushed, traces };
+}
+test('reconnect re-registers the server: pushes are accepted again after close→reconnect', () => {
+    const { fw, connection, sendPush, pushed } = makeHarness();
+    // Sanity: initial registration accepts pushes.
+    assert.equal(sendPush('e1').accepted, true);
+    assert.equal(pushed.length, 1);
+    // Transient crash: transport closed, background reconnect pending.
+    connection.willReconnect = true;
+    connection.emit('close', null, 'SIGKILL');
+    // While down, the server is deregistered — pushes are rejected.
+    const down = sendPush('e2');
+    assert.equal(down.accepted, false);
+    assert.match(down.reason ?? '', /Unknown server/);
+    // Reconnect succeeded (fresh handshake refreshed capabilities).
+    connection.emit('reconnect', { attempts: 1 });
+    // THE regression: before the fix this stayed rejected forever.
+    const revived = sendPush('e3');
+    assert.equal(revived.accepted, true, `push after reconnect must be accepted, got: ${revived.reason}`);
+    assert.equal(pushed.length, 2);
+    // The server was told its enabled feature sets again on re-registration.
+    assert.equal(connection.featureSetUpdates.length, 2, 'featureSets/update re-sent on reconnect');
+    assert.ok(fw.featureSetManager.isEnabled('srv', 'chat'));
+});
+test('checkpoint state SURVIVES a transient close + reconnect', () => {
+    const { fw, store, connection } = makeHarness();
+    // Record durable checkpoint state for the stateful feature set.
+    fw.checkpointManager.recordCheckpoint('srv', 'mem', {
+        checkpoint: 'cp1',
+        data: { counter: 42 },
+    });
+    assert.equal(fw.checkpointManager.getCurrentCheckpoint('srv', 'mem'), 'cp1');
+    // Transient close: reconnect loop is active.
+    connection.willReconnect = true;
+    connection.emit('close', 1, null);
+    assert.equal(fw.checkpointManager.getCurrentCheckpoint('srv', 'mem'), 'cp1', 'a transient disconnect must NOT destroy checkpoint trees');
+    const persisted = store.slots.get('mcpl/checkpoints');
+    assert.ok(persisted.trees['srv:mem'], 'the persisted tree must not be deleted from Chronicle');
+    // Reconnect: idempotent re-registration resumes (not resets) the tree.
+    connection.emit('reconnect', { attempts: 1 });
+    assert.equal(fw.checkpointManager.getCurrentCheckpoint('srv', 'mem'), 'cp1');
+    assert.deepEqual(fw.checkpointManager.getCurrentState('srv', 'mem'), { counter: 42 });
+});
+test('the close handler NEVER destroys checkpoints — even with willReconnect=false', () => {
+    // A clean AgentFramework.stop() sets reconnectEnabled=false BEFORE emitting
+    // 'close', so willReconnect is false on an ordinary host restart just as much
+    // as on a permanent teardown. Gating checkpoint destruction on willReconnect
+    // would therefore erase every durable checkpoint tree on a polite restart
+    // (while a SIGKILL, whose 'close' carries willReconnect=true, preserved them).
+    // Permanent removal is owned solely by disconnectMcplServer; the close handler
+    // must leave the persisted tree intact for loadFromStore() to resume.
+    const { fw, store, connection } = makeHarness();
+    fw.checkpointManager.recordCheckpoint('srv', 'mem', { checkpoint: 'cp1', data: { x: 1 } });
+    // Even a "permanent-looking" close (reconnect disabled) must not delete state.
+    connection.willReconnect = false;
+    connection.emit('close', 0, null);
+    assert.equal(fw.checkpointManager.getCurrentCheckpoint('srv', 'mem'), 'cp1', 'the close handler must not destroy checkpoints on a clean shutdown');
+    const persisted = store.slots.get('mcpl/checkpoints');
+    assert.ok(persisted.trees['srv:mem'], 'the persisted tree survives a clean shutdown for later resume');
+});
+test('disconnectMcplServer destroys checkpoints even when the connection already closed transiently', async () => {
+    const { fw, connection, config } = makeHarness();
+    fw.checkpointManager.recordCheckpoint('srv', 'mem', { checkpoint: 'cp1', data: { x: 1 } });
+    // Transient close first (checkpoints preserved for the pending reconnect)…
+    connection.willReconnect = true;
+    connection.emit('close', 1, null);
+    assert.equal(fw.checkpointManager.getCurrentCheckpoint('srv', 'mem'), 'cp1');
+    // …then the operator permanently removes the server. close() on an
+    // already-closed connection emits no second 'close', so the explicit
+    // cleanup in disconnectMcplServer must handle it.
+    fw.mcplServerRegistry = {
+        removeServer: async () => { },
+        getAllServers: () => [],
+        getServer: () => null,
+    };
+    fw.mcplPrefixMap = new Map([[`mcpl--srv`, 'srv']]);
+    await fw.disconnectMcplServer(config.id);
+    assert.equal(fw.checkpointManager.getCurrentCheckpoint('srv', 'mem'), null);
+    assert.equal(fw.featureSetManager.isEnabled('srv', 'chat'), false);
+});
+//# sourceMappingURL=mcpl-reconnect-reregistration.test.js.map

package/dist/test/mcpl-reconnect-reregistration.test.js.map

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

package/dist/test/mcpl-request-timeout.test.d.ts

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

package/dist/test/mcpl-request-timeout.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpl-request-timeout.test.d.ts","sourceRoot":"","sources":["../../test/mcpl-request-timeout.test.ts"],"names":[],"mappings":""}

package/dist/test/mcpl-request-timeout.test.js

@@ -0,0 +1,123 @@
+/**
+ * MCPL per-request timeout (6.2): a live-but-stuck server — accepts a
+ * request, never responds, never closes its transport — must not freeze the
+ * awaiting caller forever. sendRequest rejects after requestTimeoutMs with a
+ * descriptive error; the framework maps that rejection to an isError
+ * tool_result, so the agent turn completes instead of hanging.
+ */
+import { test, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { McplServerConnection } from '../src/mcpl/server-connection.js';
+// Stdio server: answers initialize and tools/list, but swallows tools/call —
+// the "zulip HTML-error / event-loop-wedge" profile (alive, deaf).
+const HUNG_SERVER = `
+let buf = '';
+process.stdin.on('data', (c) => {
+  buf += c.toString('utf8');
+  let i;
+  while ((i = buf.indexOf('\\n')) >= 0) {
+    const line = buf.slice(0, i); buf = buf.slice(i + 1);
+    if (!line.trim()) continue;
+    let m; try { m = JSON.parse(line); } catch { continue; }
+    const reply = (result) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: m.id, result }) + '\\n');
+    if (m.method === 'initialize') reply({ capabilities: {} });
+    else if (m.method === 'tools/list') reply({ tools: [{ name: 'stuck', description: 's', inputSchema: { type: 'object' } }] });
+    // tools/call: deliberately NO response, connection stays open.
+  }
+});
+setInterval(() => {}, 1 << 30); // stay alive
+`;
+const HOST_CAPS = {
+    version: '0.4',
+    pushEvents: true,
+    contextHooks: { beforeInference: true, afterInference: { blocking: true } },
+    featureSets: true,
+};
+function config(overrides) {
+    return {
+        id: 'hung',
+        command: process.execPath,
+        args: ['-e', HUNG_SERVER],
+        ...overrides,
+    };
+}
+let connection = null;
+afterEach(async () => {
+    await connection?.close();
+    connection = null;
+});
+test('tools/call against a hung server rejects within the configured timeout', async () => {
+    connection = await McplServerConnection.connect(config({ requestTimeoutMs: 250 }), HOST_CAPS);
+    connection.ready();
+    const started = Date.now();
+    await assert.rejects(connection.sendToolsCall('stuck', {}), (err) => {
+        assert.match(err.message, /did not respond to tools\/call/);
+        assert.match(err.message, /250ms/);
+        assert.match(err.message, /hung/);
+        return true;
+    });
+    const elapsed = Date.now() - started;
+    assert.ok(elapsed >= 200 && elapsed < 5000, `rejected in ${elapsed}ms (expected ~250ms)`);
+    // The connection survives the abandoned request: a request the server DOES
+    // answer still works afterwards.
+    const list = await connection.sendToolsList();
+    assert.equal(list.tools[0]?.name, 'stuck');
+});
+test('a request the server answers in time is unaffected by the timeout', async () => {
+    connection = await McplServerConnection.connect(config({ requestTimeoutMs: 2000 }), HOST_CAPS);
+    connection.ready();
+    const list = await connection.sendToolsList();
+    assert.equal(list.tools.length, 1);
+});
+test('requestTimeoutMs: 0 disables the per-request watchdog', async () => {
+    connection = await McplServerConnection.connect(config({ requestTimeoutMs: 0 }), HOST_CAPS);
+    connection.ready();
+    let settled = false;
+    const call = connection.sendToolsCall('stuck', {}).catch(() => { }).finally(() => { settled = true; });
+    await new Promise((r) => setTimeout(r, 300));
+    assert.equal(settled, false, 'with timeout disabled the request stays pending');
+    // Cleanup: closing the connection rejects the pending request.
+    await connection.close();
+    connection = null;
+    await call;
+    assert.equal(settled, true);
+});
+test('the timeout error warns the model the tool may have completed server-side', async () => {
+    connection = await McplServerConnection.connect(config({ requestTimeoutMs: 150 }), HOST_CAPS);
+    connection.ready();
+    await assert.rejects(connection.sendToolsCall('stuck', {}), (err) => {
+        // The model reads this string; it must not imply the call was cancelled.
+        assert.match(err.message, /may still have completed server-side/);
+        assert.match(err.message, /verify state before retrying/);
+        return true;
+    });
+});
+test('a timed-out request that later receives a response does not crash (orphaned response ignored)', async () => {
+    // Server that answers tools/call after 500ms — beyond a 100ms timeout.
+    const SLOW_SERVER = HUNG_SERVER.replace('// tools/call: deliberately NO response, connection stays open.', "else if (m.method === 'tools/call') setTimeout(() => reply({ content: [] }), 500);");
+    connection = await McplServerConnection.connect({ id: 'slow', command: process.execPath, args: ['-e', SLOW_SERVER], requestTimeoutMs: 100 }, HOST_CAPS);
+    connection.ready();
+    await assert.rejects(connection.sendToolsCall('stuck', {}), /did not respond/);
+    // Wait past the server's late response; it must be ignored, not crash.
+    await new Promise((r) => setTimeout(r, 600));
+    const list = await connection.sendToolsList();
+    assert.equal(list.tools.length, 1);
+});
+test('a late STATEFUL orphaned response is surfaced via mcpl:orphaned-response (not silently dropped)', async () => {
+    // Server answers tools/call after 500ms with a checkpoint-carrying result —
+    // beyond a 100ms timeout. The host advanced no checkpoint; the server did.
+    // That divergence must be greppable, so the connection emits an event.
+    const STATEFUL_SLOW = HUNG_SERVER.replace('// tools/call: deliberately NO response, connection stays open.', "else if (m.method === 'tools/call') setTimeout(() => reply({ content: [], state: { checkpoint: 'cp-late', data: { n: 1 } } }), 500);");
+    connection = await McplServerConnection.connect({ id: 'slow-stateful', command: process.execPath, args: ['-e', STATEFUL_SLOW], requestTimeoutMs: 100 }, HOST_CAPS);
+    connection.ready();
+    const orphaned = [];
+    connection.on('orphaned-response', (info) => orphaned.push(info));
+    await assert.rejects(connection.sendToolsCall('stuck', {}), /did not respond/);
+    await new Promise((r) => setTimeout(r, 600));
+    assert.equal(orphaned.length, 1, 'the dropped stateful response must be surfaced');
+    assert.equal(orphaned[0].hadState, true, 'the event records that state was carried');
+    // The connection still works afterwards.
+    const list = await connection.sendToolsList();
+    assert.equal(list.tools.length, 1);
+});
+//# sourceMappingURL=mcpl-request-timeout.test.js.map

package/dist/test/mcpl-request-timeout.test.js.map

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

package/dist/test/mcpl-runtime-lifecycle.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Runtime MCPL server lifecycle — connectMcplServer / disconnectMcplServer /
+ * restartMcplServer on a live framework, including lazy MCPL subsystem
+ * initialization when the framework started with zero configured servers.
+ */
+export {};
+//# sourceMappingURL=mcpl-runtime-lifecycle.test.d.ts.map

package/dist/test/mcpl-runtime-lifecycle.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpl-runtime-lifecycle.test.d.ts","sourceRoot":"","sources":["../../test/mcpl-runtime-lifecycle.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/test/mcpl-runtime-lifecycle.test.js

@@ -0,0 +1,142 @@
+/**
+ * Runtime MCPL server lifecycle — connectMcplServer / disconnectMcplServer /
+ * restartMcplServer on a live framework, including lazy MCPL subsystem
+ * initialization when the framework started with zero configured servers.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { tmpdir } from 'node:os';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { WebSocketServer } from 'ws';
+import { AgentFramework } from '../src/index.js';
+import { MockMembrane } from './helpers/mock-membrane.js';
+// A tiny stdio MCPL server (same shape as mcpl-ws-transport.test.ts): reads
+// NDJSON on stdin, answers initialize / tools/list / tools/call on stdout.
+const STDIO_SERVER = `
+let buf = '';
+process.stdin.on('data', (c) => {
+  buf += c.toString('utf8');
+  let i;
+  while ((i = buf.indexOf('\\n')) >= 0) {
+    const line = buf.slice(0, i); buf = buf.slice(i + 1);
+    if (!line.trim()) continue;
+    let m; try { m = JSON.parse(line); } catch { continue; }
+    const reply = (result) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: m.id, result }) + '\\n');
+    if (m.method === 'initialize') reply({ capabilities: { experimental: { mcpl: { version: '0.4', pushEvents: true } } } });
+    else if (m.method === 'tools/list') reply({ tools: [{ name: 'echo', description: 'e', inputSchema: { type: 'object' } }] });
+    else if (m.method === 'tools/call') reply({ content: [{ type: 'text', text: String((m.params && m.params.arguments && m.params.arguments.text) || '') }] });
+  }
+});
+`;
+function serverConfig(id, extra) {
+    return { id, command: process.execPath, args: ['-e', STDIO_SERVER], ...extra };
+}
+async function withFramework(withServer, fn) {
+    const tempDir = mkdtempSync(join(tmpdir(), 'mcpl-lifecycle-'));
+    const membrane = new MockMembrane();
+    const framework = await AgentFramework.create({
+        storePath: join(tempDir, 'test.chronicle'),
+        membrane: membrane.asMembrane(),
+        agents: [{ name: 'assistant', model: 'test-model', systemPrompt: 'test' }],
+        modules: [],
+        ...(withServer ? { mcplServers: [serverConfig('first')] } : {}),
+    });
+    try {
+        await fn(framework);
+    }
+    finally {
+        await framework.stop();
+        rmSync(tempDir, { recursive: true, force: true });
+    }
+}
+test('connectMcplServer lazily initializes MCPL on a zero-server framework and exposes tools', async () => {
+    await withFramework(false, async (framework) => {
+        assert.deepEqual(framework.listMcplServers(), [], 'no servers configured at start');
+        await framework.connectMcplServer(serverConfig('dyn'));
+        const servers = framework.listMcplServers();
+        assert.equal(servers.length, 1);
+        assert.equal(servers[0].id, 'dyn');
+        assert.equal(servers[0].connected, true);
+        assert.equal(servers[0].toolCount, 1);
+        const toolNames = framework.getAllTools().map(t => t.name);
+        assert.ok(toolNames.includes('mcpl--dyn--echo'), `expected mcpl--dyn--echo in ${toolNames}`);
+    });
+});
+test('disconnectMcplServer removes the server and its tools', async () => {
+    await withFramework(true, async (framework) => {
+        assert.ok(framework.getAllTools().some(t => t.name === 'mcpl--first--echo'), 'startup server tools present');
+        await framework.disconnectMcplServer('first');
+        assert.deepEqual(framework.listMcplServers(), [], 'server gone from list');
+        assert.ok(!framework.getAllTools().some(t => t.name.startsWith('mcpl--first--')), 'tools removed after disconnect');
+    });
+});
+test('restartMcplServer respawns the server and keeps tools available', async () => {
+    await withFramework(true, async (framework) => {
+        await framework.restartMcplServer('first');
+        const servers = framework.listMcplServers();
+        assert.equal(servers.length, 1);
+        assert.equal(servers[0].connected, true);
+        assert.equal(servers[0].toolCount, 1);
+        assert.ok(framework.getAllTools().some(t => t.name === 'mcpl--first--echo'));
+    });
+});
+test('restartMcplServer accepts an updated config (new toolPrefix)', async () => {
+    await withFramework(true, async (framework) => {
+        await framework.restartMcplServer('first', serverConfig('first', { toolPrefix: 'renamed' }));
+        const toolNames = framework.getAllTools().map(t => t.name);
+        assert.ok(toolNames.includes('renamed--echo'), `expected renamed--echo in ${toolNames}`);
+        assert.ok(!toolNames.some(n => n.startsWith('mcpl--first--')), 'old prefix gone');
+    });
+});
+test('connectMcplServer rejects a duplicate id and a colliding prefix', async () => {
+    await withFramework(true, async (framework) => {
+        await assert.rejects(framework.connectMcplServer(serverConfig('first')), /already registered/);
+        await assert.rejects(framework.connectMcplServer(serverConfig('second', { toolPrefix: 'mcpl--first' })), /collides with server "first"/);
+    });
+});
+test('connectMcplServer hot-connects a network-only (WebSocket) MCPL server', async () => {
+    // Minimal in-process MCPL server over WebSocket (same shape as
+    // mcpl-ws-transport.test.ts) — no child process involved.
+    const wss = new WebSocketServer({ port: 0, host: '127.0.0.1' });
+    wss.on('connection', (ws) => {
+        ws.on('message', (data) => {
+            let msg;
+            try {
+                msg = JSON.parse(String(data));
+            }
+            catch {
+                return;
+            }
+            const reply = (result) => ws.send(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result }));
+            if (msg.method === 'initialize')
+                reply({ capabilities: { experimental: { mcpl: { version: '0.4', pushEvents: true } } } });
+            else if (msg.method === 'tools/list')
+                reply({ tools: [{ name: 'echo', description: 'e', inputSchema: { type: 'object' } }] });
+        });
+    });
+    await new Promise((resolve) => (wss.address() ? resolve() : wss.once('listening', () => resolve())));
+    const url = `ws://127.0.0.1:${wss.address().port}/mcpl`;
+    try {
+        await withFramework(false, async (framework) => {
+            await framework.connectMcplServer({ id: 'netsrv', url });
+            const servers = framework.listMcplServers();
+            assert.equal(servers.length, 1);
+            assert.equal(servers[0].connected, true);
+            assert.equal(servers[0].url, url);
+            assert.ok(framework.getAllTools().some(t => t.name === 'mcpl--netsrv--echo'));
+            await framework.disconnectMcplServer('netsrv');
+            assert.ok(!framework.getAllTools().some(t => t.name.startsWith('mcpl--netsrv--')));
+        });
+    }
+    finally {
+        wss.close();
+    }
+});
+test('disconnecting an unknown server is a no-op (routing state cleared, no throw)', async () => {
+    await withFramework(true, async (framework) => {
+        await framework.disconnectMcplServer('nope');
+        assert.equal(framework.listMcplServers().length, 1, 'existing server untouched');
+    });
+});
+//# sourceMappingURL=mcpl-runtime-lifecycle.test.js.map

package/dist/test/mcpl-runtime-lifecycle.test.js.map

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

package/dist/test/mcpl-ws-transport.test.d.ts

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

package/dist/test/mcpl-ws-transport.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpl-ws-transport.test.d.ts","sourceRoot":"","sources":["../../test/mcpl-ws-transport.test.ts"],"names":[],"mappings":""}