praana 0.5.0

package/dist/auto-compact.js

@@ -0,0 +1,101 @@
+import { computeContextPressureRatio, resolveCompactionConfig, shouldTriggerAutoCompact, } from "./context-pressure.js";
+import { getAppLogger } from "./logger.js";
+export function eventsToSessionEvents(events) {
+    const out = [];
+    for (const ev of events) {
+        switch (ev.kind) {
+            case "user_message":
+                out.push({
+                    type: "user_message",
+                    timestamp: ev.timestamp,
+                    content: String(ev.payload.text ?? ""),
+                });
+                break;
+            case "agent_message":
+                out.push({
+                    type: "agent_message",
+                    timestamp: ev.timestamp,
+                    content: String(ev.payload.text ?? ""),
+                });
+                break;
+            case "tool_call":
+                out.push({
+                    type: "tool_use",
+                    timestamp: ev.timestamp,
+                    tool_name: String(ev.payload.tool ?? "unknown"),
+                    args: ev.payload.args ?? {},
+                });
+                break;
+            case "tool_result":
+                out.push({
+                    type: "tool_result",
+                    timestamp: ev.timestamp,
+                    tool_name: String(ev.payload.tool ?? "unknown"),
+                    result: ev.payload.result,
+                });
+                break;
+            default:
+                break;
+        }
+    }
+    return out;
+}
+function selectableHistoryEvents(events) {
+    return events.filter((e) => e.kind !== "context_action" && e.kind !== "system_note");
+}
+/**
+ * Classic-mode compaction: summarise oldest transcript events into Cognitive Memory
+ * and mark them compressed so they leave the compiled prompt.
+ */
+export async function maybeAutoCompactClassic(session, promptTokens, modelId) {
+    const reserved = session.config.compiler.reserved_output_tokens ?? 0;
+    const contextWindow = session.getContextWindowTokens(modelId);
+    const pressureRatio = computeContextPressureRatio(promptTokens, contextWindow, reserved);
+    const { trigger, armed } = shouldTriggerAutoCompact(pressureRatio, session.config.compiler, session.isCompactionArmed());
+    session.setCompactionArmed(armed);
+    if (!trigger) {
+        return { compacted: false, eventsCompacted: 0, factsStored: 0, pressureRatio };
+    }
+    if (!session.memoryEnabled || !session.memoryStore) {
+        return { compacted: false, eventsCompacted: 0, factsStored: 0, pressureRatio };
+    }
+    const { compactChunkFraction } = resolveCompactionConfig(session.config.compiler);
+    const all = session.eventLog.readAllUncompressed();
+    const filtered = selectableHistoryEvents(all);
+    if (filtered.length < 4) {
+        return { compacted: false, eventsCompacted: 0, factsStored: 0, pressureRatio };
+    }
+    const chunkSize = Math.max(2, Math.floor(filtered.length * compactChunkFraction));
+    const toCompress = filtered.slice(0, chunkSize);
+    if (toCompress.length === 0) {
+        return { compacted: false, eventsCompacted: 0, factsStored: 0, pressureRatio };
+    }
+    const sessionEvents = eventsToSessionEvents(toCompress);
+    const factsStored = await session.memoryStore.compressTurns(sessionEvents);
+    session.eventLog.markEventsAsCompressed(toCompress.map((e) => e.event_id));
+    session.eventLog.append({
+        kind: "system_note",
+        actor: "kernel",
+        payload: {
+            type: "history_compacted",
+            eventsCompacted: toCompress.length,
+            factsStored,
+            pressureRatio: Number(pressureRatio.toFixed(3)),
+        },
+    });
+    if (session.debug) {
+        getAppLogger().child("session").debug(`${toCompress.length} event(s) → ${factsStored} memory fact(s) (pressure ${(pressureRatio * 100).toFixed(0)}%)`, { details: { events: toCompress.length, factsStored, pressureRatio } });
+    }
+    return {
+        compacted: true,
+        eventsCompacted: toCompress.length,
+        factsStored,
+        pressureRatio,
+    };
+}
+export function formatCompactionBanner(result) {
+    if (!result.compacted)
+        return null;
+    return (`Auto-compacted ${result.eventsCompacted} older turn(s) into ` +
+        `${result.factsStored} memory fact(s) (${(result.pressureRatio * 100).toFixed(0)}% context)`);
+}

