hippo-memory 1.71.0 → 2.0.0

package/dist/mcp/tool-args.js

@@ -1,4 +1,5 @@
 // Hand-written for the JSON Schema subset the hippo tool definitions use, so the MCP server needs no validator dependency.
+import { truncateWithEllipsis } from '../util/ellipsize.js';
 const ARG_PREVIEW_CHARS = 40;
 function isArgString(v) {
     return typeof v === 'string';
@@ -24,7 +25,7 @@ function describeValue(v) {
     if (Array.isArray(v))
         return 'array';
     if (isArgString(v))
-        return JSON.stringify(v.length > ARG_PREVIEW_CHARS ? `${v.slice(0, ARG_PREVIEW_CHARS)}...` : v);
+        return JSON.stringify(truncateWithEllipsis(v, ARG_PREVIEW_CHARS));
     if (isArgNumber(v) || isArgBoolean(v))
         return String(v);
     return 'object';

package/dist/mcp/tools.js

@@ -1,18 +1,18 @@
 // Tool definitions and input schemas served by tools/list.
 import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
 import { DEFAULT_ASSEMBLE_BUDGET } from '../api/assemble.js';
-import { MAX_ID_LEN } from '../util/http-util.js';
+import { MAX_ID_LEN, MAX_LIST_LIMIT } from '../util/limits.js';
 import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../store/rows.js';
 import { DEFAULT_CONFIG } from '../core/config.js';
 // ── Tool definitions ──
 // HTTP sets no budget cap; 25x the recall default leaves room for large-context clients while bounding one call's work.
 const MAX_BUDGET_TOKENS = 25 * DEFAULT_RECALL_BUDGET;
-// Same ceiling as the HTTP list routes' parseListLimit.
-const MAX_LIST_LIMIT = 1000;
 export const TOOLS = [
     {
         name: 'hippo_recall',
-        description: 'Retrieve relevant memories from the project memory store. Returns memories ranked by relevance, strength, and recency within the token budget. Use at session start or when you need context about a topic. Pass include_continuity=true to also surface the active task snapshot, latest matching session handoff, and recent session events as a "## Continuity" appendix.',
+        description: 'Retrieve relevant memories from the project memory store. Returns memories ranked by relevance, strength, and recency within the token budget. Use ' +
+            'at session start or when you need context about a topic. Pass include_continuity=true to also surface the active task snapshot, latest matching ' +
+            'session handoff, and recent session events as a "## Continuity" appendix.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -29,28 +29,37 @@ export const TOOLS = [
                 },
                 scope: {
                     type: 'string',
-                    description: 'Restrict results and continuity to memories/rows matching this scope exactly. When omitted, default-deny applies to ANY <source>:private:* (slack, github, ...) and unknown-legacy rows.',
+                    description: 'Restrict results and continuity to memories/rows matching this scope exactly. When omitted, default-deny applies to ANY ' +
+                        '<source>:private:* (slack, github, ...) and unknown-legacy rows.',
                 },
                 fresh_tail_count: {
                     type: 'number',
-                    description: 'When > 0, surface the last N kind=raw rows tagged isFreshTail=true regardless of query match. Useful for "what did I just see" continuity. Capped at 200.',
+                    description: 'When > 0, surface the last N kind=raw rows tagged isFreshTail=true regardless of query match. Useful for "what did I just see" ' +
+                        'continuity. Capped at 200.',
                 },
                 fresh_tail_session_id: {
                     type: 'string',
-                    description: 'Restrict the fresh-tail window to a specific session. Without this, fresh-tail is tenant-wide (legacy v1.5.2 behaviour, pre-v1.6.3 default).',
+                    description: 'Restrict the fresh-tail window to a specific session. Without this, fresh-tail is tenant-wide (legacy v1.5.2 behaviour, pre-v1.6.3 ' +
+                        'default).',
                 },
                 summarize_overflow: {
                     type: 'boolean',
-                    description: 'When true (default), entries that overflow the limit and share a level-2 parent summary cause that summary to be appended in their place. Set false for strict-limit behaviour.',
+                    description: 'When true (default), entries that overflow the limit and share a level-2 parent summary cause that summary to be appended in their ' +
+                        'place. Set false for strict-limit behaviour.',
                 },
                 scorer_window: {
                     type: 'number',
-                    description: `How many of the top-ranked memories the fresh-tail and summarize-overflow appendix is worked out against. The main list ranks the whole tenant store, so scorer_window does not narrow it. Default ${DEFAULT_SEARCH_CANDIDATE_LIMIT}. Rejected as RecallContractError code=invalid_scorer_window if 0/negative/non-finite/non-numeric.`,
+                    description: `How many of the top-ranked memories the fresh-tail and summarize-overflow appendix is worked out against. ` +
+                        `The main list ranks the whole tenant store, so scorer_window does not narrow it. ` +
+                        `Default ${DEFAULT_SEARCH_CANDIDATE_LIMIT}. ` +
+                        `Rejected as RecallContractError code=invalid_scorer_window if 0/negative/non-finite/non-numeric.`,
                 },
                 session_id: {
                     type: 'string',
                     maxLength: MAX_ID_LEN,
-                    description: `Optional session id (v1.7.4). When set AND (tenant, session) has active goals, applies the dlPFC goal-stack boost to the ranked memories before formatting. Mirrors fresh_tail_session_id shape (${MAX_ID_LEN}-char cap).`,
+                    description: `Optional session id (v1.7.4). When set AND (tenant, session) has active goals, ` +
+                        `applies the dlPFC goal-stack boost to the ranked memories before formatting. ` +
+                        `Mirrors fresh_tail_session_id shape (${MAX_ID_LEN}-char cap).`,
                 },
             },
             required: ['query'],
@@ -58,7 +67,9 @@ export const TOOLS = [
     },
     {
         name: 'hippo_assemble',
-        description: 'Build a chronologically-ordered context window for a session. Returns ordered items: fresh-tail raw rows + level-2 summary substitutions for older rows + budget-fit. Hippo-additive vs lossless-claw: eviction picks lowest-strength non-fresh-tail items first instead of oldest-first. Tenant-scoped; default-deny on private scopes.',
+        description: 'Build a chronologically-ordered context window for a session. Returns ordered items: fresh-tail raw rows + level-2 summary substitutions for older ' +
+            'rows + budget-fit. Hippo-additive vs lossless-claw: eviction picks lowest-strength non-fresh-tail items first instead of oldest-first. ' +
+            'Tenant-scoped; default-deny on private scopes.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -82,7 +93,8 @@ export const TOOLS = [
                 },
                 scope: {
                     type: 'string',
-                    description: 'Restrict to memories whose scope matches exactly. When omitted, default-deny applies to ANY <source>:private:* scope and unknown:legacy rows. Pass an explicit scope to assemble a private session with consent.',
+                    description: 'Restrict to memories whose scope matches exactly. When omitted, default-deny applies to ANY <source>:private:* scope and ' +
+                        'unknown:legacy rows. Pass an explicit scope to assemble a private session with consent.',
                 },
             },
             required: ['session_id'],
@@ -90,7 +102,8 @@ export const TOOLS = [
     },
     {
         name: 'hippo_drill',
-        description: 'Walk one step down the DAG from a level-2+ topic summary to its direct children. Companion to hippo_recall: when recall returns an item with isSummary=true and substitutedFor=[ids], pass the summary id here to recover the original detail. Tenant-scoped; default-deny on private scopes.',
+        description: 'Walk one step down the DAG from a level-2+ topic summary to its direct children. Companion to hippo_recall: when recall returns an item with ' +
+            'isSummary=true and substitutedFor=[ids], pass the summary id here to recover the original detail. Tenant-scoped; default-deny on private scopes.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -114,7 +127,8 @@ export const TOOLS = [
                     type: 'integer',
                     minimum: 1,
                     maximum: 10,
-                    description: 'v0.30 / E5: walk N levels down (default 1 = direct children only). Higher values include children of children. Token budget remains GLOBAL across levels. Hard cap 10.',
+                    description: 'v0.30 / E5: walk N levels down (default 1 = direct children only). Higher values include children of children. Token budget remains ' +
+                        'GLOBAL across levels. Hard cap 10.',
                 },
             },
             required: ['summary_id'],
