praana 0.5.0

package/dist/logger.js

@@ -0,0 +1,287 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { APP_HOME_DIR, APP_NAME, resolveAppHomePath, } from "./app-identity.js";
+import pino from "pino";
+import pretty from "pino-pretty";
+import { Writable } from "node:stream";
+/** Daily rotated logs; symlink at `current.log` points to today's file. */
+export const LOG_SYMLINK_FILENAME = "current.log";
+export const LOG_RETENTION_DAYS = 15;
+/** pino-roll retains `count` rotated files plus the active file. */
+export const LOG_RETENTION_COUNT = LOG_RETENTION_DAYS - 1;
+const PINO_LEVEL = {
+    error: "error",
+    warn: "warn",
+    info: "info",
+    debug: "debug",
+};
+function expandHome(p) {
+    return p.startsWith("~/") ? join(homedir(), p.slice(2)) : p;
+}
+export function getAppLogDir() {
+    return resolveAppHomePath("logs");
+}
+/** Base path for pino-roll (extension added by rotator). */
+export function getAppLogBase() {
+    return join(getAppLogDir(), APP_NAME.toLowerCase());
+}
+/** Stable symlink path for tailing the active app log. */
+export function getAppLogPath() {
+    return join(getAppLogDir(), LOG_SYMLINK_FILENAME);
+}
+export function getSessionLogBase(sessionLogDir, sessionId) {
+    return join(expandHome(sessionLogDir), sessionId, "system");
+}
+/** Stable symlink path for tailing the active session system log. */
+export function getSessionSystemLogPath(sessionLogDir, sessionId) {
+    return join(expandHome(sessionLogDir), sessionId, LOG_SYMLINK_FILENAME);
+}
+function ensureParentDir(filePath) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function isTestEnv() {
+    return process.env.VITEST === "true";
+}
+const rollingStreams = new Map();
+async function createRollingFileDestination(basePath) {
+    const cached = rollingStreams.get(basePath);
+    if (cached)
+        return cached;
+    ensureParentDir(`${basePath}.log`);
+    const pinoRoll = (await import("pino-roll")).default;
+    const stream = await pinoRoll({
+        file: basePath,
+        frequency: "daily",
+        dateFormat: "yyyy-MM-dd",
+        mkdir: true,
+        sync: true,
+        symlink: true,
+        limit: { count: LOG_RETENTION_COUNT, removeOtherLogFiles: true },
+    });
+    rollingStreams.set(basePath, stream);
+    return stream;
+}
+function createStderrDestination(options) {
+    if (options.writeLine) {
+        return new Writable({
+            write(chunk, _encoding, callback) {
+                options.writeLine(String(chunk).trimEnd());
+                callback();
+            },
+        });
+    }
+    if (isTestEnv()) {
+        return new Writable({
+            write(_chunk, _encoding, callback) {
+                callback();
+            },
+        });
+    }
+    if (process.stderr.isTTY) {
+        return pretty({
+            destination: 2,
+            colorize: true,
+            ignore: "pid,hostname,sessionId,domain,code,details,notice",
+            messageFormat: (log, messageKey) => {
+                const domain = typeof log.domain === "string" ? `[${log.domain}] ` : "";
+                const code = typeof log.code === "string" ? `(${log.code}) ` : "";
+                return `${domain}${code}${log[messageKey]}`;
+            },
+        });
+    }
+    return pino.destination({ dest: 2, sync: true });
+}
+function createPinoLogger(options) {
+    const debug = options.debug ?? false;
+    const stderrLevel = debug ? "debug" : "warn";
+    const fileLevel = debug ? "debug" : "info";
+    const streams = [
+        { level: stderrLevel, stream: createStderrDestination(options) },
+    ];
+    if (!options.writeLine && !isTestEnv()) {
+        if (options.appFileStream) {
+            streams.push({ level: fileLevel, stream: options.appFileStream });
+        }
+        if (options.sessionFileStream) {
+            streams.push({ level: fileLevel, stream: options.sessionFileStream });
+        }
+    }
+    const destination = streams.length === 1 ? streams[0].stream : pino.multistream(streams);
+    return pino({
+        level: debug ? "debug" : "info",
+        base: options.sessionId ? { sessionId: options.sessionId } : undefined,
+    }, destination);
+}
+export class PraanaLogger {
+    pino;
+    options;
+    constructor(options = {}) {
+        this.options = {
+            domain: options.domain ?? "app",
+            debug: options.debug ?? false,
+            sessionId: options.sessionId,
+            sessionLogDir: options.sessionLogDir,
+            appFileStream: options.appFileStream,
+            sessionFileStream: options.sessionFileStream,
+            writeLine: options.writeLine,
+            captureNotice: options.captureNotice,
+        };
+        this.pino = createPinoLogger(this.options).child({ domain: this.options.domain });
+    }
+    child(domain) {
+        return new PraanaLogger({ ...this.options, domain });
+    }
+    log(entry) {
+        const fields = {
+            ...(entry.code ? { code: entry.code } : {}),
+            ...(entry.details ? { details: entry.details } : {}),
+            ...(entry.cause ? { err: entry.cause } : {}),
+        };
+        const target = entry.domain && entry.domain !== this.options.domain
+            ? this.pino.child({ domain: entry.domain })
+            : this.pino;
+        target[PINO_LEVEL[entry.level]](fields, entry.message);
+    }
+    error(message, opts) {
+        this.log({
+            level: "error",
+            domain: opts?.domain ?? this.options.domain,
+            message,
+            code: opts?.code,
+            details: opts?.details,
+            cause: opts?.cause,
+        });
+    }
+    warn(message, opts) {
+        this.log({
+            level: "warn",
+            domain: opts?.domain ?? this.options.domain,
+            message,
+            code: opts?.code,
+            details: opts?.details,
+            cause: opts?.cause,
+        });
+    }
+    info(message, opts) {
+        this.log({
+            level: "info",
+            domain: opts?.domain ?? this.options.domain,
+            message,
+            details: opts?.details,
+        });
+    }
+    debug(message, opts) {
+        this.log({
+            level: "debug",
+            domain: opts?.domain ?? this.options.domain,
+            message,
+            details: opts?.details,
+        });
+    }
+    /** User-visible status — always on stderr; also written to system log files at info level. */
+    notice(message, opts) {
+        const domain = opts?.domain ?? this.options.domain;
+        const line = `[${domain}] ${message}`;
+        if (this.options.captureNotice) {
+            this.options.captureNotice(line);
+        }
+        else if (this.options.writeLine) {
+            this.options.writeLine(line);
+        }
+        else if (!isTestEnv()) {
+            process.stderr.write(line + "\n");
+        }
+        const target = domain !== this.options.domain ? this.pino.child({ domain }) : this.pino;
+        target.info({
+            ...(opts?.details ? { details: opts.details } : {}),
+            notice: true,
+        }, message);
+    }
+}
+let appLogger = new PraanaLogger({ domain: "app" });
+let appLogInitPromise = null;
+export function getAppLogger() {
+    return appLogger;
+}
+export function setAppLogger(logger) {
+    appLogger = logger;
+}
+/** Initialise daily-rotating app log under ~/.praana/logs (no-op in tests). */
+export async function initAppLogFile() {
+    if (isTestEnv())
+        return;
+    if (appLogInitPromise)
+        return appLogInitPromise;
+    appLogInitPromise = (async () => {
+        const stream = await createRollingFileDestination(getAppLogBase());
+        appLogger = new PraanaLogger({ domain: "app", appFileStream: stream });
+    })();
+    return appLogInitPromise;
+}
+export async function createSessionLogger(opts) {
+    if (isTestEnv()) {
+        return new PraanaLogger({
+            domain: "session",
+            debug: opts.debug ?? false,
+            sessionId: opts.sessionId,
+            sessionLogDir: opts.sessionLogDir,
+        });
+    }
+    await initAppLogFile();
+    const appStream = rollingStreams.get(getAppLogBase());
+    const sessionStream = await createRollingFileDestination(getSessionLogBase(opts.sessionLogDir, opts.sessionId));
+    return new PraanaLogger({
+        domain: "session",
+        debug: opts.debug ?? false,
+        sessionId: opts.sessionId,
+        sessionLogDir: opts.sessionLogDir,
+        appFileStream: appStream,
+        sessionFileStream: sessionStream,
+        captureNotice: opts.captureNotice,
+    });
+}
+export function createTestLogger(writeLine, opts) {
+    return new PraanaLogger({
+        domain: "app",
+        debug: opts?.debug ?? false,
+        writeLine,
+    });
+}
+/** Extract a human-readable message from a pi-ai assistant/error message object. */
+export function extractLlmErrorMessage(message) {
+    if (!message || typeof message !== "object")
+        return undefined;
+    const msg = message;
+    if (typeof msg.errorMessage === "string" && msg.errorMessage.trim()) {
+        return msg.errorMessage.trim();
+    }
+    const content = msg.content;
+    if (Array.isArray(content)) {
+        for (const block of content) {
+            if (!block || typeof block !== "object")
+                continue;
+            const b = block;
+            if (b.type === "text" && typeof b.text === "string" && b.text.trim()) {
+                return b.text.trim();
+            }
+        }
+    }
+    return undefined;
+}
+export function formatUserFacingLlmError(opts) {
+    const detail = opts.llmMessage?.trim();
+    if (detail) {
+        return `[LLM error: ${detail}]`;
+    }
+    if (opts.reason === "error") {
+        return `[LLM request failed — see ~/.${APP_HOME_DIR}/logs/current.log or the session current.log (model: ${opts.model}, provider: ${opts.provider})]`;
+    }
+    return "[no response from model — try again or switch models with /model]";
+}
+export function isLogLevel(value) {
+    return value === "error" || value === "warn" || value === "info" || value === "debug";
+}

