mcp-tenant-lib 0.3.3 → 0.3.5

package/dist/channel-tools.js

@@ -34,9 +34,17 @@ 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.', {}, async () => {
-        const ids = [...tenants.keys()];
-        return { content: [{ type: 'text', text: JSON.stringify(ids, null, 2) }] };
+        '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 ' +

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/manifest-tools.js

@@ -25,6 +25,12 @@ function manifestEntryToZodShape(entry) {
     return shape;
 }
 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 ' +
+    '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 ' +
@@ -111,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;
@@ -122,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 });
                 }
@@ -131,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();
@@ -147,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/tenant.d.ts

@@ -56,6 +56,16 @@ export declare class Tenant<TSchema, TValues> {
      * list_fields read should be able to see that they're done.
      */
     submitted: boolean;
+    /**
+     * Timestamp of the most recent real edit to `store` (a field value
+     * changing) or a successfully-applied `restoreState` (see below) —
+     * distinct from `lastActivityAt`, which also counts reads/pings and
+     * drives idle-sweep instead. Used solely to arbitrate `resync` messages
+     * (ws.ts) when more than one browser tab reconnects to the same
+     * recreated tenant: whichever tab's last edit is newer wins, rather than
+     * whichever tab's resync happens to reach the server first.
+     */
+    lastStateChangeAt: number;
     wsClients: Set<WebSocket>;
     connections: Map<string, TenantConnection>;
     lastActivityAt: number;
@@ -127,10 +137,39 @@ 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;
     applyState(schema: TSchema, values: TValues): void;
+    /**
+     * Restores schema/values/submitted from a browser page's own live state
+     * after this tenant was recreated empty (see the `recreated` init flag in
+     * ws.ts) — unlike applyState (used by define_form to redefine a form),
+     * this preserves `submitted` as reported by the page rather than always
+     * resetting it, since a resync is recovering prior state, not starting a
+     * new round.
+     *
+     * `changedAt` is the pushing page's own last-local-edit timestamp
+     * (Date.now() when the user or agent last changed a field in that tab —
+     * see mcp-form's client). When two tabs both reconnect to the same
+     * recreated tenant, each pushes its own resync independently; without
+     * this guard, whichever happens to reach the server first would win,
+     * which has nothing to do with which tab actually has the fresher data.
+     * Comparing against `lastStateChangeAt` (bumped by every real edit,
+     * including a previously-applied resync) means an older resync arriving
+     * after a newer one — or after the tenant was already touched some other
+     * way, e.g. an agent's set_field — is ignored rather than clobbering it.
+     * Returns whether the resync was applied.
+     */
+    restoreState(schema: TSchema, values: TValues, submitted: boolean, changedAt: number): boolean;
     broadcastReinit(): void;
     broadcastUpdate(field: string, value: unknown): void;
     dispose(): void;

package/dist/tenant.js

@@ -59,6 +59,16 @@ export class Tenant {
      * list_fields read should be able to see that they're done.
      */
     submitted = false;
+    /**
+     * Timestamp of the most recent real edit to `store` (a field value
+     * changing) or a successfully-applied `restoreState` (see below) —
+     * distinct from `lastActivityAt`, which also counts reads/pings and
+     * drives idle-sweep instead. Used solely to arbitrate `resync` messages
+     * (ws.ts) when more than one browser tab reconnects to the same
+     * recreated tenant: whichever tab's last edit is newer wins, rather than
+     * whichever tab's resync happens to reach the server first.
+     */
+    lastStateChangeAt = 0;
     wsClients;
     connections = new Map();
     #legacyManifest;
@@ -102,7 +112,7 @@ export class Tenant {
     constructor(id, initialSchema, initialValues) {
         this.id = id;
         this.schema = initialSchema;
-        this.store = new Store(initialValues);
+        this.store = new Store(initialValues); // placeholder; #attachStore below wires the real onChange listener
         this.submitBus = new EventEmitter();
         this.submitBus.setMaxListeners(0);
         this.submitBus.on('newListener', (event) => {
@@ -117,7 +127,7 @@ export class Tenant {
         });
         this.wsClients = new Set();
         this.lastActivityAt = Date.now();
-        this.store.onChange((field, value) => this.broadcastUpdate(field, value));
+        this.#attachStore(this.store);
     }
     /**
      * Legacy/no-WS path: registers a manifest with no real connection behind
@@ -261,6 +271,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)
@@ -278,14 +302,51 @@ export class Tenant {
     touch() {
         this.lastActivityAt = Date.now();
     }
+    #attachStore(store) {
+        this.store = store;
+        this.store.onChange((field, value) => {
+            this.lastStateChangeAt = Date.now();
+            this.broadcastUpdate(field, value);
+        });
+    }
     applyState(schema, values) {
         this.store.dispose();
         this.schema = schema;
-        this.store = new Store(values);
+        this.#attachStore(new Store(values));
         this.submitted = false;
-        this.store.onChange((field, value) => this.broadcastUpdate(field, value));
         this.broadcastReinit();
     }
+    /**
+     * Restores schema/values/submitted from a browser page's own live state
+     * after this tenant was recreated empty (see the `recreated` init flag in
+     * ws.ts) — unlike applyState (used by define_form to redefine a form),
+     * this preserves `submitted` as reported by the page rather than always
+     * resetting it, since a resync is recovering prior state, not starting a
+     * new round.
+     *
+     * `changedAt` is the pushing page's own last-local-edit timestamp
+     * (Date.now() when the user or agent last changed a field in that tab —
+     * see mcp-form's client). When two tabs both reconnect to the same
+     * recreated tenant, each pushes its own resync independently; without
+     * this guard, whichever happens to reach the server first would win,
+     * which has nothing to do with which tab actually has the fresher data.
+     * Comparing against `lastStateChangeAt` (bumped by every real edit,
+     * including a previously-applied resync) means an older resync arriving
+     * after a newer one — or after the tenant was already touched some other
+     * way, e.g. an agent's set_field — is ignored rather than clobbering it.
+     * Returns whether the resync was applied.
+     */
+    restoreState(schema, values, submitted, changedAt) {
+        if (changedAt < this.lastStateChangeAt)
+            return false;
+        this.store.dispose();
+        this.schema = schema;
+        this.#attachStore(new Store(values));
+        this.submitted = submitted;
+        this.lastStateChangeAt = changedAt;
+        this.broadcastReinit();
+        return true;
+    }
     broadcastReinit() {
         const payload = JSON.stringify({ type: 'reinit', schema: this.schema, state: this.store.snapshot(), waiting: this.waiting, submitted: this.submitted });
         for (const client of this.wsClients) {

package/dist/types.d.ts

@@ -4,7 +4,14 @@ export interface SubmitPayload {
     [field: string]: unknown;
 }
 export type ServerMessage<TSchema = unknown, TValues = unknown> = {
-    type: 'init' | 'reinit';
+    type: 'init';
+    schema: TSchema;
+    state: TValues;
+    waiting: boolean;
+    submitted: boolean;
+    recreated: boolean;
+} | {
+    type: 'reinit';
     schema: TSchema;
     state: TValues;
     waiting: boolean;
@@ -16,12 +23,40 @@ export type ServerMessage<TSchema = unknown, TValues = unknown> = {
 } | {
     type: 'waiting';
     waiting: boolean;
+} | {
+    type: 'identify';
+    label?: string;
 } | CallMessage;
 export interface SetMessage {
     type: 'set';
     field: string;
     value: unknown;
 }
+/**
+ * Sent by a page that reconnects to a tenant the server reports as
+ * `recreated` (see the `init` message) — i.e. the in-memory tenant was
+ * lost, most commonly an MCP server restart, while this page's own JS
+ * runtime (and therefore its last-known schema/values) survived because
+ * the tab itself never reloaded. Lets the still-live browser page push its
+ * state back up as the source of truth instead of accepting the server's
+ * freshly-recreated default state. The server applies it via the same
+ * path as define_form (Tenant.applyState) and rebroadcasts `reinit` to any
+ * other connected tabs.
+ */
+export interface ResyncMessage<TSchema = unknown, TValues = unknown> {
+    type: 'resync';
+    schema: TSchema;
+    values: TValues;
+    submitted: boolean;
+    /**
+     * The pushing page's own last-local-edit timestamp (Date.now()) — lets
+     * the server arbitrate when two tabs both resync the same recreated
+     * tenant, favoring whichever has the more recently edited data rather
+     * than whichever resync message happens to arrive first. See
+     * Tenant.restoreState in mcp-tenant-lib for the comparison.
+     */
+    changedAt: number;
+}
 export interface SubmitMessage {
     type: 'submit';
 }
@@ -90,4 +125,4 @@ export interface RenameConnectionMessage {
     type: 'rename_connection';
     appLabel: string;
 }
-export type ClientMessage = SetMessage | SubmitMessage | InterruptMessage | RegisterToolsMessage | CallResultMessage | RenameConnectionMessage;
+export type ClientMessage = SetMessage | SubmitMessage | InterruptMessage | RegisterToolsMessage | CallResultMessage | RenameConnectionMessage | ResyncMessage;

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)`);
@@ -51,7 +60,7 @@ export function attachWebSocketServer(httpServer, port, initialSchema, initialVa
             if (state)
                 state.isAlive = true;
         });
-        ws.send(JSON.stringify({ type: 'init', schema: t.schema, state: t.store.snapshot(), waiting: t.waiting, submitted: t.submitted }));
+        ws.send(JSON.stringify({ type: 'init', schema: t.schema, state: t.store.snapshot(), waiting: t.waiting, submitted: t.submitted, recreated }));
         ws.on('message', (raw) => {
             t.touch();
             let msg;
@@ -83,6 +92,12 @@ export function attachWebSocketServer(httpServer, port, initialSchema, initialVa
                 else
                     t.resolveCall(msg.id, msg.result);
             }
+            if (msg.type === 'resync') {
+                const applied = t.restoreState(msg.schema, msg.values, msg.submitted, msg.changedAt);
+                console.error(applied
+                    ? `[ws] resync from connection=${connectionId}: restoring tenant "${tenantId}" state pushed back by the browser`
+                    : `[ws] resync from connection=${connectionId}: ignored — tenant "${tenantId}" already has state at least as recent`);
+            }
         });
         ws.on('close', (code, reason) => {
             console.error(`[ws] connection closed: tenant=${tenantId} connection=${connectionId} code=${code} reason=${reason.toString() || '(none)'}`);

package/package.json

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