@zhin.js/workroom 0.0.0 → 0.0.2

package/lib/room/room-guards.js

@@ -0,0 +1,222 @@
+/**
+ * Room guard components (B4). Pure, independently testable and fail-closed: any internal error, bad
+ * configuration or missing data rejects instead of allowing. Nothing here sends messages or touches the
+ * Bus; C1 wires the decisions into RoomBus / tools / ingress and projects the "@ human" escalation.
+ */
+const WINDOW_MS = 60_000;
+const SWEEP_THRESHOLD = 1024;
+export class RoomGuardRejectedError extends Error {
+    code;
+    retryAfterMs;
+    constructor(code, message, retryAfterMs) {
+        super(message);
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'RoomGuardRejectedError';
+    }
+}
+/**
+ * Counts `task.handoff` events of `taskId` between members `a` and `b` in either direction.
+ * Pure over the journal history, so the result survives restarts and is reproducible.
+ */
+export function countPairHandoffs(events, taskId, a, b) {
+    let count = 0;
+    for (const event of events) {
+        if (event.type !== 'task.handoff' || event.taskId !== taskId)
+            continue;
+        if ((event.from === a && event.to === b) || (event.from === b && event.to === a))
+            count += 1;
+    }
+    return count;
+}
+function positive(name, value, fallback) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new RangeError(`Room guard option ${name} must be a positive integer, got ${String(resolved)}`);
+    }
+    return resolved;
+}
+export function createRoomGuards(options = {}) {
+    const now = options.now ?? (() => Date.now());
+    const maxHandoffDepth = positive('maxHandoffDepth', options.maxHandoffDepth, 8);
+    const maxPingPong = positive('maxPingPong', options.maxPingPong, 3);
+    const maxTurnsPerMinute = positive('maxTurnsPerMinute', options.maxTurnsPerMinute, 12);
+    const maxQueuedTurns = positive('maxQueuedTurns', options.maxQueuedTurns, 8);
+    const { logger } = options;
+    if (options.sensitiveAccounts !== undefined && !Array.isArray(options.sensitiveAccounts)) {
+        throw new TypeError('Room guard option sensitiveAccounts must be an array of account ids');
+    }
+    const sensitive = new Set();
+    for (const account of options.sensitiveAccounts ?? []) {
+        if (typeof account !== 'string')
+            throw new TypeError('Room guard option sensitiveAccounts must contain strings only');
+        const trimmed = account.trim();
+        if (trimmed !== '')
+            sensitive.add(trimmed);
+    }
+    const windows = new Map();
+    const lanes = new Map();
+    const prune = (stamps, at) => {
+        while (stamps.length > 0 && stamps[0] <= at - WINDOW_MS)
+            stamps.shift();
+    };
+    const sweepWindows = (at) => {
+        for (const [room, stamps] of windows) {
+            prune(stamps, at);
+            if (stamps.length === 0)
+                windows.delete(room);
+        }
+    };
+    const guardError = (error) => `guard error: ${error instanceof Error ? error.message : String(error)}`;
+    const admitTurn = (roomId) => {
+        try {
+            if (typeof roomId !== 'string' || roomId === '')
+                throw new TypeError('roomId must be a non-empty string');
+            const at = now();
+            if (!Number.isFinite(at))
+                throw new TypeError('clock returned a non-finite value');
+            if (windows.size >= SWEEP_THRESHOLD)
+                sweepWindows(at);
+            const stamps = windows.get(roomId) ?? [];
+            prune(stamps, at);
+            if (stamps.length >= maxTurnsPerMinute) {
+                windows.set(roomId, stamps);
+                return { allowed: false, code: 'turn_rate', retryAfterMs: Math.max(1, stamps[0] + WINDOW_MS - at) };
+            }
+            stamps.push(at);
+            windows.set(roomId, stamps);
+            return { allowed: true };
+        }
+        catch (error) {
+            logger?.warn(`room turn admission failed closed: ${guardError(error)}`);
+            return { allowed: false, code: 'turn_rate', retryAfterMs: WINDOW_MS };
+        }
+    };
+    const requireHuman = (actor) => actor?.origin === 'human';
+    const authorizeSensitive = (op, actor) => {
+        try {
+            if (!requireHuman(actor))
+                return `${op} requires a human actor`;
+            const account = typeof actor?.accountId === 'string' ? actor.accountId.trim() : '';
+            if (account === '')
+                return `${op} requires an identified account`;
+            if (!sensitive.has(account))
+                return `${op} is not allowed for this account`;
+            return undefined;
+        }
+        catch (error) {
+            return guardError(error);
+        }
+    };
+    return Object.freeze({
+        checkHandoff(input) {
+            try {
+                const { roomId, taskId, from, to, handoffCount, history } = input;
+                if ([roomId, taskId, from, to].some((v) => typeof v !== 'string' || v === '')) {
+                    throw new TypeError('roomId, taskId, from and to must be non-empty strings');
+                }
+                if (!Number.isSafeInteger(handoffCount) || handoffCount < 0) {
+                    throw new TypeError('handoffCount must be a non-negative integer');
+                }
+                if (!Array.isArray(history))
+                    throw new TypeError('history is required');
+                if (handoffCount >= maxHandoffDepth) {
+                    return {
+                        allowed: false, code: 'handoff_depth', escalateToHuman: true,
+                        reason: `task ${taskId} reached the handoff depth limit (${maxHandoffDepth})`,
+                    };
+                }
+                const pair = countPairHandoffs(history, taskId, from, to);
+                if (pair >= maxPingPong) {
+                    return {
+                        allowed: false, code: 'ping_pong', escalateToHuman: true,
+                        reason: `task ${taskId} bounced ${pair} times between ${from} and ${to} (limit ${maxPingPong})`,
+                    };
+                }
+                return { allowed: true };
+            }
+            catch (error) {
+                logger?.warn(`room handoff check failed closed: ${guardError(error)}`);
+                return { allowed: false, code: 'guard_error', escalateToHuman: true, reason: guardError(error) };
+            }
+        },
+        runExclusive(roomId, work) {
+            if (typeof roomId !== 'string' || roomId === '') {
+                return Promise.reject(new RoomGuardRejectedError('guard_error', 'roomId must be a non-empty string'));
+            }
+            const existing = lanes.get(roomId);
+            if (existing && existing.queued.size >= maxQueuedTurns) {
+                return Promise.reject(new RoomGuardRejectedError('queue_full', `room ${roomId} already has ${existing.queued.size} queued turns`));
+            }
+            const admission = admitTurn(roomId);
+            if (!admission.allowed) {
+                return Promise.reject(new RoomGuardRejectedError('turn_rate', `room ${roomId} exceeded ${maxTurnsPerMinute} turns per minute`, admission.retryAfterMs));
+            }
+            const lane = existing ?? { tail: Promise.resolve(), queued: new Set() };
+            if (!existing)
+                lanes.set(roomId, lane);
+            return new Promise((resolve, reject) => {
+                const turn = {
+                    cancelled: false,
+                    controller: new AbortController(),
+                    rejectCancelled: reject,
+                };
+                lane.queued.add(turn);
+                const start = async () => {
+                    lane.queued.delete(turn);
+                    if (turn.cancelled)
+                        throw new RoomGuardRejectedError('cancelled', `room ${roomId} turn was cancelled before it started`);
+                    lane.running = turn;
+                    try {
+                        return await work(turn.controller.signal);
+                    }
+                    finally {
+                        lane.running = undefined;
+                    }
+                };
+                const run = lane.tail.then(start, start);
+                run.then(resolve, reject);
+                const tail = run.catch(() => undefined);
+                lane.tail = tail;
+                void tail.then(() => {
+                    if (lane.tail === tail && lanes.get(roomId) === lane)
+                        lanes.delete(roomId);
+                });
+            });
+        },
+        cancelRoom(roomId, actor) {
+            if (!requireHuman(actor)) {
+                throw new RoomGuardRejectedError('forbidden', 'only a human may cancel a room turn');
+            }
+            const lane = lanes.get(roomId);
+            if (!lane)
+                return { cancelledRunning: false, cancelledQueued: 0 };
+            let cancelledRunning = false;
+            if (lane.running && !lane.running.controller.signal.aborted) {
+                lane.running.controller.abort(new RoomGuardRejectedError('cancelled', `room ${roomId} turn was cancelled by a human`));
+                cancelledRunning = true;
+            }
+            let cancelledQueued = 0;
+            const queueRefusal = authorizeSensitive('room.cancel_queue', actor);
+            if (queueRefusal !== undefined) {
+                if (lane.queued.size === 0)
+                    return { cancelledRunning, cancelledQueued };
+                logger?.warn(`room ${roomId} queue left intact: ${queueRefusal}`);
+                return { cancelledRunning, cancelledQueued, queueRefused: true };
+            }
+            for (const turn of lane.queued) {
+                turn.cancelled = true;
+                turn.controller.abort();
+                turn.rejectCancelled(new RoomGuardRejectedError('cancelled', `room ${roomId} turn was cancelled by a human`));
+                cancelledQueued += 1;
+            }
+            lane.queued.clear();
+            return { cancelledRunning, cancelledQueued };
+        },
+        authorizeSensitive,
+        stats() {
+            return { lanes: lanes.size, rateWindows: windows.size };
+        },
+    });
+}
+//# sourceMappingURL=room-guards.js.map

