@ouro.bot/cli 0.1.0-alpha.730 → 0.1.0-alpha.732

package/dist/heart/daemon/prunable-bundle.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSafePrunableAgentName = isSafePrunableAgentName;
+exports.resolvePrunableAgentBundle = resolvePrunableAgentBundle;
+exports.listPrunableAgentBundles = listPrunableAgentBundles;
+exports.isManagedDaemonLogEntry = isManagedDaemonLogEntry;
+exports.validatePrunableLogEntry = validatePrunableLogEntry;
+exports.validatePrunableLogsDirectory = validatePrunableLogsDirectory;
+exports.validatePrunableLogsTarget = validatePrunableLogsTarget;
+const path_1 = require("path");
+const runtime_1 = require("../../nerves/runtime");
+const defaultFs = {
+    existsSync: (filePath) => require("fs").existsSync(filePath),
+    readdirSync: (dirPath) => require("fs").readdirSync(dirPath),
+    lstatSync: (filePath) => require("fs").lstatSync(filePath),
+    realpathSync: (filePath) => require("fs").realpathSync(filePath),
+};
+const defaultLogsFs = {
+    readdirSync: (dirPath) => require("fs").readdirSync(dirPath),
+    lstatSync: (filePath) => require("fs").lstatSync(filePath),
+    realpathSync: (filePath) => require("fs").realpathSync(filePath),
+};
+const SAFE_AGENT_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function isSafePrunableAgentName(agentName) {
+    return SAFE_AGENT_NAME.test(agentName) && agentName !== "." && agentName !== "..";
+}
+function invalidTarget(agentName, reason) {
+    return new Error(`agent ${JSON.stringify(agentName)} is not a prunable agent bundle: ${reason}`);
+}
+function resolvePrunableAgentBundle(options) {
+    const io = options.fs ?? defaultFs;
+    const agentName = options.agentName;
+    if (!isSafePrunableAgentName(agentName)) {
+        throw invalidTarget(agentName, "name must match [A-Za-z0-9][A-Za-z0-9._-]* and be at most 128 characters");
+    }
+    let rootReal;
+    try {
+        rootReal = io.realpathSync(options.bundlesRoot);
+    }
+    catch {
+        throw invalidTarget(agentName, "bundles root does not exist");
+    }
+    const bundleDir = (0, path_1.join)(options.bundlesRoot, `${agentName}.ouro`);
+    let bundleStat;
+    try {
+        bundleStat = io.lstatSync(bundleDir);
+    }
+    catch {
+        throw invalidTarget(agentName, "bundle does not exist");
+    }
+    if (bundleStat.isSymbolicLink() || !bundleStat.isDirectory()) {
+        throw invalidTarget(agentName, "bundle must be a real directory, not a symlink or other entry");
+    }
+    let bundleReal;
+    try {
+        bundleReal = io.realpathSync(bundleDir);
+    }
+    catch {
+        throw invalidTarget(agentName, "bundle cannot be resolved");
+    }
+    if ((0, path_1.dirname)(bundleReal) !== rootReal || (0, path_1.basename)(bundleReal) !== `${agentName}.ouro`) {
+        throw invalidTarget(agentName, "bundle must be a direct child of the bundles root");
+    }
+    if (!io.existsSync((0, path_1.join)(bundleReal, "agent.json"))) {
+        throw invalidTarget(agentName, "agent.json is not present");
+    }
+    const target = { agentName, bundleDir: bundleReal, logsDir: (0, path_1.join)(bundleReal, "state", "daemon", "logs") };
+    (0, runtime_1.emitNervesEvent)({
+        component: "nerves",
+        event: "nerves.prunable_bundle_resolved",
+        message: "resolved prunable agent bundle",
+        meta: { agentName, bundleDir: bundleReal },
+    });
+    return target;
+}
+function listPrunableAgentBundles(options) {
+    const io = options.fs ?? defaultFs;
+    let entries;
+    try {
+        entries = io.readdirSync(options.bundlesRoot);
+    }
+    catch {
+        entries = [];
+    }
+    const agents = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(".ouro"))
+            continue;
+        const agentName = entry.slice(0, -".ouro".length);
+        if (!isSafePrunableAgentName(agentName))
+            continue;
+        try {
+            resolvePrunableAgentBundle({ ...options, agentName });
+            agents.push(agentName);
+        }
+        catch {
+            // Invalid entries are not prune candidates.
+        }
+    }
+    agents.sort((left, right) => left.localeCompare(right));
+    (0, runtime_1.emitNervesEvent)({
+        component: "nerves",
+        event: "nerves.prunable_bundles_listed",
+        message: "listed prunable agent bundles",
+        meta: { bundlesRoot: options.bundlesRoot, count: agents.length },
+    });
+    return agents;
+}
+function isManagedDaemonLogEntry(name) {
+    const activeNdjson = name.endsWith(".ndjson") && !/\.\d+\.ndjson$/.test(name);
+    const activeLog = name.endsWith(".log") && !/\.\d+\.log$/.test(name);
+    return activeNdjson || activeLog ||
+        /\.\d+\.ndjson(?:\.gz)?$/.test(name) ||
+        /\.log\.\d+(?:\.gz)?$/.test(name) ||
+        /\.\d+\.log$/.test(name);
+}
+function validatePrunableLogEntry(filePath, logsReal, io = defaultLogsFs) {
+    const stat = io.lstatSync(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error(`daemon log entry must be a regular non-symlink file: ${filePath}`);
+    }
+    if ((0, path_1.dirname)(io.realpathSync(filePath)) !== logsReal) {
+        throw new Error(`daemon log entry escapes the canonical logs directory: ${filePath}`);
+    }
+}
+function validatePrunableLogsDirectory(logsDir, expectedCanonicalLogsDir, io = defaultLogsFs) {
+    const stat = io.lstatSync(logsDir);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error(`daemon logs directory must be a real directory: ${logsDir}`);
+    }
+    const logsReal = io.realpathSync(logsDir);
+    if (expectedCanonicalLogsDir && logsReal !== expectedCanonicalLogsDir) {
+        throw new Error(`daemon logs directory must remain inside its canonical agent bundle: ${logsDir}`);
+    }
+    const entries = io.readdirSync(logsDir);
+    for (const name of entries) {
+        if (isManagedDaemonLogEntry(name))
+            validatePrunableLogEntry((0, path_1.join)(logsDir, name), logsReal, io);
+    }
+    return { entries, logsReal };
+}
+function validatePrunableLogsTarget(target, io = defaultLogsFs) {
+    return validatePrunableLogsDirectory(target.logsDir, target.logsDir, io);
+}

