@gamaze/hicortex 0.18.2 → 0.19.0

package/dist/token-budget.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTokenCap = resolveTokenCap;
+exports.initTokenBudget = initTokenBudget;
+exports.getTokenCap = getTokenCap;
+exports.isTokenBudgetExceeded = isTokenBudgetExceeded;
+exports.recordDistillUsage = recordDistillUsage;
+/**
+ * Per-tenant monthly token-budget enforcement (#110 Phase 0B item #5).
+ *
+ * Limits LLM token consumption over /distill (the cost-generating path the
+ * nightly consolidation throttle did NOT cover). Mode-agnostic — gates on
+ * `cap > 0`, never on `hostedMode`:
+ *   - Self-hosted: the cap is the operator's own `llmTokensPerMonth` config
+ *     (default 0 = unlimited → never throttles). Protects the operator's wallet
+ *     from a runaway nightly on an expensive model.
+ *   - Hosted: the cap is provider-set via the `HICORTEX_TOKEN_CAP` env, which
+ *     takes PRECEDENCE over config. The tenant process cannot mutate boot-time
+ *     env, so a hosted tenant cannot raise its own cap (the config.json
+ *     self-edit loophole is closed). Protects the provider's wallet.
+ *
+ * Reuses the existing machinery: `shouldThrottleTokens` (consolidate.ts) for the
+ * decision (incl. monthly reset), and `llmTokensThisPeriod` + `updateState`
+ * (state.ts) for the counter + atomic persistence.
+ *
+ * Concurrency: state.json is read fresh for each check and written via
+ * `updateState` (a synchronous read-modify-write; Node's single thread
+ * serializes concurrent /distill calls within the server process, so no
+ * in-process tally is needed). The nightly consolidation is a SEPARATE process
+ * that also writes state.json; a rare cross-process write collision can lose a
+ * small increment — negligible on a multi-million-token monthly budget. A
+ * DB-backed counter (WAL transactions serialize across processes) is the future
+ * hardening if it ever matters.
+ */
+const state_js_1 = require("./state.js");
+const consolidate_js_1 = require("./consolidate.js");
+/** Env override (hosted: provider-set, tenant-immutable at runtime). */
+const TOKEN_CAP_ENV = "HICORTEX_TOKEN_CAP";
+let cap = 0;
+/** periodStart we last emitted the 80% warning at, to dedup within a period. */
+let warnedPeriod = null;
+/**
+ * Resolve the effective cap: env (HICORTEX_TOKEN_CAP) takes precedence over the
+ * config key. A positive, finite env wins; otherwise the config value (0/absent
+ * = unlimited). Pure — exported for tests.
+ */
+function resolveTokenCap(configCap) {
+    const envCap = Number(process.env[TOKEN_CAP_ENV]);
+    if (Number.isFinite(envCap) && envCap > 0)
+        return envCap;
+    const cfg = Number(configCap);
+    return Number.isFinite(cfg) && cfg > 0 ? cfg : 0;
+}
+/**
+ * Initialise at server boot (after stateDir is known). Resolves + caches the cap
+ * and seeds the 80%-warn dedup so a restart mid-period doesn't re-warn.
+ */
+function initTokenBudget(stateDir, configCap) {
+    cap = resolveTokenCap(configCap);
+    if (cap > 0) {
+        const p = (0, state_js_1.loadState)(stateDir).llmTokensThisPeriod;
+        warnedPeriod = p && p.total >= cap * 0.8 ? (p.periodStart ?? null) : null;
+        // Label the source truthfully: only claim env if the env value was actually
+        // used (a malformed env falls back to config, so the label must not lie).
+        const fromEnv = Number(process.env[TOKEN_CAP_ENV]) === cap;
+        console.log(`[hicortex] Token budget: ${cap.toLocaleString()}/month${fromEnv ? " (HICORTEX_TOKEN_CAP)" : ""}`);
+    }
+}
+/** The resolved monthly cap (0 = unlimited / enforcement off). */
+function getTokenCap() {
+    return cap;
+}
+/**
+ * Pre-call check for /distill: refuse (429) when the tenant is already at/over
+ * the monthly cap. Reuses `shouldThrottleTokens(cap, period, 0)` — lastRunTokens
+ * is 0 because we cannot predict a call's cost before making it, so this refuses
+ * only when already over (a tenant exactly at the cap is refused on the next
+ * call). Reads state.json fresh so the nightly process's writes are reflected.
+ */
+function isTokenBudgetExceeded(stateDir) {
+    if (cap <= 0)
+        return false;
+    const period = (0, state_js_1.loadState)(stateDir).llmTokensThisPeriod;
+    return (0, consolidate_js_1.shouldThrottleTokens)(cap, period, 0).throttle;
+}
+/**
+ * After a successful distill, add the consumed tokens to the monthly counter and
+ * emit the 80% warning once per period. Synchronous read-modify-write via
+ * `updateState` (serializes concurrent in-process /distill; picks up the nightly
+ * process's writes via the fresh read). Accumulates the full breakdown
+ * (prompt/completion/total) so the dashboard's prompt+completion stays
+ * consistent with total (distill + consolidation).
+ */
+function recordDistillUsage(stateDir, usage) {
+    // Record ALWAYS; the cap only governs ENFORCEMENT (isTokenBudgetExceeded)
+    // and the 80% warning below. Without this, an uncapped install (self-hosted
+    // default) never accrues distill tokens into the period meter, so the
+    // dashboard's monthly headline read consolidation-only while the per-run
+    // chart next to it showed true (distill-inclusive) totals — numbers on the
+    // same card telling different stories (#287 CR). Always-recording makes the
+    // meter the honest "what did this install spend" number everywhere.
+    if (usage.total <= 0)
+        return;
+    let newTotal = 0;
+    let periodStart = "";
+    (0, state_js_1.updateState)((s) => {
+        const prev = s.llmTokensThisPeriod;
+        // Monthly reset (year+month) — matches shouldThrottleTokens's staleness check.
+        const stale = !prev?.periodStart ||
+            new Date(prev.periodStart).getUTCFullYear() !== new Date().getUTCFullYear() ||
+            new Date(prev.periodStart).getUTCMonth() !== new Date().getUTCMonth();
+        if (stale) {
+            s.llmTokensThisPeriod = {
+                prompt: usage.prompt,
+                completion: usage.completion,
+                total: usage.total,
+                periodStart: new Date().toISOString(),
+            };
+        }
+        else {
+            const base = prev;
+            s.llmTokensThisPeriod = {
+                prompt: (base.prompt ?? 0) + usage.prompt,
+                completion: (base.completion ?? 0) + usage.completion,
+                total: (base.total ?? 0) + usage.total,
+                periodStart: base.periodStart,
+            };
+        }
+        newTotal = s.llmTokensThisPeriod.total;
+        periodStart = s.llmTokensThisPeriod.periodStart;
+    }, stateDir);
+    // 80% warning — dedup per period (once per month per threshold crossing).
+    // Cap-gated by design: no cap → no percentage to warn about.
+    if (cap > 0 && periodStart && warnedPeriod !== periodStart && newTotal >= cap * 0.8) {
+        warnedPeriod = periodStart;
+        const pct = Math.round((newTotal / cap) * 100);
+        console.warn(`[hicortex] Token usage at ${pct}% of monthly cap (${newTotal.toLocaleString()}/${cap.toLocaleString()}).`);
+    }
+}

