praana 0.5.0

package/dist/ui-events.js

@@ -0,0 +1,33 @@
+import { printDebug, printDebugBlock, printMemoryBanner, printToolCall, startSpinner, stopSpinner, } from "./ui.js";
+/** Default sink: streaming callbacks + legacy terminal helpers. */
+export function createDefaultTurnSink(options) {
+    return {
+        onTextDelta: (delta) => {
+            if (options?.onTextDelta)
+                options.onTextDelta(delta);
+            else
+                process.stdout.write(delta);
+        },
+        onThinkingDelta: (delta) => options?.onThinkingDelta?.(delta),
+        onToolCallsStart: () => options?.onToolCallsStart?.(),
+        onToolCall: (toolName, args) => printToolCall(toolName, args),
+        onToolResult: () => {
+            /* terminal mode doesn't need a separate result block; it streams naturally */
+        },
+        onDebug: (message) => printDebug(message),
+        onDebugBlock: (stepIndex, toolCalls, toolResults) => printDebugBlock(stepIndex, toolCalls, toolResults),
+        onMemoryBanner: (stats) => printMemoryBanner(stats),
+        onSpinnerStart: (text) => startSpinner(text),
+        onSpinnerStop: () => stopSpinner(),
+        onNewline: () => process.stdout.write("\n"),
+        onFallback: (text) => process.stdout.write(text + "\n"),
+        onError: (entry) => {
+            if (entry.level === "error" || entry.level === "warn") {
+                process.stderr.write(`[${entry.domain}] ${entry.message}\n`);
+            }
+        },
+    };
+}
+export function hasTurnUiSink(sink) {
+    return sink !== undefined;
+}

package/dist/ui.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Terminal UI helpers for ARIA.
+ * Tool/status output goes to stderr; stdout gets blank-line breaks so
+ * agent text and debug blocks don't run together in the terminal.
+ *
+ * Color output is managed via chalk (respects NO_COLOR / non-TTY automatically).
+ * Spinner (ora) is only activated when stderr is a real TTY.
+ *
+ * Rich Markdown rendering is provided by marked + marked-terminal.
+ * Boxed layouts use boxen.
+ */
+type UiWriters = {
+    stderr: (line: string) => void;
+    breakStdout: () => void;
+};
+export declare function setUiWriters(overrides?: Partial<UiWriters>): void;
+/** Write a line to the UI stderr channel (tool diffs, ancillary output). */
+export declare function writeUiStderr(line: string): void;
+/**
+ * Start a spinner on stderr with the given text.
+ * No-op when stderr is not a TTY (tests, CI, piped output).
+ */
+export declare function startSpinner(text: string): void;
+/**
+ * Stop and clear the active spinner.
+ * Safe to call when no spinner is running.
+ */
+export declare function stopSpinner(): void;
+/**
+ * Render content inside a styled box (using boxen).
+ * Output goes to stderr.
+ */
+export declare function printBox(content: string, options?: {
+    title?: string;
+    padding?: number;
+    borderColor?: "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "gray";
+}): void;
+/**
+ * Render Markdown text to terminal (writes to stderr).
+ */
+export declare function printMarkdown(text: string): void;
+/** Compact tool indicator — shown in normal mode. */
+export declare function printToolCall(toolName: string, args: Record<string, unknown>): void;
+/**
+ * Render a complete debug block with all tool calls and results in a single
+ * styled box (using boxen). This is the preferred debug display — replaces
+ * the manual start/content/end sequence for a polished look.
+ */
+export declare function printDebugBlock(stepIndex: number, toolCalls: Array<{
+    toolName: string;
+    args: Record<string, unknown>;
+}>, toolResults: Array<{
+    toolName: string;
+    result: unknown;
+}>): void;
+/** Debug block header before a batch of tool calls in a step. */
+export declare function printToolBlockStart(stepIndex: number): void;
+/** Debug tool call with full args. */
+export declare function printToolCallDebug(toolName: string, args: Record<string, unknown>): void;
+/** Debug tool result. */
+export declare function printToolResultDebug(toolName: string, result: unknown): void;
+/** Debug block footer. */
+export declare function printToolBlockEnd(): void;
+/** General debug message (prompt saved, etc.). */
+export declare function printDebug(message: string): void;
+/** Compact per-turn memory banner after each response. */
+export declare function printMemoryBanner(stats: {
+    activeState: number;
+    totalState: number;
+    digestLen: number;
+    recallCalls: number;
+    recallHits: number;
+    autoHydrated: number;
+    promptTokens: number;
+    outputTokens: number;
+}): void;
+export {};

