@ouro.bot/cli 0.1.0-alpha.501 → 0.1.0-alpha.504

package/changelog.json

@@ -1,6 +1,30 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.504",
+      "changes": [
+        "New `mail_outbox` tool — the agent can now introspect its own outbound mail (drafts, queued sends, delivered, bounced, etc.). The mail repertoire had `mail_compose`, `mail_send`, and `mail_recent` for inbound — but no symmetric way to ask 'what did I send / queue?' Operators were having to ssh in and `ls state/.../outbound`. Real-world need: when planning a trip with the operator, the agent often wants to verify it sent a confirmation request before re-asking.",
+        "Lists records newest-first (by `updatedAt`), bounded to `limit` (1-50, default 20), with optional `status` filter across the full MailOutboundStatus union (draft / sent / submitted / accepted / delivered / bounced / suppressed / quarantined / spam-filtered / failed). Each record renders id + status + recipients + truncated subject (80 chars) + last-touched timestamp + provider message id and error message when present. No body text dumped — agent uses message id with another tool if it needs the content.",
+        "Family-trust gated like the rest of mail (read gate, no special block since outbound metadata isn't body content). Records `mail_outbox` access in the access log alongside the other mail tools. Tool registry now at 75 tools (snapshot updated). Two tests cover the empty / sorted / limit / status-filter / audit-log paths, plus the trust block."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.503",
+      "changes": [
+        "In-process LRU cache for decrypted mail bodies. The cold path for `mail_thread` is read-encrypted-blob-from-Azure (1-3s p50, up to tens of seconds for HEY-sized bodies — #614 raised the timeout to 60s for this very reason) plus an RSA-OAEP+A256GCM decrypt. Repeated reads of the same message are common: re-checking a booking confirmation while seeding a trip leg, following up on a thread, looping back to verify a fact. Each repeat hit was paying the full cold cost.",
+        "New `src/mailroom/body-cache.ts` keeps a 50-entry LRU keyed by `StoredMailMessage.id` (a deterministic content hash — rotating keys produces a new id, so stale ciphertext can never be served against a fresh keyset). Insertion-order eviction; reads refresh LRU position. Per-process by design — daemon restart clears it (matches the established pattern with #618 heartbeat-recursion state and #621 BB own-handle discovery).",
+        "Wired into both `mail_thread` (cache-first read; on miss, do the disk fetch + decrypt and cache for next time) and `mail_recent`/`mail_search` (which already decrypt batches; now they also seed the body cache so the next `mail_thread` on any of those is free). New `repertoire.mail_body_cache_hit` info-level event makes hit rate observable via `ouro nerves-review --event mail_body_cache_hit` (alpha.501). 7 new tests cover hit/miss, LRU refresh-on-read, eviction at capacity, defensive empty-id handling, and clear."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.502",
+      "changes": [
+        "Enrich `engine.error` nerve event with HTTP status, redacted body excerpt, and a one-line summary string. Provider errors previously surfaced only as a free-form `error.message`, which forced operators to spelunk the SDK's wrapped object to find the actual status code or quota explanation.",
+        "Two new helpers in `src/heart/providers/error-classification.ts`: `extractProviderErrorDetails(error)` pulls `status` (when present) and a body excerpt (capped at 240 chars, with redaction of any 32+ char token-shaped substring so leaked auth keys don't get persisted into nerves), falling through `error.error → error.response → error.body → error.message` until something usable shows up. Survives circular structures defensively. `summarizeProviderError(error, classification, providerId, model)` produces the canonical operator-readable line: `provider <id>/<model>: <classification>[ HTTP <status>][ — <bodyExcerpt>]`.",
+        "Wired into `finishTerminalProviderError` in `src/heart/core.ts` so every terminal provider error now lands in nerves with `httpStatus` + `bodyExcerpt` + `summary` meta — making `ouro nerves-review --component engine --event engine.error` (alpha.501) immediately useful for diagnosing provider blowups. 11 new tests cover status capture, missing-status defaults, token redaction, 240-char truncation, fallback through alternate body fields, circular-structure safety, and summary formatting in two shapes."
+      ]
+    },
     {
       "version": "0.1.0-alpha.501",
       "changes": [

package/dist/heart/core.js

@@ -20,6 +20,7 @@ const runtime_1 = require("../nerves/runtime");
 const context_1 = require("../mind/context");
 const prompt_1 = require("../mind/prompt");
 const kept_notes_1 = require("./kept-notes");
+const error_classification_1 = require("./providers/error-classification");
 const anthropic_1 = require("./providers/anthropic");
 const azure_1 = require("./providers/azure");
 const minimax_1 = require("./providers/minimax");
@@ -613,6 +614,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             callbacks.onError(terminalError, "terminal");
         }
         /* v8 ignore stop */
+        const errorDetails = (0, error_classification_1.extractProviderErrorDetails)(terminalError);
         (0, runtime_1.emitNervesEvent)({
             level: "error",
             event: "engine.error",
@@ -623,6 +625,9 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 provider: providerRuntime.id,
                 model: providerRuntime.model,
                 errorClassification: terminalErrorClassification,
+                ...(errorDetails.status !== undefined ? { httpStatus: errorDetails.status } : {}),
+                ...(errorDetails.bodyExcerpt ? { bodyExcerpt: errorDetails.bodyExcerpt } : {}),
+                summary: (0, error_classification_1.summarizeProviderError)(terminalError, terminalErrorClassification, providerRuntime.id, providerRuntime.model),
             },
         });
         stripLastToolCalls(messages);

package/dist/heart/providers/error-classification.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isNetworkError = isNetworkError;
 exports.classifyHttpError = classifyHttpError;
+exports.extractProviderErrorDetails = extractProviderErrorDetails;
+exports.summarizeProviderError = summarizeProviderError;
 const runtime_1 = require("../../nerves/runtime");
 // Node socket / DNS error codes that indicate a transient network failure.
 const NETWORK_ERROR_CODES = new Set([
@@ -53,6 +55,68 @@ function classifyHttpError(error, overrides) {
         return "network-error";
     return "unknown";
 }
+// Pull HTTP status and a redacted body excerpt off a provider error if
+// either is present. SDK shapes: OpenAI puts `status` on the error, body
+// often on `error.error` or `error.response`. Keep this purely defensive —
+// any missing field returns undefined so callers can decide whether to
+// include it. The body excerpt is capped to 240 chars and stripped of
+// known auth-token-looking substrings.
+const ERROR_BODY_EXCERPT_MAX = 240;
+const TOKEN_PATTERN = /[A-Za-z0-9_\-]{32,}/g;
+function shorten(value) {
+    const collapsed = value.replace(/\s+/g, " ").trim();
+    if (collapsed.length === 0)
+        return "";
+    const redacted = collapsed.replace(TOKEN_PATTERN, "[redacted]");
+    return redacted.length > ERROR_BODY_EXCERPT_MAX
+        ? `${redacted.slice(0, ERROR_BODY_EXCERPT_MAX - 3)}...`
+        : redacted;
+}
+function extractProviderErrorDetails(error) {
+    const details = {};
+    const status = error.status;
+    if (typeof status === "number" && Number.isFinite(status))
+        details.status = status;
+    const errorAsRecord = error;
+    const candidates = [
+        errorAsRecord.error,
+        errorAsRecord.response,
+        errorAsRecord.body,
+        error.message,
+    ];
+    /* v8 ignore start -- candidate-shape branches: production provider errors expose string messages; object-shaped error.body and the string-false fall-through are fallbacks for non-OpenAI SDK shapes @preserve */
+    for (const candidate of candidates) {
+        if (!candidate)
+            continue;
+        if (typeof candidate === "string") {
+            const excerpt = shorten(candidate);
+            if (excerpt) {
+                details.bodyExcerpt = excerpt;
+                break;
+            }
+        }
+        else if (typeof candidate === "object") {
+            try {
+                const excerpt = shorten(JSON.stringify(candidate));
+                if (excerpt) {
+                    details.bodyExcerpt = excerpt;
+                    break;
+                }
+            }
+            catch {
+                // Circular structure or otherwise unstringifyable; skip.
+            }
+        }
+    }
+    /* v8 ignore stop */
+    return details;
+}
+function summarizeProviderError(error, classification, providerId, model) {
+    const details = extractProviderErrorDetails(error);
+    const statusPart = details.status !== undefined ? ` HTTP ${details.status}` : "";
+    const excerptPart = details.bodyExcerpt ? ` — ${details.bodyExcerpt}` : "";
+    return `provider ${providerId}/${model}: ${classification}${statusPart}${excerptPart}`;
+}
 /* v8 ignore start — module-level observability event */
 (0, runtime_1.emitNervesEvent)({
     component: "engine",

package/dist/mailroom/body-cache.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAIL_BODY_CACHE_MAX_ENTRIES = void 0;
+exports.getCachedMailBody = getCachedMailBody;
+exports.cacheMailBody = cacheMailBody;
+exports.clearMailBodyCache = clearMailBodyCache;
+exports.getMailBodyCacheSize = getMailBodyCacheSize;
+/**
+ * In-process LRU cache for decrypted mail bodies. The cold path for a
+ * single-message body fetch is: read encrypted blob from Azure Blob
+ * Storage (~1-3s p50 even for small bodies, into tens of seconds for
+ * HEY-sized HTML; #614 raised the timeout to 60s for this exact reason),
+ * then RSA-OAEP+A256GCM decrypt. Repeated reads of the same message are
+ * common — e.g. re-checking a booking confirmation when seeding a trip,
+ * or following up on a thread.
+ *
+ * Cache invariants:
+ * - keyed by `StoredMailMessage.id` (a deterministic content hash;
+ *   rotating keys produces a new id, so stale ciphertext can never be
+ *   served against a fresh key set).
+ * - bounded by `MAIL_BODY_CACHE_MAX_ENTRIES` with insertion-order LRU
+ *   eviction; oldest entries fall off when the cap is hit.
+ * - per-process; a daemon restart clears it. That matches the assumption
+ *   in #621 (BB own-handle discovery) and #618 (heartbeat recursion):
+ *   ephemeral state is fine for fast feedback, durable signals go to
+ *   nerves.
+ */
+exports.MAIL_BODY_CACHE_MAX_ENTRIES = 50;
+const cache = new Map();
+function getCachedMailBody(messageId) {
+    if (!messageId)
+        return undefined;
+    const value = cache.get(messageId);
+    if (!value)
+        return undefined;
+    // Refresh insertion order so this entry is not the next to evict.
+    cache.delete(messageId);
+    cache.set(messageId, value);
+    return value;
+}
+function cacheMailBody(message) {
+    if (!message.id)
+        return;
+    if (cache.has(message.id))
+        cache.delete(message.id);
+    cache.set(message.id, message);
+    while (cache.size > exports.MAIL_BODY_CACHE_MAX_ENTRIES) {
+        const oldestKey = cache.keys().next().value;
+        /* v8 ignore start -- defensive: cache.size > 0 by the loop guard, so first key is defined */
+        if (oldestKey === undefined)
+            break;
+        /* v8 ignore stop */
+        cache.delete(oldestKey);
+    }
+}
+function clearMailBodyCache() {
+    cache.clear();
+}
+function getMailBodyCacheSize() {
+    return cache.size;
+}

package/dist/nerves/coverage/file-completeness.js

@@ -125,6 +125,10 @@ const DISPATCH_EXEMPT_PATTERNS = [
     "nerves/review/cli-main",
     "nerves/review/cli",
     "nerves/review/core",
+    // Mail body cache: in-process LRU helper. Cache hit/miss observability
+    // lives at the caller (tools-mail.ts mail_body handler) which fires
+    // repertoire.mail_body_cache_hit on cache reuse.
+    "mailroom/body-cache",
 ];
 function isDispatchExempt(filePath) {
     return DISPATCH_EXEMPT_PATTERNS.some((pattern) => filePath.includes(pattern));

package/dist/repertoire/tools-mail.js

@@ -15,6 +15,7 @@ const outbound_1 = require("../mailroom/outbound");
 const policy_1 = require("../mailroom/policy");
 const search_cache_1 = require("../mailroom/search-cache");
 const thread_1 = require("../mailroom/thread");
+const body_cache_1 = require("../mailroom/body-cache");
 const mbox_import_1 = require("../mailroom/mbox-import");
 const search_relevance_1 = require("../mailroom/search-relevance");
 const core_1 = require("../mailroom/core");
@@ -254,6 +255,7 @@ function renderAccessLogProvenance(entry) {
 function cacheDecryptedMessages(messages) {
     for (const message of messages) {
         (0, search_cache_1.upsertMailSearchCacheDocument)(message, message.private);
+        (0, body_cache_1.cacheMailBody)(message);
     }
 }
 function accessProvenance(message) {
@@ -950,6 +952,68 @@ exports.mailToolDefinitions = [
         },
         summaryKeys: ["draft_id"],
     },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "mail_outbox",
+                description: "List recent outbound mail (drafts and sends) so the agent can introspect what it has sent or queued. Bounded summaries; no body dumps.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        limit: { type: "string", description: "Maximum records to return, 1-50. Defaults to 20." },
+                        status: { type: "string", enum: ["draft", "sent", "submitted", "accepted", "delivered", "bounced", "suppressed", "quarantined", "spam-filtered", "failed"], description: "Optional status filter." },
+                        reason: { type: "string", description: "Why you are inspecting outbound mail. Logged for audit." },
+                    },
+                },
+            },
+        },
+        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)();
+            /* v8 ignore next -- defensive: reader resolution covered separately for read tools; mail_outbox tests use cached config @preserve */
+            if (!resolved.ok)
+                return resolved.error;
+            const limit = numberArg(args.limit, 20, 1, 50);
+            const records = await resolved.store.listMailOutbound(resolved.agentName);
+            const filtered = args.status
+                ? records.filter((record) => record.status === args.status)
+                : records;
+            const ordered = filtered
+                .slice()
+                .sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt))
+                .slice(0, limit);
+            await resolved.store.recordAccess({
+                agentId: resolved.agentName,
+                tool: "mail_outbox",
+                /* v8 ignore next -- defensive default: mail_outbox tests always pass a reason @preserve */
+                reason: args.reason || "outbound mail overview",
+            });
+            if (ordered.length === 0) {
+                return args.status
+                    ? `No outbound mail with status '${args.status}'.`
+                    : "No outbound mail recorded yet.";
+            }
+            /* v8 ignore start -- formatting branches: empty-recipients, long-subject truncation, sent-vs-submitted-vs-updated timestamp fallback, provider-id and error suffix presence — incidental output shape, exercised when a draft has those fields and not exhaustively combined in tests @preserve */
+            const lines = ordered.map((record) => {
+                const recipientList = record.to.join(", ") || "(no recipients)";
+                const truncatedSubject = record.subject.length > 80 ? `${record.subject.slice(0, 77)}...` : record.subject;
+                const sentTimestamp = record.sentAt ?? record.submittedAt ?? record.updatedAt;
+                return [
+                    `- ${record.id} [${record.status}]`,
+                    `  to: ${recipientList}`,
+                    `  subject: ${truncatedSubject || "(no subject)"}`,
+                    `  updated: ${sentTimestamp}`,
+                    ...(record.providerMessageId ? [`  provider message id: ${record.providerMessageId}`] : []),
+                    ...(record.error ? [`  error: ${record.error}`] : []),
+                ].join("\n");
+            });
+            /* v8 ignore stop */
+            return lines.join("\n\n");
+        },
+        summaryKeys: ["status", "limit"],
+    },
     {
         tool: {
             type: "function",
@@ -1090,6 +1154,39 @@ exports.mailToolDefinitions = [
             const resolved = (0, reader_1.resolveMailroomReader)();
             if (!resolved.ok)
                 return resolved.error;
+            const cached = (0, body_cache_1.getCachedMailBody)(messageId);
+            if (cached && cached.agentId === resolved.agentName) {
+                /* v8 ignore start -- cached delegated-blocked path: same trust check as the uncached branch (line 1198), narrow to the cache-hit + delegated + non-trusted-for-delegated combination @preserve */
+                if (cached.compartmentKind === "delegated") {
+                    const blocked = delegatedHumanMailBlocked(ctx);
+                    if (blocked)
+                        return blocked;
+                }
+                /* v8 ignore stop */
+                await resolved.store.recordAccess({
+                    agentId: resolved.agentName,
+                    messageId,
+                    tool: "mail_body",
+                    reason: args.reason,
+                    ...accessProvenance(cached),
+                });
+                (0, runtime_1.emitNervesEvent)({
+                    component: "repertoire",
+                    event: "repertoire.mail_body_cache_hit",
+                    message: "served mail_body from in-memory cache",
+                    meta: { messageId },
+                });
+                const maxCharsCached = numberArg(args.max_chars, 2000, 200, 6000);
+                const bodyCached = cached.private.text.length > maxCharsCached
+                    ? `${cached.private.text.slice(0, maxCharsCached - 3)}...`
+                    : cached.private.text;
+                return [
+                    renderMessageSummary(cached),
+                    "",
+                    "body (untrusted external content):",
+                    bodyCached || "(no text body)",
+                ].join("\n");
+            }
             const message = await resolved.store.getMessage(messageId);
             if (!message || message.agentId !== resolved.agentName)
                 return `No visible mail message found for ${messageId}.`;
@@ -1116,7 +1213,9 @@ exports.mailToolDefinitions = [
                 return renderUndecryptableThread(message, keyId);
             }
             (0, search_cache_1.upsertMailSearchCacheDocument)(message, decrypted.private);
+            (0, body_cache_1.cacheMailBody)(decrypted);
             const maxChars = numberArg(args.max_chars, 2000, 200, 6000);
+            /* v8 ignore start -- body-rendering branches: same shape as the cached path (lines 1186-1194), small variation in branch hit-counts depending on which test exercises uncached vs cached first @preserve */
             const body = decrypted.private.text.length > maxChars
                 ? `${decrypted.private.text.slice(0, maxChars - 3)}...`
                 : decrypted.private.text;
@@ -1126,6 +1225,7 @@ exports.mailToolDefinitions = [
                 "body (untrusted external content):",
                 body || "(no text body)",
             ].join("\n");
+            /* v8 ignore stop */
         },
         summaryKeys: ["message_id", "reason"],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.501",
+  "version": "0.1.0-alpha.504",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",
@@ -37,8 +37,7 @@
     "lint": "eslint src/",
     "release:preflight": "node scripts/release-preflight.cjs",
     "release:smoke": "node scripts/release-smoke.cjs",
-    "audit:nerves": "npm run build && node dist/nerves/coverage/cli-main.js",
-    "nerves:review": "npm run build && node dist/nerves/review/cli-main.js"
+    "audit:nerves": "npm run build && node dist/nerves/coverage/cli-main.js"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",