@mneme-ai/core 2.19.30 → 2.19.32

package/dist/handoff_snapshot/index.d.ts

@@ -0,0 +1,156 @@
+/**
+ * v2.19.32 — MNEME HANDOFF SNAPSHOT (the brain you hand to your child device)
+ *
+ *   User mandate (2026-05-17):
+ *   "อยากให้ลูก mneme เก่งสุดๆ และรู้จักการเอาตัวรอดได้ทุกสถานการณ์ ...
+ *    BEACON ทำมานานแล้วแต่ไม่เคยใช้ได้เลยผมเครียดมากๆๆ ... ทุก handoff =
+ *    fresh snapshot. ไม่ใช่ pre-baked file. child ได้ context เดียวกับ
+ *    parent ตอนนั้นเป๊ะ"
+ *
+ *   Diagnosis: prior BEACON shipped a "soul prompt" that was generic +
+ *   stale — same paragraph every release, no actual conversation context.
+ *   When user scanned QR on phone, they got a paragraph about Mneme's
+ *   features, not "we were debugging the auth bypass on line 216 of
+ *   beacon/index.ts." That's why BEACON has never been used in anger.
+ *
+ *   v2.19.32 HANDOFF SNAPSHOT is the pure-function COMPOSER: caller
+ *   supplies the live conversation + git state + activity (caller has the
+ *   I/O), this module canonicalises + HMAC-signs + ages it. The result
+ *   is a HandoffEnvelope the BEACON server can serve to whoever scans the
+ *   QR code, and the child device's `mneme receive` can verify + ingest.
+ *
+ *   What's NEW vs prior soul prompt:
+ *     - LIVE conversation (caller passes last N turns from MCP session)
+ *     - GIT STATE (branch / dirty / last N commits) at SNAPSHOT time
+ *     - RECENT ACTIVITY (tail of .mneme/cli-activity.jsonl)
+ *     - ACTIVE INTENT (what the user was just asking about)
+ *     - CAPABILITIES (mneme version + tool families) for child compatibility
+ *     - FRESHNESS TIMESTAMP — receiver enforces 5-min staleness gate
+ *
+ *   Composes onto:
+ *     - v2.9   BEACON (the QR + local HTTP server that carries this)
+ *     - v2.19.31 BUG #1 fix (token-required transport — no auth bypass)
+ *     - v2.19.32 PAIR CODE (6-char human-friendly handle bound to envelope)
+ *     - v2.19.32 CONSCIOUSNESS FORK (HMAC parent/child lineage record)
+ *
+ * Honest scope:
+ *   - PURE FUNCTION composer. Caller has the I/O (read git, tail jsonl,
+ *     get conversation). This makes it testable + vendor-neutral.
+ *   - HMAC-SHA256 signed for tamper detection at the receiver.
+ *   - Defensive: empty conversation OK, missing git OK, malformed input
+ *     returns minimal-but-valid envelope rather than throw.
+ *   - Freshness gate: receiver checks freshnessMs against TTL.
+ *   - 24/7 safe: never throws on bad input; 1000 random snapshots in a
+ *     row never crashes (measured in test suite).
+ */
+declare const PROTOCOL_VERSION: 2;
+export interface ConversationTurn {
+    role: "user" | "assistant" | "system";
+    /** UTF-8 text. Caller may pre-trim to budget. */
+    text: string;
+    /** ms since epoch. */
+    ts: number;
+}
+export interface GitState {
+    branch?: string;
+    /** Output of `git status --short` (already truncated by caller). */
+    dirty?: string;
+    /** Last N commit subject lines. */
+    recentCommits?: string[];
+}
+export interface ActivityRecord {
+    /** Tool name OR free-form action (caller picks). */
+    action: string;
+    /** ms since epoch. */
+    ts: number;
+    /** Optional structured metadata (must be JSON-serialisable). */
+    meta?: Record<string, unknown>;
+}
+export interface CapabilitiesSnapshot {
+    mnemeVersion: string;
+    /** MCP tool family names (e.g. ["synapse", "truth", "soul"]). */
+    toolFamilies: string[];
+    /** Tools whose presence the receiver should require for full fidelity. */
+    requiredTools?: string[];
+}
+export interface HandoffSnapshotInput {
+    /** Last N conversation turns. Caller trims to budget. */
+    conversation?: ConversationTurn[];
+    /** Free-form one-line current intent inferred from conversation tail. */
+    activeIntent?: string;
+    gitState?: GitState;
+    /** Tail of cli-activity.jsonl (caller pre-reads + parses). */
+    recentActivity?: ActivityRecord[];
+    capabilities?: CapabilitiesSnapshot;
+    /** Optional voice directive — agent-tone instructions. */
+    voiceDirective?: string;
+    /** Optional shared dictionary for cross-vendor term consistency. */
+    mnemeDictionary?: Record<string, string>;
+    /** Parent device fingerprint (e.g. host hash). */
+    parentDeviceId?: string;
+    /** ms since epoch. Default Date.now(). */
+    nowMs?: number;
+    secret?: string;
+}
+export interface HandoffEnvelope {
+    v: typeof PROTOCOL_VERSION;
+    /** Stable deterministic id derived from (parentDeviceId, snapshotAt, content hash). */
+    envelopeId: string;
+    parentDeviceId: string;
+    snapshotAtMs: number;
+    /** TTL the receiver should enforce. */
+    freshnessTtlMs: number;
+    conversation: ConversationTurn[];
+    activeIntent: string;
+    gitState: Required<GitState>;
+    recentActivity: ActivityRecord[];
+    capabilities: CapabilitiesSnapshot;
+    voiceDirective: string;
+    mnemeDictionary: Record<string, string>;
+    /** HMAC-SHA256 over canonical body. */
+    sig: string;
+}
+/**
+ * Compose a fresh handoff envelope. Defensive at every boundary:
+ *   - missing fields filled with sane defaults
+ *   - bad types coerced or dropped
+ *   - HMAC always computed (never empty sig)
+ *   - return value ALWAYS valid; never throws
+ */
+export declare function captureSnapshot(input: HandoffSnapshotInput): HandoffEnvelope;
+/** Verify envelope HMAC. Returns false on shape mismatch / tampered sig. */
+export declare function verifyEnvelope(envelope: HandoffEnvelope, secret?: string): boolean;
+/**
+ * Receiver-side freshness gate. Returns age in ms; caller compares to TTL.
+ * Stale envelope = receiver should refuse to ingest + ask parent to refresh.
+ */
+export interface FreshnessResult {
+    ageMs: number;
+    isFresh: boolean;
+    isExpired: boolean;
+    reason: "fresh" | "stale" | "expired" | "future_clock_skew";
+}
+export declare function freshnessCheck(envelope: HandoffEnvelope, nowMs?: number): FreshnessResult;
+/**
+ * Render an envelope as the AI-ingestible text the child will paste into
+ * its new vendor session (Gemini / GPT / Claude / etc). Deterministic,
+ * vendor-neutral, safe to display in clear text — the SIG is what gives
+ * tamper-evidence, not secrecy. (For confidentiality wrap in ECDH at the
+ * transport layer; out of scope for this composer.)
+ */
+export declare function renderForChildVendor(envelope: HandoffEnvelope): string;
+export interface SnapshotStats {
+    envelopeId: string;
+    conversationTurns: number;
+    activityRecords: number;
+    totalBytes: number;
+    ageMs: number;
+}
+export declare function computeSnapshotStats(envelope: HandoffEnvelope, nowMs?: number): SnapshotStats;
+export declare function formatSnapshotLine(s: SnapshotStats): string;
+export declare const HANDOFF_SNAPSHOT_TUNABLES: Readonly<{
+    PROTOCOL_VERSION: 2;
+    DEFAULT_FRESHNESS_TTL_MS: number;
+}>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/handoff_snapshot/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handoff_snapshot/index.ts"],"names":[],"mappings":"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"}

