hippo-memory 1.69.0 → 1.70.0

package/dist/trust/quarantine.js

@@ -0,0 +1,8 @@
+/** 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);
+}
+//# sourceMappingURL=quarantine.js.map

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

@@ -0,0 +1,23 @@
+import { type RejectedValueRow } from '../store/rejection.js';
+import { type AppliedRejection, type LiftedRejection } from '../store/rejected-values.js';
+export interface RejectFlowOpts {
+    hippoRoot: string;
+    tenantId: string;
+    actor: string;
+    reason: string;
+    /** By-id form: reject the CURRENT content of an existing memory. */
+    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. */
+    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. */
+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. */
+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[];
+//# sourceMappingURL=reject-flow.d.ts.map

package/dist/trust/reject-flow.js

@@ -0,0 +1,67 @@
+// The reject, unreject and list flow the CLI verbs and the api functions share: the rules and their wording live here,
+// and src/store/rejected-values.ts runs each one on a single handle.
+import { BadRequestError } from '../core/api-errors.js';
+import { isPersonalScope } from '../store/recall-scope.js';
+import { mergedSuccessor } from '../consolidate/merged-row.js';
+import { normalizeValueForRejection } from '../store/rejection.js';
+import { applyRejection, liftRejection, loadRejectedValues, } from '../store/rejected-values.js';
+function assertRejectOpts(opts) {
+    if (!opts.reason.trim()) {
+        throw new Error('reject requires a non-empty --reason (the tombstone stores no content; reason is its only identity).');
+    }
+    if (opts.memoryId === undefined && opts.value === undefined) {
+        throw new Error('reject requires either a memory id or --value.');
+    }
+    if (opts.memoryId !== undefined && opts.value !== undefined) {
+        // Enforced here, not only in the CLI parser, so a direct api caller passing both
+        // is refused instead of silently getting the memoryId path with `value` ignored.
+        throw new Error('reject accepts either a memory id or --value, not both.');
+    }
+    if (opts.value !== undefined && normalizeValueForRejection(opts.value).length === 0) {
+        // Direct api callers can pass strings the CLI flag parser would have
+        // refused; an empty-normalized tombstone would refuse nothing meaningful
+        // and pollute the listing.
+        throw new Error('reject --value requires non-empty content.');
+    }
+}
+function contentToReject(opts, row) {
+    if (opts.memoryId === undefined)
+        return opts.value;
+    if (!row || row.tenant_id !== opts.tenantId) {
+        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))
+        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. */
+export function rejectValue(opts) {
+    assertRejectOpts(opts);
+    return applyRejection(opts.hippoRoot, {
+        tenantId: opts.tenantId,
+        actor: opts.actor,
+        reason: opts.reason,
+        memoryId: opts.memoryId,
+        textOf: (source) => contentToReject(opts, source),
+        inReach: (scope) => inReach(opts, scope),
+        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. */
+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) {
+        return { status: 'not_found' };
+    }
+    return liftRejection(hippoRoot, tenantId, digestOrPrefix, actor);
+}
+/** `hippo rejections` / `api.listRejections` — list tombstones for a tenant. */
+export function listRejectionsForTenant(hippoRoot, tenantId) {
+    return loadRejectedValues(hippoRoot, tenantId);
+}
+//# sourceMappingURL=reject-flow.js.map

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

@@ -0,0 +1,31 @@
+/** 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;
+    maxTokens: number;
+    prompt: string;
+    /** Injected for tests; defaults to the real fetch. */
+    fetcher?: typeof fetch;
+}
+export type AnthropicMessageFailure = {
+    kind: 'request';
+    message: string;
+} | {
+    kind: 'http';
+    status: number;
+} | {
+    kind: 'unreadable';
+    message: string;
+};
+export type AnthropicMessageResult = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    failure: AnthropicMessageFailure;
+};
+/** The reply's first text block, trimmed (empty when the reply has none); never throws. */
+export declare function sendAnthropicMessage(req: AnthropicMessageRequest): Promise<AnthropicMessageResult>;
+/** The text extraction and DAG summaries hand to their `onError` callback. */
+export declare function describeMessageFailure(failure: AnthropicMessageFailure): string;
+//# sourceMappingURL=anthropic-messages.d.ts.map

