hippo-memory 1.70.0 → 1.71.0

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

package/dist/util/atomic-write.js

@@ -52,18 +52,47 @@ function removeTemp(tmp) {
         log.warn(`could not remove the temporary file ${tmp}: ${errorMessage(err)}`);
     }
 }
-function replaceViaTemp(target, text, old) {
-    const tmp = `${target}.${process.pid}.tmp`;
+/** 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) {
+    const fd = fs.openSync(tmp, 'w', (old?.mode ?? 0o666) & 0o777);
     try {
-        fs.writeFileSync(tmp, text, { encoding: 'utf8', mode: (old?.mode ?? 0o666) & 0o777 });
+        fs.writeFileSync(fd, text, 'utf8');
         if (old)
             keepAccess(tmp, old);
+        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. */
+function flushFolder(dir) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        const fd = fs.openSync(dir, 'r');
+        try {
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (err) {
+        log.warn(`could not flush the folder ${dir} to disk after replacing a file in it: ${errorMessage(err)}`);
+    }
+}
+function replaceViaTemp(target, text, old) {
+    const tmp = `${target}.${process.pid}.tmp`;
+    try {
+        writeFlushed(tmp, text, old);
         renameOnto(tmp, target);
     }
     catch (err) {
         removeTemp(tmp);
         throw err;
     }
+    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. */
 function writeInPlace(target, text) {
@@ -79,7 +108,8 @@ function writeInPlace(target, text) {
         throw new Error(`${target} ${reason}`, { cause: err });
     }
 }
-/** 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 function writeFileAtomic(file, text) {
     const target = writeTarget(file);
     const old = fs.statSync(target, { throwIfNoEntry: false });
@@ -101,6 +131,7 @@ export function writeFileAtomic(file, text) {
     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`);
         writeInPlace(target, text);
     }
 }

package/dist/util/capped-json.d.ts

@@ -0,0 +1,6 @@
+import type { JsonValue } from './json.js';
+/** Reads a reply body as JSON and stops with an error as soon as it passes `maxBytes`. */
+export declare function readCappedJson(resp: Response, maxBytes: number): Promise<JsonValue>;
+/** Reads at most `maxBytes` of a body as text, then cancels the rest; never throws on size. */
+export declare function readCappedText(resp: Response, maxBytes: number): Promise<string>;
+//# sourceMappingURL=capped-json.d.ts.map

package/dist/util/capped-json.js

@@ -0,0 +1,46 @@
+// The timeout bounds time, not bytes: a hostile endpoint could stream a huge 2xx body into memory.
+/** Reads a reply body as JSON and stops with an error as soon as it passes `maxBytes`. */
+export async function readCappedJson(resp, maxBytes) {
+    if (!resp.body)
+        throw new Error('reply has no body');
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder();
+    let raw = '';
+    let received = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        received += value.byteLength;
+        if (received > maxBytes) {
+            await reader.cancel();
+            throw new Error(`reply over ${maxBytes} bytes`);
+        }
+        raw += decoder.decode(value, { stream: true });
+    }
+    raw += decoder.decode();
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error('reply is not JSON', { cause: err });
+    }
+}
+/** Reads at most `maxBytes` of a body as text, then cancels the rest; never throws on size. */
+export async function readCappedText(resp, maxBytes) {
+    if (!resp.body)
+        return '';
+    const reader = resp.body.getReader();
+    const chunks = [];
+    let received = 0;
+    while (received < maxBytes) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(value.subarray(0, maxBytes - received));
+        received += chunks[chunks.length - 1].byteLength;
+    }
+    await reader.cancel();
+    return new TextDecoder().decode(Buffer.concat(chunks));
+}
+//# sourceMappingURL=capped-json.js.map

package/dist/util/crash-handlers.d.ts

@@ -1,5 +1,12 @@
+/** What an entry point runs before it exits, and how long that may take before the process is ended without it. */
+export interface Shutdown {
+    readonly run: () => void | Promise<void>;
+    readonly boundMs: number;
+}
 /** Exit once stdout and stderr have drained, so the last reply and the last log line reach their reader; capped at 1 s. */
 export declare function exitAfterFlush(code: number): void;
