letagents 0.12.11 → 0.12.13

package/dist/shared/activation-routing.js

@@ -1,3 +1,13 @@
+import { normalizeRoutingHandle, normalizeRoutingSender, routingIdentityAliases, routingSenderAliasRows, routingSenderAliases, } from "../../shared/routing-aliases.mjs";
+import { parsePositivePgIntegerScopedId } from "./scoped-ids.js";
+/**
+ * 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",
@@ -33,6 +43,54 @@ export function attachAgentMessageActivation(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];
@@ -40,17 +98,27 @@ export function attachAgentMessageActivations(messages, identity, context = {})
     return messages.map((message) => attachAgentMessageActivation(message, identity, context));
 }
 export function decideAgentMessageActivation(message, identity, context = {}) {
-    if (normalizeSender(message.source) === "managed_agent_failure") {
+    if (normalizeSender(message.source) === "managed_agent_failure"
+        || isUntrustedExternalActivationSource(message.source)) {
         return decision("silent", "system_event");
     }
-    if (senderMatchesIdentity(message.sender, identity)) {
+    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");
     }
-    if (mentions.some((mention) => identityAliases(identity).has(normalizeMentionIdentityHandle(mention)))) {
+    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)) {
@@ -59,13 +127,22 @@ export function decideAgentMessageActivation(message, identity, context = {}) {
     if (mentions.some(isLikelyAgentMentionHandle)) {
         return decision("silent", "explicit_other_mention");
     }
-    if (senderMatchesIdentity(message.reply_to?.sender, identity)) {
+    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) && threadParticipantsIncludeIdentity(message, identity)) {
+    if (isThreadReply(message)
+        && (hasAuthoritativeThreadMembership
+            ? authoritativeThreadParticipantRootIds.has(threadRootId(message))
+            : threadParticipantsIncludeIdentity(message, identity))) {
         return decision("activate", "thread_participant");
     }
     const taskOwnerDecision = decideTaskOwnerActivation(message, identity, context);
@@ -83,9 +160,12 @@ function decision(decisionValue, reason) {
 }
 function isThreadReply(message) {
     const ownId = normalizedString(message.id);
-    const rootId = normalizedString(message.thread_root_id) || normalizedString(message.thread?.root_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";
 }
@@ -204,24 +284,111 @@ function senderMatchesIdentity(sender, identity) {
     const normalizedSender = normalizeSender(sender);
     if (!normalizedSender)
         return false;
-    const aliases = identityAliases(identity);
+    const aliases = activationIdentityAliases(identity);
     if (aliases.has(normalizedSender))
         return true;
     return String(sender || "")
         .split("|")
         .some((part) => aliases.has(normalizeSender(part)));
 }
-function identityAliases(identity) {
-    const aliases = new Set();
-    const values = [
-        identity.actor_label,
-        identity.display_name,
-        identity.agent_key,
-        identity.agent_key.split("/").pop(),
-    ];
-    for (const alias of aliasesForValues(values))
-        aliases.add(alias);
-    return aliases;
+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) {
+    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);
+        }
+    }
+    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 keys = keysByAlias.get(alias);
+            if (keys?.size === 1)
+                explicitMentionKeys.add(keys.values().next().value);
+        }
+        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 : "";
@@ -261,10 +428,10 @@ function normalizedString(value) {
     return typeof value === "string" ? value.trim() : "";
 }
 function normalizeSender(value) {
-    return normalizedString(value).toLowerCase().replace(/\s+/g, " ");
+    return normalizeRoutingSender(value);
 }
 function normalizeHandle(value) {
-    return normalizedString(value).toLowerCase().replace(/[^a-z0-9_.:/-]+/g, "");
+    return normalizeRoutingHandle(value);
 }
 function normalizeMentionIdentityHandle(value) {
     const normalized = normalizeHandle(value);

package/dist/shared/agent-presence.js

@@ -21,6 +21,12 @@ export const ROOM_AGENT_SESSION_KINDS = [
     "controller",
     "worker",
 ];
+export function isRoomAgentDeliveryCredentialExpired(fence, now = Date.now()) {
+    if (fence?.kind !== "bearer" || !fence.expires_at)
+        return false;
+    const expiresAt = Date.parse(fence.expires_at);
+    return Number.isFinite(expiresAt) && expiresAt <= now;
+}
 export function normalizeRoomAgentSessionKind(value) {
     return String(value || "").trim().toLowerCase() === "worker" ? "worker" : "controller";
 }

package/dist/shared/desktop-release-manifest.js

@@ -0,0 +1,63 @@
+export const MAC_DESKTOP_PUBLIC_BASE_URL = "https://downloads.letagents.chat";
+function record(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object.`);
+    }
+    return value;
+}
+function numericVersion(value) {
+    if (!/^\d+\.\d+\.\d+$/.test(value)) {
+        throw new Error("Desktop release manifest version must be numeric x.y.z.");
+    }
+    return value.split(".").map(Number);
+}
+function compareVersions(left, right) {
+    const leftParts = numericVersion(left);
+    const rightParts = numericVersion(right);
+    for (let index = 0; index < leftParts.length; index += 1) {
+        if (leftParts[index] !== rightParts[index])
+            return leftParts[index] - rightParts[index];
+    }
+    return 0;
+}
+export function parseMacDesktopPublicReleaseManifest(value, minimumVersion) {
+    const manifest = record(value, "Desktop release manifest");
+    const version = manifest.version;
+    if (manifest.schemaVersion !== 1 || manifest.channel !== "beta") {
+        throw new Error("Desktop release manifest has an unsupported contract.");
+    }
+    if (typeof version !== "string") {
+        throw new Error("Desktop release manifest version must be numeric x.y.z.");
+    }
+    numericVersion(version);
+    if (compareVersions(version, minimumVersion) < 0) {
+        throw new Error(`Desktop release manifest ${version} is older than ${minimumVersion}.`);
+    }
+    const rawAssets = record(manifest.assets, "Desktop release assets");
+    const checksumsUrl = `${MAC_DESKTOP_PUBLIC_BASE_URL}/desktop/v${version}/checksums.txt`;
+    if (manifest.checksumsUrl !== checksumsUrl) {
+        throw new Error("Desktop release manifest does not use the immutable public checksum URL.");
+    }
+    const assets = {};
+    for (const architecture of ["arm64", "x64"]) {
+        const rawAsset = record(rawAssets[architecture], `${architecture} desktop release asset`);
+        const fileName = `LetAgents-${version}-darwin-${architecture}.dmg`;
+        const publicUrl = `${MAC_DESKTOP_PUBLIC_BASE_URL}/desktop/v${version}/${fileName}`;
+        if (rawAsset.fileName !== fileName || rawAsset.publicUrl !== publicUrl) {
+            throw new Error(`${architecture} desktop release asset does not use the immutable public URL.`);
+        }
+        if (!Number.isSafeInteger(rawAsset.bytes) || Number(rawAsset.bytes) <= 0) {
+            throw new Error(`${architecture} desktop release asset must have a positive byte size.`);
+        }
+        if (typeof rawAsset.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(rawAsset.sha256)) {
+            throw new Error(`${architecture} desktop release asset must have a lowercase SHA-256 digest.`);
+        }
+        assets[architecture] = {
+            fileName,
+            publicUrl,
+            bytes: Number(rawAsset.bytes),
+            sha256: rawAsset.sha256,
+        };
+    }
+    return { schemaVersion: 1, channel: "beta", version, checksumsUrl, assets };
+}

package/dist/shared/desktop-release.js

@@ -0,0 +1,60 @@
+const MAC_DESKTOP_BETA_VERSION = "0.1.5";
+const MAC_DESKTOP_PUBLIC_BASE_URL = "https://downloads.letagents.chat/desktop";
+function macDesktopAsset(architecture, sha256) {
+    const fileName = `LetAgents-${MAC_DESKTOP_BETA_VERSION}-darwin-${architecture}.dmg`;
+    return {
+        fileName,
+        publicUrl: `${MAC_DESKTOP_PUBLIC_BASE_URL}/v${MAC_DESKTOP_BETA_VERSION}/${fileName}`,
+        sha256,
+    };
+}
+export const MAC_DESKTOP_BETA_RELEASE = {
+    version: MAC_DESKTOP_BETA_VERSION,
+    tag: `desktop-v${MAC_DESKTOP_BETA_VERSION}`,
+    assets: {
+        arm64: macDesktopAsset("arm64", "704355796cee5214a9cfbb79105a035e0e00dc3a3aa57be7d389b97cf35fc804"),
+        x64: macDesktopAsset("x64", "1e4b0b8b2c42ad8eaaf652fc887ab089445c8dd83233d763a6acdaa6617c2471"),
+    },
+};
+export const MAC_DESKTOP_BETA_CHECKSUM_RELEASES = [
+    MAC_DESKTOP_BETA_RELEASE,
+    {
+        version: "0.1.4",
+        assets: {
+            arm64: {
+                fileName: "LetAgents-0.1.4-darwin-arm64.dmg",
+                sha256: "27abe236232d33db10ed4533f4a7443a66f93568e9fa73a2ca472b6467fcf1cb",
+            },
+            x64: {
+                fileName: "LetAgents-0.1.4-darwin-x64.dmg",
+                sha256: "4c807ad0c799b4e46ab81d1098e5b65934d6b0b49f0a99ced2713897e1c2bc35",
+            },
+        },
+    },
+    {
+        version: "0.1.3",
+        assets: {
+            arm64: {
+                fileName: "LetAgents-0.1.3-darwin-arm64.dmg",
+                sha256: "6010454bc7375a38571d707f90c077207a7d2b49b01a1db1655b03f4def9b502",
+            },
+            x64: {
+                fileName: "LetAgents-0.1.3-darwin-x64.dmg",
+                sha256: "b7574e17ef87aebf418926478de10d9937fd1a96ca0c7a53b826a109302c5560",
+            },
+        },
+    },
+    {
+        version: "0.1.2",
+        assets: {
+            arm64: {
+                fileName: "LetAgents-0.1.2-darwin-arm64.dmg",
+                sha256: "e5355deced8383bc7d024ec60b109a38dde69dfeb6b6339352e1f5bc5c53bd43",
+            },
+            x64: {
+                fileName: "LetAgents-0.1.2-darwin-x64.dmg",
+                sha256: "67d2896b806695dae8c0224b3bc2780aee6902e897569c983ecc1bdb0330b6b0",
+            },
+        },
+    },
+];

package/dist/shared/scoped-ids.js

@@ -0,0 +1,6 @@
+import { POSTGRES_INTEGER_MAX, parsePositivePgIntegerScopedId as parseSharedPositivePgIntegerScopedId, } from "../../shared/message-contracts.mjs";
+export { POSTGRES_INTEGER_MAX };
+/** Parse the canonical `<prefix>_<positive PostgreSQL integer>` wire form. */
+export function parsePositivePgIntegerScopedId(value, prefix) {
+    return parseSharedPositivePgIntegerScopedId(value, prefix);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letagents",
-  "version": "0.12.11",
+  "version": "0.12.13",
   "description": "Let Agents Chat — MCP server for AI agent communication",
   "type": "module",
   "main": "dist/mcp/server.js",
@@ -11,6 +11,7 @@
     "dist/mcp/**",
     "dist/api/board-intent-payloads.js",
     "dist/shared/**",
+    "shared/**",
     "README.md"
   ],
   "scripts": {
@@ -24,6 +25,9 @@
     "test:orchestrator": "node --import tsx --test src/orchestrator/__tests__/*.test.ts",
     "test:web": "node --import tsx --test src/web/tests/*.test.ts src/web/src/composables/*.test.ts",
     "test:dependency-age": "node --test scripts/verify-dependency-age.test.mjs",
+    "test:docker-context": "node --test scripts/verify-docker-context.test.mjs",
+    "test:workflow-supply-chain": "node --test scripts/verify-workflow-supply-chain.test.mjs",
+    "test:notifications": "node --import tsx --test src/api/notifications/__tests__/*.test.ts",
     "verify:dependency-age": "node scripts/verify-dependency-age.mjs",
     "db:generate": "drizzle-kit generate",
     "db:migrate": "tsx src/api/migrate.ts",
@@ -31,7 +35,7 @@
     "prepublishOnly": "npm run build",
     "dev:api": "tsx src/api/server.ts",
     "dev:mcp": "tsx src/mcp/server.ts",
-    "dev:desktop": "npm --prefix apps/desktop run dev"
+    "dev:desktop": "node scripts/ensure-desktop-dependencies.mjs && npm --prefix apps/desktop run dev"
   },
   "keywords": [
     "mcp",
@@ -62,8 +66,12 @@
     "ws": "8.21.0"
   },
   "overrides": {
+    "@hono/node-server": "2.0.10",
     "@esbuild-kit/core-utils": {
       "esbuild": "^0.25.12"
-    }
+    },
+    "fast-uri": "3.1.5",
+    "hono": "4.12.34",
+    "ip-address": "10.3.1"
   }
 }

