@ouro.bot/cli 0.1.0-alpha.485 → 0.1.0-alpha.488

package/dist/repertoire/tools-mail.js

@@ -1,48 +1,27 @@
 "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;
-    };
-})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mailToolDefinitions = void 0;
-const fs = __importStar(require("node:fs"));
+exports.mailToolDefinitions = exports.__mailStatusTestOnly = void 0;
+exports.renderCachedMessageSummary = renderCachedMessageSummary;
+exports.mergeCachedMailSearchDocuments = mergeCachedMailSearchDocuments;
+exports.searchSuccessfulImportArchives = searchSuccessfulImportArchives;
+const node_fs_1 = __importDefault(require("node:fs"));
 const types_1 = require("../mind/friends/types");
 const file_store_1 = require("../mailroom/file-store");
 const reader_1 = require("../mailroom/reader");
 const outbound_1 = require("../mailroom/outbound");
 const policy_1 = require("../mailroom/policy");
+const search_cache_1 = require("../mailroom/search-cache");
+const mbox_import_1 = require("../mailroom/mbox-import");
+const search_relevance_1 = require("../mailroom/search-relevance");
 const core_1 = require("../mailroom/core");
 const runtime_1 = require("../nerves/runtime");
 const credential_access_1 = require("./credential-access");