package/lib/room/room-guards.js.map

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

package/lib/room/room-membership.d.ts

@@ -0,0 +1,15 @@
+import type { RoomMembershipPort } from '@zhin.js/core/runtime';
+import type { RoomRegistry } from './room-registry.js';
+/**
+ * The single factory for core's `RoomMembershipPort`. `hasRoom` and `route` are always provided
+ * together: core only dedups Room conversations when `hasRoom` is true, and without `route` the
+ * Endpoint that loses the dedup would never get its @ / reply / pending interaction resolved.
+ * Do not expose `hasRoom` on its own.
+ *
+ * `hasRoom` is decided per (conversation, receiving Endpoint): it is true only when the Endpoint
+ * that received the copy is a member of the Room bound to the conversation. A non-member Bot in
+ * the same group is treated as being in an ordinary group (it handles its own copy, no claim /
+ * arbitrate / forced mention). `route` applies the same membership check as a second guard.
+ */
+export declare function createRoomMembershipPort(registry: RoomRegistry): RoomMembershipPort;
+//# sourceMappingURL=room-membership.d.ts.map

package/lib/room/room-membership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-membership.d.ts","sourceRoot":"","sources":["../../src/room/room-membership.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,YAAY,GAAG,kBAAkB,CAkBnF"}

package/lib/room/room-membership.js

