@gamaze/hicortex 0.19.5 → 0.20.0

package/dist/opencode-transcript-reader.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * opencode transcript reader — the nightly capture path for the opencode
+ * coding agent (#347).
+ *
+ * opencode persists every session in ONE SQLite store:
+ *   ~/.local/share/opencode/opencode.db
+ *
+ * Schema (relevant columns, verified live on opencode 1.18.20/1.18.23):
+ *   session(id TEXT PK, directory TEXT, parent_id TEXT NULL,
+ *           time_created INTEGER, time_updated INTEGER)  — epoch MILLISECONDS
+ *   message(id TEXT PK, session_id TEXT, time_created INTEGER,
+ *           time_updated INTEGER, data TEXT)             — data = {"role",…}
+ *   part(id TEXT PK, message_id TEXT, time_created INTEGER, data TEXT)
+ *                                                         — data = {"type","text",…}
+ *
+ * The message row holds METADATA ONLY (role, model, cost — no text); the
+ * conversation text lives in the message's part rows as
+ * {"type":"text","text":…}. part types tool/reasoning/step-start/step-finish
+ * are plumbing, not conversation, and are excluded by the `$.type`='text'
+ * filter. A message left with no text yields no entry.
+ *
+ * Cursor: message.time_created (epoch ms) — deliberately NOT rowid. message
+ * has a TEXT primary key, so rowid is implicit, reusable after the
+ * session-delete cascade and renumbered by VACUUM — a stored rowid cursor can
+ * silently skip rows (loss, breaking the dup-over-loss invariant). Unlike the
+ * Hermes cursor column (INTEGER PRIMARY KEY AUTOINCREMENT — strictly
+ * increasing, never reused), time_created is never rewritten. The delta is
+ * EXCLUSIVE (`time_created > cursor`, ORDER BY time_created, id — the id
+ * tie-break makes the order total) so a rediscovered session with no new
+ * messages produces an empty delta and posts nothing; segment ids stay
+ * byte-stable for the server's segment-exact dedup. Residual gap: two
+ * messages written in the same millisecond with the capture boundary inside
+ * that group — bounded by that group's size, not observed on real data
+ * (smallest observed inter-message gap 13 ms).
+ *
+ * Sub-agent sessions (session.parent_id set) are skipped, mirroring the CC
+ * reader's isSidechain drop. Written defensively: parent_id was NULL for
+ * every session on the verified installs, so whether opencode populates it
+ * is unconfirmed — the skip costs nothing if the column stays empty.
+ *
+ * Marker-fenced text parts (Hicortex injection echo) are skipped so memory
+ * never re-enters itself — defense in depth: the recall channel the opencode
+ * plugin uses (experimental.chat.messages.transform) is verified NOT to
+ * persist its output, but the reader guards regardless.
+ *
+ * No-ops (returns []) when the database, a table, or a column is absent —
+ * the schema is young (migration tables present), so the reader
+ * shape-guards and never crashes the nightly run.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readOpencodeSessions = readOpencodeSessions;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const OPENCODE_DATA_HOME = (0, node_path_1.join)((0, node_os_1.homedir)(), ".local", "share", "opencode");
+/**
+ * Fence around every block the opencode plugin injects (opencode-plugin/
+ * hicortex/index.ts CONTEXT_START/END). Duplicated here because the plugin
+ * is dependency-free and outside the package — keep the strings in sync.
+ */
+const FENCE_START = "<!-- hicortex-context-start -->";
+const FENCE_END = "<!-- hicortex-context-end -->";
+/**
+ * Read opencode sessions updated since `since` (the bulk watermark; opencode
+ * times are epoch milliseconds, so `since.getTime()` compares directly —
+ * NO *1000, unlike the Hermes reader's unix-seconds store). Returns one
+ * batch per session, parallel to readHermesSessions().
+ *
+ * @param opencodeHome opencode's data dir (default
+ *   ~/.local/share/opencode); injectable for tests.
+ * @param cursors Per-session capture cursors (#189), keyed
+ *   `opencode:<sessionId>`. The cursor value is the highest captured
+ *   message.time_created; the delta is exclusive (`time_created > cursor`).
+ */
+function readOpencodeSessions(since, opencodeHome = OPENCODE_DATA_HOME, cursors = {}) {
+    const dbPath = (0, node_path_1.join)(opencodeHome, "opencode.db");
+    if (!(0, node_fs_1.existsSync)(dbPath))
+        return []; // no opencode on this machine
+    let db;
+    try {
+        db = new better_sqlite3_1.default(dbPath, { readonly: true, fileMustExist: true });
+    }
+    catch {
+        return []; // locked / unreadable — skip, retry next run
+    }
+    const batches = [];
+    try {
+        // Discovery: sessions touched since the watermark. parent_id IS NULL
+        // drops sub-agent sessions (the CC isSidechain equivalent).
+        const sessions = db
+            .prepare(`SELECT id, directory, parent_id FROM session
+          WHERE time_updated > ? AND parent_id IS NULL
+          ORDER BY time_created`)
+            .all(since.getTime());
+        // Delta rows for one session. EXCLUSIVE on time_created; the id
+        // tie-break makes the read order total when two messages share a
+        // millisecond. json_extract pulls the role out of the JSON data column.
+        const msgStmt = db.prepare(`SELECT id, time_created, json_extract(data, '$.role') AS role
+         FROM message
+        WHERE session_id = ? AND time_created > ?
+        ORDER BY time_created, id`);
+        // The message's text parts in part.time_created order (distinct within a
+        // message on real data, so the join order is deterministic). Non-text
+        // part types (tool/reasoning/step-start/step-finish) are excluded here.
+        const partStmt = db.prepare(`SELECT json_extract(data, '$.text') AS text
+         FROM part
+        WHERE message_id = ? AND json_extract(data, '$.type') = 'text'
+        ORDER BY time_created`);
+        // Highest time_created in the session — used only for the shrink guard.
+        const maxStmt = db.prepare("SELECT MAX(time_created) AS m FROM message WHERE session_id = ?");
+        for (const s of sessions) {
+            const cursorKey = `opencode:${s.id}`;
+            const pos = cursors[cursorKey] ?? { cursor: 0, gen: 0 };
+            let startCursor = pos.cursor;
+            let gen = pos.gen;
+            // Shrink guard (the Hermes fix-8 pattern): a stored cursor above the
+            // session's max time_created means the DB was reset/restored — re-read
+            // from 0 and bump the generation so post-reset segment ids can't
+            // collide with pre-reset ones on the server's content-blind dedup.
+            if (startCursor > 0) {
+                const max = maxStmt.get(s.id).m ?? 0;
+                if (startCursor > max) {
+                    startCursor = 0;
+                    gen = pos.gen + 1;
+                }
+            }
+            const rows = msgStmt.all(s.id, startCursor);
+            if (rows.length === 0)
+                continue; // empty delta — nothing to post
+            const entries = [];
+            const entryCursors = [];
+            for (const r of rows) {
+                const parts = partStmt.all(r.id);
+                const content = parts
+                    .map((p) => (typeof p.text === "string" ? p.text : ""))
+                    // Fenced parts are Hicortex injection echo, not conversation.
+                    .filter((t) => t !== "" && !t.includes(FENCE_START) && !t.includes(FENCE_END))
+                    .join("\n");
+                // A message with no surviving text (tool-only / fenced-only) yields
+                // no entry. It also stays unconsumed (the cursor advances only to the
+                // last ENTRY), so it is re-scanned next run — dup-over-loss, and the
+                // entryless tail costs one no-op query until a text message lands.
+                if (content.trim() === "")
+                    continue;
+                // A NULL role passes through as "" — extractConversationText renders
+                // anything not "user" as ASSISTANT, so no turn is fabricated.
+                entries.push({ role: r.role ?? "", content });
+                entryCursors.push(r.time_created); // one end-cursor per entry
+            }
+            if (entries.length === 0)
+                continue; // entryless delta posts nothing
+            // date = the delta's LAST message time — already milliseconds, so
+            // unlike the Hermes reader there is no *1000 (copying that line would
+            // put the date ~57,000 years out).
+            batches.push({
+                sessionId: s.id,
+                projectName: (0, node_path_1.basename)(s.directory ?? "") || "opencode",
+                sourceAgent: "opencode",
+                date: new Date(rows[rows.length - 1].time_created).toISOString().slice(0, 10),
+                entries,
+                cursorKey,
+                startCursor,
+                generation: gen,
+                entryCursors,
+            });
+        }
+    }
+    catch {
+        // Query failed (schema drift on an opencode upgrade) — no-op, don't crash the run.
+        return [];
+    }
+    finally {
+        db.close();
+    }
+    return batches;
+}

package/dist/status.js

@@ -132,6 +132,29 @@ async function runStatus() {
     }
     catch { /* no CC settings */ }
     console.log(`  CC MCP:     ${ccRegistered ? `registered → ${ccUrl}` : "not registered"}`);
+    // Pi (#348): the bundled extension at ~/.pi/agent/extensions/hicortex.ts.
+    // "not found" = no Pi on this machine; "not installed" = Pi present, run
+    // init to place the extension.
+    const piAgentDir = (0, node_path_1.join)((0, node_os_1.homedir)(), ".pi", "agent");
+    if ((0, node_fs_1.existsSync)(piAgentDir)) {
+        const piInstalled = (0, node_fs_1.existsSync)((0, node_path_1.join)(piAgentDir, "extensions", "hicortex.ts"));
+        console.log(`  Pi plugin:  ${piInstalled ? "installed" : "not installed (run: npx @gamaze/hicortex init)"}`);
+    }
+    else {
+        console.log("  Pi plugin:  not found");
+    }
+    // opencode (#347): the bundled plugin at ~/.config/opencode/plugins/hicortex.ts.
+    // "not found" = no opencode on this machine; "not installed" = opencode
+    // present, run init to place the plugin.
+    const opencodeConfigDir = (0, node_path_1.join)((0, node_os_1.homedir)(), ".config", "opencode");
+    const opencodeDataDir = (0, node_path_1.join)((0, node_os_1.homedir)(), ".local", "share", "opencode");
+    if ((0, node_fs_1.existsSync)(opencodeConfigDir) || (0, node_fs_1.existsSync)(opencodeDataDir)) {
+        const openCodeInstalled = (0, node_fs_1.existsSync)((0, node_path_1.join)(opencodeConfigDir, "plugins", "hicortex.ts"));
+        console.log(`  opencode:   ${openCodeInstalled ? "installed" : "not installed (run: npx @gamaze/hicortex init)"}`);
+    }
+    else {
+        console.log("  opencode:   not found");
+    }
     console.log();
     // Server status. /health/detail carries the diagnostics (version, memories,
     // llm) — /health itself is the public minimal {status:"ok"} probe (#253).

package/dist/telemetry.d.ts

@@ -6,11 +6,11 @@
  *   v        — package version
  *   pv       — payload schema version
  *   mode     — server or client
- *   agent    — cc, pi, oc, or mixed (detected from session sources); OMITTED
- *              when the agent type is genuinely unknown (pre-flight abort — no
- *              transcripts read yet). The admin summary buckets a missing agent
- *              as "?", distinct from any real type, so an aborting Hermes/OC
- *              client is never miscounted as "cc".
+ *   agent    — cc, hermes, pi, oc, opencode, or mixed (detected from session
+ *              sources); OMITTED when the agent type is genuinely unknown
+ *              (pre-flight abort — no transcripts read yet). The admin summary
+ *              buckets a missing agent as "?", distinct from any real type, so
+ *              an aborting Hermes/OC client is never miscounted as "cc".
  *   mem      — total memory count
  *   lessons  — total lesson count
  *   lessonsGenerated — lessons created THIS run (server mode only; the per-run
@@ -89,15 +89,19 @@ export interface TelemetryPayload {
      * Consolidation outcome for THIS full nightly (server mode only —
      * capture-only runs send no nightly ping, so the field is absent there).
      * `runConsolidation`'s status: "completed" | "skipped" | "failed", plus
-     * "no_llm" when consolidation was skipped because no LLM was configured, and
+     * "no_llm" when consolidation was skipped because no LLM was configured,
      * "throttled" (#246) when the run was skipped because the
-     * `llmTokensPerMonth` fair-use cap was projected to be exceeded.
+     * `llmTokensPerMonth` fair-use cap was projected to be exceeded, and
+     * "endpoint_down" (#337) when the pre-consolidation readiness probe failed
+     * or the LLM circuit breaker was open after the run — a TRANSIENT state
+     * (retried next run), never reported as "completed" even though the stages
+     * fail soft.
      * "skipped" = the built-in nothing-to-do short-circuit (no new + no unscored
      * memories → zero LLM calls), NOT a failure. Lets the fleet aggregate tell a
      * real consolidation run from a no-op without repurposing `ok` (which is the
      * capture-health signal). 0.17+.
      */
-    consolidation?: "completed" | "skipped" | "failed" | "no_llm" | "throttled";
+    consolidation?: "completed" | "skipped" | "failed" | "no_llm" | "throttled" | "endpoint_down";
     /**
      * Total LLM tokens consumed by THIS nightly's consolidation (#246) — the
      * BudgetTracker total. Server-mode only (capture-only + client runs make no

package/dist/telemetry.js

@@ -7,11 +7,11 @@
  *   v        — package version
  *   pv       — payload schema version
  *   mode     — server or client
- *   agent    — cc, pi, oc, or mixed (detected from session sources); OMITTED
- *              when the agent type is genuinely unknown (pre-flight abort — no
- *              transcripts read yet). The admin summary buckets a missing agent
- *              as "?", distinct from any real type, so an aborting Hermes/OC
- *              client is never miscounted as "cc".
+ *   agent    — cc, hermes, pi, oc, opencode, or mixed (detected from session
+ *              sources); OMITTED when the agent type is genuinely unknown
+ *              (pre-flight abort — no transcripts read yet). The admin summary
+ *              buckets a missing agent as "?", distinct from any real type, so
+ *              an aborting Hermes/OC client is never miscounted as "cc".
  *   mem      — total memory count
  *   lessons  — total lesson count
  *   lessonsGenerated — lessons created THIS run (server mode only; the per-run

package/dist/types.d.ts

@@ -392,6 +392,48 @@ export interface HicortexConfig {
      * doubled for margin). Only relevant when `ollamaFlushEvery` > 0.
      */
     ollamaFlushWaitMs?: number;
+    /**
+     * ONE per-attempt timeout ceiling (ms) for every LLM phase — distill,
+     * reflect, classify, and scoring alike (#337). Default 900000 (15 min). The
+     * openai-compat and anthropic requests fetch through an undici dispatcher
+     * with undici's hidden 5-minute header/body timers disabled, so this knob is
+     * the ONLY ceiling: a legitimate long generation is no longer abandoned
+     * client-side at 5 min while the server keeps generating for the dead
+     * client (the 2026-08-23/24 incident's amplification mechanism). Before
+     * #337, scoring used a 600 s ceiling and the other phases 900 s; one knob
+     * now covers all four. No effect on the ollama path (already streams) or
+     * claude-cli (subprocess timeout).
+     */
+    llmTimeoutMs?: number;
+    /**
+     * Consecutive ladder-exhausted TOTAL failures (fetch-failed / ECONNREFUSED /
+     * timeout / "Headers Timeout" class) after which the per-endpoint circuit
+     * breaker opens (#337). Default 3; `0` disables. While open, calls throw
+     * `LlmCircuitOpenError` immediately with NO network I/O. HTTP error statuses
+     * with a response, parse errors, and rate limits never count (they throw
+     * before the retry ladder can be exhausted). Any success resets the counter.
+     */
+    llmBreakerThreshold?: number;
+    /**
+     * How long (ms) an open circuit breaker stays open before the next call
+     * becomes a half-open trial (#337). Default 600000 (10 min). A trial failure
+     * re-opens the breaker; a trial success resets it.
+     */
+    llmBreakerCooldownMs?: number;
+    /**
+     * Timeout (ms) for the readiness probe's single 1-token generation attempt
+     * (#337). Default 60000. The probe asks "can this endpoint GENERATE", which
+     * /health-style liveness checks cannot answer (a wedged gateway keeps
+     * answering /v1/models). Read by the nightly before consolidation and by the
+     * daemon before distilling.
+     */
+    llmProbeTimeoutMs?: number;
+    /**
+     * How long (ms) the daemon caches a /distill probe outcome before probing
+     * again (#337). Default 300000 — a healthy capture cadence pays at most one
+     * probe per window. Nightly runs are single-shot and never cache.
+     */
+    llmProbeTtlMs?: number;
     /**
      * Max lessons injected into an agent's session-start context (default 10).
      * Lessons are ranked per-session by project/domain affinity + recency +

package/dist/uninstall.js

@@ -234,6 +234,40 @@ async function runUninstall() {
     if ((0, claude_md_js_1.removeLessonsBlock)(CLAUDE_MD)) {
         console.log("  ✓ Removed Hicortex Learnings block from CLAUDE.md");
     }
+    // 6. Remove the Pi extension (#348). Guarded on the "hicortex" marker the
+    //    installer always ships — "hicortex.ts" is a plausible user filename,
+    //    and uninstall never deletes a file we did not write. Fail-soft when
+    //    absent (no Pi on the machine) or unreadable.
+    const piExtension = (0, node_path_1.join)((0, node_os_1.homedir)(), ".pi", "agent", "extensions", "hicortex.ts");
+    if ((0, node_fs_1.existsSync)(piExtension)) {
+        try {
+            if ((0, node_fs_1.readFileSync)(piExtension, "utf-8").toLowerCase().includes("hicortex")) {
+                (0, node_fs_1.unlinkSync)(piExtension);
+                console.log("  ✓ Removed Pi extension (~/.pi/agent/extensions/hicortex.ts)");
+            }
+            else {
+                console.log("  ⚠ Skipping ~/.pi/agent/extensions/hicortex.ts — not a Hicortex file, left untouched");
+            }
+        }
+        catch { /* unreadable — leave it */ }
+    }
+    // 7. Remove the opencode plugin (#347). Same marker guard — the plugins
+    //    directory is shared (third-party files live there too), and uninstall
+    //    never deletes a file we did not write. Fail-soft when absent (no
+    //    opencode on the machine) or unreadable.
+    const openCodePlugin = (0, node_path_1.join)((0, node_os_1.homedir)(), ".config", "opencode", "plugins", "hicortex.ts");
+    if ((0, node_fs_1.existsSync)(openCodePlugin)) {
+        try {
+            if ((0, node_fs_1.readFileSync)(openCodePlugin, "utf-8").toLowerCase().includes("hicortex")) {
+                (0, node_fs_1.unlinkSync)(openCodePlugin);
+                console.log("  ✓ Removed opencode plugin (~/.config/opencode/plugins/hicortex.ts)");
+            }
+            else {
+                console.log("  ⚠ Skipping ~/.config/opencode/plugins/hicortex.ts — not a Hicortex file, left untouched");
+            }
+        }
+        catch { /* unreadable — leave it */ }
+    }
     console.log(`\n✓ Uninstalled. Database preserved at ${HICORTEX_HOME}/hicortex.db`);
     console.log("  To remove all data: rm -rf ~/.hicortex");
 }