@gamaze/hicortex 0.16.3 → 0.16.4

package/dist/config-read.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Strict config readers for primitive values. Pure functions — no LlmConfig
+ * dependency — shared by the nightly preflight knobs and the distill-tier
+ * overlay (llm.ts / mcp-server.ts).
+ *
+ * The point is to reject wrong-typed config values AT THE BOUNDARY (disk →
+ * runtime) with a warn, rather than casting them straight through. The trap
+ * these guard: a JSON slip like `"enableThinking": "false"` (string,
+ * not boolean) casts to a truthy value downstream — for the Qwen chat template
+ * a non-empty string flips thinking ON, which is precisely the failure the key
+ * exists to prevent, with no error anywhere. Same class as the #225
+ * preflight-knob validation.
+ */
+/**
+ * Read a positive finite number from a config object. Returns `def` when the
+ * key is absent OR present-but-invalid (with a warn in the latter case).
+ */
+export declare function readPositiveConfig(config: Record<string, unknown>, key: string, def: number): number;
+/**
+ * Read a strict boolean from a config object. Returns the boolean when valid,
+ * `undefined` when the key is absent OR present-but-not-a-boolean (with a warn
+ * in the latter case). Never coerces — `"false"` (string) is rejected, not
+ * treated as truthy.
+ */
+export declare function readStrictBoolean(config: Record<string, unknown>, key: string): boolean | undefined;

package/dist/config-read.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Strict config readers for primitive values. Pure functions — no LlmConfig
+ * dependency — shared by the nightly preflight knobs and the distill-tier
+ * overlay (llm.ts / mcp-server.ts).
+ *
+ * The point is to reject wrong-typed config values AT THE BOUNDARY (disk →
+ * runtime) with a warn, rather than casting them straight through. The trap
+ * these guard: a JSON slip like `"enableThinking": "false"` (string,
+ * not boolean) casts to a truthy value downstream — for the Qwen chat template
+ * a non-empty string flips thinking ON, which is precisely the failure the key
+ * exists to prevent, with no error anywhere. Same class as the #225
+ * preflight-knob validation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPositiveConfig = readPositiveConfig;
+exports.readStrictBoolean = readStrictBoolean;
+/**
+ * Read a positive finite number from a config object. Returns `def` when the
+ * key is absent OR present-but-invalid (with a warn in the latter case).
+ */
+function readPositiveConfig(config, key, def) {
+    const v = config[key];
+    if (v === undefined)
+        return def;
+    if (typeof v === "number" && Number.isFinite(v) && v > 0)
+        return v;
+    console.warn(`[hicortex] config "${key}" = ${String(v)} is not a positive finite number — using default ${def}.`);
+    return def;
+}
+/**
+ * Read a strict boolean from a config object. Returns the boolean when valid,
+ * `undefined` when the key is absent OR present-but-not-a-boolean (with a warn
+ * in the latter case). Never coerces — `"false"` (string) is rejected, not
+ * treated as truthy.
+ */
+function readStrictBoolean(config, key) {
+    const v = config[key];
+    if (v === undefined)
+        return undefined;
+    if (typeof v === "boolean")
+        return v;
+    console.warn(`[hicortex] config "${key}" = ${String(v)} is not a boolean — ignored.`);
+    return undefined;
+}

package/dist/llm.d.ts

