peon-mem 1.0.6 → 1.0.8

package/dist/compression.js

@@ -1,3 +1,4 @@
+import { llmEnabled, llmEndpoint, llmHeaders } from "./config.js";
 /**
  * Builds the LLM summarizer the brain uses to compress a topic cluster into one
  * gist belief. Kept separate from brain.ts so the curation logic stays pure and
@@ -5,7 +6,7 @@
  * or no key is configured (the brain then runs cost-free, skipping compression).
  */
 export function createClusterSummarizer(config) {
-    if (config.aiMode === "off" || !config.openRouterApiKey)
+    if (!llmEnabled(config))
         return null;
     return async (cluster) => {
         const beliefs = cluster.members.map((m, i) => `${i + 1}. ${m.content}`).join("\n");
@@ -14,9 +15,9 @@ export function createClusterSummarizer(config) {
             "Losing a specific fact is a failure; merge wording, never drop information. Drop only redundancy and filler. " +
             "Output ONLY the summary sentence(s) — no preamble, no markdown, no quotes around it. Max 240 characters.";
         const user = `Topic: ${cluster.entity}\n\nBeliefs to compress:\n${beliefs}\n\nOne compact summary:`;
-        const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+        const response = await fetch(llmEndpoint(config), {
             method: "POST",
-            headers: { Authorization: `Bearer ${config.openRouterApiKey}`, "Content-Type": "application/json" },
+            headers: llmHeaders(config),
             body: JSON.stringify({
                 model: config.processingModel,
                 messages: [

package/dist/config.d.ts

@@ -19,4 +19,17 @@ export interface PeonConfig {
 type Env = Record<string, string | undefined>;
 export declare function loadPeonConfig(env?: Env): PeonConfig;
 export declare function readEnvFile(startDir?: string): Env;
+/**
+ * Is an LLM available for optional AI passes (compression, entity extraction, HyDE,
+ * global extraction)?
+ *
+ * These used to gate on `openRouterApiKey`, which meant a fully-local setup
+ * (PEON_PROVIDER=ollama, no OpenRouter key) silently skipped every one of them —
+ * "local mode" was not actually local. A local provider needs no key; a hosted one does.
+ */
+export declare function llmEnabled(config: PeonConfig): boolean;
+/** The chat-completions endpoint for the configured provider. */
+export declare function llmEndpoint(config: PeonConfig): string;
+/** Auth + content headers for the configured provider (local providers need no key). */
+export declare function llmHeaders(config: PeonConfig): Record<string, string>;
 export {};

package/dist/config.js

@@ -97,3 +97,29 @@ function findEnvFile(startDir) {
         current = dirname(current);
     }
 }
+/**
+ * Is an LLM available for optional AI passes (compression, entity extraction, HyDE,
+ * global extraction)?
+ *
+ * These used to gate on `openRouterApiKey`, which meant a fully-local setup
+ * (PEON_PROVIDER=ollama, no OpenRouter key) silently skipped every one of them —
+ * "local mode" was not actually local. A local provider needs no key; a hosted one does.
+ */
+export function llmEnabled(config) {
+    if (config.aiMode === "off")
+        return false;
+    if (config.provider === "ollama")
+        return true;
+    return Boolean(config.llmApiKey ?? config.openRouterApiKey);
+}
+/** The chat-completions endpoint for the configured provider. */
+export function llmEndpoint(config) {
+    return `${config.llmBaseUrl.replace(/\/$/, "")}/chat/completions`;
+}
+/** Auth + content headers for the configured provider (local providers need no key). */
+export function llmHeaders(config) {
+    return {
+        Authorization: `Bearer ${config.llmApiKey ?? config.openRouterApiKey ?? ""}`,
+        "Content-Type": "application/json"
+    };
+}

package/dist/daemon.js

@@ -102,9 +102,9 @@ export function canonicalProjectPath(projectPath, home = homedir()) {
 /**
  * Reject requests that aren't from a loopback caller — defeats DNS-rebinding and drive-by-localhost
  * attacks where a malicious web page POSTs to the daemon (which would otherwise write/read a brain
- * at an attacker-controlled path). A bad Host header (rebinding) or a cross-origin Origin/Referer
- * (browser drive-by) is refused. The node hook (no Origin) and the local monitor UI (loopback
- * Origin) both pass.
+ * at an attacker-controlled path). A bad Host header (rebinding), a cross-origin Origin/Referer
+ * (browser drive-by) or a browser's Sec-Fetch-Site: cross-site is refused. The node hook (no
+ * Origin) and the local monitor UI (loopback Origin, same-origin fetches) all pass.
  */
 function isLoopbackHostname(hostname) {
     const h = hostname.toLowerCase().replace(/^\[|\]$/g, "");
@@ -128,6 +128,12 @@ function isLocalRequest(request) {
     // A present Host must be loopback (a missing Host — rare, HTTP/1.0 — is allowed; bind is 127.0.0.1).
     if (rawHost !== undefined && !isLoopbackHostname(hostnameFromHostHeader(String(rawHost))))
         return false;
+    // Browsers label every request with where it came from. An <img> or no-referrer fetch from
+    // another site carries no Origin or Referer, so the loop below cannot see it, yet a GET like
+    // /context?projectPath=... still creates a brain at that path. Non-browser callers (the hook,
+    // the MCP server, curl) send no Sec-Fetch-Site and are unaffected.
+    if (String(request.headers["sec-fetch-site"] ?? "").toLowerCase() === "cross-site")
+        return false;
     for (const header of [request.headers.origin, request.headers.referer]) {
         if (!header)
             continue;

package/dist/embedding-store.d.ts

@@ -20,6 +20,16 @@ export interface SyncResult {
     reused: number;
     pruned: number;
 }
+export declare function embeddingCacheStats(): {
+    cachedStores: number;
+    diskReads: number;
+    reads: number;
+    expireOlderThan: (now: number) => void;
+};
+/** Test helper: forget every cached sidecar. */
+export declare function resetEmbeddingCaches(): void;
+/** Test helper: forget learned widths, simulating a fresh daemon process. */
+export declare function resetEmbeddingDimensionCache(): void;
 export declare class EmbeddingStore {
     private readonly filePath;
     private cache?;
@@ -33,6 +43,8 @@ export declare class EmbeddingStore {
      * empty map rather than throwing (retrieval falls back to lexical-only).
      */
     sync(records: MemoryRecord[], client: EmbeddingClient | null): Promise<SyncResult>;
+    /** Release this store's parsed sidecar. Costs one re-read, never correctness. */
+    dropCache(): void;
     /** Read vectors without recomputing — used by read-only retrieval paths. */
     vectorById(): Promise<Map<string, EmbeddingVector>>;
     private persist;

package/dist/embedding-store.js

@@ -1,6 +1,73 @@
 import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { contentHash } from "./embeddings.js";
+/**
+ * Bounded registry of live sidecar caches.
+ *
+ * The cache below keeps a whole embeddings.jsonl parsed in memory so read-only
+ * retrieval doesn't re-parse a multi-MB file on every prompt. That is a real win,
+ * but the daemon holds one store per project and nothing evicted: a heap snapshot
+ * showed 8 stores pinning 60,288 Float32Array vectors / 338 MB of native backing,
+ * with RSS past 1.9 GB — enough GC pressure to peg the CPU and stop the daemon
+ * answering. So caches are now LRU-bounded and released once idle; a dropped cache
+ * costs one re-read, never correctness.
+ */
+const MAX_CACHED_STORES = Number(process.env.PEON_EMBED_CACHE_STORES) > 0
+    ? Number(process.env.PEON_EMBED_CACHE_STORES)
+    : 2;
+const CACHE_TTL_MS = Number(process.env.PEON_EMBED_CACHE_TTL_MS) > 0
+    ? Number(process.env.PEON_EMBED_CACHE_TTL_MS)
+    : 5 * 60 * 1000;
+/** Insertion order is LRU order: least-recently-used first. */
+const liveCaches = new Map();
+let diskReads = 0;
+function touchCache(store, at) {
+    liveCaches.delete(store);
+    liveCaches.set(store, at);
+    pruneCaches(at);
+}
+function pruneCaches(now) {
+    for (const [store, touchedAt] of [...liveCaches]) {
+        if (now - touchedAt > CACHE_TTL_MS) {
+            store.dropCache();
+            liveCaches.delete(store);
+        }
+    }
+    while (liveCaches.size > MAX_CACHED_STORES) {
+        const oldest = liveCaches.keys().next().value;
+        if (!oldest)
+            break;
+        oldest.dropCache();
+        liveCaches.delete(oldest);
+    }
+}
+// TTL alone only fires on activity, so an idle daemon would hold its last caches
+// forever. A low-frequency sweeper lets a quiet daemon settle back down; unref'd
+// so it never keeps the process alive on its own.
+const sweeper = setInterval(() => pruneCaches(Date.now()), 60_000);
+if (typeof sweeper.unref === "function")
+    sweeper.unref();
+export function embeddingCacheStats() {
+    return {
+        cachedStores: liveCaches.size,
+        diskReads,
+        reads: diskReads,
+        expireOlderThan: (now) => pruneCaches(now)
+    };
+}
+/** Test helper: forget every cached sidecar. */
+export function resetEmbeddingCaches() {
+    for (const store of [...liveCaches.keys()])
+        store.dropCache();
+    liveCaches.clear();
+    diskReads = 0;
+}
+/** Real output width per embedding model, learned once per process. */
+const modelDimensions = new Map();
+/** Test helper: forget learned widths, simulating a fresh daemon process. */
+export function resetEmbeddingDimensionCache() {
+    modelDimensions.clear();
+}
 export class EmbeddingStore {
     filePath;
     // mtime-keyed cache so the (multi-MB) sidecar isn't re-read+parsed on every prompt's
@@ -23,8 +90,11 @@ export class EmbeddingStore {
         catch {
             mtimeMs = 0; // missing file → treat as empty, mtime 0
         }
-        if (this.cache && this.cache.mtimeMs === mtimeMs)
+        if (this.cache && this.cache.mtimeMs === mtimeMs) {
+            touchCache(this, Date.now());
             return this.cache.map;
+        }
+        diskReads += 1;
         const raw = await readFile(this.filePath, "utf8").catch(() => "");
         const map = new Map();
         for (const line of raw.split(/\r?\n/)) {
@@ -41,6 +111,7 @@ export class EmbeddingStore {
             }
         }
         this.cache = { mtimeMs, map };
+        touchCache(this, Date.now());
         return map;
     }
     /**
@@ -56,11 +127,40 @@ export class EmbeddingStore {
         const existing = await this.load();
         const liveIds = new Set(records.map((record) => record.id));
         const pruned = [...existing.keys()].filter((id) => !liveIds.has(id)).length;
+        // A stored vector can carry the right model name and hash yet the wrong width —
+        // that is exactly what a degraded fallback wrote — and cosineSimilarity scores any
+        // width mismatch as 0, so those records vanish from semantic recall without ever
+        // erroring. Width is part of validity, so we need to know the client's real width.
+        //
+        // Learning it must not cost a round trip on every sync: the width is cached per
+        // model for the process, and only probed when there is nothing to compute (the
+        // one case where a fully-poisoned sidecar would otherwise look entirely reusable).
+        let expectedDim = modelDimensions.get(client.model) ?? 0;
+        const nothingToRecompute = records.every((record) => {
+            const prior = existing.get(record.id);
+            return prior && prior.model === client.model && prior.hash === contentHash(embeddingText(record));
+        });
+        if (expectedDim === 0 && records.length > 0 && nothingToRecompute) {
+            try {
+                const probe = await client.embed([embeddingText(records[0])]);
+                if (!client.degraded && probe[0]?.length) {
+                    expectedDim = probe[0].length;
+                    modelDimensions.set(client.model, expectedDim);
+                }
+            }
+            catch {
+                expectedDim = 0; // cannot probe — fall back to model+hash validity only
+            }
+        }
+        const validDim = (vector) => expectedDim === 0 || vector.length === expectedDim;
         const toCompute = [];
         let reused = 0;
         for (const record of records) {
             const prior = existing.get(record.id);
-            if (prior && prior.model === client.model && prior.hash === contentHash(embeddingText(record))) {
+            if (prior &&
+                prior.model === client.model &&
+                prior.hash === contentHash(embeddingText(record)) &&
+                validDim(prior.vector)) {
                 reused += 1;
             }
             else {
@@ -70,7 +170,10 @@ export class EmbeddingStore {
         const result = new Map();
         for (const record of records) {
             const prior = existing.get(record.id);
-            if (prior && prior.model === client.model && prior.hash === contentHash(embeddingText(record))) {
+            if (prior &&
+                prior.model === client.model &&
+                prior.hash === contentHash(embeddingText(record)) &&
+                validDim(prior.vector)) {
                 result.set(record.id, prior);
             }
         }
@@ -78,6 +181,20 @@ export class EmbeddingStore {
         if (toCompute.length > 0) {
             try {
                 const vectors = await client.embed(toCompute.map((record) => embeddingText(record)));
+                // A degraded run returns local trigram vectors. Serving them for THIS call is
+                // fine (graceful degradation); writing them under the primary's model name is
+                // not — they would be reused forever as if they were real embeddings.
+                if (client.degraded) {
+                    const degradedById = new Map();
+                    for (const [id, stored] of result)
+                        degradedById.set(id, stored.vector);
+                    toCompute.forEach((record, i) => {
+                        const vector = vectors[i];
+                        if (vector)
+                            degradedById.set(record.id, vector);
+                    });
+                    return { vectorById: degradedById, computed: 0, reused, pruned };
+                }
                 toCompute.forEach((record, i) => {
                     result.set(record.id, {
                         id: record.id,
@@ -87,6 +204,9 @@ export class EmbeddingStore {
                     });
                 });
                 computed = toCompute.length;
+                const width = vectors[0]?.length ?? 0;
+                if (width > 0)
+                    modelDimensions.set(client.model, width);
             }
             catch {
                 // On a hard failure, keep whatever we already had and continue lexical-only.
@@ -101,6 +221,10 @@ export class EmbeddingStore {
             vectorById.set(id, stored.vector);
         return { vectorById, computed, reused, pruned };
     }
+    /** Release this store's parsed sidecar. Costs one re-read, never correctness. */
+    dropCache() {
+        this.cache = undefined;
+    }
     /** Read vectors without recomputing — used by read-only retrieval paths. */
     async vectorById() {
         const stored = await this.load();
@@ -123,6 +247,7 @@ export class EmbeddingStore {
         await writeFile(tmp, lines.length > 0 ? `${lines.join("\n")}\n` : "", "utf8");
         await rename(tmp, this.filePath);
         this.cache = undefined; // invalidate; next load() re-reads the fresh file
+        liveCaches.delete(this);
     }
 }
 /** Embed the record type alongside content so type acts as a soft semantic anchor. */

package/dist/embeddings.d.ts

@@ -81,6 +81,15 @@ export declare class FallbackEmbeddingClient implements EmbeddingClient {
     private readonly fallback;
     private readonly onFallback?;
     readonly model: string;
+    /**
+     * True when the most recent embed() degraded to the fallback. The vectors it
+     * returns are a different model AND a different width, so persisting them under
+     * the primary's name makes them indistinguishable from real ones — every later
+     * sync then "reuses" trigram vectors as if they were embeddings, and retrieval
+     * silently scores them 0 (cosineSimilarity returns 0 on a length mismatch).
+     * Callers that persist vectors must check this and skip writing.
+     */
+    degraded: boolean;
     constructor(primary: EmbeddingClient, fallback?: EmbeddingClient, onFallback?: ((error: unknown) => void) | undefined);
     embed(texts: string[]): Promise<EmbeddingVector[]>;
 }
@@ -90,4 +99,25 @@ export interface CreateEmbeddingClientOptions {
     onFallback?: (error: unknown) => void;
 }
 /** Build the embedding client implied by config, or null when embeddings are off. */
+/**
+ * What was asked for versus what will actually run.
+ *
+ * Peon degrades to deterministic local trigram embeddings whenever the configured
+ * embedder is unavailable. That is deliberate — retrieval keeps working — but it was
+ * silent, and a silent downgrade is indistinguishable from working correctly while
+ * semantic recall quietly collapses. Two real incidents: an Ollama blip embedding 30k+
+ * records with trigram vectors, and a script whose .env was not found resolving to
+ * "local" with no warning at all.
+ */
+export interface EmbeddingPlan {
+    intended: PeonConfig["embeddingMode"];
+    effective: "off" | "local" | "api" | "ollama";
+    downgraded: boolean;
+    reason?: string;
+}
+/** Only the fields the decision actually depends on, matching the client factory. */
+export type EmbeddingPlanInput = Pick<PeonConfig, "embeddingMode" | "embeddingModel" | "openRouterApiKey" | "provider" | "llmApiKey">;
+export declare function resolveEmbeddingPlan(config: EmbeddingPlanInput): EmbeddingPlan;
+/** Test helper: forget which downgrade warnings have already been emitted. */
+export declare function resetEmbeddingWarnings(): void;
 export declare function createEmbeddingClient(options: CreateEmbeddingClientOptions): EmbeddingClient | null;

package/dist/embeddings.js

@@ -290,6 +290,15 @@ export class FallbackEmbeddingClient {
     fallback;
     onFallback;
     model;
+    /**
+     * True when the most recent embed() degraded to the fallback. The vectors it
+     * returns are a different model AND a different width, so persisting them under
+     * the primary's name makes them indistinguishable from real ones — every later
+     * sync then "reuses" trigram vectors as if they were embeddings, and retrieval
+     * silently scores them 0 (cosineSimilarity returns 0 on a length mismatch).
+     * Callers that persist vectors must check this and skip writing.
+     */
+    degraded = false;
     constructor(primary, fallback = new LocalEmbeddingClient(), onFallback) {
         this.primary = primary;
         this.fallback = fallback;
@@ -298,19 +307,73 @@ export class FallbackEmbeddingClient {
     }
     async embed(texts) {
         try {
-            return await this.primary.embed(texts);
+            const vectors = await this.primary.embed(texts);
+            this.degraded = false;
+            return vectors;
         }
         catch (error) {
             this.onFallback?.(error);
+            this.degraded = true;
             return this.fallback.embed(texts);
         }
     }
 }
-/** Build the embedding client implied by config, or null when embeddings are off. */
+export function resolveEmbeddingPlan(config) {
+    const intended = config.embeddingMode;
+    if (intended === "off")
+        return { intended, effective: "off", downgraded: false };
+    if (intended === "local")
+        return { intended, effective: "local", downgraded: false };
+    if (intended === "ollama") {
+        // Reachability cannot be known at construction time; a dead server surfaces at
+        // the first embed() as a degraded run, which the store refuses to persist.
+        return { intended, effective: "ollama", downgraded: false };
+    }
+    const apiKey = config.llmApiKey ?? config.openRouterApiKey;
+    if (!apiKey) {
+        return { intended, effective: "local", downgraded: true, reason: "no API key/credentials configured" };
+    }
+    if (!config.embeddingModel) {
+        return { intended, effective: "local", downgraded: true, reason: "PEON_EMBEDDING_MODEL is not set" };
+    }
+    if (config.provider === "anthropic") {
+        return { intended, effective: "local", downgraded: true, reason: "Anthropic has no embeddings API" };
+    }
+    return { intended, effective: "api", downgraded: false };
+}
+/** Warn once per distinct reason, so a long-lived daemon does not spam its log. */
+const warnedDowngrades = new Set();
+function warnOnce(plan) {
+    if (!plan.downgraded || !plan.reason)
+        return;
+    if (warnedDowngrades.has(plan.reason))
+        return;
+    warnedDowngrades.add(plan.reason);
+    console.warn(`[peon] embedding mode "${plan.intended}" is not available (${plan.reason}); ` +
+        `falling back to local trigram embeddings. Semantic recall will be much weaker — ` +
+        `set PEON_EMBEDDING_MODE=local to silence this, or fix the configuration.`);
+}
+/** Test helper: forget which downgrade warnings have already been emitted. */
+export function resetEmbeddingWarnings() {
+    warnedDowngrades.clear();
+}
 export function createEmbeddingClient(options) {
     const { config } = options;
+    warnOnce(resolveEmbeddingPlan(config));
     if (config.embeddingMode === "off")
         return null;
+    // No caller ever supplied onFallback, so a runtime degrade (embedding server down)
+    // was completely silent. Default to warning once per process: the vectors from that
+    // run are trigram, not semantic, and the operator needs to know retrieval got worse.
+    const onFallback = options.onFallback ??
+        ((error) => {
+            if (warnedDowngrades.has("runtime-fallback"))
+                return;
+            warnedDowngrades.add("runtime-fallback");
+            console.warn(`[peon] embedding request failed (${error instanceof Error ? error.message : String(error)}); ` +
+                `falling back to local trigram embeddings for this run. Semantic recall is degraded ` +
+                `until the embedding server is reachable again.`);
+        });
     if (config.embeddingMode === "ollama") {
         // Local semantic embeddings. Fall back to the API client (if configured) then trigram-local,
         // so a stopped Ollama service degrades instead of breaking retrieval.
@@ -319,9 +382,9 @@ export function createEmbeddingClient(options) {
             baseUrl: config.ollamaBaseUrl
         });
         const fallback = config.openRouterApiKey && config.embeddingModel && config.embeddingModel.includes("/")
-            ? new FallbackEmbeddingClient(new OpenRouterEmbeddingClient({ apiKey: config.openRouterApiKey, model: config.embeddingModel }), new LocalEmbeddingClient(), options.onFallback)
+            ? new FallbackEmbeddingClient(new OpenRouterEmbeddingClient({ apiKey: config.openRouterApiKey, model: config.embeddingModel }), new LocalEmbeddingClient(), onFallback)
             : new LocalEmbeddingClient();
-        return new FallbackEmbeddingClient(ollama, fallback, options.onFallback);
+        return new FallbackEmbeddingClient(ollama, fallback, onFallback);
     }
     const apiKey = config.llmApiKey ?? config.openRouterApiKey;
     const embeddable = config.provider !== "anthropic"; // Anthropic has no embeddings API — local fallback
@@ -331,7 +394,7 @@ export function createEmbeddingClient(options) {
             model: config.embeddingModel,
             baseUrl: config.llmBaseUrl
         });
-        return new FallbackEmbeddingClient(primary, new LocalEmbeddingClient(), options.onFallback);
+        return new FallbackEmbeddingClient(primary, new LocalEmbeddingClient(), onFallback);
     }
     // Default and "api"-without-credentials both resolve to deterministic local embeddings.
     return new LocalEmbeddingClient();

package/dist/entity-extraction.js

@@ -1,9 +1,10 @@
+import { llmEnabled, llmEndpoint, llmHeaders } from "./config.js";
 const DEFAULT_MAX_ITEMS = 40;
 const DEFAULT_SNIPPET_CHARS = 240;
 export async function extractDomainEntitiesViaModel(items, options) {
     const out = new Map();
     const { config } = options;
-    if (items.length === 0 || config.aiMode === "off" || !config.openRouterApiKey)
+    if (items.length === 0 || !llmEnabled(config))
         return out;
     const doFetch = options.fetchImpl ?? globalThis.fetch;
     if (!doFetch)
@@ -19,9 +20,9 @@ export async function extractDomainEntitiesViaModel(items, options) {
         '{"n": <snippet number>, "entities": ["..."]}, empty array when a snippet names none. No prose, no fences.';
     const user = `Snippets:\n${numbered}\n\nJSON array:`;
     try {
-        const response = await doFetch("https://openrouter.ai/api/v1/chat/completions", {
+        const response = await doFetch(llmEndpoint(config), {
             method: "POST",
-            headers: { Authorization: `Bearer ${config.openRouterApiKey}`, "Content-Type": "application/json" },
+            headers: llmHeaders(config),
             body: JSON.stringify({
                 model: options.model ?? config.processingModel,
                 messages: [

package/dist/global-extraction.js

@@ -1,5 +1,6 @@
+import { llmEnabled, llmEndpoint, llmHeaders } from "./config.js";
 export function createGlobalExtractor(config) {
-    if (config.aiMode === "off" || !config.openRouterApiKey)
+    if (!llmEnabled(config))
         return null;
     return async (records) => {
         // Send the highest-signal beliefs only — bounds tokens, focuses the model.
@@ -22,9 +23,9 @@ export function createGlobalExtractor(config) {
             "Example DROP (project-internal): 'The daemon exposes a /global/extract endpoint.' " +
             "Rewrite each as one self-contained sentence with zero project context. " +
             "Output ONLY a JSON array of strings — no markdown fences, no prose. If nothing qualifies, return []. Max 8 items.";
-        const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+        const response = await fetch(llmEndpoint(config), {
             method: "POST",
-            headers: { Authorization: `Bearer ${config.openRouterApiKey}`, "Content-Type": "application/json" },
+            headers: llmHeaders(config),
             body: JSON.stringify({
                 model: config.processingModel,
                 messages: [

package/dist/hyde.js

@@ -1,10 +1,11 @@
+import { llmEnabled, llmEndpoint } from "./config.js";
 const DEFAULT_MAX_CHARS = 320;
 export async function expandQuery(query, options) {
     const q = (query ?? "").trim();
     if (!q)
         return { expanded: "", hypothetical: "" };
     const { config } = options;
-    if (config.aiMode === "off" || !config.openRouterApiKey)
+    if (!llmEnabled(config))
         return { expanded: q, hypothetical: "" };
     const doFetch = options.fetchImpl ?? globalThis.fetch;
     if (!doFetch)
@@ -16,10 +17,10 @@ export async function expandQuery(query, options) {
         "Do not hedge, do not say you lack context, do not ask questions. Output the sentences only.";
     const user = `Question: ${q}\n\nHypothetical answer:`;
     try {
-        const response = await doFetch("https://openrouter.ai/api/v1/chat/completions", {
+        const response = await doFetch(llmEndpoint(config), {
             method: "POST",
             headers: {
-                Authorization: `Bearer ${config.openRouterApiKey}`,
+                Authorization: `Bearer ${config.llmApiKey ?? config.openRouterApiKey ?? ""}`,
                 "Content-Type": "application/json"
             },
             body: JSON.stringify({

package/dist/logger.d.ts

@@ -1,5 +1,9 @@
 export interface PeonLoggerOptions {
     logDir?: string;
+    /** Rotate the live log once it exceeds this many bytes. */
+    maxBytes?: number;
+    /** Upper bound on how much of the log tail recent() will read. */
+    tailBytes?: number;
 }
 export interface PeonLogEntry {
     id: string;
@@ -9,9 +13,25 @@ export interface PeonLogEntry {
 }
 export declare class PeonLogger {
     private readonly logFile;
+    private readonly maxBytes;
+    private readonly tailBytes;
     private writeQueue;
+    private bytesWritten;
+    private sizeKnown;
     constructor(options?: PeonLoggerOptions);
     log(type: string, fields?: Record<string, unknown>): Promise<PeonLogEntry>;
+    /**
+     * Newest-first entries from the tail of the log. Cost is bounded by
+     * `tailBytes`, not by the size of the file, so this stays flat as the log
+     * grows. Entries older than the tail window are not visible here — the log
+     * file itself (and its rotated siblings) remain the full record.
+     */
     recent(limit?: number): Promise<PeonLogEntry[]>;
+    private readTail;
+    /**
+     * Move the live log aside once it exceeds maxBytes. History is preserved in a
+     * timestamped sibling rather than truncated, so nothing is lost.
+     */
+    private rotateIfNeeded;
     private enqueueWrite;
 }