mcp-tenant-lib 0.1.2 → 0.3.4

package/dist/channel-search.d.ts

@@ -0,0 +1,17 @@
+export interface ChannelMatch {
+    name: string;
+    score: number;
+}
+/**
+ * Scores one candidate channel name against a query, case-insensitively:
+ * the best of (a) whole-string typo tolerance, (b) whole-string stem match,
+ * and (c) the best per-word score against the candidate's underscore/
+ * hyphen-split words (catches "pets" -> "pet_food_memory" via "pet", and
+ * "pests" -> "pets_discussion" via a length-gated typo match on "pets").
+ */
+export declare function scoreChannelMatch(query: string, candidate: string): number;
+/**
+ * Ranks every candidate against the query, highest score first, keeping
+ * only matches above `minScore` (default 0.5).
+ */
+export declare function findChannelMatches(query: string, candidates: string[], minScore?: number): ChannelMatch[];

package/dist/channel-search.js

@@ -0,0 +1,80 @@
+import { distance } from 'fastest-levenshtein';
+/**
+ * Splits a channel name into its underscore/hyphen-delimited words, e.g.
+ * "pet_food_memory" -> ["pet", "food", "memory"]. Used so a query like
+ * "pets" can match "pet_food_memory" via the shared word "pet" even though
+ * the two full strings have a large edit distance overall.
+ */
+function words(name) {
+    return name.split(/[_-]+/).filter(Boolean);
+}
+/**
+ * Typo-tolerance score for two strings of similar length/spelling — 1 for
+ * identical, decreasing with edit distance relative to length. This is
+ * deliberately NOT used to compare unrelated short words against each other
+ * (see stemScore) — two coincidentally-similar-length words like "pets" and
+ * "prefs" have a small edit distance purely by chance, which this alone
+ * cannot tell apart from an actual typo of the same word.
+ */
+function typoScore(a, b) {
+    const maxLen = Math.max(a.length, b.length);
+    if (maxLen === 0)
+        return 1;
+    return 1 - distance(a, b) / maxLen;
+}
+/**
+ * Stem/prefix match score: how much of the shorter string is a literal
+ * prefix of the longer one, e.g. "pet" is a full-length prefix of "pets" ->
+ * strong match. Zero if neither is a prefix of the other at all — this is
+ * an intentionally strict, high-precision signal (no edit-distance fuzz),
+ * so it doesn't fire on coincidences the way typoScore can.
+ */
+function stemScore(a, b) {
+    const [shorter, longer] = a.length <= b.length ? [a, b] : [b, a];
+    if (shorter.length < 3 || !longer.startsWith(shorter))
+        return 0;
+    return shorter.length / longer.length;
+}
+/**
+ * Per-word score: the best of a strict stem match (see stemScore) and a
+ * typo-tolerant match that only kicks in when the query and word are close
+ * enough in length that a real typo is plausible (within 2 characters) —
+ * this catches "pests" -> "pets" (one transposed letter, same length).
+ * Known limitation: two short, unrelated, similar-length words (e.g.
+ * "pets" vs "prefs") can still score moderately via this path — there's no
+ * algorithmic way to distinguish "typo of the same word" from "coincidence"
+ * at that length. In practice this only surfaces as a low-ranked also-ran
+ * behind any genuine stem match, and callers (see channel-tools.ts's
+ * channel_find description) are told to disambiguate on close scores
+ * rather than blindly trust the top result.
+ */
+function wordScore(query, word) {
+    const stem = stemScore(query, word);
+    if (Math.abs(query.length - word.length) > 2)
+        return stem;
+    return Math.max(stem, typoScore(query, word));
+}
+/**
+ * Scores one candidate channel name against a query, case-insensitively:
+ * the best of (a) whole-string typo tolerance, (b) whole-string stem match,
+ * and (c) the best per-word score against the candidate's underscore/
+ * hyphen-split words (catches "pets" -> "pet_food_memory" via "pet", and
+ * "pests" -> "pets_discussion" via a length-gated typo match on "pets").
+ */
+export function scoreChannelMatch(query, candidate) {
+    const q = query.toLowerCase();
+    const c = candidate.toLowerCase();
+    const whole = Math.max(typoScore(q, c), stemScore(q, c));
+    const perWord = words(c).map((w) => wordScore(q, w));
+    return Math.max(whole, ...perWord, 0);
+}
+/**
+ * Ranks every candidate against the query, highest score first, keeping
+ * only matches above `minScore` (default 0.5).
+ */
+export function findChannelMatches(query, candidates, minScore = 0.5) {
+    return candidates
+        .map((name) => ({ name, score: scoreChannelMatch(query, name) }))
+        .filter((m) => m.score >= minScore)
+        .sort((a, b) => b.score - a.score);
+}

