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

package/dist/repertoire/tools-session.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sessionToolDefinitions = void 0;
+exports.readButlerOperationalVisibility = readButlerOperationalVisibility;
+exports.formatButlerOperationalVisibility = formatButlerOperationalVisibility;
 exports.renderInnerProgressStatus = renderInnerProgressStatus;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -55,6 +57,15 @@ const habit_session_summary_1 = require("../heart/habits/habit-session-summary")
 const cross_chat_delivery_1 = require("../heart/cross-chat-delivery");
 const mail_import_discovery_1 = require("../heart/mail-import-discovery");
 const outbound_1 = require("../senses/voice/outbound");
+const router_1 = require("../heart/external-events/router");
+const steward_policy_1 = require("../heart/steward-policy");
+const await_parser_1 = require("../heart/awaiting/await-parser");
+const daemon_health_1 = require("../heart/daemon/daemon-health");
+const turn_context_1 = require("../heart/turn-context");
+const telegram_effect_adapter_1 = require("../senses/telegram-effect-adapter");
+const telegram_admission_1 = require("../senses/telegram-admission");
+const sanctuary_health_1 = require("../senses/sanctuary-health");
+const run_ledger_1 = require("../heart/run-ledger");
 const NO_SESSION_FOUND_MESSAGE = "no session found for that friend/channel/key combination.";
 const EMPTY_SESSION_MESSAGE = "session exists but has no non-system messages.";
 const VALID_HABIT_SUMMARY_WHICH = new Set(["latest", "previous", "latest-success", "latest-failure"]);
@@ -380,6 +391,202 @@ async function buildToolActiveWorkFrame(ctx) {
         targetCandidates: [],
     });
 }
