hippo-memory 1.69.0 → 1.71.0

package/dist/cli/card.js

@@ -1,11 +1,13 @@
 // The `hippo card` verb (the agent work board); main() loads it lazily from the command table.
-import { createCard, loadCard, listCards, loadCardRuns, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, } from '../store-cards.js';
-import { isHandoffOutcome } from '../handoff.js';
-import { isCardStatus } from '../card.js';
-import { loadCardDetail } from '../card-detail.js';
-import { resolveTenantId } from '../tenant.js';
+import { createCard, loadCard, listCards, loadCardRuns, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, } from '../store/cards.js';
+import { isHandoffOutcome } from '../core/handoff.js';
+import { isCardStatus } from '../core/card.js';
+import { loadCardDetail } from '../store/card-detail.js';
 import { printError } from './output.js';
-import { requireInit, cardStringFlag } from './shared.js';
+import { stringFlagOrExit } from './flag-values.js';
+import { requireInit } from './shared.js';
+import { errorMessage } from '../util/log.js';
+import { CliExit } from './exit.js';
 // Mirrors ARCHIVE_REASON_REQUIRED so the block message can't drift from its usage line.
 const CARD_BLOCK_REASON_REQUIRED = 'hippo card block <id> requires --reason "<why>" (recorded as a comment).';
 function printCard(detail) {
@@ -51,13 +53,13 @@ function printCard(detail) {
 }
 // A too-large --run would silently round to a different id (mirrors parsePositiveIncidentId).
 function cardRunFlag(flags) {
-    const raw = cardStringFlag(flags, 'run');
+    const raw = stringFlagOrExit(flags, 'run');
     if (raw === undefined)
         return undefined;
     const n = Number(raw);
     if (!/^\d+$/.test(raw) || !Number.isSafeInteger(n) || n <= 0) {
         printError(`Invalid --run: "${raw}" (expected a positive integer).`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return n;
 }
@@ -80,13 +82,12 @@ const CARD_SUBCOMMAND_FLAGS = {
     comment: ['body', 'author'],
 };
 /** Runs `hippo card <subcommand>`: rejects flags the subcommand never reads, then hands off to its handler. */
-export function cmdCard(hippoRoot, args, flags) {
+export function handleCard({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
-    const tenantId = resolveTenantId({});
     const subcommand = args[0] ?? '';
     if (!Object.hasOwn(CARD_SUBCOMMAND_FLAGS, subcommand)) {
         printError('Usage: hippo card <create|show|list|claim|heartbeat|block|review|complete|reclaim|comment>');
-        process.exit(1);
+        throw new CliExit(1);
     }
     // SAFETY: hasOwn, unlike `in`, skips inherited keys such as constructor, so subcommand is a real key.
     const known = subcommand;
@@ -95,32 +96,32 @@ export function cmdCard(hippoRoot, args, flags) {
         if (!allowedFlags.includes(key)) {
             const valid = allowedFlags.length > 0 ? allowedFlags.map((f) => `--${f}`).join(', ') : '(none)';
             printError(`Unknown flag --${key} for hippo card ${subcommand}. Valid flags: ${valid}`);
-            process.exit(1);
+            throw new CliExit(1);
         }
     }
     CARD_HANDLERS[known](hippoRoot, tenantId, args, flags);
 }
 function cardCreate(hippoRoot, tenantId, _args, flags) {
-    const title = cardStringFlag(flags, 'title') ?? '';
+    const title = stringFlagOrExit(flags, 'title') ?? '';
     if (!title) {
         printError('Usage: hippo card create --title "..." [--repo <name>] [--contract <text>] [--budget <n>] [--depends-on <id>...]');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const repo = cardStringFlag(flags, 'repo') || undefined;
-    const contract = cardStringFlag(flags, 'contract') || undefined;
-    const budgetRaw = cardStringFlag(flags, 'budget');
+    const repo = stringFlagOrExit(flags, 'repo') || undefined;
+    const contract = stringFlagOrExit(flags, 'contract') || undefined;
+    const budgetRaw = stringFlagOrExit(flags, 'budget');
     let budget;
     if (budgetRaw !== undefined) {
         if (!/^\d+$/.test(budgetRaw)) {
             printError(`Invalid budget: "${budgetRaw}" (expected a positive integer)`);
-            process.exit(1);
+            throw new CliExit(1);
         }
         budget = Number(budgetRaw);
     }
     const dependsOnFlag = flags['depends-on'];
     if (dependsOnFlag === true) {
         printError('--depends-on requires a value');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const dependsOn = Array.isArray(dependsOnFlag) ? dependsOnFlag : [];
     let card;
@@ -128,8 +129,8 @@ function cardCreate(hippoRoot, tenantId, _args, flags) {
         card = createCard(hippoRoot, tenantId, { title, repo, contract, budget, dependsOn });
     }
     catch (error) {
-        printError(error instanceof Error ? error.message : String(error));
-        process.exit(1);
+        printError(errorMessage(error));
+        throw new CliExit(1);
     }
     console.log(`Created card ${card.id} (status: ${card.status})`);
 }
@@ -137,12 +138,12 @@ function cardShow(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     if (!id) {
         printError('Usage: hippo card show <id> [--json]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const detail = loadCardDetail(hippoRoot, tenantId, id);
     if (!detail) {
         printError(`No card found with id ${id}.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (flags['json']) {
         console.log(JSON.stringify(detail, null, 2));
@@ -151,10 +152,10 @@ function cardShow(hippoRoot, tenantId, args, flags) {
     printCard(detail);
 }
 function cardList(hippoRoot, tenantId, _args, flags) {
-    const status = cardStringFlag(flags, 'status');
+    const status = stringFlagOrExit(flags, 'status');
     if (status !== undefined && !isCardStatus(status)) {
         printError(`Invalid status: "${status}".`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const cards = listCards(hippoRoot, tenantId, { status });
     if (flags['json']) {
@@ -171,23 +172,23 @@ function cardList(hippoRoot, tenantId, _args, flags) {
 }
 function cardClaim(hippoRoot, tenantId, args, flags) {
     const id = args[1];
-    const runtime = cardStringFlag(flags, 'runtime') ?? '';
+    const runtime = stringFlagOrExit(flags, 'runtime') ?? '';
     if (!id || !runtime) {
         printError('Usage: hippo card claim <id> --runtime <name> [--session <id>]');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const sessionId = cardStringFlag(flags, 'session') || undefined;
+    const sessionId = stringFlagOrExit(flags, 'session') || undefined;
     let card;
     try {
         card = claimCard(hippoRoot, tenantId, id, runtime, sessionId);
     }
     catch (error) {
-        printError(error instanceof Error ? error.message : String(error));
-        process.exit(1);
+        printError(errorMessage(error));
+        throw new CliExit(1);
     }
     if (!card) {
         printError(`Could not claim card ${id} (not ready/blocked, or already claimed).`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     console.log(`Claimed card ${card.id} for ${runtime} (run ${card.runId}, lease until ${card.leaseUntil})`);
 }
@@ -196,28 +197,28 @@ function cardHeartbeat(hippoRoot, tenantId, args, flags) {
     const runId = cardRunFlag(flags);
     if (!id || runId === undefined) {
         printError('Usage: hippo card heartbeat <id> --run <n>');
-        process.exit(1);
+        throw new CliExit(1);
     }
     let card;
     try {
         card = heartbeatCard(hippoRoot, tenantId, id, runId);
     }
     catch (error) {
-        printError(error instanceof Error ? error.message : String(error));
-        process.exit(1);
+        printError(errorMessage(error));
+        throw new CliExit(1);
     }
     if (!card) {
         printError(`Could not heartbeat card ${id} (${cardRefusal(hippoRoot, tenantId, id)}).`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     console.log(`Heartbeat card ${card.id}: lease until ${card.leaseUntil}`);
 }
 function cardBlock(hippoRoot, tenantId, args, flags) {
     const id = args[1];
-    const reason = cardStringFlag(flags, 'reason') ?? '';
+    const reason = stringFlagOrExit(flags, 'reason') ?? '';
     if (!id || !reason) {
         printError(CARD_BLOCK_REASON_REQUIRED);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const runId = cardRunFlag(flags);
     let card;
@@ -225,13 +226,13 @@ function cardBlock(hippoRoot, tenantId, args, flags) {
         card = blockCard(hippoRoot, tenantId, id, reason, runId);
     }
     catch (error) {
-        printError(error instanceof Error ? error.message : String(error));
-        process.exit(1);
+        printError(errorMessage(error));
+        throw new CliExit(1);
     }
     if (!card) {
         const why = runId === undefined ? 'not running' : cardRefusal(hippoRoot, tenantId, id);
         printError(`Could not block card ${id} (${why}).`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     console.log(`Blocked card ${card.id}`);
 }
@@ -239,7 +240,7 @@ function cardReview(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     if (!id) {
         printError('Usage: hippo card review <id> [--run <n>]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const runId = cardRunFlag(flags);
     let card;
@@ -247,13 +248,13 @@ function cardReview(hippoRoot, tenantId, args, flags) {
         card = reviewCard(hippoRoot, tenantId, id, runId);
     }
     catch (error) {
-        printError(error instanceof Error ? error.message : String(error));
-        process.exit(1);
+        printError(errorMessage(error));
+        throw new CliExit(1);
     }
     if (!card) {
         const why = runId === undefined ? 'not running' : cardRefusal(hippoRoot, tenantId, id);
         printError(`Could not move card ${id} to review (${why}).`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     console.log(`Card ${card.id} moved to review`);
 }
@@ -262,7 +263,7 @@ function cardComplete(hippoRoot, tenantId, args, flags) {
     const outcomeRaw = flags['outcome'];
     if (!id || !isHandoffOutcome(outcomeRaw)) {
         printError('Usage: hippo card complete <id> --outcome <success|failure|partial> [--run <n>]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const runId = cardRunFlag(flags);
     let result;
@@ -270,13 +271,13 @@ function cardComplete(hippoRoot, tenantId, args, flags) {
         result = completeCard(hippoRoot, tenantId, id, outcomeRaw, runId);
     }
     catch (error) {
-        printError(error instanceof Error ? error.message : String(error));
-        process.exit(1);
+        printError(errorMessage(error));
+        throw new CliExit(1);
     }
     if (!result) {
         const why = runId === undefined ? 'not in review' : cardRefusal(hippoRoot, tenantId, id);
         printError(`Could not complete card ${id} (${why}).`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     console.log(`Completed card ${result.card.id} (status: ${result.card.status})`);
     if (result.promotedChildren.length > 0) {
@@ -286,7 +287,7 @@ function cardComplete(hippoRoot, tenantId, args, flags) {
 function cardReclaim(hippoRoot, tenantId, args) {
     if (args.length > 1) {
         printError('Usage: hippo card reclaim (sweeps every expired lease; use hippo card block <id> for one card)');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const ids = reclaimExpiredCards(hippoRoot, tenantId);
     if (ids.length === 0) {
@@ -301,20 +302,20 @@ function cardComment(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     if (!id) {
         printError('Usage: hippo card comment <id> --body "..." [--author <name>]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     // Only show and comment look the card up directly; claim/heartbeat/block/review/complete throw from the store instead.
     const card = loadCard(hippoRoot, tenantId, id);
     if (!card) {
         printError(`No card found with id ${id}.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const body = cardStringFlag(flags, 'body') ?? '';
+    const body = stringFlagOrExit(flags, 'body') ?? '';
     if (!body) {
         printError('Usage: hippo card comment <id> --body "..." [--author <name>]');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const author = cardStringFlag(flags, 'author') || 'cli';
+    const author = stringFlagOrExit(flags, 'author') || 'cli';
     const comment = addCardComment(hippoRoot, tenantId, id, author, body);
     console.log(`Added comment ${comment.id} to card ${id}`);
 }

package/dist/cli/client.d.ts

@@ -0,0 +1,28 @@
+/** HTTP client wrapper for `hippo serve`: only the routed writes (remember, forget, archive, promote); every other command opens the store directly.
+ * Server errors rethrow with the message verbatim so CLI substring matches still work; network errors propagate as the native fetch failure. */
+import type { RememberOpts, RememberResult } from '../api/index.js';
+/** An error the server answered with, not one the transport raised: the refused-connection classifier sniffs message text,
+ *  and a server message quotes the caller's own id or content back verbatim. */
+export declare class HttpResponseError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare function remember(serverUrl: string, apiKey: string | undefined, opts: RememberOpts): Promise<RememberResult>;
+export declare function forget(serverUrl: string, apiKey: string | undefined, id: string): Promise<{
+    ok: true;
+    id: string;
+}>;
+export declare function promote(serverUrl: string, apiKey: string | undefined, id: string): Promise<{
+    ok: true;
+    sourceId: string;
+    globalId: string;
+}>;
+export declare function archiveRaw(serverUrl: string, apiKey: string | undefined, id: string, reason: string): Promise<{
+    ok: true;
+    archivedAt: string;
+}>;
+/** 'never-sent': connection never opened, safe to replay locally. 'delivery-unknown': the request was on the wire and may have
+ * committed, so never replay a write. 'none': not a transport failure. */
+export type TransportFailure = 'none' | 'never-sent' | 'delivery-unknown';
+export declare function classifyTransportFailure(err: Error): TransportFailure;
+//# sourceMappingURL=client.d.ts.map

package/dist/{client.js → cli/client.js}

@@ -1,23 +1,14 @@
-/**
- * HTTP client wrapper for `hippo serve`.
- *
- * Only the writes the CLI routes (remember, forget, archive, promote), which are
- * also all HIPPO_REQUIRE_SERVER covers; every other command opens the store
- * directly. Each call returns the same shape that api.ts would.
- *
- * Errors from the server (4xx/5xx) are mapped back into thrown Errors with
- * the server's `error` message preserved verbatim so existing CLI handlers
- * that match on substrings (e.g. "not found", "already superseded") still
- * work unchanged.
- *
- * Network errors (ECONNREFUSED on a stale pidfile, etc.) propagate as the
- * native fetch failure so the caller can detect them and self-heal.
- */
-import { fetchWithRetry } from './http-retry.js';
+/** HTTP client wrapper for `hippo serve`: only the routed writes (remember, forget, archive, promote); every other command opens the store directly.
+ * Server errors rethrow with the message verbatim so CLI substring matches still work; network errors propagate as the native fetch failure. */
+import { fetchWithRetry } from '../util/http-retry.js';
+import { readCappedJson } from '../util/capped-json.js';
+import { isJsonObject, isJsonString } from '../util/json.js';
 /** A write the local server has not answered in this long is stuck; the caller treats it as delivery-unknown. */
 const SERVER_TIMEOUT_MS = 30_000;
 /** Five tries at the server's 1 s Retry-After keeps the roughly 5 s wait the CLI had before the server answered busy with 503. */
 const STORE_BUSY_ATTEMPTS = 5;
+/** Every routed write answers with a few short fields; the pidfile's port may now be another process, so cap what it sends. */
+const MAX_REPLY_BYTES = 1024 * 1024;
 /** The server sets Retry-After on a 503 only for a held write lock (server.ts replyFor); the auth-provider 503 has none. */
 function isStoreBusy(res) {
     return res.status === 503 && res.headers.has('retry-after');
@@ -34,12 +25,8 @@ function buildHeaders(apiKey, withBody) {
         headers['authorization'] = `Bearer ${apiKey}`;
     return headers;
 }
-function isNonEmptyString(value) {
-    return typeof value === 'string' && value.length > 0;
-}
-/** An error the server answered with, not one the transport raised. The
- *  refused-connection classifier sniffs message text, and a server message
- *  quotes the caller's own id or content back verbatim. */
+/** An error the server answered with, not one the transport raised: the refused-connection classifier sniffs message text,
+ *  and a server message quotes the caller's own id or content back verbatim. */
 export class HttpResponseError extends Error {
     status;
     constructor(message, status) {
@@ -48,25 +35,26 @@ export class HttpResponseError extends Error {
         this.name = 'HttpResponseError';
     }
 }
-/**
- * Throw an Error matching the server's error message. Keeps message strings
- * intact so cli.ts handlers can match on the same substrings ("not found",
- * "already superseded", "Unknown key_id") whether the call went through
- * api.ts or client.ts.
- */
+/** Throw an Error carrying the server's message verbatim, so cli.ts handlers can match the same substrings
+ * ("not found", "already superseded") as on the direct path. */
 async function throwForStatus(res) {
     let message = `${res.status} ${res.statusText}`;
     try {
-        const body = await res.json();
-        if (body && isNonEmptyString(body.error)) {
+        const body = await readCappedJson(res, MAX_REPLY_BYTES);
+        if (isJsonObject(body) && isJsonString(body.error) && body.error.length > 0) {
             message = body.error;
         }
     }
     catch {
-        // body wasn't JSON; fall back to status line.
+        // body wasn't JSON or ran past the cap; fall back to status line.
     }
     throw new HttpResponseError(message, res.status);
 }
+/** A 2xx reply's body, read under the cap. */
+async function readReply(res) {
+    // SAFETY: the reply comes from hippo's own server, whose route returns this api result as JSON.
+    return (await readCappedJson(res, MAX_REPLY_BYTES));
+}
 export async function remember(serverUrl, apiKey, opts) {
     const res = await sendWrite(`${serverUrl}/v1/memories`, {
         method: 'POST',
@@ -75,8 +63,7 @@ export async function remember(serverUrl, apiKey, opts) {
     });
     if (!res.ok)
         await throwForStatus(res);
-    const result = await res.json();
-    return result;
+    return readReply(res);
 }
 export async function forget(serverUrl, apiKey, id) {
     const res = await sendWrite(`${serverUrl}/v1/memories/${encodeURIComponent(id)}`, {
@@ -85,8 +72,7 @@ export async function forget(serverUrl, apiKey, id) {
     });
     if (!res.ok)
         await throwForStatus(res);
-    const result = await res.json();
-    return result;
+    return readReply(res);
 }
 export async function promote(serverUrl, apiKey, id) {
     const res = await sendWrite(`${serverUrl}/v1/memories/${encodeURIComponent(id)}/promote`, {
@@ -95,8 +81,7 @@ export async function promote(serverUrl, apiKey, id) {
     });
     if (!res.ok)
         await throwForStatus(res);
-    const result = await res.json();
-    return result;
+    return readReply(res);
 }
 export async function archiveRaw(serverUrl, apiKey, id, reason) {
     const res = await sendWrite(`${serverUrl}/v1/memories/${encodeURIComponent(id)}/archive`, {
@@ -106,18 +91,14 @@ export async function archiveRaw(serverUrl, apiKey, id, reason) {
     });
     if (!res.ok)
         await throwForStatus(res);
-    const result = await res.json();
-    return result;
+    return readReply(res);
 }
 function hasObjectCause(e) {
-    // Node's fs/net system errors (ECONNREFUSED, ECONNRESET) attach the syscall
-    // code on a non-null object `cause`; the strict-equality checks below
-    // validate the code value before it is used for anything.
+    // Node's fs/net system errors (ECONNREFUSED, ECONNRESET) attach the syscall code on a non-null object `cause`;
+    // the strict-equality checks below validate it before use.
     return typeof e.cause === 'object' && e.cause !== null;
 }
 export function classifyTransportFailure(err) {
-    if (!(err instanceof Error))
-        return 'none';
     // The server answered, so the transport worked, whatever the message says.
     if (err instanceof HttpResponseError)
         return 'none';

package/dist/cli/compact-resume-payload.d.ts

@@ -0,0 +1,8 @@
+export interface CompactResumePayload {
+    suppressOutput: boolean;
+    payloadSessionId: string | null;
+    boundary: boolean;
+}
+/** Fail-closed read of the SessionStart payload: only a manual run or a main-session `source: 'compact'` payload may print. */
+export declare function readCompactResumePayload(stdinText: string | undefined, stdinTimedOut: boolean): CompactResumePayload;
+//# sourceMappingURL=compact-resume-payload.d.ts.map

package/dist/cli/compact-resume-payload.js

@@ -0,0 +1,40 @@
+// The payload gate for `hippo compact-resume`.
+import { isSubagentPayload } from '../store/token-ledger.js';
+import { isJsonObject, isJsonString } from '../util/json.js';
+/** Fail-closed read of the SessionStart payload: only a manual run or a main-session `source: 'compact'` payload may print. */
+export function readCompactResumePayload(stdinText, stdinTimedOut) {
+    // An older Claude Code that ignores `matcher: 'compact'` runs this on every SessionStart, so a parsed payload with any other source stays silent.
+    const nonEmptyStdin = !!stdinText && stdinText.trim() !== '';
+    // Without a payload session_id the cross-restore guard can never fire, so a timed-out empty read must not reach the print path.
+    let suppressOutput = stdinTimedOut && !nonEmptyStdin;
+    let payloadSessionId = null;
+    // A boundary is a manual run or a payload that says it follows a compaction; anything else is not one.
+    let boundary = !nonEmptyStdin && !stdinTimedOut;
+    if (nonEmptyStdin) {
+        let payload = null;
+        try {
+            payload = JSON.parse(stdinText.trim());
+        }
+        catch {
+            // Malformed JSON is handled as a null payload by the fail-closed check below.
+            payload = null;
+        }
+        if (!isJsonObject(payload)) {
+            // Fail closed on malformed non-empty stdin; only a TTY/no-stdin manual run, which never reaches here, prints.
+            suppressOutput = true;
+        }
+        else {
+            // Fail closed on structurally incomplete payloads too ({}, [], source missing/non-string): a real SessionStart payload always carries source.
+            // A sub-agent's payload carries its parent's session id, so the mismatch guard would pass and restore the parent's snapshot into it.
+            boundary = payload.source === 'compact';
+            if (payload.source !== 'compact' || isSubagentPayload(stdinText)) {
+                suppressOutput = true;
+            }
+            if (isJsonString(payload.session_id)) {
+                payloadSessionId = payload.session_id;
+            }
+        }
+    }
+    return { suppressOutput, payloadSessionId, boundary };
+}
+//# sourceMappingURL=compact-resume-payload.js.map

package/dist/cli/context.d.ts

@@ -1,15 +1,3 @@
-import { MemoryEntry } from '../memory.js';
-import { type CommandContext } from './shared.js';
-export declare function cmdContext(hippoRoot: string, args: string[], flags: Record<string, string | boolean | string[]>, stdinText?: string): Promise<void>;
-/** @internal Exported for the render snapshot test; not a stable public API. */
-export declare function printContextMarkdown(items: Array<{
-    entry: MemoryEntry;
-    score: number;
-    tokens: number;
-    isGlobal: boolean;
-}>, totalTokens: number, framing?: string, opts?: {
-    showStrength?: boolean;
-    heading?: string;
-}): void;
+import { type CommandContext } from './flag-values.js';
 export declare function handleContext({ hippoRoot, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=context.d.ts.map