hippo-memory 1.70.0 → 1.72.0

package/dist/store/usage-reports.js

@@ -1,26 +1,18 @@
 // The token-use and failure reports, each read on one handle of its own.
 // A file apart from token-ledger-rows.ts: src/store/token-ledger.ts imports that one, so a summary there would be an import cycle.
-import { closeHippoDb, openHippoDb } from '../db/index.js';
+import { onHandle } from './open.js';
 import { summarizeTokenUse } from './token-ledger.js';
 import { summarizeFailures } from './failure-log.js';
 /** One tenant's token ledger totals since `sinceIso`. */
 export function tokenUseSummary(hippoRoot, tenantId, sinceIso) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return summarizeTokenUse(db, tenantId, sinceIso);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 /** One tenant's failure log totals since `sinceIso`. */
 export function failureLogSummary(hippoRoot, tenantId, sinceIso) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return summarizeFailures(db, tenantId, sinceIso);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 //# sourceMappingURL=usage-reports.js.map

package/dist/store/vector-index.d.ts

@@ -0,0 +1,46 @@
+import { type DatabaseSyncLike } from '../db/index.js';
+import type { MemoryEntry } from '../core/memory.js';
+import type { PhysicsParticle } from '../core/physics.js';
+import type { VectorBackfillQuery, VectorWrite, VectorWriteResult } from './port.js';
+/** What a store's vector index was built by: the stored identity, and whether any vector exists. */
+export interface EmbeddingIndexState {
+    readonly storedModel: string | null;
+    readonly hasVectors: boolean;
+}
+/** The model the index was built by: the stored identity, else the default model when vectors exist. */
+export declare function indexedModel(state: EmbeddingIndexState): string | null;
+/** Whether a vector write under the index identity `model` first drops the stored index, which another model built. */
+export declare function replacesIndex(state: EmbeddingIndexState, model: string): boolean;
+/** hippo.db's index state, the meta row and the EXISTS on one handle. */
+export declare function storedIndexState(hippoRoot: string): EmbeddingIndexState;
+/** Records `identity` as what built the index under `hippoRoot`. */
+export declare function saveIndexIdentity(hippoRoot: string, identity: string): void;
+/** Every stored vector keyed by memory id; `{}` when none. Search reads only the rows it ranks via `loadStoredVectors`. */
+export declare function loadEmbeddingIndex(hippoRoot: string): Record<string, number[]>;
+export interface StoredVectorSummary {
+    readonly ids: Set<string>;
+    readonly dims: number | undefined;
+}
+/** Every stored vector id and the float count of the first row, with no vector decoded. */
+export declare function storedVectorSummary(hippoRoot: string): StoredVectorSummary;
+/** Stored vectors for `ids` only. */
+export declare function loadStoredVectors(hippoRoot: string, ids: readonly string[]): Map<string, number[]>;
+/** `loadStoredVectors` as Float32 views, for a caller that only scores them. */
+export declare function loadStoredVectorViews(hippoRoot: string, ids: readonly string[]): Map<string, Float32Array>;
+/** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
+export declare function saveEmbeddingIndex(hippoRoot: string, index: Record<string, number[]>, model?: string): void;
+/** Inserts or replaces `rows` under `model`, each row its own commit so a failure keeps the rows before it; returns how many it wrote. */
+export declare function saveStoredVectors(hippoRoot: string, rows: Iterable<readonly [string, readonly number[]]>, model: string): number;
+/** Drops the vectors of deleted memories under `hippoRoot`, then returns the ids that still have one. */
+export declare function pruneStoredVectors(hippoRoot: string): Set<string>;
+export declare function entriesWithoutVectorAt(db: DatabaseSyncLike, query: VectorBackfillQuery): MemoryEntry[];
+export declare function writeVectorsAt(db: DatabaseSyncLike, write: VectorWrite): VectorWriteResult;
+/** Every particle stored under `hippoRoot`. */
+export declare function loadStoredParticles(hippoRoot: string): PhysicsParticle[];
+/** Writes `particles` over their stored state under `hippoRoot`, as one batch. */
+export declare function saveStoredParticles(hippoRoot: string, particles: PhysicsParticle[]): void;
+/** Replaces every particle under `hippoRoot` with a fresh one per memory in `ids` that has an embedding; returns how many. Rows are read a page at a time. */
+export declare function resetStoredParticles(hippoRoot: string, ids: readonly string[], embeddingIndex: Record<string, number[]>): number;
+/** Stores a first particle for `entry`, placed at `vector`; a memory that has one keeps it. */
+export declare function seedStoredParticle(hippoRoot: string, entry: MemoryEntry, vector: number[]): void;
+//# sourceMappingURL=vector-index.d.ts.map

package/dist/store/vector-index.js

@@ -0,0 +1,171 @@
+// Owns hippo.db's stored vectors, the identity of the model that built them, and the particle rows: every read and write of the three.
+import { getMeta, setMeta, withWriteScope } from '../db/index.js';
+import { onHandle } from './open.js';
+import { DEFAULT_EMBEDDING_MODEL } from '../embeddings/local.js';
+import { float32ToBuffer, initializeParticle, loadPhysicsState, resetAllPhysicsState, savePhysicsState } from '../db/physics-state.js';
+import { EMBEDDING_MODEL_META_KEY, deleteOrphanVectors, hasStoredVectors, loadVectors, loadVectorViews, replaceAllVectors, storedVectorDims, storedVectorIds, upsertVectors, } from '../db/vector-store.js';
+import { selectEntriesByIds } from './entry-reads.js';
+import { chunked } from '../util/chunked.js';
+import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
+const MAX_BACKFILL_PAGE = 500;
+/** The model the index was built by: the stored identity, else the default model when vectors exist. */
+export function indexedModel(state) {
+    return state.storedModel ?? (state.hasVectors ? DEFAULT_EMBEDDING_MODEL : null);
+}
+/** Whether a vector write under the index identity `model` first drops the stored index, which another model built. */
+export function replacesIndex(state, model) {
+    const indexed = indexedModel(state);
+    return indexed !== null && indexed !== model;
+}
+function embeddingIndexStateOn(db) {
+    return {
+        storedModel: getMeta(db, EMBEDDING_MODEL_META_KEY, '').trim() || null,
+        hasVectors: hasStoredVectors(db),
+    };
+}
+/** hippo.db's index state, the meta row and the EXISTS on one handle. */
+export function storedIndexState(hippoRoot) {
+    return onHandle(hippoRoot, (db) => {
+        return embeddingIndexStateOn(db);
+    });
+}
+/** Records `identity` as what built the index under `hippoRoot`. */
+export function saveIndexIdentity(hippoRoot, identity) {
+    onHandle(hippoRoot, (db) => {
+        setMeta(db, EMBEDDING_MODEL_META_KEY, identity);
+    });
+}
+/** Every stored vector keyed by memory id; `{}` when none. Search reads only the rows it ranks via `loadStoredVectors`. */
+export function loadEmbeddingIndex(hippoRoot) {
+    return onHandle(hippoRoot, (db) => {
+        return Object.fromEntries(loadVectors(db));
+    });
+}
+/** Every stored vector id and the float count of the first row, with no vector decoded. */
+export function storedVectorSummary(hippoRoot) {
+    return onHandle(hippoRoot, (db) => {
+        return { ids: storedVectorIds(db), dims: storedVectorDims(db) };
+    });
+}
+/** Stored vectors for `ids` only. */
+export function loadStoredVectors(hippoRoot, ids) {
+    if (ids.length === 0)
+        return new Map();
+    return onHandle(hippoRoot, (db) => {
+        return loadVectors(db, ids);
+    });
+}
+/** `loadStoredVectors` as Float32 views, for a caller that only scores them. */
+export function loadStoredVectorViews(hippoRoot, ids) {
+    if (ids.length === 0)
+        return new Map();
+    return onHandle(hippoRoot, (db) => {
+        return loadVectorViews(db, ids);
+    });
+}
+/** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
+export function saveEmbeddingIndex(hippoRoot, index, model) {
+    onHandle(hippoRoot, (db) => {
+        replaceAllVectors(db, index, model ?? getMeta(db, EMBEDDING_MODEL_META_KEY, ''));
+    });
+}
+/** Inserts or replaces `rows` under `model`, each row its own commit so a failure keeps the rows before it; returns how many it wrote. */
+export function saveStoredVectors(hippoRoot, rows, model) {
+    return onHandle(hippoRoot, (db) => {
+        return upsertVectors(db, rows, model);
+    });
+}
+/** Drops the vectors of deleted memories under `hippoRoot`, then returns the ids that still have one. */
+export function pruneStoredVectors(hippoRoot) {
+    return onHandle(hippoRoot, (db) => {
+        deleteOrphanVectors(db);
+        return storedVectorIds(db);
+    });
+}
+export function entriesWithoutVectorAt(db, query) {
+    if (!Number.isInteger(query.limit))
+        throw new RangeError('limit must be an integer');
+    const limit = Math.max(1, Math.min(query.limit, MAX_BACKFILL_PAGE));
+    const tenantClause = query.tenantId === undefined ? '' : ' AND tenant_id = ?';
+    const tenantArgs = query.tenantId === undefined ? [] : [query.tenantId];
+    // SAFETY: selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+    const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id > ?${tenantClause}
+       AND NOT EXISTS (SELECT 1 FROM memory_vectors v WHERE v.memory_id = memories.id AND v.model = ?)
+     ORDER BY id LIMIT ?`).all(query.afterId ?? '', ...tenantArgs, query.model, limit);
+    return rows.map(rowToEntry);
+}
+function ownedIds(db, ids, tenantId) {
+    const owned = new Set();
+    for (const chunk of chunked([...new Set(ids)])) {
+        // SAFETY: the SELECT names one column, id.
+        const rows = db.prepare(`SELECT id FROM memories WHERE +tenant_id = ? AND id IN (${chunk.map(() => '?').join(', ')})`).all(tenantId, ...chunk);
+        for (const row of rows)
+            owned.add(row.id);
+    }
+    return owned;
+}
+// savePhysicsState opens its own transaction and overwrites, so the first particle for a memory is inserted here instead.
+function insertNewParticles(db, rows) {
+    const stmt = db.prepare(`
+    INSERT INTO memory_physics (memory_id, position_blob, velocity_blob, mass, charge, temperature, last_simulation)
+    VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(memory_id) DO NOTHING
+  `);
+    for (const { memoryId, particle: p } of rows) {
+        if (p)
+            stmt.run(memoryId, float32ToBuffer(p.position), float32ToBuffer(p.velocity), p.mass, p.charge, p.temperature, p.lastSimulation);
+    }
+}
+export function writeVectorsAt(db, write) {
+    return withWriteScope(db, 'write_vectors', () => {
+        const replaces = replacesIndex(embeddingIndexStateOn(db), write.model);
+        if (replaces && !write.replaceIndex)
+            return { written: 0, modelMismatch: true };
+        const owned = ownedIds(db, write.rows.map((r) => r.memoryId), write.tenantId);
+        const rows = write.rows.filter((r) => owned.has(r.memoryId) && r.vector.length > 0 && r.vector.every(Number.isFinite));
+        if (rows.length === 0)
+            return { written: 0, modelMismatch: false };
+        if (replaces)
+            db.exec('DELETE FROM memory_vectors; DELETE FROM memory_physics;');
+        const written = upsertVectors(db, rows.map((r) => [r.memoryId, r.vector]), write.model);
+        insertNewParticles(db, rows);
+        setMeta(db, EMBEDDING_MODEL_META_KEY, write.model);
+        return { written, modelMismatch: false };
+    });
+}
+/** Every particle stored under `hippoRoot`. */
+export function loadStoredParticles(hippoRoot) {
+    return onHandle(hippoRoot, (db) => {
+        return Array.from(loadPhysicsState(db).values());
+    });
+}
+/** Writes `particles` over their stored state under `hippoRoot`, as one batch. */
+export function saveStoredParticles(hippoRoot, particles) {
+    onHandle(hippoRoot, (db) => {
+        savePhysicsState(db, particles);
+    });
+}
+const PARTICLE_PAGE = 64;
+function* entriesInPages(db, ids) {
+    for (const page of chunked(ids, PARTICLE_PAGE)) {
+        const rows = selectEntriesByIds(db, page);
+        for (const id of page) {
+            const entry = rows.get(id);
+            if (entry)
+                yield entry;
+        }
+    }
+}
+/** Replaces every particle under `hippoRoot` with a fresh one per memory in `ids` that has an embedding; returns how many. Rows are read a page at a time. */
+export function resetStoredParticles(hippoRoot, ids, embeddingIndex) {
+    return onHandle(hippoRoot, (db) => {
+        return resetAllPhysicsState(db, entriesInPages(db, ids), embeddingIndex);
+    });
+}
+/** Stores a first particle for `entry`, placed at `vector`; a memory that has one keeps it. */
+export function seedStoredParticle(hippoRoot, entry, vector) {
+    onHandle(hippoRoot, (db) => {
+        if (!loadPhysicsState(db, [entry.id]).has(entry.id))
+            savePhysicsState(db, [initializeParticle(entry, vector)]);
+    });
+}
+//# sourceMappingURL=vector-index.js.map

package/dist/store/working-memory.d.ts

@@ -1,10 +1,4 @@
-/**
- * Working Memory — bounded buffer for current-state notes.
- *
- * Separate from long-term semantic memory. Entries are scoped,
- * importance-ranked, and automatically evicted when the buffer
- * exceeds WM_MAX_ENTRIES per scope.
- */
+/** Working Memory: bounded buffer for current-state notes, separate from long-term memory; scoped, importance-ranked, evicted past WM_MAX_ENTRIES per scope. */
 import type { JsonValue } from '../util/json.js';
 export declare const WM_MAX_ENTRIES = 20;
 export type JsonObject = {
@@ -21,12 +15,8 @@ export interface WorkingMemoryItem {
     createdAt: string;
     updatedAt: string;
 }
-/**
- * Push a new entry into working memory.
- * If the scope exceeds WM_MAX_ENTRIES, the lowest-importance entry
- * is evicted (ties broken by oldest created_at).
- * Returns the new row ID.
- */
+/** Push a new entry into working memory; past WM_MAX_ENTRIES the scope's lowest-importance entry is evicted (ties: oldest created_at). Returns the new
+ * row ID. */
 export declare function wmPush(hippoRoot: string, opts: {
     scope: string;
     content: string;
@@ -36,29 +26,20 @@ export declare function wmPush(hippoRoot: string, opts: {
     metadata?: JsonObject;
     tenantId?: string;
 }): number;
-/**
- * Read working memory entries, sorted by importance DESC.
- */
+/** Read working memory entries, sorted by importance DESC. */
 export declare function wmRead(hippoRoot: string, opts?: {
     scope?: string;
     sessionId?: string;
     limit?: number;
     tenantId?: string;
 }): WorkingMemoryItem[];
-/**
- * Clear (delete) working memory entries. Returns the count deleted.
- */
+/** Clear (delete) working memory entries. Returns the count deleted. */
 export declare function wmClear(hippoRoot: string, opts?: {
     scope?: string;
     sessionId?: string;
     tenantId?: string;
 }): number;
-/**
- * Flush working memory — delete entries after session end.
- * Functionally identical to wmClear but semantically distinct:
- * used at session boundaries to discard ephemeral state.
- * Returns the count flushed.
- */
+/** Flush working memory after session end: same as wmClear, but marks the session-boundary discard of ephemeral state. Returns the count flushed. */
 export declare function wmFlush(hippoRoot: string, opts?: {
     scope?: string;
     sessionId?: string;

package/dist/store/working-memory.js

@@ -1,21 +1,14 @@
-/**
- * Working Memory — bounded buffer for current-state notes.
- *
- * Separate from long-term semantic memory. Entries are scoped,
- * importance-ranked, and automatically evicted when the buffer
- * exceeds WM_MAX_ENTRIES per scope.
- */
-import { closeHippoDb, withWriteScope } from '../db/index.js';
-import { openStore } from './open.js';
+/** Working Memory: bounded buffer for current-state notes, separate from long-term memory; scoped, importance-ranked, evicted past WM_MAX_ENTRIES per scope. */
+import { withWriteScope } from '../db/index.js';
+import { onHandle, openStore } from './open.js';
 import { warnDamagedColumn } from '../util/stored-json.js';
 import { resolveTenantId } from './tenant.js';
 export const WM_MAX_ENTRIES = 20;
 function rowToItem(row) {
     let metadata = {};
     try {
-        // SAFETY: metadata_json is always written by wmPush via
-        // JSON.stringify(opts.metadata ?? {}), so a successful parse yields a
-        // plain JSON object; malformed content falls through to the catch below.
+        // SAFETY: metadata_json is always written by wmPush via JSON.stringify(opts.metadata ?? {}), so a successful parse yields a plain JSON object;
+        // malformed content falls through to the catch below.
         metadata = JSON.parse(row.metadata_json);
     }
     catch {
@@ -34,15 +27,10 @@ function rowToItem(row) {
         updatedAt: row.updated_at,
     };
 }
-/**
- * Push a new entry into working memory.
- * If the scope exceeds WM_MAX_ENTRIES, the lowest-importance entry
- * is evicted (ties broken by oldest created_at).
- * Returns the new row ID.
- */
+/** Push a new entry into working memory; past WM_MAX_ENTRIES the scope's lowest-importance entry is evicted (ties: oldest created_at). Returns the new
+ * row ID. */
 export function wmPush(hippoRoot, opts) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const now = new Date().toISOString();
         const importance = opts.importance ?? 0;
         const tenantId = opts.tenantId ?? resolveTenantId({});
@@ -55,16 +43,11 @@ export function wmPush(hippoRoot, opts) {
             evictOverCapacity(db, opts.scope, tenantId);
             return id;
         });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 function evictOverCapacity(db, scope, tenantId) {
-    // Evict if over capacity for this scope
-    // SAFETY: `COUNT(*) AS cnt` on a scoped query always returns exactly
-    // one row shaped { cnt }; .get() returns undefined only if the driver
-    // yields no row, which COUNT(*) never does.
+    // Evict if over capacity for this scope.
+    // SAFETY: `COUNT(*) AS cnt` always returns exactly one row { cnt }, so `.get()` never yields undefined.
     const countRow = db.prepare(`
     SELECT COUNT(*) AS cnt FROM working_memory WHERE scope = ? AND tenant_id = ?
   `).get(scope, tenantId);
@@ -82,12 +65,9 @@ function evictOverCapacity(db, scope, tenantId) {
     `).run(scope, tenantId, excess);
     }
 }