@@ -0,0 +1,34 @@
+import { routeRoomMessage } from './room-router.js';
+/**
+ * The single factory for core's `RoomMembershipPort`. `hasRoom` and `route` are always provided
+ * together: core only dedups Room conversations when `hasRoom` is true, and without `route` the
+ * Endpoint that loses the dedup would never get its @ / reply / pending interaction resolved.
+ * Do not expose `hasRoom` on its own.
+ *
+ * `hasRoom` is decided per (conversation, receiving Endpoint): it is true only when the Endpoint
+ * that received the copy is a member of the Room bound to the conversation. A non-member Bot in
+ * the same group is treated as being in an ordinary group (it handles its own copy, no claim /
+ * arbitrate / forced mention). `route` applies the same membership check as a second guard.
+ */
+export function createRoomMembershipPort(registry) {
+    const port = {
+        isMember(peer, conversation) {
+            const room = registry.roomOf(conversation);
+            if (!room)
+                return false;
+            return peer.endpointIds.some((endpointId) => room.memberByEndpoint(String(endpointId)) !== undefined);
+        },
+        hasRoom(conversation) {
+            const room = registry.roomOf(conversation);
+            return room !== undefined && room.memberByEndpoint(String(conversation.endpoint.id)) !== undefined;
+        },
+        route(input) {
+            const room = registry.roomOf(input.conversation);
+            if (!room || room.memberByEndpoint(String(input.conversation.endpoint.id)) === undefined)
+                return undefined;
+            return routeRoomMessage(room, input);
+        },
+    };
+    return Object.freeze(port);
+}
+//# sourceMappingURL=room-membership.js.map

package/lib/room/room-membership.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-membership.js","sourceRoot":"","sources":["../../src/room/room-membership.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAsB;IAC7D,MAAM,IAAI,GAAuB;QAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY;YACzB,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;YAC3C,IAAI,CAAC,IAAI;gBAAE,OAAO,KAAK,CAAC;YACxB,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;QACxG,CAAC;QACD,OAAO,CAAC,YAAY;YAClB,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;YAC3C,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC;QACrG,CAAC;QACD,KAAK,CAAC,KAAK;YACT,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YACjD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC3G,OAAO,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvC,CAAC;KACF,CAAC;IACF,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/lib/room/room-registry.d.ts

