npm - @ouro.bot/cli - Versions diffs - 0.1.0-alpha.453 → 0.1.0-alpha.455 - Mend

@ouro.bot/cli 0.1.0-alpha.453 → 0.1.0-alpha.455

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/changelog.json +16 -0
package/dist/heart/daemon/cli-exec.js +161 -66
package/dist/heart/daemon/cli-help.js +12 -0
package/dist/heart/daemon/cli-parse.js +13 -0
package/dist/heart/daemon/runtime-logging.js +1 -1
package/dist/heart/daemon/sense-manager.js +10 -2
package/dist/heart/outlook/readers/mail.js +72 -2
package/dist/mailroom/attention.js +154 -0
package/dist/mailroom/blob-store.js +150 -2
package/dist/mailroom/core.js +160 -9
package/dist/mailroom/file-store.js +164 -2
package/dist/mailroom/outbound.js +177 -0
package/dist/mailroom/policy.js +263 -0
package/dist/mailroom/reader.js +16 -0
package/dist/mailroom/travel-extract.js +89 -0
package/dist/mind/prompt.js +4 -1
package/dist/outlook-ui/assets/index-BPr5vNuM.css +1 -0
package/dist/outlook-ui/assets/index-BSNvyKGt.js +61 -0
package/dist/outlook-ui/index.html +2 -2
package/dist/repertoire/guardrails.js +25 -0
package/dist/repertoire/tools-base.js +2 -0
package/dist/repertoire/tools-mail.js +480 -4
package/dist/senses/mail-entry.js +66 -0
package/dist/senses/mail.js +224 -0
package/package.json +1 -1
package/dist/outlook-ui/assets/index-BXw3xmUo.js +0 -61
package/dist/outlook-ui/assets/index-D4Wg-o8Z.css +0 -1

package/dist/outlook-ui/index.html CHANGED Viewed

@@ -6,8 +6,8 @@
     <meta name="color-scheme" content="dark" />
     <title>Ouro Outlook</title>
     <meta name="description" content="The daemon-hosted shared orientation surface for agents alive on this machine." />
-    <script type="module" crossorigin src="/assets/index-BXw3xmUo.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-D4Wg-o8Z.css">
+    <script type="module" crossorigin src="/assets/index-BSNvyKGt.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BPr5vNuM.css">
   </head>
   <body>
     <div id="app"></div>

package/dist/repertoire/guardrails.js CHANGED Viewed

@@ -301,6 +301,28 @@ const CREDENTIAL_TRUSTED_TOOLS = new Set(["credential_get", "credential_list"]);
 // advisory and geocode are public APIs but gated for consistency)
 // Flight search is also friend+ (read-only, no payment)
 const TRAVEL_TRUSTED_TOOLS = new Set(["weather_lookup", "travel_advisory", "geocode_search", "flight_search"]);
