mcp-tenant-lib 0.3.5 → 0.3.7

package/dist/channel-tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { tenants, getOrCreateTenant, isValidChannelName } from './tenant.js';
 import { findChannelMatches } from './channel-search.js';
+import { buildDescribePayload } from './manifest-tools.js';
 /**
  * Registers `join_channel` and `list_channels` on an MCP server built via
  * buildMcpServer. Shared across every mcp-tenant-lib consumer (mcp-form,
@@ -18,7 +19,8 @@ export function registerChannelTools(mcp, tenant, port, setChannel, initialSchem
         '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 }) => {
+        'to resume, or redefine/refresh it). Names are URL-safe slugs: letters, digits, underscore, hyphen only. ' +
+        'To only inspect a channel\'s tools without retargeting this session onto it, use describe_channel instead.', { 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.` }],
@@ -32,11 +34,11 @@ export function registerChannelTools(mcp, tenant, port, setChannel, initialSchem
         };
     });
     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 () => {
+        'sessions land on before calling join_channel). Use this to discover an existing named channel, 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. To see the ' +
+        'actual tools on one, call describe_channel rather than joining just to look.', {}, async () => {
         const channels = [...tenants.entries()].map(([channel, t]) => ({
             channel,
             connections: [...t.connections.values()].map((c) => ({
@@ -58,4 +60,22 @@ export function registerChannelTools(mcp, tenant, port, setChannel, initialSchem
         const matches = findChannelMatches(query, [...tenants.keys()]);
         return { content: [{ type: 'text', text: JSON.stringify(matches, null, 2) }] };
     });
+    mcp.tool('describe_channel', 'Returns the tool manifest for a named channel — same payload as describe_tools, but for ANY channel, ' +
+        'not just the one this session is currently on. Use this to go straight from a channel name (e.g. from ' +
+        'list_channels or channel_find) to what tools it has, without join_channel first retargeting this ' +
+        'session\'s own state onto it. Read-only: does not join, create, or affect this session\'s current ' +
+        'channel. Errors if the channel does not exist yet — check list_channels/channel_find first. If a tool ' +
+        'listed here fails to invoke with "No such tool available" (typically right after the MCP server ' +
+        'process was restarted), your MCP client\'s own connection is stale, not this manifest — tell the user ' +
+        'to reconnect the MCP client (e.g. /mcp in Claude Code) rather than retrying the call.', { channel: z.string().describe('Exact channel name, e.g. from list_channels or channel_find.') }, async ({ channel }) => {
+        const t = tenants.get(channel);
+        if (!t) {
+            return {
+                content: [{ type: 'text', text: `Error: no channel named "${channel}" — use list_channels or channel_find to find the right name.` }],
+                isError: true,
+            };
+        }
+        const payload = buildDescribePayload(t);
+        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    });
 }

package/dist/dashboard.d.ts

@@ -0,0 +1,33 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface DashboardConnection {
+    id: string;
+    label: string | null;
+    toolCount: number;
+    summary: string | null;
+}
+export interface DashboardChannel {
+    channel: string;
+    lastActivityAt: number;
+    connections: DashboardConnection[];
+}
+/**
+ * Flat snapshot of every live tenant ("channel" in agent-facing language)
+ * and its connections — the same data list_channels/describe_channel expose
+ * to MCP tools, reshaped for a human-facing dashboard. Rebuilt fresh on
+ * every call rather than cached: cheap (iterates in-memory maps only), and
+ * avoids a second source of truth to keep in sync with `tenants`.
+ */
+export declare function buildDashboardSnapshot(): DashboardChannel[];
+/**
+ * Handles the three dashboard HTTP routes against a raw node http.Server,
+ * the same low-level style createHttpServer (http.ts) already uses (no
+ * Express dependency in this package). Returns true if the request was
+ * handled (caller should stop routing further), false if the path/method
+ * didn't match anything here.
+ *
+ * Mount this ahead of static file serving in the consuming package's own
+ * request handler, e.g.:
+ *
+ *   if (handleDashboardRoutes(req, res)) return;
+ */
+export declare function handleDashboardRoutes(req: IncomingMessage, res: ServerResponse, port: number): boolean;

