openclaw-clawmark 0.1.0

package/dist/extractor.js

@@ -0,0 +1,138 @@
+import { EXTRACT_BATCH, MAX_FACTS_PER_RUN, MIN_EXTRACT_MESSAGES } from "./constants.js";
+import { getCursor, logEvent, setCursor } from "./db.js";
+import { setFact } from "./facts.js";
+const EXTRACT_TIMEOUT_MS = 120_000;
+const MSG_TRUNCATE_CHARS = 500;
+/** Message-count triggers process at most this many batches; idle/boot may drain fully. */
+const MAX_BATCHES_INCREMENTAL = 5;
+export function extractCursorName(source) {
+    return `extract:${source.name}`;
+}
+const EXTRACTION_PROMPT = `You extract durable long-term facts from a conversation transcript. Return ONLY a JSON
+object:
+
+{"facts": [{"key": "pref.<topic>", "value": "<fact>", "confidence": 0.9}]}
+
+Rules:
+- Keys: lowercase dot-separated, starting with one of: pref. project. user. lesson.
+- Only DURABLE facts: stated preferences, decisions, ongoing projects, corrections,
+  stable facts about the user. Exclude small talk, transient state, secrets, and anything
+  the user asked to keep private.
+- confidence: 0.9+ only when the user stated it directly; 0.8 for strong inference;
+  anything below 0.8 will be discarded, so omit weak guesses.
+- Maximum ${MAX_FACTS_PER_RUN} facts. An empty array is fine and common.
+
+Transcript:
+`;
+function renderTranscript(messages) {
+    return messages
+        .map((m) => `${m.role}: ${m.text.slice(0, MSG_TRUNCATE_CHARS)}`)
+        .join("\n");
+}
+function parseFacts(raw) {
+    const start = raw.indexOf("{");
+    if (start === -1)
+        return null;
+    // Take the largest {...} span, then narrow until it parses.
+    for (let end = raw.lastIndexOf("}"); end > start; end = raw.lastIndexOf("}", end - 1)) {
+        try {
+            const parsed = JSON.parse(raw.slice(start, end + 1));
+            if (!Array.isArray(parsed.facts))
+                return null;
+            return parsed.facts
+                .filter((f) => !!f &&
+                typeof f === "object" &&
+                typeof f.key === "string" &&
+                typeof f.value === "string" &&
+                typeof f.confidence === "number")
+                .slice(0, MAX_FACTS_PER_RUN);
+        }
+        catch {
+            // keep narrowing
+        }
+    }
+    return null;
+}
+async function callExtractModel(config, transcript) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), EXTRACT_TIMEOUT_MS);
+    try {
+        const res = await fetch(`${config.extractUrl}/v1/chat/completions`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                model: config.extractModel,
+                temperature: 0,
+                max_tokens: 1500,
+                // Qwen3-family servers otherwise spend the whole budget on reasoning before any
+                // JSON (verified 2026-07-07). Harmlessly ignored by non-thinking models.
+                chat_template_kwargs: { enable_thinking: false },
+                messages: [{ role: "user", content: EXTRACTION_PROMPT + transcript }],
+            }),
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        const payload = (await res.json());
+        return payload.choices?.[0]?.message?.content ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Read un-extracted messages behind a cursor, run one small-model call per batch, and
+ * upsert surviving facts. The cursor advances in the same transaction as the fact
+ * writes; a parse failure advances the cursor too (logged) so one bad batch can never
+ * wedge the pipeline. Crash-safe by construction: re-running a batch is absorbed by the
+ * upsert + precedence ladder.
+ */
+export async function runExtractor(db, source, config, opts = {}) {
+    const cursorName = extractCursorName(source);
+    let written = 0;
+    const maxBatches = opts.drain ? Number.POSITIVE_INFINITY : MAX_BATCHES_INCREMENTAL;
+    for (let batchNo = 0; batchNo < maxBatches; batchNo++) {
+        const batch = source.messagesAfter(getCursor(db, cursorName), EXTRACT_BATCH);
+        if (batch.messages.length === 0) {
+            if (batch.nextCursor !== null)
+                setCursor(db, cursorName, batch.nextCursor);
+            return { written };
+        }
+        const isFinalPartialBatch = batch.messages.length < EXTRACT_BATCH;
+        if (isFinalPartialBatch && batch.messages.length < MIN_EXTRACT_MESSAGES) {
+            // Not enough new material yet — wait for more; do NOT advance the cursor.
+            return { written };
+        }
+        const raw = await callExtractModel(config, renderTranscript(batch.messages));
+        if (raw === null) {
+            // Model server down — retry this batch on the next trigger.
+            return { written };
+        }
+        const facts = parseFacts(raw);
+        const commit = db.transaction(() => {
+            if (facts === null) {
+                logEvent(db, {
+                    eventType: "extract_error",
+                    memoryKey: "extractor.parse_error",
+                    newValue: raw.slice(0, 300),
+                    source: "extractor",
+                });
+            }
+            else {
+                for (const fact of facts) {
+                    const result = setFact(db, fact.key, fact.value, fact.confidence, "extracted", config.confidenceThreshold);
+                    if (result.ok)
+                        written++;
+                }
+            }
+            setCursor(db, cursorName, batch.nextCursor);
+        });
+        commit();
+        if (isFinalPartialBatch)
+            return { written };
+    }
+    return { written };
+}

