praana 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amit Kumar Dubey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# PRAANA
+
+**A terminal coding agent with adaptive context and cross-session memory.**
+
+PRAANA is experimental software. It runs in your terminal, calls an LLM, executes tools, and tries to keep long sessions usable by compressing old context instead of stuffing everything into the prompt. Between sessions it can extract learnings from transcripts and store them in a local SQLite database.
+
+We have **not** benchmarked PRAANA against other agents. Treat memory and the context engine as ideas we're still proving in real use—not solved problems.
+
+> **Status:** v0.5.0 <!-- x-release-please-version --> — experimental. Core flows work; long or messy tasks will hit rough edges.
+
+> **How it was built:** Entirely vibecoded—this codebase was written by coding agents with human direction and review, not hand-coded line by line.
+
+---
+
+## Quick Start
+
+```bash
+git clone https://github.com/amitkumardubey/praana.git
+cd praana
+npm install && npm run build
+
+cp praana.config.example.toml praana.config.toml
+export OPENROUTER_API_KEY="sk-or-v1-..."   # or another provider — see config example
+
+node dist/main.js
+```
+
+Global CLI (optional):
+
+```bash
+npm run build && npm link
+export PATH="$(npm config get prefix)/bin:$PATH"
+praana    # or the short alias: pran
+```
+
+Requires Node 22+. Default UI is the Ink TUI when stdout is a TTY (`[ui] mode = "tui"`); use `praana --ui readline` for the classic interface. See [`praana.config.example.toml`](./praana.config.example.toml) for providers, memory, and engine settings.
+
+Legacy `aria` config paths and `ARIA_*` environment variables are still read for backward compatibility.
+
+---
+
+## What it does
+
+**Two compile modes** (see `[context_engine] enabled` in config):
+
+| Mode | Default? | Behaviour |
+|---|---|---|
+| **Classic** | Yes (`enabled = false`) | Full verbatim transcript in the prompt. Same general shape as many coding agents. |
+| **Engine** | Opt-in | Tiered working memory, tool-output distillation, session checkpoint, scored prompt compilation, progressive skills. |
+
+**Cross-session memory** (optional, `[memory] enabled = true`):
+
+- At `/exit`, a summariser extracts facts, decisions, patterns, mistakes, preferences, and constraints from the transcript.
+- Next session starts with a ranked digest in the prompt.
+- Project-scoped and global scopes; both are queried and merged in project sessions (#56).
+
+**Project context:** loads `AGENTS.md` / `CLAUDE.md` plus an optional stack fingerprint (`package.json`, `go.mod`, etc.) on session start.
+
+**Skills:** in engine mode, discovers `SKILL.md` files and loads them by relevance; in classic mode, lists paths only.
+
+Architecture details: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) · [docs/concepts.md](./docs/concepts.md)
+
+---
+
+## Known limitations (honest)
+
+These are real gaps today—not a roadmap dressed up as marketing.
+
+| Area | What's weak |
+|---|---|
+| **Memory recall** | Without Ollama or another semantic embedder, `hash` fallback is not meaningfully semantic. Global and project memories merge in project sessions, but near-duplicate or conflicting entries are not automatically reconciled. |
+| **Context engine** | Off by default. Enabling it adds complexity; fallback to classic if init fails. |
+| **Long sessions** | Tiering and distillation help but don't guarantee the model stays on track. |
+| **Hydration** | Demoted state can be hidden until you mention it or the agent calls `hydrate`—the model doesn't always recover context proactively. |
+| **Summariser** | Session-end learning needs a configured summariser and API access; can run in background on exit. |
+| **Shell tool** | Optional path/command sandbox (`[shell]` in config); **off by default**. When disabled, runs with your user permissions. |
+| **Comparison** | No published evals. We don't know if memory beats a plain transcript agent for your workflows. |
+
+If cross-session memory doesn't help you after a few real projects, that's useful feedback—not a surprise.
+
+---
+
+## Slash commands
+
+| Command | Purpose |
+|---|---|
+| `/help` | Full list |
+| `/exit` | End session (runs summariser when memory is on) |
+| `/clear`, `/new` | Reset working memory (engine state / checkpoint) |
+| `/state` | Working-memory objects (engine mode) |
+| `/digest` | Cross-session memory digest |
+| `/recall <query>` | Search persistent memory |
+| `/stats` | Session + memory stats |
+| `/events` | Last 20 session log events |
+| `/model <name>` | Switch model |
+| `/sessions` | List sessions to resume |
+| `/thinking <on\|off>` | Show or hide reasoning text |
+| `/incognito <on\|off>` | Disable cross-session memory writes |
+| `/debug` | Verbose tooling + saved prompts |
+| `/why <id>` | Why a context unit was included (engine + debug) |
+
+---
+
+## Development
+
+```bash
+npm run dev
+npm run build
+npm test
+```
+
+---
+
+## What's next
+
+See [ROADMAP.md](./ROADMAP.md). High level: planner task graph, ongoing confidence reinforcement, LSP integration.
+
+Issues and PRs welcome.
+
+---
+
+## License
+
+MIT — [LICENSE](./LICENSE). Version history: [CHANGELOG.md](./CHANGELOG.md) (auto-generated by release-please on each release).