package/dist/dashboard.js

@@ -0,0 +1,74 @@
+import { tenants, dashboardEvents } from './tenant.js';
+/**
+ * Flat snapshot of every live tenant ("channel" in agent-facing language)
+ * and its connections — the same data list_channels/describe_channel expose
+ * to MCP tools, reshaped for a human-facing dashboard. Rebuilt fresh on
+ * every call rather than cached: cheap (iterates in-memory maps only), and
+ * avoids a second source of truth to keep in sync with `tenants`.
+ */
+export function buildDashboardSnapshot() {
+    return [...tenants.entries()]
+        .map(([channel, t]) => ({
+        channel,
+        lastActivityAt: t.lastActivityAt,
+        connections: [...t.connections.values()].map((c) => ({
+            id: c.id,
+            label: c.label ?? null,
+            toolCount: c.manifest.length,
+            summary: c.summary ?? null,
+        })),
+    }))
+        .sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+}
+/**
+ * Handles the three dashboard HTTP routes against a raw node http.Server,
+ * the same low-level style createHttpServer (http.ts) already uses (no
+ * Express dependency in this package). Returns true if the request was
+ * handled (caller should stop routing further), false if the path/method
+ * didn't match anything here.
+ *
+ * Mount this ahead of static file serving in the consuming package's own
+ * request handler, e.g.:
+ *
+ *   if (handleDashboardRoutes(req, res)) return;
+ */
+export function handleDashboardRoutes(req, res, port) {
+    const url = new URL(req.url ?? '/', `http://localhost:${port}`);
+    if (url.pathname === '/api/dashboard' && req.method === 'GET') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(buildDashboardSnapshot()));
+        return true;
+    }
+    // Server-sent-events stream: pushes a fresh full snapshot immediately on
+    // connect, then again every time dashboardEvents fires (a connection
+    // opened/closed, a manifest changed, a channel was created/disposed) — see
+    // tenant.ts's notifyDashboard call sites. No diffing: the snapshot is
+    // small (one row per channel/connection) and a full replace is simpler
+    // and less bug-prone client-side than patching.
+    if (url.pathname === '/api/dashboard/stream' && req.method === 'GET') {
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+        });
+        const send = () => res.write(`data: ${JSON.stringify(buildDashboardSnapshot())}\n\n`);
+        send();
+        dashboardEvents.on('change', send);
+        req.on('close', () => dashboardEvents.off('change', send));
+        return true;
+    }
+    // Triggers identifyConnection on one connection — the dashboard's "which
+    // tab is this" button, same underlying mechanism as the identify_connection
+    // MCP tool (manifest-tools.ts), just reachable from a human clicking
+    // instead of an agent calling a tool.
+    const identifyMatch = url.pathname.match(/^\/api\/dashboard\/channels\/([^/]+)\/connections\/([^/]+)\/identify$/);
+    if (identifyMatch && req.method === 'POST') {
+        const [, channel, connectionId] = identifyMatch;
+        const t = tenants.get(decodeURIComponent(channel));
+        const ok = t?.identifyConnection(decodeURIComponent(connectionId)) ?? false;
+        res.writeHead(ok ? 200 : 404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok }));
+        return true;
+    }
+    return false;
+}

package/dist/http.d.ts

