hippo-memory 1.70.0 → 1.72.0

package/dist/cli/card.js

@@ -1,13 +1,28 @@
 // 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 * as cardsApi from '../api/cards.js';
+import { cliApiContext } from './api-context.js';
 import { isHandoffOutcome } from '../core/handoff.js';
 import { isCardStatus } from '../core/card.js';
-import { loadCardDetail } from '../store/card-detail.js';
-import { resolveTenantId } from '../store/tenant.js';
 import { printError } from './output.js';
 import { stringFlagOrExit } from './flag-values.js';
 import { requireInit } from './shared.js';
 import { errorMessage } from '../util/log.js';
+import { CliExit } from './exit.js';
+// Each subcommand's usage line, written once so the repeated checks cannot drift.
+const CARD_USAGE = {
+    create: 'hippo card create --title "..." [--repo <name>] [--contract <text>] [--budget <n>] [--depends-on <id>...]',
+    show: 'hippo card show <id> [--json]',
+    claim: 'hippo card claim <id> --runtime <name> [--session <id>]',
+    heartbeat: 'hippo card heartbeat <id> --run <n>',
+    review: 'hippo card review <id> [--run <n>]',
+    complete: 'hippo card complete <id> --outcome <success|failure|partial> [--run <n>]',
+    reclaim: 'hippo card reclaim (sweeps every expired lease; use hippo card block <id> for one card)',
+    comment: 'hippo card comment <id> --body "..." [--author <name>]',
+};
+function usageError(sub) {
+    printError(`Usage: ${CARD_USAGE[sub]}`);
+    return new CliExit(1);
+}
 // 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) {
@@ -59,14 +74,15 @@ function cardRunFlag(flags) {
     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;
 }
 // Reads after the store already refused, so this only explains the refusal, never changes it.
 function cardRefusal(hippoRoot, tenantId, id) {
-    const card = loadCard(hippoRoot, tenantId, id);
-    const liveRun = loadCardRuns(hippoRoot, tenantId, id).find((r) => !r.ended);
+    const ctx = cliApiContext(hippoRoot, tenantId);
+    const card = cardsApi.cardLoad(ctx, id);
+    const liveRun = cardsApi.cardRuns(ctx, id).find((r) => !r.ended);
     return `status ${card?.status ?? 'unknown'}, live run ${liveRun?.id ?? 'none'}`;
 }
 const CARD_SUBCOMMAND_FLAGS = {
@@ -82,13 +98,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;
@@ -97,7 +112,7 @@ 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);
@@ -105,8 +120,7 @@ export function cmdCard(hippoRoot, args, flags) {
 function cardCreate(hippoRoot, tenantId, _args, flags) {
     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 usageError('create');
     }
     const repo = stringFlagOrExit(flags, 'repo') || undefined;
     const contract = stringFlagOrExit(flags, 'contract') || undefined;
@@ -115,36 +129,35 @@ function cardCreate(hippoRoot, tenantId, _args, flags) {
     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;
     try {
-        card = createCard(hippoRoot, tenantId, { title, repo, contract, budget, dependsOn });
+        card = cardsApi.cardCreate(cliApiContext(hippoRoot, tenantId), { title, repo, contract, budget, dependsOn });
     }
     catch (error) {
         printError(errorMessage(error));
-        process.exit(1);
+        throw new CliExit(1);
     }
     console.log(`Created card ${card.id} (status: ${card.status})`);
 }
 function cardShow(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     if (!id) {
-        printError('Usage: hippo card show <id> [--json]');
-        process.exit(1);
+        throw usageError('show');
     }
-    const detail = loadCardDetail(hippoRoot, tenantId, id);
+    const detail = cardsApi.cardDetail(cliApiContext(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));
@@ -156,9 +169,9 @@ function cardList(hippoRoot, tenantId, _args, flags) {
     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 });
+    const cards = cardsApi.cardList(cliApiContext(hippoRoot, tenantId), { status });
     if (flags['json']) {
         console.log(JSON.stringify({ cards }, null, 2));
         return;
@@ -175,21 +188,20 @@ function cardClaim(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     const runtime = stringFlagOrExit(flags, 'runtime') ?? '';
     if (!id || !runtime) {
-        printError('Usage: hippo card claim <id> --runtime <name> [--session <id>]');
-        process.exit(1);
+        throw usageError('claim');
     }
     const sessionId = stringFlagOrExit(flags, 'session') || undefined;
     let card;
     try {
-        card = claimCard(hippoRoot, tenantId, id, runtime, sessionId);
+        card = cardsApi.cardClaim(cliApiContext(hippoRoot, tenantId), id, runtime, sessionId);
     }
     catch (error) {
         printError(errorMessage(error));
-        process.exit(1);
+        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})`);
 }
@@ -197,20 +209,19 @@ function cardHeartbeat(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     const runId = cardRunFlag(flags);
     if (!id || runId === undefined) {
-        printError('Usage: hippo card heartbeat <id> --run <n>');
-        process.exit(1);
+        throw usageError('heartbeat');
     }
     let card;
     try {
-        card = heartbeatCard(hippoRoot, tenantId, id, runId);
+        card = cardsApi.cardHeartbeat(cliApiContext(hippoRoot, tenantId), id, runId);
     }
     catch (error) {
         printError(errorMessage(error));
-        process.exit(1);
+        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}`);
 }