@@ -0,0 +1,59 @@
+import type { RoomDefinition, RoomMemberDefinition, RoomRoleDefinition } from './room-definition.js';
+/** Minimal conversation shape the registry needs (structurally compatible with core's ConversationRef). */
+export interface RoomConversationLike {
+    readonly endpoint: {
+        readonly adapter: string;
+    };
+    readonly kind: string;
+    readonly id: string;
+    readonly threadId?: string;
+}
+export interface RoomMemberEntry {
+    readonly roomId: string;
+    readonly agent: string;
+    readonly roleName: string;
+    readonly role: RoomRoleDefinition;
+    readonly definition: RoomMemberDefinition;
+    /** Runtime Endpoint id of the member's dedicated Bot. */
+    readonly endpointId: string;
+    /** Agent name and aliases, lower-cased. */
+    readonly names: readonly string[];
+}
+export interface RoomEntry {
+    readonly id: string;
+    readonly definition: RoomDefinition;
+    /** Declaration order. */
+    readonly members: readonly RoomMemberEntry[];
+    readonly coordinator?: RoomMemberEntry;
+    memberByEndpoint(endpointId: string): RoomMemberEntry | undefined;
+    memberByAgent(agent: string): RoomMemberEntry | undefined;
+    /** Case-insensitive agent name / alias lookup. */
+    memberByAlias(name: string): RoomMemberEntry | undefined;
+    /** Member whose Bot account (resolved through `accountOf`) equals `account`. */
+    memberByAccount(account: string, accountOf: (endpointId: string) => string | undefined): RoomMemberEntry | undefined;
+}
+export interface RoomRegistry {
+    /**
+     * Room owning a conversation. Keyed by `adapter:kind:id` (endpoint excluded, same scope as the
+     * outbound ledger). A Room binding carries no thread: messages in a thread belong to the Room of
+     * the parent conversation.
+     */
+    roomOf(conversation: RoomConversationLike): RoomEntry | undefined;
+    room(roomId: string): RoomEntry | undefined;
+    memberByEndpoint(roomId: string, endpointId: string): RoomMemberEntry | undefined;
+    memberByAccount(roomId: string, account: string, accountOf: (endpointId: string) => string | undefined): RoomMemberEntry | undefined;
+    rooms(): readonly RoomEntry[];
+}
+export declare function roomConversationKey(adapter: string, kind: string, id: string): string;
+/**
+ * Builds the in-memory index of enabled Rooms.
+ *
+ * `resolveEndpointId` maps a member's declared `{adapter, endpoint}` (configuration names) to the
+ * runtime Endpoint id (CapabilityId string); the host supplies it because the mapping depends on
+ * how Adapter endpoints are published.
+ */
+export declare function createRoomRegistry(rooms: Readonly<Record<string, RoomDefinition>>, resolveEndpointId: (bot: {
+    adapter: string;
+    endpoint: string;
+}) => string): RoomRegistry;
+//# sourceMappingURL=room-registry.d.ts.map

package/lib/room/room-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-registry.d.ts","sourceRoot":"","sources":["../../src/room/room-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAErG,2GAA2G;AAC3G,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe,CAAC;IACvC,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IAClE,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IAC1D,kDAAkD;IAClD,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IACzD,gFAAgF;IAChF,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAAC;CACtH;AAED,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,MAAM,CAAC,YAAY,EAAE,oBAAoB,GAAG,SAAS,GAAG,SAAS,CAAC;IAClE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IAC5C,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IAClF,eAAe,CACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GACpD,eAAe,GAAG,SAAS,CAAC;IAC/B,KAAK,IAAI,SAAS,SAAS,EAAE,CAAC;CAC/B;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAErF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,EAC/C,iBAAiB,EAAE,CAAC,GAAG,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,KAAK,MAAM,GACxE,YAAY,CAmDd"}

package/lib/room/room-registry.js