package/bin/praana.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const mainPath = join(root, "dist/main.js");
+
+if (!existsSync(mainPath)) {
+  process.stderr.write(
+    "[praana] Not built yet. From the repo root, run: npm run build\n"
+  );
+  process.exit(1);
+}
+
+const mod = await import(mainPath);
+await mod.main();

package/bin/pran.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const mainPath = join(root, "dist/main.js");
+
+if (!existsSync(mainPath)) {
+  process.stderr.write(
+    "[pran] Not built yet. From the repo root, run: npm run build\n"
+  );
+  process.exit(1);
+}
+
+const mod = await import(mainPath);
+await mod.main();

package/dist/app-banner.d.ts

@@ -0,0 +1,11 @@
+import type { Session } from "./session.js";
+export declare const APP_VERSION: string;
+export declare function formatSessionBannerLines(session: Session, cwd: string, model: string): string[];
+export declare function printSessionBanner(session: Session, cwd: string, model: string): void;
+export declare function formatSessionEndSummary(session: Session): string;
+/** Resume hint printed after the TUI exits (OpenCode-style epilogue). */
+export declare function formatSessionEpilogue(sessionId: string): string[];
+export declare function printSessionEndSummary(session: Session): void;
+export declare function getHelpLines(): string[];
+export declare function printHelp(): void;
+export declare function formatRecentConversationLines(session: Session, maxMessages?: number): string[];

package/dist/app-banner.js

