@ouro.bot/cli 0.1.0-alpha.152 → 0.1.0-alpha.154

package/changelog.json

@@ -1,6 +1,29 @@
 {
   "_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.154",
+      "changes": [
+        "feat: clean tool status messages \u2014 human-readable by default, /debug toggle",
+        "humanReadableToolDescription derives from tool name+args, not hardcoded map",
+        "Shared tool activity callbacks (DRY) \u2014 senses only provide render function",
+        "Slash command handling moved to pipeline \u2014 all senses get /debug for free",
+        "BlueBubbles: one clean iMessage per tool, not raw shared work: processing"
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.153",
+      "changes": [
+        "Daemon health file: DaemonHealthWriter writes atomic daemon-health.json on every state change. readHealth() standalone reader for CLI and agent processes.",
+        "Nerves event buffer: createBufferedSink wraps sinks with bounded ring buffer (1000 events), auto-flushes on recovery, TTL discards after 5 min of unhealthy sink.",
+        "Cron verification + timer fallback: after cron sync, verifyCronEntries checks launchctl/crontab for registered habits. Unverified habits get in-process setTimeout fallback. getDegradedHabits() for health reporting.",
+        "Periodic reconciliation: 30s initial delay then 5-minute setTimeout chain re-scans habits and re-verifies cron entries.",
+        "Safe mode: detectSafeMode reads crash history (recentCrashes in tombstone). 3+ crashes in 5 minutes triggers safe mode - daemon stays alive, socket works, agents/habits paused. ouro up --force writes override file.",
+        "Health nerves sink: createHealthNervesSink registers as global sink, listens for daemon events (agent_started, agent_exit, habit_fire, safe_mode_entered, etc.), triggers debounced health writes.",
+        "ouro status health fallback: when daemon socket is unreachable, reads health file to show last-known status, safe mode, and degraded components.",
+        "Degraded state in agent dialog: habit turns read daemon-health.json and append scheduling degradation nudge when components are degraded."
+      ]
+    },
     {
       "version": "0.1.0-alpha.152",
       "changes": [

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

@@ -72,6 +72,7 @@ const ouro_bot_global_installer_1 = require("./ouro-bot-global-installer");
 const launchd_1 = require("./launchd");
 const socket_client_1 = require("./socket-client");
 const daemon_tombstone_1 = require("./daemon-tombstone");
+const daemon_health_1 = require("./daemon-health");
 const session_activity_1 = require("../session-activity");
 const auth_flow_1 = require("./auth-flow");
 function stringField(value) {
@@ -350,7 +351,7 @@ function buildStoppedStatusPayload(socketPath) {
         workers: [],
     };
 }
-function daemonUnavailableStatusOutput(socketPath) {
+function daemonUnavailableStatusOutput(socketPath, healthFilePath) {
     /* v8 ignore start — tombstone read tested in daemon-status-tombstone.test; branch misreported @preserve */
     const tombstone = (0, daemon_tombstone_1.readDaemonTombstone)();
     const deathLine = tombstone
@@ -371,6 +372,23 @@ function daemonUnavailableStatusOutput(socketPath) {
         lines.push("");
         /* v8 ignore stop */
     }
+    // Read health file for last-known state (best-effort)
+    const resolvedHealthPath = healthFilePath ?? (0, daemon_health_1.getDefaultHealthPath)();
+    const health = (0, daemon_health_1.readHealth)(resolvedHealthPath);
+    if (health) {
+        lines.push(`Last known status: ${health.status} (pid ${health.pid}, uptime ${health.uptimeSeconds}s)`);
+        if (health.safeMode?.active) {
+            lines.push(`SAFE MODE: ${health.safeMode.reason}`);
+        }
+        if (health.degraded.length > 0) {
+            lines.push("");
+            lines.push("Degraded:");
+            for (const d of health.degraded) {
+                lines.push(`  ${d.component}: ${d.reason} (since ${d.since})`);
+            }
+        }
+        lines.push("");
+    }
     lines.push("daemon not running; run `ouro up`");
     return lines.join("\n");
 }
@@ -3128,7 +3146,7 @@ async function runOuroCli(args, deps = createDefaultOuroCliDeps()) {
             return message;
         }
         if (command.kind === "daemon.status" && isDaemonUnavailableError(error)) {
-            const message = daemonUnavailableStatusOutput(deps.socketPath);
+            const message = daemonUnavailableStatusOutput(deps.socketPath, deps.healthFilePath);
             deps.writeStdout(message);
             return message;
         }

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

@@ -0,0 +1,136 @@
+"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.HEALTH_TRACKED_EVENTS = exports.DaemonHealthWriter = void 0;
+exports.getDefaultHealthPath = getDefaultHealthPath;
+exports.createHealthNervesSink = createHealthNervesSink;
+exports.readHealth = readHealth;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../../nerves/runtime");
+class DaemonHealthWriter {
+    healthPath;
+    constructor(healthPath) {
+        this.healthPath = healthPath;
+    }
+    writeHealth(state) {
+        try {
+            const dir = path.dirname(this.healthPath);
+            fs.mkdirSync(dir, { recursive: true });
+            const tmpPath = `${this.healthPath}.tmp.${process.pid}`;
+            fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2) + "\n", "utf-8");
+            fs.renameSync(tmpPath, this.healthPath);
+            (0, runtime_1.emitNervesEvent)({
+                component: "daemon",
+                event: "daemon.health_written",
+                message: "daemon health file written",
+                meta: { path: this.healthPath, status: state.status },
+            });
+        }
+        catch {
+            // Best-effort: if we can't write, don't crash the daemon.
+        }
+    }
+}
+exports.DaemonHealthWriter = DaemonHealthWriter;
+function getDefaultHealthPath() {
+    return path.join(os.homedir(), ".ouro-cli", "daemon-health.json");
+}
+/** Events that trigger a debounced health file write */
+exports.HEALTH_TRACKED_EVENTS = new Set([
+    "daemon.habit_cron_verification_failed",
+    "daemon.habit_fire",
+    "daemon.agent_exit",
+    "daemon.agent_started",
+    "daemon.agent_restart_exhausted",
+    "daemon.agent_permanent_failure",
+    "daemon.agent_cooldown_recovery",
+    "daemon.safe_mode_entered",
+    "daemon.habit_scheduler_start",
+]);
+/**
+ * Creates a nerves LogSink that triggers debounced health writes on relevant events.
+ * Components don't know about the health writer — they just emit events.
+ */
+function createHealthNervesSink(writer, getState) {
+    let debounceTimer = null;
+    return (entry) => {
+        if (!exports.HEALTH_TRACKED_EVENTS.has(entry.event)) {
+            return;
+        }
+        // Debounce: max once per second
+        if (debounceTimer !== null) {
+            clearTimeout(debounceTimer);
+        }
+        debounceTimer = setTimeout(() => {
+            debounceTimer = null;
+            const state = getState();
+            writer.writeHealth(state);
+        }, 1000);
+    };
+}
+function readHealth(healthPath) {
+    try {
+        const raw = fs.readFileSync(healthPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.status !== "string" ||
+            typeof parsed.mode !== "string" ||
+            typeof parsed.pid !== "number" ||
+            typeof parsed.startedAt !== "string" ||
+            typeof parsed.uptimeSeconds !== "number" ||
+            !Array.isArray(parsed.degraded) ||
+            typeof parsed.agents !== "object" ||
+            parsed.agents === null ||
+            typeof parsed.habits !== "object" ||
+            parsed.habits === null) {
+            return null;
+        }
+        return {
+            status: parsed.status,
+            mode: parsed.mode,
+            pid: parsed.pid,
+            startedAt: parsed.startedAt,
+            uptimeSeconds: parsed.uptimeSeconds,
+            safeMode: parsed.safeMode,
+            degraded: parsed.degraded,
+            agents: parsed.agents,
+            habits: parsed.habits,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/heart/daemon/daemon-tombstone.js

@@ -53,15 +53,29 @@ function setTombstonePath(p) {
     _tombstonePath = p;
 }
 function writeDaemonTombstone(reason, error) {
+    const now = new Date().toISOString();
+    const filePath = getTombstonePath();
+    // Read existing recentCrashes from previous tombstone (best-effort)
+    let existingCrashes = [];
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const existing = JSON.parse(raw);
+        if (Array.isArray(existing.recentCrashes)) {
+            existingCrashes = existing.recentCrashes.filter((entry) => typeof entry === "string");
+        }
+    }
+    catch {
+        // No existing tombstone or unreadable — start fresh
+    }
     const tombstone = {
         reason,
         message: error?.message ?? reason,
         stack: error?.stack ?? null,
-        timestamp: new Date().toISOString(),
+        timestamp: now,
         pid: process.pid,
         uptimeSeconds: Math.floor(process.uptime()),
+        recentCrashes: [...existingCrashes, now],
     };
-    const filePath = getTombstonePath();
     try {
         fs.mkdirSync(path.dirname(filePath), { recursive: true });
         fs.writeFileSync(filePath, JSON.stringify(tombstone, null, 2) + "\n", "utf-8");
@@ -98,6 +112,9 @@ function readDaemonTombstone() {
             timestamp: parsed.timestamp,
             pid: typeof parsed.pid === "number" ? parsed.pid : 0,
             uptimeSeconds: typeof parsed.uptimeSeconds === "number" ? parsed.uptimeSeconds : 0,
+            recentCrashes: Array.isArray(parsed.recentCrashes)
+                ? parsed.recentCrashes.filter((e) => typeof e === "string")
+                : [],
         };
     }
     catch {

package/dist/heart/daemon/habit-scheduler.js

@@ -45,15 +45,22 @@ class HabitScheduler {
     osCronManager;
     onHabitFire;
     deps;
+    execForVerify;
+    platform;
     watcher = null;
     debounceTimer = null;
     parseErrors = [];
+    timerFallbacks = new Map();
+    degradedHabitNames = new Map();
+    periodicTimer = null;
     constructor(options) {
         this.agent = options.agent;
         this.habitsDir = options.habitsDir;
         this.osCronManager = options.osCronManager;
         this.onHabitFire = options.onHabitFire;
         this.deps = options.deps;
+        this.execForVerify = options.execForVerify;
+        this.platform = options.platform ?? process.platform;
     }
     start() {
         (0, runtime_1.emitNervesEvent)({
@@ -65,6 +72,7 @@ class HabitScheduler {
         const habits = this.scanHabits();
         const jobs = this.buildJobs(habits);
         this.osCronManager.sync(jobs);
+        this.verifyCronAndCreateFallbacks(jobs);
         // Fire overdue habits immediately
         for (const habit of habits) {
             if (habit.status !== "active")
@@ -105,9 +113,12 @@ class HabitScheduler {
             message: "habit scheduler reconciling",
             meta: { agent: this.agent },
         });
+        // Clear ALL existing timers FIRST to prevent overlap window
+        this.clearAllTimerFallbacks();
         const habits = this.scanHabits();
         const jobs = this.buildJobs(habits);
         this.osCronManager.sync(jobs);
+        this.verifyCronAndCreateFallbacks(jobs);
     }
     stop() {
         (0, runtime_1.emitNervesEvent)({
@@ -116,6 +127,8 @@ class HabitScheduler {
             message: "habit scheduler stopping",
             meta: { agent: this.agent },
         });
+        this.stopPeriodicReconciliation();
+        this.clearAllTimerFallbacks();
         this.osCronManager.removeAll();
     }
     listOverdueHabits() {
@@ -187,6 +200,107 @@ class HabitScheduler {
             this.watcher = null;
         }
     }
+    getDegradedHabits() {
+        const result = [];
+        for (const [name, reason] of this.degradedHabitNames) {
+            result.push({ name, reason });
+        }
+        return result;
+    }
+    static DEFAULT_PERIODIC_INTERVAL_MS = 300_000; // 5 minutes
+    static INITIAL_RECONCILIATION_DELAY_MS = 30_000; // 30 seconds
+    startPeriodicReconciliation(intervalMs) {
+        const interval = intervalMs ?? HabitScheduler.DEFAULT_PERIODIC_INTERVAL_MS;
+        // First reconciliation after a short delay (30s)
+        this.periodicTimer = setTimeout(() => {
+            this.reconcile();
+            this.scheduleNextReconciliation(interval);
+        }, HabitScheduler.INITIAL_RECONCILIATION_DELAY_MS);
+    }
+    stopPeriodicReconciliation() {
+        if (this.periodicTimer !== null) {
+            clearTimeout(this.periodicTimer);
+            this.periodicTimer = null;
+        }
+    }
+    scheduleNextReconciliation(intervalMs) {
+        this.periodicTimer = setTimeout(() => {
+            this.reconcile();
+            this.scheduleNextReconciliation(intervalMs);
+        }, intervalMs);
+    }
+    verifyCronAndCreateFallbacks(jobs) {
+        if (!this.execForVerify)
+            return;
+        const verifiedLabels = this.verifyCronEntries();
+        for (const job of jobs) {
+            const label = `bot.ouro.${job.agent}.${job.taskId}`;
+            const isVerified = this.platform === "darwin"
+                ? verifiedLabels.has(label)
+                : verifiedLabels.has(job.taskId);
+            if (!isVerified) {
+                (0, runtime_1.emitNervesEvent)({
+                    component: "daemon",
+                    event: "daemon.habit_cron_verification_failed",
+                    message: `cron verification failed for habit: ${job.taskId}`,
+                    meta: { habitName: job.taskId, agent: job.agent, label },
+                });
+                // Parse cadence from the original habit file for timer interval
+                const habitFile = this.getHabitFile(job.taskId);
+                const ms = habitFile?.cadence ? (0, cadence_1.parseCadenceToMs)(habitFile.cadence) : null;
+                if (ms !== null) {
+                    this.createTimerFallback(job.taskId, ms);
+                }
+                this.degradedHabitNames.set(job.taskId, "cron registration failed — using timer fallback");
+            }
+        }
+    }
+    verifyCronEntries() {
+        const verified = new Set();
+        try {
+            if (this.platform === "darwin") {
+                const output = this.execForVerify("launchctl list");
+                const lines = output.split("\n");
+                for (const line of lines) {
+                    const match = line.match(/bot\.ouro\.\S+\.\S+/);
+                    if (match) {
+                        verified.add(match[0]);
+                    }
+                }
+            }
+            else {
+                const output = this.execForVerify("crontab -l");
+                const lines = output.split("\n");
+                for (const line of lines) {
+                    const match = line.match(/ouro poke \S+ --habit (\S+)/);
+                    if (match) {
+                        verified.add(match[1]);
+                    }
+                }
+            }
+        }
+        catch {
+            // Verification command failed — return empty set (all habits unverified)
+        }
+        return verified;
+    }
+    createTimerFallback(habitName, cadenceMs) {
+        const schedule = () => {
+            const timer = setTimeout(() => {
+                this.onHabitFire(habitName);
+                schedule();
+            }, cadenceMs);
+            this.timerFallbacks.set(habitName, timer);
+        };
+        schedule();
+    }
+    clearAllTimerFallbacks() {
+        for (const timer of this.timerFallbacks.values()) {
+            clearTimeout(timer);
+        }
+        this.timerFallbacks.clear();
+        this.degradedHabitNames.clear();
+    }
     scanHabits() {
         let files;
         try {

package/dist/heart/daemon/safe-mode.js

@@ -0,0 +1,161 @@
+"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.SAFE_MODE_OVERRIDE_FILENAME = void 0;
+exports.detectSafeMode = detectSafeMode;
+exports.pruneOldCrashes = pruneOldCrashes;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../../nerves/runtime");
+exports.SAFE_MODE_OVERRIDE_FILENAME = "safe-mode-override.json";
+/** 3+ crashes within this window triggers safe mode */
+const CRASH_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
+const CRASH_THRESHOLD = 3;
+/**
+ * Reads crash history from the tombstone file and determines if safe mode should be active.
+ * Returns active if 3+ crashes occurred within 5 minutes.
+ *
+ * Safe mode is bypassed when:
+ * - devMode is true
+ * - A safe-mode override file exists (written by `ouro up --force`)
+ */
+function detectSafeMode(tombstonePath, options) {
+    const inactive = { active: false, reason: "", enteredAt: "" };
+    // Dev mode: never enter safe mode
+    if (options?.devMode) {
+        return inactive;
+    }
+    // Check for override file (--force)
+    const overridePath = path.join(path.dirname(tombstonePath), exports.SAFE_MODE_OVERRIDE_FILENAME);
+    try {
+        if (fs.existsSync(overridePath)) {
+            return inactive;
+        }
+    }
+    catch {
+        // Best-effort check
+    }
+    // Read tombstone
+    let parsed;
+    try {
+        const raw = fs.readFileSync(tombstonePath, "utf-8");
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return inactive;
+    }
+    // Extract recentCrashes
+    if (!Array.isArray(parsed.recentCrashes)) {
+        return inactive;
+    }
+    const nowMs = options?.now ? options.now() : Date.now();
+    const windowStart = nowMs - CRASH_WINDOW_MS;
+    // Filter to valid string timestamps within the crash window
+    const recentInWindow = parsed.recentCrashes.filter((entry) => {
+        if (typeof entry !== "string")
+            return false;
+        const ts = new Date(entry).getTime();
+        if (isNaN(ts))
+            return false;
+        return ts >= windowStart;
+    });
+    if (recentInWindow.length < CRASH_THRESHOLD) {
+        return inactive;
+    }
+    const result = {
+        active: true,
+        reason: `crash loop detected: ${recentInWindow.length} crashes in last 5 minutes`,
+        enteredAt: new Date(nowMs).toISOString(),
+    };
+    (0, runtime_1.emitNervesEvent)({
+        level: "error",
+        component: "daemon",
+        event: "daemon.safe_mode_entered",
+        message: result.reason,
+        meta: {
+            crashCount: recentInWindow.length,
+            windowMs: CRASH_WINDOW_MS,
+            tombstonePath,
+        },
+    });
+    return result;
+}
+/**
+ * Prunes crash entries older than 5 minutes from the tombstone's recentCrashes.
+ * Also removes the safe-mode override file if present.
+ * Called after successful startup (uptime > stability threshold).
+ */
+function pruneOldCrashes(tombstonePath, options) {
+    // Remove override file
+    const overridePath = path.join(path.dirname(tombstonePath), exports.SAFE_MODE_OVERRIDE_FILENAME);
+    try {
+        if (fs.existsSync(overridePath)) {
+            fs.unlinkSync(overridePath);
+        }
+    }
+    catch {
+        // Best-effort
+    }
+    // Read existing tombstone
+    let parsed;
+    try {
+        const raw = fs.readFileSync(tombstonePath, "utf-8");
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    if (!Array.isArray(parsed.recentCrashes)) {
+        return;
+    }
+    const nowMs = options?.now ? options.now() : Date.now();
+    const windowStart = nowMs - CRASH_WINDOW_MS;
+    // Keep only entries within the window
+    const pruned = parsed.recentCrashes.filter((entry) => {
+        if (typeof entry !== "string")
+            return false;
+        const ts = new Date(entry).getTime();
+        if (isNaN(ts))
+            return false;
+        return ts >= windowStart;
+    });
+    parsed.recentCrashes = pruned;
+    try {
+        fs.writeFileSync(tombstonePath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+    }
+    catch {
+        // Best-effort
+    }
+}

package/dist/heart/tool-activity-callbacks.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolActivityCallbacks = createToolActivityCallbacks;
+const tool_description_1 = require("./tool-description");
+const runtime_1 = require("../nerves/runtime");
+function createToolActivityCallbacks(options) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.tool_activity_callbacks_created",
+        message: "tool activity callbacks initialized",
+        meta: { isDebug: options.isDebug },
+    });
+    return {
+        onToolStart(name, args) {
+            const description = (0, tool_description_1.humanReadableToolDescription)(name, args);
+            if (description === null)
+                return; // hidden tool (settle, rest)
+            options.onDescription(description);
+        },
+        onToolEnd(name, summary, success) {
+            if (!success) {
+                options.onFailure(`${name} failed: ${summary}`);
+                return;
+            }
+            if (options.isDebug) {
+                options.onResult(`${name}: ${summary}`);
+            }
+        },
+    };
+}