hippo-memory 1.70.0 → 1.72.0

package/dist/cli/continuity.d.ts

@@ -1,7 +1,7 @@
-import { type CliFlags } from './flag-values.js';
-export declare function cmdSnapshot(hippoRoot: string, args: string[], flags: CliFlags): void;
-export declare function cmdSession(hippoRoot: string, args: string[], flags: CliFlags): void;
-export declare function cmdHandoff(hippoRoot: string, args: string[], flags: CliFlags): void;
-export declare function cmdCurrent(hippoRoot: string, args: string[], flags: CliFlags): void;
-export declare function cmdWm(hippoRoot: string, args: string[], flags: CliFlags): void;
+import { type CommandContext } from './flag-values.js';
+export declare function handleSnapshot({ hippoRoot, tenantId, args, flags }: CommandContext): void;
+export declare function handleSession({ hippoRoot, tenantId, args, flags }: CommandContext): void;
+export declare function handleHandoff({ hippoRoot, tenantId, args, flags }: CommandContext): void;
+export declare function handleCurrent({ hippoRoot, tenantId, args, flags }: CommandContext): void;
+export declare function handleWm({ hippoRoot, tenantId, args, flags }: CommandContext): void;
 //# sourceMappingURL=continuity.d.ts.map

package/dist/cli/continuity.js

@@ -1,25 +1,24 @@
 // Where-you-left-off verbs: snapshot, session, handoff, current and working memory.
-import { saveActiveTaskSnapshot, loadActiveTaskSnapshot, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, } from '../store/sessions.js';
-import { saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome } from '../store/handoffs.js';
+import { snapshotSave as apiSnapshotSave, snapshotClear as apiSnapshotClear, snapshotLoad, sessionEventAppend, sessionEventList, continuityLatest, handoffStampOutcome, handoffSave, handoffLatest as apiHandoffLatest, handoffById, workingMemoryPush, workingMemoryRead, workingMemoryClear, workingMemoryFlush, } from '../api/continuity.js';
+import { cliApiContext } from './api-context.js';
 import { isHandoffOutcome, formatHandoffEvidenceLine } from '../core/handoff.js';
-import { resolveTenantId } from '../store/tenant.js';
-import { wmPush, wmRead, wmClear, wmFlush } from '../store/working-memory.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 } from './flag-values.js';
+import { boolFlag, isStringFlag, numberFlag } from './flag-values.js';
+import { CliExit } from './exit.js';
 const ISO_DATETIME_CHARS = 19;