@@ -0,0 +1,161 @@
+import chalk from "chalk";
+import boxen from "boxen";
+import { readFileSync } from "node:fs";
+import { getLoadedConfigSources } from "./config.js";
+import { APP_NAME, APP_TAGLINE, CLI_NAME, CLI_SHORT, } from "./app-identity.js";
+export const APP_VERSION = readAppVersion();
+function readAppVersion() {
+    try {
+        const pkgUrl = new URL("../package.json", import.meta.url);
+        const pkg = JSON.parse(readFileSync(pkgUrl, "utf-8"));
+        return pkg.version ? `v${pkg.version}` : "v0.0.0";
+    }
+    catch {
+        return "v0.0.0";
+    }
+}
+export function formatSessionBannerLines(session, cwd, model) {
+    const memoryStats = session.getMemoryStats();
+    const digestLen = session.digest?.length ?? 0;
+    const configSources = getLoadedConfigSources();
+    return [
+        `${APP_NAME} ${APP_VERSION}`,
+        `session: ${session.id}`,
+        `cwd: ${cwd}`,
+        `model: ${model}`,
+        ...(configSources.length > 0
+            ? [`config: ${configSources.join(" → ")}`]
+            : [`config: defaults`]),
+        `memory entries: ${memoryStats.total}`,
+        `digest chars: ${digestLen}`,
+        session.memoryEnabled
+            ? `memory db: ${session.getMemoryDbPath() ?? "(unknown)"}`
+            : session.isIncognito()
+                ? "memory: incognito (disabled)"
+                : "memory: disabled",
+    ];
+}
+export function printSessionBanner(session, cwd, model) {
+    const W = 72;
+    const title = `▲ ${APP_NAME} [` + APP_VERSION + "]";
+    console.log(title + " " + "─".repeat(W - title.length - 2) + "┐");
+    const tagline = APP_TAGLINE;
+    console.log("│ " + chalk.dim(tagline) + " ".repeat(W - 3 - tagline.length) + "│");
+    console.log("└" + "─".repeat(W - 2) + "┘");
+}
+export function formatSessionEndSummary(session) {
+    const summary = session.getSessionSummary();
+    return `Session ended: ${summary.turns} turns, ${summary.stateObjects} state objects, ${summary.memoriesStored} memories stored`;
+}
+/** Resume hint printed after the TUI exits (OpenCode-style epilogue). */
+export function formatSessionEpilogue(sessionId) {
+    return ["", `  ${CLI_NAME} resume ${sessionId}`, `  ${CLI_SHORT} resume ${sessionId}`, ""];
+}
+export function printSessionEndSummary(session) {
+    console.log(formatSessionEndSummary(session));
+}
+function usageLines() {
+    return [
+        `  ${CLI_NAME}                     Start new session in current directory`,
+        `  ${CLI_SHORT}                      Short alias for ${CLI_NAME}`,
+        `  ${CLI_NAME} resume <session>    Resume an existing session`,
+        `  ${CLI_NAME} --ui tui            Start with Ink TUI (default when TTY)`,
+        `  ${CLI_NAME} --ui readline       Classic readline interface`,
+        `  ${CLI_NAME} --screen alternate  Full-screen TUI (fixed viewport)`,
+        `  ${CLI_NAME} --debug             Start with debug mode enabled`,
+        `  ${CLI_NAME} --incognito         Start without cross-session memory persistence`,
+        `  ${CLI_NAME} -I                  Short alias for --incognito`,
+        `  ${CLI_NAME} --config <path>     Load config from specific .json/.toml path`,
+        `  ${CLI_NAME} --help              Show this help`,
+    ];
+}
+export function getHelpLines() {
+    return [
+        chalk.bold(`  ${APP_NAME} — ${APP_TAGLINE}`),
+        "",
+        "Usage:",
+        ...usageLines(),
+        "",
+        "Slash Commands:",
+        "  /exit                    End session and save",
+        "  /state                   List all state objects for this session",
+        "  /stats                   Show session, working-memory, and persistent-memory stats",
+        "  /digest                  Print cross-session memory digest",
+        "  /events                  Show last 20 events",
+        "  /recall <query>          Search cross-session knowledge base",
+        "  /model <name>            Switch LLM model (e.g., openai/gpt-4o)",
+        "  /sessions                List recent sessions",
+        "  /debug                   Toggle debug mode (tool blocks + saved prompts)",
+        "  /why <unit-id>           Explain last compile score for a context unit",
+        "  /thinking <on|off>       Toggle thinking stream visibility",
+        "  /incognito <on|off>      Toggle cross-session memory persistence",
+        "  /clear                   Clear working-memory state",
+        "  /new                     Clear working-memory state",
+        "",
+        "  Status bar: model, context, mode, repo, memory tiers, skills, task",
+        "  Esc Esc                  Interrupt a running turn (Ctrl+C also works)",
+        "  /help                    Show this help",
+    ];
+}
+export function printHelp() {
+    const usage = usageLines().join("\n");
+    const commands = [
+        "  /exit                    End session and save",
+        "  /state                   List all state objects for this session",
+        "  /stats                   Show session, working-memory, and persistent-memory stats",
+        "  /digest                  Print cross-session memory digest",
+        "  /events                  Show last 20 events",
+        "  /recall <query>          Search cross-session knowledge base",
+        "  /model <name>            Switch LLM model (e.g., openai/gpt-4o)",
+        "  /sessions                List recent sessions",
+        "  /debug                   Toggle debug mode (tool blocks + saved prompts)",
+        "  /why <unit-id>           Explain last compile score for a context unit",
+        "  /thinking <on|off>       Toggle thinking stream visibility",
+        "  /incognito <on|off>      Toggle cross-session memory persistence",
+        "  /clear                   Clear working-memory state",
+        "  /new                     Clear working-memory state",
+        "",
+        "  Status bar (above prompt): model, context, mode, repo, memory tiers, skills, task",
+        "  Esc Esc                  Interrupt a running turn (Ctrl+C also works)",
+        "  /help                    Show this help",
+    ].join("\n");
+    console.log(chalk.bold(`  ${APP_NAME} — ${APP_TAGLINE}`) +
+        "\n\n" +
+        boxen(usage, {
+            padding: { top: 0, bottom: 0, left: 0, right: 0 },
+            margin: { top: 0, bottom: 1, left: 0, right: 0 },
+            borderStyle: "round",
+            borderColor: "cyan",
+            title: "Usage",
+            titleAlignment: "left",
+        }) +
+        boxen(commands, {
+            padding: { top: 0, bottom: 0, left: 0, right: 0 },
+            margin: { top: 0, bottom: 1, left: 0, right: 0 },
+            borderStyle: "round",
+            borderColor: "green",
+            title: "Slash Commands",
+            titleAlignment: "left",
+        }));
+}
+export function formatRecentConversationLines(session, maxMessages = 6) {
+    const recentEvents = session.eventLog.readLast(30);
+    const turns = recentEvents.filter((e) => e.kind === "user_message" || e.kind === "agent_message");
+    if (turns.length === 0)
+        return [];
+    const lines = [
+        "─".repeat(50),
+        `  📜  Recent conversation (${Math.min(turns.length, maxMessages)} of ${turns.length} messages)`,
+        "─".repeat(50),
+    ];
+    const shown = turns.slice(-maxMessages);
+    for (const ev of shown) {
+        const prefix = ev.kind === "user_message" ? "You" : APP_NAME;
+        const text = ev.payload.text?.trim() ?? "";
+        const displayLines = text.split("\n").slice(0, 2).join(" ");
+        const display = displayLines.length > 150 ? displayLines.slice(0, 147) + "..." : displayLines;
+        lines.push(`  ${prefix}: ${display}`);
+    }
+    lines.push("─".repeat(50));
+    return lines;
+}

