@ouro.bot/cli 0.1.0-alpha.75 → 0.1.0-alpha.750

package/dist/senses/sanctuary-interactive-control.js

@@ -0,0 +1,306 @@
+"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.proveSanctuaryAttemptedRecoveryWithoutRetry = proveSanctuaryAttemptedRecoveryWithoutRetry;
+exports.executeSanctuaryInteractiveEngine = executeSanctuaryInteractiveEngine;
+exports.createSanctuaryInteractiveControl = createSanctuaryInteractiveControl;
+exports.sanctuaryInteractiveControlReady = sanctuaryInteractiveControlReady;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_net_1 = require("node:net");
+const path = __importStar(require("node:path"));
+const approval_store_1 = require("../heart/approval-store");
+const tool_approval_1 = require("../heart/tool-approval");
+const runtime_1 = require("../nerves/runtime");
+const telegram_client_1 = require("./telegram-client");
+const SHA256 = /^[0-9a-f]{64}$/u;
+const MAX_CONTROL_REQUEST = 16 * 1024;
+function object(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    return value;
+}
+function exactKeys(value, keys, label) {
+    if (JSON.stringify(Object.keys(value).sort()) !== JSON.stringify([...keys].sort()))
+        throw new Error(`${label} shape is invalid`);
+}
+function sha256(value) {
+    return (0, node_crypto_1.createHash)("sha256").update(value, "utf8").digest("hex");
+}
+function exactApproval(projections) {
+    const matches = projections.filter(({ approval }) => approval.toolName === "unraid_restart_container" && approval.arguments.container === "calibre-web");
+    if (matches.length !== 1)
+        throw new Error("interactive production approval is absent or ambiguous");
+    return matches[0];
+}
+function exactPending(records, approvalId) {
+    const validCallback = (value) => typeof value === "string" && Buffer.byteLength(value) >= 1 && Buffer.byteLength(value) <= 64;
+    const matches = records.filter((record) => record.approvalId === approvalId && record.deliveryState === "bound" && record.messageId !== null
+        && validCallback(record.approveCallbackData) && validCallback(record.denyCallbackData));
+    if (matches.length !== 1)
+        throw new Error("interactive production pending approval is absent or ambiguous");
+    return matches[0];
+}
+function exactTerminalTombstone(records, approvalId) {
+    const validCallback = (value) => typeof value === "string" && Buffer.byteLength(value) >= 1 && Buffer.byteLength(value) <= 64;
+    const matches = records.filter((record) => record.approvalId === approvalId && record.deliveryState === "terminal_tombstone" && record.messageId !== null
+        && validCallback(record.approveCallbackData) && validCallback(record.denyCallbackData)
+        && record.expiryObservation?.schemaVersion === "telegram-approval-expiry-observation-v1"
+        && record.expiryObservation.deadlineAt === record.expiresAt && Number.isSafeInteger(record.expiryObservation.observedAt)
+        && record.expiryObservation.observedAt >= record.expiresAt && typeof record.expiryObservation.evidenceMac === "string" && SHA256.test(record.expiryObservation.evidenceMac)
+        && Number.isSafeInteger(record.terminalizedAt) && Number(record.terminalizedAt) >= record.expiryObservation.observedAt);
+    if (matches.length !== 1)
+        throw new Error("interactive production terminal tombstone is absent or ambiguous");
+    return matches[0];
+}
+function pendingDigest(record) {
+    return sha256(JSON.stringify({ approvalId: record.approvalId, messageId: record.messageId, deliveryState: record.deliveryState, approveCallbackData: record.approveCallbackData, denyCallbackData: record.denyCallbackData, expiresAt: record.expiresAt }));
+}
+function proveSanctuaryAttemptedRecoveryWithoutRetry(agentRoot, scenarioHandleDigest, approval) {
+    if (!SHA256.test(scenarioHandleDigest))
+        throw new Error("attempted recovery scenario is invalid");
+    const databaseRoot = path.join(agentRoot, "state", "acceptance", "attempted-recovery-probes");
+    (0, node_fs_1.mkdirSync)(databaseRoot, { recursive: true, mode: 0o700 });
+    const databasePath = path.join(databaseRoot, `${scenarioHandleDigest}.sqlite`);
+    if ((0, node_fs_1.existsSync)(databasePath))
+        throw new Error("attempted recovery proof requires inspect-before-retry");
+    const instant = new Date("2026-08-21T00:00:00.000Z");
+    const first = (0, approval_store_1.openApprovalStore)({ databasePath, now: () => instant });
+    const ownerId = "acceptance-attempted-recovery";
+    const toolCallId = `acceptance-${approval.toolCallId}`;
+    const frozenAssistantMessage = structuredClone(approval.frozenAssistantMessage);
+    const toolCalls = frozenAssistantMessage.tool_calls;
+    if (!Array.isArray(toolCalls) || toolCalls.length !== 1 || !toolCalls[0] || typeof toolCalls[0] !== "object" || Array.isArray(toolCalls[0])) {
+        first.close();
+        throw new Error("attempted recovery frozen tool call is invalid");
+    }
+    toolCalls[0].id = toolCallId;
+    const prepared = first.prepare({
+        toolCallId, toolName: approval.toolName, arguments: approval.arguments,
+        schemaDigest: approval.schemaDigest, toolDigest: approval.toolDigest, policyDigest: approval.policyDigest, policyId: approval.policyId,
+        sessionKey: "acceptance:attempted-recovery", sessionPath: path.join(databaseRoot, `${scenarioHandleDigest}.session.json`),
+        baseSessionRevision: approval.baseSessionRevision, checkpointDigest: approval.checkpointDigest,
+        requesterId: "acceptance-probe", transport: "telegram", transportUserId: "acceptance-probe", transportChatId: "acceptance-probe",
+        expiresAt: "2099-01-01T00:00:00.000Z", frozenAssistantMessage,
+    });
+    first.activate({ approvalId: prepared.record.approvalId, checkpointDigest: prepared.record.checkpointDigest, suspendedSessionRevision: approval.suspendedSessionRevision });
+    first.bindPrompt({ approvalId: prepared.record.approvalId, transport: "telegram", transportChatId: "acceptance-probe", transportMessageId: "acceptance-message" });
+    const claimed = first.decide({
+        approvalId: prepared.record.approvalId, decisionToken: prepared.decisionToken, decision: "approve", requesterId: "acceptance-probe",
+        transport: "telegram", transportUserId: "acceptance-probe", transportChatId: "acceptance-probe", transportMessageId: "acceptance-message",
+        sessionKey: "acceptance:attempted-recovery", ownerId,
+    });
+    const attempted = first.markAttempted({ approvalId: claimed.approvalId, ownerId, epoch: claimed.epoch });
+    first.close();
+    const attemptedRecordDigest = sha256(JSON.stringify(attempted));
+    const reopened = (0, approval_store_1.openApprovalStore)({ databasePath, now: () => instant });
+    const durableAttempted = reopened.read(attempted.approvalId);
+    if (!durableAttempted || durableAttempted.state !== "attempted") {
+        reopened.close();
+        throw new Error("attempted recovery record was not durable across reopen");
+    }
+    const recovered = (0, tool_approval_1.recoverAttemptedApproval)({ approvalStore: reopened, approvalId: durableAttempted.approvalId });
+    let retryCount = 0;
+    try {
+        (0, tool_approval_1.recoverAttemptedApproval)({ approvalStore: reopened, approvalId: durableAttempted.approvalId });
+        retryCount += 1;
+    }
+    catch { /* expected */ }
+    reopened.close();
+    return { observed: recovered.state === "attempted_indeterminate", retryCount, reopened: true, attemptedRecordDigest, recoveredRecordDigest: sha256(JSON.stringify(recovered)) };
+}
+async function executeSanctuaryInteractiveEngine(raw, deps) {
+    const payload = object(raw, "interactive runtime payload");
+    exactKeys(payload, ["operation", "label", "scenarioHandleDigest"], "interactive runtime payload");
+    const operation = payload.operation;
+    const label = payload.label;
+    const scenarioHandleDigest = payload.scenarioHandleDigest;
+    if (typeof scenarioHandleDigest !== "string" || !SHA256.test(scenarioHandleDigest)
+        || !["unit-16k-timeout-stale", "unit-16l-duplicate-callback", "unit-16m-restart-continuation"].includes(label)
+        || !["drive_timeout_stale", "drive_duplicate_callbacks", "prepare_restart_continuation", "reconcile_restart_continuation"].includes(String(operation))
+        || (operation === "drive_timeout_stale") !== (label === "unit-16k-timeout-stale")
+        || (operation === "drive_duplicate_callbacks") !== (label === "unit-16l-duplicate-callback"))
+        throw new Error("interactive runtime operation binding is invalid");
+    const before = exactApproval(deps.readApprovals(scenarioHandleDigest));
+    if (!before.approval.suspendedSessionRevision)
+        throw new Error("interactive production approval checkpoint is unavailable");
+    if (operation === "drive_timeout_stale") {
+        if (before.approval.state === "proposed") {
+            exactPending(deps.readPending(), before.approval.approvalId);
+            return { state: "waiting" };
+        }
+        if (before.approval.state !== "expired" || before.approval.epoch !== 0)
+            throw new Error("timeout stale approval is not expired without a claim");
+        const captured = exactTerminalTombstone(deps.readPending(), before.approval.approvalId);
+        const session = await deps.createSession();
+        try {
+            const queryId = (0, node_crypto_1.randomBytes)(18).toString("base64url");
+            const result = await session.handle({ callbackData: captured.approveCallbackData, queryId, messageId: captured.messageId });
+            const after = exactApproval(deps.readApprovals(scenarioHandleDigest));
+            const promptTerminal = !session.pendingApprovalIds().includes(before.approval.approvalId);
+            if (!result.handled || result.accepted || result.reason !== "stale_callback" || after.approval.state !== "expired" || after.approval.epoch !== 0 || !promptTerminal) {
+                throw new Error("timeout stale callback proof failed");
+            }
+            return {
+                schemaVersion: "sanctuary-timeout-stale-driver-receipt-v1", phase: "complete", label, scenarioHandleDigest,
+                approvalIdDigest: sha256(before.approval.approvalId), checkpointDigest: before.approval.checkpointDigest,
+                suspendedSessionRevisionDigest: sha256(before.approval.suspendedSessionRevision), approvalEpochBefore: before.approval.epoch,
+                callbackAttempts: 1, distinctQueryCount: 1, callbackDataDigest: sha256(captured.approveCallbackData),
+                settledCount: 1, claimCount: 0, mutationCount: 0, staleAcknowledged: true, promptTerminal,
+            };
+        }
+        finally {
+            session.close();
+        }
+    }
+    if (before.approval.state !== "proposed")
+        throw new Error("interactive production approval is not currently proposed");
+    const pending = exactPending(deps.readPending(), before.approval.approvalId);
+    const common = { approvalIdDigest: sha256(before.approval.approvalId), checkpointDigest: before.approval.checkpointDigest, suspendedSessionRevisionDigest: sha256(before.approval.suspendedSessionRevision), approvalEpochBefore: before.approval.epoch };
+    if (operation === "prepare_restart_continuation") {
+        const recovery = deps.proveIndeterminateRecovery(before.approval, scenarioHandleDigest);
+        if (!recovery.observed || recovery.retryCount !== 0 || !recovery.reopened
+            || !SHA256.test(recovery.attemptedRecordDigest) || !SHA256.test(recovery.recoveredRecordDigest)
+            || recovery.attemptedRecordDigest === recovery.recoveredRecordDigest)
+            throw new Error("isolated attempted recovery proof failed");
+        return {
+            schemaVersion: "sanctuary-interactive-driver-receipt-v2", phase: "prepared", label, scenarioHandleDigest, ...common,
+            pendingDigestBefore: pendingDigest(pending), indeterminateRecoveryObserved: true,
+            attemptedRecoveryReopened: true, attemptedRecordDigest: recovery.attemptedRecordDigest, recoveredRecordDigest: recovery.recoveredRecordDigest,
+        };
+    }
+    const session = await deps.createSession();
+    try {
+        if (operation === "drive_duplicate_callbacks") {
+            const queryIds = [(0, node_crypto_1.randomBytes)(18).toString("base64url"), (0, node_crypto_1.randomBytes)(18).toString("base64url")];
+            let arrivals = 0;
+            let release;
+            const barrier = new Promise((resolve) => { release = resolve; });
+            const invoke = async (queryId) => { arrivals += 1; if (arrivals === 2)
+                release(); await barrier; return session.handle({ callbackData: pending.approveCallbackData, queryId, messageId: pending.messageId }); };
+            const results = await Promise.all(queryIds.map(invoke));
+            const after = exactApproval(deps.readApprovals(scenarioHandleDigest));
+            const stale = await session.handle({ callbackData: pending.approveCallbackData, queryId: (0, node_crypto_1.randomBytes)(18).toString("base64url"), messageId: pending.messageId });
+            return { schemaVersion: "sanctuary-interactive-driver-receipt-v2", phase: "complete", label, scenarioHandleDigest, ...common, callbackAttempts: 2, distinctQueryCount: new Set(queryIds).size, callbackDataDigest: sha256(pending.approveCallbackData), barrierObserved: arrivals === 2, settledCount: results.filter(({ handled }) => handled).length, claimCount: after.approval.epoch === before.approval.epoch + 1 ? 1 : 0, mutationCount: after.approval.state === "succeeded" ? 1 : 0, staleReplayAttempts: 1, staleReplaySettled: stale.handled, staleReplayMutationCount: 0, promptTerminal: !session.pendingApprovalIds().includes(before.approval.approvalId), writeCredentialObserved: deps.writeCredentialObserved() };
+        }
+        const result = await session.handle({ callbackData: pending.approveCallbackData, queryId: (0, node_crypto_1.randomBytes)(18).toString("base64url"), messageId: pending.messageId });
+        const after = exactApproval(deps.readApprovals(scenarioHandleDigest));
+        if (!after.continuation || after.approval.state !== "succeeded")
+            throw new Error("restart continuation did not complete");
+        return { approvalEpochAfterRestart: before.approval.epoch, continuationEpochAfter: after.continuation.continuationEpoch, pendingDigestAfter: pendingDigest(pending), pendingRestored: true, callbackAttempts: 1, mutationCount: result.accepted ? 1 : 0, indeterminateRetryCount: 0 };
+    }
+    finally {
+        session.close();
+    }
+}
+function createSanctuaryInteractiveControl(options) {
+    const socketPath = path.join(options.agentRoot, "state", "acceptance", "telegram-control.sock");
+    const runRequest = options.runRequest ?? (async (operation) => operation());
+    let server;
+    let updateId = 2_100_000_000;
+    return {
+        socketPath,
+        async start() {
+            if (server)
+                return;
+            (0, node_fs_1.mkdirSync)(path.dirname(socketPath), { recursive: true, mode: 0o700 });
+            if ((0, node_fs_1.existsSync)(socketPath))
+                (0, node_fs_1.unlinkSync)(socketPath);
+            server = (0, node_net_1.createServer)({ allowHalfOpen: true }, (connection) => {
+                let raw = "";
+                connection.setEncoding("utf8");
+                connection.on("error", () => undefined);
+                connection.on("data", (chunk) => { raw += chunk; if (Buffer.byteLength(raw) > MAX_CONTROL_REQUEST)
+                    connection.destroy(); });
+                connection.on("end", () => {
+                    void runRequest(async () => {
+                        try {
+                            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.sanctuary_interactive_control_request", message: "Sanctuary interactive control request received", meta: { bytes: Buffer.byteLength(raw) } });
+                            const parsed = object(JSON.parse(raw), "interactive control request");
+                            if (parsed.operation === "interactive_runtime_ready") {
+                                exactKeys(parsed, ["operation", "label", "scenarioHandleDigest"], "interactive readiness request");
+                                if (parsed.label !== "unit-16m-restart-continuation" || typeof parsed.scenarioHandleDigest !== "string" || !SHA256.test(parsed.scenarioHandleDigest))
+                                    throw new Error("interactive readiness binding is invalid");
+                                connection.end(`${JSON.stringify({ ok: true, result: { ready: true } })}\n`);
+                                return;
+                            }
+                            const result = await executeSanctuaryInteractiveEngine(parsed, {
+                                agentRoot: options.agentRoot,
+                                readApprovals: (digest) => (0, approval_store_1.readApprovalsByScenarioHandleDigest)(path.join(options.agentRoot, "state", "approvals", "approvals.sqlite"), digest),
+                                readPending: () => new telegram_client_1.FileTelegramPendingApprovalStore(path.join(options.agentRoot, "state", "approvals", "telegram-pending.json")).load(),
+                                createSession: async () => ({
+                                    handle: ({ callbackData, queryId, messageId }) => runRequest(() => options.transport.handleUpdate({
+                                        update_id: updateId++,
+                                        callback_query: {
+                                            id: queryId,
+                                            from: { id: Number(options.authorizedUserId) },
+                                            data: callbackData,
+                                            message: {
+                                                message_id: Number(messageId),
+                                                chat: { id: Number(options.authorizedChatId) },
+                                            },
+                                        },
+                                    })),
+                                    pendingApprovalIds: () => options.transport.listPendingDeliveries().map(({ approvalId }) => approvalId),
+                                    close: () => undefined,
+                                }),
+                                proveIndeterminateRecovery: (approval, digest) => proveSanctuaryAttemptedRecoveryWithoutRetry(options.agentRoot, digest, approval),
+                                writeCredentialObserved: () => /credential|api[_-]?key|token|secret/iu.test(raw),
+                            });
+                            connection.end(`${JSON.stringify({ ok: true, result })}\n`);
+                        }
+                        catch {
+                            connection.end(`${JSON.stringify({ ok: false, error: "interactive runtime operation failed" })}\n`);
+                        }
+                    }).catch(() => { if (!connection.destroyed)
+                        connection.end(`${JSON.stringify({ ok: false, error: "interactive runtime operation failed" })}\n`); });
+                });
+            });
+            await new Promise((resolve, reject) => { server.once("error", reject); server.listen(socketPath, () => { server.off("error", reject); (0, node_fs_1.chmodSync)(socketPath, 0o600); resolve(); }); });
+        },
+        async stop() { const active = server; server = undefined; if (active)
+            await new Promise((resolve) => active.close(() => resolve())); if ((0, node_fs_1.existsSync)(socketPath))
+            (0, node_fs_1.unlinkSync)(socketPath); },
+    };
+}
+async function sanctuaryInteractiveControlReady(socketPath, timeoutMs = 1_000) {
+    return new Promise((resolve) => {
+        const socket = (0, node_net_1.createConnection)(socketPath);
+        const finish = (ready) => { socket.destroy(); resolve(ready); };
+        socket.setTimeout(timeoutMs, () => finish(false));
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+    });
+}

