hippo-memory 1.72.0 → 2.1.0

package/dist/cli/client.js

@@ -1,22 +1,42 @@
-/** 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. */
+/**
+ * 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';
+import { errorFields, errorMessage, log } from '../util/log.js';
+import { isObjectLike } from '../core/capture-contract.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. */
+/**
+ * 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. */
+/**
+ * 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. */
+/**
+ * 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');
 }
-/** Replaying is safe because each routed write commits in one transaction and anything after it is best-effort, so a busy 503 means
+/**
+ * Replaying is safe because each routed write commits in one transaction and anything after it is best-effort, so a
+ * busy 503 means
  * nothing landed; a sleep is safe too, as a re-run finishes a partial one. */
 function sendWrite(url, init) {
-    return fetchWithRetry(url, init, { timeoutMs: SERVER_TIMEOUT_MS, attempts: STORE_BUSY_ATTEMPTS, retryOn: isStoreBusy });
+    return fetchWithRetry(url, init, {
+        timeoutMs: SERVER_TIMEOUT_MS,
+        attempts: STORE_BUSY_ATTEMPTS,
+        retryOn: isStoreBusy,
+    });
 }
 function buildHeaders(apiKey, withBody) {
     const headers = {};
@@ -26,8 +46,9 @@ function buildHeaders(apiKey, withBody) {
         headers['authorization'] = `Bearer ${apiKey}`;
     return headers;
 }
-/** 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, so the transport classifier can skip it by class.
+ */
 export class HttpResponseError extends Error {
     status;
     constructor(message, status) {
@@ -46,8 +67,9 @@ async function throwForStatus(res) {
             message = body.error;
         }
     }
-    catch {
+    catch (err) {
         // body wasn't JSON or ran past the cap; fall back to status line.
+        log.debug(`server error body unreadable (${errorMessage(err)}); using the status line`, errorFields(err));
     }
     throw new HttpResponseError(message, res.status);
 }
@@ -60,11 +82,15 @@ export class MalformedReplyError extends Error {
         this.name = 'MalformedReplyError';
     }
 }
-/** A 2xx reply's body, read under the cap; it must be a JSON object, and `guard` narrows it further where the shape is known. */
+/**
+ * A 2xx reply's body, read under the cap; it must be a JSON object, and `guard` narrows it further where the shape is
+ * known.
+ */
 async function readReply(res, route, guard) {
     const body = await readCappedJson(res, MAX_REPLY_BYTES);
-    if (!isJsonObject(body))
+    if (!isJsonObject(body)) {
         throw new MalformedReplyError(route, body === null ? 'null' : Array.isArray(body) ? 'array' : 'a scalar');
+    }
     if (guard && !guard(body))
         throw new MalformedReplyError(route, 'unexpected fields');
     const reply = body;
@@ -109,29 +135,33 @@ export async function archiveRaw(serverUrl, apiKey, id, reason) {
         await throwForStatus(res);
     return readReply(res, 'POST /v1/memories/:id/archive', (b) => isJsonString(b.archivedAt));
 }
-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 it before use.
-    return typeof e.cause === 'object' && e.cause !== null;
+/**
+ * The syscall code Node puts on a system error itself (`http` errors) or on the `cause` of a fetch `TypeError`; '' when
+ * there is none.
+ */
+function transportCode(err) {
+    if ('code' in err)
+        return String(err.code);
+    // Node's fetch attaches the syscall code (ECONNREFUSED, ECONNRESET) on a non-null object `cause`.
+    const cause = err.cause;
+    return isObjectLike(cause) && 'code' in cause ? String(cause.code) : '';
 }
 export function classifyTransportFailure(err) {
     // The server answered, so the transport worked, whatever the message says.
     if (err instanceof HttpResponseError)
         return 'none';
-    const message = err.message.toLowerCase();
-    const code = hasObjectCause(err) ? err.cause.code : undefined;
+    const code = transportCode(err);
     // Connect-phase failures: no request bytes ever left the client, so a stale
     // pidfile can be healed and the call replayed on the direct path.
     if (code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'EAI_AGAIN')
         return 'never-sent';
-    if (message.includes('econnrefused'))
-        return 'never-sent';
-    // The socket died mid-exchange. Node fetch surfaces this as a bare
-    // 'fetch failed' with the syscall code on the cause, so check both shapes.
+    // The socket died mid-exchange.
     if (code === 'ECONNRESET' || code === 'ECONNABORTED' || code === 'EPIPE' || code === 'UND_ERR_SOCKET') {
         return 'delivery-unknown';
     }
-    if (message.includes('socket hang up') || message.includes('fetch failed'))
+    // Fetch rejects every network failure as a TypeError, with a cause only when the syscall is known, so no code means
+    // the conservative answer.
+    if (err instanceof TypeError)
         return 'delivery-unknown';
     // The request was sent and the server went quiet, so it may have committed.
     if (err.name === 'TimeoutError')

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

@@ -3,6 +3,9 @@ export interface CompactResumePayload {
     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. */
+/**
+ * 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

@@ -1,11 +1,16 @@
 // The payload gate for `hippo compact-resume`.
 import { isSubagentPayload } from '../util/hook-payload.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. */
+/**
+ * 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.
+    // 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.
+    // 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.
@@ -24,8 +29,10 @@ export function readCompactResumePayload(stdinText, stdinTimedOut) {
             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.
+            // 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;

package/dist/cli/context.js

@@ -3,22 +3,26 @@ import { isSubagentPayload } from '../util/hook-payload.js';
 import { estimateTokens } from '../util/token-text.js';
 import { autoDetectContext } from '../api/context-auto.js';
 import { detectScope } from '../core/active-scope.js';
-import { bookLedgerTurn } from '../api/ledger-db.js';
+import { bookLedgerTurn, ledgerReachOf } from '../api/ledger-db.js';
 import { readHookStdin } from './stdin.js';
 import { isJsonObject, isJsonString } from '../util/json.js';
 import * as api from '../api/index.js';
-import { DEFAULT_CONTEXT_BUDGET } from '../api/context.js';
+import { DEFAULT_CONTEXT_BUDGET, NO_QUERY } from '../api/context.js';
 import { cliApiContext } from './api-context.js';
 import { renderAmbientSummary } from '../core/ambient.js';
 import { contextBlockLines, contextCost, crossProjectLines, settleTokens } from '../api/context-render.js';
 import { additionalContextOutput, flushDeliveryRecorder, hasContextData, startDeliveryRecorder, sessionStartEnvelope, toRenderItems, } from '../api/prompt-hook.js';
-import { parseLimitFlag, parseCountFlag, parseBudgetFlag, flagIsTrue } from './flag-values.js';
+import { parseLimitFlag, parseCountFlag, parseBudgetFlag, flagIsTrue, stringFlagOrExit, } from './flag-values.js';
 import { requireInit } from './shared.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { printActiveTaskSnapshot, printSessionEvents, printHandoff, captureConsole } from './print.js';
-import { hostSessionId, hookStoreRoot, hookRuntime, payloadCwdRoot, runHookWithStores, inPilotHoldout } from './hook-runtime.js';
+import { hostSessionId, hookStoreRoot, hookRuntime, payloadCwdRoot, runHookWithStores, inPilotHoldout, } from './hook-runtime.js';
 async function cmdContext(hippoRoot, tenantId, args, flags, stdinText) {
     const rec = startDeliveryRecorder(cliApiContext(hippoRoot, tenantId), {
-        stdinText, runtime: hookRuntime(flags), eventType: flagIsTrue(flags, 'pinned-only') ? undefined : 'context', envSessionId: hostSessionId(),
+        stdinText,
+        runtime: hookRuntime(flags),
+        eventType: flagIsTrue(flags, 'pinned-only') ? undefined : 'context',
+        envSessionId: hostSessionId(),
     });
     // No try/finally: a render throw keeps its own exit code and writes no event.
     await renderContext(hippoRoot, tenantId, args, flags, stdinText, rec);
@@ -38,13 +42,15 @@ function readHookPayload(stdinText) {
             if (isJsonString(raw))
                 prompt = raw;
         }
-        catch {
+        catch (err) {
             // Malformed/non-JSON stdin: fall through to the env fallback below.
+            log.debug(`context: hook payload is not JSON: ${errorMessage(err)}`, errorFields(err));
         }
     }
     return { sessionId, prompt };
 }
-async function renderContext(hippoRoot, resolvedTenant, args, flags, stdinText, rec) {
+/** Null when this call renders nothing: the pilot holdout arm, or a budget of zero. */
+function contextGate(hippoRoot, resolvedTenant, flags, stdinText, rec) {
     // --pinned-only fires on every prompt, even where no local .hippo exists, so it skips requireInit
     // and api.getContext falls back to global-only.
     const pinnedOnly = flagIsTrue(flags, 'pinned-only');
@@ -52,22 +58,30 @@ async function renderContext(hippoRoot, resolvedTenant, args, flags, stdinText,
         requireInit(hippoRoot);
     }
     const session = resolveContextSession(stdinText);
-    const { currentSessionId, ledgerSessionId, payloadSessionId } = session;
+    const { currentSessionId, payloadSessionId } = session;
     // The pilot arm is booked at the first hook call whatever the flags, so the holdout sees no budget or content branch.
-    if (inPilotHoldout(hippoRoot, resolvedTenant, currentSessionId, payloadSessionId !== undefined)) {
+    if (inPilotHoldout(hippoRoot, resolvedTenant, currentSessionId, { write: payloadSessionId !== undefined })) {
         rec?.disabled();
-        return;
+        return null;
     }
     const budget = parseBudgetFlag(flags['budget'], DEFAULT_CONTEXT_BUDGET);
     if (budget <= 0) {
         rec?.disabled();
-        return;
+        return null;
     }
+    return { pinnedOnly, session, budget };
+}
+async function renderContext(hippoRoot, resolvedTenant, args, flags, stdinText, rec) {
+    const gate = contextGate(hippoRoot, resolvedTenant, flags, stdinText, rec);
+    if (gate === null)
+        return;
+    const { pinnedOnly, session, budget } = gate;
+    const { ledgerSessionId, payloadSessionId } = session;
     // --auto shells out to git, so it stays CLI-side; api.getContext stays host-agnostic and falls back to '*'.
     const query = contextQuery(args, flags);
     const ctx = cliApiContext(hippoRoot, resolvedTenant);
-    const format = String(flags['format'] ?? 'markdown');
-    const framing = String(flags['framing'] ?? 'observe');
+    const format = stringFlagOrExit(flags, 'format') ?? 'markdown';
+    const framing = stringFlagOrExit(flags, 'framing') ?? 'observe';
     const opts = buildContextOpts(flags, { query, budget, pinnedOnly, format, framing, session, rec });
     const result = await api.getContext(ctx, opts);
     if (!hasContextData(result)) {
@@ -75,7 +89,18 @@ async function renderContext(hippoRoot, resolvedTenant, args, flags, stdinText,
         return;
     }
     const envelope = format === 'copilot' ? sessionStartEnvelope(stdinText) : undefined;
-    const view = { hippoRoot, tenantId: ctx.tenantId, ledgerSessionId, payloadSessionId, pinnedOnly, framing, rec, result, envelope };
+    const view = {
+        hippoRoot,
+        tenantId: ctx.tenantId,
+        ledgerSessionId,
+        payloadSessionId,
+        pinnedOnly,
+        framing,
+        rec,
+        result,
+        reach: ledgerReachOf(ctx),
+        envelope,
+    };
     renderContextView(view, format, query);
 }
 function contextQuery(args, flags) {
@@ -110,7 +135,7 @@ function resolveContextSession(stdinText) {
 }
 function buildContextOpts(flags, input) {
     // Scope detection uses cwd, so it is resolved here and passed in via opts.scope.
-    const ctxExplicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
+    const ctxExplicitScope = stringFlagOrExit(flags, 'scope') ?? null;
     const ctxActiveScope = ctxExplicitScope || detectScope();
     // --cross-project re-includes other-project memories, rendered under their own section.
     const crossProject = flagIsTrue(flags, 'cross-project');
@@ -143,7 +168,7 @@ function renderContextJson(view, query) {
         category: r.category ?? null,
     }));
     const jsonText = JSON.stringify({
-        query: query || '*',
+        query: query || NO_QUERY,
         activeSnapshot: result.activeSnapshot ?? null,
         sessionHandoff: result.sessionHandoff ?? null,
         recentSessionEvents: result.recentEvents ?? [],
@@ -158,7 +183,7 @@ function renderContextJson(view, query) {
                 event: 'inject', items: output.length, tokens: estimateTokens(jsonText),
             }],
         delivery: (write) => flushDeliveryRecorder(rec, write),
-    });
+    }, view.reach);
 }
 /** The default format; the header figure counts the whole block, sections included, as the ledger does. */
 function renderContextMarkdown(view) {
@@ -193,7 +218,7 @@ function renderContextMarkdown(view) {
                 event: 'inject', items: renderItems.length, tokens: estimateTokens(text),
             }],
         delivery: (write) => flushDeliveryRecorder(rec, write),
-    });
+    }, view.reach);
 }
 function printCrossProjectSection(items) {
     for (const line of crossProjectLines(items))

package/dist/cli/continuity.d.ts

@@ -1,7 +1,7 @@
 import { type CommandContext } from './flag-values.js';
-export declare function handleSnapshot({ hippoRoot, tenantId, args, flags }: CommandContext): void;
-export declare function handleSession({ hippoRoot, tenantId, args, flags }: CommandContext): void;
-export declare function handleHandoff({ hippoRoot, tenantId, args, flags }: CommandContext): void;
-export declare function handleCurrent({ hippoRoot, tenantId, args, flags }: CommandContext): void;
-export declare function handleWm({ hippoRoot, tenantId, args, flags }: CommandContext): void;
+export declare function handleSnapshot({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
+export declare function handleSession({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
+export declare function handleHandoff({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
+export declare function handleCurrent({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
+export declare function handleWm({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=continuity.d.ts.map