package/dist/main.d.ts

@@ -0,0 +1 @@
+export declare function main(): Promise<void>;

package/dist/main.js

@@ -0,0 +1,54 @@
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getMissingKeyMessage } from "./llm.js";
+import { loadConfig } from "./config.js";
+import { getAppLogger, initAppLogFile } from "./logger.js";
+import { parseCliArgs, resolveUiMode, resolveScreenMode, } from "./cli-args.js";
+import { printHelp } from "./app-banner.js";
+import { AppController } from "./app-controller.js";
+import { runReadlineUi } from "./ui/readline-ui.js";
+import { runTui } from "./ui/tui/run.js";
+export async function main() {
+    const parsed = parseCliArgs(process.argv.slice(2));
+    if (parsed.showHelp) {
+        printHelp();
+        process.exit(0);
+    }
+    await initAppLogFile();
+    const cwd = resolve(process.cwd());
+    const config = loadConfig(parsed.configPath);
+    const keyError = getMissingKeyMessage(config.llm.provider);
+    if (keyError) {
+        getAppLogger().error(keyError, { code: "SESSION_START_FAILED" });
+        process.exit(1);
+    }
+    const isInteractive = !!(process.stdin.isTTY && process.stdout.isTTY);
+    const uiMode = resolveUiMode(config.ui.mode, parsed.uiMode, isInteractive);
+    const screenMode = resolveScreenMode(config.ui.screen, parsed.screenMode);
+    const controller = new AppController({ cwd, config, parsed });
+    try {
+        const info = await controller.start({ uiMode });
+        if (uiMode === "tui") {
+            await runTui(controller, info, screenMode);
+        }
+        else {
+            await runReadlineUi(controller, info);
+        }
+    }
+    catch (err) {
+        getAppLogger().error("Failed to start session", {
+            code: "SESSION_START_FAILED",
+            cause: err,
+        });
+        process.exit(1);
+    }
+}
+const isDirectRun = process.argv[1]
+    ? resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+    : false;
+if (isDirectRun) {
+    main().catch((err) => {
+        getAppLogger().error("Fatal error", { cause: err });
+        process.exit(1);
+    });
+}