package/dist/channel-tools.d.ts

@@ -0,0 +1,12 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Tenant } from './tenant.js';
+/**
+ * Registers `join_channel` and `list_channels` on an MCP server built via
+ * buildMcpServer. Shared across every mcp-tenant-lib consumer (mcp-form,
+ * js-bridge-mcp, ...) so the tool behavior/wording stays identical rather
+ * than reimplemented per package.
+ *
+ * `tenant`/`setChannel`/`port` are exactly what registerFn (see mcp.ts)
+ * receives — pass them straight through from there.
+ */
+export declare function registerChannelTools<TSchema, TValues>(mcp: McpServer, tenant: () => Tenant<TSchema, TValues>, port: number, setChannel: (id: string) => void, initialSchema: TSchema, initialValues: TValues): void;

package/dist/channel-tools.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { tenants, getOrCreateTenant, isValidChannelName } from './tenant.js';
+import { findChannelMatches } from './channel-search.js';
+/**
+ * Registers `join_channel` and `list_channels` on an MCP server built via
+ * buildMcpServer. Shared across every mcp-tenant-lib consumer (mcp-form,
+ * js-bridge-mcp, ...) so the tool behavior/wording stays identical rather
+ * than reimplemented per package.
+ *
+ * `tenant`/`setChannel`/`port` are exactly what registerFn (see mcp.ts)
+ * receives — pass them straight through from there.
+ */
+export function registerChannelTools(mcp, tenant, port, setChannel, initialSchema, initialValues) {
+    mcp.tool('join_channel', 'Names (or rejoins) a channel: a persistent, agent-chosen identity for this session\'s live state, shared ' +
+        'with any other session that joins the same name. DEFAULT TO CALLING THIS as one of your first actions, ' +
+        'with a name derived from the topic at hand (e.g. a request about "pets" → join_channel("pets")) — not ' +
+        'something reserved for when you happen to think of it. Until called, a session sits on the shared, ' +
+        'anonymous "default" channel, visible to every other unnamed session on this server — skip only when the ' +
+        'user says it\'s a one-off/throwaway, or nothing suggests a distinct topic worth naming. Reusing an ' +
+        'existing name is expected, not an error: it retargets this session onto that channel\'s live state (e.g. ' +
+        'to resume, or redefine/refresh it). Names are URL-safe slugs: letters, digits, underscore, hyphen only.', { channel: z.string().describe('Agent-chosen channel name, e.g. "pets" or "pet_questions_1_of_2". Letters/digits/underscore/hyphen only.') }, async ({ channel }) => {
+        if (!isValidChannelName(channel)) {
+            return {
+                content: [{ type: 'text', text: `Error: "${channel}" is not a valid channel name — use only letters, digits, underscore, and hyphen.` }],
+                isError: true,
+            };
+        }
+        getOrCreateTenant(channel, initialSchema, initialValues);
+        setChannel(channel);
+        return {
+            content: [{ type: 'text', text: `Joined channel "${channel}" — http://localhost:${port}/t/${channel}` }],
+        };
+    });
+    mcp.tool('list_channels', 'Lists every channel currently live on this server, including "default" (the shared, anonymous channel ' +
+        'sessions land on before calling join_channel). Use this to discover an existing named channel before ' +
+        'calling join_channel on it, e.g. when a human refers to "the pets form" without giving the exact channel ' +
+        'name. Each entry includes a `connections` array — one item per live browser tab/page bridged into that ' +
+        'channel, with its display `label` and `toolCount` — so you can tell which channels actually have ' +
+        'something connected without joining each one to check.', {}, async () => {
+        const channels = [...tenants.entries()].map(([channel, t]) => ({
+            channel,
+            connections: [...t.connections.values()].map((c) => ({
+                label: c.label ?? null,
+                toolCount: c.manifest.length,
+            })),
+        }));
+        return { content: [{ type: 'text', text: JSON.stringify(channels, null, 2) }] };
+    });
+    mcp.tool('channel_find', 'Fuzzy-searches existing channel names for ones matching a loose query — use this when a human refers to ' +
+        'a channel by topic or partial name (e.g. "the pets channel") rather than its exact name, instead of ' +
+        'guessing at join_channel or falling back to eyeballing the full list_channels output yourself. Matches on ' +
+        'both whole-name similarity (catches typos) and per-word similarity against underscore/hyphen-split parts ' +
+        'of each name (catches "pets" matching "pet_food_memory" via the shared word "pet"). Returns a ranked list ' +
+        'of {name, score} (score 0..1, higher is better) — empty if nothing scores above the threshold. Read-only: ' +
+        'does NOT join or create anything, even on an exact match. Given the result(s), call join_channel yourself ' +
+        'on whichever one is actually right — if there\'s one clear best match, use it directly; if several score ' +
+        'closely, ask the user to disambiguate rather than guessing.', { query: z.string().describe('Loose/partial channel name or topic to search for, e.g. "pets".') }, async ({ query }) => {
+        const matches = findChannelMatches(query, [...tenants.keys()]);
+        return { content: [{ type: 'text', text: JSON.stringify(matches, null, 2) }] };
+    });
+}