@@ -28,5 +28,20 @@ export interface CreateHttpServerOptions<TSchema, TValues> {
      *   to the previous one.
      */
     defaultTenantMode?: 'per-session' | 'shared';
+    /**
+     * Extra static asset roots served ahead of `staticDir`, keyed by URL path
+     * prefix. Two shapes:
+     *  - A directory-style prefix (e.g. `{ '/dashboard': '.../dist/dashboard' }`)
+     *    resolves requests under it relative to that directory, falling back
+     *    to `index.html` for the bare prefix or a `/`-suffixed request — same
+     *    convention as `staticDir`. Lets a consumer ship a second, independent
+     *    static app (e.g. a monitoring dashboard) without colliding with
+     *    `staticDir`'s own `index.html`.
+     *  - A single-file prefix with an extension (e.g. `{ '/main.js': '.../dist/client' }`)
+     *    serves exactly that one file (`dir/main.js`) for a request matching
+     *    the prefix exactly — for a fixed-URL asset other pages already
+     *    reference by that path regardless of what's mounted at `/`.
+     */
+    extraStaticMounts?: Record<string, string>;
 }
-export declare function createHttpServer<TSchema, TValues>({ port, staticDir, initialSchema, initialValues, identity, registerFn, defaultTenantMode }: CreateHttpServerOptions<TSchema, TValues>): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+export declare function createHttpServer<TSchema, TValues>({ port, staticDir, initialSchema, initialValues, identity, registerFn, defaultTenantMode, extraStaticMounts }: CreateHttpServerOptions<TSchema, TValues>): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;

package/dist/http.js

@@ -6,11 +6,18 @@ import { randomUUID } from 'node:crypto';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { getOrCreateTenant } from './tenant.js';
 import { buildMcpServer } from './mcp.js';
+import { handleDashboardRoutes } from './dashboard.js';
 const UPLOAD_DIR = path.join(os.tmpdir(), 'mcp-form-uploads');
 fs.mkdirSync(UPLOAD_DIR, { recursive: true });
-const mime = { '.html': 'text/html', '.js': 'text/javascript', '.json': 'application/json' };
+const mime = {
+    '.html': 'text/html',
+    '.js': 'text/javascript',
+    '.json': 'application/json',
+    '.css': 'text/css',
+    '.svg': 'image/svg+xml',
+};
 const sessions = new Map();