package/dist/facts.d.ts

@@ -0,0 +1,21 @@
+import { type Db } from "./db.js";
+export type FactSource = "user" | "extracted";
+export type SetFactResult = {
+    ok: true;
+    action: "create" | "update";
+} | {
+    ok: false;
+    code: "KEY_FORMAT" | "VALUE_SIZE" | "CONFIDENCE" | "INJECTION" | "CONFLICT_SKIP";
+    reason: string;
+};
+export interface FactRow {
+    key: string;
+    value: string;
+    confidence: number;
+    source: string;
+    created_at: string;
+    updated_at: string;
+}
+export declare function setFact(db: Db, key: string, value: string, confidence: number, source: FactSource, confidenceThreshold: number): SetFactResult;
+export declare function deleteFact(db: Db, key: string, source: string): boolean;
+export declare function listFacts(db: Db): FactRow[];

package/dist/facts.js

@@ -0,0 +1,71 @@
+import { CONFIDENCE_TIE_BAND, FACT_KEY_PATTERN, INJECTION_PATTERNS, MAX_FACT_KEY_LEN, MAX_FACT_VALUE_CHARS, } from "./constants.js";
+import { logEvent } from "./db.js";
+export function setFact(db, key, value, confidence, source, confidenceThreshold) {
+    if (key.length > MAX_FACT_KEY_LEN || key.includes("..") || !FACT_KEY_PATTERN.test(key)) {
+        logEvent(db, { eventType: "reject", memoryKey: key, newValue: "KEY_FORMAT", source });
+        return { ok: false, code: "KEY_FORMAT", reason: `invalid key "${key}"` };
+    }
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_FACT_VALUE_CHARS) {
+        logEvent(db, { eventType: "reject", memoryKey: key, newValue: "VALUE_SIZE", source });
+        return { ok: false, code: "VALUE_SIZE", reason: `value must be 1..${MAX_FACT_VALUE_CHARS} chars` };
+    }
+    if (source === "extracted" && confidence < confidenceThreshold) {
+        logEvent(db, { eventType: "reject", memoryKey: key, newValue: "CONFIDENCE", source });
+        return { ok: false, code: "CONFIDENCE", reason: `confidence ${confidence} below ${confidenceThreshold}` };
+    }
+    if (INJECTION_PATTERNS.some((p) => p.test(value))) {
+        logEvent(db, { eventType: "injection_blocked", memoryKey: key, newValue: value.slice(0, 200), source });
+        return { ok: false, code: "INJECTION", reason: "value matched a prompt-injection pattern" };
+    }
+    const clamped = Math.max(0, Math.min(1, confidence));
+    const existing = db
+        .prepare("SELECT key, value, confidence, source FROM facts WHERE key = ? AND is_deleted = 0")
+        .get(key);
+    if (existing) {
+        const userWins = source === "user";
+        const existingIsUser = existing.source === "user";
+        const higherConfidence = clamped > existing.confidence;
+        const tieBand = Math.abs(clamped - existing.confidence) < CONFIDENCE_TIE_BAND;
+        const shouldWrite = userWins || (!existingIsUser && (higherConfidence || tieBand));
+        if (!shouldWrite) {
+            logEvent(db, {
+                eventType: "conflict_skip",
+                memoryKey: key,
+                oldValue: existing.value,
+                newValue: value,
+                source,
+            });
+            return { ok: false, code: "CONFLICT_SKIP", reason: "existing fact wins by precedence/confidence" };
+        }
+    }
+    const now = new Date().toISOString();
+    db.prepare(`INSERT INTO facts (key, value, confidence, source, created_at, updated_at, is_deleted)
+     VALUES (?, ?, ?, ?, ?, ?, 0)
+     ON CONFLICT(key) DO UPDATE SET
+       value = excluded.value, confidence = excluded.confidence, source = excluded.source,
+       updated_at = excluded.updated_at, is_deleted = 0`).run(key, value, clamped, source, now, now);
+    logEvent(db, {
+        eventType: existing ? "update" : "create",
+        memoryKey: key,
+        oldValue: existing?.value ?? null,
+        newValue: value,
+        source,
+    });
+    return { ok: true, action: existing ? "update" : "create" };
+}
+export function deleteFact(db, key, source) {
+    const result = db
+        .prepare("UPDATE facts SET is_deleted = 1, updated_at = ? WHERE key = ? AND is_deleted = 0")
+        .run(new Date().toISOString(), key);
+    if (result.changes > 0) {
+        logEvent(db, { eventType: "delete", memoryKey: key, source });
+        return true;
+    }
+    return false;
+}
+export function listFacts(db) {
+    return db
+        .prepare(`SELECT key, value, confidence, source, created_at, updated_at
+       FROM facts WHERE is_deleted = 0 ORDER BY updated_at DESC`)
+        .all();
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+type PluginEntry = ReturnType<typeof definePluginEntry>;
+declare const entry: PluginEntry;
+export default entry;

package/dist/index.js

@@ -0,0 +1,149 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { getConfig } from "./config.js";
+import { JOB_EVERY_N_MESSAGES } from "./constants.js";
+import { buildContext } from "./context.js";
+import { openDb, rotateEvents } from "./db.js";
+import { createEmbeddingClient } from "./embeddings.js";
+import { runExtractor } from "./extractor.js";
+import { runIndexer } from "./indexer.js";
+import { selectSource } from "./sources/source.js";
+import { buildTools } from "./tools.js";
+const IDLE_TICK_MS = 10 * 60 * 1000;
+const entry = definePluginEntry({
+    id: "clawmark",
+    name: "Clawmark",
+    description: "Durable facts and semantic recall derived from the message history OpenClaw already keeps.",
+    register(api) {
+        const log = {
+            info: (msg) => api.logger?.info?.(`clawmark: ${msg}`),
+            warn: (msg) => api.logger?.warn?.(`clawmark: ${msg}`),
+            error: (msg) => api.logger?.error?.(`clawmark: ${msg}`),
+        };
+        let runtime = null;
+        let idleTimer = null;
+        let messageCounter = 0;
+        let lastActivity = Date.now();
+        let jobsRunning = false;
+        const runJobs = async (opts = {}) => {
+            if (!runtime || jobsRunning)
+                return;
+            jobsRunning = true;
+            try {
+                const { db, source, embedder, config } = runtime;
+                const indexed = await runIndexer(db, source, embedder);
+                const extracted = await runExtractor(db, source, config, opts);
+                rotateEvents(db);
+                if (indexed.indexed > 0 || extracted.written > 0) {
+                    log.info(`jobs: indexed ${indexed.indexed} messages, wrote ${extracted.written} facts`);
+                }
+            }
+            catch (err) {
+                log.error(`background jobs failed: ${String(err)}`);
+            }
+            finally {
+                jobsRunning = false;
+            }
+        };
+        const noteActivity = () => {
+            lastActivity = Date.now();
+            messageCounter++;
+            if (messageCounter >= JOB_EVERY_N_MESSAGES) {
+                messageCounter = 0;
+                void runJobs();
+            }
+        };
+        api.on("gateway_start", () => {
+            try {
+                const config = getConfig();
+                const db = openDb(config.dbPath);
+                const source = selectSource(config, db);
+                const embedder = createEmbeddingClient(config, log.warn);
+                runtime = { db, source, embedder, config };
+                log.info(`started — source=${source.name}, db=${config.dbPath}`);
+                // Catch up on everything missed while the gateway was down. Cursor-based reads
+                // of a durable log make this crash-safe: kill -9 at any point loses nothing.
+                void runJobs({ drain: true });
+                idleTimer = setInterval(() => {
+                    if (!runtime)
+                        return;
+                    if (Date.now() - lastActivity >= runtime.config.idleHours * 3_600_000) {
+                        void runJobs({ drain: true });
+                    }
+                }, IDLE_TICK_MS);
+                idleTimer.unref?.();
+            }
+            catch (err) {
+                // Memory failures must never break the agent — stay inert and say why.
+                log.error(`disabled (init failed): ${String(err)}`);
+                runtime = null;
+            }
+        });
+        api.on("gateway_stop", () => {
+            try {
+                if (idleTimer)
+                    clearInterval(idleTimer);
+                idleTimer = null;
+                if (runtime) {
+                    runtime.db.pragma("wal_checkpoint(TRUNCATE)");
+                    runtime.db.close();
+                }
+            }
+            catch (err) {
+                log.error(`shutdown error: ${String(err)}`);
+            }
+            finally {
+                runtime = null;
+            }
+        });
+        api.on("before_prompt_build", async (event) => {
+            try {
+                if (!runtime)
+                    return;
+                const { db, source, embedder, config } = runtime;
+                const block = await buildContext(db, source, embedder, event.prompt ?? "", config.recallLimit);
+                if (!block)
+                    return;
+                return { prependContext: block };
+            }
+            catch (err) {
+                log.error(`before_prompt_build failed: ${String(err)}`);
+                return;
+            }
+        });
+        api.on("message_received", () => {
+            try {
+                noteActivity();
+            }
+            catch {
+                /* never break the agent */
+            }
+        });
+        api.on("agent_end", () => {
+            try {
+                noteActivity();
+            }
+            catch {
+                /* never break the agent */
+            }
+        });
+        api.on("session_end", () => {
+            try {
+                // Best-effort flush; the boot-time drain is the real guarantee.
+                void runJobs();
+            }
+            catch {
+                /* never break the agent */
+            }
+        });
+        for (const tool of buildTools(() => runtime)) {
+            try {
+                // Cast: our minimal ToolResult structurally matches AgentToolResult.
+                api.registerTool(tool, { optional: true });
+            }
+            catch (err) {
+                log.error(`tool registration failed for ${tool.name}: ${String(err)}`);
+            }
+        }
+    },
+});
+export default entry;

package/dist/indexer.d.ts

@@ -0,0 +1,12 @@
+import { type Db } from "./db.js";
+import { type EmbeddingClient } from "./embeddings.js";
+import type { MessageSource } from "./sources/source.js";
+export declare function indexCursorName(source: MessageSource): string;
+/**
+ * Incrementally embed new source messages into message_vectors.
+ * Cursor advances in the same transaction as the inserts; an embedder outage
+ * leaves the cursor untouched so the next trigger retries the same batch.
+ */
+export declare function runIndexer(db: Db, source: MessageSource, embedder: EmbeddingClient): Promise<{
+    indexed: number;
+}>;

package/dist/indexer.js

@@ -0,0 +1,47 @@
+import { MAX_INDEX_CHARS, MIN_INDEX_CHARS } from "./constants.js";
+import { getCursor, setCursor } from "./db.js";
+import { serializeVector } from "./embeddings.js";
+const BATCH_SIZE = 100;
+export function indexCursorName(source) {
+    return `index:${source.name}`;
+}
+/**
+ * Incrementally embed new source messages into message_vectors.
+ * Cursor advances in the same transaction as the inserts; an embedder outage
+ * leaves the cursor untouched so the next trigger retries the same batch.
+ */
+export async function runIndexer(db, source, embedder) {
+    const cursorName = indexCursorName(source);
+    let indexed = 0;
+    for (;;) {
+        const batch = source.messagesAfter(getCursor(db, cursorName), BATCH_SIZE);
+        if (batch.messages.length === 0) {
+            // Skipped-only progress (e.g. a stretch of tool lines) still advances the cursor.
+            if (batch.nextCursor !== null)
+                setCursor(db, cursorName, batch.nextCursor);
+            return { indexed };
+        }
+        const eligible = batch.messages.filter((m) => m.text.trim().length >= MIN_INDEX_CHARS);
+        const texts = eligible.map((m) => m.text.slice(0, MAX_INDEX_CHARS));
+        const vectors = await embedder.embedTexts(texts);
+        if (eligible.length > 0 && vectors.every((v) => v === null)) {
+            // Embedding server down — retry this batch on the next trigger.
+            return { indexed };
+        }
+        const insert = db.prepare(`INSERT OR IGNORE INTO message_vectors (source_ref, conversation_id, ts, embedding)
+       VALUES (?, ?, ?, ?)`);
+        const commit = db.transaction(() => {
+            for (let i = 0; i < eligible.length; i++) {
+                const vec = vectors[i];
+                if (vec === null)
+                    continue;
+                insert.run(eligible[i].ref, eligible[i].conversationId, eligible[i].ts, serializeVector(vec));
+                indexed++;
+            }
+            setCursor(db, cursorName, batch.nextCursor);
+        });
+        commit();
+        if (batch.messages.length < BATCH_SIZE)
+            return { indexed };
+    }
+}

package/dist/recall.d.ts

@@ -0,0 +1,15 @@
+import type { Db } from "./db.js";
+import { type EmbeddingClient } from "./embeddings.js";
+import type { MessageSource } from "./sources/source.js";
+export interface RecallResult {
+    ref: string;
+    ts: string;
+    role: string;
+    excerpt: string;
+}
+/**
+ * Query-relevant retrieval: cosine over the full vector index with a recency decay,
+ * then a cheap token-Jaccard diversity pass. Returns [] when the embedder is down —
+ * facts still inject without recall.
+ */
+export declare function recall(db: Db, source: MessageSource, embedder: EmbeddingClient, query: string, limit: number): Promise<RecallResult[]>;

package/dist/recall.js

@@ -0,0 +1,62 @@
+import { DECAY_RATE, JACCARD_DUP_THRESHOLD, RECALL_MIN_COSINE } from "./constants.js";
+import { cosine, deserializeVector } from "./embeddings.js";
+const EXCERPT_CHARS = 400;
+function tokenSet(text) {
+    return new Set(text.toLowerCase().match(/[a-z0-9_]{2,}/g) ?? []);
+}
+function jaccard(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter++;
+    return inter / (a.size + b.size - inter);
+}
+/**
+ * Query-relevant retrieval: cosine over the full vector index with a recency decay,
+ * then a cheap token-Jaccard diversity pass. Returns [] when the embedder is down —
+ * facts still inject without recall.
+ */
+export async function recall(db, source, embedder, query, limit) {
+    if (!query.trim() || limit <= 0)
+        return [];
+    const queryVec = await embedder.embedQuery(query);
+    if (queryVec === null)
+        return [];
+    const now = Date.now();
+    const scored = [];
+    const rows = db
+        .prepare("SELECT source_ref, ts, embedding FROM message_vectors")
+        .iterate();
+    for (const row of rows) {
+        const sim = cosine(queryVec, deserializeVector(row.embedding));
+        if (sim < RECALL_MIN_COSINE)
+            continue;
+        const ageDays = Math.max(0, (now - Date.parse(row.ts)) / 86_400_000) || 0;
+        scored.push({ ref: row.source_ref, ts: row.ts, score: sim * Math.exp(-DECAY_RATE * ageDays) });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    const candidates = scored.slice(0, limit * 3);
+    const messages = new Map(source.getMessages(candidates.map((c) => c.ref)).map((m) => [m.ref, m]));
+    const selected = [];
+    const selectedTokens = [];
+    for (const cand of candidates) {
+        if (selected.length >= limit)
+            break;
+        const msg = messages.get(cand.ref);
+        if (!msg)
+            continue;
+        const tokens = tokenSet(msg.text);
+        if (selectedTokens.some((prev) => jaccard(prev, tokens) > JACCARD_DUP_THRESHOLD))
+            continue;
+        selectedTokens.push(tokens);
+        selected.push({
+            ref: msg.ref,
+            ts: msg.ts,
+            role: msg.role,
+            excerpt: msg.text.slice(0, EXCERPT_CHARS),
+        });
+    }
+    return selected;
+}

package/dist/sources/lcm.d.ts

@@ -0,0 +1,2 @@
+import type { MessageSource } from "./source.js";
+export declare function openLcmSource(dbPath: string): MessageSource;

package/dist/sources/lcm.js

@@ -0,0 +1,83 @@
+import Database from "better-sqlite3";
+import fs from "node:fs";
+/**
+ * Read-only adapter over Lossless Claw's SQLite database (`lcm.db`).
+ *
+ * Schema (from lossless-claw src/db/migration.ts):
+ *   messages(message_id INTEGER PK AUTOINCREMENT, conversation_id INTEGER, seq,
+ *            role TEXT, content TEXT, token_count, identity_hash,
+ *            transcript_entry_id, created_at TEXT)
+ *
+ * Cursor/ref = stringified message_id (monotonic autoincrement).
+ * validate() checks the expected columns exist so a schema change in a future LCM
+ * release degrades to the transcript source instead of crashing.
+ */
+const REQUIRED_COLUMNS = ["message_id", "conversation_id", "role", "content", "created_at"];
+function toMessage(row) {
+    return {
+        ref: String(row.message_id),
+        conversationId: String(row.conversation_id),
+        role: row.role,
+        text: row.content,
+        ts: row.created_at,
+    };
+}
+export function openLcmSource(dbPath) {
+    let db = null;
+    const open = () => {
+        if (!db)
+            db = new Database(dbPath, { readonly: true, fileMustExist: true });
+        return db;
+    };
+    return {
+        name: "lcm",
+        validate() {
+            if (!fs.existsSync(dbPath)) {
+                return { ok: false, reason: `LCM database not found at ${dbPath}` };
+            }
+            try {
+                const cols = open()
+                    .prepare("SELECT name FROM pragma_table_info('messages')")
+                    .all();
+                const names = new Set(cols.map((c) => c.name));
+                const missing = REQUIRED_COLUMNS.filter((c) => !names.has(c));
+                if (cols.length === 0)
+                    return { ok: false, reason: "LCM 'messages' table not found" };
+                if (missing.length > 0) {
+                    return { ok: false, reason: `LCM schema drift: missing columns ${missing.join(", ")}` };
+                }
+                return { ok: true };
+            }
+            catch (err) {
+                return { ok: false, reason: `LCM database unreadable: ${String(err)}` };
+            }
+        },
+        messagesAfter(cursor, limit) {
+            const after = cursor === null ? 0 : Number(cursor);
+            const rows = open()
+                .prepare(`SELECT message_id, conversation_id, role, content, created_at
+           FROM messages WHERE message_id > ? ORDER BY message_id ASC LIMIT ?`)
+                .all(after, limit);
+            if (rows.length === 0)
+                return { messages: [], nextCursor: null };
+            return {
+                messages: rows.map(toMessage),
+                nextCursor: String(rows[rows.length - 1].message_id),
+            };
+        },
+        getMessages(refs) {
+            if (refs.length === 0)
+                return [];
+            const placeholders = refs.map(() => "?").join(",");
+            const rows = open()
+                .prepare(`SELECT message_id, conversation_id, role, content, created_at
+           FROM messages WHERE message_id IN (${placeholders})`)
+                .all(...refs.map(Number));
+            const byRef = new Map(rows.map((r) => [String(r.message_id), toMessage(r)]));
+            return refs.flatMap((ref) => {
+                const msg = byRef.get(ref);
+                return msg ? [msg] : [];
+            });
+        },
+    };
+}

package/dist/sources/source.d.ts

@@ -0,0 +1,29 @@
+import type { ClawmarkConfig } from "../config.js";
+import { type Db } from "../db.js";
+export interface SourceMessage {
+    /** Opaque, stable, unique per message within a source. */
+    ref: string;
+    conversationId: string;
+    role: string;
+    text: string;
+    /** ISO-8601 timestamp. */
+    ts: string;
+}
+export interface MessageBatch {
+    messages: SourceMessage[];
+    /** Cursor covering everything returned (and skipped) so far; null if nothing new. */
+    nextCursor: string | null;
+}
+export interface MessageSource {
+    name: "lcm" | "transcripts";
+    validate(): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    /** Ordered, cursor-exclusive read. `cursor === null` means from the beginning. */
+    messagesAfter(cursor: string | null, limit: number): MessageBatch;
+    getMessages(refs: string[]): SourceMessage[];
+}
+export declare function selectSource(config: ClawmarkConfig, db: Db): MessageSource;