@segmentstream/agent 0.12.2 → 0.13.0

package/README.md

@@ -189,13 +189,13 @@ continue using GET lookup. Starter templates and pins remain unchanged in this s
 
 ## What the extension contributes
 
-| Name                                                               | Slot           | What it does                                                                                                                                                                    |
-| ------------------------------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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.                                                                                      |
-| `segmentstream__attachments_list`, `_read`, `_promote`, `_discard` | `tools`        | The member's temporary attachments in this chat: list, read, keep through an action, drop.                                                                                      |
-| `segmentstream__attachments_send`                                  | `tools`        | Sends readable stored ontology files into the current Telegram chat and topic.                                                                                                  |
-| platform rules                                                     | `instructions` | Changes go through actions; `describe` indexes or inspects refs; `discover` searches metadata; tools are already narrowed; when to answer `[SILENT]`; how to handle attachments |
+| Name                                                                 | Slot           | What it does                                                                                                                                                                    |
+| -------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `segmentstream__ontology_describe`, `_discover`, `_inspect`, `_call` | `tools`        | Permission-filtered metadata, schema inspection and action calls as the current member.                                                                                         |
+| `segmentstream__telegram`                                            | `channels`     | `POST /eve/v1/telegram`: Telegram through the connection, with pairing, routing and voice.                                                                                      |
+| `segmentstream__attachments_list`, `_read`, `_promote`, `_discard`   | `tools`        | The member's temporary attachments in this chat: list, read, keep through an action, drop.                                                                                      |
+| `segmentstream__attachments_send`                                    | `tools`        | Sends readable stored ontology files into the current Telegram chat and topic.                                                                                                  |
+| platform rules                                                       | `instructions` | Changes go through actions; `describe` indexes or inspects refs; `discover` searches metadata; tools are already narrowed; when to answer `[SILENT]`; how to handle attachments |
 
 ### The ontology
 
@@ -222,15 +222,17 @@ 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, and sets the bot's menu
-  button, shown in private chats, to open the workspace app.
+  secret and registers the webhook after each production deployment. A workspace-supplied
+  `menuButton.text` enables the app menu button; omitting it resets the provider menu to its default
+  for Agent SDK 0.13 or later. Pre-0.13 archives without menu copy retain their existing provider menu.
 - **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.** Bots and channel posts are archived without starting turns. The sender's Telegram
   account is checked on every message, so revocation takes effect immediately. Unlinked group
   speech and attachment metadata remain raw context, including edits; no unlinked voice is decoded or gets
-  a reply. An unknown private sender gets a neutral connection button to `/agent/connect?code=…`,
-  valid for ten minutes; revoked or inactive private senders get a neutral refusal marker.
+  a reply. An unknown private sender gets the workspace pairing prompt and button to `/agent/connect?code=…`,
+  valid for ten minutes; revoked or inactive private senders receive configured refusal copy,
+  or no message when it is absent.
 - **Who the agent is.** A paired sender's turn runs with the principal id `telegram:<user>`
   (`telegram:<chat>:<user>` in groups) and the attributes `memberId`, `memberName`, `roles`,
   `chatId`, `chatType` and `username`.
@@ -516,7 +518,7 @@ ontology SDK along with this extension. See the repository's
 [conversation storage guide](../../docs/agent-conversation-storage.md) for APIs, retention,
 eve's existing storage, and Telegram's delivery limits.
 
-### Exact chat posting protocol (prepared in agent SDK 0.6.0)
+### Exact chat posting protocol
 
 An authenticated `tools/list` advertises `_meta: { "segmentstream/chat-post": 1 }` on
 `chat_post_message`. Without this marker,
@@ -525,12 +527,12 @@ missing/incomplete preview metadata is denied. The versioned connection has its
 
 The runtime reads `me` for the server-derived `attribution`, and `chat_list({ chat })` for exactly
 one eligible destination: `{ items: [{ id, title, provider, external_id }], next_cursor: null }`.
-Provider is currently `telegram`. The final plain text is exactly `attribution + ": " + text`;
+Provider is currently `telegram`. The final plain text is `text + separator + attribution`, with a blank line as the neutral separator;
 `reply_to` is optional. A preview digest is SHA-256 of the JSON array of chat ID, provider,
 external ID, title, attribution, text, final text and nullable reply target, in that order.
 The target/attribution are resolved again immediately before executing the frozen call.
 