package/dist/memory/confidence.d.ts

@@ -0,0 +1,7 @@
+import type { MemoryEntry, MemoryKind } from "./types.js";
+/** Per-kind half-life in days. null = never decays. Layer 2 entries use 4× effective half-life. */
+export declare const HALF_LIFE_DAYS: Record<MemoryKind, number | null>;
+/** Per-kind weights when ranking digest entries. */
+export declare const KIND_WEIGHTS: Record<MemoryKind, number>;
+export declare function digestScore(entry: MemoryEntry, now: number): number;
+export declare function effectiveConfidence(entry: MemoryEntry, now: number): number;

package/dist/memory/confidence.js

@@ -0,0 +1,37 @@
+/** Per-kind half-life in days. null = never decays. Layer 2 entries use 4× effective half-life. */
+export const HALF_LIFE_DAYS = {
+    constraint: null,
+    preference: 180,
+    fact: 90,
+    decision: 365,
+    mistake: 60,
+    pattern: 365,
+};
+const LAYER2_HALF_LIFE_MULTIPLIER = 4;
+const MS_PER_DAY = 86_400_000;
+/** Per-kind weights when ranking digest entries. */
+export const KIND_WEIGHTS = {
+    constraint: 1.3,
+    fact: 1.0,
+    preference: 1.2,
+    pattern: 1.1,
+    decision: 0.9,
+    mistake: 0.7,
+};
+export function digestScore(entry, now) {
+    return effectiveConfidence(entry, now) * (KIND_WEIGHTS[entry.kind] ?? 1.0);
+}
+export function effectiveConfidence(entry, now) {
+    if (entry.pinned)
+        return entry.confidence;
+    const halfLifeDays = HALF_LIFE_DAYS[entry.kind];
+    if (halfLifeDays === null)
+        return entry.confidence;
+    const ageDays = (now - entry.created_at) / MS_PER_DAY;
+    let effectiveHalfLife = halfLifeDays;
+    if (entry.layer === 2) {
+        effectiveHalfLife *= LAYER2_HALF_LIFE_MULTIPLIER;
+    }
+    const decay = Math.pow(0.5, ageDays / effectiveHalfLife);
+    return entry.confidence * decay;
+}

