hippo-memory 0.35.0 → 0.37.0

package/dist/benchmarks/e1.3/slack-1000-event-smoke.js

@@ -0,0 +1,102 @@
+/**
+ * E1.3 1000-event Slack smoke benchmark.
+ *
+ * ROADMAP success criterion: ingest 1000 synthetic Slack events, replay each
+ * one twice, and prove (a) exactly `count` unique memories are written
+ * (idempotency holds), (b) zero outbound HTTP calls escape the connector
+ * layer, (c) per-call latency stays under 500ms.
+ *
+ * The no-outbound-HTTP invariant is proven (review patch #5) by replacing
+ * `globalThis.fetch` with a function that THROWS on any call. If a future
+ * code path inside the connector ever reaches for fetch (e.g. a user
+ * resolution shortcut), this smoke fails loud rather than silently lying
+ * with a hardcoded 0. The original fetch is restored in `finally` so the
+ * spy never poisons later tests.
+ */
+import { ingestMessage } from '../../src/connectors/slack/ingest.js';
+import { loadAllEntries } from '../../src/store.js';
+export async function runSlackSmoke(opts) {
+    const ctx = {
+        hippoRoot: opts.hippoRoot,
+        tenantId: 'default',
+        actor: 'connector:slack',
+    };
+    const start = Date.now();
+    let calls = 0;
+    // Review patch #5: spy globalThis.fetch with a throwing function. The smoke
+    // fails LOUD if anything in the ingest path ever calls fetch().
+    const origFetch = globalThis.fetch;
+    let outboundHttp = 0;
+    globalThis.fetch = ((..._args) => {
+        outboundHttp++;
+        throw new Error('outbound HTTP forbidden during slack smoke');
+    });
+    try {
+        for (let pass = 0; pass < opts.replay; pass++) {
+            for (let i = 0; i < opts.count; i++) {
+                ingestMessage(ctx, {
+                    teamId: 'T1',
+                    channel: { id: 'C1', is_private: false },
+                    message: {
+                        type: 'message',
+                        channel: 'C1',
+                        user: 'U1',
+                        // Use a content body well over the 3-char minimum enforced by
+                        // memory.ts so synthetic events survive validation.
+                        text: `slack synthetic event ${i}`,
+                        ts: `${1700000000 + i}.000100`,
+                    },
+                    eventId: `Ev-${i}`,
+                });
+                calls++;
+            }
+        }
+    }
+    finally {
+        globalThis.fetch = origFetch;
+    }
+    const uniqueMemories = loadAllEntries(opts.hippoRoot).filter((e) => e.tags.includes('source:slack')).length;
+    return {
+        uniqueMemories,
+        totalIngestCalls: calls,
+        outboundHttp,
+        durationMs: Date.now() - start,
+    };
+}
+// Standalone CLI: 1000 events, replay=2, fail loud on regression.
+// Use pathToFileURL for cross-platform `import.meta.url` matching (Windows
+// emits `file:///C:/...` which `file://${process.argv[1]}` cannot match).
+const { pathToFileURL } = await import('url');
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    const { mkdtempSync, rmSync } = await import('fs');
+    const { tmpdir } = await import('os');
+    const { join } = await import('path');
+    const { initStore } = await import('../../src/store.js');
+    const root = mkdtempSync(join(tmpdir(), 'hippo-slack-smoke-cli-'));
+    try {
+        initStore(root);
+        const r = await runSlackSmoke({ hippoRoot: root, count: 1000, replay: 2 });
+        console.log(JSON.stringify(r, null, 2));
+        if (r.uniqueMemories !== 1000) {
+            console.error('FAIL: uniqueMemories !== 1000');
+            process.exit(1);
+        }
+        if (r.outboundHttp !== 0) {
+            console.error('FAIL: outboundHttp !== 0');
+            process.exit(1);
+        }
+        if (r.totalIngestCalls !== 2000) {
+            console.error('FAIL: totalIngestCalls !== 2000');
+            process.exit(1);
+        }
+        if (r.durationMs / r.totalIngestCalls > 500) {
+            console.error('FAIL: per-call latency >500ms');
+            process.exit(1);
+        }
+        console.log('PASS');
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=slack-1000-event-smoke.js.map

package/dist/benchmarks/e1.3/slack-1000-event-smoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack-1000-event-smoke.js","sourceRoot":"","sources":["../../../benchmarks/e1.3/slack-1000-event-smoke.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -45,12 +45,15 @@ import { captureError, extractLessons, deduplicateLesson, runWatched, fetchGitLo
 import { extractInvalidationTarget, invalidateMatching } from './invalidation.js';
 import { extractPathTags } from './path-context.js';
 import { detectScope, scopeMatch } from './scope.js';
-import { getGlobalRoot, initGlobal, promoteToGlobal, shareMemory, listPeers, autoShare, transferScore, searchBothHybrid, syncGlobalToLocal, } from './shared.js';
+import { getGlobalRoot, initGlobal, shareMemory, listPeers, autoShare, transferScore, searchBothHybrid, syncGlobalToLocal, } from './shared.js';
 import { DAILY_TASK_NAME, buildDailyRunnerCommand, listRegisteredWorkspaces, registerWorkspace, runDailyMaintenance, } from './scheduler.js';
 import { importChatGPT, importClaude, importCursor, importGenericFile, importMarkdown, } from './importers.js';
 import { cmdCapture } from './capture.js';
-import { auditMemories, appendAuditEvent, queryAuditEvents, } from './audit.js';
-import { createApiKey, listApiKeys, revokeApiKey } from './auth.js';
+import { auditMemories, appendAuditEvent, } from './audit.js';
+import { listApiKeys, revokeApiKey } from './auth.js';
+import * as api from './api.js';
+import * as client from './client.js';
+import { detectServer, removePidfile } from './server-detect.js';
 import { resolveTenantId } from './tenant.js';
 import { runEval, bootstrapCorpus, compareSummaries } from './eval.js';
 import { runFeatureEval, formatResult, resultToBaseline, detectRegressions } from './eval-suite.js';
@@ -59,6 +62,9 @@ import { wmPush, wmRead, wmClear, wmFlush } from './working-memory.js';
 import { multihopSearch } from './multihop.js';
 import { computeSalience } from './salience.js';
 import { computeAmbientState, renderAmbientSummary } from './ambient.js';
+import { listDlq } from './connectors/slack/dlq.js';
+import { backfillChannel } from './connectors/slack/backfill.js';
+import { slackHistoryFetcher } from './connectors/slack/web-client.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -99,6 +105,35 @@ function requireInit(hippoRoot) {
         process.exit(1);
     }
 }