+const MAIL_FAMILY_TOOLS = new Set(["mail_screener", "mail_decide", "mail_access_log", "mail_send"]);
+const MAIL_DELEGATED_READ_TOOLS = new Set(["mail_recent", "mail_search"]);
+function mailTrustGuardrail(toolName, args, context) {
+    if (MAIL_FAMILY_TOOLS.has(toolName)) {
+        if (context.trustLevel === undefined || context.trustLevel === "family")
+            return allow;
+        if (toolName === "mail_send")
+            return deny("outbound mail sends require family trust.");
+        return deny(toolName === "mail_decide"
+            ? "mail screener decisions require family trust."
+            : "delegated human mail requires family trust.");
+    }
+    if (MAIL_DELEGATED_READ_TOOLS.has(toolName)) {
+        const scope = (args.scope ?? "").trim().toLowerCase();
+        if (scope === "delegated" || scope === "all") {
+            if (context.trustLevel === undefined || context.trustLevel === "family")
+                return allow;
+            return deny("delegated human mail requires family trust.");
+        }
+    }
+    return allow;
+}
 function checkCredentialTrustGuardrails(toolName, context) {
     if (CREDENTIAL_FAMILY_TOOLS.has(toolName)) {
         if (context.trustLevel === "family")
@@ -329,6 +351,9 @@ function checkFirstClassMcpTrust(context) {
     return allow;
 }
 function checkTrustLevelGuardrails(toolName, args, context) {
+    const mailResult = mailTrustGuardrail(toolName, args, context);
+    if (!mailResult.allowed)
+        return mailResult;
     // Credential tools have their own trust rules that apply at all levels
     const credentialResult = checkCredentialTrustGuardrails(toolName, context);
     if (!credentialResult.allowed)

package/dist/repertoire/tools-base.js CHANGED Viewed

@@ -16,6 +16,7 @@ const tools_user_profile_1 = require("./tools-user-profile");
 const tools_stripe_1 = require("./tools-stripe");
 const tools_flight_1 = require("./tools-flight");
 const tools_attachments_1 = require("./tools-attachments");
+const tools_mail_1 = require("./tools-mail");
 // Re-export flow tools for consumers that import them from tools-base
 var tools_flow_1 = require("./tools-flow");
 Object.defineProperty(exports, "ponderTool", { enumerable: true, get: function () { return tools_flow_1.ponderTool; } });
@@ -46,6 +47,7 @@ exports.baseToolDefinitions = [
     ...tools_stripe_1.stripeToolDefinitions,
     ...tools_flight_1.flightToolDefinitions,
     ...tools_attachments_1.attachmentToolDefinitions,
+    ...tools_mail_1.mailToolDefinitions,
 ];
 // Convenience array of just the tool schemas (no handler/integration metadata).
 // Used by consumers that need the OpenAI function-tool format.

package/dist/repertoire/tools-mail.js CHANGED Viewed

@@ -1,9 +1,46 @@
 "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.mailToolDefinitions = void 0;
+const fs = __importStar(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 core_1 = require("../mailroom/core");
 const runtime_1 = require("../nerves/runtime");
 function trustAllowsMailRead(ctx) {
     const trustLevel = ctx?.context?.friend?.trustLevel;
@@ -16,12 +53,44 @@ function trustAllowsMailRead(ctx) {
     });
     return allowed;
 }
+function familyOrAgentSelf(ctx) {
+    const trustLevel = ctx?.context?.friend?.trustLevel;
+    return trustLevel === undefined || trustLevel === "family";
+}
+function delegatedHumanMailBlocked(ctx) {
+    if (familyOrAgentSelf(ctx))
+        return null;
+    return "delegated human mail requires family trust.";
+}
+function screenerDecisionBlocked(ctx) {
+    if (familyOrAgentSelf(ctx))
+        return null;
+    return "mail screener decisions require family trust.";
+}
+function outboundSendBlocked(ctx) {
+    if (familyOrAgentSelf(ctx))
+        return null;
+    return "outbound mail sends require family trust.";
+}
 function numberArg(value, fallback, min, max) {
     const parsed = value ? Number.parseInt(value, 10) : fallback;
     if (!Number.isFinite(parsed))
         return fallback;
     return Math.min(max, Math.max(min, parsed));
 }
+const MAIL_PLACEMENTS = ["imbox", "screener", "discarded", "quarantine", "draft", "sent"];
+function parsePlacement(value) {
+    return MAIL_PLACEMENTS.includes(value) ? value : undefined;
+}
+function parseScope(value) {
+    return value === "native" || value === "delegated" ? value : undefined;
+}
+function parseMailList(value) {
+    return (value ?? "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
 function renderMessageSummary(message) {
     const scope = message.compartmentKind === "delegated"
         ? `delegated:${message.ownerEmail ?? "unknown"}:${message.source ?? "source"}`
@@ -36,6 +105,18 @@ function renderMessageSummary(message) {
         `  warning: ${message.private.untrustedContentWarning}`,
     ].join("\n");
 }
+function renderScreenerCandidate(candidate) {
+    const delegated = candidate.ownerEmail || candidate.source
+        ? ` delegated:${candidate.ownerEmail ?? "unknown"}:${candidate.source ?? "source"}`
+        : "";
+    return [
+        `- ${candidate.id} -> ${candidate.messageId} [${candidate.status}; ${candidate.placement}${delegated}]`,
+        `  sender: ${candidate.senderDisplay || candidate.senderEmail} <${candidate.senderEmail}>`,
+        `  recipient: ${candidate.recipient}`,
+        `  last seen: ${candidate.lastSeenAt}; messages: ${candidate.messageCount}`,
+        `  reason: ${candidate.trustReason}`,
+    ].join("\n");
+}
 function renderAccessLog(entries) {
     if (entries.length === 0)
         return "No mail access records yet.";
@@ -48,6 +129,124 @@ function renderAccessLog(entries) {
     })
         .join("\n");
 }
+function actorFromContext(ctx, agentId) {
+    const friend = ctx?.context?.friend;
+    if (friend) {
+        return {
+            kind: "human",
+            friendId: friend.id,
+            trustLevel: friend.trustLevel,
+            channel: ctx?.context?.channel.channel,
+        };
+    }
+    return { kind: "agent", agentId };
+}
+const MAIL_DECISION_ACTIONS = [
+    "link-friend",
+    "create-friend",
+    "allow-sender",
+    "allow-source",
+    "allow-domain",
+    "allow-thread",
+    "discard",
+    "quarantine",
+    "restore",
+];
+function parseDecisionAction(value) {
+    return MAIL_DECISION_ACTIONS.includes(value) ? value : null;
+}
+const MAIL_CANDIDATE_STATUSES = ["pending", "allowed", "discarded", "quarantined", "restored"];
+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;
+}
+function normalizePolicySender(candidate, message, privateKeys) {
+    const candidates = [
+        candidate?.senderEmail,
+        ...(0, file_store_1.decryptMessages)([message], privateKeys)[0].private.from,
+        message.envelope.mailFrom,
+    ].filter((value) => typeof value === "string" && value.trim().length > 0 && value !== "(unknown)");
+    for (const candidateValue of candidates) {
+        try {
+            return (0, core_1.normalizeMailAddress)(candidateValue);
+        }
+        catch {
+            // Try the next source of sender truth.
+        }
+    }
+    /* v8 ignore next -- exhaustive fallback: current persisted-policy actions are handled above. @preserve */
+    return null;
+}
+function policyMatchForDecision(input) {
+    if (input.action === "allow-source") {
+        if (!input.message.source)
+            return null;
+        return {
+            match: { kind: "source", value: input.message.source.toLowerCase() },
+            scope: `source:${input.message.source.toLowerCase()}`,
+        };
+    }
+    if (!input.sender)
+        return null;
+    if (input.action === "allow-domain") {
+        const domain = input.sender.slice(input.sender.indexOf("@") + 1);
+        return { match: { kind: "domain", value: domain }, scope: policyScopeForMessage(input.message) };
+    }
+    return { match: { kind: "email", value: input.sender }, scope: policyScopeForMessage(input.message) };
+}
+function samePolicy(left, right) {
+    return left.agentId === right.agentId &&
+        left.action === right.action &&
+        left.scope === right.scope &&
+        left.match.kind === right.match.kind &&
+        left.match.value === right.match.value;
+}
+function policyLine(policy, existing) {
+    return `sender policy: ${existing ? "already " : ""}${policy.action} ${policy.match.kind} ${policy.match.value}`;
+}
+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);
+    const match = policyMatchForDecision({ action: input.action, sender, message: input.message });
+    if (!match)
+        return "sender policy: skipped (sender/source unavailable)";
+    const policy = (0, policy_1.buildSenderPolicy)({
+        agentId: input.agentId,
+        scope: match.scope,
+        match: match.match,
+        action: input.action === "discard" || input.action === "quarantine" ? input.action : "allow",
+        actor: input.actor,
+        reason: input.reason,
+    });
+    const registry = readRegistry(input.registryPath);
+    const existing = (registry.senderPolicies ?? []).find((candidatePolicy) => samePolicy(candidatePolicy, policy));
+    if (existing)
+        return policyLine(existing, true);
+    registry.senderPolicies = [...(registry.senderPolicies ?? []), policy];
+    writeRegistry(input.registryPath, registry);
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.mail_sender_policy_persisted",
+        message: "mail sender policy persisted from screener decision",
+        meta: { agentId: input.agentId, action: policy.action, scope: policy.scope, matchKind: policy.match.kind },
+    });
+    return policyLine(policy, false);
+}
 exports.mailToolDefinitions = [
     {
         tool: {
@@ -59,7 +258,7 @@ exports.mailToolDefinitions = [
                     type: "object",
                     properties: {
                         limit: { type: "string", description: "Maximum messages to return, 1-20. Defaults to 10." },
-                        placement: { type: "string", enum: ["imbox", "screener"], description: "Optional Imbox/Screener filter." },
+                        placement: { type: "string", enum: ["imbox", "screener", "discarded", "quarantine", "draft", "sent"], description: "Optional mailbox placement filter." },
                         scope: { type: "string", enum: ["native", "delegated", "all"], description: "Optional mailbox scope. Defaults to all visible mail." },
                         source: { type: "string", description: "Optional delegated source filter, e.g. hey." },
                         reason: { type: "string", description: "Why you are looking at this mail. Logged for audit." },
@@ -70,13 +269,21 @@ exports.mailToolDefinitions = [
         handler: async (args, ctx) => {
             if (!trustAllowsMailRead(ctx))
                 return "mail is private; this tool is only available in trusted contexts.";
+            const requestedScope = args.scope === "all" ? "all" : parseScope(args.scope);
+            if (requestedScope === "delegated" || requestedScope === "all") {
+                const blocked = delegatedHumanMailBlocked(ctx);
+                if (blocked)
+                    return blocked;
+            }
             const resolved = (0, reader_1.resolveMailroomReader)();
             if (!resolved.ok)
                 return resolved.error;
-            const scope = args.scope === "native" || args.scope === "delegated" ? args.scope : undefined;
+            const scope = requestedScope === "all"
+                ? undefined
+                : requestedScope ?? (familyOrAgentSelf(ctx) ? undefined : "native");
             const messages = await resolved.store.listMessages({
                 agentId: resolved.agentName,
-                placement: args.placement === "imbox" || args.placement === "screener" ? args.placement : undefined,
+                placement: parsePlacement(args.placement),
                 compartmentKind: scope,
                 source: args.source,
                 limit: numberArg(args.limit, 10, 1, 20),
@@ -92,6 +299,123 @@ exports.mailToolDefinitions = [
         },
         summaryKeys: ["scope", "placement", "source", "limit"],
     },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "mail_compose",
+                description: "Create an outbound mail draft in the agent mailbox. This does not send mail; use mail_send with explicit confirmation for that.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        to: { type: "string", description: "Comma-separated recipient email addresses." },
+                        cc: { type: "string", description: "Optional comma-separated CC addresses." },
+                        bcc: { type: "string", description: "Optional comma-separated BCC addresses." },
+                        subject: { type: "string", description: "Draft subject." },
+                        text: { type: "string", description: "Plain-text draft body." },
+                        reason: { type: "string", description: "Why this draft is being created. Logged for audit." },
+                    },
+                    required: ["to", "subject", "text", "reason"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            if (!trustAllowsMailRead(ctx))
+                return "mail is private; this tool is only available in trusted contexts.";
+            const resolved = (0, reader_1.resolveMailroomReader)();
+            if (!resolved.ok)
+                return resolved.error;
+            try {
+                const draft = await (0, outbound_1.createMailDraft)({
+                    store: resolved.store,
+                    agentId: resolved.agentName,
+                    from: resolved.config.mailboxAddress,
+                    to: parseMailList(args.to),
+                    cc: parseMailList(args.cc),
+                    bcc: parseMailList(args.bcc),
+                    subject: args.subject ?? "",
+                    text: args.text ?? "",
+                    actor: actorFromContext(ctx, resolved.agentName),
+                    reason: args.reason ?? "compose outbound mail",
+                });
+                await resolved.store.recordAccess({
+                    agentId: resolved.agentName,
+                    tool: "mail_compose",
+                    reason: args.reason || "compose outbound mail",
+                });
+                return [
+                    `Draft created: ${draft.id}`,
+                    `from: ${draft.from}`,
+                    `to: ${draft.to.join(", ")}`,
+                    `subject: ${draft.subject || "(no subject)"}`,
+                    "send: call mail_send with draft_id and confirmation=CONFIRM_SEND after explicit approval.",
+                ].join("\n");
+            }
+            catch (error) {
+                return error instanceof Error ? error.message : /* v8 ignore next -- defensive: draft creation throws Error instances. @preserve */ String(error);
+            }
+        },
+        summaryKeys: ["to", "subject"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "mail_send",
+                description: "Send a draft only after explicit confirmation. Autonomous sending is refused.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        draft_id: { type: "string", description: "Draft id from mail_compose." },
+                        confirmation: { type: "string", description: "Must be exactly CONFIRM_SEND." },
+                        reason: { type: "string", description: "Why this send is authorized. Logged for audit." },
+                        autonomous: { type: "string", enum: ["true", "false"], description: "Must not be true; autonomous sends are refused." },
+                    },
+                    required: ["draft_id", "confirmation", "reason"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            if (!trustAllowsMailRead(ctx))
+                return "mail is private; this tool is only available in trusted contexts.";
+            const blocked = outboundSendBlocked(ctx);
+            if (blocked)
+                return blocked;
+            const draftId = (args.draft_id ?? "").trim();
+            if (!draftId)
+                return "draft_id is required.";
+            const resolved = (0, reader_1.resolveMailroomReader)();
+            if (!resolved.ok)
+                return resolved.error;
+            try {
+                const sent = await (0, outbound_1.confirmMailDraftSend)({
+                    store: resolved.store,
+                    agentId: resolved.agentName,
+                    draftId,
+                    transport: (0, outbound_1.resolveOutboundTransport)(resolved.config),
+                    confirmation: args.confirmation ?? "",
+                    autonomous: args.autonomous === "true",
+                    actor: actorFromContext(ctx, resolved.agentName),
+                    reason: args.reason ?? "confirmed outbound send",
+                });
+                await resolved.store.recordAccess({
+                    agentId: resolved.agentName,
+                    tool: "mail_send",
+                    reason: args.reason || "confirmed outbound send",
+                });
+                return [
+                    `Mail sent: ${sent.id}`,
+                    `transport: ${sent.transport}`,
+                    `sentAt: ${sent.sentAt}`,
+                    `to: ${sent.to.join(", ")}`,
+                ].join("\n");
+            }
+            catch (error) {
+                return error instanceof Error ? error.message : /* v8 ignore next -- defensive: send confirmation throws Error instances. @preserve */ String(error);
+            }
+        },
+        summaryKeys: ["draft_id"],
+    },
     {
         tool: {
             type: "function",
@@ -103,6 +427,9 @@ exports.mailToolDefinitions = [
                     properties: {
                         query: { type: "string", description: "Search text." },
                         limit: { type: "string", description: "Maximum matching messages, 1-20. Defaults to 10." },
+                        placement: { type: "string", enum: ["imbox", "screener", "discarded", "quarantine", "draft", "sent"], description: "Optional mailbox placement filter." },
+                        scope: { type: "string", enum: ["native", "delegated", "all"], description: "Optional mailbox scope. Defaults to family/self-visible mail." },
+                        source: { type: "string", description: "Optional delegated source filter, e.g. hey." },
                         reason: { type: "string", description: "Why you are searching this mail. Logged for audit." },
                     },
                     required: ["query"],
@@ -115,10 +442,24 @@ exports.mailToolDefinitions = [
             const query = (args.query ?? "").trim().toLowerCase();
             if (!query)
                 return "query is required.";
+            const requestedScope = args.scope === "all" ? "all" : parseScope(args.scope);
+            const explicitScope = (args.scope ?? "").trim().length > 0;
+            if (!familyOrAgentSelf(ctx) && explicitScope && requestedScope !== "native") {
+                return "delegated human mail requires family trust.";
+            }
             const resolved = (0, reader_1.resolveMailroomReader)();
             if (!resolved.ok)
                 return resolved.error;
-            const all = await resolved.store.listMessages({ agentId: resolved.agentName, limit: 200 });
+            const scope = requestedScope === "all"
+                ? undefined
+                : requestedScope ?? (familyOrAgentSelf(ctx) ? undefined : "native");
+            const all = await resolved.store.listMessages({
+                agentId: resolved.agentName,
+                placement: parsePlacement(args.placement),
+                compartmentKind: scope,
+                source: args.source,
+                limit: 200,
+            });
             const matching = (0, file_store_1.decryptMessages)(all, resolved.config.privateKeys)
                 .filter((message) => [
                 message.private.subject,
@@ -167,6 +508,11 @@ exports.mailToolDefinitions = [
             const message = await resolved.store.getMessage(messageId);
             if (!message || message.agentId !== resolved.agentName)
                 return `No visible mail message found for ${messageId}.`;
+            if (message.compartmentKind === "delegated") {
+                const blocked = delegatedHumanMailBlocked(ctx);
+                if (blocked)
+                    return blocked;
+            }
             const decrypted = (0, file_store_1.decryptMessages)([message], resolved.config.privateKeys)[0];
             await resolved.store.recordAccess({
                 agentId: resolved.agentName,
@@ -187,6 +533,133 @@ exports.mailToolDefinitions = [
         },
         summaryKeys: ["message_id", "reason"],
     },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "mail_screener",
+                description: "List Mail Screener candidates without message bodies so the agent can ask family how to resolve unknown inbound mail.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        status: { type: "string", enum: ["pending", "allowed", "discarded", "quarantined", "restored"], description: "Optional Screener candidate status. Defaults to pending." },
+                        placement: { type: "string", enum: ["screener", "discarded", "quarantine", "imbox"], description: "Optional current placement filter." },
+                        limit: { type: "string", description: "Maximum candidates to return, 1-50. Defaults to 20." },
+                        reason: { type: "string", description: "Why you are inspecting the Screener. Logged for audit." },
+                    },
+                },
+            },
+        },
+        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;
+            const candidates = await resolved.store.listScreenerCandidates({
+                agentId: resolved.agentName,
+                status: parseCandidateStatus(args.status) ?? "pending",
+                placement: parsePlacement(args.placement),
+                limit: numberArg(args.limit, 20, 1, 50),
+            });
+            await resolved.store.recordAccess({
+                agentId: resolved.agentName,
+                tool: "mail_screener",
+                reason: args.reason || "screener overview",
+            });
+            if (candidates.length === 0)
+                return "No Screener candidates.";
+            return candidates.map(renderScreenerCandidate).join("\n\n");
+        },
+        summaryKeys: ["status", "placement", "limit"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "mail_decide",
+                description: "Apply a family-authorized Screener decision to a candidate while retaining discarded mail for recovery.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        candidate_id: { type: "string", description: "Candidate id from mail_screener." },
+                        message_id: { type: "string", description: "Message id when resolving a known message directly." },
+                        action: { type: "string", enum: ["link-friend", "create-friend", "allow-sender", "allow-source", "allow-domain", "allow-thread", "discard", "quarantine", "restore"], description: "Decision to apply." },
+                        reason: { type: "string", description: "Why this decision is authorized. Logged for audit." },
+                        friend_id: { type: "string", description: "Optional friend id for link-friend decisions." },
+                    },
+                    required: ["action", "reason"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            if (!trustAllowsMailRead(ctx))
+                return "mail is private; this tool is only available in trusted contexts.";
+            const blocked = screenerDecisionBlocked(ctx);
+            if (blocked)
+                return blocked;
+            const action = parseDecisionAction(args.action);
+            if (!action)
+                return "action is required and must be a supported mail decision.";
+            const reason = (args.reason ?? "").trim();
+            if (!reason)
+                return "reason is required.";
+            const resolved = (0, reader_1.resolveMailroomReader)();
+            if (!resolved.ok)
+                return resolved.error;
+            let messageId = (args.message_id ?? "").trim();
+            const candidateId = (args.candidate_id ?? "").trim();
+            let candidate;
+            if (candidateId) {
+                const candidates = await resolved.store.listScreenerCandidates({ agentId: resolved.agentName, limit: 200 });
+                candidate = candidates.find((entry) => entry.id === candidateId);
+                if (!candidate)
+                    return `No Screener candidate found for ${candidateId}.`;
+                messageId = candidate.messageId;
+            }
+            if (!messageId)
+                return "candidate_id or message_id is required.";
+            const message = await resolved.store.getMessage(messageId);
+            if (!message || message.agentId !== resolved.agentName)
+                return `No visible mail message found for ${messageId}.`;
+            const decision = await (0, policy_1.applyMailDecision)({
+                store: resolved.store,
+                agentId: resolved.agentName,
+                messageId,
+                action,
+                actor: actorFromContext(ctx, resolved.agentName),
+                reason,
+                ...(args.friend_id ? { friendId: args.friend_id } : {}),
+            });
+            await resolved.store.recordAccess({
+                agentId: resolved.agentName,
+                messageId,
+                tool: "mail_decide",
+                reason,
+            });
+            const senderPolicyLine = persistSenderPolicyForDecision({
+                registryPath: resolved.config.registryPath,
+                agentId: resolved.agentName,
+                action,
+                reason,
+                actor: actorFromContext(ctx, resolved.agentName),
+                ...(candidate ? { candidate } : {}),
+                message,
+                privateKeys: resolved.config.privateKeys,
+            });
+            return [
+                `Mail decision recorded: ${decision.action}`,
+                `message: ${decision.messageId}`,
+                `placement: ${decision.previousPlacement} -> ${decision.nextPlacement}`,
+                ...(senderPolicyLine ? [senderPolicyLine] : []),
+                decision.nextPlacement === "discarded" ? "discarded mail remains retained in the recovery drawer." : `decision: ${decision.id}`,
+            ].join("\n");
+        },
+        summaryKeys: ["candidate_id", "message_id", "action"],
+    },
     {
         tool: {
             type: "function",
@@ -199,6 +672,9 @@ exports.mailToolDefinitions = [
         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;