@ouro.bot/cli 0.1.0-alpha.742 → 0.1.0-alpha.743

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

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.telegramApprovalCommitBarrierHooks = telegramApprovalCommitBarrierHooks;
 exports.telegramApprovalDecisionBarrierHooks = telegramApprovalDecisionBarrierHooks;
 exports.approvalContinuationRunAgentOptions = approvalContinuationRunAgentOptions;
+exports.formatTelegramApprovalPrompt = formatTelegramApprovalPrompt;
 exports.executeApprovedTelegramTool = executeApprovedTelegramTool;
 exports.createTelegramApprovalRuntime = createTelegramApprovalRuntime;
 const path = __importStar(require("node:path"));
@@ -45,6 +46,7 @@ const approval_store_1 = require("../heart/approval-store");
 const tool_approval_1 = require("../heart/tool-approval");
 const core_1 = require("../heart/core");
 const identity_1 = require("../heart/identity");
+const session_events_1 = require("../heart/session-events");
 const sanctuary_acceptance_marker_1 = require("../heart/daemon/sanctuary-acceptance-marker");
 const telegram_1 = require("./telegram");
 const context_1 = require("../mind/context");
@@ -69,6 +71,14 @@ function telegramApprovalDecisionBarrierHooks(effectBarrier) {
 function approvalContinuationRunAgentOptions(toolContext, approvalCoordinator) {
     return { toolContext: toolContext, approvalCoordinator };
 }
+function formatTelegramApprovalPrompt(toolName, args) {
+    if (toolName === "sanctuary_resume_download_queue")
+        return "Resume household downloads? This can spend prepaid download credit. I’ll verify the queue actually resumed.";
+    const container = args.container;
+    if (toolName === "unraid_restart_container" && typeof container === "string" && container.length > 0 && container.length <= 128 && !container.includes("\n"))
+        return `Restart ${container}?`;
+    return `Approve ${toolName} with exact arguments ${JSON.stringify(args)}?`;
+}
 async function executeApprovedTelegramTool(name, args, execute, scenarioHandleDigest, approvalId, effectBarrier = () => undefined) {
     if (name === "unraid_restart_container")
         (0, runtime_1.emitNervesEvent)({
@@ -80,6 +90,21 @@ async function executeApprovedTelegramTool(name, args, execute, scenarioHandleDi
     try {
         effectBarrier();
         const result = await execute(name, args);
+        if (name === "sanctuary_resume_download_queue") {
+            let parsed;
+            try {
+                parsed = JSON.parse(result);
+            }
+            catch {
+                throw new tool_approval_1.ApprovalExecutionFailedError("approved download resume returned an invalid result");
+            }
+            const data = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+            const outcome = data?.data && typeof data.data === "object" && !Array.isArray(data.data) ? data.data : null;
+            const after = outcome?.after && typeof outcome.after === "object" && !Array.isArray(outcome.after) ? outcome.after : null;
+            if (data?.ok !== true || outcome?.verified !== true || after?.paused !== false)
+                throw new tool_approval_1.ApprovalExecutionFailedError("approved download resume was not independently verified");
+            return result;
+        }
         if (name !== "unraid_restart_container")
             return result;
         let parsed;
@@ -152,7 +177,9 @@ function createTelegramApprovalRuntime(options) {
     const provider = options.dependencies?.runProvider ?? core_1.runAgent;
     const resolveTool = options.dependencies?.resolveTool ?? tools_1.resolveToolDefinition;
     const executeTool = options.dependencies?.executeTool ?? tools_1.execTool;
-    const stateRoot = path.join(options.dependencies?.agentRoot ?? (0, identity_1.getAgentRoot)(options.agentName), "state", "approvals");
+    const agentRoot = options.dependencies?.agentRoot ?? (0, identity_1.getAgentRoot)(options.agentName);
+    const liveToolContext = { ...options.toolContext, agentRoot: options.toolContext.agentRoot ?? agentRoot };
+    const stateRoot = path.join(agentRoot, "state", "approvals");
     const store = (0, approval_store_1.openApprovalStore)({ databasePath: path.join(stateRoot, "approvals.sqlite"), now: () => new Date(now()) });
     const checkpoints = new approval_files_1.FileApprovalCheckpointStore(path.join(stateRoot, "checkpoints.json"));
     const tokens = new approval_files_1.FileApprovalTokenStore(path.join(stateRoot, "tokens.json"));
@@ -212,7 +239,7 @@ function createTelegramApprovalRuntime(options) {
                 preCallMessages: request.preCallMessages,
                 hooks: telegramApprovalCommitBarrierHooks(effectBarrier),
             });
-            const prompt = `Approve ${request.toolCall.function.name} with exact arguments ${JSON.stringify(request.arguments)}?`;
+            const prompt = formatTelegramApprovalPrompt(request.toolCall.function.name, request.arguments);
             effectBarrier();
             const actionDigest = (0, node_crypto_1.createHash)("sha256").update(JSON.stringify({ toolName: committed.record.toolName, argumentDigest: committed.record.argumentDigest })).digest("hex");
             const targetDigest = (0, node_crypto_1.createHash)("sha256").update(JSON.stringify({ container: committed.record.arguments.container })).digest("hex");
@@ -269,6 +296,7 @@ function createTelegramApprovalRuntime(options) {
                 return { accepted: false, terminalText: "⚠️ Approval checkpoint is unavailable" };
             const continuationOwnerId = `telegram-continuation-${(0, node_crypto_1.randomUUID)()}`;
             let continuationEpoch = 0;
+            let continuationCausalEventId;
             const continuationCoordinator = {
                 propose: (request) => coordinator({
                     sessionPath: record.sessionPath,
@@ -293,11 +321,18 @@ function createTelegramApprovalRuntime(options) {
                 markContinuationAttempted: () => { effectBarrier(); store.markContinuationAttempted({ approvalId: record.approvalId, ownerId: continuationOwnerId, epoch: continuationEpoch }); },
                 completeContinuation: () => { effectBarrier(); store.completeContinuation({ approvalId: record.approvalId, ownerId: continuationOwnerId, epoch: continuationEpoch }); },
                 runAgent: provider,
-                runAgentOptions: approvalContinuationRunAgentOptions(options.toolContext, continuationCoordinator),
-                persist: (messages, result) => { effectBarrier(); (0, context_1.saveSession)(record.sessionPath, messages, result?.usage, undefined, lease); },
+                runAgentOptions: approvalContinuationRunAgentOptions(liveToolContext, continuationCoordinator),
+                persist: (messages, result) => {
+                    effectBarrier();
+                    const existingEventIds = new Set((0, session_events_1.loadSessionEnvelopeFile)(record.sessionPath)?.events.map((event) => event.id) ?? []);
+                    const events = (0, context_1.saveSession)(record.sessionPath, messages, result?.usage, undefined, lease);
+                    continuationCausalEventId = result
+                        ? [...events].reverse().find((event) => event.role === "assistant" && !existingEventIds.has(event.id))?.id
+                        : undefined;
+                },
                 deliver: async (text) => {
                     effectBarrier();
-                    const messageIds = await (0, telegram_client_1.sendTelegramText)(options.api, options.authorizedChatId, text);
+                    const messageIds = await options.effects.sendText({ idempotencyKey: `approval:${record.approvalId}:continuation:${(0, node_crypto_1.createHash)("sha256").update(text).digest("hex")}`, chatId: options.authorizedChatId, text, authorClass: "butler", ...(continuationCausalEventId ? { causalEventId: continuationCausalEventId } : {}) });
                     effectBarrier();
                     if (acceptanceBinding) {
                         const unsigned = {
@@ -322,6 +357,7 @@ function createTelegramApprovalRuntime(options) {
     };
     transport = (0, telegram_client_1.createTelegramApprovalTransport)({
         api: options.api,
+        effects: options.effects,
         expectedUserId: options.authorizedUserId,
         expectedChatId: options.authorizedChatId,
         pendingStore,
@@ -375,11 +411,15 @@ function createTelegramApprovalRuntime(options) {
                     ownerId,
                     currentSessionRevision: (0, session_transaction_1.readSessionTransaction)(existing.sessionPath, lease).revision,
                     resolveTool,
+                    resolveApprovalPolicy: (name, args) => (0, tools_1.approvalPolicyForInvocation)(name, args, liveToolContext),
                     liveGuard: async () => ({ ok: true }),
                     liveRisk: async () => ({ ok: true }),
                     hooks: telegramApprovalDecisionBarrierHooks(effectBarrier),
                     execute: (name, args) => {
-                        const execute = () => executeApprovedTelegramTool(name, args, (toolName, toolArgs) => executeTool(toolName, toolArgs, options.toolContext), decisionScenarioDigest, existing.approvalId, effectBarrier);
+                        const approvedToolContext = name === "unraid_restart_container"
+                            ? { ...options.toolContext, relationshipAuthorization: undefined }
+                            : options.toolContext;
+                        const execute = () => executeApprovedTelegramTool(name, args, (toolName, toolArgs) => executeTool(toolName, toolArgs, approvedToolContext), decisionScenarioDigest, existing.approvalId, effectBarrier);
                         return decisionScenarioDigest
                             ? (0, sanctuary_acceptance_marker_1.runWithSanctuaryAcceptanceApproval)({ approvalId: existing.approvalId, argumentDigest: existing.argumentDigest }, execute)
                             : execute();

package/dist/senses/telegram-client.js

@@ -84,6 +84,11 @@ const TELEGRAM_UPDATE_DIGEST_DOMAIN = "ouroboros.telegram.update.v1";
 const TELEGRAM_UPDATE_SEQUENCE_DOMAIN = "ouroboros.telegram.update-sequence.v1";
 const TELEGRAM_UPDATE_DIGEST = /^tgu_[A-Za-z0-9_-]{43}$/u;
 const TELEGRAM_UPDATE_SEQUENCE_DIGEST = /^tgs_[A-Za-z0-9_-]{43}$/u;
+const TELEGRAM_ADMISSION_ID = /^[a-f0-9]{20}$/u;
+const TELEGRAM_SESSION_EVENT_ID = /^evt-[0-9]{6,}$/u;
+function boundedTelegramWorkText(value, maxLength) {
+    return typeof value === "string" && value.length > 0 && value.length <= maxLength;
+}
 function updateReceipt(update) {
     return {
         digest: `tgu_${(0, node_crypto_1.createHash)("sha256").update(`${TELEGRAM_UPDATE_DIGEST_DOMAIN}\0${JSON.stringify(update)}`, "utf8").digest("base64url")}`,
@@ -147,6 +152,47 @@ class FileTelegramUpdateInboxStore {
                 && Number.isSafeInteger(record.quarantinedAt)
                 && record.quarantinedAt >= 0
                 && typeof record.warningAcknowledged === "boolean";
+            const validAdmitted = (record) => Boolean(record)
+                && typeof record === "object"
+                && !Array.isArray(record)
+                && Object.keys(record).sort().join(",") === "admissionId,eventId,friendId,reference,sessionKey"
+                && TELEGRAM_ADMISSION_ID.test(record.admissionId)
+                && boundedTelegramWorkText(record.friendId, 512)
+                && boundedTelegramWorkText(record.sessionKey, 1_024)
+                && TELEGRAM_SESSION_EVENT_ID.test(record.eventId)
+                && record.reference === `telegram-admission:${record.admissionId}`;
+            const validIndeterminateAdmitted = (record) => {
+                if (!record || typeof record !== "object" || Array.isArray(record)
+                    || Object.keys(record).sort().join(",") !== "admissionId,eventId,friendId,quarantinedAt,reference,sessionKey")
+                    return false;
+                const { quarantinedAt, ...work } = record;
+                return Number.isSafeInteger(quarantinedAt) && quarantinedAt >= 0 && validAdmitted(work);
+            };
+            if (value.version === 5) {
+                if (Object.keys(value).sort().join(",") !== "admittedDispatching,admittedIndeterminate,admittedPending,admittedSettled,dispatching,indeterminate,pending,settled,version"
+                    || !Array.isArray(value.pending) || !Array.isArray(value.dispatching) || !Array.isArray(value.indeterminate) || !Array.isArray(value.settled)
+                    || !Array.isArray(value.admittedPending) || !Array.isArray(value.admittedDispatching)
+                    || !Array.isArray(value.admittedSettled) || !Array.isArray(value.admittedIndeterminate)
+                    || !value.pending.every(validReceipt) || !value.dispatching.every(validReceipt) || !value.settled.every(validReceipt)
+                    || !value.indeterminate.every(validIndeterminate)
+                    || !value.admittedPending.every(validAdmitted) || !value.admittedDispatching.every(validAdmitted)
+                    || !value.admittedSettled.every(validAdmitted) || !value.admittedIndeterminate.every(validIndeterminateAdmitted)) {
+                    throw new Error("invalid bounded inbox shape");
+                }
+                const state = structuredClone(value);
+                const timestamp = this.timestamp();
+                const prunedUpdates = this.prune(state.indeterminate, timestamp);
+                const prunedAdmitted = state.admittedIndeterminate
+                    .filter((work) => work.quarantinedAt >= timestamp - this.indeterminateRetentionMs)
+                    .sort((left, right) => left.quarantinedAt - right.quarantinedAt || left.admissionId.localeCompare(right.admissionId))
+                    .slice(-this.maxIndeterminateReceipts);
+                if (prunedUpdates.length !== state.indeterminate.length || prunedAdmitted.length !== state.admittedIndeterminate.length) {
+                    state.indeterminate = prunedUpdates;
+                    state.admittedIndeterminate = prunedAdmitted;
+                    this.write(state);
+                }
+                return state;
+            }
             if (value.version === 4) {
                 if (Object.keys(value).sort().join(",") !== "dispatching,indeterminate,pending,settled,version"
                     || !Array.isArray(value.pending) || !Array.isArray(value.dispatching) || !Array.isArray(value.indeterminate)
@@ -155,12 +201,17 @@ class FileTelegramUpdateInboxStore {
                     || !value.settled.every(validReceipt)
                     || !value.indeterminate.every(validIndeterminate))
                     throw new Error("invalid bounded inbox shape");
-                const state = structuredClone(value);
+                const state = {
+                    ...structuredClone(value),
+                    version: 5,
+                    admittedPending: [],
+                    admittedDispatching: [],
+                    admittedSettled: [],
+                    admittedIndeterminate: [],
+                };
                 const pruned = this.prune(state.indeterminate, this.timestamp());
-                if (pruned.length !== state.indeterminate.length) {
-                    state.indeterminate = pruned;
-                    this.write(state);
-                }
+                state.indeterminate = pruned;
+                this.write(state);
                 return state;
             }
             if (value.version === 3) {
@@ -171,11 +222,12 @@ class FileTelegramUpdateInboxStore {
                     throw new Error("invalid bounded inbox shape");
                 const timestamp = this.timestamp();
                 const migrated = {
-                    version: 4,
+                    version: 5,
                     pending: structuredClone(value.pending),
                     dispatching: structuredClone(value.dispatching),
                     settled: [],
                     indeterminate: this.prune(structuredClone(value.indeterminate), timestamp),
+                    admittedPending: [], admittedDispatching: [], admittedSettled: [], admittedIndeterminate: [],
                 };
                 this.write(migrated);
                 return migrated;
@@ -190,7 +242,7 @@ class FileTelegramUpdateInboxStore {
                     throw new Error("invalid opaque inbox receipt");
                 const timestamp = this.timestamp();
                 const migrated = {
-                    version: 4,
+                    version: 5,
                     pending: structuredClone(value.pending),
                     dispatching: structuredClone(value.dispatching),
                     settled: [],
@@ -199,6 +251,7 @@ class FileTelegramUpdateInboxStore {
                         quarantinedAt: timestamp,
                         warningAcknowledged: false,
                     })), timestamp),
+                    admittedPending: [], admittedDispatching: [], admittedSettled: [], admittedIndeterminate: [],
                 };
                 this.write(migrated);
                 return migrated;
@@ -217,7 +270,7 @@ class FileTelegramUpdateInboxStore {
                 throw new Error("invalid legacy inbox record");
             const timestamp = this.timestamp();
             const migrated = {
-                version: 4,
+                version: 5,
                 pending: [],
                 dispatching: [],
                 settled: [],
@@ -226,13 +279,17 @@ class FileTelegramUpdateInboxStore {
                     quarantinedAt: timestamp,
                     warningAcknowledged: false,
                 })), timestamp),
+                admittedPending: [], admittedDispatching: [], admittedSettled: [], admittedIndeterminate: [],
             };
             this.write(migrated);
             return migrated;
         }
         catch (error) {
             if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
-                return { version: 4, pending: [], dispatching: [], settled: [], indeterminate: [] };
+                return {
+                    version: 5, pending: [], dispatching: [], settled: [], indeterminate: [],
+                    admittedPending: [], admittedDispatching: [], admittedSettled: [], admittedIndeterminate: [],
+                };
             throw new Error("Telegram update inbox state is corrupt", { cause: error });
         }
     }
@@ -322,6 +379,94 @@ class FileTelegramUpdateInboxStore {
         state.settled = settled;
         this.write(state);
     }
+    captureAdmittedWork(work) {
+        if (!this.validAdmittedWork(work))
+            throw new Error("Telegram admitted work is invalid");
+        const state = this.read();
+        const existing = [
+            ...state.admittedPending,
+            ...state.admittedDispatching,
+            ...state.admittedSettled,
+            ...state.admittedIndeterminate,
+        ].find((candidate) => candidate.admissionId === work.admissionId);
+        if (existing) {
+            const { quarantinedAt: _quarantinedAt, ...canonical } = existing;
+            if (JSON.stringify(canonical) !== JSON.stringify(work))
+                throw new Error("Telegram admitted work has a conflicting receipt");
+            return false;
+        }
+        state.admittedPending.push(structuredClone(work));
+        this.write(state);
+        return true;
+    }
+    loadPendingAdmittedWork() {
+        return structuredClone(this.read().admittedPending);
+    }
+    claimAdmittedWork(admissionId) {
+        if (!TELEGRAM_ADMISSION_ID.test(admissionId))
+            throw new Error("Telegram admission id is invalid");
+        const state = this.read();
+        if (state.admittedDispatching.some((candidate) => candidate.admissionId === admissionId)
+            || state.admittedSettled.some((candidate) => candidate.admissionId === admissionId)
+            || state.admittedIndeterminate.some((candidate) => candidate.admissionId === admissionId))
+            return null;
+        const index = state.admittedPending.findIndex((candidate) => candidate.admissionId === admissionId);
+        if (index < 0)
+            return null;
+        const [work] = state.admittedPending.splice(index, 1);
+        state.admittedDispatching.push(work);
+        this.write(state);
+        return structuredClone(work);
+    }
+    completeAdmittedWork(admissionId) {
+        if (!TELEGRAM_ADMISSION_ID.test(admissionId))
+            throw new Error("Telegram admission id is invalid");
+        const state = this.read();
+        const index = state.admittedDispatching.findIndex((candidate) => candidate.admissionId === admissionId);
+        if (index < 0)
+            return;
+        const [work] = state.admittedDispatching.splice(index, 1);
+        state.admittedSettled.push(work);
+        state.admittedSettled = state.admittedSettled.slice(-this.maxIndeterminateReceipts);
+        this.write(state);
+    }
+    quarantineStrandedAdmittedWork() {
+        const state = this.read();
+        if (state.admittedDispatching.length === 0)
+            return [];
+        const timestamp = this.timestamp();
+        const stranded = state.admittedDispatching.map((work) => ({ ...work, quarantinedAt: timestamp }));
+        state.admittedDispatching = [];
+        state.admittedIndeterminate = [...state.admittedIndeterminate, ...stranded]
+            .filter((work) => work.quarantinedAt >= timestamp - this.indeterminateRetentionMs)
+            .sort((left, right) => left.quarantinedAt - right.quarantinedAt || left.admissionId.localeCompare(right.admissionId))
+            .slice(-this.maxIndeterminateReceipts);
+        this.write(state);
+        return stranded.map(({ quarantinedAt: _quarantinedAt, ...work }) => work);
+    }
+    admittedWorkState(admissionId) {
+        if (!TELEGRAM_ADMISSION_ID.test(admissionId))
+            throw new Error("Telegram admission id is invalid");
+        const state = this.read();
+        if (state.admittedPending.some((work) => work.admissionId === admissionId))
+            return "pending";
+        if (state.admittedDispatching.some((work) => work.admissionId === admissionId))
+            return "dispatching";
+        if (state.admittedSettled.some((work) => work.admissionId === admissionId))
+            return "settled";
+        if (state.admittedIndeterminate.some((work) => work.admissionId === admissionId))
+            return "indeterminate";
+        return null;
+    }
+    validAdmittedWork(work) {
+        return Boolean(work) && typeof work === "object" && !Array.isArray(work)
+            && Object.keys(work).sort().join(",") === "admissionId,eventId,friendId,reference,sessionKey"
+            && TELEGRAM_ADMISSION_ID.test(work.admissionId)
+            && boundedTelegramWorkText(work.friendId, 512)
+            && boundedTelegramWorkText(work.sessionKey, 1_024)
+            && TELEGRAM_SESSION_EVENT_ID.test(work.eventId)
+            && work.reference === `telegram-admission:${work.admissionId}`;
+    }
 }
 exports.FileTelegramUpdateInboxStore = FileTelegramUpdateInboxStore;
 function createTelegramLongPoll(options) {
@@ -340,7 +485,38 @@ function createTelegramLongPoll(options) {
         const chatId = message ? String(message.chat.id) : "";
         if (!message || message.chat.type !== "private" || userId !== options.expectedUserId || chatId !== options.expectedChatId || typeof message.text !== "string")
             return null;
-        return { updateId: update.update_id, messageId: String(message.message_id), userId, chatId, text: message.text };
+        return {
+            updateId: update.update_id,
+            messageId: String(message.message_id),
+            userId,
+            chatId,
+            text: message.text,
+            ...(Number.isSafeInteger(message.reply_to_message?.message_id) && message.reply_to_message.message_id > 0
+                ? { replyToMessageId: String(message.reply_to_message.message_id) }
+                : {}),
+        };
+    };
+    const unknownMessage = (update) => {
+        const message = update.message;
+        if (!options.onUnknownMessage || !options.botId || !message?.from || message.chat.type !== "private")
+            return null;
+        const userId = String(message.from.id);
+        const chatId = String(message.chat.id);
+        if (userId === options.expectedUserId && chatId === options.expectedChatId)
+            return null;
+        const displayLabel = [message.from.first_name, message.from.last_name].filter(Boolean).join(" ")
+            || (message.from.username ? `@${message.from.username}` : `Telegram user ${userId}`);
+        return {
+            updateId: update.update_id,
+            messageId: message.message_id,
+            botId: options.botId,
+            userId,
+            chatId,
+            text: message.text ?? message.caption ?? "",
+            displayLabel,
+            hasAttachments: Boolean(message.document || message.photo?.length || message.audio || message.video
+                || message.voice || message.animation || message.sticker),
+        };
     };
     const authorizedCallback = (update) => {
         const callback = update.callback_query;
@@ -349,7 +525,9 @@ function createTelegramLongPoll(options) {
             && String(callback.message.chat.id) === options.expectedChatId);
     };
     const dispatch = async (update) => {
-        const handled = await options.onUpdate?.(update) ?? false;
+        const handled = !update.callback_query || authorizedCallback(update)
+            ? await options.onUpdate?.(update) ?? false
+            : false;
         if (handled)
             return;
         const message = authorizedMessage(update);
@@ -357,6 +535,11 @@ function createTelegramLongPoll(options) {
             await options.onMessage(message);
             return;
         }
+        const stranger = unknownMessage(update);
+        if (stranger) {
+            await options.onUnknownMessage(stranger);
+            return;
+        }
         const distinctAccount = Boolean(update.message?.from && String(update.message.from.id) !== options.expectedUserId);
         (0, runtime_1.emitNervesEvent)({
             component: "senses",
@@ -399,7 +582,7 @@ function createTelegramLongPoll(options) {
                 continue;
             options.onBeforeDispatch?.();
             const next = update.update_id + 1;
-            const requiresDurableDispatch = Boolean(authorizedCallback(update) || authorizedMessage(update));
+            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)) {
@@ -833,31 +1016,14 @@ function createTelegramApprovalTransport(options) {
         if (pending.messageId === null)
             return now();
         const terminalEditStartedAt = now();
-        const base = {
-            chat_id: options.expectedChatId,
-            message_id: Number(pending.messageId),
-            reply_markup: { inline_keyboard: [] },
-        };
-        const editSignal = AbortSignal.timeout(exports.TELEGRAM_APPROVAL_TERMINAL_EDIT_TIMEOUT_MS);
         try {
             effectBarrier();
-            await options.api.request("editMessageText", { ...base, text: escapeTelegramHtml(terminalText), parse_mode: "HTML" }, editSignal);
+            await options.effects.edit({ idempotencyKey: `approval:${pending.approvalId}:edit:${(0, node_crypto_1.createHash)("sha256").update(terminalText).digest("hex")}`, chatId: options.expectedChatId, messageId: Number(pending.messageId), text: terminalText });
         }
         catch (error) {
             const alreadyTerminal = error instanceof TelegramApiError && error.status === 400 && /message is not modified/i.test(error.message);
-            if (!alreadyTerminal) {
-                if (!(error instanceof TelegramApiError) || error.status !== 400)
-                    throw error;
-                try {
-                    effectBarrier();
-                    await options.api.request("editMessageText", { ...base, text: terminalText }, editSignal);
-                }
-                catch (fallbackError) {
-                    if (!(fallbackError instanceof TelegramApiError) || fallbackError.status !== 400 || !/message is not modified/i.test(fallbackError.message)) {
-                        throw fallbackError;
-                    }
-                }
-            }
+            if (!alreadyTerminal)
+                throw error;
         }
         const terminalizedAt = now();
         if (pending.acceptanceBinding)
@@ -876,11 +1042,11 @@ function createTelegramApprovalTransport(options) {
     const acknowledge = async (callbackQueryId, invalid) => {
         try {
             effectBarrier();
-            await options.api.request("answerCallbackQuery", invalid ? {
-                callback_query_id: callbackQueryId,
-                text: "This approval is no longer valid.",
-                show_alert: true,
-            } : { callback_query_id: callbackQueryId });
+            await options.effects.acknowledge({
+                idempotencyKey: `approval-callback:${(0, node_crypto_1.createHash)("sha256").update(callbackQueryId).digest("hex")}`,
+                callbackQueryId,
+                ...(invalid ? { text: "This approval is no longer valid.", showAlert: true } : {}),
+            });
             return "acknowledged";
         }
         catch (error) {
@@ -1027,16 +1193,6 @@ function createTelegramApprovalTransport(options) {
             if (pendingByCallback.has(approveCallbackData) || pendingByCallback.has(denyCallbackData)) {
                 throw new Error("Telegram approval callback handle collision");
             }
-            const replyMarkup = { inline_keyboard: [[
-                        { text: "Approve", callback_data: approveCallbackData },
-                        { text: "Deny", callback_data: denyCallbackData },
-                    ]] };
-            const htmlBody = {
-                chat_id: options.expectedChatId,
-                text: escapeTelegramHtml(input.prompt),
-                parse_mode: "HTML",
-                reply_markup: replyMarkup,
-            };
             const pending = {
                 approvalId: input.approvalId,
                 decisionToken: input.decisionToken,
@@ -1065,26 +1221,16 @@ function createTelegramApprovalTransport(options) {
                 throw error;
             }
             try {
-                let result;
-                try {
-                    effectBarrier();
-                    result = await options.api.request("sendMessage", htmlBody);
-                }
-                catch (error) {
-                    if (!(error instanceof TelegramApiError) || error.status !== 400)
-                        throw error;
-                    effectBarrier();
-                    result = await options.api.request("sendMessage", {
-                        chat_id: options.expectedChatId,
-                        text: input.prompt,
-                        reply_markup: replyMarkup,
-                    });
-                }
-                if (!result || typeof result !== "object" || Array.isArray(result) || !("message_id" in result)
-                    || typeof result.message_id !== "number" || !Number.isSafeInteger(result.message_id) || result.message_id <= 0) {
+                effectBarrier();
+                const messageId = await options.effects.sendCard({
+                    idempotencyKey: `approval:${input.approvalId}:prompt`,
+                    chatId: options.expectedChatId,
+                    text: input.prompt,
+                    buttons: [[{ text: "Approve", callbackData: approveCallbackData }, { text: "Deny", callbackData: denyCallbackData }]],
+                });
+                if (!Number.isSafeInteger(messageId) || messageId <= 0)
                     throw new Error("Telegram sendMessage response did not include a canonical message_id");
-                }
-                pending.messageId = String(result.message_id);
+                pending.messageId = String(messageId);
                 pending.deliveryState = "bound";
                 if (input.acceptanceBinding) {
                     const boundAt = now();