opensquid 0.5.395

package/dist/rag/wedge/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/rag/wedge/store.ts"],"names":[],"mappings":"AAoBA,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAClB,MAAM,WAAW,CAAC;AAGnB,oGAAoG;AACpG,qBAAa,qBAAsB,SAAQ,KAAK;aAE5B,EAAE,EAAE,MAAM;aACV,OAAO,EAAE,MAAM,EAAE;gBADjB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EAAE;CAKpC;AAED,+FAA+F;AAC/F,MAAM,WAAW,WAAY,SAAQ,iBAAiB;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,YAAY,CACV,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjE,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC;IACvE,YAAY,CACV,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC,CAAC;IAC3E,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtF,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,wFAAwF;IACxF,OAAO,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB,GAAG,gBAAgB,CAyOnB"}

package/dist/rag/wedge/store.js

@@ -0,0 +1,255 @@
+/**
+ * Wedge-gate lesson lifecycle store (retire-Rust RES-3b). The TS/libSQL replacement for the engine's
+ * `lesson.*` RPC: a dedicated `wg_lessons` table + FTS + per-file source (status-dir, src/rag/wedge/
+ * source.ts) holding the lesson lifecycle (pending → promoted/...). `promoteLesson` runs the RES-3a
+ * pure gate (`./gate.ts`); a block throws `PromotionBlockedError` (RES-3c maps it to
+ * `{status:'blocked', reasons}`). This is SEPARATE from the memory/RAG `lessons` table.
+ *
+ * MOAT INVARIANT (handed over by RES-3a): `created_at` is STORE-OWNED — set on insert from the store
+ * clock, NEVER caller-supplied. RES-3a dropped the filesystem-birthtime TamperedAge check; the 24h
+ * time-floor it still enforces is only backdate-proof because the store owns the timestamp.
+ *
+ * Imports from: @libsql/client, node:crypto, ./gate.js, ./source.js, ../backends/libsql_store.js.
+ * Imported by: RES-3c (lessons.ts / store-lesson.ts / bootstrap.ts) — not yet wired.
+ */
+import { createHash } from 'node:crypto';
+import { createClient } from '@libsql/client';
+import { ftsEscape } from '../backends/libsql_store.js';
+import { checkPromotionGate, normalizeCausalNarrative, } from './gate.js';
+import { writeWedgeRecord, deleteWedgeRecord, MAX_APPLIED_SESSION_IDS } from './source.js';
+/** Thrown by `promoteLesson` when the gate blocks. `reasons` are the kebab-prefix block strings. */
+export class PromotionBlockedError extends Error {
+    id;
+    reasons;
+    constructor(id, reasons) {
+        super(`Lesson ${id} promotion blocked: ${reasons.join('; ')}`);
+        this.id = id;
+        this.reasons = reasons;
+        this.name = 'PromotionBlockedError';
+    }
+}
+export function wedgeLessonStore(opts) {
+    let client = null;
+    const now = opts.nowIso ?? (() => new Date().toISOString());
+    const db = () => {
+        if (!client)
+            throw new Error('wedge-store: not initialized');
+        return client;
+    };
+    // The moat-critical projection: row → the exact LessonFrontmatter the gate reads.
+    const toFrontmatter = (r) => ({
+        status: r.status,
+        ...(r.supersededAt !== undefined ? { supersededAt: r.supersededAt } : {}),
+        createdAt: r.createdAt,
+        appliedCount: r.appliedCount,
+        thumbsDownCount: r.thumbsDownCount,
+        externalSignalSources: r.externalSignalSources,
+        appliedSessionIds: r.appliedSessionIds,
+        ...(r.causalNarrative !== undefined ? { causalNarrative: r.causalNarrative } : {}),
+    });
+    // typeof-guarded coercion (libsql Values are unknown-typed; no String()/Number() on unknown).
+    const str = (v) => (typeof v === 'string' ? v : '');
+    const sopt = (v) => typeof v === 'string' && v.length > 0 ? v : undefined;
+    const num = (v) => typeof v === 'number' ? v : typeof v === 'bigint' ? Number(v) : 0;
+    const rowToWedge = (row) => {
+        const packId = sopt(row.pack_id);
+        const externalId = sopt(row.external_id);
+        const promotedAt = sopt(row.promoted_at);
+        const supersededAt = sopt(row.superseded_at);
+        const lastAppliedAt = sopt(row.last_applied_at);
+        const cn = str(row.causal_narrative);
+        return {
+            id: str(row.id),
+            description: str(row.description),
+            body: str(row.body),
+            status: str(row.status),
+            authoredBy: (str(row.authored_by) || 'agent'),
+            ...(packId !== undefined ? { packId } : {}),
+            ...(externalId !== undefined ? { externalId } : {}),
+            createdAt: str(row.created_at),
+            updatedAt: str(row.updated_at),
+            ...(promotedAt !== undefined ? { promotedAt } : {}),
+            ...(supersededAt !== undefined ? { supersededAt } : {}),
+            ...(lastAppliedAt !== undefined ? { lastAppliedAt } : {}),
+            appliedCount: num(row.applied_count),
+            thumbsUpCount: num(row.thumbs_up_count),
+            thumbsDownCount: num(row.thumbs_down_count),
+            externalSignalSources: JSON.parse(str(row.external_signal_sources) || '[]'),
+            appliedSessionIds: JSON.parse(str(row.applied_session_ids) || '[]'),
+            // Normalize the DB-stored JSON the same way as the per-file reader: RES-3d migrated rows
+            // carry snake_case `evidence_refs`, which a blind cast left undefined (gate mis-block / crash).
+            ...(cn !== ''
+                ? { causalNarrative: normalizeCausalNarrative(JSON.parse(cn)) }
+                : {}),
+        };
+    };
+    const read = async (id) => {
+        const rs = await db().execute({ sql: `SELECT * FROM wg_lessons WHERE id = ?`, args: [id] });
+        if (rs.rows.length === 0)
+            throw new Error(`wedge-store: lesson ${id} not found`);
+        return rowToWedge(rs.rows[0]);
+    };
+    // The table + FTS insert for one row — shared by upsert (file-first write path) and rebuild
+    // (DB-only migration path). One INSERT definition so the moat-shaped column list can't drift.
+    const dbInsert = async (c, r) => {
+        await c.execute({
+            sql: `INSERT INTO wg_lessons (id, description, body, status, authored_by, pack_id, external_id,
+        created_at, updated_at, promoted_at, superseded_at, last_applied_at, applied_count,
+        thumbs_up_count, thumbs_down_count, external_signal_sources, applied_session_ids, causal_narrative)
+        VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+            args: [
+                r.id,
+                r.description,
+                r.body,
+                r.status,
+                r.authoredBy,
+                r.packId ?? null,
+                r.externalId ?? null,
+                r.createdAt,
+                r.updatedAt,
+                r.promotedAt ?? null,
+                r.supersededAt ?? null,
+                r.lastAppliedAt ?? null,
+                r.appliedCount,
+                r.thumbsUpCount,
+                r.thumbsDownCount,
+                JSON.stringify(r.externalSignalSources),
+                JSON.stringify(r.appliedSessionIds),
+                r.causalNarrative ? JSON.stringify(r.causalNarrative) : null,
+            ],
+        });
+        await c.execute({
+            sql: `INSERT INTO wg_lessons_fts (id, description, body) VALUES (?,?,?)`,
+            args: [r.id, r.description, r.body],
+        });
+    };
+    // Idempotent upsert: FILE-FIRST (writeWedgeRecord derives the status-dir from row.status, so the
+    // new-status file lands before the DB), then delete-then-insert across table + FTS.
+    const upsert = async (r) => {
+        await writeWedgeRecord(opts.sourceDir, r);
+        const c = db();
+        await c.execute({ sql: `DELETE FROM wg_lessons WHERE id = ?`, args: [r.id] });
+        await c.execute({ sql: `DELETE FROM wg_lessons_fts WHERE id = ?`, args: [r.id] });
+        await dbInsert(c, r);
+    };
+    return {
+        async init() {
+            client = createClient({ url: opts.dbUrl });
+            await client.execute(`CREATE TABLE IF NOT EXISTS wg_lessons (
+        id TEXT PRIMARY KEY, description TEXT NOT NULL, body TEXT NOT NULL, status TEXT NOT NULL,
+        authored_by TEXT NOT NULL, pack_id TEXT, external_id TEXT,
+        created_at TEXT NOT NULL, updated_at TEXT NOT NULL, promoted_at TEXT, superseded_at TEXT,
+        last_applied_at TEXT, applied_count INTEGER NOT NULL DEFAULT 0,
+        thumbs_up_count INTEGER NOT NULL DEFAULT 0, thumbs_down_count INTEGER NOT NULL DEFAULT 0,
+        external_signal_sources TEXT NOT NULL DEFAULT '[]', applied_session_ids TEXT NOT NULL DEFAULT '[]',
+        causal_narrative TEXT
+      );`);
+            await client.execute(`CREATE VIRTUAL TABLE IF NOT EXISTS wg_lessons_fts
+        USING fts5(id UNINDEXED, description, body);`);
+        },
+        async createLesson(input) {
+            const createdAt = now(); // STORE-OWNED — caller-supplied created_at is IGNORED (moat invariant)
+            const id = `les-${createHash('sha256')
+                .update(input.description + '\n' + input.body)
+                .digest('hex')
+                .slice(0, 16)}`;
+            // pack `seedAsPromoted` (create directly into promoted/) is OUT OF SCOPE here — pack seed-ingest
+            // is dead (RES-1). All createLesson → pending.
+            const row = {
+                id,
+                description: input.description,
+                body: input.body,
+                status: 'pending',
+                authoredBy: input.authoredBy ?? 'agent',
+                createdAt,
+                updatedAt: createdAt,
+                appliedCount: 0,
+                thumbsUpCount: 0,
+                thumbsDownCount: 0,
+                externalSignalSources: [],
+                appliedSessionIds: [],
+                ...(input.evidenceRefs && input.evidenceRefs.length > 0
+                    ? {
+                        causalNarrative: {
+                            confidence: 'inferred',
+                            evidenceRefs: input.evidenceRefs,
+                        },
+                    }
+                    : {}),
+            };
+            await upsert(row);
+            return { id, status: 'pending', createdAt };
+        },
+        async promoteLesson(id) {
+            const row = await read(id);
+            // Use the STORE clock for the gate's `now` (not real time) — consistent with the store-owned
+            // created_at the 24h floor checks against, and deterministic under the nowIso seam.
+            const decision = checkPromotionGate(toFrontmatter(row), undefined, new Date(now()));
+            if (decision.kind === 'block')
+                throw new PromotionBlockedError(id, decision.reasons);
+            const t = now();
+            const promoted = { ...row, status: 'promoted', promotedAt: t, updatedAt: t };
+            await upsert(promoted); // writes promoted/<id>.md + DB FIRST
+            if (row.status !== 'promoted')
+                await deleteWedgeRecord(opts.sourceDir, row.status, id); // THEN remove old-status file
+            return { id, status: 'promoted' };
+        },
+        async recallLesson(query, limit = 5) {
+            const match = ftsEscape(query);
+            if (match === '')
+                return { query, returned: 0, results: [] };
+            const rs = await db().execute({
+                sql: `SELECT l.id, l.description, l.status, l.body, l.applied_count, f.rank
+              FROM wg_lessons_fts f JOIN wg_lessons l ON l.id = f.id
+              WHERE wg_lessons_fts MATCH ? AND l.status != 'discarded'
+              ORDER BY f.rank LIMIT ?`,
+                args: [match, limit],
+            });
+            const results = rs.rows.map((r) => ({
+                kind: 'lesson',
+                id: str(r.id),
+                description: str(r.description),
+                status: str(r.status),
+                body_preview: str(r.body).slice(0, 240),
+                similarity: Math.round((1 / (1 + num(r.rank))) * 1000) / 1000,
+                applied_count: num(r.applied_count),
+            }));
+            return { query, returned: results.length, results };
+        },
+        async captureFeedback(id, polarity, signalId) {
+            const row = await read(id);
+            const signals = row.externalSignalSources.includes(signalId)
+                ? row.externalSignalSources
+                : [...row.externalSignalSources, signalId]; // idempotent set-add → satisfies the external-signal gate
+            await upsert({
+                ...row,
+                thumbsUpCount: row.thumbsUpCount + (polarity === 'up' ? 1 : 0),
+                thumbsDownCount: row.thumbsDownCount + (polarity === 'down' ? 1 : 0),
+                externalSignalSources: signals,
+                updatedAt: now(),
+            });
+        },
+        async recordApplied(id, sessionId) {
+            const row = await read(id);
+            const sessions = sessionId === undefined || row.appliedSessionIds.includes(sessionId)
+                ? row.appliedSessionIds
+                : [...row.appliedSessionIds, sessionId].slice(-MAX_APPLIED_SESSION_IDS);
+            await upsert({
+                ...row,
+                appliedCount: row.appliedCount + 1,
+                lastAppliedAt: now(),
+                appliedSessionIds: sessions,
+                updatedAt: now(),
+            });
+        },
+        async rebuild(records) {
+            const c = db();
+            await c.execute(`DELETE FROM wg_lessons`);
+            await c.execute(`DELETE FROM wg_lessons_fts`);
+            for (const r of records)
+                await dbInsert(c, r);
+            return { indexed: records.length };
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/rag/wedge/store.js.map

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

package/dist/recall.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Phase 4: recall ranking utilities — Reciprocal Rank Fusion (RRF)
+ * + similarity-threshold gating.
+ *
+ * The engine returns lessons (text-match similarity) and memories
+ * (semantic-vector similarity) on different score scales — they're
+ * not directly comparable. RRF sidesteps that: it ignores absolute
+ * scores and uses ranks-within-list only. Items appearing in BOTH
+ * lists get a strong combined boost — "the text matched AND the
+ * embedding is close" is the most reliable signal.
+ *
+ * The similarity threshold filters PER-SOURCE before merging so a
+ * weak hit in one list can't poison the merged ranking. When all
+ * results are filtered out, recall returns an empty merged array —
+ * "no relevant context" is decision-makable; "top hit at sim=0.31"
+ * is noise.
+ */
+/** Conventional RRF damping constant — survives well across domains. */
+export declare const RRF_K = 60;
+/** Default minimum similarity to consider a result relevant. */
+export declare const DEFAULT_MIN_SIMILARITY = 0.5;
+export interface LessonHit {
+    kind: "lesson";
+    id: string;
+    description: string;
+    status: string;
+    body_preview: string;
+    similarity: number;
+    applied_count: number;
+}
+export interface MemoryHit {
+    kind: "memory";
+    id: string;
+    description: string;
+    body_preview: string;
+    similarity: number;
+    /** v0.5: present when the engine's `memory.search` ran in hybrid
+     * (or text-only) mode. `"both"` means the hit surfaced from both
+     * the semantic neighborhood AND the text-match scan — strongest
+     * signal. Surfaced through to the MCP response for diagnostics. */
+    source?: "semantic" | "text" | "both";
+}
+export type RecallHit = LessonHit | MemoryHit;
+export interface MergedHit {
+    kind: "lesson" | "memory";
+    id: string;
+    description: string;
+    body_preview: string;
+    /** Original per-source similarity (lesson text-match or memory semantic). */
+    similarity: number;
+    /** RRF score — higher is better. Not directly comparable to similarity. */
+    rrf_score: number;
+    /** 1-based rank in the lesson list (undefined if not a lesson hit). */
+    lesson_rank?: number;
+    /** 1-based rank in the memory list (undefined if not a memory hit). */
+    memory_rank?: number;
+    /** v0.5: when this hit came from a memory and the engine produced
+     * the memory in hybrid (or text-only) mode, this carries the
+     * sub-source attribution: `"semantic"`, `"text"`, or `"both"`.
+     * Lesson hits leave this undefined (engine.recall doesn't expose
+     * a sub-source). */
+    source?: "semantic" | "text" | "both";
+}
+/**
+ * Filter a hit list to those with similarity at or above `threshold`.
+ * Stable: preserves the input order (which is engine-side rank).
+ */
+export declare function filterBySimilarity<T extends {
+    similarity: number;
+}>(hits: T[], threshold: number): T[];
+/**
+ * Reciprocal Rank Fusion across two ranked lists. The RRF score for
+ * an item is `sum over each source list: 1 / (RRF_K + rank_in_that_list)`,
+ * where rank is 1-based. Items appearing in both lists accumulate
+ * contributions and naturally rank above single-source items.
+ *
+ * Returns merged hits ordered by descending `rrf_score`. Identity is
+ * by `id` — a lesson and a memory with the same id (engine never
+ * collides these in practice) would merge; we treat that as harmless.
+ */
+export declare function mergeRrf(lessons: LessonHit[], memories: MemoryHit[]): MergedHit[];
+//# sourceMappingURL=recall.d.ts.map

package/dist/recall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall.d.ts","sourceRoot":"","sources":["../src.legacy/recall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,wEAAwE;AACxE,eAAO,MAAM,KAAK,KAAK,CAAC;AAExB,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB;;;uEAGmE;IACnE,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;CACvC;AAED,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9C,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;wBAIoB;IACpB,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;CACvC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,EACjE,IAAI,EAAE,CAAC,EAAE,EACT,SAAS,EAAE,MAAM,GAChB,CAAC,EAAE,CAGL;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAwCjF"}

package/dist/recall.js

@@ -0,0 +1,81 @@
+/**
+ * Phase 4: recall ranking utilities — Reciprocal Rank Fusion (RRF)
+ * + similarity-threshold gating.
+ *
+ * The engine returns lessons (text-match similarity) and memories
+ * (semantic-vector similarity) on different score scales — they're
+ * not directly comparable. RRF sidesteps that: it ignores absolute
+ * scores and uses ranks-within-list only. Items appearing in BOTH
+ * lists get a strong combined boost — "the text matched AND the
+ * embedding is close" is the most reliable signal.
+ *
+ * The similarity threshold filters PER-SOURCE before merging so a
+ * weak hit in one list can't poison the merged ranking. When all
+ * results are filtered out, recall returns an empty merged array —
+ * "no relevant context" is decision-makable; "top hit at sim=0.31"
+ * is noise.
+ */
+/** Conventional RRF damping constant — survives well across domains. */
+export const RRF_K = 60;
+/** Default minimum similarity to consider a result relevant. */
+export const DEFAULT_MIN_SIMILARITY = 0.5;
+/**
+ * Filter a hit list to those with similarity at or above `threshold`.
+ * Stable: preserves the input order (which is engine-side rank).
+ */
+export function filterBySimilarity(hits, threshold) {
+    if (threshold <= 0)
+        return hits;
+    return hits.filter((h) => h.similarity >= threshold);
+}
+/**
+ * Reciprocal Rank Fusion across two ranked lists. The RRF score for
+ * an item is `sum over each source list: 1 / (RRF_K + rank_in_that_list)`,
+ * where rank is 1-based. Items appearing in both lists accumulate
+ * contributions and naturally rank above single-source items.
+ *
+ * Returns merged hits ordered by descending `rrf_score`. Identity is
+ * by `id` — a lesson and a memory with the same id (engine never
+ * collides these in practice) would merge; we treat that as harmless.
+ */
+export function mergeRrf(lessons, memories) {
+    const byId = new Map();
+    lessons.forEach((h, idx) => {
+        const rank = idx + 1; // 1-based
+        const score = 1 / (RRF_K + rank);
+        byId.set(h.id, {
+            kind: "lesson",
+            id: h.id,
+            description: h.description,
+            body_preview: h.body_preview,
+            similarity: h.similarity,
+            rrf_score: score,
+            lesson_rank: rank,
+        });
+    });
+    memories.forEach((h, idx) => {
+        const rank = idx + 1;
+        const score = 1 / (RRF_K + rank);
+        const existing = byId.get(h.id);
+        if (existing) {
+            existing.rrf_score += score;
+            existing.memory_rank = rank;
+            if (h.source)
+                existing.source = h.source;
+        }
+        else {
+            byId.set(h.id, {
+                kind: "memory",
+                id: h.id,
+                description: h.description,
+                body_preview: h.body_preview,
+                similarity: h.similarity,
+                rrf_score: score,
+                memory_rank: rank,
+                source: h.source,
+            });
+        }
+    });
+    return Array.from(byId.values()).sort((a, b) => b.rrf_score - a.rrf_score);
+}
+//# sourceMappingURL=recall.js.map

package/dist/recall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall.js","sourceRoot":"","sources":["../src.legacy/recall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,wEAAwE;AACxE,MAAM,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;AAExB,gEAAgE;AAChE,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAgD1C;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAS,EACT,SAAiB;IAEjB,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,IAAI,SAAS,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAoB,EAAE,QAAqB;IAClE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAqB,CAAC;IAE1C,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE;QACzB,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,UAAU;QAChC,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACb,IAAI,EAAE,QAAQ;YACd,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,YAAY,EAAE,CAAC,CAAC,YAAY;YAC5B,UAAU,EAAE,CAAC,CAAC,UAAU;YACxB,SAAS,EAAE,KAAK;YAChB,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE;QAC1B,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC;QACrB,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;QACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,SAAS,IAAI,KAAK,CAAC;YAC5B,QAAQ,CAAC,WAAW,GAAG,IAAI,CAAC;YAC5B,IAAI,CAAC,CAAC,MAAM;gBAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;QAC3C,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACb,IAAI,EAAE,QAAQ;gBACd,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,YAAY,EAAE,CAAC,CAAC,YAAY;gBAC5B,UAAU,EAAE,CAAC,CAAC,UAAU;gBACxB,SAAS,EAAE,KAAK;gBAChB,WAAW,EAAE,IAAI;gBACjB,MAAM,EAAE,CAAC,CAAC,MAAM;aACjB,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;AAC7E,CAAC"}

package/dist/runtime/agent_bridge/agent_loop.d.ts

@@ -0,0 +1,151 @@
+/**
+ * agent_bridge — agent loop core (WAB.4, 0.5.97).
+ *
+ * Authoritative spec: `docs/tasks/T-warm-agent-chat-bridge.md` WAB.4.
+ * Architecture: `docs/tasks/WAB.1-architecture.md` decisions (c) + (g).
+ *
+ * Responsibility:
+ *   Drive a single agent turn against the Anthropic Messages API:
+ *     1. Take the persisted `state.history`, append the inbound user
+ *        message to a working copy (do NOT mutate `state`).
+ *     2. Apply cache_control markers to the system prompt + the last
+ *        two USER messages in the working history (Anthropic's
+ *        prompt-cache breakpoint policy — see comment below).
+ *     3. Loop `messages.create` → assistant block → if `stop_reason`
+ *        is `'tool_use'`, dispatch tools, append `tool_result` blocks
+ *        back to working history, repeat. Otherwise return.
+ *     4. Cap at `MAX_TOOL_ITERATIONS=8` round-trips; throw on overflow.
+ *     5. Return the NEW history entries (user input + every assistant
+ *        block + tool_result blocks) plus the final reply text. Caller
+ *        feeds these into `SessionManager.appendTurn` which atomically
+ *        persists + mutates state.
+ *
+ * Decision (c) lock (WAB.1):
+ *   The Anthropic SDK client is passed in via `opts.client` — there is
+ *   exactly ONE daemon-wide client. We do NOT construct or hold one
+ *   here. This keeps connection pooling sane (one HTTP agent across all
+ *   sessions) and matches Hermes's `_get_or_create_agent` pattern.
+ *
+ * Decision (g) lock (WAB.1):
+ *   `opts.model` is a fully-resolved string (e.g.
+ *   `claude-haiku-4-5-20251001`) — alias resolution happens upstream in
+ *   WAB.6's `pack_binding.ts`. This module is model-neutral; it never
+ *   inspects the string. v1 supports `api` mode only because the
+ *   subscription/local/MCP modes don't expose a tool-use round-trip.
+ *
+ * Cache-control marker policy (Anthropic prompt caching):
+ *   - System prompt: ALWAYS marked (1 breakpoint). Most stable thing
+ *     across turns — the agent's identity + tool surface description.
+ *   - Last 2 user messages: marked on the FINAL content block of each
+ *     (2 breakpoints). This keeps the previous-turn context warm
+ *     through the current turn so a follow-up message hits the cache.
+ *   - Total: 3 of Anthropic's 4-breakpoint limit. We reserve the 4th
+ *     for a future tools-section marker.
+ *   - 5-minute TTL: Anthropic's default. We do not refresh — sessions
+ *     idle longer than 5 min lose the cache (WAB.1 risk callout
+ *     accepted this).
+ *
+ * SDK type compatibility:
+ *   `@anthropic-ai/sdk` v0.30.1's STABLE `messages.d.ts` does NOT
+ *   include `cache_control` on content-block params (only the `beta`
+ *   namespace does). The API itself accepts `cache_control` on the
+ *   stable endpoint — prompt caching went GA mid-2024 and the SDK
+ *   types haven't caught up on v0.30. To avoid forcing the upgrade or
+ *   binding ourselves to the beta path, we use a STRUCTURAL contract
+ *   (`AnthropicMessageClient`) below — opensquid owns the types, the
+ *   real SDK client satisfies the contract structurally. No `any`, no
+ *   `as never` casts at the API boundary.
+ *
+ * Imports from: ./types.js.
+ * Imported by: dispatcher.ts (WAB.5 — glue), daemon.ts (WAB.7),
+ *   agent_loop.test.ts.
+ */
+import type { ChatHistoryEntry, SessionState, ToolDispatcher, ToolSpec } from './types.js';
+/** Hard cap on tool-use round-trips per turn. Throws on overflow. */
+export declare const MAX_TOOL_ITERATIONS = 8;
+/** Default `max_tokens` for the assistant's reply. Overridable per call. */
+export declare const DEFAULT_MAX_TOKENS = 1024;
+/** Number of trailing user messages to mark with cache_control. */
+export declare const CACHE_BREAKPOINT_USER_MSGS = 2;
+export interface AnthropicCacheControl {
+    type: 'ephemeral';
+}
+export interface AnthropicTextBlockParam {
+    type: 'text';
+    text: string;
+    cache_control?: AnthropicCacheControl;
+}
+export interface AnthropicToolUseBlockParam {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+    cache_control?: AnthropicCacheControl;
+}
+export interface AnthropicToolResultBlockParam {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    cache_control?: AnthropicCacheControl;
+}
+export type AnthropicContentBlockParam = AnthropicTextBlockParam | AnthropicToolUseBlockParam | AnthropicToolResultBlockParam;
+export interface AnthropicMessageParam {
+    role: 'user' | 'assistant';
+    content: AnthropicContentBlockParam[];
+}
+export interface AnthropicSystemBlock {
+    type: 'text';
+    text: string;
+    cache_control?: AnthropicCacheControl;
+}
+export interface AnthropicResponseTextBlock {
+    type: 'text';
+    text: string;
+}
+export interface AnthropicResponseToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+}
+export type AnthropicResponseBlock = AnthropicResponseTextBlock | AnthropicResponseToolUseBlock;
+export interface AnthropicMessageResponse {
+    content: AnthropicResponseBlock[];
+    stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | null;
+}
+export interface AnthropicMessageCreateParams {
+    model: string;
+    max_tokens: number;
+    system: AnthropicSystemBlock[];
+    tools: ToolSpec[];
+    messages: AnthropicMessageParam[];
+}
+export interface AnthropicMessageClient {
+    create(params: AnthropicMessageCreateParams): Promise<AnthropicMessageResponse>;
+}
+export interface RunAgentTurnOptions {
+    /** Daemon-wide Anthropic `client.messages` (one instance per daemon). */
+    client: AnthropicMessageClient;
+    /** Resolved model id (alias resolution upstream in WAB.6). */
+    model: string;
+    /** Assistant system prompt (loaded from pack `chat_agent.yaml` in WAB.6). */
+    systemPrompt: string;
+    /** Tool surface — typically `dispatcher.list()`. */
+    tools: ToolSpec[];
+    /** Resolves `tool_use` blocks from the model. */
+    dispatcher: ToolDispatcher;
+    /** Override `DEFAULT_MAX_TOKENS`. */
+    maxTokens?: number;
+    /** Override `MAX_TOOL_ITERATIONS`. */
+    maxToolIterations?: number;
+    /** Injected clock (tests). Defaults to `() => new Date().toISOString()`. */
+    nowIso?: () => string;
+}
+export interface RunAgentTurnResult {
+    /** New entries appended during this turn (user input + assistant + tool_results). */
+    assistantEntries: ChatHistoryEntry[];
+    /** Final text reply (concatenated text blocks from the terminal assistant message). */
+    replyText: string;
+}
+export declare function runAgentTurn(state: SessionState, inboundText: string, opts: RunAgentTurnOptions): Promise<RunAgentTurnResult>;
+//# sourceMappingURL=agent_loop.d.ts.map

package/dist/runtime/agent_bridge/agent_loop.d.ts.map

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