@lincoln504/pi-research 1.6.5 → 1.6.6

package/src/utils/llm-usage.ts

@@ -67,6 +67,14 @@ function warnIfUnpriced(model: Model<any>, tokens: number, cost: number): void {
  * `tokens > 0 || cost > 0`, so a response whose usage is all-zero across the board
  * emits nothing — harmless in practice because cache fields are summed into `tokens`,
  * so a reported cache split implies a nonzero total.
+ *
+ * Accuracy note: for the openai-completions API family (which includes OpenRouter),
+ * pi-ai's usage normalization ALWAYS sets cacheRead/cacheWrite, defaulting missing
+ * upstream fields to 0 — so on those providers a route without prompt caching shows the
+ * counter at 0 rather than omitting it. The 0-vs-absent distinction only holds for APIs
+ * that omit the fields outright. A run showing llm_cache_read_tokens_total stuck at 0
+ * with nonzero input tokens is therefore most simply read as "this route reports no
+ * cached tokens", not "our prompts defeat the cache".
  */
 function recordCacheTokens(parsed: Partial<TokenUsage>, labels: Record<string, string>): void {
   if (typeof parsed.cacheRead === 'number') {

package/src/utils/log-utils.ts

@@ -38,7 +38,7 @@ export function buildDefaultDebugLogPath(): string {
  * Check whether debug/verbose logging is enabled.
  *
  * Reads PI_RESEARCH_DEBUG env var. Config SAVES sync config.DEBUG into this
- * env var (see config.ts buildEnvValues); plain config LOADS do not mutate
+ * env var (see the DEBUG → PI_RESEARCH_DEBUG bridge in config.ts createConfig); plain config LOADS do not mutate
  * process.env, so a DEBUG=true line in config.env enables verbose logging for
  * a process only after a save has run in it — export PI_RESEARCH_DEBUG=true
  * in the environment to guarantee it from process start.

package/src/web-research/browser-search.ts

@@ -331,11 +331,12 @@ export async function performSearch(
             metrics.increment('browser_search_total_failures_total', 1, { cause: 'native_binding' });
             throw new Error(
                 `Search completely failed: ${reason}, all with a missing native module. ` +
-                `This is an incomplete install, not a network problem: the browser engine's ` +
-                `native dependencies were never built. npm 12 does not run dependency install ` +
-                `scripts by default — reinstall allowing the script (global install: ` +
-                `npm install -g @lincoln504/pi-research --allow-scripts=better-sqlite3; ` +
-                `project install: npm approve-scripts better-sqlite3, then npm rebuild better-sqlite3), then retry.` +
+                `This is an incomplete install, not a network problem: better-sqlite3 13 ` +
+                `ships prebuilt bindings for every supported platform and loads them at ` +
+                `runtime, so a missing binding means an old or broken npm install. ` +
+                `Upgrade npm to ≥12 (npm install -g npm@12) and reinstall this package — ` +
+                `modern npm skips the needless recompile that fails on toolchain-less ` +
+                `machines, and the prebuilt binding then loads as-is.` +
                 (sampleWorkerError ? ` Last worker error: ${sampleWorkerError}` : '')
             );
         }