@segmentstream/agent 0.1.4 → 0.1.5

package/README.md

@@ -97,6 +97,7 @@ platform's deployment manifest.
 | ------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------- |
 | `segmentstream__ontology` | `connections`  | The app's `/mcp`, resolved per turn for the turn's member. No member, no connection.                            |
 | `segmentstream__telegram` | `channels`     | `POST /eve/v1/telegram`: Telegram through the connection, with pairing, routing and voice.                      |
+|                           |                | `POST /eve/v1/telegram/messages`: requests from the ontology's `agent_chat.send_message`.                       |
 | platform rules            | `instructions` | Changes go through actions; `describe` gives the catalog; tools are already narrowed; when to answer `[SILENT]` |
 
 ### The ontology
@@ -139,12 +140,39 @@ share a group chat's session never share a client.
   such as `[voice message, 12 s]` in context. A file over the proxy's 2 MiB limit, or a failed
   transcription, reaches the agent as a note saying so. Photos and documents up to 2 MiB reach the
   agent as eve's file parts.
+- **Chat registry.** Every group message reports its chat to the ontology's `agent_chat` registry
+  (`POST /api/ontology/agent/chats/seen`) with its title and, when the sender is paired, the
+  member's id: at most once per chat every ten minutes per process, and at once for a member not
+  yet reported there. The report runs in the background; a failure is logged and changes nothing,
+  so the next message reports again.
+  An answered group turn waits for its report, bounded by the call's ten-second timeout, and
+  carries the registry's `title`, `purpose` and `whenToUse` as a `<chat>` block. When a paired
+  member leaves the group, or is removed, the agent reports it with `leftMemberId`, so the
+  registry unlinks them; it starts no turn. A later message from them links them again. When the
+  agent itself leaves or is removed, it reports `agentLeft: true`, so the registry unlinks every
+  member and keeps the chat; members link again when they write after the agent is back. When a
+  group becomes a supergroup, either notice (`migrate_to_chat_id` in the old chat,
+  `migrate_from_chat_id` in the new one) reports the new id with `migratedFrom: <old id>`, starts
+  no turn and drops the old chat from the memo. The `<chat>` block carries at most 1000
+  characters of `whenToUse`.
+- **Requests.** `POST /eve/v1/telegram/messages` takes a request from the ontology's
+  `agent_chat.send_message`: a group or private chat, the request, the person to contact and the
+  requester, with their roles (empty when an older ontology sends none) and `actAs` (whether the
+  turn can act as them; without it, true for a member). The bearer must be a Vercel OIDC token of a production function of the same project,
+  verified with the team's issuer and audience. The request reaches the chat's session through
+  eve's proactive `receive` at `chatId::`, the address the chat's own messages continue, after the
+  session policy (idle reset, daily compaction) runs on it, with an `<agent_request>` block naming the requester and the person. A member's request with `actAs` runs as that
+  member, with their roles, which choose the model of a session the request starts; a service's,
+  or an unpaired member's (`actAs: false`), runs without a member and has no ontology, its roles
+  still choosing the model. It answers 202 with the session id, 503 outside
+  production, 404 without `channels.telegram`, 401 for a missing or invalid token and 400 for a
+  body that does not match, including a request over 4000 characters.
 - **Silence.** When the model answers a routed message with exactly `[SILENT]` (or `NO_REPLY`), in
   any case, nothing is sent to the chat. The turn stays in the session.
 
-The observed ring lives in process memory, per chat and forum topic, because eve's durable
+The observed ring and the chat reports live in process memory, per chat and forum topic, because eve's durable
 `defineState` is session state and an observed message has no session. A new function instance
-starts with an empty ring.
+starts with an empty ring and reports its chats afresh.
 
 ## Local development
 
@@ -163,17 +191,20 @@ manifest.
 The platform sets every variable on the workspace's Vercel project. None of them is a model key or
 a provider token.
 