-function snapshotSave(hippoRoot, flags) {
+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();
     if (!task || !summary || !nextStep) {
         printError('Usage: hippo snapshot save --task <task> --summary <summary> --next-step <step> [--source <source>] [--session <session-id>]');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const snapshot = saveActiveTaskSnapshot(hippoRoot, resolveTenantId({}), {
+    const snapshot = apiSnapshotSave(cliApiContext(hippoRoot, tenantId), {
         task,
         summary,
         next_step: nextStep,
@@ -33,16 +32,16 @@ function snapshotSave(hippoRoot, flags) {
         console.log(`   Session: ${snapshot.session_id}`);
     }
 }
-function snapshotClear(hippoRoot, flags) {
-    const cleared = clearActiveTaskSnapshot(hippoRoot, resolveTenantId({}), String(flags['status'] ?? 'cleared'));
+function snapshotClear(hippoRoot, tenantId, flags) {
+    const cleared = apiSnapshotClear(cliApiContext(hippoRoot, tenantId), String(flags['status'] ?? 'cleared'));
     if (!cleared) {
         console.log('No active task snapshot to clear.');
         return;
     }
     console.log('Cleared active task snapshot.');
 }
-function snapshotShow(hippoRoot, flags) {
-    const snapshot = loadActiveTaskSnapshot(hippoRoot, resolveTenantId({}));
+function snapshotShow(hippoRoot, tenantId, flags) {
+    const snapshot = snapshotLoad(cliApiContext(hippoRoot, tenantId));
     if (!snapshot) {
         if (flags['json']) {
             console.log(JSON.stringify({ snapshot: null }));
@@ -58,26 +57,26 @@ function snapshotShow(hippoRoot, flags) {
     }
     printActiveTaskSnapshot(snapshot);
 }
-export function cmdSnapshot(hippoRoot, args, flags) {
+export function handleSnapshot({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'show';
     if (subcommand === 'save')
-        return snapshotSave(hippoRoot, flags);
+        return snapshotSave(hippoRoot, tenantId, flags);
     if (subcommand === 'clear')
-        return snapshotClear(hippoRoot, flags);
+        return snapshotClear(hippoRoot, tenantId, flags);
     if (subcommand === 'show')
-        return snapshotShow(hippoRoot, flags);
+        return snapshotShow(hippoRoot, tenantId, flags);
     printError('Usage: hippo snapshot <save|show|clear>');
-    process.exit(1);
+    throw new CliExit(1);
 }
-function sessionLog(hippoRoot, s, flags) {
+function sessionLog(hippoRoot, tenantId, s, flags) {
     const eventType = String(flags['type'] ?? 'note').trim();
     const content = String(flags['content'] ?? '').trim();
     if (!s.sessionId || !content) {
         printError('Usage: hippo session log --id <session-id> --content <text> [--type <type>] [--task <task>] [--source <source>]');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const event = appendSessionEvent(hippoRoot, resolveTenantId({}), {
+    const event = sessionEventAppend(cliApiContext(hippoRoot, tenantId), {
         session_id: s.sessionId,
         task: s.task || null,
         event_type: eventType || 'note',
@@ -88,8 +87,8 @@ function sessionLog(hippoRoot, s, flags) {
     console.log(`   Session: ${event.session_id}`);
     console.log(`   Type: ${event.event_type}`);
 }
-function sessionShow(hippoRoot, s, flags) {
-    const events = listSessionEvents(hippoRoot, resolveTenantId({}), {
+function sessionShow(hippoRoot, tenantId, s, flags) {
+    const events = sessionEventList(cliApiContext(hippoRoot, tenantId), {
         session_id: s.sessionId || undefined,
         task: s.task || undefined,
         limit: s.limit,
@@ -100,10 +99,9 @@ function sessionShow(hippoRoot, s, flags) {
     }
     printSessionEvents(events);
 }
-function sessionLatest(hippoRoot, s, flags) {
-    const snapshot = loadActiveTaskSnapshot(hippoRoot, resolveTenantId({}));
-    const events = listSessionEvents(hippoRoot, resolveTenantId({}), {
-        session_id: s.sessionId || snapshot?.session_id || undefined,
+function sessionLatest(hippoRoot, tenantId, s, flags) {
+    const { snapshot, events } = continuityLatest(cliApiContext(hippoRoot, tenantId), {
+        sessionId: s.sessionId,
         limit: s.limit,
     });
     if (flags['json']) {
@@ -119,23 +117,23 @@ function sessionLatest(hippoRoot, s, flags) {
     }
     printSessionEvents(events);
 }
-function sessionComplete(hippoRoot, s, flags) {
+function sessionComplete(hippoRoot, tenantId, s, flags) {
     const { sessionId, task } = s;
     const outcomeRaw = String(flags['outcome'] ?? '').trim();
     const summary = String(flags['summary'] ?? '').trim();
     if (!sessionId) {
         printError('Usage: hippo session complete --session <session-id> --outcome <success|failure|partial> [--summary "..."]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (!isHandoffOutcome(outcomeRaw)) {
         printError(`Invalid outcome: "${outcomeRaw}". Must be one of: success, failure, partial.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const outcome = outcomeRaw;
     const metadata = { ended_at: new Date().toISOString() };
     if (summary)
         metadata.summary = summary;
-    const event = appendSessionEvent(hippoRoot, resolveTenantId({}), {
+    const event = sessionEventAppend(cliApiContext(hippoRoot, tenantId), {
         session_id: sessionId,
         task: task || null,
         event_type: 'session_complete',
@@ -144,33 +142,33 @@ function sessionComplete(hippoRoot, s, flags) {
         metadata,
     });
     console.log(`Completed session ${event.session_id} with outcome=${outcome} (event #${event.id})`);
-    const stamped = stampHandoffOutcome(hippoRoot, resolveTenantId({}), sessionId, outcome);
+    const stamped = handoffStampOutcome(cliApiContext(hippoRoot, tenantId), sessionId, outcome);
     if (stamped > 0) {
         console.log(`Stamped outcome on handoff for session ${sessionId}`);
     }
 }
-export function cmdSession(hippoRoot, args, flags) {
+export 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 limit = Math.max(1, parseInt(String(flags['limit'] ?? '8'), 10) || 8);
+    const limit = Math.max(1, numberFlag(flags, 'limit') || 8);
     const s = { sessionId, task, limit };
     if (subcommand === 'log')
-        return sessionLog(hippoRoot, s, flags);
+        return sessionLog(hippoRoot, tenantId, s, flags);
     if (subcommand === 'show')
-        return sessionShow(hippoRoot, s, flags);
+        return sessionShow(hippoRoot, tenantId, s, flags);
     if (subcommand === 'latest')
-        return sessionLatest(hippoRoot, s, flags);
+        return sessionLatest(hippoRoot, tenantId, s, flags);
     if (subcommand === 'complete')
-        return sessionComplete(hippoRoot, s, flags);
+        return sessionComplete(hippoRoot, tenantId, s, flags);
     if (subcommand === 'resume')
-        return sessionResume(hippoRoot, sessionId);
+        return sessionResume(hippoRoot, tenantId, sessionId);
     printError('Usage: hippo session <log|show|latest|resume|complete>');
-    process.exit(1);
+    throw new CliExit(1);
 }
-function sessionResume(hippoRoot, sessionId) {
-    const handoff = loadLatestHandoff(hippoRoot, resolveTenantId({}), sessionId || undefined);
+function sessionResume(hippoRoot, tenantId, sessionId) {
+    const handoff = apiHandoffLatest(cliApiContext(hippoRoot, tenantId), sessionId || undefined);
     if (!handoff) {
         console.log('No handoff to resume from.');
         return;
@@ -215,18 +213,21 @@ function sessionResume(hippoRoot, sessionId) {
 }
 /** A repeatable flag as a list: absent is empty, one value is a singleton. */
 function flagList(value) {
-    return Array.isArray(value) ? value : (typeof value === 'string' ? [value] : []);
+    return Array.isArray(value) ? value : (isStringFlag(value) ? [value] : []);
 }
-function handoffCreate(hippoRoot, flags) {
+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();
     if (!summary) {
-        printError('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>]');
-        process.exit(1);
+        printError(HANDOFF_CREATE_USAGE);
+        throw new CliExit(1);
     }
     const outcomeRaw = flags['outcome'];
     if (outcomeRaw !== undefined && !isHandoffOutcome(outcomeRaw)) {
         printError(`Invalid outcome: "${String(outcomeRaw)}". Must be one of: success, failure, partial.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const sessionId = String(flags['session'] ?? flags['id'] ?? '').trim() || `fallback-${Date.now()}-${process.pid}`;
     const nextAction = String(flags['next'] ?? '').trim() || undefined;
@@ -237,14 +238,14 @@ function handoffCreate(hippoRoot, flags) {
         // parseArgs turns a value-less flag into `true`; refuse rather than store "true".
         if (flags[name] === true) {
             printError(`--${name} needs a value`);
-            process.exit(1);
+            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 evidence = collectHandoffEvidence(process.cwd(), testStatus === 'pass' || testStatus === 'fail' ? testStatus : 'unknown');
-    const handoff = saveSessionHandoff(hippoRoot, resolveTenantId({}), {
+    const handoff = handoffSave(cliApiContext(hippoRoot, tenantId), {
         version: 1,
         sessionId,
         repoRoot: process.cwd(),
@@ -281,9 +282,9 @@ function printCreatedHandoff(handoff) {
     if (handoff.evidence)
         console.log(`   Evidence: ${formatHandoffEvidenceLine(handoff.evidence)}`);
 }
-function handoffLatest(hippoRoot, flags) {
+function handoffLatest(hippoRoot, tenantId, flags) {
     const sessionId = String(flags['session'] ?? flags['id'] ?? '').trim() || undefined;
-    const handoff = loadLatestHandoff(hippoRoot, resolveTenantId({}), sessionId);
+    const handoff = apiHandoffLatest(cliApiContext(hippoRoot, tenantId), sessionId);
     if (!handoff) {
         if (flags['json']) {
             console.log(JSON.stringify({ handoff: null }));
@@ -299,18 +300,18 @@ function handoffLatest(hippoRoot, flags) {
     }
     printHandoff(handoff);
 }
-function handoffShow(hippoRoot, args, flags) {
+function handoffShow(hippoRoot, tenantId, args, flags) {
     const idArg = args[1];
     if (!idArg) {
         printError('Usage: hippo handoff show <id> [--json]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const handoffId = parseInt(idArg, 10);
     if (!Number.isFinite(handoffId) || handoffId <= 0) {
         printError(`Invalid handoff ID: ${idArg}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const handoff = loadHandoffById(hippoRoot, resolveTenantId({}), handoffId);
+    const handoff = handoffById(cliApiContext(hippoRoot, tenantId), handoffId);
     if (!handoff) {
         if (flags['json']) {
             console.log(JSON.stringify({ handoff: null }));
@@ -326,17 +327,17 @@ function handoffShow(hippoRoot, args, flags) {
     }
     printHandoff(handoff);
 }
-export function cmdHandoff(hippoRoot, args, flags) {
+export function handleHandoff({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'latest';
     if (subcommand === 'create')
-        return handoffCreate(hippoRoot, flags);
+        return handoffCreate(hippoRoot, tenantId, flags);
     if (subcommand === 'latest')
-        return handoffLatest(hippoRoot, flags);
+        return handoffLatest(hippoRoot, tenantId, flags);
     if (subcommand === 'show')
-        return handoffShow(hippoRoot, args, flags);
+        return handoffShow(hippoRoot, tenantId, args, flags);
     printError('Usage: hippo handoff <create|latest|show>');
-    process.exit(1);
+    throw new CliExit(1);
 }
 function printCurrentState(snapshot, events) {
     console.log('# Current State\n');
@@ -361,14 +362,9 @@ function printCurrentState(snapshot, events) {
         }
     }
 }
-function currentShow(hippoRoot, flags) {
+function currentShow(hippoRoot, tenantId, flags) {
     const asJson = boolFlag(flags, 'json');
-    const snapshot = loadActiveTaskSnapshot(hippoRoot, resolveTenantId({}));
-    const sessionId = snapshot?.session_id ?? undefined;
-    const events = listSessionEvents(hippoRoot, resolveTenantId({}), {
-        session_id: sessionId,
-        limit: 5,
-    });
+    const { snapshot, events } = continuityLatest(cliApiContext(hippoRoot, tenantId), { limit: 5 });
     if (asJson) {
         console.log(JSON.stringify({
             snapshot: snapshot ?? null,
@@ -388,65 +384,64 @@ function currentShow(hippoRoot, flags) {
     }
     printCurrentState(snapshot, events);
 }
-export function cmdCurrent(hippoRoot, args, flags) {
+export function handleCurrent({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'show';
     if (subcommand === 'show')
-        return currentShow(hippoRoot, flags);
+        return currentShow(hippoRoot, tenantId, flags);
     printError('Usage: hippo current <show>');
-    process.exit(1);
+    throw new CliExit(1);
 }
-// ---------------------------------------------------------------------------
 // Working Memory
-// ---------------------------------------------------------------------------
-export function cmdWm(hippoRoot, args, flags) {
+export function handleWm({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? '';
     if (subcommand === 'push')
-        return wmPushCmd(hippoRoot, flags);
+        return wmPushCmd(hippoRoot, tenantId, flags);
     if (subcommand === 'read')
-        return wmReadCmd(hippoRoot, flags);
+        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 = wmClear(hippoRoot, { scope, sessionId });
+        const count = 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 = wmFlush(hippoRoot, { scope, sessionId });
+        const count = workingMemoryFlush(cliApiContext(hippoRoot, tenantId), { scope, sessionId });
         console.log(`Flushed ${count} working memory entries.`);
         return;
     }
     printError('Usage: hippo wm <push|read|clear|flush>');
-    process.exit(1);
+    throw new CliExit(1);
 }
-function wmPushCmd(hippoRoot, flags) {
+const WM_DEFAULT_IMPORTANCE = 0.5;
+function wmPushCmd(hippoRoot, tenantId, flags) {
     const scope = String(flags['scope'] ?? 'default').trim();
     const content = String(flags['content'] ?? '').trim();
-    const importance = parseFloat(String(flags['importance'] ?? '0.5'));
+    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;
     if (!content) {
         printError('Usage: hippo wm push --scope <scope> --content "..." [--importance 0.8] [--session <id>] [--task <id>]');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const id = wmPush(hippoRoot, {
+    const id = workingMemoryPush(cliApiContext(hippoRoot, tenantId), {
         scope,
         content,
-        importance: Number.isFinite(importance) ? importance : 0.5,
+        importance,
         sessionId,
         taskId,
     });
-    console.log(`Pushed working memory #${id} (scope=${scope}, importance=${Number.isFinite(importance) ? importance : 0.5})`);
+    console.log(`Pushed working memory #${id} (scope=${scope}, importance=${importance})`);
 }
-function wmReadCmd(hippoRoot, flags) {
+function wmReadCmd(hippoRoot, tenantId, flags) {
     const scope = flags['scope'] ? String(flags['scope']).trim() : undefined;
     const sessionId = flags['session'] ? String(flags['session']).trim() : undefined;
-    const limit = parseInt(String(flags['limit'] ?? '20'), 10) || 20;
-    const items = wmRead(hippoRoot, { scope, sessionId, limit });
+    const limit = numberFlag(flags, 'limit') || 20;
+    const items = 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,19 +1,15 @@
-import { type CliFlags, type CommandContext } from './flag-values.js';
-export declare function cmdOutcome(hippoRoot: string, flags: CliFlags): void;
-export declare function cmdConflicts(hippoRoot: string, flags: CliFlags): void;
-export declare function cmdResolve(hippoRoot: string, args: string[], flags: CliFlags): void;
-export declare function cmdReject(hippoRoot: string, args: string[], flags: CliFlags): void;
-export declare function cmdRejections(hippoRoot: string, flags: CliFlags): void;
-export declare function cmdUnreject(hippoRoot: string, args: string[], flags: CliFlags): void;
-/**
- * `hippo dormant [list] [<query>...] [--limit <n>] [--json] [--global]`,
- * `hippo dormant restore <id>`, `hippo dormant 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 cmdDormant(hippoRoot: string, args: string[], flags: CliFlags): void;
+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 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 cmdQuarantine(hippoRoot: string, args: string[], flags: CliFlags): Promise<void>;
-export declare function handleForget({ hippoRoot, args, flags }: CommandContext): Promise<void>;
-export declare function handleInvalidate({ hippoRoot, args, flags }: CommandContext): void;
+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;
 //# sourceMappingURL=curate.d.ts.map