@segmentstream/agent 0.1.4 → 0.2.0

package/dist/extension/lib/connection-proxy.mjs

@@ -5,6 +5,8 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 const MAXIMUM_PROXY_BODY_BYTES = 2097152;
+const MAXIMUM_DOWNLOAD_BYTES = 20971520;
+const PROXY_STREAM_MEDIA_TYPE = "application/vnd.segmentstream.proxy-stream.v1+ndjson";
 const CALL_TIMEOUT_MS = 4e4;
 var ConnectionProxyError = class extends Error {
 	name = "ConnectionProxyError";
@@ -55,59 +57,153 @@ function connectionProxy(input) {
 	const { environment, connection } = input;
 	const fetchImpl = input.fetch ?? fetch;
 	const url = `${`${environment.segmentstreamUrl}/api/internal/v1/workspaces/${environment.workspaceId}`}/ontology/connections/${encodeURIComponent(connection)}/request`;
+	async function send(call, accept) {
+		if (call.body.byteLength > 2097152) throw new ConnectionProxyError({
+			connection,
+			code: "invalid_request",
+			message: "The request body exceeds the proxy's 2 MiB limit."
+		});
+		const token = await input.token();
+		try {
+			return await fetchImpl(url, {
+				method: "POST",
+				headers: {
+					"x-segmentstream-runtime-identity": token,
+					"x-segmentstream-organization-id": environment.organizationId,
+					"content-type": "application/json",
+					accept
+				},
+				body: JSON.stringify({
+					...call.api === void 0 ? {} : { api: call.api },
+					method: call.method,
+					path: call.path,
+					headers: call.headers,
+					body: Buffer.from(call.body).toString("base64")
+				}),
+				redirect: "error",
+				signal: AbortSignal.timeout(CALL_TIMEOUT_MS)
+			});
+		} catch (error) {
+			throw new ConnectionProxyError({
+				connection,
+				code: error instanceof DOMException && error.name === "TimeoutError" ? "timeout" : "unavailable",
+				message: "SegmentStream's connection proxy could not be reached.",
+				cause: error
+			});
+		}
+	}
+	async function buffered(response) {
+		const text = await response.text();
+		let value;
+		try {
+			value = JSON.parse(text);
+		} catch (error) {
+			if (response.ok) throw new ConnectionProxyError({
+				connection,
+				code: "invalid_response",
+				message: "The connection proxy answered with an invalid response.",
+				cause: error
+			});
+			throw refusal(connection, response.status, void 0, error);
+		}
+		if (!response.ok) throw refusal(connection, response.status, value);
+		return decodeReply(connection, value);
+	}
 	return {
 		connection,
 		async request(call) {
-			if (call.body.byteLength > 2097152) throw new ConnectionProxyError({
-				connection,
-				code: "invalid_request",
-				message: "The request body exceeds the proxy's 2 MiB limit."
-			});
-			const token = await input.token();
-			let response;
+			return buffered(await send(call, "application/json"));
+		},
+		async download(call, maxBytes = MAXIMUM_DOWNLOAD_BYTES) {
+			const response = await send(call, PROXY_STREAM_MEDIA_TYPE);
+			const type = response.headers.get("content-type") ?? "";
+			if (!response.ok || !type.startsWith("application/vnd.segmentstream.proxy-stream.v1+ndjson") || response.body === null) return buffered(response);
 			try {
-				response = await fetchImpl(url, {
-					method: "POST",
-					headers: {
-						"x-segmentstream-runtime-identity": token,
-						"x-segmentstream-organization-id": environment.organizationId,
-						"content-type": "application/json",
-						accept: "application/json"
-					},
-					body: JSON.stringify({
-						...call.api === void 0 ? {} : { api: call.api },
-						method: call.method,
-						path: call.path,
-						headers: call.headers,
-						body: Buffer.from(call.body).toString("base64")
-					}),
-					redirect: "error",
-					signal: AbortSignal.timeout(CALL_TIMEOUT_MS)
-				});
+				return await framedReply(connection, response.body, maxBytes);
 			} catch (error) {
+				if (error instanceof ConnectionProxyError) throw error;
 				throw new ConnectionProxyError({
 					connection,
 					code: error instanceof DOMException && error.name === "TimeoutError" ? "timeout" : "unavailable",
-					message: "SegmentStream's connection proxy could not be reached.",
+					message: "SegmentStream's connection proxy stopped relaying the response.",
 					cause: error
 				});
 			}
-			const text = await response.text();
-			let value;
-			try {
-				value = JSON.parse(text);
-			} catch (error) {
-				if (response.ok) throw new ConnectionProxyError({
+		}
+	};
+}
+async function framedReply(connection, body, maxBytes) {
+	const invalid = () => new ConnectionProxyError({
+		connection,
+		code: "invalid_response",
+		message: "The connection proxy answered with an invalid stream."
+	});
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	const chunks = [];
+	let head;
+	let size = 0;
+	let pending = "";
+	let ended = false;
+	try {
+		while (!ended) {
+			const next = await reader.read();
+			if (next.done) break;
+			pending += decoder.decode(next.value, { stream: true });
+			for (let newline = pending.indexOf("\n"); newline >= 0; newline = pending.indexOf("\n")) {
+				const line = pending.slice(0, newline);
+				pending = pending.slice(newline + 1);
+				if (line.trim() === "") continue;
+				let frame;
+				try {
+					frame = JSON.parse(line);
+				} catch (error) {
+					throw new ConnectionProxyError({
+						connection,
+						code: "invalid_response",
+						message: "The connection proxy answered with an invalid stream.",
+						cause: error
+					});
+				}
+				if (!isRecord(frame)) throw invalid();
+				if (head === void 0) {
+					if (typeof frame.statusCode !== "number" || !isHeaderPairs(frame.headers)) throw invalid();
+					head = {
+						status: frame.statusCode,
+						headers: frame.headers
+					};
+				} else if (typeof frame.data === "string") {
+					const chunk = Buffer.from(frame.data, "base64");
+					size += chunk.byteLength;
+					if (size > maxBytes) throw new ConnectionProxyError({
+						connection,
+						code: "too_large",
+						message: `The response exceeds the ${Math.floor(maxBytes / 1024 / 1024)} MiB download limit.`
+					});
+					chunks.push(chunk);
+				} else if (frame.end === true) {
+					ended = true;
+					break;
+				} else if (typeof frame.error === "string") throw new ConnectionProxyError({
 					connection,
-					code: "invalid_response",
-					message: "The connection proxy answered with an invalid response.",
-					cause: error
+					code: frame.error,
+					message: "SegmentStream's connection proxy failed while relaying the response."
 				});
-				throw refusal(connection, response.status, void 0, error);
+				else throw invalid();
 			}
-			if (!response.ok) throw refusal(connection, response.status, value);
-			return decodeReply(connection, value);
 		}
+	} finally {
+		await reader.cancel().catch(() => void 0);
+	}
+	if (head === void 0 || !ended) throw new ConnectionProxyError({
+		connection,
+		code: "unavailable",
+		message: "The connection proxy's stream ended before the response did."
+	});
+	return {
+		status: head.status,
+		headers: head.headers,
+		body: new Uint8Array(Buffer.concat(chunks))
 	};
 }
-export { ConnectionProxyError, MAXIMUM_PROXY_BODY_BYTES, connectionProxy };
+export { ConnectionProxyError, MAXIMUM_DOWNLOAD_BYTES, MAXIMUM_PROXY_BODY_BYTES, PROXY_STREAM_MEDIA_TYPE, connectionProxy };

package/dist/extension/lib/environment.d.ts

@@ -20,6 +20,19 @@ export interface ProxyEnvironment {
     readonly organizationId: string;
 }
 export declare function proxyEnvironment(environment?: Environment): ProxyEnvironment;
+/**
+ * Whom the agent trusts as a caller of its own routes: Vercel OIDC tokens of the functions of this
+ * deployment's project, such as the ontology service's. The platform sets the issuer and the audience
+ * on the project for the ontology service; Vercel sets `VERCEL_PROJECT_ID`.
+ */
+export interface RuntimeIdentityEnvironment {
+    /** The team's issuer, `https://oidc.vercel.com/<team slug>`, without a trailing slash. */
+    readonly issuer: string;
+    /** The audience Vercel issues function tokens for: `https://vercel.com/<team slug>`. */
+    readonly audience: string;
+    readonly projectId: string;
+}
+export declare function runtimeIdentityEnvironment(environment?: Environment): RuntimeIdentityEnvironment;
 /** The secret Telegram echoes in `X-Telegram-Bot-Api-Secret-Token`; `undefined` when unset. */
 export declare function webhookSecret(environment?: Environment): string | undefined;
 /**

package/dist/extension/lib/environment.mjs

@@ -33,6 +33,13 @@ function proxyEnvironment(environment = process.env) {
 		organizationId: required(environment, "SEGMENTSTREAM_ORGANIZATION_ID")
 	};
 }
+function runtimeIdentityEnvironment(environment = process.env) {
+	return {
+		issuer: withoutTrailingSlashes(required(environment, "SEGMENTSTREAM_RUNTIME_OIDC_ISSUER")),
+		audience: required(environment, "SEGMENTSTREAM_RUNTIME_OIDC_AUDIENCE"),
+		projectId: required(environment, "VERCEL_PROJECT_ID")
+	};
+}
 function webhookSecret(environment = process.env) {
 	const secret = environment.SEGMENTSTREAM_AGENT_WEBHOOK_SECRET;
 	return secret === void 0 || secret === "" ? void 0 : secret;
@@ -43,4 +50,4 @@ function channelsEnabled(environment = process.env) {
 function isPreview(environment = process.env) {
 	return environment.VERCEL_ENV === "preview";
 }
-export { AgentEnvironmentError, appOrigin, channelsEnabled, isPreview, proxyEnvironment, webhookSecret };
+export { AgentEnvironmentError, appOrigin, channelsEnabled, isPreview, proxyEnvironment, runtimeIdentityEnvironment, webhookSecret };

package/dist/extension/lib/identities.d.ts

@@ -3,7 +3,8 @@ import type { RuntimeToken } from "./runtime-token.js";
  * The ontology service's pairing routes (`agent-design.md`, section 13, "Identity"). The agent
  * calls them as the deployment, with its OIDC token: it looks up which member a chat account is
  * paired with, and asks for a pairing code when it is paired with nobody. The member approves the
- * code on the app's `/agent/connect` page.
+ * code on the app's `/agent/connect` page. It also reports the group chats it is in to the
+ * ontology's `agent_chat` registry.
  */
 /** A member as the ontology resolves a paired chat account, with their current roles. */
 export interface PairedMember {
@@ -33,12 +34,32 @@ export interface ChatAccount {
     readonly provider: string;
     readonly externalId: string;
 }
+/** A group chat in the ontology's `agent_chat` registry, with what members said it is for. */
+export interface AgentChat {
+    readonly id: string;
+    readonly title: string;
+    readonly purpose: string | null;
+    readonly whenToUse: string | null;
+}
 export interface AgentIdentities {
     lookup(account: ChatAccount): Promise<IdentityLookup>;
     /** Issues a pairing code, or returns the account's pending one while it has time left. */
     createPairing(account: ChatAccount & {
         readonly display?: string;
     }): Promise<Pairing>;
+    /**
+     * Records that the agent saw the group chat, and the paired member who wrote, if any, or the
+     * paired member who left it, whom the registry unlinks from the chat, or that the agent itself
+     * left it (`agentLeft`), which unlinks every member, or that the chat was the group
+     * `migratedFrom` before it became a supergroup, whose record the registry moves to the new id.
+     */
+    seenChat(chat: ChatAccount & {
+        readonly title: string;
+        readonly memberId?: string;
+        readonly leftMemberId?: string;
+        readonly agentLeft?: true;
+        readonly migratedFrom?: string;
+    }): Promise<AgentChat>;
 }
 /** The ontology service refused or failed a pairing call. Carries its error code, not its body. */
 export declare class AgentIdentityError extends Error {

package/dist/extension/lib/identities.mjs

@@ -54,6 +54,21 @@ function pairing(value) {
 		expiresAt: value.expires_at
 	};
 }
+function nullableString(value) {
+	return value === null || typeof value === "string";
+}
+function agentChat(value) {
+	if (!isRecord(value) || typeof value.id !== "string" || typeof value.title !== "string" || !nullableString(value.purpose) || !nullableString(value.whenToUse)) throw new AgentIdentityError({
+		code: "invalid_response",
+		message: "The ontology service answered the chat report with an invalid body."
+	});
+	return {
+		id: value.id,
+		title: value.title,
+		purpose: value.purpose,
+		whenToUse: value.whenToUse
+	};
+}
 async function refusal(response, call) {
 	const status = response.status;
 	let value;
@@ -127,6 +142,11 @@ function agentIdentities(input) {
 			const created = pairing(await response.json());
 			remember(pending, key, created);
 			return created;
+		},
+		async seenChat(chat) {
+			const response = await call("/chats/seen", { body: chat });
+			if (!response.ok) throw await refusal(response, "chat report");
+			return agentChat(await response.json());
 		}
 	};
 }

package/dist/extension/lib/runtime-identity.d.ts

@@ -0,0 +1,22 @@
+import { type JWTVerifyGetKey } from "jose";
+import type { RuntimeIdentityEnvironment } from "./environment.js";
+export type RuntimeVerification = {
+    readonly status: "valid";
+}
+/** `reason` names what failed, a jose code or a claim name, never a value. */
+ | {
+    readonly status: "invalid";
+    readonly reason: string;
+}
+/**
+ * The key set could not be read: not the token's fault. `reason` is the jose code, or the error's
+ * name and message from fetching the key set, never the token.
+ */
+ | {
+    readonly status: "unavailable";
+    readonly reason: string;
+};
+export type RuntimeTokenVerifier = (token: string) => Promise<RuntimeVerification>;
+/** The issuer's key set, at `<issuer>/.well-known/jwks` as Vercel publishes it; jose caches it. */
+export declare function runtimeKeySet(issuer: string): JWTVerifyGetKey;
+export declare function runtimeTokenVerifier(config: RuntimeIdentityEnvironment, keySet?: JWTVerifyGetKey): RuntimeTokenVerifier;

package/dist/extension/lib/runtime-identity.mjs

@@ -0,0 +1,62 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { createRemoteJWKSet, errors, jwtVerify } from "jose";
+const CLOCK_TOLERANCE_SECONDS = 5;
+const JWKS_TIMEOUT_MS = 5e3;
+function runtimeKeySet(issuer) {
+	return createRemoteJWKSet(new URL(`${issuer}/.well-known/jwks`), { timeoutDuration: JWKS_TIMEOUT_MS });
+}
+function keySetUnavailable(error) {
+	if (!(error instanceof errors.JOSEError)) return true;
+	return error instanceof errors.JWKSTimeout || error instanceof errors.JWKSInvalid || error.code === errors.JOSEError.code;
+}
+function unavailableReason(error) {
+	if (error instanceof errors.JOSEError) return error.code;
+	return error instanceof Error ? `${error.name}: ${error.message}` : "unknown";
+}
+function failureReason(error) {
+	if (error instanceof errors.JWTClaimValidationFailed || error instanceof errors.JWTExpired) return `claim:${error.claim}`;
+	return error instanceof errors.JOSEError ? error.code : "invalid";
+}
+function runtimeTokenVerifier(config, keySet = runtimeKeySet(config.issuer)) {
+	return async (token) => {
+		try {
+			const { payload } = await jwtVerify(token, keySet, {
+				algorithms: ["RS256"],
+				issuer: config.issuer,
+				audience: config.audience,
+				clockTolerance: CLOCK_TOLERANCE_SECONDS,
+				requiredClaims: [
+					"exp",
+					"iat",
+					"iss",
+					"aud",
+					"project_id",
+					"environment"
+				]
+			});
+			if (payload.project_id !== config.projectId) return {
+				status: "invalid",
+				reason: "claim:project_id"
+			};
+			if (payload.environment !== "production") return {
+				status: "invalid",
+				reason: "claim:environment"
+			};
+			return { status: "valid" };
+		} catch (error) {
+			return keySetUnavailable(error) ? {
+				status: "unavailable",
+				reason: unavailableReason(error)
+			} : {
+				status: "invalid",
+				reason: failureReason(error)
+			};
+		}
+	};
+}
+export { runtimeKeySet, runtimeTokenVerifier };

package/dist/extension/lib/telegram/adapter.d.ts

@@ -1,6 +1,8 @@
 import { type TelegramChannel } from "eve/channels/telegram";
 import type { SessionSettings, TelegramSettings } from "../../config.js";
+import { type AgentAttachments } from "../attachments.js";
 import { type Environment } from "../environment.js";
+import { type RuntimeTokenVerifier } from "../runtime-identity.js";
 import { type RuntimeToken } from "../runtime-token.js";
 import { type ObservedMessages } from "./observed.js";
 import { type DecideFunction } from "./router.js";
@@ -27,8 +29,12 @@ export interface TelegramAdapterOptions {
     readonly fetch?: typeof fetch;
     readonly transcribe?: Transcriber;
     readonly observed?: ObservedMessages;
+    /** Verifies callers of the messages route; tests pass one on a local key set. */
+    readonly verify?: RuntimeTokenVerifier;
     /** Reads the tail of a session's durable stream; tests pass a fake. */
     readonly history?: HistoryReader;
+    /** The attachment store; tests pass a fake. */
+    readonly attachments?: AgentAttachments;
 }
 /** The Telegram channel of the extension. */
 export declare function segmentstreamTelegram(options: TelegramAdapterOptions): TelegramChannel;

package/dist/extension/lib/telegram/adapter.mjs

@@ -4,11 +4,14 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
-import { appOrigin, channelsEnabled, proxyEnvironment, webhookSecret } from "../environment.mjs";
-import { MAXIMUM_PROXY_BODY_BYTES, connectionProxy } from "../connection-proxy.mjs";
-import { agentIdentities } from "../identities.mjs";
+import { appOrigin, channelsEnabled, proxyEnvironment, runtimeIdentityEnvironment, webhookSecret } from "../environment.mjs";
+import { MAXIMUM_DOWNLOAD_BYTES, connectionProxy } from "../connection-proxy.mjs";
 import { runtimeToken } from "../runtime-token.mjs";
+import { agentAttachments, parseAttachmentUrl } from "../attachments.mjs";
+import { agentIdentities } from "../identities.mjs";
+import { runtimeTokenVerifier } from "../runtime-identity.mjs";
 import { botIdentityCache } from "./bot.mjs";
+import { agentChats } from "./chats.mjs";
 import { observedMessages } from "./observed.mjs";
 import { decisionRouter } from "./router.mjs";
 import { scopedAddress, sessionPolicy } from "./sessions.mjs";
@@ -16,6 +19,7 @@ import { downloadTelegramFile, gatewayTranscriber } from "./voice.mjs";
 import { handleInboundMessage } from "./inbound.mjs";
 import { InboundRequest, currentInboundRequest, runInboundRequest, withReplacedText } from "./inbound-request.mjs";
 import { TELEGRAM_PLACEHOLDER_TOKEN, TELEGRAM_PROXY_ORIGIN, telegramProxyFetch } from "./proxy-fetch.mjs";
+import { messagesRoute } from "./requests.mjs";
 import { deliverUnlessSilent } from "./silent.mjs";
 import { telegramWebhookVerifier } from "./webhook.mjs";
 import { telegramChannel } from "eve/channels/telegram";
@@ -42,6 +46,7 @@ function segmentstreamTelegram(options) {
 	const bot = botIdentityCache();
 	const proxies = new Map();
 	let identities;
+	let verify = options.verify;
 	function settings() {
 		const configured = options.settings();
 		if (configured === null) throw new Error("The Telegram channel is not configured in agent/segmentstream.json.");
@@ -69,6 +74,16 @@ function segmentstreamTelegram(options) {
 		});
 		return identities;
 	}
+	const chats = agentChats({ identities: pairing });
+	let store = options.attachments;
+	function attachments() {
+		store ??= agentAttachments({
+			origin: appOrigin(environment),
+			token,
+			...options.fetch === void 0 ? {} : { fetch: options.fetch }
+		});
+		return store;
+	}
 	const channel = telegramChannel({
 		api: {
 			apiBaseUrl: TELEGRAM_PROXY_ORIGIN,
@@ -79,7 +94,7 @@ function segmentstreamTelegram(options) {
 			botToken: TELEGRAM_PLACEHOLDER_TOKEN,
 			webhookVerifier: telegramWebhookVerifier(() => webhookSecret(environment))
 		},
-		uploadPolicy: { maxBytes: MAXIMUM_PROXY_BODY_BYTES },
+		uploadPolicy: { maxBytes: MAXIMUM_DOWNLOAD_BYTES },
 		onMessage: (context, message) => handleInboundMessage({
 			context,
 			message,
@@ -100,21 +115,55 @@ function segmentstreamTelegram(options) {
 					proxy: proxy(),
 					fileId
 				}),
+				attachments: attachments(),
 				observed,
+				chats,
 				connectUrl: (code) => `${appOrigin(environment)}/agent/connect?code=${encodeURIComponent(code)}`
 			}
 		}),
 		events: { "message.completed": deliverUnlessSilent }
 	});
+	const adapter = channel.adapter;
+	const fetchTelegramFile = adapter?.fetchFile;
+	async function fetchFile(url, context) {
+		const reference = parseAttachmentUrl(url);
+		if (reference === void 0) return fetchTelegramFile === void 0 ? null : fetchTelegramFile(url, context);
+		const sessionId = sessionIdOf(context);
+		const { attachment, bytes } = await attachments().read({
+			memberId: reference.memberId,
+			conversation: reference.conversation,
+			...sessionId === void 0 ? {} : { sessionId }
+		}, reference.id);
+		return {
+			bytes: Buffer.from(bytes),
+			mediaType: attachment.contentType,
+			filename: attachment.filename
+		};
+	}
 	return {
 		...channel,
-		routes: channel.routes.map((route) => gatedRoute({
+		...adapter === void 0 ? {} : { adapter: {
+			...adapter,
+			fetchFile
+		} },
+		routes: [...channel.routes.map((route) => gatedRoute({
 			route,
 			options,
 			environment
-		}))
+		})), messagesRoute({
+			channel,
+			enabled: () => channelsEnabled(environment),
+			configured: () => options.settings() !== null,
+			verify: () => verify ??= runtimeTokenVerifier(runtimeIdentityEnvironment(environment)),
+			sessionPolicy: policy,
+			scope: () => options.sessions().scope
+		})]
 	};
 }
+function sessionIdOf(context) {
+	const session = typeof context === "object" && context !== null ? context.session : void 0;
+	return typeof session?.id === "string" && session.id !== "" ? session.id : void 0;
+}
 function gatedRoute(input) {
 	const { route, options, environment } = input;
 	if (route.transport === "websocket") return route;
@@ -129,6 +178,7 @@ function gatedRoute(input) {
 				resolveSession: args.resolveSession,
 				from: args.from
 			};
+			inbound.waitUntil = args.waitUntil;
 			return runInboundRequest(inbound, () => route.handler(request, {
 				...args,
 				from: (address) => withReplacedText(args.from(scoped(address)), inbound)

package/dist/extension/lib/telegram/chats.d.ts

@@ -0,0 +1,46 @@
+import type { AgentChat, AgentIdentities } from "../identities.js";
+/** How long a chat's report stands before the next message reports it again. */
+export declare const REPORT_INTERVAL_MS: number;
+export interface ChatReport {
+    readonly chatId: string;
+    readonly title: string;
+    readonly memberId?: string;
+}
+export interface AgentChats {
+    /** Reports the chat when due. Resolves when done; never rejects. */
+    seen(report: ChatReport): Promise<void>;
+    /**
+     * Reports that the paired member left the chat, so the registry unlinks them, and forgets them
+     * here, so that a later message from them links them again. Resolves when done; never rejects.
+     */
+    left(report: ChatReport & {
+        readonly memberId: string;
+    }): Promise<void>;
+    /**
+     * Reports that the agent itself left the chat, so the registry unlinks every member, and forgets
+     * the members reported here, so that each links again when they write after the agent is back.
+     * Resolves when done; never rejects.
+     */
+    agentLeft(report: {
+        readonly chatId: string;
+        readonly title: string;
+    }): Promise<void>;
+    /**
+     * Reports that the group `migratedFrom` became the supergroup `chatId`, so the registry moves its
+     * record, and forgets the old chat here. Resolves when done; never rejects.
+     */
+    migrated(report: {
+        readonly chatId: string;
+        readonly title: string;
+        readonly migratedFrom: string;
+    }): Promise<void>;
+    /** The registry's latest answer for the chat, if this process has one. */
+    chat(chatId: string): AgentChat | undefined;
+}
+export declare function agentChats(input: {
+    readonly identities: () => AgentIdentities;
+    readonly now?: () => number;
+    readonly log?: (message: string, error: unknown) => void;
+}): AgentChats;
+/** The registry's facts as turn context: only the fields it holds. */
+export declare function chatContext(chat: AgentChat | undefined): ReadonlyArray<string>;