@jack200714/mafw 4.5.1

package/gateway/dist/recall/reflection.js

@@ -0,0 +1,318 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReflectionPipeline = exports.QUESTIONS_SYSTEM = exports.REFLECT_SYSTEM = exports.ORPHAN_SESSION = void 0;
+exports.parseQuestions = parseQuestions;
+exports.parseInsights = parseInsights;
+exports.unreflectedBySession = unreflectedBySession;
+const harmonic_file_store_1 = require("../memory/harmonic-file-store");
+const minhash_merger_1 = require("../core/memory/minhash-merger");
+const harmonic_types_1 = require("../core/memory/harmonic-types");
+const salience_perceptor_1 = require("../core/memory/salience-perceptor");
+const memory_curator_agent_1 = require("../skills/memory-curator-agent");
+/** Session key for episodic memories with no source_session_id (legacy data). */
+exports.ORPHAN_SESSION = '__orphan__';
+exports.REFLECT_SYSTEM = `You are a reflection system for a coding agent's long-term memory. Review the episodic memories of one conversation and distill durable, reusable insights. Return ONLY valid JSON, no markdown:
+{"insights":[{"category":"failure|correction|insight|preference|convention|tool-quirk","content":"<one sentence>","cue_anchors":["<keyword>"]}]}
+Rules:
+- no redundant insights; each insight must be a durable lesson, preference, failure, convention, or tool quirk
+- every cue_anchors list MUST include the topic entity names (project, module, API, person, feature) so the insight can be found across sessions
+- for category "preference", include a machine-readable anchor like "pref:<dimension>=<value>" (e.g., "pref:output-language=chinese" or "pref:spicy=false")
+- prefer insights that hold across multiple episodes of this conversation
+Division of labor: focus on CROSS-EPISODE high-level patterns — recurring failure root causes, lessons that generalize to future tasks, user behavior patterns. Do NOT re-record single-point facts already present in the episodic memories (the hourly extract pipeline already saved those).
+
+### Cross-Session Entity Linking (CRITICAL):
+- Extract ALL named entities from the episodes: project names, module names, person names, API endpoints, feature names, file paths, commands, error messages, configuration keys
+- For each insight, include entities that would help find this insight in OTHER sessions about the same topic
+- Include entity variants: e.g., both "React" and "react", both "User Auth Module" and "auth module"
+- For technical discussions, include error codes, stack traces, or specific function names as anchors
+- For user preferences, include the dimension AND value: e.g., "pref:ui-language=chinese" AND "chinese" AND "ui-language"
+- Think: "If someone asked about this topic in a different session, what keywords would they search for?"
+${memory_curator_agent_1.HARD_BOUNDARIES}`;
+exports.QUESTIONS_SYSTEM = `You are a reflection system for a coding agent's long-term memory. Review the episodic memories of one conversation and generate the 2-3 most salient high-level questions about this session — questions whose answers would reveal durable patterns, recurring root causes, or generalizable lessons. Return ONLY valid JSON, no markdown:
+{"questions":["<question>","<question>"]}
+Rules:
+- questions must be answerable from past conversations (not speculation)
+- prefer questions that span multiple episodes
+- questions should be specific enough to retrieve relevant memories (include entity names like project, module, API, feature)
+- for multi-topic sessions, generate questions for each topic separately
+- for user preferences, ask about the preference itself (e.g., "What UI language does the user prefer?") rather than the context where it was mentioned
+${memory_curator_agent_1.HARD_BOUNDARIES}`;
+function parseQuestions(text) {
+    try {
+        const parsed = JSON.parse(text.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/, ''));
+        const items = parsed?.questions ?? parsed;
+        if (!Array.isArray(items))
+            return [];
+        return items.filter((q) => typeof q === 'string' && q.trim()).slice(0, 3).map(String);
+    }
+    catch {
+        return [];
+    }
+}
+const CATEGORY_TO_TYPE = {
+    failure: 'semantic',
+    correction: 'semantic',
+    insight: 'semantic',
+    preference: 'semantic',
+    convention: 'semantic',
+    'tool-quirk': 'procedural',
+};
+const CATEGORY_ENERGY = {
+    failure: 0.9,
+    correction: 0.9,
+    insight: 0.8,
+    preference: 0.85,
+    convention: 0.75,
+    'tool-quirk': 0.8,
+};
+function parseInsights(text) {
+    try {
+        const parsed = JSON.parse(text.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/, ''));
+        const items = parsed?.insights ?? parsed;
+        if (!Array.isArray(items))
+            return [];
+        return items
+            .filter((i) => i?.content?.trim() &&
+            ['failure', 'correction', 'insight', 'preference', 'convention', 'tool-quirk'].includes(i.category))
+            .map((i) => ({
+            category: i.category,
+            content: String(i.content).trim(),
+            cue_anchors: Array.isArray(i.cue_anchors) ? i.cue_anchors.slice(0, 8).map(String) : [],
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Groups index episodic entries by session (source_session_id; legacy entries
+ * without one go to the ORPHAN group). Returns only unreflected ids.
+ */
+function unreflectedBySession(index, cursor, maxPerSession) {
+    const bySession = new Map();
+    for (const entry of index.getIndex().entries) {
+        if (entry.type !== 'episodic')
+            continue;
+        const session = entry.source_session_id || exports.ORPHAN_SESSION;
+        if (cursor.isReflected(session, entry.id))
+            continue;
+        let list = bySession.get(session);
+        if (!list) {
+            list = [];
+            bySession.set(session, list);
+        }
+        if (list.length >= maxPerSession)
+            continue;
+        list.push({ id: entry.id, text: `${entry.primary_abstraction} ${(entry.cue_anchors ?? []).join(' ')}` });
+    }
+    return bySession;
+}
+class ReflectionPipeline {
+    opts;
+    store;
+    merger = new minhash_merger_1.MinHashMerger();
+    constructor(opts) {
+        this.opts = opts;
+        this.store = new harmonic_file_store_1.HarmonicUnitFileStore(opts.baseDir, opts.index);
+    }
+    /**
+     * Three-way classification for a new insight against existing memories:
+     * - 'duplicate': MinHash > 0.6 → skip (same content)
+     * - 'conflict': MinHash 0.4-0.6 + shared cue_anchors → supersede old entry
+     * - 'novel': no significant overlap → write normally
+     *
+     * The conflict band (0.4-0.6) catches "same topic, different value" cases
+     * that MinHash dedup misses — e.g., "deploy to us-east-1" vs "deploy to
+     * eu-west-1" share structure but differ in the critical detail.
+     */
+    classifyInsight(content, cueAnchors) {
+        const sig = this.merger.generateSignature(content);
+        let bestMatch = null;
+        for (const entry of this.opts.index.getIndex().entries) {
+            if (entry.type !== 'semantic' && entry.type !== 'procedural')
+                continue;
+            if (entry.superseded_by)
+                continue; // skip already-superseded entries
+            // Merged blobs concatenate segments with ' | ' — compare per segment
+            // so a true duplicate of one segment is not diluted by the rest.
+            let sim = 0;
+            for (const seg of minhash_merger_1.MinHashMerger.segmentsOf(entry.primary_abstraction)) {
+                const other = `${seg} ${(entry.cue_anchors ?? []).join(' ')}`;
+                const s = this.merger.similarity(sig, this.merger.generateSignature(other));
+                if (s > sim)
+                    sim = s;
+            }
+            if (sim > 0.6)
+                return { kind: 'duplicate' };
+            if (sim > 0.4 && sim > (bestMatch?.sim ?? 0)) {
+                bestMatch = { id: entry.id, sim };
+            }
+        }
+        // Conflict requires both MinHash in the 0.4-0.6 band AND at least one shared cue_anchor
+        if (bestMatch && bestMatch.sim > 0.4) {
+            const targetEntry = this.opts.index.getIndex().entries.find(e => e.id === bestMatch.id);
+            const targetAnchors = targetEntry?.cue_anchors ?? [];
+            const sharedAnchors = cueAnchors.filter(a => targetAnchors.includes(a));
+            if (sharedAnchors.length > 0) {
+                return { kind: 'conflict', conflictTarget: bestMatch.id };
+            }
+        }
+        return { kind: 'novel' };
+    }
+    /**
+     * Reflect one session's unreflected episodes. Returns the number of
+     * reviewed episodes (0 when nothing pending). Marks ids reflected only
+     * after insights were successfully written (failure keeps them pending for
+     * the next run).
+     */
+    async reflectSession(sessionID, episodes) {
+        const result = { sessions: 0, reviewed: 0, distilled: 0, deduped: 0, superseded: 0, failed: 0, pendingSessions: 0 };
+        if (episodes.length === 0)
+            return result;
+        result.reviewed = episodes.length;
+        const promptLines = [];
+        for (let i = 0; i < episodes.length; i++) {
+            const ep = episodes[i];
+            let text = ep.text;
+            try {
+                const unit = await this.store.read(ep.id);
+                if (unit?.memory_value)
+                    text = unit.memory_value.slice(0, 2000);
+            }
+            catch { /* fall back to summary line */ }
+            promptLines.push(`${i + 1}. ${text}`);
+        }
+        const prompt = promptLines.join('\n');
+        const worker = this.opts.workerFor(sessionID);
+        let insights = [];
+        try {
+            // Step 1: generate salient questions
+            const qText = await worker.prompt(prompt, exports.QUESTIONS_SYSTEM, this.opts.workerModel, 'memory-curator');
+            const questions = parseQuestions(qText);
+            // Step 2: retrieve evidence per question (bm25, no graph expansion)
+            const evidence = [];
+            if (questions.length > 0) {
+                for (const q of questions) {
+                    const hits = this.opts.index.searchScored(q, 5, { retriever: 'bm25', graphExpand: false });
+                    for (const hit of hits) {
+                        const line = `- [${hit.entry.id}] ${hit.entry.primary_abstraction}`;
+                        if (!evidence.includes(line))
+                            evidence.push(line);
+                    }
+                }
+            }
+            // Step 3: distill insights with evidence context
+            const evidenceBlock = evidence.length > 0 ? `\n\n### Related Historical Memories\n${evidence.join('\n')}` : '';
+            // Step 3.5: Extract entities from episodes for cross-session linking
+            const episodeEntities = new Set();
+            for (const ep of episodes) {
+                // Extract camelCase/PascalCase identifiers
+                const camelPascal = ep.text.match(/\b[A-Z][a-z]+(?:[A-Z][a-z]+)+\b/g);
+                if (camelPascal)
+                    camelPascal.forEach(e => episodeEntities.add(e));
+                // Extract ALL_CAPS words
+                const allCaps = ep.text.match(/\b[A-Z]{2,}\b/g);
+                if (allCaps)
+                    allCaps.forEach(e => { if (e.length >= 3)
+                        episodeEntities.add(e); });
+                // Extract quoted strings
+                const quoted = ep.text.match(/['"]([^'"]+)['"]/g);
+                if (quoted)
+                    quoted.forEach(q => episodeEntities.add(q.slice(1, -1).trim()));
+            }
+            // Inject entity context into evidence block for cross-session linking
+            const entityBlock = episodeEntities.size > 0
+                ? `\n\n### Session Entities (for cross-session linking)\n${[...episodeEntities].slice(0, 20).join(', ')}`
+                : '';
+            const text = await worker.prompt(prompt + evidenceBlock + entityBlock, exports.REFLECT_SYSTEM, this.opts.workerModel, 'memory-curator');
+            insights = parseInsights(text);
+        }
+        catch {
+            result.failed++;
+            return result; // episodes stay unreflected
+        }
+        const maxInsights = this.opts.maxInsights ?? 10;
+        for (const insight of insights.slice(0, maxInsights)) {
+            const classification = this.classifyInsight(insight.content, insight.cue_anchors ?? []);
+            if (classification.kind === 'duplicate') {
+                result.deduped++;
+                continue;
+            }
+            const now = new Date().toISOString();
+            const unit = {
+                id: (0, harmonic_types_1.generateHarmonicId)(),
+                type: CATEGORY_TO_TYPE[insight.category],
+                primary_abstraction: insight.content.slice(0, 200),
+                cue_anchors: insight.cue_anchors ?? [],
+                memory_value: insight.content,
+                energy: CATEGORY_ENERGY[insight.category],
+                salience: (0, salience_perceptor_1.calculateSalience)(insight.content),
+                abstraction_level: 2,
+                created_at: now,
+                updated_at: now,
+                source_session_id: sessionID === exports.ORPHAN_SESSION ? undefined : sessionID,
+            };
+            try {
+                // If this insight conflicts with an existing memory, supersede the old one
+                if (classification.kind === 'conflict' && classification.conflictTarget) {
+                    this.store.markSuperseded(classification.conflictTarget, unit.id);
+                    result.superseded++;
+                }
+                await this.store.write(unit);
+                result.distilled++;
+            }
+            catch {
+                result.failed++;
+            }
+        }
+        // Mark the batch reflected once the LLM produced a parseable result —
+        // regardless of dedup/partial write failures. The episodes were processed;
+        // retrying them would only re-extract the same (deduped) insights. Only a
+        // hard LLM failure (no insights at all) keeps them pending.
+        if (insights.length > 0) {
+            this.opts.cursor.markReflected(sessionID, episodes.map((e) => e.id));
+        }
+        result.sessions = insights.length > 0 ? 1 : 0;
+        return result;
+    }
+    /**
+     * Reflect all sessions with unreflected episodes (daily cron). Each session
+     * goes through the exclusive gate so concurrent triggers (restore, manual)
+     * can never double-process the same episodes on the same worker.
+     */
+    async runAll() {
+        const total = { sessions: 0, reviewed: 0, distilled: 0, deduped: 0, superseded: 0, failed: 0, pendingSessions: 0 };
+        const bySession = unreflectedBySession(this.opts.index, this.opts.cursor, this.opts.maxEpisodicPerSession ?? 100);
+        const exclusive = this.opts.exclusive ?? ((_sessionID, fn) => fn());
+        for (const [sessionID, episodes] of bySession) {
+            const res = await exclusive(sessionID, async () => {
+                return this.reflectSession(sessionID, episodes);
+            });
+            const r = res;
+            total.sessions += r.sessions;
+            total.reviewed += r.reviewed;
+            total.distilled += r.distilled;
+            total.deduped += r.deduped;
+            total.superseded += r.superseded;
+            total.failed += r.failed;
+        }
+        // Maintenance: drop reflected ids that no longer exist in the index so the
+        // bounded per-session list never re-exposes stale episodes.
+        this.opts.cursor.prune(new Set(this.opts.index.getIndex().entries.map((e) => e.id)));
+        return total;
+    }
+    /** Reflect a single session (restoreWorkerState / shouldReflect path). */
+    async runSession(sessionID) {
+        const bySession = unreflectedBySession(this.opts.index, this.opts.cursor, this.opts.maxEpisodicPerSession ?? 100);
+        const episodes = bySession.get(sessionID);
+        if (!episodes || episodes.length === 0)
+            return { sessions: 0, reviewed: 0, distilled: 0, deduped: 0, superseded: 0, failed: 0, pendingSessions: 0 };
+        return this.reflectSession(sessionID, episodes);
+    }
+    /** Number of unreflected episodes for a session (shouldReflect gate). */
+    pendingFor(sessionID) {
+        const bySession = unreflectedBySession(this.opts.index, this.opts.cursor, this.opts.maxEpisodicPerSession ?? 100);
+        return bySession.get(sessionID)?.length ?? 0;
+    }
+}
+exports.ReflectionPipeline = ReflectionPipeline;

package/gateway/dist/recall/session-worker-pool.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionWorkerPool = void 0;
+// Per-session worker pool: every active session gets its own extract and
+// reflect MemoryWorker (background Observer/Reflector pair). Entries are
+// lazily created, TTL-refreshed on access, and disposed on eviction (24h idle
+// or hard-cap overflow). runExclusive serializes pipeline work per
+// (session, kind) so concurrent triggers (cron + restore + manual) can never
+// run the same worker twice at once.
+const ttl_map_1 = require("./ttl-map");
+const memory_worker_1 = require("./memory-worker");
+class SessionWorkerPool {
+    opts;
+    entries;
+    inflight = new Map();
+    creationOrder = [];
+    constructor(opts) {
+        this.opts = opts;
+        const ttlMs = opts.ttlMs;
+        this.entries = new ttl_map_1.TtlMap(ttlMs, {
+            onEvict: (_key, pair) => {
+                void pair.extract.dispose();
+                void pair.reflect.dispose();
+            },
+        });
+    }
+    maxSessions() {
+        return this.opts.maxSessions ?? 64;
+    }
+    /** Get (or lazily create) the worker for a session. Touches the TTL. */
+    getWorker(sessionID, kind) {
+        this.entries.sweep(); // release idle/expired sessions before serving one
+        let pair = this.entries.getAndTouch(sessionID, this.opts.ttlMs);
+        if (!pair) {
+            // Hard cap: evict the oldest entry that is not mid-flight (never kill a
+            // worker whose prompt is in progress — that degrades to fallback/retry).
+            while (this.entries.size() >= this.maxSessions()) {
+                const idx = this.creationOrder.findIndex((id) => id !== sessionID && !this.isRunning(id, 'extract') && !this.isRunning(id, 'reflect'));
+                if (idx === -1)
+                    break; // everything in flight → accept the overflow
+                const oldest = this.creationOrder.splice(idx, 1)[0];
+                this.entries.delete(oldest);
+            }
+            const label = `mem-${sessionID}`;
+            pair = {
+                extract: new memory_worker_1.MemoryWorker(this.opts.client, {
+                    directory: this.opts.directory,
+                    label: `${label}:extract`,
+                    compactIdleMs: this.opts.compactIdleMs,
+                    onSessionCreated: this.opts.onSessionCreated
+                        ? (sid) => this.opts.onSessionCreated(sid, 'extract')
+                        : undefined,
+                }),
+                reflect: new memory_worker_1.MemoryWorker(this.opts.client, {
+                    directory: this.opts.directory,
+                    label: `${label}:reflect`,
+                    compactIdleMs: this.opts.compactIdleMs,
+                    onSessionCreated: this.opts.onSessionCreated
+                        ? (sid) => this.opts.onSessionCreated(sid, 'reflect')
+                        : undefined,
+                }),
+                label,
+            };
+            this.entries.set(sessionID, pair, this.opts.ttlMs);
+            this.creationOrder.push(sessionID);
+        }
+        return kind === 'extract' ? pair.extract : pair.reflect;
+    }
+    /**
+     * Serialize work per (session, kind): if a run is already in flight for the
+     * same key, the new call awaits the existing one instead of starting a
+     * second concurrent run (prevents duplicate extraction / cursor races).
+     */
+    runExclusive(sessionID, kind, fn) {
+        const key = `${sessionID}:${kind}`;
+        const prev = this.inflight.get(key);
+        if (prev)
+            return prev;
+        const run = fn().finally(() => {
+            if (this.inflight.get(key) === run)
+                this.inflight.delete(key);
+        });
+        this.inflight.set(key, run);
+        return run;
+    }
+    isRunning(sessionID, kind) {
+        return this.inflight.has(`${sessionID}:${kind}`);
+    }
+    size() {
+        return this.entries.size();
+    }
+    /** Dispose every worker (gateway stop / restart). */
+    disposeAll() {
+        this.entries.clear(); // onEvict disposes pairs
+        this.inflight.clear();
+        this.creationOrder = [];
+        return Promise.resolve();
+    }
+}
+exports.SessionWorkerPool = SessionWorkerPool;

package/gateway/dist/recall/stale-verify.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StaleVerifyPipeline = exports.STALE_VERIFY_SYSTEM = void 0;
+const memory_curator_agent_1 = require("../skills/memory-curator-agent");
+exports.STALE_VERIFY_SYSTEM = `You are the stale-memory reviewer for the harmonic memory system.
+You receive a list of existing long-term memories. Re-verify each one against the CURRENT environment using read/grep/glob/ls (read-only):
+- still true → do nothing.
+- contradicted by the environment → write the corrected version with mafw_add_memory, passing the old memory's id in its supersedes field (or call mafw_supersede_memory on the old id when there is nothing worth replacing it with).
+- not verifiable with read-only tools (preferences, past events, opinions) → skip it.
+Spend at most 3 probes per memory. Probing verifies a memory; it never continues the work the memory describes.
+${memory_curator_agent_1.HARD_BOUNDARIES}
+
+After processing, ALWAYS end your response with exactly one line:
+[STALE-REVIEW: checked=N superseded=M]
+This line MUST be the very last line of your response.`;
+const DAY_MS = 24 * 60 * 60 * 1000;
+class StaleVerifyPipeline {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** High-value, drift-exposed memories: procedural/semantic, live (not
+     *  superseded), older than minAgeDays, ranked by energy × salience. */
+    selectCandidates() {
+        const now = this.opts.now ?? Date.now();
+        const topK = this.opts.topK ?? 10;
+        const minAgeDays = this.opts.minAgeDays ?? 14;
+        return this.opts.index
+            .getIndex()
+            .entries.filter((e) => (e.type === 'procedural' || e.type === 'semantic') && !e.superseded_by)
+            .filter((e) => {
+            const created = e.created_at ? new Date(e.created_at).getTime() : 0;
+            return created > 0 && now - created >= minAgeDays * DAY_MS;
+        })
+            .sort((a, b) => b.energy * (b.salience ?? 1) - a.energy * (a.salience ?? 1))
+            .slice(0, topK);
+    }
+    async runOnce() {
+        const candidates = this.selectCandidates();
+        const result = {
+            candidates: candidates.length,
+            checked: 0,
+            superseded: 0,
+            failed: false,
+        };
+        if (candidates.length === 0)
+            return result;
+        const blocks = [];
+        for (const c of candidates) {
+            const unit = await this.opts.readMemory(c.id).catch(() => null);
+            if (!unit)
+                continue;
+            blocks.push(`---\nid: ${c.id}\ntype: ${c.type}\ncontent:\n${unit.memory_value}`);
+        }
+        if (blocks.length === 0)
+            return result;
+        const prompt = `Re-verify the following ${blocks.length} memories against the current environment:\n\n${blocks.join('\n')}`;
+        try {
+            const reply = await this.opts.worker.prompt(prompt, exports.STALE_VERIFY_SYSTEM, this.opts.workerModel, 'memory-curator');
+            const m = reply.match(/\[STALE-REVIEW:\s*checked=(\d+)\s+superseded=(\d+)\s*\]/);
+            if (m) {
+                result.checked = parseInt(m[1], 10);
+                result.superseded = parseInt(m[2], 10);
+            }
+        }
+        catch {
+            result.failed = true;
+        }
+        return result;
+    }
+}
+exports.StaleVerifyPipeline = StaleVerifyPipeline;

package/gateway/dist/recall/step-inject.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StepInjectState = exports.FINISHED_EXCLUSIONS = void 0;
+exports.defaultStepInjectOptions = defaultStepInjectOptions;
+exports.stepPropsFromPartUpdated = stepPropsFromPartUpdated;
+exports.stepPropsFromMessageUpdated = stepPropsFromMessageUpdated;
+exports.shouldConsiderStep = shouldConsiderStep;
+exports.selectMemories = selectMemories;
+exports.memoryFingerprint = memoryFingerprint;
+// Step-ended memory injection (path 1): on a settled LLM step, search high
+// salience memories and, after the session goes idle, promptAsync them back
+// into the session as a memory block so the agent can act on them.
+//
+// Concurrency model: every method below is synchronous — no await in between
+// state reads/writes, so Node's single thread makes each call atomic. Awaiting
+// happens only in the caller (search, promptAsync) and never while holding
+// state. Mark-before-async (markStepSeen) prevents duplicate evaluation when
+// concurrent step.ended events arrive during an await.
+const ttl_map_1 = require("./ttl-map");
+exports.FINISHED_EXCLUSIONS = ['tool-calls', 'unknown'];
+function defaultStepInjectOptions() {
+    return {
+        queueCap: 3,
+        intervalMs: 15 * 60 * 1000,
+        ttlMs: 24 * 60 * 60 * 1000,
+        threshold: 0.7,
+        maxMemories: 2,
+    };
+}
+// opencode ≥1.18 no longer publishes `session.next.step.ended`. Steps settle as
+// `step-finish` parts carried by `message.part.updated`. Messages also emit
+// `message.updated` with `info.role='assistant'` and `info.time.completed` once
+// the final assistant message is settled. These helpers normalize both shapes
+// back into the old StepEndedProps contract.
+function stepPropsFromPartUpdated(props) {
+    const part = props?.part;
+    if (!part || part.type !== 'step-finish')
+        return null;
+    return {
+        sessionID: part.sessionID,
+        assistantMessageID: part.messageID,
+        finish: part.reason,
+    };
+}
+function stepPropsFromMessageUpdated(props) {
+    const info = props?.info;
+    if (!info || info.role !== 'assistant' || !info.time?.completed)
+        return null;
+    return {
+        sessionID: info.sessionID,
+        assistantMessageID: info.id,
+        finish: info.finish,
+    };
+}
+function shouldConsiderStep(props) {
+    if (!props.sessionID || !props.assistantMessageID)
+        return false;
+    if (exports.FINISHED_EXCLUSIONS.includes(props.finish || ''))
+        return false;
+    return true;
+}
+function selectMemories(results, threshold, max) {
+    return results
+        .filter((r) => r.energy >= threshold)
+        .sort((a, b) => b.energy - a.energy)
+        .slice(0, max);
+}
+/** Fingerprint of a memory group by sorted IDs — not block text, so dynamic
+ *  content (timestamps etc.) never defeats dedup. */
+function memoryFingerprint(memIds) {
+    return [...memIds].sort().join('|');
+}
+/**
+ * All per-session state for step injection. Every method is synchronous; the
+ * caller owns all awaiting. Entries expire via TtlMap (idle/ended sessions
+ * are released, not leaked).
+ */
+class StepInjectState {
+    opts;
+    queue = new ttl_map_1.TtlMap();
+    lastInjectedAt = new ttl_map_1.TtlMap();
+    seenSteps = new ttl_map_1.TtlMap();
+    seenFingerprints = new ttl_map_1.TtlMap();
+    pushedMemories = new ttl_map_1.TtlMap();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * B1 mark-before-async: returns true only the first time this assistant
+     * message ID is evaluated; call it *before* any await so concurrent
+     * duplicate step.ended events are dropped.
+     */
+    markStepSeen(sessionID, assistantMessageID) {
+        let set = this.seenSteps.get(sessionID);
+        if (!set) {
+            set = new Set();
+            this.seenSteps.set(sessionID, set);
+        }
+        if (set.has(assistantMessageID))
+            return false;
+        set.add(assistantMessageID);
+        return true;
+    }
+    /** True if this memory group was already injected this session (fingerprint dedup). */
+    fingerprintSeen(sessionID, fp) {
+        const set = this.seenFingerprints.get(sessionID);
+        return !!set && set.has(fp);
+    }
+    rememberFingerprint(sessionID, fp) {
+        let set = this.seenFingerprints.get(sessionID);
+        if (!set) {
+            set = new Set();
+            this.seenFingerprints.set(sessionID, set);
+        }
+        set.add(fp);
+    }
+    enqueue(sessionID, injection) {
+        let list = this.queue.get(sessionID);
+        if (!list) {
+            list = [];
+            this.queue.set(sessionID, list);
+        }
+        if (list.length >= this.opts.queueCap) {
+            list.shift(); // drop oldest, keep the newest high-value group
+        }
+        list.push(injection);
+    }
+    /**
+     * B2 consumption entry: checks the frequency gate first — if the session
+     * injected recently, the whole queue is discarded (single log line) instead
+     * of failing each entry.
+     */
+    consume(sessionID) {
+        const list = this.queue.get(sessionID);
+        if (!list || list.length === 0)
+            return null;
+        const last = this.lastInjectedAt.get(sessionID);
+        if (last !== undefined && Date.now() - last < this.opts.intervalMs) {
+            this.queue.delete(sessionID);
+            return null;
+        }
+        const next = list.shift();
+        if (list.length === 0)
+            this.queue.delete(sessionID);
+        return next ?? null;
+    }
+    /** B3: register an injected group; the IDs become invisible to /api/recall/context. */
+    markInjected(sessionID, memIds, fp) {
+        this.lastInjectedAt.set(sessionID, Date.now());
+        this.rememberFingerprint(sessionID, fp);
+        let set = this.pushedMemories.get(sessionID);
+        if (!set) {
+            set = new Set();
+            this.pushedMemories.set(sessionID, set);
+        }
+        for (const id of memIds)
+            set.add(id);
+    }
+    /** B3 rollback on promptAsync failure so IDs are never permanently masked. */
+    rollbackPushed(sessionID, memIds) {
+        const set = this.pushedMemories.get(sessionID);
+        if (!set)
+            return;
+        for (const id of memIds)
+            set.delete(id);
+        if (set.size === 0)
+            this.pushedMemories.delete(sessionID);
+    }
+    pushedMemoriesFor(sessionID) {
+        return this.pushedMemories.get(sessionID) ?? new Set();
+    }
+}
+exports.StepInjectState = StepInjectState;