-export function createHttpServer({ port, staticDir, initialSchema, initialValues, identity, registerFn, defaultTenantMode = 'per-session' }) {
+export function createHttpServer({ port, staticDir, initialSchema, initialValues, identity, registerFn, defaultTenantMode = 'per-session', extraStaticMounts = {} }) {
     const getTenant = (id) => {
         const t = getOrCreateTenant(id, initialSchema, initialValues);
         t.touch();
@@ -96,6 +103,8 @@ export function createHttpServer({ port, staticDir, initialSchema, initialValues
             res.end('Unknown session');
             return;
         }
+        if (url.pathname.startsWith('/api/dashboard') && handleDashboardRoutes(req, res, port))
+            return;
         if (url.pathname === '/upload' && req.method === 'POST') {
             const contentType = req.headers['content-type'] ?? '';
             const boundaryMatch = contentType.match(/boundary=(.+)$/);
@@ -143,8 +152,27 @@ export function createHttpServer({ port, staticDir, initialSchema, initialValues
         if (pathname.startsWith('/t/')) {
             pathname = '/';
         }
-        let filePath = pathname === '/' ? '/index.html' : pathname;
-        filePath = path.join(staticDir, filePath);
+        const mountEntry = Object.entries(extraStaticMounts).find(([prefix]) => pathname === prefix || pathname.startsWith(`${prefix}/`));
+        let filePath;
+        if (mountEntry) {
+            const [prefix, dir] = mountEntry;
+            if (path.extname(prefix)) {
+                // A prefix with a file extension (e.g. "/main.js") is a single-file
+                // mount — `dir` is that file's parent directory, and any request
+                // exactly matching `prefix` resolves straight to it, no index.html
+                // fallback. Lets a consumer serve one fixed-URL asset (e.g. an
+                // embed script referenced by other pages as "<server>/main.js")
+                // from a build directory that also happens to hold other files.
+                filePath = path.join(dir, path.basename(prefix));
+            }
+            else {
+                const rest = pathname.slice(prefix.length);
+                filePath = path.join(dir, rest === '' || rest === '/' ? '/index.html' : rest);
+            }
+        }
+        else {
+            filePath = path.join(staticDir, pathname === '/' ? '/index.html' : pathname);
+        }
         fs.readFile(filePath, (err, data) => {
             if (err) {
                 res.writeHead(404);

package/dist/index.d.ts

@@ -1,8 +1,10 @@
-export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName } from './tenant.js';
+export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName, sanitizeChannelName, dashboardEvents } 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 { handleDashboardRoutes, buildDashboardSnapshot, type DashboardChannel, type DashboardConnection } from './dashboard.js';
 export { findChannelMatches, scoreChannelMatch, type ChannelMatch } from './channel-search.js';
+export { enablePersistence } from './persistence.js';
 export * from './types.js';

package/dist/index.js

@@ -1,8 +1,10 @@
-export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName } from './tenant.js';
+export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName, sanitizeChannelName, dashboardEvents } 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 { handleDashboardRoutes, buildDashboardSnapshot } from './dashboard.js';
 export { findChannelMatches, scoreChannelMatch } from './channel-search.js';
+export { enablePersistence } from './persistence.js';
 export * from './types.js';

package/dist/manifest-tools.d.ts

@@ -4,6 +4,33 @@ export interface ManifestToolRegistry {
     handles: Map<string, RegisteredTool>;
     sync(): void;
 }
+/**
+ * Same shape describe_tools returns for the caller's own current channel,
+ * built from any Tenant — shared with describe_channel (channel-tools.ts)
+ * so a channel's manifest can be inspected by name without join_channel
+ * retargeting the session onto it first.
+ */
+export declare function buildDescribePayload<TSchema, TValues>(t: Tenant<TSchema, TValues>): {
+    summary: string | null;
+    tools: {
+        name: string;
+        description: string;
+    }[];
+    connections?: undefined;
+} | {
+    connections: {
+        id: string;
+        label: string | null;
+        toolPrefix: string | undefined;
+        summary: string | null;
+        tools: {
+            name: string;
+            description: string;
+        }[];
+    }[];
+    summary?: undefined;
+    tools?: undefined;
+};
 /**
  * Registers one MCP tool per entry in tenant().toolManifest, dispatching
  * calls to the page via tenant().call(target, args). Also always registers

package/dist/manifest-tools.js

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+class UnsupportedParamTypeError extends Error {
+}
 function paramSpecToZod(spec) {
     let schema;
     switch (spec.type) {
@@ -11,7 +13,7 @@ function paramSpecToZod(spec) {
         case 'boolean':
             schema = z.boolean();
             break;
-        default: throw new Error(`unsupported param type "${spec.type}" (supported: string, number, boolean)`);
+        default: throw new UnsupportedParamTypeError(`unsupported param type "${spec.type}" (supported: string, number, boolean)`);
     }
     if (spec.description)
         schema = schema.describe(spec.description);
@@ -24,6 +26,34 @@ function manifestEntryToZodShape(entry) {
     }
     return shape;
 }
+/**
+ * Same shape describe_tools returns for the caller's own current channel,
+ * built from any Tenant — shared with describe_channel (channel-tools.ts)
+ * so a channel's manifest can be inspected by name without join_channel
+ * retargeting the session onto it first.
+ */
+export function buildDescribePayload(t) {
+    const conns = [...t.connections.values()];
+    if (conns.length <= 1) {
+        return {
+            summary: t.toolManifestSummary ?? null,
+            tools: t.toolManifest.map((e) => ({ name: e.name, description: e.description })),
+        };
+    }
+    const slugFor = computeSlugs(conns);
+    return {
+        connections: conns.map((c) => ({
+            id: c.id,
+            label: c.label ?? null,
+            toolPrefix: slugFor.get(c.id),
+            summary: c.summary ?? null,
+            tools: c.manifest.map((e) => ({
+                name: `${slugFor.get(c.id)}__${e.name}`,
+                description: e.description,
+            })),
+        })),
+    };
+}
 const DESCRIBE_TOOLS_NAME = 'describe_tools';
 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 ' +
@@ -43,7 +73,10 @@ const DESCRIBE_TOOLS_DESCRIPTION = 'Returns manifest-level context for the tools
     '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.';
+    'and join_channel to it before assuming nothing is connected. If a tool listed here instead fails to ' +
+    'invoke with "No such tool available" (typically right after the MCP server process was restarted), ' +
+    'your MCP client\'s own connection is stale, not this manifest — tell the user to reconnect the MCP ' +
+    'client (e.g. /mcp in Claude Code) rather than retrying the call.';
 /**
  * Derives a stable, unique tool-name prefix per connection: sanitized from
  * `label` (falling back to "tab" when absent or empty after sanitizing),
@@ -91,28 +124,7 @@ export function createManifestToolRegistry(mcp, tenant) {
     const handles = new Map();
     function registerDescribeTools() {
         const handle = mcp.registerTool(DESCRIBE_TOOLS_NAME, { description: DESCRIBE_TOOLS_DESCRIPTION, inputSchema: {} }, async () => {
-            const t = tenant();
-            const conns = [...t.connections.values()];
-            if (conns.length <= 1) {
-                const payload = {
-                    summary: t.toolManifestSummary ?? null,
-                    tools: t.toolManifest.map((e) => ({ name: e.name, description: e.description })),
-                };
-                return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
-            }
-            const slugFor = computeSlugs(conns);
-            const payload = {
-                connections: conns.map((c) => ({
-                    id: c.id,
-                    label: c.label ?? null,
-                    toolPrefix: slugFor.get(c.id),
-                    summary: c.summary ?? null,
-                    tools: c.manifest.map((e) => ({
-                        name: `${slugFor.get(c.id)}__${e.name}`,
-                        description: e.description,
-                    })),
-                })),
-            };
+            const payload = buildDescribePayload(tenant());
             return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
         });
         handles.set(DESCRIBE_TOOLS_NAME, handle);
@@ -177,7 +189,22 @@ export function createManifestToolRegistry(mcp, tenant) {
         for (const [registeredName, { connectionId, entry }] of registeredNow) {
             if (handles.has(registeredName))
                 continue;
-            const handle = mcp.registerTool(registeredName, { description: entry.description, inputSchema: manifestEntryToZodShape(entry) }, async (args) => {
+            let inputSchema;
+            try {
+                inputSchema = manifestEntryToZodShape(entry);
+            }
+            catch (err) {
+                // A single page-authored tool with a malformed param spec (bad/missing
+                // `type`) must not take down sync() for every other tool on the
+                // channel, nor crash whatever triggered this sync (e.g. join_channel
+                // migrating the registry) — skip just this one entry.
+                if (err instanceof UnsupportedParamTypeError) {
+                    console.error(`[mcp-tenant-lib] skipping tool "${registeredName}": ${err.message}`);
+                    continue;
+                }
+                throw err;
+            }
+            const handle = mcp.registerTool(registeredName, { description: entry.description, inputSchema }, async (args) => {
                 try {
                     const result = await tenant().call(connectionId, entry.name, args);
                     return { content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }] };

package/dist/persistence.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Loads persisted tenant state from `filePath` (if present) and pre-seeds
+ * the shared `tenants` map with it *before* any getOrCreateTenant('default')
+ * call runs at boot — so a server restart comes back up with the last known
+ * form schema/values already in place instead of blank defaults, without
+ * requiring any browser tab to still be open to push a resync (see
+ * Tenant.restoreState in tenant.ts, which only helps if a tab survived the
+ * restart). Returns the set of tenant ids it seeded, purely for logging.
+ *
+ * Then wires a debounced save-on-change: any tenant currently in memory
+ * (present or created afterward) that mutates its store gets its next
+ * snapshot written back within WRITE_DEBOUNCE_MS. Polling `tenants`
+ * directly (rather than requiring every getOrCreateTenant call site to opt
+ * in) means callers of enablePersistence don't need to change how they
+ * create tenants elsewhere in the codebase.
+ */
+export declare function enablePersistence<TSchema, TValues>(filePath: string): {
+    seededIds: string[];
+};

package/dist/persistence.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Tenant, tenants } from './tenant.js';
+/**
+ * Debounce delay between a tenant edit and the write hitting disk. Keeps
+ * rapid-fire field edits (typing in a text input broadcasts on every
+ * keystroke) from turning into one fsync per keystroke, while staying well
+ * under any timeframe a user would notice as "my edit wasn't saved".
+ */
+const WRITE_DEBOUNCE_MS = 500;
+/**
+ * Loads persisted tenant state from `filePath` (if present) and pre-seeds
+ * the shared `tenants` map with it *before* any getOrCreateTenant('default')
+ * call runs at boot — so a server restart comes back up with the last known
+ * form schema/values already in place instead of blank defaults, without
+ * requiring any browser tab to still be open to push a resync (see
+ * Tenant.restoreState in tenant.ts, which only helps if a tab survived the
+ * restart). Returns the set of tenant ids it seeded, purely for logging.
+ *
+ * Then wires a debounced save-on-change: any tenant currently in memory
+ * (present or created afterward) that mutates its store gets its next
+ * snapshot written back within WRITE_DEBOUNCE_MS. Polling `tenants`
+ * directly (rather than requiring every getOrCreateTenant call site to opt
+ * in) means callers of enablePersistence don't need to change how they
+ * create tenants elsewhere in the codebase.
+ */
+export function enablePersistence(filePath) {
+    const seededIds = [];
+    let persisted = {};
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        persisted = JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            console.error(`[persistence] failed to read ${filePath}: ${err.message}`);
+        }
+    }
+    for (const [id, state] of Object.entries(persisted)) {
+        if (tenants.has(id))
+            continue;
+        const tenant = new Tenant(id, state.schema, state.values);
+        tenant.submitted = state.submitted;
+        tenant.lastStateChangeAt = state.lastStateChangeAt;
+        tenant.lastActivityAt = state.lastActivityAt;
+        tenants.set(id, tenant);
+        seededIds.push(id);
+    }
+    const writeToDisk = () => {
+        const out = {};
+        for (const [id, tenant] of tenants) {
+            out[id] = {
+                schema: tenant.schema,
+                values: tenant.store.snapshot(),
+                submitted: tenant.submitted,
+                lastStateChangeAt: tenant.lastStateChangeAt,
+                lastActivityAt: tenant.lastActivityAt,
+            };
+        }
+        try {
+            fs.mkdirSync(path.dirname(filePath), { recursive: true });
+            fs.writeFileSync(filePath, JSON.stringify(out));
+        }
+        catch (err) {
+            console.error(`[persistence] failed to write ${filePath}: ${err.message}`);
+        }
+    };
+    // Polls `lastStateChangeAt` (bumped on every real store edit or applied
+    // resync — see Tenant#attachStore/restoreState) rather than subscribing
+    // to each tenant's `store.onChange`, since define_form/resync/reconnect
+    // all replace `tenant.store` with a brand-new Store (Tenant#attachStore),
+    // which would silently drop a direct subscription. Polling at the same
+    // cadence as the write debounce means a change is never more than one
+    // interval late to be noticed, and comparing against a per-tenant
+    // last-seen timestamp keeps this a no-op when nothing changed.
+    const seen = new Map();
+    for (const [id, tenant] of tenants)
+        seen.set(id, tenant.lastStateChangeAt);
+    const pollInterval = setInterval(() => {
+        let dirty = false;
+        for (const [id, tenant] of tenants) {
+            if (seen.get(id) !== tenant.lastStateChangeAt) {
+                seen.set(id, tenant.lastStateChangeAt);
+                dirty = true;
+            }
+        }
+        for (const id of seen.keys()) {
+            if (!tenants.has(id)) {
+                seen.delete(id);
+                dirty = true;
+            } // tenant disposed (idle sweep)
+        }
+        if (dirty)
+            writeToDisk();
+    }, WRITE_DEBOUNCE_MS);
+    pollInterval.unref();
+    return { seededIds };
+}

package/dist/tenant.d.ts

@@ -1,6 +1,17 @@
 import { EventEmitter } from 'node:events';
 import type { WebSocket } from 'ws';
 import type { ToolManifestEntry } from './types.js';
+/**
+ * Fires whenever the *shape* of the tenants map changes in a way a
+ * dashboard/monitoring view would care about: a tenant created/disposed, a
+ * connection opening/closing, or a connection's manifest/label changing.
+ * Deliberately does NOT fire on ordinary state (Store) changes or waiting/
+ * submitted flips — those are per-tenant form data, not "who's connected."
+ * One process-wide emitter (not per-tenant) so a single dashboard SSE
+ * stream can subscribe once for every channel rather than one listener per
+ * tenant. See dashboard.ts for the consumer.
+ */
+export declare const dashboardEvents: EventEmitter<[never]>;
 /**
  * One WS connection's own tool manifest/summary/label, addressable
  * independently of other connections sharing the same tenant (e.g. two
@@ -181,8 +192,24 @@ export declare class Tenant<TSchema, TValues> {
  * rejected up front rather than silently mangled.
  */
 declare function isValidChannelName(id: string): boolean;
+/**
+ * Best-effort fixup for a browser-supplied channel name that fails
+ * isValidChannelName — collapses any run of disallowed characters (spaces,
+ * punctuation, etc.) into a single underscore and trims leading/trailing
+ * underscores, e.g. "bulletino 222aaa" -> "bulletino_222aaa". Used only on
+ * the WS connect path (ws.ts): a human renaming a bridged tab via a plain
+ * `prompt()` has no reason to know or care about the exact slug rule, so
+ * silently coercing their input into something valid is friendlier than a
+ * hard 4404 reject with no recovery. Deliberately NOT applied to
+ * join_channel (channel-tools.ts) — that's agent-driven, the tool
+ * description already states the rule up front, and an agent silently
+ * landing on a DIFFERENT name than it asked for is more likely to cause
+ * confusion (e.g. mismatched describe_channel lookups) than a clear
+ * rejection it can self-correct from.
+ */
+declare function sanitizeChannelName(id: string): string;
 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, isValidChannelName };
+export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName, sanitizeChannelName };

package/dist/tenant.js

@@ -1,5 +1,20 @@
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
+/**
+ * Fires whenever the *shape* of the tenants map changes in a way a
+ * dashboard/monitoring view would care about: a tenant created/disposed, a
+ * connection opening/closing, or a connection's manifest/label changing.
+ * Deliberately does NOT fire on ordinary state (Store) changes or waiting/
+ * submitted flips — those are per-tenant form data, not "who's connected."
+ * One process-wide emitter (not per-tenant) so a single dashboard SSE
+ * stream can subscribe once for every channel rather than one listener per
+ * tenant. See dashboard.ts for the consumer.
+ */
+export const dashboardEvents = new EventEmitter();
+dashboardEvents.setMaxListeners(0);
+function notifyDashboard() {
+    dashboardEvents.emit('change');
+}
 /**
  * How long Tenant.call waits for some connection to reappear on a tenant
  * before giving up, when the connection it was targeting has already
@@ -144,6 +159,7 @@ export class Tenant {
     registerConnection(id, socket) {
         this.connections.set(id, { id, socket, manifest: [], summary: undefined, label: undefined });
         this.wsClients.add(socket);
+        notifyDashboard();
     }
     updateConnectionManifest(id, manifest, summary, label) {
         const conn = this.connections.get(id);
@@ -174,6 +190,7 @@ export class Tenant {
             this.wsClients.delete(conn.socket);
         this.connections.delete(id);
         this.syncManifestToolRegistries();
+        notifyDashboard();
     }
     addManifestToolRegistry(registry) {
         this.#manifestToolRegistries.add(registry);
@@ -185,6 +202,7 @@ export class Tenant {
     syncManifestToolRegistries() {
         for (const registry of this.#manifestToolRegistries)
             registry.sync();
+        notifyDashboard();
     }
     /**
      * `connectionId` targets the call at one specific connection's socket —
@@ -395,18 +413,38 @@ export class Tenant {
 function isValidChannelName(id) {
     return /^[a-zA-Z0-9_-]+$/.test(id);
 }
+/**
+ * Best-effort fixup for a browser-supplied channel name that fails
+ * isValidChannelName — collapses any run of disallowed characters (spaces,
+ * punctuation, etc.) into a single underscore and trims leading/trailing
+ * underscores, e.g. "bulletino 222aaa" -> "bulletino_222aaa". Used only on
+ * the WS connect path (ws.ts): a human renaming a bridged tab via a plain
+ * `prompt()` has no reason to know or care about the exact slug rule, so
+ * silently coercing their input into something valid is friendlier than a
+ * hard 4404 reject with no recovery. Deliberately NOT applied to
+ * join_channel (channel-tools.ts) — that's agent-driven, the tool
+ * description already states the rule up front, and an agent silently
+ * landing on a DIFFERENT name than it asked for is more likely to cause
+ * confusion (e.g. mismatched describe_channel lookups) than a clear
+ * rejection it can self-correct from.
+ */
+function sanitizeChannelName(id) {
+    return id.replace(/[^a-zA-Z0-9_-]+/g, '_').replace(/^_+|_+$/g, '');
+}
 const tenants = new Map();
 function getOrCreateTenant(id, initialSchema, initialValues) {
     let tenant = tenants.get(id);
     if (!tenant) {
         tenant = new Tenant(id, initialSchema, initialValues);
         tenants.set(id, tenant);
+        notifyDashboard();
     }
     return tenant;
 }
 function disposeTenant(id) {
     tenants.get(id)?.dispose();
     tenants.delete(id);
+    notifyDashboard();
 }
 function envMs(name, defaultMs) {
     const raw = process.env[name];
@@ -432,4 +470,4 @@ function startIdleSweep(onSweep) {
     sweepInterval.unref();
     return sweepInterval;
 }
-export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName };
+export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName, sanitizeChannelName };