package/dist/handoff_snapshot/index.js

@@ -0,0 +1,261 @@
+/**
+ * v2.19.32 — MNEME HANDOFF SNAPSHOT (the brain you hand to your child device)
+ *
+ *   User mandate (2026-05-17):
+ *   "อยากให้ลูก mneme เก่งสุดๆ และรู้จักการเอาตัวรอดได้ทุกสถานการณ์ ...
+ *    BEACON ทำมานานแล้วแต่ไม่เคยใช้ได้เลยผมเครียดมากๆๆ ... ทุก handoff =
+ *    fresh snapshot. ไม่ใช่ pre-baked file. child ได้ context เดียวกับ
+ *    parent ตอนนั้นเป๊ะ"
+ *
+ *   Diagnosis: prior BEACON shipped a "soul prompt" that was generic +
+ *   stale — same paragraph every release, no actual conversation context.
+ *   When user scanned QR on phone, they got a paragraph about Mneme's
+ *   features, not "we were debugging the auth bypass on line 216 of
+ *   beacon/index.ts." That's why BEACON has never been used in anger.
+ *
+ *   v2.19.32 HANDOFF SNAPSHOT is the pure-function COMPOSER: caller
+ *   supplies the live conversation + git state + activity (caller has the
+ *   I/O), this module canonicalises + HMAC-signs + ages it. The result
+ *   is a HandoffEnvelope the BEACON server can serve to whoever scans the
+ *   QR code, and the child device's `mneme receive` can verify + ingest.
+ *
+ *   What's NEW vs prior soul prompt:
+ *     - LIVE conversation (caller passes last N turns from MCP session)
+ *     - GIT STATE (branch / dirty / last N commits) at SNAPSHOT time
+ *     - RECENT ACTIVITY (tail of .mneme/cli-activity.jsonl)
+ *     - ACTIVE INTENT (what the user was just asking about)
+ *     - CAPABILITIES (mneme version + tool families) for child compatibility
+ *     - FRESHNESS TIMESTAMP — receiver enforces 5-min staleness gate
+ *
+ *   Composes onto:
+ *     - v2.9   BEACON (the QR + local HTTP server that carries this)
+ *     - v2.19.31 BUG #1 fix (token-required transport — no auth bypass)
+ *     - v2.19.32 PAIR CODE (6-char human-friendly handle bound to envelope)
+ *     - v2.19.32 CONSCIOUSNESS FORK (HMAC parent/child lineage record)
+ *
+ * Honest scope:
+ *   - PURE FUNCTION composer. Caller has the I/O (read git, tail jsonl,
+ *     get conversation). This makes it testable + vendor-neutral.
+ *   - HMAC-SHA256 signed for tamper detection at the receiver.
+ *   - Defensive: empty conversation OK, missing git OK, malformed input
+ *     returns minimal-but-valid envelope rather than throw.
+ *   - Freshness gate: receiver checks freshnessMs against TTL.
+ *   - 24/7 safe: never throws on bad input; 1000 random snapshots in a
+ *     row never crashes (measured in test suite).
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+const PROTOCOL_VERSION = 2;
+const DEFAULT_FRESHNESS_TTL_MS = 5 * 60 * 1000; // 5 min
+// ─── canonical helpers ───────────────────────────────────────────────
+function canon(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return "[" + v.map(canon).join(",") + "]";
+    const keys = Object.keys(v).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + canon(v[k])).join(",") + "}";
+}
+function defaultSecret() {
+    return process.env["MNEME_HANDOFF_SECRET"] || `mneme-handoff-v${PROTOCOL_VERSION}`;
+}
+function hmacHex(body, secret) {
+    return createHmac("sha256", secret).update(canon(body)).digest("hex");
+}
+function safeEqHex(a, b) {
+    try {
+        return timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+    }
+    catch {
+        return false;
+    }
+}
+function clean(s, fallback = "") {
+    return typeof s === "string" ? s : fallback;
+}
+function cleanArray(a, fallback = []) {
+    return Array.isArray(a) ? a : fallback;
+}
+/**
+ * Compose a fresh handoff envelope. Defensive at every boundary:
+ *   - missing fields filled with sane defaults
+ *   - bad types coerced or dropped
+ *   - HMAC always computed (never empty sig)
+ *   - return value ALWAYS valid; never throws
+ */
+export function captureSnapshot(input) {
+    const nowMs = input.nowMs ?? Date.now();
+    const secret = input.secret ?? defaultSecret();
+    // Defensive coercions — every field has a defined shape
+    const conversation = cleanArray(input.conversation).filter((t) => t && typeof t.text === "string" && (t.role === "user" || t.role === "assistant" || t.role === "system")).map((t) => ({
+        role: t.role,
+        text: t.text,
+        ts: typeof t.ts === "number" && Number.isFinite(t.ts) ? t.ts : nowMs,
+    }));
+    const activeIntent = clean(input.activeIntent, conversation.length > 0
+        ? `handoff continuing: ${conversation[conversation.length - 1].text.slice(0, 80)}`
+        : "fresh handoff");
+    const gitState = {
+        branch: clean(input.gitState?.branch, "unknown"),
+        dirty: clean(input.gitState?.dirty, ""),
+        recentCommits: cleanArray(input.gitState?.recentCommits),
+    };
+    const recentActivity = cleanArray(input.recentActivity).filter((r) => r && typeof r.action === "string" && typeof r.ts === "number" && Number.isFinite(r.ts));
+    const capabilities = {
+        mnemeVersion: clean(input.capabilities?.mnemeVersion, "unknown"),
+        toolFamilies: cleanArray(input.capabilities?.toolFamilies).filter((s) => typeof s === "string"),
+        requiredTools: cleanArray(input.capabilities?.requiredTools).filter((s) => typeof s === "string"),
+    };
+    const voiceDirective = clean(input.voiceDirective, "");
+    const mnemeDictionary = (input.mnemeDictionary && typeof input.mnemeDictionary === "object" && !Array.isArray(input.mnemeDictionary))
+        ? input.mnemeDictionary
+        : {};
+    const parentDeviceId = clean(input.parentDeviceId, "anonymous-parent");
+    // Body before sig
+    const bodyForSig = {
+        v: PROTOCOL_VERSION,
+        parentDeviceId,
+        snapshotAtMs: nowMs,
+        freshnessTtlMs: DEFAULT_FRESHNESS_TTL_MS,
+        conversation,
+        activeIntent,
+        gitState,
+        recentActivity,
+        capabilities,
+        voiceDirective,
+        mnemeDictionary,
+    };
+    const sig = hmacHex(bodyForSig, secret);
+    const envelopeId = hmacHex({ parentDeviceId, snapshotAtMs: nowMs, sig }, secret).slice(0, 16);
+    return {
+        v: PROTOCOL_VERSION,
+        envelopeId,
+        parentDeviceId,
+        snapshotAtMs: nowMs,
+        freshnessTtlMs: DEFAULT_FRESHNESS_TTL_MS,
+        conversation,
+        activeIntent,
+        gitState,
+        recentActivity,
+        capabilities,
+        voiceDirective,
+        mnemeDictionary,
+        sig,
+    };
+}
+/** Verify envelope HMAC. Returns false on shape mismatch / tampered sig. */
+export function verifyEnvelope(envelope, secret) {
+    if (!envelope || typeof envelope !== "object")
+        return false;
+    if (envelope.v !== PROTOCOL_VERSION)
+        return false;
+    if (typeof envelope.sig !== "string" || !/^[0-9a-f]{64}$/.test(envelope.sig))
+        return false;
+    if (typeof envelope.parentDeviceId !== "string")
+        return false;
+    if (typeof envelope.snapshotAtMs !== "number" || !Number.isFinite(envelope.snapshotAtMs))
+        return false;
+    const sec = secret ?? defaultSecret();
+    const { sig, envelopeId: _eid, v: _v, ...body } = envelope;
+    const bodyForSig = { v: PROTOCOL_VERSION, ...body };
+    return safeEqHex(hmacHex(bodyForSig, sec), sig);
+}
+export function freshnessCheck(envelope, nowMs) {
+    const now = nowMs ?? Date.now();
+    const age = now - envelope.snapshotAtMs;
+    // Clock skew detection — receiver clock behind parent by > 1s
+    if (age < -1000)
+        return { ageMs: age, isFresh: false, isExpired: false, reason: "future_clock_skew" };
+    const ttl = envelope.freshnessTtlMs ?? DEFAULT_FRESHNESS_TTL_MS;
+    if (age > ttl)
+        return { ageMs: age, isFresh: false, isExpired: true, reason: "expired" };
+    // 80% of TTL → stale warning (receiver may still ingest with caveat)
+    if (age > ttl * 0.8)
+        return { ageMs: age, isFresh: false, isExpired: false, reason: "stale" };
+    return { ageMs: age, isFresh: true, isExpired: false, reason: "fresh" };
+}
+/**
+ * Render an envelope as the AI-ingestible text the child will paste into
+ * its new vendor session (Gemini / GPT / Claude / etc). Deterministic,
+ * vendor-neutral, safe to display in clear text — the SIG is what gives
+ * tamper-evidence, not secrecy. (For confidentiality wrap in ECDH at the
+ * transport layer; out of scope for this composer.)
+ */
+export function renderForChildVendor(envelope) {
+    const lines = [];
+    lines.push(`# 🧬 Mneme Handoff — continuing from parent`);
+    lines.push(``);
+    lines.push(`**Parent device**: ${envelope.parentDeviceId}`);
+    lines.push(`**Snapshot at**: ${new Date(envelope.snapshotAtMs).toISOString()}`);
+    lines.push(`**Mneme version**: ${envelope.capabilities.mnemeVersion}`);
+    if (envelope.activeIntent) {
+        lines.push(``);
+        lines.push(`**Active intent**: ${envelope.activeIntent}`);
+    }
+    if (envelope.gitState.branch !== "unknown") {
+        lines.push(``);
+        lines.push(`## Git state`);
+        lines.push(`- branch: \`${envelope.gitState.branch}\``);
+        if (envelope.gitState.dirty) {
+            lines.push(`- dirty files:`);
+            lines.push("```");
+            lines.push(envelope.gitState.dirty);
+            lines.push("```");
+        }
+        if (envelope.gitState.recentCommits.length > 0) {
+            lines.push(`- recent commits:`);
+            for (const c of envelope.gitState.recentCommits)
+                lines.push(`  - ${c}`);
+        }
+    }
+    if (envelope.conversation.length > 0) {
+        lines.push(``);
+        lines.push(`## Conversation tail`);
+        for (const t of envelope.conversation.slice(-10)) {
+            lines.push(`**${t.role}**: ${t.text}`);
+            lines.push(``);
+        }
+    }
+    if (envelope.recentActivity.length > 0) {
+        lines.push(``);
+        lines.push(`## Recent activity`);
+        for (const r of envelope.recentActivity.slice(-10)) {
+            lines.push(`- \`${r.action}\` @ ${new Date(r.ts).toISOString()}`);
+        }
+    }
+    if (envelope.voiceDirective) {
+        lines.push(``);
+        lines.push(`## Voice directive`);
+        lines.push(envelope.voiceDirective);
+    }
+    if (Object.keys(envelope.mnemeDictionary).length > 0) {
+        lines.push(``);
+        lines.push(`## Shared dictionary`);
+        for (const [k, v] of Object.entries(envelope.mnemeDictionary)) {
+            lines.push(`- **${k}**: ${v}`);
+        }
+    }
+    lines.push(``);
+    lines.push(`---`);
+    lines.push(`HMAC sig (last 12): \`...${envelope.sig.slice(-12)}\` · envelope ${envelope.envelopeId}`);
+    return lines.join("\n");
+}
+export function computeSnapshotStats(envelope, nowMs) {
+    const bytes = JSON.stringify(envelope).length;
+    return {
+        envelopeId: envelope.envelopeId,
+        conversationTurns: envelope.conversation.length,
+        activityRecords: envelope.recentActivity.length,
+        totalBytes: bytes,
+        ageMs: (nowMs ?? Date.now()) - envelope.snapshotAtMs,
+    };
+}
+export function formatSnapshotLine(s) {
+    const ageSec = Math.max(0, Math.floor(s.ageMs / 1000));
+    const kb = (s.totalBytes / 1024).toFixed(1);
+    return `🧬 SNAPSHOT ${s.envelopeId} · ${s.conversationTurns} turns · ${s.activityRecords} activity · ${kb}KB · age=${ageSec}s`;
+}
+export const HANDOFF_SNAPSHOT_TUNABLES = Object.freeze({
+    PROTOCOL_VERSION,
+    DEFAULT_FRESHNESS_TTL_MS,
+});
+//# sourceMappingURL=index.js.map

package/dist/handoff_snapshot/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/handoff_snapshot/index.ts"],"names":[],"mappings":"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"}

package/dist/handoff_snapshot/system_e2e.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * v2.19.32 SYSTEM E2E TEST — the full PARENT → QR → CHILD pipeline
+ *
+ * Exercises all 4 v2.19.32 modules together with a realistic 4-vendor
+ * scenario. If this test passes, BEACON HANDOFF actually works.
+ */
+export {};
+//# sourceMappingURL=system_e2e.test.d.ts.map

package/dist/handoff_snapshot/system_e2e.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system_e2e.test.d.ts","sourceRoot":"","sources":["../../src/handoff_snapshot/system_e2e.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}