package/dist/ui.js

@@ -0,0 +1,179 @@
+/**
+ * Terminal UI helpers for ARIA.
+ * Tool/status output goes to stderr; stdout gets blank-line breaks so
+ * agent text and debug blocks don't run together in the terminal.
+ *
+ * Color output is managed via chalk (respects NO_COLOR / non-TTY automatically).
+ * Spinner (ora) is only activated when stderr is a real TTY.
+ *
+ * Rich Markdown rendering is provided by marked + marked-terminal.
+ * Boxed layouts use boxen.
+ */
+import chalk from "chalk";
+import ora from "ora";
+import boxen from "boxen";
+import { renderMarkdown } from "./render.js";
+import { summarizeArgs, summarizeResult } from "./tool-summary.js";
+const defaultWriters = {
+    stderr: (line) => process.stderr.write(line),
+    breakStdout: () => process.stdout.write("\n"),
+};
+let writers = defaultWriters;
+let activeSpinner = null;
+function stderr(line) {
+    writers.stderr(line);
+}
+/** Break the agent text flow on stdout before/after ancillary output. */
+function breakStdout() {
+    writers.breakStdout();
+}
+export function setUiWriters(overrides) {
+    if (!overrides) {
+        writers = defaultWriters;
+        return;
+    }
+    writers = {
+        stderr: overrides.stderr ?? defaultWriters.stderr,
+        breakStdout: overrides.breakStdout ?? defaultWriters.breakStdout,
+    };
+}
+/** Write a line to the UI stderr channel (tool diffs, ancillary output). */
+export function writeUiStderr(line) {
+    writers.stderr(line.endsWith("\n") ? line : line + "\n");
+}
+/**
+ * Start a spinner on stderr with the given text.
+ * No-op when stderr is not a TTY (tests, CI, piped output).
+ */
+export function startSpinner(text) {
+    if (!process.stderr.isTTY)
+        return;
+    stopSpinner();
+    activeSpinner = ora({ text, stream: process.stderr, discardStdin: false }).start();
+}
+/**
+ * Stop and clear the active spinner.
+ * Safe to call when no spinner is running.
+ */
+export function stopSpinner() {
+    if (!activeSpinner)
+        return;
+    activeSpinner.stop();
+    activeSpinner = null;
+}
+/**
+ * Render content inside a styled box (using boxen).
+ * Output goes to stderr.
+ */
+export function printBox(content, options) {
+    if (!content)
+        return;
+    const opts = {
+        padding: options?.padding ?? 1,
+        margin: 0,
+        borderStyle: "round",
+        title: options?.title,
+        titleAlignment: "left",
+        ...(options?.borderColor ? { borderColor: options.borderColor } : {}),
+    };
+    stderr(boxen(content, opts) + "\n");
+}
+/**
+ * Render Markdown text to terminal (writes to stderr).
+ */
+export function printMarkdown(text) {
+    if (!text)
+        return;
+    const rendered = renderMarkdown(text);
+    stderr(rendered);
+    if (!rendered.endsWith("\n"))
+        stderr("\n");
+}
+/** Compact tool indicator — shown in normal mode. */
+export function printToolCall(toolName, args) {
+    breakStdout();
+    const summary = summarizeArgs(toolName, args);
+    stderr(`\n${chalk.dim("[tool]")} ${chalk.cyan(toolName)}${summary ? ` ${chalk.dim(`:: ${summary}`)}` : ""}\n`);
+    breakStdout();
+}
+/**
+ * Render a complete debug block with all tool calls and results in a single
+ * styled box (using boxen). This is the preferred debug display — replaces
+ * the manual start/content/end sequence for a polished look.
+ */
+export function printDebugBlock(stepIndex, toolCalls, toolResults) {
+    breakStdout();
+    const lines = [];
+    for (const tc of toolCalls) {
+        const argsJson = JSON.stringify(tc.args);
+        const display = argsJson.length > 200 ? argsJson.slice(0, 197) + "..." : argsJson;
+        lines.push(`${chalk.yellow("▸")} ${chalk.cyan(tc.toolName)}(${chalk.dim(display)})`);
+    }
+    for (const tr of toolResults) {
+        const summary = summarizeResult(tr.result);
+        lines.push(`  ${chalk.green("◂")} ${chalk.cyan(tr.toolName)} ${chalk.dim(summary)}`);
+    }
+    if (lines.length === 0)
+        return;
+    stderr(boxen(lines.join("\n"), {
+        padding: { top: 0, bottom: 0, left: 1, right: 1 },
+        margin: 0,
+        borderStyle: "round",
+        borderColor: "yellow",
+        title: `step ${stepIndex} tools`,
+        titleAlignment: "left",
+    }) + "\n");
+    breakStdout();
+}
+/** Debug block header before a batch of tool calls in a step. */
+export function printToolBlockStart(stepIndex) {
+    breakStdout();
+    stderr(`\n${chalk.yellow("[debug]")} ${chalk.dim(`┌ step ${stepIndex} tool execution ${"─".repeat(18)}┐`)}\n`);
+}
+/** Debug tool call with full args. */
+export function printToolCallDebug(toolName, args) {
+    const argsJson = JSON.stringify(args);
+    const display = argsJson.length > 200 ? argsJson.slice(0, 197) + "..." : argsJson;
+    stderr(`  ${chalk.yellow(">")} ${toolName}(${display})\n`);
+}
+/** Debug tool result. */
+export function printToolResultDebug(toolName, result) {
+    const summary = summarizeResult(result);
+    stderr(`  ${chalk.green("<")} ${toolName} ${chalk.dim(summary)}\n`);
+}
+/** Debug block footer. */
+export function printToolBlockEnd() {
+    stderr(`${chalk.dim(`└${"─".repeat(46)}┘`)}\n`);
+    breakStdout();
+}
+/** General debug message (prompt saved, etc.). */
+export function printDebug(message) {
+    stderr(`\n${chalk.yellow("[debug]")} ${message}\n`);
+    breakStdout();
+}
+/** Compact per-turn memory banner after each response. */
+export function printMemoryBanner(stats) {
+    if (stats.activeState === 0 &&
+        stats.recallCalls === 0 &&
+        stats.autoHydrated === 0 &&
+        stats.digestLen === 0 &&
+        !stats.promptTokens &&
+        !stats.outputTokens)
+        return;
+    const parts = [];
+    if (stats.activeState > 0 || stats.totalState > 0)
+        parts.push(`${stats.activeState}/${stats.totalState} state`);
+    if (stats.digestLen > 0)
+        parts.push(`digest ${stats.digestLen}c`);
+    if (stats.recallCalls > 0)
+        parts.push(`recall ${stats.recallHits}h`);
+    if (stats.autoHydrated > 0)
+        parts.push(`auto+${stats.autoHydrated}`);
+    if (stats.promptTokens && stats.promptTokens > 0)
+        parts.push(`prompt ~${stats.promptTokens}t`);
+    if (stats.outputTokens && stats.outputTokens > 0)
+        parts.push(`out ~${stats.outputTokens}t`);
+    if (parts.length === 0)
+        return;
+    stderr(`\n${chalk.dim(`[state] ${parts.join(" | ")}`)}\n`);
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "praana",
+  "version": "0.5.0",
+  "description": "Terminal coding agent with adaptive context and cross-session memory",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amitkumardubey/praana.git"
+  },
+  "keywords": [
+    "cli",
+    "ai",
+    "coding-agent",
+    "terminal",
+    "assistant",
+    "llm"
+  ],
+  "type": "module",
+  "bin": {
+    "praana": "bin/praana.js",
+    "pran": "bin/pran.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "praana.config.example.toml"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "rm -rf dist && tsc",
+    "start": "node dist/main.js",
+    "dev": "tsx src/main.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.75.5",
+    "better-sqlite3": "^11.0.0",
+    "boxen": "^8.0.1",
+    "chalk": "^5.6.2",
+    "cli-highlight": "^2.1.11",
+    "cliui": "^9.0.1",
+    "ink": "^7.0.5",
+    "ink-text-input": "^6.0.0",
+    "js-yaml": "^4.2.0",
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0",
+    "ora": "^9.4.0",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "pino-roll": "^4.0.0",
+    "react": "^19.2.7",
+    "sqlite-vec": "^0.1.6",
+    "strip-ansi": "^7.2.0",
+    "toml": "^3.0.0",
+    "ulid": "^2.3.0",
+    "zod": "^3.23.0",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.17",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.7"
+  }
+}

