praana 0.5.0

package/dist/state-graph.js

@@ -0,0 +1,255 @@
+import { ulid } from "ulid";
+export class StateGraph {
+    objects = new Map();
+    touchedTurn = new Map(); // turn number when last touched
+    turnCount = 0;
+    clear() {
+        this.objects.clear();
+        this.touchedTurn.clear();
+        this.turnCount = 0;
+    }
+    create(kind, payload) {
+        const now = Date.now();
+        const obj = {
+            id: ulid(),
+            kind,
+            tier: "active",
+            payload,
+            created: now,
+            updated: now,
+            lastTouched: now,
+        };
+        this.objects.set(obj.id, obj);
+        this.touchedTurn.set(obj.id, this.turnCount);
+        return obj;
+    }
+    update(id, patch) {
+        const obj = this.objects.get(id);
+        if (!obj)
+            return null;
+        obj.payload = { ...obj.payload, ...patch };
+        obj.updated = Date.now();
+        obj.lastTouched = Date.now();
+        this.touchedTurn.set(id, this.turnCount);
+        return obj;
+    }
+    setTier(id, tier) {
+        const obj = this.objects.get(id);
+        if (!obj)
+            return false;
+        obj.tier = tier;
+        obj.lastTouched = Date.now();
+        this.touchedTurn.set(id, this.turnCount);
+        return true;
+    }
+    retractObject(id) {
+        const obj = this.objects.get(id);
+        if (!obj)
+            return false;
+        obj.retracted = true;
+        obj.updated = Date.now();
+        obj.lastTouched = Date.now();
+        this.touchedTurn.set(id, this.turnCount);
+        return true;
+    }
+    get(id) {
+        return this.objects.get(id);
+    }
+    /** All active objects; focused object first, then by created asc, id asc. */
+    getActive() {
+        return [...this.objects.values()]
+            .filter((o) => o.tier === "active" && !o.retracted)
+            .sort((a, b) => {
+            const af = a.focused ? 1 : 0;
+            const bf = b.focused ? 1 : 0;
+            if (bf !== af)
+                return bf - af;
+            return a.created - b.created || (a.id < b.id ? -1 : 1);
+        });
+    }
+    /** Pin one task/object as focused; clears focus on all others. */
+    setFocus(id) {
+        const target = this.objects.get(id);
+        if (!target)
+            return false;
+        for (const obj of this.objects.values()) {
+            obj.focused = obj.id === id;
+        }
+        target.lastTouched = Date.now();
+        this.touchedTurn.set(id, this.turnCount);
+        return true;
+    }
+    /** All soft + hard objects, sorted by updated desc. */
+    getPeripheral() {
+        return [...this.objects.values()]
+            .filter((o) => (o.tier === "soft" || o.tier === "hard") && !o.retracted)
+            .sort((a, b) => b.updated - a.updated);
+    }
+    /** All objects with summary. */
+    list() {
+        return [...this.objects.values()]
+            .filter((o) => !o.retracted)
+            .sort((a, b) => a.created - b.created || (a.id < b.id ? -1 : 1))
+            .map((o) => ({
+            id: o.id,
+            kind: o.kind,
+            tier: o.tier,
+            summary: summarizePayload(o),
+        }));
+    }
+    /** Full snapshot including retracted objects — for event logging and audit. */
+    snapshot() {
+        return [...this.objects.values()].sort((a, b) => a.created - b.created || (a.id < b.id ? -1 : 1));
+    }
+    getTouchedTurn(id) {
+        return this.touchedTurn.get(id) ?? 0;
+    }
+    incrementTurn() {
+        this.turnCount++;
+    }
+    getTurnCount() {
+        return this.turnCount;
+    }
+    /**
+     * Auto-promote peripheral objects whose payload matches keywords in the query.
+     * Returns IDs of objects that were hydrated.
+     */
+    autoHydrate(query) {
+        const keywords = extractKeywords(query);
+        if (keywords.length === 0)
+            return [];
+        const hydrated = [];
+        for (const obj of this.getPeripheral()) {
+            const text = payloadToSearchableText(obj).toLowerCase();
+            if (keywords.some((kw) => text.includes(kw))) {
+                obj.tier = "active";
+                obj.lastTouched = Date.now();
+                this.touchedTurn.set(obj.id, this.turnCount);
+                hydrated.push(obj.id);
+            }
+        }
+        return hydrated;
+    }
+    /** Rebuild state from context_action events during resume. */
+    replayAction(payload) {
+        const action = payload.action;
+        const id = payload.id;
+        switch (action) {
+            case "create":
+                this.objects.set(id, {
+                    id,
+                    kind: payload.kind,
+                    tier: payload.tier ?? "active",
+                    payload: payload.statePayload,
+                    created: payload.created,
+                    updated: payload.updated,
+                    lastTouched: payload.lastTouched,
+                });
+                break;
+            case "update": {
+                const obj = this.objects.get(id);
+                if (obj && payload.statePayload) {
+                    obj.payload = {
+                        ...obj.payload,
+                        ...payload.statePayload,
+                    };
+                    obj.updated = payload.updated;
+                    obj.lastTouched = payload.lastTouched;
+                }
+                break;
+            }
+            case "setTier": {
+                const obj2 = this.objects.get(id);
+                if (obj2) {
+                    obj2.tier = payload.tier;
+                    obj2.lastTouched = payload.lastTouched;
+                }
+                break;
+            }
+            case "setFocus": {
+                const obj3 = this.objects.get(id);
+                if (obj3) {
+                    for (const o of this.objects.values()) {
+                        o.focused = o.id === id;
+                    }
+                    obj3.lastTouched = payload.lastTouched;
+                }
+                break;
+            }
+            case "retract": {
+                const obj4 = this.objects.get(id);
+                if (obj4) {
+                    obj4.retracted = true;
+                    obj4.updated = payload.updated;
+                }
+                break;
+            }
+        }
+    }
+}
+// ---- Helpers ----
+function summarizePayload(obj) {
+    switch (obj.kind) {
+        case "task": {
+            const p = obj.payload;
+            return `${p.status}: ${p.title}`;
+        }
+        case "decision": {
+            const p = obj.payload;
+            return p.summary;
+        }
+        case "constraint": {
+            const p = obj.payload;
+            return p.text.length > 80 ? p.text.slice(0, 80) + "..." : p.text;
+        }
+        case "note": {
+            const p = obj.payload;
+            return p.text.length > 80 ? p.text.slice(0, 80) + "..." : p.text;
+        }
+    }
+}
+export function summarizePayloadFn(obj) {
+    return summarizePayload(obj);
+}
+// ---- Auto-hydrate helpers ----
+const STOP_WORDS = new Set([
+    "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
+    "have", "has", "had", "do", "does", "did", "will", "would", "could",
+    "should", "may", "might", "must", "shall", "can", "need", "ought",
+    "to", "of", "in", "for", "on", "with", "at", "by", "from", "as",
+    "into", "through", "during", "before", "after", "above", "below",
+    "between", "under", "again", "further", "then", "once", "here",
+    "there", "when", "where", "why", "how", "all", "each", "few", "more",
+    "most", "other", "some", "such", "no", "nor", "not", "only", "own",
+    "same", "so", "than", "too", "very", "just", "and", "but", "if", "or",
+    "because", "until", "while", "what", "which", "who", "whom", "this",
+    "that", "these", "those", "am", "it", "its", "they", "them", "their",
+    "i", "me", "my", "we", "our", "you", "your", "he", "him", "his", "she",
+    "her", "hers",
+]);
+function extractKeywords(query) {
+    return query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((w) => w.length >= 3 && !STOP_WORDS.has(w));
+}
+function payloadToSearchableText(obj) {
+    switch (obj.kind) {
+        case "task": {
+            const p = obj.payload;
+            return [p.title, p.description ?? ""].join(" ");
+        }
+        case "decision": {
+            const p = obj.payload;
+            return [p.summary, p.rationale].join(" ");
+        }
+        case "constraint": {
+            const p = obj.payload;
+            return p.text;
+        }
+        case "note": {
+            const p = obj.payload;
+            return p.text;
+        }
+    }
+}

