@ouro.bot/cli 0.1.0-alpha.96 → 0.1.0-alpha.961

package/dist/senses/mail.js

@@ -0,0 +1,524 @@
+"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.scanMailImportDiscoveryAttention = scanMailImportDiscoveryAttention;
+exports.startMailSenseApp = startMailSenseApp;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+const identity_1 = require("../heart/identity");
+const runtime_credentials_1 = require("../heart/runtime-credentials");
+const pending_1 = require("../mind/pending");
+const socket_client_1 = require("../heart/daemon/socket-client");
+const background_operations_1 = require("../heart/background-operations");
+const mail_import_discovery_1 = require("../heart/mail-import-discovery");
+const attention_1 = require("../mailroom/attention");
+const reader_1 = require("../mailroom/reader");
+const smtp_ingress_1 = require("../mailroom/smtp-ingress");
+function readRegistry(registryPath) {
+    return JSON.parse(fs.readFileSync(registryPath, "utf-8"));
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function unverifiableCoverage(checkedAt, reason) {
+    return { status: "could-not-verify", declaredKeyIds: [], absentKeyIds: [], reason, checkedAt };
+}
+/**
+ * Key ids the registry says mail can currently be encrypted to for this agent.
+ *
+ * Filtered to this agent because the hosted registry is domain-wide: counting
+ * every agent's records would report another agent's keys as absent on every
+ * cycle, and a check that always fails is a check operators learn to ignore.
+ *
+ * The match is case-insensitive. The harness sends `agentId: agent` verbatim to
+ * hosted Mail Control while this repo's own hosted ensure-response fixture
+ * returns the lowercased form for that same request, so a registry record's
+ * agent id can differ from the sense's agent name by case alone. Case-sensitive
+ * matching would then declare nothing and report `could-not-verify` forever —
+ * the same silence this probe exists to end. Widening the match cannot produce
+ * a false `absent` unless two agents differ only by case, which the store and
+ * address resolvers could not tell apart either.
+ *
+ * Disabled source grants are excluded because `resolveMailAddress`
+ * (`mailroom/core.ts`) refuses their alias outright, so no new mail can be
+ * encrypted to their key and a missing private half is not a live gap.
+ */
+function registryDeclaredKeyIds(registry, agentName) {
+    const wanted = agentName.toLowerCase();
+    const isThisAgent = (agentId) => agentId.toLowerCase() === wanted;
+    const declared = [
+        ...registry.mailboxes.filter((mailbox) => isThisAgent(mailbox.agentId)).map((mailbox) => mailbox.keyId),
+        ...registry.sourceGrants.filter((grant) => isThisAgent(grant.agentId) && grant.enabled).map((grant) => grant.keyId),
+    ];
+    return [...new Set(declared.filter((keyId) => keyId.trim().length > 0))];
+}
+/**
+ * Mail key ids the vault can actually decrypt with, read fresh rather than
+ * taken from the reader resolution captured at sense startup — a sense that has
+ * been up for days would otherwise measure a key set the vault has since
+ * changed, and report a rotation as a loss.
+ *
+ * Throws rather than returning empty when the read is untrustworthy, so the
+ * caller classifies it `could-not-verify` instead of `absent`. An empty-but-
+ * present `privateKeys` record is a real observation and is not a throw.
+ */
+function vaultMailKeyIds(agentName) {
+    const runtime = (0, runtime_credentials_1.readRuntimeCredentialConfig)(agentName);
+    if (!runtime.ok)
+        throw new Error(`vault ${runtime.itemPath} read is ${runtime.reason}`);
+    const mailroom = runtime.config.mailroom;
+    const privateKeys = isRecord(mailroom) ? mailroom.privateKeys : undefined;
+    if (!isRecord(privateKeys))
+        throw new Error(`vault ${runtime.itemPath} has no mailroom.privateKeys record`);
+    return Object.entries(privateKeys)
+        .filter((entry) => typeof entry[1] === "string" && entry[1].trim().length > 0)
+        .map((entry) => entry[0]);
+}
+/**
+ * Never throws: every failure degrades to `could-not-verify`. `scan()` is
+ * awaited during sense startup, so a throw here would stop the mail sense from
+ * starting — an integrity probe must not be able to take mail down.
+ */
+async function computeMailKeyCoverage(input) {
+    try {
+        const registry = await input.readRegistry(input.config);
+        const declaredKeyIds = registryDeclaredKeyIds(registry, input.agentName);
+        if (declaredKeyIds.length === 0) {
+            // Nothing to check against is not the same as nothing wrong: reporting
+            // `covered` for an empty declaration would turn an unprovisioned or
+            // wrong registry into a green light.
+            return unverifiableCoverage(input.checkedAt, `mailroom registry declares no mail keys for ${input.agentName}`);
+        }
+        const present = new Set(vaultMailKeyIds(input.agentName));
+        const absentKeyIds = declaredKeyIds.filter((keyId) => !present.has(keyId));
+        return {
+            status: absentKeyIds.length === 0 ? "covered" : "absent",
+            declaredKeyIds,
+            absentKeyIds,
+            reason: null,
+            checkedAt: input.checkedAt,
+        };
+    }
+    catch (error) {
+        return unverifiableCoverage(input.checkedAt, error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * Coverage has to push, not wait to be asked. `ouro doctor` is on-demand — it
+ * has no scheduled invocation — so a doctor line alone leaves a gap invisible
+ * until someone happens to run it, which is how `mail_slugger-hey_6e7b4bfa34c0b826`
+ * stayed unnoticed for 23 hours while mail encrypted to it piled up unreadable.
+ */
+function emitMailKeyCoverageEvents(agentName, coverage) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.mail_key_coverage_recorded",
+        message: "mail key coverage recorded",
+        meta: {
+            agentName,
+            status: coverage.status,
+            declaredCount: coverage.declaredKeyIds.length,
+            absentCount: coverage.absentKeyIds.length,
+            reason: coverage.reason,
+        },
+    });
+    if (coverage.status !== "absent")
+        return;
+    (0, runtime_1.emitNervesEvent)({
+        level: "error",
+        component: "senses",
+        event: "senses.mail_key_coverage_absent",
+        message: `mailroom registry declares mail keys with no private half in ${agentName}'s vault: ${coverage.absentKeyIds.join(", ")}`,
+        meta: {
+            agentName,
+            absentKeyIds: coverage.absentKeyIds,
+            declaredKeyIds: coverage.declaredKeyIds,
+        },
+    });
+}
+function validPort(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 65535 ? value : 0;
+}
+function serverAddress(server) {
+    const direct = server;
+    if (typeof direct.address === "function")
+        return direct.address();
+    const wrapped = server;
+    if (typeof wrapped.server?.address === "function")
+        return wrapped.server.address();
+    return null;
+}
+function serverPort(server) {
+    const address = serverAddress(server);
+    if (!address || typeof address !== "object")
+        return null;
+    return typeof address.port === "number" ? address.port : null;
+}
+function listeningServer(server) {
+    const wrapped = server;
+    if (typeof wrapped.server?.once === "function")
+        return wrapped.server;
+    const direct = server;
+    return typeof direct.once === "function" ? direct : null;
+}
+function waitForListening(server) {
+    if (serverAddress(server))
+        return Promise.resolve();
+    const listening = listeningServer(server);
+    if (!listening)
+        return new Promise((resolve) => setImmediate(resolve));
+    if (listening.listening)
+        return Promise.resolve();
+    return new Promise((resolve) => listening.once?.("listening", resolve));
+}
+function runtimeStatePath(agentName) {
+    return path.join((0, identity_1.getAgentRoot)(agentName), "state", "senses", "mail", "runtime.json");
+}
+function attentionStatePath(agentName) {
+    return path.join((0, identity_1.getAgentRoot)(agentName), "state", "senses", "mail", "attention.json");
+}
+function importDiscoveryStatePath(agentName) {
+    return path.join((0, identity_1.getAgentRoot)(agentName), "state", "senses", "mail", "import-discovery.json");
+}
+function writeRuntimeState(filePath, state) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.mail_sense_runtime_state_written",
+        message: "mail sense runtime state written",
+        meta: { agentName: state.agentName, status: state.status, lastQueuedCount: state.lastQueuedCount },
+    });
+}
+function emptyImportDiscoveryState(updatedAt) {
+    return {
+        schemaVersion: 1,
+        lastNotifiedFingerprint: null,
+        updatedAt,
+    };
+}
+function readImportDiscoveryState(filePath, updatedAt) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        return {
+            schemaVersion: 1,
+            lastNotifiedFingerprint: typeof parsed.lastNotifiedFingerprint === "string" && parsed.lastNotifiedFingerprint.trim().length > 0
+                ? parsed.lastNotifiedFingerprint
+                : null,
+            updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : updatedAt,
+        };
+    }
+    catch {
+        return emptyImportDiscoveryState(updatedAt);
+    }
+}
+function writeImportDiscoveryState(filePath, state) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+}
+function candidateDescriptors(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((entry) => !!entry && typeof entry === "object" && !Array.isArray(entry))
+        .map((entry) => ({
+        path: typeof entry.path === "string" ? entry.path : "",
+        originKind: typeof entry.originKind === "string" ? entry.originKind : undefined,
+        originLabel: typeof entry.originLabel === "string" ? entry.originLabel : undefined,
+    }))
+        .filter((entry) => entry.path.trim().length > 0);
+}
+function renderImportDiscoveryContent(candidatePaths, descriptors) {
+    const renderedCandidates = descriptors.length > 0
+        ? descriptors.map((descriptor) => `- [${descriptor.originLabel ?? descriptor.originKind ?? "filesystem"}] ${descriptor.path}`)
+        : candidatePaths.map((candidatePath) => `- ${candidatePath}`);
+    return [
+        "[Mail Import Ready]",
+        "A local MBOX archive is ready for delegated-mail backfill.",
+        "This may live in a worktree-local Playwright sandbox rather than ~/Downloads.",
+        "",
+        "recent candidates:",
+        ...renderedCandidates,
+        "",
+        "If this matches an expected mailbox backfill, run `ouro mail import-mbox --discover --owner-email <email> --source hey --agent <agent>` first so Ouro can pick the matching archive or report ambiguity.",
+    ].join("\n");
+}
+function buildMailImportDiscoveryPrivateWakeOptions(input) {
+    return {
+        reason: "mail import discovery private attention",
+        triggerSource: "mail-import-discovery",
+        budgetClass: "interactive",
+        idempotencyKey: `mail-import-discovery:${input.agentName}:${input.fingerprint}`,
+        originRefs: [
+            { kind: "mail-import-discovery", id: input.fingerprint },
+            ...input.candidatePaths.map((candidatePath) => ({ kind: "mail-import-candidate", id: candidatePath })),
+        ],
+    };
+}
+async function scanMailImportDiscoveryAttention(input) {
+    const nowMs = input.now?.() ?? Date.now();
+    const updatedAt = new Date(nowMs).toISOString();
+    const statePath = input.statePath ?? importDiscoveryStatePath(input.agentName);
+    const pendingDir = input.pendingDir ?? (0, pending_1.getPrivateRuntimePendingDir)(input.agentName);
+    const state = readImportDiscoveryState(statePath, updatedAt);
+    const existingOperations = (0, background_operations_1.listBackgroundOperations)({
+        agentName: input.agentName,
+        agentRoot: (0, identity_1.getAgentRoot)(input.agentName),
+        limit: 10,
+    });
+    const discovered = (0, mail_import_discovery_1.listAmbientMailImportOperations)({
+        agentName: input.agentName,
+        agentRoot: (0, identity_1.getAgentRoot)(input.agentName),
+        existingOperations,
+        repoRoot: (0, identity_1.getRepoRoot)(),
+        homeDir: process.env.HOME,
+        nowMs,
+    })[0] ?? null;
+    const fingerprint = typeof discovered?.spec?.fingerprint === "string" && discovered.spec.fingerprint.trim().length > 0
+        ? discovered.spec.fingerprint
+        : null;
+    const candidatePaths = stringArray(discovered?.spec?.candidatePaths);
+    const descriptors = candidateDescriptors(discovered?.spec?.candidateDescriptors);
+    const shouldQueue = Boolean(discovered && fingerprint && fingerprint !== state.lastNotifiedFingerprint);
+    if (shouldQueue && fingerprint) {
+        (0, pending_1.queuePendingMessage)(pendingDir, {
+            from: "mailroom",
+            friendId: "self",
+            channel: "mail",
+            key: "import-ready",
+            content: renderImportDiscoveryContent(candidatePaths, descriptors),
+            timestamp: nowMs,
+            mode: "reflect",
+        });
+        await (0, socket_client_1.requestPrivateWake)(input.agentName, undefined, buildMailImportDiscoveryPrivateWakeOptions({
+            agentName: input.agentName,
+            fingerprint,
+            candidatePaths,
+        })).catch(() => undefined);
+    }
+    writeImportDiscoveryState(statePath, {
+        schemaVersion: 1,
+        lastNotifiedFingerprint: shouldQueue ? fingerprint : state.lastNotifiedFingerprint,
+        updatedAt,
+    });
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.mail_import_discovery_scanned",
+        message: "mail import discovery scanned",
+        meta: {
+            agentName: input.agentName,
+            queued: shouldQueue,
+            candidateCount: candidatePaths.length,
+            fingerprint,
+        },
+    });
+    return {
+        queued: shouldQueue,
+        fingerprint,
+        candidatePaths,
+    };
+}
+function closeServer(server) {
+    return new Promise((resolve) => {
+        server.close(resolve);
+    });
+}
+async function startMailSenseApp(options) {
+    const now = options.now ?? (() => Date.now());
+    /* v8 ignore next -- production wiring uses the default vault refresh; tests inject a deterministic refresh. @preserve */
+    const refreshRuntime = options.refreshRuntime ?? runtime_credentials_1.refreshRuntimeCredentialConfig;
+    await refreshRuntime(options.agentName, { preserveCachedOnFailure: true }).catch(() => undefined);
+    const resolved = options.resolveReader
+        ? options.resolveReader(options.agentName)
+        : (0, reader_1.resolveMailroomReader)(options.agentName);
+    if (!resolved.ok) {
+        throw new Error(resolved.error);
+    }
+    const hostedReaderOnly = resolved.storeKind === "azure-blob" && !resolved.config.registryPath;
+    if (!resolved.config.registryPath && !hostedReaderOnly) {
+        throw new Error(`missing mailroom.registryPath for ${options.agentName}; agent-runnable repair: 'ouro connect mail --agent ${options.agentName}'`);
+    }
+    const host = resolved.config.host ?? "127.0.0.1";
+    const ingress = hostedReaderOnly
+        ? null
+        : (options.startIngress ?? smtp_ingress_1.startMailroomIngress)({
+            registry: readRegistry(resolved.config.registryPath),
+            store: resolved.store,
+            smtpPort: validPort(resolved.config.smtpPort),
+            httpPort: validPort(resolved.config.httpPort),
+            host,
+        });
+    if (ingress) {
+        await Promise.all([
+            waitForListening(ingress.smtp),
+            waitForListening(ingress.health),
+        ]);
+    }
+    const activeSmtpPort = () => ingress ? serverPort(ingress.smtp) : null;
+    const activeHttpPort = () => ingress ? serverPort(ingress.health) : null;
+    const runtimePath = runtimeStatePath(options.agentName);
+    const attentionPath = attentionStatePath(options.agentName);
+    const importDiscoveryPath = importDiscoveryStatePath(options.agentName);
+    let lastScanAt = null;
+    let lastQueuedCount = 0;
+    let lastKeyCoverage = unverifiableCoverage(new Date(now()).toISOString(), "mail key coverage not probed yet");
+    const scan = async () => {
+        const scanStartedAt = new Date(now()).toISOString();
+        let queuedCount = 0;
+        try {
+            const screener = await (0, attention_1.scanMailScreenerAttention)({
+                agentName: options.agentName,
+                store: resolved.store,
+                pendingDir: (0, pending_1.getPrivateRuntimePendingDir)(options.agentName),
+                statePath: attentionPath,
+                now,
+            });
+            queuedCount += screener.queued.length;
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.mail_sense_scan_error",
+                message: "mail sense attention scan failed",
+                meta: { agentName: options.agentName, error: error instanceof Error ? error.message : String(error) },
+            });
+        }
+        try {
+            const importDiscovery = await scanMailImportDiscoveryAttention({
+                agentName: options.agentName,
+                pendingDir: (0, pending_1.getPrivateRuntimePendingDir)(options.agentName),
+                statePath: importDiscoveryPath,
+                now,
+            });
+            if (importDiscovery.queued) {
+                queuedCount += 1;
+            }
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.mail_import_discovery_scan_error",
+                message: "mail import discovery scan failed",
+                meta: { agentName: options.agentName, error: error instanceof Error ? error.message : String(error) },
+            });
+        }
+        lastKeyCoverage = await computeMailKeyCoverage({
+            agentName: options.agentName,
+            config: resolved.config,
+            readRegistry: options.readRegistry ?? reader_1.readMailroomRegistry,
+            checkedAt: scanStartedAt,
+        });
+        emitMailKeyCoverageEvents(options.agentName, lastKeyCoverage);
+        lastScanAt = scanStartedAt;
+        lastQueuedCount = queuedCount;
+        writeRuntimeState(runtimePath, {
+            schemaVersion: 1,
+            agentName: options.agentName,
+            status: "running",
+            mailboxAddress: resolved.config.mailboxAddress,
+            smtpPort: activeSmtpPort(),
+            httpPort: activeHttpPort(),
+            host,
+            storeKind: resolved.storeKind,
+            storeLabel: resolved.storeLabel,
+            lastScanAt,
+            lastQueuedCount,
+            keyCoverage: lastKeyCoverage,
+            updatedAt: new Date(now()).toISOString(),
+        });
+    };
+    await scan();
+    const intervalMs = Math.max(5_000, resolved.config.attentionIntervalMs ?? 30_000);
+    const timer = (options.setIntervalFn ?? ((callback, ms) => setInterval(callback, ms)))(() => {
+        void scan();
+    }, intervalMs);
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.mail_sense_started",
+        message: "mail sense started",
+        meta: {
+            agentName: options.agentName,
+            mailboxAddress: resolved.config.mailboxAddress,
+            smtpPort: activeSmtpPort(),
+            httpPort: activeHttpPort(),
+            intervalMs,
+        },
+    });
+    return {
+        runtimeStatePath: runtimePath,
+        attentionStatePath: attentionPath,
+        smtpPort: activeSmtpPort(),
+        httpPort: activeHttpPort(),
+        async stop() {
+            ;
+            (options.clearIntervalFn ?? ((activeTimer) => clearInterval(activeTimer)))(timer);
+            if (ingress) {
+                await Promise.all([
+                    closeServer(ingress.smtp),
+                    closeServer(ingress.health),
+                ]);
+            }
+            writeRuntimeState(runtimePath, {
+                schemaVersion: 1,
+                agentName: options.agentName,
+                status: "stopped",
+                mailboxAddress: resolved.config.mailboxAddress,
+                smtpPort: activeSmtpPort(),
+                httpPort: activeHttpPort(),
+                host,
+                storeKind: resolved.storeKind,
+                storeLabel: resolved.storeLabel,
+                lastScanAt,
+                lastQueuedCount,
+                keyCoverage: lastKeyCoverage,
+                updatedAt: new Date(now()).toISOString(),
+            });
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.mail_sense_stopped",
+                message: "mail sense stopped",
+                meta: { agentName: options.agentName },
+            });
+        },
+    };
+}