@@ -0,0 +1,64 @@
+export function roomConversationKey(adapter, kind, id) {
+    return `${adapter}:${kind}:${id}`;
+}
+/**
+ * Builds the in-memory index of enabled Rooms.
+ *
+ * `resolveEndpointId` maps a member's declared `{adapter, endpoint}` (configuration names) to the
+ * runtime Endpoint id (CapabilityId string); the host supplies it because the mapping depends on
+ * how Adapter endpoints are published.
+ */
+export function createRoomRegistry(rooms, resolveEndpointId) {
+    const byConversation = new Map();
+    const byId = new Map();
+    for (const [roomId, definition] of Object.entries(rooms)) {
+        if (definition.enabled === false)
+            continue;
+        const members = definition.members.map((member) => {
+            const role = definition.roles[member.role];
+            if (!role)
+                throw new Error(`Room ${roomId}: member ${member.agent} references unknown role ${member.role}`);
+            return Object.freeze({
+                roomId,
+                agent: member.agent,
+                roleName: member.role,
+                role,
+                definition: member,
+                endpointId: resolveEndpointId(member.botEndpoint),
+                names: Object.freeze([member.agent, ...(member.aliases ?? [])].map((name) => name.toLowerCase())),
+            });
+        });
+        const byEndpoint = new Map(members.map((member) => [member.endpointId, member]));
+        const byAgent = new Map(members.map((member) => [member.agent, member]));
+        const byName = new Map();
+        for (const member of members)
+            for (const name of member.names)
+                if (!byName.has(name))
+                    byName.set(name, member);
+        const coordinator = definition.coordinator !== undefined ? byAgent.get(definition.coordinator) : undefined;
+        const entry = Object.freeze({
+            id: roomId,
+            definition,
+            members: Object.freeze(members),
+            ...(coordinator ? { coordinator } : {}),
+            memberByEndpoint: (endpointId) => byEndpoint.get(endpointId),
+            memberByAgent: (agent) => byAgent.get(agent),
+            memberByAlias: (name) => byName.get(name.toLowerCase()),
+            memberByAccount: (account, accountOf) => members.find((member) => accountOf(member.endpointId) === account),
+        });
+        byId.set(roomId, entry);
+        const { adapter, kind, id } = definition.conversation;
+        const key = roomConversationKey(adapter, kind, id);
+        // Conversation ownership is validated upstream; first enabled Room wins defensively.
+        if (!byConversation.has(key))
+            byConversation.set(key, entry);
+    }
+    return Object.freeze({
+        roomOf: (conversation) => byConversation.get(roomConversationKey(conversation.endpoint.adapter, conversation.kind, conversation.id)),
+        room: (roomId) => byId.get(roomId),
+        memberByEndpoint: (roomId, endpointId) => byId.get(roomId)?.memberByEndpoint(endpointId),
+        memberByAccount: (roomId, account, accountOf) => byId.get(roomId)?.memberByAccount(account, accountOf),
+        rooms: () => Object.freeze([...byId.values()]),
+    });
+}
+//# sourceMappingURL=room-registry.js.map

package/lib/room/room-registry.js.map

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

package/lib/room/room-router.d.ts

@@ -0,0 +1,31 @@
+import type { RoomEntry } from './room-registry.js';
+/** Why the router picked an Endpoint (structurally equal to core's RoomRouteDecision). */
+export interface RoomRouteResult {
+    readonly endpointId: string;
+    readonly reason: 'pending' | 'mention' | 'reply' | 'coordinator' | 'role';
+    /**
+     * Other available members after the target, in takeover priority order
+     * (generalist, then chat/general, then declaration order). The target is never included.
+     * core lets them take over after a grace period when the target never receives a copy.
+     */
+    readonly fallbackEndpointIds: readonly string[];
+}
+/** Trusted facts about one inbound human message (structurally a subset of core's RoomInboundRouteInput). */
+export interface RoomRouteFacts {
+    readonly content: string;
+    readonly mentionTargets: readonly string[];
+    readonly replyToEndpointId?: string;
+    pending(endpointId: string): boolean;
+    accountOf(endpointId: string): string | undefined;
+    isAvailable(endpointId: string): boolean;
+}
+/**
+ * Pure routing decision for one inbound human message in a Room. Priority is fixed:
+ * pending answer > mention > reply > coordinator > role match. Every step skips unavailable
+ * Endpoints (falls through to the next priority); if nothing is available returns `undefined`
+ * so the caller falls back to first-come dedup. The decision never depends on which Endpoint
+ * received the copy or on its `mentioned` flag. A mention segment that points only to accounts
+ * outside the Room yields no target (`undefined`), so it is not handed to the coordinator or role.
+ */
+export declare function routeRoomMessage(room: RoomEntry, facts: RoomRouteFacts): RoomRouteResult | undefined;
+//# sourceMappingURL=room-router.d.ts.map

package/lib/room/room-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-router.d.ts","sourceRoot":"","sources":["../../src/room/room-router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,oBAAoB,CAAC;AAErE,0FAA0F;AAC1F,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,GAAG,MAAM,CAAC;IAC1E;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AAED,6GAA6G;AAC7G,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IACrC,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAClD,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1C;AAgDD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,GAAG,eAAe,GAAG,SAAS,CA4CpG"}

package/lib/room/room-router.js