package/dist/status-bar.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Session status bar rendered above the readline prompt (stderr).
+ * Surfaces model, context usage, mode, repo, memory tiers, skills, and current task.
+ */
+import type { CompileMetrics } from "./compiler.js";
+import type { Session } from "./session.js";
+import type { StateGraph } from "./state-graph.js";
+/** Default model context window when provider metadata is unavailable. */
+export declare const DEFAULT_CONTEXT_WINDOW = 128000;
+export interface StatusBarInput {
+    model: string;
+    repoPath: string;
+    cwd: string;
+    debug: boolean;
+    thinking: boolean;
+    memoryEnabled: boolean;
+    incognito: boolean;
+    contextUsedTokens: number;
+    contextWindowTokens: number;
+    memoryStats: {
+        active: number;
+        soft: number;
+        hard: number;
+    };
+    skills: string[];
+    skillResidency: {
+        hot: number;
+        warm: number;
+        total: number;
+    } | null;
+    currentTask: string | null;
+    agentsContextLoaded: boolean;
+}
+/** Format token counts for compact display (e.g. 18400 → "18.4k"). */
+export declare function formatTokenCount(tokens: number): string;
+/** Short repo label: git root folder name, or cwd folder name. */
+export declare function formatRepoLabel(repoPath: string, cwd: string): string;
+/** Mode string for the status bar (debug + thinking visibility). */
+export declare function formatMode(debug: boolean, thinking: boolean): string;
+/** Pick the current task title: doing first, then oldest todo. */
+export declare function getCurrentTaskTitle(stateGraph: StateGraph): string | null;
+export declare function buildStatusBarInput(session: Session, opts: {
+    model: string;
+    debug: boolean;
+    thinking: boolean;
+    contextWindowTokens?: number;
+    compileMetrics?: CompileMetrics | null;
+}): StatusBarInput;
+/** Render status bar lines (no trailing newline on last line — caller adds newline). */
+export declare function formatStatusBarLines(input: StatusBarInput): string[];
+/** Write the status bar to stderr (no-op when not a TTY). */
+export declare function renderStatusBar(input: StatusBarInput): void;
+/** One-line emoji status bar — compact with pipe separators. */
+export declare function formatEmojiStatusLine(input: StatusBarInput): string;