+/**
+ * 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
+ *           and the caller should fall back to the direct path.
+ *
+ * Per the A1 plan footgun #1: stale pidfiles must self-heal, not crash.
+ */
+async function runViaServerIfAvailable(hippoRoot, httpFn) {
+    const info = detectServer(hippoRoot);
+    if (!info)
+        return false;
+    const apiKey = process.env['HIPPO_API_KEY'];
+    try {
+        await httpFn(info, apiKey);
+        return true;
+    }
+    catch (err) {
+        if (client.isConnectionRefused(err)) {
+            console.error('hippo: stale server pidfile detected, falling back to direct mode');
+            removePidfile(hippoRoot);
+            return false;
+        }
+        throw err;
+    }
+}
 function parseArgs(argv) {
     const [, , command = '', ...rest] = argv;
     const args = [];
@@ -2159,12 +2194,17 @@ function cmdOutcome(hippoRoot, flags) {
 }
 function cmdForget(hippoRoot, id) {
     requireInit(hippoRoot);
-    const ok = deleteEntry(hippoRoot, id);
-    if (ok) {
+    const ctx = {
+        hippoRoot,
+        tenantId: resolveTenantId({}),
+        actor: 'cli',
+    };
+    try {
+        api.forget(ctx, id);
         updateStats(hippoRoot, { forgotten: 1 });
         console.log(`Forgot ${id}`);
     }
-    else {
+    catch {
         console.error(`Memory not found: ${id}`);
         process.exit(1);
     }
@@ -3238,14 +3278,14 @@ function cmdPromote(hippoRoot, id) {
         console.error('Usage: hippo promote <id>');
         process.exit(1);
     }
+    const ctx = {
+        hippoRoot,
+        tenantId: resolveTenantId({}),
+        actor: 'cli',
+    };
     try {
-        const globalEntry = promoteToGlobal(hippoRoot, id);
-        // Emit audit on the global store (where the promoted memory now lives).
-        // The writeEntry inside promoteToGlobal already fires a 'remember' on the
-        // global db; we add a separate 'promote' event so the audit trail keeps
-        // the user-facing intent distinct from the underlying upsert.
-        emitCliAudit(getGlobalRoot(), 'promote', globalEntry.id, { sourceId: id });
-        console.log(`Promoted ${id} to global store as ${globalEntry.id}`);
+        const result = api.promote(ctx, id);
+        console.log(`Promoted ${id} to global store as ${result.globalId}`);
         console.log(`   Global store: ${getGlobalRoot()}`);
     }
     catch (err) {
@@ -3813,21 +3853,18 @@ function cmdAuthCreate(hippoRoot, flags) {
     const root = resolveAuthRoot(hippoRoot, flags);
     const tenantFlag = typeof flags['tenant'] === 'string' ? flags['tenant'] : undefined;
     const labelFlag = typeof flags['label'] === 'string' ? flags['label'] : undefined;
-    const tenantId = tenantFlag ?? resolveTenantId({});
     const asJson = Boolean(flags['json']);
-    const db = openHippoDb(root);
-    let result;
-    try {
-        result = createApiKey(db, { tenantId, label: labelFlag });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    const ctx = {
+        hippoRoot: root,
+        tenantId: resolveTenantId({}),
+        actor: 'cli',
+    };
+    const result = api.authCreate(ctx, { tenantId: tenantFlag, label: labelFlag });
     if (asJson) {
         console.log(JSON.stringify({
             keyId: result.keyId,
             plaintext: result.plaintext,
-            tenantId,
+            tenantId: result.tenantId,
             label: labelFlag ?? null,
         }));
         return;
@@ -3969,14 +4006,8 @@ function cmdAuditList(hippoRoot, flags) {
         console.error(`--limit must be between 1 and 10000 (got ${limit}).`);
         process.exit(1);
     }
-    const db = openHippoDb(root);
-    let events;
-    try {
-        events = queryAuditEvents(db, { tenantId, op, since, limit });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    const ctx = { hippoRoot: root, tenantId, actor: 'cli' };
+    const events = api.auditList(ctx, { op, since, limit });
     if (asJson) {
         console.log(JSON.stringify(events));
         return;
@@ -4027,6 +4058,82 @@ function cmdAuth(hippoRoot, args, flags) {
             process.exit(1);
     }
 }
+// ---------------------------------------------------------------------------
+// Slack subcommands (E1.3 — `hippo slack backfill` / `hippo slack dlq list`)
+// ---------------------------------------------------------------------------
+function printSlackBackfillUsage() {
+    console.log('hippo slack backfill --channel <id> [--since ISO]');
+    console.log('  --channel  Slack channel id (required, e.g. C0123ABC)');
+    console.log('  --since    backfill from ISO timestamp (default: cursor)');
+}
+function cmdSlackBackfill(hippoRoot, flags) {
+    // M3: detect --help BEFORE token check so operators can read usage in
+    // environments without SLACK_BOT_TOKEN configured.
+    if (flags['help']) {
+        printSlackBackfillUsage();
+        return;
+    }
+    const channel = typeof flags['channel'] === 'string' ? flags['channel'] : undefined;
+    if (!channel) {
+        printSlackBackfillUsage();
+        process.exit(1);
+    }
+    // Real fetcher requires SLACK_BOT_TOKEN with channels:history scope.
+    const token = process.env.SLACK_BOT_TOKEN;
+    if (!token) {
+        console.error('SLACK_BOT_TOKEN is not set. Backfill requires a Slack bot token with channels:history scope.');
+        process.exit(2);
+    }
+    // --since is advisory in V1: the slack_cursors row drives resume, so the
+    // backfill loop always picks up where it last left off. Honoured-by-cursor
+    // semantics keep idempotency clean.
+    const sinceIso = flags['since'];
+    void sinceIso;
+    const fetcher = slackHistoryFetcher(token);
+    const ctx = {
+        hippoRoot,
+        tenantId: process.env.HIPPO_TENANT ?? 'default',
+        actor: 'cli:slack-backfill',
+    };
+    backfillChannel(ctx, {
+        teamId: process.env.SLACK_TEAM_ID ?? 'T_UNKNOWN',
+        channel: { id: channel, is_private: false },
+        fetcher,
+    })
+        .then((r) => {
+        console.log(`backfill ${channel}: ${r.ingested} new messages across ${r.pages} pages`);
+    })
+        .catch((e) => {
+        console.error('backfill failed:', e.message);
+        process.exit(3);
+    });
+}
+function cmdSlackDlqList(hippoRoot, _flags) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        const tenantId = process.env.HIPPO_TENANT ?? 'default';
+        const items = listDlq(db, { tenantId });
+        for (const it of items) {
+            console.log(`${it.id}\t${it.receivedAt}\t${it.error}`);
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+function cmdSlack(hippoRoot, args, flags) {
+    const sub = args[0];
+    if (sub === 'backfill') {
+        cmdSlackBackfill(hippoRoot, flags);
+        return;
+    }
+    if (sub === 'dlq' && args[1] === 'list') {
+        cmdSlackDlqList(hippoRoot, flags);
+        return;
+    }
+    console.error('Usage: hippo slack <backfill|dlq list> [...]');
+    process.exit(1);
+}
 function printUsage() {
     console.log(`
 Hippo - biologically-inspired memory system for AI agents
@@ -4350,6 +4457,37 @@ async function main() {
                 console.error('Memory content too short (minimum 3 characters).');
                 process.exit(1);
             }
+            // Thin-client routing. When a server is up, simple `remember` calls go
+            // over HTTP so the daemon stays single-writer (footgun #2). Rich CLI
+            // flags (--pin, --layer, --extract, --global, salience gates) still
+            // need the direct path; we only intercept the minimal envelope.
+            const richFlag = flags['pin'] || flags['global'] || flags['extract'] || flags['force'] ||
+                flags['observed'] || flags['inferred'] || flags['verified'] ||
+                flags['layer'] !== undefined;
+            if (!richFlag) {
+                const rememberKindRaw = typeof flags['kind'] === 'string' ? flags['kind'].toLowerCase() : undefined;
+                const rememberKindAllowed = ['distilled', 'superseded'];
+                if (rememberKindRaw === undefined || rememberKindAllowed.includes(rememberKindRaw)) {
+                    const tagsRaw = flags['tag'];
+                    const tags = Array.isArray(tagsRaw)
+                        ? tagsRaw.map(String)
+                        : typeof tagsRaw === 'string' ? [tagsRaw] : undefined;
+                    const remembered = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
+                        const result = await client.remember(info.url, apiKey, {
+                            content: text,
+                            kind: rememberKindRaw,
+                            scope: typeof flags['scope'] === 'string' ? flags['scope'] : undefined,
+                            owner: typeof flags['owner'] === 'string' ? flags['owner'] : undefined,
+                            artifactRef: typeof flags['artifact-ref'] === 'string' ? flags['artifact-ref'] : undefined,
+                            tags,
+                        });
+                        console.log(`Remembered [${result.id}] (via ${info.url})`);
+                        console.log(`   Kind: ${result.kind} | Tenant: ${result.tenantId}`);
+                    });
+                    if (remembered)
+                        break;
+                }
+            }
             await cmdRemember(hippoRoot, text, flags);
             break;
         }
@@ -4429,6 +4567,9 @@ async function main() {
         case 'auth':
             cmdAuth(hippoRoot, args, flags);
             break;
+        case 'slack':
+            cmdSlack(hippoRoot, args, flags);
+            break;
         case 'audit': {
             // `audit list` -> A5 audit-log viewer. Other forms (no sub, --fix) keep
             // the existing memory-quality auditor for backwards compatibility.
@@ -4499,6 +4640,18 @@ async function main() {
                 console.error('Please provide a memory ID.');
                 process.exit(1);
             }
+            const routed = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
+                try {
+                    await client.forget(info.url, apiKey, id);
+                    console.log(`Forgot ${id}`);
+                }
+                catch (err) {
+                    console.error(err.message);
+                    process.exit(1);
+                }
+            });
+            if (routed)
+                break;
             cmdForget(hippoRoot, id);
             break;
         }
@@ -4540,6 +4693,18 @@ async function main() {
                 console.error('Please provide a memory ID.');
                 process.exit(1);
             }
+            const promoted = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
+                try {
+                    const result = await client.promote(info.url, apiKey, id);
+                    console.log(`Promoted ${id} to global store as ${result.globalId}`);
+                }
+                catch (err) {
+                    console.error(`Failed to promote: ${err.message}`);
+                    process.exit(1);
+                }
+            });
+            if (promoted)
+                break;
             cmdPromote(hippoRoot, id);
             break;
         }
@@ -4689,12 +4854,35 @@ async function main() {
         case 'wm':
             cmdWm(hippoRoot, args, flags);
             break;
-        case 'mcp':
-            // Start MCP server over stdio - dynamically import to keep main CLI lean
-            await import('./mcp/server.js');
+        case 'mcp': {
+            // Start MCP server over stdio. Dynamic import keeps main CLI lean; the
+            // dispatcher itself is transport-agnostic, so we explicitly attach the
+            // stdio loop here. (HTTP/SSE transport is wired in src/server.ts and
+            // imports the same module without triggering stdin handlers.)
+            const mod = await import('./mcp/server.js');
+            mod.startStdioLoop();
             // Server runs until stdin closes, so we never reach here
             await new Promise(() => { }); // hang forever
             break;
+        }
+        case 'serve': {
+            requireInit(hippoRoot);
+            const portRaw = flags['port'] ?? process.env['HIPPO_PORT'] ?? '6789';
+            const port = Number(portRaw);
+            if (!Number.isFinite(port) || port < 0) {
+                console.error(`Invalid --port: ${String(portRaw)}`);
+                process.exit(1);
+            }
+            const host = typeof flags['host'] === 'string' ? flags['host'] : '127.0.0.1';
+            const { serve } = await import('./server.js');
+            const handle = await serve({ hippoRoot, port, host });
+            console.log(`hippo serve listening on ${handle.url} (pid ${process.pid})`);
+            console.log(`pidfile: ${path.join(hippoRoot, 'server.pid')}`);
+            console.log('press Ctrl+C to stop');
+            // SIGINT/SIGTERM handlers wired in server.ts (skipped under VITEST). Hang.
+            await new Promise(() => { });
+            break;
+        }
         case 'invalidate': {
             requireInit(hippoRoot);
             const target = args[0];