package/dist/app-controller.d.ts

@@ -0,0 +1,44 @@
+import type { PraanaConfig } from "./types.js";
+import type { CliArgs } from "./cli-args.js";
+import type { UiMode } from "./types.js";
+import { Session } from "./session.js";
+import type { StatusBarInput } from "./status-bar.js";
+import { type SlashCommandResult } from "./slash-commands.js";
+import type { TurnUiSink } from "./ui-events.js";
+export interface StartupInfo {
+    session: Session;
+    cwd: string;
+    model: string;
+    bannerLines: string[];
+    recentConversationLines: string[];
+    /** Full transcript entries rebuilt from event log on resume (TUI). */
+    transcriptBootstrap: import("./ui/tui/reducer.js").TranscriptEntry[];
+    isResume: boolean;
+}
+export declare class AppController {
+    session: Session;
+    readonly cwd: string;
+    readonly config: PraanaConfig;
+    readonly parsed: CliArgs;
+    showThinking: boolean;
+    currentModel?: string;
+    sessionEnded: boolean;
+    private readonly turnController;
+    private interruptHandling;
+    constructor(opts: {
+        cwd?: string;
+        config: PraanaConfig;
+        parsed: CliArgs;
+    });
+    start(opts?: {
+        uiMode?: UiMode;
+    }): Promise<StartupInfo>;
+    currentModelOrDefault(): string;
+    getStatusBarInput(): StatusBarInput;
+    isTurnActive(): boolean;
+    abortTurn(): void;
+    handleUserInterrupt(onPromptExit?: () => void): "abort_turn" | "prompt_exit" | "noop";
+    executeSlashCommand(input: string): Promise<SlashCommandResult>;
+    runUserTurn(input: string, sink?: TurnUiSink): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/app-controller.js

@@ -0,0 +1,143 @@
+import { resolve } from "node:path";
+import { Session } from "./session.js";
+import { runTurn } from "./turn.js";
+import { TurnController } from "./turn-control.js";
+import { buildStatusBarInput } from "./status-bar.js";
+import { executeSlashCommand } from "./slash-commands.js";
+import { createDefaultTurnSink } from "./ui-events.js";
+import { formatRecentConversationLines, formatSessionBannerLines, } from "./app-banner.js";
+import { buildTranscriptFromEvents } from "./ui/tui/transcript-replay.js";
+export class AppController {
+    session;
+    cwd;
+    config;
+    parsed;
+    showThinking = false;
+    currentModel;
+    sessionEnded = false;
+    turnController = new TurnController();
+    interruptHandling = false;
+    constructor(opts) {
+        this.cwd = opts.cwd ?? resolve(process.cwd());
+        this.config = opts.config;
+        this.parsed = opts.parsed;
+    }
+    async start(opts) {
+        const { sessionId, resumeMode, debug } = this.parsed;
+        const captureNotice = opts?.uiMode === "tui" ? (_line) => { } : undefined;
+        if (resumeMode && sessionId) {
+            this.session = await Session.resume(sessionId, this.cwd, this.config, {
+                captureNotice,
+            });
+            this.session.debug = debug;
+        }
+        else {
+            this.session = await Session.create(this.cwd, this.config, {
+                incognito: this.parsed.incognito,
+                captureNotice,
+            });
+            this.session.debug = debug;
+        }
+        this.currentModel = this.session.getModelOverride() ?? undefined;
+        const model = this.currentModelOrDefault();
+        return {
+            session: this.session,
+            cwd: this.cwd,
+            model,
+            bannerLines: formatSessionBannerLines(this.session, this.cwd, model),
+            recentConversationLines: resumeMode
+                ? formatRecentConversationLines(this.session)
+                : [],
+            transcriptBootstrap: resumeMode
+                ? buildTranscriptFromEvents(this.session.eventLog.readAll())
+                : [],
+            isResume: !!resumeMode,
+        };
+    }
+    currentModelOrDefault() {
+        return this.currentModel ?? this.session.config.llm.model;
+    }
+    getStatusBarInput() {
+        const model = this.currentModelOrDefault();
+        return buildStatusBarInput(this.session, {
+            model,
+            debug: this.session.debug,
+            thinking: this.showThinking,
+            contextWindowTokens: this.session.getContextWindowTokens(model),
+        });
+    }
+    isTurnActive() {
+        return this.turnController.isActive();
+    }
+    abortTurn() {
+        this.turnController.abort();
+    }
+    handleUserInterrupt(onPromptExit) {
+        if (this.interruptHandling)
+            return "noop";
+        this.interruptHandling = true;
+        setImmediate(() => {
+            this.interruptHandling = false;
+        });
+        if (this.turnController.isActive()) {
+            this.turnController.abort();
+            return "abort_turn";
+        }
+        onPromptExit?.();
+        return "prompt_exit";
+    }
+    async executeSlashCommand(input) {
+        return executeSlashCommand(input, this.session, {
+            setModel: (m) => {
+                this.currentModel = m;
+            },
+            setThinking: (v) => {
+                this.showThinking = v;
+            },
+            getThinking: () => this.showThinking,
+        });
+    }
+    async runUserTurn(input, sink) {
+        const uiSink = sink ?? createDefaultTurnSink();
+        const signal = this.turnController.begin();
+        uiSink.onSpinnerStart?.("thinking…");
+        let spinnerStopped = false;
+        const stopSpinnerOnce = () => {
+            if (spinnerStopped)
+                return;
+            uiSink.onSpinnerStop?.();
+            spinnerStopped = true;
+        };
+        const wrappedSink = {
+            ...uiSink,
+            onTextDelta: (delta) => {
+                stopSpinnerOnce();
+                uiSink.onTextDelta?.(delta);
+            },
+            onThinkingDelta: (delta) => {
+                stopSpinnerOnce();
+                uiSink.onThinkingDelta?.(delta);
+            },
+            onToolCallsStart: () => {
+                uiSink.onToolCallsStart?.();
+            },
+        };
+        try {
+            await runTurn(this.session, input, this.currentModel, {
+                signal,
+                sink: wrappedSink,
+            });
+            stopSpinnerOnce();
+        }
+        finally {
+            this.turnController.end();
+        }
+    }
+    async shutdown() {
+        if (this.sessionEnded)
+            return;
+        this.sessionEnded = true;
+        const events = this.session.getTranscriptEvents();
+        await this.session.end("clean", events, { memoryTimeoutMs: 5_000 });
+    }
+}

package/dist/app-identity.d.ts

@@ -0,0 +1,18 @@
+/** Product identity — single source of truth for rename-sensitive strings. */
+export declare const APP_NAME = "PRAANA";
+export declare const APP_TAGLINE = "Persistent Reasoning Agent with Adaptive Navigation and Action";
+export declare const APP_AGENT_ID = "praana";
+/** Memory entries written before the PRAANA rename used this agent scope. */
+export declare const LEGACY_APP_AGENT_ID = "aria";
+export declare const APP_HOME_DIR = ".praana";
+export declare const LEGACY_APP_HOME_DIR = ".aria";
+export declare const CLI_NAME = "praana";
+export declare const CLI_SHORT = "pran";
+export declare function appHomePath(...parts: string[]): string;
+export declare function legacyAppHomePath(...parts: string[]): string;
+/** Prefer PRAANA home; fall back to legacy ~/.aria when the new dir is unused. */
+export declare function resolveAppHomePath(...parts: string[]): string;
+export declare function resolveDefaultMemoryDbPath(): string;
+export declare function resolveDefaultSessionLogDir(): string;
+export declare function envOverride(primary: string, legacy?: string): string | undefined;
+export declare function envFlag(primary: string, legacy?: string): boolean | undefined;

package/dist/app-identity.js

@@ -0,0 +1,52 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Product identity — single source of truth for rename-sensitive strings. */
+export const APP_NAME = "PRAANA";
+export const APP_TAGLINE = "Persistent Reasoning Agent with Adaptive Navigation and Action";
+export const APP_AGENT_ID = "praana";
+/** Memory entries written before the PRAANA rename used this agent scope. */
+export const LEGACY_APP_AGENT_ID = "aria";
+export const APP_HOME_DIR = ".praana";
+export const LEGACY_APP_HOME_DIR = ".aria";
+export const CLI_NAME = "praana";
+export const CLI_SHORT = "pran";
+export function appHomePath(...parts) {
+    return join(homedir(), APP_HOME_DIR, ...parts);
+}
+export function legacyAppHomePath(...parts) {
+    return join(homedir(), LEGACY_APP_HOME_DIR, ...parts);
+}
+/** Prefer PRAANA home; fall back to legacy ~/.aria when the new dir is unused. */
+export function resolveAppHomePath(...parts) {
+    const next = appHomePath(...parts);
+    if (parts.length === 0) {
+        return existsSync(next) || !existsSync(legacyAppHomePath())
+            ? next
+            : legacyAppHomePath();
+    }
+    if (existsSync(next))
+        return next;
+    const legacy = legacyAppHomePath(...parts);
+    return existsSync(legacy) ? legacy : next;
+}
+export function resolveDefaultMemoryDbPath() {
+    return resolveAppHomePath("memory.db");
+}
+export function resolveDefaultSessionLogDir() {
+    return resolveAppHomePath("sessions");
+}
+export function envOverride(primary, legacy) {
+    const value = process.env[primary]?.trim();
+    if (value)
+        return value;
+    if (!legacy)
+        return undefined;
+    return process.env[legacy]?.trim() || undefined;
+}
+export function envFlag(primary, legacy) {
+    const raw = envOverride(primary, legacy);
+    if (raw === undefined)
+        return undefined;
+    return raw === "true" || raw === "1";
+}

package/dist/auto-compact.d.ts

@@ -0,0 +1,16 @@
+import type { Event } from "./types.js";
+import type { Session } from "./session.js";
+import type { SessionEvent } from "./memory/types.js";
+export interface ClassicCompactionResult {
+    compacted: boolean;
+    eventsCompacted: number;
+    factsStored: number;
+    pressureRatio: number;
+}
+export declare function eventsToSessionEvents(events: Event[]): SessionEvent[];
+/**
+ * Classic-mode compaction: summarise oldest transcript events into Cognitive Memory
+ * and mark them compressed so they leave the compiled prompt.
+ */
+export declare function maybeAutoCompactClassic(session: Session, promptTokens: number, modelId: string): Promise<ClassicCompactionResult>;
+export declare function formatCompactionBanner(result: ClassicCompactionResult): string | null;