package/shared/message-contracts.d.mts

@@ -0,0 +1,32 @@
+export const POSTGRES_INTEGER_MAX: number;
+export const MESSAGE_SENDER_MAX_CODE_POINTS: number;
+export const MESSAGE_SENDER_MAX_UTF8_BYTES: number;
+export function parsePositivePgIntegerScopedId(value: unknown, prefix: string): number | null;
+export function isMessageSenderWithinBounds(sender: unknown): sender is string;
+export type ParsedAccountAgentRouting =
+  | { version: 1; authority: "invalid" }
+  | {
+      version: 1;
+      authority: "receipts";
+      recipientAgentKeys: string[];
+      recipientSessions: Array<{
+        agentKey: string;
+        agentSessionId: string;
+        successorAgentSessionId?: string;
+      }>;
+      controlAuthorized: boolean;
+    }
+  | {
+      version: 1;
+      authority: "legacy";
+      recipientAgentKeys: string[];
+      recipientSessions: Array<{
+        agentKey: string;
+        agentSessionId: string;
+        activationReason: string;
+      }>;
+      controlAuthorized: boolean;
+    };
+export function parseAccountAgentRoutingEnvelope(
+  routing: unknown,
+): ParsedAccountAgentRouting | undefined;

package/shared/message-contracts.mjs