@@ -0,0 +1,99 @@
+/** Unicode-aware word characters (plus `-`), so a CJK alias is not matched as a prefix of a longer CJK name. */
+const WORD = '\\p{L}\\p{N}_-';
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Position of the first `@name` in text, case-insensitive, name delimited on both sides.
+ * A text mention needs a separator after the name: `@研究 你好` and `@研究，` match, but `@研究`
+ * does not match `@研究员`, and unspaced CJK like `@研究员帮我` does not match either. The reliable
+ * path is the platform mention segment; text `@alias` is a convenience. Multiple mentions: the
+ * first one wins (segments before text).
+ */
+function textMentionIndex(content, name) {
+    const pattern = new RegExp(`(?<![${WORD}])@${escapeRegExp(name)}(?![${WORD}])`, 'iu');
+    const match = pattern.exec(content);
+    return match ? match.index : -1;
+}
+/**
+ * Members mentioned by the message, first mention first. Structured mention targets (platform
+ * mention segments, matched on the member's Bot account) come before `@alias` text mentions,
+ * because the platform vouches for them; text mentions are ordered by position.
+ */
+function mentionedMembers(room, facts) {
+    const seen = new Set();
+    const ordered = [];
+    const push = (member) => {
+        if (member && !seen.has(member)) {
+            seen.add(member);
+            ordered.push(member);
+        }
+    };
+    for (const target of facts.mentionTargets)
+        push(room.memberByAccount(target, facts.accountOf));
+    const textHits = [];
+    for (const member of room.members) {
+        let best = -1;
+        for (const name of member.names) {
+            const index = textMentionIndex(facts.content, name);
+            if (index >= 0 && (best < 0 || index < best))
+                best = index;
+        }
+        if (best >= 0)
+            textHits.push({ index: best, member });
+    }
+    textHits.sort((a, b) => a.index - b.index);
+    for (const hit of textHits)
+        push(hit.member);
+    return ordered;
+}
+/**
+ * Pure routing decision for one inbound human message in a Room. Priority is fixed:
+ * pending answer > mention > reply > coordinator > role match. Every step skips unavailable
+ * Endpoints (falls through to the next priority); if nothing is available returns `undefined`
+ * so the caller falls back to first-come dedup. The decision never depends on which Endpoint
+ * received the copy or on its `mentioned` flag. A mention segment that points only to accounts
+ * outside the Room yields no target (`undefined`), so it is not handed to the coordinator or role.
+ */
+export function routeRoomMessage(room, facts) {
+    const usable = (member) => member !== undefined && facts.isAvailable(member.endpointId);
+    const available = room.members.filter(usable);
+    const isGeneralist = (member) => member.role.accepts === undefined;
+    const isChat = (member) => member.role.accepts?.some((c) => c === 'chat' || c === 'general') === true;
+    const fallbacksFor = (target) => {
+        const others = available.filter((member) => member !== target);
+        return [
+            ...others.filter(isGeneralist),
+            ...others.filter((member) => !isGeneralist(member) && isChat(member)),
+            ...others.filter((member) => !isGeneralist(member) && !isChat(member)),
+        ].map((member) => member.endpointId);
+    };
+    const pick = (member, reason) => usable(member)
+        ? { endpointId: member.endpointId, reason, fallbackEndpointIds: fallbacksFor(member) }
+        : undefined;
+    const pending = room.members.find((member) => usable(member) && facts.pending(member.endpointId));
+    if (pending)
+        return pick(pending, 'pending');
+    // Only the first mentioned member counts; if it is unavailable, fall to the next priority.
+    const mentioned = mentionedMembers(room, facts);
+    const mention = pick(mentioned[0], 'mention');
+    if (mention)
+        return mention;
+    if (facts.replyToEndpointId !== undefined) {
+        const reply = pick(room.memberByEndpoint(facts.replyToEndpointId), 'reply');
+        if (reply)
+            return reply;
+    }
+    // The message is addressed to someone outside the Room: no target, so core falls back to
+    // first-come dedup and member copies keep their original `mentioned` semantics.
+    if (facts.mentionTargets.length > 0 && mentioned.length === 0)
+        return undefined;
+    const coordinator = pick(room.coordinator, 'coordinator');
+    if (coordinator)
+        return coordinator;
+    // Role match (no coordinator, or it is unavailable): generalist first, then chat/general, then anyone.
+    const generalist = available.find(isGeneralist);
+    const chat = available.find(isChat);
+    return pick(generalist ?? chat ?? available[0], 'role');
+}
+//# sourceMappingURL=room-router.js.map

package/lib/room/room-router.js.map

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