@segmentstream/agent 0.7.3 → 0.8.0

package/README.md

@@ -82,7 +82,7 @@ Both entry points export the same handle: `@segmentstream/agent` and
 | Field                                    | Default                        | Meaning                                                                                                                                                            |
 | ---------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `channels.telegram.connection`           | none                           | The Connect key whose credential is the bot token. Without `channels.telegram`, no Telegram.                                                                       |
-| `channels.telegram.policy`               | `"smart"`                      | Classifies unaddressed group messages and captionless uploads; legacy `mention` is an alias for `smart`; tags are optional                                         |
+| `channels.telegram.policy`               | `"smart"`                      | Classifies unaddressed group messages and captionless uploads; `mention` observes unaddressed messages without decoding or inference                               |
 | `channels.telegram.linkPreviews`         | `external`                     | Suppress own-workspace previews and preview the first external link; opt into `all` for native previews or `none` to disable them. Caller options take precedence. |
 | `channels.telegram.additionalOwnOrigins` | `[]`                           | Additional exact HTTP(S) workspace origins, including local ports; no paths or credentials.                                                                        |
 | `models.stt`                             | `"spacexai/grok-stt"`          | The AI Gateway transcription model for voice messages; `false` leaves them untranscribed                                                                           |
@@ -94,6 +94,99 @@ An unknown field or an invalid value fails the mount with `SegmentStreamAgentCon
 each path. `manifestOf(config)` returns the normalized configuration, defaults applied, for the
 platform's deployment manifest.
 
+## Channel admission and first contact
+
+The platform and SDK provide admission, identity resolution, onboarding execution, notice tracking
+and durable limits. Workspace apps own channel policy, member grants, onboarding actions, notice
+content and lower limit values. No channel defaults to open, and no notice or limit reply text
+ships as a default. Existing invited-channel pairing and refusal replies remain unchanged.
+
+Admission belongs in the ontology's `signIn.channels`; each unlisted provider stays invited,
+independently of email `signIn.policy`. Opening a channel is an explicit workspace opt-in.
+For an intentionally open provider, declare safe named `member.permissions`. Wildcards and
+generated create/update/delete grants are rejected. Shared named reads need review; move staff
+reads into a named role. Actions handling a member's own records enforce ownership with
+`principal.id`. Groups never register users. Closing a channel stops new registrations;
+block or deactivate an existing member to stop their access.
+
+Configure app-owned text and lower limits in `agent/segmentstream.json`. These placeholders
+represent text authored by the workspace, not SDK defaults:
+
+```json
+{
+  "firstContact": {
+    "version": "1",
+    "notice": {
+      "en": "<workspace-authored first-contact notice>",
+      "ru": "<workspace-authored translated notice>"
+    }
+  },
+  "limits": {
+    "perSender": { "turnsPerMinute": 4, "turnsPerDay": 40 },
+    "newUsersPerHour": 20,
+    "workspaceTurnsPerDay": 2000
+  },
+  "replies": {
+    "perSenderLimited": { "en": "<workspace-authored sender limit reply>" },
+    "workspaceLimited": { "en": "<workspace-authored workspace limit reply>" },
+    "registrationsLimited": { "en": "<workspace-authored registration limit reply>" }
+  }
+}
+```
+
+All three sections are optional. If present, `firstContact` requires a nonblank version of at most
+200 characters, without surrounding whitespace, and a nonempty locale-to-text `notice` map.
+Text values must be nonblank and at most 4000 characters; locale keys must be valid language tags.
+Unknown settings, including the superseded `publicUsers` field, fail validation.
+The sender's language code chooses the exact locale, then its base language, then `en`,
+then the first entry. The same selection applies to configured replies. `replies.limited` is an
+optional fallback for any missing scope-specific limit reply. Without either reply, limits silently
+stop processing. `groupPairingRequired` and `refused` may override existing pairing/refusal copy.
+
+Omitted limit fields use platform ceilings: 6 turns/minute and 80/day per sender, 30 new users/hour,
+and 3000 workspace turns/day. Overrides must be positive integers at or below each ceiling.
+The trusted runtime submits these effective limits; the ontology clamps and persists them for other
+admission paths. Only self-registered users with exactly the member role consume sender/workspace
+turn quotas, keyed by user id across identities. Paired-only users and holders of named roles
+remain exempt. Every registration shares the hourly new-user cap. These settings grant no access.
+
+Admission runs after cheap edit/service gates, before decoding, then before jev and chat.
+Private messages with content and directly addressed group messages resolve with `turn: true`.
+Other group messages first resolve with `turn: false`, including replies to the bot that address
+another recipient. Mention-policy and other-recipient messages observe without counting,
+downloading or decoding. A recipient-only reply to a recent pending question remains eligible
+as answer data. Empty events remain uncounted even with a pending question.
+Eligible senders obtain counted admission before transcription, attachment work, smart-routing
+inference or pending-answer dispatch. Smart decisions
+consume a turn even if they choose observation, and reuse it if they reply. Each message requests
+counted admission at most once. No-op edits never resolve; caption-only edits reuse decoded
+evidence without downloading the same attachments again. Deferred-card presses use GET lookup
+and act-as authorization, never resolve or quotas: their initiating turn was already counted.
+Limited private inbound events and replies retain the member's archive grant through an uncounted
+binding lookup before the first persistence.
+
+Resolver statuses are `existing`, `created`, `pairing_required`, `refused` (inactive/blocked)
+and `limited`. A limit reply requires the server's `notify` flag and an addressed message or
+chosen reply. Empty events get no turn or pairing reply. A configured due notice is sent only on
+a private eligible turn, before processing; resolve carries its version and selected-text SHA-256,
+and acknowledgement records the same version/hash after delivery. Version or selected-text changes
+request delivery again. Failures retain diagnostics and retry on the next private turn.
+Without a configured notice, the SDK sends and acknowledges nothing. Ontology check warns about
+missing notice/limits when agent config is supplied; its CLI reports when that check is skipped.
+
+An app may declare `signIn.onNewUser` as an idempotent member-runnable action. The ontology executes
+it before returning an accepted eligible resolve, retries pending failures, and never delegates it
+to the model. Handlers receive read-only `principal.identities[{provider, subject, username?, verified}]`,
+`createdVia` and `authenticatedVia`. The SDK forwards verified provider provenance with the
+member's act-as header. No identity facts contain credentials.
+
+### Release order
+
+Deploy backend-next's strict validator before publishing agent SDK 0.8.0. Upgrade the workspace
+ontology to the v2 resolver/notice contract before its agent. A resolve-route HTTP 404 falls back
+to the unchanged GET lookup and invited pairing; other failures stop admission. Older agents
+continue using GET lookup. Starter templates and pins remain unchanged in this stage.
+
 ## What the extension contributes
 
 | Name                                                               | Slot           | What it does                                                                                                                                                                    |
@@ -135,7 +228,7 @@ share a group chat's session never share a client.
   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, including edits and voice transcripts, remains context and never starts a turn or gets
+  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.
 - **Who the agent is.** A paired sender's turn runs with the principal id `telegram:<user>`
@@ -144,7 +237,7 @@ share a group chat's session never share a client.
 - **Routing.** Private chats and messages explicitly addressed to the bot retain direct admission.
   Other group messages, including captionless attachments, go through one `decide` question with
   the agent's purpose, recent conversation, open questions and confirmation state. The legacy
-  `mention` policy is an alias for `smart`; tags are optional. Attachments never force a turn.
+  `mention` policy observes unaddressed messages without paid work. Attachments never force a turn.
   Human reply edges and other recipients are untrusted context for inference. Failed decisions
   observe. Unanswered messages join the bounded backlog; answered messages remain in recent
   shared context without rejoining that backlog on retries. Decision events retain the reason,

package/dist/extension/channels/telegram.mjs

@@ -12,6 +12,7 @@ var telegram_default = segmentstreamTelegram({
 	models: () => segmentstream.config.models,
 	confirmationMode: () => segmentstream.config.confirmations.mode,
 	sessions: () => segmentstream.config.sessions,
+	admission: () => segmentstream.config,
 	decide: (options) => decide(options)
 });
 export { telegram_default as default };

package/dist/extension/config.d.ts

@@ -1,8 +1,8 @@
 import { type TelegramLinkPreviews } from "@segmentstream-cloud/ontology/telegram";
 export declare const TELEGRAM_POLICIES: readonly ["mention", "smart"];
 /**
- * Group messages use smart routing without requiring tags. `mention` remains a legacy alias
- * for stored configurations; it does not disable untagged requests or follow-ups.
+ * Smart routing classifies unaddressed group messages. Mention policy observes them
+ * without decoding or inference; direct requests and pending-question replies still run.
  */
 export type TelegramPolicy = (typeof TELEGRAM_POLICIES)[number];
 /** The speech-to-text model voice messages are transcribed with, in the AI Gateway catalog. */
@@ -12,11 +12,46 @@ export declare const DEFAULT_IMAGE_DESCRIPTION_MODEL = "google/gemini-2.5-flash-
 export declare const DEFAULT_ATTACHMENTS_MODEL = "google/gemini-2.5-flash-lite";
 /** Pinned platform routing model; independent of eve's own default. */
 export declare const DEFAULT_DECISION_MODEL = "typesafe-ai/jev-1.14.0";
+/** Platform ceilings; workspace configuration may only lower them. */
+export declare const DEFAULT_ADMISSION_LIMITS: {
+    readonly perSender: {
+        readonly turnsPerMinute: 6;
+        readonly turnsPerDay: 80;
+    };
+    readonly newUsersPerHour: 30;
+    readonly workspaceTurnsPerDay: 3000;
+};
+export interface AdmissionLimits {
+    readonly perSender: {
+        readonly turnsPerMinute: number;
+        readonly turnsPerDay: number;
+    };
+    readonly newUsersPerHour: number;
+    readonly workspaceTurnsPerDay: number;
+}
+export type AdmissionLimitsInput = Partial<Omit<AdmissionLimits, "perSender">> & {
+    readonly perSender?: Partial<AdmissionLimits["perSender"]>;
+};
+export type LocalizedText = Readonly<Record<string, string>>;
+export interface FirstContactSettings {
+    readonly version: string;
+    readonly notice: LocalizedText;
+}
+export declare const ADMISSION_REPLY_KEYS: readonly ["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;
+}
 /**
  * `agent/segmentstream.json` as authored. A JSON import widens string literals to `string` and
  * `false` to `boolean`, so the accepted types are wider than the values validation allows.
  */
 export interface SegmentStreamAgentConfigInput {
+    readonly firstContact?: FirstContactSettings;
+    readonly limits?: AdmissionLimitsInput;
+    readonly replies?: AdmissionReplies;
     readonly channels?: {
         readonly telegram?: {
             /** The Connect key whose credential is the bot token, such as `telegram`. */
@@ -104,7 +139,7 @@ export interface SessionSettings {
     readonly idleResetHours: number | false;
 }
 /** The validated configuration with defaults applied. It stays JSON-serializable. */
-export interface SegmentStreamAgentConfig {
+export interface SegmentStreamAgentConfig extends AdmissionSettings {
     readonly channels: {
         readonly telegram: TelegramSettings | null;
     };

package/dist/extension/config.mjs

@@ -11,6 +11,22 @@ const DEFAULT_STT_MODEL = "spacexai/grok-stt";
 const DEFAULT_IMAGE_DESCRIPTION_MODEL = "google/gemini-2.5-flash-lite";
 const DEFAULT_ATTACHMENTS_MODEL = DEFAULT_IMAGE_DESCRIPTION_MODEL;
 const DEFAULT_DECISION_MODEL = "typesafe-ai/jev-1.14.0";
+const DEFAULT_ADMISSION_LIMITS = {
+	perSender: {
+		turnsPerMinute: 6,
+		turnsPerDay: 80
+	},
+	newUsersPerHour: 30,
+	workspaceTurnsPerDay: 3e3
+};
+const ADMISSION_REPLY_KEYS = [
+	"limited",
+	"perSenderLimited",
+	"workspaceLimited",
+	"registrationsLimited",
+	"groupPairingRequired",
+	"refused"
+];
 const SESSION_SCOPES = ["chat", "thread"];
 var SegmentStreamAgentConfigError = class extends Error {
 	issues;
@@ -197,6 +213,103 @@ function sessionSettings(value, issues) {
 		idleResetHours: typeof idleResetHours === "number" && Number.isFinite(idleResetHours) && idleResetHours > 0 ? idleResetHours : false
 	};
 }
+function localizedText(value, path, issues) {
+	if (!isRecord(value) || Object.keys(value).length === 0) {
+		issues.push({
+			message: "must be a non-empty locale-to-text object",
+			path
+		});
+		return {};
+	}
+	for (const [locale, text] of Object.entries(value)) {
+		try {
+			if (Intl.getCanonicalLocales(locale).length !== 1) throw new RangeError("empty locale");
+		} catch {
+			issues.push({
+				message: "must be a language tag such as en or en-US",
+				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",
+			path: [...path, locale]
+		});
+	}
+	return value;
+}
+function firstContactSettings(value, issues) {
+	const path = ["firstContact"];
+	const settings = section({
+		value,
+		path,
+		allowed: ["version", "notice"],
+		issues
+	});
+	if (settings === void 0) return null;
+	const version = settings.version;
+	if (typeof version !== "string" || version.trim() === "" || version !== version.trim() || version.length > 200) issues.push({
+		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);
+	return {
+		version: typeof version === "string" ? version : "",
+		notice
+	};
+}
+function admissionLimits(value, issues) {
+	const path = ["limits"];
+	const limits = section({
+		value,
+		path,
+		allowed: Object.keys(DEFAULT_ADMISSION_LIMITS),
+		issues
+	});
+	const perSender = section({
+		value: limits?.perSender,
+		path: [...path, "perSender"],
+		allowed: Object.keys(DEFAULT_ADMISSION_LIMITS.perSender),
+		issues
+	});
+	function limit(value, ceiling, path) {
+		if (value === void 0) return ceiling;
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > ceiling) {
+			issues.push({
+				message: "must be an integer between 1 and " + ceiling,
+				path
+			});
+			return ceiling;
+		}
+		return value;
+	}
+	return {
+		perSender: {
+			turnsPerMinute: limit(perSender?.turnsPerMinute, DEFAULT_ADMISSION_LIMITS.perSender.turnsPerMinute, [
+				...path,
+				"perSender",
+				"turnsPerMinute"
+			]),
+			turnsPerDay: limit(perSender?.turnsPerDay, DEFAULT_ADMISSION_LIMITS.perSender.turnsPerDay, [
+				...path,
+				"perSender",
+				"turnsPerDay"
+			])
+		},
+		newUsersPerHour: limit(limits?.newUsersPerHour, DEFAULT_ADMISSION_LIMITS.newUsersPerHour, [...path, "newUsersPerHour"]),
+		workspaceTurnsPerDay: limit(limits?.workspaceTurnsPerDay, DEFAULT_ADMISSION_LIMITS.workspaceTurnsPerDay, [...path, "workspaceTurnsPerDay"])
+	};
+}
+function admissionReplies(value, issues) {
+	const replies = section({
+		value,
+		path: ["replies"],
+		allowed: ADMISSION_REPLY_KEYS,
+		issues
+	});
+	const configured = {};
+	for (const key of ADMISSION_REPLY_KEYS) if (replies?.[key] !== void 0) configured[key] = localizedText(replies[key], ["replies", key], issues);
+	return configured;
+}
 function validateConfig(input) {
 	const issues = [];
 	const root = section({
@@ -207,7 +320,10 @@ function validateConfig(input) {
 			"models",
 			"ontology",
 			"sessions",
-			"confirmations"
+			"confirmations",
+			"firstContact",
+			"limits",
+			"replies"
 		],
 		issues
 	});
@@ -273,6 +389,9 @@ function validateConfig(input) {
 	});
 	const connection = ontology?.connection ?? true;
 	const sessions = sessionSettings(root?.sessions, issues);
+	const firstContact = firstContactSettings(root?.firstContact, issues);
+	const limits = admissionLimits(root?.limits, issues);
+	const replies = admissionReplies(root?.replies, issues);
 	if (typeof connection !== "boolean") issues.push({
 		message: "must be true or false",
 		path: ["ontology", "connection"]
@@ -289,7 +408,10 @@ function validateConfig(input) {
 		},
 		ontology: { connection: connection === true },
 		confirmations: { mode: mode === "held" ? "held" : "deferred" },
-		sessions
+		sessions,
+		firstContact,
+		limits,
+		replies
 	} };
 }
 const configSchema = { "~standard": {
@@ -303,4 +425,4 @@ function manifestOf(config) {
 	if (validation.issues !== void 0) throw new SegmentStreamAgentConfigError(validation.issues);
 	return validation.value;
 }
-export { 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, 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 SessionScope, type SessionSettings, type TelegramPolicy, type TelegramSettings, } from "./config.js";
+export { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, DEFAULT_ADMISSION_LIMITS, SegmentStreamAgentConfigError, manifestOf, type ChatModelChoice, type AdmissionLimits, type AdmissionLimitsInput, type AdmissionSettings, type AdmissionReplies, type FirstContactSettings, type LocalizedText, 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

@@ -4,7 +4,7 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
-import { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, configSchema, manifestOf } from "./config.mjs";
+import { DEFAULT_ADMISSION_LIMITS, DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, configSchema, manifestOf } from "./config.mjs";
 import { chooseModel, model } from "./model.mjs";
 import { defineExtension } from "eve/extension";
 const extension = defineExtension({ config: configSchema });
@@ -12,4 +12,4 @@ const segmentstream = Object.assign(extension, {
 	model: (choice) => model(choice ?? (() => extension.config.models.chat)),
 	manifestOf
 });
-export { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, chooseModel, segmentstream as default, segmentstream, manifestOf, model };
+export { DEFAULT_ADMISSION_LIMITS, DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SegmentStreamAgentConfigError, chooseModel, segmentstream as default, segmentstream, manifestOf, model };

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

@@ -0,0 +1,13 @@
+import type { AdmissionSettings, LocalizedText } from "../config.js";
+import type { AgentIdentities, IdentityResolution, ResolveIdentityInput } from "./identities.js";
+/** Sender language, then English, then the first configured entry. No platform copy. */
+export declare function localizedText(texts: LocalizedText | undefined, languageCode?: string): string | undefined;
+/** Channel-independent admission and at-least-once versioned notice delivery. */
+export declare function admitMessage(input: {
+    readonly identity: ResolveIdentityInput;
+    readonly identities: AgentIdentities;
+    readonly settings: AdmissionSettings;
+    readonly languageCode?: string;
+    readonly sendNotice: (text: string) => Promise<unknown>;
+    readonly noticeFailed: (error: unknown) => void;
+}): Promise<IdentityResolution>;

package/dist/extension/lib/admission.mjs

@@ -0,0 +1,42 @@
+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 { createHash } from "node:crypto";
+function localizedText(texts, languageCode) {
+	if (texts === void 0) return;
+	const entries = Object.entries(texts);
+	const language = languageCode?.toLowerCase();
+	const exact = entries.find(([locale]) => locale.toLowerCase() === language);
+	const base = entries.find(([locale]) => locale.toLowerCase() === language?.split("-")[0]);
+	const english = entries.find(([locale]) => locale.toLowerCase() === "en");
+	return (exact ?? base ?? english ?? entries[0])?.[1];
+}
+async function admitMessage(input) {
+	const firstContact = input.settings.firstContact;
+	const notice = localizedText(firstContact?.notice, input.languageCode);
+	const sha256 = notice === void 0 ? void 0 : createHash("sha256").update(notice).digest("hex");
+	const resolved = await input.identities.resolve({
+		...input.identity,
+		limits: input.settings.limits,
+		...firstContact === null ? {} : {
+			noticeVersion: firstContact.version,
+			noticeSha256: sha256
+		}
+	});
+	if ((resolved.status === "existing" || resolved.status === "created") && resolved.noticeDue && input.identity.turn && input.identity.chat === "private" && firstContact !== null && notice !== void 0 && sha256 !== void 0) try {
+		await input.sendNotice(notice);
+		await input.identities.notice({
+			provider: input.identity.provider,
+			externalId: input.identity.externalId,
+			version: firstContact.version,
+			sha256
+		});
+	} catch (error) {
+		input.noticeFailed(error);
+	}
+	return resolved;
+}
+export { admitMessage, localizedText };

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

@@ -9,7 +9,7 @@ export declare function conversationCoordinates(context: {
 }): {
     provider: string;
     chatId: string;
-    chatType: "channel" | "group" | "private";
+    chatType: "private" | "group" | "channel";
     threadId: string | null;
     participantIds: string[];
     senderId: string | null;

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

@@ -1,3 +1,4 @@
+import type { AdmissionLimitsInput } from "../config.js";
 import type { RuntimeToken } from "./runtime-token.js";
 /**
  * The ontology service's pairing routes (`agent-design.md`, section 13, "Identity"). The agent
@@ -25,6 +26,36 @@ export type IdentityLookup = {
  | {
     readonly status: "refused";
 };
+export type IdentityResolution = (({
+    readonly status: "existing";
+} | {
+    readonly status: "created";
+}) & {
+    readonly member: PairedMember;
+    readonly provisioned: boolean;
+    readonly noticeDue: boolean;
+    readonly onNewUserPending: boolean;
+}) | {
+    readonly status: "pairing_required";
+} | {
+    readonly status: "refused";
+    readonly reason?: "blocked" | "inactive";
+} | {
+    readonly status: "limited";
+    readonly scope: "turnsPerMinute" | "turnsPerDay" | "newUsersPerHour" | "workspaceTurnsPerDay";
+    readonly retryAfterSeconds: number;
+    readonly notify: boolean;
+    readonly notificationId?: string;
+};
+export interface ResolveIdentityInput extends ChatAccount {
+    readonly chat: "private" | "group";
+    readonly turn: boolean;
+    readonly display?: string;
+    readonly username?: string;
+    readonly limits?: AdmissionLimitsInput;
+    readonly noticeVersion?: string;
+    readonly noticeSha256?: string;
+}
 /** A pairing code the member approves at `/agent/connect?code=<code>`. */
 export interface Pairing {
     readonly code: string;
@@ -44,6 +75,16 @@ export interface AgentChat {
 }
 export interface AgentIdentities {
     lookup(account: ChatAccount): Promise<IdentityLookup>;
+    /** Server-owned admission; only an older server's route 404 falls back to GET lookup. */
+    resolve(input: ResolveIdentityInput): Promise<IdentityResolution>;
+    notice(input: ChatAccount & {
+        readonly version: string;
+        readonly sha256: string;
+    }): Promise<void>;
+    completeLimitNotice(input: {
+        readonly notificationId: string;
+        readonly delivered: boolean;
+    }): Promise<void>;
     /** Issues a pairing code, or returns the account's pending one while it has time left. */
     createPairing(account: ChatAccount & {
         readonly display?: string;

package/dist/extension/lib/identities.mjs

@@ -58,6 +58,33 @@ function pairing(value) {
 		expiresAt: value.expires_at
 	};
 }
+function resolution(value) {
+	if (isRecord(value)) {
+		if ((value.status === "existing" || value.status === "created") && typeof value.provisioned === "boolean" && typeof value.notice_due === "boolean" && typeof value.on_new_user_pending === "boolean") return {
+			status: value.status,
+			member: pairedMember(value),
+			provisioned: value.provisioned,
+			noticeDue: value.notice_due,
+			onNewUserPending: value.on_new_user_pending
+		};
+		if (value.status === "pairing_required") return { status: "pairing_required" };
+		if (value.status === "refused" && (value.reason === "blocked" || value.reason === "inactive")) return {
+			status: "refused",
+			reason: value.reason
+		};
+		if (value.status === "limited" && (value.scope === "turnsPerMinute" || value.scope === "turnsPerDay" || value.scope === "newUsersPerHour" || value.scope === "workspaceTurnsPerDay") && typeof value.retry_after_seconds === "number" && Number.isInteger(value.retry_after_seconds) && value.retry_after_seconds >= 0 && typeof value.notify === "boolean") return {
+			status: "limited",
+			scope: value.scope,
+			retryAfterSeconds: value.retry_after_seconds,
+			notify: value.notify,
+			...typeof value.notification_id === "string" ? { notificationId: value.notification_id } : {}
+		};
+	}
+	throw new AgentIdentityError({
+		code: "invalid_response",
+		message: "The ontology service answered the identity resolution with an invalid body."
+	});
+}
 function nullableString(value) {
 	return value === null || typeof value === "string";
 }
@@ -138,18 +165,59 @@ function agentIdentities(input) {
 			});
 		}
 	}
+	async function lookup(account) {
+		const response = await call(`/identities/${encodeURIComponent(account.provider)}/${encodeURIComponent(account.externalId)}`, {});
+		if (response.status === 404) return { status: "unknown" };
+		if (response.status === 403) return { status: "refused" };
+		if (!response.ok) throw await safeRefusal(response, "identity lookup");
+		const member = pairedMember(await response.json());
+		pending.delete(accountKey(account));
+		return {
+			status: "paired",
+			member
+		};
+	}
 	return {
-		async lookup(account) {
-			const response = await call(`/identities/${encodeURIComponent(account.provider)}/${encodeURIComponent(account.externalId)}`, {});
-			if (response.status === 404) return { status: "unknown" };
-			if (response.status === 403) return { status: "refused" };
-			if (!response.ok) throw await safeRefusal(response, "identity lookup");
-			const member = pairedMember(await response.json());
-			pending.delete(accountKey(account));
-			return {
-				status: "paired",
-				member
-			};
+		lookup,
+		async resolve(account) {
+			const { externalId, noticeVersion, noticeSha256, ...details } = account;
+			const response = await call("/identities/resolve", { body: {
+				...details,
+				external_id: externalId,
+				...noticeVersion === void 0 ? {} : { notice_version: noticeVersion },
+				...noticeSha256 === void 0 ? {} : { notice_sha256: noticeSha256 }
+			} });
+			if (response.status === 404) {
+				const existing = await lookup(account);
+				if (existing.status === "unknown") return { status: "pairing_required" };
+				return existing.status === "paired" ? {
+					...existing,
+					status: "existing",
+					provisioned: false,
+					noticeDue: false,
+					onNewUserPending: false
+				} : existing;
+			}
+			if (!response.ok) throw await safeRefusal(response, "identity resolution");
+			const resolved = resolution(await response.json());
+			if (resolved.status === "existing" || resolved.status === "created") pending.delete(accountKey(account));
+			return resolved;
+		},
+		async completeLimitNotice(input) {
+			const response = await call("/identities/limit-notice", { body: {
+				notification_id: input.notificationId,
+				delivered: input.delivered
+			} });
+			if (!response.ok) throw await safeRefusal(response, "limit notice completion");
+		},
+		async notice(account) {
+			const response = await call("/identities/notice", { body: {
+				provider: account.provider,
+				external_id: account.externalId,
+				version: account.version,
+				sha256: account.sha256
+			} });
+			if (!response.ok) throw await safeRefusal(response, "identity notice acknowledgement");
 		},
 		async createPairing(account) {
 			const key = accountKey(account);

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

@@ -5,7 +5,7 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { appOrigin } from "./environment.mjs";
-import { memberIdOf } from "./telegram/principal.mjs";
+import { identityProviderOf, memberIdOf } from "./telegram/principal.mjs";
 import { CHAT_POST_ENVELOPE, chatPostDigest, chatPostOperationId, isChatPost } from "./chat-post-confirmation.mjs";
 import { actionApproval, confirmations } from "./confirmations.mjs";
 import { runtimeToken, tokenExpiry } from "./runtime-token.mjs";
@@ -20,7 +20,11 @@ function actAsHeaders(input) {
 	const memberId = memberIdOf(input.principal);
 	if (memberId === void 0) throw new MemberRequiredError("The ontology is reachable only for a member paired with this agent.");
 	if (memberId !== input.expectedMemberId) throw new MemberRequiredError("The ontology connection was opened for another member.");
-	return { [ACT_AS_HEADER]: memberId };
+	const provider = identityProviderOf(input.principal);
+	return {
+		[ACT_AS_HEADER]: memberId,
+		...provider === void 0 ? {} : { "X-SegmentStream-Identity-Provider": provider }
+	};
 }
 function ontologyConnection(input) {
 	const memberId = memberIdOf(input.principal);

package/dist/extension/lib/ontology-tools.d.ts

@@ -1,8 +1,10 @@
+import type { SessionAuthContext } from "eve/context";
 import type { ActionAnnotations } from "./confirmations.js";
 import { type Environment } from "./environment.js";
 import { type RuntimeToken } from "./runtime-token.js";
 /** A fresh, permission-filtered catalog. Listing tools cannot run an action's prepare step. */
 export declare function ontologyTools(options?: {
+    readonly principal?: SessionAuthContext | null;
     readonly environment?: Environment;
     readonly token?: RuntimeToken;
     readonly fetch?: typeof fetch;

package/dist/extension/lib/ontology-tools.mjs

@@ -5,12 +5,14 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { appOrigin } from "./environment.mjs";
+import { identityProviderOf, memberIdOf } from "./telegram/principal.mjs";
 import { describeConfirmation, object } from "./confirmation-description.mjs";
 import { describeChatPost, isChatPost, supportsChatPost } from "./chat-post-confirmation.mjs";
 import { redactDiagnostic } from "./diagnostics.mjs";
 import { runtimeToken } from "./runtime-token.mjs";
 function ontologyTools(options = {}) {
 	async function rpc(memberId, method, params, signal) {
+		const provider = memberIdOf(options.principal) === memberId ? identityProviderOf(options.principal) : void 0;
 		const credential = await (options.token ?? runtimeToken)();
 		const secrets = new Set([credential]);
 		try {
@@ -19,6 +21,7 @@ function ontologyTools(options = {}) {
 				headers: {
 					authorization: `Bearer ${credential}`,
 					"X-SegmentStream-Act-As": memberId,
+					...provider === void 0 ? {} : { "X-SegmentStream-Identity-Provider": provider },
 					"content-type": "application/json",
 					accept: "application/json, text/event-stream",
 					"mcp-protocol-version": "2025-11-25"

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

@@ -1,6 +1,6 @@
 import { type AttachmentDescriber } from "./attachment-description.js";
 import { type TelegramChannel } from "eve/channels/telegram";
-import type { ChatModelChoice, SessionSettings, TelegramSettings } from "../../config.js";
+import type { ChatModelChoice, AdmissionSettings, SessionSettings, TelegramSettings } from "../../config.js";
 import { type AgentAttachments } from "../attachments.js";
 import { type Environment } from "../environment.js";
 import { type Conversations } from "../conversations.js";
@@ -30,6 +30,7 @@ export interface TelegramAdapterOptions {
     };
     /** The mounted `sessions`. */
     readonly sessions: () => SessionSettings;
+    readonly admission?: () => AdmissionSettings;
     readonly confirmationMode?: () => "deferred" | "held";
     readonly decide: DecideFunction;
     readonly environment?: Environment;

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

@@ -4,7 +4,7 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
-import "../../config.mjs";
+import { manifestOf } from "../../config.mjs";
 import { appOrigin, channelsEnabled, proxyEnvironment, runtimeIdentityEnvironment, webhookSecret } from "../environment.mjs";
 import { conversationLanguage, telegramPrincipal } from "./principal.mjs";
 import { chooseModel } from "../../model.mjs";
@@ -165,6 +165,7 @@ function segmentstreamTelegram(options) {
 					dependencies: {
 						policy: settings().policy,
 						sessions: options.sessions,
+						admission: options.admission ?? (() => manifestOf({})),
 						sessionPolicy: policy,
 						sttModel: options.models().stt,
 						attachmentsModel: options.models().imageDescription ?? options.models().attachments ?? "google/gemini-2.5-flash-lite",

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

@@ -130,11 +130,15 @@ async function captureTelegramWebhook(input) {
 		attachments,
 		at: new Date(sentAt).toISOString()
 	});
-	await input.archive.append(event);
+	let persisted;
 	const capture = {
 		event,
 		message,
 		archive: input.archive,
+		persist: () => {
+			persisted ??= input.archive.append(capture.event).then(() => void 0);
+			return persisted;
+		},
 		...lookup === void 0 ? {} : { lookup }
 	};
 	const revisionId = edited === void 0 ? void 0 : `telegram:${message.chat.id}:${message.messageId}:routing:${createHash("sha256").update(JSON.stringify({
@@ -161,6 +165,7 @@ async function captureTelegramWebhook(input) {
 		...message.messageThreadId === void 0 ? {} : { messageThreadId: message.messageThreadId }
 	});
 	const automated = message.from === void 0 || message.from.isBot || message.chat.type === "channel";
+	if (automated || edited !== void 0 || message.raw.left_chat_member || message.raw.migrate_to_chat_id || message.raw.migrate_from_chat_id) await capture.persist();
 	const history = automated ? void 0 : await input.archive.context({
 		provider: "telegram",
 		chatId: message.chat.id,
@@ -200,6 +205,7 @@ async function captureTelegramWebhook(input) {
 		if (unchangedAttachments && event.attachments.length > 0) {
 			const decoded = Array.isArray(previousRouting.decoded) ? previousRouting.decoded : [];
 			const media = typeof previousRouting.media === "string" ? previousRouting.media : void 0;
+			await capture.persist();
 			const metadata = record(JSON.parse(capture.event.argsSummary ?? "{}"));
 			capture.event = {
 				...capture.event,
@@ -269,7 +275,7 @@ async function captureTelegramWebhook(input) {
 			if (latest !== void 0 && !revisionEvents.some((item) => item.eventId === `${latest.eventId}:failed`) && Date.now() - Date.parse(latest.at) < 12e4) return false;
 			const attempt = claims.length === 0 ? void 0 : Math.max(...claims.map((item) => Number(item.eventId.slice(revisionId.length).replace(":retry:", "")))) + 1;
 			const claim = {
-				...event,
+				...capture.event,
 				eventId: attempt === void 0 ? revisionId : `${revisionId}:retry:${attempt}`,
 				at: new Date(Date.now()).toISOString(),
 				kind: "decision",
@@ -289,7 +295,7 @@ async function captureTelegramWebhook(input) {
 		let accepted = false;
 		let dispatchStarted = false;
 		const claimEvent = (reason, status, suffix = "") => ({
-			...event,
+			...capture.event,
 			eventId: `${claimId}${suffix}`,
 			kind: "decision",
 			decision: "reply",
@@ -331,9 +337,10 @@ async function captureTelegramWebhook(input) {
 		}) }) : alreadyHandled ? new Request(input.request, { body: JSON.stringify({ update_id: update.update_id }) }) : void 0);
 	} catch (error) {
 		try {
+			await capture.persist();
 			await inbound?.finishClaim?.(false);
 			await input.archive.append({
-				...event,
+				...capture.event,
 				eventId: `${event.eventId}:decision`,
 				kind: "decision",
 				text: null,
@@ -350,14 +357,15 @@ async function captureTelegramWebhook(input) {
 		}
 		throw error;
 	}
+	await capture.persist();
 	await inbound?.finishClaim?.(false);
 	await input.archive.append({
-		...event,
+		...capture.event,
 		eventId: `${event.eventId}:decision`,
 		kind: "decision",
 		argsSummary: JSON.stringify({
 			...capture.diagnostics === void 0 ? {} : { decision: capture.diagnostics },
-			routing: { membership: capture.lookup === void 0 ? "unknown" : capture.lookup.status === "paired" ? "linked" : "unlinked" }
+			routing: { membership: capture.lookup === void 0 ? "unknown" : capture.lookup.status === "paired" || capture.lookup.status === "existing" || capture.lookup.status === "created" ? "linked" : "unlinked" }
 		}),
 		text: capture.note ?? (edited !== void 0 ? "Message edit recorded as context; no agent turn started." : null),
 		decision: capture.decision ?? "silent",
@@ -402,8 +410,9 @@ async function recordInboundContent(content) {
 	const inbound = currentInboundRequest();
 	const capture = inbound === void 0 ? void 0 : captures.get(inbound);
 	if (capture?.archive === void 0) return;
+	await capture.persist();
 	const metadata = record(JSON.parse(capture.event.argsSummary ?? "{}"));
-	const membership = capture.lookup === void 0 ? record(metadata.routing).membership : capture.lookup.status === "paired" ? "linked" : "unlinked";
+	const membership = capture.lookup === void 0 ? record(metadata.routing).membership : capture.lookup.status === "paired" || capture.lookup.status === "existing" || capture.lookup.status === "created" ? "linked" : "unlinked";
 	if (content.text === capture.event.text && content.media === record(metadata.routing).media && membership === record(metadata.routing).membership && JSON.stringify(content.decoded) === JSON.stringify(record(metadata.routing).decoded)) return;
 	const contentHash = createHash("sha256").update(JSON.stringify({
 		...content,
@@ -507,13 +516,40 @@ function captureTelegramFetch(fetchImpl, archive, identities) {
 function conversationIdentities(identities) {
 	return {
 		...identities,
+		resolve: async (account) => {
+			const resolved = await identities.resolve(account);
+			const inbound = currentInboundRequest();
+			const capture = inbound === void 0 ? void 0 : captures.get(inbound);
+			if (account.provider === "telegram" && capture?.message.from?.id === account.externalId) {
+				capture.lookup = resolved;
+				if (capture.event.chatType === "private" && (resolved.status === "existing" || resolved.status === "created")) capture.event = {
+					...capture.event,
+					participantIds: [resolved.member.id]
+				};
+				if (capture.event.chatType === "private" && resolved.status === "limited") {
+					const binding = await identities.lookup(account);
+					if (binding.status === "paired") capture.event = {
+						...capture.event,
+						participantIds: [binding.member.id]
+					};
+				}
+				await capture.persist();
+			}
+			return resolved;
+		},
 		lookup: async (account) => {
 			const inbound = currentInboundRequest();
 			const capture = inbound === void 0 ? void 0 : captures.get(inbound);
-			if (account.provider === "telegram" && capture?.message.from?.id === account.externalId && capture.lookup !== void 0) return capture.lookup;
-			const lookup = await identities.lookup(account);
-			if (account.provider === "telegram" && capture?.message.from?.id === account.externalId) capture.lookup = lookup;
-			return lookup;
+			if (account.provider === "telegram" && capture?.message.from?.id === account.externalId) {
+				const cached = capture.lookup;
+				if (cached?.status === "paired" || cached?.status === "refused" || cached?.status === "unknown") return cached;
+				if (cached?.status === "existing" || cached?.status === "created") return {
+					status: "paired",
+					member: cached.member
+				};
+				if (cached?.status === "pairing_required") return { status: "unknown" };
+			}
+			return identities.lookup(account);
 		}
 	};
 }

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

@@ -1,5 +1,5 @@
 import type { TelegramContext, TelegramInboundResult, TelegramMessage } from "eve/channels/telegram";
-import type { SessionSettings, TelegramPolicy } from "../../config.js";
+import type { AdmissionSettings, SessionSettings, TelegramPolicy } from "../../config.js";
 import type { AgentAttachments } from "../attachments.js";
 import type { AgentIdentities, PairedMember } from "../identities.js";
 import type { BotIdentityLookup } from "./bot.js";
@@ -38,6 +38,7 @@ import type { PdfTextExtractor } from "./pdf-text.js";
  */
 export interface InboundDependencies {
     readonly policy: TelegramPolicy;
+    readonly admission: () => AdmissionSettings;
     readonly sessions: () => SessionSettings;
     readonly sessionPolicy: SessionPolicy;
     readonly sttModel: string | false;

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

@@ -8,7 +8,7 @@ import { conversationLanguage, telegramPrincipal } from "./principal.mjs";
 import { p as reportTelegramError } from "../../../_chunks/inbound-request-BwBvXk0A.mjs";
 import { formatAddress, messageAddress, scopedAddress } from "./sessions.mjs";
 import { contentShape, messageContent } from "./content.mjs";
-import { messageAudience } from "./audience.mjs";
+import { messageAudience, otherRecipient } from "./audience.mjs";
 import { attachmentKind, messageMetadata, observedChatKey, observedContext } from "./observed.mjs";
 import { MAXIMUM_NATIVE_IMAGE_BYTES } from "./images.mjs";
 import { MAXIMUM_ROUTING_ATTACHMENT_BYTES, describeRoutingAttachment, routingAttachmentDeadline } from "./attachment-description.mjs";
@@ -19,6 +19,7 @@ import { questionAddress, questionFromHistory } from "./confirmations.mjs";
 import { routingContext } from "./routing-context.mjs";
 import { recordGateDecision, recordInboundContent, recordRouteDecision } from "./conversations.mjs";
 import { chatContext } from "./chats.mjs";
+import { admitMessage, localizedText } from "../admission.mjs";
 import { attachmentsContext, inboundAttachments, stageFiles } from "./files.mjs";
 import { voiceOf, voiceText } from "./voice.mjs";
 const UNKNOWN_PRIVATE = "🔗";
@@ -94,13 +95,39 @@ function unknownInGroup(bot) {
 }
 async function answerUnpaired(input) {
 	const { context, message, lookup, dependencies } = input;
+	if (lookup.status === "limited") {
+		if (lookup.notify) {
+			const replies = dependencies.admission().replies;
+			const configured = lookup.scope === "workspaceTurnsPerDay" ? replies.workspaceLimited : lookup.scope === "newUsersPerHour" ? replies.registrationsLimited : replies.perSenderLimited;
+			const text = localizedText(configured ?? replies.limited, message.from.languageCode);
+			if (text !== void 0) {
+				let delivered = false;
+				try {
+					await context.telegram.post(text);
+					delivered = true;
+				} finally {
+					if (lookup.notificationId !== void 0) try {
+						await dependencies.identities.completeLimitNotice({
+							notificationId: lookup.notificationId,
+							delivered
+						});
+					} catch (error) {
+						reportTelegramError("limit_notice_completion_failed", error);
+					}
+				}
+				return true;
+			}
+		}
+		return false;
+	}
 	if (lookup.status === "refused") {
-		await context.telegram.post(REFUSED);
-		return;
+		const text = localizedText(dependencies.admission().replies.refused, message.from.languageCode);
+		await context.telegram.post(text ?? REFUSED);
+		return true;
 	}
 	if (message.chat.type !== "private") {
-		await context.telegram.post(unknownInGroup(input.bot));
-		return;
+		await context.telegram.post(localizedText(dependencies.admission().replies.groupPairingRequired, message.from.languageCode) ?? unknownInGroup(input.bot));
+		return true;
 	}
 	const sender = display(message.from);
 	const pairing = await dependencies.identities.createPairing({
@@ -112,6 +139,7 @@ async function answerUnpaired(input) {
 		text: UNKNOWN_PRIVATE,
 		reply_markup: buttonTo("🔗", dependencies.connectUrl(pairing.code))
 	});
+	return true;
 }
 function isGroupChat(message) {
 	return message.chat.type === "group" || message.chat.type === "supergroup";
@@ -190,10 +218,41 @@ async function handleInboundMessage(input) {
 	const bot = await dependencies.bot(context.telegram);
 	const audience = messageAudience(sent, bot);
 	const addressed = addressingReason(sent, bot);
-	const lookup = await dependencies.identities.lookup({
+	const elsewhere = otherRecipient(audience);
+	if (input.request?.edited) {
+		if (addressed === void 0 && !input.request.attachmentsChanged && (input.request.previousText ?? "").trim().replace(/\s+/gu, " ") === audience.originalText.trim().replace(/\s+/gu, " ")) {
+			recordGateDecision("message_edit");
+			return null;
+		}
+		if (input.request.claimRevision !== void 0 && !await input.request.claimRevision()) {
+			recordGateDecision("message_revision_already_handled");
+			return null;
+		}
+	}
+	const sender = display(sent.from);
+	const hasContent = (sent.text || sent.caption).trim() !== "" || voiceOf(sent.raw) !== void 0 || sent.attachments.length > 0;
+	const identity = {
 		provider: "telegram",
-		externalId: sent.from.id
+		externalId: sent.from.id,
+		chat: sent.chat.type === "private" ? "private" : "group",
+		...sender === void 0 ? {} : { display: sender },
+		...sent.from.username === void 0 ? {} : { username: sent.from.username }
+	};
+	const resolve = (turn) => admitMessage({
+		identity: {
+			...identity,
+			turn
+		},
+		identities: dependencies.identities,
+		settings: dependencies.admission(),
+		languageCode: sent.from.languageCode,
+		sendNotice: (text) => context.telegram.post(text),
+		noticeFailed: (error) => {
+			reportTelegramError("identity_notice_failed", error, { provider: "telegram" });
+		}
 	});
+	const turn = addressed !== void 0 && hasContent && (addressed !== "reply-to-bot" || elsewhere === void 0);
+	const lookup = await resolve(turn);
 	const group = isGroupChat(sent);
 	const chat = observedChatKey({
 		chatId: sent.chat.id,
@@ -202,7 +261,7 @@ async function handleInboundMessage(input) {
 	const report = group ? dependencies.chats.seen({
 		chatId: sent.chat.id,
 		title: sent.chat.title ?? "",
-		...lookup.status === "paired" ? { memberId: lookup.member.id } : {}
+		...lookup.status === "existing" || lookup.status === "created" ? { memberId: lookup.member.id } : {}
 	}) : void 0;
 	if (report !== void 0) input.request?.waitUntil?.(report);
 	const voice = voiceOf(sent.raw);
@@ -266,37 +325,43 @@ async function handleInboundMessage(input) {
 			text = [caption, unavailable].filter(Boolean).join("\n\n");
 		}
 	};
-	if (lookup.status !== "paired") {
-		if (group) {
-			const retained = input.request?.edited ? void 0 : dependencies.observed.recent(chat).find((entry) => entry.messageId === sent.messageId);
-			if (retained === void 0) {
-				if (voice !== void 0) await transcribeVoice(true);
-				await recordInboundContent({
-					text,
-					decoded
-				});
-			}
-			dependencies.observed.add(chat, retained ?? observedMessage(sent, text || "[attachment]", void 0, notes.join("\n"), bot));
-		}
-		recordGateDecision(`identity_${lookup.status}`, !group && addressed !== void 0 ? "reply" : "silent");
-		if (addressed !== void 0 && !group) await answerUnpaired({
+	async function reject(refused, reply) {
+		const replied = hasContent && reply && (refused.status !== "limited" || refused.notify) ? await answerUnpaired({
 			context,
 			message: sent,
-			lookup,
+			lookup: refused,
 			bot,
 			dependencies
+		}) : false;
+		recordGateDecision("identity_" + refused.status, replied ? "reply" : "silent");
+	}
+	async function observeRaw() {
+		await recordInboundContent({
+			text,
+			decoded
 		});
+		if (group) dependencies.observed.add(chat, observedMessage(sent, text || "[attachment]", void 0, void 0, bot));
+	}
+	if (lookup.status !== "existing" && lookup.status !== "created") {
+		const configuredGroupPairing = lookup.status === "pairing_required" && localizedText(dependencies.admission().replies.groupPairingRequired, sent.from.languageCode) !== void 0;
+		await reject(lookup, addressed !== void 0 && (!group || lookup.status === "limited" || configuredGroupPairing));
+		await observeRaw();
 		return null;
 	}
-	if (input.request?.edited) {
-		if (addressed === void 0 && !input.request.attachmentsChanged && (input.request.previousText ?? "").trim().replace(/\s+/gu, " ") === audience.originalText.trim().replace(/\s+/gu, " ")) {
-			recordGateDecision("message_edit");
-			return null;
-		}
-		if (input.request.claimRevision !== void 0 && !await input.request.claimRevision()) {
-			recordGateDecision("message_revision_already_handled");
-			return null;
+	let member = lookup.member;
+	let turnAdmitted = turn || !lookup.provisioned || member.roles.length !== 1 || member.roles[0] !== "member";
+	let admissionRefused = false;
+	async function admitTurn(reply) {
+		if (turnAdmitted) return true;
+		const admitted = await resolve(true);
+		if (admitted.status !== "existing" && admitted.status !== "created") {
+			admissionRefused = true;
+			await reject(admitted, reply);
+			return false;
 		}
+		member = admitted.member;
+		turnAdmitted = true;
+		return true;
 	}
 	let address = scopedAddress(messageAddress(sent), dependencies.sessions().scope);
 	const operations = input.request?.sessions;
@@ -306,7 +371,7 @@ async function handleInboundMessage(input) {
 		conversationId: ""
 	});
 	const questionOwner = {
-		memberId: lookup.member.id,
+		memberId: member.id,
 		chatId: sent.chat.id,
 		messageThreadId: String(sent.messageThreadId ?? "")
 	};
@@ -315,7 +380,7 @@ async function handleInboundMessage(input) {
 	const owner = questionSession ?? await operations?.resolveSession(address) ?? await operations?.resolveSession(topicAddress);
 	const questionHistory = owner === void 0 || dependencies.history === void 0 ? [] : await dependencies.history(owner.id);
 	const pending = questionFromHistory(questionHistory, questionOwner);
-	let answering = pending !== void 0 && pending.memberId === lookup.member.id && pending.chatId === sent.chat.id && pending.messageThreadId === String(sent.messageThreadId ?? "");
+	let answering = pending !== void 0 && pending.memberId === member.id && pending.chatId === sent.chat.id && pending.messageThreadId === String(sent.messageThreadId ?? "");
 	const asked = questionHistory.findLast((event) => {
 		const data = isRecord(event.data) ? event.data : {};
 		const result = isRecord(data.result) ? data.result : {};
@@ -328,7 +393,27 @@ async function handleInboundMessage(input) {
 		address = pending.address || (questionSession === void 0 ? topicAddress : memberQuestionAddress);
 		input.request.address = address;
 	}
-	const mediaPlan = voice !== void 0 || sent.attachments.length > 0 || dependencies.observed.list(chat).some((message) => (message.images?.length ?? 0) > 0) ? await dependencies.mediaPlan?.(lookup.member, owner?.id) : void 0;
+	if (group && (addressed === void 0 && !answering && dependencies.policy === "mention" || elsewhere !== void 0 && (addressed === void 0 || addressed === "reply-to-bot" && !recipientAnswer))) {
+		await recordInboundContent({
+			text,
+			decoded
+		});
+		dependencies.observed.add(chat, observedMessage(sent, text || "[attachment]", member, void 0, bot));
+		recordRouteDecision("observe", addressed, dependencies.policy, {
+			reason: elsewhere === void 0 ? "mention_policy" : "other_recipient",
+			note: elsewhere ?? "Mention policy observes unaddressed messages."
+		});
+		return null;
+	}
+	if (hasContent && answering && !await admitTurn(true)) {
+		await observeRaw();
+		return null;
+	}
+	if ((voice !== void 0 || sent.attachments.length > 0) && !await admitTurn(addressed !== void 0 || answering)) {
+		await observeRaw();
+		return null;
+	}
+	const mediaPlan = voice !== void 0 || sent.attachments.length > 0 || dependencies.observed.list(chat).some((message) => (message.images?.length ?? 0) > 0) ? await dependencies.mediaPlan?.(member, owner?.id) : void 0;
 	if (voice !== void 0 && !group) await transcribeVoice(false);
 	if (voice !== void 0 && mediaPlan?.audio) notes.push("[The chat model supports audio, but this host cannot deliver native audio. The configured speech-to-text fallback was used if enabled.]");
 	if (text.trim() === "" && sent.attachments.length === 0) {
@@ -352,7 +437,11 @@ async function handleInboundMessage(input) {
 		media_type: file.mediaType,
 		size: file.size
 	})) })];
-	let media = [...attachmentMetadata, ...notes].join("\n");
+	let media = [
+		input.request?.previousContent?.media,
+		...attachmentMetadata,
+		...notes
+	].filter(Boolean).join("\n");
 	let processedMedia;
 	let classified = false;
 	let question;
@@ -386,7 +475,7 @@ async function handleInboundMessage(input) {
 			recent: context.recent,
 			pendingConfirmations: context.pendingConfirmations,
 			pendingQuestions: context.pendingQuestions.filter((question) => question.chatId === sent.chat.id && question.messageThreadId === String(sent.messageThreadId ?? "")),
-			message: observedMessage(sent, text, lookup.member, media, bot),
+			message: observedMessage(sent, text, member, media, bot),
 			audience,
 			captionlessAttachments: caption.trim() === "" ? messageMetadata(sent, bot).attachmentKinds : []
 		};
@@ -394,12 +483,15 @@ async function handleInboundMessage(input) {
 	};
 	const route = await routeMessage({
 		chatId: sent.chat.id,
-		memberId: lookup.member.id,
+		memberId: member.id,
 		policy: dependencies.policy,
 		addressed: addressed ?? (answering ? "pending-question" : void 0),
 		recipientAnswer,
 		audience,
-		record: (decision) => recordRouteDecision(decision.route, addressed, dependencies.policy, decision),
+		record: (decision) => {
+			if (decision.reason !== "admission_refused") recordRouteDecision(decision.route, addressed, dependencies.policy, decision);
+		},
+		beforeDecide: () => admitTurn(false),
 		decide: dependencies.decide,
 		question: async () => {
 			classified = true;
@@ -447,11 +539,19 @@ async function handleInboundMessage(input) {
 			return conversation();
 		}
 	});
-	if (group && route === "observe") dependencies.observed.add(chat, observedMessage(sent, text, lookup.member, media, bot));
+	if (admissionRefused) {
+		await recordInboundContent({
+			text,
+			decoded
+		});
+		dependencies.observed.add(chat, observedMessage(sent, text || "[attachment]", member, void 0, bot));
+		return null;
+	}
+	if (group && route === "observe") dependencies.observed.add(chat, observedMessage(sent, text, member, media, bot));
 	if (sent.attachments.length > 0) await report;
-	let files = sent.attachments.length === 0 || dependencies.attachments === void 0 || input.request === void 0 ? new Map() : await stageFiles({
+	let files = input.request?.edited && !input.request.attachmentsChanged && (input.request.previousContent?.decoded.length ?? 0) > 0 || sent.attachments.length === 0 || dependencies.attachments === void 0 || input.request === void 0 ? new Map() : await stageFiles({
 		message: sent,
-		memberId: lookup.member.id,
+		memberId: member.id,
 		attachments: dependencies.attachments,
 		download: async (fileId) => {
 			const bytes = voiceBytes !== void 0 && voice?.fileId === fileId ? voiceBytes : routingBytes !== void 0 && routingFile?.fileId === fileId ? routingBytes : await dependencies.download(fileId);
@@ -487,7 +587,7 @@ async function handleInboundMessage(input) {
 	if (route === "observe") {
 		const images = [...files.values()].flatMap((file) => file.status === "stored" && file.imageInput === "native" ? [file.attachment] : []);
 		dependencies.observed.add(chat, {
-			...observedMessage(sent, text === "" ? "[attachment]" : text, lookup.member, media, bot),
+			...observedMessage(sent, text === "" ? "[attachment]" : text, member, media, bot),
 			images
 		});
 		return null;
@@ -539,7 +639,7 @@ async function handleInboundMessage(input) {
 				type: "file",
 				data: attachmentUrl({
 					id: image.id,
-					memberId: lookup.member.id,
+					memberId: member.id,
 					conversation: `telegram:${sent.chat.id}`
 				}),
 				mediaType: image.contentType,
@@ -553,13 +653,13 @@ async function handleInboundMessage(input) {
 		recordGateDecision("message_already_handled");
 		return null;
 	}
-	dependencies.observed.remember(chat, observedMessage(sent, text, lookup.member, retainedMedia, bot));
+	dependencies.observed.remember(chat, observedMessage(sent, text, member, retainedMedia, bot));
 	const principal = telegramPrincipal({
 		message: {
 			...sent,
 			text
 		},
-		member: lookup.member,
+		member,
 		conversationLanguage: language
 	});
 	return {
@@ -575,7 +675,7 @@ async function handleInboundMessage(input) {
 			...group ? chatContext(dependencies.chats.chat(sent.chat.id)) : [],
 			speakerBlock({
 				message: sent,
-				member: lookup.member,
+				member,
 				bot,
 				omitQuote: group && question?.recent.some((entry) => "role" in entry && entry.confirmation !== void 0 && entry.messageId === audience.replyTo?.messageId)
 			}),

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

@@ -21,3 +21,5 @@ export declare function conversationLanguage(texts: readonly string[]): "ru" | "
 export declare function memberIdOf(principal: SessionAuthContext | null | undefined): string | undefined;
 /** The member's roles on a session principal; empty when it carries none. */
 export declare function rolesOf(principal: SessionAuthContext | null | undefined): ReadonlyArray<string>;
+/** Verified channel provenance stamped by the channel adapter, never by model input. */
+export declare function identityProviderOf(principal: SessionAuthContext | null | undefined): string | undefined;

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

@@ -13,6 +13,7 @@ function telegramPrincipal(input) {
 	const sender = message.from.id;
 	const attributes = {
 		memberId: member.id,
+		identityProvider: "telegram",
 		roles: member.roles,
 		chatId: message.chat.id,
 		chatType: message.chat.type
@@ -48,4 +49,8 @@ function rolesOf(principal) {
 	if (typeof roles === "string") return [roles];
 	return roles ?? [];
 }
-export { TELEGRAM_AUTHENTICATOR, conversationLanguage, memberIdOf, rolesOf, telegramPrincipal };
+function identityProviderOf(principal) {
+	const provider = principal?.attributes.identityProvider;
+	return typeof provider === "string" && provider !== "" ? provider : void 0;
+}
+export { TELEGRAM_AUTHENTICATOR, conversationLanguage, identityProviderOf, memberIdOf, rolesOf, telegramPrincipal };

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

@@ -111,5 +111,6 @@ export declare function routeMessage(input: {
     readonly record?: (decision: RouteDecision) => void;
     /** Builds the question only when a decision is needed: it reads the agent's description. */
     readonly question: () => Promise<RouteQuestion>;
+    readonly beforeDecide?: () => Promise<boolean>;
     readonly decide: RouteDecider;
 }): Promise<Route>;

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

@@ -233,6 +233,8 @@ async function routeMessage(input) {
 	if (elsewhere !== void 0) return complete("observe", "other_recipient", elsewhere);
 	if (input.addressed === "reply-to-bot") return complete("reply", "reply-to-bot", "Bot addressed directly: reply-to-bot.");
 	if (input.addressed === "pending-question") return complete("reply", "pending-question", "Answer to this member's pending agent question, without another explicit recipient.");
+	if (input.policy === "mention") return complete("observe", "mention_policy", "Mention policy observes unaddressed messages.");
+	if (input.beforeDecide !== void 0 && !await input.beforeDecide()) return complete("observe", "admission_refused", "Admission refused before decoding or inference.");
 	try {
 		const question = await input.question();
 		const elsewhere = otherRecipient(question.audience);

package/package.json

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