hippo-memory 1.72.0 → 2.1.0

package/dist/cli/continuity.js

@@ -3,26 +3,25 @@ import { snapshotSave as apiSnapshotSave, snapshotClear as apiSnapshotClear, sna
 import { cliApiContext } from './api-context.js';
 import { isHandoffOutcome, formatHandoffEvidenceLine } from '../core/handoff.js';
 import { collectHandoffEvidence } from '../capture/handoff-evidence.js';
-import { printError } from './output.js';
 import { requireInit } from './shared.js';
 import { printActiveTaskSnapshot, printSessionEvents, printHandoff } from './print.js';
-import { boolFlag, isStringFlag, numberFlag } from './flag-values.js';
-import { CliExit } from './exit.js';
+import { boolFlag, isStringFlag, numberFlag, stringFlagOrExit, } from './flag-values.js';
+import { fail } from './exit.js';
 const ISO_DATETIME_CHARS = 19;
-function snapshotSave(hippoRoot, tenantId, flags) {
-    const task = String(flags['task'] ?? '').trim();
-    const summary = String(flags['summary'] ?? '').trim();
-    const nextStep = String(flags['next-step'] ?? '').trim();
-    const sessionId = String(flags['session'] ?? flags['id'] ?? '').trim();
+async function snapshotSave(hippoRoot, tenantId, flags) {
+    const task = stringFlagOrExit(flags, 'task') ?? '';
+    const summary = stringFlagOrExit(flags, 'summary') ?? '';
+    const nextStep = stringFlagOrExit(flags, 'next-step') ?? '';
+    const sessionId = stringFlagOrExit(flags, 'session') ?? stringFlagOrExit(flags, 'id') ?? '';
     if (!task || !summary || !nextStep) {
-        printError('Usage: hippo snapshot save --task <task> --summary <summary> --next-step <step> [--source <source>] [--session <session-id>]');
-        throw new CliExit(1);
+        fail('Usage: hippo snapshot save --task <task> --summary <summary> --next-step <step> ' +
+            '[--source <source>] [--session <session-id>]');
     }
-    const snapshot = apiSnapshotSave(cliApiContext(hippoRoot, tenantId), {
+    const snapshot = await apiSnapshotSave(cliApiContext(hippoRoot, tenantId), {
         task,
         summary,
         next_step: nextStep,
-        source: String(flags['source'] ?? 'cli'),
+        source: stringFlagOrExit(flags, 'source') ?? 'cli',
         session_id: sessionId || null,
     });
     console.log(`Saved active task snapshot #${snapshot.id}`);
@@ -32,16 +31,17 @@ function snapshotSave(hippoRoot, tenantId, flags) {
         console.log(`   Session: ${snapshot.session_id}`);
     }
 }
-function snapshotClear(hippoRoot, tenantId, flags) {
-    const cleared = apiSnapshotClear(cliApiContext(hippoRoot, tenantId), String(flags['status'] ?? 'cleared'));
+async function snapshotClear(hippoRoot, tenantId, flags) {
+    const status = stringFlagOrExit(flags, 'status') ?? 'cleared';
+    const cleared = await apiSnapshotClear(cliApiContext(hippoRoot, tenantId), status);
     if (!cleared) {
         console.log('No active task snapshot to clear.');
         return;
     }
     console.log('Cleared active task snapshot.');
 }
-function snapshotShow(hippoRoot, tenantId, flags) {
-    const snapshot = snapshotLoad(cliApiContext(hippoRoot, tenantId));
+async function snapshotShow(hippoRoot, tenantId, flags) {
+    const snapshot = await snapshotLoad(cliApiContext(hippoRoot, tenantId));
     if (!snapshot) {
         if (flags['json']) {
             console.log(JSON.stringify({ snapshot: null }));
@@ -57,7 +57,7 @@ function snapshotShow(hippoRoot, tenantId, flags) {
     }
     printActiveTaskSnapshot(snapshot);
 }
-export function handleSnapshot({ hippoRoot, tenantId, args, flags }) {
+export async function handleSnapshot({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'show';
     if (subcommand === 'save')
@@ -66,30 +66,29 @@ export function handleSnapshot({ hippoRoot, tenantId, args, flags }) {
         return snapshotClear(hippoRoot, tenantId, flags);
     if (subcommand === 'show')
         return snapshotShow(hippoRoot, tenantId, flags);
-    printError('Usage: hippo snapshot <save|show|clear>');
-    throw new CliExit(1);
+    fail('Usage: hippo snapshot <save|show|clear>');
 }
-function sessionLog(hippoRoot, tenantId, s, flags) {
-    const eventType = String(flags['type'] ?? 'note').trim();
-    const content = String(flags['content'] ?? '').trim();
+async function sessionLog(hippoRoot, tenantId, s, flags) {
+    const eventType = stringFlagOrExit(flags, 'type') ?? 'note';
+    const content = stringFlagOrExit(flags, 'content') ?? '';
     if (!s.sessionId || !content) {
-        printError('Usage: hippo session log --id <session-id> --content <text> [--type <type>] [--task <task>] [--source <source>]');
-        throw new CliExit(1);
+        fail('Usage: hippo session log --id <session-id> --content <text> [--type <type>] [--task <task>] ' +
+            '[--source <source>]');
     }
-    const event = sessionEventAppend(cliApiContext(hippoRoot, tenantId), {
+    const event = await sessionEventAppend(cliApiContext(hippoRoot, tenantId), {
         session_id: s.sessionId,
         task: s.task || null,
         event_type: eventType || 'note',
         content,
-        source: String(flags['source'] ?? 'cli'),
+        source: stringFlagOrExit(flags, 'source') ?? 'cli',
     });
     console.log(`Logged session event #${event.id}`);
     console.log(`   Session: ${event.session_id}`);
     console.log(`   Type: ${event.event_type}`);
 }
-function sessionShow(hippoRoot, tenantId, s, flags) {
-    const events = sessionEventList(cliApiContext(hippoRoot, tenantId), {
-        session_id: s.sessionId || undefined,
+async function sessionShow(hippoRoot, tenantId, s, flags) {
+    const events = await sessionEventList(cliApiContext(hippoRoot, tenantId), {
+        sessionId: s.sessionId || undefined,
         task: s.task || undefined,
         limit: s.limit,
     });
@@ -99,8 +98,8 @@ function sessionShow(hippoRoot, tenantId, s, flags) {
     }
     printSessionEvents(events);
 }
-function sessionLatest(hippoRoot, tenantId, s, flags) {
-    const { snapshot, events } = continuityLatest(cliApiContext(hippoRoot, tenantId), {
+async function sessionLatest(hippoRoot, tenantId, s, flags) {
+    const { snapshot, events } = await continuityLatest(cliApiContext(hippoRoot, tenantId), {
         sessionId: s.sessionId,
         limit: s.limit,
     });
@@ -117,41 +116,39 @@ function sessionLatest(hippoRoot, tenantId, s, flags) {
     }
     printSessionEvents(events);
 }
-function sessionComplete(hippoRoot, tenantId, s, flags) {
+async function sessionComplete(hippoRoot, tenantId, s, flags) {
     const { sessionId, task } = s;
-    const outcomeRaw = String(flags['outcome'] ?? '').trim();
-    const summary = String(flags['summary'] ?? '').trim();
+    const outcomeRaw = stringFlagOrExit(flags, 'outcome') ?? '';
+    const summary = stringFlagOrExit(flags, 'summary') ?? '';
     if (!sessionId) {
-        printError('Usage: hippo session complete --session <session-id> --outcome <success|failure|partial> [--summary "..."]');
-        throw new CliExit(1);
+        fail('Usage: hippo session complete --session <session-id> --outcome <success|failure|partial> [--summary "..."]');
     }
     if (!isHandoffOutcome(outcomeRaw)) {
-        printError(`Invalid outcome: "${outcomeRaw}". Must be one of: success, failure, partial.`);
-        throw new CliExit(1);
+        fail(`Invalid outcome: "${outcomeRaw}". Must be one of: success, failure, partial.`);
     }
     const outcome = outcomeRaw;
     const metadata = { ended_at: new Date().toISOString() };
     if (summary)
         metadata.summary = summary;
-    const event = sessionEventAppend(cliApiContext(hippoRoot, tenantId), {
+    const event = await sessionEventAppend(cliApiContext(hippoRoot, tenantId), {
         session_id: sessionId,
         task: task || null,
         event_type: 'session_complete',
         content: outcome,
-        source: String(flags['source'] ?? 'cli'),
+        source: stringFlagOrExit(flags, 'source') ?? 'cli',
         metadata,
     });
     console.log(`Completed session ${event.session_id} with outcome=${outcome} (event #${event.id})`);
-    const stamped = handoffStampOutcome(cliApiContext(hippoRoot, tenantId), sessionId, outcome);
+    const stamped = await handoffStampOutcome(cliApiContext(hippoRoot, tenantId), sessionId, outcome);
     if (stamped > 0) {
         console.log(`Stamped outcome on handoff for session ${sessionId}`);
     }
 }
-export function handleSession({ hippoRoot, tenantId, args, flags }) {
+export async function handleSession({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'show';
-    const sessionId = String(flags['id'] ?? flags['session'] ?? '').trim();
-    const task = String(flags['task'] ?? '').trim();
+    const sessionId = stringFlagOrExit(flags, 'id') ?? stringFlagOrExit(flags, 'session') ?? '';
+    const task = stringFlagOrExit(flags, 'task') ?? '';
     const limit = Math.max(1, numberFlag(flags, 'limit') || 8);
     const s = { sessionId, task, limit };
     if (subcommand === 'log')
@@ -164,11 +161,10 @@ export function handleSession({ hippoRoot, tenantId, args, flags }) {
         return sessionComplete(hippoRoot, tenantId, s, flags);
     if (subcommand === 'resume')
         return sessionResume(hippoRoot, tenantId, sessionId);
-    printError('Usage: hippo session <log|show|latest|resume|complete>');
-    throw new CliExit(1);
+    fail('Usage: hippo session <log|show|latest|resume|complete>');
 }
-function sessionResume(hippoRoot, tenantId, sessionId) {
-    const handoff = apiHandoffLatest(cliApiContext(hippoRoot, tenantId), sessionId || undefined);
+async function sessionResume(hippoRoot, tenantId, sessionId) {
+    const handoff = await apiHandoffLatest(cliApiContext(hippoRoot, tenantId), sessionId || undefined);
     if (!handoff) {
         console.log('No handoff to resume from.');
         return;
@@ -215,37 +211,30 @@ function sessionResume(hippoRoot, tenantId, sessionId) {
 function flagList(value) {
     return Array.isArray(value) ? value : (isStringFlag(value) ? [value] : []);
 }
-const HANDOFF_CREATE_USAGE = 'Usage: hippo handoff create --summary "..." [--next "..."] [--session <id>] [--task <id>] [--artifact <path>...] ' +
+const HANDOFF_CREATE_USAGE = 'Usage: hippo handoff create --summary "..." [--next "..."] [--session <id>] ' +
+    '[--task <id>] [--artifact <path>...] ' +
     '[--constraint <text>...] [--outcome <success|failure|partial>] [--target-runtime <name>] [--card-id <id>] ' +
     '[--tests <pass|fail|unknown>]';
-function handoffCreate(hippoRoot, tenantId, flags) {
-    const summary = String(flags['summary'] ?? '').trim();
+async function handoffCreate(hippoRoot, tenantId, flags) {
+    const summary = stringFlagOrExit(flags, 'summary') ?? '';
     if (!summary) {
-        printError(HANDOFF_CREATE_USAGE);
-        throw new CliExit(1);
+        fail(HANDOFF_CREATE_USAGE);
     }
     const outcomeRaw = flags['outcome'];
     if (outcomeRaw !== undefined && !isHandoffOutcome(outcomeRaw)) {
-        printError(`Invalid outcome: "${String(outcomeRaw)}". Must be one of: success, failure, partial.`);
-        throw new CliExit(1);
+        fail(`Invalid outcome: "${String(outcomeRaw)}". Must be one of: success, failure, partial.`);
     }
-    const sessionId = String(flags['session'] ?? flags['id'] ?? '').trim() || `fallback-${Date.now()}-${process.pid}`;
-    const nextAction = String(flags['next'] ?? '').trim() || undefined;
-    const taskId = String(flags['task'] ?? '').trim() || undefined;
+    const sessionId = (stringFlagOrExit(flags, 'session') ?? stringFlagOrExit(flags, 'id') ?? '') ||
+        `fallback-${Date.now()}-${process.pid}`;
+    const nextAction = stringFlagOrExit(flags, 'next') || undefined;
+    const taskId = stringFlagOrExit(flags, 'task') || undefined;
     const artifacts = flagList(flags['artifact']);
     const constraints = flagList(flags['constraint']);
-    for (const name of ['target-runtime', 'card-id']) {
-        // parseArgs turns a value-less flag into `true`; refuse rather than store "true".
-        if (flags[name] === true) {
-            printError(`--${name} needs a value`);
-            throw new CliExit(1);
-        }
-    }
-    const targetRuntime = String(flags['target-runtime'] ?? '').trim() || undefined;
-    const cardId = String(flags['card-id'] ?? '').trim() || undefined;
-    const testStatus = String(flags['tests'] ?? '').trim();
+    const targetRuntime = stringFlagOrExit(flags, 'target-runtime') || undefined;
+    const cardId = stringFlagOrExit(flags, 'card-id') || undefined;
+    const testStatus = stringFlagOrExit(flags, 'tests') ?? '';
     const evidence = collectHandoffEvidence(process.cwd(), testStatus === 'pass' || testStatus === 'fail' ? testStatus : 'unknown');
-    const handoff = handoffSave(cliApiContext(hippoRoot, tenantId), {
+    const handoff = await handoffSave(cliApiContext(hippoRoot, tenantId), {
         version: 1,
         sessionId,
         repoRoot: process.cwd(),
@@ -282,9 +271,9 @@ function printCreatedHandoff(handoff) {
     if (handoff.evidence)
         console.log(`   Evidence: ${formatHandoffEvidenceLine(handoff.evidence)}`);
 }
-function handoffLatest(hippoRoot, tenantId, flags) {
-    const sessionId = String(flags['session'] ?? flags['id'] ?? '').trim() || undefined;
-    const handoff = apiHandoffLatest(cliApiContext(hippoRoot, tenantId), sessionId);
+async function handoffLatest(hippoRoot, tenantId, flags) {
+    const sessionId = (stringFlagOrExit(flags, 'session') ?? stringFlagOrExit(flags, 'id') ?? '') || undefined;
+    const handoff = await apiHandoffLatest(cliApiContext(hippoRoot, tenantId), sessionId);
     if (!handoff) {
         if (flags['json']) {
             console.log(JSON.stringify({ handoff: null }));
@@ -300,18 +289,16 @@ function handoffLatest(hippoRoot, tenantId, flags) {
     }
     printHandoff(handoff);
 }
-function handoffShow(hippoRoot, tenantId, args, flags) {
+async function handoffShow(hippoRoot, tenantId, args, flags) {
     const idArg = args[1];
     if (!idArg) {
-        printError('Usage: hippo handoff show <id> [--json]');
-        throw new CliExit(1);
+        fail('Usage: hippo handoff show <id> [--json]');
     }
     const handoffId = parseInt(idArg, 10);
     if (!Number.isFinite(handoffId) || handoffId <= 0) {
-        printError(`Invalid handoff ID: ${idArg}`);
-        throw new CliExit(1);
+        fail(`Invalid handoff ID: ${idArg}`);
     }
-    const handoff = handoffById(cliApiContext(hippoRoot, tenantId), handoffId);
+    const handoff = await handoffById(cliApiContext(hippoRoot, tenantId), handoffId);
     if (!handoff) {
         if (flags['json']) {
             console.log(JSON.stringify({ handoff: null }));
@@ -327,7 +314,7 @@ function handoffShow(hippoRoot, tenantId, args, flags) {
     }
     printHandoff(handoff);
 }
-export function handleHandoff({ hippoRoot, tenantId, args, flags }) {
+export async function handleHandoff({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'latest';
     if (subcommand === 'create')
@@ -336,8 +323,7 @@ export function handleHandoff({ hippoRoot, tenantId, args, flags }) {
         return handoffLatest(hippoRoot, tenantId, flags);
     if (subcommand === 'show')
         return handoffShow(hippoRoot, tenantId, args, flags);
-    printError('Usage: hippo handoff <create|latest|show>');
-    throw new CliExit(1);
+    fail('Usage: hippo handoff <create|latest|show>');
 }
 function printCurrentState(snapshot, events) {
     console.log('# Current State\n');
@@ -362,9 +348,9 @@ function printCurrentState(snapshot, events) {
         }
     }
 }
-function currentShow(hippoRoot, tenantId, flags) {
+async function currentShow(hippoRoot, tenantId, flags) {
     const asJson = boolFlag(flags, 'json');
-    const { snapshot, events } = continuityLatest(cliApiContext(hippoRoot, tenantId), { limit: 5 });
+    const { snapshot, events } = await continuityLatest(cliApiContext(hippoRoot, tenantId), { limit: 5 });
     if (asJson) {
         console.log(JSON.stringify({
             snapshot: snapshot ?? null,
@@ -384,16 +370,15 @@ function currentShow(hippoRoot, tenantId, flags) {
     }
     printCurrentState(snapshot, events);
 }
-export function handleCurrent({ hippoRoot, tenantId, args, flags }) {
+export async function handleCurrent({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'show';
     if (subcommand === 'show')
         return currentShow(hippoRoot, tenantId, flags);
-    printError('Usage: hippo current <show>');
-    throw new CliExit(1);
+    fail('Usage: hippo current <show>');
 }
 // Working Memory
-export function handleWm({ hippoRoot, tenantId, args, flags }) {
+export async function handleWm({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? '';
     if (subcommand === 'push')
@@ -401,34 +386,32 @@ export function handleWm({ hippoRoot, tenantId, args, flags }) {
     if (subcommand === 'read')
         return wmReadCmd(hippoRoot, tenantId, flags);
     if (subcommand === 'clear') {
-        const scope = flags['scope'] ? String(flags['scope']).trim() : undefined;
-        const sessionId = flags['session'] ? String(flags['session']).trim() : undefined;
-        const count = workingMemoryClear(cliApiContext(hippoRoot, tenantId), { scope, sessionId });
+        const scope = stringFlagOrExit(flags, 'scope') || undefined;
+        const sessionId = stringFlagOrExit(flags, 'session') || undefined;
+        const count = await workingMemoryClear(cliApiContext(hippoRoot, tenantId), { scope, sessionId });
         console.log(`Cleared ${count} working memory entries.`);
         return;
     }
     if (subcommand === 'flush') {
-        const scope = flags['scope'] ? String(flags['scope']).trim() : undefined;
-        const sessionId = flags['session'] ? String(flags['session']).trim() : undefined;
-        const count = workingMemoryFlush(cliApiContext(hippoRoot, tenantId), { scope, sessionId });
+        const scope = stringFlagOrExit(flags, 'scope') || undefined;
+        const sessionId = stringFlagOrExit(flags, 'session') || undefined;
+        const count = await workingMemoryFlush(cliApiContext(hippoRoot, tenantId), { scope, sessionId });
         console.log(`Flushed ${count} working memory entries.`);
         return;
     }
-    printError('Usage: hippo wm <push|read|clear|flush>');
-    throw new CliExit(1);
+    fail('Usage: hippo wm <push|read|clear|flush>');
 }
 const WM_DEFAULT_IMPORTANCE = 0.5;
-function wmPushCmd(hippoRoot, tenantId, flags) {
-    const scope = String(flags['scope'] ?? 'default').trim();
-    const content = String(flags['content'] ?? '').trim();
+async function wmPushCmd(hippoRoot, tenantId, flags) {
+    const scope = stringFlagOrExit(flags, 'scope') ?? 'default';
+    const content = stringFlagOrExit(flags, 'content') ?? '';
     const importance = numberFlag(flags, 'importance') ?? WM_DEFAULT_IMPORTANCE;
-    const sessionId = flags['session'] ? String(flags['session']).trim() : undefined;
-    const taskId = flags['task'] ? String(flags['task']).trim() : undefined;
+    const sessionId = stringFlagOrExit(flags, 'session') || undefined;
+    const taskId = stringFlagOrExit(flags, 'task') || undefined;
     if (!content) {
-        printError('Usage: hippo wm push --scope <scope> --content "..." [--importance 0.8] [--session <id>] [--task <id>]');
-        throw new CliExit(1);
+        fail('Usage: hippo wm push --scope <scope> --content "..." [--importance 0.8] [--session <id>] [--task <id>]');
     }
-    const id = workingMemoryPush(cliApiContext(hippoRoot, tenantId), {
+    const id = await workingMemoryPush(cliApiContext(hippoRoot, tenantId), {
         scope,
         content,
         importance,
@@ -437,11 +420,11 @@ function wmPushCmd(hippoRoot, tenantId, flags) {
     });
     console.log(`Pushed working memory #${id} (scope=${scope}, importance=${importance})`);
 }
-function wmReadCmd(hippoRoot, tenantId, flags) {
-    const scope = flags['scope'] ? String(flags['scope']).trim() : undefined;
-    const sessionId = flags['session'] ? String(flags['session']).trim() : undefined;
+async function wmReadCmd(hippoRoot, tenantId, flags) {
+    const scope = stringFlagOrExit(flags, 'scope') || undefined;
+    const sessionId = stringFlagOrExit(flags, 'session') || undefined;
     const limit = numberFlag(flags, 'limit') || 20;
-    const items = workingMemoryRead(cliApiContext(hippoRoot, tenantId), { scope, sessionId, limit });
+    const items = await workingMemoryRead(cliApiContext(hippoRoot, tenantId), { scope, sessionId, limit });
     if (flags['json']) {
         console.log(JSON.stringify({ items }, null, 2));
         return;

package/dist/cli/curate.d.ts

@@ -1,14 +1,15 @@
 import { type CommandContext } from './flag-values.js';
-export declare function handleOutcome({ hippoRoot, tenantId, flags }: CommandContext): void;
-export declare function handleConflicts({ hippoRoot, tenantId, flags }: CommandContext): void;
+export declare function handleOutcome({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
+export declare function handleConflicts({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
 export declare function handleResolve({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 export declare function handleReject({ hippoRoot, tenantId, args, flags }: CommandContext): void;
 export declare function handleRejections({ hippoRoot, tenantId, flags }: CommandContext): void;
 export declare function handleUnreject({ hippoRoot, tenantId, args, flags }: CommandContext): void;
 /** `hippo dormant [list|restore <id>|forget <id>]`: dormant memories are what sleep keeps instead of deleting
  * (on by default; `"dormant": { "enabled": false }` in .hippo/config.json deletes instead). */
-export declare function handleDormant({ hippoRoot, tenantId, args, flags }: CommandContext): void;
-/** `hippo quarantine [list] [--all] [--json] [--global]`, `quarantine approve <id>`, `quarantine reject <id>` (poisoning defence). */
+export declare function handleDormant({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
+/** `hippo quarantine [list] [--all] [--json] [--global]`,
+ * `quarantine approve <id>`, `quarantine reject <id>` (poisoning defence). */
 export declare function handleQuarantine({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 export declare function handleForget({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 export declare function handleInvalidate({ hippoRoot, tenantId, args, flags }: CommandContext): void;