@0xmaxma/claude-gateway 1.6.8 → 1.7.0

package/dist/agent/knowledge/archive-db.js

@@ -0,0 +1,474 @@
+"use strict";
+/**
+ * Per-agent knowledge archive — SQLite/FTS5 substrate (planning-64 K0).
+ *
+ * One `kb.sqlite` per agent, alongside `history.db`. Backed by `node:sqlite`
+ * `DatabaseSync` (zero new dependency — the same substrate `src/history/db.ts`
+ * uses, which already runs FTS5). Schema adapted from openclaw memory-core,
+ * trimmed for v1 (FTS5-only; no vector table yet).
+ *
+ * IMPORTANT: `DatabaseSync` is synchronous. Every method here blocks. Callers
+ * MUST run indexing/queries OFF the gateway event loop (the nightly dreaming
+ * spawn or an out-of-process tool) — never on the HTTP read path (#277 lesson).
+ * K0 ships this as dormant infrastructure; no gateway runtime path calls it yet.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArchiveDB = void 0;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const node_sqlite_1 = require("node:sqlite");
+// Singleton cache: one DB handle per absolute file path.
+const cache = new Map();
+class ArchiveDB {
+    constructor(dbPath, tokenizer) {
+        this.dbPath = dbPath;
+        this.tokenizer = tokenizer;
+        fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+        this.db = new node_sqlite_1.DatabaseSync(dbPath);
+        this.db.exec('PRAGMA journal_mode=WAL');
+        this.db.exec('PRAGMA synchronous=NORMAL');
+        this.db.exec('PRAGMA foreign_keys=ON');
+        // All sessions of an agent reindex the SAME kb.sqlite; concurrent reindex
+        // subprocesses would otherwise hit SQLITE_BUSY immediately. Wait instead of
+        // failing so a losing writer completes rather than silently no-opping.
+        this.db.exec('PRAGMA busy_timeout=5000');
+        this._initSchema();
+        this.stmts = {
+            getSource: this.db.prepare('SELECT id, path, hash, mtime, size, source FROM kb_sources WHERE path = ?'),
+            upsertSource: this.db.prepare(`INSERT INTO kb_sources (path, hash, mtime, size, source) VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(path) DO UPDATE SET hash=excluded.hash, mtime=excluded.mtime, size=excluded.size, source=excluded.source`),
+            deleteSource: this.db.prepare('DELETE FROM kb_sources WHERE path = ?'),
+            insertChunk: this.db.prepare(`INSERT INTO kb_chunks (id, path, start_line, end_line, text, updated_at, entry_hash) VALUES (?, ?, ?, ?, ?, ?, ?)`),
+            insertRecall: this.db.prepare(`INSERT INTO kb_chunk_recall (chunk_id, importance, triggers, project_key) VALUES (?, ?, ?, ?)`),
+            insertProvenance: this.db.prepare(`INSERT INTO kb_chunk_provenance (chunk_id, origin_class, session_kind, observed_at, supersedes_key)
+         VALUES (?, ?, ?, ?, ?)`),
+            // Age survives reindex: first_seen is written ONCE (never reset); a later
+            // reindex of the same entry only refreshes its current path (planning-66).
+            upsertLifecycle: this.db.prepare(`INSERT INTO kb_entry_lifecycle (entry_hash, path, first_seen) VALUES (?, ?, ?)
+         ON CONFLICT(entry_hash) DO UPDATE SET path = excluded.path`),
+        };
+    }
+    static forPath(dbPath, tokenizer = 'unicode61') {
+        const abs = path.resolve(dbPath);
+        if (!cache.has(abs))
+            cache.set(abs, new ArchiveDB(abs, tokenizer));
+        return cache.get(abs);
+    }
+    static evict(dbPath) {
+        const inst = cache.get(path.resolve(dbPath));
+        if (inst)
+            inst.close(); // closes the handle + removes it from the cache
+    }
+    _initSchema() {
+        // FTS5 tokenizer is a trusted, enum-validated value (resolveArchiveConfig),
+        // never raw user input — safe to interpolate into the CREATE. NOTE (K0
+        // limitation): the FTS vtable is created with IF NOT EXISTS, so an existing
+        // kb.sqlite keeps its ORIGINAL tokenizer — changing `tokenizer` in config does
+        // not retokenize a built index. A later phase (planning-64) will persist the
+        // config signature in kb_index_state and force a rebuild when it changes.
+        const tok = this.tokenizer.replace(/[^a-z0-9]/g, '') || 'unicode61';
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS kb_sources (
+        id     INTEGER PRIMARY KEY AUTOINCREMENT,
+        path   TEXT    NOT NULL UNIQUE,
+        hash   TEXT    NOT NULL,
+        mtime  REAL    NOT NULL,
+        size   INTEGER NOT NULL,
+        source TEXT    NOT NULL DEFAULT 'memory'
+      );
+
+      CREATE TABLE IF NOT EXISTS kb_chunks (
+        rowid_id   INTEGER PRIMARY KEY AUTOINCREMENT,
+        id         TEXT    NOT NULL UNIQUE,
+        path       TEXT    NOT NULL,
+        start_line INTEGER NOT NULL,
+        end_line   INTEGER NOT NULL,
+        text       TEXT    NOT NULL,
+        updated_at INTEGER NOT NULL,
+        entry_hash TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_kb_chunks_path ON kb_chunks(path);
+      CREATE INDEX IF NOT EXISTS idx_kb_chunks_entry_hash ON kb_chunks(entry_hash);
+
+      CREATE TABLE IF NOT EXISTS kb_chunk_recall (
+        chunk_id    TEXT PRIMARY KEY,
+        importance  INTEGER CHECK (importance IS NULL OR importance BETWEEN 1 AND 10),
+        triggers    TEXT,
+        project_key TEXT,
+        FOREIGN KEY (chunk_id) REFERENCES kb_chunks(id) ON DELETE CASCADE
+      );
+
+      CREATE TABLE IF NOT EXISTS kb_chunk_provenance (
+        chunk_id       TEXT PRIMARY KEY,
+        origin_class   TEXT NOT NULL CHECK (origin_class IN ('owner','agent','untrusted','system')),
+        session_kind   TEXT NOT NULL CHECK (session_kind IN ('interactive','cron','heartbeat','subagent','unknown')),
+        observed_at    INTEGER NOT NULL,
+        supersedes_key TEXT,
+        FOREIGN KEY (chunk_id) REFERENCES kb_chunks(id) ON DELETE CASCADE
+      );
+
+      -- Per-ENTRY lifecycle (planning-66). Deliberately NOT a FK-cascade child of
+      -- kb_chunks: reindex does delete-then-insert of chunks, which would wipe any
+      -- cascade child — so age/recall/invalidation must live in a standalone table
+      -- keyed by the stable entry_hash (sha256 of normalized block text), which
+      -- survives re-chunking. NULL invalid_at = live; a stamp = soft-invalidated
+      -- (Zep bi-temporal: still indexed + searchable, never hard-deleted).
+      CREATE TABLE IF NOT EXISTS kb_entry_lifecycle (
+        entry_hash      TEXT PRIMARY KEY,
+        path            TEXT NOT NULL,
+        first_seen      INTEGER NOT NULL,
+        last_retrieved  INTEGER,
+        retrieval_count INTEGER NOT NULL DEFAULT 0,
+        superseded_by   TEXT,
+        invalid_at      INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_kb_lifecycle_invalid ON kb_entry_lifecycle(invalid_at);
+      CREATE INDEX IF NOT EXISTS idx_kb_lifecycle_superseded ON kb_entry_lifecycle(superseded_by);
+
+      -- Append-only retrieval log (planning-66). The Bun read path appends a row
+      -- per memory_search hit (fire-and-forget); the Node side folds it into
+      -- kb_entry_lifecycle.last_retrieved/retrieval_count at GC time, then clears
+      -- the folded rows. Keyed by the stable entry_hash, never the line-based id.
+      CREATE TABLE IF NOT EXISTS kb_retrieval_log (
+        rowid_id     INTEGER PRIMARY KEY AUTOINCREMENT,
+        entry_hash   TEXT    NOT NULL,
+        retrieved_at INTEGER NOT NULL
+      );
+
+      CREATE VIRTUAL TABLE IF NOT EXISTS kb_chunks_fts USING fts5(
+        text,
+        content='kb_chunks',
+        content_rowid='rowid_id',
+        tokenize='${tok}'
+      );
+
+      -- INVARIANT: kb_chunks rows are IMMUTABLE — only ever INSERTed or DELETEd
+      -- (replaceSource does delete-then-insert, never UPDATE). Hence there is no
+      -- AFTER UPDATE trigger and the revision counter bumps on INSERT only. Any
+      -- future code that UPDATEs kb_chunks.text MUST add an _au FTS trigger + a
+      -- revision bump, or the FTS index will silently desync.
+      CREATE TRIGGER IF NOT EXISTS kb_chunks_ai AFTER INSERT ON kb_chunks BEGIN
+        INSERT INTO kb_chunks_fts(rowid, text) VALUES (new.rowid_id, new.text);
+      END;
+      CREATE TRIGGER IF NOT EXISTS kb_chunks_ad AFTER DELETE ON kb_chunks BEGIN
+        INSERT INTO kb_chunks_fts(kb_chunks_fts, rowid, text) VALUES ('delete', old.rowid_id, old.text);
+      END;
+
+      -- Single revision counter, bumped on any source/chunk mutation. An
+      -- optimistic-concurrency hook for later phases (shadow reindex publish).
+      CREATE TABLE IF NOT EXISTS kb_index_state (
+        id       INTEGER PRIMARY KEY CHECK (id = 1),
+        revision INTEGER NOT NULL
+      );
+      INSERT OR IGNORE INTO kb_index_state (id, revision) VALUES (1, 0);
+
+      CREATE TRIGGER IF NOT EXISTS kb_sources_rev AFTER INSERT ON kb_sources BEGIN
+        UPDATE kb_index_state SET revision = revision + 1 WHERE id = 1;
+      END;
+      CREATE TRIGGER IF NOT EXISTS kb_sources_rev_u AFTER UPDATE ON kb_sources BEGIN
+        UPDATE kb_index_state SET revision = revision + 1 WHERE id = 1;
+      END;
+      CREATE TRIGGER IF NOT EXISTS kb_sources_rev_d AFTER DELETE ON kb_sources BEGIN
+        UPDATE kb_index_state SET revision = revision + 1 WHERE id = 1;
+      END;
+      CREATE TRIGGER IF NOT EXISTS kb_chunks_rev AFTER INSERT ON kb_chunks BEGIN
+        UPDATE kb_index_state SET revision = revision + 1 WHERE id = 1;
+      END;
+    `);
+        // Idempotent column migration (planning-66): a kb.sqlite built before the
+        // entry_hash column exists keeps its rows via CREATE TABLE IF NOT EXISTS, but
+        // the new column is absent. Add it in place (nullable, no default) so the
+        // insert/read statements below don't fail on an upgraded DB. The lifecycle +
+        // retrieval-log tables above are new, so IF NOT EXISTS creates them cleanly.
+        const cols = this.db.prepare(`PRAGMA table_info(kb_chunks)`).all();
+        if (!cols.some((c) => c.name === 'entry_hash')) {
+            this.db.exec(`ALTER TABLE kb_chunks ADD COLUMN entry_hash TEXT`);
+            this.db.exec(`CREATE INDEX IF NOT EXISTS idx_kb_chunks_entry_hash ON kb_chunks(entry_hash)`);
+        }
+    }
+    /** Look up an indexed source by its workspace-relative path. */
+    getSource(relPath) {
+        const row = this.stmts.getSource.get(relPath);
+        if (!row)
+            return undefined;
+        return {
+            id: row.id,
+            path: row.path,
+            hash: row.hash,
+            mtime: row.mtime,
+            size: row.size,
+            source: row.source,
+        };
+    }
+    /**
+     * Replace a file's index atomically: delete its old chunks, upsert the source
+     * row, insert the fresh chunks (+ recall + provenance), then upsert the entry
+     * lifecycle rows for ALL of the file's blocks. Runs in a transaction so a
+     * failure never leaves a half-indexed file.
+     *
+     * `entryBlocks` (planning-66) is the FULL set of archive-entry blocks in the file
+     * — one lifecycle row each — NOT derived from chunks: a single FTS chunk can span
+     * several blocks, so per-chunk upsert would miss the inner ones. Empty for
+     * non-archive-tier files (evergreen/pinned/shared get no lifecycle).
+     */
+    replaceSource(source, chunks, entryBlocks = []) {
+        this.db.exec('BEGIN');
+        try {
+            // Drop old chunks for this path first (cascades recall + provenance + FTS).
+            this._deleteChunksForPath(source.path);
+            this.stmts.upsertSource.run(source.path, source.hash, source.mtime, source.size, source.source);
+            for (const { chunk, recall, provenance, entryHash } of chunks) {
+                this.stmts.insertChunk.run(chunk.id, chunk.path, chunk.startLine, chunk.endLine, chunk.text, chunk.updatedAt, entryHash ?? null);
+                this.stmts.insertRecall.run(chunk.id, recall.importance, recall.triggers, recall.projectKey);
+                this.stmts.insertProvenance.run(chunk.id, provenance.originClass, provenance.sessionKind, provenance.observedAt, provenance.supersedesKey);
+            }
+            // Entry lifecycle (planning-66): upsert-once first_seen per BLOCK keyed by the
+            // stable entry_hash; a re-index only refreshes the current path. Age therefore
+            // survives edits and re-chunking (kb_chunks is delete-then-insert, but this
+            // standalone table is not a cascade child, so its first_seen is preserved).
+            for (const b of entryBlocks) {
+                this.stmts.upsertLifecycle.run(b.entryHash, source.path, b.firstSeen);
+            }
+            this.db.exec('COMMIT');
+        }
+        catch (err) {
+            // A failing COMMIT may have already rolled the txn back, so this ROLLBACK
+            // can itself throw "no transaction is active" — swallow it so the ORIGINAL
+            // error is the one that propagates.
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                /* txn already unwound */
+            }
+            throw err;
+        }
+    }
+    /** Remove a source and all its chunks (file disappeared). */
+    deleteSource(relPath) {
+        this.db.exec('BEGIN');
+        try {
+            this._deleteChunksForPath(relPath);
+            this.stmts.deleteSource.run(relPath);
+            this.db.exec('COMMIT');
+        }
+        catch (err) {
+            // A failing COMMIT may have already rolled the txn back, so this ROLLBACK
+            // can itself throw "no transaction is active" — swallow it so the ORIGINAL
+            // error is the one that propagates.
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                /* txn already unwound */
+            }
+            throw err;
+        }
+    }
+    _deleteChunksForPath(relPath) {
+        // Explicit DELETE so the FTS delete-trigger + FK cascades both fire.
+        this.db.prepare('DELETE FROM kb_chunks WHERE path = ?').run(relPath);
+    }
+    /** All indexed source paths. */
+    listSourcePaths() {
+        const rows = this.db.prepare('SELECT path FROM kb_sources ORDER BY path').all();
+        return rows.map((r) => r.path);
+    }
+    /** Current index revision (bumped on every mutation). */
+    getRevision() {
+        const row = this.db.prepare('SELECT revision FROM kb_index_state WHERE id = 1').get();
+        return row ? row.revision : 0;
+    }
+    /** Total chunk count (test/introspection helper). */
+    chunkCount() {
+        const row = this.db.prepare('SELECT COUNT(*) AS n FROM kb_chunks').get();
+        return row.n;
+    }
+    /** Provenance row for a chunk (test/introspection helper). */
+    getProvenance(chunkId) {
+        const row = this.db
+            .prepare('SELECT origin_class, session_kind, observed_at, supersedes_key FROM kb_chunk_provenance WHERE chunk_id = ?')
+            .get(chunkId);
+        if (!row)
+            return undefined;
+        return {
+            originClass: row.origin_class,
+            sessionKind: row.session_kind,
+            observedAt: row.observed_at,
+            supersedesKey: row.supersedes_key ?? null,
+        };
+    }
+    // ── Entry lifecycle / staleness GC (planning-66) ──────────────────────────
+    /** Append a retrieval event (Node-side seed for tests + aggregation symmetry). */
+    logRetrieval(entryHash, retrievedAt) {
+        this.db
+            .prepare('INSERT INTO kb_retrieval_log (entry_hash, retrieved_at) VALUES (?, ?)')
+            .run(entryHash, retrievedAt);
+    }
+    /**
+     * Fold the append-only retrieval log into per-entry lifecycle: bump each entry's
+     * `last_retrieved` to the newest hit and add the hit count, then delete the
+     * folded rows (bounded by the max rowid read, so a concurrent append after this
+     * read survives to the next GC). Returns how many log rows were folded. A hit for
+     * an entry_hash no longer in lifecycle (its text changed → new hash) updates 0
+     * rows and is harmlessly dropped.
+     */
+    aggregateRetrievalLog() {
+        const rows = this.db
+            .prepare('SELECT rowid_id, entry_hash, retrieved_at FROM kb_retrieval_log ORDER BY rowid_id')
+            .all();
+        if (rows.length === 0)
+            return 0;
+        const agg = new Map();
+        let maxRowId = 0;
+        for (const r of rows) {
+            maxRowId = Math.max(maxRowId, r.rowid_id);
+            const cur = agg.get(r.entry_hash);
+            if (cur) {
+                cur.max = Math.max(cur.max, r.retrieved_at);
+                cur.count += 1;
+            }
+            else {
+                agg.set(r.entry_hash, { max: r.retrieved_at, count: 1 });
+            }
+        }
+        const upd = this.db.prepare(`UPDATE kb_entry_lifecycle
+       SET last_retrieved = MAX(COALESCE(last_retrieved, 0), ?), retrieval_count = retrieval_count + ?
+       WHERE entry_hash = ?`);
+        this.db.exec('BEGIN');
+        try {
+            for (const [hash, { max, count }] of agg)
+                upd.run(max, count, hash);
+            this.db.prepare('DELETE FROM kb_retrieval_log WHERE rowid_id <= ?').run(maxRowId);
+            this.db.exec('COMMIT');
+        }
+        catch (err) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                /* txn already unwound */
+            }
+            throw err;
+        }
+        return rows.length;
+    }
+    /** All lifecycle rows, joined with the MAX importance across their chunks. */
+    listLifecycle() {
+        const rows = this.db
+            .prepare(`SELECT l.entry_hash, l.path, l.first_seen, l.last_retrieved, l.retrieval_count,
+                l.superseded_by, l.invalid_at,
+                (SELECT MAX(r.importance) FROM kb_chunks c JOIN kb_chunk_recall r ON r.chunk_id = c.id
+                 WHERE c.entry_hash = l.entry_hash) AS importance
+         FROM kb_entry_lifecycle l`)
+            .all();
+        return rows.map((r) => ({
+            entryHash: r.entry_hash,
+            path: r.path,
+            firstSeen: r.first_seen,
+            lastRetrieved: r.last_retrieved ?? null,
+            retrievalCount: r.retrieval_count ?? 0,
+            supersededBy: r.superseded_by ?? null,
+            invalidAt: r.invalid_at ?? null,
+            importance: r.importance ?? null,
+        }));
+    }
+    /** Read one lifecycle row (test/introspection helper). */
+    getLifecycle(entryHash) {
+        return this.listLifecycle().find((l) => l.entryHash === entryHash);
+    }
+    /** Mark `entryHash` superseded by `bySpec` (or clear when null). */
+    setSuperseded(entryHash, bySpec) {
+        this.db
+            .prepare('UPDATE kb_entry_lifecycle SET superseded_by = ? WHERE entry_hash = ?')
+            .run(bySpec, entryHash);
+    }
+    /**
+     * Populate the (previously inert) provenance `supersedes_key` for every chunk of
+     * a superseded entry — so the search-side provenance reflects supersession too,
+     * not just the lifecycle table. Best-effort mirror of {@link setSuperseded}.
+     */
+    setSupersedesKeyForEntry(entryHash, key) {
+        this.db
+            .prepare(`UPDATE kb_chunk_provenance SET supersedes_key = ?
+         WHERE chunk_id IN (SELECT id FROM kb_chunks WHERE entry_hash = ?)`)
+            .run(key, entryHash);
+    }
+    /** Stamp (soft-invalidate) or clear an entry's invalidation. */
+    stampInvalid(entryHash, invalidAt) {
+        this.db
+            .prepare('UPDATE kb_entry_lifecycle SET invalid_at = ? WHERE entry_hash = ?')
+            .run(invalidAt, entryHash);
+    }
+    /**
+     * Keyword search over chunk text (FTS5 BM25). K0 helper for tests/introspection;
+     * the ranked, agent-facing `memory_search` tool is K1. Returns best matches
+     * first. Query tokens are quoted so punctuation can't inject FTS syntax.
+     */
+    search(query, limit = 10) {
+        const match = query
+            .split(/[^\p{L}\p{N}_]+/u)
+            .filter(Boolean)
+            .map((t) => `"${t.replace(/"/g, '""')}"`)
+            .join(' ');
+        if (!match)
+            return [];
+        const rows = this.db
+            .prepare(`SELECT c.id, c.path, c.start_line, c.end_line, c.text, c.updated_at
+         FROM kb_chunks_fts f JOIN kb_chunks c ON c.rowid_id = f.rowid
+         WHERE kb_chunks_fts MATCH ? ORDER BY bm25(kb_chunks_fts) LIMIT ?`)
+            .all(match, limit);
+        return rows.map((r) => ({
+            id: r.id,
+            path: r.path,
+            startLine: r.start_line,
+            endLine: r.end_line,
+            text: r.text,
+            updatedAt: r.updated_at,
+        }));
+    }
+    /**
+     * Close the handle AND drop it from the singleton cache, so a later
+     * `forPath(samePath)` opens a fresh handle instead of returning this closed one
+     * (whose statements would throw). Mirrors `evict()`.
+     */
+    close() {
+        this.db.close();
+        cache.delete(this.dbPath);
+    }
+}
+exports.ArchiveDB = ArchiveDB;
+//# sourceMappingURL=archive-db.js.map