-| Variable                             | Used for                                                                        |
-| ------------------------------------ | ------------------------------------------------------------------------------- |
-| `VERCEL_PROJECT_PRODUCTION_URL`      | The app's origin: `/mcp`, `/api/ontology/agent/*` and the `/agent/connect` link |
-| `SEGMENTSTREAM_AGENT_ONTOLOGY_URL`   | Overrides that origin in local development                                      |
-| `SEGMENTSTREAM_URL`                  | backend-next, where the connection proxy answers                                |
-| `SEGMENTSTREAM_WORKSPACE_ID`         | The workspace in the proxy's path                                               |
-| `SEGMENTSTREAM_ORGANIZATION_ID`      | The tenant the proxy selects                                                    |
-| `SEGMENTSTREAM_AGENT_WEBHOOK_SECRET` | The Telegram webhook secret; the only secret                                    |
-| `VERCEL_ENV`                         | Channels run only in `production`; `preview` selects the preview model          |
-| `VERCEL_OIDC_TOKEN`                  | The runtime token outside a request; Vercel sends it on each request otherwise  |
-| `AI_GATEWAY_API_KEY`                 | Optional. AI Gateway uses the OIDC token when it is unset                       |
+| Variable                              | Used for                                                                        |
+| ------------------------------------- | ------------------------------------------------------------------------------- |
+| `VERCEL_PROJECT_PRODUCTION_URL`       | The app's origin: `/mcp`, `/api/ontology/agent/*` and the `/agent/connect` link |
+| `SEGMENTSTREAM_AGENT_ONTOLOGY_URL`    | Overrides that origin in local development                                      |
+| `SEGMENTSTREAM_URL`                   | backend-next, where the connection proxy answers                                |
+| `SEGMENTSTREAM_WORKSPACE_ID`          | The workspace in the proxy's path                                               |
+| `SEGMENTSTREAM_ORGANIZATION_ID`       | The tenant the proxy selects                                                    |
+| `SEGMENTSTREAM_AGENT_WEBHOOK_SECRET`  | The Telegram webhook secret; the only secret                                    |
+| `SEGMENTSTREAM_RUNTIME_OIDC_ISSUER`   | The team's OIDC issuer, which signs the tokens the messages route accepts       |
+| `SEGMENTSTREAM_RUNTIME_OIDC_AUDIENCE` | The audience those tokens must name                                             |
+| `VERCEL_PROJECT_ID`                   | The project those tokens must name                                              |
+| `VERCEL_ENV`                          | Channels run only in `production`; `preview` selects the preview model          |
+| `VERCEL_OIDC_TOKEN`                   | The runtime token outside a request; Vercel sends it on each request otherwise  |
+| `AI_GATEWAY_API_KEY`                  | Optional. AI Gateway uses the OIDC token when it is unset                       |
 
 ## License
 

package/dist/extension/instructions.md

@@ -11,3 +11,8 @@ talking to you, and you act with exactly their permissions.
 - Never invent records or values. Say when the ontology does not hold what was asked.
 - When you have been routed a message but a reply would add nothing, answer with exactly
   `[SILENT]` and nothing else. Use it only in that case; it suppresses delivery to the chat.
+- To ask someone something in a group or a private chat, run the ontology action
+  `agent_chat.send_message`; their replies come back into that chat's session, where you handle
+  them. The groups you are in are listed in `agent_chat`, with the `purpose` and `whenToUse` members
+  set; when a member who may change it tells you what a group is for, record it with
+  `agent_chat.update`.

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,7 @@
 import { type TelegramChannel } from "eve/channels/telegram";
 import type { SessionSettings, TelegramSettings } from "../../config.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,6 +28,8 @@ 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;
 }

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

@@ -4,11 +4,13 @@ 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 { appOrigin, channelsEnabled, proxyEnvironment, runtimeIdentityEnvironment, webhookSecret } from "../environment.mjs";
 import { MAXIMUM_PROXY_BODY_BYTES, connectionProxy } from "../connection-proxy.mjs";
 import { agentIdentities } from "../identities.mjs";
+import { runtimeTokenVerifier } from "../runtime-identity.mjs";
 import { runtimeToken } from "../runtime-token.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 +18,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 +45,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 +73,7 @@ function segmentstreamTelegram(options) {
 		});
 		return identities;
 	}
+	const chats = agentChats({ identities: pairing });
 	const channel = telegramChannel({
 		api: {
 			apiBaseUrl: TELEGRAM_PROXY_ORIGIN,
@@ -101,6 +106,7 @@ function segmentstreamTelegram(options) {
 					fileId
 				}),
 				observed,
+				chats,
 				connectUrl: (code) => `${appOrigin(environment)}/agent/connect?code=${encodeURIComponent(code)}`
 			}
 		}),