package/dist/memory/consolidation.d.ts

@@ -0,0 +1,26 @@
+import type { SessionEvent, SummarizerLLM } from "./types.js";
+import type { MemoryStore } from "./store.js";
+export interface ConsolidationConfig {
+    enabled: boolean;
+    model?: string;
+    promotion_threshold: number;
+    run_delay_seconds: number;
+}
+export interface ConsolidationResult {
+    promotions: number;
+    confirmations: number;
+    contradictions: number;
+    newEntries: number;
+    duration_ms: number;
+}
+/**
+ * Run the consolidation processor.
+ * Re-evaluates session learnings against existing memory and promotes confirmed entries.
+ */
+export declare function runConsolidation(opts: {
+    store: MemoryStore;
+    llm: SummarizerLLM;
+    sessionId: string;
+    events: SessionEvent[];
+    config: ConsolidationConfig;
+}): Promise<ConsolidationResult>;

package/dist/memory/consolidation.js

@@ -0,0 +1,166 @@
+// ============================================================
+// ARIA Memory — Consolidation Processor
+//
+// Background learning loop: re-evaluates session learnings,
+// cross-checks against existing Layer 1 entries, and promotes
+// confirmed patterns to Layer 2 (deep memory).
+// ============================================================
+import { effectiveConfidence } from "./confidence.js";
+import { getAppLogger } from "../logger.js";
+const SYSTEM_PROMPT = `You are a memory consolidation processor for a coding agent.
+Given a session transcript and existing Layer 1 memory entries, you must:
+1. Identify which existing entries are confirmed by the session
+2. Identify which entries are contradicted by the session
+3. Extract new facts, patterns, or decisions not yet in memory
+4. Recommend entries for promotion to Layer 2 (deep memory)
+
+Output ONLY a JSON object with this structure:
+{
+  "confirmations": ["entry_id_1", ...],
+  "contradictions": ["entry_id_2", ...],
+  "new_entries": [
+    { "kind": "fact|preference|decision|pattern|mistake|constraint", "content": "...", "certainty": "high|medium|low" }
+  ],
+  "promotions": ["entry_id_3", ...]
+}
+
+Rules:
+- confirmations: entry IDs that the session reinforces (mentions, uses, or validates)
+- contradictions: entry IDs that the session explicitly contradicts or disproves
+- new_entries: NEW facts not already covered by existing entries (max 5)
+- promotions: entry IDs ready for Layer 2 (high confidence, confirmed multiple times)
+- Be conservative: only promote entries with confirmation_count >= threshold AND confidence >= 0.6
+- Output ONLY the JSON object. No prose.`;
+function buildConsolidationPrompt(transcript, layer1Entries, promotionThreshold) {
+    const lines = [];
+    lines.push("## Session Transcript");
+    lines.push(truncateText(transcript, 4000));
+    lines.push("");
+    lines.push("## Existing Layer 1 Entries");
+    if (layer1Entries.length === 0) {
+        lines.push("(none)");
+    }
+    else {
+        for (const entry of layer1Entries) {
+            lines.push(`- [${entry.id}] (${entry.kind}, conf=${entry.confidence.toFixed(2)}, confirms=${entry.confirmation_count}) ${entry.content}`);
+        }
+    }
+    lines.push("");
+    lines.push(`## Promotion Threshold`);
+    lines.push(`- confirmation_count >= ${promotionThreshold}`);
+    lines.push(`- confidence >= 0.6`);
+    lines.push("");
+    return lines.join("\n");
+}
+function transcriptToText(events) {
+    const lines = [];
+    for (const e of events) {
+        if (e.type === "user_message")
+            lines.push(`User: ${e.content}`);
+        else if (e.type === "agent_message")
+            lines.push(`Agent: ${e.content}`);
+        else if (e.type === "tool_use")
+            lines.push(`[tool] ${e.tool_name}(${JSON.stringify(e.args ?? {})})`);
+        else if (e.type === "tool_result")
+            lines.push(`[result] ${truncateText(JSON.stringify(e.result), 200)}`);
+    }
+    return lines.join("\n");
+}
+function truncateText(text, maxLen) {
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen - 3) + "...";
+}
+/**
+ * Run the consolidation processor.
+ * Re-evaluates session learnings against existing memory and promotes confirmed entries.
+ */
+export async function runConsolidation(opts) {
+    const startTime = Date.now();
+    const result = {
+        promotions: 0,
+        confirmations: 0,
+        contradictions: 0,
+        newEntries: 0,
+        duration_ms: 0,
+    };
+    if (!opts.config.enabled)
+        return result;
+    if (opts.events.length === 0)
+        return result;
+    if (!(await opts.llm.available()))
+        return result;
+    try {
+        // Get Layer 1 entries for the current scope
+        const allEntries = opts.store.getAllEntries();
+        const layer1Entries = allEntries.filter((e) => e.layer === 1);
+        // Build the prompt
+        const transcript = transcriptToText(opts.events);
+        const prompt = buildConsolidationPrompt(transcript, layer1Entries, opts.config.promotion_threshold);
+        // Single LLM call
+        const raw = await opts.llm.complete({
+            system: SYSTEM_PROMPT,
+            prompt,
+            temperature: 0.2,
+            maxTokens: 2000,
+            json: true,
+            timeoutMs: 60_000,
+        });
+        const parsed = JSON.parse(raw);
+        // Process confirmations
+        if (Array.isArray(parsed.confirmations)) {
+            for (const id of parsed.confirmations) {
+                const entry = allEntries.find((e) => e.id === id);
+                if (entry && entry.layer === 1) {
+                    opts.store.reinforceFromSuccessfulToolOutcome([id], 0.1);
+                    result.confirmations++;
+                }
+            }
+        }
+        // Process contradictions
+        if (Array.isArray(parsed.contradictions)) {
+            for (const id of parsed.contradictions) {
+                const entry = allEntries.find((e) => e.id === id);
+                if (entry && entry.layer === 1) {
+                    // Weaken contradicted entries
+                    opts.store.weakenEntry(id, 0.2);
+                    result.contradictions++;
+                }
+            }
+        }
+        // Process new entries
+        if (Array.isArray(parsed.new_entries)) {
+            for (const newEntry of parsed.new_entries.slice(0, 5)) {
+                if (["fact", "preference", "decision", "pattern", "mistake", "constraint"].includes(newEntry.kind)) {
+                    await opts.store.remember(newEntry.content, {
+                        kind: newEntry.kind,
+                        certainty: (newEntry.certainty === "high" || newEntry.certainty === "medium" || newEntry.certainty === "low")
+                            ? newEntry.certainty
+                            : "medium",
+                    });
+                    result.newEntries++;
+                }
+            }
+        }
+        // Process promotions to Layer 2
+        if (Array.isArray(parsed.promotions)) {
+            for (const id of parsed.promotions) {
+                const entry = allEntries.find((e) => e.id === id);
+                if (entry &&
+                    entry.layer === 1 &&
+                    entry.confirmation_count >= opts.config.promotion_threshold &&
+                    effectiveConfidence(entry, Date.now()) >= 0.6) {
+                    opts.store.promoteToLayer2(id);
+                    result.promotions++;
+                }
+            }
+        }
+    }
+    catch (err) {
+        getAppLogger().child("memory").warn("Error during consolidation", {
+            cause: err,
+        });
+    }
+    result.duration_ms = Date.now() - startTime;
+    return result;
+}

