@bryti/agent 0.0.1 → 0.1.0

package/dist/projection/reflection.js

@@ -0,0 +1,334 @@
+/**
+ * Projection reflection pass.
+ *
+ * Lightweight background job that scans recent conversation history for
+ * future references the agent missed during live chat.
+ *
+ * Runs every 30 min via cron. Reads the JSONL audit log, makes a single
+ * completeSimple() call with a narrow extraction prompt (no agent loop,
+ * no tools), parses the JSON output, and writes projections directly to
+ * SQLite. Existing pending projections are included in the prompt so the
+ * model won't duplicate them. A per-user timestamp tracks the last run
+ * to skip unchanged transcripts.
+ *
+ * Why completeSimple() instead of a full agent loop?
+ * The reflection pass has no side effects and requires no tool calls. It only
+ * needs one prompt in and one JSON blob out. Using a full agent loop would add
+ * latency, cost, and the risk of unintended tool invocations. completeSimple()
+ * is cheaper, faster, and keeps the pass strictly read-only from the model's
+ * perspective.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import Database from "better-sqlite3";
+import { completeSimple } from "@mariozechner/pi-ai";
+import { createProjectionStore } from "./store.js";
+import { formatProjectionsForPrompt } from "./format.js";
+import { toUtc, getUserTimezone } from "../time.js";
+import { createModelInfra, resolveFirstModel } from "../model-infra.js";
+/**
+ * Read user+assistant messages from the JSONL audit log for the last
+ * `windowMinutes`. Returns entries in chronological order, capped at
+ * `maxMessages`.
+ *
+ * Reads from the JSONL audit log written by src/compaction/history.ts, NOT
+ * from the pi SDK session file. The audit log is the only way to get
+ * structured turn-by-turn history outside of a live session context: the pi
+ * session file is append-only and interleaved with tool scaffolding, whereas
+ * the audit log contains clean role/content/timestamp records per message.
+ */
+export function readRecentHistory(historyDir, windowMinutes, maxMessages = 40) {
+    if (!fs.existsSync(historyDir))
+        return [];
+    const cutoff = new Date(Date.now() - windowMinutes * 60 * 1000);
+    const files = fs.readdirSync(historyDir)
+        .filter((f) => f.endsWith(".jsonl"))
+        .sort()
+        .reverse(); // Most recent first
+    const collected = [];
+    for (const file of files) {
+        // Quick file-level date check: skip files older than cutoff date
+        const fileDate = path.basename(file, ".jsonl"); // "YYYY-MM-DD"
+        const fileDateObj = new Date(fileDate + "T00:00:00Z");
+        // A file from yesterday may still have messages within the window
+        if (fileDateObj.getTime() + 86400 * 1000 < cutoff.getTime()) {
+            break; // Files are sorted newest first; nothing older will match
+        }
+        const filePath = path.join(historyDir, file);
+        const lines = fs.readFileSync(filePath, "utf-8").split("\n");
+        for (const line of lines.reverse()) { // Newest first within file
+            if (!line.trim())
+                continue;
+            try {
+                const entry = JSON.parse(line);
+                if (entry.role !== "user" && entry.role !== "assistant")
+                    continue;
+                const ts = new Date(entry.timestamp);
+                if (ts < cutoff)
+                    continue;
+                collected.push(entry);
+                if (collected.length >= maxMessages)
+                    break;
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        if (collected.length >= maxMessages)
+            break;
+    }
+    // Return chronological order
+    return collected.reverse();
+}
+// ---------------------------------------------------------------------------
+// Last-reflection tracking
+// ---------------------------------------------------------------------------
+/**
+ * Read/write the last reflection timestamp from a metadata table in memory.db.
+ *
+ * The timestamp is used to skip reflection when there are no new messages
+ * since the last run: if the newest audit-log entry is not newer than the
+ * stored timestamp, the pass exits early without calling the LLM. This keeps
+ * cron overhead negligible for idle users.
+ *
+ * The timestamp is stored in the same SQLite database as archival memory
+ * (memory.db), so it survives process restarts. A plain text file was
+ * considered but SQLite gives atomic writes for free.
+ */
+function getLastReflectionTimestamp(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS reflection_meta (
+      key   TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+  `);
+    const row = db.prepare("SELECT value FROM reflection_meta WHERE key = 'last_reflection'").get();
+    return row?.value ?? null;
+}
+function setLastReflectionTimestamp(db, ts) {
+    db.prepare("INSERT OR REPLACE INTO reflection_meta (key, value) VALUES ('last_reflection', ?)").run(ts);
+}
+/**
+ * Single chat completion via the pi SDK provider layer. Uses reflection_model
+ * if configured, otherwise falls back to the primary model and then the
+ * fallback chain. This lets operators use a cheaper model for reflection.
+ */
+export async function sdkComplete(config, messages) {
+    const { modelRegistry } = createModelInfra(config);
+    // Resolve the model: reflection_model > primary model > first fallback
+    const candidates = [
+        config.agent.reflection_model,
+        config.agent.model,
+        ...(config.agent.fallback_models ?? []),
+    ].filter(Boolean);
+    const model = resolveFirstModel(candidates, modelRegistry);
+    if (!model) {
+        throw new Error(`Reflection: no usable model found. Tried: ${candidates.join(", ")}`);
+    }
+    // Separate system prompt from user/assistant messages
+    const systemMsg = messages.find((m) => m.role === "system");
+    const userMessages = messages.filter((m) => m.role !== "system");
+    const context = {
+        systemPrompt: systemMsg?.content,
+        messages: userMessages.map((m) => ({
+            role: m.role,
+            content: m.content,
+            timestamp: Date.now(),
+        })),
+    };
+    const apiKey = await modelRegistry.getApiKey(model);
+    const result = await completeSimple(model, context, {
+        maxTokens: 1024,
+        temperature: 0,
+        apiKey: apiKey ?? undefined,
+    });
+    if (result.stopReason === "error") {
+        throw new Error(`Reflection LLM error: ${result.errorMessage ?? "unknown"}`);
+    }
+    return result.content
+        .filter((c) => c.type === "text")
+        .map((c) => c.type === "text" ? c.text : "")
+        .join("");
+}
+// ---------------------------------------------------------------------------
+// Reflection prompt
+// ---------------------------------------------------------------------------
+function buildReflectionPrompt(turns, pendingProjections, currentDatetime) {
+    const transcript = turns
+        .map((t) => `${t.role.toUpperCase()}: ${t.content}`)
+        .join("\n\n");
+    const systemPrompt = `You are a memory assistant. Your job is to extract future commitments, ` +
+        `plans, deadlines, reminders, and events from a conversation transcript.\n\n` +
+        `Current datetime: ${currentDatetime}\n\n` +
+        `Rules:\n` +
+        `- Only extract things that are clearly about the FUTURE (from the perspective of the current datetime).\n` +
+        `- Do NOT extract things already listed under "Already stored".\n` +
+        `- Resolve time expressions to ISO dates or datetimes where possible.\n` +
+        `- For 'when': use "YYYY-MM-DD HH:MM" for exact times, "YYYY-MM-DD" for day-resolution, ` +
+        `"YYYY-Www" for week-resolution (e.g. "2026-W09"), "YYYY-MM" for month-resolution, ` +
+        `or "someday" for no specific time.\n` +
+        `- For 'resolution': use "exact", "day", "week", "month", or "someday".\n` +
+        `- Only include items with at least a clear summary. Context is optional.\n` +
+        `- If there is nothing new to extract, output: {"project":[],"archive":[]}\n` +
+        `- Output valid JSON only. No commentary before or after.\n\n` +
+        `Already stored as pending projections:\n${pendingProjections}`;
+    const userPrompt = `Here is the recent conversation:\n\n${transcript}\n\n` +
+        `What future events, plans, or commitments are mentioned that are NOT already stored?\n` +
+        `Output JSON only:`;
+    return [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: userPrompt },
+    ];
+}
+// ---------------------------------------------------------------------------
+// JSON parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse the LLM output, tolerating markdown code fences and minor formatting.
+ *
+ * Even with `temperature: 0` and an explicit "output JSON only" instruction,
+ * models occasionally wrap their response in a ```json ... ``` code fence.
+ * The stripping step removes those fences before calling JSON.parse(), so
+ * both bare JSON and fenced JSON are accepted.
+ */
+export function parseReflectionOutput(raw) {
+    const stripped = raw
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/\s*```\s*$/, "")
+        .trim();
+    try {
+        const parsed = JSON.parse(stripped);
+        return {
+            project: Array.isArray(parsed.project) ? parsed.project : [],
+            archive: Array.isArray(parsed.archive) ? parsed.archive : [],
+        };
+    }
+    catch {
+        // If the whole thing doesn't parse, return empty
+        return { project: [], archive: [] };
+    }
+}
+// ---------------------------------------------------------------------------
+// Main reflection function
+// ---------------------------------------------------------------------------
+/**
+ * Run one reflection pass for a user. Reads recent conversation, extracts
+ * future references via LLM, and writes new projections to the store.
+ */
+export async function runReflection(config, userId, windowMinutes = 30, store, completeFn) {
+    // Step 1: Read history from the JSONL audit log.
+    const historyDir = path.join(config.data_dir, "history");
+    const turns = readRecentHistory(historyDir, windowMinutes);
+    // Open store (or use injected one for tests)
+    const ownStore = !store;
+    const projStore = store ?? createProjectionStore(userId, config.data_dir);
+    // Access the underlying DB for metadata tracking via the store's DB path
+    const dbPath = path.join(config.data_dir, "users", userId, "memory.db");
+    let metaDb = null;
+    try {
+        // Step 2: Check for new messages. Skip the LLM call entirely if there is
+        // nothing to process: no turns in the window, or no turns newer than the
+        // last reflection timestamp.
+        if (turns.length === 0) {
+            return { projectionsAdded: 0, candidates: [], skipped: true, skipReason: "no recent messages" };
+        }
+        metaDb = new Database(dbPath);
+        const lastReflection = getLastReflectionTimestamp(metaDb);
+        if (lastReflection) {
+            const lastTs = new Date(lastReflection);
+            const newestTurn = turns[turns.length - 1];
+            if (new Date(newestTurn.timestamp) <= lastTs) {
+                return { projectionsAdded: 0, candidates: [], skipped: true, skipReason: "no new messages since last reflection" };
+            }
+        }
+        // Step 3: Load existing pending projections so the model can skip them.
+        // A 90-day window is used here (wider than the history window) to give the
+        // deduplication step the best chance of catching near-duplicates.
+        const upcoming = projStore.getUpcoming(90);
+        const pendingText = formatProjectionsForPrompt(upcoming, 30);
+        const tz = getUserTimezone(config);
+        const now = new Date();
+        const currentDatetime = now
+            .toLocaleString("sv-SE", { timeZone: tz, hour12: false })
+            .slice(0, 16)
+            .replace("T", " ") + (tz !== "UTC" ? ` (${tz})` : " UTC");
+        const messages = buildReflectionPrompt(turns, pendingText, currentDatetime);
+        // Step 4: Call the LLM. One prompt in, one JSON blob out — no tool calls.
+        const doComplete = completeFn ?? sdkComplete;
+        let raw;
+        try {
+            raw = await doComplete(config, messages);
+        }
+        catch (err) {
+            console.error("[reflection] LLM call failed:", err.message);
+            return { projectionsAdded: 0, candidates: [], skipped: true, skipReason: `LLM error: ${err.message}` };
+        }
+        // Step 5: Parse JSON from the raw LLM output.
+        const output = parseReflectionOutput(raw);
+        // Step 6: Deduplicate against existing projections and write survivors.
+        // Deduplication is prompt-based: the existing pending projections were
+        // included in the system prompt under "Already stored", and the model is
+        // instructed not to re-extract them. This is approximate — the model may
+        // still emit a candidate whose summary is a paraphrase of an existing one.
+        // A secondary code-level check (substring match on summaries) would reduce
+        // false duplicates but is not currently implemented.
+        const tz2 = getUserTimezone(config);
+        let projectionsAdded = 0;
+        for (const candidate of output.project) {
+            if (!candidate.summary?.trim())
+                continue;
+            try {
+                let resolved_when;
+                let raw_when;
+                let resolution = candidate.resolution ?? "day";
+                if (candidate.when && candidate.when !== "someday") {
+                    const isoPattern = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2})?/;
+                    const weekPattern = /^\d{4}-W\d{2}$/;
+                    const monthPattern = /^\d{4}-\d{2}$/;
+                    if (weekPattern.test(candidate.when)) {
+                        raw_when = candidate.when;
+                        resolution = "week";
+                    }
+                    else if (monthPattern.test(candidate.when)) {
+                        raw_when = candidate.when;
+                        resolution = "month";
+                    }
+                    else if (isoPattern.test(candidate.when)) {
+                        const hasTime = candidate.when.includes("T") || (candidate.when.length > 10 && candidate.when[10] === " ");
+                        resolved_when = hasTime ? toUtc(candidate.when, tz2) : candidate.when;
+                        resolution = hasTime ? "exact" : (candidate.resolution ?? "day");
+                    }
+                    else {
+                        raw_when = candidate.when;
+                    }
+                }
+                else if (candidate.when === "someday") {
+                    resolution = "someday";
+                }
+                projStore.add({
+                    summary: candidate.summary.trim(),
+                    raw_when,
+                    resolved_when,
+                    resolution,
+                    context: candidate.context,
+                });
+                projectionsAdded++;
+            }
+            catch (err) {
+                console.warn("[reflection] Failed to store projection:", err.message, candidate);
+            }
+        }
+        // Update last-reflection timestamp
+        const reflectedAt = new Date().toISOString();
+        if (metaDb) {
+            setLastReflectionTimestamp(metaDb, reflectedAt);
+        }
+        return { projectionsAdded, candidates: output.project, skipped: false };
+    }
+    finally {
+        metaDb?.close();
+        if (ownStore)
+            projStore.close();
+    }
+}
+//# sourceMappingURL=reflection.js.map

