@ouro.bot/cli 0.1.0-alpha.500 → 0.1.0-alpha.502

package/changelog.json

@@ -1,6 +1,22 @@
 {
   "_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.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": [
+        "New `ouro nerves-review` CLI for tailing the agent's nerves ndjson with structured filters. Read-only. Operators previously had to grep raw ndjson by hand to track down something like 'how many heartbeat-recursion-suspected events fired today' or 'show me the last hour of senses warnings'.",
+        "Filters: `--component <substr>`, `--event <substr>`, `--level <level>`, `--since <duration>` (e.g. 5m, 2h, 1d), `--limit <N>`, `--process <name>` (default: daemon), `--agent <name>` (default: current). Output modes: human-readable text (`<time> [<level>] <component>/<event> — <message>`) and `--json` (one parsed object per line for piping to jq).",
+        "Pure `reviewNerveEvents(filePath, filter)` core in `src/nerves/review/core.ts` reads the tail of the ndjson (8 MB cap, walks last 200+ lines) and applies in-memory filters; testable without filesystem mocks beyond a temp file. 12 tests cover all six filter dimensions plus duration parsing edge cases (ms/s/m/h/d, malformed inputs), missing-file handling, and the two CLI flag paths (--help, invalid --since). Wired as `npm run nerves:review -- <flags>` and `dist/nerves/review/cli-main.js`."
+      ]
+    },
     {
       "version": "0.1.0-alpha.500",
       "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/nerves/coverage/file-completeness.js

@@ -120,6 +120,11 @@ const DISPATCH_EXEMPT_PATTERNS = [
     "heart/session-playback-cli-main",
     "heart/session-playback-cli",
     "heart/session-playback",
+    // Nerves review: read-only NDJSON tail/filter CLI for debugging.
+    // Diagnostics-only utility; the running daemon owns observability.
+    "nerves/review/cli-main",
+    "nerves/review/cli",
+    "nerves/review/core",
 ];
 function isDispatchExempt(filePath) {
     return DISPATCH_EXEMPT_PATTERNS.some((pattern) => filePath.includes(pattern));

package/dist/nerves/review/cli-main.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cli_1 = require("./cli");
+const code = (0, cli_1.runNervesReviewCli)(process.argv.slice(2));
+process.exit(code);

package/dist/nerves/review/cli.js

@@ -0,0 +1,156 @@
+"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.runNervesReviewCli = runNervesReviewCli;
+const path = __importStar(require("node:path"));
+const identity_1 = require("../../heart/identity");
+const core_1 = require("./core");
+function parseArgs(argv) {
+    const args = { process: "daemon", json: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        const next = argv[i + 1];
+        switch (token) {
+            case "--help":
+            case "-h":
+                args.help = true;
+                break;
+            case "--process":
+                if (next)
+                    args.process = next;
+                i++;
+                break;
+            case "--agent":
+                if (next)
+                    args.agent = next;
+                i++;
+                break;
+            case "--component":
+                if (next)
+                    args.componentSubstring = next;
+                i++;
+                break;
+            case "--event":
+                if (next)
+                    args.eventSubstring = next;
+                i++;
+                break;
+            case "--level":
+                if (next)
+                    args.level = next;
+                i++;
+                break;
+            case "--since":
+                if (next)
+                    args.since = next;
+                i++;
+                break;
+            case "--limit":
+                if (next) {
+                    const parsed = Number.parseInt(next, 10);
+                    if (Number.isFinite(parsed) && parsed > 0)
+                        args.limit = parsed;
+                }
+                i++;
+                break;
+            case "--json":
+                args.json = true;
+                break;
+        }
+    }
+    return args;
+}
+function printHelp() {
+    // eslint-disable-next-line no-console -- meta-tooling
+    console.log([
+        "usage: ouro nerves-review [options]",
+        "",
+        "Tail the agent's nerves ndjson and filter recent events. Read-only.",
+        "",
+        "options:",
+        "  --process <name>      log stream to read (default: daemon)",
+        "  --agent <name>        agent bundle to read from (default: current)",
+        "  --component <substr>  filter by component substring (case-insensitive)",
+        "  --event <substr>      filter by event-name substring (case-insensitive)",
+        "  --level <level>       filter by exact level (debug|info|warn|error)",
+        "  --since <duration>    only events newer than e.g. 5m, 2h, 1d",
+        "  --limit <N>           cap returned events (default: 50)",
+        "  --json                output one JSON object per line",
+    ].join("\n"));
+}
+function runNervesReviewCli(argv) {
+    const args = parseArgs(argv);
+    if (args.help) {
+        printHelp();
+        return 0;
+    }
+    let sinceMs;
+    if (args.since) {
+        const parsed = (0, core_1.parseDuration)(args.since);
+        if (parsed === null) {
+            // eslint-disable-next-line no-console -- meta-tooling
+            console.error(`nerves-review: --since '${args.since}' is not a valid duration (e.g. 5m, 2h, 1d)`);
+            return 2;
+        }
+        sinceMs = parsed;
+    }
+    const logsDir = (0, identity_1.getAgentDaemonLogsDir)(args.agent);
+    const filePath = path.join(logsDir, `${args.process}.ndjson`);
+    const filter = {
+        componentSubstring: args.componentSubstring,
+        eventSubstring: args.eventSubstring,
+        level: args.level,
+        sinceMs,
+        limit: args.limit,
+        nowMs: Date.now(),
+    };
+    const entries = (0, core_1.reviewNerveEvents)(filePath, filter);
+    if (entries.length === 0) {
+        // eslint-disable-next-line no-console -- meta-tooling
+        console.log(`(no matching nerves events in ${filePath})`);
+        return 0;
+    }
+    for (const entry of entries) {
+        if (args.json) {
+            // eslint-disable-next-line no-console -- meta-tooling
+            console.log(entry.raw);
+        }
+        else {
+            // eslint-disable-next-line no-console -- meta-tooling
+            console.log((0, core_1.formatNerveEntry)(entry));
+        }
+    }
+    return 0;
+}

package/dist/nerves/review/core.js

@@ -0,0 +1,152 @@
+"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.parseDuration = parseDuration;
+exports.reviewNerveEvents = reviewNerveEvents;
+exports.formatNerveEntry = formatNerveEntry;
+const fs = __importStar(require("node:fs"));
+const DURATION_PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/;
+function parseDuration(value) {
+    const match = DURATION_PATTERN.exec(value.trim().toLowerCase());
+    if (!match)
+        return null;
+    const amount = Number.parseFloat(match[1]);
+    if (!Number.isFinite(amount) || amount < 0)
+        return null;
+    switch (match[2]) {
+        case "ms": return amount;
+        case "s": return amount * 1_000;
+        case "m": return amount * 60_000;
+        case "h": return amount * 3_600_000;
+        case "d": return amount * 86_400_000;
+        /* v8 ignore start -- exhaustive switch over the regex group; unreachable */
+        default: return null;
+        /* v8 ignore stop */
+    }
+}
+function entryTimeMs(parsed) {
+    if (!parsed)
+        return null;
+    const time = parsed.time;
+    if (typeof time === "string") {
+        const ms = Date.parse(time);
+        return Number.isFinite(ms) ? ms : null;
+    }
+    return null;
+}
+function readLastNLines(filePath, maxLines, maxBytes = 8 * 1024 * 1024) {
+    let text;
+    try {
+        const stat = fs.statSync(filePath);
+        if (stat.size > maxBytes) {
+            const fd = fs.openSync(filePath, "r");
+            try {
+                const buf = Buffer.alloc(maxBytes);
+                fs.readSync(fd, buf, 0, maxBytes, stat.size - maxBytes);
+                text = buf.toString("utf-8");
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        else {
+            text = fs.readFileSync(filePath, "utf-8");
+        }
+    }
+    catch {
+        return [];
+    }
+    const lines = text.split("\n").filter((line) => line.length > 0);
+    return lines.slice(-maxLines);
+}
+function reviewNerveEvents(filePath, filter = {}) {
+    const limit = filter.limit ?? 50;
+    const candidateLineCount = Math.max(limit * 4, 200);
+    const lines = readLastNLines(filePath, candidateLineCount);
+    const cutoffMs = filter.sinceMs !== undefined && filter.nowMs !== undefined
+        ? filter.nowMs - filter.sinceMs
+        : null;
+    const matched = [];
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const raw = lines[i];
+        let parsed = null;
+        try {
+            const value = JSON.parse(raw);
+            if (value && typeof value === "object" && !Array.isArray(value)) {
+                parsed = value;
+            }
+        }
+        catch {
+            parsed = null;
+        }
+        if (!parsed)
+            continue;
+        if (filter.componentSubstring) {
+            const component = String(parsed.component ?? "");
+            if (!component.toLowerCase().includes(filter.componentSubstring.toLowerCase()))
+                continue;
+        }
+        if (filter.eventSubstring) {
+            const event = String(parsed.event ?? "");
+            if (!event.toLowerCase().includes(filter.eventSubstring.toLowerCase()))
+                continue;
+        }
+        if (filter.level) {
+            const level = String(parsed.level ?? "info");
+            if (level !== filter.level)
+                continue;
+        }
+        if (cutoffMs !== null) {
+            const eventMs = entryTimeMs(parsed);
+            if (eventMs === null || eventMs < cutoffMs)
+                continue;
+        }
+        matched.push({ raw, parsed });
+        if (matched.length >= limit)
+            break;
+    }
+    return matched.reverse();
+}
+function formatNerveEntry(entry) {
+    const parsed = entry.parsed;
+    if (!parsed)
+        return entry.raw;
+    const time = String(parsed.time ?? "");
+    const level = String(parsed.level ?? "info");
+    const component = String(parsed.component ?? "?");
+    const event = String(parsed.event ?? "?");
+    const message = String(parsed.message ?? "");
+    return `${time} [${level.padEnd(5)}] ${component}/${event} — ${message}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.500",
+  "version": "0.1.0-alpha.502",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",