letagents 0.12.19 → 0.12.21

package/shared/local-supervised-routing.d.mts

@@ -0,0 +1,9 @@
+import type { SqliteRoutingDatabase } from "./sqlite-thread-routing.mjs";
+export type LocalSupervisedMessageRow = {
+  room_id: string; number: number; sender: string; text: string; source: string | null;
+  publisher_agent_key: string | null; thread_root_number: number | null; reply_to_number: number | null;
+  control_authorized: number | null; timestamp: string; sync_key: string | null;
+};
+export function ensureLocalSupervisedRoutingSchema(db: SqliteRoutingDatabase): void;
+export function captureLocalSupervisedRouting(db: SqliteRoutingDatabase, row: LocalSupervisedMessageRow): void;
+export function runLocalSupervisedMessageWrite<T>(db: SqliteRoutingDatabase, roomId: string, threadRootNumber: number | null, work: () => T): Promise<T>;

package/shared/local-supervised-routing.mjs

@@ -0,0 +1,93 @@
+import { createGlobalAgentAddressResolver, decideAgentMessageActivation, humanConversationFallback } from "./activation-routing.mjs";
+import { readProjectedLocalThreadRoutingAgentKeys, ensureRequestedRootsProjected, runLocalSqliteWriteTransactionAsync, LocalThreadRoutingProjectionChangedError } from "./sqlite-thread-routing.mjs";
+import { parseSupervisedReplySourceNumber } from "./message-contracts.mjs";
+export function ensureLocalSupervisedRoutingSchema(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS local_supervisor_message_routes (
+    room_id TEXT NOT NULL, message_id TEXT NOT NULL, routes_json TEXT NOT NULL,
+    PRIMARY KEY(room_id, message_id)
+  ) STRICT`);
+}
+function recentRecipient(db, message) {
+    const recent = db.prepare(`SELECT * FROM local_chat_messages WHERE room_id=? AND number<?
+    ORDER BY number DESC LIMIT 50`).all(message.room_id, message.number)
+        .filter(row => Date.parse(String(row.timestamp)) >= Date.parse(message.timestamp) - 30 * 60_000);
+    const human = recent.find(row => row.source === "browser" && !row.publisher_agent_key
+        && row.control_authorized === 1 && row.thread_root_number === null);
+    if (!human)
+        return null;
+    const captured = db.prepare("SELECT routes_json FROM local_supervisor_message_routes WHERE room_id=? AND message_id=?")
+        .get(message.room_id, `msg_${human.number}`);
+    if (!captured)
+        return null;
+    const recipients = Object.entries(JSON.parse(String(captured.routes_json)))
+        .filter(([, route]) => route.decision === "activate").map(([key]) => key);
+    if (recipients.length === 1)
+        return recipients[0];
+    const answered = new Set();
+    for (const reply of recent) {
+        const key = String(reply.publisher_agent_key || "");
+        const prefix = `local-supervised:${key}:`;
+        const receipt = String(reply.sync_key || "");
+        if (reply.source === "agent" && Number(reply.number) > Number(human.number)
+            && recipients.includes(key) && (reply.reply_to_number === human.number
+            || (receipt.startsWith(prefix)
+                && parseSupervisedReplySourceNumber(receipt.slice(prefix.length)) === human.number)))
+            answered.add(key);
+    }
+    return answered.size === 1 ? [...answered][0] : null;
+}
+/** Capture all recipients atomically with the message, including the empty-room case. */
+export function captureLocalSupervisedRouting(db, row) {
+    const reply = row.reply_to_number ? db.prepare("SELECT * FROM local_chat_messages WHERE room_id=? AND number=?")
+        .get(row.room_id, row.reply_to_number) : null;
+    const registered = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='local_supervisor_grants'").get();
+    const identities = registered
+        ? db.prepare("SELECT agent_key,display_name FROM local_supervisor_grants WHERE room_id=? AND revoked_at IS NULL ORDER BY entry_id")
+            .all(row.room_id).map(grant => ({ agent_key: String(grant.agent_key), display_name: String(grant.display_name),
+            actor_label: String(grant.display_name), agent_instance_id: null, agent_session_id: null, session_kind: "worker" })) : [];
+    const id = `msg_${row.number}`;
+    const rootId = `msg_${row.thread_root_number ?? row.number}`;
+    const threadReply = row.thread_root_number !== null && row.thread_root_number !== row.number;
+    const message = { id, text: row.text, sender: row.sender, source: row.source,
+        thread_root_id: threadReply ? rootId : null, reply_to: reply ? { id: `msg_${reply.number}`, sender: reply.sender } : null };
+    const address = createGlobalAgentAddressResolver(identities)(message);
+    const participants = threadReply ? readProjectedLocalThreadRoutingAgentKeys(db, row.room_id, [row.thread_root_number], identities.map(identity => ({ agentKey: identity.agent_key, displayName: identity.display_name, actorLabel: identity.actor_label })))
+        .get(row.thread_root_number) ?? new Set() : new Set();
+    const fallback = humanConversationFallback({ source: row.source,
+        publisherAccountId: row.control_authorized === 1 ? "local-owner" : null, publisherAgentKey: row.publisher_agent_key,
+        explicitlyAddressed: address.broadcast || address.hasAgentMention || threadReply || Boolean(reply),
+        registeredAgentKeys: identities.map(identity => identity.agent_key),
+        recentAgentKey: identities.length > 2 ? recentRecipient(db, row) : null });
+    const routes = {};
+    for (const identity of identities) {
+        const key = identity.agent_key;
+        let decision = decideAgentMessageActivation(message, identity, {
+            selfMessageIds: new Set(row.source === "agent" && row.publisher_agent_key === key ? [id] : []),
+            explicitMentionMessageIds: new Set(address.explicitMentionKeys.has(key) ? [id] : []),
+            replyTargetMessageIds: new Set(!threadReply && (reply?.publisher_agent_key
+                ? reply.publisher_agent_key === key : address.replyTargetKeys.has(key)) ? [id] : []),
+            threadParticipantRootIds: new Set(participants.has(key) ? [rootId] : []),
+        });
+        if (row.source === "agent" && !row.publisher_agent_key)
+            decision = { decision: "silent", reason: "unaddressed", addressed: false };
+        if (decision.reason === "unaddressed" && fallback?.agentKeys.includes(key)) {
+            decision = { decision: "activate", reason: fallback.reason, addressed: true };
+        }
+        routes[key] = decision;
+    }
+    db.prepare("INSERT INTO local_supervisor_message_routes(room_id,message_id,routes_json) VALUES(?,?,?)")
+        .run(row.room_id, id, JSON.stringify(routes));
+}
+
+/** Repair outside the write lock; a concurrent invalidation rolls back the entire send. */
+export async function runLocalSupervisedMessageWrite(db, roomId, threadRootNumber, work) {
+  const deadline = performance.now() + 2_000;
+  for (;;) {
+    if (threadRootNumber) await ensureRequestedRootsProjected(db, roomId, [threadRootNumber]);
+    try {
+      return await runLocalSqliteWriteTransactionAsync(db, work);
+    } catch (error) {
+      if (!(error instanceof LocalThreadRoutingProjectionChangedError) || performance.now() >= deadline) throw error;
+    }
+  }
+}

package/shared/message-contracts.d.mts

@@ -30,3 +30,5 @@ export type ParsedAccountAgentRouting =
 export function parseAccountAgentRoutingEnvelope(
   routing: unknown,
 ): ParsedAccountAgentRouting | undefined;
+
+export function parseSupervisedReplySourceNumber(clientMessageId: string | null): number | null;

package/shared/message-contracts.mjs

@@ -107,3 +107,14 @@ export function parseAccountAgentRoutingEnvelope(routing) {
     controlAuthorized: routing.control_authorized === true,
   };
 }
+
+/** Only daemon publication identities can link an answer to its source receipt. */
+export function parseSupervisedReplySourceNumber(clientMessageId) {
+  if (!clientMessageId) return null;
+  const parts = clientMessageId.split(":");
+  if (parts[0] !== "supervised-room" || parts.at(-2) !== "reply" || parts.at(-1) !== "v1") return null;
+  const body = parts.slice(1, -2);
+  if (body.length !== 2 && body.length !== 3) return null;
+  const source = body.at(-1);
+  return source ? parsePositivePgIntegerScopedId(source, "msg") : null;
+}

package/shared/room-api-origin.d.mts

@@ -0,0 +1,3 @@
+export const LOCAL_ROOM_API_ORIGIN: "letagents-local://rooms";
+export function isLocalRoomApi(value: unknown): boolean;
+export function roomApiOrigin(value: string): string;

package/shared/room-api-origin.mjs

@@ -0,0 +1,12 @@
+/** An in-process storage adapter, never an HTTP endpoint or cloud credential audience. */
+export const LOCAL_ROOM_API_ORIGIN = "letagents-local://rooms";
+
+export function isLocalRoomApi(value) {
+  return value === LOCAL_ROOM_API_ORIGIN;
+}
+
+/** Preserve the existing HTTP normalization while retaining the explicit local authority. */
+export function roomApiOrigin(value) {
+  if (isLocalRoomApi(value)) return LOCAL_ROOM_API_ORIGIN;
+  return new URL(value).origin;
+}

package/shared/room-knowledge.d.mts

@@ -0,0 +1,25 @@
+export type KnowledgeType = 'memory' | 'attention';
+export type MemoryCategory = 'goal' | 'decision' | 'constraint' | 'term' | 'reference';
+export type AttentionCategory = 'question' | 'decision' | 'approval' | 'review';
+export interface KnowledgeActor { id: string; label: string; kind: 'human' | 'agent' }
+export interface KnowledgeInput {
+  category: MemoryCategory | AttentionCategory; title: string; body: string;
+  recommendation?: string; unblocks?: string; source_url?: string; source_message_id?: string;
+}
+export interface KnowledgeRecord extends Required<KnowledgeInput> {
+  id: string; room_id: string; type: KnowledgeType; version: number;
+  author: KnowledgeActor; updated_by: KnowledgeActor; created_at: string; updated_at: string; archived: boolean;
+  response: { body: string; actor: KnowledgeActor; at: string } | null;
+}
+export interface KnowledgePage { records: KnowledgeRecord[]; truncated: boolean }
+export interface KnowledgeRevisionInput extends Partial<KnowledgeInput> { expected_version: number; response?: string; archived?: boolean }
+export const MEMORY_CATEGORIES: MemoryCategory[];
+export const ATTENTION_CATEGORIES: AttentionCategory[];
+export class RoomKnowledgeError extends Error { status: number; constructor(message: string, status?: number) }
+export function parseKnowledgeInput(type: KnowledgeType, value: unknown): Required<KnowledgeInput>;
+export function knowledgeId(value: unknown): string;
+export function createKnowledgeRecord(room_id: string, type: KnowledgeType, input: KnowledgeInput & { client_id: string }, author: KnowledgeActor, now?: string): KnowledgeRecord;
+export function reviseKnowledgeRecord(record: KnowledgeRecord, input: KnowledgeRevisionInput, actor: KnowledgeActor, now?: string): KnowledgeRecord;
+export function assertKnowledgeReplay(existing: KnowledgeRecord, candidate: KnowledgeRecord): void;
+
+export function formatAttentionResponse(record: KnowledgeRecord): string;

package/shared/room-knowledge.mjs

@@ -0,0 +1,74 @@
+export const MEMORY_CATEGORIES = ['goal', 'decision', 'constraint', 'term', 'reference'];
+export const ATTENTION_CATEGORIES = ['question', 'decision', 'approval', 'review'];
+
+export class RoomKnowledgeError extends Error {
+  constructor(message, status = 400) { super(message); this.status = status; }
+}
+
+function text(value, name, max, required = false) {
+  if (value == null && !required) return '';
+  if (typeof value !== 'string' || value.length > max || (required && !value.trim())) {
+    throw new RoomKnowledgeError(`${name} must be ${required ? 'nonempty text' : 'text'} of at most ${max} characters.`);
+  }
+  return value.trim();
+}
+
+export function parseKnowledgeInput(type, value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new RoomKnowledgeError('A record is required.');
+  const categories = type === 'memory' ? MEMORY_CATEGORIES : type === 'attention' ? ATTENTION_CATEGORIES : [];
+  if (!categories.includes(value.category)) throw new RoomKnowledgeError('Choose a valid category.');
+  const source_url = text(value.source_url, 'Source URL', 2048);
+  if (source_url) {
+    let url;
+    try { url = new URL(source_url); } catch { throw new RoomKnowledgeError('Source URL must be an HTTP or HTTPS link.'); }
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password) throw new RoomKnowledgeError('Source URL must be an HTTP or HTTPS link without credentials.');
+  }
+  const source_message_id = text(value.source_message_id, 'Source message', 40);
+  if (source_message_id && (!/^msg_[1-9]\d{0,9}$/.test(source_message_id) || Number(source_message_id.slice(4)) > 2147483647)) throw new RoomKnowledgeError('Invalid source message.');
+  return {
+    category: value.category,
+    title: text(value.title, 'Title', 160, true),
+    body: text(value.body, 'Context', 8000, true),
+    recommendation: type === 'attention' ? text(value.recommendation, 'Recommendation', 2000) : '',
+    unblocks: type === 'attention' ? text(value.unblocks, 'What this unblocks', 1000) : '',
+    source_url,
+    source_message_id,
+  };
+}
+
+export function knowledgeId(value) {
+  if (typeof value !== 'string' || !/^[a-zA-Z0-9_-]{8,80}$/.test(value)) throw new RoomKnowledgeError('Use a stable client ID of 8–80 letters, numbers, underscores or hyphens.');
+  return value;
+}
+
+export function createKnowledgeRecord(room_id, type, input, author, now = new Date().toISOString()) {
+  return { ...parseKnowledgeInput(type, input), id: knowledgeId(input.client_id), room_id, type,
+    version: 1, author, updated_by: author, created_at: now, updated_at: now,
+    archived: false, response: null };
+}
+
+export function reviseKnowledgeRecord(record, input, actor, now = new Date().toISOString()) {
+  if (input.expected_version !== record.version) throw new RoomKnowledgeError('This changed since you opened it. Refresh to see the latest version.', 409);
+  if (actor.kind !== 'human') throw new RoomKnowledgeError('Only a human can revise shared memory or answer a request.', 403);
+  if (record.type === 'attention') {
+    if (record.response) throw new RoomKnowledgeError('This request has already been answered.', 409);
+    return { ...record, version: record.version + 1, updated_at: now, updated_by: actor,
+      response: { body: text(input.response, 'Response', 8000, true), actor, at: now } };
+  }
+  if (input.archived !== undefined && typeof input.archived !== 'boolean') throw new RoomKnowledgeError('Archived must be true or false.');
+  const content = input.archived !== undefined ? {} : parseKnowledgeInput('memory', input);
+  return { ...record, ...content, archived: input.archived ?? record.archived,
+    version: record.version + 1, updated_at: now, updated_by: actor };
+}
+
+export function assertKnowledgeReplay(existing, candidate) {
+  const keys = ['type', 'category', 'title', 'body', 'recommendation', 'unblocks', 'source_url', 'source_message_id'];
+  if (existing.author.id !== candidate.author.id || existing.author.kind !== candidate.author.kind || keys.some(key => existing[key] !== candidate[key])) {
+    throw new RoomKnowledgeError('This client ID was already used for different content. Use a new ID for a new record.', 409);
+  }
+}
+
+export function formatAttentionResponse(record) {
+  const handle = record.author.kind === 'agent' ? record.author.id.trim().replace(/[A-Z]/g, c => c.toLowerCase()).replace(/[^a-z0-9_.:/-]+/g, '') : '';
+  return `${handle ? `@agent:${handle}\n\n` : ''}Human response (${record.id}):\n\n${record.response.body}`;
+}

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

@@ -70,3 +70,7 @@ export function getLocalThreadRoutingAgentKeysForRoots(
     signal?: AbortSignal;
   },
 ): Promise<Map<number, Set<string>>>;
+
+export function ensureRequestedRootsProjected(database: SqliteRoutingDatabase, roomId: string, rootNumbers: readonly number[], options?: { foregroundTimeBudgetMs?: number; scheduleOnTimeout?: boolean; signal?: AbortSignal }): Promise<void>;
+export function readProjectedLocalThreadRoutingAgentKeys(database: SqliteRoutingDatabase, roomId: string, rootNumbers: readonly number[], identities: readonly RoutingIdentityLike[]): Map<number, Set<string>>;
+export class LocalThreadRoutingProjectionChangedError extends LocalThreadRoutingProjectionUnavailableError {}

package/shared/sqlite-thread-routing.mjs

@@ -788,7 +788,7 @@ export function invalidateLocalThreadRoutingRoots(database, roomId, rootNumbersI
   }
 }
 
-async function ensureRequestedRootsProjected(database, roomId, rootNumbers, options = {}) {
+export async function ensureRequestedRootsProjected(database, roomId, rootNumbers, options = {}) {
   if (rootNumbers.length > LOCAL_THREAD_ROUTING_MAX_REQUESTED_ROOTS) {
     throw new LocalThreadRoutingProjectionUnavailableError();
   }
@@ -869,6 +869,33 @@ export async function getLocalThreadRoutingAgentKeysForRoots(
   if (rootNumbers.length === 0 || identities.length === 0) return new Map();
   await ensureRequestedRootsProjected(database, roomId, rootNumbers, options);
 
+  const batches = readProjectedThreadRoutingBatches(database, roomId, rootNumbers, identities);
+  for (;;) {
+    const step = batches.next();
+    if (step.done) return step.value;
+    await yieldToEventLoop();
+  }
+}
+
+/** Read prepared projections synchronously inside an existing message transaction. */
+export function readProjectedLocalThreadRoutingAgentKeys(database, roomId, rootNumbers, identities) {
+  const statements = requestedRootProjectionStatements(database);
+  const rootsJson = JSON.stringify(rootNumbers);
+  if (pendingRequestedRoots(statements, roomId, rootsJson).length
+    || statements.invalidated.all(roomId, rootsJson).length) {
+    throw new LocalThreadRoutingProjectionChangedError();
+  }
+  const batches = readProjectedThreadRoutingBatches(database, roomId, rootNumbers, identities);
+  for (;;) {
+    const step = batches.next();
+    if (step.done) return step.value;
+  }
+}
+
+export class LocalThreadRoutingProjectionChangedError extends LocalThreadRoutingProjectionUnavailableError {}
+
+function* readProjectedThreadRoutingBatches(database, roomId, rootNumbers, identities) {
+  if (!rootNumbers.length || !identities.length) return new Map();
   const keysByHash = new Map();
   const durableKeysByHash = new Map();
   for (const identity of identities) {
@@ -938,7 +965,7 @@ export async function getLocalThreadRoutingAgentKeysForRoots(
       keys.add(agentKey);
       result.set(root, keys);
     }
-    await yieldToEventLoop();
+    yield;
   }
 
   const aliasInputs = [];
@@ -1032,7 +1059,7 @@ export async function getLocalThreadRoutingAgentKeysForRoots(
       keys.add(agentKey);
       result.set(root, keys);
     }
-    await yieldToEventLoop();
+    yield;
   }
   return result;
 }