hippo-memory 1.69.0 → 1.71.0

package/dist/cli/setup.d.ts

@@ -1,4 +1,5 @@
-export declare function cmdHook(args: string[]): void;
-export declare function cmdSetup(flags: Record<string, string | boolean | string[]>): void;
-export declare function cmdDailyRunner(): void;
+import { type CommandContext } from './flag-values.js';
+export declare function handleHook({ args }: CommandContext): void;
+export declare function handleSetup({ flags }: CommandContext): void;
+export declare function handleDailyRunner(_ctx: CommandContext): void;
 //# sourceMappingURL=setup.d.ts.map

package/dist/cli/setup.js

@@ -9,19 +9,22 @@ import { installOpencodePlugin, uninstallOpencodePlugin, resolveOpencodePluginPa
 import { COPILOT_CLI_MCP, VSCODE_MCP, copilotMcpSnippet, copilotPaths, installCopilot, isCopilotCliPresent, isMcpFailure, uninstallCopilot, } from '../hooks/copilot.js';
 import { isInitialized } from '../store/open.js';
 import { currentMachine, importUserMemories } from '../agent-memories/sync.js';
-import { getGlobalRoot } from '../shared.js';
-import { listRegisteredWorkspaces, runDailyMaintenance } from '../scheduler.js';
-import { replayCompactionsAt } from '../compaction-record.js';
-import { log } from '../log.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
+import { listRegisteredWorkspaces, runDailyMaintenance } from './scheduler.js';
+import { replayCompactionsAt } from '../capture/compaction-record.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
+import { envDailyStepTimeoutMs } from '../util/env.js';
+import { writeFileAtomic } from '../util/atomic-write.js';
 import { printError } from './output.js';
-import { printAgentImport, installCodexMemoryHooks, setupDailySchedule, warnClaudeSettingsUnusable } from './shared.js';
+import { boolFlag } from './flag-values.js';
+import { printAgentImport } from './print.js';
+import { installCodexMemoryHooks, setupDailySchedule, warnClaudeSettingsUnusable } from './install-steps.js';
 import { repairQualityOnceAt } from './quality-repair-once.js';
-import { HOOK_MARKERS, HOOKS, hippoBlock, withoutHookBlock } from './hook-blocks.js';
-import { escapeRegex } from '../escape.js';
-// ---------------------------------------------------------------------------
+import { HOOK_MARKERS, HOOKS, hippoBlock, withoutHookBlock } from '../hooks/hook-blocks.js';
+import { escapeRegex } from '../util/escape.js';
+import { CliExit } from './exit.js';
 // Hook install/uninstall
-// ---------------------------------------------------------------------------
-export function cmdHook(args) {
+export function handleHook({ args }) {
     const subcommand = args[0];
     const target = args[1];
     if (subcommand === 'list')
@@ -31,7 +34,7 @@ export function cmdHook(args) {
     if (subcommand === 'uninstall')
         return hookUninstall(target);
     printError('Usage: hippo hook <install|uninstall|list> [target]');
-    process.exit(1);
+    throw new CliExit(1);
 }
 // Cursor has no init row, so the AGENTS.md block is usually another agent's, and Cursor reads that one as it is.
 function othersBlock(target, text) {
@@ -53,7 +56,7 @@ function hookInstall(target) {
     if (!target || !HOOKS[target]) {
         printError(`Unknown hook target: ${target ?? '(none)'}`);
         printError(`   Available: ${[...Object.keys(HOOKS), 'copilot'].join(', ')}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const hook = HOOKS[target];
     patchAgentFile(hook, target);
@@ -89,19 +92,18 @@ function patchAgentFile(hook, target) {
         else if (existing.includes(HOOK_MARKERS.start)) {
             const re = new RegExp(`${escapeRegex(HOOK_MARKERS.start)}[\\s\\S]*?${escapeRegex(HOOK_MARKERS.end)}`, 'g');
             const updated = existing.replace(re, block);
-            fs.writeFileSync(filepath, updated, 'utf8');
+            writeFileAtomic(filepath, updated);
             console.log(`Updated Hippo hook in ${hook.file}`);
         }
         else {
             const sep = existing.endsWith('\n') ? '\n' : '\n\n';
-            fs.writeFileSync(filepath, existing + sep + block + '\n', 'utf8');
+            writeFileAtomic(filepath, existing + sep + block + '\n');
             console.log(`Installed Hippo hook in ${hook.file} (appended)`);
         }
     }
     else {
-        // Do not create a new agent-instructions file (CLAUDE.md, AGENTS.md, etc.) in directories that don't already have one —
-        // avoids polluting cwd with files the user didn't ask for. The settings.json hook below is still installed for
-        // claude-code, so the consolidation hook still runs.
+        // Do not create an agent-instructions file (CLAUDE.md, AGENTS.md, etc.) in directories without one, to avoid polluting cwd;
+        // the settings.json hook below is still installed for claude-code.
         console.log(`${hook.file} not found in ${process.cwd()} — skipping agent-instructions patch.`);
         console.log(`   Create ${hook.file} and re-run \`hippo hook install ${target}\` if you want the agent prompt.`);
     }
@@ -140,7 +142,7 @@ function printClaudeHookInstall(result) {
     }
 }
 function installOpencodeHook() {
-    // opencode uses a TS plugin, not JSON hooks. See src/hooks.ts.
+    // opencode uses a TS plugin, not JSON hooks. See src/hooks/opencode.ts.
     const result = installOpencodePlugin();
     if (result.installed) {
         console.log(`Installed hippo opencode plugin at ${result.pluginPath}`);
@@ -250,7 +252,7 @@ function hookUninstall(target) {
         return printCopilotUninstall(uninstallCopilot());
     if (!target || !HOOKS[target]) {
         printError(`Unknown hook target: ${target ?? '(none)'}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     unpatchAgentFile(HOOKS[target], target);
     // For Claude Code, also strip its SessionEnd/SessionStart entries.
@@ -263,9 +265,7 @@ function hookUninstall(target) {
         }
     }
     else if (target === 'opencode') {
-        // opencode uses a TS plugin; uninstall removes the plugin file AND
-        // also runs the legacy-hooks migration so the downgrade/remove path
-        // leaves opencode launchable.
+        // opencode uses a TS plugin; uninstall removes the plugin file and also runs the legacy-hooks migration, so remove leaves opencode launchable.
         if (uninstallOpencodePlugin()) {
             console.log(`Removed hippo opencode plugin (and any legacy hooks block from opencode.json)`);
         }
@@ -295,7 +295,7 @@ function unpatchAgentFile(hook, target) {
         console.log(`Left the hippo block in ${hook.file}: ${whose}. Delete it by hand if no agent needs it.`);
     }
     else if (existing.includes(HOOK_MARKERS.start)) {
-        fs.writeFileSync(filepath, withoutHookBlock(existing) + '\n', 'utf8');
+        writeFileAtomic(filepath, withoutHookBlock(existing) + '\n');
         console.log(`Removed Hippo hook from ${hook.file}`);
     }
     else {
@@ -309,21 +309,13 @@ function removeLegacyCursorRules() {
     if (old.includes(HOOK_MARKERS.start)) {
         const left = withoutHookBlock(old);
         if (left)
-            fs.writeFileSync(legacy, left + '\n', 'utf8');
+            writeFileAtomic(legacy, left + '\n');
         else
             fs.unlinkSync(legacy);
         console.log(left ? 'Removed the old Hippo hook from .cursorrules' : 'Deleted .cursorrules, which held only the old Hippo hook');
     }
 }
-// `hippo setup` -- one-shot configuration for every AI coding tool on the box.
-// Detection and install logic live in ./hooks.ts.
-export function cmdSetup(flags) {
-    const dryRun = Boolean(flags['dry-run']);
-    const forceAll = Boolean(flags['all']);
-    const tools = detectInstalledTools();
-    const globalRoot = getGlobalRoot();
-    console.log('Hippo setup -- configuring SessionEnd + SessionStart hooks');
-    console.log('');
+function setupDetectedTools(tools, forceAll, dryRun) {
     const jsonTools = tools.filter((t) => t.kind === 'json-hook' && (t.detected || forceAll));
     const wrapperTools = tools.filter((t) => t.kind === 'wrapper' && (t.detected || forceAll));
     const skipped = tools.filter((t) => t.kind === 'json-hook' && !t.detected && !forceAll);
@@ -353,6 +345,17 @@ export function cmdSetup(flags) {
             console.log(`  ${tool.name.padEnd(14)} ${tool.notes}`);
         }
     }
+}
+// `hippo setup` -- one-shot configuration for every AI coding tool on the box.
+// Detection and install logic live in src/hooks/.
+export function handleSetup({ flags }) {
+    const dryRun = boolFlag(flags, 'dry-run');
+    const forceAll = boolFlag(flags, 'all');
+    const tools = detectInstalledTools();
+    const globalRoot = getGlobalRoot();
+    console.log('Hippo setup -- configuring SessionEnd + SessionStart hooks');
+    console.log('');
+    setupDetectedTools(tools, forceAll, dryRun);
     if (!flags['no-schedule']) {
         console.log('');
         if (dryRun) {
@@ -382,14 +385,16 @@ function setupCopilot(dryRun) {
 function setupJsonTool(tool, dryRun) {
     if (tool.name === 'copilot')
         return setupCopilot(dryRun);
+    // SAFETY: detectInstalledTools gives kind 'json-hook' only to claude-code and copilot (hooks/shared.ts), and copilot returned above.
+    const target = tool.name;
     if (dryRun) {
         // Resolve the real settings path so the filename is right for each tool
         // (claude-code -> settings.json, opencode -> opencode.json).
-        const { settings } = resolveJsonHookPaths(tool.name);
+        const { settings } = resolveJsonHookPaths(target);
         console.log(`[dry-run] would install hooks in ${settings}`);
         return;
     }
-    const result = installJsonHooks(tool.name);
+    const result = installJsonHooks(target);
     if (warnClaudeSettingsUnusable(result, `  ${tool.name.padEnd(14)} `))
         return;
     const bits = [];
@@ -467,7 +472,15 @@ function setupPluginTool(tool, dryRun) {
         console.log(`  ${tool.name.padEnd(14)} ${bits.join(', ')} -> ${result.pluginPath}`);
     }
 }
-export function cmdDailyRunner() {
+// Three times the 10 minutes POST /v1/sleep allows a consolidation, so a slow real sleep fits and a hung child cannot stall every later workspace.
+const DAILY_STEP_TIMEOUT_MS = 30 * 60_000;
+/** Why a child step failed; a child killed at the deadline says so, since its own message is only the spawn error code. */
+function dailyStepFailure(err, timeoutMs) {
+    if (err instanceof Error && 'code' in err && err.code === 'ETIMEDOUT')
+        return `timed out after ${timeoutMs} ms and was stopped`;
+    return errorMessage(err);
+}
+export function handleDailyRunner(_ctx) {
     const globalRoot = getGlobalRoot();
     // No workspace sleep ever opens the global store, yet hooks in folders without a store compact into it.
     if (isInitialized(globalRoot)) {
@@ -485,12 +498,14 @@ export function cmdDailyRunner() {
     console.log(`Running daily maintenance across ${workspaces.length} registered workspace${workspaces.length === 1 ? '' : 's'}...`);
     let processed = 0;
     let failed = 0;
+    const timeout = envDailyStepTimeoutMs() ?? DAILY_STEP_TIMEOUT_MS;
     runDailyMaintenance(workspaces, (cwd, args) => {
         try {
             execFileSync(process.execPath, [process.argv[1], ...args], {
                 cwd,
                 stdio: 'inherit',
                 windowsHide: true,
+                timeout,
             });
             if (args[0] === 'sleep')
                 processed++;
@@ -498,9 +513,12 @@ export function cmdDailyRunner() {
         catch (err) {
             failed++;
             const action = args.join(' ');
-            log.error(`daily-runner failed in ${cwd} during \`${action}\`: ${err.message}`);
+            log.error(`daily-runner failed in ${cwd} during \`${action}\`: ${dailyStepFailure(err, timeout)}`, { workspace: cwd, ...errorFields(err) });
         }
     });
     console.log(`Daily maintenance complete: ${processed} workspace${processed === 1 ? '' : 's'} processed, ${failed} command failure${failed === 1 ? '' : 's'}.`);
+    // The scheduler that runs this only sees the exit code, so a failed workspace must not read as a clean run.
+    if (failed > 0)
+        process.exitCode = 1;
 }
 //# sourceMappingURL=setup.js.map

package/dist/cli/shared.d.ts

@@ -1,131 +1,27 @@
-import { type InstallResult } from '../hooks/json-hooks.js';
-import { TaskSnapshot, SessionEvent } from '../store/rows.js';
-import type { HookRuntime } from '../capture-contract.js';
-import type { SessionHandoff } from '../handoff.js';
-import type { SearchResult } from '../search/types.js';
-import { type HippoConfig } from '../config.js';
-import { type ImportReport } from '../agent-memories/report.js';
-import { type ChurnStaleResult } from '../invalidation.js';
-import { type AuditOp } from '../audit.js';
-import { type ServerInfo } from '../server-detect.js';
-import type { RecallSearchOpts } from '../recall-pipeline.js';
-export declare function parseLimitFlag(value: string | boolean | string[] | undefined): number;
-export declare function parseCountFlag(value: string | boolean | string[] | undefined): number;
-export declare function parseBudgetFlag(value: string | boolean | string[] | undefined, fallback: number): number;
-/**
- * Emit an audit event against `hippoRoot`'s db. Opens its own short-lived
- * connection so callers don't have to thread a db handle. Swallows all errors
- * — audit must never crash a CLI command.
- */
-export declare function emitCliAudit(hippoRoot: string, op: AuditOp, targetId?: string, metadata?: Record<string, unknown>): void;
+import { type ChurnStaleResult } from '../learn/invalidation.js';
+import { type AuditOp } from '../store/audit.js';
+import { type ServerInfo } from '../server/server-detect.js';
+import type { JsonObject } from '../store/working-memory.js';
+import type { CliFlags } from './flag-values.js';
+/** Emit an audit event on its own short-lived connection to `hippoRoot`'s db; swallows all errors, since audit must never crash a CLI command. */
+export declare function emitCliAudit(hippoRoot: string, op: AuditOp, targetId?: string, metadata?: JsonObject): void;
 export declare function requireInit(hippoRoot: string): void;
 /** Runs detectChurnStale against every store this repo's memories can live in. */
 export declare function runChurnStaleForRepo(hippoRoot: string, dryRun: boolean): {
     root: string;
     result: ChurnStaleResult;
 }[];
-/**
- * Run an HTTP-routed command if a `hippo serve` instance is detected for
- * `hippoRoot`. Returns:
- *   - true  if the HTTP path ran (success OR a structured server error that
- *           was already surfaced to stdout/stderr by `httpFn`),
- *   - false if no server was detected, or if the detected pidfile turned out
- *           to be stale (connection refused). On stale, the pidfile is removed
- *           if it still names that dead server (a newer one may have replaced
- *           it) and the caller should fall back to the direct path.
- *
- * Stale pidfiles must self-heal, not crash.
- * When HIPPO_REQUIRE_SERVER is set, both fallback paths throw instead of
- * returning false, so a missing server fails loudly rather than silently
- * degrading to direct mode.
- */
+/** Run an HTTP-routed command if a `hippo serve` is detected: true if it ran, false on no server or a stale pidfile (removed if it names the dead server).
+ * With HIPPO_REQUIRE_SERVER set both fallbacks throw; a stale pidfile must self-heal, not crash. */
 export declare function runViaServerIfAvailable(hippoRoot: string, httpFn: (info: ServerInfo, apiKey: string | undefined) => Promise<void>): Promise<boolean>;
-export declare function fmt(n: number, digits?: number): string;
-export declare function recallEntryText(r: SearchResult, query: string, showWhy: boolean, isGlobal: boolean): string;
-export declare function recallHeading(entries: number, tokens: number, query: string): string;
-/** One line when an agent memory import moved anything; its warnings go to stderr. */
-export declare function printAgentImport(report: ImportReport, indent?: string): void;
 /** True, after one line, on a shared store: this account's commits and agent notes are not its members' memories. */
 export declare function skipLearnOnSharedStore(hippoRoot: string): boolean;
-/** Adds hippo's two Codex hooks and says what changed; each install ends on the trust reminder, since Codex skips an untrusted hook. */
-export declare function installCodexMemoryHooks(indent: string): void;
-/** The one line init, hook install, hook uninstall and setup print when Claude Code's settings.json is not JSON hippo can edit and so was left unchanged; true when it printed. */
-export declare function warnClaudeSettingsUnusable(result: Pick<InstallResult, 'settingsPath' | 'invalidJson'>, indent: string, action?: 'install' | 'uninstall'): boolean;
-/**
- * Set up a machine-level daily runner that sweeps all registered Hippo
- * workspaces.
- * Linux/macOS: writes to user crontab.
- * Windows: creates a scheduled task.
- * Skips if already installed.
- */
-export declare function setupDailySchedule(globalRoot: string): void;
-export type CliFlags = Record<string, string | boolean | string[]>;
-/** What the command table hands each verb's run(). */
-export interface CommandContext {
-    readonly hippoRoot: string;
-    readonly args: string[];
-    readonly flags: CliFlags;
-}
-export type EngineFlags = Pick<RecallSearchOpts, 'usePhysics' | 'physicsConfig' | 'mmr' | 'mmrLambda' | 'localBump'>;
-export declare function parseAsOfFlag(flags: CliFlags): string | undefined;
-/** --physics forces physics, --classic forces BM25+cosine, else physics unless the config turns it off. */
-export declare function engineFlags(flags: CliFlags, config: HippoConfig): EngineFlags;
-/**
- * Detached worker that counts re-reads, runs sleep, then capture. Invoked via the internal
- * `__session-end-worker` subcommand (not user-facing). Failures in one stage
- * do 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 snapshot-close step in
- * `cmdSessionEndWorker`. `cmdSleep`/`cmdCapture` each tee console output to
- * `logFile` only for their own duration (the tee is restored before this
- * runs), so a plain `console.log` here would be silently discarded under
- * the detached worker's `stdio: 'ignore'` — write straight to the file
- * instead, matching capture.ts's `appendPreCompactLog` convention.
- */
-export declare function appendSessionEndCloseLog(logFile: string | null, message: string, opts?: {
-    startFresh?: boolean;
-}): void;
-export declare function printActiveTaskSnapshot(snapshot: TaskSnapshot): void;
-export declare function printSessionEvents(events: SessionEvent[]): void;
-export declare function printHandoff(handoff: SessionHandoff): void;
-export declare function cardStringFlag(flags: Record<string, string | boolean | string[]>, key: string): string | undefined;
-export declare function hostSessionId(): string | undefined;
-/**
- * Compaction drops the pinned blocks the per-prompt hook injected
- * earlier, so record a `reset` for the payload's session and the next prompt
- * injects again even if nothing changed. `requiredSource` limits it to hook
- * payloads with that `source` (SessionStart fires for other reasons too).
- * Best-effort and silent: a malformed payload records nothing.
- */
-export declare function resetHookInjection(hippoRoot: string, stdinText: string | undefined, requiredSource: string | null): void;
-/**
- * Run `fn` with console.log captured; returns the captured lines joined by
- * newlines (what the same calls would have printed, minus the final newline).
- */
-export declare function captureConsole(fn: () => void): string;
-/**
- * The store a Claude Code hook writes to: the project store when there is
- * one, else an existing global store, else the project path (which the hook
- * then skips, since hooks fire in every directory and must not create one).
- * Pre-compact and compact-resume must agree, or a snapshot saved to one store
- * is looked for in the other.
- */
-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 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;
-export declare function learnFromRepo(hippoRoot: string, repoPath: string, days: number, label?: string): {
+interface LearnFromRepoResult {
     added: number;
     skipped: number;
     lowInfo: number;
-};
-export declare function resolveAuthRoot(hippoRoot: string, flags: Record<string, string | boolean | string[]>): 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;
+}
+export declare function learnFromRepo(hippoRoot: string, repoPath: string, days: number, label?: string): LearnFromRepoResult;
+export declare function resolveAuthRoot(hippoRoot: string, flags: CliFlags): string;
+export {};
 //# sourceMappingURL=shared.d.ts.map