hippo-memory 1.70.0 → 1.72.0

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/chunked.d.ts

@@ -0,0 +1,3 @@
+/** `items` in consecutive slices of at most `size`. */
+export declare function chunked<T>(items: readonly T[], size?: number): T[][];
+//# sourceMappingURL=chunked.d.ts.map

package/dist/util/chunked.js

@@ -0,0 +1,10 @@
+/** Ids per `IN (...)` list: far under SQLite's bound-parameter limit, with room for the tenant filter. */
+const ID_CHUNK = 500;
+/** `items` in consecutive slices of at most `size`. */
+export function chunked(items, size = ID_CHUNK) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+//# sourceMappingURL=chunked.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/ellipsize.d.ts

@@ -0,0 +1,3 @@
+/** `text` cut to `max` characters plus a marker, or unchanged when it already fits. */
+export declare function truncateWithEllipsis(text: string, max: number, marker?: string): string;
+//# sourceMappingURL=ellipsize.d.ts.map

package/dist/util/ellipsize.js

@@ -0,0 +1,5 @@
+/** `text` cut to `max` characters plus a marker, or unchanged when it already fits. */
+export function truncateWithEllipsis(text, max, marker = '...') {
+    return text.length > max ? `${text.slice(0, max)}${marker}` : text;
+}
+//# sourceMappingURL=ellipsize.js.map

package/dist/util/env.d.ts

@@ -28,10 +28,13 @@ 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;
+export declare function envSkipSchedule(): boolean;
 export declare function envMcpStdio(): boolean;
 /** `1` or `true`, so `0` and `false` turn it off; `true` stays on for anyone who set it that way. */
 export declare function envRequireServer(): boolean;
@@ -44,12 +47,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; util/request-scope.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 +75,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 +91,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,13 +71,16 @@ 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'); }
 export function envSkipPostinstall() { return isOne('HIPPO_SKIP_POSTINSTALL'); }
+export function envSkipSchedule() { return isOne('HIPPO_SKIP_SCHEDULE'); }
 export function envMcpStdio() { return isOne('HIPPO_MCP_STDIO'); }
 /** `1` or `true`, so `0` and `false` turn it off; `true` stays on for anyone who set it that way. */
 export function envRequireServer() { return isOneOrTrue('HIPPO_REQUIRE_SERVER'); }
@@ -91,12 +94,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; util/request-scope.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 +123,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 +140,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/format.d.ts

@@ -0,0 +1,3 @@
+/** A 0..1 fraction as a percentage with one decimal, e.g. 0.256 -> "25.6%". */
+export declare function pct(fraction: number): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/util/format.js

@@ -0,0 +1,6 @@
+// Number-to-text helpers shared by report and eval output.
+/** A 0..1 fraction as a percentage with one decimal, e.g. 0.256 -> "25.6%". */
+export function pct(fraction) {
+    return (fraction * 100).toFixed(1) + '%';
+}
+//# sourceMappingURL=format.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/hook-payload.d.ts

@@ -0,0 +1,8 @@
+/** A hook payload's non-empty `session_id`, or null; with `requiredSource`, also null when its `source` differs. */
+export declare function hookPayloadSessionId(stdinText: string | undefined, requiredSource?: string | null): string | null;
+/** A hook payload's string `field` as sent, or null when the payload or the field is missing or not a string. */
+export declare function hookPayloadString(stdinText: string | undefined, field: string): string | null;
+/** Whether a hook fired inside a sub-agent, the only payload with `agent_id` (https://code.claude.com/docs/en/hooks#common-input-fields).
+ *  Its `session_id` is the parent's, so a sub-agent's blocks and compactions must not count as the parent's. */
+export declare function isSubagentPayload(stdinText: string | undefined): boolean;
+//# sourceMappingURL=hook-payload.d.ts.map

package/dist/util/hook-payload.js

