hippo-memory 1.69.0 → 1.71.0

package/dist/cli/goals.js

@@ -1,86 +1,93 @@
 // `hippo goal`: the per-session goal stack that recall boosts.
-import { envHippoSessionId } from '../env.js';
-import * as api from '../api.js';
-import { resolveTenantId } from '../tenant.js';
+import { DEFAULT_TENANT_ID, envHippoSessionId } from '../util/env.js';
+import * as api from '../api/index.js';
+import { cliApiContext } from './api-context.js';
 import { printError } from './output.js';
-// ---------------------------------------------------------------------------
+import { boolFlag, flagIsTrue, isStringFlag, stringFlag } from './flag-values.js';
+import { CliExit } from './exit.js';
 // `hippo goal <push|list|complete|suspend|resume>`
-// ---------------------------------------------------------------------------
 const GOAL_POLICY_TYPES = [
     'schema-fit-biased',
     'error-prioritized',
     'recency-first',
     'hybrid',
 ];
+function isGoalPolicyType(value) {
+    return GOAL_POLICY_TYPES.some((type) => type === value);
+}
 function sanitizeGoalName(s) {
     // Strip C0 control chars + DEL to prevent terminal escape injection.
-    return s.replace(/[\x00-\x1f\x7f]/g, '?');
+    return s.replace(/[^\x20-\x7e\u0080-\uffff]/g, '?');
 }