package/dist/projection/reflection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflection.js","sourceRoot":"","sources":["../../src/projection/reflection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAiDxE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAAkB,EAClB,aAAqB,EACrB,WAAW,GAAG,EAAE;IAEhB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,EAAE,CAAC;IAE1C,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,aAAa,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAChE,MAAM,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,UAAU,CAAC;SACrC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;SACnC,IAAI,EAAE;SACN,OAAO,EAAE,CAAC,CAAC,oBAAoB;IAElC,MAAM,SAAS,GAAmB,EAAE,CAAC;IAErC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,iEAAiE;QACjE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,eAAe;QAC/D,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,QAAQ,GAAG,YAAY,CAAC,CAAC;QACtD,kEAAkE;QAClE,IAAI,WAAW,CAAC,OAAO,EAAE,GAAG,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;YAC5D,MAAM,CAAC,0DAA0D;QACnE,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAC7C,MAAM,KAAK,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAE7D,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,2BAA2B;YAC/D,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;gBAAE,SAAS;YAC3B,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAiB,CAAC;gBAC/C,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW;oBAAE,SAAS;gBAClE,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;gBACrC,IAAI,EAAE,GAAG,MAAM;oBAAE,SAAS;gBAC1B,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBACtB,IAAI,SAAS,CAAC,MAAM,IAAI,WAAW;oBAAE,MAAM;YAC7C,CAAC;YAAC,MAAM,CAAC;gBACP,uBAAuB;YACzB,CAAC;QACH,CAAC;QACD,IAAI,SAAS,CAAC,MAAM,IAAI,WAAW;YAAE,MAAM;IAC7C,CAAC;IAED,6BAA6B;IAC7B,OAAO,SAAS,CAAC,OAAO,EAAE,CAAC;AAC7B,CAAC;AAED,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,SAAS,0BAA0B,CAAC,EAAqB;IACvD,EAAE,CAAC,IAAI,CAAC;;;;;GAKP,CAAC,CAAC;IACH,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,iEAAiE,CAAC,CAAC,GAAG,EAAmC,CAAC;IACjI,OAAO,GAAG,EAAE,KAAK,IAAI,IAAI,CAAC;AAC5B,CAAC;AAED,SAAS,0BAA0B,CAAC,EAAqB,EAAE,EAAU;IACnE,EAAE,CAAC,OAAO,CACR,mFAAmF,CACpF,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACZ,CAAC;AAWD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAc,EACd,QAA6B;IAE7B,MAAM,EAAE,aAAa,EAAE,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAEnD,uEAAuE;IACvE,MAAM,UAAU,GAAG;QACjB,MAAM,CAAC,KAAK,CAAC,gBAAgB;QAC7B,MAAM,CAAC,KAAK,CAAC,KAAK;QAClB,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,IAAI,EAAE,CAAC;KACxC,CAAC,MAAM,CAAC,OAAO,CAAa,CAAC;IAE9B,MAAM,KAAK,GAAG,iBAAiB,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IAC3D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,6CAA6C,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACrE,CAAC;IACJ,CAAC;IAED,sDAAsD;IACtD,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAC5D,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAEjE,MAAM,OAAO,GAAG;QACd,YAAY,EAAE,SAAS,EAAE,OAAO;QAChC,QAAQ,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACjC,IAAI,EAAE,CAAC,CAAC,IAAc;YACtB,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC,CAAC;KACJ,CAAC;IAEF,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE;QAClD,SAAS,EAAE,IAAI;QACf,WAAW,EAAE,CAAC;QACd,MAAM,EAAE,MAAM,IAAI,SAAS;KAC5B,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,UAAU,KAAK,OAAO,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,CAAC,YAAY,IAAI,SAAS,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,OAAO,MAAM,CAAC,OAAO;SAClB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,SAAS,qBAAqB,CAC5B,KAAqB,EACrB,kBAA0B,EAC1B,eAAuB;IAEvB,MAAM,UAAU,GAAG,KAAK;SACrB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,IAAI,CAAC,MAAM,CAAC,CAAC;IAEhB,MAAM,YAAY,GAChB,yEAAyE;QACzE,6EAA6E;QAC7E,qBAAqB,eAAe,MAAM;QAC1C,UAAU;QACV,2GAA2G;QAC3G,kEAAkE;QAClE,wEAAwE;QACxE,yFAAyF;QACzF,oFAAoF;QACpF,sCAAsC;QACtC,0EAA0E;QAC1E,4EAA4E;QAC5E,6EAA6E;QAC7E,8DAA8D;QAC9D,2CAA2C,kBAAkB,EAAE,CAAC;IAElE,MAAM,UAAU,GACd,uCAAuC,UAAU,MAAM;QACvD,wFAAwF;QACxF,mBAAmB,CAAC;IAEtB,OAAO;QACL,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE;QACzC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE;KACtC,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,MAAM,QAAQ,GAAG,GAAG;SACjB,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC;SAChC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;SACzB,IAAI,EAAE,CAAC;IAEV,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAA8B,CAAC;QACjE,OAAO;YACL,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;YAC5D,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;SAC7D,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,iDAAiD;QACjD,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACtC,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAc,EACd,MAAc,EACd,aAAa,GAAG,EAAE,EAClB,KAAuB,EACvB,UAA+B;IAE/B,iDAAiD;IACjD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,iBAAiB,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IAE3D,6CAA6C;IAC7C,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC;IACxB,MAAM,SAAS,GAAG,KAAK,IAAI,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAE1E,yEAAyE;IACzE,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IACxE,IAAI,MAAM,GAA6B,IAAI,CAAC;IAE5C,IAAI,CAAC;QACH,yEAAyE;QACzE,yEAAyE;QACzE,6BAA6B;QAC7B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,EAAE,gBAAgB,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,oBAAoB,EAAE,CAAC;QAClG,CAAC;QAED,MAAM,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC9B,MAAM,cAAc,GAAG,0BAA0B,CAAC,MAAM,CAAC,CAAC;QAC1D,IAAI,cAAc,EAAE,CAAC;YACnB,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,cAAc,CAAC,CAAC;YACxC,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAC3C,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,MAAM,EAAE,CAAC;gBAC7C,OAAO,EAAE,gBAAgB,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,uCAAuC,EAAE,CAAC;YACrH,CAAC;QACH,CAAC;QAED,wEAAwE;QACxE,2EAA2E;QAC3E,kEAAkE;QAClE,MAAM,QAAQ,GAAG,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QAC3C,MAAM,WAAW,GAAG,0BAA0B,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC7D,MAAM,EAAE,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QACnC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,eAAe,GAAG,GAAG;aACxB,cAAc,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;aACxD,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;aACZ,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAE5D,MAAM,QAAQ,GAAG,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,eAAe,CAAC,CAAC;QAE5E,0EAA0E;QAC1E,MAAM,UAAU,GAAG,UAAU,IAAI,WAAW,CAAC;QAC7C,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC3C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAG,GAAa,CAAC,OAAO,CAAC,CAAC;YACvE,OAAO,EAAE,gBAAgB,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,cAAe,GAAa,CAAC,OAAO,EAAE,EAAE,CAAC;QACpH,CAAC;QAED,8CAA8C;QAC9C,MAAM,MAAM,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;QAE1C,wEAAwE;QACxE,uEAAuE;QACvE,yEAAyE;QACzE,yEAAyE;QACzE,2EAA2E;QAC3E,2EAA2E;QAC3E,qDAAqD;QACrD,MAAM,GAAG,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,gBAAgB,GAAG,CAAC,CAAC;QACzB,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACvC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE;gBAAE,SAAS;YACzC,IAAI,CAAC;gBACH,IAAI,aAAiC,CAAC;gBACtC,IAAI,QAA4B,CAAC;gBACjC,IAAI,UAAU,GAAyB,SAAS,CAAC,UAAU,IAAI,KAAK,CAAC;gBAErE,IAAI,SAAS,CAAC,IAAI,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;oBACnD,MAAM,UAAU,GAAG,sCAAsC,CAAC;oBAC1D,MAAM,WAAW,GAAG,gBAAgB,CAAC;oBACrC,MAAM,YAAY,GAAG,eAAe,CAAC;oBAErC,IAAI,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;wBACrC,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC;wBAC1B,UAAU,GAAG,MAAM,CAAC;oBACtB,CAAC;yBAAM,IAAI,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;wBAC7C,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC;wBAC1B,UAAU,GAAG,OAAO,CAAC;oBACvB,CAAC;yBAAM,IAAI,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;wBAC3C,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,GAAG,EAAE,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC;wBAC3G,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC;wBACtE,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,IAAI,KAAK,CAAC,CAAC;oBACnE,CAAC;yBAAM,CAAC;wBACN,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC;oBAC5B,CAAC;gBACH,CAAC;qBAAM,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;oBACxC,UAAU,GAAG,SAAS,CAAC;gBACzB,CAAC;gBAED,SAAS,CAAC,GAAG,CAAC;oBACZ,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE;oBACjC,QAAQ;oBACR,aAAa;oBACb,UAAU;oBACV,OAAO,EAAE,SAAS,CAAC,OAAO;iBAC3B,CAAC,CAAC;gBACH,gBAAgB,EAAE,CAAC;YACrB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,IAAI,CAAC,0CAA0C,EAAG,GAAa,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;YAC9F,CAAC;QACH,CAAC;QAED,mCAAmC;QACnC,MAAM,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC7C,IAAI,MAAM,EAAE,CAAC;YACX,0BAA0B,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAClD,CAAC;QAED,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC1E,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,KAAK,EAAE,CAAC;QAChB,IAAI,QAAQ;YAAE,SAAS,CAAC,KAAK,EAAE,CAAC;IAClC,CAAC;AACH,CAAC"}