package/dist/cli-args.d.ts

@@ -0,0 +1,14 @@
+import type { UiMode, UiScreenMode } from "./types.js";
+export interface CliArgs {
+    sessionId: string | null;
+    resumeMode: boolean;
+    debug: boolean;
+    incognito: boolean;
+    configPath: string | undefined;
+    showHelp: boolean;
+    uiMode: UiMode | undefined;
+    screenMode: UiScreenMode | undefined;
+}
+export declare function parseCliArgs(args: string[]): CliArgs;
+export declare function resolveUiMode(configMode: UiMode, cliMode: UiMode | undefined, isInteractive: boolean): UiMode;
+export declare function resolveScreenMode(configScreen: UiScreenMode, cliScreen: UiScreenMode | undefined): UiScreenMode;

package/dist/cli-args.js

@@ -0,0 +1,69 @@
+export function parseCliArgs(args) {
+    let sessionId = null;
+    let resumeMode = false;
+    let debug = false;
+    let incognito = false;
+    let configPath;
+    let showHelp = false;
+    let uiMode;
+    let screenMode;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--help" || args[i] === "-h") {
+            showHelp = true;
+            continue;
+        }
+        if (args[i] === "--debug" || args[i] === "-d") {
+            debug = true;
+            continue;
+        }
+        if (args[i] === "--incognito" || args[i] === "-I") {
+            incognito = true;
+            continue;
+        }
+        if ((args[i] === "--config" || args[i] === "-c") && args[i + 1]) {
+            configPath = args[i + 1];
+            i++;
+            continue;
+        }
+        if (args[i] === "--ui" && args[i + 1]) {
+            const mode = args[i + 1].toLowerCase();
+            if (mode === "tui" || mode === "readline") {
+                uiMode = mode;
+            }
+            i++;
+            continue;
+        }
+        if (args[i] === "--screen" && args[i + 1]) {
+            const screen = args[i + 1].toLowerCase();
+            if (screen === "preserve" || screen === "alternate") {
+                screenMode = screen;
+            }
+            i++;
+            continue;
+        }
+        if (args[i] === "resume" && args[i + 1]) {
+            resumeMode = true;
+            sessionId = args[i + 1];
+            i++;
+        }
+    }
+    return {
+        sessionId,
+        resumeMode,
+        debug,
+        incognito,
+        configPath,
+        showHelp,
+        uiMode,
+        screenMode,
+    };
+}
+export function resolveUiMode(configMode, cliMode, isInteractive) {
+    const mode = cliMode ?? configMode;
+    if (mode === "tui" && !isInteractive)
+        return "readline";
+    return mode;
+}
+export function resolveScreenMode(configScreen, cliScreen) {
+    return cliScreen ?? configScreen;
+}

package/dist/compile-classic.d.ts

@@ -0,0 +1,21 @@
+import type { Event } from "./types.js";
+import type { CompileMetrics } from "./compiler.js";
+export interface ClassicCompileInput {
+    cwd: string;
+    sessionId: string;
+    toolSchemas: string[];
+    agentsContext?: string | null;
+    projectContext?: string | null;
+    skillsCatalog?: string | null;
+    memoryDigest?: string | null;
+    events: Event[];
+    userInput?: string;
+}
+export declare function buildClassicSystemFrame(cwd: string, sessionId: string, toolSchemas: string[], agentsContext?: string | null, projectContext?: string | null): string;
+/** Drop the trailing user_message when it duplicates the current turn input. */
+export declare function excludeCurrentUserInputFromEvents(events: Event[], userInput?: string): Event[];
+export declare function buildFullConversationHistory(events: Event[]): string;
+export declare function compileClassicWithMetrics(input: ClassicCompileInput): {
+    prompt: string;
+    metrics: CompileMetrics;
+};

package/dist/compile-classic.js

