@ouro.bot/cli 0.1.0-alpha.815 → 0.1.0-alpha.817

package/dist/senses/telegram-approval-runtime.js

@@ -52,9 +52,11 @@ const sanctuary_acceptance_marker_1 = require("../heart/daemon/sanctuary-accepta
 const telegram_1 = require("./telegram");
 const context_1 = require("../mind/context");
 const session_transaction_1 = require("../mind/session-transaction");
+const relationship_authorization_1 = require("../repertoire/relationship-authorization");
 const tools_1 = require("../repertoire/tools");
 const mcp_manager_1 = require("../repertoire/mcp-manager");
 const runtime_1 = require("../nerves/runtime");
+const shared_turn_1 = require("./shared-turn");
 const telegram_client_1 = require("./telegram-client");
 function telegramApprovalCommitBarrierHooks(effectBarrier) {
     return {
@@ -190,11 +192,11 @@ function createTelegramApprovalRuntime(options) {
     const resolveTool = options.dependencies?.resolveTool ?? tools_1.resolveToolDefinition;
     const agentRoot = options.dependencies?.agentRoot ?? (0, identity_1.getAgentRoot)(options.agentName);
     const owner = Object.freeze({ agentName: options.agentName, agentRoot });
-    const currentOptions = async (record) => {
+    const currentOptions = async (record, phase) => {
         try {
             if (!options.resolveLiveToolContext)
                 throw new Error("current owner authority producer is unavailable");
-            const context = await options.resolveLiveToolContext(record);
+            let context = await options.resolveLiveToolContext(record);
             const relationship = context.relationshipAuthorization;
             if (context.agentName !== owner.agentName || context.agentRoot !== owner.agentRoot
                 || relationship?.profileId !== "sanctuary-owner" || relationship.actor?.trustLevel !== "family"
@@ -203,6 +205,26 @@ function createTelegramApprovalRuntime(options) {
                 || context.currentSession.key !== record.sessionKey || context.currentSession.sessionPath !== record.sessionPath) {
                 throw new Error("current approval owner coordinates are not exact");
             }
+            if (record.toolName === "unraid_restart_container") {
+                const restartOwner = await resolveRestartOwnerContext(record, context);
+                if (restartOwner.allowed) {
+                    context = restartOwner.context;
+                }
+                else {
+                    const { reason } = restartOwner;
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn", component: "senses", event: "senses.telegram_approval_owner_denied",
+                        message: "restart approval owner revalidation failed",
+                        meta: { approvalId: record.approvalId, reason, phase },
+                    });
+                    if (phase === "decision")
+                        return null;
+                    context = {
+                        ...context,
+                        relationshipAuthorization: { authorizedContextScopes: [], advertisedToolNames: [], authorizeTool: () => ({ allowed: false, reason }) },
+                    };
+                }
+            }
             const runtime = await (options.dependencies?.getProviderRuntime ?? core_1.getProviderRuntime)("human", owner);
             const mcpManager = await (options.dependencies?.getSharedMcpManager ?? mcp_manager_1.getSharedMcpManager)(owner) ?? undefined;
             const selectCurrentTools = () => (0, tools_1.selectToolsForChannel)((0, friends_1.getChannelCapabilities)("telegram"), context.context?.friend.toolPreferences, context.context, runtime.capabilities, mcpManager, runtime.model, context);
@@ -220,9 +242,10 @@ function createTelegramApprovalRuntime(options) {
             return null;
         }
     };
-    const invocationContext = (current, definition) => ({
+    const invocationContext = (current, definition, restartApproval) => ({
         ...current.toolContext,
         toolSelection: Object.freeze({ ordinary: Object.freeze([definition]), engine: Object.freeze([]) }),
+        ...(restartApproval ? { restartApproval } : {}),
     });
     const stateRoot = path.join(agentRoot, "state", "approvals");
     const store = (0, approval_store_1.openApprovalStore)({ databasePath: path.join(stateRoot, "approvals.sqlite"), now: () => new Date(now()) });
@@ -230,6 +253,44 @@ function createTelegramApprovalRuntime(options) {
     const tokens = new approval_files_1.FileApprovalTokenStore(path.join(stateRoot, "tokens.json"));
     const pendingStore = new telegram_client_1.FileTelegramPendingApprovalStore(path.join(stateRoot, "telegram-pending.json"));
     let transport;
+    const ownerSessionMatches = (binding, sessionPath) => {
+        if (binding.sessionKey !== `telegram:${options.subject}`
+            || sessionPath !== (0, shared_turn_1.getSenseSessionPath)(options.agentName, binding.friendId, "telegram", binding.sessionKey, agentRoot))
+            return false;
+        const envelope = (0, session_events_1.loadSessionEnvelopeFile)(sessionPath);
+        const latestUser = envelope && (0, session_events_1.selectEffectiveSessionEvents)(envelope.events).findLast((event) => event.role === "user");
+        return latestUser?.id === binding.sessionEventId && latestUser.relations.references.includes(binding.requestId);
+    };
+    const resolveRestartOwnerContext = async (record, currentContext) => {
+        const resolve = options.resolveOwnerRelationship;
+        const binding = record.ownerBinding && Object.freeze({ ...record.ownerBinding });
+        if (!binding || !resolve || (options.toolContext.agentRoot ?? agentRoot) !== agentRoot || record.sessionKey !== binding.sessionKey) {
+            return { allowed: false, reason: "restart approval owner binding is unavailable" };
+        }
+        try {
+            if (!ownerSessionMatches(binding, record.sessionPath))
+                return { allowed: false, reason: "restart approval owner session changed" };
+            const relationship = await resolve(binding);
+            const context = {
+                ...currentContext,
+                relationshipAuthorization: {
+                    ...relationship,
+                    requestId: binding.requestId,
+                    authorizeTool: async (name, args) => {
+                        const current = await resolve(binding);
+                        if (!ownerSessionMatches(binding, record.sessionPath))
+                            return { allowed: false, reason: "restart approval owner session changed" };
+                        return current.authorizeTool(name, args);
+                    },
+                },
+            };
+            const authorization = await (0, relationship_authorization_1.authorizeRestartApprovalRequester)(context, record.arguments, binding);
+            return authorization.allowed ? { allowed: true, context } : authorization;
+        }
+        catch {
+            return { allowed: false, reason: "restart approval owner authorization is unavailable" };
+        }
+    };
     const commitAcceptanceEvidence = options.dependencies?.commitAcceptanceEvidence ?? (async (event, meta) => {
         if (event === "telegram.callback_settled") {
             await (0, runtime_1.emitNervesEventDurable)({
@@ -256,6 +317,25 @@ function createTelegramApprovalRuntime(options) {
             if (request.toolCall.type !== "function")
                 throw new Error("approval requires a function tool call");
             effectBarrier();
+            let ownerBinding;
+            if (request.toolCall.function.name === "unraid_restart_container") {
+                const live = request.liveToolContext;
+                const authorization = await (0, relationship_authorization_1.authorizeRoutineActionRequester)(live, request.arguments);
+                if (!authorization.allowed || authorization.requester.kind !== "owner"
+                    || live?.agentRoot !== agentRoot || live.currentSession?.sessionPath !== context.sessionPath) {
+                    throw new Error("restart approval requires a current owner request");
+                }
+                const requester = authorization.requester;
+                ownerBinding = {
+                    friendId: requester.friendId, requestId: requester.requestId, sessionEventId: requester.sessionEventId,
+                    sessionKey: requester.origin.key, profileVersion: authorization.profileVersion,
+                };
+                if (!ownerSessionMatches(ownerBinding, context.sessionPath))
+                    throw new Error("restart approval owner session changed");
+                const policy = await (0, tools_1.approvalPolicyForInvocation)("unraid_restart_container", request.arguments, live);
+                if (policy.kind !== "required")
+                    throw new Error("restart approval no longer has owner fallback");
+            }
             const scenarioHandleDigest = acceptanceMarker()?.scenarioHandleDigest;
             const committed = (0, tool_approval_1.commitApprovalProposal)({
                 approvalStore: store,
@@ -279,6 +359,7 @@ function createTelegramApprovalRuntime(options) {
                     transportChatId: options.subject,
                     expiresAt: new Date(now() + 300_000).toISOString(),
                     frozenAssistantMessage: request.frozenAssistantMessage,
+                    ...(ownerBinding ? { ownerBinding } : {}),
                     ...(scenarioHandleDigest ? { scenarioHandleDigest } : {}),
                 },
                 preCallMessages: request.preCallMessages,
@@ -369,7 +450,7 @@ function createTelegramApprovalRuntime(options) {
                 completeContinuation: () => { effectBarrier(); store.completeContinuation({ approvalId: record.approvalId, ownerId: continuationOwnerId, epoch: continuationEpoch }); },
                 runAgent: provider,
                 revalidate: async () => {
-                    const current = await currentOptions(record);
+                    const current = await currentOptions(record, "continuation");
                     continuationAuthorized = current !== null;
                     return current ? { ...current, ...approvalContinuationRunAgentOptions(current.toolContext, continuationCoordinator) } : null;
                 },
@@ -457,6 +538,7 @@ function createTelegramApprovalRuntime(options) {
             }
             else if (existing.state === "proposed") {
                 const ownerId = `telegram-decision-${(0, node_crypto_1.randomUUID)()}`;
+                let restartApproval;
                 let definition;
                 record = await (0, session_transaction_1.withSessionTurnLease)(existing.sessionPath, async (lease) => (0, tool_approval_1.executeApprovalDecision)({
                     approvalStore: store,
@@ -470,31 +552,67 @@ function createTelegramApprovalRuntime(options) {
                         sessionKey: existing.sessionKey,
                     },
                     ownerId,
-                    currentSessionRevision: (0, session_transaction_1.readSessionTransaction)(existing.sessionPath, lease).revision,
+                    currentSessionRevision: () => (0, session_transaction_1.readSessionTransaction)(existing.sessionPath, lease).revision,
                     resolveTool: async (name) => {
-                        const current = await currentOptions(existing);
+                        const current = await currentOptions(existing, "decision");
                         definition = current ? resolveTool(name, current.toolContext.toolSelection) : undefined;
                         return definition;
                     },
                     resolveApprovalPolicy: async (name, args) => {
-                        const current = await currentOptions(existing);
+                        const current = await currentOptions(existing, "decision");
                         return current ? (0, tools_1.approvalPolicyForInvocation)(name, args, current.toolContext) : { kind: "not_required" };
                     },
-                    liveGuard: async () => ({ ok: true }),
+                    liveGuard: async (context) => {
+                        if (existing.toolName !== "unraid_restart_container")
+                            return { ok: true };
+                        const current = await currentOptions(existing, "decision");
+                        if (!current || !existing.ownerBinding)
+                            return { ok: false, reason: "restart approval owner binding is unavailable" };
+                        const restartToolContext = current.toolContext;
+                        const authorization = await (0, relationship_authorization_1.authorizeRestartApprovalRequester)(restartToolContext, context.arguments, existing.ownerBinding);
+                        if (!authorization.allowed)
+                            return { ok: false, reason: authorization.reason };
+                        try {
+                            const listed = await restartToolContext.sanctuary?.listContainers();
+                            if (!listed || typeof listed !== "object" || !("ok" in listed) || listed.ok !== true
+                                || !("data" in listed) || !listed.data || typeof listed.data !== "object"
+                                || !("truncated" in listed.data) || listed.data.truncated !== false
+                                || !("containers" in listed.data) || !Array.isArray(listed.data.containers)) {
+                                return { ok: false, reason: "restart approval inventory is invalid" };
+                            }
+                            const matches = listed.data.containers.filter((target) => target?.name === context.arguments.container);
+                            const target = matches[0];
+                            if (matches.length !== 1 || typeof target?.id !== "string" || !target.id.trim() || target.id !== target.id.trim() || target.degraded !== false) {
+                                return { ok: false, reason: "restart approval target is not exact" };
+                            }
+                            restartApproval = Object.freeze({
+                                approvalId: existing.approvalId, agentRoot, sessionPath: existing.sessionPath,
+                                ownerBinding: Object.freeze({ ...existing.ownerBinding }),
+                                argumentDigest: existing.argumentDigest,
+                                target: Object.freeze({ id: target.id, name: String(context.arguments.container) }),
+                            });
+                            return { ok: true };
+                        }
+                        catch {
+                            return { ok: false, reason: "restart approval target is unavailable" };
+                        }
+                    },
                     liveRisk: async () => ({ ok: true }),
                     preflight: async (context) => {
-                        const current = await currentOptions(existing);
+                        const current = await currentOptions(existing, "decision");
                         if (!current)
                             return { ok: false, reason: "current tool authority is unavailable" };
-                        const result = await (0, tools_1.preflightToolCall)(context.record.toolName, context.arguments, invocationContext(current, context.definition));
+                        const result = await (0, tools_1.preflightToolCall)(context.record.toolName, context.arguments, invocationContext(current, context.definition, restartApproval));
                         return result.kind === "ready" ? { ok: true } : { ok: false, reason: result.text };
                     },
                     hooks: telegramApprovalDecisionBarrierHooks(effectBarrier),
                     execute: async (name, args) => {
-                        const current = await currentOptions(existing);
+                        if (name === "unraid_restart_container" && !restartApproval)
+                            return { kind: "rejected_before_handler", text: "restart approval was not revalidated" };
+                        const current = await currentOptions(existing, "decision");
                         if (!current || !definition)
                             return { kind: "rejected_before_handler", text: "current approved tool authority is unavailable" };
-                        const approvedToolContext = invocationContext(current, definition);
+                        const approvedToolContext = invocationContext(current, definition, restartApproval);
                         const execute = () => executeApprovedTelegramTool(name, args, (toolName, toolArgs) => (0, tools_1.executeTool)(toolName, toolArgs, approvedToolContext, options.dependencies?.executeTool), decisionScenarioDigest, existing.approvalId, effectBarrier);
                         return decisionScenarioDigest
                             ? (0, sanctuary_acceptance_marker_1.runWithSanctuaryAcceptanceApproval)({ approvalId: existing.approvalId, argumentDigest: existing.argumentDigest }, execute)

package/dist/senses/telegram-attachments.js

@@ -150,7 +150,11 @@ async function ingestTelegramAttachments(input) {
                 throw new Error("invalid remote path");
             if (remote.file_size !== undefined && (!Number.isSafeInteger(remote.file_size) || remote.file_size < 0 || remote.file_size > exports.MAX_TELEGRAM_ATTACHMENT_BYTES))
                 throw new Error("advertised size exceeds limit");
-            const response = await fetchImpl(`https://api.telegram.org/file/bot${input.botToken}/${remote.file_path}`, { signal: AbortSignal.timeout(30_000) });
+            const response = input.downloadFile
+                ? await input.downloadFile(remote.file_path)
+                : input.botToken
+                    ? await fetchImpl(`https://api.telegram.org/file/bot${input.botToken}/${remote.file_path}`, { signal: AbortSignal.timeout(30_000) })
+                    : (() => { throw new Error("attachment transport is unavailable"); })();
             if (!response.ok)
                 throw new Error(`download failed with HTTP ${response.status}`);
             const buffer = await readBounded(response, exports.MAX_TELEGRAM_ATTACHMENT_BYTES);

package/dist/senses/telegram-authority-transport.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSanctuaryTelegramAuthorityTransport = createSanctuaryTelegramAuthorityTransport;
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../nerves/runtime");
+const sanctuary_authority_codec_1 = require("../heart/daemon/sanctuary-authority-codec");
+const root_host_approval_port_1 = require("./root-host-approval-port");
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validPollBody(body) {
+    return Object.keys(body).sort().join(",") === "allowed_updates,offset,timeout"
+        && Number.isSafeInteger(body.offset)
+        && body.offset >= 0
+        && body.timeout === 50
+        && Array.isArray(body.allowed_updates)
+        && body.allowed_updates.length === 2
+        && body.allowed_updates[0] === "message"
+        && body.allowed_updates[1] === "callback_query";
+}
+function rawUpdateDigest(update) {
+    return `tgu_${(0, node_crypto_1.createHash)("sha256")
+        .update(`ouroboros.telegram.update.v1\0${JSON.stringify(update)}`, "utf8")
+        .digest("base64url")}`;
+}
+function exactKeys(value, keys) {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+function canonicalTime(value) {
+    if (typeof value !== "string")
+        return false;
+    const instant = new Date(value);
+    return !Number.isNaN(instant.getTime()) && instant.toISOString() === value;
+}
+function verifyObservation(artifact, update, verification) {
+    let payload;
+    try {
+        payload = (0, sanctuary_authority_codec_1.verifyAuthorityPayload)({
+            artifact,
+            expectedDomain: "ouro.sanctuary.telegram-observation.v1",
+            expectedKeyId: verification.expectedKeyId,
+            publicKey: verification.publicKey,
+        });
+    }
+    catch (error) {
+        throw new Error("Sanctuary Telegram authority poll response is invalid", { cause: error });
+    }
+    if (!isObject(payload)
+        || !exactKeys(payload, [
+            "targetHost", "botId", "updateId", "updateClass", "userId", "chatId", "ownerEligible",
+            "messageId", "callbackQueryId", "rawUpdateDigest", "observedAt", "settlement", "nonce", "publicKeyDigest",
+            ...(Object.hasOwn(payload, "deliveryUpdateDigest") ? ["deliveryUpdateDigest"] : []),
+        ])
+        || payload.targetHost !== verification.expectedTargetHost
+        || payload.botId !== verification.expectedBotId
+        || payload.publicKeyDigest !== verification.expectedPublicKeyDigest
+        || payload.updateId !== update.update_id
+        || !["message", "callback"].includes(String(payload.updateClass))
+        || typeof payload.userId !== "string"
+        || typeof payload.chatId !== "string"
+        || typeof payload.ownerEligible !== "boolean"
+        || (payload.messageId !== null && typeof payload.messageId !== "string")
+        || (payload.callbackQueryId !== null && typeof payload.callbackQueryId !== "string")
+        || typeof payload.rawUpdateDigest !== "string"
+        || !/^tgu_[A-Za-z0-9_-]{43}$/u.test(payload.rawUpdateDigest)
+        || (Object.hasOwn(payload, "deliveryUpdateDigest") && typeof payload.deliveryUpdateDigest !== "string")
+        || (payload.deliveryUpdateDigest ?? payload.rawUpdateDigest) !== rawUpdateDigest(update)
+        || !canonicalTime(payload.observedAt)
+        || payload.settlement !== "pending"
+        || typeof payload.nonce !== "string"
+        || !/^[A-Za-z0-9_-]{43}$/u.test(payload.nonce)) {
+        throw new Error("Sanctuary Telegram authority observation payload is invalid");
+    }
+    const callback = update.callback_query;
+    const message = update.message;
+    if ((!callback && !message) || (callback && message) || (callback && (!callback.message || !callback.from)) || (message && !message.from)) {
+        throw new Error("Sanctuary Telegram authority observation update is unsupported");
+    }
+    const updateClass = callback ? "callback" : "message";
+    const userId = String(callback ? callback.from.id : message.from.id);
+    const chatId = String(callback ? callback.message.chat.id : message.chat.id);
+    const messageId = String(callback ? callback.message.message_id : message.message_id);
+    const callbackQueryId = callback ? callback.id : null;
+    if (payload.updateClass !== updateClass
+        || payload.userId !== userId
+        || payload.chatId !== chatId
+        || payload.messageId !== messageId
+        || payload.callbackQueryId !== callbackQueryId
+        || payload.ownerEligible !== (userId === verification.expectedOwnerUserId && chatId === verification.expectedOwnerChatId)) {
+        throw new Error("Sanctuary Telegram authority observation coordinates changed");
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        observationDigest: (0, sanctuary_authority_codec_1.authorityArtifactDigest)(artifact.domain, payload),
+        targetHost: payload.targetHost,
+        botId: payload.botId,
+        updateId: payload.updateId,
+        updateClass: payload.updateClass,
+        userId: payload.userId,
+        chatId: payload.chatId,
+        ownerEligible: payload.ownerEligible,
+        messageId: payload.messageId,
+        callbackQueryId: payload.callbackQueryId,
+        rawUpdateDigest: payload.rawUpdateDigest,
+        ...(payload.deliveryUpdateDigest ? { deliveryUpdateDigest: payload.deliveryUpdateDigest } : {}),
+        observedAt: payload.observedAt,
+        keyId: artifact.keyId,
+        publicKeyDigest: payload.publicKeyDigest,
+    });
+}
+function createSanctuaryTelegramAuthorityTransport(client, verification) {
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.sanctuary_authority_transport_created", message: "Tokenless Sanctuary Telegram authority transport created" });
+    verification = Object.freeze({ ...verification });
+    const observations = new Map();
+    const metadata = new Map();
+    const callbacks = new Map();
+    let currentObservation = null;
+    let stopped = false;
+    const api = {
+        async request(method, body, signal) {
+            if (signal?.aborted)
+                throw signal.reason;
+            if (stopped)
+                throw new Error("Sanctuary Telegram authority transport is stopped");
+            if (method !== "getUpdates") {
+                return await client.request("telegram.request", {
+                    method,
+                    body,
+                    ...(currentObservation ? {
+                        observation: {
+                            updateId: currentObservation.payload.updateId,
+                            observationDigest: (0, sanctuary_authority_codec_1.authorityArtifactDigest)(currentObservation.domain, currentObservation.payload),
+                        },
+                    } : {}),
+                });
+            }
+            if (!validPollBody(body))
+                throw new Error("Sanctuary Telegram authority poll request is invalid");
+            const result = await client.request("telegram.poll", {});
+            if (result === null)
+                return [];
+            if (!isObject(result)
+                || !isObject(result.observation)
+                || !isObject(result.observation.payload)
+                || !isObject(result.update)
+                || !Number.isSafeInteger(result.update.update_id)
+                || result.observation.payload.updateId !== result.update.update_id) {
+                throw new Error("Sanctuary Telegram authority poll response is invalid");
+            }
+            const update = result.update;
+            const observation = result.observation;
+            const verifiedMetadata = verifyObservation(observation, update, verification);
+            const existing = observations.get(update.update_id);
+            if (existing
+                && (0, sanctuary_authority_codec_1.authorityArtifactDigest)(existing.domain, existing.payload)
+                    !== (0, sanctuary_authority_codec_1.authorityArtifactDigest)(observation.domain, observation.payload)) {
+                throw new Error("Sanctuary Telegram authority observation changed during redelivery");
+            }
+            observations.set(update.update_id, observation);
+            metadata.set(update.update_id, verifiedMetadata);
+            callbacks.set(update.update_id, result.hostCallback);
+            currentObservation = observation;
+            return [update];
+        },
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            client.close();
+        },
+    };
+    const transport = {
+        api,
+        async downloadFile(filePath) {
+            const result = await client.request("telegram.file", { filePath });
+            if (!isObject(result)
+                || typeof result.bodyBase64 !== "string"
+                || (result.contentType !== undefined && typeof result.contentType !== "string")) {
+                throw new Error("Sanctuary Telegram authority file response is invalid");
+            }
+            const body = Buffer.from(result.bodyBase64, "base64");
+            if (body.toString("base64") !== result.bodyBase64 || body.length > 20_000_000) {
+                throw new Error("Sanctuary Telegram authority file response is invalid");
+            }
+            return new Response(body, {
+                headers: result.contentType ? { "content-type": result.contentType } : undefined,
+            });
+        },
+        async admitChat(input) {
+            await client.request("telegram.chat.admit", input);
+        },
+        async revokeChat(input) {
+            await client.request("telegram.chat.revoke", input);
+        },
+        metadataForUpdate(update) {
+            const value = metadata.get(update.update_id);
+            if (!value)
+                return null;
+            if ((value.deliveryUpdateDigest ?? value.rawUpdateDigest) !== rawUpdateDigest(update)) {
+                throw new Error("Sanctuary Telegram authority update changed after verification");
+            }
+            return value;
+        },
+        async settleTransport(update, outcome) {
+            const observation = observations.get(update.update_id);
+            if (!observation)
+                throw new Error("Sanctuary Telegram authority observation is unavailable for settlement");
+            await client.request("telegram.settle", {
+                updateId: update.update_id,
+                observationDigest: (0, sanctuary_authority_codec_1.authorityArtifactDigest)(observation.domain, observation.payload),
+                outcome,
+            });
+            observations.delete(update.update_id);
+            metadata.delete(update.update_id);
+            callbacks.delete(update.update_id);
+            if (currentObservation?.payload.updateId === update.update_id)
+                currentObservation = null;
+        },
+    };
+    transport.hostApproval = (0, root_host_approval_port_1.createRootHostApprovalPort)(client, verification, {
+        current: () => currentObservation ? metadata.get(currentObservation.payload.updateId) : null,
+        lookup: (update) => {
+            const value = transport.metadataForUpdate(update);
+            return value ? { metadata: value, hostCallback: callbacks.get(update.update_id) } : null;
+        },
+        stopped: () => stopped,
+    });
+    return transport;
+}

package/dist/senses/telegram-client.js

@@ -507,7 +507,7 @@ function createTelegramLongPoll(options) {
     const rawAttachmentCount = (message) => [
         message.document, message.audio, message.video, message.voice, message.animation, message.sticker,
     ].filter(Boolean).length + (message.photo?.length ? 1 : 0);
-    const authorizedMessage = (update) => {
+    const authorizedMessage = (update, authority) => {
         const message = update.message;
         const userId = message?.from ? String(message.from.id) : "";
         const chatId = message ? String(message.chat.id) : "";
@@ -532,9 +532,10 @@ function createTelegramLongPoll(options) {
             ...(Number.isSafeInteger(message.reply_to_message?.message_id) && message.reply_to_message.message_id > 0
                 ? { replyToMessageId: String(message.reply_to_message.message_id) }
                 : {}),
+            ...(authority ? { authority } : {}),
         };
     };
-    const unknownMessage = (update) => {
+    const unknownMessage = (update, authority) => {
         const message = update.message;
         if (!options.onUnknownMessage || !options.botId || !message?.from || message.chat.type !== "private")
             return null;
@@ -557,6 +558,7 @@ function createTelegramLongPoll(options) {
             hasAttachments: attachmentCount > 0,
             attachments,
             ...(attachmentCount > attachments.length ? { attachmentNotices: ["attachment unavailable: Telegram media metadata was incomplete"] } : {}),
+            ...(authority ? { authority } : {}),
         };
     };
     const authorizedCallback = (update) => {
@@ -566,17 +568,18 @@ function createTelegramLongPoll(options) {
             && String(callback.message.chat.id) === options.expectedChatId);
     };
     const dispatch = async (update) => {
+        const authority = options.transportMetadata?.(update) ?? undefined;
         const handled = !update.callback_query || authorizedCallback(update)
-            ? await options.onUpdate?.(update) ?? false
+            ? await options.onUpdate?.(update, authority) ?? false
             : false;
         if (handled)
             return;
-        const message = authorizedMessage(update);
+        const message = authorizedMessage(update, authority);
         if (message) {
             await options.onMessage(message);
             return;
         }
-        const stranger = unknownMessage(update);
+        const stranger = unknownMessage(update, authority);
         if (stranger) {
             await options.onUnknownMessage(stranger);
             return;
@@ -619,15 +622,18 @@ function createTelegramLongPoll(options) {
         if (!Array.isArray(updates))
             throw new Error("Telegram getUpdates result must be an array");
         for (const update of updates) {
-            if (!update || !Number.isSafeInteger(update.update_id) || update.update_id < nextUpdateId)
+            if (!update || !Number.isSafeInteger(update.update_id) || (update.update_id < nextUpdateId && !options.settleTransport))
                 continue;
             options.onBeforeDispatch?.();
-            const next = update.update_id + 1;
+            const next = Math.max(nextUpdateId, update.update_id + 1);
             const requiresDurableDispatch = Boolean(authorizedCallback(update) || authorizedMessage(update) || unknownMessage(update));
             const newlyCaptured = requiresDurableDispatch ? (options.inboxStore?.capture(update) ?? true) : true;
             if (newlyCaptured) {
                 if (requiresDurableDispatch && options.inboxStore && !options.inboxStore.claim(update)) {
                     options.onDispatchSettled?.();
+                    const indeterminate = options.inboxStore.loadIndeterminate()
+                        .some((receipt) => sameReceipt(receipt, updateReceipt(update)));
+                    await options.settleTransport?.(update, indeterminate ? "indeterminate" : "completed");
                     options.offsetStore.save(next);
                     nextUpdateId = next;
                     options.inboxStore.commit?.(update);
@@ -651,11 +657,28 @@ function createTelegramLongPoll(options) {
                         throw new AggregateError([dispatchError, auditError], "Telegram dispatch and acceptance audit verification failed");
                     throw auditError;
                 }
+                try {
+                    if (options.settleTransport) {
+                        await options.settleTransport?.(update, dispatchError === undefined ? "completed" : "indeterminate");
+                    }
+                }
+                catch (settlementError) {
+                    if (dispatchError !== undefined)
+                        throw new AggregateError([dispatchError, settlementError], "Telegram dispatch and transport settlement failed");
+                    throw settlementError;
+                }
                 if (dispatchError !== undefined)
                     throw dispatchError;
             }
-            else
+            else {
                 options.onDispatchSettled?.();
+                if (options.settleTransport) {
+                    // Only an existing inbox can report that this update was already captured.
+                    const indeterminate = options.inboxStore.loadIndeterminate()
+                        .some((receipt) => sameReceipt(receipt, updateReceipt(update)));
+                    await options.settleTransport(update, indeterminate ? "indeterminate" : "completed");
+                }
+            }
             options.offsetStore.save(next);
             nextUpdateId = next;
             if (requiresDurableDispatch)

package/dist/senses/telegram-entry.js

@@ -61,7 +61,7 @@ Promise.all([
     }
     const machine = loadOrCreateMachineIdentity();
     await refreshMachineRuntimeCredentialConfig(agentName, machine.machineId, { preserveCachedOnFailure: true }).catch(() => undefined);
-    const app = await startTelegramSenseApp(agentName);
+    const app = await startTelegramSenseApp(agentName, true);
     let stopping;
     const stop = () => { stopping ??= app.stop(); };
     process.once("SIGTERM", stop);