package/dist/type-classify.js

@@ -78,10 +78,13 @@ function buildTypeClassifyPrompt(content) {
         `occurrence ("tried X, failed because Y", a correction, a debugging session).\n` +
         `- knowledge: a durable truth that holds across sessions, not tied to a ` +
         `single moment ("the API is at :8787", "uv is used for packages").\n` +
-        `- decisions: a choice made that future work builds on and a later ` +
-        `decision can supersede ("switched from gemma4 to qwen3.5", "adopted the ` +
-        `graded-schema tag model"). Not knowledge (it can change) and not an ` +
-        `experience (it persists).\n\n` +
+        `- decisions: a choice the user explicitly made or confirmed (or one the ` +
+        `memory records as actually carried out/applied) that future work builds ` +
+        `on and a later decision can supersede ("switched from gemma4 to qwen3.5", ` +
+        `"adopted the graded-schema tag model"). Not knowledge (it can change) and ` +
+        `not an experience (it persists). A bare AI recommendation or proposal is ` +
+        `NEVER a decision — "AI proposed X → user declined/held" is experience ` +
+        `(#290).\n\n` +
         `IMPORTANCE (0.0–1.0):\n` +
         `- 0.8–1.0: load-bearing — a core piece of knowledge or a decision the ` +
         `agent must know.\n` +

package/dist/types.d.ts

@@ -412,6 +412,15 @@ export interface HicortexConfig {
      * so these were not surfacing in the top-k anyway).
      */
     memorySoftCap?: number;
+    /**
+     * Hosted-service mode (issue #110, #271 — spec 2026-07-27 §1-§2). When true,
+     * the server enforces hosted-tenant constraints at boot: it refuses to start
+     * if `HICORTEX_DB_PATH` is set (path-override attacks) or if the localhost
+     * auth-bypass marker file is present (hosted must be fail-closed — no bypass).
+     * Absent/false (the self-hosted default) → the assertions never fire and
+     * behaviour is unchanged. Read at server boot via readStrictBoolean.
+     */
+    hostedMode?: boolean;
     /**
      * Monthly fair-use ceiling on consolidation LLM token consumption (#246).
      * Default `0` = unlimited (the self-hosted default — no cap, never throttled).
@@ -425,6 +434,46 @@ export interface HicortexConfig {
      * set it. Period resets monthly (state.json `llmTokensThisPeriod.periodStart`).
      */
     llmTokensPerMonth?: number;
+    /**
+     * Max request body size in MB accepted by the REST/MCP server (#7). The body
+     * is fully JSON-parsed into memory before the distiller truncates content to
+     * 80K chars, so an unbounded body is an OOM vector — a tenant (hosted) or a
+     * misbehaving client could POST a huge payload to exhaust RAM. Default: 25 MB
+     * self-hosted (unchanged), 5 MB hosted (the spec §6.3 figure — ~25× the 200KB
+     * segment max, so legitimate capture never approaches it; it's a pure
+     * abuse/OOM backstop). Oversized bodies get HTTP 413.
+     */
+    distillBodyLimitMb?: number;
+    /**
+     * Output directory for backup artifacts (#6). Default `<HICORTEX_HOME>/backups`.
+     * Both the CLI (`hicortex backup`) and the nightly backup stage resolve this
+     * before calling createBackup; an unset value falls back to the home dir.
+     * Operator-owned: point at a mounted backup volume, a tmpfs, etc.
+     */
+    backupDir?: string;
+    /**
+     * Post-backup offsite hook (#6). When set, `hicortex backup` and the nightly
+     * backup stage invoke this command with the artifact path appended as the LAST
+     * arg (e.g. `"rclone copyto"` → `rclone copyto <path> remote:bucket/`). Cloud
+     * credentials + active alerting (email/Discord) stay in the operator's wrapper
+     * script, out of the product. The hook is split on whitespace (no shell); a
+     * command with quoted args containing spaces should be a wrapper script. A
+     * failing/missing/timed-out hook reports `{ok:false}` and never throws —
+     * capture/consolidation have already succeeded, so a backup-hook failure must
+     * not fail the nightly. 5 min timeout.
+     */
+    backupCommand?: string;
+    /**
+     * Account identity shown in the dashboard header (hosted). When ALL three
+     * are absent the header renders no account element (self-hosted default —
+     * nothing changes). Strings only; read via readStringConfig, null when
+     * absent/not a string. Set per-tenant by provision-tenant.sh.
+     */
+    displayName?: string;
+    /** Organization name — rendered alongside displayName as "Name · Org". */
+    orgName?: string;
+    /** Plan/tier label rendered as a small badge (e.g. "Cloud · Early bird"). */
+    planLabel?: string;
 }
 /** A config-owned life-sphere domain (see HicortexConfig.domains). */
 export interface DomainDef {

package/dist/viz.d.ts

@@ -45,8 +45,16 @@ export declare const VIZ_VENDOR_FILES: ReadonlySet<string>;
  * always evaluated (no short-circuit), so a caller cannot learn WHICH token
  * matched from the response timing. Absent/empty `authTokenPrevious` behaves
  * exactly as the single-token middleware always has.
+ *
+ * `allowLocalhostBypass` (0.18, #110 §2/#271): when false (or omitted), the
+ * localhost bypass is DISABLED — localhost connections need the bearer token
+ * like any other (fail-closed). When true, localhost loopback (127.0.0.1,
+ * ::1, ::ffff:127.0.0.1) bypasses auth as before. The marker file
+ * `~/.hicortex/.allow-localhost-bypass` (written by self-hosted init) gates
+ * this — a hosted tenant dir is fail-closed by default. mcp-server.ts captures
+ * the marker state once at boot and passes it in (no per-request stat).
  */
-export declare function createAuthMiddleware(authToken: string | undefined, authTokenPrevious?: string): express.RequestHandler;
+export declare function createAuthMiddleware(authToken: string | undefined, authTokenPrevious?: string, allowLocalhostBypass?: boolean): express.RequestHandler;
 /**
  * Resolve the on-disk path of the viz page. Throws (fail explicitly) when the
  * asset is missing — a broken install should surface, not degrade silently.

package/dist/viz.js

@@ -92,9 +92,18 @@ function safeBearerMatch(headerValue, expectedToken) {
  * always evaluated (no short-circuit), so a caller cannot learn WHICH token
  * matched from the response timing. Absent/empty `authTokenPrevious` behaves
  * exactly as the single-token middleware always has.
+ *
+ * `allowLocalhostBypass` (0.18, #110 §2/#271): when false (or omitted), the
+ * localhost bypass is DISABLED — localhost connections need the bearer token
+ * like any other (fail-closed). When true, localhost loopback (127.0.0.1,
+ * ::1, ::ffff:127.0.0.1) bypasses auth as before. The marker file
+ * `~/.hicortex/.allow-localhost-bypass` (written by self-hosted init) gates
+ * this — a hosted tenant dir is fail-closed by default. mcp-server.ts captures
+ * the marker state once at boot and passes it in (no per-request stat).
  */
-function createAuthMiddleware(authToken, authTokenPrevious) {
+function createAuthMiddleware(authToken, authTokenPrevious, allowLocalhostBypass) {
     const previous = authTokenPrevious && authTokenPrevious.length > 0 ? authTokenPrevious : undefined;
+    const bypassEnabled = allowLocalhostBypass === true;
     return (req, res, next) => {
         if (req.path === "/health")
             return next();
@@ -142,7 +151,7 @@ function createAuthMiddleware(authToken, authTokenPrevious) {
                 return next();
         }
         const ip = req.ip ?? req.socket.remoteAddress ?? "";
-        if (ip === "127.0.0.1" || ip === "::1" || ip === "::ffff:127.0.0.1")
+        if (bypassEnabled && (ip === "127.0.0.1" || ip === "::1" || ip === "::ffff:127.0.0.1"))
             return next();
         // Constant-time bearer check (#254). When authTokenPrevious is set, BOTH
         // tokens are compared every request (no short-circuit) so timing cannot

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.18.2",
-  "description": "Persistent agent identity for AI agents — a hand-edited identity layer, nightly-distilled experience, and lessons injected every session, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
+  "version": "0.19.0",
+  "description": "Persistent agent identity for AI agents \u2014 a hand-edited identity layer, nightly-distilled experience, and lessons injected every session, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {
     "hicortex": "dist/cli.js"
@@ -47,6 +47,7 @@
     "@types/better-sqlite3": "^7.6.0",
     "@types/express": "^5.0.6",
     "@types/node": "^22.0.0",
+    "@types/tar-stream": "^3.1.4",
     "typescript": "^5.4.0",
     "vitest": "^3.0.0"
   },
@@ -69,6 +70,7 @@
     "@modelcontextprotocol/sdk": "^1.28.0",
     "better-sqlite3": "^12.11.1",
     "express": "^4.21.0",
-    "sqlite-vec": "^0.1.7"
+    "sqlite-vec": "^0.1.7",
+    "tar-stream": "^2.2.0"
   }
-}
+}