+function boundedStatusText(value, max = 180) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    return normalized.length <= max ? normalized : `${normalized.slice(0, max - 3)}...`;
+}
+function readButlerOperationalVisibility(agentRoot = (0, identity_1.getAgentRoot)(), agentName = (0, identity_1.getAgentName)()) {
+    const sourceErrors = {};
+    const read = (source, operation, fallback) => {
+        try {
+            return operation();
+        }
+        catch (error) {
+            sourceErrors[source] = boundedStatusText(error instanceof Error ? error.message : String(error)) || "unknown read failure";
+            return fallback;
+        }
+    };
+    const awaitsDir = path.join(agentRoot, "awaiting");
+    const awaits = read("awaits", () => fs.existsSync(awaitsDir) ? fs.readdirSync(awaitsDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+        .map((entry) => {
+        const filePath = path.join(awaitsDir, entry.name);
+        return (0, await_parser_1.parseAwaitFile)(fs.readFileSync(filePath, "utf8"), filePath);
+    })
+        .filter((entry) => entry.status === "pending") : [], []);
+    const effectsRoot = path.join(agentRoot, "state", "telegram", "effects");
+    const telegramEffects = read("telegram_effects", () => {
+        if (!fs.existsSync(effectsRoot))
+            throw new Error("Telegram effect journal has not been created yet");
+        const journal = new telegram_effect_adapter_1.FileTelegramEffectJournal(effectsRoot);
+        try {
+            return journal.list().map((artifact) => ({
+                id: artifact.id,
+                authorClass: artifact.authorClass,
+                targetKind: artifact.target.kind,
+                state: artifact.parts.some((part) => part.state === "indeterminate") ? "indeterminate"
+                    : artifact.parts.some((part) => part.state === "attempting") ? "attempting"
+                        : artifact.parts.every((part) => part.state === "session_recorded") ? "session_recorded"
+                            : artifact.parts.some((part) => part.state === "accepted") ? "accepted"
+                                : "prepared",
+                acceptedAt: artifact.parts.flatMap((part) => part.acceptedAt ? [part.acceptedAt] : []).sort().at(-1) ?? null,
+                sessionRecordedAt: artifact.parts.flatMap((part) => part.sessionRecordedAt ? [part.sessionRecordedAt] : []).sort().at(-1) ?? null,
+                messageIds: artifact.parts.flatMap((part) => part.messageId ? [part.messageId] : []),
+                sessionEventIds: artifact.parts.flatMap((part) => part.sessionEventId ? [part.sessionEventId] : []),
+                updatedAt: artifact.updatedAt,
+            }));
+        }
+        finally {
+            journal.close();
+        }
+    }, []);
+    const admissionsRoot = path.join(agentRoot, "state", "senses", "telegram", "admissions");
+    const telegramAdmissions = read("telegram_admissions", () => {
+        if (!fs.existsSync(admissionsRoot))
+            throw new Error("Telegram admission store has not been created yet");
+        const store = new telegram_admission_1.FileTelegramAdmissionStore(admissionsRoot);
+        try {
+            return store.list().map((record) => ({ id: record.id, status: record.status, displayCode: record.displayCode, createdAt: record.createdAt, expiresAt: record.expiresAt }));
+        }
+        finally {
+            store.close();
+        }
+    }, []);
+    return {
+        agentName,
+        externalEvents: read("external_events", () => (0, router_1.listExternalEventStatus)((0, router_1.getExternalEventRoot)()).filter((event) => event.agent === agentName), []),
+        stewardPolicy: read("steward_policy", () => (0, steward_policy_1.readStewardPolicy)(agentRoot), { schemaVersion: 1, version: 0, desiredStates: {}, routineActionGrants: {}, updatedAt: null }),
+        awaits,
+        telegramEffects,
+        telegramAdmissions,
+        daemonHealth: read("daemon_health", () => {
+            const health = (0, daemon_health_1.readHealth)((0, daemon_health_1.getDefaultHealthPath)());
+            if (!health)
+                throw new Error("daemon health is missing or invalid");
+            return health;
+        }, null),
+        healthState: read("health_state", () => (0, sanctuary_health_1.readSanctuaryHealthState)(path.join(agentRoot, "state", "health", "sanctuary-health.json")), undefined),
+        routineActions: read("routine_actions", () => (0, steward_policy_1.readRoutineActionReceipts)(agentRoot), []),
+        providerLanes: read("provider", () => {
+            const config = (0, identity_1.loadAgentConfig)();
+            if (!config.humanFacing || !config.agentFacing)
+                throw new Error("provider lanes are unavailable");
+            return { outward: config.humanFacing, inner: config.agentFacing };
+        }, null),
+        lastAutomatedEventRun: read("run_ledger", () => (0, run_ledger_1.readRunLedger)(agentRoot)
+            .filter((row) => row.sourceKind === "private-runtime" && row.senseOrHabit === "external-event" && row.lifecycle === "completed")
+            .sort((left, right) => (right.endedAt ?? right.recordedAt).localeCompare(left.endedAt ?? left.recordedAt))[0] ?? null, null),
+        senseStatusLines: read("senses", () => (0, turn_context_1.readSenseStatusLines)(), []),
+        sourceErrors,
+    };
+}
+function formatButlerOperationalVisibility(status, options = {}) {
+    const section = options.section ?? "all";
+    const offset = Math.max(0, options.offset ?? 0);
+    const limit = Math.min(20, Math.max(1, options.limit ?? 10));
+    const show = (wanted) => section === "all" || section === wanted;
+    const page = (rows) => rows.slice(offset, offset + limit);
+    const more = (label, total) => total > offset + limit ? `  - ${total - offset - limit} more ${label}; call query_active_work with section=${label}, offset=${offset + limit}, limit=${limit}` : null;
+    const daemon = status.daemonHealth;
+    const agentHealth = daemon?.agents[status.agentName];
+    const lines = ["## butler operational visibility"];
+    const error = (source) => status.sourceErrors[source] ? `unavailable (${status.sourceErrors[source]})` : null;
+    if (show("health")) {
+        lines.push(`- daemon: ${error("daemon_health") ?? daemon?.status ?? "unavailable"}${daemon ? `; mode ${daemon.mode}; pid ${daemon.pid}` : ""}`);
+        lines.push(`- butler: ${agentHealth ? `${agentHealth.status}; pid ${agentHealth.pid ?? "none"}; crashes ${agentHealth.crashes}` : "unavailable"}`);
+        lines.push("- senses:");
+        lines.push(...(error("senses") ? [`  - ${error("senses")}`] : status.senseStatusLines.length > 0 ? status.senseStatusLines.map((line) => `  ${line}`) : ["  - unavailable"]));
+        const health = status.healthState;
+        lines.push(`- health sweeps: ${error("health_state") ?? health?.sweepReceipts.length ?? 0}; delivered ${health?.deliveredReceipts.length ?? 0}; indeterminate ${health?.indeterminateDeliveries.length ?? 0}; outbox ${health?.outbox ? `${health.outbox.status}:${health.outbox.id}` : "clear"}; open incidents ${health ? Object.keys(health.incidents).length : 0}; updated ${health?.updatedAt ?? "unavailable"}`);
+        const healthRows = [
+            ...(health?.sweepReceipts ?? []).map((sweep) => ({ at: sweep.completedAt, text: `sweep ${sweep.sweepId}: opened ${sweep.opened}; recovered ${sweep.recovered}; completed ${sweep.completedAt}${sweep.deliveryId ? `; delivery ${sweep.deliveryId}` : ""}` })),
+            ...(health?.deliveredReceipts ?? []).map((delivery) => ({ at: delivery.deliveredAt, text: `delivered ${delivery.deliveryId}: ${delivery.kind}; messages ${delivery.messageIds.join(",")}; at ${delivery.deliveredAt}` })),
+            ...(health?.indeterminateDeliveries ?? []).map((delivery) => ({ at: delivery.createdAt, text: `indeterminate ${delivery.id}: ${delivery.kind}; ${delivery.status}; created ${delivery.createdAt}` })),
+        ].sort((a, b) => b.at.localeCompare(a.at));
+        for (const row of page(healthRows))
+            lines.push(`  - ${row.text}`);
+        const overflow = more("health", healthRows.length);
+        if (overflow)
+            lines.push(overflow);
+    }
+    if (show("provider"))
+        lines.push(`- provider lanes: ${error("provider") ?? (status.providerLanes ? `outward ${status.providerLanes.outward.provider}/${status.providerLanes.outward.model}; inner ${status.providerLanes.inner.provider}/${status.providerLanes.inner.model}` : "unavailable")}`);
+    if (show("policy")) {
+        lines.push(`- steward policy: ${error("steward_policy") ?? `version ${status.stewardPolicy.version}; ${Object.keys(status.stewardPolicy.desiredStates).length} desired states; ${Object.keys(status.stewardPolicy.routineActionGrants).length} routine grants`}`);
+        const entries = [...Object.entries(status.stewardPolicy.desiredStates).map(([key, value]) => ({ key, kind: "desired", value })), ...Object.entries(status.stewardPolicy.routineActionGrants).map(([key, value]) => ({ key, kind: "grant", value }))];
+        for (const entry of page(entries)) {
+            const expiry = entry.value.expiresAt;
+            const active = !expiry || Date.parse(expiry) > Date.now();
+            lines.push(entry.kind === "desired" ? `  - ${entry.key} = ${boundedStatusText(entry.value.value)}; ${active ? "active" : "expired"}; ${entry.value.provenance}; source ${boundedStatusText(entry.value.source)}; v${entry.value.version}${expiry ? `; expires ${expiry}` : ""}` : `  - ${entry.key}: ${entry.value.action} on ${entry.value.targets.join(", ")}; ${active ? "active" : "expired"}; max ${entry.value.maxCount}/${entry.value.windowMs}ms; ${entry.value.verificationRequired ? "verification required" : "no verification"}; v${entry.value.version}${expiry ? `; expires ${expiry}` : ""}`);
+        }
+        const overflow = more("policy", entries.length);
+        if (overflow)
+            lines.push(overflow);
+    }
+    if (show("actions")) {
+        const actions = [...(status.routineActions ?? [])].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        lines.push(`- routine action receipts: ${error("routine_actions") ?? actions.length}`);
+        for (const action of page(actions)) {
+            const verification = action.state === "verified" ? `verified ${action.verifiedAfterState ?? "state unavailable"}` : action.state === "failed" ? "failed" : action.state === "indeterminate" ? "indeterminate; manual inspection required" : action.state === "recovered_no_effect" ? "no effect occurred" : "pending";
+            lines.push(`  - ${action.id}: ${action.action} ${action.target}; ${action.state}; updated ${action.updatedAt}; verification ${verification}`);
+        }
+        const overflow = more("actions", actions.length);
+        if (overflow)
+            lines.push(overflow);
+    }
+    if (show("awaits")) {
+        lines.push(`- pending awaits: ${status.awaits.length}`);
+        if (error("awaits"))
+            lines.push(`  - ${error("awaits")}`);
+        for (const pending of page(status.awaits))
+            lines.push(`  - ${pending.name}: ${boundedStatusText(pending.condition ?? (pending.body || "condition unavailable"))}${pending.wake_at ? `; wake ${pending.wake_at}` : ""}`);
+        const overflow = more("awaits", status.awaits.length);
+        if (overflow)
+            lines.push(overflow);
+    }
+    if (show("telegram")) {
+        const acceptedTimes = status.telegramEffects.flatMap((effect) => effect.acceptedAt ? [effect.acceptedAt] : []).sort().reverse();
+        const recordedTimes = status.telegramEffects.flatMap((effect) => effect.sessionRecordedAt ? [effect.sessionRecordedAt] : []).sort().reverse();
+        const legacyAccepted = status.telegramEffects.some((effect) => !effect.acceptedAt && (effect.state === "accepted" || effect.state === "session_recorded"));
+        const legacyRecorded = status.telegramEffects.some((effect) => !effect.sessionRecordedAt && effect.state === "session_recorded");
+        lines.push(`- latest Telegram accepted: ${acceptedTimes[0] ?? (legacyAccepted ? "timestamp unavailable (legacy artifacts present)" : "none")}; latest session recorded: ${recordedTimes[0] ?? (legacyRecorded ? "timestamp unavailable (legacy artifacts present)" : "none")}`);
+        lines.push(`- Telegram effects: ${error("telegram_effects") ?? status.telegramEffects.length}`);
+        lines.push(`- Telegram admissions: ${error("telegram_admissions") ?? status.telegramAdmissions.length}`);
+        const telegramRows = [
+            ...status.telegramEffects.map((effect) => ({ at: effect.updatedAt, effect })),
+            ...status.telegramAdmissions.map((admission) => ({ at: new Date(admission.createdAt).toISOString(), admission })),
+        ].sort((a, b) => b.at.localeCompare(a.at));
+        for (const row of page(telegramRows)) {
+            if ("admission" in row) {
+                const admission = row.admission;
+                lines.push(`  - admission ${admission.id}: ${admission.status}; code ${admission.displayCode}; expires ${new Date(admission.expiresAt).toISOString()}`);
+                continue;
+            }
+            const effect = row.effect;
+            const accepted = effect.acceptedAt ?? ((effect.state === "accepted" || effect.state === "session_recorded") ? "timestamp unavailable (legacy)" : "not accepted");
+            const recorded = effect.sessionRecordedAt ?? (effect.state === "session_recorded" ? "timestamp unavailable (legacy)" : "not recorded");
+            lines.push(`  - ${effect.id}: ${effect.state}; ${effect.authorClass}; ${effect.targetKind}; accepted ${accepted}; session recorded ${recorded}; message ids ${effect.messageIds?.join(",") || "none"}; session events ${effect.sessionEventIds?.join(",") || "none"}; updated ${effect.updatedAt}`);
+        }
+        const overflow = more("telegram", telegramRows.length);
+        if (overflow)
+            lines.push(overflow);
+    }
+    if (show("events")) {
+        const events = [...status.externalEvents].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+        const completedRun = status.lastAutomatedEventRun;
+        lines.push(`- external issues: ${events.length}; last successful automated event turn ${error("run_ledger") ?? (completedRun ? `${completedRun.endedAt ?? completedRun.recordedAt}; run ${completedRun.runId}; target ${completedRun.targetHash}` : "none")}`);
+        if (error("external_events"))
+            lines.push(`  - ${error("external_events")}`);
+        for (const event of page(events)) {
+            const policy = event.stewardPolicy?.kind === "current" ? `${event.stewardPolicy.key}@${event.stewardPolicy.version}` : "none";
+            lines.push(`  - ${event.source}/${event.eventType}/${event.eventId}: ${event.executionState}; disposition ${event.classification ?? "pending"}/${event.decision ?? "pending"}; reason ${boundedStatusText(event.reason ?? event.lastError ?? "not yet recorded")}; silence/wake ${event.nextWake ? JSON.stringify(event.nextWake) : "pending"}; steward ${policy}${event.awaitId ? `; await ${event.awaitId}` : ""}${event.careId ? `; care ${event.careId}` : ""}`);
+        }
+        const overflow = more("events", events.length);
+        if (overflow)
+            lines.push(overflow);
+    }
+    return lines.join("\n");
+}
 function findDelegatingBridgeId(ctx) {
     const currentSession = ctx?.currentSession;
     if (!currentSession)
@@ -422,16 +629,24 @@ exports.sessionToolDefinitions = [
             type: "function",
             function: {
                 name: "query_active_work",
-                description: "read the current live world-state across visible sessions, coding lanes, private-runtime work, and return obligations. use this instead of piecing status together from separate session and coding tools.",
+                description: "read the current live world-state across visible sessions, coding lanes, private-runtime work, and return obligations. Sanctuary operational details support bounded section/offset/limit paging.",
                 parameters: {
                     type: "object",
-                    properties: {},
+                    properties: {
+                        section: { type: "string", enum: ["all", "health", "policy", "awaits", "telegram", "events", "actions", "provider"], description: "Sanctuary detail section; defaults to all" },
+                        offset: { type: "string", description: "zero-based detail offset; defaults to 0" },
+                        limit: { type: "string", description: "detail rows per section, 1-20; defaults to 10" },
+                    },
                 },
             },
         },
-        handler: async (_args, ctx) => {
+        handler: async (args, ctx) => {
             const frame = await buildToolActiveWorkFrame(ctx);
-            return `this is my current top-level live world-state.\nanswer whole-self status questions from this before drilling into individual sessions.\n\n${(0, active_work_1.formatActiveWorkFrame)(frame)}`;
+            const activeWork = `this is my current top-level live world-state.\nanswer whole-self status questions from this before drilling into individual sessions.\n\n${(0, active_work_1.formatActiveWorkFrame)(frame)}`;
+            const numeric = (value, fallback, min, max) => value === undefined ? fallback : /^\d+$/u.test(value) ? Math.min(max, Math.max(min, Number(value))) : fallback;
+            return (0, identity_1.getAgentName)() === "sanctuary"
+                ? `${activeWork}\n\n${formatButlerOperationalVisibility(readButlerOperationalVisibility(), { section: args.section, offset: numeric(args.offset, 0, 0, 10_000), limit: numeric(args.limit, 10, 1, 20) })}`
+                : activeWork;
         },
     },
     {

package/dist/repertoire/tools-steward-policy.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stewardPolicyToolDefinition = void 0;
+const steward_policy_1 = require("../heart/steward-policy");
+const runtime_1 = require("../nerves/runtime");
+function arrayArgument(raw, label) {
+    if (!raw)
+        throw new Error(`${label} is required`);
+    const value = JSON.parse(raw);
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string"))
+        throw new Error(`${label} must be a JSON string array`);
+    return value;
+}
+exports.stewardPolicyToolDefinition = {
+    tool: {
+        type: "function",
+        function: {
+            name: "steward_policy_manage",
+            description: "Read or update the household steward's typed desired-state and routine-action policy. Updates require the current authenticated family request and exact policy version.",
+            parameters: {
+                type: "object",
+                properties: {
+                    action: { type: "string", enum: ["read", "set_desired_state", "grant_routine_action"] },
+                    expectedVersion: { type: "integer", minimum: 0 },
+                    key: { type: "string" },
+                    value: { type: "string" },
+                    provenance: { type: "string", enum: ["stated", "observed", "default", "installed_explicit_policy"] },
+                    source: { type: "string" },
+                    routineAction: { type: "string" },
+                    targetsJson: { type: "string", description: "JSON array of exact target names" },
+                    maxCount: { type: "integer", minimum: 1 },
+                    windowMs: { type: "integer", minimum: 1 },
+                    verificationRequired: { type: "boolean" },
+                    exclusionsJson: { type: "string", description: "JSON array of exact excluded target names" },
+                    expiresAt: { type: "string" },
+                },
+                required: ["action"],
+                additionalProperties: false,
+            },
+        },
+    },
+    handler: (args, ctx) => {
+        if (!ctx?.agentRoot)
+            throw new Error("steward policy runtime is unavailable");
+        if (!ctx.relationshipAuthorization)
+            throw new Error("steward policy access requires authenticated relationship authority");
+        if (args.action === "read") {
+            (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.steward_policy_tool_call", message: "read steward policy", meta: { action: "read" } });
+            return JSON.stringify((0, steward_policy_1.readStewardPolicy)(ctx.agentRoot));
+        }
+        const actor = ctx.relationshipAuthorization?.actor;
+        if (!actor)
+            throw new Error("steward policy mutation requires authenticated relationship authority");
+        const expectedVersion = Number(args.expectedVersion);
+        if (!Number.isInteger(expectedVersion) || expectedVersion < 0)
+            throw new Error("expectedVersion must be a nonnegative integer");
+        let mutation;
+        if (args.action === "set_desired_state") {
+            if (args.provenance !== "stated" && args.provenance !== "observed" && args.provenance !== "default")
+                throw new Error("desired state provenance is invalid");
+            mutation = { kind: "set_desired_state", key: args.key ?? "", value: args.value ?? "", provenance: args.provenance, source: args.source ?? "", ...(args.expiresAt ? { expiresAt: args.expiresAt } : {}) };
+        }
+        else if (args.action === "grant_routine_action") {
+            if (args.provenance !== "stated" && args.provenance !== "installed_explicit_policy")
+                throw new Error("routine action provenance is invalid");
+            mutation = {
+                kind: "grant_routine_action",
+                key: args.key ?? "",
+                action: args.routineAction ?? "",
+                targets: arrayArgument(args.targetsJson, "targetsJson"),
+                maxCount: Number(args.maxCount),
+                windowMs: Number(args.windowMs),
+                verificationRequired: args.verificationRequired === "true",
+                exclusions: arrayArgument(args.exclusionsJson, "exclusionsJson"),
+                provenance: args.provenance,
+                ...(args.expiresAt ? { expiresAt: args.expiresAt } : {}),
+            };
+        }
+        else
+            throw new Error("steward policy action is invalid");
+        const result = (0, steward_policy_1.updateStewardPolicy)(ctx.agentRoot, { expectedVersion, actor, mutation });
+        (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.steward_policy_tool_call", message: "updated steward policy", meta: { action: args.action } });
+        return JSON.stringify(result);
+    },
+    riskProfile: (args) => args.action === "read"
+        ? { mutates: "none", risk: "low" }
+        : { mutates: "durable_state_write", risk: "high", reason: "updates typed household steward policy under authenticated family authority" },
+};

package/dist/repertoire/tools-telegram-contacts.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.telegramContactToolDefinition = void 0;
+const runtime_1 = require("../nerves/runtime");
+exports.telegramContactToolDefinition = {
+    tool: { type: "function", function: {
+            name: "telegram_contact_manage",
+            description: "List household Telegram contacts, revoke one exact approved contact, or release one exact blocked contact request. Owner only; quarantined message text is never returned.",
+            parameters: { type: "object", properties: {
+                    action: { type: "string", enum: ["list", "revoke", "unblock"] },
+                    friendId: { type: "string", description: "Exact Friend ID from list; required for revoke." },
+                    admissionId: { type: "string", description: "Exact blocked admission ID from list; required for unblock." },
+                }, required: ["action"], additionalProperties: false },
+        } },
+    handler: async (args, ctx) => {
+        const actor = ctx?.relationshipAuthorization?.actor;
+        const manager = ctx?.telegramContactManager;
+        if (!actor || actor.trustLevel !== "family" || !manager)
+            return JSON.stringify({ ok: false, error: "Telegram contact management requires the live owner relationship" });
+        const action = String(args.action ?? "");
+        if (action === "list")
+            return JSON.stringify({ ok: true, ...(await manager.list({ actorFriendId: actor.friendId })) });
+        if (action === "revoke" && typeof args.friendId === "string" && args.friendId.trim())
+            return JSON.stringify({ ok: true, ...(await manager.revoke({ actorFriendId: actor.friendId, friendId: args.friendId })) });
+        if (action === "unblock" && typeof args.admissionId === "string" && args.admissionId.trim())
+            return JSON.stringify({ ok: true, ...(await manager.unblock({ actorFriendId: actor.friendId, admissionId: args.admissionId })) });
+        return JSON.stringify({ ok: false, error: "Telegram contact management arguments are invalid" });
+    },
+    riskProfile: (args) => String(args.action) === "list" ? { mutates: "none", risk: "low" } : { mutates: "durable_state_write", risk: "high", reason: "changes one exact household Telegram admission" },
+    approvalPolicy: () => ({ kind: "not_required" }),
+};
+(0, runtime_1.emitNervesEvent)({
+    component: "repertoire",
+    event: "repertoire.telegram_contact_tool_loaded",
+    message: "Telegram contact management tool loaded",
+    meta: { operations: 3 },
+});

package/dist/repertoire/tools-unraid.js

@@ -6,6 +6,9 @@ exports.createUnraidReadTools = createUnraidReadTools;
 const node_crypto_1 = require("node:crypto");
 const runtime_1 = require("../nerves/runtime");
 const unraid_client_1 = require("./unraid-client");
+const tools_base_1 = require("./tools-base");
+const steward_policy_1 = require("../heart/steward-policy");
+const obligations_1 = require("../arc/obligations");
 exports.SANCTUARY_CONTAINERS_QUERY = `query SanctuaryContainers {
   docker { containers(skipCache: true) { id names state status autoStart } }
 }`;
@@ -16,6 +19,7 @@ exports.SANCTUARY_STORAGE_QUERY = `query SanctuaryStorage {
   vars { id }
   array { state capacity { kilobytes { used free total } } }
   shares { id name used free size }
+  docker { containers(skipCache: true) { id names state status autoStart } }
 }`;
 exports.SANCTUARY_DISKS_QUERY = `query SanctuaryDisks {
   disks { id name smartStatus temperature }
@@ -197,7 +201,30 @@ function createUnraidReadTools(client) {
                     const free = numberOrNull(item.free);
                     return { name, usedBytes: used, freeBytes: free, usedPercent: percent(used, free), degraded: used === null || free === null };
                 }).sort((a, b) => a.name.localeCompare(b.name));
-                return { ok: true, data: { sourceIdentityDigest, array: { state: state.value, usedBytes, freeBytes, usedPercent: percent(usedBytes, freeBytes), degraded: state.truncated || usedBytes === null || freeBytes === null }, shares, truncated } };
+                const largestCandidates = shares
+                    .filter((share) => share.usedBytes !== null && share.usedBytes > 0)
+                    .sort((a, b) => Number(b.usedBytes) - Number(a.usedBytes) || a.name.localeCompare(b.name))
+                    .slice(0, 10)
+                    .map((share) => ({ kind: "share", name: share.name, usedBytes: share.usedBytes }));
+                let unmanic = { state: "unknown", degraded: true };
+                if (data.docker && typeof data.docker === "object" && !Array.isArray(data.docker)) {
+                    const matches = mapContainers(data).containers.filter((container) => container.name === "unmanic");
+                    if (matches.length === 1)
+                        unmanic = { state: matches[0].state, degraded: matches[0].degraded };
+                }
+                return { ok: true, data: {
+                        sourceIdentityDigest,
+                        array: { state: state.value, usedBytes, freeBytes, usedPercent: percent(usedBytes, freeBytes), degraded: state.truncated || usedBytes === null || freeBytes === null },
+                        shares,
+                        largestCandidates,
+                        optimization: {
+                            unmanic,
+                            estimatedReclaimableBytes: null,
+                            estimateConfidence: "unavailable",
+                            reason: "Share usage is real, but the read-only Unraid API does not expose bounded file-level codec evidence; no savings estimate is claimed.",
+                        },
+                        truncated,
+                    } };
             }
             catch (error) {
                 return fail(error);
@@ -284,6 +311,52 @@ const emptyParameters = { type: "object", properties: {}, additionalProperties:
 function missingRuntime() {
     return JSON.stringify({ ok: false, error: { code: "invalid_response", message: "Sanctuary runtime is unavailable", degraded: true } });
 }
+function householdRepairObligation(ctx, target) {
+    const requester = (0, tools_base_1.routineActionRequester)(ctx);
+    if (requester?.kind !== "household_request")
+        return null;
+    if (!ctx.agentRoot)
+        throw new Error("household repair request tracking is unavailable");
+    const existing = (0, obligations_1.findPendingObligationForRequest)(ctx.agentRoot, { requestId: requester.requestId, owedTo: requester.origin });
+    if (existing)
+        return existing;
+    return (0, obligations_1.createObligation)(ctx.agentRoot, {
+        origin: requester.origin,
+        owedTo: requester.origin,
+        requestId: requester.requestId,
+        sourceProvenance: { kind: "human_request", source: requester.origin.channel, ref: `request:${requester.requestId}` },
+        content: `Restore Sanctuary service ${target} and report the outcome`,
+        currentSurface: { kind: "runtime", label: `Sanctuary container ${target}` },
+        nextAction: `Restart ${target} under the Butler's standing grant and verify recovery`,
+    });
+}
+async function runTrackedRestart(ctx, target, routine) {
+    const obligation = householdRepairObligation(ctx, target);
+    if (obligation && ctx.agentRoot)
+        (0, obligations_1.advanceObligation)(ctx.agentRoot, obligation.id, { status: "updating_runtime", latestNote: `Starting the requested restart of ${target}` });
+    try {
+        const result = await ctx.sanctuary.restartContainer({ container: target }, routine ? { routine } : undefined);
+        if (obligation && ctx.agentRoot) {
+            const succeeded = !!result && typeof result === "object" && !Array.isArray(result) && result.ok === true;
+            if (succeeded)
+                (0, obligations_1.advanceObligation)(ctx.agentRoot, obligation.id, {
+                    status: "updating_runtime",
+                    latestNote: `The requested restart of ${target} verified recovery`,
+                    nextAction: "Report the verified outcome to the exact requester",
+                });
+            else
+                (0, obligations_1.advanceObligation)(ctx.agentRoot, obligation.id, { status: "investigating", latestNote: `The requested restart of ${target} did not verify recovery`, nextAction: `Diagnose ${target} and report back to the requester` });
+            if (succeeded)
+                (0, obligations_1.markObligationReturnReady)(ctx.agentRoot, obligation.id, `unraid-restart:${target}:verified`);
+        }
+        return result;
+    }
+    catch (error) {
+        if (obligation && ctx.agentRoot)
+            (0, obligations_1.advanceObligation)(ctx.agentRoot, obligation.id, { status: "investigating", latestNote: `The requested restart of ${target} failed`, nextAction: `Diagnose ${target} and report back to the requester` });
+        throw error;
+    }
+}
 function readDefinition(name, description, method) {
     return {
         tool: { type: "function", function: { name, description, parameters: emptyParameters } },
@@ -319,12 +392,20 @@ exports.unraidToolDefinitions = [
     readDefinition("unraid_get_disks", "Read bounded Sanctuary disk SMART, temperature, and parity health.", "getDisks"),
     readDefinition("unraid_get_notifications", "Read bounded unacknowledged Sanctuary notifications.", "getNotifications"),
     readDefinition("unraid_get_system", "Read bounded Sanctuary system and version health.", "getSystem"),
+    readDefinition("unraid_check_services", "Freshly check the fixed public Sanctuary service endpoints and return bounded status with an observation timestamp.", "checkServices"),
+    readDefinition("sanctuary_get_download_queue", "Read the bounded live household download queue state, including whether the spend guard has paused it.", "getDownloadQueue"),
+    {
+        tool: { type: "function", function: { name: "sanctuary_resume_download_queue", description: "Resume the household download queue after Ari confirms the provider is ready, then independently verify paused=false. This can spend prepaid download credit.", parameters: emptyParameters } },
+        handler: async (_args, ctx) => JSON.stringify(ctx?.sanctuary ? await ctx.sanctuary.resumeDownloadQueue() : JSON.parse(missingRuntime())),
+        riskProfile: { mutates: "external_side_effect", risk: "high", reason: "resumes downloads that can spend prepaid provider credit" },
+        approvalPolicy: () => ({ kind: "required", policyId: "sanctuary.downloads.resume.v1", actionClass: "sanctuary.downloads.resume", requiresSoleCall: true }),
+    },
     {
         tool: {
             type: "function",
             function: {
                 name: "unraid_restart_container",
-                description: "Propose restarting one exact existing allowlisted Sanctuary container. Execution requires human approval.",
+                description: "Restart one exact existing allowlisted Sanctuary container when standing policy allows; otherwise request approval.",
                 parameters: {
                     type: "object",
                     properties: { container: { type: "string" } },
@@ -333,9 +414,35 @@ exports.unraidToolDefinitions = [
                 },
             },
         },
-        handler: async (args, ctx) => JSON.stringify(ctx?.sanctuary
-            ? await ctx.sanctuary.restartContainer({ container: String(args.container) })
-            : JSON.parse(missingRuntime())),
+        handler: async (args, ctx) => {
+            if (!ctx?.sanctuary)
+                return missingRuntime();
+            const target = String(args.container);
+            let routine;
+            if (ctx.routineActionSelection) {
+                if (!ctx.agentRoot || !(0, tools_base_1.routineActionRequester)(ctx))
+                    return JSON.stringify({ ok: false, error: { code: "approval_required", message: "routine action authorization is unavailable", degraded: true } });
+                const { key, expectedPolicyVersion } = ctx.routineActionSelection;
+                if (ctx.routineActionSelection.target !== target)
+                    return JSON.stringify({ ok: false, error: { code: "approval_required", message: "routine action arguments changed", degraded: true } });
+                const decision = (0, steward_policy_1.inspectRoutineActionGrant)(ctx.agentRoot, { key, action: "unraid.container.restart", target, expectedPolicyVersion });
+                if (!decision.allowed)
+                    return JSON.stringify({ ok: false, error: { code: "approval_required", message: decision.reason, degraded: true } });
+                routine = {
+                    key,
+                    expectedPolicyVersion: decision.policyVersion,
+                    reauthorize: async () => {
+                        const authorization = await ctx.relationshipAuthorization.authorizeTool("unraid_restart_container", { container: target });
+                        if (!authorization.allowed)
+                            return authorization;
+                        if (!Number.isInteger(authorization.profileVersion) || Number(authorization.profileVersion) < 1)
+                            return { allowed: false, reason: "relationship capability profile is not versioned" };
+                        return { allowed: true, receiptId: authorization.receiptId, profileVersion: Number(authorization.profileVersion) };
+                    },
+                };
+            }
+            return JSON.stringify(await runTrackedRestart(ctx, target, routine));
+        },
         riskProfile: { mutates: "external_side_effect", risk: "high", reason: "restarts one existing allowlisted Docker container" },
         approvalPolicy: () => ({
             kind: "required",
@@ -349,5 +456,5 @@ exports.unraidToolDefinitions = [
     component: "repertoire",
     event: "repertoire.unraid_tools_loaded",
     message: "typed Unraid tools loaded",
-    meta: { operations: 6 },
+    meta: { operations: 9 },
 });