package/dist/agent/knowledge/archive-db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-db.js","sourceRoot":"","sources":["../../../src/agent/knowledge/archive-db.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,2CAA6B;AAC7B,uCAAyB;AACzB,6CAA0D;AAQ1D,yDAAyD;AACzD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;AA4B3C,MAAa,SAAS;IAcpB,YAAoB,MAAc,EAAE,SAAiB;QACnD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC,EAAE,GAAG,IAAI,0BAAY,CAAC,MAAM,CAAC,CAAC;QACnC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;QACxC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;QAC1C,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;QACvC,0EAA0E;QAC1E,4EAA4E;QAC5E,uEAAuE;QACvE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;QACzC,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG;YACX,SAAS,EAAE,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,2EAA2E,CAAC;YACvG,YAAY,EAAE,IAAI,CAAC,EAAE,CAAC,OAAO,CAC3B;8HACsH,CACvH;YACD,YAAY,EAAE,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,uCAAuC,CAAC;YACtE,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC,OAAO,CAC1B,mHAAmH,CACpH;YACD,YAAY,EAAE,IAAI,CAAC,EAAE,CAAC,OAAO,CAC3B,+FAA+F,CAChG;YACD,gBAAgB,EAAE,IAAI,CAAC,EAAE,CAAC,OAAO,CAC/B;gCACwB,CACzB;YACD,0EAA0E;YAC1E,2EAA2E;YAC3E,eAAe,EAAE,IAAI,CAAC,EAAE,CAAC,OAAO,CAC9B;oEAC4D,CAC7D;SACF,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,OAAO,CAAC,MAAc,EAAE,SAAS,GAAG,WAAW;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,SAAS,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;QACnE,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;IACzB,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,MAAc;QACzB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAC7C,IAAI,IAAI;YAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,gDAAgD;IAC1E,CAAC;IAEO,WAAW;QACjB,4EAA4E;QAC5E,uEAAuE;QACvE,4EAA4E;QAC5E,+EAA+E;QAC/E,6EAA6E;QAC7E,0EAA0E;QAC1E,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,IAAI,WAAW,CAAC;QACpE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAwEG,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAmClB,CAAC,CAAC;QAEH,0EAA0E;QAC1E,8EAA8E;QAC9E,0EAA0E;QAC1E,6EAA6E;QAC7E,6EAA6E;QAC7E,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,8BAA8B,CAAC,CAAC,GAAG,EAA6B,CAAC;QAC9F,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC,EAAE,CAAC;YAC/C,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,kDAAkD,CAAC,CAAC;YACjE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,8EAA8E,CAAC,CAAC;QAC/F,CAAC;IACH,CAAC;IAED,gEAAgE;IAChE,SAAS,CAAC,OAAe;QACvB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAwC,CAAC;QACrF,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAC;QAC3B,OAAO;YACL,EAAE,EAAE,GAAG,CAAC,EAAY;YACpB,IAAI,EAAE,GAAG,CAAC,IAAc;YACxB,IAAI,EAAE,GAAG,CAAC,IAAc;YACxB,KAAK,EAAE,GAAG,CAAC,KAAe;YAC1B,IAAI,EAAE,GAAG,CAAC,IAAc;YACxB,MAAM,EAAE,GAAG,CAAC,MAAgB;SAC7B,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACH,aAAa,CACX,MAAoC,EACpC,MAAuB,EACvB,cAA+D,EAAE;QAEjE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACtB,IAAI,CAAC;YACH,4EAA4E;YAC5E,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACvC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;YAChG,KAAK,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,MAAM,EAAE,CAAC;gBAC9D,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CACxB,KAAK,CAAC,EAAE,EACR,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,SAAS,EACf,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,SAAS,EACf,SAAS,IAAI,IAAI,CAClB,CAAC;gBACF,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;gBAC7F,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAC7B,KAAK,CAAC,EAAE,EACR,UAAU,CAAC,WAAW,EACtB,UAAU,CAAC,WAAW,EACtB,UAAU,CAAC,UAAU,EACrB,UAAU,CAAC,aAAa,CACzB,CAAC;YACJ,CAAC;YACD,+EAA+E;YAC/E,+EAA+E;YAC/E,4EAA4E;YAC5E,4EAA4E;YAC5E,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;gBAC5B,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;YACxE,CAAC;YACD,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,0EAA0E;YAC1E,2EAA2E;YAC3E,oCAAoC;YACpC,IAAI,CAAC;gBACH,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC3B,CAAC;YAAC,MAAM,CAAC;gBACP,yBAAyB;YAC3B,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,6DAA6D;IAC7D,YAAY,CAAC,OAAe;QAC1B,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACtB,IAAI,CAAC;YACH,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;YACnC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACrC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,0EAA0E;YAC1E,2EAA2E;YAC3E,oCAAoC;YACpC,IAAI,CAAC;gBACH,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC3B,CAAC;YAAC,MAAM,CAAC;gBACP,yBAAyB;YAC3B,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAEO,oBAAoB,CAAC,OAAe;QAC1C,qEAAqE;QACrE,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,sCAAsC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACvE,CAAC;IAED,gCAAgC;IAChC,eAAe;QACb,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,2CAA2C,CAAC,CAAC,GAAG,EAA6B,CAAC;QAC3G,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,yDAAyD;IACzD,WAAW;QACT,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,kDAAkD,CAAC,CAAC,GAAG,EAEtE,CAAC;QACd,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,CAAC;IAED,qDAAqD;IACrD,UAAU;QACR,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,qCAAqC,CAAC,CAAC,GAAG,EAAmB,CAAC;QAC1F,OAAO,GAAG,CAAC,CAAC,CAAC;IACf,CAAC;IAED,8DAA8D;IAC9D,aAAa,CAAC,OAAe;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE;aAChB,OAAO,CAAC,4GAA4G,CAAC;aACrH,GAAG,CAAC,OAAO,CAAwC,CAAC;QACvD,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAC;QAC3B,OAAO;YACL,WAAW,EAAE,GAAG,CAAC,YAAmD;YACpE,WAAW,EAAE,GAAG,CAAC,YAAmD;YACpE,UAAU,EAAE,GAAG,CAAC,WAAqB;YACrC,aAAa,EAAG,GAAG,CAAC,cAAgC,IAAI,IAAI;SAC7D,CAAC;IACJ,CAAC;IAED,6EAA6E;IAE7E,kFAAkF;IAClF,YAAY,CAAC,SAAiB,EAAE,WAAmB;QACjD,IAAI,CAAC,EAAE;aACJ,OAAO,CAAC,uEAAuE,CAAC;aAChF,GAAG,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;OAOG;IACH,qBAAqB;QACnB,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE;aACjB,OAAO,CAAC,mFAAmF,CAAC;aAC5F,GAAG,EAA2E,CAAC;QAClF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QAChC,MAAM,GAAG,GAAG,IAAI,GAAG,EAA0C,CAAC;QAC9D,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;YAC1C,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;YAClC,IAAI,GAAG,EAAE,CAAC;gBACR,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC;gBAC5C,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC;YACjB,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,YAAY,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CACzB;;4BAEsB,CACvB,CAAC;QACF,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACtB,IAAI,CAAC;YACH,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,IAAI,GAAG;gBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;YACpE,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,kDAAkD,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAClF,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC;gBACH,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC3B,CAAC;YAAC,MAAM,CAAC;gBACP,yBAAyB;YAC3B,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,8EAA8E;IAC9E,aAAa;QACX,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE;aACjB,OAAO,CACN;;;;mCAI2B,CAC5B;aACA,GAAG,EAAoC,CAAC;QAC3C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtB,SAAS,EAAE,CAAC,CAAC,UAAoB;YACjC,IAAI,EAAE,CAAC,CAAC,IAAc;YACtB,SAAS,EAAE,CAAC,CAAC,UAAoB;YACjC,aAAa,EAAG,CAAC,CAAC,cAAgC,IAAI,IAAI;YAC1D,cAAc,EAAG,CAAC,CAAC,eAA0B,IAAI,CAAC;YAClD,YAAY,EAAG,CAAC,CAAC,aAA+B,IAAI,IAAI;YACxD,SAAS,EAAG,CAAC,CAAC,UAA4B,IAAI,IAAI;YAClD,UAAU,EAAG,CAAC,CAAC,UAA4B,IAAI,IAAI;SACpD,CAAC,CAAC,CAAC;IACN,CAAC;IAED,0DAA0D;IAC1D,YAAY,CAAC,SAAiB;QAC5B,OAAO,IAAI,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC;IACrE,CAAC;IAED,oEAAoE;IACpE,aAAa,CAAC,SAAiB,EAAE,MAAqB;QACpD,IAAI,CAAC,EAAE;aACJ,OAAO,CAAC,sEAAsE,CAAC;aAC/E,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,wBAAwB,CAAC,SAAiB,EAAE,GAAW;QACrD,IAAI,CAAC,EAAE;aACJ,OAAO,CACN;2EACmE,CACpE;aACA,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACzB,CAAC;IAED,gEAAgE;IAChE,YAAY,CAAC,SAAiB,EAAE,SAAwB;QACtD,IAAI,CAAC,EAAE;aACJ,OAAO,CAAC,mEAAmE,CAAC;aAC5E,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC/B,CAAC;IAGD;;;;OAIG;IACH,MAAM,CAAC,KAAa,EAAE,KAAK,GAAG,EAAE;QAC9B,MAAM,KAAK,GAAG,KAAK;aAChB,KAAK,CAAC,kBAAkB,CAAC;aACzB,MAAM,CAAC,OAAO,CAAC;aACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;aACxC,IAAI,CAAC,GAAG,CAAC,CAAC;QACb,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE;aACjB,OAAO,CACN;;0EAEkE,CACnE;aACA,GAAG,CAAC,KAAK,EAAE,KAAK,CAAmC,CAAC;QACvD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtB,EAAE,EAAE,CAAC,CAAC,EAAY;YAClB,IAAI,EAAE,CAAC,CAAC,IAAc;YACtB,SAAS,EAAE,CAAC,CAAC,UAAoB;YACjC,OAAO,EAAE,CAAC,CAAC,QAAkB;YAC7B,IAAI,EAAE,CAAC,CAAC,IAAc;YACtB,SAAS,EAAE,CAAC,CAAC,UAAoB;SAClC,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;QAChB,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;CACF;AA7dD,8BA6dC"}