+/** On SIGTERM or SIGINT: runs `shutdown` once, then exits 0. */
+export declare function installSignalHandlers(name: string, shutdown: Shutdown): void;
 /** After an uncaught throw the process state is unknown: log the cause, run `shutdown` once, then exit 1 for the supervisor or client to restart it. */
-export declare function installCrashHandlers(name: string, shutdown?: () => void | Promise<void>): void;
+export declare function installCrashHandlers(name: string, shutdown?: Shutdown): void;
 //# sourceMappingURL=crash-handlers.d.ts.map

package/dist/util/crash-handlers.js

@@ -1,17 +1,59 @@
 // Last-resort process handlers shared by the long-running entry points (`hippo mcp`, `hippo serve`).
 import { errorFields, errorMessage, log } from './log.js';
-/** Exit once stdout and stderr have drained, so the last reply and the last log line reach their reader; capped at 1 s. */
-export function exitAfterFlush(code) {
-    process.exitCode = code;
+function afterFlush(leave) {
     let pending = 2;
     const done = () => { if (--pending === 0)
-        process.exit(code); };
+        leave(); };
     process.stdout.write('', done);
     process.stderr.write('', done);
-    setTimeout(() => process.exit(code), 1000).unref();
+    setTimeout(leave, 1000).unref();
+}
+/** Exit once stdout and stderr have drained, so the last reply and the last log line reach their reader; capped at 1 s. */
+export function exitAfterFlush(code) {
+    process.exitCode = code;
+    afterFlush(() => process.exit(code));
+}
+// process.exit joins every worker thread, so one stuck in a synchronous statement would hold the exit open; a kill cannot be held.
+function killSelf() {
+    process.kill(process.pid, 'SIGKILL');
+}
+/** Runs `shutdown` for `cause`, then exits with `code`, or 1 when it threw. One still running after its bound is logged and the process ended without it. */
+function exitAfterShutdown(name, cause, shutdown, code) {
+    let ended = false;
+    // Referenced on purpose: a shutdown that never settles must end at the bound, not when the loop happens to empty.
+    const bound = setTimeout(() => {
+        ended = true;
+        log.error(`${name} shutdown after ${cause} did not finish within ${shutdown.boundMs} ms; ending the process without it`);
+        process.exitCode = 1;
+        afterFlush(killSelf);
+    }, shutdown.boundMs);
+    void Promise.resolve()
+        .then(shutdown.run)
+        .then(() => code, (err) => {
+        log.error(`${name} shutdown after ${cause} failed: ${errorMessage(err)}`, errorFields(err));
+        return 1;
+    })
+        .then((exitCode) => {
+        clearTimeout(bound);
+        if (!ended)
+            exitAfterFlush(exitCode);
+    });
+}
+/** On SIGTERM or SIGINT: runs `shutdown` once, then exits 0. */
+export function installSignalHandlers(name, shutdown) {
+    let shuttingDown = false;
+    const stopFor = (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        log.warn(`received ${signal}, shutting down`);
+        exitAfterShutdown(name, signal, shutdown, 0);
+    };
+    process.once('SIGTERM', () => stopFor('SIGTERM'));
+    process.once('SIGINT', () => stopFor('SIGINT'));
 }
 /** After an uncaught throw the process state is unknown: log the cause, run `shutdown` once, then exit 1 for the supervisor or client to restart it. */
