hippo-memory 1.70.0 → 1.72.0

package/dist/postinstall.js

@@ -3,15 +3,14 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { detectRealCodexPath, isCodexWrapperInstalled, repairCodexWrapperIfInstalled } from './hooks/codex-wrapper.js';
-import { claudeConfigDir } from './hooks/shared.js';
+import { claudeConfigDir } from './util/agent-homes.js';
 import { errorMessage, log } from './util/log.js';
 function main() {
     if (envSkipPostinstall())
         return;
     try {
-        // Repair-only, for users who opted in (a Codex update can restore the real binary over our shim).
-        // Swapping the binary from postinstall is a consent violation that supply-chain scanners read as
-        // hijacking, so first install is `hippo hook install codex` only.
+        // Repair-only, for users who opted in (a Codex update can restore the real binary over our shim): swapping the binary from postinstall
+        // is a consent violation that supply-chain scanners read as hijacking, so first install is `hippo hook install codex` only.
         repairCodexWrapperIfInstalled();
     }
     catch (err) {
@@ -31,16 +30,8 @@ function main() {
         // Never fail package install because the install hint could not be printed.
     }
 }
-/**
- * Read-only nudge: if Claude Code is detected on the machine and the Hippo
- * UserPromptSubmit hook is NOT yet installed, print a short message pointing
- * the user at `hippo init`. No config writes. Silent otherwise.
- *
- * We avoid aggressively auto-patching ~/.claude/settings.json from a package
- * postinstall — that's surprising, breaks the principle of least authority,
- * and trips security scanners. A one-line visible prompt is the friendly
- * middle ground.
- */
+/** Read-only nudge: if Claude Code is detected and the Hippo UserPromptSubmit hook is not installed, point the user at `hippo init`.
+ * It never patches ~/.claude/settings.json from a package postinstall: surprising, against least authority, and trips security scanners. */
 function printClaudeCodeNudge() {
     const claudeDir = claudeConfigDir(os.homedir());
     if (!fs.existsSync(claudeDir))
@@ -76,12 +67,8 @@ function printClaudeCodeNudge() {
     line('To skip this message on future installs: export HIPPO_SKIP_POSTINSTALL=1');
     line('');
 }
-/**
- * Read-only nudge: if the Codex CLI is on PATH and the Hippo session-capture
- * wrapper is NOT installed, print the opt-in command. Mirrors the Claude Code
- * nudge above — same least-authority reasoning: we tell the user what to run,
- * we never swap their binary for them.
- */
+/** Read-only nudge: if the Codex CLI is on PATH and the session-capture wrapper is not installed, print the opt-in command;
+ * same least-authority reasoning as the Claude Code nudge, we never swap the user's binary. */
 function printCodexNudge() {
     if (isCodexWrapperInstalled())
         return;

package/dist/predictions/planning-fallacy.d.ts

@@ -1,15 +1,8 @@
 import type { AppendAuditOpts } from '../store/audit.js';
 import { type ForwardClaimMatch } from '../learn/forward-claim-detector.js';
 import type { PlanningFallacyEvidence } from '../store/planning-fallacy-evidence.js';
-/**
- * Surface delivered on `RecallResult.planningFallacyHint` when an
- * agent's recall query carries a forward-prediction phrase AND the closest
- * matching prediction class has closed historical data.
- *
- * The agent sees its track record at the moment of forecasting, anchoring
- * on the outside view (Lovallo-Kahneman 2003) rather than the inside-view
- * inside the planning fallacy.
- */
+/** Surface delivered on `RecallResult.planningFallacyHint` when a recall query carries a forward-prediction phrase and the closest class has closed history,
+ *  so the agent sees its own track record at the moment of forecasting. */
 export interface PlanningFallacyHint {
     classTag: string;
     /** Verbatim PredictionBaserate.summary, e.g.
@@ -17,50 +10,34 @@ export interface PlanningFallacyHint {
     baserateSummary: string;
     /** Discriminator vs hypothetical future manual-override hints. */
     source: 'j3.2-auto';
-    /** The regex match snippet that triggered detection. Lets the agent
-     *  see WHY the hint appeared and self-correct if detection misfires
-     *  (e.g. "I wasn't predicting; ignore"). */
+    /** The regex match snippet that triggered detection, so the agent sees WHY the hint appeared and can self-correct if detection misfired. */
     detectedPhrase: string;
     nClosed: number;
     /** Null only when every closed-row had estimate_value=0 (ratio undefined). */
     meanRatio: number | null;
 }
-/**
- * "Watching" variant emitted when the forward-claim regex matched but no
- * PlanningFallacyHint baserate was returned. Silence was the most common
- * real-world failure: a natural-language query carries a
- * forward-claim phrase but its non-stopword tokens don't overlap with
- * any prediction class tag, so hippo emitted nothing despite
- * the regex match. The watching variant surfaces the detection event
- * + a one-line suggestion so the agent can either re-tag the prediction
- * or pass the suggestion through to the user.
- */
+/** "Watching" variant emitted when the forward-claim regex matched but no baserate hint was returned (no prediction class tag overlaps the query's tokens).
+ *  It surfaces the detection plus a one-line suggestion so the agent can re-tag the prediction or pass the suggestion to the user. */
 export interface PlanningFallacyWatching {
     /** The forward-claim phrase the detector matched (verbatim regex match snippet). */
     detectedPhrase: string;
-    /** Why hippo couldn't produce a baserate hint despite the match.
-     *  - 'no_class_match': no class scored >=1 on token overlap.
-     *  - 'tiebreak': >=2 classes tied at the same best score (silent on ambiguity). */
+    /** Why hippo could not produce a baserate hint despite the match: 'no_class_match' (no class scored >=1 on token overlap)
+     *  or 'tiebreak' (>=2 classes tied at the best score; silent on ambiguity). */
     reason: 'no_class_match' | 'tiebreak';
     /** One-line agent-facing suggestion for how the user can give hippo
      *  enough signal to produce a baserate next time. */
     suggestion: string;
 }
-/**
- * What `decidePlanningFallacy` hands to recall. Carries EITHER `hint` (baserate
- * available) OR `watching` (regex fired, no baserate), or NEITHER (mode=off,
- * no queryText, no regex match, or nClosed=0 silent path). Never both.
- */
+/** What `decidePlanningFallacy` hands to recall: EITHER `hint` (baserate available) OR `watching` (regex fired, no baserate), or NEITHER (mode=off,
+ *  no queryText, no regex match, or nClosed=0). Never both. */
 export interface PlanningFallacyOutput {
     hint?: PlanningFallacyHint;
     watching?: PlanningFallacyWatching;
 }
 export type AutodebiasMode = 'off' | 'regex';
 export interface ComputePlanningFallacyHintOpts {
-    /** Override env. When undefined, reads process.env.HIPPO_AUTODEBIAS at
-     *  call time (per-call to allow test-time env toggling without module
-     *  reload). 'off' short-circuits to null BEFORE the regex gate so the
-     *  AUTODEBIAS=off path pays zero work. */
+    /** Override env; undefined reads process.env.HIPPO_AUTODEBIAS per call (so tests can toggle it).
+     *  'off' short-circuits to null before the regex gate. */
     mode?: AutodebiasMode;
 }
 /** The output a claim earns from its evidence, and the audit row that records the decision when there is one. */

package/dist/rerankers/clef.js

@@ -1,15 +1,14 @@
 import { envClefEndpoint, envClefEndpointToken, envClefTimeoutMs, envCloudflareAccountId, envCloudflareApiToken } from '../util/env.js';
 import { buildRelevanceRequest, JEV_DEFAULT_TOP_K, rankByScores } from './jev.js';
 import { createOutageWarning } from './outage-warning.js';
-import { rerankerPost } from './remote.js';
-import { isJsonObject } from '../util/json.js';
+import { rerankerPost, RERANKER_MAX_REPLY_BYTES } from './remote.js';
+import { readCappedJson } from '../util/capped-json.js';
+import { isJsonObject, isJsonString } from '../util/json.js';
 import { errorMessage } from '../util/log.js';
 const RAY_ID_MAX_CHARS = 64;
 const CLEF_MODELS = ['clef-flash', 'clef'];
 const DEFAULT_TIMEOUT_MS = 15_000;
 const MAX_TIMEOUT_MS = 120_000;
-// 64 answers fit in a few KB; 1 MiB leaves room for a verbose envelope.
-const MAX_REPLY_BYTES = 1024 * 1024;
 // Workers AI rejects a request with more than 64 questions, one per candidate here.
 const MAX_CANDIDATES = 64;
 const ACCOUNT_ID = /^[0-9a-f]{32}$/i;
@@ -24,9 +23,6 @@ function isLoopback(hostname) {
 function isNumber(v) {
     return Number.isFinite(v);
 }
-function isString(v) {
-    return v !== undefined && v !== null && v.constructor === String;
-}
 function isRejection(v) {
     return v.constructor === String;
 }
@@ -84,7 +80,7 @@ export function parseClefReply(body, n, model, requireModel) {
     if (!isJsonObject(reply))
         return 'reply has no result object';
     const actual = reply.model;
-    if (actual !== undefined && (!isString(actual) || actual.trim() !== model))
+    if (actual !== undefined && (!isJsonString(actual) || actual.trim() !== model))
         return 'reply names a different model';
     if (actual === undefined && requireModel)
         return 'reply does not name its model';
@@ -106,38 +102,11 @@ export function parseClefReply(body, n, model, requireModel) {
     const usage = isJsonObject(reply.usage) ? reply.usage : {};
     return {
         scores,
-        actualModel: isString(actual) ? actual.trim() : undefined,
+        actualModel: isJsonString(actual) ? actual.trim() : undefined,
         inputTokens: isNumber(usage.input_tokens) ? usage.input_tokens : undefined,
         outputTokens: isNumber(usage.output_tokens) ? usage.output_tokens : undefined,
     };
 }
-// The timeout bounds time, not bytes: a hostile endpoint could stream a huge 2xx body into memory.
-async function readCappedJson(resp) {
-    if (!resp.body)
-        throw new Error('reply has no body');
-    const reader = resp.body.getReader();
-    const decoder = new TextDecoder();
-    let raw = '';
-    let received = 0;
-    for (;;) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        received += value.byteLength;
-        if (received > MAX_REPLY_BYTES) {
-            await reader.cancel();
-            throw new Error(`reply over ${MAX_REPLY_BYTES} bytes`);
-        }
-        raw += decoder.decode(value, { stream: true });
-    }
-    raw += decoder.decode();
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        throw new Error('reply is not JSON');
-    }
-}
 async function requestScores(model, query, head, route) {
     const { state, questions } = buildRelevanceRequest(query, head);
     // Strict parse: parseInt would read "15s" as 15 ms, and Node clamps a delay past 2^31-1 to 1 ms.
@@ -153,7 +122,7 @@ async function requestScores(model, query, head, route) {
         await resp.body?.cancel();
         throw new Error(`HTTP ${resp.status}${ray ? `, ray ${ray}` : ''}`);
     }
-    const body = await readCappedJson(resp);
+    const body = await readCappedJson(resp, RERANKER_MAX_REPLY_BYTES);
     const parsed = parseClefReply(body, head.length, model, route.backend === 'cloudflare');
     if (isRejection(parsed))
         throw new Error(parsed);

package/dist/rerankers/cross-encoder.d.ts

@@ -1,4 +1,33 @@
 import type { RerankerFn } from './types.js';
-/** Track 2 reranker: MS-MARCO MiniLM cross-encoder, identity fallback if the model will not load. */
-export declare const crossEncoderReranker: RerankerFn;
+interface Tokenized {
+    readonly input_ids: object;
+    readonly attention_mask: object;
+}
+type TokenizerFn = (text: string, opts: {
+    text_pair: string;
+    padding: boolean;
+    truncation: boolean;
+}) => Promise<Tokenized>;
+type SeqClsModel = (inputs: Tokenized) => Promise<{
+    logits: {
+        data: ArrayLike<number>;
+    };
+}>;
+interface FromPretrained<T> {
+    from_pretrained: (model: string) => Promise<T>;
+}
+interface TransformersExports {
+    AutoTokenizer?: FromPretrained<TokenizerFn>;
+    AutoModelForSequenceClassification?: FromPretrained<SeqClsModel>;
+}
+interface TransformersModuleNamespace extends TransformersExports {
+    default?: TransformersExports;
+}
+type ImportModule = () => Promise<{
+    readonly name: string;
+    readonly mod: TransformersModuleNamespace;
+} | null>;
+/** Track 2 reranker: MS-MARCO MiniLM cross-encoder, identity fallback if the model will not load. Each instance owns its model and outage warning. */
+export declare function createCrossEncoderReranker(importModule?: ImportModule): RerankerFn;
+export {};
 //# sourceMappingURL=cross-encoder.d.ts.map

package/dist/rerankers/cross-encoder.js

@@ -1,110 +1,53 @@
-import { createRequire } from 'node:module';
-import { pathToFileURL } from 'node:url';
 import { createOutageWarning } from './outage-warning.js';
 import { compareScoresDesc } from '../core/compare.js';
-import { errorMessage, log } from '../util/log.js';
+import { createModelLoads, importTransformers, MODEL_LOAD_POLICY } from '../embeddings/transformers.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 const DEFAULT_CROSS_ENCODER_TOP_K = 50;
 const MODEL_NAME = 'Xenova/ms-marco-MiniLM-L-6-v2';
-const _require = createRequire(import.meta.url);
-const TRANSFORMERS_PACKAGES = ['@huggingface/transformers', '@xenova/transformers'];
-// Returns the ESM entry URL, the same build src/store/embeddings/index.ts imports. A
-// require-style resolve picks the CommonJS build and puts a second copy of
-// the library, with its own ONNX sessions, in the process.
-function resolveTransformersPackage() {
-    for (const name of TRANSFORMERS_PACKAGES) {
-        try {
-            return import.meta.resolve(name);
-        }
-        catch {
-            // import.meta.resolve is missing under some module runners (vitest's
-            // included); fall through to the require-based resolve there.
-            try {
-                return pathToFileURL(_require.resolve(name)).href;
-            }
-            catch {
-                // Try the legacy fallback only when the preferred package is not installed.
-            }
-        }
-    }
-    return null;
+async function importModelClasses(importModule) {
+    const imported = await importModule();
+    if (!imported)
+        throw new Error('no Transformers.js package is installed');
+    const { name, mod } = imported;
+    const tok = mod.AutoTokenizer ?? mod.default?.AutoTokenizer;
+    const seq = mod.AutoModelForSequenceClassification ?? mod.default?.AutoModelForSequenceClassification;
+    if (!tok || !seq)
+        throw new Error(`${name} exports no AutoTokenizer or AutoModelForSequenceClassification`);
+    return { AutoTokenizer: tok, AutoModelForSequenceClassification: seq };
 }
-async function loadTransformersModule() {
-    // Import one backend only. Loading both native ONNX runtimes in one process
-    // can abort during finalization; Hugging Face is the maintained default.
-    const url = resolveTransformersPackage();
-    if (!url)
-        return null;
-    try {
-        const mod = await import(/* @vite-ignore */ url);
-        const tok = mod.AutoTokenizer ?? mod.default?.AutoTokenizer;
-        const seq = mod.AutoModelForSequenceClassification ?? mod.default?.AutoModelForSequenceClassification;
-        return tok && seq ? { AutoTokenizer: tok, AutoModelForSequenceClassification: seq } : null;
-    }
-    catch (err) {
-        log.debug(`cross-encoder: transformers import failed: ${errorMessage(err)}`);
-        return null;
-    }
+// NOT the text-classification pipeline: this is a num_labels=1 regression head and that pipeline softmaxes a length-1 logit vector (always 1.0).
+// Read the logit, then squash it.
+async function buildPipeline(importModule) {
+    const mod = await importModelClasses(importModule);
+    const [tokenizer, model] = await Promise.all([
+        mod.AutoTokenizer.from_pretrained(MODEL_NAME),
+        mod.AutoModelForSequenceClassification.from_pretrained(MODEL_NAME),
+    ]);
+    return async (query, candidate) => {
+        const inputs = await tokenizer(query, {
+            text_pair: candidate,
+            padding: true,
+            truncation: true,
+        });
+        const { logits } = await model(inputs);
+        const score = 1 / (1 + Math.exp(-Number(logits.data[0])));
+        // NaN would make the sort comparator a no-op; throwing hands this
+        // candidate to the per-candidate fallback instead.
+        if (!Number.isFinite(score))
+            throw new Error('cross-encoder returned a non-finite score');
+        return score;
+    };
 }
-let pipelineLoading = null;
-const outage = createOutageWarning('cross-encoder', 'falling back to identity ordering');
-// NOT the text-classification pipeline: this model is a num_labels=1
-// regression head, and that pipeline softmaxes a length-1 logit vector, which
-// is identically 1.0 for every input. Read the logit, then squash it.
-async function buildPipeline() {
-    try {
-        const mod = await loadTransformersModule();
-        if (!mod)
-            return null;
-        const [tokenizer, model] = await Promise.all([
-            mod.AutoTokenizer.from_pretrained(MODEL_NAME),
-            mod.AutoModelForSequenceClassification.from_pretrained(MODEL_NAME),
-        ]);
-        return async (query, candidate) => {
-            const inputs = await tokenizer(query, {
-                text_pair: candidate,
-                padding: true,
-                truncation: true,
-            });
-            const { logits } = await model(inputs);
-            const score = 1 / (1 + Math.exp(-Number(logits.data[0])));
-            // NaN would make the sort comparator a no-op; throwing hands this
-            // candidate to the per-candidate fallback instead.
-            if (!Number.isFinite(score))
-                throw new Error('cross-encoder returned a non-finite score');
-            return score;
-        };
-    }
-    catch (err) {
-        log.debug(`cross-encoder: model load failed: ${errorMessage(err)}`);
-        return null;
-    }
-}
-// One shared in-flight load: two first calls must not fetch the model twice.
-// A failed load clears the slot so a later call can try again.
-function loadPipeline() {
-    pipelineLoading ??= buildPipeline().then((pipe) => {
-        if (!pipe)
-            pipelineLoading = null;
-        return pipe;
-    });
-    return pipelineLoading;
+/** The head in its input order, scored as it came. */
+function identityOrder(head) {
+    return head.map((r, i) => ({
+        ...r,
+        rerankScore: r.score,
+        preRerankRank: r.preRerankRank ?? i + 1,
+        postRerankRank: i + 1,
+    }));
 }
-/** Track 2 reranker: MS-MARCO MiniLM cross-encoder, identity fallback if the model will not load. */
-export const crossEncoderReranker = async (query, results, options) => {
-    const topK = options?.topK ?? DEFAULT_CROSS_ENCODER_TOP_K;
-    const head = results.slice(0, topK);
-    const pipe = await loadPipeline();
-    if (!pipe) {
-        // A silent identity fallback otherwise reads as a working reranker.
-        outage.failed('no Transformers.js backend, or model fetch blocked');
-        return head.map((r, i) => ({
-            ...r,
-            rerankScore: r.score,
-            preRerankRank: r.preRerankRank ?? i + 1,
-            postRerankRank: i + 1,
-        }));
-    }
-    outage.answered();
+async function scoreHead(pipe, query, head) {
     const scored = await Promise.all(head.map(async (r, i) => {
         let ceScore;
         try {
@@ -127,5 +70,26 @@ export const crossEncoderReranker = async (query, results, options) => {
     scored.sort((a, b) => compareScoresDesc(a.rerankScore, b.rerankScore));
     scored.forEach((r, i) => (r.postRerankRank = i + 1));
     return scored;
-};
+}
+/** Track 2 reranker: MS-MARCO MiniLM cross-encoder, identity fallback if the model will not load. Each instance owns its model and outage warning. */
+export function createCrossEncoderReranker(importModule = importTransformers) {
+    const outage = createOutageWarning('cross-encoder', 'falling back to identity ordering');
+    // The outage warning already says each failure, at most once per window, so the loads report nothing themselves.
+    const pipelines = createModelLoads(MODEL_LOAD_POLICY);
+    return async (query, results, options) => {
+        const head = results.slice(0, options?.topK ?? DEFAULT_CROSS_ENCODER_TOP_K);
+        let pipe;
+        try {
+            // One shared load per backoff window: two first calls fetch the model once, and a failure is not fetched again on every recall.
+            pipe = await pipelines.load(MODEL_NAME, () => buildPipeline(importModule));
+        }
+        catch (err) {
+            // A silent identity fallback otherwise reads as a working reranker.
+            outage.failed(errorMessage(err), errorFields(err));
+            return identityOrder(head);
+        }
+        outage.answered();
+        return scoreHead(pipe, query, head);
+    };
+}
 //# sourceMappingURL=cross-encoder.js.map

package/dist/rerankers/index.js

@@ -1,13 +1,14 @@
 import { createClefReranker } from './clef.js';
-import { crossEncoderReranker } from './cross-encoder.js';
+import { createCrossEncoderReranker } from './cross-encoder.js';
 import { createJevReranker } from './jev.js';
 import { createLlmReranker } from './llm.js';
-// Each hosted reranker is built once here, so its outage warning lasts the process.
+// Each reranker is built once here, so its outage warning lasts the process; jev falls back to the same cross-encoder, so one model loads.
+const crossEncoder = createCrossEncoderReranker();
 const REGISTRY = {
     clef: createClefReranker('clef'),
     'clef-flash': createClefReranker('clef-flash'),
-    'cross-encoder': crossEncoderReranker,
-    jev: createJevReranker(crossEncoderReranker),
+    'cross-encoder': crossEncoder,
+    jev: createJevReranker(crossEncoder),
     llm: createLlmReranker(),
 };
 function isRegisteredRerankerName(name) {

package/dist/rerankers/jev.js

@@ -1,7 +1,10 @@
+import { truncateWithEllipsis } from '../util/ellipsize.js';
 import { envJevModel, envJevTimeoutMs, envTypesafeApiKey } from '../util/env.js';
 import { redactSecretsStrict } from '../util/secret-detect.js';
 import { createOutageWarning } from './outage-warning.js';
-import { rerankerPost } from './remote.js';
+import { rerankerPost, RERANKER_MAX_REPLY_BYTES } from './remote.js';
+import { readCappedJson } from '../util/capped-json.js';
+import { isJsonNumber, isJsonObject } from '../util/json.js';
 import { compareScoresDesc } from '../core/compare.js';
 import { errorMessage } from '../util/log.js';
 const REQUEST_ID_MAX_CHARS = 64;
@@ -13,20 +16,19 @@ const TRUNCATE_CHARS = 1200;
 const DEFAULT_MODEL = 'jev-1.13.0';
 // The pool size the eval numbers were measured at.
 export const JEV_DEFAULT_TOP_K = 40;
-function truncate(s, n) {
-    return s.length <= n ? s : `${s.slice(0, n)}...`;
-}
 // Number.isFinite rejects a string or null without coercing it, which the
 // declared type cannot promise about a third-party payload.
 function isProbability(v) {
-    return v !== undefined && Number.isFinite(v) && v >= 0 && v <= 1;
+    return isJsonNumber(v) && Number.isFinite(v) && v >= 0 && v <= 1;
 }
 // A half-scored list ranks worse than the order it would replace, so one bad
 // answer voids the whole response.
-function parseScores(answers, n) {
+function parseScores(body, n) {
+    const answers = isJsonObject(body) ? body.answers : undefined;
     const out = [];
     for (let i = 1; i <= n; i++) {
-        const v = answers?.[`c${i}`]?.noul;
+        const answer = isJsonObject(answers) ? answers[`c${i}`] : undefined;
+        const v = isJsonObject(answer) ? answer.noul : undefined;
         if (!isProbability(v))
             return null;
         out.push(v);
@@ -36,7 +38,7 @@ function parseScores(answers, n) {
 /** Redacted query plus numbered, redacted, truncated candidates. Shared with CLEF so both arms see matched input. */
 export function buildRelevanceRequest(query, head) {
     // Strict: this text leaves the machine, so Bearer, Basic-auth and JWT shapes go too.
-    const lines = head.map((r, i) => `[${i + 1}] ${truncate(redactSecretsStrict(r.entry.content), TRUNCATE_CHARS)}`);
+    const lines = head.map((r, i) => `[${i + 1}] ${truncateWithEllipsis(redactSecretsStrict(r.entry.content), TRUNCATE_CHARS)}`);
     const state = `Query: ${redactSecretsStrict(query)}\n\nNumbered candidate memories from an AI coding agent's project store:\n\n${lines.join('\n\n')}`;
     const questions = {};
     for (let i = 1; i <= head.length; i++) {
@@ -67,8 +69,7 @@ async function requestScores(query, head) {
         await resp.body?.cancel();
         throw new Error(`HTTP ${resp.status}${requestId ? `, request ${requestId}` : ''}`);
     }
-    const body = await resp.json();
-    const scores = parseScores(body.answers, head.length);
+    const scores = parseScores(await readCappedJson(resp, RERANKER_MAX_REPLY_BYTES), head.length);
     if (!scores)
         throw new Error('incomplete or out-of-range answers');
     return scores;

package/dist/rerankers/llm.d.ts

@@ -1,14 +1,5 @@
 import type { RerankerFn } from './types.js';
-/**
- * Track 3 reranker: listwise LLM rerank. Uses a customer-supplied
- * OpenAI-compatible endpoint. Gated on HIPPO_LLM_RERANKER_URL to prevent
- * accidental cost.
- *
- * Skeleton only; full characterisation is deferred.
- *
- * Timeout: defaults to 30s for the whole call, retries included; overridable
- * via HIPPO_LLM_RERANKER_TIMEOUT_MS. On timeout or any failure the reranker
- * falls back to identity ordering; recall must not hang on a wedged endpoint.
- */
+/** Track 3 reranker (skeleton): listwise LLM rerank on a customer-supplied OpenAI-compatible endpoint, gated on HIPPO_LLM_RERANKER_URL against accidental cost.
+ * Timeout is 30s for the whole call, retries included (HIPPO_LLM_RERANKER_TIMEOUT_MS); any failure falls back to identity ordering, so recall never hangs. */
 export declare function createLlmReranker(): RerankerFn;
 //# sourceMappingURL=llm.d.ts.map

package/dist/rerankers/llm.js

@@ -1,21 +1,14 @@
 import { envLlmRerankerKey, envLlmRerankerModel, envLlmRerankerTimeoutMs, envLlmRerankerUrl } from '../util/env.js';
 import { redactSecretsStrict } from '../util/secret-detect.js';
 import { createOutageWarning } from './outage-warning.js';
-import { rerankerPost } from './remote.js';
+import { rerankerPost, RERANKER_MAX_REPLY_BYTES } from './remote.js';
+import { readCappedJson } from '../util/capped-json.js';
+import { isJsonObject, isJsonString } from '../util/json.js';
 import { errorMessage } from '../util/log.js';
 const DEFAULT_LLM_RERANK_TOP_K = 20;
 const DEFAULT_TIMEOUT_MS = 30_000;
-/**
- * Track 3 reranker: listwise LLM rerank. Uses a customer-supplied
- * OpenAI-compatible endpoint. Gated on HIPPO_LLM_RERANKER_URL to prevent
- * accidental cost.
- *
- * Skeleton only; full characterisation is deferred.
- *
- * Timeout: defaults to 30s for the whole call, retries included; overridable
- * via HIPPO_LLM_RERANKER_TIMEOUT_MS. On timeout or any failure the reranker
- * falls back to identity ordering; recall must not hang on a wedged endpoint.
- */
+/** Track 3 reranker (skeleton): listwise LLM rerank on a customer-supplied OpenAI-compatible endpoint, gated on HIPPO_LLM_RERANKER_URL against accidental cost.
+ * Timeout is 30s for the whole call, retries included (HIPPO_LLM_RERANKER_TIMEOUT_MS); any failure falls back to identity ordering, so recall never hangs. */
 export function createLlmReranker() {
     const outage = createOutageWarning('llm', 'keeping the input order');
     return async (query, results, options) => {
@@ -42,6 +35,14 @@ export function createLlmReranker() {
         }));
     };
 }
+/** The first choice's message text, or '' when the reply has none. */
+function replyText(body) {
+    const choices = isJsonObject(body) ? body.choices : undefined;
+    const choice = Array.isArray(choices) ? choices[0] : undefined;
+    const message = isJsonObject(choice) ? choice.message : undefined;
+    const content = isJsonObject(message) ? message.content : undefined;
+    return isJsonString(content) ? content : '';
+}
 /** One chat-completions call; rejects with the reason when the reply holds no usable permutation. */
 async function requestPermutation(url, query, head) {
     const key = envLlmRerankerKey();
@@ -69,8 +70,7 @@ async function requestPermutation(url, query, head) {
         await resp.body?.cancel();
         throw new Error(`HTTP ${resp.status}`);
     }
-    const j = await resp.json();
-    const txt = j.choices?.[0]?.message?.content ?? '';
+    const txt = replyText(await readCappedJson(resp, RERANKER_MAX_REPLY_BYTES));
     const m = txt.match(/\[\s*(\d+(?:\s*,\s*\d+)*)\s*\]/);
     const parsed = m ? m[1].split(',').map((s) => parseInt(s.trim(), 10)) : [];
     const isPermutation = parsed.length === head.length &&

package/dist/rerankers/outage-warning.d.ts

@@ -1,7 +1,10 @@
+import { type LogFields } from '../util/log.js';
 export interface OutageWarning {
-    failed(reason: string): void;
+    /** `fields` carries the error's class and stack onto the warning line. */
+    failed(reason: string, fields?: LogFields): void;
     answered(): void;
 }
-/** Warns when `name` starts failing, at most every five minutes while it keeps failing, and once when it answers again. `fallback` says what recall does meanwhile. */
+/** Warns when `name` starts failing, at most every five minutes while it keeps failing,
+ * and once when it answers again. `fallback` says what recall does meanwhile. */
 export declare function createOutageWarning(name: string, fallback: string): OutageWarning;
 //# sourceMappingURL=outage-warning.d.ts.map

package/dist/rerankers/outage-warning.js

@@ -1,20 +1,23 @@
 // One way for a reranker to report that it stopped working, without a line per recall.
+import { MINUTE_MS } from '../util/time.js';
 import { log } from '../util/log.js';
-const REPEAT_MS = 5 * 60_000;
-/** Warns when `name` starts failing, at most every five minutes while it keeps failing, and once when it answers again. `fallback` says what recall does meanwhile. */
+const REPEAT_MS = 5 * MINUTE_MS;
+/** Warns when `name` starts failing, at most every five minutes while it keeps failing,
+ * and once when it answers again. `fallback` says what recall does meanwhile. */
 export function createOutageWarning(name, fallback) {
     let failures = 0;
     let unreported = 0;
     let warnedAt = 0;
     return {
-        failed(reason) {
+        failed(reason, fields) {
             failures++;
             if (failures > 1 && Date.now() - warnedAt < REPEAT_MS) {
                 unreported++;
                 return;
             }
             const skipped = unreported > 0 ? ` ${unreported} more calls failed since the last warning.` : '';
-            log.warn(`${name} reranker unavailable (${reason}); ${fallback}.${skipped} While it fails this repeats at most every ${REPEAT_MS / 60_000} minutes.`);
+            const repeat = `While it fails this repeats at most every ${REPEAT_MS / MINUTE_MS} minutes.`;
+            log.warn(`${name} reranker unavailable (${reason}); ${fallback}.${skipped} ${repeat}`, fields);
             warnedAt = Date.now();
             unreported = 0;
         },

package/dist/rerankers/remote.d.ts

@@ -1,3 +1,4 @@
+export declare const RERANKER_MAX_REPLY_BYTES: number;
 /** POST a scoring request. A dropped connection, 429 or 5xx is retried, since scoring changes nothing on the far side. */
 export declare function rerankerPost(url: string, init: RequestInit, budgetMs: number): Promise<Response>;
 //# sourceMappingURL=remote.d.ts.map

package/dist/rerankers/remote.js

@@ -2,6 +2,8 @@
 import { fetchWithRetry } from '../util/http-retry.js';
 // A Retry-After longer than this would outlast most budgets, so the answer is handed back and the reranker falls back.
 const RETRY_WAIT_CAP_MS = 2_000;
+// Every reranker reads its reply through this cap; the largest honest reply is a few KB, and 1 MiB leaves room for a verbose envelope.
+export const RERANKER_MAX_REPLY_BYTES = 1024 * 1024;
 /** POST a scoring request. A dropped connection, 429 or 5xx is retried, since scoring changes nothing on the far side. */
 export async function rerankerPost(url, init, budgetMs) {
     // The budget bounds the whole call, retries included, so recall never waits past the configured timeout.