-Eve supplies the model-hidden `_segmentstream` argument on **all** calls of a negotiated connection.
+The SDK constructs model-hidden `_segmentstream` metadata for approved runtime posts.
 It contains `version: 1`, `session_id` and `call_id`. A consumed, unexpired chat approval additionally
 supplies `operation_id`, source provider/chat/topic coordinates and `expected: { chat_id, digest }`.
 The operation ID is `hq:` plus SHA-256 of the JSON array `[session_id, call_id]`; it stays stable
@@ -538,7 +540,8 @@ on replay and changes for a revision. The model cannot provide an idempotency ke
 The ontology must authenticate runtime provenance, consume/remove the envelope before strict input
 validation for ordinary tools, derive the posting key from the operation, and recompute attribution.
 External OAuth/service callers still supply their own `idempotency_key` and cannot use this envelope.
-These server changes belong to the later ontology stage; do not advertise the marker prematurely.
+The coordinated ontology SDK implements this protocol; deploy the compatible ontology before
+using agent exact posting.
 
 Source previews, accepted decisions and receipts use existing archive events with operation-linked
 `toolCallId`/event IDs. A cancelled Edit carries its pending revision question in the authoritative
@@ -546,10 +549,12 @@ Eve resolution, so member/topic routing survives a cold start. No second provide
 
 ## Release and migration
 
-The tested release uses agent SDK 0.6.4, Eve 0.76.3 and ontology SDK 0.28.3.
-Deploy the agent first, then backend archive migration 0033/API, then the ontology
-with its declared Telegram provider mapping and explicit `agent_chat:post_message`
-grant. Older ontologies keep ordinary tools working without the extra envelope.
+The coordinated release uses Agent SDK 0.13.0, Eve 0.76.3, Ontology SDK 0.49.0 and App SDK 0.24.1.
+The compatible Cloud archive/API must be deployed first; migrations run only through its CI/CD gate.
+Publish the ontology SDK before the agent SDK. Upgrade the workspace ontology before its agent,
+with the declared Telegram provider mapping and explicit `agent_chat:post_message` grant.
+Supply the required workspace presentation before upgrading the agent to 0.13.x.
+Older ontologies keep ordinary tools working without the extra envelope.
 An older archive returning only `{stored:true}` cannot authorize a send.
 
 Rollback
@@ -615,7 +620,7 @@ can redeliver the same source; the hook and attachment reservation must preserve
 idempotent source membership, storage results and the single acknowledgement.
 Such a failure must not become an HTTP success with no queued work.
 
-### Legacy held approvals
+### Deferred approvals and legacy recovery
 
 Deferred mode supplies four eager tools: `segmentstream__ontology_discover`,
 `segmentstream__ontology_describe`, `segmentstream__ontology_inspect` and `segmentstream__ontology_call`. Registration
@@ -636,11 +641,13 @@ actionable explanation. Reply delivery carries the owning turn's reply anchor
 explicitly after restore. Omitting the version preserves existing closed lifecycle
 data schemas; workspaces opt in only after their hook accepts the additional fields.
 
-Explicit `confirmations.mode: "held"` overrides the deferred default. Switching a package version
-does not migrate already-running held turns. In deferred mode the Telegram adapter reads the owning session's
+`confirmations.mode: "held"` is rejected. Already-running held turns still need recovery.
+The Telegram adapter reads the owning session's
 recorded approval inputs and requests cancellation of that exact turn before admitting a new
 addressed message. It never approves the old call or reuses the old member's authorization.
 Cancellation failure requests webhook replay; terminal/resolved approvals are left alone.
 Deferred mode retains its ten-minute database deadline and minute expiry sweep. Runtime health
 reports the effective confirmation mode and attachment-lifecycle presence behind its existing
 runtime authentication; source pins and public health alone are not settings-adoption proof.