-export function installCrashHandlers(name, shutdown = () => { }) {
+export function installCrashHandlers(name, shutdown) {
     let crashing = false;
     const crash = (kind, err) => {
         log.error(`${name} ${kind}: ${errorMessage(err)}`, errorFields(err));
@@ -19,10 +61,10 @@ export function installCrashHandlers(name, shutdown = () => { }) {
         if (crashing)
             return;
         crashing = true;
-        Promise.resolve()
-            .then(shutdown)
-            .catch((shutdownErr) => log.error(`${name} shutdown after ${kind} failed: ${errorMessage(shutdownErr)}`, errorFields(shutdownErr)))
-            .finally(() => exitAfterFlush(1));
+        if (shutdown)
+            exitAfterShutdown(name, kind, shutdown, 1);
+        else
+            exitAfterFlush(1);
     };
     process.on('uncaughtException', (err) => crash('uncaught exception', err));
     process.on('unhandledRejection', (err) => crash('unhandled rejection', err));

package/dist/util/env.d.ts

@@ -28,7 +28,9 @@ export declare function envClaudeCodeSessionId(): string | undefined;
 export declare function envScope(): string | undefined;
 export declare function envGstackSkill(): string | undefined;
 export declare function envOpenclawSkill(): string | undefined;
-/** HIPPO_TENANT trimmed; empty or whitespace-only falls through to 'default'. */
+/** The tenant of a store that names none. */
+export declare const DEFAULT_TENANT_ID = "default";
+/** HIPPO_TENANT trimmed; empty or whitespace-only falls through to the default tenant. */
 export declare function envTenant(): string;
 export declare function envSkipAutoIntegrations(): boolean;
 export declare function envSkipPostinstall(): boolean;
@@ -44,12 +46,15 @@ export declare function envPort(): string | undefined;
 /** How long a client waits for a running server's /health before writing to the store directly; server-detect.ts holds the default. */
 export declare function envHealthProbeMs(): number | undefined;
 export declare function envRequireAuth(): boolean;
+/** `1` lets a request made on this machine in with no key, as host admin; HIPPO_REQUIRE_AUTH=1 wins over it. */
+export declare function envAllowKeylessLocal(): boolean;
 export declare function envV1Rps(): string | undefined;
 /** How long a request body may take to arrive; http-util.ts holds the default. */
 export declare function envBodyTimeoutMs(): number | undefined;
 /** How long POST /v1/sleep lets its consolidation run; server/sleep-offload.ts holds the default. */
 export declare function envSleepTimeoutMs(): number | undefined;
-/** How long a /v1 or /mcp request may run before the server answers 504, 0 for no deadline; server/deadline.ts holds the default. */
+/** How long a /v1 or /mcp request may run before the server answers 504, and a stdio MCP
+ * request before its timeout error; 0 for no deadline; server/deadline.ts holds the default. */
 export declare function envRequestDeadlineMs(): number | undefined;
 /** How many store calls may wait for one worker thread before the next is refused; store/sqlite/executor.ts holds the default. */
 export declare function envStoreQueueMax(): number | undefined;
@@ -69,6 +74,8 @@ export declare function envLlmTimeoutMs(): number | undefined;
 export declare function envTypesafeApiKey(): string | undefined;
 export declare function envJevTimeoutMs(): number | undefined;
 export declare function envJevModel(): string | undefined;
+/** How long a recall waits for an API provider to embed its query before ranking on BM25 alone; search/vector.ts holds the default. */
+export declare function envQueryEmbedTimeoutMs(): number | undefined;
 export declare function envLlmRerankerUrl(): string | undefined;
 export declare function envLlmRerankerKey(): string | undefined;
 export declare function envLlmRerankerModel(): string | undefined;
@@ -83,8 +90,8 @@ export declare function envSlackTeamId(): string | undefined;
 export declare function envSlackSigningSecret(): string | undefined;
 export declare function envSlackSigningSecretPrevious(): string | undefined;
 export declare function envSlackAllowUnknownTeamFallback(): boolean;
-export declare function envGithubToken(): string | undefined;
-export declare function envGithubWebhookSecret(): string | undefined;
-export declare function envGithubWebhookSecretPrevious(): string | undefined;
-export declare function envGithubAllowUnknownInstallationFallback(): boolean;
+export declare function envGitHubToken(): string | undefined;
+export declare function envGitHubWebhookSecret(): string | undefined;
+export declare function envGitHubWebhookSecretPrevious(): string | undefined;
+export declare function envGitHubAllowUnknownInstallationFallback(): boolean;
 //# sourceMappingURL=env.d.ts.map

package/dist/util/env.js

@@ -71,9 +71,11 @@ export function envClaudeCodeSessionId() { return trimmed('CLAUDE_CODE_SESSION_I
 export function envScope() { return raw('HIPPO_SCOPE'); }
 export function envGstackSkill() { return raw('GSTACK_SKILL'); }
 export function envOpenclawSkill() { return raw('OPENCLAW_SKILL'); }
-/** HIPPO_TENANT trimmed; empty or whitespace-only falls through to 'default'. */
+/** The tenant of a store that names none. */
+export const DEFAULT_TENANT_ID = 'default';
+/** HIPPO_TENANT trimmed; empty or whitespace-only falls through to the default tenant. */
 export function envTenant() {
-    return raw('HIPPO_TENANT')?.trim() || 'default';
+    return raw('HIPPO_TENANT')?.trim() || DEFAULT_TENANT_ID;
 }
 // Install and CLI switches.
 export function envSkipAutoIntegrations() { return isOne('HIPPO_SKIP_AUTO_INTEGRATIONS'); }
@@ -91,12 +93,15 @@ export function envPort() { return raw('HIPPO_PORT'); }
 /** How long a client waits for a running server's /health before writing to the store directly; server-detect.ts holds the default. */
 export function envHealthProbeMs() { return positiveInt('HIPPO_HEALTH_PROBE_MS'); }
 export function envRequireAuth() { return isOne('HIPPO_REQUIRE_AUTH'); }
+/** `1` lets a request made on this machine in with no key, as host admin; HIPPO_REQUIRE_AUTH=1 wins over it. */
+export function envAllowKeylessLocal() { return isOne('HIPPO_ALLOW_KEYLESS_LOCAL'); }
 export function envV1Rps() { return raw('HIPPO_V1_RPS'); }
 /** How long a request body may take to arrive; http-util.ts holds the default. */
 export function envBodyTimeoutMs() { return positiveInt('HIPPO_BODY_TIMEOUT_MS'); }
 /** How long POST /v1/sleep lets its consolidation run; server/sleep-offload.ts holds the default. */
 export function envSleepTimeoutMs() { return positiveInt('HIPPO_SLEEP_TIMEOUT_MS'); }
-/** How long a /v1 or /mcp request may run before the server answers 504, 0 for no deadline; server/deadline.ts holds the default. */
+/** How long a /v1 or /mcp request may run before the server answers 504, and a stdio MCP
+ * request before its timeout error; 0 for no deadline; server/deadline.ts holds the default. */
 export function envRequestDeadlineMs() { return nonNegativeInt('HIPPO_REQUEST_DEADLINE_MS'); }
 /** How many store calls may wait for one worker thread before the next is refused; store/sqlite/executor.ts holds the default. */
 export function envStoreQueueMax() { return positiveInt('HIPPO_STORE_QUEUE_MAX'); }
@@ -117,6 +122,8 @@ export function envLlmTimeoutMs() { return positiveInt('HIPPO_LLM_TIMEOUT_MS');
 export function envTypesafeApiKey() { return trimmed('TYPESAFE_API_KEY'); }
 export function envJevTimeoutMs() { return positiveInt('HIPPO_JEV_TIMEOUT_MS'); }
 export function envJevModel() { return raw('HIPPO_JEV_MODEL'); }
+/** How long a recall waits for an API provider to embed its query before ranking on BM25 alone; search/vector.ts holds the default. */
+export function envQueryEmbedTimeoutMs() { return positiveInt('HIPPO_QUERY_EMBED_TIMEOUT_MS'); }
 export function envLlmRerankerUrl() { return raw('HIPPO_LLM_RERANKER_URL'); }
 export function envLlmRerankerKey() { return raw('HIPPO_LLM_RERANKER_KEY'); }
 export function envLlmRerankerModel() { return raw('HIPPO_LLM_RERANKER_MODEL'); }
@@ -132,8 +139,8 @@ export function envSlackTeamId() { return raw('SLACK_TEAM_ID'); }
 export function envSlackSigningSecret() { return raw('SLACK_SIGNING_SECRET'); }
 export function envSlackSigningSecretPrevious() { return raw('SLACK_SIGNING_SECRET_PREVIOUS'); }
 export function envSlackAllowUnknownTeamFallback() { return isOne('SLACK_ALLOW_UNKNOWN_TEAM_FALLBACK'); }
-export function envGithubToken() { return raw('GITHUB_TOKEN'); }
-export function envGithubWebhookSecret() { return raw('GITHUB_WEBHOOK_SECRET'); }
-export function envGithubWebhookSecretPrevious() { return raw('GITHUB_WEBHOOK_SECRET_PREVIOUS'); }
-export function envGithubAllowUnknownInstallationFallback() { return isOne('GITHUB_ALLOW_UNKNOWN_INSTALLATION_FALLBACK'); }
+export function envGitHubToken() { return raw('GITHUB_TOKEN'); }
+export function envGitHubWebhookSecret() { return raw('GITHUB_WEBHOOK_SECRET'); }
+export function envGitHubWebhookSecretPrevious() { return raw('GITHUB_WEBHOOK_SECRET_PREVIOUS'); }
+export function envGitHubAllowUnknownInstallationFallback() { return isOne('GITHUB_ALLOW_UNKNOWN_INSTALLATION_FALLBACK'); }
 //# sourceMappingURL=env.js.map

package/dist/util/home-path.d.ts

@@ -1,4 +1,5 @@
-/** One pattern per path shape that carries a user name: Windows, Git Bash and WSL mounts, extended-length, UNC home shares, Linux, macOS and 8.3 short names. */
+/** One pattern per path shape that carries a user name: Windows, Git Bash and WSL
+ * mounts, extended-length, UNC home shares, Linux, macOS and 8.3 short names. */
 export declare const USER_SEGMENT: readonly RegExp[];
 /** `text` with each home-directory segment replaced by `[home]`. */
 export declare function maskHomePaths(text: string): string;

package/dist/util/home-path.js

@@ -2,7 +2,8 @@
 // VS Code writes file links URL-encoded, so a separator may be %5C or %2F.
 const WIN_SEP = String.raw `(?:[\\/]|%5[Cc]|%2[Ff])`;
 const WIN_CHAR = String.raw `(?:(?!%5[Cc]|%2[Ff])[^\\/:*?"<>|\s])`;
-// A Windows name never holds a quote, so JSON stops it; one with spaces runs to a separator, quote, closing mark or line end, leaving the mark, as stopping at its first word leaks the surname.
+// A Windows name never holds a quote, so JSON stops it; one with spaces runs to a separator, quote,
+// closing mark or line end, leaving the mark, as stopping at its first word leaks the surname.
 const WIN_USER = String.raw `(?:${WIN_CHAR}+(?: ${WIN_CHAR}+){0,3}(?=${WIN_SEP}|["'\`)\]>,;]|\.(?=\s|$)|(?<!\.)(?:[^\S ]|$))(?<![\`)\],;'])|${WIN_CHAR}+)`;
 // Slash-led homes with their case spelled out and no flag, so one pattern can hold all four: Git Bash and WSL mounts, Linux, root and macOS.
 const MOUNT_HOME = String.raw `(?:\/[Mm][Nn][Tt])?\/[A-Za-z]\/[Uu][Ss][Ee][Rr][Ss]\/${WIN_USER}`;
@@ -18,7 +19,8 @@ const MOUNT_START = String.raw `(?<![\w.])${MOUNT_HOME}`;
 const LINUX_START = String.raw `(?<![\w.~-])${LINUX_HOME}`;
 const ROOT_START = String.raw `(?<![\w.~-])${ROOT_HOME}`;
 const MAC_START = String.raw `(?<![\w.~-])${MAC_HOME}`;
-/** One pattern per path shape that carries a user name: Windows, Git Bash and WSL mounts, extended-length, UNC home shares, Linux, macOS and 8.3 short names. */
+/** One pattern per path shape that carries a user name: Windows, Git Bash and WSL
+ * mounts, extended-length, UNC home shares, Linux, macOS and 8.3 short names. */
 export const USER_SEGMENT = [
     DRIVE_HOME,
     new RegExp(MOUNT_START),

package/dist/util/http-retry.d.ts

@@ -12,6 +12,7 @@ export interface RetryPolicy {
     /** Also retry a dropped connection or a timed-out attempt. On for GET and HEAD; any other method turns it on only when a replay cannot commit twice. */
     retryTransport?: boolean;
     fetchFn?: typeof fetch;
+    /** Replaces the timer between attempts. A caller `signal` that aborts still ends the wait at once. */
     sleep?: (ms: number) => Promise<void>;
     random?: () => number;
 }
@@ -22,6 +23,7 @@ export declare function isRetryableStatus(status: number): boolean;
 export declare function parseRetryAfterMs(header: string | null, now?: number): number | null;
 /** A dropped connection, a DNS hiccup or a timed-out attempt: faults a second try can clear. A refused connection is not one. */
 export declare function isTransientTransportError<E>(err: E): boolean;
-/** `fetch` with a per-attempt timeout and up to `attempts` tries on 429, 5xx and (see `retryTransport`) transport faults; the last response or error comes back as is. */
+/** `fetch` with a per-attempt timeout and up to `attempts` tries on 429, 5xx and (see
+ * `retryTransport`) transport faults; the last response or error comes back as is. */
 export declare function fetchWithRetry(url: string | URL, init: RequestInit, policy: RetryPolicy): Promise<Response>;
 //# sourceMappingURL=http-retry.d.ts.map

package/dist/util/http-retry.js

@@ -39,14 +39,35 @@ function isIdempotent(method) {
     const verb = (method ?? 'GET').toUpperCase();
     return verb === 'GET' || verb === 'HEAD';
 }
-const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-/** `fetch` with a per-attempt timeout and up to `attempts` tries on 429, 5xx and (see `retryTransport`) transport faults; the last response or error comes back as is. */
+// `cancel` clears the timer, so a wait the caller left does not keep the process alive.
+const timerSleep = (ms, cancel) => new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    cancel?.addEventListener('abort', () => clearTimeout(timer), { once: true });
+});
+/** The wait between attempts. With a caller signal it ends the moment that signal aborts and rejects with its reason, so no further attempt starts. */
+async function backoffWait(ms, sleep, signal) {
+    if (!signal)
+        return (sleep ?? timerSleep)(ms);
+    signal.throwIfAborted();
+    const left = new AbortController();
+    const aborted = new Promise((_resolve, reject) => {
+        signal.addEventListener('abort', () => reject(signal.reason), { once: true, signal: left.signal });
+    });
+    try {
+        // An injected sleep cannot be cancelled, so it is raced and left to run out.
+        await Promise.race([sleep ? sleep(ms) : timerSleep(ms, left.signal), aborted]);
+    }
+    finally {
+        left.abort();
+    }
+}
+/** `fetch` with a per-attempt timeout and up to `attempts` tries on 429, 5xx and (see
+ * `retryTransport`) transport faults; the last response or error comes back as is. */
 export async function fetchWithRetry(url, init, policy) {
     const fetchFn = policy.fetchFn ?? fetch;
     const attempts = Math.max(1, policy.attempts ?? DEFAULT_ATTEMPTS);
     const baseDelayMs = policy.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
     const maxDelayMs = policy.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
-    const sleep = policy.sleep ?? realSleep;
     const random = policy.random ?? Math.random;
     const retryOn = policy.retryOn ?? ((res) => isRetryableStatus(res.status));
     const retryTransport = policy.retryTransport ?? isIdempotent(init.method);
@@ -66,7 +87,7 @@ export async function fetchWithRetry(url, init, policy) {
             // The caller's own abort is a decision, not a fault, so it ends the call.
             if (!retryTransport || attempt >= attempts || init.signal?.aborted || !isTransientTransportError(err))
                 throw err;
-            await sleep(backoffMs(attempt));
+            await backoffWait(backoffMs(attempt), policy.sleep, init.signal);
             continue;
         }
         if (!retryOn(res) || attempt >= attempts)
@@ -76,7 +97,7 @@ export async function fetchWithRetry(url, init, policy) {
             return res;
         // Frees the pooled socket before the next attempt.
         await res.body?.cancel();
-        await sleep(retryAfter ?? backoffMs(attempt));
+        await backoffWait(retryAfter ?? backoffMs(attempt), policy.sleep, init.signal);
     }
 }
 //# sourceMappingURL=http-retry.js.map

package/dist/util/log.d.ts

@@ -1,4 +1,5 @@
-/** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info, debug); unset or unknown means warn. `HIPPO_LOG_FORMAT=json` writes JSON lines. */
+/** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info,
+ * debug); unset or unknown means warn. `HIPPO_LOG_FORMAT=json` writes JSON lines. */
 export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
 /** Extra key=value pairs appended to the line. `ts` and, inside a request, `requestId` are added to every line written. */
 export interface LogFields {
@@ -13,7 +14,7 @@ export declare function isLevelEnabled(level: LogLevel): boolean;
 export declare function formatLogLine(level: LogLevel, message: string, fields?: LogFields): string;
 /** One JSON object per line for a log collector; JSON escaping keeps a multi-line value on the one line. */
 export declare function formatLogJson(level: LogLevel, message: string, fields?: LogFields): string;
-/** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. */
+/** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. Past the key cap an unseen key logs at debug. */
 declare function once(key: string, level: LogLevel, message: string, fields?: LogFields): void;
 /** Warn the first time `key` is seen in this process, then log at debug, so a repeating failure stays findable without flooding stderr. */
 declare function warnThenDebug(key: string, message: string, fields?: LogFields): void;

package/dist/util/log.js

@@ -1,4 +1,5 @@
-/** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info, debug); unset or unknown means warn. `HIPPO_LOG_FORMAT=json` writes JSON lines. */
+/** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info,
+ * debug); unset or unknown means warn. `HIPPO_LOG_FORMAT=json` writes JSON lines. */
 import { envLogJson, envLogLevel } from './env.js';
 import { currentRequestId } from './request-scope.js';
 const RANK = { error: 0, warn: 1, info: 2, debug: 3 };
@@ -36,19 +37,33 @@ function write(level, message, fields) {
     const format = envLogJson() ? formatLogJson : formatLogLine;
     process.stderr.write(`${format(level, message, stamped)}\n`);
 }
+// Some keys follow the data (one per damaged row and column), so the set of them stops growing here.
+const ONCE_KEY_CAP = 1_000;
 const onceKeys = new Set();
-/** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. */
-function once(key, level, message, fields) {
+let onceCapReported = false;
+/** 'new' records the key and 'seen' is a repeat. 'uncounted' is an unseen key once the set is full: it is not recorded, and the first one says so at warn. */
+function sightOnceKey(key) {
     if (onceKeys.has(key))
-        return;
-    onceKeys.add(key);
-    write(level, message, fields);
+        return 'seen';
+    if (onceKeys.size < ONCE_KEY_CAP) {
+        onceKeys.add(key);
+        return 'new';
+    }
+    if (!onceCapReported) {
+        onceCapReported = true;
+        write('warn', `log: ${ONCE_KEY_CAP} once-only warnings were written; further new ones in this process log at debug`);
+    }
+    return 'uncounted';
+}
+/** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. Past the key cap an unseen key logs at debug. */
+function once(key, level, message, fields) {
+    const sighting = sightOnceKey(key);
+    if (sighting !== 'seen')
+        write(sighting === 'new' ? level : 'debug', message, fields);
 }
 /** Warn the first time `key` is seen in this process, then log at debug, so a repeating failure stays findable without flooding stderr. */
 function warnThenDebug(key, message, fields) {
-    const level = onceKeys.has(key) ? 'debug' : 'warn';
-    onceKeys.add(key);
-    write(level, message, fields);
+    write(sightOnceKey(key) === 'new' ? 'warn' : 'debug', message, fields);
 }
 /** The class name and stack of a thrown value, as log fields; a non-Error throw has no stack. */
 export function errorFields(err) {
@@ -71,5 +86,6 @@ export function errorMessage(cause) {
 /** Test hook: forget which once-keys have fired. */
 export function resetLogOnce() {
     onceKeys.clear();
+    onceCapReported = false;
 }
 //# sourceMappingURL=log.js.map

package/dist/util/request-scope.d.ts

@@ -22,6 +22,7 @@ export declare const requestScopes: AsyncLocalStorage<RequestScope>;
 export declare function currentRequestId(): string | undefined;
 /** The deadline of the request this code runs for, if it has one. */
 export declare function currentDeadline(): RequestDeadline | undefined;
-/** Runs `fn` with `requestId` on every log line it writes, including the ones from timers and promises it starts. `deadline` reaches every store call made inside. */
+/** Runs `fn` with `requestId` on every log line it writes, including the ones from
+ * timers and promises it starts. `deadline` reaches every store call made inside. */
 export declare function runWithRequestId<T>(requestId: string, fn: () => T, deadline?: RequestDeadline): T;
 //# sourceMappingURL=request-scope.d.ts.map

package/dist/util/request-scope.js

@@ -40,7 +40,8 @@ export function currentRequestId() {
 export function currentDeadline() {
     return requestScopes.getStore()?.deadline;
 }
-/** Runs `fn` with `requestId` on every log line it writes, including the ones from timers and promises it starts. `deadline` reaches every store call made inside. */
+/** Runs `fn` with `requestId` on every log line it writes, including the ones from
+ * timers and promises it starts. `deadline` reaches every store call made inside. */
 export function runWithRequestId(requestId, fn, deadline) {
     return requestScopes.run({ requestId, deadline }, fn);
 }

package/dist/util/secret-detect.d.ts

@@ -1,22 +1,5 @@
-/**
- * Secret detection for memory content (memory scope isolation).
- *
- * Conservative, provider-bounded patterns only - a bare `sk-` in prose must
- * NOT flag. Detection gates two surfaces:
- *  - producer: shareMemory/autoShare never promote flagged rows to the
- *    global store;
- *  - consumer: ambient context (getContext) never injects a flagged row
- *    outside its owning project, and never anywhere when the row has no
- *    project origin. Explicit recall is unaffected - recalling a secret is
- *    a deliberate act.
- *
- * This is deliberately a thin slice of lifecycle compliance
- * (no PII detection). Write-time scrubbing covers only text no person
- * typed into hippo; see `vetSecrets`.
- *
- * Leaf module: keep free of imports from store/api/shared so all of them
- * can import it without cycles.
- */
+/** Secret detection for memory content: conservative provider-bounded patterns (a bare `sk-` in prose must not flag). Flagged rows are never shared to
+ * the global store or injected as ambient context outside their project; explicit recall is unaffected. Leaf module: no imports from store/api/shared. */
 /** Result of scanning one memory. `reason` names the tag or pattern that fired. */
 export interface SecretDetection {
     flagged: boolean;
@@ -24,21 +7,13 @@ export interface SecretDetection {
 }
 /** Tags that flag a memory as secret, lower case; detectSecret folds a tag's case before the lookup. */
 export declare const SECRET_TAGS: ReadonlySet<string>;
-/**
- * Scan a memory's tags + content for secret material.
- * Pure and deterministic; no filesystem or store access.
- */
+/** Scan a memory's tags + content for secret material; pure and deterministic, no filesystem or store access. */
 export declare function detectSecret(entry: {
     content: string;
     tags: string[];
 }): SecretDetection;
-/**
- * Replace secret-shaped substrings in free text with a redaction marker.
- * Reuses the same `SECRET_PATTERNS` / co-occurrence guard as `detectSecret`
- * (which only flags whole-entry content) so callers that must persist raw
- * text that never passes through the normal capture content gate (e.g. the
- * pre-compact snapshot fields) can scrub it in place instead.
- */
+/** Replace secret-shaped substrings in free text with a redaction marker, using the same `SECRET_PATTERNS` and co-occurrence guard as `detectSecret`;
+ * for callers persisting text that skips the capture content gate (e.g. pre-compact snapshot fields). */
 export declare function redactSecrets(text: string): string;
 /** Memories never hold a raw email address (AGENTS.md); phone numbers are left alone, as their patterns misfire on ids. */
 export declare function maskEmails(text: string): string;