@@ -0,0 +1,37 @@
+import { isJsonObjectLiteral, isJsonString } from './json.js';
+/** A Claude Code hook payload on stdin as a JSON object; null when empty, malformed or not an object. */
+function parseHookPayload(stdinText) {
+    if (!stdinText || stdinText.trim() === '')
+        return null;
+    try {
+        // SAFETY: JSON.parse returns a JSON value by definition.
+        const payload = JSON.parse(stdinText.trim());
+        return isJsonObjectLiteral(payload) ? payload : null;
+    }
+    catch {
+        // Malformed is one of the null cases the docblock names.
+        return null;
+    }
+}
+/** A hook payload's non-empty `session_id`, or null; with `requiredSource`, also null when its `source` differs. */
+export function hookPayloadSessionId(stdinText, requiredSource = null) {
+    const payload = parseHookPayload(stdinText);
+    const sessionId = payload?.session_id;
+    if (!payload || !isJsonString(sessionId) || sessionId.trim() === '')
+        return null;
+    if (requiredSource !== null && payload.source !== requiredSource)
+        return null;
+    return sessionId;
+}
+/** A hook payload's string `field` as sent, or null when the payload or the field is missing or not a string. */
+export function hookPayloadString(stdinText, field) {
+    const value = parseHookPayload(stdinText)?.[field];
+    return isJsonString(value) ? value : null;
+}
+/** Whether a hook fired inside a sub-agent, the only payload with `agent_id` (https://code.claude.com/docs/en/hooks#common-input-fields).
+ *  Its `session_id` is the parent's, so a sub-agent's blocks and compactions must not count as the parent's. */
+export function isSubagentPayload(stdinText) {
+    const agentId = parseHookPayload(stdinText)?.agent_id;
+    return isJsonString(agentId) && agentId.trim() !== '';
+}
+//# sourceMappingURL=hook-payload.js.map

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

@@ -4,6 +4,8 @@ export interface RetryPolicy {
     timeoutMs: number;
     /** Total attempts including the first. */
     attempts?: number;
+    /** Limit on the whole call, waits included: an attempt is cut short at it and no retry starts whose wait would reach it. */
+    totalMs?: number;
     baseDelayMs?: number;
     /** A Retry-After longer than this hands the response back, so a caller with its own long pause keeps it. */
     maxDelayMs?: number;
@@ -12,16 +14,22 @@ 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;
+    /** Replaces the clock `totalMs` is measured on. */
+    now?: () => number;
 }
 /** LLM calls (consolidation refine, DAG summaries, fact extraction) share one budget; `HIPPO_LLM_TIMEOUT_MS` overrides it. */
 export declare function llmTimeoutMs(): number;
+/** One LLM call with its retries: two full attempts and the longest wait between them, where three slow failures would hold a sleep for 3x the timeout. */
+export declare function llmTotalMs(): number;
 export declare function isRetryableStatus(status: number): boolean;
 /** Retry-After as milliseconds: delta-seconds or an HTTP date; null when absent or unreadable. */
 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

@@ -1,13 +1,19 @@
 /** One retry policy for outbound HTTP: a timeout on every attempt, backoff on 429 and 5xx, and on a dropped connection where a replay is safe. */
+import { MINUTE_MS } from './time.js';
 import { envLlmTimeoutMs } from './env.js';
+import { errorCode, errorFields, log } from './log.js';
 const DEFAULT_ATTEMPTS = 3;
 const DEFAULT_BASE_DELAY_MS = 250;
 const DEFAULT_MAX_DELAY_MS = 8_000;
-const DEFAULT_LLM_TIMEOUT_MS = 60_000;
+const DEFAULT_LLM_TIMEOUT_MS = MINUTE_MS;
 /** LLM calls (consolidation refine, DAG summaries, fact extraction) share one budget; `HIPPO_LLM_TIMEOUT_MS` overrides it. */
 export function llmTimeoutMs() {
     return envLlmTimeoutMs() ?? DEFAULT_LLM_TIMEOUT_MS;
 }
+/** One LLM call with its retries: two full attempts and the longest wait between them, where three slow failures would hold a sleep for 3x the timeout. */
+export function llmTotalMs() {
+    return 2 * llmTimeoutMs() + DEFAULT_MAX_DELAY_MS;
+}
 export function isRetryableStatus(status) {
     return status === 429 || (status >= 500 && status <= 599);
 }
