@ouro.bot/cli 0.1.0-alpha.321 → 0.1.0-alpha.322

package/changelog.json

@@ -1,6 +1,13 @@
 {
   "_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.322",
+      "changes": [
+        "fix(bluebubbles): share BlueBubbles health diagnostics between runtime status and doctor so fetch, malformed URL, auth, and upstream server failures produce actionable repair guidance instead of a bare `fetch failed`.",
+        "fix(doctor): actively probe enabled BlueBubbles upstreams, validate `bluebubbles.serverUrl` and `bluebubbles.password`, and report exactly whether config, reachability, auth, or upstream health needs repair."
+      ]
+    },
     {
       "version": "0.1.0-alpha.321",
       "changes": [

package/dist/heart/daemon/bluebubbles-health-diagnostics.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stringifyBlueBubblesHealthError = stringifyBlueBubblesHealthError;
+exports.redactBlueBubblesHealthDetailForNerves = redactBlueBubblesHealthDetailForNerves;
+exports.formatBlueBubblesHealthcheckFailure = formatBlueBubblesHealthcheckFailure;
+exports.probeBlueBubblesHealth = probeBlueBubblesHealth;
+const runtime_1 = require("../../nerves/runtime");
+const error_classification_1 = require("../providers/error-classification");
+function buildBlueBubblesApiUrl(baseUrl, endpoint, password) {
+    const root = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    const url = new URL(endpoint.replace(/^\//, ""), root);
+    url.searchParams.set("password", password);
+    return url.toString();
+}
+function stringifyBlueBubblesHealthError(error) {
+    if (error instanceof Error) {
+        const message = error.message.trim();
+        if (message)
+            return message;
+        return error.name || "unknown";
+    }
+    const value = String(error).trim();
+    return value || "unknown";
+}
+function redactBlueBubblesHealthDetailForNerves(detail) {
+    return detail
+        .replace(/\bbluebubbles\.password\b/gi, "bluebubbles credential")
+        .replace(/\bpassword\b/gi, "credential");
+}
+function blueBubblesHealthStatus(error) {
+    return error instanceof Error && typeof error.status === "number"
+        ? error.status
+        : null;
+}
+function blueBubblesHealthClassification(error) {
+    return error instanceof Error ? (0, error_classification_1.classifyHttpError)(error) : "unknown";
+}
+function formatBlueBubblesHealthcheckFailure(serverUrlInput, error) {
+    const serverUrl = serverUrlInput.trim() || "configured BlueBubbles server";
+    const rawReason = stringifyBlueBubblesHealthError(error);
+    const status = blueBubblesHealthStatus(error);
+    if (!(error instanceof Error)) {
+        return `BlueBubbles health check failed at ${serverUrl}. Check \`bluebubbles.serverUrl\`, confirm the BlueBubbles app/API is running, and inspect daemon logs. Raw error: ${rawReason}`;
+    }
+    switch (blueBubblesHealthClassification(error)) {
+        case "network-error":
+            return `Cannot reach BlueBubbles at ${serverUrl}. Check \`bluebubbles.serverUrl\`, confirm the BlueBubbles app/API is running, and verify this machine can reach it. Raw error: ${rawReason}`;
+        case "auth-failure":
+            return `BlueBubbles auth failed at ${serverUrl} (HTTP ${status}). Check \`bluebubbles.password\` in secrets.json and confirm the server accepts it. Raw error: ${rawReason}`;
+        case "server-error":
+            return `BlueBubbles upstream returned HTTP ${status} at ${serverUrl}. Check the BlueBubbles app/server logs and confirm the upstream API is healthy. Raw error: ${rawReason}`;
+        default:
+            return `BlueBubbles health check failed at ${serverUrl}${status === null ? "" : ` (HTTP ${status})`}. Check \`bluebubbles.serverUrl\`, the BlueBubbles server configuration, and daemon logs. Raw error: ${rawReason}`;
+    }
+}
+async function probeBlueBubblesHealth(input) {
+    try {
+        const url = buildBlueBubblesApiUrl(input.serverUrl, "/api/v1/message/count", input.password);
+        const response = await input.fetchImpl(url, {
+            method: "GET",
+            signal: AbortSignal.timeout(input.requestTimeoutMs),
+        });
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => "");
+            const error = new Error(errorText || "unknown");
+            error.status = response.status;
+            throw error;
+        }
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.bluebubbles_health_probe_checked",
+            message: "checked bluebubbles upstream health",
+            meta: {
+                serverUrl: input.serverUrl,
+                ok: true,
+                status: response.status,
+            },
+        });
+        return {
+            ok: true,
+            detail: "upstream reachable",
+            reason: null,
+            status: response.status,
+            classification: null,
+        };
+    }
+    catch (error) {
+        const detail = formatBlueBubblesHealthcheckFailure(input.serverUrl, error);
+        const reason = stringifyBlueBubblesHealthError(error);
+        const status = blueBubblesHealthStatus(error);
+        const classification = blueBubblesHealthClassification(error);
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.bluebubbles_health_probe_checked",
+            message: "checked bluebubbles upstream health",
+            meta: {
+                serverUrl: input.serverUrl,
+                ok: false,
+                status,
+                reason,
+                classification,
+                detail: redactBlueBubblesHealthDetailForNerves(detail),
+            },
+        });
+        return {
+            ok: false,
+            detail,
+            reason,
+            status,
+            classification,
+        };
+    }
+}
+/* v8 ignore start -- module load observability event */
+(0, runtime_1.emitNervesEvent)({
+    component: "daemon",
+    event: "daemon.bluebubbles_health_diagnostics_loaded",
+    message: "bluebubbles health diagnostics loaded",
+    meta: {},
+});
+/* v8 ignore stop */