package/dist/senses/sanctuary-runtime.js

@@ -0,0 +1,240 @@
+"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.runWithSanctuaryToolReceiptCollection = runWithSanctuaryToolReceiptCollection;
+exports.createSanctuaryToolContext = createSanctuaryToolContext;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const node_async_hooks_1 = require("node:async_hooks");
+const identity_1 = require("../heart/identity");
+const runtime_credentials_1 = require("../heart/runtime-credentials");
+const unraid_restart_1 = require("../repertoire/unraid-restart");
+const steward_policy_1 = require("../heart/steward-policy");
+const unraid_client_1 = require("../repertoire/unraid-client");
+const tools_unraid_1 = require("../repertoire/tools-unraid");
+const runtime_1 = require("../nerves/runtime");
+const sanctuary_acceptance_marker_1 = require("../heart/daemon/sanctuary-acceptance-marker");
+const sanctuary_grounding_1 = require("./sanctuary-grounding");
+const sanctuary_health_1 = require("./sanctuary-health");
+const sanctuary_sab_1 = require("./sanctuary-sab");
+const sanctuaryToolReceipts = new node_async_hooks_1.AsyncLocalStorage();
+const sanctuaryToolGroundings = new node_async_hooks_1.AsyncLocalStorage();
+const acceptanceLedgerTails = new Map();
+async function runWithSanctuaryToolReceiptCollection(operation, observer) {
+    const digests = observer?.toolResultDigests ?? [];
+    const groundings = observer?.toolGroundings ?? [];
+    const result = await sanctuaryToolReceipts.run(digests, () => sanctuaryToolGroundings.run(groundings, operation));
+    return { result, toolResultDigests: [...digests], ...(groundings.length > 0 ? { toolGroundings: structuredClone(groundings) } : {}) };
+}
+function collectToolResult(result, toolName) {
+    const digest = (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(result)).digest("hex");
+    sanctuaryToolReceipts.getStore()?.push(digest);
+    let facts = null;
+    try {
+        facts = toolName ? (0, sanctuary_grounding_1.projectSanctuaryGrounding)(toolName, result) : null;
+    }
+    catch { /* validated tool adapters own malformed-result failure */ }
+    if (!facts || (toolName !== "unraid_get_system" && toolName !== "unraid_get_storage"))
+        return { resultDigest: digest };
+    const groundingDigest = (0, sanctuary_grounding_1.sanctuaryGroundingDigest)(facts);
+    const envelope = result;
+    const sourceIdentityDigest = envelope?.data?.sourceIdentityDigest;
+    if (typeof sourceIdentityDigest !== "string" || !/^[0-9a-f]{64}$/u.test(sourceIdentityDigest))
+        throw new Error("Sanctuary grounding source identity is invalid");
+    const verifiedSourceIdentityDigest = sourceIdentityDigest;
+    const observedAt = new Date().toISOString();
+    sanctuaryToolGroundings.getStore()?.push({ toolName, resultDigest: digest, groundingDigest, sourceIdentityDigest: verifiedSourceIdentityDigest, observedAt, facts });
+    return { resultDigest: digest, groundingDigest, sourceIdentityDigest: verifiedSourceIdentityDigest, observedAt };
+}
+function machineConfig(agentName) {
+    const result = (0, runtime_credentials_1.readMachineRuntimeCredentialConfig)(agentName);
+    if (!result.ok)
+        throw new Error(`Sanctuary machine runtime config is ${result.reason}`);
+    return result.config;
+}
+function required(config, field) {
+    const value = config[field];
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new Error(`Sanctuary ${field} is missing`);
+    return value.trim();
+}
+function persistAttempt(filePath, attempt) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const temporary = `${filePath}.tmp-${process.pid}-${(0, node_crypto_1.randomUUID)()}`;
+    fs.writeFileSync(temporary, `${JSON.stringify(attempt)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, filePath);
+}
+async function appendAcceptanceAttempt(agentName, attempt) {
+    if (!attempt.scenarioHandleDigest)
+        return;
+    const filePath = path.join((0, identity_1.getAgentRoot)(agentName), "state", "acceptance", "restart-attempts.ndjson");
+    const previous = acceptanceLedgerTails.get(filePath) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(() => {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+        let existing = [];
+        try {
+            if (fs.statSync(filePath).size > 4 * 1024 * 1024)
+                throw new Error("restart ledger exceeds its bound");
+            existing = fs.readFileSync(filePath, "utf8").split("\n").filter(Boolean);
+            if (existing.length > 500 || existing.some((line) => Buffer.byteLength(line) > 8 * 1024))
+                throw new Error("restart ledger rows exceed their bound");
+            for (const line of existing) {
+                const value = JSON.parse(line);
+                if (!value || typeof value !== "object" || !value.container || typeof value.container.id !== "string" || !value.container.id || value.container.id.length > 128
+                    || typeof value.container.name !== "string" || !value.container.name || value.container.name.length > 128
+                    || !["attempt_not_started", "attempting", "succeeded", "attempted_or_indeterminate"].includes(String(value.state))
+                    || typeof value.observedAt !== "string" || !Number.isFinite(Date.parse(value.observedAt)) || new Date(Date.parse(value.observedAt)).toISOString() !== value.observedAt
+                    || !/^[0-9a-f]{64}$/u.test(String(value.actionDigest)) || !/^[0-9a-f]{64}$/u.test(String(value.argumentDigest))
+                    || !/^[0-9a-f]{64}$/u.test(String(value.scenarioHandleDigest)) || typeof value.approvalId !== "string" || !value.approvalId || value.approvalId.length > 128
+                    || typeof value.attemptId !== "string" || !value.attemptId || value.attemptId.length > 128 || typeof value.mutationAcknowledged !== "boolean"
+                    || (value.afterState !== null && (typeof value.afterState !== "string" || value.afterState.length > 64)))
+                    throw new Error("restart ledger row is invalid");
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw new Error("Sanctuary acceptance restart ledger is corrupt", { cause: error });
+        }
+        const entries = [...existing, JSON.stringify(attempt)].slice(-500);
+        const temporary = `${filePath}.tmp-${process.pid}-${(0, node_crypto_1.randomUUID)()}`;
+        fs.writeFileSync(temporary, `${entries.join("\n")}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        const handle = fs.openSync(temporary, "r");
+        try {
+            fs.fsyncSync(handle);
+        }
+        finally {
+            fs.closeSync(handle);
+        }
+        fs.renameSync(temporary, filePath);
+        fs.chmodSync(filePath, 0o600);
+        const directory = fs.openSync(path.dirname(filePath), "r");
+        try {
+            fs.fsyncSync(directory);
+        }
+        finally {
+            fs.closeSync(directory);
+        }
+    });
+    acceptanceLedgerTails.set(filePath, current);
+    try {
+        await current;
+    }
+    finally {
+        if (acceptanceLedgerTails.get(filePath) === current)
+            acceptanceLedgerTails.delete(filePath);
+    }
+}
+function createSanctuaryToolContext(agentName) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.sanctuary_runtime_create",
+        message: "creating typed Sanctuary tool context",
+        meta: { agentName },
+    });
+    const initial = machineConfig(agentName);
+    const endpoint = required(initial, "unraidGraphqlUrl");
+    const readClient = new unraid_client_1.UnraidClient({ endpoint, apiKey: required(initial, "unraidReadApiKey") });
+    const reads = (0, tools_unraid_1.createUnraidReadTools)(readClient);
+    const sab = (0, sanctuary_sab_1.createSanctuarySabClient)();
+    const acceptanceRead = (toolName, read) => async (...args) => {
+        try {
+            const result = await read(...args);
+            const receipt = collectToolResult(result, toolName);
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.sanctuary_read_receipt", message: "Sanctuary live read completed", meta: { toolName, success: true, ...receipt, ...(0, sanctuary_acceptance_marker_1.sanctuaryAcceptanceEventMeta)(agentName) } });
+            return result;
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.sanctuary_read_receipt_error", message: "Sanctuary live read failed", meta: { toolName, success: false, category: error instanceof Error ? error.name : "unknown", ...(0, sanctuary_acceptance_marker_1.sanctuaryAcceptanceEventMeta)(agentName) } });
+            throw error;
+        }
+    };
+    const restart = (0, unraid_restart_1.createApprovedUnraidRestartExecutor)({
+        endpoint,
+        listContainers: reads.listContainers,
+        loadWriteApiKey: async () => required(machineConfig(agentName), "unraidWriteApiKey"),
+        persistAttempt: async (attempt) => {
+            persistAttempt(path.join((0, identity_1.getAgentRoot)(agentName), "state", "approvals", "unraid-restart-attempt.json"), attempt);
+            await appendAcceptanceAttempt(agentName, attempt);
+        },
+        acceptanceScenarioHandleDigest: () => (0, sanctuary_acceptance_marker_1.readSanctuaryAcceptanceMarker)(agentName)?.scenarioHandleDigest,
+        acceptanceApproval: sanctuary_acceptance_marker_1.readSanctuaryAcceptanceApproval,
+        reserveRoutineAction: (input) => (0, steward_policy_1.consumeRoutineActionGrant)((0, identity_1.getAgentRoot)(agentName), input),
+        transitionRoutineAction: (input) => (0, steward_policy_1.transitionRoutineActionReceipt)((0, identity_1.getAgentRoot)(agentName), input),
+    });
+    return {
+        sanctuary: {
+            listContainers: acceptanceRead("unraid_list_containers", reads.listContainers),
+            getContainerLogs: acceptanceRead("unraid_get_container_logs", reads.getContainerLogs),
+            getStorage: acceptanceRead("unraid_get_storage", reads.getStorage),
+            getDisks: acceptanceRead("unraid_get_disks", reads.getDisks),
+            getNotifications: acceptanceRead("unraid_get_notifications", reads.getNotifications),
+            getSystem: acceptanceRead("unraid_get_system", reads.getSystem),
+            checkServices: acceptanceRead("unraid_check_services", async () => {
+                const services = await Promise.all(sanctuary_health_1.SANCTUARY_PUBLIC_ENDPOINTS.map(async (url) => ({ name: new URL(url).hostname.split(".")[0], ...await (0, sanctuary_health_1.probeSanctuaryEndpoint)(url) })));
+                return { ok: true, data: { observedAt: new Date().toISOString(), services, degraded: services.some((service) => !service.ok) } };
+            }),
+            getDownloadQueue: acceptanceRead("sanctuary_get_download_queue", sab.readQueue),
+            resumeDownloadQueue: async () => {
+                try {
+                    const result = await sab.resumeQueue();
+                    collectToolResult(result);
+                    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.sanctuary_download_resume_receipt", message: "Sanctuary download queue resume completed", meta: { changed: result.changed, verified: result.verified, receiptDigest: result.receiptDigest } });
+                    return { ok: true, data: result };
+                }
+                catch (error) {
+                    (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.sanctuary_download_resume_error", message: "Sanctuary download queue resume failed", meta: { category: error instanceof Error ? error.name : "unknown" } });
+                    throw error;
+                }
+            },
+            restartContainer: async (args, execution) => {
+                const result = execution ? await restart(args, execution) : await restart(args);
+                collectToolResult(result);
+                return result;
+            },
+            recoverRoutineActions: () => (0, steward_policy_1.recoverRoutineActionReceipts)((0, identity_1.getAgentRoot)(agentName), {
+                observeTarget: async (target) => {
+                    const observed = await reads.listContainers();
+                    if (!observed.ok)
+                        throw new Error(observed.error.message);
+                    const matches = observed.data.containers.filter((container) => container.id === target.id && container.name === target.name);
+                    if (matches.length !== 1)
+                        return { ...target, state: "unknown" };
+                    return { id: matches[0].id, name: matches[0].name, state: matches[0].state };
+                },
+            }),
+        },
+    };
+}