package/praana.config.example.toml

@@ -0,0 +1,231 @@
+# PRAANA Configuration — Example
+#
+# Copy this file to `praana.config.toml` in your project root and customize:
+#   cp praana.config.example.toml praana.config.toml
+#
+# All values shown are the built-in defaults. You only need to
+# override what you want to change. PRAANA works with zero config.
+#
+# Config is loaded from (later overrides earlier):
+#   1. ~/.praana/praana.config.json
+#   2. ~/.praana/config.toml
+#   3. ./praana.config.json
+#   4. ./praana.config.toml
+
+[llm]
+# LLM provider. Supported values:
+#   openrouter   — OpenRouter (default). Works with 200+ models from any provider.
+#   openai       — OpenAI API (gpt-4o, o3, etc.)
+#   anthropic    — Anthropic API (claude-sonnet-4, claude-3.5, etc.)
+#   google       — Google Gemini API (gemini-2.5-flash, gemini-2.5-pro)
+#   deepseek     — DeepSeek API (deepseek-v4-pro, deepseek-chat)
+#   groq         — Groq API (fast inference on open models)
+#   mistral      — Mistral AI API
+#   xai          — xAI API (grok)
+#   fireworks    — Fireworks AI
+#   together     — Together AI
+#   ollama       — Local Ollama (no API key needed)
+#   opencode — OpenCode Zen (big-pickle, minimax-m2.5, etc.)
+#   amazon-bedrock — AWS Bedrock (uses AWS credentials, not an API key)
+provider = "openrouter"
+
+# Model name passed to the provider.
+# For OpenRouter: use "provider/model" format, e.g. "deepseek/deepseek-v4-pro"
+# For native providers: use the model name directly, e.g. "claude-sonnet-4-20250514"
+# Override at runtime via PRAANA_MODEL env var (legacy: ARIA_MODEL) or /model command.
+model = "deepseek/deepseek-v4-flash:free"
+
+# Optional: override detected model context window (input tokens) for pressure and compaction
+# context_window = 128000
+
+# Free tier — zero cost, good for getting started.
+# Upgrade to a paid model for better results on complex tasks:
+#   deepseek/deepseek-v4-pro
+#   anthropic/claude-sonnet-4-5
+#   openai/gpt-4o
+
+# Optional: Custom API base URL (e.g., for self-hosted or proxy)
+# base_url = "https://my-proxy.example.com/v1"
+
+# API keys are read from environment variables:
+#   openrouter    → OPENROUTER_API_KEY
+#   openai        → OPENAI_API_KEY
+#   anthropic     → ANTHROPIC_API_KEY
+#   google        → GOOGLE_GENERATIVE_AI_API_KEY
+#   deepseek      → DEEPSEEK_API_KEY
+#   groq          → GROQ_API_KEY
+#   mistral       → MISTRAL_API_KEY
+#   xai           → XAI_API_KEY
+#   fireworks     → FIREWORKS_API_KEY
+#   together      → TOGETHER_API_KEY
+#   ollama        → (none — runs locally)
+#   opencode → OPENCODE_API_KEY (from https://opencode.ai/auth)
+#   amazon-bedrock → (none — uses AWS credentials chain)
+
+[memory]
+# Enable/disable Cognitive Memory (SQLite-backed cross-session persistence)
+enabled = true
+
+# Session-end learning extraction (runs on /exit):
+#   disabled    — no LLM call; no cross-session learnings saved
+#   ollama      — local Ollama chat API (no API key; see ollama_* below)
+#   openrouter  — OpenRouter (OPENROUTER_API_KEY)
+#   openai      — OpenAI API (OPENAI_API_KEY)
+summarizer = "openrouter"
+
+# Path to the SQLite memory database (~ is expanded to $HOME)
+db_path = "~/.praana/memory.db"
+
+# --- Embeddings (semantic /recall) ---
+#   auto          — try Ollama, fall back to hash with a warning
+#   ollama        — require Ollama (fall back to hash if unavailable)
+#   transformers  — @huggingface/transformers (npm install, ~266MB)
+#   llama-cpp     — node-llama-cpp (native, requires build tools)
+#   hash          — deterministic offline vectors (non-semantic)
+embedder = "auto"
+
+# Ollama daemon URL (embeddings + summarizer when summarizer = "ollama")
+ollama_url = "http://localhost:11434"
+
+# Embedding model — must be installed: `ollama pull nomic-embed-text`
+ollama_model = "nomic-embed-text"
+
+# Chat model for summarizer = "ollama" (session-end learnings).
+# Must be a chat model from `ollama list`, not an embedding model.
+# Ways to set it (pick one):
+#   1. ollama_summarizer_model below (recommended)
+#   2. PRAANA_SUMMARIZER_MODEL env var (e.g. export PRAANA_SUMMARIZER_MODEL=qwen3.5:4b)
+#   3. Leave unset — auto-picks the first non-embedding model from `ollama list`
+# ollama_summarizer_model = "qwen3.5:4b"
+
+# --- Example: fully local memory (no OpenRouter for summarizer) ---
+# summarizer = "ollama"
+# embedder = "ollama"
+# ollama_url = "http://localhost:11434"
+# ollama_model = "nomic-embed-text"
+# ollama_summarizer_model = "qwen3.5:4b"
+
+# Summarizer model override for openrouter/openai (ignored when summarizer = "ollama"):
+#   export PRAANA_SUMMARIZER_MODEL=google/gemini-2.5-flash
+
+[compiler]
+# Total estimated token budget for the compiled prompt
+token_budget = 100000
+
+# Number of recent user/agent turns to include in context
+recent_turns = 10
+
+# Token budget reserved specifically for the Recent Turns section
+recent_turns_token_budget = 30000
+
+# Max share of token_budget for AGENTS.md / project context in the system frame
+agents_budget_ratio = 0.3
+
+# Tokens reserved for model output when measuring context pressure
+# reserved_output_tokens = 0
+
+# Auto-compact when prompt fill reaches this ratio of the model context window (classic mode)
+auto_compact_at = 0.75
+
+# Disarm compaction hysteresis below this ratio (classic mode)
+auto_compact_clear_at = 0.55
+
+# Fraction of oldest transcript events to summarise per compaction (classic mode)
+compact_chunk_fraction = 0.25
+
+# Classic mode: never auto-compact (full verbatim until model limit)
+# verbatim_only = false
+
+[skills]
+# Discover and load SKILL.md files (https://agentskills.io/)
+enabled = true
+
+# Max share of token_budget for the skills section in the compiled prompt
+max_token_budget_ratio = 0.2
+
+# Residency: hot skills demote to warm after this many idle turns
+active_skill_idle_turns = 5
+
+# Warm skills evict to cold after this many idle turns
+warm_skill_eviction_turns = 20
+
+# Max directory depth when scanning skill search paths
+max_depth = 6
+
+[tiers]
+# Turns of inactivity before active → soft tier demotion
+idle_soft_after_turns = 20
+
+# Turns of inactivity before active/soft → hard tier demotion
+idle_hard_after_turns = 50
+
+[session]
+# Directory where session event logs are stored
+log_dir = "~/.praana/sessions"
+
+[search_code]
+# Optional: absolute path to the ripgrep binary.
+# Leave unset to resolve "rg" from $PATH (default).
+# Useful when ripgrep is installed outside PATH (e.g. a vendored copy).
+# rg_path = "/opt/homebrew/bin/rg"
+
+[context_engine]
+# Context engine: structured checkpoint, distillation, and scored compilation.
+# When disabled (false), PRAANA runs in classic mode — full verbatim conversation
+# history, no StateGraph tools, skills loaded as metadata catalog only.
+# If enabled but initialization fails, PRAANA falls back to the same classic mode.
+#
+# When enabled, SessionCheckpoint is reconciled after every turn from a
+# deterministic TurnDigest (never by the LLM). Checkpoint sections:
+#   - Active request (latest user intent)
+#   - Session narrative (rolling prose from digest data, max 20 entries)
+#   - Plan (current + superseded plans with completion hints)
+#   - Constraints (append-only, never dropped)
+#   - Decisions (rationale retained even after age-based compaction)
+#   - Files in play, findings, errors, recent activity
+# Casual user preferences ("we use pnpm", "let's use JWT") are NOT captured by regex —
+# the system prompt nudge directs the LLM to call add_constraint for those.
+# Only the unambiguous "not X, Y" correction pattern is regex-captured.
+enabled = false
+
+# Write telemetry even when engine is off (debug / comparison during development)
+measurement_mode = false
+
+# Tool outputs at or below this token count appear verbatim in the prompt
+artifact_inline_threshold = 400
+
+# Turns without access before an artifact is eligible for eviction
+artifact_ttl_turns = 50
+
+# Enable structured SessionCheckpoint in the prompt (see section list above).
+# Section token budgets are fixed in code: narrative/plan 400 each, decisions 800,
+# findings 300. No per-section config yet.
+checkpoint_enabled = true
+
+# Use LLM for ambiguous userIntent extraction (default: first 120 chars)
+llm_digest = false
+
+# Max rolling activity entries kept for checkpoint preview
+activity_log_max_entries = 15
+
+[context_engine.distiller]
+# Distiller compression intensity: "lite" (conservative) or "full" (aggressive)
+default_intensity = "full"
+
+[context_engine.scoring]
+# Scoring weights for context unit selection (3-term model: pin + recency + relevance)
+w_pin = 1.0
+w_recency = 0.5
+w_relevance = 0.3
+
+[context_engine.pressure]
+# Prompt pressure ratio triggers compaction
+compact_at = 0.70
+# Emergency: drop all turn digests, keep checkpoint + verbatim last 2 turns
+emergency_at = 0.85
+
+[ui]
+# Terminal interface: "tui" (Ink chat shell) or "readline" (classic CLI)
+mode = "tui"
+# Screen mode for TUI: "preserve" keeps scrollback (default), "alternate" uses full-screen buffer
+screen = "preserve"