package/dist/util/anthropic-messages.js

@@ -0,0 +1,46 @@
+/** The one Anthropic Messages client: sends one user prompt and returns the reply text or a typed failure the caller reacts to. */
+import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
+import { errorMessage } from './log.js';
+const MESSAGES_URL = 'https://api.anthropic.com/v1/messages';
+const API_VERSION = '2023-06-01';
+const DEFAULT_MODEL = 'claude-sonnet-4-6';
+/** The reply's first text block, trimmed (empty when the reply has none); never throws. */
+export async function sendAnthropicMessage(req) {
+    let res;
+    try {
+        res = await fetchWithRetry(MESSAGES_URL, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-api-key': req.apiKey,
+                'anthropic-version': API_VERSION,
+            },
+            body: JSON.stringify({
+                model: req.model ?? DEFAULT_MODEL,
+                max_tokens: req.maxTokens,
+                messages: [{ role: 'user', content: req.prompt }],
+            }),
+        }, { timeoutMs: llmTimeoutMs(), fetchFn: req.fetcher ?? fetch });
+    }
+    catch (err) {
+        return { ok: false, failure: { kind: 'request', message: errorMessage(err) } };
+    }
+    if (!res.ok)
+        return { ok: false, failure: { kind: 'http', status: res.status } };
+    try {
+        const data = await res.json();
+        return { ok: true, text: data.content?.[0]?.text?.trim() ?? '' };
+    }
+    catch (err) {
+        return { ok: false, failure: { kind: 'unreadable', message: errorMessage(err) } };
+    }
+}
+/** The text extraction and DAG summaries hand to their `onError` callback. */
+export function describeMessageFailure(failure) {
+    switch (failure.kind) {
+        case 'request': return `request failed: ${failure.message}`;
+        case 'http': return `HTTP ${failure.status}`;
+        case 'unreadable': return `unparseable response: ${failure.message}`;
+    }
+}
+//# sourceMappingURL=anthropic-messages.js.map

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

@@ -0,0 +1,3 @@
+/** 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. */
+export declare function writeFileAtomic(file: string, text: string): void;
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/util/atomic-write.js