package/dist/senses/sanctuary-sab.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSanctuarySabClient = createSanctuarySabClient;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const runtime_1 = require("../nerves/runtime");
+const DEFAULT_INI_PATH = "/run/sanctuary/sabnzbd.ini";
+const BASE_URL = "http://127.0.0.1:8090/api";
+function apiKey(iniPath) {
+    let contents = "";
+    try {
+        contents = (0, node_fs_1.readFileSync)(iniPath, "utf8");
+    }
+    catch {
+        throw new Error("SAB queue verification credential is unavailable");
+    }
+    const value = contents.match(/^\s*api_key\s*=\s*(\S+)\s*$/mu)?.[1];
+    if (!value)
+        throw new Error("SAB queue verification credential is unavailable");
+    return value;
+}
+function queuedJobs(value) {
+    const parsed = typeof value === "string" && /^\d{1,7}$/u.test(value) ? Number(value) : value;
+    if (!Number.isSafeInteger(parsed) || Number(parsed) < 0 || Number(parsed) > 1_000_000)
+        throw new Error("SAB queue response is malformed");
+    return Number(parsed);
+}
+function createSanctuarySabClient(options = {}) {
+    const iniPath = options.iniPath ?? DEFAULT_INI_PATH;
+    const fetchImpl = options.fetch ?? fetch;
+    let cachedApiKey = null;
+    const request = async (mode) => {
+        cachedApiKey ??= apiKey(iniPath);
+        let response;
+        try {
+            response = await fetchImpl(`${BASE_URL}?mode=${mode}${mode === "queue" ? "&output=json" : ""}&apikey=${encodeURIComponent(cachedApiKey)}`, { signal: AbortSignal.timeout(15_000) });
+        }
+        catch {
+            throw new Error("SAB queue request failed");
+        }
+        if (!response.ok)
+            throw new Error("SAB queue request failed");
+        return response;
+    };
+    const readQueue = async () => {
+        const response = await request("queue");
+        const body = await response.json();
+        if (!body || typeof body !== "object" || Array.isArray(body))
+            throw new Error("SAB queue response is malformed");
+        const queue = body.queue;
+        if (!queue || typeof queue !== "object" || Array.isArray(queue))
+            throw new Error("SAB queue response is malformed");
+        const fields = queue;
+        if (typeof fields.paused !== "boolean" || (fields.status !== undefined && (typeof fields.status !== "string" || Buffer.byteLength(fields.status) > 64)))
+            throw new Error("SAB queue response is malformed");
+        const status = typeof fields.status === "string" ? fields.status : "unknown";
+        const jobs = fields.noofslots === undefined ? 0 : queuedJobs(fields.noofslots);
+        const observedAt = options.now?.() ?? new Date().toISOString();
+        const stateDigest = (0, node_crypto_1.createHash)("sha256").update(JSON.stringify({ paused: fields.paused, status, queuedJobs: jobs })).digest("hex");
+        return { paused: fields.paused, status, queuedJobs: jobs, observedAt, stateDigest };
+    };
+    return {
+        readQueue,
+        async resumeQueue() {
+            const before = await readQueue();
+            if (!before.paused) {
+                const receiptDigest = (0, node_crypto_1.createHash)("sha256").update(`sabnzbd.resume\0${before.stateDigest}\0${before.stateDigest}`).digest("hex");
+                return { changed: false, before, after: before, verified: true, receiptDigest };
+            }
+            const response = await request("resume");
+            await response.body?.cancel().catch(() => undefined);
+            const after = await readQueue();
+            if (after.paused)
+                throw new Error("SAB queue resume could not be verified");
+            const receiptDigest = (0, node_crypto_1.createHash)("sha256").update(`sabnzbd.resume\0${before.stateDigest}\0${after.stateDigest}`).digest("hex");
+            return { changed: true, before, after, verified: true, receiptDigest };
+        },
+    };
+}
+(0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.sanctuary_sab_loaded", message: "typed Sanctuary SAB queue client loaded", meta: { operations: 2 } });