@remnic/core 9.69.39 → 9.69.41

package/src/index.ts

@@ -1224,6 +1224,7 @@ export {
 
 export {
   FallbackLlmClient,
+  FallbackLlmClient as TaskLlmClient,
   type FallbackLlmOptions,
   type FallbackLlmResponse,
   type FallbackLlmRuntimeContext,

package/src/local-llm-config.ts

@@ -2,7 +2,7 @@ import { coerceNumber } from "./connectors/coerce.js";
 import { parseBackgroundGeneration } from "./background-generation-config.js";
 import type { BackgroundGenerationConfig } from "./background-generation-config.js";
 import { readEnvVar } from "./runtime/env.js";
-
+import { parseTaskLlmConfig } from "./task-llm-config.js";
 export interface LocalLlmConfig {
   // Local LLM Provider (v2.1)
   localLlmEnabled: boolean;
@@ -17,14 +17,17 @@ export interface LocalLlmConfig {
   /** If false, do not send Authorization header even when localLlmApiKey is set. */
   localLlmAuthHeader: boolean;
   localLlmFallback: boolean;
+  taskLlmFallback?: boolean;
   /** Optional home directory override for local LLM helpers (LM Studio settings, CLI PATH). */
   localLlmHomeDir?: string;
   /** Optional absolute path to LMS CLI binary (preferred over auto-detection). */
   localLmsCliPath?: string;
   /** Optional bin directory prepended to PATH for LMS CLI execution. */
   localLmsBinDir?: string;
-  /** Hard timeout for local LLM and gateway fallback requests (ms). */
+  /** Hard timeout for local LLM requests (ms). Legacy alias for the task-chain timeout when `taskLlmTimeoutMs` is absent. */
   localLlmTimeoutMs: number;
+  /** Timeout for the gateway/task LLM chain (ms). */
+  taskLlmTimeoutMs?: number;
   /** Max context window for local LLM (override auto-detection). Set lower if your LLM server defaults to smaller contexts. */
   localLlmMaxContext?: number;
 }
@@ -33,11 +36,6 @@ export type LocalLlmParseResult = LocalLlmConfig & {
   backgroundGeneration?: BackgroundGenerationConfig;
 };
 
-function parseLocalLlmTimeoutMs(value: unknown): number {
-  const coerced = coerceNumber(value);
-  if (coerced === undefined) return 180_000;
-  return Math.min(86_400_000, Math.max(1, Math.floor(coerced)));
-}
 
 function parseLocalLlmMaxContext(value: unknown): number | undefined {
   if (value === undefined || value === null) return undefined;
@@ -70,8 +68,9 @@ export function parseLocalLlmConfig(
   localLlmApiKeyEnv: string | undefined,
   resolveEnvVars: (value: string) => string,
 ): LocalLlmParseResult {
+  const taskLlm = parseTaskLlmConfig(cfg);
   return {
-    backgroundGeneration: parseBackgroundGeneration(cfg),
+    backgroundGeneration: parseBackgroundGeneration(cfg, resolveEnvVars),
     localLlmEnabled: cfg.localLlmEnabled === true || cfg.localLlmEnabled === "true",
     localLlmUrl:
       typeof cfg.localLlmUrl === "string" && cfg.localLlmUrl.length > 0
@@ -90,7 +89,8 @@ export function parseLocalLlmConfig(
     localLlmApiKeyEnv,
     localLlmHeaders: copyStringRecord(cfg.localLlmHeaders),
     localLlmAuthHeader: cfg.localLlmAuthHeader !== false,
-    localLlmFallback: cfg.localLlmFallback !== false,
+    localLlmFallback: taskLlm.fallback,
+    taskLlmFallback: taskLlm.fallback,
     localLlmHomeDir:
       typeof cfg.localLlmHomeDir === "string" && cfg.localLlmHomeDir.length > 0
         ? cfg.localLlmHomeDir
@@ -103,7 +103,8 @@ export function parseLocalLlmConfig(
       typeof cfg.localLmsBinDir === "string" && cfg.localLmsBinDir.length > 0
         ? cfg.localLmsBinDir
         : undefined,
-    localLlmTimeoutMs: parseLocalLlmTimeoutMs(cfg.localLlmTimeoutMs),
+    localLlmTimeoutMs: taskLlm.localTimeoutMs,
+    taskLlmTimeoutMs: taskLlm.timeoutMs,
     localLlmMaxContext: parseLocalLlmMaxContext(cfg.localLlmMaxContext),
   };
 }

package/src/local-llm-headers-timeout.test.ts

@@ -12,6 +12,7 @@ import {
 } from "undici";
 
 import { LocalLlmClient } from "./local-llm.js";
+import { classifyAnalysisProviderError } from "./activity/timeline/analysis-provider.js";
 import { ChatTransport } from "./local-llm-transport.js";
 import { initLogger, resetLogger } from "./logger.js";
 import type { PluginConfig } from "./types.js";
@@ -553,3 +554,32 @@ test("sensitive local requests do not log provider error bodies", { concurrency:
     await dispatcherOf(client).close();
   }
 });
+
+test("failureDiag preserves a 429 rate-limit failure cause (issue #2891)", { concurrency: false }, async () => {
+  const original = globalThis.fetch;
+  globalThis.fetch = (async () =>
+    new Response(JSON.stringify({ error: { message: "rate limit exceeded" } }), {
+      status: 429,
+      headers: { "content-type": "application/json" },
+    })) as typeof fetch;
+  const client = new LocalLlmClient(createConfig());
+
+  try {
+    primeClient(client);
+    const failureDiag: { lastError?: unknown } = {};
+    assert.equal(
+      await client.chatCompletion(
+        [{ role: "user", content: "test" }],
+        { redactProviderErrors: true, failureDiag },
+      ),
+      null,
+    );
+    const lastError = failureDiag.lastError;
+    assert.ok(lastError instanceof Error, "expected the terminal provider error to survive the request");
+    assert.equal("status" in lastError ? lastError.status : undefined, 429);
+    assert.equal(classifyAnalysisProviderError(lastError), "rate_limited");
+  } finally {
+    globalThis.fetch = original;
+    await dispatcherOf(client).close();
+  }
+});

package/src/local-llm-helpers.ts

@@ -1,4 +1,32 @@
 import { log } from "./logger.js";
+import type { LocalLlmRequestPriority } from "./local-llm.js";
+
+export interface LocalLlmChatCompletionOptions {
+  temperature?: number;
+  maxTokens?: number;
+  responseFormat?: { type: string };
+  timeoutMs?: number;
+  operation?: string;
+  forceDisableThinking?: boolean;
+  disableThinking?: boolean;
+  priority?: LocalLlmRequestPriority;
+  signal?: AbortSignal;
+  redactProviderErrors?: boolean;
+  /** Per-request model; defaults to config.localLlmModel. */
+  model?: string;
+  /**
+   * Optional out-box for the terminal failure cause (issue #2891): on a
+   * failed request the client records the last provider error here so
+   * callers can classify it (e.g. HTTP 429 → rate-limited) in memory
+   * instead of seeing only null. Never logged.
+   */
+  failureDiag?: { lastError?: unknown };
+}
+
+export interface LocalLlmChatCompletionResult {
+  content: string;
+  usage?: { promptTokens: number; completionTokens: number; totalTokens: number };
+}
 export function isAbortError(err: unknown): boolean {
   if (!err || typeof err !== "object") return false;
   const maybe = err as { name?: string; message?: string };

package/src/local-llm.ts

@@ -19,6 +19,8 @@ import {
   normalizeBackendTripReason,
   waitForRetryBackoff,
   SingleFlightProbe,
+  type LocalLlmChatCompletionOptions,
+  type LocalLlmChatCompletionResult,
 } from "./local-llm-helpers.js";
 
 /** Trim trailing slash characters without backtracking regex. */
@@ -226,20 +228,8 @@ export interface LocalModelInfo {
 
 export type LocalLlmRequestPriority = "recall-critical" | "background";
 
-interface LocalLlmChatCompletionOptions {
-  temperature?: number;
-  maxTokens?: number;
-  responseFormat?: { type: string };
-  timeoutMs?: number;
-  operation?: string;
-  forceDisableThinking?: boolean;
-  disableThinking?: boolean;
-  priority?: LocalLlmRequestPriority;
-  signal?: AbortSignal;
-  redactProviderErrors?: boolean;
-  /** Per-request model; defaults to config.localLlmModel. */
-  model?: string;
-}
+// LocalLlmChatCompletionOptions and LocalLlmChatCompletionResult live in
+// local-llm-helpers.ts so this file stays under its size ceiling (#1995).
 interface LocalLlmQueuedRequest {
   messages: Array<{ role: string; content: string }>;
   options: LocalLlmChatCompletionOptions;
@@ -248,11 +238,6 @@ interface LocalLlmQueuedRequest {
   resolve: (value: LocalLlmChatCompletionResult | null) => void;
 }
 
-interface LocalLlmChatCompletionResult {
-  content: string;
-  usage?: { promptTokens: number; completionTokens: number; totalTokens: number };
-}
-
 const LOCAL_LLM_GLOBAL_BACKEND_STATE = "__openclawEngramLocalLlmBackendState";
 
 type LocalLlmBackendState = {
@@ -1165,6 +1150,10 @@ export class LocalLlmClient {
         } else {
           this.consecutive400s = 0;
         }
+        if (options.failureDiag)
+          options.failureDiag.lastError = Object.assign(new Error("local LLM http failure"), {
+            status: response.status,
+          });
         return null;
       }
       this.consecutive400s = 0;

package/src/meetings/config.test.ts

@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import { test } from "node:test";
 
 import { DEFAULT_MEETING_APP_PATTERNS } from "./detect.js";
+import { parseConfig } from "../config.js";
 import { DEFAULT_MEETINGS_CONFIG, parseMeetingsConfig } from "./config.js";
 
 test("absent config is the disabled default with shipped app patterns", () => {
@@ -70,3 +71,60 @@ test("finding 5 — inverted trust thresholds (autoApprove < review) are rejecte
   // still caught (the override interacts with the default).
   assert.throws(() => parseMeetingsConfig({ autoApproveTrust: 0.3 }), /must be >= meetings\.reviewTrust/);
 });
+
+test("fully-specified valid config round-trips unchanged through the canonical parser (#2936)", () => {
+  const full = {
+    enabled: true,
+    appPatterns: ["CustomConf App"],
+    minOverlapMinutes: 5,
+    audioOnlyMinMinutes: 30,
+    mergeGapMinutes: 7,
+    contextDwellSeconds: 60,
+    maxContextChars: 12_000,
+    summaryMode: "review",
+    sourceTrust: 0.9,
+    autoApproveTrust: 0.8,
+    reviewTrust: 0.6,
+  };
+  const cfg = parseMeetingsConfig(full);
+  // Every knob must come back exactly as supplied — no re-normalization,
+  // no silent defaulting of valid values.
+  assert.equal(cfg.enabled, true);
+  assert.deepEqual(cfg.appPatterns, [...DEFAULT_MEETING_APP_PATTERNS, "CustomConf App"]);
+  assert.equal(cfg.minOverlapMinutes, 5);
+  assert.equal(cfg.audioOnlyMinMinutes, 30);
+  assert.equal(cfg.mergeGapMinutes, 7);
+  assert.equal(cfg.contextDwellSeconds, 60);
+  assert.equal(cfg.maxContextChars, 12_000);
+  assert.equal(cfg.summaryMode, "review");
+  assert.equal(cfg.sourceTrust, 0.9);
+  assert.equal(cfg.autoApproveTrust, 0.8);
+  assert.equal(cfg.reviewTrust, 0.6);
+});
+
+test("parseConfig routes meetings through exactly one canonical path — no silent aliases (#2936)", () => {
+  const full = {
+    enabled: true,
+    minOverlapMinutes: 9,
+    summaryMode: "off",
+    sourceTrust: 0.5,
+    autoApproveTrust: 0.5,
+    reviewTrust: 0.5,
+  };
+
+  // The one canonical entrypoint: a top-level `meetings` block.
+  const viaRoot = parseConfig({ meetings: full }).meetings;
+  assert.deepEqual(viaRoot, parseMeetingsConfig(full));
+
+  // No legacy-alias shapes feed the meetings block: anything other than the
+  // top-level `meetings` key must leave the subsystem at its defaults. A new
+  // alias would be a second parsed surface for the same runtime keys and
+  // must not land silently (it would also need schema + docs + snapshot
+  // updates and would flip this assertion).
+  const viaAliasShapes = parseConfig({
+    meeting: full,
+    desktopCapture: { meetings: full },
+    captureCompanions: { meetings: full },
+  }).meetings;
+  assert.deepEqual(viaAliasShapes, parseMeetingsConfig(undefined));
+});

package/src/namespaces/search.test.ts

@@ -21,6 +21,7 @@ class FakeBackend implements SearchBackend {
   strictEmbeds = 0;
   strictCollectionEmbeds: string[] = [];
   disposed = 0;
+  disposeWait: Promise<void> | null = null;
   available = true;
   calls: Array<{
     method: string;
@@ -28,6 +29,7 @@ class FakeBackend implements SearchBackend {
     maxResults: number | undefined;
   }> = [];
   availabilitySignals: Array<AbortSignal | undefined> = [];
+  probeSignals: Array<AbortSignal | undefined> = [];
   probeCalls = 0;
   ensureSignals: Array<AbortSignal | undefined> = [];
   ensureCollections: Array<string | undefined> = [];
@@ -54,8 +56,9 @@ class FakeBackend implements SearchBackend {
       : this.results;
   }
 
-  async probe(): Promise<boolean> {
+  async probe(execution?: SearchExecutionOptions): Promise<boolean> {
     this.probeCalls += 1;
+    this.probeSignals.push(execution?.signal);
     return this.available;
   }
 
@@ -89,6 +92,7 @@ class FakeBackend implements SearchBackend {
 
   async dispose(): Promise<void> {
     this.disposed += 1;
+    await this.disposeWait;
   }
 
   async search(
@@ -470,10 +474,56 @@ test("ensureNamespaceCollection forwards abort signals to backend collection che
   });
 
   assert.equal(state, "present");
+  assert.deepEqual(backend.probeSignals, [controller.signal]);
   assert.deepEqual(backend.ensureSignals, [controller.signal]);
   assert.deepEqual(backend.ensureCollections, ["openclaw-engram--ns-6d61696e"]);
 });
 
+test("disableSearchBackends releases cached namespace backends without recreating search", async () => {
+  const backend = new FakeBackend(false);
+  const router = new NamespaceSearchRouter(
+    config(),
+    { storageFor: async (namespace: string) => ({ dir: `/tmp/remnic/${namespace}` }) },
+    () => backend,
+  );
+
+  assert.equal(await router.ensureNamespaceCollection("main"), "present");
+  await router.disableSearchBackends();
+
+  await router.disableSearchBackends();
+
+  assert.equal(backend.disposed, 1, "repeated runtime disable must not double-dispose the same backend");
+  assert.equal(await router.backendForNamespace("main"), null);
+  assert.equal(await router.ensureNamespaceCollection("main"), "missing");
+  assert.equal(backend.probeCalls, 1, "disabled records must not recreate a concrete backend");
+});
+
+test("clearCache releases evicted namespace backend handles before recreation", async () => {
+  const oldBackend = new FakeBackend(false);
+  const newBackend = new FakeBackend(false);
+  let releaseOldDispose: (() => void) | undefined;
+  oldBackend.disposeWait = new Promise<void>((resolve) => { releaseOldDispose = resolve; });
+  let createCalls = 0;
+  const router = new NamespaceSearchRouter(
+    config(),
+    { storageFor: async (namespace: string) => ({ dir: `/tmp/remnic/${namespace}` }) },
+    () => {
+      createCalls += 1;
+      return createCalls === 1 ? oldBackend : newBackend;
+    },
+  );
+
+  await router.ensureNamespaceCollection("main");
+  router.clearCache();
+  const recreation = router.ensureNamespaceCollection("main");
+  await Promise.resolve();
+  assert.equal(createCalls, 1, "recreation must wait for the evicted handle disposal barrier");
+  releaseOldDispose?.();
+  assert.equal(await recreation, "present");
+  assert.equal(oldBackend.disposed, 1);
+  assert.equal(createCalls, 2);
+});
+
 test("legacy default namespace root auto-creates its base collection (broad root, #1929)", async () => {
   const backend = new FakeBackend(false);
   const router = new NamespaceSearchRouter(

package/src/namespaces/search.ts

@@ -45,6 +45,7 @@ type NamespaceBackendRecord = {
   available: boolean;
   collectionState: CollectionState;
   filtersNestedNamespaces: boolean;
+  disposed: boolean;
 };
 
 export interface NamespaceUpdateResult {
@@ -83,6 +84,7 @@ type BackendRecordOptions = {
 
 export class NamespaceSearchRouter {
   private readonly cache = new Map<string, Promise<NamespaceBackendRecord>>();
+  private readonly pendingDisposals = new Set<Promise<void>>();
 
   constructor(
     private readonly config: PluginConfig,
@@ -344,21 +346,62 @@ export class NamespaceSearchRouter {
     return cachedRecord;
   }
 
+  private trackDisposal(promise: Promise<void>): void {
+    this.pendingDisposals.add(promise);
+    void promise.finally(() => this.pendingDisposals.delete(promise));
+  }
+
+  private async drainPendingDisposals(): Promise<void> {
+    if (this.pendingDisposals.size === 0) return;
+    await Promise.allSettled(this.pendingDisposals);
+  }
+
   /** Clear cached backend records so the next access re-probes availability. */
   clearCache(): void {
+    const pendingRecords = Array.from(this.cache.values());
     this.cache.clear();
+    const disposal = Promise.allSettled(pendingRecords).then(async (settled) => {
+      await Promise.allSettled(
+        settled.flatMap((entry) =>
+          entry.status === "fulfilled" ? [this.disposeRecord(entry.value)] : []),
+      );
+    });
+    this.trackDisposal(disposal);
+  }
+
+  private async disposeRecord(record: NamespaceBackendRecord): Promise<void> {
+    if (record.disposed) return;
+    record.disposed = true;
+    const dispose = (record.backend as { dispose?: () => void | Promise<void> }).dispose;
+    await dispose?.call(record.backend);
   }
 
   /** Release any per-namespace backend handles held by cached records. */
   async dispose(): Promise<void> {
+    await this.drainPendingDisposals();
     const pendingRecords = Array.from(this.cache.values());
     this.cache.clear();
     const settled = await Promise.allSettled(pendingRecords);
+    await Promise.allSettled(
+      settled.flatMap((entry) =>
+        entry.status === "fulfilled" ? [this.disposeRecord(entry.value)] : []),
+    );
+  }
+
+  /**
+   * Disable namespace search for this runtime while retaining the resolved
+   * records as unavailable/missing. This releases concrete QMD/daemon handles
+   * without letting later reads recreate a search backend after the root path
+   * has been switched to NoopSearchBackend for a missing collection.
+   */
+  async disableSearchBackends(): Promise<void> {
+    const settled = await Promise.allSettled(this.cache.values());
     await Promise.allSettled(
       settled.flatMap((entry) => {
         if (entry.status !== "fulfilled") return [];
-        const dispose = (entry.value.backend as { dispose?: () => void | Promise<void> }).dispose;
-        return dispose ? [dispose.call(entry.value.backend)] : [];
+        entry.value.available = false;
+        entry.value.collectionState = "missing";
+        return [this.disposeRecord(entry.value)];
       }),
     );
   }
@@ -367,6 +410,7 @@ export class NamespaceSearchRouter {
     namespace: string,
     execution?: SearchExecutionOptions,
   ): Promise<NamespaceBackendRecord> {
+    await this.drainPendingDisposals();
     const key = namespace.trim() || this.config.defaultNamespace;
     const existing = this.cache.get(key);
     if (existing) return await existing;
@@ -412,7 +456,7 @@ export class NamespaceSearchRouter {
     try {
       const availabilityProbe =
         options.autoCreateCollection || typeof backend.checkAvailability !== "function"
-          ? backend.probe()
+          ? backend.probe(execution)
           : backend.checkAvailability({ signal: execution?.signal });
       const available = await awaitWithAbort(availabilityProbe, execution?.signal).catch((error) => {
         if (error instanceof NamespaceSearchAbortError && !options.abortAsUnavailable) {
@@ -453,6 +497,7 @@ export class NamespaceSearchRouter {
         available,
         collectionState,
         filtersNestedNamespaces,
+        disposed: false,
       };
     } catch (error) {
       const dispose = (backend as { dispose?: () => void | Promise<void> }).dispose;