@@ -25,6 +25,10 @@ export interface LlmConfig {
     distillBaseUrl?: string;
     distillApiKey?: string;
     distillProvider?: string;
+    /** Max output tokens for all phases (distill/reflect/classify/scoring). Heavy phases fall back to 8192, scoring to 2048. */
+    maxTokens?: number;
+    /** Toggle thinking on the openai-compat path for the heavy phases. Absent = no kwarg sent. */
+    enableThinking?: boolean;
     /** Optional separate endpoint for reflect-tier LLM (e.g. remote Ollama with larger model). */
     reflectBaseUrl?: string;
     reflectApiKey?: string;
@@ -87,6 +91,21 @@ export type { ModelTierOverride } from "./types.js";
  * a dead score apiKey/provider under an ollama base.
  */
 export declare function applyModelsBlock(saved: Record<string, unknown> | null): Record<string, unknown> | null;
+/**
+ * Validate + copy the heavy-phase tuning keys (#220: maxTokens + enableThinking)
+ * from the saved disk config onto a runtime LlmConfig. Called by BOTH LlmConfig
+ * construction sites — the daemon in mcp-server.ts (runs distill) AND
+ * resolveSavedLlmConfig below (the nightly runs reflect + classify) — so every
+ * process that runs a heavy phase honors the keys, and a future site calling
+ * this inherits them by construction.
+ *
+ * Both keys are optional; absent = call-site defaults (8192 / thinking kwarg
+ * omitted). Wrong-typed values warn and are dropped (readPositiveConfig /
+ * readStrictBoolean) — notably a JSON slip `"enableThinking": "false"` (string)
+ * is rejected rather than coerced to truthy thinking-on, which would silently
+ * invert the fix this key exists to apply.
+ */
+export declare function applyTierTuningOverlay(llmConfig: LlmConfig, savedConfig: Record<string, unknown> | null | undefined): void;
 /**
  * Resolve an LlmConfig from a saved ~/.hicortex/config.json object.
  *

package/dist/llm.js

@@ -18,6 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LlmClient = exports.RateLimitError = exports.resolveLlmConfigForCC = void 0;
 exports.resolveExplicitLlmConfig = resolveExplicitLlmConfig;
 exports.applyModelsBlock = applyModelsBlock;
+exports.applyTierTuningOverlay = applyTierTuningOverlay;
 exports.resolveSavedLlmConfig = resolveSavedLlmConfig;
 exports.resolveClassifyProbeTarget = resolveClassifyProbeTarget;
 exports.findClaudeBinary = findClaudeBinary;
@@ -25,6 +26,7 @@ exports.claudeCliConfig = claudeCliConfig;
 exports.probeOllama = probeOllama;
 exports.probeOllamaModel = probeOllamaModel;
 exports.resolveDistillFallback = resolveDistillFallback;
+const config_read_js_1 = require("./config-read.js");
 /**
  * Resolve LLM configuration from explicit config-file overrides or
  * Hicortex-specific env vars only. Returns null when nothing explicit is set.
@@ -182,6 +184,31 @@ function applyModelsBlock(saved) {
     }
     return { ...saved, ...mapped };
 }
+/**
+ * Validate + copy the heavy-phase tuning keys (#220: maxTokens + enableThinking)
+ * from the saved disk config onto a runtime LlmConfig. Called by BOTH LlmConfig
+ * construction sites — the daemon in mcp-server.ts (runs distill) AND
+ * resolveSavedLlmConfig below (the nightly runs reflect + classify) — so every
+ * process that runs a heavy phase honors the keys, and a future site calling
+ * this inherits them by construction.
+ *
+ * Both keys are optional; absent = call-site defaults (8192 / thinking kwarg
+ * omitted). Wrong-typed values warn and are dropped (readPositiveConfig /
+ * readStrictBoolean) — notably a JSON slip `"enableThinking": "false"` (string)
+ * is rejected rather than coerced to truthy thinking-on, which would silently
+ * invert the fix this key exists to apply.
+ */
+function applyTierTuningOverlay(llmConfig, savedConfig) {
+    if (!savedConfig)
+        return;
+    if (savedConfig.maxTokens !== undefined) {
+        llmConfig.maxTokens = (0, config_read_js_1.readPositiveConfig)(savedConfig, "maxTokens", 8192);
+    }
+    const thinking = (0, config_read_js_1.readStrictBoolean)(savedConfig, "enableThinking");
+    if (thinking !== undefined) {
+        llmConfig.enableThinking = thinking;
+    }
+}
 /**
  * Resolve an LlmConfig from a saved ~/.hicortex/config.json object.
  *
@@ -232,6 +259,12 @@ function resolveSavedLlmConfig(savedConfig, findBinary = findClaudeBinary) {
         llmConfig.reflectApiKey = savedConfig.reflectApiKey ?? llmConfig.apiKey;
         llmConfig.reflectProvider = savedConfig.reflectProvider ?? llmConfig.provider;
     }
+    // Heavy-phase tuning (#220: maxTokens + enableThinking). The nightly runs
+    // reflect + classify (consolidation), the daemon runs distill — both need the
+    // keys, so the overlay is applied at both construction sites.
+    if (llmConfig) {
+        applyTierTuningOverlay(llmConfig, savedConfig);
+    }
     // Optional classify tier (memory tag classification). Same overlay pattern
     // as distillModel/distillBaseUrl: when absent, completeClassify falls back
     // to the reflect tier — zero behavior change for existing installs.
@@ -504,28 +537,39 @@ class LlmClient {
     /**
      * Fast-tier completion (importance scoring, simple tasks).
      */
-    async completeFast(prompt, maxTokens = 2048) {
-        return this.complete(this.config.model, prompt, maxTokens, 600_000);
+    async completeFast(prompt, maxTokens) {
+        const tokens = maxTokens ?? this.config.maxTokens ?? 2048;
+        // No `thinking` arg: scoring is excluded from the thinking toggle (it's the
+        // local fast tier; on ollama it's think:false regardless). completeFast never
+        // threads thinking, so chat_template_kwargs is never sent for scoring.
+        return this.complete(this.config.model, prompt, tokens, 600_000);
     }
     /**
      * Reflect-tier completion (nightly reflection, needs reasoning).
      * Routes to reflectBaseUrl/reflectProvider if configured (e.g. remote Ollama with larger model).
      */
-    async completeReflect(prompt, maxTokens = 8192) {
+    async completeReflect(prompt, maxTokens) {
+        const tokens = maxTokens ?? this.config.maxTokens ?? 8192;
+        const thinking = this.config.enableThinking;
         if (this.config.reflectBaseUrl) {
-            return this.completeWithOverride(this.config.reflectBaseUrl, this.config.reflectApiKey ?? this.config.apiKey, this.config.reflectProvider ?? this.config.provider, this.config.reflectModel, prompt, maxTokens, 900_000);
+            return this.completeWithOverride(this.config.reflectBaseUrl, this.config.reflectApiKey ?? this.config.apiKey, this.config.reflectProvider ?? this.config.provider, this.config.reflectModel, prompt, tokens, 900_000, thinking);
         }
-        return this.complete(this.config.reflectModel, prompt, maxTokens, 900_000);
+        return this.complete(this.config.reflectModel, prompt, tokens, 900_000, thinking);
     }
     /**
      * Distillation-tier completion (session knowledge extraction).
      * Routes to distillBaseUrl/distillProvider if configured (e.g. remote Ollama with faster model).
      */
-    async completeDistill(prompt, maxTokens = 2048) {
+    async completeDistill(prompt, maxTokens) {
+        const tokens = maxTokens ?? this.config.maxTokens ?? 8192;
+        // enableThinking is threaded explicitly (not read inside the shared
+        // completeOpenAiCompat) so the chat_template_kwargs kwarg is scoped to the
+        // heavy phases — distill/reflect/classify — and never reaches scoring. See #220.
+        const thinking = this.config.enableThinking;
         if (this.config.distillBaseUrl) {
-            return this.completeWithOverride(this.config.distillBaseUrl, this.config.distillApiKey ?? this.config.apiKey, this.config.distillProvider ?? this.config.provider, this.config.distillModel ?? this.config.model, prompt, maxTokens, 900_000);
+            return this.completeWithOverride(this.config.distillBaseUrl, this.config.distillApiKey ?? this.config.apiKey, this.config.distillProvider ?? this.config.provider, this.config.distillModel ?? this.config.model, prompt, tokens, 900_000, thinking);
         }
-        return this.complete(this.config.distillModel ?? this.config.model, prompt, maxTokens, 900_000);
+        return this.complete(this.config.distillModel ?? this.config.model, prompt, tokens, 900_000, thinking);
     }
     /**
      * Classification-tier completion (memory tag classification).
@@ -538,33 +582,35 @@ class LlmClient {
      *   - Only classifyModel set → the classify model on the reflect endpoint
      *     when one is configured, else on the base endpoint.
      */
-    async completeClassify(prompt, maxTokens = 8192) {
+    async completeClassify(prompt, maxTokens) {
+        const tokens = maxTokens ?? this.config.maxTokens ?? 8192;
+        const thinking = this.config.enableThinking;
         if (!this.config.classifyModel && !this.config.classifyBaseUrl) {
-            return this.completeReflect(prompt, maxTokens);
+            return this.completeReflect(prompt, tokens);
         }
         const model = this.config.classifyModel ?? this.config.reflectModel;
         if (this.config.classifyBaseUrl) {
-            return this.completeWithOverride(this.config.classifyBaseUrl, this.config.classifyApiKey ?? this.config.apiKey, this.config.classifyProvider ?? this.config.provider, model, prompt, maxTokens, 900_000);
+            return this.completeWithOverride(this.config.classifyBaseUrl, this.config.classifyApiKey ?? this.config.apiKey, this.config.classifyProvider ?? this.config.provider, model, prompt, tokens, 900_000, thinking);
         }
         if (this.config.reflectBaseUrl) {
-            return this.completeWithOverride(this.config.reflectBaseUrl, this.config.reflectApiKey ?? this.config.apiKey, this.config.reflectProvider ?? this.config.provider, model, prompt, maxTokens, 900_000);
+            return this.completeWithOverride(this.config.reflectBaseUrl, this.config.reflectApiKey ?? this.config.apiKey, this.config.reflectProvider ?? this.config.provider, model, prompt, tokens, 900_000, thinking);
         }
-        return this.complete(model, prompt, maxTokens, 900_000);
+        return this.complete(model, prompt, tokens, 900_000, thinking);
     }
     /**
      * Complete with overridden baseUrl/apiKey/provider (used for reflect tier with separate endpoint).
      * Creates a temporary LlmClient to avoid mutating shared config under concurrent calls.
      */
-    async completeWithOverride(baseUrl, apiKey, provider, model, prompt, maxTokens, timeoutMs) {
+    async completeWithOverride(baseUrl, apiKey, provider, model, prompt, maxTokens, timeoutMs, thinking) {
         const tempClient = new LlmClient({
             ...this.config,
             baseUrl,
             apiKey,
             provider,
         });
-        return tempClient.complete(model, prompt, maxTokens, timeoutMs);
+        return tempClient.complete(model, prompt, maxTokens, timeoutMs, thinking);
     }
-    async complete(model, prompt, maxTokens, timeoutMs) {
+    async complete(model, prompt, maxTokens, timeoutMs, thinking) {
         if (this.isRateLimited) {
             throw new RateLimitError(this.rateLimitedUntil - Date.now());
         }
@@ -572,7 +618,7 @@ class LlmClient {
         let lastErr;
         for (let attempt = 0; attempt <= retryDelays.length; attempt++) {
             try {
-                return await this.completeOnce(model, prompt, maxTokens, timeoutMs);
+                return await this.completeOnce(model, prompt, maxTokens, timeoutMs, thinking);
             }
             catch (err) {
                 lastErr = err instanceof Error ? err : new Error(String(err));
@@ -589,7 +635,7 @@ class LlmClient {
         }
         throw lastErr;
     }
-    async completeOnce(model, prompt, maxTokens, timeoutMs) {
+    async completeOnce(model, prompt, maxTokens, timeoutMs, thinking) {
         if (this.config.provider === "claude-cli") {
             return this.completeClaude(model, prompt, timeoutMs);
         }
@@ -599,7 +645,10 @@ class LlmClient {
         if (this.config.provider === "anthropic") {
             return this.completeAnthropic(model, prompt, maxTokens, timeoutMs);
         }
-        return this.completeOpenAiCompat(model, prompt, maxTokens, timeoutMs);
+        // thinking is threaded from each heavy phase (distill/reflect/classify), so
+        // the kwarg is emitted for those tiers on the openai-compat path; completeFast
+        // (scoring) never passes it (PR #227 review F1).
+        return this.completeOpenAiCompat(model, prompt, maxTokens, timeoutMs, thinking);
     }
     /**
      * Claude CLI: shell out to `claude -p` for subscription users.
@@ -711,7 +760,7 @@ class LlmClient {
     /**
      * OpenAI-compatible /v1/chat/completions (works for OpenAI, OpenRouter, etc).
      */
-    async completeOpenAiCompat(model, prompt, maxTokens, timeoutMs) {
+    async completeOpenAiCompat(model, prompt, maxTokens, timeoutMs, thinking) {
         const baseUrl = this.config.baseUrl.replace(/\/$/, "");
         // Some providers include the API version in the base URL already
         const hasVersion = /\/v\d+\/?$/.test(baseUrl);
@@ -724,14 +773,24 @@ class LlmClient {
         if (this.config.apiKey) {
             headers["Authorization"] = `Bearer ${this.config.apiKey}`;
         }
+        // Qwen3 thinking mode: when on, the model can burn the whole token budget on
+        // an unclosed <think> block and emit nothing (probed 2026-08-04). `thinking`
+        // is threaded here ONLY from completeDistill, so the kwarg is emitted solely
+        // for the distill tier — reflect/classify/fast never send it (PR #227 F1).
+        // mlx-lm forwards chat_template_kwargs to the chat template (mirrors the
+        // ollama path's think:false). See #220.
+        const body = {
+            model,
+            messages: [{ role: "user", content: prompt }],
+            max_tokens: maxTokens,
+        };
+        if (thinking !== undefined) {
+            body.chat_template_kwargs = { enable_thinking: thinking };
+        }
         const resp = await fetch(url, {
             method: "POST",
             headers,
-            body: JSON.stringify({
-                model,
-                messages: [{ role: "user", content: prompt }],
-                max_tokens: maxTokens,
-            }),
+            body: JSON.stringify(body),
             signal: AbortSignal.timeout(timeoutMs),
         });
         if (resp.status === 429)

package/dist/mcp-server.js

@@ -424,6 +424,10 @@ async function startServer(options = {}) {
             llmConfig.distillApiKey = savedConfig.distillApiKey ?? llmConfig.apiKey;
             llmConfig.distillProvider = savedConfig.distillProvider ?? llmConfig.provider;
         }
+        // Heavy-phase tuning (#220): maxTokens + enableThinking, validated + copied
+        // via the shared overlay (also applied in resolveSavedLlmConfig for the
+        // nightly's reflect + classify). Wrong-typed values warn + drop.
+        (0, llm_js_1.applyTierTuningOverlay)(llmConfig, savedConfig);
         // Apply separate reflect endpoint if configured (e.g. remote Ollama with larger model)
         if (savedConfig?.reflectBaseUrl) {
             llmConfig.reflectBaseUrl = savedConfig.reflectBaseUrl;

package/dist/nightly.js

@@ -55,6 +55,7 @@ try {
 }
 catch { }
 const db_js_1 = require("./db.js");
+const config_read_js_1 = require("./config-read.js");
 const llm_js_1 = require("./llm.js");
 const embedder_js_1 = require("./embedder.js");
 const storage = __importStar(require("./storage.js"));
@@ -187,27 +188,9 @@ function captureLockWaitMs() {
     const env = Number(process.env.HICORTEX_CAPTURE_LOCK_WAIT_MS);
     return Number.isFinite(env) && env >= 0 ? env : CAPTURE_LOCK_WAIT_MS;
 }
-/**
- * Read a positive finite number from a nightly config key, falling back to
- * `def` when the key is absent/invalid. Used by the pre-flight retry knobs
- * (#163): tuning knobs live in config, never hardcoded (cf. decayHalfLifeDays,
- * recallMinSimilarity).
- *
- * A value that is PRESENT but rejected (non-number, non-finite, or ≤ 0) warns
- * — e.g. an operator who sets `preflightAttempts: 0` intending "don't retry"
- * would otherwise silently get the default 3. (Single-try is
- * `preflightAttempts: 1`, so there's no functional gap — this just makes the
- * silent coercion visible, consistent with the fail-explicit pattern.)
- */
-function readPositiveConfig(config, key, def) {
-    const v = config[key];
-    if (v === undefined)
-        return def;
-    if (typeof v === "number" && Number.isFinite(v) && v > 0)
-        return v;
-    console.warn(`[hicortex] config "${key}" = ${String(v)} is not a positive finite number — using default ${def}.`);
-    return def;
-}
+// readPositiveConfig moved to ./config-read.ts (shared with the distill-tier
+// overlay in llm.ts / mcp-server.ts). Validates positive-number config knobs
+// at the disk→runtime boundary with a warn-on-rejected-value.
 const NIGHTLY_LOG_MAX_BYTES = 1024 * 1024; // 1 MB — years of normal runs
 /**
  * Keep ~/.hicortex/nightly.log bounded. The launchd plist and systemd unit
@@ -524,9 +507,9 @@ async function runClientNightly(config, dryRun, stateDir = HICORTEX_HOME, recapt
     // elapsed time can exceed it. Not a defect: the capture lock isn't held
     // during the retry and the cursor design is dup-over-loss, so a late success
     // is harmless. Just don't treat 2m45s as a hard wall-clock bound.
-    const PREFLIGHT_TIMEOUT_MS = readPositiveConfig(config, "preflightTimeoutMs", 15_000);
-    const PREFLIGHT_ATTEMPTS = Math.max(1, Math.floor(readPositiveConfig(config, "preflightAttempts", 3)));
-    const PREFLIGHT_RETRY_GAP_MS = readPositiveConfig(config, "preflightRetryGapMs", 60_000);
+    const PREFLIGHT_TIMEOUT_MS = (0, config_read_js_1.readPositiveConfig)(config, "preflightTimeoutMs", 15_000);
+    const PREFLIGHT_ATTEMPTS = Math.max(1, Math.floor((0, config_read_js_1.readPositiveConfig)(config, "preflightAttempts", 3)));
+    const PREFLIGHT_RETRY_GAP_MS = (0, config_read_js_1.readPositiveConfig)(config, "preflightRetryGapMs", 60_000);
     let reachable = false;
     for (let attempt = 1; attempt <= PREFLIGHT_ATTEMPTS; attempt++) {
         try {

package/dist/types.d.ts

@@ -282,6 +282,27 @@ export interface HicortexConfig {
      * dup-over-loss); just don't treat the nominal sum as a hard bound.
      */
     preflightRetryGapMs?: number;
+    /**
+     * Max output tokens for the LLM phases — distillation, reflection, classification,
+     * and scoring (completeDistill / completeReflect / completeClassify / completeFast).
+     * Default 8192 for the heavy phases, 2048 for scoring (the local fast tier); an
+     * explicit value overrides all of them. A ceiling, not a target: generation stops
+     * at the model's natural end (finish_reason stop), so a higher cap costs no latency
+     * when it finishes early. Read in llm.ts; see #220.
+     */
+    maxTokens?: number;
+    /**
+     * Toggle the model's internal reasoning ("thinking") stream on the openai-compat
+     * path — applies to the heavy phases (distill / reflect / classify) that share an
+     * OpenAI-compatible endpoint (e.g. a reasoning model served via a local gateway).
+     * Default false. A thinking model with thinking ON can burn the entire token
+     * budget on an unclosed <think> block and emit nothing (probed 2026-08-04). When
+     * set (true or false), completeOpenAiCompat sends
+     * chat_template_kwargs:{enable_thinking}. Threaded structurally from each heavy
+     * phase, so scoring (ollama) never sends it. No effect on the anthropic path.
+     * See #220.
+     */
+    enableThinking?: boolean;
 }
 /** A config-owned life-sphere domain (see HicortexConfig.domains). */
 export interface DomainDef {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.16.3",
+  "version": "0.16.4",
   "description": "Self-learning memory for AI agents — experience captured automatically, distilled into lessons overnight, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {