hippo-memory 1.72.0 → 2.1.0

package/dist/store/tombstone-checks.js

@@ -1,7 +1,8 @@
 // Sleep's tombstone checks run on one handle for the whole pass, owned here so no stage holds a raw one.
 import { closeHippoDb, openHippoDb } from '../db/index.js';
-import { appendAuditEvent } from './audit.js';
+import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 import { findRejectedValue } from './rejection.js';
+import { errorMessage } from '../util/log.js';
 // Lazy so a sleep that checks nothing never opens the store; make it IMMEDIATELY before the try whose
 // finally closes it, so a throw in any phase cannot leak the handle.
 export function lazyTombstoneChecks(hippoRoot, dryRun) {
@@ -22,6 +23,14 @@ export function lazyTombstoneChecks(hippoRoot, dryRun) {
             if (db)
                 appendAuditEvent(db, event);
         },
+        auditOrCount(event) {
+            try {
+                this.audit(event);
+            }
+            catch (error) {
+                reportAuditWriteFailure(event.op, errorMessage(error), event.targetId);
+            }
+        },
         close() {
             if (handle)
                 closeHippoDb(handle);

package/dist/store/usage-reports.js

@@ -1,5 +1,6 @@
 // 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.
+// 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 { onHandle } from './open.js';
 import { summarizeTokenUse } from './token-ledger.js';
 import { summarizeFailures } from './failure-log.js';

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

@@ -15,7 +15,8 @@ export declare function replacesIndex(state: EmbeddingIndexState, model: string)
 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`. */
+/** 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>;
@@ -29,17 +30,19 @@ export declare function loadStoredVectors(hippoRoot: string, ids: readonly strin
 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. */
+/** 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>;
+/** Drops the vectors of deleted memories under `hippoRoot`, then returns the ids with no vector, oldest first. */
+export declare function pruneStoredVectorsListPending(hippoRoot: string): 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. */
+/** 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;

package/dist/store/vector-index.js

@@ -1,12 +1,16 @@
-// 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.
+// 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 { loadPhysicsState, resetAllPhysicsState, savePhysicsState } from '../db/physics-state.js';
+import { initializeParticle } from '../core/physics.js';
+import { float32ToBuffer } from '../util/vector-codec.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';
+import { placeholders } from '../util/sql.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) {
@@ -35,7 +39,8 @@ export function saveIndexIdentity(hippoRoot, identity) {
         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`. */
+/** 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));
@@ -69,17 +74,24 @@ export function saveEmbeddingIndex(hippoRoot, index, model) {
         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. */
+/** 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) {
+/** Drops the vectors of deleted memories under `hippoRoot`, then returns the ids with no vector, oldest first. */
+export function pruneStoredVectorsListPending(hippoRoot) {
     return onHandle(hippoRoot, (db) => {
         deleteOrphanVectors(db);
-        return storedVectorIds(db);
+        // SAFETY: the SELECT names exactly the one column read.
+        const rows = db
+            .prepare(`SELECT id FROM memories
+         WHERE NOT EXISTS (SELECT 1 FROM memory_vectors v WHERE v.memory_id = memories.id)
+         ORDER BY created ASC, id ASC`)
+            .all();
+        return rows.map((r) => r.id);
     });
 }
 export function entriesWithoutVectorAt(db, query) {
@@ -98,21 +110,25 @@ 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);
+        const rows = db
+            .prepare(`SELECT id FROM memories WHERE +tenant_id = ? AND id IN (${placeholders(chunk.length)})`)
+            .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.
+// 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)
+        if (p) {
             stmt.run(memoryId, float32ToBuffer(p.position), float32ToBuffer(p.velocity), p.mass, p.charge, p.temperature, p.lastSimulation);
+        }
     }
 }
 export function writeVectorsAt(db, write) {
@@ -155,7 +171,8 @@ function* entriesInPages(db, ids) {
         }
     }
 }
-/** 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. */
+/** 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);

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

@@ -1,4 +1,5 @@
-/** Working Memory: bounded buffer for current-state notes, separate from long-term memory; scoped, importance-ranked, evicted past 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 = {
@@ -15,8 +16,8 @@ export interface WorkingMemoryItem {
     createdAt: string;
     updatedAt: string;
 }
-/** 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. */
+/** 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;
@@ -39,7 +40,8 @@ export declare function wmClear(hippoRoot: string, opts?: {
     sessionId?: string;
     tenantId?: string;
 }): number;
-/** Flush working memory after session end: same as wmClear, but marks the session-boundary discard of 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,4 +1,5 @@
-/** Working Memory: bounded buffer for current-state notes, separate from long-term memory; scoped, importance-ranked, evicted past 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 { withWriteScope } from '../db/index.js';
 import { onHandle, openStore } from './open.js';
 import { warnDamagedColumn } from '../util/stored-json.js';
@@ -7,8 +8,8 @@ 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 {
@@ -27,18 +28,21 @@ function rowToItem(row) {
         updatedAt: row.updated_at,
     };
 }
-/** 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. */
+/** 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) {
     return onHandle(hippoRoot, (db) => {
         const now = new Date().toISOString();
         const importance = opts.importance ?? 0;
         const tenantId = opts.tenantId ?? resolveTenantId({});
         return withWriteScope(db, 'wm_push', () => {
-            const result = db.prepare(`
-        INSERT INTO working_memory(scope, session_id, task_id, importance, content, metadata_json, created_at, updated_at, tenant_id)
+            const result = db
+                .prepare(`
+        INSERT INTO working_memory(scope, session_id, task_id, importance, content, metadata_json, created_at,
+        updated_at, tenant_id)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(opts.scope, opts.sessionId ?? null, opts.taskId ?? null, importance, opts.content, JSON.stringify(opts.metadata ?? {}), now, now, tenantId);
+      `)
+                .run(opts.scope, opts.sessionId ?? null, opts.taskId ?? null, importance, opts.content, JSON.stringify(opts.metadata ?? {}), now, now, tenantId);
             const id = Number(result.lastInsertRowid ?? 0);
             evictOverCapacity(db, opts.scope, tenantId);
             return id;
@@ -111,7 +115,8 @@ export function wmClear(hippoRoot, opts) {
         return Number(result.changes ?? 0);
     }, openStore);
 }
-/** Flush working memory after session end: same as wmClear, but marks the session-boundary discard of 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

@@ -18,7 +18,8 @@ import { errorMessage } from './util/log.js';
 const TAIL_MAX_BYTES = 256 * 1024;
 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.
+// 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/embeddings/provider.ts, connectors/*).
 const OTHER_ENV_NAMES = [
@@ -202,7 +203,8 @@ const HOME_SPELLINGS = [
     fileUrlPath,
     (p) => p.replace(/[^A-Za-z0-9]/g, '-'),
 ];
-// Git Bash, Cygwin and WSL mount a drive at /c, /cygdrive/c and /mnt/c; a Claude Code folder name writes each / and : as -.
+// Git Bash, Cygwin and WSL mount a drive at /c, /cygdrive/c and /mnt/c; a Claude Code folder name writes each / and :
+// as -.
 function mountedDrive(letter) {
     return `(?:${letter}[:-]|(?:[-/](?:cygdrive|mnt))?[-/]${letter})`;
 }
@@ -211,7 +213,8 @@ function spellingPattern(spelling, deep) {
     if (process.platform !== 'win32')
         return spelling.length >= 3 ? escapeRegex(spelling) : null;
     // Each tool that mounts a drive writes it its own way, so a home two or more folders below its drive (\Users\<name>)
-    // matches after any prefix, with \, / or JSON's \\ between folders. A drive written a known way goes into the swap with it.
+    // matches after any prefix, with \, / or JSON's \\ between folders. A drive written a known way goes into the swap
+    // with it.
     const drive = /^([A-Za-z])[:-]/.exec(spelling);
     const below = drive === null ? spelling : spelling.slice(2);
     const body = below.split(/[\\/]+/).map(escapeRegex).join('[\\\\/]+');
@@ -222,7 +225,8 @@ function spellingPattern(spelling, deep) {
     }
     if (deep)
         return `${mountedDrive(drive[1])}?${body}`;
-    // One folder (C:\x, D:\home) is a name any path may hold, so it swaps only after its drive and as a whole name; a drive
+    // One folder (C:\x, D:\home) is a name any path may hold, so it swaps only after its drive and as a whole name; a
+    // drive
     // root swaps nothing.
     return /[^\\/-]/.test(below) ? `(?<![\\p{L}\\p{N}_])${mountedDrive(drive[1])}${body}` : null;
 }
@@ -301,7 +305,8 @@ export function buildSupportBundle(opts) {
         env: listSetEnvNames(),
         logs: buildLogsSection(opts),
     };
-    // Store paths found from the working folder arrive resolved; the global root arrives as HIPPO_HOME was typed, and log lines
+    // Store paths found from the working folder arrive resolved; the global root arrives as HIPPO_HOME was typed, and log
+    // lines
     // often quote the temp folder, which usually sits under the home.
     const redacted = redactStrings(bundle, buildHomePattern(opts.home, [getGlobalRoot(), os.tmpdir()]));
     // SAFETY: the value built above is always a JsonObject; redactStrings preserves object shape.

package/dist/trust/quarantine.d.ts

@@ -1,4 +1,3 @@
 /** Quarantine tier (CD5, AT3): pending/approved/rejected record for a memory `remember` flagged as untrusted. */
-export { quarantineScopeFor } from '../store/quarantine.js';
-export declare function isQuarantineScope(scope: string | null | undefined): boolean;
+export { isQuarantineScope, quarantineScopeFor } from '../store/quarantine.js';
 //# sourceMappingURL=quarantine.d.ts.map

package/dist/trust/quarantine.js

@@ -1,8 +1,4 @@
 /** Quarantine tier (CD5, AT3): pending/approved/rejected record for a memory `remember` flagged as untrusted. */
-import { QUARANTINE_SCOPE_PREFIX } from '../store/quarantine.js';
 // The scope a held memory is stored under is the table's own rule, so the store module owns it.
-export { quarantineScopeFor } from '../store/quarantine.js';
-export function isQuarantineScope(scope) {
-    return scope != null && scope.startsWith(QUARANTINE_SCOPE_PREFIX);
-}
+export { isQuarantineScope, quarantineScopeFor } from '../store/quarantine.js';
 //# sourceMappingURL=quarantine.js.map

package/dist/trust/reject-flow.d.ts

@@ -9,14 +9,23 @@ export interface RejectFlowOpts {
     memoryId?: string;
     /** Pre-emptive form: reject a value not currently stored (or already gone). */
     value?: string;
-    /** The caller's own personal scope: the only personal rows the sweep may remove. Unset (the CLI) skips every personal row. */
+    /**
+     * The caller's own personal scope: the only personal rows the sweep may remove. Unset (the CLI) skips every personal
+     * row.
+     */
     ownScope?: string;
 }
 export type RejectFlowResult = AppliedRejection;
-/** `hippo reject` and `api.reject`: refuses a bad request, then tombstones the value and removes every row in reach that holds it. */
+/**
+ * `hippo reject` and `api.reject`: refuses a bad request, then tombstones the value and removes every row in reach that
+ * holds it.
+ */
 export declare function rejectValue(opts: RejectFlowOpts): RejectFlowResult;
 export type UnrejectOutcome = LiftedRejection;
-/** `hippo unreject` and `api.unreject`: lifts the one tombstone a digest or prefix names. The only way to allow a rejected value again. */
+/**
+ * `hippo unreject` and `api.unreject`: lifts the one tombstone a digest or prefix names. The only way to allow a
+ * rejected value again.
+ */
 export declare function unrejectValue(hippoRoot: string, tenantId: string, digestOrPrefix: string, actor: string): UnrejectOutcome;
 /** `hippo rejections` / `api.listRejections` — list tombstones for a tenant. */
 export declare function listRejectionsForTenant(hippoRoot: string, tenantId: string): RejectedValueRow[];

package/dist/trust/reject-flow.js

@@ -18,7 +18,8 @@ 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 refuse; an empty-normalized tombstone would refuse nothing 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.');
     }
 }
@@ -29,15 +30,19 @@ function contentToReject(opts, row) {
         throw new Error(`memory not found: ${opts.memoryId}`);
     }
     // A tombstone is tenant-wide, so one made from personal text would show its reason to everyone.
-    if (isPersonalScope(row.scope))
+    if (isPersonalScope(row.scope)) {
         throw new BadRequestError("Personal memories can't be rejected. Use forget to remove it.");
+    }
     return row.content;
 }
 /** Every row but another person's personal one, which is outside the caller's recall and so outside its reject. */
 function inReach(opts, scope) {
     return !isPersonalScope(scope) || scope === opts.ownScope;
 }
-/** `hippo reject` and `api.reject`: refuses a bad request, then tombstones the value and removes every row in reach that holds it. */
+/**
+ * `hippo reject` and `api.reject`: refuses a bad request, then tombstones the value and removes every row in reach that
+ * holds it.
+ */
 export function rejectValue(opts) {
     assertRejectOpts(opts);
     return applyRejection(opts.hippoRoot, {
@@ -50,7 +55,10 @@ export function rejectValue(opts) {
         successorOf: mergedSuccessor,
     });
 }
-/** `hippo unreject` and `api.unreject`: lifts the one tombstone a digest or prefix names. The only way to allow a rejected value again. */
+/**
+ * `hippo unreject` and `api.unreject`: lifts the one tombstone a digest or prefix names. The only way to allow a
+ * rejected value again.
+ */
 export function unrejectValue(hippoRoot, tenantId, digestOrPrefix, actor) {
     // A blank prefix would match every digest and list the whole tombstone set as ambiguous.
     if (digestOrPrefix.trim().length === 0) {

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

@@ -1,4 +1,7 @@
-/** The one Anthropic Messages client: sends one user prompt and returns the reply text or a typed failure the caller reacts to. */
+/**
+ * The one Anthropic Messages client: sends one user prompt and returns the reply text or a typed failure the caller
+ * reacts to.
+ */
 export interface AnthropicMessageRequest {
     apiKey: string;
     model?: string;
@@ -17,6 +20,8 @@ export type AnthropicMessageFailure = {
 } | {
     kind: 'unreadable';
     message: string;
+} | {
+    kind: 'empty';
 };
 export type AnthropicMessageResult = {
     ok: true;
@@ -27,7 +32,7 @@ export type AnthropicMessageResult = {
 };
 /** 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. */
+/** The reply's first text block, trimmed; a reply with no text is a failure of kind 'empty'. Never throws. */
 export declare function sendAnthropicMessage(req: AnthropicMessageRequest): Promise<AnthropicMessageResult>;
 /** The text extraction and DAG summaries hand to their `onError` callback. */
 export declare function describeMessageFailure(failure: AnthropicMessageFailure): string;

package/dist/util/anthropic-messages.js

@@ -1,6 +1,9 @@
-/** The one Anthropic Messages client: sends one user prompt and returns the reply text or a typed failure the caller reacts to. */
+/**
+ * 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, llmTotalMs } from './http-retry.js';
-import { errorMessage } from './log.js';
+import { errorFields, errorMessage, log } from './log.js';
 import { readCappedJson, readCappedText } from './capped-json.js';
 import { isJsonObject, isJsonString } from './json.js';
 import { redactSecretsStrict } from './secret-detect.js';
@@ -24,14 +27,19 @@ function firstText(reply) {
 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. */
+/**
+ * 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(() => '');
+    const body = await readCappedText(res, ERROR_SNIPPET_CHARS * UTF8_MAX_BYTES_PER_CHAR).catch((err) => {
+        log.warn(`anthropic: could not read the error body of a ${res.status} reply`, errorFields(err));
+        return '';
+    });
     // 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. */
+/** The reply's first text block, trimmed; a reply with no text is a failure of kind 'empty'. Never throws. */
 export async function sendAnthropicMessage(req) {
     let res;
     try {
@@ -56,9 +64,11 @@ export async function sendAnthropicMessage(req) {
         return { ok: false, failure: { kind: 'http', status: res.status, detail: await errorSnippet(res) } };
     try {
         const data = await readCappedJson(res, MAX_REPLY_BYTES);
-        if (!isJsonObject(data))
+        if (!isJsonObject(data)) {
             return { ok: false, failure: { kind: 'unreadable', message: 'the reply is not a JSON object' } };
-        return { ok: true, text: firstText(data) };
+        }
+        const text = firstText(data);
+        return text === '' ? { ok: false, failure: { kind: 'empty' } } : { ok: true, text };
     }
     catch (err) {
         return { ok: false, failure: { kind: 'unreadable', message: errorMessage(err) } };
@@ -70,6 +80,7 @@ export function describeMessageFailure(failure) {
         case 'request': return `request failed: ${failure.message}`;
         case 'http': return failure.detail ? `HTTP ${failure.status}: ${failure.detail}` : `HTTP ${failure.status}`;
         case 'unreadable': return `unparseable response: ${failure.message}`;
+        case 'empty': return 'the reply held no text';
     }
 }
 //# sourceMappingURL=anthropic-messages.js.map

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

@@ -1,4 +1,9 @@
-/** 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;
+/** 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.
+ *  `durable: false` skips the fsyncs for derived files that can be rebuilt; a reader still never sees a torn file. */
+export declare function writeFileAtomic(file: string, text: string, opts?: {
+    readonly durable?: boolean;
+}): void;
 //# sourceMappingURL=atomic-write.d.ts.map

package/dist/util/atomic-write.js

@@ -1,17 +1,19 @@
 // One way to replace a file a user or another program depends on: write a temp file beside it, then rename over it.
 import * as fs from 'fs';
 import * as path from 'path';
-import { errorMessage, log } from './log.js';
+import { errorMessage, log, errorFields } from './log.js';
 const RENAME_RETRY_MS = 1000;
 const WINDOWS_RENAME_REFUSALS = ['EPERM', 'EACCES', 'EBUSY'];
-// A rename can be refused where an in-place write still works (a bind-mounted file, a read-only folder), so these fall back to one.
+// A rename can be refused where an in-place write still works (a bind-mounted file, a read-only folder), so these fall
+// back to one.
 const REPLACE_REFUSALS = ['EBUSY', 'EXDEV', 'EACCES', 'EPERM'];
 // Matches the usual SYMLOOP_MAX, so a link cycle ends in an error instead of a hang.
 const MAX_LINK_HOPS = 40;
 function errnoCode(err) {
     return 'code' in err ? String(err.code) : '';
 }
-/** Windows refuses a rename onto a file another program has open, usually for a moment, so a refusal is retried before it is reported. */
+/** Windows refuses a rename onto a file another program has open, usually for a moment, so a refusal is retried
+ * before it is reported. */
 function renameOnto(tmp, target) {
     const deadline = Date.now() + RENAME_RETRY_MS;
     const idle = new Int32Array(new SharedArrayBuffer(4));
@@ -29,7 +31,8 @@ function renameOnto(tmp, target) {
         }
     }
 }
-/** Where a write to `file` lands: through any symlink, a dangling one included, so a dotfile manager's link survives. */
+/** Where a write to `file` lands: through any symlink, a
+ * dangling one included, so a dotfile manager's link survives. */
 function writeTarget(file) {
     let target = file;
     for (let hop = 0; hop < MAX_LINK_HOPS && fs.lstatSync(target, { throwIfNoEntry: false })?.isSymbolicLink(); hop++) {
@@ -43,29 +46,33 @@ function keepAccess(tmp, old) {
     if (process.getuid?.() === 0)
         fs.chownSync(tmp, old.uid, old.gid);
 }
-/** Cleanup must not hide the failure that made it necessary, so a cleanup error is logged and the first error stays the one thrown. */
+/** Cleanup must not hide the failure that made it necessary, so a cleanup error is logged and the first error stays
+ * the one thrown. */
 function removeTemp(tmp) {
     try {
         fs.rmSync(tmp, { force: true });
     }
     catch (err) {
-        log.warn(`could not remove the temporary file ${tmp}: ${errorMessage(err)}`);
+        log.warn(`could not remove the temporary file ${tmp}: ${errorMessage(err)}`, errorFields(err));
     }
 }
-/** Flushed before the rename, or a crash soon after could leave the file's name on bytes that never reached the disk. */
-function writeFlushed(tmp, text, old) {
+/** Flushed before the rename, or a crash soon after could
+ * leave the file's name on bytes that never reached the disk. */
+function writeFlushed(tmp, text, old, durable) {
     const fd = fs.openSync(tmp, 'w', (old?.mode ?? 0o666) & 0o777);
     try {
         fs.writeFileSync(fd, text, 'utf8');
         if (old)
             keepAccess(tmp, old);
-        fs.fsyncSync(fd);
+        if (durable)
+            fs.fsyncSync(fd);
     }
     finally {
         fs.closeSync(fd);
     }
 }
-/** Stores the rename itself. Windows cannot flush a folder handle, and a failure here costs durability, not content, so it only warns. */
+/** Stores the rename itself. Windows cannot flush a folder handle, and a failure here costs durability, not content,
+ * so it only warns. */
 function flushFolder(dir) {
     if (process.platform === 'win32')
         return;
@@ -79,22 +86,24 @@ function flushFolder(dir) {
         }
     }
     catch (err) {
-        log.warn(`could not flush the folder ${dir} to disk after replacing a file in it: ${errorMessage(err)}`);
+        log.warn(`could not flush the folder ${dir} to disk after replacing a file in it: ${errorMessage(err)}`, errorFields(err));
     }
 }
-function replaceViaTemp(target, text, old) {
+function replaceViaTemp(target, text, old, durable) {
     const tmp = `${target}.${process.pid}.tmp`;
     try {
-        writeFlushed(tmp, text, old);
+        writeFlushed(tmp, text, old, durable);
         renameOnto(tmp, target);
     }
     catch (err) {
         removeTemp(tmp);
         throw err;
     }
-    flushFolder(path.dirname(target));
+    if (durable)
+        flushFolder(path.dirname(target));
 }
-/** The pre-rename write: it truncates first, so it is only the fallback, but it needs just a writable file and keeps hard links together. */
+/** The pre-rename write: it truncates first, so it is only the fallback, but it needs just a writable file and keeps
+ * hard links together. */
 function writeInPlace(target, text) {
     try {
         fs.writeFileSync(target, text, 'utf8');
@@ -108,16 +117,21 @@ function writeInPlace(target, text) {
         throw new Error(`${target} ${reason}`, { cause: err });
     }
 }
-/** 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 function writeFileAtomic(file, text) {
+/** 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.
+ *  `durable: false` skips the fsyncs for derived files that can be rebuilt; a reader still never sees a torn file. */
+export function writeFileAtomic(file, text, opts = {}) {
+    const durable = opts.durable !== false;
     const target = writeTarget(file);
     const old = fs.statSync(target, { throwIfNoEntry: false });
     if (old === undefined) {
         fs.mkdirSync(path.dirname(target), { recursive: true });
     }
     else {
-        // A rename replaces a read-only file that the in-place write refused, and Windows would retry that refusal for a second.
+        // A rename replaces a read-only file that the in-place write
+        // refused, and Windows would retry that refusal for a second.
         fs.accessSync(target, fs.constants.W_OK);
     }
     if (old !== undefined && old.nlink > 1) {
@@ -126,12 +140,13 @@ export function writeFileAtomic(file, text) {
         return;
     }
     try {
-        replaceViaTemp(target, text, old);
+        replaceViaTemp(target, text, old, durable);
     }
     catch (err) {
         if (!(err instanceof Error) || !REPLACE_REFUSALS.includes(errnoCode(err)))
             throw err;
-        log.warn(`${target} could not be replaced by a rename (${errnoCode(err)}), so it is written in place: not atomic, a crash mid-write can leave it truncated`);
+        log.warn(`${target} could not be replaced by a rename (${errnoCode(err)}), so it is ` +
+            `written in place: not atomic, a crash mid-write can leave it truncated`, errorFields(err));
         writeInPlace(target, text);
     }
 }