letagents 0.12.19 → 0.12.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letagents",
-  "version": "0.12.19",
+  "version": "0.12.21",
   "description": "Let Agents Chat — MCP server for AI agent communication",
   "type": "module",
   "main": "dist/mcp/server.js",
@@ -71,7 +71,7 @@
       "esbuild": "^0.25.12"
     },
     "fast-uri": "3.1.6",
-    "hono": "4.12.34",
+    "hono": "4.13.5",
     "ip-address": "10.3.1"
   }
 }

package/shared/activation-routing.d.mts

@@ -0,0 +1,139 @@
+export type AgentMessageActivationDecision = "activate" | "silent" | "unclear";
+export type AgentMessageActivationReason = "self_message" | "explicit_mention" | "explicit_other_mention" | "broadcast" | "reply_target" | "other_reply_target" | "thread_participant" | "task_owner" | "small_room" | "recent_conversation" | "system_event" | "unaddressed";
+/** Send-time human fallback only; never use this to re-route historical reads. */
+export declare function humanConversationFallback(input: {
+    source: string | null;
+    publisherAccountId: string | null;
+    publisherAgentKey: string | null;
+    explicitlyAddressed: boolean;
+    registeredAgentKeys: readonly string[];
+    recentAgentKey?: string | null;
+}): {
+    reason: "small_room" | "recent_conversation";
+    agentKeys: string[];
+} | null;
+/**
+ * Repository events can contain text written by any external contributor.
+ * They remain visible room activity, but their text is never an instruction
+ * channel for a managed local worker.
+ */
+export declare function isUntrustedExternalActivationSource(source: unknown): boolean;
+export interface AgentMessageActivation {
+    for_current_agent: {
+        decision: AgentMessageActivationDecision;
+        reason: AgentMessageActivationReason;
+        addressed: boolean;
+    };
+}
+type MessageLike = {
+    id?: unknown;
+    sender?: unknown;
+    text?: unknown;
+    source?: unknown;
+    thread_root_id?: unknown;
+    thread?: {
+        root_message_id?: unknown;
+        participants?: Array<{
+            sender?: unknown;
+        }> | null;
+        latest_reply?: {
+            sender?: unknown;
+        } | null;
+    } | null;
+    reply_to?: {
+        sender?: unknown;
+        source?: unknown;
+    } | null;
+};
+export type ActivationIdentity = {
+    actor_label: string;
+    agent_key: string;
+    agent_instance_id: string | null;
+    agent_session_id: string | null;
+    display_name: string;
+    session_kind: string;
+};
+type ActivationTaskLeaseLike = {
+    kind: string;
+    status: string;
+    actor_label: string;
+    agent_key: string;
+    agent_instance_id: string | null;
+    agent_session_id: string | null;
+};
+export type AgentMessageActivationContext = {
+    activeTaskLeases?: readonly ActivationTaskLeaseLike[];
+    /** Legacy messages authored by this exact durable identity. */
+    selfMessageIds?: ReadonlySet<string>;
+    /** Thread roots whose routing projection contains this exact identity. */
+    threadParticipantRootIds?: ReadonlySet<string>;
+    /** Legacy messages whose globally resolved mention names this identity. */
+    explicitMentionMessageIds?: ReadonlySet<string>;
+    /** Legacy messages whose globally resolved reply target names this identity. */
+    replyTargetMessageIds?: ReadonlySet<string>;
+    /** Complete legacy decisions supplied by the room-global routing authority. */
+    authoritativeLegacyDecisions?: ReadonlyMap<string, AgentMessageActivation["for_current_agent"]>;
+};
+export declare function attachAgentMessageActivation<T extends MessageLike>(message: T, identity: ActivationIdentity, context?: AgentMessageActivationContext): T & {
+    activation: AgentMessageActivation;
+};
+/**
+ * Send-time receipts are the activation authority. For a snapshot-bearing
+ * message, a receipt activates and the absence of one is the durable
+ * send-time "silent" — never re-promoted by re-running the router against
+ * later task/thread/session state, which would create a second authority.
+ * Only messages that predate routing snapshots keep the lazy per-reader
+ * decision, so legacy backlog mentions still activate rotated sessions.
+ */
+export declare function attachAgentMessageActivationsFromReceipts<T extends MessageLike>(messages: readonly T[], identity: ActivationIdentity | null, receiptsMap: ReadonlyMap<number | string, {
+    activation_reason: string;
+}>, snapshotNumbers: ReadonlySet<number>, context?: AgentMessageActivationContext): T[] | Array<T & {
+    activation: AgentMessageActivation;
+}>;
+export declare function attachAgentMessageActivations<T extends MessageLike>(messages: readonly T[], identity: ActivationIdentity | null, context?: AgentMessageActivationContext): T[] | Array<T & {
+    activation: AgentMessageActivation;
+}>;
+export declare function decideAgentMessageActivation(message: MessageLike, identity: ActivationIdentity, context?: AgentMessageActivationContext): AgentMessageActivation["for_current_agent"];
+export declare function activationIdentityAliases(identity: ActivationIdentity): Set<string>;
+/** Canonical aliases materialized from a historical message sender. */
+export declare function activationSenderAliases(sender: unknown, segmentLimit?: number): Set<string>;
+/**
+ * Resolve identity-bearing addresses against the complete active room
+ * population. A display alias is authority only when it names one durable
+ * agent key globally; account/provider filtering happens after this step.
+ * Full historical sender labels take precedence over their pipe-delimited
+ * compatibility segments.
+ */
+export declare function resolveGloballyAddressedAgentKeys(message: Pick<MessageLike, "text" | "reply_to">, identities: readonly ActivationIdentity[]): {
+    explicitMentionKeys: Set<string>;
+    replyTargetKeys: Set<string>;
+};
+export interface GlobalAgentAddressResolverOptions {
+    /**
+     * Break a duplicate friendly-name tie only when exactly one of the durable
+     * identities is currently reachable. Canonical agent-key aliases remain
+     * unique without this hint, and multiple reachable matches still fail
+     * closed.
+     */
+    preferredExplicitMentionAgentKeys?: ReadonlySet<string>;
+    /**
+     * Stable ownership boundary for each preferred key. Reachability may only
+     * break a tie when every colliding durable key belongs to the same scope.
+     */
+    explicitMentionOwnerScopeByAgentKey?: ReadonlyMap<string, string>;
+}
+/**
+ * Build the room-wide alias authority once, then resolve a page of legacy
+ * messages without rebuilding every active worker alias set per message.
+ */
+export declare function createGlobalAgentAddressResolver(identities: readonly ActivationIdentity[], options?: GlobalAgentAddressResolverOptions): (message: Pick<MessageLike, "text" | "reply_to"> & Partial<Pick<MessageLike, "sender">>) => {
+    broadcast: boolean;
+    hasMention: boolean;
+    hasAgentMention: boolean;
+    explicitMentionKeys: Set<string>;
+    replyTargetKeys: Set<string>;
+    senderKeys: Set<string>;
+};
+/** Shared legacy task-follow-up classifier used by API and desktop overlays. */
+export declare function isTaskOwnerFollowUpMessageText(text: unknown): boolean;
+export {};

