@remnic/core 9.4.0 → 9.4.2

package/dist/qmd-Db9mOkzB.d.ts

@@ -0,0 +1,330 @@
+import { Q as QmdSearchResult, az as QmdSearchExplain } from './types-ljkd82rn.js';
+import { SearchBackend, SearchExecutionOptions, SearchQueryOptions } from './search/port.js';
+
+declare const QMD_PROBE_TIMEOUT_MS = 8000;
+declare const QMD_PROBE_RETRY_BACKOFF_MS: number[];
+declare const QMD_SUPPORTED_VERSION = "2.5.3";
+/**
+ * Classify a `qmd --version` probe failure so the preflight can distinguish a
+ * slow/overloaded binary (a genuine deadline timeout) from a real
+ * misconfiguration (ENOENT/EACCES — the configured path is missing or not
+ * executable). Only transient failures are retried; missing binaries fail fast.
+ *
+ * Classification keys on STRUCTURED signals, never the error *message*: a
+ * non-zero-exit failure embeds the child's stderr in its message, so scanning
+ * that text for "abort"/"timed out"/"not found" would misclassify a healthy
+ * binary. The structured signals are: `code` (ENOENT/EACCES) for missing; the
+ * `timedOut` flag set by `runCommandWithTimeout` for a genuine timeout; an
+ * AbortError name for a deadline/abort under load. Issue #1841.
+ */
+type QmdProbeFailureKind = "transient" | "missing" | "other";
+declare function classifyProbeFailure(err: unknown): QmdProbeFailureKind;
+declare function parseQmdVersion(version: string | null): QmdVersionTuple | null;
+declare function parseQmdVersionOutput(stdout: string, stderr: string): string | null;
+declare function compareQmdVersions(left: QmdVersionTuple | null, right: QmdVersionTuple | null): number;
+declare function versionAtLeast(current: QmdVersionTuple | null, target: QmdVersionTuple): boolean;
+declare function resolveQmdCapabilities(version: string | null): QmdCapabilities;
+declare function shouldAutoUpgradeQmd(installedVersion: string | null, supportedVersion?: string): boolean;
+declare function getQmdPostInstallProbeTargets(qmdPath: string, qmdPathSource: "configured" | "auto-path" | "auto-fallback"): Array<{
+    qmdPath: string;
+    source: "auto-path" | "auto-fallback";
+}>;
+declare function qmdVersionToString(version: QmdVersionTuple): string;
+
+interface QmdClientOptions {
+    slowLog?: {
+        enabled: boolean;
+        thresholdMs: number;
+    };
+    updateTimeoutMs?: number;
+    updateMinIntervalMs?: number;
+    qmdPath?: string;
+    daemonUrl?: string;
+    daemonRecheckIntervalMs?: number;
+    qmdSupportedVersion?: string;
+    qmdAutoUpgradeEnabled?: boolean;
+    qmdAutoUpgradeCheckIntervalMs?: number;
+    qmdChunkStrategy?: QmdChunkStrategy;
+    qmdCandidateLimit?: number;
+    qmdQueryRerankEnabled?: boolean;
+    qmdIndexName?: string;
+    qmdForceCpu?: boolean;
+    qmdGpuBackend?: "auto" | "metal" | "cuda" | "vulkan" | "false";
+    qmdEmbedParallelism?: number;
+    qmdEmbedModel?: string;
+    qmdRerankModel?: string;
+    qmdGenerateModel?: string;
+    /** Daemon search plan; default "hybrid" preserves lex+vec+hyde. Issue #1335. */
+    qmdSearchStrategy?: QmdSearchStrategy;
+    /** Subprocess fallback command; default "query" keeps LLM expansion. Issue #1335. */
+    qmdSubprocessStrategy?: QmdSubprocessStrategy;
+    /** Override automatic qmd fallback probes; defaults to known install paths. */
+    qmdFallbackPaths?: string[];
+    /** Per-call daemon search timeout in ms; default 8000. Issue #1335. */
+    qmdDaemonTimeoutMs?: number;
+}
+type QmdVersionTuple = [number, number, number];
+type QmdChunkStrategy = "auto" | "regex";
+type QmdStructuredSearchType = "lex" | "vec" | "hyde";
+/**
+ * Daemon search plan. Issue #1335.
+ * - "hybrid" → lex + vec + hyde (DEFAULT — full recall; runs an embedding pass
+ *   plus a HyDE generate pass, which dominates latency on CPU-only models).
+ * - "lex-vec" → lex + vec (drops the expensive HyDE generate leg).
+ * - "lex" → lex only (BM25; fastest, no model inference).
+ */
+type QmdSearchStrategy = "hybrid" | "lex-vec" | "lex";
+/**
+ * Subprocess fallback command (used only when the daemon is unavailable). Issue #1335.
+ * - "query" → `qmd query` (DEFAULT — LLM query expansion + rerank; see CLAUDE.md
+ *   gotcha #7, this is intentional and must remain the default).
+ * - "search" → `qmd search` (BM25-only; fast, but no expansion/rerank).
+ */
+type QmdSubprocessStrategy = "query" | "search";
+interface QmdStructuredSearch {
+    type: QmdStructuredSearchType;
+    query: string;
+}
+interface QmdCapabilities {
+    version: string | null;
+    parsedVersion: QmdVersionTuple | null;
+    stableSdk: boolean;
+    unifiedSearch: boolean;
+    getDocumentBody: boolean;
+    maintenanceApi: boolean;
+    legacySkillInstall: boolean;
+    intentHints: boolean;
+    explainTraces: boolean;
+    candidateLimit: boolean;
+    v2McpQueryTool: boolean;
+    structuredSearches: boolean;
+    queryRerankToggle: boolean;
+    chunkStrategy: boolean;
+    qmdBench: boolean;
+    perCollectionModels: boolean;
+    jsonLineNumbers: boolean;
+    editorLinks: boolean;
+    doctor: boolean;
+    versionedSkills: boolean;
+    absoluteSnippetLines: boolean;
+    fullQueryOutput: boolean;
+    forceCpu: boolean;
+    gpuBackendOverride: boolean;
+    embedParallelism: boolean;
+    modelEnvConsistency: boolean;
+    scopedEmbed: boolean;
+    safeStatusDeviceProbe: boolean;
+    mcpIndexSelection: boolean;
+    outputFormatFlag: boolean;
+}
+interface QmdVersionStatus {
+    installedVersion: string | null;
+    supportedVersion: string;
+    supported: boolean;
+    newerThanSupported: boolean;
+    upgradeAvailable: boolean;
+    capabilities: QmdCapabilities;
+}
+interface QmdDoctorReport {
+    available: boolean;
+    skipped?: string;
+    report?: unknown;
+    raw?: string;
+    error?: string;
+}
+type QmdRuntimeEnv = Record<string, string | undefined>;
+/**
+ * Build the structured sub-queries the daemon `query` tool runs in one request.
+ *
+ * The default `"hybrid"` plan (lex + vec + hyde) intentionally exercises QMD's
+ * full RRF + rerank path for best recall. On CPU-only models the `hyde` leg
+ * (1.7B generate + embed) dominates wall-clock — operators on constrained
+ * hardware can trade recall for latency via `qmdSearchStrategy` (issue #1335)
+ * without losing the default behavior. A per-call `structuredSearches` override
+ * always wins so callers with stronger query-document structure stay in control.
+ */
+declare function buildDefaultStructuredSearches(query: string, options?: SearchQueryOptions, strategy?: QmdSearchStrategy): QmdStructuredSearch[];
+declare function parseQmdExplain(value: unknown): QmdSearchExplain | undefined;
+declare function getQmdCommandName(args: string[]): string;
+declare class QmdDaemonSession {
+    private child;
+    private initialized;
+    private buffer;
+    private startPromise;
+    private pendingRequests;
+    private readonly qmdPath;
+    private readonly runtimeEnv;
+    private readonly indexName?;
+    constructor(qmdPath: string, runtimeEnv?: QmdRuntimeEnv, indexName?: string);
+    /** Spawn the qmd mcp child process and perform MCP handshake. */
+    start(): Promise<boolean>;
+    /** Call an MCP tool and return the parsed result. */
+    callTool(name: string, args: Record<string, unknown>, timeoutMs?: number, signal?: AbortSignal): Promise<unknown>;
+    /** Kill stdio process and clear state so the next probe can restart. */
+    invalidate(): void;
+    /** Kill stdio process and wait briefly for the child handle to close. */
+    close(timeoutMs?: number): Promise<void>;
+    isActive(): boolean;
+    /** True while the process is spawned but the MCP handshake has not yet completed. */
+    isLoading(): boolean;
+    private sendRequest;
+    private sendNotification;
+    private handleStdoutData;
+    private handleMessage;
+    private cleanup;
+}
+declare function retainSharedDaemonSession(qmdPath: string, runtimeEnv?: QmdRuntimeEnv, indexName?: string, cliVersion?: string | null): QmdDaemonSession;
+declare function releaseSharedDaemonSession(session: QmdDaemonSession | null): Promise<void>;
+declare const sharedDaemonSessionCountForTest: () => number;
+
+declare class QmdClient implements SearchBackend {
+    private readonly collection;
+    private readonly maxResults;
+    private available;
+    private _lastUpdateFailAtMs;
+    private lastEmbedFailAtMs;
+    private lastUpdateRunAtMs;
+    get lastUpdateFailedAtMs(): number | null;
+    get lastUpdateRanAtMs(): number | null;
+    resetUpdateThrottles(): void;
+    private readonly updateTimeoutMs;
+    private readonly updateMinIntervalMs;
+    private readonly slowLog?;
+    private readonly configuredQmdPath?;
+    private readonly qmdSupportedVersion;
+    private readonly qmdAutoUpgradeEnabled;
+    private readonly qmdAutoUpgradeCheckIntervalMs;
+    private readonly qmdChunkStrategy?;
+    private readonly qmdCandidateLimit?;
+    private readonly qmdQueryRerankEnabled;
+    private readonly qmdIndexName?;
+    private readonly qmdSearchStrategy;
+    private readonly qmdSubprocessStrategy;
+    private readonly qmdFallbackPaths;
+    private readonly daemonTimeoutMs;
+    private readonly qmdRuntimeEnv;
+    private qmdPathSource;
+    private cliVersion;
+    private lastCliProbeError;
+    private qmdCapabilities;
+    private daemonSession;
+    private daemonAvailable;
+    private daemonSessionPath;
+    private lastDaemonCheckAtMs;
+    private readonly daemonEnabled;
+    private readonly daemonRecheckIntervalMs;
+    /** Consecutive transient daemon failures before invalidating the session. */
+    private daemonTransientFailures;
+    private static readonly DAEMON_MAX_TRANSIENT_FAILURES;
+    constructor(collection: string, maxResults: number, opts?: QmdClientOptions);
+    private qmdPath;
+    private buildRuntimeEnv;
+    probe(): Promise<boolean>;
+    checkAvailability(execution?: SearchExecutionOptions): Promise<boolean>;
+    private probeDaemon;
+    /**
+     * Run a single `qmd --version` probe against `qmdPath`. Extracted as its own
+     * method so tests can inject a fake probe runner that exercises the preflight
+     * retry/classification paths without spawning a real qmd binary. Issue #1841.
+     */
+    private runVersionProbe;
+    private probeCli;
+    private maybeAutoUpgradeQmd;
+    private probePostInstallQmdVersion;
+    private autoUpgradeTargetKey;
+    private logCliProbeWarning;
+    /** Re-probe daemon if it was down and recheck interval has elapsed. */
+    private maybeProbeDaemon;
+    isAvailable(): boolean;
+    /** Debug string for troubleshooting availability issues. */
+    debugStatus(): string;
+    getVersionStatus(): QmdVersionStatus;
+    doctor(): Promise<QmdDoctorReport>;
+    isDaemonMode(): boolean;
+    dispose(): Promise<void>;
+    /**
+     * Record a daemon search success — resets the transient failure counter.
+     */
+    private recordDaemonSuccess;
+    /**
+     * Handle a non-timeout, non-cancellation daemon error.
+     * Tolerates up to DAEMON_MAX_TRANSIENT_FAILURES consecutive failures
+     * before invalidating the session. This prevents a single transient
+     * error from pushing all concurrent searches through the subprocess
+     * mutex for the full recheck interval.
+     */
+    private handleDaemonTransientError;
+    private runQmdCommand;
+    private supportsIntentHints;
+    private supportsExplainTraces;
+    private supportsCandidateLimit;
+    private supportsRerankToggle;
+    private supportsChunkStrategy;
+    /**
+     * QMD v2 (>= 2.0.0) uses a new MCP tool API:
+     * - `search` and `vsearch` tools removed; only `query` tool exists
+     * - `query` accepts `{ searches: [{ type, query }], collections?: string[] }`
+     *   instead of `{ query: string, collection?: string }`
+     * - `collection` (singular) → `collections` (plural array)
+     */
+    private isQmdV2;
+    private resolveSearchOptions;
+    resolveSupportedSearchOptions(options?: SearchQueryOptions): SearchQueryOptions | undefined;
+    private addResolvedSearchOptionsToArgs;
+    private addQmdJsonOutputArgs;
+    private addResolvedSearchOptionsToMcpArgs;
+    private buildEmbedArgs;
+    search(query: string, collection?: string, maxResults?: number, options?: SearchQueryOptions, execution?: SearchExecutionOptions): Promise<QmdSearchResult[]>;
+    searchGlobal(query: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<QmdSearchResult[]>;
+    /**
+     * BM25 keyword search (fast, ~0.3s). Uses `qmd search`.
+     */
+    bm25Search(query: string, collection?: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<QmdSearchResult[]>;
+    /**
+     * Vector similarity search (~3-4s). Uses `qmd vsearch`.
+     */
+    vectorSearch(query: string, collection?: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<QmdSearchResult[]>;
+    /**
+     * Hybrid search: runs BM25 + vector in parallel, merges/dedupes by path
+     * keeping the best score and first non-empty snippet.
+     */
+    hybridSearch(query: string, collection?: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<QmdSearchResult[]>;
+    private searchViaDaemon;
+    private bm25SearchViaDaemon;
+    private vsearchViaDaemon;
+    /**
+     * Report a backend degradation to the caller's observer (#1536): an empty
+     * result caused by unavailability/loading/timeout is otherwise
+     * indistinguishable from "no matches" (CLAUDE.md rule 34). Observer
+     * failures are swallowed — observability must never break search.
+     */
+    private notifyDegradation;
+    /**
+     * Condense an error into a degradation `detail` string that is safe to
+     * serialize on LastRecallSnapshot and expose via last-recall MCP/HTTP
+     * surfaces (cursor review on #1544): first line only, path-like tokens
+     * redacted (absolute, home-rooted, and Windows drive paths can leak
+     * usernames and filesystem layout), capped at 160 chars. The unredacted
+     * error still reaches operators via the warn log at the failure site.
+     */
+    private degradationDetail;
+    private searchViaSubprocess;
+    private bm25SearchViaSubprocess;
+    private vsearchViaSubprocess;
+    private searchGlobalViaSubprocess;
+    update(execution?: SearchExecutionOptions): Promise<void>;
+    updateStrict(execution?: SearchExecutionOptions): Promise<void>;
+    updateCollection(collection: string, execution?: SearchExecutionOptions): Promise<void>;
+    updateCollectionStrict(collection: string, execution?: SearchExecutionOptions): Promise<void>;
+    updatesAllCollections(): boolean;
+    private runUpdateForCollection;
+    embed(): Promise<void>;
+    embedStrict(): Promise<void>;
+    embedCollection(collection: string): Promise<void>;
+    embedCollectionStrict(collection: string): Promise<void>;
+    private runEmbedForCollection;
+    checkCollection(collectionOrExecution?: string | SearchExecutionOptions, execution?: SearchExecutionOptions): Promise<"present" | "missing" | "unknown" | "skipped">;
+    ensureCollection(memoryDir: string, collectionOrExecution?: string | SearchExecutionOptions, execution?: SearchExecutionOptions): Promise<"present" | "missing" | "unknown" | "skipped">;
+}
+
+export { releaseSharedDaemonSession as A, retainSharedDaemonSession as B, sharedDaemonSessionCountForTest as C, QmdClient as Q, QMD_PROBE_RETRY_BACKOFF_MS as a, QMD_PROBE_TIMEOUT_MS as b, QMD_SUPPORTED_VERSION as c, type QmdProbeFailureKind as d, classifyProbeFailure as e, compareQmdVersions as f, getQmdPostInstallProbeTargets as g, parseQmdVersionOutput as h, type QmdCapabilities as i, type QmdChunkStrategy as j, type QmdClientOptions as k, type QmdDoctorReport as l, type QmdSearchStrategy as m, type QmdStructuredSearch as n, type QmdStructuredSearchType as o, parseQmdVersion as p, qmdVersionToString as q, resolveQmdCapabilities as r, shouldAutoUpgradeQmd as s, type QmdSubprocessStrategy as t, type QmdVersionStatus as u, versionAtLeast as v, type QmdVersionTuple as w, buildDefaultStructuredSearches as x, getQmdCommandName as y, parseQmdExplain as z };

package/dist/qmd-preflight.d.ts

@@ -0,0 +1,5 @@
+export { a as QMD_PROBE_RETRY_BACKOFF_MS, b as QMD_PROBE_TIMEOUT_MS, c as QMD_SUPPORTED_VERSION, d as QmdProbeFailureKind, e as classifyProbeFailure, f as compareQmdVersions, g as getQmdPostInstallProbeTargets, p as parseQmdVersion, h as parseQmdVersionOutput, q as qmdVersionToString, r as resolveQmdCapabilities, s as shouldAutoUpgradeQmd, v as versionAtLeast } from './qmd-Db9mOkzB.js';
+import './types-ljkd82rn.js';
+import './types-gb_SNtjR.js';
+import './message-parts/index.js';
+import './search/port.js';

package/dist/qmd-preflight.js

@@ -0,0 +1,31 @@
+import {
+  QMD_PROBE_RETRY_BACKOFF_MS,
+  QMD_PROBE_TIMEOUT_MS,
+  QMD_SUPPORTED_VERSION,
+  classifyProbeFailure,
+  compareQmdVersions,
+  getQmdPostInstallProbeTargets,
+  parseQmdVersion,
+  parseQmdVersionOutput,
+  qmdVersionToString,
+  resolveQmdCapabilities,
+  shouldAutoUpgradeQmd,
+  versionAtLeast
+} from "./chunk-64UDOIMI.js";
+import "./chunk-PVGDJXVK.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  QMD_PROBE_RETRY_BACKOFF_MS,
+  QMD_PROBE_TIMEOUT_MS,
+  QMD_SUPPORTED_VERSION,
+  classifyProbeFailure,
+  compareQmdVersions,
+  getQmdPostInstallProbeTargets,
+  parseQmdVersion,
+  parseQmdVersionOutput,
+  qmdVersionToString,
+  resolveQmdCapabilities,
+  shouldAutoUpgradeQmd,
+  versionAtLeast
+};
+//# sourceMappingURL=qmd-preflight.js.map

package/dist/qmd-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/qmd-recall-cache.d.ts

@@ -1,4 +1,4 @@
-import { b as RecallPlanMode } from './types-D1iBqhJA.js';
+import { b as RecallPlanMode } from './types-ljkd82rn.js';
 import { SearchQueryOptions } from './search/port.js';
 import './types-gb_SNtjR.js';
 import './message-parts/index.js';