package/dist/client-bridge.d.ts

@@ -36,6 +36,8 @@ export interface StateSocketHandlers<TSchema, TValues> {
     onCall?(id: string, name: string, args: unknown): void;
     onConnect?(): void;
     onDisconnect?(): void;
+    /** Server-pushed "identify yourself" signal (see identify_connection tool). Defaults to a window.alert(). */
+    onIdentify?(label: string | undefined): void;
 }
 export interface StateSocketOptions {
     /**

package/dist/client-bridge.js

@@ -30,10 +30,22 @@ export function createClientBridge(actions) {
         },
     };
 }
+/** Steady-state delay between reconnect attempts once the connection drops. */
+const RECONNECT_INTERVAL_MS = 10_000;
+/**
+ * How long to keep retrying at RECONNECT_INTERVAL_MS before giving up
+ * entirely. A dropped connection is usually the server restarting (or a
+ * laptop sleeping) rather than something permanent, and unknown named
+ * tenants are now recreated on demand server-side (see ws.ts) rather than
+ * rejected — so it's worth retrying for a long while rather than a few
+ * seconds, without retrying literally forever if the server is gone for good.
+ */
+const RECONNECT_GIVE_UP_MS = 60 * 60 * 1000;
 export function connectStateSocket(handlers, options = {}) {
     let ws;
     let closedByCaller = false;
     let reconnectAttempts = 0;
+    let firstDisconnectAt;
     const connect = () => {
         const tenantId = options.tenant ?? (location.pathname.startsWith('/t/')
             ? location.pathname.slice('/t/'.length).split('/')[0]
@@ -48,6 +60,7 @@ export function connectStateSocket(handlers, options = {}) {
         ws.onopen = () => {
             console.log(`[mcp-ws] connected${reconnectAttempts > 0 ? ` after ${reconnectAttempts} reconnect attempt(s)` : ''}`);
             reconnectAttempts = 0;
+            firstDisconnectAt = undefined;
             handlers.onConnect?.();
         };
         ws.onclose = (event) => {
@@ -56,12 +69,17 @@ export function connectStateSocket(handlers, options = {}) {
             if (closedByCaller)
                 return;
             if (event.code === 4404) {
-                console.log('[mcp-ws] tenant unknown/expired (4404) — not retrying');
+                console.log('[mcp-ws] invalid tenant id (4404) — not retrying');
+                return;
+            }
+            firstDisconnectAt ??= Date.now();
+            if (Date.now() - firstDisconnectAt > RECONNECT_GIVE_UP_MS) {
+                console.log(`[mcp-ws] giving up after retrying for over ${RECONNECT_GIVE_UP_MS / 60_000} minutes`);
                 return;
             }
             reconnectAttempts++;
-            console.log(`[mcp-ws] retrying in 2s (attempt ${reconnectAttempts + 1})`);
-            setTimeout(connect, 2000);
+            console.log(`[mcp-ws] retrying in ${RECONNECT_INTERVAL_MS / 1000}s (attempt ${reconnectAttempts + 1})`);
+            setTimeout(connect, RECONNECT_INTERVAL_MS);
         };
         ws.onerror = () => {
             console.log('[mcp-ws] socket error (see close event for details)');
@@ -76,6 +94,12 @@ export function connectStateSocket(handlers, options = {}) {
                 handlers.onUpdate?.(msg.field, msg.value);
             if (msg.type === 'call')
                 handlers.onCall?.(msg.id, msg.name, msg.args);
+            if (msg.type === 'identify') {
+                if (handlers.onIdentify)
+                    handlers.onIdentify(msg.label);
+                else
+                    alert(`Identify: this is the "${msg.label ?? 'unlabeled'}" connection`);
+            }
         };
     };
     connect();

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep } from './tenant.js';
+export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName } from './tenant.js';
 export { buildMcpServer, type RegisterToolsFn, type McpServerIdentity } from './mcp.js';
 export { createHttpServer, type CreateHttpServerOptions } from './http.js';
 export { attachWebSocketServer } from './ws.js';
 export { createManifestToolRegistry, type ManifestToolRegistry } from './manifest-tools.js';
+export { registerChannelTools } from './channel-tools.js';
+export { findChannelMatches, scoreChannelMatch, type ChannelMatch } from './channel-search.js';
 export * from './types.js';

package/dist/index.js

@@ -1,6 +1,8 @@
-export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep } from './tenant.js';
+export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName } from './tenant.js';
 export { buildMcpServer } from './mcp.js';
 export { createHttpServer } from './http.js';
 export { attachWebSocketServer } from './ws.js';
 export { createManifestToolRegistry } from './manifest-tools.js';
+export { registerChannelTools } from './channel-tools.js';
+export { findChannelMatches, scoreChannelMatch } from './channel-search.js';
 export * from './types.js';

package/dist/manifest-tools.js

@@ -25,7 +25,13 @@ function manifestEntryToZodShape(entry) {
     return shape;
 }
 const DESCRIBE_TOOLS_NAME = 'describe_tools';
-const DESCRIBE_TOOLS_DESCRIPTION = 'Returns manifest-level context for the tools this connected page registered: a ' +
+const IDENTIFY_CONNECTION_NAME = 'identify_connection';
+const IDENTIFY_CONNECTION_DESCRIPTION = 'Pops an alert in the browser tab behind one connection, so a human looking at several open tabs/windows ' +
+    'can tell which one this session means. Use when the user has multiple tabs bridged in and asks "which one ' +
+    'is X" or you need them to look at a specific one. Pass the connection `id` from describe_tools\' ' +
+    '`connections` array (single-connection channels can omit it). Fire-and-forget: returns immediately, does ' +
+    'not confirm the human saw it.';
+const DESCRIBE_TOOLS_DESCRIPTION = 'Returns manifest-level context for the tools connected to THIS SESSION\'S CURRENT CHANNEL: a ' +
     'page-authored summary (what kind of page/app this is, cross-tool sequencing rules, ' +
     'domain concepts) plus the current list of tool names and one-line descriptions. Call ' +
     'this once after connecting, before calling any other tool from this page, so you have ' +
@@ -33,7 +39,11 @@ const DESCRIBE_TOOLS_DESCRIPTION = 'Returns manifest-level context for the tools
     'pages/tabs are connected to this session at once, tool names are prefixed per ' +
     'connection (e.g. "formalin__submit_form", "htmlpaint__clear_canvas") and this tool\'s ' +
     'response includes a `connections` array listing each connection\'s id, label, and ' +
-    'prefix — call it whenever you\'re unsure which prefix routes to which tab.';
+    'prefix — call it whenever you\'re unsure which prefix routes to which tab. ' +
+    'IMPORTANT — an empty or unexpected result here does NOT mean no page is bridged: this session may ' +
+    'simply be on the wrong channel (see join_channel). If the user expects a specific bridged app/page by ' +
+    'name (e.g. "the bulletino tab") and it\'s missing, call list_channels to check for a matching channel ' +
+    'and join_channel to it before assuming nothing is connected.';
 /**
  * Derives a stable, unique tool-name prefix per connection: sanitized from
  * `label` (falling back to "tab" when absent or empty after sanitizing),
@@ -107,6 +117,24 @@ export function createManifestToolRegistry(mcp, tenant) {
         });
         handles.set(DESCRIBE_TOOLS_NAME, handle);
     }
+    function registerIdentifyConnection() {
+        const handle = mcp.registerTool(IDENTIFY_CONNECTION_NAME, {
+            description: IDENTIFY_CONNECTION_DESCRIPTION,
+            inputSchema: { id: z.string().optional().describe('Connection id from describe_tools\' `connections` array. Omit when only one connection is live.') },
+        }, async ({ id }) => {
+            const t = tenant();
+            const targetId = id ?? [...t.connections.keys()][0];
+            if (!targetId) {
+                return { content: [{ type: 'text', text: 'No live connection on this channel to identify.' }], isError: true };
+            }
+            const ok = t.identifyConnection(targetId);
+            return {
+                content: [{ type: 'text', text: ok ? `Identify signal sent to connection "${targetId}".` : `Connection "${targetId}" is not currently open.` }],
+                isError: !ok,
+            };
+        });
+        handles.set(IDENTIFY_CONNECTION_NAME, handle);
+    }
     function sync() {
         const conns = [...tenant().connections.values()];
         const multi = conns.length >= 2;
@@ -118,7 +146,7 @@ export function createManifestToolRegistry(mcp, tenant) {
         if (multi) {
             for (const conn of conns) {
                 for (const entry of conn.manifest) {
-                    if (entry.name === DESCRIBE_TOOLS_NAME)
+                    if (entry.name === DESCRIBE_TOOLS_NAME || entry.name === IDENTIFY_CONNECTION_NAME)
                         continue;
                     registeredNow.set(`${slugFor.get(conn.id)}__${entry.name}`, { connectionId: conn.id, entry });
                 }
@@ -127,14 +155,15 @@ export function createManifestToolRegistry(mcp, tenant) {
         else {
             const conn = conns[0];
             for (const entry of tenant().toolManifest) {
-                if (entry.name === DESCRIBE_TOOLS_NAME)
+                if (entry.name === DESCRIBE_TOOLS_NAME || entry.name === IDENTIFY_CONNECTION_NAME)
                     continue;
                 registeredNow.set(entry.name, { connectionId: conn?.id, entry });
             }
         }
-        // A page tool named "describe_tools" would collide with the fixed tool
-        // below - the fixed one always wins so agents can rely on the name.
-        const currentNames = new Set([DESCRIBE_TOOLS_NAME, ...registeredNow.keys()]);
+        // Page tools named "describe_tools"/"identify_connection" would collide
+        // with the fixed tools below - the fixed ones always win so agents can
+        // rely on the name.
+        const currentNames = new Set([DESCRIBE_TOOLS_NAME, IDENTIFY_CONNECTION_NAME, ...registeredNow.keys()]);
         for (const [name, handle] of handles) {
             if (!currentNames.has(name)) {
                 handle.remove();
@@ -143,6 +172,8 @@ export function createManifestToolRegistry(mcp, tenant) {
         }
         if (!handles.has(DESCRIBE_TOOLS_NAME))
             registerDescribeTools();
+        if (!handles.has(IDENTIFY_CONNECTION_NAME))
+            registerIdentifyConnection();
         for (const [registeredName, { connectionId, entry }] of registeredNow) {
             if (handles.has(registeredName))
                 continue;

package/dist/mcp.d.ts

@@ -1,8 +1,17 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { Tenant } from './tenant.js';
-export type RegisterToolsFn<TSchema = any, TValues = any> = (mcp: McpServer, tenant: () => Tenant<TSchema, TValues>, port: number) => void;
+export type RegisterToolsFn<TSchema = any, TValues = any> = (mcp: McpServer, tenant: () => Tenant<TSchema, TValues>, port: number, setChannel: (id: string) => void) => void;
 export interface McpServerIdentity {
     name: string;
     version: string;
 }
+/**
+ * `tenantId` is only the session's bootstrap identity — a private id minted
+ * before any tool call has happened, so before an agent could have chosen a
+ * channel name (see channel-tools.ts). It is NOT fixed for the session's
+ * lifetime: `setChannel` (passed into `registerFn`, typically wired to a
+ * `join_channel` tool) reassigns which tenant `tenant()` resolves to from
+ * that point on, so a session can retarget itself onto an agent-named,
+ * cross-session-shared channel after connecting.
+ */
 export declare function buildMcpServer<TSchema, TValues>(identity: McpServerIdentity, tenantId: string, getTenant: (id: string) => Tenant<TSchema, TValues>, port: number, registerFn: RegisterToolsFn<TSchema, TValues>): McpServer;

package/dist/mcp.js

@@ -1,7 +1,18 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * `tenantId` is only the session's bootstrap identity — a private id minted
+ * before any tool call has happened, so before an agent could have chosen a
+ * channel name (see channel-tools.ts). It is NOT fixed for the session's
+ * lifetime: `setChannel` (passed into `registerFn`, typically wired to a
+ * `join_channel` tool) reassigns which tenant `tenant()` resolves to from
+ * that point on, so a session can retarget itself onto an agent-named,
+ * cross-session-shared channel after connecting.
+ */
 export function buildMcpServer(identity, tenantId, getTenant, port, registerFn) {
     const mcp = new McpServer(identity);
-    const tenant = () => getTenant(tenantId);
-    registerFn(mcp, tenant, port);
+    let currentTenantId = tenantId;
+    const tenant = () => getTenant(currentTenantId);
+    const setChannel = (id) => { currentTenantId = id; };
+    registerFn(mcp, tenant, port, setChannel);
     return mcp;
 }

package/dist/tenant.d.ts

@@ -127,6 +127,14 @@ export declare class Tenant<TSchema, TValues> {
      * self-contained and cheap for the rare/short-lived window it's used in.
      */
     private waitForReconnect;
+    /**
+     * Pushes an 'identify' message at one connection so its page can surface
+     * something a human watching the browser will notice (alert/sound) — lets
+     * an agent say "which tab is this" when several are bridged into one
+     * channel. Fire-and-forget like rename_connection: no ack, and silently
+     * a no-op if the connection has since closed.
+     */
+    identifyConnection(connectionId: string): boolean;
     resolveCall(id: string, result: unknown): void;
     rejectCall(id: string, error: string): void;
     touch(): void;
@@ -135,8 +143,15 @@ export declare class Tenant<TSchema, TValues> {
     broadcastUpdate(field: string, value: unknown): void;
     dispose(): void;
 }
+/**
+ * URL-safe slug rule for agent-chosen channel names (see channel-tools.ts):
+ * letters, digits, underscore, hyphen only. Channel names become part of the
+ * form URL path (`/t/<id>`), so anything requiring percent-encoding is
+ * rejected up front rather than silently mangled.
+ */
+declare function isValidChannelName(id: string): boolean;
 declare const tenants: Map<string, Tenant<any, any>>;
 declare function getOrCreateTenant<TSchema, TValues>(id: string, initialSchema: TSchema, initialValues: TValues): Tenant<TSchema, TValues>;
 declare function disposeTenant(id: string): void;
 declare function startIdleSweep(onSweep: (id: string) => void): NodeJS.Timeout;
-export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep };
+export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName };

package/dist/tenant.js

@@ -261,6 +261,20 @@ export class Tenant {
             poll();
         });
     }