-function resolveGoalSession(flags) {
+function resolveGoalSession(flags, defaultTenantId) {
     const sessionId = (flags['session-id'] !== undefined
         ? String(flags['session-id'])
         : envHippoSessionId() ?? '').trim();
     if (!sessionId) {
         printError('session id required (set HIPPO_SESSION_ID or pass --session-id)');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const tenantId = (flags['tenant-id'] !== undefined
         ? String(flags['tenant-id'])
-        : resolveTenantId({})).trim() || 'default';
+        : defaultTenantId).trim() || DEFAULT_TENANT_ID;
     return { sessionId, tenantId };
 }
-function cmdGoalPush(hippoRoot, args, flags) {
+function readGoalPolicy(flags) {
+    const policyRaw = flags['policy'];
+    if (policyRaw === true) {
+        printError('--policy requires a value (e.g., --policy error-prioritized)');
+        throw new CliExit(1);
+    }
+    if (!isStringFlag(policyRaw))
+        return undefined;
+    if (!isGoalPolicyType(policyRaw)) {
+        printError(`Unknown --policy '${policyRaw}'. Expected one of: ${GOAL_POLICY_TYPES.join(' | ')}.`);
+        throw new CliExit(1);
+    }
+    return { policyType: policyRaw };
+}
+function readGoalLevel(flags) {
+    const levelRaw = flags['level'];
+    if (levelRaw === true) {
+        printError('--level requires a value (e.g., --level 1)');
+        throw new CliExit(1);
+    }
+    if (levelRaw === undefined)
+        return undefined;
+    const parsed = Number(levelRaw);
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 2 || !Number.isInteger(parsed)) {
+        printError('--level must be an integer in [0, 2]');
+        throw new CliExit(1);
+    }
+    return parsed;
+}
+function cmdGoalPush(hippoRoot, defaultTenantId, args, flags) {
     const rawName = args.join(' ').trim();
     if (!rawName) {
         printError('Usage: hippo goal push <name> [--policy <type>] [--success "<condition>"] [--level N] [--parent <goalId>]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     // Sanitize at WRITE time so corrupt names never enter the DB.
     const name = sanitizeGoalName(rawName);
     if (name !== rawName) {
         printError('note: stripped control characters from goal name');
     }
-    const { sessionId, tenantId } = resolveGoalSession(flags);
-    let policy;
-    const policyRaw = flags['policy'];
-    if (policyRaw === true) {
-        printError('--policy requires a value (e.g., --policy error-prioritized)');
-        process.exit(1);
-    }
-    if (typeof policyRaw === 'string') {
-        if (!GOAL_POLICY_TYPES.includes(policyRaw)) {
-            printError(`Unknown --policy '${policyRaw}'. Expected one of: ${GOAL_POLICY_TYPES.join(' | ')}.`);
-            process.exit(1);
-        }
-        policy = { policyType: policyRaw };
-    }
+    const { sessionId, tenantId } = resolveGoalSession(flags, defaultTenantId);
+    const policy = readGoalPolicy(flags);
     const successRaw = flags['success'];
     if (successRaw === true) {
         printError('--success requires a value (e.g., --success "<condition>")');
-        process.exit(1);
-    }
-    const successCondition = typeof successRaw === 'string' ? successRaw : undefined;
-    const levelRaw = flags['level'];
-    let level;
-    if (levelRaw === true) {
-        printError('--level requires a value (e.g., --level 1)');
-        process.exit(1);
-    }
-    if (levelRaw !== undefined) {
-        const parsed = Number(levelRaw);
-        if (!Number.isFinite(parsed) || parsed < 0 || parsed > 2 || !Number.isInteger(parsed)) {
-            printError('--level must be an integer in [0, 2]');
-            process.exit(1);
-        }
-        level = parsed;
+        throw new CliExit(1);
     }
+    const successCondition = stringFlag(flags, 'success');
+    const level = readGoalLevel(flags);
     const parentRaw = flags['parent'];
     if (parentRaw === true) {
         printError('--parent requires a value (e.g., --parent <goalId>)');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const parentGoalId = typeof parentRaw === 'string' ? parentRaw : undefined;
-    const goal = api.goalPush(goalContext(hippoRoot, tenantId), {
+    const parentGoalId = stringFlag(flags, 'parent');
+    const goal = api.goalPush(cliApiContext(hippoRoot, tenantId), {
         sessionId,
         goalName: name,
         level,
@@ -90,21 +97,15 @@ function cmdGoalPush(hippoRoot, args, flags) {
     });
     console.log(goal.id);
 }
-function goalContext(hippoRoot, tenantId = resolveTenantId({})) {
-    return { hippoRoot, tenantId, actor: api.adminActor('cli') };
-}
-function cmdGoalList(hippoRoot, flags) {
-    const { sessionId, tenantId } = resolveGoalSession(flags);
-    const showAll = Boolean(flags['all']);
-    const goals = api.goalList(goalContext(hippoRoot, tenantId), { sessionId, all: showAll });
+function cmdGoalList(hippoRoot, defaultTenantId, flags) {
+    const { sessionId, tenantId } = resolveGoalSession(flags, defaultTenantId);
+    const showAll = boolFlag(flags, 'all');
+    const goals = api.goalList(cliApiContext(hippoRoot, tenantId), { sessionId, all: showAll });
     if (goals.length === 0) {
         console.log('(no goals)');
         return;
     }
-    // 4-column table: id, status, goal_name, outcome. Plan calls it a "2-column"
-    // table but the assertion list (id, status, goal_name, outcome) needs four;
-    // tests check for substrings ('active', '0.9', name) so column count is
-    // observably four but not asserted.
+    // Four columns (id, status, goal_name, outcome); tests only check substrings, so the count is not asserted.
     const rows = goals.map(g => ({
         id: g.id,
         status: g.status,
@@ -123,74 +124,74 @@ function cmdGoalList(hippoRoot, flags) {
         console.log(`${pad(r.id, widths.id)}  ${pad(r.status, widths.status)}  ${pad(r.name, widths.name)}  ${pad(r.outcome, widths.outcome)}`);
     }
 }
-function cmdGoalComplete(hippoRoot, args, flags) {
+function cmdGoalComplete(hippoRoot, tenantId, args, flags) {
     const id = args[0];
     if (!id) {
         printError('Usage: hippo goal complete <id> [--outcome <0..1>] [--no-propagate]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     let outcomeScore;
     const outcomeRaw = flags['outcome'];
     if (outcomeRaw === true) {
         printError('--outcome requires a value (e.g., --outcome 0.9)');
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (outcomeRaw !== undefined) {
         const parsed = Number(outcomeRaw);
         if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
             printError('--outcome must be a number in [0, 1]');
-            process.exit(1);
+            throw new CliExit(1);
         }
         outcomeScore = parsed;
     }
-    const noPropagate = flags['no-propagate'] === true;
-    api.goalComplete(goalContext(hippoRoot), id, { outcomeScore, noPropagate });
+    const noPropagate = flagIsTrue(flags, 'no-propagate');
+    api.goalComplete(cliApiContext(hippoRoot, tenantId), id, { outcomeScore, noPropagate });
     console.log('ok');
 }
-function cmdGoalSuspend(hippoRoot, args) {
+function cmdGoalSuspend(hippoRoot, tenantId, args) {
     const id = args[0];
     if (!id) {
         printError('Usage: hippo goal suspend <id>');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    api.goalSuspend(goalContext(hippoRoot), id);
+    api.goalSuspend(cliApiContext(hippoRoot, tenantId), id);
     console.log('ok');
 }
-function cmdGoalResume(hippoRoot, args) {
+function cmdGoalResume(hippoRoot, tenantId, args) {
     const id = args[0];
     if (!id) {
         printError('Usage: hippo goal resume <id>');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    api.goalResume(goalContext(hippoRoot), id);
+    api.goalResume(cliApiContext(hippoRoot, tenantId), id);
     console.log('ok');
 }
-export function cmdGoal(hippoRoot, args, flags) {
+export function handleGoal({ hippoRoot, tenantId, args, flags }) {
     const sub = args[0];
     if (!sub) {
         printError('Usage: hippo goal <push|list|complete|suspend|resume> [args]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const subArgs = args.slice(1);
     switch (sub) {
         case 'push':
-            cmdGoalPush(hippoRoot, subArgs, flags);
+            cmdGoalPush(hippoRoot, tenantId, subArgs, flags);
             return;
         case 'list':
-            cmdGoalList(hippoRoot, flags);
+            cmdGoalList(hippoRoot, tenantId, flags);
             return;
         case 'complete':
-            cmdGoalComplete(hippoRoot, subArgs, flags);
+            cmdGoalComplete(hippoRoot, tenantId, subArgs, flags);
             return;
         case 'suspend':
-            cmdGoalSuspend(hippoRoot, subArgs);
+            cmdGoalSuspend(hippoRoot, tenantId, subArgs);
             return;
         case 'resume':
-            cmdGoalResume(hippoRoot, subArgs);
+            cmdGoalResume(hippoRoot, tenantId, subArgs);
             return;
         default:
             printError(`Unknown goal subcommand: ${sub}. Expected: push | list | complete | suspend | resume.`);
-            process.exit(1);
+            throw new CliExit(1);
     }
 }
 //# sourceMappingURL=goals.js.map

package/dist/cli/hook-runtime.d.ts

@@ -0,0 +1,31 @@
+import type { HookRuntime } from '../core/capture-contract.js';
+import { type DeliveryEventType, type DeliveryRecorder } from '../store/delivery-recorder.js';
+import type { CliFlags } from './flag-values.js';
+/** Detached worker (internal `__session-end-worker`): counts re-reads, runs sleep, then capture; one stage failing does not block the other. */
+/** A folder without its own store never sleeps at session end, so its project's agent notes go to the global store here. */
+export declare function logSessionEndImport(logFile: string | null, transcriptPath: string | undefined): void;
+/** Best-effort log line for the cmdSessionEndWorker snapshot-close step: cmdSleep/cmdCapture restore their console tee before this runs,
+ * so console.log would be lost under the worker's `stdio: 'ignore'`; write to the file directly. */
+export declare function appendSessionEndCloseLog(logFile: string | null, message: string, opts?: {
+    startFresh?: boolean;
+}): void;
+/** A session-end step that failed: one warn line, and the same text in the session log, the only place a detached worker's output survives. */
+export declare function reportSessionEndFailure<E>(logFile: string | null, step: string, err: E): void;
+export declare function hostSessionId(): string | undefined;
+/** Compaction drops the pinned blocks the per-prompt hook injected, so record a `reset` for the payload's session and the next prompt injects again.
+ * `requiredSource` limits it to payloads with that `source`; best-effort and silent on a malformed payload. */
+export declare function resetHookInjection(hippoRoot: string, stdinText: string | undefined, requiredSource: string | null): void;
+/** Store a hook writes to: the project store, else an existing global one, else the project path (skipped: hooks must not create a store).
+ * Pre-compact and compact-resume must agree, or a snapshot is looked for in the other store. */
+export declare function hookStoreRoot(hippoRoot: string): string;
+/** `--runtime copilot`, or `--format copilot` on `hippo context`, marks a Copilot hook: the flag decides, never the payload. */
+export declare function hookRuntime(flags: CliFlags): HookRuntime;
+/** A delivery recorder when the ledger store enables one, else null; never throws. */
+export declare function startDeliveryRecorder(hippoRoot: string, stdinText: string | undefined, runtime: HookRuntime, eventType?: DeliveryEventType): DeliveryRecorder | null;
+/** A Copilot hook's project root, from the payload's `cwd`, since VS Code runs user-level hooks in the home folder; other runtimes keep `hippoRoot`. */
+export declare function payloadCwdRoot(hippoRoot: string, stdinText: string | undefined, runtime: HookRuntime): string;
+/** Hook commands share one handle per store and wait at most HOOK_DB_WAIT_MS for a lock; a store still busy after that skips the hook's work with one warning, exit 0. */
+export declare function runHookWithStores<T>(fn: () => T | Promise<T>): Promise<T | undefined>;
+/** Whether this session sits in the pilot's holdout arm; off at rate 0 and with no session id. */
+export declare function inPilotHoldout(hippoRoot: string, tenantId: string, sessionId: string | undefined, write: boolean): boolean;
+//# sourceMappingURL=hook-runtime.d.ts.map

package/dist/cli/hook-runtime.js

@@ -0,0 +1,139 @@
+// What the hook commands share: session id, store choice, delivery recorder, session-end log and store-busy handling.
+import { envClaudeCodeSessionId, envHippoSessionId } from '../util/env.js';
+import * as path from 'path';
+import * as fs from 'fs';
+import { getHippoRoot, isInitialized } from '../store/open.js';
+import { loadConfig } from '../core/config.js';
+import { createDeliveryRecorder } from '../store/delivery-recorder.js';
+import { isSqliteBusy, noteStoreBusy, runWithRequestStores, HOOK_DB_WAIT_MS } from '../db/index.js';
+import { bookTokenUse, ledgerRoot } from '../api/ledger-db.js';
+import { sessionPilotArm } from '../api/pilot-arm.js';
+import { hookPayloadSessionId, hookPayloadString, isSubagentPayload } from '../store/token-ledger.js';
+import { blockHash } from '../util/token-text.js';
+import { importAtSessionEnd, currentMachine } from '../agent-memories/sync.js';
+import { summaryLine } from '../agent-memories/report.js';
+import { isGlobalStoreRoot } from '../core/project-identity.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
+import { sanitizeLogMessage } from '../capture/compact.js';
+import { resolveTenantId } from '../store/tenant.js';
+import { errorMessage, log } from '../util/log.js';
+/** Detached worker (internal `__session-end-worker`): counts re-reads, runs sleep, then capture; one stage failing does not block the other. */
+/** A folder without its own store never sleeps at session end, so its project's agent notes go to the global store here. */
+export function logSessionEndImport(logFile, transcriptPath) {
+    try {
+        const report = importAtSessionEnd(process.cwd(), transcriptPath, { machine: currentMachine() });
+        const line = summaryLine(report);
+        if (line !== null)
+            appendSessionEndCloseLog(logFile, line);
+        for (const warning of report.warnings)
+            appendSessionEndCloseLog(logFile, `agent memories: ${warning}`);
+    }
+    catch (err) {
+        appendSessionEndCloseLog(logFile, `agent memory import failed: ${errorMessage(err)}`);
+    }
+}
+/** Best-effort log line for the cmdSessionEndWorker snapshot-close step: cmdSleep/cmdCapture restore their console tee before this runs,
+ * so console.log would be lost under the worker's `stdio: 'ignore'`; write to the file directly. */
+export function appendSessionEndCloseLog(logFile, message, opts = {}) {
+    if (!logFile)
+        return;
+    try {
+        fs.mkdirSync(path.dirname(logFile), { recursive: true });
+        // sanitizeLogMessage: `message` interpolates the payload-controlled
+        // session_id — same log-forgery guard appendPreCompactLog applies.
+        const write = opts.startFresh ? fs.writeFileSync : fs.appendFileSync;
+        write(logFile, `[hippo] ${new Date().toISOString()} ${sanitizeLogMessage(message)}\n`, 'utf8');
+    }
+    catch (err) {
+        // Best-effort only: a log-write failure must never fail the hook.
+        log.debug(`session-end log not written: ${errorMessage(err)}`);
+    }
+}
+/** A session-end step that failed: one warn line, and the same text in the session log, the only place a detached worker's output survives. */
+export function reportSessionEndFailure(logFile, step, err) {
+    const line = `${step} failed: ${errorMessage(err)}`;
+    log.warn(line);
+    appendSessionEndCloseLog(logFile, line);
+}
+// Claude Code exports its own session var, not ours; without the fallback agent-run recalls trace with no session.
+export function hostSessionId() {
+    return envHippoSessionId() ?? envClaudeCodeSessionId();
+}
+/** Compaction drops the pinned blocks the per-prompt hook injected, so record a `reset` for the payload's session and the next prompt injects again.
+ * `requiredSource` limits it to payloads with that `source`; best-effort and silent on a malformed payload. */
+export function resetHookInjection(hippoRoot, stdinText, requiredSource) {
+    const sessionId = hookPayloadSessionId(stdinText, requiredSource);
+    // A sub-agent's compaction leaves its parent's context, and the blocks in it, as they were.
+    if (sessionId === null || isSubagentPayload(stdinText))
+        return;
+    bookTokenUse(hippoRoot, {
+        tenantId: resolveTenantId({}), sessionId, surface: 'hook', event: 'reset', items: 0, tokens: 0,
+    });
+}
+/** Store a hook writes to: the project store, else an existing global one, else the project path (skipped: hooks must not create a store).
+ * Pre-compact and compact-resume must agree, or a snapshot is looked for in the other store. */
+export function hookStoreRoot(hippoRoot) {
+    if (isInitialized(hippoRoot))
+        return hippoRoot;
+    const globalRoot = getGlobalRoot();
+    return isInitialized(globalRoot) ? globalRoot : hippoRoot;
+}
+/** `--runtime copilot`, or `--format copilot` on `hippo context`, marks a Copilot hook: the flag decides, never the payload. */
+export function hookRuntime(flags) {
+    return flags['runtime'] === 'copilot' || flags['format'] === 'copilot' ? 'copilot' : 'claude-code';
+}
+/** A delivery recorder when the ledger store enables one, else null; never throws. */
+export function startDeliveryRecorder(hippoRoot, stdinText, runtime, eventType) {
+    try {
+        // The same store withLedgerDb writes the token ledger to, so its config governs both.
+        const root = ledgerRoot(hippoRoot);
+        if (root === null || !loadConfig(root).deliveryLedger.enabled)
+            return null;
+        return createDeliveryRecorder({
+            root,
+            storeHash: blockHash(path.resolve(root)),
+            writeStore: isGlobalStoreRoot(root) ? 'global' : 'local',
+            tenantId: resolveTenantId({}),
+            stdinText,
+            envSessionId: hostSessionId(),
+            runtime: runtime === 'copilot' ? 'copilot' : undefined,
+            eventType,
+        });
+    }
+    catch (error) {
+        log.warn(`delivery ledger skipped: ${errorMessage(error)}`);
+        return null;
+    }
+}
+/** A Copilot hook's project root, from the payload's `cwd`, since VS Code runs user-level hooks in the home folder; other runtimes keep `hippoRoot`. */
+export function payloadCwdRoot(hippoRoot, stdinText, runtime) {
+    const cwd = runtime === 'copilot' ? hookPayloadString(stdinText, 'cwd') : null;
+    if (cwd === null || cwd.trim() === '')
+        return hippoRoot;
+    try {
+        // Moving, not just re-rooting, keeps project identity, scope, handoff evidence and the session-end worker on that folder too.
+        process.chdir(cwd);
+    }
+    catch (err) {
+        log.warn(`hippo: payload cwd ${cwd} is not usable, so the hook stays in ${process.cwd()}: ${errorMessage(err)}`);
+        return hippoRoot;
+    }
+    return getHippoRoot(process.cwd());
+}
+/** Hook commands share one handle per store and wait at most HOOK_DB_WAIT_MS for a lock; a store still busy after that skips the hook's work with one warning, exit 0. */
+export async function runHookWithStores(fn) {
+    try {
+        return await runWithRequestStores(fn, { busyWaitMs: HOOK_DB_WAIT_MS, failFastWhenBusy: true });
+    }
+    catch (error) {
+        if (!isSqliteBusy(error))
+            throw error;
+        noteStoreBusy('hook skipped');
+        return undefined;
+    }
+}
+/** Whether this session sits in the pilot's holdout arm; off at rate 0 and with no session id. */
+export function inPilotHoldout(hippoRoot, tenantId, sessionId, write) {
+    return sessionPilotArm(hippoRoot, tenantId, sessionId, write) === 'holdout';
+}
+//# sourceMappingURL=hook-runtime.js.map

package/dist/cli/init.d.ts

@@ -1,2 +1,3 @@
-export declare function cmdInit(hippoRoot: string, flags: Record<string, string | boolean | string[]>): void;
+import { type CommandContext } from './flag-values.js';
+export declare function handleInit({ hippoRoot, flags }: CommandContext): void;
 //# sourceMappingURL=init.d.ts.map