package/dist/status-bar.js

@@ -0,0 +1,184 @@
+/**
+ * Session status bar rendered above the readline prompt (stderr).
+ * Surfaces model, context usage, mode, repo, memory tiers, skills, and current task.
+ */
+import { basename } from "node:path";
+import chalk from "chalk";
+/** Default model context window when provider metadata is unavailable. */
+export const DEFAULT_CONTEXT_WINDOW = 128_000;
+/** Format token counts for compact display (e.g. 18400 → "18.4k"). */
+export function formatTokenCount(tokens) {
+    if (tokens < 1000)
+        return String(tokens);
+    if (tokens < 1_000_000) {
+        const k = tokens / 1000;
+        if (k >= 100 && Number.isInteger(k))
+            return `${k}k`;
+        if (k >= 100)
+            return `${Math.round(k)}k`;
+        const fixed = k.toFixed(1);
+        return `${fixed.endsWith(".0") ? fixed.slice(0, -2) : fixed}k`;
+    }
+    return `${(tokens / 1_000_000).toFixed(1)}M`;
+}
+/** Short repo label: git root folder name, or cwd folder name. */
+export function formatRepoLabel(repoPath, cwd) {
+    const rootName = basename(repoPath);
+    const cwdName = basename(cwd);
+    if (repoPath === cwd || rootName === cwdName)
+        return rootName;
+    return `${rootName}/${cwdName}`;
+}
+/** Mode string for the status bar (debug + thinking visibility). */
+export function formatMode(debug, thinking) {
+    if (debug && thinking)
+        return "debug+think";
+    if (debug)
+        return "debug";
+    if (!thinking)
+        return "normal·think-off";
+    return "normal";
+}
+/** Pick the current task title: doing first, then oldest todo. */
+export function getCurrentTaskTitle(stateGraph) {
+    const tasks = stateGraph
+        .list()
+        .filter((o) => o.kind === "task")
+        .map((o) => {
+        const obj = stateGraph.get(o.id);
+        return obj ? obj.payload : null;
+    })
+        .filter((p) => p !== null);
+    const doing = tasks.find((t) => t.status === "doing");
+    if (doing)
+        return doing.title;
+    const todo = tasks.find((t) => t.status === "todo");
+    return todo?.title ?? null;
+}
+export function buildStatusBarInput(session, opts) {
+    const mem = session.getMemoryStats();
+    const metrics = opts.compileMetrics ?? session.getLastCompileMetrics();
+    const agentsContextTokens = session.agentsContext
+        ? Math.ceil(session.agentsContext.length / 4)
+        : 0;
+    const skillResidency = session.skillRuntime?.getResidencyCounts();
+    return {
+        model: opts.model,
+        repoPath: session.getRepoRoot(),
+        cwd: session.cwd,
+        debug: opts.debug,
+        thinking: opts.thinking,
+        memoryEnabled: session.memoryEnabled,
+        incognito: session.isIncognito(),
+        contextUsedTokens: metrics?.totalTokens ?? agentsContextTokens,
+        contextWindowTokens: opts.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW,
+        memoryStats: { active: mem.active, soft: mem.soft, hard: mem.hard },
+        skills: (session.skills ?? []).map((s) => s.name),
+        skillResidency: skillResidency
+            ? { hot: skillResidency.hot, warm: skillResidency.warm, total: skillResidency.hot + skillResidency.warm + skillResidency.cold }
+            : null,
+        currentTask: getCurrentTaskTitle(session.stateGraph),
+        agentsContextLoaded: !!session.agentsContext,
+    };
+}
+/** Render status bar lines (no trailing newline on last line — caller adds newline). */
+export function formatStatusBarLines(input) {
+    const ctx = `${formatTokenCount(input.contextUsedTokens)} / ${formatTokenCount(input.contextWindowTokens)}`;
+    const repo = formatRepoLabel(input.repoPath, input.cwd);
+    const memFlag = input.incognito
+        ? chalk.magenta("incognito")
+        : input.memoryEnabled
+            ? chalk.green("on")
+            : chalk.dim("off");
+    const agents = input.agentsContextLoaded ? chalk.dim("· AGENTS.md") : "";
+    const line1 = [
+        chalk.cyan(input.model.split("/").pop() ?? input.model),
+        chalk.dim(ctx),
+        chalk.yellow(formatMode(input.debug, input.thinking)),
+        chalk.blue(repo),
+        `memory ${memFlag}${agents}`,
+    ].join(chalk.dim(" · "));
+    const line2 = [
+        chalk.bold("Memory:"),
+        `${input.memoryStats.active} active`,
+        `${input.memoryStats.soft} soft`,
+        `${input.memoryStats.hard} hard`,
+    ].join(chalk.dim(" · "));
+    const line3 = [chalk.bold("Context:"), ctx].join(" ");
+    const skillsLabel = input.skills.length > 0
+        ? `${input.skills.length} skills (${input.skillResidency ? `${input.skillResidency.hot} HOT · ${input.skillResidency.warm} WARM · ${input.skillResidency.total - input.skillResidency.hot - input.skillResidency.warm} COLD` : "?/?/? loaded"})`
+        : chalk.dim("(none — add skills/*.md to project root)");
+    const line4 = [chalk.bold("Skills:"), skillsLabel].join(" ");
+    const taskLabel = input.currentTask
+        ? chalk.white(input.currentTask)
+        : chalk.dim("(none — create_task)");
+    const line5 = [chalk.bold("Current task:"), taskLabel].join(" ");
+    return [line1, line2, line3, line4, line5];
+}
+/** Write the status bar to stderr (no-op when not a TTY). */
+export function renderStatusBar(input) {
+    if (!process.stderr.isTTY)
+        return;
+    const width = process.stderr.columns ?? 80;
+    const lines = formatStatusBarLines(input).map((line) => truncateAnsiLine(line, width));
+    for (const line of lines) {
+        process.stderr.write(line + "\n");
+    }
+}
+/** One-line emoji status bar — compact with pipe separators. */
+export function formatEmojiStatusLine(input) {
+    const modelShort = input.model.split("/").pop() ?? input.model;
+    const pct = input.contextWindowTokens > 0
+        ? Math.min(100, Math.round((input.contextUsedTokens / input.contextWindowTokens) * 100))
+        : 0;
+    const memStr = input.incognito ? "incognito" : input.memoryEnabled ? "on" : "off";
+    const skillsCount = input.skills.length;
+    let stateStr = "";
+    if (input.memoryStats && (input.memoryStats.active > 0 || input.memoryStats.soft > 0 || input.memoryStats.hard > 0)) {
+        const parts = [];
+        if (input.memoryStats.active > 0)
+            parts.push(`${input.memoryStats.active}A`);
+        if (input.memoryStats.soft > 0)
+            parts.push(`${input.memoryStats.soft}S`);
+        if (input.memoryStats.hard > 0)
+            parts.push(`${input.memoryStats.hard}H`);
+        stateStr = parts.join("/");
+    }
+    const parts = [
+        chalk.cyan(`📦 model: ${input.model}`),
+        pct > 90 ? chalk.red(`🧠 ctx: ${pct}%`) : pct > 70 ? chalk.yellow(`🧠 ctx: ${pct}%`) : chalk.dim(`🧠 ctx: ${pct}%`),
+        memStr === "on" ? chalk.green(`💾 mem: ${memStr}`) : chalk.dim(`💾 mem: ${memStr}`),
+    ];
+    if (skillsCount > 0) {
+        parts.push(chalk.magenta(`🛠️  ${skillsCount}sk${stateStr ? ` [${stateStr}]` : ""}`));
+    }
+    else if (stateStr) {
+        parts.push(chalk.magenta(`🛠️  [${stateStr}]`));
+    }
+    if (input.currentTask) {
+        parts.push(chalk.dim(`🎯 ${input.currentTask}`));
+    }
+    return parts.join(chalk.dim("  |  "));
+}
+function truncateAnsiLine(line, maxWidth) {
+    const visible = stripAnsi(line);
+    if (visible.length <= maxWidth)
+        return line;
+    const suffix = "…";
+    const target = Math.max(10, maxWidth - suffix.length);
+    let cut = 0;
+    let vis = 0;
+    while (cut < line.length && vis < target) {
+        if (line[cut] === "\x1b") {
+            const end = line.indexOf("m", cut);
+            cut = end >= 0 ? end + 1 : cut + 1;
+            continue;
+        }
+        cut++;
+        vis++;
+    }
+    return line.slice(0, cut) + chalk.dim(suffix);
+}
+function stripAnsi(s) {
+    return s.replace(/\x1b\[[0-9;]*m/g, "");
+}

package/dist/thinking-display.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Pure helpers for the thinking block display.
+ *
+ * Extracted from main.ts so the buffering / summary / toggle logic
+ * can be unit-tested without mocking process.stdout or stdin.
+ */
+export interface ThinkingState {
+    open: boolean;
+    buffer: string;
+    visible: boolean;
+}
+export declare function createThinkingState(initialVisible: boolean): ThinkingState;
+/** Append a thinking delta to the buffer. Returns whether the header should be printed. */
+export declare function onThinkingDelta(state: ThinkingState, delta: string): {
+    printHeader: boolean;
+    printDelta: boolean;
+};
+/** Close the thinking block. Returns the summary line (or null if empty). */
+export declare function closeThinking(state: ThinkingState): string | null;
+/** Toggle visibility. Returns the new state. */
+export declare function toggleThinking(state: ThinkingState): boolean;

package/dist/thinking-display.js

@@ -0,0 +1,37 @@
+/**
+ * Pure helpers for the thinking block display.
+ *
+ * Extracted from main.ts so the buffering / summary / toggle logic
+ * can be unit-tested without mocking process.stdout or stdin.
+ */
+export function createThinkingState(initialVisible) {
+    return { open: false, buffer: "", visible: initialVisible };
+}
+/** Append a thinking delta to the buffer. Returns whether the header should be printed. */
+export function onThinkingDelta(state, delta) {
+    if (!state.visible) {
+        return { printHeader: false, printDelta: false };
+    }
+    state.buffer += delta;
+    if (!state.open) {
+        state.open = true;
+        return { printHeader: true, printDelta: true };
+    }
+    return { printHeader: false, printDelta: true };
+}
+/** Close the thinking block. Returns the summary line (or null if empty). */
+export function closeThinking(state) {
+    if (!state.open)
+        return null;
+    const summary = state.buffer.trim().length > 0
+        ? `  [thinking: ${state.buffer.trim().length} chars]`
+        : null;
+    state.open = false;
+    state.buffer = "";
+    return summary;
+}
+/** Toggle visibility. Returns the new state. */
+export function toggleThinking(state) {
+    state.visible = !state.visible;
+    return state.visible;
+}

package/dist/tool-summary.d.ts

@@ -0,0 +1,4 @@
+/** Compact summaries for tool call / result display in terminal and TUI. */
+export declare function formatToolResultRawText(result: unknown): string;
+export declare function summarizeArgs(toolName: string, args: Record<string, unknown>): string;
+export declare function summarizeResult(result: unknown): string;

package/dist/tool-summary.js

@@ -0,0 +1,67 @@
+/** Compact summaries for tool call / result display in terminal and TUI. */
+export function formatToolResultRawText(result) {
+    if (typeof result === "string")
+        return result;
+    try {
+        return JSON.stringify(result);
+    }
+    catch {
+        return String(result);
+    }
+}
+export function summarizeArgs(toolName, args) {
+    switch (toolName) {
+        case "read_file":
+        case "write_file":
+        case "edit_file":
+            return String(args.path ?? "");
+        case "shell":
+            return String(args.command ?? "").slice(0, 80);
+        case "create_task":
+            return String(args.title ?? "");
+        case "complete_task":
+        case "hydrate":
+        case "soft_unload":
+        case "hard_unload":
+            return String(args.id ?? "").slice(0, 26);
+        case "add_constraint":
+        case "add_note":
+            return String(args.text ?? "").slice(0, 60);
+        case "decide":
+            return String(args.summary ?? "").slice(0, 60);
+        case "recall":
+        case "search_session_log":
+            return String(args.query ?? "").slice(0, 60);
+        case "remember":
+            return String(args.content ?? "").slice(0, 60);
+        default:
+            return Object.entries(args)
+                .map(([k, v]) => `${k}=${JSON.stringify(v).slice(0, 40)}`)
+                .join(", ")
+                .slice(0, 80);
+    }
+}
+export function summarizeResult(result) {
+    if (result === null || result === undefined)
+        return "done";
+    if (typeof result !== "object")
+        return String(result).slice(0, 120);
+    const r = result;
+    if (r.ok === false && r.error)
+        return `error: ${String(r.error).slice(0, 100)}`;
+    if (r.ok === true || r.ok === undefined) {
+        if (typeof r.stdout === "string" && r.stdout.length > 0) {
+            const lines = r.stdout.trim().split("\n").length;
+            return `exit ${r.exitCode ?? 0}, ${lines} line(s)`;
+        }
+        if (typeof r.content === "string") {
+            return `${r.content.length} chars`;
+        }
+        if (typeof r.output === "string") {
+            return r.output.slice(0, 100);
+        }
+        if (r.id)
+            return `id ${String(r.id).slice(0, 26)}`;
+    }
+    return JSON.stringify(result).slice(0, 100);
+}