@@ -0,0 +1,106 @@
+import { buildCrossSessionMemory } from "./compiler.js";
+function estTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+export function buildClassicSystemFrame(cwd, sessionId, toolSchemas, agentsContext, projectContext) {
+    const lines = [
+        "# System",
+        "",
+        "You are PRAANA, a coding agent with persistent memory.",
+        `Working directory: ${cwd}`,
+        `Session ID: ${sessionId}`,
+    ];
+    if (agentsContext?.trim()) {
+        lines.push("", "## Project Context", "", agentsContext.trim());
+    }
+    if (projectContext?.trim()) {
+        lines.push("", "## Project Stack", "", projectContext.trim());
+    }
+    lines.push("", "## Available Tools", "", ...toolSchemas.map((t) => `- ${t}`), "", "Use tools when needed to accomplish the user's request. Respond concisely.", "", "## Skills", "", "Skills are listed below by name and path. Use read_file on a SKILL.md path when a skill is relevant.", "", "## Memory", "", "Use recall() for cross-session memory. Use search_session_log() to search this session's event log.", "Session event log file: ~/.praana/sessions/<session_id>/events.jsonl", "", "## Tool Safety", "", "RULE: Never call write_file, edit_file, or use shell commands with file write side-effects (e.g. `echo > file`, `sed -i`, `tee`) unless the user's message in THIS turn explicitly requests changes. Describing what you would change does not count. If unsure, ask first.");
+    return lines.join("\n");
+}
+/** Drop the trailing user_message when it duplicates the current turn input. */
+export function excludeCurrentUserInputFromEvents(events, userInput) {
+    if (!userInput?.trim() || events.length === 0)
+        return events;
+    const last = events[events.length - 1];
+    if (last.kind === "user_message" &&
+        last.payload.text === userInput) {
+        return events.slice(0, -1);
+    }
+    return events;
+}
+export function buildFullConversationHistory(events) {
+    if (events.length === 0) {
+        return "# Conversation History\n\n(no prior turns)";
+    }
+    const lines = ["# Conversation History"];
+    const filtered = events.filter((event) => event.kind !== "context_action" && event.kind !== "system_note");
+    let lastToolName;
+    for (const event of filtered) {
+        switch (event.kind) {
+            case "user_message":
+                lines.push(`User: ${event.payload.text ?? ""}`);
+                break;
+            case "agent_message":
+                lines.push(`PRAANA: ${event.payload.text ?? ""}`);
+                break;
+            case "tool_call":
+                lastToolName = event.payload.tool;
+                lines.push(`Tool call: ${lastToolName ?? "unknown"}(${JSON.stringify(event.payload.args ?? {})})`);
+                break;
+            case "tool_result": {
+                const result = event.payload.result;
+                const resultStr = typeof result === "string" ? result : JSON.stringify(result ?? null);
+                const toolName = event.payload.tool ?? lastToolName ?? "unknown";
+                lines.push(`Result (${toolName}): ${resultStr}`);
+                break;
+            }
+        }
+    }
+    return lines.join("\n");
+}
+export function compileClassicWithMetrics(input) {
+    const sections = [];
+    const frame = buildClassicSystemFrame(input.cwd, input.sessionId, input.toolSchemas, input.agentsContext, input.projectContext);
+    sections.push(frame);
+    let skillsSection = "";
+    if (input.skillsCatalog?.trim()) {
+        skillsSection = input.skillsCatalog.trim();
+        sections.push(skillsSection);
+    }
+    let crossSection = "";
+    if (input.memoryDigest?.trim()) {
+        crossSection = buildCrossSessionMemory(input.memoryDigest);
+        sections.push(crossSection);
+    }
+    const history = buildFullConversationHistory(excludeCurrentUserInputFromEvents(input.events, input.userInput));
+    sections.push(history);
+    let currentSection = "";
+    if (input.userInput) {
+        currentSection = `## Current Input\n\nUser: ${input.userInput}`;
+        sections.push(currentSection);
+    }
+    const fullPrompt = sections.join("\n\n");
+    return {
+        prompt: fullPrompt,
+        metrics: {
+            totalTokens: estTokens(fullPrompt),
+            systemFrameTokens: estTokens(frame),
+            agentsContextTokens: input.agentsContext ? estTokens(input.agentsContext) : 0,
+            skillsCatalogTokens: skillsSection ? estTokens(skillsSection) : 0,
+            checkpointTokens: 0,
+            crossSessionTokens: crossSection ? estTokens(crossSection) : 0,
+            activeStateTokens: 0,
+            peripheralStubsTokens: 0,
+            recentTurnsTokens: estTokens(history),
+            currentInputTokens: estTokens(currentSection),
+            activeObjectCount: 0,
+            peripheralObjectCount: 0,
+            recentTurnsTruncated: false,
+            memoryTruncated: false,
+            agentsContextTruncated: false,
+            skillsTruncated: false,
+        },
+    };
+}

