praana 0.5.0

package/dist/context-engine/turn-digest.js

@@ -0,0 +1,250 @@
+import { diffStateGraph } from "./state-snapshot.js";
+const USER_INTENT_MAX = 120;
+const NARRATIVE_MAX_CHARS = 160;
+export function extractUserIntent(userMessage) {
+    const trimmed = userMessage.trim().replace(/\s+/g, " ");
+    if (trimmed.length <= USER_INTENT_MAX)
+        return trimmed;
+    return trimmed.slice(0, USER_INTENT_MAX - 3) + "...";
+}
+export function buildToolSummary(record) {
+    if (record.toolCalls.length === 0)
+        return "no tools";
+    const counts = new Map();
+    for (const tc of record.toolCalls) {
+        counts.set(tc.tool, (counts.get(tc.tool) ?? 0) + 1);
+    }
+    const parts = [...counts.entries()].map(([tool, count]) => count > 1 ? `${tool}×${count}` : tool);
+    return parts.join(", ");
+}
+export function decisionSummary(decision) {
+    return typeof decision === "string" ? decision : decision.summary;
+}
+export function normalizeTurnDigest(raw) {
+    const decisions = (raw.decisions ?? []).map((d) => typeof d === "string" ? { summary: d } : d);
+    return {
+        ...raw,
+        filesWritten: raw.filesWritten ?? [],
+        decisions,
+    };
+}
+/**
+ * Extract implicit constraints from user messages.
+ *
+ * **Architecture note:** Regex is a minimal safety net for the most syntactically
+ * unambiguous patterns only. It is NOT the primary mechanism for capturing
+ * implicit knowledge — the system prompt nudge (see `compiler.ts` "Implicit
+ * Knowledge Capture") is the primary mechanism, because the LLM is the
+ * language-understanding component, not regex.
+ *
+ * We only capture patterns where the syntax is unambiguous enough that missing
+ * them would be worse than occasionally over-capturing. Specifically:
+ * - "not X, Y" corrections (the user directly reversing a wrong choice)
+ *
+ * Patterns like "we use", "let's use", "I prefer", "make sure", "how about"
+ * are NOT captured here because they are too variable in natural language.
+ * Those are the LLM's responsibility via the system prompt nudge.
+ */
+export function extractImplicitConstraints(userMessage) {
+    const constraints = [];
+    const text = userMessage.trim();
+    if (!text)
+        return constraints;
+    // "not X, Y" — the most unambiguous correction pattern.
+    // "not npm, pnpm" → "Use pnpm, not npm"
+    // "not npm, but actually pnpm" → "Use pnpm, not npm"
+    const notPattern = text.match(/\bnot\s+([^,]+?),\s*(?:but\s+)?(?:actually\s+)?(.+?)(?:[.!?]|$)/i);
+    if (notPattern) {
+        const avoided = notPattern[1].trim();
+        const preferred = notPattern[2].trim().replace(/[.!?]$/, "");
+        constraints.push(`Use ${preferred}, not ${avoided}`);
+    }
+    return constraints;
+}
+export function isNarrativeWorthy(digest, previousIntent) {
+    if (digest.decisions.length > 0)
+        return true;
+    if (digest.constraints.length > 0)
+        return true;
+    if (digest.errorsNew.length > 0 || digest.errorsFixed.length > 0)
+        return true;
+    if (digest.filesWritten.length > 0)
+        return true;
+    if (previousIntent && digest.userIntent !== previousIntent)
+        return true;
+    return false;
+}
+export function buildNarrativeEntry(digest, previousIntent) {
+    const parts = [];
+    if (previousIntent && digest.userIntent !== previousIntent) {
+        parts.push(digest.userIntent);
+    }
+    if (digest.decisions.length > 0) {
+        const summaries = digest.decisions.map(decisionSummary).join(", ");
+        parts.push(`Decided: ${summaries}`);
+    }
+    if (digest.errorsFixed.length > 0) {
+        parts.push(`Fixed: ${digest.errorsFixed.join(", ")}`);
+    }
+    if (digest.errorsNew.length > 0) {
+        parts.push(`Error: ${digest.errorsNew.join(", ")}`);
+    }
+    if (digest.filesWritten.length > 0) {
+        parts.push(`Wrote: ${digest.filesWritten.join(", ")}`);
+    }
+    if (digest.constraints.length > 0) {
+        parts.push(`Constraints: ${digest.constraints.join(", ")}`);
+    }
+    if (parts.length === 0)
+        return null;
+    let text = parts.join(". ");
+    if (text.length > NARRATIVE_MAX_CHARS) {
+        text = text.slice(0, NARRATIVE_MAX_CHARS - 1) + "…";
+    }
+    return text;
+}
+const PLAN_KEYWORDS = /\b(?:the plan|my approach|i'll start by|next i'll)\b/i;
+const NUMBERED_LIST = /(?:^|\n)\s*\d+\.\s+.+/m;
+const STEP_MARKERS = /(?:^|\n)\s*(?:-\s*step\s*\d+:|step\s*\d+:|first:|next:)/i;
+const MARKDOWN_TASKS = /(?:^|\n)\s*-\s*\[[ x]\]\s+.+/m;
+const BULLET_LIST = /(?:^|\n)\s*[-*]\s+.+/m;
+export function extractPlan(assistantMessage) {
+    const text = assistantMessage.trim();
+    if (!text)
+        return null;
+    // Skip content inside code blocks (plans don't live there)
+    const stripped = text.replace(/```[\s\S]*?```/g, "");
+    const hasPlanSignal = PLAN_KEYWORDS.test(stripped) ||
+        NUMBERED_LIST.test(stripped) ||
+        STEP_MARKERS.test(stripped) ||
+        MARKDOWN_TASKS.test(stripped);
+    if (!hasPlanSignal)
+        return null;
+    const lines = stripped.split("\n");
+    const planLines = [];
+    let inPlan = false;
+    for (const line of lines) {
+        // Numbered items
+        if (/^\s*\d+\.\s+/.test(line)) {
+            inPlan = true;
+            planLines.push(line.trim());
+            continue;
+        }
+        // Step markers
+        if (STEP_MARKERS.test(line)) {
+            inPlan = true;
+            planLines.push(line.trim());
+            continue;
+        }
+        // Markdown task items
+        if (/^\s*-\s*\[[ x]\]\s+/.test(line)) {
+            inPlan = true;
+            planLines.push(line.trim());
+            continue;
+        }
+        // Sub-items / continuation bullets within a plan block
+        if (inPlan && /^\s*[-*]\s+/.test(line)) {
+            planLines.push(line.trim());
+            continue;
+        }
+        // Indented sub-items (under a numbered step)
+        if (inPlan && /^\s{2,}\S/.test(line)) {
+            planLines.push(line.trim());
+            continue;
+        }
+        // Blank lines within plan block — skip
+        if (inPlan && line.trim() === "") {
+            continue;
+        }
+        // Non-plan content breaks the block
+        if (inPlan && planLines.length > 0) {
+            break;
+        }
+    }
+    if (planLines.length >= 2) {
+        return planLines.join("\n");
+    }
+    const planMatch = stripped.match(/(?:the plan is|my approach is|i'll start by)\s*[:\-]?\s*(?:to\s+)?(.+?)(?:\n\n|$)/i);
+    if (planMatch) {
+        return planMatch[1].trim();
+    }
+    if (NUMBERED_LIST.test(stripped)) {
+        const numbered = lines.filter((line) => /^\s*\d+\.\s+/.test(line));
+        if (numbered.length >= 2) {
+            return numbered.map((line) => line.trim()).join("\n");
+        }
+    }
+    return null;
+}
+export function extractPlanItems(planText) {
+    const items = [];
+    for (const line of planText.split("\n")) {
+        const numbered = line.match(/^\s*\d+\.\s+(.+)/);
+        if (numbered) {
+            items.push(numbered[1].trim());
+            continue;
+        }
+        const step = line.match(/^\s*(?:-\s*)?(?:step\s*\d+:|first:|next:)\s*(.+)/i);
+        if (step) {
+            items.push(step[1].trim());
+            continue;
+        }
+        const task = line.match(/^\s*-\s*\[[ x]\]\s+(.+)/);
+        if (task) {
+            items.push(task[1].trim());
+            continue;
+        }
+        const bullet = line.match(/^\s*[-*]\s+(.+)/);
+        if (bullet) {
+            items.push(bullet[1].trim());
+        }
+    }
+    if (items.length === 0 && planText.trim()) {
+        return planText
+            .split(/[,;]/)
+            .map((part) => part.trim())
+            .filter(Boolean);
+    }
+    return items;
+}
+export function detectCompletedPlanItems(planItems, digest) {
+    const signals = [
+        ...digest.filesChanged,
+        ...digest.filesWritten,
+        ...digest.decisions.map(decisionSummary),
+        ...digest.constraints,
+    ]
+        .join(" ")
+        .toLowerCase();
+    return planItems.filter((item) => {
+        const keywords = item
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((word) => word.length > 3);
+        return keywords.some((keyword) => signals.includes(keyword));
+    });
+}
+export function extractTurnDigest(input) {
+    const { decisions, constraints: stateConstraints } = diffStateGraph(input.stateBefore, input.stateGraph.snapshot());
+    const implicitConstraints = extractImplicitConstraints(input.userMessage);
+    const constraints = [
+        ...new Set([...stateConstraints, ...implicitConstraints]),
+    ];
+    const filesChanged = [
+        ...new Set([...input.record.filesRead, ...input.record.filesWritten]),
+    ];
+    const extractedPlan = extractPlan(input.record.assistantMessage);
+    return {
+        turnId: input.turn,
+        userIntent: extractUserIntent(input.userMessage),
+        filesChanged,
+        filesWritten: [...input.record.filesWritten],
+        artifactRefs: [...input.record.artifactIds],
+        decisions,
+        constraints,
+        errorsNew: input.errorsNew,
+        errorsFixed: input.errorsFixed,
+        toolSummary: buildToolSummary(input.record),
+        extractedPlan: extractedPlan ?? undefined,
+    };
+}

package/dist/context-engine/turn-ledger.d.ts

@@ -0,0 +1,18 @@
+import type Database from "better-sqlite3";
+import type { Event } from "../types.js";
+import type { TurnRecord, TurnSearchMatch } from "./types.js";
+export declare function groupEventsIntoTurns(events: Event[]): Array<{
+    userMessage: string;
+    events: Event[];
+}>;
+export declare class TurnLedger {
+    private readonly db;
+    private readonly sessionId;
+    constructor(db: Database.Database, sessionId: string);
+    append(record: TurnRecord): void;
+    get(turn: number): TurnRecord | null;
+    list(): TurnRecord[];
+    getMaxTurn(): number | null;
+    migrateFromEvents(events: Event[]): number;
+    search(query: string, limit?: number): TurnSearchMatch[];
+}

package/dist/context-engine/turn-ledger.js

@@ -0,0 +1,184 @@
+import { getMaxLedgerTurn, getTurnRecord, hasLedgerTurn, insertTurnRecord, listArtifactIdsForTurn, listTurnRecords, } from "./db.js";
+import { buildTurnSearchText, extractFilePathsFromTool, extractToolError, } from "./turn-recorder.js";
+import { bm25Score, tokenize } from "./bm25.js";
+function buildExcerpt(record, maxLen = 400) {
+    const text = [
+        record.userMessage,
+        record.assistantMessage,
+        ...record.errors,
+    ]
+        .join(" ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen - 3) + "...";
+}
+function pairToolCalls(events) {
+    const calls = [];
+    const pending = [];
+    for (const ev of events) {
+        if (ev.kind === "tool_call") {
+            pending.push({
+                tool: String(ev.payload.tool ?? ""),
+                args: ev.payload.args ?? {},
+            });
+            continue;
+        }
+        if (ev.kind !== "tool_result")
+            continue;
+        const tool = String(ev.payload.tool ?? "");
+        const idx = pending.findIndex((p) => p.tool === tool);
+        const call = idx >= 0 ? pending.splice(idx, 1)[0] : { tool, args: {} };
+        const result = ev.payload.result;
+        const isError = !!result &&
+            typeof result === "object" &&
+            (("ok" in result && result.ok === false) ||
+                "error" in result);
+        calls.push({
+            tool: call.tool,
+            args: call.args,
+            isError,
+        });
+    }
+    return calls;
+}
+function collectFilesAndErrors(toolCalls, events) {
+    const filesRead = new Set();
+    const filesWritten = new Set();
+    const errors = [];
+    for (const tc of toolCalls) {
+        const paths = extractFilePathsFromTool(tc.tool, tc.args);
+        if (paths.read)
+            filesRead.add(paths.read);
+        if (paths.written)
+            filesWritten.add(paths.written);
+    }
+    for (const ev of events) {
+        if (ev.kind !== "tool_result")
+            continue;
+        const result = ev.payload.result;
+        const err = extractToolError(result, false);
+        if (err)
+            errors.push(err);
+    }
+    return {
+        filesRead: [...filesRead],
+        filesWritten: [...filesWritten],
+        errors,
+    };
+}
+export function groupEventsIntoTurns(events) {
+    const turns = [];
+    let current = null;
+    for (const ev of events) {
+        if (ev.kind === "user_message") {
+            if (current)
+                turns.push(current);
+            current = {
+                userMessage: String(ev.payload.text ?? ""),
+                events: [],
+            };
+            continue;
+        }
+        if (!current)
+            continue;
+        current.events.push(ev);
+    }
+    if (current)
+        turns.push(current);
+    return turns;
+}
+export class TurnLedger {
+    db;
+    sessionId;
+    constructor(db, sessionId) {
+        this.db = db;
+        this.sessionId = sessionId;
+    }
+    append(record) {
+        if (hasLedgerTurn(this.db, this.sessionId, record.turn))
+            return;
+        insertTurnRecord(this.db, this.sessionId, record, buildTurnSearchText(record));
+    }
+    get(turn) {
+        return getTurnRecord(this.db, this.sessionId, turn);
+    }
+    list() {
+        return listTurnRecords(this.db, this.sessionId);
+    }
+    getMaxTurn() {
+        return getMaxLedgerTurn(this.db, this.sessionId);
+    }
+    migrateFromEvents(events) {
+        const grouped = groupEventsIntoTurns(events);
+        let inserted = 0;
+        grouped.forEach((group, turnIndex) => {
+            if (hasLedgerTurn(this.db, this.sessionId, turnIndex))
+                return;
+            const assistantMessage = group.events
+                .filter((e) => e.kind === "agent_message")
+                .map((e) => String(e.payload.text ?? ""))
+                .join("\n") || "";
+            const turnEvents = group.events.filter((e) => e.kind === "tool_call" || e.kind === "tool_result");
+            const toolCalls = pairToolCalls(turnEvents);
+            const { filesRead, filesWritten, errors } = collectFilesAndErrors(toolCalls, group.events);
+            const artifactIds = listArtifactIdsForTurn(this.db, this.sessionId, turnIndex);
+            const record = {
+                turn: turnIndex,
+                userMessage: group.userMessage,
+                assistantMessage,
+                toolCalls,
+                artifactIds,
+                filesRead,
+                filesWritten,
+                errors,
+                tokenCount: 0,
+                timestamp: group.events[group.events.length - 1]?.timestamp ?? Date.now(),
+            };
+            insertTurnRecord(this.db, this.sessionId, record, buildTurnSearchText(record));
+            inserted++;
+        });
+        return inserted;
+    }
+    search(query, limit = 20) {
+        const trimmed = query.trim();
+        if (!trimmed)
+            return [];
+        const records = this.list();
+        if (records.length === 0)
+            return [];
+        const queryTokens = tokenize(trimmed);
+        if (queryTokens.length === 0)
+            return [];
+        const docs = records.map((r) => tokenize(buildTurnSearchText(r)));
+        const totalDocs = docs.length;
+        const avgDocLen = docs.reduce((sum, d) => sum + d.length, 0) / totalDocs;
+        const docFreq = new Map();
+        for (const doc of docs) {
+            const seen = new Set(doc);
+            for (const t of seen)
+                docFreq.set(t, (docFreq.get(t) ?? 0) + 1);
+        }
+        const scored = records
+            .map((record, i) => ({
+            record,
+            score: bm25Score(queryTokens, docs[i], avgDocLen, totalDocs, docFreq),
+        }))
+            .filter((entry) => entry.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+        return scored.map(({ record, score }) => ({
+            turn: record.turn,
+            score,
+            userMessage: record.userMessage,
+            assistantMessage: record.assistantMessage,
+            excerpt: buildExcerpt(record),
+            artifactIds: record.artifactIds,
+            filesRead: record.filesRead,
+            filesWritten: record.filesWritten,
+            errors: record.errors,
+            timestamp: record.timestamp,
+        }));
+    }
+}

package/dist/context-engine/turn-recorder.d.ts

@@ -0,0 +1,24 @@
+import type { TurnRecord } from "./types.js";
+export declare function extractToolError(result: unknown, isError: boolean): string | null;
+export declare function extractFilePathsFromTool(tool: string, args: Record<string, unknown>): {
+    read?: string;
+    written?: string;
+};
+export declare function buildTurnSearchText(record: TurnRecord): string;
+export declare class TurnRecorder {
+    readonly userMessage: string;
+    private readonly toolCalls;
+    private readonly artifactIds;
+    private readonly filesRead;
+    private readonly filesWritten;
+    private readonly errors;
+    constructor(userMessage: string);
+    recordToolCall(input: {
+        tool: string;
+        args: Record<string, unknown>;
+        result: unknown;
+        isError: boolean;
+        artifactId?: string;
+    }): void;
+    toRecord(assistantMessage: string, turn: number, tokenCount: number): TurnRecord;
+}

package/dist/context-engine/turn-recorder.js

@@ -0,0 +1,88 @@
+export function extractToolError(result, isError) {
+    if (isError) {
+        if (result && typeof result === "object" && "error" in result) {
+            return String(result.error ?? "tool error");
+        }
+        return "tool error";
+    }
+    if (result && typeof result === "object" && "ok" in result) {
+        if (result.ok === false) {
+            return String(result.error ?? "tool failed");
+        }
+    }
+    return null;
+}
+export function extractFilePathsFromTool(tool, args) {
+    const path = typeof args.path === "string" ? args.path : undefined;
+    if (!path)
+        return {};
+    if (tool === "read_file" || tool === "read_and_summarize") {
+        return { read: path };
+    }
+    if (tool === "write_file" || tool === "edit_file") {
+        return { written: path };
+    }
+    return {};
+}
+export function buildTurnSearchText(record) {
+    const parts = [
+        record.userMessage,
+        record.assistantMessage,
+        ...record.errors,
+        ...record.filesRead,
+        ...record.filesWritten,
+        ...record.artifactIds,
+        ...record.toolCalls.map((tc) => `${tc.tool} ${JSON.stringify(tc.args)}`),
+    ];
+    return parts.filter(Boolean).join("\n");
+}
+export class TurnRecorder {
+    userMessage;
+    toolCalls = [];
+    artifactIds = new Set();
+    filesRead = new Set();
+    filesWritten = new Set();
+    errors = [];
+    constructor(userMessage) {
+        this.userMessage = userMessage;
+    }
+    recordToolCall(input) {
+        this.toolCalls.push({
+            tool: input.tool,
+            args: input.args,
+            resultArtifactId: input.artifactId,
+            isError: input.isError,
+            resultText: truncateResultText(input.result),
+        });
+        if (input.artifactId)
+            this.artifactIds.add(input.artifactId);
+        const paths = extractFilePathsFromTool(input.tool, input.args);
+        if (paths.read)
+            this.filesRead.add(paths.read);
+        if (paths.written)
+            this.filesWritten.add(paths.written);
+        const err = extractToolError(input.result, input.isError);
+        if (err)
+            this.errors.push(err);
+    }
+    toRecord(assistantMessage, turn, tokenCount) {
+        return {
+            turn,
+            userMessage: this.userMessage,
+            assistantMessage,
+            toolCalls: [...this.toolCalls],
+            artifactIds: [...this.artifactIds],
+            filesRead: [...this.filesRead],
+            filesWritten: [...this.filesWritten],
+            errors: [...this.errors],
+            tokenCount,
+            timestamp: Date.now(),
+        };
+    }
+}
+function truncateResultText(result, maxLen = 400) {
+    const text = typeof result === "string" ? result : JSON.stringify(result);
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen) + "…";
+}