@@ -108,11 +114,18 @@ function segmentstreamTelegram(options) {
 	});
 	return {
 		...channel,
-		routes: channel.routes.map((route) => gatedRoute({
+		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 gatedRoute(input) {
@@ -129,6 +142,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>;

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

@@ -0,0 +1,123 @@
+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);
+const MAXIMUM_WHEN_TO_USE_LENGTH = 1e3;
+const REPORT_INTERVAL_MS = 6e5;
+const MAXIMUM_CHATS = 500;
+function agentChats(input) {
+	const chats = new Map();
+	const now = input.now ?? Date.now;
+	const log = input.log ?? ((message, error) => console.warn(message, error));
+	function remember(chatId, value) {
+		chats.delete(chatId);
+		chats.set(chatId, value);
+		if (chats.size > MAXIMUM_CHATS) {
+			const oldest = chats.keys().next();
+			if (oldest.done !== true) chats.delete(oldest.value);
+		}
+	}
+	function restore(chatId, written, previous) {
+		if (chats.get(chatId) !== written) return;
+		if (previous === void 0) chats.delete(chatId);
+		else chats.set(chatId, previous);
+	}
+	async function report(chatId, fallback, body) {
+		try {
+			const chat = await input.identities().seenChat({
+				provider: "telegram",
+				externalId: chatId,
+				...body
+			});
+			remember(chatId, {
+				...chats.get(chatId) ?? fallback,
+				chat
+			});
+			return true;
+		} catch (error) {
+			log("The agent could not report the chat to the ontology's registry.", error);
+			return false;
+		}
+	}
+	return {
+		async seen({ chatId, title, memberId }) {
+			const known = chats.get(chatId);
+			const at = now();
+			if (!(known === void 0 || at - known.reportedAt >= 6e5 || memberId !== void 0 && !known.members.has(memberId))) return;
+			const members = new Set(known?.members);
+			if (memberId !== void 0) members.add(memberId);
+			const written = {
+				reportedAt: at,
+				members,
+				chat: known?.chat
+			};
+			remember(chatId, written);
+			if (!await report(chatId, {
+				reportedAt: at,
+				members,
+				chat: void 0
+			}, {
+				title,
+				...memberId === void 0 ? {} : { memberId }
+			})) restore(chatId, written, known);
+		},
+		async left({ chatId, title, memberId }) {
+			const known = chats.get(chatId);
+			const remembered = {
+				reportedAt: known?.reportedAt ?? now(),
+				members: new Set([...known?.members ?? []].filter((member) => member !== memberId)),
+				chat: known?.chat
+			};
+			remember(chatId, remembered);
+			if (!await report(chatId, remembered, {
+				title,
+				leftMemberId: memberId
+			})) restore(chatId, remembered, known);
+		},
+		async agentLeft({ chatId, title }) {
+			const known = chats.get(chatId);
+			const remembered = {
+				reportedAt: known?.reportedAt ?? now(),
+				members: new Set(),
+				chat: known?.chat
+			};
+			remember(chatId, remembered);
+			if (!await report(chatId, remembered, {
+				title,
+				agentLeft: true
+			})) restore(chatId, remembered, known);
+		},
+		async migrated({ chatId, title, migratedFrom }) {
+			const old = chats.get(migratedFrom);
+			const known = chats.get(chatId);
+			const remembered = {
+				reportedAt: now(),
+				members: new Set([...old?.members ?? [], ...known?.members ?? []]),
+				chat: known?.chat
+			};
+			chats.delete(migratedFrom);
+			remember(chatId, remembered);
+			if (!await report(chatId, remembered, {
+				title,
+				migratedFrom
+			})) {
+				restore(chatId, remembered, known);
+				if (old !== void 0 && !chats.has(migratedFrom)) remember(migratedFrom, old);
+			}
+		},
+		chat(chatId) {
+			return chats.get(chatId)?.chat;
+		}
+	};
+}
+function chatContext(chat) {
+	if (chat === void 0) return [];
+	const lines = ["<chat>", `title: ${chat.title}`];
+	if (chat.purpose !== null && chat.purpose !== "") lines.push(`purpose: ${chat.purpose}`);
+	if (chat.whenToUse !== null && chat.whenToUse !== "") lines.push(`when_to_use: ${chat.whenToUse.slice(0, MAXIMUM_WHEN_TO_USE_LENGTH)}`);
+	lines.push("</chat>");
+	return [lines.join("\n")];
+}
+export { REPORT_INTERVAL_MS, agentChats, chatContext };

package/dist/extension/lib/telegram/inbound-request.d.ts

@@ -14,6 +14,8 @@ export declare class InboundRequest {
     text: string | undefined;
     /** The route's session operations, on addresses already mapped to the configured scope. */
     sessions: SessionOperations | undefined;
+    /** Keeps work the request started, such as a chat report, alive after it answers. */
+    waitUntil: ((task: Promise<unknown>) => void) | undefined;
     constructor(
     /** The agent's description from the compiled manifest, for the routing decision. */
     agentDescription: () => Promise<string>);

package/dist/extension/lib/telegram/inbound-request.mjs

@@ -9,6 +9,7 @@ var InboundRequest = class {
 	agentDescription;
 	text;
 	sessions;
+	waitUntil;
 	constructor(agentDescription) {
 		this.agentDescription = agentDescription;
 	}

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

@@ -2,6 +2,7 @@ import type { TelegramContext, TelegramInboundResult, TelegramMessage } from "ev
 import type { SessionSettings, TelegramPolicy } from "../../config.js";
 import type { AgentIdentities } from "../identities.js";
 import type { BotIdentityLookup } from "./bot.js";
+import { type AgentChats } from "./chats.js";
 import type { InboundRequest } from "./inbound-request.js";
 import { type ObservedMessages } from "./observed.js";
 import { type RouteDecider } from "./router.js";
@@ -11,13 +12,19 @@ import { type Transcriber } from "./voice.js";
  * eve's Telegram `onMessage` hook, in the order `agent-design.md` gives:
  *
  * 1. The hard gate, with no model: bots, channel posts and senders without a live pairing never
- *    start a turn. An unknown sender who writes to the bot privately gets a pairing button.
+ *    start a turn. An unknown sender who writes to the bot privately gets a pairing button. A group
+ *    message reports its chat to the ontology's registry in the background, whatever follows. A
+ *    group's notice that a member left is never a turn: a paired member's departure is reported,
+ *    and so is the agent's own, which unlinks every member. Neither is the notice, in the old chat
+ *    or the new one, that a group became a supergroup: the migration is reported.
  * 2. Voice becomes text, so the router and the agent read what was said.
  * 3. The router answers or observes. An observed message goes to the chat's ring and stops here.
  * 4. The session policy runs on the session the message continues: an idle one is cleared, the
  *    first message after the day's compaction time compacts it.
- * 5. An answered message dispatches as the paired member, with the ring and a `<speaker>` block
- *    naming the member, their roles and the message they replied to ahead of it as context.
+ * 5. An answered message dispatches as the paired member, with the ring, the registry's `<chat>`
+ *    block and a `<speaker>` block naming the member, their roles and the message they replied to
+ *    ahead of it as context. An answered group message waits for its chat's report first, so that
+ *    a chat new to the process already carries its `<chat>` block.
  */
 export interface InboundDependencies {
     readonly policy: TelegramPolicy;
@@ -30,6 +37,7 @@ export interface InboundDependencies {
     readonly transcribe: Transcriber;
     readonly download: (fileId: string) => Promise<Uint8Array>;
     readonly observed: ObservedMessages;
+    readonly chats: AgentChats;
     /** The app's `/agent/connect` link for a pairing code. */
     readonly connectUrl: (code: string) => string;
 }

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

@@ -5,6 +5,7 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { telegramPrincipal } from "./principal.mjs";
+import { chatContext } from "./chats.mjs";
 import { observedChatKey, observedContext } from "./observed.mjs";
 import { isAddressed, routeMessage } from "./router.mjs";
 import { messageAddress, scopedAddress } from "./sessions.mjs";
@@ -90,9 +91,67 @@ async function answerUnpaired(input) {
 		reply_markup: buttonTo("Connect account", dependencies.connectUrl(pairing.code))
 	});
 }
+function isGroupChat(message) {
+	return message.chat.type === "group" || message.chat.type === "supergroup";
+}
+async function reportDeparture(input) {
+	const { context, message, left, dependencies } = input;
+	const id = left.id;
+	if (typeof id !== "number" && typeof id !== "string") return;
+	if (left.is_bot === true) {
+		const bot = await dependencies.bot(context.telegram);
+		if (bot !== void 0 && String(id) === bot.id) await dependencies.chats.agentLeft({
+			chatId: message.chat.id,
+			title: message.chat.title ?? ""
+		});
+		return;
+	}
+	const lookup = await dependencies.identities.lookup({
+		provider: "telegram",
+		externalId: String(id)
+	});
+	if (lookup.status === "paired") await dependencies.chats.left({
+		chatId: message.chat.id,
+		title: message.chat.title ?? "",
+		memberId: lookup.member.id
+	});
+}
+function rawChatId(value) {
+	return typeof value === "number" || typeof value === "string" && value !== "" ? String(value) : void 0;
+}
+function migrationOf(message) {
+	const to = rawChatId(message.raw.migrate_to_chat_id);
+	const from = rawChatId(message.raw.migrate_from_chat_id);
+	if (to !== void 0) return {
+		chatId: to,
+		migratedFrom: message.chat.id
+	};
+	return from === void 0 ? void 0 : {
+		chatId: message.chat.id,
+		migratedFrom: from
+	};
+}
 async function handleInboundMessage(input) {
 	const { context, dependencies } = input;
 	const message = input.message;
+	const left = message.raw.left_chat_member;
+	const migration = isGroupChat(message) ? migrationOf(message) : void 0;
+	if (isGroupChat(message) && isRecord(left)) {
+		await reportDeparture({
+			context,
+			message,
+			left,
+			dependencies
+		});
+		return null;
+	}
+	if (migration !== void 0) {
+		await dependencies.chats.migrated({
+			...migration,
+			title: message.chat.title ?? ""
+		});
+		return null;
+	}
 	if (message.from === void 0 || message.from.isBot || message.chat.type === "channel") return null;
 	const sent = {
 		...message,
@@ -104,6 +163,13 @@ async function handleInboundMessage(input) {
 		provider: "telegram",
 		externalId: sent.from.id
 	});
+	const group = isGroupChat(sent);
+	const report = group ? dependencies.chats.seen({
+		chatId: sent.chat.id,
+		title: sent.chat.title ?? "",
+		...lookup.status === "paired" ? { memberId: lookup.member.id } : {}
+	}) : void 0;
+	if (report !== void 0) input.request?.waitUntil?.(report);
 	if (lookup.status !== "paired") {
 		if (addressed) await answerUnpaired({
 			context,
@@ -160,6 +226,7 @@ async function handleInboundMessage(input) {
 		dependencies.sessionPolicy.delivered(address);
 	}
 	await context.telegram.startTyping();
+	await report;
 	return {
 		auth: telegramPrincipal({
 			message: sent,
@@ -167,6 +234,7 @@ async function handleInboundMessage(input) {
 		}),
 		context: [
 			...observedContext(dependencies.observed.take(chat)),
+			...group ? chatContext(dependencies.chats.chat(sent.chat.id)) : [],
 			speakerBlock({
 				message: sent,
 				member: lookup.member,

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

@@ -0,0 +1,71 @@
+import { type RouteDefinition } from "eve/channels";
+import type { TelegramChannel, TelegramChannelState } from "eve/channels/telegram";
+import type { SessionAuthContext } from "eve/context";
+import type { SessionSettings } from "../../config.js";
+import type { RuntimeTokenVerifier } from "../runtime-identity.js";
+import { type SessionPolicy } from "./sessions.js";
+/**
+ * Requests from the ontology's `agent_chat.send_message` action: an external agent or a member asks
+ * the workspace agent to contact someone in a group or a private chat. The ontology service resolves
+ * the chat and posts here with its own Vercel OIDC token; the request is delivered into the chat's
+ * session through eve's proactive `receive`, without a seed message, so it continues the session
+ * the chat's own messages reach (`chatId::`, the chat-scope address) and the replies land there too.
+ * The session policy runs on that session first, as it does for an inbound message.
+ */
+export declare const MESSAGES_ROUTE = "/eve/v1/telegram/messages";
+export interface AgentRequest {
+    readonly target: {
+        readonly kind: "group" | "private";
+        readonly provider: "telegram";
+        /** The group's chat id, or the Telegram user id of a private chat. */
+        readonly chatId: string;
+    };
+    readonly message: string;
+    /** Whom to contact, when the requester named someone. */
+    readonly person: {
+        readonly id: string;
+        readonly name: string;
+    } | null;
+    readonly requester: {
+        readonly id: string;
+        readonly name: string;
+        readonly kind: "member" | "service";
+        /** The roles the requester holds; empty from an ontology that does not send them. */
+        readonly roles: ReadonlyArray<string>;
+        /**
+         * Whether the turn can act as the requester: a member with a live paired identity. An ontology
+         * that does not send it means a member can.
+         */
+        readonly actAs: boolean;
+    };
+}
+/** The request body, or `undefined` when it does not match the contract. */
+export declare function agentRequest(value: unknown): AgentRequest | undefined;
+/**
+ * Whom the request's turn runs as. A member requester the ontology says can be acted as is the
+ * turn's member, so the ontology connection acts as them and the ontology service checks, as for any
+ * turn, that they are active and paired. Their roles, as the action's principal held them, choose the
+ * model of a session the request starts; the service resolves them afresh on every call. A service
+ * user, or a member who has not paired, cannot be acted as, so the request runs without a member and
+ * the turn has no ontology; their roles still choose the model, and grant nothing, since the
+ * ontology connection acts only for a `memberId`.
+ */
+export declare function requestPrincipal(request: AgentRequest): SessionAuthContext;
+/** What the turn is about, for the model, ahead of the request itself. */
+export declare function requestContext(request: AgentRequest): string;
+/**
+ * `POST /eve/v1/telegram/messages`. Gated like the webhook: outside production it answers 503 and a
+ * workspace without a Telegram channel 404. The caller must be a function of this deployment's
+ * project, verified from its Vercel OIDC token.
+ */
+export declare function messagesRoute(input: {
+    readonly channel: TelegramChannel;
+    readonly enabled: () => boolean;
+    readonly configured: () => boolean;
+    readonly verify: () => RuntimeTokenVerifier;
+    /** The adapter's session policy, which the webhook route applies too. */
+    readonly sessionPolicy: SessionPolicy;
+    /** The mounted `sessions.scope`. */
+    readonly scope: () => SessionSettings["scope"];
+    readonly log?: (message: string, detail: unknown) => void;
+}): RouteDefinition<TelegramChannelState>;

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

@@ -0,0 +1,173 @@
+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 { TELEGRAM_AUTHENTICATOR } from "./principal.mjs";
+import { formatAddress, scopedAddress } from "./sessions.mjs";
+import { POST } from "eve/channels";
+const MESSAGES_ROUTE = "/eve/v1/telegram/messages";
+const MAX_REQUEST_MESSAGE_LENGTH = 4e3;
+const CHAT_ID = /^-?\d{1,20}$/;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isText(value) {
+	return typeof value === "string" && value.trim() !== "";
+}
+function user(value) {
+	return isRecord(value) && isText(value.id) && isText(value.name) ? {
+		id: value.id,
+		name: value.name
+	} : void 0;
+}
+function roles(value) {
+	if (value === void 0) return [];
+	return Array.isArray(value) && value.every((role) => typeof role === "string") ? value : void 0;
+}
+function agentRequest(value) {
+	if (!isRecord(value)) return;
+	const { target, message, requester } = value;
+	const person = value.person === null ? null : user(value.person);
+	const from = user(requester);
+	const held = isRecord(requester) ? roles(requester.roles) : void 0;
+	const actAs = isRecord(requester) ? requester.actAs : void 0;
+	if (!isRecord(target) || target.kind !== "group" && target.kind !== "private" || target.provider !== "telegram" || typeof target.chatId !== "string" || !CHAT_ID.test(target.chatId) || !isText(message) || message.length > MAX_REQUEST_MESSAGE_LENGTH || person === void 0 || from === void 0 || !isRecord(requester) || requester.kind !== "member" && requester.kind !== "service" || held === void 0 || actAs !== void 0 && typeof actAs !== "boolean") return;
+	return {
+		target: {
+			kind: target.kind,
+			provider: "telegram",
+			chatId: target.chatId
+		},
+		message,
+		person,
+		requester: {
+			...from,
+			kind: requester.kind,
+			roles: held,
+			actAs: actAs ?? requester.kind === "member"
+		}
+	};
+}
+function requestPrincipal(request) {
+	const { requester, target } = request;
+	if (requester.kind === "member" && requester.actAs) return {
+		authenticator: TELEGRAM_AUTHENTICATOR,
+		issuer: "segmentstream",
+		principalId: `segmentstream:${requester.id}`,
+		principalType: "user",
+		subject: requester.id,
+		attributes: {
+			memberId: requester.id,
+			memberName: requester.name,
+			roles: requester.roles,
+			chatId: target.chatId,
+			chatType: target.kind
+		}
+	};
+	return {
+		authenticator: TELEGRAM_AUTHENTICATOR,
+		issuer: "segmentstream",
+		principalId: `segmentstream:${requester.kind}:${requester.id}`,
+		principalType: requester.kind === "member" ? "user" : "service",
+		subject: requester.id,
+		attributes: {
+			requesterId: requester.id,
+			requesterName: requester.name,
+			roles: requester.roles,
+			chatId: target.chatId,
+			chatType: target.kind
+		}
+	};
+}
+function requestContext(request) {
+	const { requester, person } = request;
+	const to = person === null ? "" : ` to ${person.name} (user_id ${person.id})`;
+	const lines = [
+		"<agent_request>",
+		`A request from ${requester.name} (${requester.kind}, user_id ${requester.id}) arrived through the ontology action agent_chat.send_message; the message is the request.`,
+		`Write in this chat${to}, ask what the request needs, and handle the replies here.`
+	];
+	if (requester.kind === "service" || !requester.actAs) lines.push(`${requester.kind === "service" ? "The requester is a service, not a member" : "The requester has not paired a Telegram account with the agent"}, so this turn runs without a member and the ontology is not available in it. Each member who replies acts with their own permissions.`);
+	lines.push("</agent_request>");
+	return lines.join("\n");
+}
+function withContext(source, context) {
+	return {
+		...source,
+		send(message, options) {
+			return source.send(message, {
+				...options,
+				context: [...options.context ?? [], context]
+			});
+		}
+	};
+}
+function bearer(header) {
+	return (header === null ? null : /^Bearer\s+(\S+)$/i.exec(header.trim()))?.[1];
+}
+function error(code, status) {
+	return Response.json({ error: code }, { status });
+}
+function messagesRoute(input) {
+	const log = input.log ?? ((message, detail) => console.warn(message, detail));
+	return POST(MESSAGES_ROUTE, async (request, args) => {
+		if (!input.enabled()) return error("channels_disabled", 503);
+		if (!input.configured()) return error("not_found", 404);
+		const token = bearer(request.headers.get("authorization"));
+		if (token === void 0) return error("unauthorized", 401);
+		let verifier;
+		try {
+			verifier = input.verify();
+		} catch (cause) {
+			log("The agent cannot verify requests: the runtime identity is not configured.", cause);
+			return error("unavailable", 503);
+		}
+		const verification = await verifier(token);
+		if (verification.status === "unavailable") {
+			log("The agent cannot verify requests: the runtime key set is unavailable.", verification.reason);
+			return error("unavailable", 503);
+		}
+		if (verification.status !== "valid") {
+			log("The agent refused a request with an invalid runtime token.", verification.reason);
+			return error("unauthorized", 401);
+		}
+		let body;
+		try {
+			body = await request.json();
+		} catch {
+			return error("invalid_body", 400);
+		}
+		const parsed = agentRequest(body);
+		const receive = input.channel.receive;
+		if (parsed === void 0) return error("invalid_body", 400);
+		if (receive === void 0) throw new Error("eve's Telegram channel has no receive hook.");
+		const chatAddress = scopedAddress(formatAddress({
+			chatId: parsed.target.chatId,
+			messageThreadId: "",
+			conversationId: ""
+		}), input.scope());
+		await input.sessionPolicy.apply({
+			address: chatAddress,
+			operations: {
+				resolveSession: args.resolveSession,
+				from: args.from
+			}
+		});
+		const session = await receive({
+			target: { chatId: parsed.target.chatId },
+			message: parsed.message,
+			auth: requestPrincipal(parsed)
+		}, {
+			from: (address) => withContext(args.from(address), requestContext(parsed)),
+			resolveSession: args.resolveSession
+		});
+		input.sessionPolicy.delivered(chatAddress);
+		return Response.json({
+			delivered: true,
+			sessionId: session.id
+		}, { status: 202 });
+	});
+}
+export { MESSAGES_ROUTE, agentRequest, messagesRoute, requestContext, requestPrincipal };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream/agent",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Mount a SegmentStream workspace's agent on eve: the ontology as tools, acting as the member who writes, and Telegram through the workspace's connection.",
   "license": "Apache-2.0",
   "author": "SegmentStream",
@@ -61,7 +61,8 @@
   },
   "dependencies": {
     "@vercel/oidc": "^3.8.4",
-    "ai": "^7.0.128"
+    "ai": "^7.0.128",
+    "jose": "^6.2.12"
   },
   "peerDependencies": {
     "eve": "0.76.3"