letagents 0.12.12 → 0.12.14

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/room-agent-work.d.mts

@@ -0,0 +1,31 @@
+export const ROOM_WORK_STATES: readonly ["active", "completed", "completed_no_reply", "failed", "interrupted", "lost", "unknown"];
+export const ROOM_WORK_OPERATION_OUTCOMES: readonly ["unresolved", "succeeded", "failed", "denied_before_start", "cancelled_before_start", "interrupted_after_start", "lost_after_start"];
+export type RoomAgentWorkSummary = {
+  version: 1;
+  recorded_state: typeof ROOM_WORK_STATES[number];
+  evidence_incomplete: boolean;
+  elapsed_ms: number | null;
+  operation_counts: Record<typeof ROOM_WORK_OPERATION_OUTCOMES[number], number>;
+};
+// Server-issued availability marker, not a publisher-supplied execution state.
+export type ClearedRoomAgentWorkSummary = { version: 1; availability: "cleared" };
+export type RoomAgentWork = {
+  attempt_id: string;
+  room_id: string;
+  source_message_id: string;
+  agent_key: string;
+  revision: number;
+  summary: RoomAgentWorkSummary | ClearedRoomAgentWorkSummary;
+  updated_at: string;
+};
+export type RoomAgentWorkSnapshot = { work: RoomAgentWork[]; truncated: boolean };
+/** Synchronizes the latest-50 view, not intermediate events or complete history.
+ * A changed snapshot replaces the client's bounded cache; it must not be merged.
+ * The server-issued cursor is a comparison hint, never authorization. */
+export type RoomAgentWorkPollResponse = { room_id: string; cursor: string } & (
+  | { changed: true; snapshot: RoomAgentWorkSnapshot }
+  | { changed: false; snapshot: null }
+);
+export function isClearedRoomAgentWorkSummary(value: unknown): value is ClearedRoomAgentWorkSummary;
+/** Return a canonical allowlisted copy, or reject without echoing private input. */
+export function parseRoomAgentWorkSummary(value: unknown): RoomAgentWorkSummary | null;

package/shared/room-agent-work.mjs

@@ -0,0 +1,44 @@
+// Room-public, host-reported evidence; never execution or approval authority.
+// No free-form strings, native handles, paths, command text, or output belong
+// in this version. Both the publisher and server use this strict boundary.
+export const ROOM_WORK_STATES = [
+  "active", "completed", "completed_no_reply", "failed", "interrupted", "lost", "unknown",
+];
+export const ROOM_WORK_OPERATION_OUTCOMES = [
+  "unresolved", "succeeded", "failed", "denied_before_start", "cancelled_before_start",
+  "interrupted_after_start", "lost_after_start",
+];
+
+function exactKeys(value, keys) {
+  return !!value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).length === keys.length
+    && keys.every((key) => Object.hasOwn(value, key));
+}
+
+export function isClearedRoomAgentWorkSummary(value) {
+  return exactKeys(value, ["version", "availability"]) && value.version === 1 && value.availability === "cleared";
+}
+
+/** Return a canonical allowlisted copy, or reject without echoing private input. */
+export function parseRoomAgentWorkSummary(value) {
+  if (!exactKeys(value, ["version", "recorded_state", "evidence_incomplete", "elapsed_ms", "operation_counts"])
+    || value.version !== 1 || !ROOM_WORK_STATES.includes(value.recorded_state)
+    || typeof value.evidence_incomplete !== "boolean"
+    || (value.elapsed_ms !== null && (!Number.isSafeInteger(value.elapsed_ms) || Number(value.elapsed_ms) < 0))
+    || !exactKeys(value.operation_counts, ROOM_WORK_OPERATION_OUTCOMES)) return null;
+  const counts = {};
+  let total = 0;
+  for (const outcome of ROOM_WORK_OPERATION_OUTCOMES) {
+    const count = value.operation_counts[outcome];
+    if (!Number.isSafeInteger(count) || Number(count) < 0) return null;
+    counts[outcome] = Number(count);
+    total += Number(count);
+  }
+  // A bounded evidence snapshot, not an unbounded lifetime counter.
+  if (total > 10_000) return null;
+  return {
+    version: 1, recorded_state: value.recorded_state,
+    evidence_incomplete: value.evidence_incomplete, elapsed_ms: value.elapsed_ms,
+    operation_counts: counts,
+  };
+}

package/shared/room-resource-invalidation.d.mts