package/dist/agent/knowledge/chunk.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Markdown line-accumulator chunker (planning-64 K0).
+ *
+ * Splits a file into overlapping, line-aligned chunks sized by an approximate
+ * token budget. Mirrors openclaw memory-core's `chunkMarkdown` line accumulator:
+ * fill until adding the next line would exceed the char budget, flush, then carry
+ * a trailing overlap tail into the next chunk. Line-aligned so `memory_get`
+ * excerpts map back to real line ranges. Deterministic — no model calls.
+ */
+export interface Chunk {
+    startLine: number;
+    endLine: number;
+    text: string;
+}
+/**
+ * @param content    full file text
+ * @param chunkTokens target chunk size in ~tokens
+ * @param overlap     overlap between consecutive chunks in ~tokens (< chunkTokens)
+ */
+export declare function chunkMarkdown(content: string, chunkTokens: number, overlap: number): Chunk[];
+//# sourceMappingURL=chunk.d.ts.map

package/dist/agent/knowledge/chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../../src/agent/knowledge/chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,WAAW,KAAK;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,CAoD5F"}

package/dist/agent/knowledge/chunk.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Markdown line-accumulator chunker (planning-64 K0).
+ *
+ * Splits a file into overlapping, line-aligned chunks sized by an approximate
+ * token budget. Mirrors openclaw memory-core's `chunkMarkdown` line accumulator:
+ * fill until adding the next line would exceed the char budget, flush, then carry
+ * a trailing overlap tail into the next chunk. Line-aligned so `memory_get`
+ * excerpts map back to real line ranges. Deterministic — no model calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chunkMarkdown = chunkMarkdown;
+/** Rough chars-per-token estimate (matches openclaw's estimate). */
+const CHARS_PER_TOKEN = 4;
+/**
+ * @param content    full file text
+ * @param chunkTokens target chunk size in ~tokens
+ * @param overlap     overlap between consecutive chunks in ~tokens (< chunkTokens)
+ */
+function chunkMarkdown(content, chunkTokens, overlap) {
+    const maxChars = Math.max(32, chunkTokens * CHARS_PER_TOKEN);
+    const overlapChars = Math.max(0, overlap * CHARS_PER_TOKEN);
+    // Preserve line structure; a file with no trailing newline still yields its lines.
+    const lines = content.split('\n');
+    const chunks = [];
+    // Current chunk accumulator: 1-indexed start line + the lines it holds.
+    let startLine = 1;
+    let buf = [];
+    let bufChars = 0;
+    const flush = (endLine) => {
+        const text = buf.join('\n').trim();
+        if (text.length > 0) {
+            chunks.push({ startLine, endLine, text });
+        }
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNo = i + 1; // 1-indexed
+        const addLen = line.length + 1; // +1 for the joining newline
+        // Flush before overflowing — but only if the buffer already has content
+        // (a single over-long line becomes its own chunk rather than an empty flush).
+        if (bufChars > 0 && bufChars + addLen > maxChars) {
+            flush(lineNo - 1);
+            // Carry an overlap tail: keep trailing lines whose cumulative length stays
+            // under overlapChars, but ALWAYS drop at least the first line of the
+            // flushed chunk so the window advances (no infinite loop).
+            const carry = [];
+            let carryChars = 0;
+            for (let j = buf.length - 1; j >= 1; j--) {
+                const l = buf[j];
+                if (carryChars + l.length + 1 > overlapChars)
+                    break;
+                carry.unshift(l);
+                carryChars += l.length + 1;
+            }
+            buf = carry;
+            bufChars = carryChars;
+            startLine = lineNo - carry.length;
+        }
+        buf.push(line);
+        bufChars += addLen;
+    }
+    if (bufChars > 0)
+        flush(lines.length);
+    return chunks;
+}
+//# sourceMappingURL=chunk.js.map

