@gamaze/hicortex 0.17.1 → 0.17.3

package/dist/llm.d.ts

@@ -108,6 +108,33 @@ export declare class RateLimitError extends Error {
     retryAfterMs: number;
     constructor(retryAfterMs: number);
 }
+/**
+ * Token-usage triplet reported by every LLM call (#246). All three fields are
+ * populated from real API responses — no estimation, no fallback. `usage` is
+ * `undefined` ONLY when a backend genuinely returned no usage object (which
+ * should never happen on a healthy path: OpenAI-compat and Ollama both echo
+ * usage on every successful completion). Callers that record usage must treat
+ * `undefined` as "no signal this call" and skip — never as zero (zero would
+ * silently undercount a real cost).
+ *
+ * Field names mirror the OpenAI spec (`prompt_tokens` / `completion_tokens` /
+ * `total_tokens`) so the shape is parseable by anything that already speaks
+ * that API. Ollama's `prompt_eval_count` / `eval_count` are mapped at the
+ * provider boundary in completeOllama.
+ */
+export interface LlmUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+/**
+ * The result of every LLM completion. `text` is the trimmed model output;
+ * `usage` is the token accounting from the API response (#246).
+ */
+export interface LlmResult {
+    text: string;
+    usage?: LlmUsage;
+}
 export declare class LlmClient {
     private config;
     private ollamaCallCount;
@@ -125,32 +152,43 @@ export declare class LlmClient {
      * ollama flush stays (provider-gated) — it is a scoring-call-count cadence and
      * scoring is the highest-frequency call, so this is where the flush belongs.
      */
-    completeFast(prompt: string, maxTokens?: number): Promise<string>;
+    completeFast(prompt: string, maxTokens?: number): Promise<LlmResult>;
     /**
      * Reflect-tier completion (nightly reflection). One model serves all phases
      * (#231) — this is a thin wrapper kept for call-site readability.
      */
-    completeReflect(prompt: string, maxTokens?: number): Promise<string>;
+    completeReflect(prompt: string, maxTokens?: number): Promise<LlmResult>;
     /**
      * Distillation-tier completion (session knowledge extraction). One model
      * serves all phases (#231) — thin wrapper kept for call-site readability.
      */
-    completeDistill(prompt: string, maxTokens?: number): Promise<string>;
+    completeDistill(prompt: string, maxTokens?: number): Promise<LlmResult>;
     /**
      * Classification-tier completion (memory tag classification). One model
      * serves all phases (#231) — thin wrapper kept for call-site readability.
      */
-    completeClassify(prompt: string, maxTokens?: number): Promise<string>;
+    completeClassify(prompt: string, maxTokens?: number): Promise<LlmResult>;
     private complete;
     private completeOnce;
     /**
      * Claude CLI: shell out to `claude -p` for subscription users.
      * No API key needed — uses CC's authenticated session.
+     *
+     * Token usage (#246): the claude CLI JSON output does not carry a token
+     * usage field, so this path returns `usage: undefined`. The CLI is billed
+     * by Claude subscription, not per-token — there is nothing to meter. The
+     * fair-use cap therefore never trips on a claude-cli install, which is the
+     * correct outcome (no meterable cost to defend against).
      */
     private completeClaude;
     /**
      * Ollama: use /api/generate with think:false (important for qwen3.5 models).
      * num_ctx is read from config (one value, all phases — #231; default 8192).
+     *
+     * Token usage (#246): the FINAL streamed chunk carries the per-request
+     * accounting as `prompt_eval_count` (input) + `eval_count` (output). Earlier
+     * chunks have null/zero — only the terminal chunk is meaningful, so we keep
+     * updating as chunks arrive and the last one wins.
      */
     private completeOllama;
     /**
@@ -166,11 +204,21 @@ export declare class LlmClient {
     /**
      * Anthropic Messages API (/v1/messages).
      * Auth via x-api-key header.
+     *
+     * Token usage (#246): Anthropic's response carries `usage.input_tokens` +
+     * `usage.output_tokens`. Mapped to the OpenAI-spec field names so downstream
+     * accounting is uniform across providers.
      */
     private completeAnthropic;
     /**
      * OpenAI-compatible /v1/chat/completions (works for OpenAI, OpenRouter, etc).
      * enableThinking is read from config here (one value, all phases — #231).
+     *
+     * Token usage (#246): the OpenAI spec's `usage` object is always present on
+     * a successful completion — `prompt_tokens` / `completion_tokens` /
+     * `total_tokens`. The MLX gateway emits the same shape (verified v0.31.3).
+     * Parsed verbatim; absent only on a non-conforming endpoint, in which case
+     * `usage` stays undefined (no signal, never a fabricated zero).
      */
     private completeOpenAiCompat;
 }

package/dist/llm.js

@@ -365,6 +365,12 @@ class LlmClient {
     /**
      * Claude CLI: shell out to `claude -p` for subscription users.
      * No API key needed — uses CC's authenticated session.
+     *
+     * Token usage (#246): the claude CLI JSON output does not carry a token
+     * usage field, so this path returns `usage: undefined`. The CLI is billed
+     * by Claude subscription, not per-token — there is nothing to meter. The
+     * fair-use cap therefore never trips on a claude-cli install, which is the
+     * correct outcome (no meterable cost to defend against).
      */
     async completeClaude(model, prompt, timeoutMs) {
         const { execSync } = require("node:child_process");
@@ -375,7 +381,7 @@ class LlmClient {
             if (data.is_error) {
                 throw new Error(`Claude CLI error: ${data.result}`);
             }
-            return (data.result ?? "").trim();
+            return { text: (data.result ?? "").trim() };
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -388,6 +394,11 @@ class LlmClient {
     /**
      * Ollama: use /api/generate with think:false (important for qwen3.5 models).
      * num_ctx is read from config (one value, all phases — #231; default 8192).
+     *
+     * Token usage (#246): the FINAL streamed chunk carries the per-request
+     * accounting as `prompt_eval_count` (input) + `eval_count` (output). Earlier
+     * chunks have null/zero — only the terminal chunk is meaningful, so we keep
+     * updating as chunks arrive and the last one wins.
      */
     async completeOllama(model, prompt, maxTokens, timeoutMs) {
         const url = `${this.config.baseUrl.replace(/\/$/, "")}/api/generate`;
@@ -418,8 +429,13 @@ class LlmClient {
             }
             throw new Error(`Ollama error ${resp.status}: ${text}`);
         }
-        // Collect streamed response chunks
+        // Collect streamed response chunks. The terminal chunk carries the token
+        // accounting (`prompt_eval_count` / `eval_count`); earlier chunks have
+        // null. Track the latest values so the final ones win (mirrors the official
+        // ollama-js streaming parser).
         let result = "";
+        let promptTokens;
+        let completionTokens;
         const reader = resp.body?.getReader();
         if (!reader)
             throw new Error("No response body");
@@ -436,11 +452,26 @@ class LlmClient {
                     const data = JSON.parse(line);
                     if (data.response)
                         result += data.response;
+                    // Token accounting — only present on the terminal chunk. Keep the last
+                    // non-null value; missing on both → usage stays undefined (no signal).
+                    if (typeof data.prompt_eval_count === "number") {
+                        promptTokens = data.prompt_eval_count;
+                    }
+                    if (typeof data.eval_count === "number") {
+                        completionTokens = data.eval_count;
+                    }
                 }
                 catch { /* skip malformed lines */ }
             }
         }
-        return result.trim();
+        const usage = promptTokens !== undefined && completionTokens !== undefined
+            ? {
+                prompt_tokens: promptTokens,
+                completion_tokens: completionTokens,
+                total_tokens: promptTokens + completionTokens,
+            }
+            : undefined;
+        return { text: result.trim(), usage };
     }
     /**
      * Flush ollama's accumulated memory: unload the model (keep_alive:0) so the
@@ -472,6 +503,10 @@ class LlmClient {
     /**
      * Anthropic Messages API (/v1/messages).
      * Auth via x-api-key header.
+     *
+     * Token usage (#246): Anthropic's response carries `usage.input_tokens` +
+     * `usage.output_tokens`. Mapped to the OpenAI-spec field names so downstream
+     * accounting is uniform across providers.
      */
     async completeAnthropic(model, prompt, maxTokens, timeoutMs) {
         const baseUrl = this.config.baseUrl.replace(/\/$/, "");
@@ -499,11 +534,26 @@ class LlmClient {
         }
         const data = (await resp.json());
         const textBlock = data.content?.find((c) => c.type === "text");
-        return (textBlock?.text ?? "").trim();
+        const inT = data.usage?.input_tokens;
+        const outT = data.usage?.output_tokens;
+        const usage = typeof inT === "number" && typeof outT === "number"
+            ? {
+                prompt_tokens: inT,
+                completion_tokens: outT,
+                total_tokens: inT + outT,
+            }
+            : undefined;
+        return { text: (textBlock?.text ?? "").trim(), usage };
     }
     /**
      * OpenAI-compatible /v1/chat/completions (works for OpenAI, OpenRouter, etc).
      * enableThinking is read from config here (one value, all phases — #231).
+     *
+     * Token usage (#246): the OpenAI spec's `usage` object is always present on
+     * a successful completion — `prompt_tokens` / `completion_tokens` /
+     * `total_tokens`. The MLX gateway emits the same shape (verified v0.31.3).
+     * Parsed verbatim; absent only on a non-conforming endpoint, in which case
+     * `usage` stays undefined (no signal, never a fabricated zero).
      */
     async completeOpenAiCompat(model, prompt, maxTokens, timeoutMs) {
         const baseUrl = this.config.baseUrl.replace(/\/$/, "");
@@ -547,7 +597,17 @@ class LlmClient {
             throw new Error(`LLM API error ${resp.status}: ${text}`);
         }
         const data = (await resp.json());
-        return (data.choices?.[0]?.message?.content ?? "").trim();
+        const u = data.usage;
+        const usage = typeof u?.prompt_tokens === "number" &&
+            typeof u?.completion_tokens === "number" &&
+            typeof u?.total_tokens === "number"
+            ? {
+                prompt_tokens: u.prompt_tokens,
+                completion_tokens: u.completion_tokens,
+                total_tokens: u.total_tokens,
+            }
+            : undefined;
+        return { text: (data.choices?.[0]?.message?.content ?? "").trim(), usage };
     }
 }
 exports.LlmClient = LlmClient;

package/dist/mcp-server.js

@@ -546,6 +546,11 @@ async function startServer(options = {}) {
     console.log(authToken
         ? `[hicortex] Bearer token auth enabled`
         : `[hicortex] No auth token configured — remote access DISABLED (localhost only). Run init to generate a token.`);
+    // Root → dashboard redirect (#249). Registered BEFORE the auth middleware so
+    // the redirect itself is public — it carries no data; the destination
+    // /dashboard has its own shell-exemption pattern. Gives the console one entry
+    // point: http://<host>:8787/ → /dashboard.
+    app.get("/", (_req, res) => res.redirect("/dashboard"));
     app.use((0, viz_js_1.createAuthMiddleware)(authToken));
     // SSE transport management — each connection gets its own McpServer instance
     const transports = new Map();

package/dist/nightly.d.ts

@@ -25,4 +25,11 @@ export declare function runNightly(options?: {
      * capture-only). Uniform across client + server/co-located.
      */
     watchdog?: boolean;
+    /**
+     * Consolidate-only mode (hosted service, #110): skip capture entirely, run
+     * consolidation only. The hosted consolidation timer uses this so per-tenant
+     * nightly runs don't ingest the operator's local sessions into the tenant's
+     * DB — the tenant's agents push via /distill; the server only consolidates.
+     */
+    consolidateOnly?: boolean;
 }): Promise<void>;