+const background_operations_1 = require("../heart/background-operations");
+const mail_import_discovery_1 = require("../heart/mail-import-discovery");
+const identity_1 = require("../heart/identity");
 function trustAllowsMailRead(ctx) {
     const trustLevel = ctx?.context?.friend?.trustLevel;
     const allowed = trustLevel === undefined || (0, types_1.isTrustedLevel)(trustLevel);
@@ -92,6 +71,13 @@ function parseMailList(value) {
         .map((entry) => entry.trim())
         .filter(Boolean);
 }
+function mailSearchTerms(query) {
+    return query
+        .split(/\s+OR\s+/i)
+        .flatMap((entry) => entry.split(/[\n,;]+/))
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
 function missingPrivateMailKeyId(error) {
     const match = /^(?:Error: )?Missing private mail key ([^\s]+)$/.exec(String(error));
     return match?.[1] ?? null;
@@ -183,6 +169,49 @@ function renderMessageSummary(message) {
         `  warning: ${message.private.untrustedContentWarning}`,
     ].join("\n");
 }
+function renderCachedMessageSummary(message, queryTerms = []) {
+    const scope = message.compartmentKind === "delegated"
+        ? `delegated:${message.ownerEmail ?? "unknown"}:${message.source ?? "source"}`
+        : "native";
+    const from = message.from.join(", ") || "(unknown sender)";
+    const subject = message.subject || "(no subject)";
+    const lines = [
+        `- ${message.messageId} [${message.placement}; ${scope}]`,
+        `  from: ${from}`,
+        `  subject: ${subject}`,
+    ];
+    if (typeof message.attachmentCount === "number" && message.attachmentCount > 0) {
+        lines.push(`  attachments: ${message.attachmentCount}`);
+    }
+    if (queryTerms.length > 0) {
+        const hint = (0, search_relevance_1.formatRelevanceHint)((0, search_relevance_1.scoreMailSearchDocument)(message, queryTerms));
+        if (hint)
+            lines.push(`  matched on: ${hint}`);
+    }
+    lines.push(`  snippet: ${message.snippet}`);
+    lines.push(`  warning: ${message.untrustedContentWarning}`);
+    return lines.join("\n");
+}
+function mergeCachedMailSearchDocuments(cached, imported, limit, queryTerms = []) {
+    const merged = [];
+    const seen = new Set();
+    const all = [...cached, ...imported];
+    const ordered = queryTerms.length > 0
+        ? all
+            .map((document) => ({ document, relevance: (0, search_relevance_1.scoreMailSearchDocument)(document, queryTerms) }))
+            .sort(search_relevance_1.compareByRelevanceThenRecency)
+            .map((entry) => entry.document)
+        : all.sort((left, right) => right.receivedAt.localeCompare(left.receivedAt));
+    for (const message of ordered) {
+        if (seen.has(message.messageId))
+            continue;
+        seen.add(message.messageId);
+        merged.push(message);
+        if (merged.length >= limit)
+            break;
+    }
+    return merged;
+}
 function renderScreenerCandidate(candidate) {
     const delegated = candidate.ownerEmail || candidate.source
         ? ` delegated:${candidate.ownerEmail ?? "unknown"}:${candidate.source ?? "source"}`
@@ -196,9 +225,12 @@ function renderScreenerCandidate(candidate) {
     ].join("\n");
 }
 function renderAccessLog(entries) {
+    const warning = typeof entries.malformedEntriesSkipped === "number" && entries.malformedEntriesSkipped > 0
+        ? `warning: skipped ${entries.malformedEntriesSkipped} malformed file-backed mail access log line${entries.malformedEntriesSkipped === 1 ? "" : "s"}`
+        : "";
     if (entries.length === 0)
-        return "No mail access records yet.";
-    return entries
+        return warning || "No mail access records yet.";
+    const rendered = entries
         .slice(-20)
         .reverse()
         .map((entry) => {
@@ -207,6 +239,7 @@ function renderAccessLog(entries) {
         return `- ${entry.accessedAt} ${entry.tool} ${target}${provenance} reason="${entry.reason}"`;
     })
         .join("\n");
+    return warning ? `${warning}\n${rendered}` : rendered;
 }
 function renderAccessLogProvenance(entry) {
     if (entry.mailboxRole === "delegated-human-mailbox") {
@@ -217,6 +250,11 @@ function renderAccessLogProvenance(entry) {
     }
     return "";
 }
+function cacheDecryptedMessages(messages) {
+    for (const message of messages) {
+        (0, search_cache_1.upsertMailSearchCacheDocument)(message, message.private);
+    }
+}
 function accessProvenance(message) {
     const provenance = (0, core_1.describeMailProvenance)(message);
     return {
@@ -226,15 +264,9 @@ function accessProvenance(message) {
         source: provenance.source,
     };
 }
-function renderSourceGrantStatus(config, agentId) {
-    if (!config.registryPath) {
-        return [
-            "delegated source aliases: unknown (runtime config has no registryPath).",
-            `agent-runnable repair: run ouro connect mail --agent ${agentId} --owner-email <human-email> --source hey.`,
-        ];
-    }
+async function renderSourceGrantStatus(config, agentId) {
     try {
-        const registry = readRegistry(config.registryPath);
+        const registry = await (0, reader_1.readMailroomRegistry)(config);
         const grants = registry.sourceGrants
             .filter((grant) => grant.agentId === agentId && grant.enabled)
             .map((grant) => `${grant.source}:${grant.ownerEmail} -> ${grant.aliasAddress}`);
@@ -257,10 +289,11 @@ function renderSourceGrantStatus(config, agentId) {
 async function renderEmptyMailResult(input) {
     const anyVisible = await input.store.listMessages({ agentId: input.agentId, limit: 1 });
     if (anyVisible.length === 0) {
+        const sourceGrantStatus = await renderSourceGrantStatus(input.config, input.agentId);
         return [
             "No visible mail yet.",
             `mail onboarding status: Mailroom is provisioned for ${input.config.mailboxAddress}, but this agent's encrypted store has 0 messages.`,
-            ...renderSourceGrantStatus(input.config, input.agentId),
+            ...sourceGrantStatus,
             "interpretation: this is not evidence that the human's HEY inbox is empty; Agent Mail has not yet received or imported mail visible to this agent.",
             `agent next move: guide setup from docs/agent-mail-setup.md. If HEY mail is needed, ensure the delegated hey alias exists, first try ouro mail import-mbox --agent ${input.agentId} --owner-email <human-email> --source hey --discover so Ouro can find a browser-downloaded export in .playwright-mcp or Downloads. Only ask the human for a file path if discovery cannot find a unique MBOX, then run ouro mail import-mbox --agent ${input.agentId} --owner-email <human-email> --source hey --file <mbox-path>. Verify with mail_recent/mail_search/Ouro Mailbox.`,
             "validation golden paths before claiming setup works:",
@@ -279,9 +312,10 @@ async function renderEmptyMailResult(input) {
             limit: 1,
         });
         if (delegated.length === 0) {
+            const sourceGrantStatus = await renderSourceGrantStatus(input.config, input.agentId);
             return [
                 "No delegated mail is visible for this source/scope yet.",
-                ...renderSourceGrantStatus(input.config, input.agentId),
+                ...sourceGrantStatus,
                 "Mailroom has other mail, so check the delegated HEY import/forwarding/source filter before treating the human inbox as empty.",
             ].join("\n");
         }
@@ -318,12 +352,6 @@ const MAIL_CANDIDATE_STATUSES = ["pending", "allowed", "discarded", "quarantined
 function parseCandidateStatus(value) {
     return MAIL_CANDIDATE_STATUSES.includes(value) ? value : undefined;
 }
-function readRegistry(registryPath) {
-    return JSON.parse(fs.readFileSync(registryPath, "utf-8"));
-}
-function writeRegistry(registryPath, registry) {
-    fs.writeFileSync(registryPath, `${JSON.stringify(registry, null, 2)}\n`, "utf-8");
-}
 function policyScopeForMessage(message) {
     return message.source ? `source:${message.source.toLowerCase()}` : message.compartmentKind;
 }
@@ -378,13 +406,11 @@ function samePolicy(left, right) {
 function policyLine(policy, existing) {
     return `sender policy: ${existing ? "already " : ""}${policy.action} ${policy.match.kind} ${policy.match.value}`;
 }
-function persistSenderPolicyForDecision(input) {
+async function persistSenderPolicyForDecision(input) {
     const persistedActions = ["allow-sender", "allow-domain", "allow-source", "link-friend", "create-friend", "discard", "quarantine"];
     if (!persistedActions.includes(input.action)) {
         return null;
     }
-    if (!input.registryPath)
-        return "sender policy: skipped (registryPath missing)";
     const sender = input.action === "allow-source"
         ? null
         : normalizePolicySender(input.candidate, input.message, input.privateKeys);
@@ -399,12 +425,25 @@ function persistSenderPolicyForDecision(input) {
         actor: input.actor,
         reason: input.reason,
     });
-    const registry = readRegistry(input.registryPath);
+    let registry;
+    try {
+        registry = await (0, reader_1.readMailroomRegistry)(input.config);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return `sender policy: unavailable (mail registry unreadable: ${message})`;
+    }
     const existing = (registry.senderPolicies ?? []).find((candidatePolicy) => samePolicy(candidatePolicy, policy));
     if (existing)
         return policyLine(existing, true);
     registry.senderPolicies = [...(registry.senderPolicies ?? []), policy];
-    writeRegistry(input.registryPath, registry);
+    try {
+        await (0, reader_1.writeMailroomRegistry)(input.config, registry);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return `sender policy: unavailable (mail registry write failed: ${message})`;
+    }
     (0, runtime_1.emitNervesEvent)({
         component: "repertoire",
         event: "repertoire.mail_sender_policy_persisted",
@@ -413,7 +452,310 @@ function persistSenderPolicyForDecision(input) {
     });
     return policyLine(policy, false);
 }
+function latestComparableOperationTimestamp(record) {
+    const candidates = [
+        typeof record.spec?.fileModifiedAt === "string" ? record.spec.fileModifiedAt : null,
+        record.finishedAt ?? null,
+        record.updatedAt,
+    ];
+    for (const candidate of candidates) {
+        if (!candidate)
+            continue;
+        const parsed = Date.parse(candidate);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return null;
+}
+function operationResultText(record, key) {
+    const value = record.result?.[key];
+    return typeof value === "string" ? value.trim() : "";
+}
+function comparableOperationTimestamp(record) {
+    return Number(latestComparableOperationTimestamp(record)) || 0;
+}
+function matchingMailImportOperation(agentId, candidate) {
+    const operations = (0, background_operations_1.listBackgroundOperations)({
+        agentName: agentId,
+        agentRoot: (0, identity_1.getAgentRoot)(agentId),
+        limit: 20,
+    }).filter((record) => record.kind === "mail.import-mbox" && (record.spec?.filePath ?? null) === candidate.path);
+    /* v8 ignore start -- defensive `?? null` is unreachable in normal flow */
+    return operations[0] ?? null;
+    /* v8 ignore stop */
+}
+function archiveLaneKey(ownerEmail, source) {
+    const owner = ownerEmail.trim().toLowerCase();
+    const provider = source.trim().toLowerCase();
+    if (!owner && !provider)
+        return null;
+    return `${owner || "unknown"}::${provider || "unknown"}`;
+}
+function archiveFreshnessNote(candidate, operation, newestCurrentLaneArchiveMtimeMs = null) {
+    /* v8 ignore start -- defensive: callers in tests always pass an operation; covered by integration paths */
+    if (!operation) {
+        return "freshness: unimported (no prior import recorded; import needed)";
+    }
+    /* v8 ignore stop */
+    const sourceFreshThrough = operationResultText(operation, "sourceFreshThrough");
+    if (operation.status === "succeeded") {
+        const operationTimestamp = latestComparableOperationTimestamp(operation);
+        if (operationTimestamp !== null && candidate.mtimeMs <= operationTimestamp + 1_000) {
+            if (newestCurrentLaneArchiveMtimeMs !== null && candidate.mtimeMs + 1_000 < newestCurrentLaneArchiveMtimeMs) {
+                return [
+                    "freshness: current older snapshot (older imported snapshot for this delegated lane; newest known archive is listed separately)",
+                    ...(sourceFreshThrough ? [`fresh through: ${sourceFreshThrough}`] : []),
+                ].join("; ");
+            }
+            return [
+                "freshness: current (newest known archive for this delegated lane; re-import unnecessary)",
+                ...(sourceFreshThrough ? [`fresh through: ${sourceFreshThrough}`] : []),
+            ].join("; ");
+        }
+        if (operationTimestamp !== null) {
+            return [
+                "freshness: stale-risky (newer archive discovered after the last import; re-import needed)",
+                ...(sourceFreshThrough ? [`fresh through: ${sourceFreshThrough}`] : []),
+            ].join("; ");
+        }
+        return "freshness: stale-risky (last successful import has no comparable timestamp; verify the archive before relying on it)";
+    }
+    if (operation.status === "failed") {
+        return "freshness: blocked (last import failed; current freshness is not yet trustworthy)";
+    }
+    return "freshness: pending (import still in progress; current freshness will settle when the operation finishes)";
+}
+function archiveFilenameBoundEmail(candidate) {
+    const stem = candidate.name.replace(/\.mbox$/i, "");
+    const matches = stem.match(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/ig);
+    const match = matches?.at(-1);
+    if (!match)
+        return null;
+    try {
+        return (0, core_1.normalizeMailAddress)(match.replace(/^hey-emails-/i, "").replace(/^emails-/i, ""));
+    }
+    catch {
+        return null;
+    }
+}
+function archiveIdentityNote(candidate, ownerEmail, source) {
+    const fileEmail = archiveFilenameBoundEmail(candidate);
+    if (!fileEmail || !ownerEmail)
+        return "";
+    try {
+        if ((0, core_1.normalizeMailAddress)(ownerEmail) === fileEmail)
+            return "";
+    }
+    catch {
+        return "";
+    }
+    return `mapping: filename suggests ${fileEmail}, but this archive is bound to ${ownerEmail} / ${source || "unknown"} because delegated owner/source comes from the explicit import lane, not the local filename`;
+}
+exports.__mailStatusTestOnly = {
+    archiveFilenameBoundEmail,
+    archiveFreshnessNote,
+    archiveIdentityNote,
+};
+function newestCurrentLaneArchiveMtimes(candidates, operationsByPath) {
+    const newestByLane = new Map();
+    for (const candidate of candidates) {
+        const operation = operationsByPath.get(candidate.path);
+        if (!operation || operation.status !== "succeeded")
+            continue;
+        const ownerEmail = typeof operation.spec?.ownerEmail === "string" ? operation.spec.ownerEmail : "";
+        const source = typeof operation.spec?.source === "string" ? operation.spec.source : "";
+        const laneKey = archiveLaneKey(ownerEmail, source);
+        if (!laneKey)
+            continue;
+        const operationTimestamp = latestComparableOperationTimestamp(operation);
+        if (operationTimestamp === null || candidate.mtimeMs > operationTimestamp + 1_000)
+            continue;
+        const previous = newestByLane.get(laneKey) ?? 0;
+        if (candidate.mtimeMs > previous)
+            newestByLane.set(laneKey, candidate.mtimeMs);
+    }
+    return newestByLane;
+}
+function renderArchiveStatus(candidate, operation, newestCurrentLaneArchiveMtimeMs) {
+    /* v8 ignore start -- defensive: tests reach this helper through integration paths that always provide an operation; same archiveFreshnessNote fallback covered there */
+    if (!operation) {
+        return `- [${candidate.originLabel}] ${candidate.path} :: status: ready; ${archiveFreshnessNote(candidate, null, newestCurrentLaneArchiveMtimeMs)}`;
+    }
+    /* v8 ignore stop */
+    const operationTimestamp = latestComparableOperationTimestamp(operation);
+    const ownerEmail = typeof operation.spec?.ownerEmail === "string" ? operation.spec.ownerEmail : "";
+    const source = typeof operation.spec?.source === "string" ? operation.spec.source : "";
+    const provenance = ownerEmail || source ? `; owner/source: ${ownerEmail || "unknown"} / ${source || "unknown"}` : "";
+    const freshness = `; ${archiveFreshnessNote(candidate, operation, newestCurrentLaneArchiveMtimeMs)}`;
+    const identity = archiveIdentityNote(candidate, ownerEmail, source);
+    const identityNote = identity ? `; ${identity}` : "";
+    if (operation.status === "succeeded" && operationTimestamp !== null && candidate.mtimeMs <= operationTimestamp + 1_000) {
+        return `- [${candidate.originLabel}] ${candidate.path} :: status: imported via ${operation.id}${provenance}${freshness}; ${operation.detail ?? operation.summary}${identityNote}`;
+    }
+    if (operation.status === "succeeded") {
+        return `- [${candidate.originLabel}] ${candidate.path} :: status: ready (newer than last import via ${operation.id})${provenance}${freshness}; ${operation.detail ?? operation.summary}${identityNote}`;
+    }
+    if (operation.status === "failed") {
+        return `- [${candidate.originLabel}] ${candidate.path} :: status: failed via ${operation.id}${provenance}${freshness}; ${operation.failure?.class ?? "unknown failure"}${identityNote}`;
+    }
+    return `- [${candidate.originLabel}] ${candidate.path} :: status: ${operation.status} via ${operation.id}${provenance}${freshness}; ${operation.summary}${identityNote}`;
+}
+function renderRecentArchiveStatus(agentId) {
+    const candidates = (0, mail_import_discovery_1.defaultMailImportDiscoveryDirs)({
+        agentName: agentId,
+        repoRoot: (0, identity_1.getRepoRoot)(),
+        homeDir: process.env.HOME,
+    })
+        .flatMap((dir) => (0, mail_import_discovery_1.listDiscoveredMboxCandidates)(dir))
+        .sort((left, right) => right.mtimeMs - left.mtimeMs)
+        .slice(0, 5);
+    if (candidates.length === 0)
+        return ["- none discovered in browser sandboxes or Downloads"];
+    /* v8 ignore start -- branchy convergence helpers (operation + lane key + newestByLane) are exercised end-to-end via mail_status integration tests; leaf branches here are convergence-pass1 internals */
+    const operationsByPath = new Map();
+    for (const candidate of candidates) {
+        const operation = matchingMailImportOperation(agentId, candidate);
+        if (operation)
+            operationsByPath.set(candidate.path, operation);
+    }
+    const newestByLane = newestCurrentLaneArchiveMtimes(candidates, operationsByPath);
+    return candidates.map((candidate) => {
+        const operation = operationsByPath.get(candidate.path) ?? null;
+        const ownerEmail = typeof operation?.spec?.ownerEmail === "string" ? operation.spec.ownerEmail : "";
+        const source = typeof operation?.spec?.source === "string" ? operation.spec.source : "";
+        const laneKey = archiveLaneKey(ownerEmail, source);
+        return renderArchiveStatus(candidate, operation, laneKey ? (newestByLane.get(laneKey) ?? null) : null);
+    });
+    /* v8 ignore stop */
+}
+function renderRecentImportOperations(agentId) {
+    const operations = (0, background_operations_1.listBackgroundOperations)({
+        agentName: agentId,
+        agentRoot: (0, identity_1.getAgentRoot)(agentId),
+        limit: 10,
+    }).filter((record) => record.kind === "mail.import-mbox")
+        .sort((left, right) => {
+        const leftTs = comparableOperationTimestamp(left);
+        const rightTs = comparableOperationTimestamp(right);
+        return rightTs - leftTs;
+    })
+        .slice(0, 5);
+    if (operations.length === 0)
+        return ["- none recorded yet"];
+    return operations.map((operation) => {
+        const ownerEmail = typeof operation.spec?.ownerEmail === "string" ? operation.spec.ownerEmail : "";
+        const source = typeof operation.spec?.source === "string" ? operation.spec.source : "";
+        const provenance = ownerEmail || source ? ` ${ownerEmail || "unknown"} / ${source || "unknown"}` : "";
+        const failure = operation.failure?.class ? `; failure=${operation.failure.class}` : "";
+        return `- ${operation.id} [${operation.status}]${provenance} :: ${operation.detail ?? operation.summary}${failure}`;
+    });
+}
+async function searchSuccessfulImportArchives(input) {
+    if (input.limit <= 0 || input.queryTerms.length === 0)
+        return [];
+    let registry;
+    try {
+        registry = await (0, reader_1.readMailroomRegistry)(input.config);
+    }
+    catch {
+        return [];
+    }
+    const operations = (0, background_operations_1.listBackgroundOperations)({
+        agentName: input.agentId,
+        agentRoot: (0, identity_1.getAgentRoot)(input.agentId),
+        limit: 20,
+    })
+        .filter((record) => record.kind === "mail.import-mbox" && record.status === "succeeded")
+        .sort((left, right) => comparableOperationTimestamp(right) - comparableOperationTimestamp(left));
+    const seenPaths = new Set();
+    const matches = [];
+    const seenMessages = new Set();
+    for (const operation of operations) {
+        const filePath = typeof operation.spec?.filePath === "string" ? operation.spec.filePath.trim() : "";
+        if (!filePath || seenPaths.has(filePath) || !node_fs_1.default.existsSync(filePath))
+            continue;
+        seenPaths.add(filePath);
+        const source = typeof operation.spec?.source === "string" ? operation.spec.source : "";
+        if (input.source && source.toLowerCase() !== input.source.toLowerCase())
+            continue;
+        const ownerEmail = typeof operation.spec?.ownerEmail === "string" ? operation.spec.ownerEmail : undefined;
+        const found = await (0, mbox_import_1.cacheMatchingMailSearchDocumentsFromMboxFile)({
+            registry,
+            agentId: input.agentId,
+            filePath,
+            ownerEmail,
+            source: source || input.source,
+            queryTerms: input.queryTerms,
+            limit: input.limit - matches.length,
+        });
+        for (const document of found) {
+            if (seenMessages.has(document.messageId))
+                continue;
+            seenMessages.add(document.messageId);
+            matches.push(document);
+        }
+        if (matches.length >= input.limit)
+            break;
+    }
+    return matches.sort((left, right) => right.receivedAt.localeCompare(left.receivedAt));
+}
+async function renderMailStatus(agentId, config, storeLabel) {
+    const sourceGrantStatus = await renderSourceGrantStatus(config, agentId);
+    const delegatedLines = sourceGrantStatus
+        .flatMap((line) => line.startsWith("delegated source aliases: ")
+        ? line
+            .replace("delegated source aliases: ", "")
+            .replace(/\.$/, "")
+            .split("; ")
+            .filter(Boolean)
+            .map((grant) => {
+            const [sourceOwner, alias] = grant.split(" -> ");
+            const [source, ownerEmail] = sourceOwner.split(":");
+            return source && ownerEmail && alias
+                ? `- delegated: ${ownerEmail} / ${source} -> ${alias}`
+                : `- delegated: ${grant}`;
+        })
+        : [`- ${line}`]);
+    return [
+        `mailbox: ${config.mailboxAddress}`,
+        `store: ${storeLabel}`,
+        "lane map:",
+        `- native: ${config.mailboxAddress}`,
+        ...delegatedLines,
+        "recent archives:",
+        ...renderRecentArchiveStatus(agentId),
+        "recent imports:",
+        ...renderRecentImportOperations(agentId),
+    ].join("\n");
+}
 exports.mailToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "mail_status",
+                description: "Show the current mail operating model: native/delegated lanes, recent import artifacts, and recent mail import operations.",
+                parameters: { type: "object", properties: {} },
+            },
+        },
+        handler: async (_args, ctx) => {
+            if (!trustAllowsMailRead(ctx))
+                return "mail is private; this tool is only available in trusted contexts.";
+            const blocked = delegatedHumanMailBlocked(ctx);
+            if (blocked)
+                return blocked;
+            const resolved = (0, reader_1.resolveMailroomReader)();
+            if (!resolved.ok)
+                return resolved.error;
+            await resolved.store.recordAccess({
+                agentId: resolved.agentName,
+                tool: "mail_status",
+                reason: "mail operating model overview",
+            });
+            return renderMailStatus(resolved.agentName, resolved.config, resolved.storeLabel);
+        },
+        summaryKeys: [],
+    },
     {
         tool: {
             type: "function",
@@ -472,6 +814,7 @@ exports.mailToolDefinitions = [
             if (result.decrypted.length === 0) {
                 return appendDecryptSkips("No decryptable mail to show.", result.skipped);
             }
+            cacheDecryptedMessages(result.decrypted);
             return appendDecryptSkips(result.decrypted.map(renderMessageSummary).join("\n\n"), result.skipped);
         },
         summaryKeys: ["scope", "placement", "source", "limit"],
@@ -632,6 +975,7 @@ exports.mailToolDefinitions = [
             const query = (args.query ?? "").trim().toLowerCase();
             if (!query)
                 return "query is required.";
+            const terms = mailSearchTerms(query);
             const requestedScope = args.scope === "all" ? "all" : parseScope(args.scope);
             const explicitScope = (args.scope ?? "").trim().length > 0;
             if (!familyOrAgentSelf(ctx) && explicitScope && requestedScope !== "native") {
@@ -643,22 +987,62 @@ exports.mailToolDefinitions = [
             const scope = requestedScope === "all"
                 ? undefined
                 : requestedScope ?? (familyOrAgentSelf(ctx) ? undefined : "native");
+            const limit = numberArg(args.limit, 10, 1, 20);
+            const cachedMatches = (0, search_cache_1.searchMailSearchCache)({
+                agentId: resolved.agentName,
+                placement: parsePlacement(args.placement),
+                compartmentKind: scope,
+                source: args.source,
+                queryTerms: terms,
+                limit,
+            });
+            if (cachedMatches.length > 0 && cachedMatches.every((message) => message.compartmentKind === "delegated")) {
+                await resolved.store.recordAccess({
+                    agentId: resolved.agentName,
+                    tool: "mail_search",
+                    reason: args.reason || `search: ${query}`,
+                });
+                return cachedMatches.map((message) => renderCachedMessageSummary(message, terms)).join("\n\n");
+            }
+            if (scope !== "native"
+                && resolved.storeKind === "azure-blob"
+                && (cachedMatches.length === 0 || cachedMatches.some((message) => message.compartmentKind !== "delegated"))) {
+                const importedMatches = await searchSuccessfulImportArchives({
+                    agentId: resolved.agentName,
+                    config: resolved.config,
+                    queryTerms: terms,
+                    limit,
+                    ...(args.source ? { source: args.source } : {}),
+                });
+                if (importedMatches.length > 0) {
+                    const mergedMatches = mergeCachedMailSearchDocuments(cachedMatches, importedMatches, limit, terms);
+                    await resolved.store.recordAccess({
+                        agentId: resolved.agentName,
+                        tool: "mail_search",
+                        reason: args.reason || `search: ${query}`,
+                    });
+                    return mergedMatches.map((message) => renderCachedMessageSummary(message, terms)).join("\n\n");
+                }
+            }
             const all = await resolved.store.listMessages({
                 agentId: resolved.agentName,
                 placement: parsePlacement(args.placement),
                 compartmentKind: scope,
                 source: args.source,
-                limit: 200,
             });
             const result = decryptVisibleMessages(all, resolved.config.privateKeys);
+            cacheDecryptedMessages(result.decrypted);
             const matching = result.decrypted
-                .filter((message) => [
-                message.private.subject,
-                message.private.snippet,
-                message.private.text,
-                message.private.from.join(" "),
-            ].join("\n").toLowerCase().includes(query))
-                .slice(0, numberArg(args.limit, 10, 1, 20));
+                .filter((message) => {
+                const haystack = [
+                    message.private.subject,
+                    message.private.snippet,
+                    message.private.text,
+                    message.private.from.join(" "),
+                ].join("\n").toLowerCase();
+                return terms.some((term) => haystack.includes(term));
+            })
+                .slice(0, limit);
             await resolved.store.recordAccess({
                 agentId: resolved.agentName,
                 tool: "mail_search",
@@ -730,6 +1114,7 @@ exports.mailToolDefinitions = [
                     throw error;
                 return renderUndecryptableThread(message, keyId);
             }
+            (0, search_cache_1.upsertMailSearchCacheDocument)(message, decrypted.private);
             const maxChars = numberArg(args.max_chars, 2000, 200, 6000);
             const body = decrypted.private.text.length > maxChars
                 ? `${decrypted.private.text.slice(0, maxChars - 3)}...`
@@ -851,8 +1236,8 @@ exports.mailToolDefinitions = [
                 reason,
                 ...accessProvenance(message),
             });
-            const senderPolicyLine = persistSenderPolicyForDecision({
-                registryPath: resolved.config.registryPath,
+            const senderPolicyLine = await persistSenderPolicyForDecision({
+                config: resolved.config,
                 agentId: resolved.agentName,
                 action,
                 reason,