package/dist/mailroom/blob-store.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AzureBlobMailroomStore = void 0;
+exports.canonicalMailIndexRecordSnapshot = canonicalMailIndexRecordSnapshot;
 exports.decryptBlobMessages = decryptBlobMessages;
+const node_crypto_1 = require("node:crypto");
 const runtime_1 = require("../nerves/runtime");
 const core_1 = require("./core");
 const search_cache_1 = require("./search-cache");
@@ -198,21 +200,53 @@ function parseMessageIndexBlobName(name) {
     const agentId = parts[1];
     const stem = parts[2].slice(0, -5);
     const [sortKey, compartmentKind, placement, sourceToken, ...idParts] = stem.split("__");
-    if (!sortKey || !compartmentKind || !placement || !sourceToken || idParts.length === 0)
+    const id = idParts.join("__");
+    if (!agentId || !sortKey || !compartmentKind || !placement || !sourceToken || !id)
+        return null;
+    if (!/^\d{13}$/.test(sortKey))
         return null;
     if (compartmentKind !== "native" && compartmentKind !== "delegated")
         return null;
-    const receivedAtMs = MESSAGE_INDEX_SORT_MAX_MS - Number.parseInt(sortKey, 10);
+    if (!["imbox", "screener", "discarded", "quarantine", "draft", "sent"].includes(placement))
+        return null;
+    const decodedSource = decodeSourceToken(sourceToken);
+    const receivedAtMs = MESSAGE_INDEX_SORT_MAX_MS - Number(sortKey);
     return {
         schemaVersion: 1,
-        id: idParts.join("__"),
+        id,
         agentId,
         compartmentKind,
         placement: placement,
-        ...(decodeSourceToken(sourceToken) ? { source: decodeSourceToken(sourceToken) } : {}),
-        receivedAt: Number.isFinite(receivedAtMs) ? new Date(receivedAtMs).toISOString() : new Date(0).toISOString(),
+        ...(decodedSource ? { source: decodedSource } : {}),
+        receivedAt: new Date(receivedAtMs).toISOString(),
+    };
+}
+function canonicalIndexRecord(record) {
+    return {
+        id: record.id,
+        receivedAt: record.receivedAt,
+        placement: record.placement,
+        compartmentKind: record.compartmentKind,
+        source: record.source?.toLowerCase() ?? null,
+    };
+}
+function canonicalMailIndexRecordSnapshot(records) {
+    const normalizedRecords = records
+        .map(canonicalIndexRecord)
+        .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+    const receivedTimes = records
+        .map((record) => record.receivedAt)
+        .sort((left, right) => Date.parse(left) - Date.parse(right));
+    return {
+        visibleMessageCount: records.length,
+        messageIndexFingerprint: (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(normalizedRecords)).digest("hex"),
+        ...(receivedTimes[0] ? { oldestReceivedAt: receivedTimes[0] } : {}),
+        ...(receivedTimes.at(-1) ? { newestReceivedAt: receivedTimes.at(-1) } : {}),
     };
 }