@@ -219,43 +230,42 @@ function cardBlock(hippoRoot, tenantId, args, flags) {
     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;
     try {
-        card = blockCard(hippoRoot, tenantId, id, reason, runId);
+        card = cardsApi.cardBlock(cliApiContext(hippoRoot, tenantId), id, reason, runId);
     }
     catch (error) {
         printError(errorMessage(error));
-        process.exit(1);
+        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}`);
 }
 function cardReview(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     if (!id) {
-        printError('Usage: hippo card review <id> [--run <n>]');
-        process.exit(1);
+        throw usageError('review');
     }
     const runId = cardRunFlag(flags);
     let card;
     try {
-        card = reviewCard(hippoRoot, tenantId, id, runId);
+        card = cardsApi.cardReview(cliApiContext(hippoRoot, tenantId), id, runId);
     }
     catch (error) {
         printError(errorMessage(error));
-        process.exit(1);
+        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`);
 }
@@ -263,22 +273,21 @@ function cardComplete(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     const outcomeRaw = flags['outcome'];
     if (!id || !isHandoffOutcome(outcomeRaw)) {
-        printError('Usage: hippo card complete <id> --outcome <success|failure|partial> [--run <n>]');
-        process.exit(1);
+        throw usageError('complete');
     }
     const runId = cardRunFlag(flags);
     let result;
     try {
-        result = completeCard(hippoRoot, tenantId, id, outcomeRaw, runId);
+        result = cardsApi.cardComplete(cliApiContext(hippoRoot, tenantId), id, outcomeRaw, runId);
     }
     catch (error) {
         printError(errorMessage(error));
-        process.exit(1);
+        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) {
@@ -287,10 +296,9 @@ 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 usageError('reclaim');
     }
-    const ids = reclaimExpiredCards(hippoRoot, tenantId);
+    const ids = cardsApi.cardReclaimExpired(cliApiContext(hippoRoot, tenantId));
     if (ids.length === 0) {
         console.log('No expired leases.');
         return;
@@ -302,22 +310,21 @@ function cardReclaim(hippoRoot, tenantId, args) {
 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 usageError('comment');
     }
     // 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);
+    const ctx = cliApiContext(hippoRoot, tenantId);
+    const card = cardsApi.cardLoad(ctx, id);
     if (!card) {
         printError(`No card found with id ${id}.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const body = stringFlagOrExit(flags, 'body') ?? '';
     if (!body) {
-        printError('Usage: hippo card comment <id> --body "..." [--author <name>]');
-        process.exit(1);
+        throw usageError('comment');
     }
     const author = stringFlagOrExit(flags, 'author') || 'cli';
-    const comment = addCardComment(hippoRoot, tenantId, id, author, body);
+    const comment = cardsApi.cardComment(ctx, id, author, body);
     console.log(`Added comment ${comment.id} to card ${id}`);
 }
 const CARD_HANDLERS = {

package/dist/cli/client.d.ts

@@ -1,26 +1,17 @@
-/**
- * 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.
- */
+/** 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. */
+/** 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);
 }
+/** A 2xx reply that is not the JSON object the route promises: another process may now own the pidfile's port. */
+export declare class MalformedReplyError extends Error {
+    readonly route: string;
+    constructor(route: string, detail: string);
+}
 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;
@@ -35,14 +26,8 @@ export declare function archiveRaw(serverUrl: string, apiKey: string | undefined
     ok: true;
     archivedAt: string;
 }>;
-/**
- * How far a request got before the transport failed.
- *
- * 'never-sent' means the connection never opened, so the caller may safely
- * replay the call locally. 'delivery-unknown' means the socket broke with the
- * request already on the wire: the server may have committed it, so replaying a
- * write would store it twice. 'none' means this was not a transport failure.
- */
+/** '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: unknown): TransportFailure;
+export declare function classifyTransportFailure(err: Error): TransportFailure;
 //# sourceMappingURL=client.d.ts.map

package/dist/cli/client.js

@@ -1,28 +1,20 @@
-/**
- * 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.
- */
+/** 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');
 }
-/** 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. */
+/** 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 });
 }
@@ -34,12 +26,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 +36,41 @@ 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 that is not the JSON object the route promises: another process may now own the pidfile's port. */
+export class MalformedReplyError extends Error {
+    route;
+    constructor(route, detail) {
+        super(`the hippo server's reply to ${route} was not the expected JSON object (${detail})`);
+        this.route = route;
+        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. */
+async function readReply(res, route, guard) {
+    const body = await readCappedJson(res, MAX_REPLY_BYTES);
+    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;
+    // SAFETY: the reply comes from hippo's own server, whose route returns this api result as JSON.
+    return reply;
+}
 export async function remember(serverUrl, apiKey, opts) {
     const res = await sendWrite(`${serverUrl}/v1/memories`, {
         method: 'POST',
@@ -75,8 +79,7 @@ export async function remember(serverUrl, apiKey, opts) {
     });
     if (!res.ok)
         await throwForStatus(res);
-    const result = await res.json();
-    return result;
+    return readReply(res, 'POST /v1/memories');
 }
 export async function forget(serverUrl, apiKey, id) {
     const res = await sendWrite(`${serverUrl}/v1/memories/${encodeURIComponent(id)}`, {
@@ -85,8 +88,7 @@ export async function forget(serverUrl, apiKey, id) {
     });
     if (!res.ok)
         await throwForStatus(res);
-    const result = await res.json();
-    return result;
+    return readReply(res, 'DELETE /v1/memories/:id', (b) => isJsonString(b.id));
 }
 export async function promote(serverUrl, apiKey, id) {
     const res = await sendWrite(`${serverUrl}/v1/memories/${encodeURIComponent(id)}/promote`, {
@@ -95,8 +97,7 @@ export async function promote(serverUrl, apiKey, id) {
     });
     if (!res.ok)
         await throwForStatus(res);
-    const result = await res.json();
-    return result;
+    return readReply(res, 'POST /v1/memories/:id/promote', (b) => isJsonString(b.sourceId) && isJsonString(b.globalId));
 }
 export async function archiveRaw(serverUrl, apiKey, id, reason) {
     const res = await sendWrite(`${serverUrl}/v1/memories/${encodeURIComponent(id)}/archive`, {
@@ -106,18 +107,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, '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 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.js

@@ -1,5 +1,6 @@
 // The payload gate for `hippo compact-resume`.
-import { isSubagentPayload } from '../store/token-ledger.js';
+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. */
 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.
@@ -18,7 +19,7 @@ export function readCompactResumePayload(stdinText, stdinTimedOut) {
             // Malformed JSON is handled as a null payload by the fail-closed check below.
             payload = null;
         }
-        if (!payload || typeof payload !== 'object') {
+        if (!isJsonObject(payload)) {
             // Fail closed on malformed non-empty stdin; only a TTY/no-stdin manual run, which never reaches here, prints.
             suppressOutput = true;
         }
@@ -29,7 +30,7 @@ export function readCompactResumePayload(stdinText, stdinTimedOut) {
             if (payload.source !== 'compact' || isSubagentPayload(stdinText)) {
                 suppressOutput = true;
             }
-            if (typeof payload.session_id === 'string') {
+            if (isJsonString(payload.session_id)) {
                 payloadSessionId = payload.session_id;
             }
         }

package/dist/cli/context.d.ts

@@ -1,4 +1,3 @@
-import { type CliFlags, type CommandContext } from './flag-values.js';
-export declare function cmdContext(hippoRoot: string, args: string[], flags: CliFlags, stdinText?: string): Promise<void>;
-export declare function handleContext({ hippoRoot, args, flags }: CommandContext): Promise<void>;
+import { type CommandContext } from './flag-values.js';
+export declare function handleContext({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=context.d.ts.map

package/dist/cli/context.js

@@ -1,23 +1,27 @@
 // The `hippo context` verb, which the per-prompt hook also runs; main() loads it lazily from the command table.
-import { isSubagentPayload } from '../store/token-ledger.js';
+import { isSubagentPayload } from '../util/hook-payload.js';
 import { estimateTokens } from '../util/token-text.js';
 import { autoDetectContext } from '../api/context-auto.js';
-import { detectScope } from '../sharing/scope.js';
+import { detectScope } from '../core/active-scope.js';
 import { bookLedgerTurn } 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 { resolveTenantId } from '../store/tenant.js';
+import { DEFAULT_CONTEXT_BUDGET } 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, sessionStartEnvelope, toRenderItems, } from '../api/prompt-hook.js';
+import { additionalContextOutput, flushDeliveryRecorder, hasContextData, startDeliveryRecorder, sessionStartEnvelope, toRenderItems, } from '../api/prompt-hook.js';
 import { parseLimitFlag, parseCountFlag, parseBudgetFlag, flagIsTrue } from './flag-values.js';
 import { requireInit } from './shared.js';
 import { printActiveTaskSnapshot, printSessionEvents, printHandoff, captureConsole } from './print.js';
-import { hostSessionId, hookStoreRoot, hookRuntime, payloadCwdRoot, runHookWithStores, inPilotHoldout, startDeliveryRecorder } from './hook-runtime.js';
-export async function cmdContext(hippoRoot, args, flags, stdinText) {
-    const rec = flagIsTrue(flags, 'pinned-only') ? startDeliveryRecorder(hippoRoot, stdinText, hookRuntime(flags)) : null;
+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(),
+    });
     // No try/finally: a render throw keeps its own exit code and writes no event.
-    await renderContext(hippoRoot, args, flags, stdinText, rec);
+    await renderContext(hippoRoot, tenantId, args, flags, stdinText, rec);
     flushDeliveryRecorder(rec);
 }
 /** The hook payload's session id and raw prompt; a malformed or empty payload yields neither. */
@@ -26,11 +30,12 @@ function readHookPayload(stdinText) {
     let prompt;
     if (stdinText && stdinText.trim() !== '') {
         try {
-            // SAFETY: both fields are type-checked below before use; `?? {}` covers a JSON null payload.
-            const { session_id: sid, prompt: raw } = (JSON.parse(stdinText.trim()) ?? {});
-            if (typeof sid === 'string' && sid.trim() !== '')
+            const payload = JSON.parse(stdinText.trim());
+            const sid = isJsonObject(payload) ? payload['session_id'] : undefined;
+            const raw = isJsonObject(payload) ? payload['prompt'] : undefined;
+            if (isJsonString(sid) && sid.trim() !== '')
                 sessionId = sid;
-            if (typeof raw === 'string')
+            if (isJsonString(raw))
                 prompt = raw;
         }
         catch {
@@ -39,7 +44,7 @@ function readHookPayload(stdinText) {
     }
     return { sessionId, prompt };
 }
-async function renderContext(hippoRoot, args, flags, stdinText, rec) {
+async function renderContext(hippoRoot, resolvedTenant, args, 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');
@@ -49,19 +54,18 @@ async function renderContext(hippoRoot, args, flags, stdinText, rec) {
     const session = resolveContextSession(stdinText);
     const { currentSessionId, ledgerSessionId, payloadSessionId } = session;
     // The pilot arm is booked at the first hook call whatever the flags, so the holdout sees no budget or content branch.
-    const resolvedTenant = resolveTenantId({});
     if (inPilotHoldout(hippoRoot, resolvedTenant, currentSessionId, payloadSessionId !== undefined)) {
         rec?.disabled();
         return;
     }
-    const budget = parseBudgetFlag(flags['budget'], 1500);
+    const budget = parseBudgetFlag(flags['budget'], DEFAULT_CONTEXT_BUDGET);
     if (budget <= 0) {
         rec?.disabled();
         return;
     }
     // --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 = { hippoRoot, tenantId: resolvedTenant, actor: api.adminActor('cli') };
+    const ctx = cliApiContext(hippoRoot, resolvedTenant);
     const format = String(flags['format'] ?? 'markdown');
     const framing = String(flags['framing'] ?? 'observe');
     const opts = buildContextOpts(flags, { query, budget, pinnedOnly, format, framing, session, rec });
@@ -195,10 +199,10 @@ function printCrossProjectSection(items) {
     for (const line of crossProjectLines(items))
         console.log(line);
 }
-export async function handleContext({ hippoRoot, args, flags }) {
+export async function handleContext({ hippoRoot, tenantId, args, flags }) {
     // Bounded, not a TTY guard: the hot stdin path and a manual run share this one command.
     const { text: stdinText } = await readHookStdin();
     const root = payloadCwdRoot(hippoRoot, stdinText, hookRuntime(flags));
-    await runHookWithStores(() => cmdContext(hookStoreRoot(root), args, flags, stdinText));
+    await runHookWithStores(() => cmdContext(hookStoreRoot(root), tenantId, args, flags, stdinText));
 }
 //# sourceMappingURL=context.js.map