@@ -0,0 +1,38 @@
+export const ROOM_RESOURCE_INVALIDATION_CAPABILITY: "resource_invalidation_v1";
+export const ROOM_RESOURCE_AGENT_WORK: "agent_work";
+/** Content-free approval-state hint; consumers repair through separately authorized exact reads. */
+export const ROOM_RESOURCE_AGENT_APPROVAL: "agent_approval";
+export const ROOM_RESOURCE_EXECUTION_DELEGATION: "execution_delegation";
+/** Protocol-known references; consumers independently choose what they render. */
+export const ROOM_RESOURCE_INVALIDATION_RESOURCES: readonly [
+  "agent_work",
+  "agent_approval",
+  "execution_delegation",
+];
+
+export type RoomResourceInvalidationResource =
+  typeof ROOM_RESOURCE_INVALIDATION_RESOURCES[number];
+
+export type RoomResourceInvalidationPointer<Resource extends string = string> = {
+  room_id: string;
+  resource: Resource;
+};
+
+export type RoomResourceInvalidationParseResult =
+  | {
+      status: "supported";
+      pointer: RoomResourceInvalidationPointer<RoomResourceInvalidationResource>;
+    }
+  | {
+      status: "unsupported";
+      pointer: RoomResourceInvalidationPointer;
+    }
+  | { status: "malformed" };
+
+/**
+ * Parse a bounded room-resource pointer without echoing malformed input.
+ * Unknown but well-formed resources remain forward-compatible cursor no-ops.
+ */
+export function parseRoomResourceInvalidation(
+  value: unknown,
+): RoomResourceInvalidationParseResult;

package/shared/room-resource-invalidation.mjs

@@ -0,0 +1,50 @@
+export const ROOM_RESOURCE_INVALIDATION_CAPABILITY = "resource_invalidation_v1";
+export const ROOM_RESOURCE_AGENT_WORK = "agent_work";
+// Content-free hint emitted when an approval projection is published or its
+// decision-relevant room state changes. Consumers repair through separately
+// authorized exact reads; the pointer never carries approval content.
+export const ROOM_RESOURCE_AGENT_APPROVAL = "agent_approval";
+export const ROOM_RESOURCE_EXECUTION_DELEGATION = "execution_delegation";
+// Protocol-known references. Each consumer still decides which surfaces, if
+// any, react to a supported pointer.
+export const ROOM_RESOURCE_INVALIDATION_RESOURCES = [
+  ROOM_RESOURCE_AGENT_WORK,
+  ROOM_RESOURCE_AGENT_APPROVAL,
+  ROOM_RESOURCE_EXECUTION_DELEGATION,
+];
+
+function exactKeys(value, keys) {
+  return !!value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).length === keys.length
+    && keys.every((key) => Object.hasOwn(value, key));
+}
+
+function isValidRoomIdentifier(value) {
+  return typeof value === "string"
+    && value.length > 0
+    && value.length <= 512
+    && value.trim() === value
+    && !/[\u0000-\u001f\u007f]/.test(value);
+}
+
+function isValidResource(value) {
+  return typeof value === "string"
+    && /^[a-z0-9][a-z0-9._-]{0,63}$/.test(value);
+}
+
+/**
+ * Parse a bounded room-resource pointer without echoing malformed input.
+ * Unknown but well-formed resources remain forward-compatible cursor no-ops.
+ */
+export function parseRoomResourceInvalidation(value) {
+  if (
+    !exactKeys(value, ["room_id", "resource"])
+    || !isValidRoomIdentifier(value.room_id)
+    || !isValidResource(value.resource)
+  ) return { status: "malformed" };
+
+  const pointer = { room_id: value.room_id, resource: value.resource };
+  return ROOM_RESOURCE_INVALIDATION_RESOURCES.includes(value.resource)
+    ? { status: "supported", pointer }
+    : { status: "unsupported", pointer };
+}

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;