package/dist/memory/db.d.ts

@@ -0,0 +1,40 @@
+import Database from "better-sqlite3";
+import type { MemoryEntry, MemoryKind } from "./types.js";
+export interface OpenMemoryDbResult {
+    db: Database.Database;
+    needsReembed: boolean;
+}
+export declare function openMemoryDb(path: string, embeddingDim?: number): OpenMemoryDbResult;
+export declare function markReembedNeeded(db: Database.Database): void;
+export declare function clearReembedNeeded(db: Database.Database): void;
+export declare function insertEntry(db: Database.Database, e: MemoryEntry): void;
+export declare function touchEntry(db: Database.Database, id: string, now: number): void;
+export declare function reinforceEntry(db: Database.Database, id: string, alpha?: number): void;
+export declare function weakenEntry(db: Database.Database, id: string, beta?: number): void;
+export declare function stampReinforcement(db: Database.Database, entryId: string, sessionId: string): void;
+export declare function flushReinforcements(db: Database.Database, sessionId: string): void;
+export declare function getEntryById(db: Database.Database, id: string): MemoryEntry | undefined;
+export declare function getAllEntries(db: Database.Database): MemoryEntry[];
+export declare function getEntriesByScope(db: Database.Database, scopes: string[]): MemoryEntry[];
+export declare function deleteEntry(db: Database.Database, id: string): void;
+export declare function retractMemory(db: Database.Database, id: string): void;
+export declare function startSessionRow(db: Database.Database, s: {
+    id: string;
+    agent: string;
+    user_id: string;
+    context_id: string;
+    started_at: number;
+}): void;
+export declare function endSessionRow(db: Database.Database, id: string, endedAt: number, reason: string): void;
+export declare function upsertEmbedding(db: Database.Database, entryId: string, embedding: Float32Array): void;
+export declare function searchByVector(db: Database.Database, query: Float32Array, k: number): Array<{
+    entry_id: string;
+    distance: number;
+}>;
+export declare function searchByFts(db: Database.Database, query: string, k: number, filters?: {
+    scopes?: string[];
+    kinds?: MemoryKind[];
+}): Array<{
+    entry_id: string;
+    rank: number;
+}>;