praana 0.5.0

package/dist/types.d.ts

@@ -0,0 +1,233 @@
+export type StateObjectKind = "task" | "decision" | "constraint" | "note";
+export type StateTier = "active" | "soft" | "hard";
+export interface TaskPayload {
+    title: string;
+    description?: string;
+    status: "todo" | "doing" | "done";
+}
+export interface DecisionPayload {
+    summary: string;
+    rationale: string;
+}
+export interface ConstraintPayload {
+    text: string;
+}
+export interface NotePayload {
+    text: string;
+}
+export type StatePayload = TaskPayload | DecisionPayload | ConstraintPayload | NotePayload;
+export interface StateObject {
+    id: string;
+    kind: StateObjectKind;
+    tier: StateTier;
+    payload: StatePayload;
+    created: number;
+    updated: number;
+    lastTouched: number;
+    focused?: boolean;
+    retracted?: boolean;
+}
+export type EventKind = "user_message" | "agent_message" | "tool_call" | "tool_result" | "context_action" | "system_note";
+export type EventActor = "user" | "agent" | "kernel" | "tool";
+export interface Event {
+    event_id: string;
+    session_id: string;
+    timestamp: number;
+    kind: EventKind;
+    actor: EventActor;
+    payload: Record<string, unknown>;
+}
+export interface ToolResult {
+    ok: boolean;
+    output?: string;
+    error?: string;
+}
+export interface CreateTaskResult extends ToolResult {
+    id?: string;
+}
+export interface ListStateResult extends ToolResult {
+    objects?: Array<{
+        id: string;
+        kind: StateObjectKind;
+        tier: StateTier;
+        summary: string;
+    }>;
+}
+export interface HydrateResult extends ToolResult {
+    payload?: Record<string, unknown>;
+}
+export interface RecallResult extends ToolResult {
+    entries?: Array<{
+        id: string;
+        kind: string;
+        content: string;
+        score?: number;
+        confidence?: number;
+        scopes?: string[];
+    }>;
+}
+export interface RememberResult extends ToolResult {
+    id?: string;
+}
+export interface LlmConfig {
+    provider: string;
+    model: string;
+    base_url?: string;
+    /** Override model context window (input tokens) for pressure and compaction. */
+    context_window?: number;
+}
+export type EmbedderStrategy = "auto" | "ollama" | "transformers" | "llama-cpp" | "hash";
+export interface MemoryConfig {
+    enabled: boolean;
+    /** disabled | ollama | openrouter | openai */
+    summarizer: string;
+    db_path?: string;
+    embedder?: EmbedderStrategy;
+    ollama_url?: string;
+    /** Embedding model (e.g. nomic-embed-text) */
+    ollama_model?: string;
+    /** Chat model for session-end learnings (e.g. qwen3.5:4b). Falls back to first non-embed model from `ollama list`. */
+    ollama_summarizer_model?: string;
+}
+export interface CompilerConfig {
+    token_budget: number;
+    recent_turns: number;
+    recent_turns_token_budget?: number;
+    /** Minimum digest score for a memory entry to appear in the prompt. */
+    recall_min_score?: number;
+    /** Max share of usable prompt budget for cross-session memory section. */
+    memories_budget_ratio?: number;
+    /** Max share of usable prompt budget for project context (AGENTS.md). */
+    agents_budget_ratio?: number;
+    /** @deprecated Use agents_budget_ratio */
+    skills_budget_ratio?: number;
+    /** Tokens reserved for model output when computing section ceilings. */
+    reserved_output_tokens?: number;
+    /** Context fill ratio (0–1) that triggers auto-compaction. Default: 0.75. */
+    auto_compact_at?: number;
+    /** Disarm compaction hysteresis below this ratio. Default: 0.55. */
+    auto_compact_clear_at?: number;
+    /** Fraction (0–1) of oldest transcript events to compact per trigger. Default: 0.25. */
+    compact_chunk_fraction?: number;
+    /** Classic mode: never auto-compact (full verbatim until model limit). Default: false. */
+    verbatim_only?: boolean;
+    /** @deprecated Use auto_compact_at */
+    compression_watermark?: number;
+    /** @deprecated Use compact_chunk_fraction */
+    compression_flush_fraction?: number;
+}
+export interface TiersConfig {
+    idle_soft_after_turns: number;
+    idle_hard_after_turns: number;
+}
+export interface SessionConfig {
+    log_dir: string;
+}
+export interface ConsolidationConfig {
+    /** Enable/disable the background consolidation processor. */
+    enabled: boolean;
+    /** LLM model for consolidation (defaults to memory.summarizer). */
+    model?: string;
+    /** Number of confirmations needed to promote to Layer 2. Default: 3. */
+    promotion_threshold: number;
+    /** Delay in seconds after session end before running consolidation. Default: 30. */
+    run_delay_seconds: number;
+}
+export interface SandboxConfig {
+    enabled: boolean;
+    readonly allowed_paths: readonly string[];
+}
+export type { SkillMetadata, SkillRecord } from "./skills/types.js";
+export interface SkillsConfig {
+    enabled: boolean;
+    max_token_budget_ratio: number;
+    active_skill_idle_turns: number;
+    warm_skill_eviction_turns: number;
+    max_depth: number;
+}
+export interface EditConfig {
+    confirm: boolean;
+}
+export interface SearchCodeConfig {
+    /** Absolute path to the ripgrep binary. Omit to use system "rg" via PATH. */
+    rg_path?: string;
+}
+export type UiMode = "readline" | "tui";
+export type UiScreenMode = "preserve" | "alternate";
+export interface UiConfig {
+    mode: UiMode;
+    screen: UiScreenMode;
+    markdown_rendering: boolean;
+    syntax_highlighting: boolean;
+    syntax_theme: string;
+}
+export type DistillerIntensity = "lite" | "full";
+export interface ContextEngineDistillerConfig {
+    default_intensity: DistillerIntensity;
+}
+export interface ContextEngineScoringConfig {
+    w_pin: number;
+    w_recency: number;
+    w_relevance: number;
+}
+export interface ContextEnginePressureConfig {
+    compact_at: number;
+    emergency_at: number;
+}
+export interface ContextEngineConfig {
+    /** false = classic mode (full verbatim history, no StateGraph, skill metadata only). */
+    enabled: boolean;
+    /** Write context-engine telemetry when engine is off (debug / comparison). */
+    measurement_mode: boolean;
+    /** Tool outputs at or below this token count appear verbatim in the prompt. */
+    artifact_inline_threshold: number;
+    /** Turns without access before an artifact is eligible for eviction. */
+    artifact_ttl_turns: number;
+    distiller: ContextEngineDistillerConfig;
+    /** Use LLM for ambiguous userIntent extraction (default: first 120 chars). */
+    llm_digest: boolean;
+    /** Max rolling activity entries kept for checkpoint preview. */
+    activity_log_max_entries: number;
+    /** Enable structured SessionCheckpoint in the prompt. */
+    checkpoint_enabled: boolean;
+    scoring: ContextEngineScoringConfig;
+    pressure: ContextEnginePressureConfig;
+}
+export interface ProjectDetectionConfig {
+    enabled: boolean;
+    /** Override auto-detected languages (e.g. ["TypeScript", "Python"]) */
+    manual_languages?: string[];
+    /** Override auto-detected frameworks (e.g. ["React", "FastAPI"]) */
+    manual_frameworks?: string[];
+}
+export interface PraanaConfig {
+    llm: LlmConfig;
+    memory: MemoryConfig;
+    compiler: CompilerConfig;
+    tiers: TiersConfig;
+    session: SessionConfig;
+    consolidation: ConsolidationConfig;
+    shell: SandboxConfig;
+    edit: EditConfig;
+    search_code?: SearchCodeConfig;
+    skills: SkillsConfig;
+    ui: UiConfig;
+    context_engine: ContextEngineConfig;
+    project_detection: ProjectDetectionConfig;
+}
+export interface SessionMeta {
+    session_id: string;
+    started_at: number;
+    cwd: string;
+    agent: string;
+}
+export interface CompilerOptions {
+    stateGraph: any;
+    memoryDigest: string | null;
+    recentEvents: Event[];
+    userInput: string;
+    toolSchemas: string[];
+    cwd: string;
+    sessionId: string;
+    tokenBudget: number;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// ============================================================
+// PRAANA — Core Types
+// ============================================================
+export {};

package/dist/ui/readline-ui.d.ts

@@ -0,0 +1,2 @@
+import type { AppController, StartupInfo } from "../app-controller.js";
+export declare function runReadlineUi(controller: AppController, info: StartupInfo): Promise<void>;

package/dist/ui/readline-ui.js

@@ -0,0 +1,176 @@
+import * as readline from "node:readline";
+import chalk from "chalk";
+import { TurnAbortedError, EscInterruptListener } from "../turn-control.js";
+import { formatEmojiStatusLine } from "../status-bar.js";
+import { printSessionBanner, printSessionEndSummary } from "../app-banner.js";
+import { createDefaultTurnSink } from "../ui-events.js";
+import { createThinkingState, onThinkingDelta, closeThinking as closeThinkingBlock, toggleThinking, } from "../thinking-display.js";
+import { startSpinner, stopSpinner } from "../ui.js";
+import { writeMarkdown } from "../render.js";
+export async function runReadlineUi(controller, info) {
+    const { session, cwd, model, isResume } = info;
+    printSessionBanner(session, cwd, model);
+    if (isResume) {
+        if (info.recentConversationLines.length > 0) {
+            console.log("\n" + info.recentConversationLines.join("\n") + "\n");
+        }
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        prompt: "◆ ",
+    });
+    const refreshStatusBar = () => {
+        const line = formatEmojiStatusLine(controller.getStatusBarInput());
+        if (process.stderr.isTTY) {
+            process.stderr.write(line + "\n");
+        }
+        else {
+            console.log(line);
+        }
+    };
+    refreshStatusBar();
+    console.log();
+    rl.prompt();
+    const escListener = new EscInterruptListener();
+    const handleUserInterrupt = () => {
+        controller.handleUserInterrupt(() => {
+            console.log("\nUse /exit to save and quit.");
+            rl.prompt();
+        });
+    };
+    process.on("SIGINT", handleUserInterrupt);
+    rl.on("line", async (line) => {
+        const input = line.trim();
+        if (!input) {
+            rl.prompt();
+            return;
+        }
+        if (input.startsWith("/")) {
+            const result = await controller.executeSlashCommand(input);
+            for (const l of result.lines) {
+                if (l)
+                    console.log(l);
+            }
+            if (result.action === "refresh_status")
+                refreshStatusBar();
+            if (result.action === "exit") {
+                rl.close();
+                return;
+            }
+            rl.prompt();
+            return;
+        }
+        startSpinner("thinking…");
+        let spinnerStopped = false;
+        const stopSpinnerOnce = () => {
+            if (spinnerStopped)
+                return;
+            stopSpinner();
+            spinnerStopped = true;
+        };
+        const thinking = createThinkingState(controller.showThinking);
+        const closeThinking = () => {
+            const summary = closeThinkingBlock(thinking);
+            if (summary) {
+                process.stdout.write(chalk.dim(`\n${summary}\n`));
+            }
+            else {
+                process.stdout.write("\n");
+            }
+        };
+        const onKeypress = (_, key) => {
+            if (key?.name === "t") {
+                const nowVisible = toggleThinking(thinking);
+                process.stdout.write(chalk.dim(nowVisible ? "\n[thinking on]" : "\n[thinking off]"));
+                refreshStatusBar();
+            }
+        };
+        const markdownRendering = controller.config.ui.markdown_rendering;
+        const syntaxTheme = controller.config.ui.syntax_theme;
+        let textBuffer = "";
+        const flushMarkdown = () => {
+            if (textBuffer) {
+                if (markdownRendering) {
+                    // Strip trailing \n before rendering — marked adds its own paragraph breaks.
+                    // Leaving it causes double newlines when successive deltas flush at \n boundaries.
+                    const text = textBuffer.replace(/\n$/, "");
+                    if (text)
+                        writeMarkdown(text, process.stdout);
+                }
+                else {
+                    process.stdout.write(textBuffer);
+                }
+                textBuffer = "";
+            }
+        };
+        const sink = createDefaultTurnSink({
+            onThinkingDelta: (delta) => {
+                stopSpinnerOnce();
+                const { printHeader, printDelta } = onThinkingDelta(thinking, delta);
+                if (!printDelta)
+                    return;
+                if (printHeader) {
+                    process.stdout.write(chalk.dim("\n\n[thinking]\n"));
+                }
+                process.stdout.write(chalk.dim(delta));
+            },
+            onTextDelta: (delta) => {
+                stopSpinnerOnce();
+                closeThinking();
+                if (!markdownRendering) {
+                    process.stdout.write(delta);
+                    return;
+                }
+                textBuffer += delta;
+                const lastNewline = textBuffer.lastIndexOf("\n");
+                if (lastNewline >= 0) {
+                    const toFlush = textBuffer.slice(0, lastNewline);
+                    textBuffer = textBuffer.slice(lastNewline + 1);
+                    if (toFlush)
+                        writeMarkdown(toFlush, process.stdout);
+                }
+            },
+            onToolCallsStart: () => {
+                flushMarkdown();
+                closeThinking();
+            },
+        });
+        sink.flushText = flushMarkdown;
+        process.stdin.on("keypress", onKeypress);
+        escListener.start(() => controller.abortTurn(), rl);
+        try {
+            await controller.runUserTurn(input, sink);
+            flushMarkdown();
+            closeThinking();
+            stopSpinnerOnce();
+        }
+        catch (err) {
+            stopSpinnerOnce();
+            closeThinking();
+            if (err instanceof TurnAbortedError) {
+                console.log(chalk.yellow("\n[interrupted]"));
+            }
+            else {
+                session.getLogger().error("Turn failed", {
+                    code: "TURN_FAILED",
+                    cause: err,
+                });
+            }
+        }
+        finally {
+            process.stdin.removeListener("keypress", onKeypress);
+            escListener.stop();
+        }
+        console.log();
+        refreshStatusBar();
+        rl.prompt();
+    });
+    rl.on("close", async () => {
+        console.log("\nShutting down...");
+        await controller.shutdown();
+        printSessionEndSummary(session);
+        process.exit(0);
+    });
+    rl.on("SIGINT", handleUserInterrupt);
+}

package/dist/ui/tui/app.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+import type { AppController } from "../../app-controller.js";
+export interface TuiAppProps {
+    controller: AppController;
+    initialStatus: import("../../status-bar.js").StatusBarInput;
+    recentLines: string[];
+    transcriptBootstrap?: import("./reducer.js").TranscriptEntry[];
+    bootSummary?: string;
+    markdownRendering?: boolean;
+    syntaxHighlighting?: boolean;
+    syntaxTheme?: string;
+}
+export declare function TuiApp({ controller, initialStatus, recentLines, transcriptBootstrap, bootSummary, markdownRendering, syntaxHighlighting, syntaxTheme, }: TuiAppProps): React.JSX.Element;