package/shared/routing-aliases.mjs

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Stable cross-engine fold: ASCII A-Z only. Unicode case conversion varies by
+ * JS/ICU/PostgreSQL version and locale, so non-ASCII aliases are deliberately
+ * case-sensitive while exact non-ASCII labels still match everywhere.
+ */
+function foldRoutingText(value) {
+  return String(value ?? "").replace(/[A-Z]/g, (character) =>
+    String.fromCharCode(character.charCodeAt(0) + 32));
+}
+
+export function normalizeRoutingSender(value) {
+  return foldRoutingText(typeof value === "string" ? value.trim() : "")
+    .replace(/\s+/g, " ");
+}
+
+export function normalizeRoutingHandle(value) {
+  return foldRoutingText(typeof value === "string" ? value.trim() : "")
+    .replace(/[^a-z0-9_.:/-]+/g, "");
+}
+
+function routingIdentityAliasInputs(identity) {
+  const agentKey = typeof identity?.agentKey === "string"
+    ? identity.agentKey
+    : typeof identity?.agent_key === "string"
+      ? identity.agent_key
+      : "";
+  return Array.from(new Set([
+    identity?.actorLabel ?? identity?.actor_label,
+    identity?.displayName ?? identity?.display_name,
+    agentKey,
+    agentKey.split("/").pop(),
+  ].map((value) => typeof value === "string" ? value.trim() : "").filter(Boolean)));
+}
+
+export function routingIdentityAliases(identity) {
+  const aliases = new Set();
+  for (const value of routingIdentityAliasInputs(identity)) {
+    const senderAlias = normalizeRoutingSender(value);
+    if (senderAlias) aliases.add(senderAlias);
+    const handleAlias = normalizeRoutingHandle(value);
+    if (handleAlias) aliases.add(handleAlias);
+  }
+  return aliases;
+}
+
+export function routingSenderAliasRows(sender, segmentLimit = 16) {
+  const raw = typeof sender === "string" ? sender : "";
+  const fullAlias = normalizeRoutingSender(raw);
+  const byAlias = new Map();
+  if (fullAlias) byAlias.set(fullAlias, true);
+  for (const segment of raw.split("|").slice(0, Math.max(0, segmentLimit))) {
+    const alias = normalizeRoutingSender(segment);
+    if (alias && !byAlias.has(alias)) byAlias.set(alias, false);
+  }
+  return [...byAlias].map(([alias, isFull]) => ({ alias, isFull }));
+}
+
+export function routingSenderAliases(sender, segmentLimit = 16) {
+  return new Set(routingSenderAliasRows(sender, segmentLimit).map(({ alias }) => alias));
+}
+
+export function routingAliasHash(alias) {
+  return createHash("md5").update(alias).digest("hex");
+}

package/shared/sqlite-thread-routing.d.mts

@@ -0,0 +1,72 @@
+import type { RoutingIdentityLike } from "./routing-aliases.mjs";
+
+export type SqliteRoutingDatabase = {
+  exec(sql: string): void;
+  prepare(sql: string): {
+    all(...params: unknown[]): Record<string, unknown>[];
+    get(...params: unknown[]): Record<string, unknown> | undefined;
+    run(...params: unknown[]): unknown;
+  };
+};
+
+export const LOCAL_THREAD_ROUTING_BACKFILL_BATCH_SIZE: number;
+export const LOCAL_THREAD_ROUTING_LOOKUP_BATCH_SIZE: number;
+export const LOCAL_THREAD_ROUTING_BACKFILL_TIME_BUDGET_MS: number;
+export class LocalThreadRoutingProjectionUnavailableError extends Error {}
+export function ensureLocalThreadRoutingProjectionSchema(database: SqliteRoutingDatabase): void;
+export function ensureLocalThreadRoutingProjectionSchemaAsync(
+  database: SqliteRoutingDatabase,
+  options?: { maxWaitMs?: number; random?: () => number },
+): Promise<void>;
+export function runLocalSqliteWriteTransactionAsync<T>(
+  database: SqliteRoutingDatabase,
+  work: () => T,
+  options?: { maxWaitMs?: number; random?: () => number },
+): Promise<T>;
+export function projectLocalThreadRoutingMessage(
+  database: SqliteRoutingDatabase,
+  row: {
+    room_id: string;
+    number: number;
+    thread_root_number?: number | null;
+    reply_to_number?: number | null;
+    sender: string;
+    text?: string;
+    source?: string | null;
+    timestamp?: string;
+    [key: string]: unknown;
+  },
+): void;
+export function runLocalThreadRoutingBackfillBatch(
+  database: SqliteRoutingDatabase,
+  batchSize?: number,
+): { processed: number; completed: boolean };
+export function scheduleLocalThreadRoutingBackfill(
+  database: SqliteRoutingDatabase,
+  options?: {
+    onError?: (error: unknown, delayMs: number | null) => void;
+    setImmediate?: (callback: () => void) => { unref?(): void } | unknown;
+    setTimeout?: (callback: () => void, delayMs: number) => { unref?(): void } | unknown;
+  },
+): void;
+export function scheduleLocalThreadRoutingRootsRepair(
+  database: SqliteRoutingDatabase,
+  roomId: string,
+  rootNumbers: readonly number[],
+): void;
+export function invalidateLocalThreadRoutingRoots(
+  database: SqliteRoutingDatabase,
+  roomId: string,
+  rootNumbers: readonly number[],
+): void;
+export function getLocalThreadRoutingAgentKeysForRoots(
+  database: SqliteRoutingDatabase,
+  roomId: string,
+  rootNumbers: readonly number[],
+  identities: readonly RoutingIdentityLike[],
+  options?: {
+    foregroundTimeBudgetMs?: number;
+    scheduleOnTimeout?: boolean;
+    signal?: AbortSignal;
+  },
+): Promise<Map<number, Set<string>>>;