-/**
- * Read working memory entries, sorted by importance DESC.
- */
+/** Read working memory entries, sorted by importance DESC. */
 export function wmRead(hippoRoot, opts) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const clauses = ['tenant_id = ?'];
         const params = [opts?.tenantId ?? resolveTenantId({})];
         if (opts?.scope) {
@@ -111,17 +91,11 @@ export function wmRead(hippoRoot, opts) {
       LIMIT ?
     `).all(...params);
         return rows.map(rowToItem);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Clear (delete) working memory entries. Returns the count deleted.
- */
+/** Clear (delete) working memory entries. Returns the count deleted. */
 export function wmClear(hippoRoot, opts) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const clauses = ['tenant_id = ?'];
         const params = [opts?.tenantId ?? resolveTenantId({})];
         if (opts?.scope) {
@@ -135,17 +109,9 @@ export function wmClear(hippoRoot, opts) {
         const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
         const result = db.prepare(`DELETE FROM working_memory ${where}`).run(...params);
         return Number(result.changes ?? 0);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Flush working memory — delete entries after session end.
- * Functionally identical to wmClear but semantically distinct:
- * used at session boundaries to discard ephemeral state.
- * Returns the count flushed.
- */
+/** Flush working memory after session end: same as wmClear, but marks the session-boundary discard of ephemeral state. Returns the count flushed. */
 export function wmFlush(hippoRoot, opts) {
     return wmClear(hippoRoot, opts);
 }

package/dist/support-bundle.js

@@ -1,13 +1,13 @@
-/** `hippo support-bundle`: one redacted JSON snapshot for a support ticket. Read-only (SQLite may leave empty -wal and -shm files); never touches memory content. */
+/** `hippo support-bundle`: one redacted JSON snapshot for a support ticket. Read-only
+ * (SQLite may leave empty -wal and -shm files); never touches memory content. */
 import { envByName, processEnv } from './util/env.js';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { pathToFileURL } from 'url';
-import { findHippoStoreDir, isGlobalStoreRoot } from './core/project-identity.js';
+import { findHippoStoreDir, isGlobalStoreRoot, isInitialized } from './core/project-identity.js';
 import { realpathOrResolve } from './util/real-path.js';
-import { getGlobalRoot } from './sharing/shared.js';
-import { isInitialized } from './store/open.js';
+import { getGlobalRoot } from './sharing/global-store.js';
 import { readStoreInventory } from './store/diagnostics.js';
 import { runDoctor } from './doctor.js';
 import { loadConfig } from './core/config.js';
@@ -20,7 +20,7 @@ export const TAIL_MAX_LINES = 200;
 const TAIL_MAX_LINE_CHARS = 2000;
 // Greedy on purpose: complete key blocks are redacted first, so any END left is an orphan and what precedes it may be key body.
 const ORPHAN_KEY_END_RE = /^[\s\S]*-----END [A-Z ]*PRIVATE KEY-----/;
-// The other env vars hippo reads outside the HIPPO_ prefix (src/store/embeddings/provider.ts, connectors/*).
+// The other env vars hippo reads outside the HIPPO_ prefix (src/embeddings/provider.ts, connectors/*).
 const OTHER_ENV_NAMES = [
     'ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'VOYAGE_API_KEY', 'COHERE_API_KEY', 'TYPESAFE_API_KEY',
     'GITHUB_TOKEN', 'GITHUB_WEBHOOK_SECRET', 'GITHUB_WEBHOOK_SECRET_PREVIOUS',
@@ -117,12 +117,13 @@ function listLogFileNames(dir) {
         .sort();
 }
 function tailLogFile(file) {
-    const size = fs.statSync(file).size;
-    const readSize = Math.min(size, TAIL_MAX_BYTES);
-    const startedMidFile = size > TAIL_MAX_BYTES;
     const fd = fs.openSync(file, 'r');
     let text;
+    let startedMidFile;
     try {
+        const size = fs.fstatSync(fd).size;
+        const readSize = Math.min(size, TAIL_MAX_BYTES);
+        startedMidFile = size > TAIL_MAX_BYTES;
         const buf = Buffer.alloc(readSize);
         fs.readSync(fd, buf, 0, readSize, size - readSize);
         text = buf.toString('utf8');

package/dist/trust/reject-flow.js

@@ -1,8 +1,8 @@
 // The reject, unreject and list flow the CLI verbs and the api functions share: the rules and their wording live here,
 // and src/store/rejected-values.ts runs each one on a single handle.
 import { BadRequestError } from '../core/api-errors.js';
-import { isPersonalScope } from '../store/recall-scope.js';
-import { mergedSuccessor } from '../consolidate/merged-row.js';
+import { isPersonalScope } from '../core/recall-scope.js';
+import { mergedSuccessor } from '../core/merged-row.js';
 import { normalizeValueForRejection } from '../store/rejection.js';
 import { applyRejection, liftRejection, loadRejectedValues, } from '../store/rejected-values.js';
 function assertRejectOpts(opts) {
@@ -18,9 +18,7 @@ function assertRejectOpts(opts) {
         throw new Error('reject accepts either a memory id or --value, not both.');
     }
     if (opts.value !== undefined && normalizeValueForRejection(opts.value).length === 0) {
-        // Direct api callers can pass strings the CLI flag parser would have
-        // refused; an empty-normalized tombstone would refuse nothing meaningful
-        // and pollute the listing.
+        // Direct api callers can pass strings the CLI flag parser would refuse; an empty-normalized tombstone would refuse nothing and pollute the listing.
         throw new Error('reject --value requires non-empty content.');
     }
 }

package/dist/util/agent-homes.d.ts

@@ -0,0 +1,15 @@
+type Env = Readonly<Record<string, string | undefined>>;
+export declare function homeDir(): string;
+/** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
+export declare function codexHomeDir(home?: string, env?: Env): string;
+/** Claude Code's config folder, where it reads settings.json: $CLAUDE_CONFIG_DIR when set and non-empty, else
+ * ~/.claude under os.homedir(), as Claude Code does (a HOME that differs from the profile must not move it). */
+export declare function claudeConfigDir(home?: string, env?: Env): string;
+/** VS Code's user-data resolution: portable install first, then the app-data override, then the platform default. */
+export declare function vscodeDataFolders(ctx: {
+    readonly env: Env;
+    readonly home: string;
+    readonly platform: NodeJS.Platform;
+}): string[];
+export {};
+//# sourceMappingURL=agent-homes.d.ts.map

package/dist/util/agent-homes.js

@@ -0,0 +1,34 @@
+// Where the agent tools keep their config and data, shared by the hook installers and the agent-memory readers.
+import * as os from 'os';
+import * as path from 'path';
+import { envHomeDir, processEnv } from './env.js';
+const VSCODE_PRODUCTS = ['Code', 'Code - Insiders'];
+export function homeDir() {
+    return envHomeDir() || os.homedir();
+}
+/** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
+export function codexHomeDir(home = homeDir(), env = processEnv()) {
+    return env.CODEX_HOME || path.join(home, '.codex');
+}
+/** Claude Code's config folder, where it reads settings.json: $CLAUDE_CONFIG_DIR when set and non-empty, else
+ * ~/.claude under os.homedir(), as Claude Code does (a HOME that differs from the profile must not move it). */
+export function claudeConfigDir(home = os.homedir(), env = processEnv()) {
+    return env.CLAUDE_CONFIG_DIR || path.join(home, '.claude');
+}
+/** VS Code's user-data resolution: portable install first, then the app-data override, then the platform default. */
+export function vscodeDataFolders(ctx) {
+    const { env, home, platform } = ctx;
+    if (env.VSCODE_PORTABLE)
+        return [path.join(env.VSCODE_PORTABLE, 'user-data')];
+    let appData;
+    if (env.VSCODE_APPDATA)
+        appData = env.VSCODE_APPDATA;
+    else if (platform === 'win32')
+        appData = env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    else if (platform === 'darwin')
+        appData = path.join(home, 'Library', 'Application Support');
+    else
+        appData = env.XDG_CONFIG_HOME || path.join(home, '.config');
+    return VSCODE_PRODUCTS.map((product) => path.join(appData, product));
+}
+//# sourceMappingURL=agent-homes.js.map

package/dist/util/anthropic-messages.d.ts

@@ -13,6 +13,7 @@ export type AnthropicMessageFailure = {
 } | {
     kind: 'http';
     status: number;
+    detail: string;
 } | {
     kind: 'unreadable';
     message: string;
@@ -24,6 +25,8 @@ export type AnthropicMessageResult = {
     ok: false;
     failure: AnthropicMessageFailure;
 };
+/** True for a failure the next call would repeat, so a caller looping over items should stop rather than retry. */
+export declare function isPermanentFailure(failure: AnthropicMessageFailure): boolean;
 /** The reply's first text block, trimmed (empty when the reply has none); never throws. */
 export declare function sendAnthropicMessage(req: AnthropicMessageRequest): Promise<AnthropicMessageResult>;
 /** The text extraction and DAG summaries hand to their `onError` callback. */

package/dist/util/anthropic-messages.js

@@ -1,9 +1,36 @@
 /** The one Anthropic Messages client: sends one user prompt and returns the reply text or a typed failure the caller reacts to. */
-import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
+import { fetchWithRetry, llmTimeoutMs, llmTotalMs } from './http-retry.js';
 import { errorMessage } from './log.js';
+import { readCappedJson, readCappedText } from './capped-json.js';
+import { isJsonObject, isJsonString } from './json.js';
+import { redactSecretsStrict } from './secret-detect.js';
 const MESSAGES_URL = 'https://api.anthropic.com/v1/messages';
 const API_VERSION = '2023-06-01';
 const DEFAULT_MODEL = 'claude-sonnet-4-6';
+// Callers ask for at most 1,200 tokens, a reply of a few KB; 1 MiB leaves room for a verbose envelope.
+const MAX_REPLY_BYTES = 1024 * 1024;
+// The error body names the cause (bad key, no credit, unknown model) in its first line or two.
+const ERROR_SNIPPET_CHARS = 256;
+const UTF8_MAX_BYTES_PER_CHAR = 4;
+// A bad or missing key, no credit, no permission, an unknown model: every later call gets the same answer.
+const PERMANENT_STATUSES = new Set([401, 402, 403, 404]);
+/** The first content block's text, trimmed; empty when the reply has no such block. */
+function firstText(reply) {
+    const first = Array.isArray(reply.content) ? reply.content[0] : undefined;
+    const text = isJsonObject(first) ? first.text : undefined;
+    return isJsonString(text) ? text.trim() : '';
+}
+/** True for a failure the next call would repeat, so a caller looping over items should stop rather than retry. */
+export function isPermanentFailure(failure) {
+    return failure.kind === 'http' && PERMANENT_STATUSES.has(failure.status);
+}
+/** The start of a failed reply's body, on one line with any key-shaped text masked; empty when the body cannot be read. */
+async function errorSnippet(res) {
+    // The status is the failure reported; a body that cannot be read only costs its snippet.
+    const body = await readCappedText(res, ERROR_SNIPPET_CHARS * UTF8_MAX_BYTES_PER_CHAR).catch(() => '');
+    // Masked before the cut, so a key that straddles the cut is never left half shown.
+    return redactSecretsStrict(body.replace(/\s+/g, ' ').trim()).slice(0, ERROR_SNIPPET_CHARS);
+}
 /** The reply's first text block, trimmed (empty when the reply has none); never throws. */
 export async function sendAnthropicMessage(req) {
     let res;
@@ -20,16 +47,18 @@ export async function sendAnthropicMessage(req) {
                 max_tokens: req.maxTokens,
                 messages: [{ role: 'user', content: req.prompt }],
             }),
-        }, { timeoutMs: llmTimeoutMs(), fetchFn: req.fetcher ?? fetch });
+        }, { timeoutMs: llmTimeoutMs(), totalMs: llmTotalMs(), fetchFn: req.fetcher ?? fetch });
     }
     catch (err) {
         return { ok: false, failure: { kind: 'request', message: errorMessage(err) } };
     }
     if (!res.ok)
-        return { ok: false, failure: { kind: 'http', status: res.status } };
+        return { ok: false, failure: { kind: 'http', status: res.status, detail: await errorSnippet(res) } };
     try {
-        const data = await res.json();
-        return { ok: true, text: data.content?.[0]?.text?.trim() ?? '' };
+        const data = await readCappedJson(res, MAX_REPLY_BYTES);
+        if (!isJsonObject(data))
+            return { ok: false, failure: { kind: 'unreadable', message: 'the reply is not a JSON object' } };
+        return { ok: true, text: firstText(data) };
     }
     catch (err) {
         return { ok: false, failure: { kind: 'unreadable', message: errorMessage(err) } };
@@ -39,7 +68,7 @@ export async function sendAnthropicMessage(req) {
 export function describeMessageFailure(failure) {
     switch (failure.kind) {
         case 'request': return `request failed: ${failure.message}`;
-        case 'http': return `HTTP ${failure.status}`;
+        case 'http': return failure.detail ? `HTTP ${failure.status}: ${failure.detail}` : `HTTP ${failure.status}`;
         case 'unreadable': return `unparseable response: ${failure.message}`;
     }
 }

package/dist/util/atomic-write.d.ts

@@ -1,3 +1,4 @@
-/** Writes `text` to `file` so a reader sees the old content or the new, never a truncated file: a crash mid-write leaves the old one. */
+/** Replaces `file` through a flushed temp file and a rename, so a reader, or a crash at any point, finds the old content or the new, whole.
+ *  A file with other hard links, or a rename the platform refuses (logged), is written in place: a crash mid-write can leave it truncated. */
 export declare function writeFileAtomic(file: string, text: string): void;
 //# sourceMappingURL=atomic-write.d.ts.map