@segmentstream/agent 0.1.2 → 0.1.4

package/README.md

@@ -51,17 +51,15 @@ import { segmentstream } from "@segmentstream/agent";
 
 export default defineAgent({
   defaultTools: false,
-  model: segmentstream.model({
-    default: "spacexai/grok-4.7",
-    byRole: { finance: "anthropic/claude-opus-5.5" },
-    preview: "google/gemini-flash",
-  }),
+  model: segmentstream.model(),
   reasoning: "medium",
   limits: { maxTokenCostUsdPerSession: 2 },
 });
 ```
 
-`segmentstream.model()` resolves on `session.started`. On a preview deployment it returns `preview`
+`segmentstream.model()` resolves on `session.started` from `models.chat` in `agent/segmentstream.json`
+(`{ "default", "byRole", "preview" }`), where the platform reads it too; an inline
+`segmentstream.model({ default, byRole, preview })` works the same. On a preview deployment it returns `preview`
 when set. Otherwise it returns the model of the first `byRole` entry whose role the member holds, in
 the order written, and `default` when none matches. The roles come from the member's pairing, not
 from the message. The model is never switched mid-session, which keeps the provider's prompt cache.
@@ -118,7 +116,8 @@ share a group chat's session never share a client.
   proxy. The token stays in SegmentStream.
 - **Webhook.** A webhook is accepted only with `X-Telegram-Bot-Api-Secret-Token` equal to
   `SEGMENTSTREAM_AGENT_WEBHOOK_SECRET`, compared in constant time. The platform generates the
-  secret and registers the webhook after each production deployment.
+  secret and registers the webhook after each production deployment, and sets the bot's menu
+  button, shown in private chats, to open the workspace app.
 - **Production only.** Outside `VERCEL_ENV=production` the route answers 200 and does nothing, so a
   preview never answers a real chat. Without `channels.telegram` it answers 404.
 - **Pairing.** Messages from bots and channel posts are dropped. The sender's Telegram account is

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

@@ -30,6 +30,16 @@ export interface SegmentStreamAgentConfigInput {
         };
     };
     readonly models?: {
+        /**
+         * The chat model `segmentstream.model()` chooses per session: `default` for everyone, one per
+         * member role in `byRole` (the first role the member holds wins, in the order written) and
+         * `preview` for preview deployments.
+         */
+        readonly chat?: {
+            readonly default: string;
+            readonly byRole?: Readonly<Record<string, string>>;
+            readonly preview?: string;
+        };
         /** A Gateway transcription model, or `false` to leave voice messages untranscribed. */
         readonly stt?: string | boolean;
         /** The Gateway decision model of the inbound router. */
@@ -39,23 +49,65 @@ 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;
     readonly policy: TelegramPolicy;
 }
+/** The chat models `segmentstream.model()` chooses between, as AI Gateway model ids. */
+export interface ChatModelChoice {
+    /** The model for every session no other rule picks. */
+    readonly default: string;
+    /**
+     * A model per member role. The first entry whose role the member holds wins, in the order
+     * written, so put the more specific roles first.
+     */
+    readonly byRole?: Readonly<Record<string, string>>;
+    /** 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: {
         readonly telegram: TelegramSettings | null;
     };
     readonly models: {
+        /** `null` when `agent.ts` passes the choice to `segmentstream.model()` itself. */
+        readonly chat: ChatModelChoice | null;
         readonly stt: string | false;
         readonly decision: string;
     };
     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";
@@ -72,6 +73,110 @@ function modelId(input) {
 	}
 	return input.value;
 }
+function chatModelChoice(value, issues) {
+	const path = ["models", "chat"];
+	const chat = section({
+		value,
+		path,
+		allowed: [
+			"default",
+			"byRole",
+			"preview"
+		],
+		issues
+	});
+	if (chat === void 0) return null;
+	const fallback = "";
+	if (chat.default === void 0) issues.push({
+		message: "is required",
+		path: [...path, "default"]
+	});
+	const defaultModel = modelId({
+		value: chat.default,
+		fallback,
+		path: [...path, "default"],
+		issues
+	});
+	const byRole = section({
+		value: chat.byRole,
+		path: [...path, "byRole"],
+		allowed: Object.keys(isRecord(chat.byRole) ? chat.byRole : {}),
+		issues
+	});
+	const roles = Object.fromEntries(Object.entries(byRole ?? {}).map(([role, model]) => [role, modelId({
+		value: model,
+		fallback,
+		path: [
+			...path,
+			"byRole",
+			role
+		],
+		issues
+	})]));
+	const preview = chat.preview === void 0 ? void 0 : modelId({
+		value: chat.preview,
+		fallback,
+		path: [...path, "preview"],
+		issues
+	});
+	return {
+		default: defaultModel,
+		...byRole === void 0 ? {} : { byRole: roles },
+		...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({
@@ -80,7 +185,8 @@ function validateConfig(input) {
 		allowed: [
 			"channels",
 			"models",
-			"ontology"
+			"ontology",
+			"sessions"
 		],
 		issues
 	});
@@ -93,7 +199,11 @@ function validateConfig(input) {
 	const models = section({
 		value: root?.models,
 		path: ["models"],
-		allowed: ["stt", "decision"],
+		allowed: [
+			"chat",
+			"stt",
+			"decision"
+		],
 		issues
 	});
 	const ontology = section({
@@ -103,6 +213,7 @@ function validateConfig(input) {
 		issues
 	});
 	const telegram = telegramSettings(channels?.telegram, issues);
+	const chat = chatModelChoice(models?.chat, issues);
 	const stt = models?.stt === false ? false : modelId({
 		value: models?.stt,
 		fallback: DEFAULT_STT_MODEL,
@@ -116,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"]
@@ -124,10 +236,12 @@ function validateConfig(input) {
 	return { value: {
 		channels: { telegram },
 		models: {
+			chat,
 			stt,
 			decision
 		},
-		ontology: { connection: connection === true }
+		ontology: { connection: connection === true },
+		sessions
 	} };
 }
 const configSchema = { "~standard": {
@@ -141,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

@@ -1,5 +1,5 @@
 import { manifestOf } from "./config.js";
-import { model } from "./model.js";
+import { type DynamicModel, type ModelChoice } from "./model.js";
 export declare const segmentstream: import("eve/extension").ExtensionHandle<{
     readonly "~standard": {
         readonly version: 1;
@@ -11,9 +11,9 @@ export declare const segmentstream: import("eve/extension").ExtensionHandle<{
         };
     };
 }> & {
-    model: typeof model;
+    model: (choice?: ModelChoice) => DynamicModel;
     manifestOf: typeof manifestOf;
 };
 export default segmentstream;
-export { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, manifestOf, 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/extension.mjs

@@ -9,7 +9,7 @@ import { chooseModel, model } from "./model.mjs";
 import { defineExtension } from "eve/extension";
 const extension = defineExtension({ config: configSchema });
 const segmentstream = Object.assign(extension, {
-	model,
+	model: (choice) => model(choice ?? (() => extension.config.models.chat)),
 	manifestOf
 });
 export { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, chooseModel, segmentstream as default, segmentstream, manifestOf, model };

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

@@ -1,9 +1,10 @@
 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 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 +18,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 +27,8 @@ export interface TelegramAdapterOptions {
     readonly fetch?: typeof fetch;
     readonly transcribe?: Transcriber;
     readonly observed?: ObservedMessages;
+    /** 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

@@ -11,6 +11,7 @@ import { runtimeToken } from "../runtime-token.mjs";
 import { botIdentityCache } from "./bot.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";
@@ -18,10 +19,26 @@ import { TELEGRAM_PLACEHOLDER_TOKEN, TELEGRAM_PROXY_ORIGIN, telegramProxyFetch }
 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;
@@ -69,6 +86,8 @@ function segmentstreamTelegram(options) {
 			request: currentInboundRequest(),
 			dependencies: {
 				policy: settings().policy,
+				sessions: options.sessions,
+				sessionPolicy: policy,
 				sttModel: options.models().stt,
 				identities: pairing(),
 				bot,
@@ -105,9 +124,14 @@ 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
+			};
 			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/inbound-request.d.ts

@@ -1,4 +1,5 @@
 import type { ChannelSource } from "eve/channels";
+import type { SessionOperations } from "./sessions.js";
 /**
  * What one webhook request shares between eve's `onMessage` hook and the route wrapper around it.
  * `onMessage` may only return `{ auth, context, title }`; it cannot change the message eve sends.
@@ -11,6 +12,8 @@ export declare class InboundRequest {
     readonly agentDescription: () => Promise<string>;
     /** The text the turn should carry instead of the parsed message, once a transcript exists. */
     text: string | undefined;
+    /** The route's session operations, on addresses already mapped to the configured scope. */
+    sessions: SessionOperations | 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

@@ -8,6 +8,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 var InboundRequest = class {
 	agentDescription;
 	text;
+	sessions;
 	constructor(agentDescription) {
 		this.agentDescription = agentDescription;
 	}

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

@@ -1,10 +1,11 @@
 import type { TelegramContext, TelegramInboundResult, TelegramMessage } from "eve/channels/telegram";
-import type { TelegramPolicy } from "../../config.js";
+import type { SessionSettings, TelegramPolicy } from "../../config.js";
 import type { AgentIdentities } from "../identities.js";
 import type { BotIdentityLookup } from "./bot.js";
 import type { InboundRequest } from "./inbound-request.js";
 import { type ObservedMessages } from "./observed.js";
 import { type RouteDecider } from "./router.js";
+import { type SessionPolicy } from "./sessions.js";
 import { type Transcriber } from "./voice.js";
 /**
  * eve's Telegram `onMessage` hook, in the order `agent-design.md` gives:
@@ -13,10 +14,15 @@ import { type Transcriber } from "./voice.js";
  *    start a turn. An unknown sender who writes to the bot privately gets a pairing button.
  * 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. An answered message dispatches as the paired member, with the ring ahead of it as context.
+ * 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.
  */
 export interface InboundDependencies {
     readonly policy: TelegramPolicy;
+    readonly sessions: () => SessionSettings;
+    readonly sessionPolicy: SessionPolicy;
     readonly sttModel: string | false;
     readonly identities: AgentIdentities;
     readonly bot: BotIdentityLookup;

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

@@ -7,10 +7,12 @@ __eveCreateRequire(import.meta.url);
 import { telegramPrincipal } from "./principal.mjs";
 import { observedChatKey, observedContext } from "./observed.mjs";
 import { isAddressed, routeMessage } from "./router.mjs";
+import { messageAddress, scopedAddress } from "./sessions.mjs";
 import { voiceNote, voiceOf, voiceText } from "./voice.mjs";
 const UNKNOWN_PRIVATE = "Hi, I don't know you yet. Connect your Telegram account to the workspace and I'll act as you. The button works for ten minutes.";
 const UNKNOWN_IN_GROUP = "I don't know you yet. Message me privately to connect your account.";
 const REFUSED = "Your access to this agent was revoked, or your membership is inactive. Ask a workspace administrator.";
+const MAXIMUM_QUOTE_LENGTH = 500;
 function buttonTo(text, url) {
 	return { inline_keyboard: [[{
 		text,
@@ -26,13 +28,41 @@ function sentAt(message) {
 	const date = message.raw.date;
 	return new Date(typeof date === "number" ? date * 1e3 : Date.now()).toISOString();
 }
-function observedMessage(message, text) {
+function authorOf(user, member) {
+	const name = display(user) ?? user.id;
+	if (member === void 0) return name;
+	const roles = member.roles.length === 0 ? "" : ` (${member.roles.join(", ")})`;
+	return member.name === null ? `${name}${roles}` : `${member.name}${roles}, ${name}`;
+}
+function observedMessage(message, text, member) {
 	return {
-		author: display(message.from) ?? message.from.id,
+		author: authorOf(message.from, member),
 		text,
 		at: sentAt(message)
 	};
 }
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function speakerBlock(input) {
+	const { message, member, bot } = input;
+	const roles = member.roles.length === 0 ? "no roles" : member.roles.join(", ");
+	const lines = [
+		"<speaker>",
+		`member: ${member.name ?? "unnamed member"} (${roles})`,
+		`telegram: ${display(message.from) ?? "no name"}, user_id ${message.from.id}`
+	];
+	const raw = message.raw.reply_to_message;
+	if (isRecord(raw)) {
+		const from = isRecord(raw.from) ? raw.from : {};
+		const author = from.is_bot === true && bot !== void 0 && String(from.id) === bot.id ? "the agent" : typeof from.username === "string" ? `@${from.username}` : typeof from.first_name === "string" ? from.first_name : "unknown sender";
+		const text = typeof raw.text === "string" ? raw.text : typeof raw.caption === "string" ? raw.caption : "";
+		const quoted = text.length > MAXIMUM_QUOTE_LENGTH ? `${text.slice(0, MAXIMUM_QUOTE_LENGTH)}…` : text;
+		lines.push(`reply_to: ${author}: ${JSON.stringify(quoted)}`);
+	}
+	lines.push("</speaker>");
+	return lines.join("\n");
+}
 function unknownInGroup(bot) {
 	return bot?.username === void 0 ? { text: UNKNOWN_IN_GROUP } : {
 		text: UNKNOWN_IN_GROUP,
@@ -84,6 +114,8 @@ async function handleInboundMessage(input) {
 		});
 		return null;
 	}
+	const address = scopedAddress(messageAddress(sent), dependencies.sessions().scope);
+	const operations = input.request?.sessions;
 	const voice = voiceOf(sent.raw);
 	const caption = sent.text || sent.caption;
 	const notes = [];
@@ -110,21 +142,38 @@ async function handleInboundMessage(input) {
 		question: async () => ({
 			agent: await input.request?.agentDescription() ?? "",
 			observed: dependencies.observed.list(chat),
-			message: observedMessage(sent, text)
+			message: observedMessage(sent, text, lookup.member)
 		})
 	}) === "observe") {
-		dependencies.observed.add(chat, observedMessage(sent, text === "" ? "[attachment]" : text));
+		dependencies.observed.add(chat, observedMessage(sent, text === "" ? "[attachment]" : text, lookup.member));
 		return null;
 	}
 	if (voice !== void 0 && input.request !== void 0) input.request.text = text;
 	else if (voice !== void 0) notes.push(text);
+	if (operations !== void 0) {
+		const newest = dependencies.observed.list(chat).at(-1);
+		if (await dependencies.sessionPolicy.apply({
+			address,
+			operations,
+			...newest === void 0 ? {} : { activeAt: Date.parse(newest.at) || 0 }
+		}) === "cleared") dependencies.observed.take(chat);
+		dependencies.sessionPolicy.delivered(address);
+	}
 	await context.telegram.startTyping();
 	return {
 		auth: telegramPrincipal({
 			message: sent,
 			member: lookup.member
 		}),
-		context: [...observedContext(dependencies.observed.take(chat)), ...notes]
+		context: [
+			...observedContext(dependencies.observed.take(chat)),
+			speakerBlock({
+				message: sent,
+				member: lookup.member,
+				bot
+			}),
+			...notes
+		]
 	};
 }
 export { handleInboundMessage };

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

@@ -0,0 +1,84 @@
+import type { TelegramMessage } from "eve/channels/telegram";
+import type { SessionSettings } from "../../config.js";
+/**
+ * Session policy for the Telegram channel (`agent-design.md`, section 4, and docs/agent.md,
+ * "Sessions"): what a group session spans, the daily compaction and the idle reset. The policy
+ * runs in the webhook route, before eve delivers a message, with the operations the route offers
+ * on a continuation address (`resolveSession`, `compact`, `clear`); the history it needs is read
+ * from the session's own durable stream, so nothing is stored beside eve.
+ */
+/** eve's Telegram continuation address: `chat:thread:conversation`, the last two possibly empty. */
+export interface TelegramAddress {
+    readonly chatId: string;
+    readonly messageThreadId: string;
+    readonly conversationId: string;
+}
+export declare function parseAddress(address: string): TelegramAddress;
+export declare function formatAddress(address: TelegramAddress): string;
+/**
+ * The address eve derives from an inbound message: the chat, the forum topic and, in a group, the
+ * reply thread (a reply to the bot continues the bot's message, anything else starts its own).
+ */
+export declare function messageAddress(message: TelegramMessage): string;
+/**
+ * The address a message continues under the configured scope. `chat` drops eve's reply-thread
+ * anchor, so every message of a group chat (and forum topic) reaches one session; `thread` keeps
+ * eve's own address. A private chat has no anchor either way.
+ */
+export declare function scopedAddress(address: string, scope: SessionSettings["scope"]): string;
+/** The most recent `HH:MM` in `timezone` at or before `now`. */
+export declare function compactBoundary(now: Date, compactAt: string, timezone: string): Date;
+/** What the policy knows about one session: from its stream, then kept per process. */
+export interface SessionHistory {
+    /** When the session last did anything. */
+    readonly lastAt: number;
+    /** When its history last started afresh: creation, compaction or clear. */
+    readonly resetAt: number;
+    /** Turns completed since `resetAt`; a compaction is worth nothing before the first. */
+    readonly turnsSinceReset: number;
+}
+/** One recorded event, as much of eve's envelope as the policy reads. */
+export interface RecordedEvent {
+    readonly type: string;
+    readonly meta: {
+        readonly at: string;
+    };
+}
+/** The last events of a session, oldest first. Production reads eve's durable stream. */
+export type HistoryReader = (sessionId: string) => Promise<ReadonlyArray<RecordedEvent>>;
+/** How many events of the tail the reader fetches: enough for a day of a busy group. */
+export declare const HISTORY_TAIL = 400;
+/** Folds a tail into a history; with no reset marker in it, `resetAt` is its earliest event. */
+export declare function historyOf(events: ReadonlyArray<RecordedEvent>): SessionHistory;
+/** The route's operations on a continuation address, as eve gives them to the handler. */
+export interface SessionOperations {
+    readonly resolveSession: (address: string) => Promise<{
+        readonly id: string;
+    } | undefined>;
+    readonly from: (address: string) => {
+        compact(): Promise<unknown>;
+        clear(): Promise<unknown>;
+    };
+}
+export type SessionAction = "none" | "cleared" | "compacted";
+export interface SessionPolicy {
+    /**
+     * Applies the policy to the session `address` continues, before a message is delivered to it:
+     * clears a history idle for longer than `idleResetHours`, else compacts it once after each
+     * day's `compactAt`. A session that does not exist yet needs neither.
+     */
+    apply(input: {
+        readonly address: string;
+        readonly operations: SessionOperations;
+        /** The newest activity the stream does not show, such as an observed group message. */
+        readonly activeAt?: number;
+        readonly now?: Date;
+    }): Promise<SessionAction>;
+    /** Records that a message was just delivered to the session. */
+    delivered(address: string, now?: Date): void;
+}
+export declare function sessionPolicy(input: {
+    readonly settings: () => SessionSettings;
+    readonly read: HistoryReader;
+    readonly log?: (message: string, error: unknown) => void;
+}): SessionPolicy;

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

@@ -0,0 +1,200 @@
+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);
+function parseAddress(address) {
+	const [chatId = "", messageThreadId = "", conversationId = ""] = address.split(":");
+	return {
+		chatId,
+		messageThreadId,
+		conversationId
+	};
+}
+function formatAddress(address) {
+	return `${address.chatId}:${address.messageThreadId}:${address.conversationId}`;
+}
+function messageAddress(message) {
+	const group = message.chat.type === "group" || message.chat.type === "supergroup";
+	const reply = message.replyToMessage;
+	const conversationId = !group ? "" : reply?.from?.isBot === true ? reply.messageId : message.messageId;
+	return formatAddress({
+		chatId: message.chat.id,
+		messageThreadId: message.messageThreadId === void 0 ? "" : String(message.messageThreadId),
+		conversationId
+	});
+}
+function scopedAddress(address, scope) {
+	if (scope === "thread") return address;
+	return formatAddress({
+		...parseAddress(address),
+		conversationId: ""
+	});
+}
+function localParts(timezone, date) {
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone: timezone,
+		hourCycle: "h23",
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit"
+	}).formatToParts(date);
+	const value = (type) => Number(parts.find((part) => part.type === type)?.value ?? "0");
+	return {
+		year: value("year"),
+		month: value("month"),
+		day: value("day"),
+		hour: value("hour"),
+		minute: value("minute"),
+		second: value("second")
+	};
+}
+function offsetMinutes(timezone, date) {
+	const local = localParts(timezone, date);
+	const asUtc = Date.UTC(local.year, local.month - 1, local.day, local.hour, local.minute, local.second);
+	return Math.round((asUtc - date.getTime()) / 6e4);
+}
+function instantOf(timezone, local) {
+	const guess = Date.UTC(local.year, local.month - 1, local.day, local.hour, local.minute);
+	const first = new Date(guess - offsetMinutes(timezone, new Date(guess)) * 6e4);
+	const second = new Date(guess - offsetMinutes(timezone, first) * 6e4);
+	const back = localParts(timezone, second);
+	if (back.hour !== local.hour || back.minute !== local.minute) return first > second ? first : second;
+	return second;
+}
+function compactBoundary(now, compactAt, timezone) {
+	const [hour = 0, minute = 0] = compactAt.split(":").map(Number);
+	const today = localParts(timezone, now);
+	const candidate = instantOf(timezone, {
+		...today,
+		hour,
+		minute
+	});
+	if (candidate.getTime() <= now.getTime()) return candidate;
+	const yesterday = new Date(Date.UTC(today.year, today.month - 1, today.day - 1));
+	return instantOf(timezone, {
+		year: yesterday.getUTCFullYear(),
+		month: yesterday.getUTCMonth() + 1,
+		day: yesterday.getUTCDate(),
+		hour,
+		minute
+	});
+}
+const HISTORY_TAIL = 400;
+function historyOf(events) {
+	let lastAt = 0;
+	let resetAt = 0;
+	let earliest = 0;
+	let marked = false;
+	let turnsSinceReset = 0;
+	for (const event of events) {
+		const at = Date.parse(event.meta.at);
+		if (Number.isNaN(at)) continue;
+		lastAt = Math.max(lastAt, at);
+		earliest = earliest === 0 ? at : Math.min(earliest, at);
+		if (event.type === "session.started" || event.type === "compaction.completed" || event.type === "context.cleared") {
+			resetAt = at;
+			marked = true;
+			turnsSinceReset = 0;
+		} else if (event.type === "turn.completed") turnsSinceReset += 1;
+	}
+	return {
+		lastAt,
+		resetAt: marked ? resetAt : earliest,
+		turnsSinceReset
+	};
+}
+const MAXIMUM_REMEMBERED = 500;
+function sessionPolicy(input) {
+	const remembered = new Map();
+	const log = input.log ?? ((message, error) => console.warn(message, error));
+	function remember(address, history) {
+		remembered.delete(address);
+		remembered.set(address, history);
+		if (remembered.size > MAXIMUM_REMEMBERED) {
+			const oldest = remembered.keys().next();
+			if (oldest.done !== true) remembered.delete(oldest.value);
+		}
+	}
+	async function history(address, operations, fresh = false) {
+		const known = fresh ? void 0 : remembered.get(address);
+		if (known !== void 0) return known;
+		const session = await operations.resolveSession(address);
+		if (session === void 0) {
+			remembered.delete(address);
+			return;
+		}
+		const read = historyOf(await input.read(session.id));
+		remember(address, read);
+		return read;
+	}
+	function due(known, settings, now, activeAt) {
+		const idle = settings.idleResetHours;
+		const lastAt = Math.max(known.lastAt, activeAt);
+		if (idle !== false && now.getTime() - lastAt >= idle * 36e5) return "clear";
+		if (settings.compactAt !== false) {
+			const boundary = compactBoundary(now, settings.compactAt, settings.timezone).getTime();
+			if (known.resetAt < boundary && known.turnsSinceReset > 0) return "compact";
+		}
+		return "none";
+	}
+	return {
+		async apply({ address, operations, activeAt = 0, now = new Date() }) {
+			const settings = input.settings();
+			const cached = remembered.has(address);
+			let known;
+			try {
+				known = await history(address, operations);
+			} catch (error) {
+				log("The session policy could not read the session's history; delivering as is.", error);
+				return "none";
+			}
+			if (known === void 0) return "none";
+			let action = due(known, settings, now, activeAt);
+			if (action !== "none" && cached) {
+				try {
+					known = await history(address, operations, true);
+				} catch (error) {
+					log("The session policy could not re-read the session's history; delivering as is.", error);
+					return "none";
+				}
+				if (known === void 0) return "none";
+				action = due(known, settings, now, activeAt);
+			}
+			if (action === "clear") try {
+				await operations.from(address).clear();
+				remember(address, {
+					lastAt: known.lastAt,
+					resetAt: now.getTime(),
+					turnsSinceReset: 0
+				});
+				return "cleared";
+			} catch (error) {
+				log("The idle reset could not clear the session; delivering as is.", error);
+				return "none";
+			}
+			if (action === "compact") try {
+				await operations.from(address).compact();
+				remembered.delete(address);
+				return "compacted";
+			} catch (error) {
+				log("The daily compaction could not be queued; delivering as is.", error);
+			}
+			return "none";
+		},
+		delivered(address, now = new Date()) {
+			const known = remembered.get(address);
+			if (known === void 0) return;
+			remember(address, {
+				lastAt: now.getTime(),
+				resetAt: known.resetAt,
+				turnsSinceReset: known.turnsSinceReset + 1
+			});
+		}
+	};
+}
+export { HISTORY_TAIL, compactBoundary, formatAddress, historyOf, messageAddress, parseAddress, scopedAddress, sessionPolicy };

package/dist/extension/model.d.ts

@@ -1,18 +1,9 @@
 import { type AgentModelDefinition, type AgentStaticModelDefinition } from "eve";
 import type { SessionAuthContext } from "eve/context";
+import type { ChatModelChoice } from "./config.js";
 import { type Environment } from "./lib/environment.js";
 /** The models `segmentstream.model()` chooses between, as AI Gateway model ids. */
-export interface ModelChoice {
-    /** The model for every session no other rule picks. */
-    readonly default: string;
-    /**
-     * A model per member role. The first entry whose role the member holds wins, in the order
-     * written, so put the more specific roles first.
-     */
-    readonly byRole?: Readonly<Record<string, string>>;
-    /** The model of preview deployments, so a preview never spends on a large model. */
-    readonly preview?: string;
-}
+export type ModelChoice = ChatModelChoice;
 /** The dynamic form of an agent's `model`, which `defineAgent` accepts as the whole field. */
 export type DynamicModel = Exclude<AgentModelDefinition, AgentStaticModelDefinition>;
 /** The one model for a session started by `principal`. */
@@ -24,6 +15,8 @@ export declare function chooseModel(input: {
 /**
  * The agent's model, chosen once when a session starts from the member's roles and `VERCEL_ENV`.
  * Choosing once keeps the provider's prompt cache: a switch mid-session re-reads the history at
- * full price.
+ * full price. The choice is given here, or read when the session starts, from `models.chat` of
+ * `agent/segmentstream.json` through the mounted extension; a session without either fails to
+ * start with a message naming the missing setting.
  */
-export declare function model(choice: ModelChoice): DynamicModel;
+export declare function model(choice: ModelChoice | (() => ModelChoice | null)): DynamicModel;

package/dist/extension/model.mjs

@@ -15,9 +15,13 @@ function chooseModel(input) {
 	return choice.default;
 }
 function model(choice) {
-	return defineDynamic({ events: { "session.started": (_event, context) => chooseModel({
-		choice,
-		principal: context.session.auth.current ?? context.session.auth.initiator
-	}) } });
+	return defineDynamic({ events: { "session.started": (_event, context) => {
+		const chosen = typeof choice === "function" ? choice() : choice;
+		if (chosen === null) throw new Error("segmentstream.model() has no model to choose from: set models.chat in agent/segmentstream.json or pass the choice to segmentstream.model().");
+		return chooseModel({
+			choice: chosen,
+			principal: context.session.auth.current ?? context.session.auth.initiator
+		});
+	} } });
 }
 export { chooseModel, model };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream/agent",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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",