+
+Telegram 0.13.0 requires workspace-authored pairing and confirmation text. See [workspace Telegram text](../../docs/agent.md#workspace-telegram-text) for keys, limits, neutral fallbacks and unsupported Eve buttons.

package/dist/_chunks/{build-metadata-CLprTpsn.mjs → build-metadata-BLeBanNg.mjs}

@@ -4,7 +4,7 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
-var version = "0.12.2";
+var version = "0.13.0";
 function agentBuild(environment = process.env) {
 	return {
 		agent: version,

package/dist/_chunks/{inbound-request-BrWspFw5.mjs → inbound-request-BXhiIph-.mjs}

@@ -4,15 +4,16 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
+import { telegramText } from "../extension/lib/telegram/texts.mjs";
 import { isTechnicalText } from "../extension/lib/customer-text-safety.mjs";
 import { redactDiagnostic } from "../extension/lib/diagnostics.mjs";
 import { isConfirmationText } from "../extension/lib/telegram/confirmation-text.mjs";
 import { chatPostCardLinks, isExactChatPostCard } from "../extension/lib/telegram/chat-post-card.mjs";
 import { plainTelegramText, splitTelegramText, telegramMarkdown } from "../extension/lib/telegram/format.mjs";
 import { inTelegramSendQueue } from "../extension/lib/telegram/send-queue.mjs";
-import { telegramPreviewOptions, telegramTextLinks } from "@segmentstream-cloud/ontology/telegram";
 import { randomBytes, randomUUID } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { telegramPreviewOptions, telegramTextLinks } from "@segmentstream-cloud/ontology/telegram";
 const deliveryLocale = new AsyncLocalStorage();
 function withDeliveryLocale(locale, run, threadId, replyTo, chatId) {
 	return deliveryLocale.run({
@@ -28,15 +29,16 @@ function currentLocale() {
 function currentThreadId() {
 	return deliveryLocale.getStore()?.threadId ?? currentInboundRequest()?.threadId;
 }
-function customerCopy() {
+function customerCopy(locale = currentLocale()) {
 	return {
-		failed: "⚠️",
-		recovery: "⚠️",
-		attachment: "⚠️",
-		authorization: "⚠️",
-		response: "⚠️",
-		connected: "✅",
-		disconnected: "❌"
+		failed: telegramText("notice", "failed", locale),
+		recovery: telegramText("notice", "recovery", locale),
+		attachment: telegramText("notice", "attachment", locale),
+		authorization: telegramText("notice", "authorization", locale),
+		response: telegramText("notice", "response", locale),
+		connected: telegramText("notice", "connected", locale),
+		disconnected: telegramText("notice", "disconnected", locale),
+		cancelled: telegramText("notice", "cancelled", locale)
 	};
 }
 function redactCredentials(value) {
@@ -46,7 +48,7 @@ function redactCredentials(value) {
 	return value;
 }
 function reportTelegramError(operation, error, metadata = {}, secrets = new Set()) {
-	const errorId = randomBytes(4).toString("hex").toUpperCase();
+	const errorId = randomBytes(4).toString("hex");
 	const credentials = new Set([...secrets, ...[process.env.AI_GATEWAY_API_KEY, process.env.VERCEL_OIDC_TOKEN].filter((value) => value !== void 0)]);
 	console.error("[segmentstream] Telegram delivery diagnostic", {
 		...metadata,
@@ -57,8 +59,8 @@ function reportTelegramError(operation, error, metadata = {}, secrets = new Set(
 	return errorId;
 }
 function failureText(errorId, kind = "failed", _locale = currentLocale()) {
-	if (kind === "cancelled") return `⏹ ${errorId}`;
-	return `${customerCopy()[kind]} ${errorId}`;
+	const text = customerCopy(_locale)[kind];
+	return text === void 0 ? errorId : `${text} ${errorId}`;
 }
 function customerText(text, locale = currentLocale()) {
 	if (!isTechnicalText(text)) return text;
@@ -118,6 +120,7 @@ function safeTelegramFetch(fetchImpl, scope = "telegram", previews = {}) {
 		"sendMessage",
 		"editMessageText",
 		"editMessageCaption",
+		"editMessageReplyMarkup",
 		"answerCallbackQuery",
 		"sendPhoto",
 		"sendDocument",
@@ -160,14 +163,13 @@ function safeTelegramFetch(fetchImpl, scope = "telegram", previews = {}) {
 		const markup = body.reply_markup;
 		if (Array.isArray(markup?.inline_keyboard)) {
 			if ((textBlocked || typeof body.text === "string" && body.text.length > 4096) && markup.inline_keyboard.some((row) => row.some((button) => typeof button.callback_data === "string" && button.callback_data.startsWith("ss-confirm:")))) throw new Error("Approval buttons require the complete, safe confirmation text.");
-			markup.inline_keyboard = markup.inline_keyboard.map((row) => row.map((button) => {
-				if (typeof button.text !== "string" || !isTechnicalText(button.text)) return button;
+			const rows = markup.inline_keyboard.map((row) => row.filter((button) => {
+				if (typeof button.text !== "string" || !isTechnicalText(button.text)) return true;
 				reportTelegramError("technical_button_label_blocked", { text: button.text });
-				return {
-					...button,
-					text: "➡️"
-				};
-			}));
+				return false;
+			})).filter((row) => row.length > 0);
+			if (rows.length === 0 && markup.inline_keyboard.length > 0) delete body.reply_markup;
+			else markup.inline_keyboard = rows;
 		}
 		const send = async () => {
 			const parts = url.endsWith("/sendMessage") && typeof body.text === "string" && !isExactChatPostCard(body.text) ? splitTelegramText({

package/dist/extension/_manifest.json

@@ -8,7 +8,6 @@
     "dynamicTool": 79,
     "channel": 58,
     "schedule": 31,
-    "connection": 46,
     "hook": 44,
     "instructions": 2,
     "dynamicInstructions": 37,

package/dist/extension/config.d.ts

@@ -1,5 +1,6 @@
 import { type GroupPolicyInput } from "@segmentstream-cloud/ontology/groups";
 import { type GroupPolicy } from "./lib/group-routing/policy.js";
+import { type TelegramTexts } from "./lib/telegram/texts.js";
 import type { AttachmentLifecycle } from "./lib/telegram/lifecycle.js";
 import { type TelegramLinkPreviews } from "@segmentstream-cloud/ontology/telegram";
 export declare const TELEGRAM_POLICIES: readonly ["mention", "smart"];
@@ -40,12 +41,13 @@ export interface FirstContactSettings {
     readonly version: string;
     readonly notice: LocalizedText;
 }
-export declare const ADMISSION_REPLY_KEYS: readonly ["limited", "perSenderLimited", "workspaceLimited", "registrationsLimited", "groupPairingRequired", "refused"];
+export declare const ADMISSION_REPLY_KEYS: readonly ["pairingRequired", "pairingButton", "groupPairingButton", "limited", "perSenderLimited", "workspaceLimited", "registrationsLimited", "groupPairingRequired", "refused"];
 export type AdmissionReplies = Partial<Record<(typeof ADMISSION_REPLY_KEYS)[number], LocalizedText>>;
 export interface AdmissionSettings {
     readonly firstContact: FirstContactSettings | null;
     readonly limits: AdmissionLimits;
     readonly replies: AdmissionReplies;
+    readonly texts?: TelegramTexts;
 }
 /**
  * `agent/segmentstream.json` as authored. A JSON import widens string literals to `string` and
@@ -54,6 +56,7 @@ export interface AdmissionSettings {
  */
 export interface SegmentStreamAgentConfigInput {
     readonly groups?: GroupPolicyInput;
+    readonly texts?: TelegramTexts;
     readonly firstContact?: FirstContactSettings;
     readonly limits?: AdmissionLimitsInput;
     readonly replies?: AdmissionReplies;
@@ -72,6 +75,9 @@ export interface SegmentStreamAgentConfigInput {
             readonly linkPreviews?: string;
             /** Additional exact HTTP(S) origins belonging to this workspace. */
             readonly additionalOwnOrigins?: readonly string[];
+            readonly menuButton?: {
+                readonly text: LocalizedText;
+            };
             readonly attachmentLifecycle?: Omit<AttachmentLifecycle, "contextVersion"> & {
                 readonly contextVersion?: number;
             };
@@ -102,7 +108,7 @@ export interface SegmentStreamAgentConfigInput {
         readonly connection?: boolean;
     };
     readonly confirmations?: {
-        /** `deferred` (default) returns immediately; `held` uses eve approval. */
+        /** `deferred` (default) returns immediately. Eve button approvals are unsupported. */
         readonly mode?: string;
     };
     readonly sessions?: {
@@ -133,6 +139,9 @@ export interface TelegramSettings {
     readonly linkPreviews?: TelegramLinkPreviews;
     readonly additionalOwnOrigins?: readonly string[];
     readonly attachmentLifecycle?: AttachmentLifecycle;
+    readonly menuButton?: {
+        readonly text: LocalizedText;
+    };
 }
 /** The chat models `segmentstream.model()` chooses between, as AI Gateway model ids. */
 export interface ChatModelChoice {
@@ -175,7 +184,7 @@ export interface SegmentStreamAgentConfig extends AdmissionSettings {
         readonly connection: boolean;
     };
     readonly confirmations: {
-        readonly mode: "deferred" | "held";
+        readonly mode: "deferred";
     };
     readonly sessions: SessionSettings;
 }
@@ -196,8 +205,12 @@ export declare class SegmentStreamAgentConfigError extends Error {
     readonly name = "SegmentStreamAgentConfigError";
     constructor(issues: ReadonlyArray<ConfigIssue>);
 }
+/** Exact historical pins retain the pre-0.13 presentation contract at the archive boundary. */
+export declare function isLegacyAgentArchive(version: string | undefined): boolean;
 /** Validates the authored configuration and applies the defaults. */
-export declare function validateConfig(input: unknown): Validation;
+export declare function validateConfig(input: unknown, options?: {
+    readonly archiveSdkVersion?: string;
+}): Validation;
 /**
  * The Standard Schema eve validates the mount with. `types` exists only for type inference, as the
  * Standard Schema specification allows.
@@ -206,7 +219,7 @@ export declare const configSchema: {
     readonly "~standard": {
         readonly version: 1;
         readonly vendor: "segmentstream";
-        readonly validate: typeof validateConfig;
+        readonly validate: (input: unknown) => Validation;
         readonly types: {
             readonly input: SegmentStreamAgentConfigInput;
             readonly output: SegmentStreamAgentConfig;

package/dist/extension/config.mjs

@@ -5,6 +5,9 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { effectiveGroupPolicy, groupPolicy } from "./lib/group-routing/policy.mjs";
+import { localizedText as localizedText$1 } from "./lib/admission.mjs";
+import { TELEGRAM_TEXT_KEYS } from "./lib/telegram/texts.mjs";
+import { isTechnicalText } from "./lib/customer-text-safety.mjs";
 import { readFileSync, realpathSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { expandGroupFiles, groupPolicyIssues } from "@segmentstream-cloud/ontology/groups";
@@ -24,6 +27,9 @@ const DEFAULT_ADMISSION_LIMITS = {
 	workspaceTurnsPerDay: 3e3
 };
 const ADMISSION_REPLY_KEYS = [
+	"pairingRequired",
+	"pairingButton",
+	"groupPairingButton",
 	"limited",
 	"perSenderLimited",
 	"workspaceLimited",
@@ -72,7 +78,8 @@ function telegramSettings(value, issues) {
 			"groups",
 			"linkPreviews",
 			"additionalOwnOrigins",
-			"attachmentLifecycle"
+			"attachmentLifecycle",
+			"menuButton"
 		],
 		issues
 	});
@@ -115,6 +122,17 @@ function telegramSettings(value, issues) {
 		message: "must be an array of HTTP(S) origins without paths, credentials, queries or fragments",
 		path: [...path, "additionalOwnOrigins"]
 	});
+	const menuButton = section({
+		value: telegram.menuButton,
+		path: [...path, "menuButton"],
+		allowed: ["text"],
+		issues
+	});
+	const menuText = menuButton === void 0 ? void 0 : localizedText(menuButton.text, [
+		...path,
+		"menuButton",
+		"text"
+	], issues, 64);
 	const lifecycle = section({
 		value: telegram.attachmentLifecycle,
 		path: [...path, "attachmentLifecycle"],
@@ -143,6 +161,7 @@ function telegramSettings(value, issues) {
 		...signalSettings === void 0 ? {} : { groups: signalSettings },
 		linkPreviews,
 		additionalOwnOrigins,
+		...menuText === void 0 ? {} : { menuButton: { text: menuText } },
 		...lifecycle === void 0 ? {} : { attachmentLifecycle: {
 			entity: String(lifecycle.entity),
 			action: String(lifecycle.action),
@@ -265,7 +284,7 @@ function sessionSettings(value, issues) {
 		idleResetHours: typeof idleResetHours === "number" && Number.isFinite(idleResetHours) && idleResetHours > 0 ? idleResetHours : false
 	};
 }
-function localizedText(value, path, issues) {
+function localizedText(value, path, issues, maximum = 4e3, safe = true) {
 	if (!isRecord(value) || Object.keys(value).length === 0) {
 		issues.push({
 			message: "must be a non-empty locale-to-text object",
@@ -282,14 +301,14 @@ function localizedText(value, path, issues) {
 				path: [...path, locale]
 			});
 		}
-		if (typeof text !== "string" || text.trim() === "" || text.length > 4e3) issues.push({
-			message: "must be non-empty text of at most 4000 characters",
+		if (typeof text !== "string" || text.trim() === "" || text.length > maximum || safe && typeof text === "string" && isTechnicalText(text)) issues.push({
+			message: `must be ${safe ? "safe " : ""}non-empty text of at most ${maximum} characters`,
 			path: [...path, locale]
 		});
 	}
 	return value;
 }
-function firstContactSettings(value, issues) {
+function firstContactSettings(value, issues, safe = true) {
 	const path = ["firstContact"];
 	const settings = section({
 		value,
@@ -303,7 +322,7 @@ function firstContactSettings(value, issues) {
 		message: "must be non-empty text of at most 200 characters without surrounding whitespace",
 		path: [...path, "version"]
 	});
-	const notice = localizedText(settings.notice, [...path, "notice"], issues);
+	const notice = localizedText(settings.notice, [...path, "notice"], issues, 4e3, safe);
 	return {
 		version: typeof version === "string" ? version : "",
 		notice
@@ -351,7 +370,7 @@ function admissionLimits(value, issues) {
 		workspaceTurnsPerDay: limit(limits?.workspaceTurnsPerDay, DEFAULT_ADMISSION_LIMITS.workspaceTurnsPerDay, [...path, "workspaceTurnsPerDay"])
 	};
 }
-function admissionReplies(value, issues) {
+function admissionReplies(value, issues, safe = true) {
 	const replies = section({
 		value,
 		path: ["replies"],
@@ -359,10 +378,90 @@ function admissionReplies(value, issues) {
 		issues
 	});
 	const configured = {};
-	for (const key of ADMISSION_REPLY_KEYS) if (replies?.[key] !== void 0) configured[key] = localizedText(replies[key], ["replies", key], issues);
+	for (const key of ADMISSION_REPLY_KEYS) if (replies?.[key] !== void 0) configured[key] = localizedText(replies[key], ["replies", key], issues, safe && key.endsWith("Button") ? 24 : 4e3, safe);
 	return configured;
 }
-function validateConfig(input) {
+function telegramTexts(value, issues) {
+	const root = section({
+		value,
+		path: ["texts"],
+		allowed: Object.keys(TELEGRAM_TEXT_KEYS),
+		issues
+	});
+	const output = {};
+	for (const [group, keys] of Object.entries(TELEGRAM_TEXT_KEYS)) {
+		const sectionValue = section({
+			value: root?.[group],
+			path: ["texts", group],
+			allowed: keys,
+			issues
+		});
+		if (sectionValue === void 0) continue;
+		output[group] = {};
+		for (const key of keys) if (sectionValue[key] !== void 0) {
+			const maximum = group === "confirmation" ? key === "question" ? 300 : 24 : group === "callback" ? 200 : group === "authorization" && key === "button" ? 24 : 4e3;
+			output[group][key] = localizedText(sectionValue[key], [
+				"texts",
+				group,
+				key
+			], issues, maximum);
+		}
+	}
+	const confirmation = output.confirmation;
+	if (confirmation?.confirm !== void 0 && confirmation.cancel !== void 0) {
+		const locales = new Set([
+			"en",
+			...Object.keys(confirmation.confirm),
+			...Object.keys(confirmation.cancel)
+		]);
+		for (const locale of locales) {
+			const confirm = localizedText$1(confirmation.confirm, locale);
+			const cancel = localizedText$1(confirmation.cancel, locale);
+			if (typeof confirm === "string" && typeof cancel === "string" && confirm.trim() === cancel.trim()) issues.push({
+				message: "confirm and cancel must have distinct effective localized labels",
+				path: [
+					"texts",
+					"confirmation",
+					"cancel",
+					locale
+				]
+			});
+		}
+	}
+	const authorization = output.authorization;
+	if (authorization?.url !== void 0) for (const [locale, value] of Object.entries(authorization.url)) try {
+		const url = new URL(value);
+		if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) throw new Error("Invalid authorization URL");
+	} catch {
+		issues.push({
+			message: "must be an HTTP(S) URL without credentials",
+			path: [
+				"texts",
+				"authorization",
+				"url",
+				locale
+			]
+		});
+	}
+	if ((authorization?.url !== void 0 || authorization?.button !== void 0) && authorization?.prompt === void 0) issues.push({
+		message: "is required when an authorization button is configured",
+		path: [
+			"texts",
+			"authorization",
+			"prompt"
+		]
+	});
+	if (authorization?.url === void 0 !== (authorization?.button === void 0)) issues.push({
+		message: "url and button must be supplied together",
+		path: ["texts", "authorization"]
+	});
+	return output;
+}
+function isLegacyAgentArchive(version) {
+	return /^0\.(?:[0-9]|1[0-2])\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version ?? "");
+}
+function validateConfig(input, options = {}) {
+	const legacyArchive = isLegacyAgentArchive(options.archiveSdkVersion);
 	const issues = [];
 	const root = section({
 		value: input ?? {},
@@ -376,7 +475,8 @@ function validateConfig(input) {
 			"confirmations",
 			"firstContact",
 			"limits",
-			"replies"
+			"replies",
+			"texts"
 		],
 		issues
 	});
@@ -410,8 +510,8 @@ function validateConfig(input) {
 		allowed: ["mode"],
 		issues
 	})?.mode ?? "deferred";
-	if (mode !== "deferred" && mode !== "held") issues.push({
-		message: "must be \"deferred\" or \"held\"",
+	if (mode !== "deferred" && !(legacyArchive && mode === "held")) issues.push({
+		message: "must be \"deferred\"; Telegram Eve approval buttons are unsupported",
 		path: ["confirmations", "mode"]
 	});
 	const telegram = telegramSettings(channels?.telegram, issues);
@@ -502,9 +602,28 @@ function validateConfig(input) {
 	});
 	const connection = ontology?.connection ?? true;
 	const sessions = sessionSettings(root?.sessions, issues);
-	const firstContact = firstContactSettings(root?.firstContact, issues);
+	const firstContact = firstContactSettings(root?.firstContact, issues, !legacyArchive);
 	const limits = admissionLimits(root?.limits, issues);
-	const replies = admissionReplies(root?.replies, issues);
+	const replies = admissionReplies(root?.replies, issues, !legacyArchive);
+	const texts = telegramTexts(root?.texts, issues);
+	if (!legacyArchive && replies.groupPairingButton !== void 0 && replies.groupPairingRequired === void 0) issues.push({
+		message: "is required when groupPairingButton is configured",
+		path: ["replies", "groupPairingRequired"]
+	});
+	if (telegram !== null && !legacyArchive) {
+		for (const key of ["pairingRequired", "pairingButton"]) if (replies[key] === void 0) issues.push({
+			message: "is required for Telegram",
+			path: ["replies", key]
+		});
+		for (const key of TELEGRAM_TEXT_KEYS.confirmation) if (texts.confirmation?.[key] === void 0) issues.push({
+			message: "is required for Telegram confirmations",
+			path: [
+				"texts",
+				"confirmation",
+				key
+			]
+		});
+	}
 	if (typeof connection !== "boolean") issues.push({
 		message: "must be true or false",
 		path: ["ontology", "connection"]
@@ -524,17 +643,18 @@ function validateConfig(input) {
 			attachments
 		},
 		ontology: { connection: connection === true },
-		confirmations: { mode: mode === "held" ? "held" : "deferred" },
+		confirmations: { mode: "deferred" },
 		sessions,
 		firstContact,
 		limits,
-		replies
+		replies,
+		texts
 	} };
 }
 const configSchema = { "~standard": {
 	version: 1,
 	vendor: "segmentstream",
-	validate: validateConfig,
+	validate: (input) => validateConfig(input),
 	types: void 0
 } };
 function manifestOf(config) {
@@ -542,4 +662,4 @@ function manifestOf(config) {
 	if (validation.issues !== void 0) throw new SegmentStreamAgentConfigError(validation.issues);
 	return validation.value;
 }
-export { ADMISSION_REPLY_KEYS, DEFAULT_ADMISSION_LIMITS, DEFAULT_ATTACHMENTS_MODEL, DEFAULT_DECISION_MODEL, DEFAULT_IMAGE_DESCRIPTION_MODEL, DEFAULT_STT_MODEL, SESSION_SCOPES, SegmentStreamAgentConfigError, TELEGRAM_POLICIES, configSchema, manifestOf, validateConfig };
+export { ADMISSION_REPLY_KEYS, DEFAULT_ADMISSION_LIMITS, DEFAULT_ATTACHMENTS_MODEL, DEFAULT_DECISION_MODEL, DEFAULT_IMAGE_DESCRIPTION_MODEL, DEFAULT_STT_MODEL, SESSION_SCOPES, SegmentStreamAgentConfigError, TELEGRAM_POLICIES, configSchema, isLegacyAgentArchive, manifestOf, validateConfig };

package/dist/extension/extension.d.ts

@@ -4,7 +4,12 @@ export declare const segmentstream: import("eve/extension").ExtensionHandle<{
     readonly "~standard": {
         readonly version: 1;
         readonly vendor: "segmentstream";
-        readonly validate: typeof import("./config.js").validateConfig;
+        readonly validate: (input: unknown) => {
+            readonly value: import("./config.js").SegmentStreamAgentConfig;
+            readonly issues?: undefined;
+        } | {
+            readonly issues: ReadonlyArray<import("./config.js").ConfigIssue>;
+        };
         readonly types: {
             readonly input: import("./config.js").SegmentStreamAgentConfigInput;
             readonly output: import("./config.js").SegmentStreamAgentConfig;
@@ -25,3 +30,4 @@ export { archivedRoutingMessages } from "./lib/group-routing/routing-context.js"
 export { replayRouterPayload } from "./lib/group-routing/replay.js";
 export { conversationState as groupConversationState, conversationAddressing as groupConversationAddressing, type ConversationAnalysis, type ConversationPath, } from "./lib/group-routing/conversation.js";
 export { routingBurst, debounceBurst } from "./lib/group-routing/burst.js";
+export type { TelegramTexts } from "./lib/telegram/texts.js";

package/dist/extension/hooks/authorization.d.ts

@@ -0,0 +1,3 @@
+/** Channel delivery reports the reference; the public hook owns cancellation of the running turn. */
+declare const _default: import("eve/hooks").HookDefinition<"authorization.required">;
+export default _default;

package/dist/extension/hooks/authorization.mjs

@@ -0,0 +1,16 @@
+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 { localizedText } from "../lib/admission.mjs";
+import "../lib/telegram/principal.mjs";
+import segmentstream from "../extension.mjs";
+import { confirmationLocale } from "../lib/telegram/confirmation-text.mjs";
+import { defineHook } from "eve/hooks";
+var authorization_default = defineHook({ events: { "authorization.required": (event, context) => {
+	const principal = context.session.auth.current;
+	if (principal?.authenticator === "segmentstream-telegram" && event.data.candidateId === void 0 && localizedText(segmentstream.config.texts?.authorization?.prompt, confirmationLocale(principal)) === void 0) context.cancel();
+} } });
+export { authorization_default as default };