@@ -0,0 +1,107 @@
+// 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';
+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.
+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. */
+function renameOnto(tmp, target) {
+    const deadline = Date.now() + RENAME_RETRY_MS;
+    const idle = new Int32Array(new SharedArrayBuffer(4));
+    for (let pause = 10;; pause = Math.min(pause * 2, 200)) {
+        try {
+            fs.renameSync(tmp, target);
+            return;
+        }
+        catch (err) {
+            const transient = process.platform === 'win32' && err instanceof Error && WINDOWS_RENAME_REFUSALS.includes(errnoCode(err));
+            const left = deadline - Date.now();
+            if (!transient || left <= 0)
+                throw err;
+            Atomics.wait(idle, 0, 0, Math.min(pause, left));
+        }
+    }
+}
+/** 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++) {
+        target = path.resolve(path.dirname(target), fs.readlinkSync(target));
+    }
+    return fs.existsSync(target) ? fs.realpathSync(target) : target;
+}
+/** Gives the replacement the old file's exact mode (umask trims the create mode) and, for root, its owner. */
+function keepAccess(tmp, old) {
+    fs.chmodSync(tmp, old.mode & 0o777);
+    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. */
+function removeTemp(tmp) {
+    try {
+        fs.rmSync(tmp, { force: true });
+    }
+    catch (err) {
+        log.warn(`could not remove the temporary file ${tmp}: ${errorMessage(err)}`);
+    }
+}
+function replaceViaTemp(target, text, old) {
+    const tmp = `${target}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(tmp, text, { encoding: 'utf8', mode: (old?.mode ?? 0o666) & 0o777 });
+        if (old)
+            keepAccess(tmp, old);
+        renameOnto(tmp, target);
+    }
+    catch (err) {
+        removeTemp(tmp);
+        throw err;
+    }
+}
+/** 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');
+    }
+    catch (err) {
+        if (!(err instanceof Error))
+            throw err;
+        const reason = errnoCode(err) === 'EBUSY'
+            ? 'is in use by another program, so hippo could not replace it; close that program and run the command again'
+            : `could not be replaced (${errnoCode(err) || err.message})`;
+        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. */
+export function writeFileAtomic(file, text) {
+    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.
+        fs.accessSync(target, fs.constants.W_OK);
+    }
+    if (old !== undefined && old.nlink > 1) {
+        // A rename gives the file a new inode, which would leave the other hard links on the old content.
+        writeInPlace(target, text);
+        return;
+    }
+    try {
+        replaceViaTemp(target, text, old);
+    }
+    catch (err) {
+        if (!(err instanceof Error) || !REPLACE_REFUSALS.includes(errnoCode(err)))
+            throw err;
+        writeInPlace(target, text);
+    }
+}
+//# sourceMappingURL=atomic-write.js.map

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

@@ -0,0 +1,5 @@
+/** 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;
+/** 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;
+//# sourceMappingURL=crash-handlers.d.ts.map

package/dist/util/crash-handlers.js

@@ -0,0 +1,30 @@
+// 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;
+    let pending = 2;
+    const done = () => { if (--pending === 0)
+        process.exit(code); };
+    process.stdout.write('', done);
+    process.stderr.write('', done);
+    setTimeout(() => process.exit(code), 1000).unref();
+}
+/** 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 = () => { }) {
+    let crashing = false;
+    const crash = (kind, err) => {
+        log.error(`${name} ${kind}: ${errorMessage(err)}`, errorFields(err));
+        // A throw while shutdown runs is logged above and must not start it again.
+        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));
+    };
+    process.on('uncaughtException', (err) => crash('uncaught exception', err));
+    process.on('unhandledRejection', (err) => crash('unhandled rejection', err));
+}
+//# sourceMappingURL=crash-handlers.js.map

package/dist/{env.d.ts → util/env.d.ts}

@@ -12,8 +12,6 @@ export declare function envAblateRecency(): boolean;
 export declare function envEvalRecencyDays(): number | null;
 /** HIPPO_FAKE_NOW as epoch millis, or null unless it is byte-identical to Date.toISOString output. */
 export declare function envFakeNowMs(): number | null;
-export declare function envTestDeliveryFault(): string;
-export declare function envForceLikePath(): boolean;
 export declare function envLossAversionRatio(): string | undefined;
 export declare function envSummaryDeboost(): string | undefined;
 export declare function envAutodebiasOff(): boolean;
@@ -40,14 +38,29 @@ export declare function envRequireServer(): boolean;
 export declare function envRequireSessionScopedFreshTail(): boolean;
 export declare function envStdinWaitMs(): number | undefined;
 export declare function envLogLevel(): string;
+/** `HIPPO_LOG_FORMAT=json` writes each log line as one JSON object; anything else keeps the text line. */
+export declare function envLogJson(): boolean;
 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;
 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. */
+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;
+/** How long the daily runner lets one child `hippo` step run; cli/setup.ts holds the default. */
+export declare function envDailyStepTimeoutMs(): number | undefined;
 export declare function envApiKey(): string | undefined;
 export declare function envClientIpHeader(): string | undefined;
 export declare function envTrustedProxies(): string | undefined;
+/** Paths to the PEM certificate and key `hippo serve` answers HTTPS with; the --tls-cert and --tls-key flags win. */
+export declare function envTlsCert(): string | undefined;
+export declare function envTlsKey(): string | undefined;
 export declare function envMcpSseMaxStreams(): number | undefined;
 export declare function envMcpSseHeartbeatMs(): number | undefined;
 export declare function envMcpSseMaxAgeSec(): number | undefined;

package/dist/{env.js → util/env.js}

@@ -15,6 +15,11 @@ function positiveInt(name) {
     const parsed = Number.parseInt(raw(name) ?? '', 10);
     return parsed > 0 ? parsed : undefined;
 }
+/** parseInt, kept from zero up, for a setting whose 0 means off. */
+function nonNegativeInt(name) {
+    const parsed = Number.parseInt(raw(name) ?? '', 10);
+    return parsed >= 0 ? parsed : undefined;
+}
 /** Trimmed, with an empty or whitespace-only value read as unset. */
 function trimmed(name) {
     return raw(name)?.trim() || undefined;
@@ -48,8 +53,6 @@ export function envFakeNowMs() {
     const parsed = Date.parse(value);
     return Number.isFinite(parsed) && new Date(parsed).toISOString() === value ? parsed : null;
 }
-export function envTestDeliveryFault() { return raw('HIPPO_TEST_DELIVERY_FAULT') ?? ''; }
-export function envForceLikePath() { return isOne('HIPPO_FORCE_LIKE_PATH'); }
 export function envLossAversionRatio() { return raw('HIPPO_LOSS_AVERSION_RATIO'); }
 export function envSummaryDeboost() { return raw('HIPPO_SUMMARY_DEBOOST'); }
 export function envAutodebiasOff() { return raw('HIPPO_AUTODEBIAS') === 'off'; }
@@ -81,15 +84,30 @@ export function envRequireServer() { return isOneOrTrue('HIPPO_REQUIRE_SERVER');
 export function envRequireSessionScopedFreshTail() { return isOne('HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL'); }
 export function envStdinWaitMs() { return positiveInt('HIPPO_STDIN_WAIT_MS'); }
 export function envLogLevel() { return raw('HIPPO_LOG')?.trim().toLowerCase() ?? ''; }
+/** `HIPPO_LOG_FORMAT=json` writes each log line as one JSON object; anything else keeps the text line. */
+export function envLogJson() { return raw('HIPPO_LOG_FORMAT')?.trim().toLowerCase() === 'json'; }
 // Server.
 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'); }
 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. */
+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'); }
+/** How long the daily runner lets one child `hippo` step run; cli/setup.ts holds the default. */
+export function envDailyStepTimeoutMs() { return positiveInt('HIPPO_DAILY_STEP_TIMEOUT_MS'); }
 export function envApiKey() { return raw('HIPPO_API_KEY'); }
 export function envClientIpHeader() { return raw('HIPPO_CLIENT_IP_HEADER')?.trim().toLowerCase(); }
 export function envTrustedProxies() { return raw('HIPPO_TRUSTED_PROXIES'); }
+/** Paths to the PEM certificate and key `hippo serve` answers HTTPS with; the --tls-cert and --tls-key flags win. */
+export function envTlsCert() { return trimmed('HIPPO_TLS_CERT'); }
+export function envTlsKey() { return trimmed('HIPPO_TLS_KEY'); }
 export function envMcpSseMaxStreams() { return positiveInt('MCP_SSE_MAX_STREAMS'); }
 export function envMcpSseHeartbeatMs() { return positiveInt('MCP_SSE_HEARTBEAT_MS'); }
 export function envMcpSseMaxAgeSec() { return positiveInt('MCP_SSE_MAX_AGE_SEC'); }

package/dist/util/home-path.js

@@ -0,0 +1,67 @@
+// Home-directory paths name their user, so text bound for a shared store tests or masks them here; no imports keep it light.
+// 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.
+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}`;
+const LINUX_HOME = String.raw `(?:\/var)?\/home\/[^/\s]+`;
+const ROOT_HOME = String.raw `(?:\/var)?\/root(?![\w.-])`;
+const MAC_HOME = String.raw `\/Users\/[^/\s]+`;
+const DRIVE_HOME = new RegExp(String.raw `[A-Za-z](?::|%3A)${WIN_SEP}+(?:Users|Documents and Settings)${WIN_SEP}+${WIN_USER}`, 'i');
+const LONG_PATH = /\\\\\?\\/;
+const SHARE_HOME = new RegExp(String.raw `\\\\[^\\/\s]+\\+(?:homes?|users|profiles?)\$?\\+${WIN_USER}`, 'i');
+const SHORT_NAME = /[\\/][A-Z0-9_$]{1,6}~\d{1,6}(?:\.[A-Z0-9]{1,3})?(?![\w~])|\b[A-Z0-9_$]{1,6}~\d{1,6}(?:\.[A-Z0-9]{1,3})?[\\/]/;
+// A slash-led home counts only at the start of a path, so each takes a guard against the text before it.
+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. */
+export const USER_SEGMENT = [
+    DRIVE_HOME,
+    new RegExp(MOUNT_START),
+    LONG_PATH,
+    SHARE_HOME,
+    new RegExp(LINUX_START),
+    new RegExp(ROOT_START),
+    new RegExp(MAC_START),
+    SHORT_NAME,
+];
+const MASK = '[home]';
+// Global copies, so the shared test patterns keep their lastIndex at 0.
+const allOf = (re) => new RegExp(re.source, `${re.flags}g`);
+const [DRIVE_HOMES, LONG_PATHS, SHARE_HOMES, SHORT_NAMES] = [DRIVE_HOME, LONG_PATH, SHARE_HOME, SHORT_NAME].map(allOf);
+// A home glued after another starts where a mask will end, which no guard refuses: one match takes the whole run, as masking one a pass costs a pass per home.
+// A run holds only shapes whose own step is not still to come, so a later step meets the same text it would without the run.
+const runFrom = (start, ...glued) => new RegExp(`${start}(?:${glued.join('|')})*`, 'g');
+const MOUNT_RUNS = runFrom(MOUNT_START, MOUNT_HOME);
+const LINUX_RUNS = runFrom(LINUX_START, MOUNT_HOME, LINUX_HOME);
+const ROOT_RUNS = runFrom(ROOT_START, MOUNT_HOME, LINUX_HOME, ROOT_HOME);
+const MAC_RUNS = runFrom(MAC_START, MOUNT_HOME, LINUX_HOME, ROOT_HOME, MAC_HOME);
+const SLASH_HOMES = new RegExp(`${MOUNT_HOME}|${LINUX_HOME}|${ROOT_HOME}|${MAC_HOME}`, 'g');
+const maskRun = (run) => MASK.repeat(run.match(SLASH_HOMES)?.length ?? 1);
+function maskOnce(text) {
+    return text
+        .replace(DRIVE_HOMES, MASK)
+        .replace(MOUNT_RUNS, maskRun)
+        .replace(LONG_PATHS, MASK)
+        .replace(SHARE_HOMES, MASK)
+        .replace(LINUX_RUNS, maskRun)
+        .replace(ROOT_RUNS, maskRun)
+        .replace(MAC_RUNS, maskRun)
+        .replace(SHORT_NAMES, MASK);
+}
+/** `text` with each home-directory segment replaced by `[home]`. */
+export function maskHomePaths(text) {
+    let out = text;
+    let next = maskOnce(out);
+    // A mask can uncover a home path its text was hiding, so passes repeat until one changes nothing; each takes a separator out, so they end.
+    while (next !== out) {
+        out = next;
+        next = maskOnce(out);
+    }
+    return out;
+}
+//# sourceMappingURL=home-path.js.map

package/dist/{http-retry.d.ts → util/http-retry.d.ts}

@@ -1,4 +1,4 @@
-/** One retry policy for outbound HTTP: a timeout on every attempt, and backoff on 429 and 5xx only. */
+/** 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. */
 export interface RetryPolicy {
     /** Per-attempt limit; a stalled peer ends as a thrown `TimeoutError`, never a hang. */
     timeoutMs: number;
@@ -9,6 +9,8 @@ export interface RetryPolicy {
     maxDelayMs?: number;
     /** Which responses to retry; defaults to 429 and 5xx. A write narrows it to answers that prove nothing committed. */
     retryOn?: (res: Response) => boolean;
+    /** 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;
     sleep?: (ms: number) => Promise<void>;
     random?: () => number;
@@ -18,6 +20,8 @@ export declare function llmTimeoutMs(): 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;
-/** `fetch` with a per-attempt timeout and up to `attempts` tries on 429 and 5xx; the last response comes back as is and transport errors throw at once. */
+/** 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. */
 export declare function fetchWithRetry(url: string | URL, init: RequestInit, policy: RetryPolicy): Promise<Response>;
 //# sourceMappingURL=http-retry.d.ts.map

package/dist/{http-retry.js → util/http-retry.js}

@@ -1,4 +1,4 @@
-/** One retry policy for outbound HTTP: a timeout on every attempt, and backoff on 429 and 5xx only. */
+/** 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 { envLlmTimeoutMs } from './env.js';
 const DEFAULT_ATTEMPTS = 3;
 const DEFAULT_BASE_DELAY_MS = 250;
@@ -21,8 +21,26 @@ export function parseRetryAfterMs(header, now = Date.now()) {
     const at = Date.parse(header);
     return Number.isNaN(at) ? null : Math.max(0, at - now);
 }
+// Node's fetch reports a broken socket as a bare `fetch failed` with one of these on its cause.
+const TRANSIENT_CODES = new Set([
+    'ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN', 'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT',
+]);
+/** A dropped connection, a DNS hiccup or a timed-out attempt: faults a second try can clear. A refused connection is not one. */
+export function isTransientTransportError(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (err.name === 'TimeoutError')
+        return true;
+    const holder = err.cause instanceof Object ? err.cause : err;
+    const code = 'code' in holder ? String(holder.code) : '';
+    return TRANSIENT_CODES.has(code) || err.message.toLowerCase().includes('socket hang up');
+}
+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 and 5xx; the last response comes back as is and transport errors throw at once. */
+/** `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);
@@ -31,21 +49,34 @@ export async function fetchWithRetry(url, init, policy) {
     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);
+    // 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 signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
-        const res = await fetchFn(url, { ...init, signal });
+        let res;
+        try {
+            res = await fetchFn(url, { ...init, signal });
+        }
+        catch (err) {
+            // 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));
+            continue;
+        }
         if (!retryOn(res) || attempt >= attempts)
             return res;
         const retryAfter = parseRetryAfterMs(res.headers.get('retry-after'));
         if (retryAfter !== null && retryAfter > maxDelayMs)
             return res;
-        // Jitter over the upper half keeps parallel callers from retrying in lockstep.
-        const ceiling = Math.min(maxDelayMs, baseDelayMs * 2 ** (attempt - 1));
-        const delay = retryAfter ?? ceiling / 2 + random() * (ceiling / 2);
         // Frees the pooled socket before the next attempt.
         await res.body?.cancel();
-        await sleep(delay);
+        await sleep(retryAfter ?? backoffMs(attempt));
     }
 }
 //# sourceMappingURL=http-retry.js.map

package/dist/{http-util.d.ts → util/http-util.d.ts}

@@ -1,7 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { JsonValue } from './json.js';
-export declare function isJsonObjectRecord(value: JsonValue | undefined): value is Record<string, JsonValue>;
 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";
@@ -12,6 +11,11 @@ export declare class HttpError extends Error {
     readonly retryAfterSec: number | undefined;
     constructor(status: number, message: string, retryAfterSec?: number);
 }
+/** A request, or a store call it waited on, ran past the request's deadline; the reply carries `code` so a client branches without parsing prose. */
+export declare class DeadlineExceededError extends HttpError {
+    readonly code = "deadline_exceeded";
+    constructor(message: string);
+}
 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. */
@@ -29,10 +33,12 @@ export declare const STORE_NOT_PORTED_MESSAGE = "store_not_ported";
 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. */
+export declare function bodyDeadlineMs(): number;
 export interface ReadBodyOpts {
     /** Defaults to 1 MB. */
     maxBytes?: number;
-    /** Fails with BodyTimeoutError when the whole body has not arrived by then; unset waits for as long as the socket stays open. */
+    /** Fails with BodyTimeoutError when the whole body has not arrived by then; defaults to bodyDeadlineMs(). */
     deadlineMs?: number;
 }
 /** The body as text, refused mid-stream past maxBytes and past deadlineMs, so an oversized or slow sender cannot tie up the server. */
@@ -47,6 +53,11 @@ export interface WebhookRequest {
     res: ServerResponse;
     opts: {
         hippoRoot: string;
+        webhookBodyDeadlineMs?: number;
     };
 }
+/** Call before refusing a webhook unread: a caller still sending its body loses the socket once the reply is out, as it does after a 413. */
+export declare function closeIfBodyUnread({ req, res }: WebhookRequest): void;
+/** A webhook's raw body, exactly as sent, for the receiver's HMAC check; call it only once a secret is configured and the signature headers are present. */
+export declare function readWebhookBody({ req, opts }: WebhookRequest): Promise<string>;
 //# sourceMappingURL=http-util.d.ts.map