package/dist/ws.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { WebSocketServer } from 'ws';
-import { getOrCreateTenant, tenants, isValidChannelName } from './tenant.js';
+import { getOrCreateTenant, tenants, isValidChannelName, sanitizeChannelName } 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
@@ -31,13 +31,22 @@ export function attachWebSocketServer(httpServer, port, initialSchema, initialVa
     wss.on('close', () => clearInterval(heartbeat));
     wss.on('connection', (ws, req) => {
         const wsUrl = new URL(req.url ?? '/', `http://localhost:${port}`);
-        const requestedTenantId = wsUrl.searchParams.get('tenant');
+        let requestedTenantId = wsUrl.searchParams.get('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;
+            // A browser-supplied name (e.g. a human renaming a bridged tab via a
+            // plain prompt()) has no reason to know the slug rule — coerce it
+            // into something valid rather than rejecting outright, same as
+            // join_channel would reject a raw name but this WS path favors
+            // recovering the connection. Only a genuinely empty result (every
+            // character was disallowed) still gets rejected below.
+            const sanitized = sanitizeChannelName(requestedTenantId);
+            if (!sanitized) {
+                console.error(`[ws] rejected connection: invalid tenant id "${requestedTenantId}" (nothing left after sanitizing)`);
+                ws.close(4404, 'Invalid tenant id');
+                return;
+            }
+            console.error(`[ws] sanitized invalid tenant id "${requestedTenantId}" -> "${sanitized}"`);
+            requestedTenantId = sanitized;
         }
         const tenantId = requestedTenantId || 'default';
         const recreated = !!requestedTenantId && !tenants.has(requestedTenantId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-tenant-lib",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "type": "module",
   "description": "Generic tenant/session bookkeeping + MCP wiring, reusable across projects.",
   "repository": {