@@ -39,24 +45,64 @@ 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. */
+/** Host plus pathname only: a query string can carry a key. */
+function redactedTarget(url) {
+    try {
+        const u = new URL(url);
+        return `${u.host}${u.pathname}`;
+    }
+    catch {
+        return 'unparseable-url';
+    }
+}
+function logRetry(init, url, reason, attempt, attempts, delayMs) {
+    // Debug: an attempt that may still succeed is not a warning, and the caller reports the final failure.
+    log.debug('http retry', {
+        method: (init.method ?? 'GET').toUpperCase(), target: redactedTarget(url), reason, attempt: `${attempt}/${attempts}`, delayMs: Math.round(delayMs),
+    });
+}
+// `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);
+    const now = policy.now ?? Date.now;
+    const deadline = policy.totalMs === undefined ? Infinity : now() + policy.totalMs;
+    const fitsBudget = (delayMs) => now() + delayMs < deadline;
     // Jitter over the upper half keeps parallel callers from retrying in lockstep.
     const backoffMs = (attempt) => {
         const ceiling = Math.min(maxDelayMs, baseDelayMs * 2 ** (attempt - 1));
         return ceiling / 2 + random() * (ceiling / 2);
     };
     for (let attempt = 1;; attempt++) {
-        const timeout = AbortSignal.timeout(policy.timeoutMs);
+        const timeout = AbortSignal.timeout(Math.max(1, Math.min(policy.timeoutMs, deadline - now())));
         const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
         let res;
         try {
@@ -66,7 +112,11 @@ 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));
+            const delay = backoffMs(attempt);
+            if (!fitsBudget(delay))
+                throw err;
+            logRetry(init, url, errorCode(err) || (err instanceof Error ? err.name : 'transport'), attempt, attempts, delay);
+            await backoffWait(delay, policy.sleep, init.signal);
             continue;
         }
         if (!retryOn(res) || attempt >= attempts)
@@ -74,9 +124,18 @@ export async function fetchWithRetry(url, init, policy) {
         const retryAfter = parseRetryAfterMs(res.headers.get('retry-after'));
         if (retryAfter !== null && retryAfter > maxDelayMs)
             return res;
+        const delay = retryAfter ?? backoffMs(attempt);
+        if (!fitsBudget(delay))
+            return res;
         // Frees the pooled socket before the next attempt.
-        await res.body?.cancel();
-        await sleep(retryAfter ?? backoffMs(attempt));
+        try {
+            await res.body?.cancel();
+        }
+        catch (err) {
+            log.debug('http retry: body cancel failed', errorFields(err));
+        }
+        logRetry(init, url, `status ${res.status}`, attempt, attempts, delay);
+        await backoffWait(delay, policy.sleep, init.signal);
     }
 }
 //# sourceMappingURL=http-retry.js.map

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

@@ -1,7 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 export declare function isHeaderString(value: string | string[] | undefined): value is string;
 export declare const MAX_BODY_BYTES: number;
-export declare const MAX_ID_LEN = 256;
 export declare const JSON_HEADERS: {
     readonly 'content-type': "application/json";
 };
@@ -21,16 +20,9 @@ export declare class BodyTooLargeError extends Error {
 /** The body did not arrive in time. Its own class so mapApiError answers 408 and the server drops the socket. */
 export declare class BodyTimeoutError extends Error {
 }
-/** The status and client-facing message for one failed request. */
-export interface ApiErrorReply {
-    status: number;
-    message: string;
-}
 export declare const INTERNAL_ERROR_MESSAGE = "internal server error";
 /** The reply when a request under another store reaches code that still opens hippo.db. */
 export declare const STORE_NOT_PORTED_MESSAGE = "store_not_ported";
-/** Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server log. */
-export declare function mapApiError<E>(err: E): ApiErrorReply;
 /** Serialises before the head goes out, so a body that is not JSON still reaches the caller's error reply. */
 export declare function sendJson<T>(res: ServerResponse, status: number, body: T): void;
 /** How long any route waits for a request body, so a client that sends headers and then stalls cannot hold a request open: 30 s, or HIPPO_BODY_TIMEOUT_MS. */