@ouro.bot/cli 0.1.0-alpha.92 → 0.1.0-alpha.921

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

@@ -0,0 +1,793 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+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"));
+const node_crypto_1 = require("node:crypto");
+const friends_1 = require("@ouro.bot/friends");
+const approval_files_1 = require("../heart/approval-files");
+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");
+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 {
+        afterJournalPrepare: effectBarrier,
+        afterTokenPersist: effectBarrier,
+        afterCheckpointWrite: effectBarrier,
+    };
+}
+function telegramApprovalDecisionBarrierHooks(effectBarrier) {
+    return {
+        afterClaim: effectBarrier,
+        afterAttempt: effectBarrier,
+        afterHandler: 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)({
+            component: "senses",
+            event: "senses.telegram_approved_restart_start",
+            message: "approved Sanctuary restart execution started",
+            meta: { ...(scenarioHandleDigest ? { scenarioHandleDigest } : {}), ...(approvalId ? { approvalId } : {}) },
+        });
+    try {
+        effectBarrier();
+        const outcome = await execute(name, args);
+        if (outcome.kind !== "handler_succeeded") {
+            if (name === "unraid_restart_container")
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error", component: "senses", event: "senses.telegram_approved_restart_error",
+                    message: "approved Sanctuary restart did not complete",
+                    meta: { ...(scenarioHandleDigest ? { scenarioHandleDigest } : {}), ...(approvalId ? { approvalId } : {}), outcome: outcome.kind },
+                });
+            return outcome;
+        }
+        const result = outcome.text;
+        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 verification = data?.data && typeof data.data === "object" && !Array.isArray(data.data) ? data.data : null;
+            const after = verification?.after && typeof verification.after === "object" && !Array.isArray(verification.after) ? verification.after : null;
+            if (data?.ok !== true || verification?.verified !== true || after?.paused !== false)
+                throw new tool_approval_1.ApprovalExecutionFailedError("approved download resume was not independently verified");
+            return outcome;
+        }
+        if (name !== "unraid_restart_container")
+            return outcome;
+        let parsed;
+        try {
+            parsed = JSON.parse(result);
+        }
+        catch {
+            throw new tool_approval_1.ApprovalExecutionFailedError("approved restart returned an invalid result");
+        }
+        if (!parsed || typeof parsed !== "object" || !("ok" in parsed)) {
+            throw new tool_approval_1.ApprovalExecutionFailedError("approved restart returned an invalid result");
+        }
+        if (parsed.ok !== true) {
+            const error = parsed.error;
+            const message = error && typeof error === "object" && typeof error.message === "string"
+                ? error.message.slice(0, 240)
+                : "approved restart failed";
+            throw new tool_approval_1.ApprovalExecutionFailedError(message);
+        }
+        const data = parsed.data;
+        const container = data && typeof data === "object" ? data.container : null;
+        const validSuccess = data !== null
+            && typeof data === "object"
+            && container !== null
+            && typeof container === "object"
+            && typeof container.id === "string"
+            && container.id.length > 0
+            && typeof container.name === "string"
+            && container.name.length > 0
+            && typeof data.beforeState === "string"
+            && typeof data.afterState === "string"
+            && data.observedRestart === true
+            && data.degraded === false;
+        if (!validSuccess) {
+            throw new tool_approval_1.ApprovalExecutionFailedError("approved restart returned an invalid result");
+        }
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.telegram_approved_restart_end",
+            message: "approved Sanctuary restart execution completed",
+            meta: { ...(scenarioHandleDigest ? { scenarioHandleDigest } : {}), ...(approvalId ? { approvalId } : {}), observedRestart: true },
+        });
+        return outcome;
+    }
+    catch (error) {
+        if (name === "unraid_restart_container")
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.telegram_approved_restart_error",
+                message: "approved Sanctuary restart execution failed",
+                meta: { ...(scenarioHandleDigest ? { scenarioHandleDigest } : {}), ...(approvalId ? { approvalId } : {}), reason: error instanceof Error ? error.message.slice(0, 240) : "unknown" },
+            });
+        throw error;
+    }
+}
+function opaqueTelegramMessageBinding(subject, messageId) {
+    return `tgm_${(0, node_crypto_1.createHmac)("sha256", subject).update(`message:${messageId}`, "utf8").digest("base64url")}`;
+}
+function createTelegramApprovalRuntime(options) {
+    const effectBarrier = options.effectBarrier ?? (() => undefined);
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.telegram_approval_runtime_create",
+        message: "creating durable Telegram approval runtime",
+        meta: { agentName: options.agentName },
+    });
+    const now = options.dependencies?.now ?? Date.now;
+    const acceptanceMarker = options.dependencies?.acceptanceMarker ?? (() => (0, sanctuary_acceptance_marker_1.readSanctuaryAcceptanceMarker)(options.agentName));
+    const provider = options.dependencies?.runProvider ?? core_1.runAgent;
+    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, phase) => {
+        try {
+            if (!options.resolveLiveToolContext)
+                throw new Error("current owner authority producer is unavailable");
+            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"
+                || context.context?.friend.trustLevel !== "family" || context.context.friend.id !== relationship.actor.friendId
+                || context.currentSession?.friendId !== relationship.actor.friendId
+                || 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);
+            return {
+                providerRuntimeOverride: runtime, mcpManager,
+                toolContext: { ...context, toolSelection: selectCurrentTools(), selectCurrentTools },
+            };
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn", component: "senses", event: "senses.telegram_approval_authority_unavailable",
+                message: "current approval authority could not be reconstructed; execution remains disabled",
+                meta: { approvalId: record.approvalId, category: error instanceof Error ? error.name : "unknown" },
+            });
+            return null;
+        }
+    };
+    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()) });
+    const checkpoints = new approval_files_1.FileApprovalCheckpointStore(path.join(stateRoot, "checkpoints.json"));
+    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)({
+                component: "senses",
+                event: "telegram.callback_settled",
+                message: "Telegram approval acceptance evidence durably recorded",
+                meta,
+            });
+        }
+        else if (event === "telegram.callback_recovery_settled") {
+            await (0, runtime_1.emitNervesEventDurable)({
+                component: "senses",
+                event: "telegram.callback_recovery_settled",
+                message: "Telegram approval acceptance evidence durably recorded",
+                meta,
+            });
+        }
+        else {
+            throw new Error("Telegram durable acceptance settlement event is unsupported");
+        }
+    });
+    const coordinator = (context) => ({
+        propose: async (request) => {
+            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,
+                checkpointStore: checkpoints,
+                tokenStore: tokens,
+                proposal: {
+                    toolCallId: request.toolCall.id,
+                    toolName: request.toolCall.function.name,
+                    arguments: request.arguments,
+                    schemaDigest: request.schemaDigest,
+                    toolDigest: request.toolDigest,
+                    policyDigest: request.policyDigest,
+                    policyId: request.policyId,
+                    sessionKey: `telegram:${options.subject}`,
+                    sessionPath: context.sessionPath,
+                    baseSessionRevision: context.baseSessionRevision,
+                    checkpointDigest: "0".repeat(64),
+                    requesterId: options.subject,
+                    transport: "telegram",
+                    transportUserId: options.subject,
+                    transportChatId: options.subject,
+                    expiresAt: new Date(now() + 300_000).toISOString(),
+                    frozenAssistantMessage: request.frozenAssistantMessage,
+                    ...(ownerBinding ? { ownerBinding } : {}),
+                    ...(scenarioHandleDigest ? { scenarioHandleDigest } : {}),
+                },
+                preCallMessages: request.preCallMessages,
+                hooks: telegramApprovalCommitBarrierHooks(effectBarrier),
+            });
+            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");
+            const sent = await transport.sendApproval({
+                approvalId: committed.record.approvalId,
+                decisionToken: committed.decisionToken,
+                prompt,
+                ...(scenarioHandleDigest ? { acceptanceBinding: {
+                        scenarioHandleDigest,
+                        actionDigest,
+                        targetDigest,
+                        checkpointDigest: committed.record.checkpointDigest,
+                        suspendedSessionRevisionDigest: (0, node_crypto_1.createHash)("sha256").update(committed.record.suspendedSessionRevision, "utf8").digest("hex"),
+                    } } : {}),
+            });
+            effectBarrier();
+            store.bindPrompt({
+                approvalId: committed.record.approvalId,
+                transport: "telegram",
+                transportChatId: options.subject,
+                transportMessageId: opaqueTelegramMessageBinding(options.subject, sent.messageId),
+                expiresAt: new Date(sent.expiresAt).toISOString(),
+            });
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.telegram_approval_proposed",
+                message: "Telegram approval proposal was durably bound",
+                meta: { ...(scenarioHandleDigest ? { scenarioHandleDigest } : {}), toolName: request.toolCall.function.name },
+            });
+            return {
+                approvalId: committed.record.approvalId,
+                checkpointDigest: committed.record.checkpointDigest,
+                suspendedSessionRevision: committed.record.suspendedSessionRevision,
+            };
+        },
+    });
+    const terminalOutcome = (record) => {
+        const accepted = record.state === "succeeded";
+        return {
+            accepted,
+            terminalText: accepted
+                ? "✅ Approved — action completed"
+                : record.state === "denied"
+                    ? "❌ Denied — no action taken"
+                    : record.state === "attempted_indeterminate"
+                        ? "⚠️ Action outcome is indeterminate after restart — it was not retried"
+                        : "⚠️ Approval did not complete",
+        };
+    };
+    const continueTerminalRecord = (record, acceptanceBinding) => {
+        return (0, session_transaction_1.withSessionTurnLease)(record.sessionPath, async (lease) => {
+            const checkpoint = checkpoints.read(record.approvalId);
+            if (!checkpoint)
+                return { accepted: false, terminalText: "⚠️ Approval checkpoint is unavailable" };
+            const continuationOwnerId = `telegram-continuation-${(0, node_crypto_1.randomUUID)()}`;
+            let continuationEpoch = 0;
+            let continuationCausalEventId;
+            let continuationAuthorized = false;
+            let controlNotice;
+            const continuationCoordinator = {
+                propose: (request) => coordinator({
+                    sessionPath: record.sessionPath,
+                    baseSessionRevision: (0, session_transaction_1.readSessionTransaction)(record.sessionPath, lease).revision,
+                }).propose(request),
+            };
+            effectBarrier();
+            await (0, core_1.resumeApprovalContinuation)({
+                record,
+                checkpoint,
+                currentSessionRevision: (0, session_transaction_1.readSessionTransaction)(record.sessionPath, lease).revision,
+                sessionMessages: checkpoint.preCallMessages,
+                callbacks: {},
+                channel: "telegram",
+                claimContinuation: () => {
+                    effectBarrier();
+                    const claim = store.claimContinuation({ approvalId: record.approvalId, ownerId: continuationOwnerId });
+                    continuationEpoch = claim.record.continuationEpoch;
+                    return claim;
+                },
+                markContinuationMaterialized: () => { effectBarrier(); store.markContinuationMaterialized({ approvalId: record.approvalId, ownerId: continuationOwnerId, epoch: continuationEpoch }); },
+                markContinuationAttempted: () => { effectBarrier(); store.markContinuationAttempted({ approvalId: record.approvalId, ownerId: continuationOwnerId, epoch: continuationEpoch }); },
+                completeContinuation: () => { effectBarrier(); store.completeContinuation({ approvalId: record.approvalId, ownerId: continuationOwnerId, epoch: continuationEpoch }); },
+                runAgent: provider,
+                revalidate: async () => {
+                    const current = await currentOptions(record, "continuation");
+                    continuationAuthorized = current !== null;
+                    return current ? { ...current, ...approvalContinuationRunAgentOptions(current.toolContext, continuationCoordinator) } : null;
+                },
+                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();
+                    if (!continuationAuthorized) {
+                        controlNotice = text;
+                        (0, runtime_1.emitNervesEvent)({
+                            component: "senses", event: "senses.telegram_approval_control_only",
+                            message: "approval result will use its existing terminal control instead of an unauthorized Butler message",
+                            meta: { approvalId: record.approvalId, state: record.state },
+                        });
+                        return;
+                    }
+                    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 = {
+                            approvalId: record.approvalId,
+                            ...acceptanceBinding,
+                            deliveredAt: now(),
+                            resultDigest: (0, node_crypto_1.createHash)("sha256").update(JSON.stringify({ state: record.state, result: record.result })).digest("hex"),
+                            deliveryDigest: (0, node_crypto_1.createHash)("sha256").update(text, "utf8").digest("hex"),
+                            deliveryMessageIdDigest: (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(messageIds ?? [])).digest("hex"),
+                        };
+                        (0, runtime_1.emitNervesEvent)({
+                            component: "senses",
+                            event: "senses.telegram_approval_continuation_delivered",
+                            message: "Telegram approval continuation result was delivered",
+                            meta: { ...unsigned, evidenceMac: (0, telegram_1.sanctuaryTelegramApprovalEvidenceMac)(options.identityKey, "senses.telegram_approval_continuation_delivered", unsigned) },
+                        });
+                    }
+                },
+            });
+            return { ...terminalOutcome(record), ...(controlNotice ? { terminalText: controlNotice } : {}) };
+        });
+    };
+    transport = (0, telegram_client_1.createTelegramApprovalTransport)({
+        api: options.api,
+        effects: options.effects,
+        expectedUserId: options.authorizedUserId,
+        expectedChatId: options.authorizedChatId,
+        pendingStore,
+        createOpaqueHandle: () => (0, node_crypto_1.randomBytes)(12).toString("base64url"),
+        acceptanceEventMeta: () => {
+            const scenarioHandleDigest = acceptanceMarker()?.scenarioHandleDigest;
+            const meta = scenarioHandleDigest ? { scenarioHandleDigest } : {};
+            return meta;
+        },
+        effectBarrier,
+        signAcceptanceEvidence: (event, meta) => (0, telegram_1.sanctuaryTelegramApprovalEvidenceMac)(options.identityKey, event, meta),
+        commitAcceptanceEvidence,
+        onSettlementComplete: async (approvalId) => { tokens.remove(approvalId); },
+        acceptanceMessageIdDigest: (messageId) => (0, node_crypto_1.createHash)("sha256").update(opaqueTelegramMessageBinding(options.subject, messageId), "utf8").digest("hex"),
+        now,
+        resolveDecisionToken: async (approvalId) => tokens.get(approvalId) ?? "",
+        onExpire: async (approvalId) => {
+            effectBarrier();
+            store.expire({ approvalId });
+            effectBarrier();
+            tokens.remove(approvalId);
+        },
+        onDecision: async (decision) => {
+            effectBarrier();
+            const decisionScenarioDigest = acceptanceMarker()?.scenarioHandleDigest;
+            const existing = store.read(decision.approvalId);
+            if (!existing)
+                return { accepted: false, terminalText: "⚠️ Approval is no longer valid" };
+            let record;
+            if (existing.state === "claimed") {
+                effectBarrier();
+                record = (0, tool_approval_1.recoverClaimedApproval)({ approvalStore: store, approvalId: existing.approvalId, reason: "decision interrupted before action attempt; action was not executed" });
+            }
+            else if (existing.state === "attempted") {
+                effectBarrier();
+                record = (0, tool_approval_1.recoverAttemptedApproval)({ approvalStore: store, approvalId: existing.approvalId });
+            }
+            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,
+                    checkpointStore: checkpoints,
+                    decision: {
+                        ...decision,
+                        requesterId: options.subject,
+                        transportUserId: options.subject,
+                        transportChatId: options.subject,
+                        transportMessageId: opaqueTelegramMessageBinding(options.subject, decision.transportMessageId),
+                        sessionKey: existing.sessionKey,
+                    },
+                    ownerId,
+                    currentSessionRevision: () => (0, session_transaction_1.readSessionTransaction)(existing.sessionPath, lease).revision,
+                    resolveTool: async (name) => {
+                        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, "decision");
+                        return current ? (0, tools_1.approvalPolicyForInvocation)(name, args, current.toolContext) : { kind: "not_required" };
+                    },
+                    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, "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, restartApproval));
+                        return result.kind === "ready" ? { ok: true } : { ok: false, reason: result.text };
+                    },
+                    hooks: telegramApprovalDecisionBarrierHooks(effectBarrier),
+                    execute: async (name, args) => {
+                        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, 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)
+                            : execute();
+                    },
+                }));
+            }
+            else if (["succeeded", "failed", "attempted_indeterminate", "denied", "expired", "drifted", "session_head_changed", "abandoned_before_attempt"].includes(existing.state)) {
+                record = existing;
+            }
+            else {
+                return { accepted: false, terminalText: "⚠️ Approval is not recoverable" };
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.telegram_approval_terminal",
+                message: "Telegram approval reached a terminal decision state",
+                meta: { state: record.state, ...(decisionScenarioDigest ? { scenarioHandleDigest: decisionScenarioDigest } : {}) },
+            });
+            return continueTerminalRecord(record, decision.acceptanceBinding);
+        },
+    });
+    const recover = async () => {
+        let failureCount = 0;
+        let fencedFailure;
+        for (const pending of transport.listPendingDeliveries()) {
+            let persistedState;
+            try {
+                persistedState = (0, telegram_client_1.classifyTelegramPersistedApprovalState)(pending);
+            }
+            catch (error) {
+                failureCount += 1;
+                fencedFailure ??= error;
+                continue;
+            }
+            const mustFailClosed = persistedState === "decision_attempt" || persistedState === "action_terminal";
+            try {
+                const existing = store.read(pending.approvalId);
+                if (!existing) {
+                    if (mustFailClosed)
+                        throw new Error("Telegram fenced approval journal is unavailable");
+                    const orphanRecovery = await transport.terminalizeOrphaned(pending.approvalId, "⚠️ Approval record is unavailable — the action outcome is unknown and will not be retried");
+                    (0, runtime_1.emitNervesEvent)({
+                        component: "senses",
+                        event: "senses.telegram_approval_orphan_recovered",
+                        message: "orphaned Telegram approval transport state was removed",
+                        meta: {
+                            agentName: options.agentName,
+                            recovery: "missing_journal",
+                            terminalEditSucceeded: orphanRecovery.terminalEditSucceeded,
+                        },
+                    });
+                    continue;
+                }
+                if (mustFailClosed) {
+                    await transport.recoverDecisionAttempt(pending.approvalId);
+                    continue;
+                }
+                if (persistedState === "expiry_observed") {
+                    await transport.reconcileExpired();
+                    continue;
+                }
+                if (persistedState === "delivery_interruption") {
+                    await transport.terminalizeRecovered(pending.approvalId, pending.terminal.terminalText);
+                    continue;
+                }
+                const deliveryState = pending.deliveryState ?? "bound";
+                if (existing.state === "awaiting_prompt_binding" && deliveryState !== "bound") {
+                    effectBarrier();
+                    const record = store.abandonPromptBinding({
+                        approvalId: existing.approvalId,
+                        reason: deliveryState === "pending"
+                            ? "approval prompt was interrupted before delivery; action was not executed"
+                            : "approval prompt delivery was indeterminate; action was not executed",
+                    });
+                    const outcome = await continueTerminalRecord(record);
+                    await transport.terminalizeRecovered(record.approvalId, outcome.terminalText);
+                    continue;
+                }
+                if (existing.state === "awaiting_prompt_binding" && deliveryState === "bound" && pending.messageId) {
+                    effectBarrier();
+                    store.bindPrompt({
+                        approvalId: existing.approvalId,
+                        transport: "telegram",
+                        transportChatId: options.subject,
+                        transportMessageId: opaqueTelegramMessageBinding(options.subject, pending.messageId),
+                    });
+                    continue;
+                }
+                if (existing.state === "proposed" || existing.state === "preparing" || existing.state === "awaiting_prompt_binding")
+                    continue;
+                if (existing.state === "expired" && !pending.terminal) {
+                    await transport.reconcileExpired();
+                    continue;
+                }
+                let record = existing;
+                if (record.state === "claimed") {
+                    effectBarrier();
+                    record = (0, tool_approval_1.recoverClaimedApproval)({ approvalStore: store, approvalId: record.approvalId, reason: "decision interrupted before action attempt; action was not executed" });
+                }
+                else if (record.state === "attempted") {
+                    effectBarrier();
+                    record = (0, tool_approval_1.recoverAttemptedApproval)({ approvalStore: store, approvalId: record.approvalId });
+                }
+                const outcome = await continueTerminalRecord(record);
+                await transport.terminalizeRecovered(record.approvalId, outcome.terminalText);
+            }
+            catch (error) {
+                failureCount += 1;
+                if (mustFailClosed)
+                    fencedFailure ??= error;
+            }
+        }
+        if (failureCount > 0) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.telegram_approval_recovery_error",
+                message: "Telegram approval startup recovery completed with isolated failures",
+                meta: { failureCount },
+            });
+        }
+        if (fencedFailure !== undefined)
+            throw fencedFailure;
+    };
+    const legacySubjects = () => (store.listTelegramIdentitySubjects?.() ?? [])
+        .filter((candidate) => candidate !== options.subject);
+    const migrateIdentity = (subjects) => {
+        for (const legacySubject of subjects) {
+            effectBarrier();
+            store.migrateTelegramIdentity?.({
+                legacyUserId: legacySubject,
+                legacyChatId: legacySubject,
+                subject: options.subject,
+            });
+        }
+        effectBarrier();
+        store.migrateTelegramIdentity?.({
+            legacyUserId: options.authorizedUserId,
+            legacyChatId: options.authorizedChatId,
+            subject: options.subject,
+        });
+    };
+    const isPendingTerminalControl = async (input) => {
+        if (input.authorClass !== "control")
+            return false;
+        const effect = input.effect;
+        for (const pending of transport.listPendingDeliveries()) {
+            const record = store.read(pending.approvalId);
+            if (!record || !pending.messageId || record.transport !== "telegram"
+                || record.requesterId !== options.subject || record.transportUserId !== options.subject
+                || record.transportChatId !== options.subject || record.sessionKey !== `telegram:${options.subject}`
+                || record.transportMessageId !== opaqueTelegramMessageBinding(options.subject, pending.messageId)
+                || !["succeeded", "failed", "attempted_indeterminate", "denied", "expired", "drifted", "session_head_changed", "abandoned_before_attempt"].includes(record.state)
+                || (pending.terminal && pending.terminal.accepted !== (record.state === "succeeded")))
+                continue;
+            let matches = false;
+            if (effect.kind === "callback_ack") {
+                const digest = (0, node_crypto_1.createHash)("sha256").update(effect.callbackQueryId).digest("hex");
+                matches = Boolean(pending.terminal && effect.text === undefined && effect.showAlert !== true
+                    && pending.decisionAttempt?.queryIdDigest === digest && input.idempotencyKey === `approval-callback:${digest}`);
+            }
+            else if (effect.kind === "edit") {
+                const terminalText = pending.terminal?.terminalText
+                    ?? (record.state === "expired" && pending.expiryObservation?.deadlineAt === pending.expiresAt
+                        && pending.expiryObservation.observedAt >= pending.expiresAt ? telegram_client_1.TELEGRAM_APPROVAL_EXPIRED_TEXT : undefined);
+                matches = terminalText !== undefined && effect.text === terminalText && effect.messageId === Number(pending.messageId)
+                    && input.idempotencyKey === `approval:${pending.approvalId}:edit:${(0, node_crypto_1.createHash)("sha256").update(terminalText).digest("hex")}`;
+            }
+            if (!matches)
+                continue;
+            await transport.validatePendingTerminalControl(pending.approvalId);
+            return true;
+        }
+        return false;
+    };
+    return { transport, coordinator, legacySubjects, migrateIdentity, recover, isPendingTerminalControl, close: () => store.close() };
+}