@@ -122,7 +136,8 @@ export const TOOLS = [
     },
     {
         name: 'hippo_remember',
-        description: 'Store a new memory. Use when you learn something non-obvious, hit an error, or discover a useful pattern. Memories decay over time unless retrieved. Errors get 2x half-life.',
+        description: 'Store a new memory. Use when you learn something non-obvious, hit an error, or discover a useful pattern. Memories decay over time unless retrieved. ' +
+            'Errors get 2x half-life.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -133,14 +148,16 @@ export const TOOLS = [
                 error: { type: 'boolean', description: 'Mark as error memory (doubles half-life)' },
                 pin: { type: 'boolean', description: 'Pin memory (never decays)' },
                 tag: { type: 'string', description: 'Optional tag for categorization' },
-                personal: { type: 'boolean', description: 'Store it as your own private memory: only you can recall it, in every project. Needs a key you minted or a sign-in.' },
+                personal: { type: 'boolean', description: 'Store it as your own private memory: only you can recall it, in every project. Needs a key you minted or ' +
+                        'a sign-in.' },
             },
             required: ['text'],
         },
     },
     {
         name: 'hippo_outcome',
-        description: "Report whether recalled memories were useful. Good outcomes slow a memory's decay and bad ones speed it up, in proportion to its record. Call after completing work.",
+        description: "Report whether recalled memories were useful. Good outcomes slow a memory's decay and bad ones speed it up, in proportion to its record. Call after " +
+            "completing work.",
         inputSchema: {
             type: 'object',
             properties: {
@@ -154,7 +171,9 @@ export const TOOLS = [
     },
     {
         name: 'hippo_context',
-        description: 'Smart context injection: auto-detects current task from git state and returns relevant memories plus the active task snapshot, session handoff and recent session trail (the same bundle as GET /v1/context). Use at the start of any session. Memories and those sections are scope-filtered: a no-scope caller does NOT see ANY <source>:private:* (slack, github, ...) or legacy-quarantine rows.',
+        description: 'Smart context injection: auto-detects current task from git state and returns relevant memories plus the active task snapshot, session handoff and ' +
+            'recent session trail (the same bundle as GET /v1/context). Use at the start of any session. Memories and those sections are scope-filtered: a ' +
+            'no-scope caller does NOT see ANY <source>:private:* (slack, github, ...) or legacy-quarantine rows.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -166,7 +185,8 @@ export const TOOLS = [
                 },
                 scope: {
                     type: 'string',
-                    description: 'Restrict memories, snapshot, handoff and trail to this scope exactly. When omitted, default-deny applies to ANY <source>:private:* (slack, github, ...) and unknown-legacy rows.',
+                    description: 'Restrict memories, snapshot, handoff and trail to this scope exactly. When omitted, default-deny applies to ANY <source>:private:* ' +
+                        '(slack, github, ...) and unknown-legacy rows.',
                 },
             },
         },
@@ -234,13 +254,16 @@ export const TOOLS = [
     },
     {
         name: 'hippo_predict_baserate',
-        description: 'J3 reference-class / planning-fallacy detector. Get base-rate stats for closed predictions in a class. Call this when you make a forward-looking claim (effort estimate, rollout risk, deadline) to anchor on the past track record rather than the inside view. Returns count + mean estimate + mean actual + mean ratio + median ratio + MAE + a human-readable summary. Tenant-scoped.',
+        description: 'J3 reference-class / planning-fallacy detector. Get base-rate stats for closed predictions in a class. Call this when you make a forward-looking ' +
+            'claim (effort estimate, rollout risk, deadline) to anchor on the past track record rather than the inside view. Returns count + mean estimate + ' +
+            'mean actual + mean ratio + median ratio + MAE + a human-readable summary. Tenant-scoped.',
         inputSchema: {
             type: 'object',
             properties: {
                 class_tag: {
                     type: 'string',
-                    description: 'Cohort label, e.g. "migration-effort", "rollout-risk", "deadline-week". Must match the class_tag used when the predictions were created via hippo_predict (or `hippo predict ...`).',
+                    description: 'Cohort label, e.g. "migration-effort", "rollout-risk", "deadline-week". Must match the class_tag used when the predictions were ' +
+                        'created via hippo_predict (or `hippo predict ...`).',
                 },
             },
             required: ['class_tag'],

package/dist/objects/customer-notes.d.ts

@@ -2,8 +2,8 @@
  *  The `customer_notes` table is the source of truth; the memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall. */
 import type { KeysetPosition } from '../util/keyset.js';
 import type { SavableDescriptor } from './descriptor.js';
-import type { CustomerNote, NoteStatus } from '../store/object-types.js';
-export type { CustomerNote, NoteStatus } from '../store/object-types.js';
+import type { CustomerNote, NoteStatus } from '../core/object-types.js';
+export type { CustomerNote, NoteStatus } from '../core/object-types.js';
 export declare const VALID_NOTE_STATES: ReadonlySet<NoteStatus>;
 /** Field caps (untrusted at the HTTP/SDK boundary). note is a body, so a larger cap
  *  than the 4096 short-field convention. */

package/dist/objects/decisions.d.ts

@@ -3,8 +3,8 @@
 import type { MemoryEntry } from '../core/memory.js';
 import type { KeysetPosition } from '../util/keyset.js';
 import type { SavableDescriptor } from './descriptor.js';
-import type { Decision, DecisionStatus } from '../store/object-types.js';
-export type { Decision, DecisionStatus } from '../store/object-types.js';
+import type { Decision, DecisionStatus } from '../core/object-types.js';
+export type { Decision, DecisionStatus } from '../core/object-types.js';
 export declare const VALID_DECISION_STATES: ReadonlySet<DecisionStatus>;
 export interface SaveDecisionOpts {
     decisionText: string;

package/dist/objects/descriptor.d.ts

@@ -1,5 +1,5 @@
 import type { KeysetPosition } from '../util/keyset.js';
-import type { ObjectByKind, ObjectFields, ObjectKind, SavableKind } from '../store/object-types.js';
+import type { ObjectByKind, ObjectFields, ObjectKind, SavableKind } from '../core/object-types.js';
 export interface ObjectDescriptor<K extends ObjectKind> {
     readonly kind: K;
     /** The nouns error text uses: "brief 3 not found", "only active briefs". */

package/dist/objects/incidents.d.ts

@@ -3,9 +3,9 @@
  *  linked_memory_ids must all exist in the SAME tenant or save throws before the insert. */
 import type { KeysetPosition } from '../util/keyset.js';
 import type { ObjectDescriptor } from './descriptor.js';
-import type { Incident, IncidentStatus } from '../store/object-types.js';
+import type { Incident, IncidentStatus } from '../core/object-types.js';
 import { type Objects } from '../store/port.js';
-export type { Incident, IncidentStatus } from '../store/object-types.js';
+export type { Incident, IncidentStatus } from '../core/object-types.js';
 export declare const VALID_INCIDENT_STATES: ReadonlySet<IncidentStatus>;
 export interface SaveIncidentOpts {
     incidentText: string;

package/dist/objects/lifecycle.d.ts

@@ -1,5 +1,5 @@
 import { type MemoryEntry } from '../core/memory.js';
-import type { ObjectByKind, ObjectKind, SavableKind } from '../store/object-types.js';
+import type { ObjectByKind, ObjectKind, SavableKind } from '../core/object-types.js';
 import { type Objects } from '../store/port.js';
 import type { ObjectDescriptor, ObjectListOpts, SavableDescriptor } from './descriptor.js';
 /** Newest first. */

package/dist/objects/lifecycle.js

@@ -1,6 +1,7 @@
 // Save, close, load-by-id and list for every typed object: the checks, the mirror memory and the error text, over the `objects` store group.
 // Each flow is written twice over the same steps: `...At` answers at once on hippo.db for the CLI, and the other awaits a served store's group for the routes.
 // The tenant, the fields and the list status are checked first, so a bad request fails before a store is asked.
+import { DEFAULT_LIST_LIMIT } from '../util/limits.js';
 import { BadRequestError, ConflictError, NotFoundError } from '../core/api-errors.js';
 import { loadConfig } from '../core/config.js';
 import { createMemory, Layer } from '../core/memory.js';
@@ -13,7 +14,7 @@ function listQuery(d, tenantId, opts) {
     if (opts.status && !d.states.has(opts.status)) {
         throw new BadRequestError(`${d.fn.list}: status must be one of ${Array.from(d.states).join('|')}; got ${opts.status}`);
     }
-    return { status: opts.status || undefined, filter: opts.filter || undefined, limit: opts.limit ?? 100, after: opts.after };
+    return { status: opts.status || undefined, filter: opts.filter || undefined, limit: opts.limit ?? DEFAULT_LIST_LIMIT, after: opts.after };
 }
 /** Newest first. */
 export function listObjectsAt(hippoRoot, d, tenantId, opts) {

package/dist/objects/policies.d.ts

@@ -3,9 +3,9 @@
  *  All dates are normalised to ISO-8601 (`toISOString`) at the store boundary so the lexical half-open comparison is sound. */
 import type { KeysetPosition } from '../util/keyset.js';
 import type { SavableDescriptor } from './descriptor.js';
-import type { Policy, PolicyStatus } from '../store/object-types.js';
+import type { Policy, PolicyStatus } from '../core/object-types.js';
 import type { Objects } from '../store/port.js';
-export type { Policy, PolicyStatus } from '../store/object-types.js';
+export type { Policy, PolicyStatus } from '../core/object-types.js';
 export declare const VALID_POLICY_STATES: ReadonlySet<PolicyStatus>;
 export interface SavePolicyOpts {
     policyName: string;

package/dist/objects/policies.js

@@ -1,6 +1,7 @@
 /** Policy object: a rule in force over a valid-time range [valid_from, valid_to), evolving via supersession; `loadPoliciesAsOf` queries it.
  *  Transaction-time travel (what we believed at past system time T) is deferred. Superseding keeps the predecessor's valid-time range.
  *  All dates are normalised to ISO-8601 (`toISOString`) at the store boundary so the lexical half-open comparison is sound. */
+import { DEFAULT_LIST_LIMIT } from '../util/limits.js';
 import { BadRequestError } from '../core/api-errors.js';
 import { assertTenantId } from '../store/tenant.js';
 import { closeObjectAt, listObjectsAt, objectByIdAt, saveObjectAt } from './lifecycle.js';
@@ -97,6 +98,6 @@ function inForceQuery(tenantId, asOfDate, opts) {
     const asOf = /^\d{4}-\d{2}-\d{2}$/.test(asOfDate.trim())
         ? normalizePolicyDate(`${asOfDate.trim()}T23:59:59.999Z`, 'asOfDate')
         : normalizePolicyDate(asOfDate, 'asOfDate');
-    return { asOf, name: opts.name, limit: opts.limit ?? 100 };
+    return { asOf, name: opts.name, limit: opts.limit ?? DEFAULT_LIST_LIMIT };
 }
 //# sourceMappingURL=policies.js.map

package/dist/objects/processes.d.ts

@@ -4,8 +4,8 @@
 import type { KeysetPosition } from '../util/keyset.js';
 import { type JsonValue } from '../util/json.js';
 import type { SavableDescriptor } from './descriptor.js';
-import type { Process, ProcessStatus } from '../store/object-types.js';
-export type { Process, ProcessStatus } from '../store/object-types.js';
+import type { Process, ProcessStatus } from '../core/object-types.js';
+export type { Process, ProcessStatus } from '../core/object-types.js';
 export declare const VALID_PROCESS_STATES: ReadonlySet<ProcessStatus>;
 /** DoS / abuse caps on the steps body (untrusted at the HTTP/SDK boundary). */
 export declare const MAX_PROCESS_STEPS = 200;

package/dist/objects/project-briefs.d.ts

@@ -4,9 +4,9 @@
 import type { KeysetPosition } from '../util/keyset.js';
 import type { SavableDescriptor } from './descriptor.js';
 import { type ObjectSaveSite } from './lifecycle.js';
-import type { BriefStatus, ProjectBrief } from '../store/object-types.js';
+import type { BriefStatus, ProjectBrief } from '../core/object-types.js';
 import type { Objects } from '../store/port.js';
-export type { BriefStatus, ProjectBrief } from '../store/object-types.js';
+export type { BriefStatus, ProjectBrief } from '../core/object-types.js';
 export declare const VALID_BRIEF_STATES: ReadonlySet<BriefStatus>;
 /** Field caps (untrusted at the HTTP/SDK boundary). summary is a body, so a larger
  *  cap than the 4096 short-field convention. */

package/dist/objects/project-briefs.js

@@ -1,6 +1,7 @@
 /** Project_brief object: the living, repo-scoped `summary` of a repository, evolving via supersession.
  *  `refreshBrief` assembles recent `path:<repo>` receipts with a deterministic (no-LLM) assembler; an LLM pipeline is deferred.
  *  The `project_briefs` table is the source of truth; the memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall. */
+import { truncateWithEllipsis } from '../util/ellipsize.js';
 import { BadRequestError } from '../core/api-errors.js';
 import { assertTenantId } from '../store/tenant.js';
 import { checkText, requireLine } from './fields.js';
@@ -87,9 +88,7 @@ function newestActive(repo) {
 function receiptHeadline(content) {
     const firstLine = (content ?? '').split(/\r?\n/).find((l) => l.trim().length > 0) ?? '';
     const trimmed = firstLine.trim();
-    return trimmed.length > MAX_RECEIPT_HEADLINE_LEN
-        ? `${trimmed.slice(0, MAX_RECEIPT_HEADLINE_LEN)}...`
-        : trimmed;
+    return truncateWithEllipsis(trimmed, MAX_RECEIPT_HEADLINE_LEN);
 }
 /** The tag a memory of the repo carries; the store matches it whole, so `path:hip` never matches `path:hippo`. */
 function receiptTag(normalizedRepo) {

package/dist/objects/skills.d.ts

@@ -3,9 +3,9 @@
  *  `trigger` is stored in `trigger_text` because it is a SQLite reserved keyword. */
 import type { KeysetPosition } from '../util/keyset.js';
 import type { SavableDescriptor } from './descriptor.js';
-import type { Skill, SkillStatus } from '../store/object-types.js';
+import type { Skill, SkillStatus } from '../core/object-types.js';
 import type { Objects } from '../store/port.js';
-export type { Skill, SkillStatus } from '../store/object-types.js';
+export type { Skill, SkillStatus } from '../core/object-types.js';
 export declare const VALID_SKILL_STATES: ReadonlySet<SkillStatus>;
 /** Field caps (untrusted at the HTTP/SDK boundary). instructions is a body, so a
  *  larger cap than the 4096 short-field convention. */

package/dist/postinstall.js

@@ -3,7 +3,7 @@ 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())

package/dist/rerankers/clef.js

@@ -3,7 +3,7 @@ import { buildRelevanceRequest, JEV_DEFAULT_TOP_K, rankByScores } from './jev.js
 import { createOutageWarning } from './outage-warning.js';
 import { rerankerPost, RERANKER_MAX_REPLY_BYTES } from './remote.js';
 import { readCappedJson } from '../util/capped-json.js';
-import { isJsonObject } from '../util/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'];
@@ -23,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;
 }
@@ -83,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';
@@ -105,7 +102,7 @@ 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,
     };

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,112 +1,59 @@
-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 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;
-    }
+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 };
 }
-let pipelineLoading = null;
-const outage = createOutageWarning('cross-encoder', 'falling back to identity ordering');
 // 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() {
-    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;
-    }
+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;
+    };
 }
-// 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) {
+    let succeeded = 0;
     const scored = await Promise.all(head.map(async (r, i) => {
         let ceScore;
         try {
             ceScore = await pipe(query, r.entry.content);
+            succeeded++;
         }
         catch (err) {
             // One bad inference must not sink the whole pass.
@@ -124,6 +71,32 @@ export const crossEncoderReranker = async (query, results, options) => {
     // relevance order, never an arbitrary content order.
     scored.sort((a, b) => compareScoresDesc(a.rerankScore, b.rerankScore));
     scored.forEach((r, i) => (r.postRerankRank = i + 1));
-    return scored;
-};
+    return { results: scored, succeeded };
+}
+/** 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);
+        }
+        const { results: scored, succeeded } = await scoreHead(pipe, query, head);
+        // A loaded model whose every call throws is as dead as one that never loaded.
+        if (head.length > 0 && succeeded === 0)
+            outage.failed('every inference failed');
+        else
+            outage.answered();
+        return scored;
+    };
+}
 //# sourceMappingURL=cross-encoder.js.map