+    /**
+     * Pushes an 'identify' message at one connection so its page can surface
+     * something a human watching the browser will notice (alert/sound) — lets
+     * an agent say "which tab is this" when several are bridged into one
+     * channel. Fire-and-forget like rename_connection: no ack, and silently
+     * a no-op if the connection has since closed.
+     */
+    identifyConnection(connectionId) {
+        const conn = this.connections.get(connectionId);
+        if (!conn || conn.socket.readyState !== conn.socket.OPEN)
+            return false;
+        conn.socket.send(JSON.stringify({ type: 'identify', label: conn.label }));
+        return true;
+    }
     resolveCall(id, result) {
         const pending = this.pendingCalls.get(id);
         if (!pending)
@@ -325,6 +339,15 @@ export class Tenant {
         this.connections.clear();
     }
 }
+/**
+ * URL-safe slug rule for agent-chosen channel names (see channel-tools.ts):
+ * letters, digits, underscore, hyphen only. Channel names become part of the
+ * form URL path (`/t/<id>`), so anything requiring percent-encoding is
+ * rejected up front rather than silently mangled.
+ */
+function isValidChannelName(id) {
+    return /^[a-zA-Z0-9_-]+$/.test(id);
+}
 const tenants = new Map();
 function getOrCreateTenant(id, initialSchema, initialValues) {
     let tenant = tenants.get(id);
@@ -345,7 +368,7 @@ function envMs(name, defaultMs) {
     const n = Number(raw);
     return Number.isFinite(n) && n > 0 ? n : defaultMs;
 }
-const TENANT_IDLE_TIMEOUT_MS = envMs('TENANT_IDLE_TIMEOUT_MS', 30 * 60 * 1000);
+const TENANT_IDLE_TIMEOUT_MS = envMs('TENANT_IDLE_TIMEOUT_MS', 2 * 60 * 60 * 1000);
 const TENANT_SWEEP_INTERVAL_MS = envMs('TENANT_SWEEP_INTERVAL_MS', 5 * 60 * 1000);
 function startIdleSweep(onSweep) {
     const sweepInterval = setInterval(() => {
@@ -362,4 +385,4 @@ function startIdleSweep(onSweep) {
     sweepInterval.unref();
     return sweepInterval;
 }
-export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep };
+export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName };

package/dist/types.d.ts

@@ -16,6 +16,9 @@ export type ServerMessage<TSchema = unknown, TValues = unknown> = {
 } | {
     type: 'waiting';
     waiting: boolean;
+} | {
+    type: 'identify';
+    label?: string;
 } | CallMessage;
 export interface SetMessage {
     type: 'set';

package/dist/ws.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { WebSocketServer } from 'ws';
-import { getOrCreateTenant, tenants } from './tenant.js';
+import { getOrCreateTenant, tenants, isValidChannelName } from './tenant.js';
 /**
  * Ping interval for the liveness check below. Half-open sockets (client
  * process killed/suspended without a clean TCP close — the common case for
@@ -32,16 +32,25 @@ export function attachWebSocketServer(httpServer, port, initialSchema, initialVa
     wss.on('connection', (ws, req) => {
         const wsUrl = new URL(req.url ?? '/', `http://localhost:${port}`);
         const requestedTenantId = wsUrl.searchParams.get('tenant');
-        if (requestedTenantId && !tenants.has(requestedTenantId)) {
-            // An explicit tenant was requested but no longer exists (for example
-            // because its MCP session was disposed). Reject instead of silently
-            // falling back to the shared default tenant.
-            console.error(`[ws] rejected connection: unknown/expired tenant "${requestedTenantId}"`);
-            ws.close(4404, 'Unknown or expired tenant');
+        if (requestedTenantId && !isValidChannelName(requestedTenantId)) {
+            // Never silently vivify a channel from a malformed/hostile id — same
+            // validation join_channel applies agent-side.
+            console.error(`[ws] rejected connection: invalid tenant id "${requestedTenantId}"`);
+            ws.close(4404, 'Invalid tenant id');
             return;
         }
         const tenantId = requestedTenantId || 'default';
+        const recreated = !!requestedTenantId && !tenants.has(requestedTenantId);
         const t = getOrCreateTenant(tenantId, initialSchema, initialValues);
+        if (recreated) {
+            // A page reconnecting (browser retry loop) to a named channel that no
+            // longer exists server-side — most commonly a server restart, which
+            // wipes the in-memory tenants map entirely. Recreate it on demand
+            // rather than rejecting, so the page keeps working and an agent can
+            // rejoin the same name later instead of the connection being stuck
+            // retrying forever against a channel the server will never revive.
+            console.error(`[ws] recreated previously unknown/expired tenant "${tenantId}" on reconnect`);
+        }
         const connectionId = randomUUID();
         t.registerConnection(connectionId, ws);
         console.error(`[ws] connection opened: tenant=${tenantId} connection=${connectionId} (${t.connections.size} connection(s) on tenant)`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-tenant-lib",
-  "version": "0.1.2",
+  "version": "0.3.4",
   "type": "module",
   "description": "Generic tenant/session bookkeeping + MCP wiring, reusable across projects.",
   "repository": {
@@ -35,6 +35,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
+    "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
     "zod": "^3.23.8"
   },