package/dist/heart/daemon/cli-exec.js

@@ -2189,6 +2189,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             statSync: (p) => fs.statSync(p),
             /* v8 ignore stop */
             checkSocketAlive: deps.checkSocketAlive,
+            fetchImpl: deps.fetchImpl ?? fetch,
             socketPath: deps.socketPath,
             bundlesRoot: deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)(),
             secretsRoot: deps.secretsRoot ?? path.join(os.homedir(), ".agentsecrets"),

package/dist/heart/daemon/doctor.js

@@ -15,6 +15,8 @@ exports.checkSecurity = checkSecurity;
 exports.checkDisk = checkDisk;
 exports.runDoctorChecks = runDoctorChecks;
 const runtime_1 = require("../../nerves/runtime");
+const bluebubbles_health_diagnostics_1 = require("./bluebubbles-health-diagnostics");
+const DEFAULT_BLUEBUBBLES_REQUEST_TIMEOUT_MS = 30_000;
 // ── Category checkers ──
 async function checkDaemon(deps) {
     const checks = [];
@@ -47,6 +49,27 @@ function discoverAgents(deps) {
         return [];
     return deps.readdirSync(deps.bundlesRoot).filter((name) => name.endsWith(".ouro"));
 }
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function textField(record, key) {
+    const value = record?.[key];
+    return typeof value === "string" ? value.trim() : "";
+}
+function numberField(record, key, fallback) {
+    const value = record?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function readJsonObject(deps, filePath) {
+    try {
+        return asRecord(JSON.parse(deps.readFileSync(filePath)));
+    }
+    catch {
+        return null;
+    }
+}
 function checkAgents(deps) {
     const checks = [];
     if (!deps.existsSync(deps.bundlesRoot)) {
@@ -105,10 +128,11 @@ function checkAgents(deps) {
     }
     return { name: "Agents", checks };
 }
-function checkSenses(deps) {
+async function checkSenses(deps) {
     const checks = [];
     const agents = discoverAgents(deps);
     for (const agentDir of agents) {
+        const agentName = agentDir.replace(/\.ouro$/, "");
         const configPath = `${deps.bundlesRoot}/${agentDir}/agent.json`;
         if (!deps.existsSync(configPath))
             continue;
@@ -145,6 +169,61 @@ function checkSenses(deps) {
                     detail: senseObj.enabled ? "enabled" : "disabled",
                 });
             }
+            if (sense === "bluebubbles" && senseObj.enabled === true) {
+                const secretsPath = `${deps.secretsRoot}/${agentName}/secrets.json`;
+                if (!deps.existsSync(secretsPath)) {
+                    checks.push({
+                        label: `${agentDir} bluebubbles config`,
+                        status: "fail",
+                        detail: "missing secrets.json",
+                    });
+                    continue;
+                }
+                const secrets = readJsonObject(deps, secretsPath);
+                if (!secrets) {
+                    checks.push({
+                        label: `${agentDir} bluebubbles config`,
+                        status: "fail",
+                        detail: "secrets.json unparseable",
+                    });
+                    continue;
+                }
+                const bluebubbles = asRecord(secrets.bluebubbles);
+                const bluebubblesChannel = asRecord(secrets.bluebubblesChannel);
+                const serverUrl = textField(bluebubbles, "serverUrl");
+                const password = textField(bluebubbles, "password");
+                const missing = [];
+                if (!serverUrl)
+                    missing.push("bluebubbles.serverUrl");
+                if (!password)
+                    missing.push("bluebubbles.password");
+                if (missing.length > 0) {
+                    checks.push({
+                        label: `${agentDir} bluebubbles config`,
+                        status: "fail",
+                        detail: `missing ${missing.join("/")}`,
+                    });
+                    continue;
+                }
+                checks.push({
+                    label: `${agentDir} bluebubbles config`,
+                    status: "pass",
+                    detail: serverUrl,
+                });
+                if (deps.fetchImpl) {
+                    const probe = await (0, bluebubbles_health_diagnostics_1.probeBlueBubblesHealth)({
+                        serverUrl,
+                        password,
+                        requestTimeoutMs: numberField(bluebubblesChannel, "requestTimeoutMs", DEFAULT_BLUEBUBBLES_REQUEST_TIMEOUT_MS),
+                        fetchImpl: deps.fetchImpl,
+                    });
+                    checks.push({
+                        label: `${agentDir} bluebubbles upstream`,
+                        status: probe.ok ? "pass" : "fail",
+                        detail: probe.detail,
+                    });
+                }
+            }
         }
     }
     if (checks.length === 0) {

package/dist/senses/bluebubbles/client.js

@@ -4,6 +4,7 @@ exports.createBlueBubblesClient = createBlueBubblesClient;
 const node_crypto_1 = require("node:crypto");
 const config_1 = require("../../heart/config");
 const identity_1 = require("../../heart/identity");
+const bluebubbles_health_diagnostics_1 = require("../../heart/daemon/bluebubbles-health-diagnostics");
 const runtime_1 = require("../../nerves/runtime");
 const minimax_1 = require("../../heart/providers/minimax");
 const minimax_vlm_1 = require("../../heart/providers/minimax-vlm");
@@ -332,19 +333,19 @@ function createBlueBubblesClient(config = (0, config_1.getBlueBubblesConfig)(),
             }
         },
         async checkHealth() {
-            const url = buildBlueBubblesApiUrl(config.serverUrl, "/api/v1/message/count", config.password);
             (0, runtime_1.emitNervesEvent)({
                 component: "senses",
                 event: "senses.bluebubbles_healthcheck_start",
                 message: "probing bluebubbles upstream health",
                 meta: { serverUrl: config.serverUrl },
             });
-            const response = await fetch(url, {
-                method: "GET",
-                signal: AbortSignal.timeout(channelConfig.requestTimeoutMs),
+            const result = await (0, bluebubbles_health_diagnostics_1.probeBlueBubblesHealth)({
+                serverUrl: config.serverUrl,
+                password: config.password,
+                requestTimeoutMs: channelConfig.requestTimeoutMs,
+                fetchImpl: fetch,
             });
-            if (!response.ok) {
-                const errorText = await response.text().catch(() => "");
+            if (!result.ok) {
                 (0, runtime_1.emitNervesEvent)({
                     level: "warn",
                     component: "senses",
@@ -352,11 +353,13 @@ function createBlueBubblesClient(config = (0, config_1.getBlueBubblesConfig)(),
                     message: "bluebubbles upstream health probe failed",
                     meta: {
                         serverUrl: config.serverUrl,
-                        status: response.status,
-                        reason: errorText || "unknown",
+                        status: result.status,
+                        reason: result.reason,
+                        classification: result.classification,
+                        detail: (0, bluebubbles_health_diagnostics_1.redactBlueBubblesHealthDetailForNerves)(result.detail),
                     },
                 });
-                throw new Error(`BlueBubbles upstream health check failed (${response.status}): ${errorText || "unknown"}`);
+                throw new Error(result.detail);
             }
             (0, runtime_1.emitNervesEvent)({
                 component: "senses",

package/package.json

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