@segmentstream/agent 0.1.3 → 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/channels/telegram.mjs

@@ -10,6 +10,7 @@ import { decide } from "eve/ai";
 var telegram_default = segmentstreamTelegram({
 	settings: () => segmentstream.config.channels.telegram,
 	models: () => segmentstream.config.models,
+	sessions: () => segmentstream.config.sessions,
 	decide: (options) => decide(options)
 });
 export { telegram_default as default };

package/dist/extension/config.d.ts

@@ -49,6 +49,22 @@ export interface SegmentStreamAgentConfigInput {
         /** Whether the agent reaches the ontology over MCP. On by default. */
         readonly connection?: boolean;
     };
+    readonly sessions?: {
+        /**
+         * What a group session spans: `chat` (default) keeps one session per group chat and forum
+         * topic, `thread` keeps eve's one session per reply thread.
+         */
+        readonly scope?: string;
+        /**
+         * The local time, `HH:MM`, after which the first message of a chat compacts its session's
+         * history before the turn runs; `false` leaves compaction to eve's context-window check.
+         */
+        readonly compactAt?: string | boolean;
+        /** The IANA time zone `compactAt` is read in, such as `Europe/London`. */
+        readonly timezone?: string;
+        /** Hours of silence after which a chat's next message starts with an empty history. */
+        readonly idleResetHours?: number | boolean;
+    };
 }
 export interface TelegramSettings {
     readonly connection: string;
@@ -66,6 +82,17 @@ export interface ChatModelChoice {
     /** The model of preview deployments, so a preview never spends on a large model. */
     readonly preview?: string;
 }
+export declare const SESSION_SCOPES: readonly ["chat", "thread"];
+/** What one group session spans: the chat (and forum topic), or one reply thread. */
+export type SessionScope = (typeof SESSION_SCOPES)[number];
+/** How the Telegram adapter keeps sessions: their scope, the daily compaction and the idle reset. */
+export interface SessionSettings {
+    readonly scope: SessionScope;
+    /** `HH:MM` in `timezone`, or `false`. */
+    readonly compactAt: string | false;
+    readonly timezone: string;
+    readonly idleResetHours: number | false;
+}
 /** The validated configuration with defaults applied. It stays JSON-serializable. */
 export interface SegmentStreamAgentConfig {
     readonly channels: {
@@ -80,6 +107,7 @@ export interface SegmentStreamAgentConfig {
     readonly ontology: {
         readonly connection: boolean;
     };
+    readonly sessions: SessionSettings;
 }
 /** One validation failure, in Standard Schema's issue shape. */
 export interface ConfigIssue {

package/dist/extension/config.mjs

@@ -8,6 +8,7 @@ const CONNECTION_KEY = /^[a-z][a-z0-9_]{0,63}$/;
 const TELEGRAM_POLICIES = ["mention", "smart"];
 const DEFAULT_STT_MODEL = "spacexai/grok-stt";
 const DEFAULT_DECISION_MODEL = "typesafe-ai/jev";
+const SESSION_SCOPES = ["chat", "thread"];
 var SegmentStreamAgentConfigError = class extends Error {
 	issues;
 	name = "SegmentStreamAgentConfigError";
@@ -124,6 +125,58 @@ function chatModelChoice(value, issues) {
 		...preview === void 0 ? {} : { preview }
 	};
 }
+const TIME_OF_DAY = /^(?:[01]\d|2[0-3]):[0-5]\d$/;
+function isSessionScope(value) {
+	return SESSION_SCOPES.some((scope) => scope === value);
+}
+function isTimeZone(value) {
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone: value });
+		return true;
+	} catch {
+		return false;
+	}
+}
+function sessionSettings(value, issues) {
+	const path = ["sessions"];
+	const sessions = section({
+		value,
+		path,
+		allowed: [
+			"scope",
+			"compactAt",
+			"timezone",
+			"idleResetHours"
+		],
+		issues
+	}) ?? {};
+	const scope = sessions.scope ?? "chat";
+	const compactAt = sessions.compactAt ?? "00:00";
+	const timezone = sessions.timezone ?? "UTC";
+	const idleResetHours = sessions.idleResetHours ?? false;
+	if (!isSessionScope(scope)) issues.push({
+		message: "must be \"chat\" or \"thread\"",
+		path: [...path, "scope"]
+	});
+	if (compactAt !== false && (typeof compactAt !== "string" || !TIME_OF_DAY.test(compactAt))) issues.push({
+		message: "must be a time such as 00:00, or false",
+		path: [...path, "compactAt"]
+	});
+	if (typeof timezone !== "string" || !isTimeZone(timezone)) issues.push({
+		message: "must be an IANA time zone such as Europe/London",
+		path: [...path, "timezone"]
+	});
+	if (idleResetHours !== false && (typeof idleResetHours !== "number" || !Number.isFinite(idleResetHours) || idleResetHours <= 0)) issues.push({
+		message: "must be a number of hours greater than zero, or false",
+		path: [...path, "idleResetHours"]
+	});
+	return {
+		scope: isSessionScope(scope) ? scope : "chat",
+		compactAt: typeof compactAt === "string" && TIME_OF_DAY.test(compactAt) ? compactAt : false,
+		timezone: typeof timezone === "string" ? timezone : "UTC",
+		idleResetHours: typeof idleResetHours === "number" && Number.isFinite(idleResetHours) && idleResetHours > 0 ? idleResetHours : false
+	};
+}
 function validateConfig(input) {
 	const issues = [];
 	const root = section({
@@ -132,7 +185,8 @@ function validateConfig(input) {
 		allowed: [
 			"channels",
 			"models",
-			"ontology"
+			"ontology",
+			"sessions"
 		],
 		issues
 	});
@@ -173,6 +227,7 @@ function validateConfig(input) {
 		issues
 	});
 	const connection = ontology?.connection ?? true;
+	const sessions = sessionSettings(root?.sessions, issues);
 	if (typeof connection !== "boolean") issues.push({
 		message: "must be true or false",
 		path: ["ontology", "connection"]
@@ -185,7 +240,8 @@ function validateConfig(input) {
 			stt,
 			decision
 		},
-		ontology: { connection: connection === true }
+		ontology: { connection: connection === true },
+		sessions
 	} };
 }
 const configSchema = { "~standard": {
@@ -199,4 +255,4 @@ function manifestOf(config) {
 	if (validation.issues !== void 0) throw new SegmentStreamAgentConfigError(validation.issues);
 	return validation.value;
 }
-export { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, TELEGRAM_POLICIES, configSchema, manifestOf, validateConfig };
+export { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SESSION_SCOPES, SegmentStreamAgentConfigError, TELEGRAM_POLICIES, configSchema, manifestOf, validateConfig };

package/dist/extension/extension.d.ts

@@ -15,5 +15,5 @@ export declare const segmentstream: import("eve/extension").ExtensionHandle<{
     manifestOf: typeof manifestOf;
 };
 export default segmentstream;
-export { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, manifestOf, type ChatModelChoice, type SegmentStreamAgentConfig, type SegmentStreamAgentConfigInput, type TelegramPolicy, type TelegramSettings, } from "./config.js";
+export { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, manifestOf, type ChatModelChoice, type SegmentStreamAgentConfig, type SegmentStreamAgentConfigInput, type SessionScope, type SessionSettings, type TelegramPolicy, type TelegramSettings, } from "./config.js";
 export { chooseModel, model, type DynamicModel, type ModelChoice } from "./model.js";

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,9 +1,11 @@
 import { type TelegramChannel } from "eve/channels/telegram";
-import type { TelegramSettings } from "../../config.js";
+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";
+import { type HistoryReader } from "./sessions.js";
 import { type Transcriber } from "./voice.js";
 /**
  * The SegmentStream Telegram adapter: eve's `telegramChannel`, with its credentials, identity,
@@ -17,6 +19,8 @@ export interface TelegramAdapterOptions {
         readonly stt: string | false;
         readonly decision: string;
     };
+    /** The mounted `sessions`. */
+    readonly sessions: () => SessionSettings;
     readonly decide: DecideFunction;
     readonly environment?: Environment;
     readonly token?: RuntimeToken;
@@ -24,6 +28,10 @@ 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 Telegram channel of the extension. */
 export declare function segmentstreamTelegram(options: TelegramAdapterOptions): TelegramChannel;

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

@@ -4,27 +4,48 @@ 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";
 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";
+const eveHistory = async (sessionId) => {
+	const { sessions } = await import("eve/server");
+	const events = [];
+	for await (const event of sessions.attach(sessionId).stream({
+		startIndex: -400,
+		follow: false
+	})) events.push({
+		type: event.type,
+		meta: { at: event.meta.at }
+	});
+	return events;
+};
 function segmentstreamTelegram(options) {
 	const environment = options.environment ?? process.env;
 	const token = options.token ?? runtimeToken;
 	const observed = options.observed ?? observedMessages();
+	const policy = sessionPolicy({
+		settings: options.sessions,
+		read: options.history ?? eveHistory
+	});
 	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.");
@@ -52,6 +73,7 @@ function segmentstreamTelegram(options) {
 		});
 		return identities;
 	}
+	const chats = agentChats({ identities: pairing });
 	const channel = telegramChannel({
 		api: {
 			apiBaseUrl: TELEGRAM_PROXY_ORIGIN,
@@ -69,6 +91,8 @@ function segmentstreamTelegram(options) {
 			request: currentInboundRequest(),
 			dependencies: {
 				policy: settings().policy,
+				sessions: options.sessions,
+				sessionPolicy: policy,
 				sttModel: options.models().stt,
 				identities: pairing(),
 				bot,
@@ -82,6 +106,7 @@ function segmentstreamTelegram(options) {
 					fileId
 				}),
 				observed,
+				chats,
 				connectUrl: (code) => `${appOrigin(environment)}/agent/connect?code=${encodeURIComponent(code)}`
 			}
 		}),
@@ -89,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) {
@@ -105,9 +137,15 @@ function gatedRoute(input) {
 			if (!channelsEnabled(environment)) return new Response("ok");
 			if (options.settings() === null) return new Response("not found", { status: 404 });
 			const inbound = new InboundRequest(async () => (await args.describe()).description ?? "");
+			const scoped = (address) => scopedAddress(address, options.sessions().scope);
+			inbound.sessions = {
+				resolveSession: args.resolveSession,
+				from: args.from
+			};
+			inbound.waitUntil = args.waitUntil;
 			return runInboundRequest(inbound, () => route.handler(request, {
 				...args,
-				from: (address) => withReplacedText(args.from(address), inbound)
+				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>;