+function canonicalMailIndexRecordOrder(left, right) {
+    return JSON.stringify(canonicalIndexRecord(left)).localeCompare(JSON.stringify(canonicalIndexRecord(right)));
+}
 function sourceMatchesFilter(source, filter) {
     if (!filter)
         return true;
@@ -344,6 +378,69 @@ class AzureBlobMailroomStore {
         });
         return applyOptionalLimit(sorted, filters.limit);
     }
+    async observeMessageIndexAuthority(agentId) {
+        const prefix = messageIndexPrefix(agentId);
+        const operationTimeout = timeoutSignal(this.blobOperationTimeoutMs);
+        const records = [];
+        let totalNameCount = 0;
+        let parseFailureCount = 0;
+        try {
+            for await (const item of this.container.listBlobsFlat({ prefix, abortSignal: operationTimeout.signal })) {
+                totalNameCount += 1;
+                let parsed = null;
+                try {
+                    parsed = parseMessageIndexBlobName(item.name);
+                }
+                catch {
+                    parsed = null;
+                }
+                if (!parsed) {
+                    parseFailureCount += 1;
+                    continue;
+                }
+                records.push(parsed);
+            }
+        }
+        catch (error) {
+            const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+            if ((error instanceof Error && error.name === "AbortError") || message.includes("aborted")) {
+                throw normalizeBlobOperationError("list", { name: prefix }, this.blobOperationTimeoutMs, error);
+            }
+            throw error;
+        }
+        finally {
+            operationTimeout.dispose();
+        }
+        records.sort(canonicalMailIndexRecordOrder);
+        const counts = new Map();
+        for (const record of records)
+            counts.set(record.id, (counts.get(record.id) ?? 0) + 1);
+        const duplicateIds = [...counts.entries()]
+            .filter(([, count]) => count > 1)
+            .map(([id]) => id)
+            .sort((left, right) => left.localeCompare(right));
+        const observation = {
+            totalNameCount,
+            parsedRecordCount: records.length,
+            parseFailureCount,
+            duplicateIds,
+            records,
+            snapshot: canonicalMailIndexRecordSnapshot(records),
+        };
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.mail_blob_store_authority_observed",
+            message: "azure blob mailroom index authority observed",
+            meta: {
+                agentId,
+                totalNameCount,
+                parsedRecordCount: records.length,
+                parseFailureCount,
+                duplicateIdCount: duplicateIds.length,
+            },
+        });
+        return observation;
+    }
     async listMessagesFromIndexes(filters) {
         const records = await this.listMessageIndexRecords(filters);
         if (records === null)
@@ -465,7 +562,6 @@ class AzureBlobMailroomStore {
         return message;
     }
     async getIndexedMessageById(id) {
-        await this.ensureContainer();
         const message = await downloadIndexedJson(this.messageBlob(id), this.blobOperationTimeoutMs);
         (0, runtime_1.emitNervesEvent)({
             component: "senses",

package/dist/mailroom/cache-sync-cli.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHostedMailCacheSync = runHostedMailCacheSync;
+const runtime_credentials_1 = require("../heart/runtime-credentials");
+const runtime_1 = require("../nerves/runtime");
+const hosted_cache_sync_1 = require("./hosted-cache-sync");
+const reader_1 = require("./reader");
+async function runHostedMailCacheSync(agentName) {
+    const freshRuntime = await (0, runtime_credentials_1.refreshRuntimeCredentialConfig)(agentName, { preserveCachedOnFailure: false });
+    if (!freshRuntime.ok) {
+        throw new Error(`mail cache sync for ${agentName} requires fresh ${freshRuntime.itemPath}: ${freshRuntime.error}`);
+    }
+    const reader = (0, reader_1.resolveMailroomReader)(agentName);
+    if (!reader.ok)
+        throw new Error(reader.error);
+    if (reader.storeKind !== "azure-blob") {
+        throw new Error(`mail cache sync for ${agentName} requires hosted Azure Mailroom; resolved ${reader.storeKind}`);
+    }
+    const authority = (0, reader_1.resolveHostedMailAuthority)(agentName);
+    if (!authority.ok)
+        throw new Error(authority.error);
+    const result = await (0, hosted_cache_sync_1.syncHostedMailSearchCache)({
+        agentId: agentName,
+        mode: "full-convergence",
+        authority: authority.authority,
+        store: reader.store,
+        privateKeys: reader.config.privateKeys,
+        storeKind: reader.storeKind,
+        cacheOptions: reader.store.mailSearchCacheOptions?.(),
+    });
+    const text = [
+        `hosted mail cache converged for ${agentName}.`,
+        `visible authoritative messages: ${result.coverage.visibleMessageCount}`,
+        `decryptable cached messages: ${result.coverage.decryptableMessageCount}`,
+        `fetched this run: ${result.fetched}`,
+        `already current: ${result.alreadyCached}`,
+        `removed stale local files: ${result.removed}`,
+        `skipped unavailable messages: ${result.skipped}`,
+        `indexed at: ${result.coverage.indexedAt}`,
+    ].join("\n");
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.mail_cache_sync_cli_completed",
+        message: "foreground hosted mail cache sync completed",
+        meta: {
+            agentName,
+            visible: result.coverage.visibleMessageCount,
+            cached: result.coverage.decryptableMessageCount,
+            removed: result.removed,
+            skipped: result.skipped,
+        },
+    });
+    return text;
+}

package/dist/mailroom/hosted-cache-sync.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mailSearchCacheDocumentMatchesRecord = mailSearchCacheDocumentMatchesRecord;
+exports.syncHostedMailSearchCache = syncHostedMailSearchCache;
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../nerves/runtime");
+const blob_store_1 = require("./blob-store");
+const core_1 = require("./core");
+const search_cache_1 = require("./search-cache");
+function filtersFor(input) {
+    return {
+        agentId: input.agentId,
+        ...(input.placement ? { placement: input.placement } : {}),
+        ...(input.scope ? { compartmentKind: input.scope } : {}),
+        ...(input.source ? { source: input.source } : {}),
+    };
+}
+function recordFor(message) {
+    return {
+        schemaVersion: 1,
+        id: message.id,
+        agentId: message.agentId,
+        compartmentKind: message.compartmentKind,
+        placement: message.placement,
+        ...(message.source ? { source: message.source } : {}),
+        receivedAt: message.receivedAt,
+    };
+}
+function sameOptionalText(left, right) {
+    return (left ?? "").toLowerCase() === (right ?? "").toLowerCase();
+}
+function mailSearchCacheDocumentMatchesRecord(document, record, requireKeyProvenance) {
+    return document.schemaVersion === 1
+        && document.agentId === record.agentId
+        && document.messageId === record.id
+        && document.receivedAt === record.receivedAt
+        && document.placement === record.placement
+        && document.compartmentKind === record.compartmentKind
+        && sameOptionalText(document.source, record.source)
+        && document.textProjectionVersion === search_cache_1.MAIL_SEARCH_TEXT_PROJECTION_VERSION
+        && (!requireKeyProvenance || typeof document.decryptionKeyId === "string");
+}
+function messageMatchesRecord(message, record) {
+    return message.id === record.id
+        && message.agentId === record.agentId
+        && message.receivedAt === record.receivedAt
+        && message.placement === record.placement
+        && message.compartmentKind === record.compartmentKind
+        && sameOptionalText(message.source, record.source);
+}
+async function scopedRecords(input) {
+    const filters = filtersFor(input);
+    const indexed = await input.store.listMessageIndexRecords?.(filters);
+    if (indexed)
+        return indexed;
+    return (await input.store.listMessages(filters)).map(recordFor);
+}
+async function fetchIndexedMessage(store, id) {
+    return store.getIndexedMessageById
+        ? store.getIndexedMessageById(id)
+        : store.getMessage(id);
+}
+function removeCanonicalIfPresent(agentId, messageId, options) {
+    return (0, search_cache_1.removeMailSearchCacheDocument)(agentId, messageId, options) ? 1 : 0;
+}
+function missingPrivateKeyId(error) {
+    if (!(error instanceof Error))
+        return null;
+    const keyId = error.keyId;
+    return typeof keyId === "string" && keyId.length > 0 ? keyId : null;
+}
+/**
+ * Converge a local decrypted cache against hosted index authority, or perform
+ * the legacy bounded upsert used by the in-agent refresh tool. This core never
+ * writes remote mail state and never records access; adapters own audit policy.
+ */
+async function performHostedMailSearchCacheSync(input) {
+    let authority = null;
+    let records;
+    if (input.mode === "full-convergence") {
+        const observer = input.authority ?? input.store;
+        if (!observer.observeMessageIndexAuthority) {
+            throw new Error("hosted mail authority observer is unavailable");
+        }
+        authority = await observer.observeMessageIndexAuthority(input.agentId);
+        if (authority.parseFailureCount > 0 || authority.duplicateIds.length > 0) {
+            throw new Error(`hosted mail authority is ambiguous: ${authority.parseFailureCount} malformed index name(s), ${authority.duplicateIds.length} duplicate message id(s)`);
+        }
+        if (authority.records.length === 0) {
+            throw new Error("hosted mail authority is empty and cannot safely drive full convergence");
+        }
+        records = authority.records;
+    }
+    else {
+        records = await scopedRecords(input);
+    }
+    const recordsById = new Map(records.map((record) => [record.id, record]));
+    const canonicalDocuments = new Map();
+    let removed = 0;
+    if (input.mode === "full-convergence") {
+        for (const inspected of (0, search_cache_1.inspectMailSearchCacheFiles)(input.agentId, input.cacheOptions)) {
+            const document = inspected.document;
+            const canonicalName = document ? `${document.messageId}.json` : null;
+            const record = document ? recordsById.get(document.messageId) : undefined;
+            if (!document || inspected.fileName !== canonicalName || document.agentId !== input.agentId || !record) {
+                removed += Number((0, search_cache_1.removeMailSearchCacheFile)(input.agentId, inspected.fileName, input.cacheOptions));
+                continue;
+            }
+            canonicalDocuments.set(document.messageId, document);
+        }
+    }
+    else {
+        for (const document of (0, search_cache_1.searchMailSearchCache)({
+            agentId: input.agentId,
+            placement: input.placement,
+            compartmentKind: input.scope,
+            source: input.source,
+        }, input.cacheOptions)) {
+            canonicalDocuments.set(document.messageId, document);
+        }
+    }
+    let fetched = 0;
+    let alreadyCached = 0;
+    let skipped = 0;
+    const failures = [];
+    for (const record of records) {
+        const cached = canonicalDocuments.get(record.id);
+        if (cached && input.mode === "full-convergence" && cached.decryptionKeyId && !input.privateKeys[cached.decryptionKeyId]) {
+            removed += removeCanonicalIfPresent(input.agentId, record.id, input.cacheOptions);
+            skipped += 1;
+            continue;
+        }
+        if (cached && mailSearchCacheDocumentMatchesRecord(cached, record, input.mode === "full-convergence")) {
+            alreadyCached += 1;
+            continue;
+        }
+        try {
+            const message = await fetchIndexedMessage(input.store, record.id);
+            if (!message)
+                throw new Error("indexed message was not retrievable");
+            fetched += 1;
+            if (!messageMatchesRecord(message, record)) {
+                throw new Error(`indexed message metadata did not match authority for ${record.id}`);
+            }
+            const decrypted = (0, core_1.readDecryptedMailMessage)(message, input.privateKeys);
+            (0, search_cache_1.upsertMailSearchCacheDocument)(message, decrypted.private, input.cacheOptions, {
+                ...(message.bodyForm === "encrypted" ? { decryptionKeyId: message.privateEnvelope.keyId } : {}),
+            });
+        }
+        catch (error) {
+            if (input.mode === "full-convergence" || missingPrivateKeyId(error)) {
+                removed += removeCanonicalIfPresent(input.agentId, record.id, input.cacheOptions);
+                skipped += 1;
+            }
+            else {
+                failures.push({ id: record.id, error: error instanceof Error ? error.message : String(error) });
+            }
+        }
+    }
+    if (failures.length > 0) {
+        const sample = failures.slice(0, 3).map((entry) => `${entry.id}: ${entry.error}`).join("; ");
+        throw new Error(`mail search index refresh incomplete; ${failures.length} fetch failed. first failure(s): ${sample}`);
+    }
+    const cachedIds = new Set((0, search_cache_1.searchMailSearchCache)({
+        agentId: input.agentId,
+        placement: input.placement,
+        compartmentKind: input.scope,
+        source: input.source,
+    }, input.cacheOptions).filter((document) => recordsById.has(document.messageId)).map((document) => document.messageId));
+    const snapshot = authority?.snapshot ?? (0, blob_store_1.canonicalMailIndexRecordSnapshot)(records);
+    const coverage = (0, search_cache_1.writeMailSearchCoverageRecord)({
+        schemaVersion: 1,
+        agentId: input.agentId,
+        storeKind: input.storeKind,
+        ...(input.placement ? { placement: input.placement } : {}),
+        ...(input.scope ? { compartmentKind: input.scope } : {}),
+        ...(input.source ? { source: input.source } : {}),
+        indexedAt: new Date().toISOString(),
+        visibleMessageCount: records.length,
+        cachedMessageCount: cachedIds.size,
+        decryptableMessageCount: cachedIds.size,
+        skippedMessageCount: skipped,
+        messageIndexFingerprint: snapshot.messageIndexFingerprint,
+        textProjectionVersion: search_cache_1.MAIL_SEARCH_TEXT_PROJECTION_VERSION,
+        ...(snapshot.oldestReceivedAt ? { oldestReceivedAt: snapshot.oldestReceivedAt } : {}),
+        ...(snapshot.newestReceivedAt ? { newestReceivedAt: snapshot.newestReceivedAt } : {}),
+    }, input.cacheOptions);
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.mail_search_cache_synced",
+        message: "hosted mail search cache synchronized",
+        meta: {
+            agentId: input.agentId,
+            mode: input.mode,
+            visible: records.length,
+            fetched,
+            alreadyCached,
+            removed,
+            skipped,
+        },
+    });
+    return { coverage, fetched, alreadyCached, removed, skipped };
+}
+async function syncHostedMailSearchCache(input) {
+    const traceId = (0, node_crypto_1.randomUUID)();
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.mail_search_cache_sync_start",
+        trace_id: traceId,
+        message: "synchronizing hosted mail search cache",
+        meta: { agentId: input.agentId, mode: input.mode, storeKind: input.storeKind },
+    });
+    try {
+        const result = await performHostedMailSearchCacheSync(input);
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.mail_search_cache_sync_end",
+            trace_id: traceId,
+            message: "hosted mail search cache synchronization completed",
+            meta: {
+                agentId: input.agentId,
+                mode: input.mode,
+                storeKind: input.storeKind,
+                visible: result.coverage.visibleMessageCount,
+                fetched: result.fetched,
+                alreadyCached: result.alreadyCached,
+                removed: result.removed,
+                skipped: result.skipped,
+            },
+        });
+        return result;
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.mail_search_cache_sync_error",
+            trace_id: traceId,
+            level: "error",
+            message: "hosted mail search cache synchronization failed",
+            meta: {
+                agentId: input.agentId,
+                mode: input.mode,
+                storeKind: input.storeKind,
+                error: String(error),
+            },
+        });
+        throw error;
+    }
+}