@@ -0,0 +1,109 @@
+import { normalizeRoutingSender } from "./routing-aliases.mjs";
+
+export const POSTGRES_INTEGER_MAX = 2_147_483_647;
+export const MESSAGE_SENDER_MAX_CODE_POINTS = 512;
+export const MESSAGE_SENDER_MAX_UTF8_BYTES = 2_048;
+
+/** Parse the canonical `<prefix>_<positive PostgreSQL integer>` wire form. */
+export function parsePositivePgIntegerScopedId(value, prefix) {
+  if (typeof value !== "string" || typeof prefix !== "string" || !prefix) return null;
+  const marker = `${prefix}_`;
+  if (!value.startsWith(marker)) return null;
+  const decimal = value.slice(marker.length);
+  if (!/^[1-9]\d*$/.test(decimal)) return null;
+  const parsed = Number(decimal);
+  return Number.isSafeInteger(parsed) && parsed <= POSTGRES_INTEGER_MAX ? parsed : null;
+}
+
+/** Bound sender labels before routing projections duplicate their raw value. */
+export function isMessageSenderWithinBounds(sender) {
+  if (typeof sender !== "string") return false;
+  let codePoints = 0;
+  for (const _character of sender) {
+    codePoints += 1;
+    if (codePoints > MESSAGE_SENDER_MAX_CODE_POINTS) return false;
+  }
+  return new TextEncoder().encode(sender).byteLength <= MESSAGE_SENDER_MAX_UTF8_BYTES;
+}
+
+/**
+ * Parse the account-scoped routing envelope shared by Desktop and MCP.
+ * Undefined means an older/local message supplied no authority. Any present
+ * malformed shape returns explicit invalid authority and must never fall back
+ * to mutable display aliases.
+ */
+export function parseAccountAgentRoutingEnvelope(routing) {
+  if (routing === undefined) return undefined;
+  if (!routing || typeof routing !== "object" || routing.version !== 1) {
+    return { version: 1, authority: "invalid" };
+  }
+  if (routing.authority !== "receipts" && routing.authority !== "legacy") {
+    return { version: 1, authority: "invalid" };
+  }
+  if (
+    !Array.isArray(routing.recipient_agent_keys)
+    || !routing.recipient_agent_keys.every((value) => typeof value === "string")
+    || !Array.isArray(routing.recipient_agent_sessions)
+  ) {
+    return { version: 1, authority: "invalid" };
+  }
+  const recipientAgentKeys = routing.recipient_agent_keys.map(normalizeRoutingSender);
+  if (recipientAgentKeys.some((value) => !value)) {
+    return { version: 1, authority: "invalid" };
+  }
+  const uniqueKeys = new Set(recipientAgentKeys);
+  if (uniqueKeys.size !== recipientAgentKeys.length) {
+    return { version: 1, authority: "invalid" };
+  }
+  const targetKeys = new Set();
+  const recipientSessions = [];
+  for (const value of routing.recipient_agent_sessions) {
+    if (!value || typeof value !== "object") {
+      return { version: 1, authority: "invalid" };
+    }
+    const agentKey = typeof value.agent_key === "string"
+      ? normalizeRoutingSender(value.agent_key)
+      : "";
+    const agentSessionId = typeof value.agent_session_id === "string"
+      ? value.agent_session_id.trim()
+      : "";
+    if (!agentKey || !agentSessionId || targetKeys.has(agentKey)) {
+      return { version: 1, authority: "invalid" };
+    }
+    targetKeys.add(agentKey);
+    if (routing.authority === "receipts") {
+      const successorAgentSessionId = value.successor_agent_session_id === undefined
+        ? undefined
+        : typeof value.successor_agent_session_id === "string"
+          ? value.successor_agent_session_id.trim()
+          : "";
+      if (successorAgentSessionId !== undefined && !successorAgentSessionId) {
+        return { version: 1, authority: "invalid" };
+      }
+      recipientSessions.push({
+        agentKey,
+        agentSessionId,
+        ...(successorAgentSessionId ? { successorAgentSessionId } : {}),
+      });
+    } else {
+      const activationReason = typeof value.activation_reason === "string"
+        ? value.activation_reason.trim()
+        : "";
+      if (!activationReason) return { version: 1, authority: "invalid" };
+      recipientSessions.push({ agentKey, agentSessionId, activationReason });
+    }
+  }
+  if (
+    targetKeys.size !== uniqueKeys.size
+    || [...uniqueKeys].some((key) => !targetKeys.has(key))
+  ) {
+    return { version: 1, authority: "invalid" };
+  }
+  return {
+    version: 1,
+    authority: routing.authority,
+    recipientAgentKeys: [...uniqueKeys],
+    recipientSessions,
+    controlAuthorized: routing.control_authorized === true,
+  };
+}

package/shared/routing-aliases.d.mts

@@ -0,0 +1,18 @@
+export type RoutingIdentityLike = {
+  actorLabel?: string | null;
+  actor_label?: string | null;
+  displayName?: string | null;
+  display_name?: string | null;
+  agentKey?: string | null;
+  agent_key?: string | null;
+};
+
+export function normalizeRoutingSender(value: unknown): string;
+export function normalizeRoutingHandle(value: unknown): string;
+export function routingIdentityAliases(identity: RoutingIdentityLike): Set<string>;
+export function routingSenderAliasRows(
+  sender: unknown,
+  segmentLimit?: number,
+): Array<{ alias: string; isFull: boolean }>;
+export function routingSenderAliases(sender: unknown, segmentLimit?: number): Set<string>;
+export function routingAliasHash(alias: string): string;