package/shared/activation-routing.mjs

@@ -0,0 +1,468 @@
+import { normalizeRoutingHandle, normalizeRoutingSender, routingIdentityAliases, routingSenderAliasRows, routingSenderAliases, } from "./routing-aliases.mjs";
+import { parsePositivePgIntegerScopedId } from "./message-contracts.mjs";
+/** Send-time human fallback only; never use this to re-route historical reads. */
+export function humanConversationFallback(input) {
+    if (input.source !== "browser" || !input.publisherAccountId || input.publisherAgentKey || input.explicitlyAddressed)
+        return null;
+    const keys = [...new Set(input.registeredAgentKeys)];
+    if (keys.length > 0 && keys.length <= 2)
+        return { reason: "small_room", agentKeys: keys };
+    if (keys.length > 2 && input.recentAgentKey && keys.includes(input.recentAgentKey)) {
+        return { reason: "recent_conversation", agentKeys: [input.recentAgentKey] };
+    }
+    return null;
+}
+/**
+ * Repository events can contain text written by any external contributor.
+ * They remain visible room activity, but their text is never an instruction
+ * channel for a managed local worker.
+ */
+export function isUntrustedExternalActivationSource(source) {
+    return normalizeSender(source) === "github";
+}
+const NON_AGENT_AT_HANDLES = new Set([
+    "charset",
+    "container",
+    "counter-style",
+    "font-face",
+    "font-feature-values",
+    "font-palette-values",
+    "import",
+    "keyframes",
+    "layer",
+    "media",
+    "namespace",
+    "page",
+    "package",
+    "property",
+    "scope",
+    "starting-style",
+    "supports",
+    "types",
+    "viewport",
+]);
+const TASK_OWNER_FOLLOW_UP_PATTERNS = [
+    /^(?:ok(?:ay)?|right|cool|great|nice)?[\s,]*(?:try again|retry|rerun|re-run|continue|proceed|go ahead|carry on)\b/,
+    /^(?:ok(?:ay)?|right|cool|great|nice)?[\s,]*(?:open|create|make|raise)\s+(?:a\s+)?pr\b/,
+    /^(?:ok(?:ay)?|right|cool|great|nice)?[\s,]*(?:push|merge|ship|fix|test|run|update)\s+(?:it|that|this|again|tests?|the\s+tests?|ci)\b/,
+    /\b(?:try again|open\s+(?:a\s+)?pr|create\s+(?:a\s+)?pr|make\s+(?:a\s+)?pr|push it|merge it|update it)\b/,
+];
+export function attachAgentMessageActivation(message, identity, context = {}) {
+    return {
+        ...message,
+        activation: {
+            for_current_agent: decideAgentMessageActivation(message, identity, context),
+        },
+    };
+}
+/**
+ * Send-time receipts are the activation authority. For a snapshot-bearing
+ * message, a receipt activates and the absence of one is the durable
+ * send-time "silent" — never re-promoted by re-running the router against
+ * later task/thread/session state, which would create a second authority.
+ * Only messages that predate routing snapshots keep the lazy per-reader
+ * decision, so legacy backlog mentions still activate rotated sessions.
+ */
+export function attachAgentMessageActivationsFromReceipts(messages, identity, receiptsMap, snapshotNumbers, context = {}) {
+    if (!identity || identity.session_kind !== "worker") {
+        return [...messages];
+    }
+    return messages.map((message) => {
+        const msgIdStr = String(message.id ?? "");
+        const msgNum = parsePositivePgIntegerScopedId(msgIdStr, "msg");
+        const receipt = msgNum !== null ? receiptsMap.get(msgNum) || receiptsMap.get(msgIdStr) : null;
+        if (receipt) {
+            const reason = receipt.activation_reason;
+            return {
+                ...message,
+                activation: {
+                    for_current_agent: {
+                        decision: "activate",
+                        reason: reason || "explicit_mention",
+                        addressed: true,
+                    },
+                },
+            };
+        }
+        // System failure rows are canonical silent control events. A routing
+        // snapshot with no receipt must not erase their diagnostic reason.
+        if (msgNum !== null
+            && snapshotNumbers.has(msgNum)
+            && normalizeSender(message.source) !== "managed_agent_failure") {
+            return {
+                ...message,
+                activation: {
+                    for_current_agent: {
+                        decision: "silent",
+                        reason: "unaddressed",
+                        addressed: false,
+                    },
+                },
+            };
+        }
+        return attachAgentMessageActivation(message, identity, context);
+    });
+}
+export function attachAgentMessageActivations(messages, identity, context = {}) {
+    if (!identity || identity.session_kind !== "worker") {
+        return [...messages];
+    }
+    return messages.map((message) => attachAgentMessageActivation(message, identity, context));
+}
+export function decideAgentMessageActivation(message, identity, context = {}) {
+    if (normalizeSender(message.source) === "managed_agent_failure"
+        || isUntrustedExternalActivationSource(message.source)) {
+        return decision("silent", "system_event");
+    }
+    const messageId = normalizedString(message.id);
+    const authoritativeLegacyDecision = context.authoritativeLegacyDecisions?.get(messageId);
+    if (authoritativeLegacyDecision)
+        return authoritativeLegacyDecision;
+    if (context.selfMessageIds !== undefined
+        ? context.selfMessageIds.has(messageId)
+        : senderMatchesIdentity(message.sender, identity)) {
+        return decision("silent", "self_message");
+    }
+    const mentions = extractMentionHandles(message.text);
+    if (mentions.some(isBroadcastHandle)) {
+        return decision("activate", "broadcast");
+    }
+    const authoritativeExplicitMentions = context.explicitMentionMessageIds;
+    if (authoritativeExplicitMentions !== undefined
+        ? authoritativeExplicitMentions.has(messageId)
+        : mentions.some((mention) => activationIdentityAliases(identity).has(normalizeMentionIdentityHandle(mention)))) {
+        return decision("activate", "explicit_mention");
+    }
+    if (hasBroadcastAddress(message.text)) {
+        return decision("activate", "broadcast");
+    }
+    if (mentions.some(isLikelyAgentMentionHandle)) {
+        return decision("silent", "explicit_other_mention");
+    }
+    const authoritativeThreadParticipantRootIds = context.threadParticipantRootIds;
+    const authoritativeReplyTargets = context.replyTargetMessageIds;
+    const hasAuthoritativeThreadMembership = isThreadReply(message)
+        && authoritativeThreadParticipantRootIds !== undefined;
+    if (authoritativeReplyTargets !== undefined
+        ? authoritativeReplyTargets.has(messageId)
+        : !hasAuthoritativeThreadMembership && senderMatchesIdentity(message.reply_to?.sender, identity)) {
+        return decision("activate", "reply_target");
+    }
+    if (isAgentReplyTarget(message.reply_to) && !isThreadReply(message)) {
+        return decision("silent", "other_reply_target");
+    }
+    if (isThreadReply(message)
+        && (hasAuthoritativeThreadMembership
+            ? authoritativeThreadParticipantRootIds.has(threadRootId(message))
+            : threadParticipantsIncludeIdentity(message, identity))) {
+        return decision("activate", "thread_participant");
+    }
+    const taskOwnerDecision = decideTaskOwnerActivation(message, identity, context);
+    if (taskOwnerDecision) {
+        return taskOwnerDecision;
+    }
+    return decision("unclear", "unaddressed");
+}
+function decision(decisionValue, reason) {
+    return {
+        decision: decisionValue,
+        reason,
+        addressed: decisionValue === "activate",
+    };
+}
+function isThreadReply(message) {
+    const ownId = normalizedString(message.id);
+    const rootId = threadRootId(message);
+    return Boolean(ownId && rootId && ownId !== rootId);
+}
+function threadRootId(message) {
+    return normalizedString(message.thread_root_id) || normalizedString(message.thread?.root_message_id);
+}
+function isAgentReplyTarget(replyTo) {
+    return normalizeSender(replyTo?.source) === "agent";
+}
+function threadParticipantsIncludeIdentity(message, identity) {
+    const senders = [
+        message.reply_to?.sender,
+        message.thread?.latest_reply?.sender,
+        ...(message.thread?.participants ?? []).map((participant) => participant.sender),
+    ];
+    return senders.some((sender) => senderMatchesIdentity(sender, identity));
+}
+function decideTaskOwnerActivation(message, identity, context) {
+    if (!isTaskOwnerFollowUp(message.text)) {
+        return null;
+    }
+    const owners = uniqueActiveWorkOwners(context.activeTaskLeases ?? []);
+    if (owners.length !== 1) {
+        return null;
+    }
+    const owner = owners[0];
+    if (senderMatchesLeaseOwner(message.sender, owner)) {
+        return null;
+    }
+    if (leaseOwnerMatchesIdentity(owner, identity)) {
+        return decision("activate", "task_owner");
+    }
+    if (identityOverlapsLeaseOwner(identity, owner)) {
+        return null;
+    }
+    return decision("silent", "task_owner");
+}
+function uniqueActiveWorkOwners(leases) {
+    const ownersByKey = new Map();
+    for (const lease of leases) {
+        if (lease.kind !== "work" || lease.status !== "active")
+            continue;
+        const key = leaseOwnerKey(lease);
+        if (!key)
+            continue;
+        ownersByKey.set(key, lease);
+    }
+    return [...ownersByKey.values()];
+}
+function leaseOwnerKey(lease) {
+    const sessionId = normalizedString(lease.agent_session_id);
+    if (sessionId)
+        return `session:${sessionId}`;
+    const instanceId = normalizedString(lease.agent_instance_id);
+    const agentKey = normalizeSender(lease.agent_key);
+    if (instanceId)
+        return `instance:${agentKey}:${instanceId}`;
+    if (agentKey)
+        return `agent:${agentKey}`;
+    const actorLabel = normalizeSender(lease.actor_label);
+    return actorLabel ? `label:${actorLabel}` : null;
+}
+function leaseOwnerMatchesIdentity(lease, identity) {
+    const leaseSessionId = normalizedString(lease.agent_session_id);
+    if (leaseSessionId) {
+        return leaseSessionId === normalizedString(identity.agent_session_id);
+    }
+    const leaseInstanceId = normalizedString(lease.agent_instance_id);
+    if (leaseInstanceId) {
+        return (leaseInstanceId === normalizedString(identity.agent_instance_id) &&
+            normalizeSender(lease.agent_key) === normalizeSender(identity.agent_key));
+    }
+    const leaseAgentKey = normalizeSender(lease.agent_key);
+    if (leaseAgentKey) {
+        return leaseAgentKey === normalizeSender(identity.agent_key);
+    }
+    return senderMatchesIdentity(lease.actor_label, identity);
+}
+function senderMatchesLeaseOwner(sender, lease) {
+    const normalizedSender = normalizeSender(sender);
+    if (!normalizedSender)
+        return false;
+    return leaseOwnerAliases(lease).has(normalizedSender);
+}
+function identityOverlapsLeaseOwner(identity, lease) {
+    const identityAliasesForOwner = aliasesForValues([
+        identity.actor_label,
+        identity.display_name,
+        identity.agent_key,
+        identity.agent_instance_id,
+        identity.agent_session_id,
+    ]);
+    for (const ownerAlias of leaseOwnerAliases(lease)) {
+        if (identityAliasesForOwner.has(ownerAlias)) {
+            return true;
+        }
+    }
+    return false;
+}
+function leaseOwnerAliases(lease) {
+    return aliasesForValues([
+        lease.actor_label,
+        ...String(lease.actor_label || "").split("|"),
+        lease.agent_key,
+        lease.agent_instance_id,
+        lease.agent_session_id,
+    ]);
+}
+function aliasesForValues(values) {
+    const aliases = new Set();
+    for (const value of values) {
+        const senderAlias = normalizeSender(value);
+        if (senderAlias)
+            aliases.add(senderAlias);
+        const handleAlias = normalizeHandle(value);
+        if (handleAlias)
+            aliases.add(handleAlias);
+    }
+    return aliases;
+}
+function senderMatchesIdentity(sender, identity) {
+    const normalizedSender = normalizeSender(sender);
+    if (!normalizedSender)
+        return false;
+    const aliases = activationIdentityAliases(identity);
+    if (aliases.has(normalizedSender))
+        return true;
+    return String(sender || "")
+        .split("|")
+        .some((part) => aliases.has(normalizeSender(part)));
+}
+export function activationIdentityAliases(identity) {
+    return routingIdentityAliases(identity);
+}
+/** Canonical aliases materialized from a historical message sender. */
+export function activationSenderAliases(sender, segmentLimit = 16) {
+    return routingSenderAliases(sender, segmentLimit);
+}
+/**
+ * Resolve identity-bearing addresses against the complete active room
+ * population. A display alias is authority only when it names one durable
+ * agent key globally; account/provider filtering happens after this step.
+ * Full historical sender labels take precedence over their pipe-delimited
+ * compatibility segments.
+ */
+export function resolveGloballyAddressedAgentKeys(message, identities) {
+    return createGlobalAgentAddressResolver(identities)(message);
+}
+/**
+ * Build the room-wide alias authority once, then resolve a page of legacy
+ * messages without rebuilding every active worker alias set per message.
+ */
+export function createGlobalAgentAddressResolver(identities, options = {}) {
+    const keysByAlias = new Map();
+    for (const identity of identities) {
+        const key = normalizedString(identity.agent_key);
+        if (!key)
+            continue;
+        for (const alias of activationIdentityAliases(identity)) {
+            const keys = keysByAlias.get(alias) ?? new Set();
+            keys.add(key);
+            keysByAlias.set(alias, keys);
+        }
+    }
+    const resolveExplicitMentionKey = (keys) => {
+        if (!keys || keys.size === 0)
+            return null;
+        if (keys.size === 1)
+            return keys.values().next().value;
+        const preferredMatches = [...keys].filter((key) => options.preferredExplicitMentionAgentKeys?.has(key));
+        if (preferredMatches.length !== 1)
+            return null;
+        const ownerScopes = new Set();
+        for (const key of keys) {
+            const scope = options.explicitMentionOwnerScopeByAgentKey?.get(key);
+            if (!scope)
+                return null;
+            ownerScopes.add(scope);
+        }
+        return ownerScopes.size === 1 ? preferredMatches[0] : null;
+    };
+    return (message) => {
+        const mentions = extractMentionHandles(message.text);
+        const broadcast = mentions.some(isBroadcastHandle) || hasBroadcastAddress(message.text);
+        const hasMention = mentions.some((mention) => !isBroadcastHandle(mention));
+        const hasAgentMention = mentions.some(isLikelyAgentMentionHandle);
+        const explicitMentionKeys = new Set();
+        for (const mention of mentions) {
+            if (isBroadcastHandle(mention))
+                continue;
+            const alias = normalizeMentionIdentityHandle(mention);
+            if (!alias)
+                continue;
+            const resolvedKey = resolveExplicitMentionKey(keysByAlias.get(alias));
+            if (resolvedKey)
+                explicitMentionKeys.add(resolvedKey);
+        }
+        const replyTargetKeys = new Set();
+        const replyAliases = normalizedString(message.reply_to?.source) === "agent"
+            ? routingSenderAliasRows(message.reply_to?.sender)
+            : [];
+        const matchingKeys = (full) => {
+            const keys = new Set();
+            for (const row of replyAliases) {
+                if (row.isFull !== full)
+                    continue;
+                for (const key of keysByAlias.get(row.alias) ?? [])
+                    keys.add(key);
+            }
+            return keys;
+        };
+        const fullMatches = matchingKeys(true);
+        const replyMatches = fullMatches.size > 0 ? fullMatches : matchingKeys(false);
+        if (replyMatches.size === 1)
+            replyTargetKeys.add(replyMatches.values().next().value);
+        const senderKeys = new Set();
+        const senderAliases = routingSenderAliasRows(message.sender);
+        const senderMatchingKeys = (full) => {
+            const keys = new Set();
+            for (const row of senderAliases) {
+                if (row.isFull !== full)
+                    continue;
+                for (const key of keysByAlias.get(row.alias) ?? [])
+                    keys.add(key);
+            }
+            return keys;
+        };
+        const senderFullMatches = senderMatchingKeys(true);
+        const senderMatches = senderFullMatches.size > 0
+            ? senderFullMatches
+            : senderMatchingKeys(false);
+        if (senderMatches.size === 1)
+            senderKeys.add(senderMatches.values().next().value);
+        return {
+            broadcast,
+            hasMention,
+            hasAgentMention,
+            explicitMentionKeys,
+            replyTargetKeys,
+            senderKeys,
+        };
+    };
+}
+/** Shared legacy task-follow-up classifier used by API and desktop overlays. */
+export function isTaskOwnerFollowUpMessageText(text) {
+    return isTaskOwnerFollowUp(text);
+}
+function extractMentionHandles(text) {
+    const raw = typeof text === "string" ? text : "";
+    const mentions = [];
+    for (const match of raw.matchAll(/(^|[\s([{:;,])@([A-Za-z0-9][A-Za-z0-9_.:-]*(?:\/[A-Za-z0-9][A-Za-z0-9_.-]*)*)/g)) {
+        mentions.push(match[2]);
+    }
+    return mentions;
+}
+function isBroadcastHandle(handle) {
+    const normalized = normalizeHandle(handle);
+    return normalized === "agents" || normalized === "everyone" || normalized === "room";
+}
+function isLikelyAgentMentionHandle(handle) {
+    const raw = normalizedString(handle);
+    if (!raw)
+        return false;
+    const normalized = raw.toLowerCase();
+    const firstSegment = normalized.split("/", 1)[0].replace(/_/g, "-");
+    if (normalized.startsWith("agent:"))
+        return true;
+    if (normalized.includes("/") && normalized === raw)
+        return false;
+    return !NON_AGENT_AT_HANDLES.has(firstSegment);
+}
+function hasBroadcastAddress(text) {
+    const raw = typeof text === "string" ? text.toLowerCase() : "";
+    return /\b(everyone|all agents|you guys|both of you|any agent|whoever owns this)\b/.test(raw);
+}
+function isTaskOwnerFollowUp(text) {
+    const raw = typeof text === "string" ? text.trim().toLowerCase() : "";
+    if (!raw)
+        return false;
+    return TASK_OWNER_FOLLOW_UP_PATTERNS.some((pattern) => pattern.test(raw));
+}
+function normalizedString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function normalizeSender(value) {
+    return normalizeRoutingSender(value);
+}
+function normalizeHandle(value) {
+    return normalizeRoutingHandle(value);
+}
+function normalizeMentionIdentityHandle(value) {
+    const normalized = normalizeHandle(value);
+    return normalized.startsWith("agent:") ? normalized.slice("agent:".length) : normalized;
+}

package/shared/local-room-knowledge.d.mts

@@ -0,0 +1,7 @@
+import type { KnowledgePage, KnowledgeRecord, KnowledgeType } from './room-knowledge.mjs';
+export interface KnowledgeDatabase { exec(sql: string): void; prepare(sql: string): { get(...args: unknown[]): any; all(...args: unknown[]): any[]; run(...args: unknown[]): unknown } }
+export function initializeRoomKnowledge(db: KnowledgeDatabase): void;
+export function listLocalKnowledge(db: KnowledgeDatabase, roomId: string, type: KnowledgeType): KnowledgePage;
+export function getLocalKnowledge(db: KnowledgeDatabase, roomId: string, id: string): KnowledgeRecord | null;
+export function localKnowledgeHistory(db: KnowledgeDatabase, roomId: string, id: string): KnowledgeRecord[];
+export function saveLocalKnowledge(db: KnowledgeDatabase, record: KnowledgeRecord, expectedVersion?: number): KnowledgeRecord;

package/shared/local-room-knowledge.mjs

@@ -0,0 +1,53 @@
+import { assertKnowledgeReplay, RoomKnowledgeError } from './room-knowledge.mjs';
+
+export function initializeRoomKnowledge(db) {
+  db.exec(`CREATE TABLE IF NOT EXISTS local_room_knowledge (
+    room_id TEXT NOT NULL, id TEXT NOT NULL, type TEXT NOT NULL, version INTEGER NOT NULL,
+    value TEXT NOT NULL, PRIMARY KEY(room_id, id));
+    CREATE TABLE IF NOT EXISTS local_room_knowledge_revisions (
+    room_id TEXT NOT NULL, id TEXT NOT NULL, version INTEGER NOT NULL, value TEXT NOT NULL,
+    PRIMARY KEY(room_id, id, version));
+    CREATE TABLE IF NOT EXISTS local_room_knowledge_outbox (room_id TEXT NOT NULL, id TEXT NOT NULL, value TEXT NOT NULL, PRIMARY KEY(room_id, id));`);
+}
+export function listLocalKnowledge(db, roomId, type) {
+  initializeRoomKnowledge(db);
+  const rows = db.prepare('SELECT value FROM local_room_knowledge WHERE room_id = ? AND type = ? ORDER BY json_extract(value, \'$.archived\') ASC, (json_extract(value, \'$.response\') IS NULL) DESC, json_extract(value, \'$.updated_at\') DESC LIMIT 201').all(roomId, type);
+  return { records: rows.slice(0, 200).map(row => JSON.parse(row.value)), truncated: rows.length > 200 };
+}
+export function getLocalKnowledge(db, roomId, id) {
+  initializeRoomKnowledge(db);
+  const row = db.prepare('SELECT value FROM local_room_knowledge WHERE room_id = ? AND id = ?').get(roomId, id);
+  return row ? JSON.parse(row.value) : null;
+}
+export function localKnowledgeHistory(db, roomId, id) {
+  initializeRoomKnowledge(db);
+  return db.prepare('SELECT value FROM local_room_knowledge_revisions WHERE room_id = ? AND id = ? ORDER BY version DESC LIMIT 100').all(roomId, id).map(row => JSON.parse(row.value));
+}
+export function saveLocalKnowledge(db, record, expectedVersion) {
+  initializeRoomKnowledge(db);
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    const existing = getLocalKnowledge(db, record.room_id, record.id);
+    if (record.source_message_id) assertLocalKnowledgeSource(db, record);
+    if (expectedVersion === undefined && existing) {
+      const row = db.prepare('SELECT value FROM local_room_knowledge_revisions WHERE room_id = ? AND id = ? AND version = 1').get(record.room_id, record.id);
+      if (!row) throw new RoomKnowledgeError('The original version is unavailable. Please refresh.', 409);
+      const initial = JSON.parse(row.value);
+      assertKnowledgeReplay(initial, record);
+      db.exec('COMMIT');
+      return existing;
+    }
+    if (expectedVersion !== undefined && existing?.version !== expectedVersion) throw new RoomKnowledgeError('This changed since you opened it. Refresh to see the latest version.', 409);
+    db.prepare('INSERT INTO local_room_knowledge VALUES (?, ?, ?, ?, ?) ON CONFLICT(room_id, id) DO UPDATE SET version = excluded.version, value = excluded.value').run(record.room_id, record.id, record.type, record.version, JSON.stringify(record));
+    db.prepare('INSERT INTO local_room_knowledge_revisions VALUES (?, ?, ?, ?)').run(record.room_id, record.id, record.version, JSON.stringify(record));
+    if (record.type === 'attention' && record.response) db.prepare('INSERT OR IGNORE INTO local_room_knowledge_outbox VALUES (?, ?, ?)').run(record.room_id, record.id, JSON.stringify(record));
+    db.exec('COMMIT');
+    return record;
+  } catch (error) { db.exec('ROLLBACK'); throw error; }
+}
+
+function assertLocalKnowledgeSource(db, record) {
+  const table = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'local_chat_messages'").get();
+  const row = table && db.prepare("SELECT number FROM local_chat_messages WHERE room_id = ? AND number = ? AND NOT (COALESCE(agent_prompt_kind, '') = 'auto' AND TRIM(text) = '')").get(record.room_id, Number(record.source_message_id.slice(4)));
+  if (!row) throw new RoomKnowledgeError('The source message does not exist or is not visible in this local room.');
+}