package/dist/agent/knowledge/chunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../../src/agent/knowledge/chunk.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAgBH,sCAoDC;AAlED,oEAAoE;AACpE,MAAM,eAAe,GAAG,CAAC,CAAC;AAQ1B;;;;GAIG;AACH,SAAgB,aAAa,CAAC,OAAe,EAAE,WAAmB,EAAE,OAAe;IACjF,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,WAAW,GAAG,eAAe,CAAC,CAAC;IAC7D,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC,CAAC;IAE5D,mFAAmF;IACnF,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,MAAM,GAAY,EAAE,CAAC;IAE3B,wEAAwE;IACxE,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,GAAG,GAAa,EAAE,CAAC;IACvB,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,MAAM,KAAK,GAAG,CAAC,OAAe,EAAQ,EAAE;QACtC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC,CAAC;IAEF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,6BAA6B;QAE7D,wEAAwE;QACxE,8EAA8E;QAC9E,IAAI,QAAQ,GAAG,CAAC,IAAI,QAAQ,GAAG,MAAM,GAAG,QAAQ,EAAE,CAAC;YACjD,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAElB,2EAA2E;YAC3E,qEAAqE;YACrE,2DAA2D;YAC3D,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,IAAI,UAAU,GAAG,CAAC,CAAC;YACnB,KAAK,IAAI,CAAC,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBACzC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;gBACjB,IAAI,UAAU,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,GAAG,YAAY;oBAAE,MAAM;gBACpD,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBACjB,UAAU,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;YAC7B,CAAC;YACD,GAAG,GAAG,KAAK,CAAC;YACZ,QAAQ,GAAG,UAAU,CAAC;YACtB,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QACpC,CAAC;QAED,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACf,QAAQ,IAAI,MAAM,CAAC;IACrB,CAAC;IAED,IAAI,QAAQ,GAAG,CAAC;QAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACtC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/agent/knowledge/config.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolve the effective knowledge-archive config for one agent.
+ *
+ * Precedence mirrors `resolveDreamingConfig`: a per-agent override wins over the
+ * global gateway default, which wins over the built-in default. Numeric fields
+ * are sanitized (non-finite / out-of-range JSON ⇒ default) so the indexer never
+ * chunks with a NaN window.
+ */
+import type { KnowledgeArchiveConfig, ResolvedKnowledgeArchiveCfg, KnowledgeSharedConfig, ResolvedKnowledgeSharedCfg } from './types';
+export declare const ARCHIVE_DEFAULTS: ResolvedKnowledgeArchiveCfg;
+export declare function resolveArchiveConfig(agentCfg?: KnowledgeArchiveConfig, globalCfg?: KnowledgeArchiveConfig): ResolvedKnowledgeArchiveCfg;
+export declare const SHARED_DEFAULTS: ResolvedKnowledgeSharedCfg;
+export declare function resolveSharedConfig(agentCfg?: KnowledgeSharedConfig, globalCfg?: KnowledgeSharedConfig): ResolvedKnowledgeSharedCfg;
+/** Directory for a project's shared vault: <root>/<project>. */
+export declare function sharedVaultDir(cfg: ResolvedKnowledgeSharedCfg): string;
+/** The shared vault's SQLite index path. */
+export declare function sharedDbPath(cfg: ResolvedKnowledgeSharedCfg): string;
+/** The shared vault's notes dir (agents drop shared `*.md` here; indexed to kb.sqlite). */
+export declare function sharedNotesDir(cfg: ResolvedKnowledgeSharedCfg): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/agent/knowledge/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/agent/knowledge/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,0BAA0B,EAC3B,MAAM,SAAS,CAAC;AAEjB,eAAO,MAAM,gBAAgB,EAAE,2BAK9B,CAAC;AAiBF,wBAAgB,oBAAoB,CAClC,QAAQ,CAAC,EAAE,sBAAsB,EACjC,SAAS,CAAC,EAAE,sBAAsB,GACjC,2BAA2B,CAuB7B;AAID,eAAO,MAAM,eAAe,EAAE,0BAM7B,CAAC;AAoBF,wBAAgB,mBAAmB,CACjC,QAAQ,CAAC,EAAE,qBAAqB,EAChC,SAAS,CAAC,EAAE,qBAAqB,GAChC,0BAA0B,CAiB5B;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,GAAG,EAAE,0BAA0B,GAAG,MAAM,CAEtE;AAED,4CAA4C;AAC5C,wBAAgB,YAAY,CAAC,GAAG,EAAE,0BAA0B,GAAG,MAAM,CAEpE;AAED,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,GAAG,EAAE,0BAA0B,GAAG,MAAM,CAEtE"}