@ouro.bot/cli 0.1.0-alpha.83 → 0.1.0-alpha.831

package/dist/heart/daemon/pulse.js

@@ -0,0 +1,511 @@
+"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.getPulsePath = getPulsePath;
+exports.getPulseDeliveredPath = getPulseDeliveredPath;
+exports.buildAlertId = buildAlertId;
+exports.readAgentActivity = readAgentActivity;
+exports.buildPulseState = buildPulseState;
+exports.findNovelBrokenAgents = findNovelBrokenAgents;
+exports.findRecoveredAgents = findRecoveredAgents;
+exports.buildRecoveryAlertId = buildRecoveryAlertId;
+exports.buildPulsePrivateWakeRequest = buildPulsePrivateWakeRequest;
+exports.pickWakeRecipient = pickWakeRecipient;
+exports.writePulse = writePulse;
+exports.readPulse = readPulse;
+exports.readDeliveredState = readDeliveredState;
+exports.writeDeliveredState = writeDeliveredState;
+exports.pruneDeliveredState = pruneDeliveredState;
+exports.flushPulse = flushPulse;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../../nerves/runtime");
+const provider_visibility_1 = require("../provider-visibility");
+/* v8 ignore next 3 -- path defaults: tests always inject @preserve */
+function defaultPulsePath() {
+    return path.join(os.homedir(), ".ouro-cli", "pulse.json");
+}
+/* v8 ignore next 3 -- path defaults: tests always inject @preserve */
+function defaultDeliveredPath() {
+    return path.join(os.homedir(), ".ouro-cli", "pulse-delivered.json");
+}
+function getPulsePath() {
+    return defaultPulsePath();
+}
+function getPulseDeliveredPath() {
+    return defaultDeliveredPath();
+}
+/**
+ * Hash an error reason into a short stable identifier. We use a simple
+ * non-cryptographic hash because we only need stability across daemon
+ * restarts on the same machine, not collision resistance against
+ * adversaries. djb2 is fine.
+ */
+function hashErrorReason(reason) {
+    let h = 5381;
+    for (let i = 0; i < reason.length; i++) {
+        h = ((h << 5) + h + reason.charCodeAt(i)) >>> 0;
+    }
+    return h.toString(16);
+}
+/**
+ * Build a stable alert ID for a (agent, error) pair. Same agent + same
+ * error → same ID, even across daemon restarts. Different error → new ID.
+ */
+function buildAlertId(agent, errorReason) {
+    return `${agent}:${hashErrorReason(errorReason)}`;
+}
+/**
+ * Read an agent's private-runtime state and format it as a short
+ * activity hint string suitable for display in another agent's pulse
+ * section. Returns null when the file is missing or malformed — both
+ * cases are silent (the pulse just doesn't include activity for that
+ * agent).
+ *
+ * Pure: takes a file reader so tests can inject content without touching
+ * fs. Defaults to fs.readFileSync for the production daemon caller.
+ */
+function readAgentActivity(bundlePath, readFile = (p) => fs.readFileSync(p, "utf-8")) {
+    const runtimePath = path.join(bundlePath, "state", "sessions", "self", "inner", "runtime.json");
+    let raw;
+    try {
+        raw = readFile(runtimePath);
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const status = typeof parsed.status === "string" ? parsed.status : null;
+    const reason = typeof parsed.reason === "string" ? parsed.reason : null;
+    const startedAt = typeof parsed.startedAt === "string" ? parsed.startedAt : null;
+    if (!status)
+        return null;
+    // Format compactly. Examples:
+    //   "running (instinct since 23:44)"
+    //   "idle since 21:30"
+    //   "running"
+    const sinceStr = startedAt ? ` since ${startedAt.slice(11, 16)}` : "";
+    if (status === "running" && reason) {
+        return `running (${reason}${sinceStr})`;
+    }
+    return `${status}${sinceStr}`;
+}
+/**
+ * Convert daemon process-manager snapshots into the pulse state shape.
+ * Pure: no fs side effects (activity reading goes through the injected
+ * `readActivity` callback so tests can pin everything).
+ *
+ * The bundlePath comes from the bundlesRoot — we don't read the bundle
+ * directly, we just compute where it lives so sibling agents have a
+ * starting point if they want to navigate there manually.
+ */
+function buildPulseState(snapshots, bundlesRoot, daemonVersion, now, readActivity = readAgentActivity, readProviderVisibility = () => null) {
+    const agents = snapshots.map((snap) => {
+        const errorReason = snap.errorReason;
+        const bundlePath = path.join(bundlesRoot, `${snap.name}.ouro`);
+        return {
+            name: snap.name,
+            bundlePath,
+            status: snap.status,
+            lastSeenAt: snap.startedAt,
+            errorReason,
+            fixHint: snap.fixHint,
+            alertId: errorReason ? buildAlertId(snap.name, errorReason) : null,
+            // Only read activity for agents that are actually running. For
+            // crashed/stopped agents, the runtime.json is stale at best.
+            currentActivity: snap.status === "running" ? readActivity(bundlePath) : null,
+            providerVisibility: readProviderVisibility(snap.name, bundlePath),
+        };
+    });
+    return {
+        generatedAt: now.toISOString(),
+        daemonVersion,
+        agents,
+    };
+}
+/**
+ * A "novel broken transition" is an agent that is currently broken AND
+ * either (a) wasn't broken in the previous pulse state, OR (b) was broken
+ * but with a different alertId. Used to decide when to queue a proactive
+ * pulse wake.
+ *
+ * Pure: takes prev and next states, returns the list of newly-broken
+ * agents that warrant a wake.
+ */
+function findNovelBrokenAgents(prev, next) {
+    const novel = [];
+    for (const agent of next.agents) {
+        if (!agent.alertId)
+            continue;
+        const prevAgent = prev?.agents.find((a) => a.name === agent.name);
+        const wasBrokenWithSameAlert = prevAgent?.alertId === agent.alertId;
+        if (wasBrokenWithSameAlert)
+            continue;
+        novel.push(agent);
+    }
+    return novel;
+}
+/**
+ * A "recovery transition" is an agent that was broken in the previous
+ * pulse state but is healthy now. The pulse fires a wake on these too,
+ * so the user gets a positive notification when their fix takes effect.
+ *
+ * Pure: takes prev and next states, returns the list of newly-recovered
+ * agents that warrant a wake.
+ */
+function findRecoveredAgents(prev, next) {
+    if (!prev)
+        return [];
+    const recovered = [];
+    for (const agent of next.agents) {
+        // Healthy in next.
+        if (agent.alertId !== null)
+            continue;
+        if (agent.status !== "running")
+            continue;
+        // Was broken in prev.
+        const prevAgent = prev.agents.find((a) => a.name === agent.name);
+        if (!prevAgent || prevAgent.alertId === null)
+            continue;
+        recovered.push(agent);
+    }
+    return recovered;
+}
+/**
+ * Build a stable alert ID for a recovery event. Used so the recovery
+ * wake is also at-most-once (no re-paging on every snapshot change after
+ * recovery). Includes the recovery timestamp so a later break+heal cycle
+ * generates a fresh ID.
+ */
+function buildRecoveryAlertId(agent, recoveredAt) {
+    return `recovery:${agent}:${recoveredAt}`;
+}
+function buildPulsePrivateWakeRequest(options) {
+    const prefix = options.triggerSource === "pulse-alert" ? "pulse alert" : "pulse recovery";
+    const detail = options.subject.errorReason ? `: ${options.subject.errorReason}` : "";
+    const originKind = options.triggerSource === "pulse-alert" ? "pulse-alert" : "pulse-recovery";
+    return {
+        agent: options.recipient,
+        reason: `${prefix} for ${options.subject.name}${detail}`,
+        triggerSource: options.triggerSource,
+        budgetClass: "scheduled",
+        idempotencyKey: `pulse:${options.recipient}:${options.alertId}`,
+        originRefs: [
+            { kind: originKind, id: options.alertId },
+            { kind: "agent", id: options.subject.name },
+        ],
+    };
+}
+/**
+ * Pick which agent should receive a pulse wake for a fleet alert. Heuristic:
+ * the most-recently-active running agent (by `lastSeenAt`), excluding the
+ * broken agent itself and any agents that aren't currently running. Returns
+ * null if there's no eligible recipient (e.g., the only other agent on the
+ * machine is also broken).
+ *
+ * Pure: takes the pulse state and the alert target, returns the chosen
+ * recipient name or null.
+ */
+function pickWakeRecipient(state, brokenAgent) {
+    const candidates = state.agents
+        .filter((a) => a.name !== brokenAgent)
+        .filter((a) => a.status === "running")
+        .filter((a) => a.lastSeenAt !== null)
+        .sort((a, b) => {
+        // Most-recent first. lastSeenAt is non-null per the filter above.
+        const aMs = Date.parse(a.lastSeenAt);
+        const bMs = Date.parse(b.lastSeenAt);
+        return bMs - aMs;
+    });
+    return candidates[0]?.name ?? null;
+}
+/**
+ * Write the pulse state to disk. Best-effort: if the write fails, emit a
+ * nerves event but do not throw. The pulse is a notification mechanism;
+ * the daemon's primary work should not be blocked by it.
+ */
+function writePulse(state, deps = {}) {
+    /* v8 ignore start -- dep defaults: production-only paths; tests inject all four explicitly @preserve */
+    const filePath = deps.pulsePath ?? defaultPulsePath();
+    const writeFile = deps.writeFile ?? ((p, c) => fs.writeFileSync(p, c, "utf-8"));
+    const mkdirp = deps.mkdirp ?? ((d) => fs.mkdirSync(d, { recursive: true }));
+    /* v8 ignore stop */
+    try {
+        mkdirp(path.dirname(filePath));
+        writeFile(filePath, JSON.stringify(state, null, 2) + "\n");
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.pulse_written",
+            message: "wrote machine pulse state",
+            meta: { filePath, agentCount: state.agents.length },
+        });
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.pulse_write_error",
+            message: "failed to write pulse state",
+            meta: {
+                filePath,
+                error: error instanceof Error ? error.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(error),
+            },
+        });
+    }
+}
+/**
+ * Read the pulse state from disk. Returns null if the file doesn't exist
+ * or is malformed — pulse readers (like the prompt assembler) should
+ * gracefully degrade to "no pulse, render nothing" rather than crash.
+ */
+function readPulse(deps = {}) {
+    const filePath = deps.pulsePath ?? defaultPulsePath();
+    /* v8 ignore next -- dep default: tests always inject @preserve */
+    const readFile = deps.readFile ?? ((p) => fs.readFileSync(p, "utf-8"));
+    try {
+        const raw = readFile(filePath);
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.generatedAt !== "string")
+            return null;
+        if (typeof parsed.daemonVersion !== "string")
+            return null;
+        if (!Array.isArray(parsed.agents))
+            return null;
+        return {
+            generatedAt: parsed.generatedAt,
+            daemonVersion: parsed.daemonVersion,
+            agents: parsed.agents.filter(isValidPulseAgentEntry).map((agent) => {
+                const rawAgent = agent;
+                if (!Object.prototype.hasOwnProperty.call(rawAgent, "providerVisibility"))
+                    return agent;
+                return {
+                    ...agent,
+                    providerVisibility: (0, provider_visibility_1.isAgentProviderVisibility)(rawAgent.providerVisibility)
+                        ? rawAgent.providerVisibility
+                        : null,
+                };
+            }),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isValidPulseAgentEntry(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const v = value;
+    return (typeof v.name === "string"
+        && typeof v.bundlePath === "string"
+        && (v.status === "running" || v.status === "starting" || v.status === "stopped" || v.status === "crashed")
+        && (v.lastSeenAt === null || typeof v.lastSeenAt === "string")
+        && (v.errorReason === null || typeof v.errorReason === "string")
+        && (v.fixHint === null || typeof v.fixHint === "string")
+        && (v.alertId === null || typeof v.alertId === "string"));
+}
+/**
+ * Read the persistent delivered-alerts state. Returns an empty set if the
+ * file doesn't exist or is malformed.
+ */
+function readDeliveredState(deps = {}) {
+    /* v8 ignore start -- dep defaults: production-only paths; tests inject all explicitly @preserve */
+    const filePath = deps.deliveredPath ?? defaultDeliveredPath();
+    const readFile = deps.readFile ?? ((p) => fs.readFileSync(p, "utf-8"));
+    /* v8 ignore stop */
+    try {
+        const raw = readFile(filePath);
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.delivered))
+            return new Set();
+        return new Set(parsed.delivered.filter((id) => typeof id === "string"));
+    }
+    catch {
+        return new Set();
+    }
+}
+/**
+ * Persist the delivered-alerts state to disk. Best-effort.
+ */
+function writeDeliveredState(delivered, deps = {}) {
+    /* v8 ignore start -- dep defaults: production-only paths; tests inject all four explicitly @preserve */
+    const filePath = deps.deliveredPath ?? defaultDeliveredPath();
+    const writeFile = deps.writeFile ?? ((p, c) => fs.writeFileSync(p, c, "utf-8"));
+    const mkdirp = deps.mkdirp ?? ((d) => fs.mkdirSync(d, { recursive: true }));
+    /* v8 ignore stop */
+    try {
+        mkdirp(path.dirname(filePath));
+        const state = { delivered: [...delivered].sort() };
+        writeFile(filePath, JSON.stringify(state, null, 2) + "\n");
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.pulse_delivered_write_error",
+            message: "failed to write pulse delivered state",
+            meta: {
+                filePath,
+                error: error instanceof Error ? error.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(error),
+            },
+        });
+    }
+}
+/**
+ * Prune delivered alert IDs that no longer correspond to an active broken
+ * agent. When the user fixes ouroboros's config, the next pulse state has
+ * no alertId for ouroboros, so we drop the old delivered entry — meaning
+ * if ouroboros breaks AGAIN later (with the same error), we re-page.
+ */
+function pruneDeliveredState(delivered, state) {
+    const liveAlertIds = new Set();
+    for (const agent of state.agents) {
+        if (agent.alertId)
+            liveAlertIds.add(agent.alertId);
+    }
+    const pruned = new Set();
+    for (const id of delivered) {
+        if (liveAlertIds.has(id))
+            pruned.add(id);
+    }
+    return pruned;
+}
+/**
+ * Single entry point the daemon's onSnapshotChange callback uses. Builds
+ * the new pulse state, diffs against the previous, writes the file, and
+ * queues pulse wakes on novel broken transitions for the most-recently-active
+ * sibling. Persistent at-most-once delivery via the delivered state file.
+ *
+ * Pure-ish: all I/O goes through dep callbacks so tests can pin every
+ * input and assert every effect. Defaults wire to the real fs functions
+ * for production callers.
+ */
+function flushPulse(deps) {
+    const state = buildPulseState(deps.snapshots, deps.bundlesRoot, deps.daemonVersion, deps.now, readAgentActivity, (agentName, bundlePath) => (0, provider_visibility_1.buildAgentProviderVisibility)({ agentName, agentRoot: bundlePath }));
+    /* v8 ignore start -- dep defaults: production daemon path; the arrow functions only fire when the corresponding dep is omitted, which only happens in production code paths. Tests inject all deps explicitly. @preserve */
+    const readPrev = deps.readPrev ?? (() => readPulse());
+    const writeNext = deps.writeNext ?? ((s) => writePulse(s));
+    const readDelivered = deps.readDelivered ?? (() => readDeliveredState());
+    const writeDelivered = deps.writeDelivered ?? ((d) => writeDeliveredState(d));
+    const fireInnerWake = deps.fireInnerWake ?? null;
+    const firePrivateWake = deps.firePrivateWake ?? null;
+    /* v8 ignore stop */
+    const prev = readPrev();
+    let delivered = readDelivered();
+    // Write the new pulse state first so any reader (including the
+    // wake-recipient agent's prompt assembly on its next turn) sees the
+    // current state. Doing this before firing the wake matters: if the
+    // wake races against a fast prompt build on the recipient, we want
+    // the recipient to read the NEW state, not the old one.
+    writeNext(state);
+    // Find agents that newly transitioned to broken (or to a different
+    // error than before).
+    const novelBroken = findNovelBrokenAgents(prev, state);
+    // Of those, the ones we haven't already delivered an alert for.
+    const undeliveredBroken = novelBroken.filter((a) => a.alertId !== null && !delivered.has(a.alertId));
+    // Find agents that newly recovered (were broken in prev, healthy now).
+    const recovered = findRecoveredAgents(prev, state);
+    // For recovery wakes, build a fresh alert ID per recovery event so
+    // we don't re-page on every subsequent flush.
+    const recoveryAlertIds = recovered.map((a) => buildRecoveryAlertId(a.name, state.generatedAt));
+    const undeliveredRecovered = recovered.filter((_, i) => !delivered.has(recoveryAlertIds[i]));
+    // Fire wakes and update the delivered set.
+    const wakeFiredFor = [];
+    const newlyDelivered = [];
+    for (const broken of undeliveredBroken) {
+        /* v8 ignore next -- defensive: undeliveredBroken already filtered to non-null alertId; this is a TS narrowing helper @preserve */
+        if (broken.alertId === null)
+            continue;
+        const recipient = pickWakeRecipient(state, broken.name);
+        if (recipient !== null && firePrivateWake !== null) {
+            firePrivateWake(buildPulsePrivateWakeRequest({
+                recipient,
+                subject: broken,
+                alertId: broken.alertId,
+                triggerSource: "pulse-alert",
+            }));
+            wakeFiredFor.push(recipient);
+        }
+        else if (recipient !== null && fireInnerWake !== null) {
+            fireInnerWake(recipient);
+            wakeFiredFor.push(recipient);
+        }
+        // Mark delivered even if no recipient was available — otherwise
+        // the daemon will keep trying to wake every time the snapshot
+        // changes, which would spam logs without producing any user value.
+        // The passive prompt section still surfaces the broken state to
+        // the recipient when they eventually have a turn for any reason.
+        delivered.add(broken.alertId);
+        newlyDelivered.push(broken.alertId);
+    }
+    for (let i = 0; i < undeliveredRecovered.length; i++) {
+        const recoveredAgent = undeliveredRecovered[i];
+        const recoveryAlertId = buildRecoveryAlertId(recoveredAgent.name, state.generatedAt);
+        const recipient = pickWakeRecipient(state, recoveredAgent.name);
+        if (recipient !== null && firePrivateWake !== null) {
+            firePrivateWake(buildPulsePrivateWakeRequest({
+                recipient,
+                subject: recoveredAgent,
+                alertId: recoveryAlertId,
+                triggerSource: "pulse-recovery",
+            }));
+            wakeFiredFor.push(recipient);
+        }
+        else if (recipient !== null && fireInnerWake !== null) {
+            fireInnerWake(recipient);
+            wakeFiredFor.push(recipient);
+        }
+        delivered.add(recoveryAlertId);
+        newlyDelivered.push(recoveryAlertId);
+    }
+    // Drop delivered ids for agents that have healed since (this drops
+    // the original `agent_config_failure:...` IDs once the agent recovers,
+    // so a future relapse re-pages). Recovery alert IDs are NOT pruned by
+    // pruneDeliveredState because they're tied to a healthy state, not a
+    // broken state — they live in the delivered set until the same agent
+    // breaks and recovers again, at which point a new recovery ID is
+    // generated and the old one becomes harmless cruft. We could clean
+    // them up too, but the cost is bounded by the number of recovery
+    // cycles, which is small.
+    delivered = pruneDeliveredState(delivered, state);
+    writeDelivered(delivered);
+    return { state, wakeFiredFor, newlyDelivered };
+}