package/dist/projection/store.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Projection store: SQLite-backed storage for forward-looking agent memory.
+ *
+ * Stores future events, plans, and commitments with a resolution
+ * (exact/day/week/month/someday) and lifecycle (pending -> done/cancelled/passed).
+ *
+ * Lives in the same per-user memory.db as archival memory, its own table.
+ *
+ * Key columns: summary, raw_when (what the user said), resolved_when (ISO
+ * datetime), resolution, recurrence (cron), trigger_on_fact (keyword trigger),
+ * status, and dependencies (separate table for DAG relationships).
+ */
+export type ProjectionResolution = "exact" | "day" | "week" | "month" | "someday";
+export type ProjectionStatus = "pending" | "done" | "cancelled" | "passed";
+export type DependencyConditionType = "status_change" | "llm";
+export interface ProjectionDependency {
+    id: string;
+    observer_id: string;
+    subject_id: string;
+    condition: string;
+    condition_type: DependencyConditionType;
+    created_at: string;
+}
+export interface ProjectionDependencyInput {
+    subject_id: string;
+    condition: string;
+    condition_type?: DependencyConditionType;
+}
+export interface Projection {
+    id: string;
+    summary: string;
+    raw_when: string | null;
+    resolved_when: string | null;
+    resolution: ProjectionResolution;
+    recurrence: string | null;
+    trigger_on_fact: string | null;
+    context: string | null;
+    linked_ids: string[];
+    status: ProjectionStatus;
+    created_at: string;
+    resolved_at: string | null;
+}
+export interface ProjectionStore {
+    /** Add a projection. Returns the new id. */
+    add(params: {
+        summary: string;
+        raw_when?: string;
+        resolved_when?: string;
+        resolution?: ProjectionResolution;
+        recurrence?: string;
+        trigger_on_fact?: string;
+        context?: string;
+        linked_ids?: string[];
+        depends_on?: ProjectionDependencyInput[];
+    }): string;
+    /**
+     * Get active (pending) projections within the next horizon_days days.
+     * Always includes someday projections.
+     */
+    getUpcoming(horizon_days: number): Projection[];
+    /**
+     * Get pending projections due in the next window_minutes minutes that have
+     * resolution='exact'. Used by the 5-minute scheduler check. window_minutes
+     * must be larger than the scheduler tick to avoid missing events that fall
+     * between ticks.
+     */
+    getExactDue(window_minutes: number): Projection[];
+    /**
+     * Mark a projection's status (done/cancelled/passed).
+     * Returns false if the id does not exist.
+     */
+    resolve(id: string, status: ProjectionStatus): boolean;
+    /**
+     * Rearm a recurring projection: reset it to pending with a new resolved_when
+     * and clear resolved_at so it looks fresh for the next cycle. Only called
+     * after a recurring projection fires; non-recurring projections should be
+     * resolved instead.
+     * Returns false if the id does not exist.
+     */
+    rearm(id: string, nextResolvedWhen: string): boolean;
+    /**
+     * Check pending projections whose trigger_on_fact condition matches the given
+     * fact content. First tries keyword matching (all keywords present). For
+     * non-matches, falls back to embedding cosine similarity if an embed function
+     * is provided. Activate each match by setting resolved_when to now and
+     * resolution to 'exact', then clear its trigger_on_fact.
+     * Returns the list of projections that were activated.
+     */
+    checkTriggers(factContent: string, embed?: (text: string) => Promise<number[]>, similarityThreshold?: number): Promise<Projection[]>;
+    /**
+     * Mark pending projections as 'passed' when their resolved_when is more than
+     * threshold_hours hours in the past and they are still pending. Exact-resolution
+     * projections always expire after 1 hour; other resolutions use threshold_hours.
+     * Someday projections are never expired by time.
+     * Returns the number of rows updated.
+     */
+    autoExpire(threshold_hours?: number): number;
+    /**
+     * Link an existing observer projection to a subject projection.
+     * Throws if the relationship is invalid (missing projection, cycle, or chain too deep).
+     */
+    linkDependency(observerId: string, subjectId: string, condition: string, conditionType?: DependencyConditionType): string;
+    /**
+     * Evaluate pending dependencies and activate observer projections whose
+     * conditions are satisfied.
+     */
+    evaluateDependencies(): number;
+    /** List dependencies, optionally filtered by observer projection id. */
+    getDependencies(observerId?: string): ProjectionDependency[];
+    /** Close the database connection. */
+    close(): void;
+}
+/**
+ * Open (or create) the per-user projection store. Shares memory.db with
+ * archival memory.
+ *
+ * Schema overview
+ * ---------------
+ * projections
+ *   Primary record. Holds the summary, timing fields (raw_when, resolved_when,
+ *   resolution), recurrence cron, trigger_on_fact keyword, and status.
+ *
+ * projection_links
+ *   Many-to-many cross-reference between projections (e.g., "this task belongs
+ *   to that project"). Links are stored as a JSON array on the projections row
+ *   (linked_ids) and optionally in this table for reverse lookups.
+ *
+ * projection_dependencies
+ *   DAG edges. An observer projection waits for its subject projection(s) to
+ *   reach a condition before it becomes active. Conditions are either a status
+ *   keyword ("done", "cancelled", "passed") or an LLM-evaluated expression.
+ *
+ * Lifecycle state machine
+ * -----------------------
+ *   pending  →  done       (agent or user explicitly resolves it)
+ *   pending  →  cancelled  (agent or user cancels it)
+ *   pending  →  passed     (autoExpire: the time window elapsed without action)
+ *
+ * Recurring projections return to pending after each firing (see rearm()).
+ * Trigger-based projections become active (resolution='exact') when a matching
+ * fact arrives via checkTriggers(), then fire on the next scheduler tick.
+ */
+export declare function createProjectionStore(userId: string, dataDir: string): ProjectionStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/projection/store.d.ts.map

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