@ouro.bot/cli 0.1.0-alpha.816 → 0.1.0-alpha.818

package/dist/senses/root-host-approval-runtime.js

@@ -0,0 +1,393 @@
+"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.FileRootHostPendingApprovalStore = void 0;
+exports.classifyRootHostPendingApproval = classifyRootHostPendingApproval;
+exports.createRootHostApprovalRuntime = createRootHostApprovalRuntime;
+const path = __importStar(require("node:path"));
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_util_1 = require("node:util");
+const friends_1 = require("@ouro.bot/friends");
+const core_1 = require("../heart/core");
+const tool_approval_1 = require("../heart/tool-approval");
+const context_1 = require("../mind/context");
+const session_transaction_1 = require("../mind/session-transaction");
+const runtime_1 = require("../nerves/runtime");
+const mcp_manager_1 = require("../repertoire/mcp-manager");
+const tool_arguments_1 = require("../repertoire/tool-arguments");
+const tools_1 = require("../repertoire/tools");
+const tools_sanctuary_host_1 = require("../repertoire/tools-sanctuary-host");
+const shared_turn_1 = require("./shared-turn");
+class RootHostPendingApprovalError extends Error {
+}
+function requireValid(condition) {
+    if (!condition)
+        throw new RootHostPendingApprovalError("Root host pending approval is invalid");
+}
+function exact(value, keys) {
+    requireValid(value !== null && typeof value === "object" && !Array.isArray(value));
+    requireValid((0, node_util_1.isDeepStrictEqual)(Object.keys(value).sort(), keys.sort()));
+}
+function validate(value) {
+    exact(value, ["schemaVersion", "approvalId", "registration", "binding", "checkpoint", "executionRequested", "continuationState", "materializedSessionRevision", "rootStatusDigest", "reconciliationRequired"]);
+    requireValid(value.schemaVersion === 1 && typeof value.approvalId === "string" && /^root-host-[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/u.test(value.approvalId));
+    requireValid(typeof value.executionRequested === "boolean" && typeof value.reconciliationRequired === "boolean"
+        && typeof value.continuationState === "string" && ["pending", "materialized", "attempted", "complete"].includes(value.continuationState));
+    requireValid(value.rootStatusDigest === null || (typeof value.rootStatusDigest === "string" && /^sha256:[a-f0-9]{64}$/u.test(value.rootStatusDigest)));
+    requireValid(value.materializedSessionRevision === null || (typeof value.materializedSessionRevision === "string" && /^[a-f0-9]{64}$/u.test(value.materializedSessionRevision)));
+    requireValid((value.continuationState !== "materialized" && value.continuationState !== "attempted") || value.materializedSessionRevision !== null);
+    requireValid(value.continuationState !== "pending" || value.materializedSessionRevision === null);
+    exact(value.registration, ["registration", "registrationId", "telegramMessageId", "expiresAt"]);
+    requireValid(typeof value.registration.registrationId === "string" && /^hostreg-[A-Za-z0-9_-]{43}$/u.test(value.registration.registrationId)
+        && Number.isSafeInteger(value.registration.telegramMessageId) && value.registration.telegramMessageId > 0
+        && typeof value.registration.expiresAt === "string" && Number.isFinite(Date.parse(value.registration.expiresAt)));
+    exact(value.registration.registration, ["schemaVersion", "domain", "keyId", "payload", "signature"]);
+    const artifact = value.registration.registration;
+    requireValid(artifact.schemaVersion === 1 && artifact.domain === "ouro.sanctuary.host-registration.v1"
+        && typeof artifact.keyId === "string" && artifact.keyId.length > 0 && typeof artifact.signature === "string" && artifact.signature.length > 0
+        && artifact.payload !== null && typeof artifact.payload === "object" && !Array.isArray(artifact.payload));
+    exact(value.binding, ["agentRoot", "friendId", "requestId", "sessionKey", "sessionPath", "sessionEventId", "profileId", "profileVersion", "keyId", "publicKeyDigest", "targetHost"]);
+    const binding = value.binding;
+    requireValid(binding.profileId === "sanctuary-owner" && Number.isSafeInteger(binding.profileVersion) && binding.profileVersion >= 9);
+    requireValid(Object.entries(binding).every(([key, item]) => key === "profileVersion" || (typeof item === "string" && item.length > 0 && item.length <= 4096)));
+    requireValid(/^sha256:[a-f0-9]{64}$/u.test(binding.publicKeyDigest));
+    validateCheckpoint(value.checkpoint, value.approvalId, binding.targetHost);
+}
+function validateCheckpoint(value, approvalId, targetHost) {
+    exact(value, ["approvalId", "checkpointDigest", "baseSessionRevision", "suspendedSessionRevision", "argumentDigest", "schemaDigest", "toolDigest", "policyDigest", "preCallDigest", "preCallMessages", "frozenAssistantMessage"]);
+    const c = value;
+    requireValid(c.approvalId === approvalId && Array.isArray(c.preCallMessages));
+    requireValid(c.preCallMessages.every((message) => message !== null && typeof message === "object"
+        && ["system", "developer", "user", "assistant", "tool", "function"].includes(message.role)));
+    requireValid(["checkpointDigest", "baseSessionRevision", "suspendedSessionRevision", "argumentDigest", "schemaDigest", "toolDigest", "policyDigest", "preCallDigest"]
+        .every((key) => typeof c[key] === "string" && /^[a-f0-9]{64}$/u.test(String(c[key]))));
+    requireValid(c.preCallDigest === (0, tool_arguments_1.digestJson)(c.preCallMessages) && c.checkpointDigest === (0, tool_approval_1.digestApprovalSuspensionCheckpointPayload)(c));
+    requireValid(c.suspendedSessionRevision === c.baseSessionRevision);
+    requireValid(c.frozenAssistantMessage !== null && typeof c.frozenAssistantMessage === "object" && !Array.isArray(c.frozenAssistantMessage));
+    const calls = c.frozenAssistantMessage.tool_calls;
+    requireValid(Array.isArray(calls) && calls.length === 1);
+    exact(calls[0], ["id", "type", "function"]);
+    requireValid(c.frozenAssistantMessage.role === "assistant" && calls[0].type === "function" && typeof calls[0].id === "string" && calls[0].id.length > 0);
+    exact(calls[0].function, ["name", "arguments"]);
+    requireValid(calls[0].function.name === "sanctuary_host_execute" && typeof calls[0].function.arguments === "string");
+    const args = JSON.parse(calls[0].function.arguments);
+    requireValid((0, tool_arguments_1.digestJson)(args) === c.argumentDigest);
+    (0, tools_sanctuary_host_1.validateRootHostToolArguments)(args, targetHost);
+}
+function checkDefinition(checkpoint, definition) {
+    const args = JSON.parse(checkpoint.frozenAssistantMessage.tool_calls[0].function.arguments);
+    const policy = definition.approvalPolicy?.(args);
+    requireValid(policy?.kind === "required");
+    requireValid(checkpoint.schemaDigest === (0, tool_arguments_1.digestJson)(definition.tool.function.parameters));
+    requireValid(checkpoint.toolDigest === (0, tool_approval_1.digestApprovalToolDefinition)(definition, checkpoint.schemaDigest, policy.policyId));
+    requireValid(checkpoint.policyDigest === (0, tool_arguments_1.digestJson)({ policyId: policy.policyId, actionClass: policy.actionClass, classification: "required" }));
+    return policy;
+}
+function classifyRootHostPendingApproval(value) {
+    validate(value);
+    if (value.continuationState !== "pending")
+        return value.continuationState;
+    if (value.reconciliationRequired)
+        return "reconciliation_required";
+    return value.executionRequested ? "executing" : "pending";
+}
+class FileRootHostPendingApprovalStore {
+    filePath;
+    constructor(agentRoot) { this.filePath = path.join(agentRoot, "state", "root-host-approvals", "v1", "pending.json"); }
+    list() {
+        return (0, session_transaction_1.withImmediateSessionTurnLease)(this.filePath, (lease) => {
+            const transaction = (0, session_transaction_1.readSessionTransaction)(this.filePath, lease);
+            if (!transaction.bytes) {
+                requireValid(!(0, node_fs_1.existsSync)(this.filePath));
+                return [];
+            }
+            exact(transaction.value, ["schemaVersion", "records"]);
+            requireValid(transaction.value.schemaVersion === 1 && Array.isArray(transaction.value.records));
+            const records = transaction.value.records;
+            records.forEach(validate);
+            requireValid(new Set(records.map((record) => record.approvalId)).size === records.length
+                && new Set(records.map((record) => record.registration.registrationId)).size === records.length
+                && new Set(records.map((record) => record.registration.telegramMessageId)).size === records.length);
+            return structuredClone(records);
+        });
+    }
+    put(record) {
+        validate(record);
+        (0, session_transaction_1.withImmediateSessionTurnLease)(this.filePath, (lease) => {
+            const revision = (0, session_transaction_1.readSessionTransaction)(this.filePath, lease).revision;
+            const records = this.list();
+            const previous = records.find((item) => item.approvalId === record.approvalId);
+            if (previous) {
+                requireValid((0, node_util_1.isDeepStrictEqual)(previous.binding, record.binding) && (0, node_util_1.isDeepStrictEqual)(previous.registration, record.registration)
+                    && (0, node_util_1.isDeepStrictEqual)(previous.checkpoint, record.checkpoint));
+                const phases = ["pending", "materialized", "attempted", "complete"];
+                requireValid(phases.indexOf(record.continuationState) >= phases.indexOf(previous.continuationState)
+                    && (!previous.executionRequested || record.executionRequested)
+                    && (previous.materializedSessionRevision === null || previous.materializedSessionRevision === record.materializedSessionRevision));
+                Object.assign(previous, structuredClone(record));
+            }
+            else {
+                requireValid(!records.some((item) => item.registration.registrationId === record.registration.registrationId
+                    || item.registration.telegramMessageId === record.registration.telegramMessageId));
+                records.push(structuredClone(record));
+            }
+            (0, session_transaction_1.writeSessionTransaction)(this.filePath, { schemaVersion: 1, records }, { lease, expectedRevision: revision });
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.root_host_pending_saved", message: "root host continuation checkpoint saved", meta: { approvalId: record.approvalId, state: classifyRootHostPendingApproval(record) } });
+        });
+    }
+}
+exports.FileRootHostPendingApprovalStore = FileRootHostPendingApprovalStore;
+function terminalProjection(record, status) {
+    const call = record.checkpoint.frozenAssistantMessage.tool_calls[0];
+    const common = { approvalId: record.approvalId, toolCallId: call.id };
+    if (status.state === "denied" || status.state === "expired")
+        return { ...common, state: status.state, result: null };
+    if (status.state !== "executed")
+        return null;
+    requireValid(status.receipt && status.permit);
+    const state = status.receipt.payload.state;
+    requireValid(state === "verified" || state === "failed" || state === "ambiguous");
+    requireValid(status.receipt.payload.cleanup === "cgroup_empty");
+    return { ...common, state: state === "verified" ? "succeeded" : state === "failed" ? "failed" : "attempted_indeterminate", result: JSON.stringify(status.receipt) };
+}
+function correlation(record) {
+    const b = record.binding;
+    return {
+        registrationId: record.registration.registrationId, residentFriendId: b.friendId,
+        relationshipProfileId: b.profileId, relationshipProfileVersion: b.profileVersion, requestId: b.requestId,
+        sessionKey: b.sessionKey, sessionEventId: b.sessionEventId, residentApprovalId: record.approvalId, stewardPolicy: null,
+    };
+}
+function createRootHostApprovalRuntime(options) {
+    const store = new FileRootHostPendingApprovalStore(options.agentRoot);
+    const port = options.port;
+    const barrier = options.effectBarrier ?? (() => undefined);
+    const readStatus = async (record) => {
+        const status = await port.status(record.registration);
+        if (status.permit)
+            requireValid(Object.entries(correlation(record)).every(([key, value]) => (0, node_util_1.isDeepStrictEqual)(status.permit.payload[key], value)));
+        return status;
+    };
+    const current = async (record) => {
+        requireValid(record.binding.agentRoot === options.agentRoot);
+        if (!await port.refresh())
+            throw new Error("Root host authority is unavailable");
+        const context = await options.resolveContext(record.binding);
+        requireValid(context.rootHost?.port === port);
+        await (0, tools_sanctuary_host_1.authorizeRootHostContext)(context, record.binding);
+        const owner = { agentName: "sanctuary", agentRoot: options.agentRoot };
+        const runtime = await (options.dependencies?.getProviderRuntime ?? core_1.getProviderRuntime)("human", owner);
+        const mcp = await (options.dependencies?.getMcp ?? mcp_manager_1.getSharedMcpManager)(owner) ?? undefined;
+        if (!port.isHealthy() && !await port.refresh())
+            throw new Error("Root host authority is unavailable");
+        const select = () => (0, tools_1.selectToolsForChannel)((0, friends_1.getChannelCapabilities)("telegram"), context.context?.friend.toolPreferences, context.context, runtime.capabilities, mcp, runtime.model, context);
+        const toolContext = { ...context, toolSelection: select(), selectCurrentTools: select };
+        const call = record.checkpoint.frozenAssistantMessage.tool_calls[0];
+        requireValid(call.type === "function");
+        const args = JSON.parse(call.function.arguments);
+        const preflight = await (0, tools_1.preflightToolCall)("sanctuary_host_execute", args, toolContext);
+        if (preflight.kind === "rejected_before_handler" && preflight.error && !(preflight.error instanceof tools_sanctuary_host_1.RootHostAuthorizationError))
+            throw preflight.error;
+        requireValid(preflight.kind === "ready" && preflight.definition);
+        checkDefinition(record.checkpoint, preflight.definition);
+        const proposed = (0, tools_sanctuary_host_1.validateRootHostToolArguments)(args, record.binding.targetHost);
+        for (const [key, value] of Object.entries(proposed))
+            requireValid((0, node_util_1.isDeepStrictEqual)(record.registration.registration.payload[key], value));
+        return { toolContext, providerRuntimeOverride: runtime, mcpManager: mcp };
+    };
+    const coordinator = (context) => ({
+        async propose(request) {
+            barrier();
+            const live = request.liveToolContext;
+            const { liveToolContext: _live, ...proposal } = request;
+            request = structuredClone(proposal);
+            requireValid(live?.rootHost?.port === port && request.toolCall.type === "function" && request.toolCall.function.name === "sanctuary_host_execute");
+            requireValid(live.currentSession?.sessionPath === context.sessionPath && live.agentRoot === options.agentRoot);
+            const binding = await (0, tools_sanctuary_host_1.authorizeRootHostContext)(live);
+            const preflight = await (0, tools_1.preflightToolCall)("sanctuary_host_execute", request.arguments, live);
+            requireValid(preflight.kind === "ready" && preflight.definition);
+            requireValid((0, session_transaction_1.withImmediateSessionTurnLease)(context.sessionPath, (lease) => (0, session_transaction_1.readSessionTransaction)(context.sessionPath, lease).revision) === context.baseSessionRevision);
+            const args = (0, tools_sanctuary_host_1.validateRootHostToolArguments)(request.arguments, binding.targetHost);
+            const approvalId = `root-host-${(0, node_crypto_1.randomUUID)()}`;
+            const draft = {
+                approvalId, baseSessionRevision: context.baseSessionRevision, argumentDigest: (0, tool_arguments_1.digestJson)(request.arguments),
+                schemaDigest: request.schemaDigest, toolDigest: request.toolDigest, policyDigest: request.policyDigest,
+                preCallDigest: (0, tool_arguments_1.digestJson)(request.preCallMessages), preCallMessages: structuredClone(request.preCallMessages),
+                frozenAssistantMessage: structuredClone(request.frozenAssistantMessage),
+            };
+            const checkpoint = { ...draft, suspendedSessionRevision: context.baseSessionRevision, checkpointDigest: (0, tool_approval_1.digestApprovalSuspensionCheckpointPayload)(draft) };
+            validateCheckpoint(checkpoint, approvalId, binding.targetHost);
+            requireValid((0, node_util_1.isDeepStrictEqual)(request.frozenAssistantMessage.tool_calls[0], request.toolCall));
+            const policy = checkDefinition(checkpoint, preflight.definition);
+            requireValid(request.policyId === policy.policyId && request.actionClass === policy.actionClass);
+            const observation = live.rootHost.observation;
+            barrier();
+            const registration = await port.register({ ...args, ownerObservation: {
+                    digest: observation.observationDigest, updateId: observation.updateId, userId: observation.userId, chatId: observation.chatId, messageId: observation.messageId,
+                } });
+            await (0, tools_sanctuary_host_1.authorizeRootHostContext)(live);
+            requireValid((0, session_transaction_1.withImmediateSessionTurnLease)(context.sessionPath, (lease) => (0, session_transaction_1.readSessionTransaction)(context.sessionPath, lease).revision) === context.baseSessionRevision);
+            barrier();
+            store.put({ schemaVersion: 1, approvalId, registration, binding, checkpoint, executionRequested: false, continuationState: "pending", materializedSessionRevision: null, rootStatusDigest: null, reconciliationRequired: false });
+            return { approvalId, checkpointDigest: checkpoint.checkpointDigest, suspendedSessionRevision: checkpoint.suspendedSessionRevision };
+        },
+    });
+    const reconcile = async (initial) => {
+        // Never choose a filesystem path from an unvalidated persisted binding.
+        requireValid(initial.binding.agentRoot === options.agentRoot
+            && initial.binding.sessionPath === (0, shared_turn_1.getSenseSessionPath)("sanctuary", initial.binding.friendId, "telegram", initial.binding.sessionKey, options.agentRoot));
+        await (0, session_transaction_1.withSessionTurnLease)(initial.binding.sessionPath, async (lease) => {
+            const record = store.list().find((item) => item.approvalId === initial.approvalId);
+            if (record.continuationState === "complete")
+                return;
+            barrier();
+            let status = await readStatus(record);
+            record.rootStatusDigest = status.statusDigest;
+            if (status.state === "approved" && !record.executionRequested) {
+                await current(record);
+                requireValid((0, session_transaction_1.readSessionTransaction)(record.binding.sessionPath, lease).revision === record.checkpoint.suspendedSessionRevision);
+                record.executionRequested = true;
+                barrier();
+                store.put(record);
+                try {
+                    await port.execute(correlation(record));
+                }
+                catch {
+                    record.reconciliationRequired = true;
+                    store.put(record);
+                    return;
+                }
+                status = await readStatus(record);
+                record.rootStatusDigest = status.statusDigest;
+            }
+            record.reconciliationRequired = status.execution === "reconciliation_required" || (record.executionRequested && status.state === "approved");
+            barrier();
+            store.put(record);
+            const terminal = terminalProjection(record, status);
+            if (!terminal)
+                return;
+            const expectedRevision = record.materializedSessionRevision ?? record.checkpoint.suspendedSessionRevision;
+            if (record.continuationState === "attempted"
+                || (0, session_transaction_1.readSessionTransaction)(record.binding.sessionPath, lease).revision !== expectedRevision) {
+                record.continuationState = "complete";
+                barrier();
+                store.put(record);
+                (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.root_host_terminal_control", message: "root outcome retained without retrying an attempted or superseded continuation", meta: { approvalId: record.approvalId } });
+                return;
+            }
+            try {
+                await current(record);
+                requireValid((0, session_transaction_1.readSessionTransaction)(record.binding.sessionPath, lease).revision === expectedRevision);
+            }
+            catch (error) {
+                if (!(error instanceof tools_sanctuary_host_1.RootHostAuthorizationError) && !(error instanceof RootHostPendingApprovalError))
+                    throw error;
+                record.continuationState = "complete";
+                barrier();
+                store.put(record);
+                (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.root_host_authority_control", message: "root terminal outcome retained without a continuation because current owner authority changed", meta: { approvalId: record.approvalId, state: terminal.state } });
+                return;
+            }
+            let authorized = false;
+            const continuationCoordinator = {
+                propose: (request) => (options.approvalCoordinatorFactory ?? coordinator)({
+                    sessionPath: record.binding.sessionPath, baseSessionRevision: (0, session_transaction_1.readSessionTransaction)(record.binding.sessionPath, lease).revision,
+                }).propose(request),
+            };
+            await (0, core_1.resumeApprovalContinuation)({
+                record: terminal, checkpoint: record.checkpoint, currentSessionRevision: (0, session_transaction_1.readSessionTransaction)(record.binding.sessionPath, lease).revision,
+                sessionMessages: record.continuationState === "pending" ? record.checkpoint.preCallMessages : (0, context_1.loadSession)(record.binding.sessionPath).messages,
+                callbacks: {}, channel: "telegram",
+                claimContinuation: () => ({ claimed: true, interruptedAfterAttempt: false, record: { continuationState: record.continuationState === "materialized" ? "materialized" : "claimed" } }),
+                markContinuationMaterialized: () => { barrier(); record.materializedSessionRevision = (0, session_transaction_1.readSessionTransaction)(record.binding.sessionPath, lease).revision; record.continuationState = "materialized"; store.put(record); },
+                markContinuationAttempted: () => { barrier(); record.continuationState = "attempted"; store.put(record); },
+                completeContinuation: () => { barrier(); record.continuationState = "complete"; store.put(record); },
+                runAgent: options.dependencies?.runProvider ?? core_1.runAgent,
+                revalidate: async () => {
+                    try {
+                        const live = await current(record);
+                        requireValid((0, session_transaction_1.readSessionTransaction)(record.binding.sessionPath, lease).revision === record.materializedSessionRevision);
+                        authorized = true;
+                        return { ...live, approvalCoordinator: continuationCoordinator };
+                    }
+                    catch (error) {
+                        if (!(error instanceof tools_sanctuary_host_1.RootHostAuthorizationError) && !(error instanceof RootHostPendingApprovalError))
+                            throw error;
+                        return null;
+                    }
+                },
+                persist: (messages, result) => { barrier(); (0, context_1.saveSession)(record.binding.sessionPath, messages, result?.usage, undefined, lease); },
+                deliver: async (text) => {
+                    barrier();
+                    if (authorized)
+                        await options.deliver(text, record.approvalId);
+                    else
+                        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.root_host_terminal_control", message: "root owns the terminal host approval card; no unauthorized resident message was sent", meta: { approvalId: record.approvalId, state: terminal.state } });
+                },
+            });
+        });
+    };
+    const recover = async (registrationId) => {
+        for (const record of store.list()) {
+            if (record.continuationState === "complete" || (registrationId && registrationId !== record.registration.registrationId))
+                continue;
+            try {
+                await reconcile(record);
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.root_host_reconciliation_required", message: "root host continuation remains pending reconciliation", meta: { approvalId: record.approvalId, category: error instanceof Error ? error.name : "unknown" } });
+            }
+        }
+    };
+    return {
+        coordinator,
+        recover: () => recover(),
+        async handleUpdate(update) {
+            const callback = port.callbackForUpdate(update);
+            if (!callback.handled)
+                return false;
+            if (callback.registrationId) {
+                try {
+                    await recover(callback.registrationId);
+                }
+                catch {
+                    (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.root_host_reconciliation_required", message: "claimed root callback retained despite unavailable local pending state", meta: { registrationId: callback.registrationId } });
+                }
+            }
+            return true;
+        },
+    };
+}

package/dist/senses/sanctuary-authority-resident.js

@@ -0,0 +1,102 @@
+"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.openSanctuaryResidentAuthority = openSanctuaryResidentAuthority;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const sanctuary_telegram_authority_service_1 = require("../heart/daemon/sanctuary-telegram-authority-service");
+const sanctuary_authority_codec_1 = require("../heart/daemon/sanctuary-authority-codec");
+const runtime_1 = require("../nerves/runtime");
+const telegram_authority_transport_1 = require("./telegram-authority-transport");
+function openSanctuaryResidentAuthority(runtime, machineRuntime, options = {}) {
+    if ([runtime, machineRuntime].some((config) => Object.prototype.hasOwnProperty.call(config, "telegramBotToken"))) {
+        throw new Error("Sanctuary resident Telegram token residue must be removed by the root migration");
+    }
+    const configPath = options.configPath ?? "/run/ouro-authority/resident.json";
+    const expectedUid = options.expectedUid ?? 0;
+    const expectedGid = options.expectedGid ?? 10001;
+    const root = path.dirname(configPath);
+    const parent = fs.lstatSync(root);
+    if (!parent.isDirectory() || parent.uid !== expectedUid || parent.gid !== expectedGid || (parent.mode & 0o7777) !== 0o750 || fs.realpathSync(root) !== root) {
+        throw new Error("Sanctuary resident authority directory is unsafe");
+    }
+    const descriptor = fs.openSync(configPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    let value;
+    try {
+        const stat = fs.fstatSync(descriptor);
+        if (!stat.isFile() || stat.uid !== expectedUid || stat.gid !== expectedGid || (stat.mode & 0o7777) !== 0o640 || stat.nlink !== 1 || stat.size > 8192)
+            throw new Error("Sanctuary resident authority pins are unsafe");
+        value = JSON.parse(fs.readFileSync(descriptor, "utf8"));
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Sanctuary resident authority pins are invalid");
+    const config = value;
+    if (Object.keys(config).sort().join(",") !== "botId,keyId,ownerChatId,ownerUserId,publicKeyDigest,publicKeyPem,schemaVersion,targetHost"
+        || config.schemaVersion !== 1 || config.targetHost !== "sanctuary"
+        || !["botId", "ownerUserId", "ownerChatId"].every((key) => typeof config[key] === "string" && /^[1-9][0-9]*$/u.test(config[key]))
+        || config.ownerUserId !== config.ownerChatId || typeof config.keyId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/u.test(config.keyId)
+        || typeof config.publicKeyPem !== "string" || typeof config.publicKeyDigest !== "string")
+        throw new Error("Sanctuary resident authority identity is invalid");
+    const publicKey = (0, node_crypto_1.createPublicKey)(config.publicKeyPem);
+    if (publicKey.asymmetricKeyType !== "ed25519" || config.publicKeyDigest !== `sha256:${(0, node_crypto_1.createHash)("sha256").update(publicKey.export({ format: "der", type: "spki" })).digest("hex")}`)
+        throw new Error("Sanctuary resident authority issuer pin changed");
+    const client = (options.createClient ?? ((socketPath) => new sanctuary_telegram_authority_service_1.SocketSanctuaryTelegramAuthorityClient(socketPath)))(path.join(root, "authority.sock"));
+    const credentials = { botId: config.botId, authorizedUserId: config.ownerUserId, authorizedChatId: config.ownerChatId };
+    const authorityTransport = (0, telegram_authority_transport_1.createSanctuaryTelegramAuthorityTransport)(client, {
+        expectedTargetHost: config.targetHost, expectedBotId: credentials.botId, expectedOwnerUserId: credentials.authorizedUserId,
+        expectedOwnerChatId: credentials.authorizedChatId, expectedKeyId: config.keyId, expectedPublicKeyDigest: config.publicKeyDigest, publicKey,
+    });
+    async function cursorSnapshot(at) {
+        const snapshot = (0, sanctuary_authority_codec_1.verifyAuthorityPayload)({
+            artifact: await client.request("telegram.cursor.snapshot", {}), expectedDomain: "ouro.sanctuary.telegram-cursor.v1", expectedKeyId: config.keyId, publicKey,
+        });
+        const now = at ?? Date.now();
+        if (!snapshot || Object.keys(snapshot).sort().join(",") !== "botId,cursor,keyId,observedAt,ownerChatId,ownerUserId,pendingUpdateIds,progressDigest,publicKeyDigest,targetHost"
+            || !["targetHost", "botId", "ownerUserId", "ownerChatId", "keyId", "publicKeyDigest"].every((key) => snapshot[key] === config[key])
+            || !Number.isSafeInteger(snapshot.cursor) || snapshot.cursor < 0
+            || !Array.isArray(snapshot.pendingUpdateIds) || !snapshot.pendingUpdateIds.every((id, index, ids) => Number.isSafeInteger(id) && id >= snapshot.cursor && (index === 0 || id > ids[index - 1]))
+            || typeof snapshot.progressDigest !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(snapshot.progressDigest)
+            || typeof snapshot.observedAt !== "string" || !Number.isFinite(Date.parse(snapshot.observedAt)) || new Date(snapshot.observedAt).toISOString() !== snapshot.observedAt
+            || Date.parse(snapshot.observedAt) > now + 1000 || now - Date.parse(snapshot.observedAt) > 30_000)
+            throw new Error("Sanctuary authority cursor snapshot is invalid or stale");
+        return snapshot;
+    }
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.sanctuary_authority_pins_loaded", message: "Sanctuary resident authority pins loaded", meta: { keyId: config.keyId } });
+    return { credentials, authorityTransport, cursorSnapshot };
+}

package/dist/senses/telegram-admission.js

@@ -524,6 +524,7 @@ function createTelegramAdmissionController(options) {
     const compensateFriend = async (record) => {
         if (!record.friendId)
             return;
+        await options.revokeCommunication?.({ userId: record.userId, chatId: record.chatId });
         const revocation = await options.revokeFriend({
             provider: "telegram-user",
             botId: record.botId,
@@ -562,6 +563,12 @@ function createTelegramAdmissionController(options) {
         }
         try {
             if (record.status === "friend_bound") {
+                await options.registerCommunication?.({
+                    id: record.id,
+                    updateId: record.updateId,
+                    userId: record.userId,
+                    chatId: record.chatId,
+                });
                 if (record.quarantinedText === null || !record.friendId)
                     throw new Error("Telegram admission lost input before durable ingress");
                 const committedBase = await options.commitApprovedIngress({

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);