package/dist/mailroom/reader.js

@@ -37,6 +37,7 @@ exports.parseMailroomConfig = parseMailroomConfig;
 exports.readMailroomRegistry = readMailroomRegistry;
 exports.writeMailroomRegistry = writeMailroomRegistry;
 exports.resolveMailroomReader = resolveMailroomReader;
+exports.resolveHostedMailAuthority = resolveHostedMailAuthority;
 exports.resolveMailroomReaderWithRefresh = resolveMailroomReaderWithRefresh;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -221,6 +222,64 @@ function resolveMailroomReader(agentName = (0, identity_2.getAgentName)()) {
     });
     return result;
 }
+function resolveHostedMailAuthority(agentName = (0, identity_2.getAgentName)()) {
+    const runtime = (0, runtime_credentials_1.readRuntimeCredentialConfig)(agentName);
+    if (!runtime.ok) {
+        const result = {
+            ok: false,
+            agentName,
+            reason: "auth-required",
+            error: `AUTH_REQUIRED:mailroom -- Hosted mail authority is unavailable because ${runtime.itemPath} is ${runtime.reason}: ${runtime.error}`,
+        };
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.mail_hosted_authority_resolved",
+            message: "hosted mail authority resolved",
+            meta: { agentName, status: result.reason },
+        });
+        return result;
+    }
+    const mailroom = isRecord(runtime.config.mailroom) ? runtime.config.mailroom : null;
+    const azureAccountUrl = mailroom ? textField(mailroom, "azureAccountUrl") : undefined;
+    if (!mailroom || !azureAccountUrl) {
+        const result = {
+            ok: false,
+            agentName,
+            reason: "misconfigured",
+            error: `Hosted mail authority for ${agentName} is missing mailroom.azureAccountUrl in vault runtime/config.`,
+        };
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.mail_hosted_authority_resolved",
+            message: "hosted mail authority resolved",
+            meta: { agentName, status: result.reason },
+        });
+        return result;
+    }
+    const azureContainer = textField(mailroom, "azureContainer") ?? "mailroom";
+    const azureManagedIdentityClientId = textField(mailroom, "azureManagedIdentityClientId");
+    const store = new blob_store_1.AzureBlobMailroomStore({
+        serviceClient: new storage_blob_1.BlobServiceClient(azureAccountUrl, azureManagedIdentityClientId
+            ? new identity_1.DefaultAzureCredential({ managedIdentityClientId: azureManagedIdentityClientId })
+            : new identity_1.DefaultAzureCredential()),
+        containerName: azureContainer,
+    });
+    const result = {
+        ok: true,
+        agentName,
+        authority: {
+            observeMessageIndexAuthority: (authorityAgentId) => store.observeMessageIndexAuthority(authorityAgentId),
+        },
+        storeLabel: `${azureAccountUrl}/${azureContainer}`,
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.mail_hosted_authority_resolved",
+        message: "hosted mail authority resolved",
+        meta: { agentName, status: "ready" },
+    });
+    return result;
+}
 async function resolveMailroomReaderWithRefresh(agentName = (0, identity_2.getAgentName)()) {
     const resolved = resolveMailroomReader(agentName);
     if (resolved.ok