package/dist/compiler.d.ts

@@ -0,0 +1,75 @@
+import type { Event } from "./types.js";
+import type { StateGraph } from "./state-graph.js";
+export interface CompileInput {
+    stateGraph: StateGraph;
+    memoryDigest: string | null;
+    recentEvents: Event[];
+    userInput?: string;
+    toolSchemas: string[];
+    cwd: string;
+    sessionId: string;
+    tokenBudget: number;
+    recentTurnsTokenBudget?: number;
+    agentsContext?: string | null;
+    skillsPromptSection?: string | null;
+    checkpointSection?: string | null;
+    memoriesBudgetRatio?: number;
+    agentsBudgetRatio?: number;
+    skillsSectionBudgetRatio?: number;
+    reservedOutputTokens?: number;
+}
+/** Token-estimate metrics per section, emitted for eval / observability. */
+export interface CompileMetrics {
+    totalTokens: number;
+    systemFrameTokens: number;
+    agentsContextTokens: number;
+    skillsCatalogTokens: number;
+    checkpointTokens: number;
+    crossSessionTokens: number;
+    activeStateTokens: number;
+    peripheralStubsTokens: number;
+    recentTurnsTokens: number;
+    currentInputTokens: number;
+    activeObjectCount: number;
+    peripheralObjectCount: number;
+    /** If true, some recent turns were truncated due to budget. */
+    recentTurnsTruncated: boolean;
+    /** If true, cross-session memory was trimmed to section ceiling. */
+    memoryTruncated: boolean;
+    /** If true, project context was degraded to fit agents budget. */
+    agentsContextTruncated: boolean;
+    /** If true, skills section was trimmed to section ceiling. */
+    skillsTruncated: boolean;
+}
+/** Build a deterministic prompt from structured state. */
+export declare function compile(input: CompileInput): string;
+/** Compile with detailed token metrics per section. */
+export declare function compileWithMetrics(input: CompileInput): {
+    prompt: string;
+    metrics: CompileMetrics;
+};
+export declare function buildSystemFrame(cwd: string, sessionId: string, toolSchemas: string[], stateSummary?: string, agentsContext?: string | null): string;
+export declare function buildCrossSessionMemory(digest: string): string;
+export declare function buildActiveState(stateGraph: StateGraph): string;
+export declare function buildPeripheralStubs(stateGraph: StateGraph): string | null;
+/**
+ * Calculate token savings: compare compact peripheral stubs vs.
+ * rendering the same objects in full active form.
+ * Returns { compactTokens, fullTokens, savedTokens, savingsRatio }.
+ */
+export declare function calculateTokenSavings(stateGraph: StateGraph): {
+    compactTokens: number;
+    fullTokens: number;
+    savedTokens: number;
+    savingsRatio: number;
+};
+/** Build a brief summary of working memory state for the system prompt */
+export declare function buildStateSummary(stateGraph: StateGraph): string;
+export declare function trimSectionToTokenBudget(text: string, maxTokens: number, truncationNote?: string): {
+    text: string;
+    truncated: boolean;
+};
+export declare function trimAgentsContext(agentsContext: string | null | undefined, maxTokens: number): {
+    text: string | null;
+    truncated: boolean;
+};