praana 0.5.0

package/dist/skills/types.d.ts

@@ -0,0 +1,93 @@
+export type SkillResidency = "hot" | "warm" | "cold";
+export type SkillSection = "planner" | "execution" | "recovery" | "examples";
+export declare const ALL_SKILL_SECTIONS: SkillSection[];
+export declare const SECTION_HEADINGS: Record<SkillSection, string>;
+export interface SkillMetadata {
+    name: string;
+    description: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, string>;
+    allowedTools?: string;
+}
+export interface SkillRecord {
+    name: string;
+    description: string;
+    location: string;
+    directory: string;
+    body: string;
+    metadata: SkillMetadata;
+}
+export interface SkillSectionMapping {
+    planner?: string[];
+    execution?: string[];
+    recovery?: string[];
+    examples?: string[];
+}
+export interface SkillBudgetConfig {
+    priority?: "normal" | "high" | "low";
+    max_tokens?: number;
+}
+export interface SkillAriaMeta {
+    tags?: string[];
+    trigger?: string;
+    synonyms?: string[];
+    neighbors?: string[];
+    sections?: SkillSectionMapping;
+    budget?: SkillBudgetConfig;
+}
+export type SkillsMetaFile = Record<string, SkillAriaMeta>;
+export interface SkillIndexEntry {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    trigger?: string;
+    synonyms?: string[];
+    neighbors?: string[];
+    /** Tokenized searchable text for BM25 */
+    searchText: string;
+    /** Parsed section boundaries from SKILL.md body */
+    sectionRanges?: Record<SkillSection, {
+        start: number;
+        end: number;
+    }>;
+    budgetPriority: "normal" | "high" | "low";
+    maxTokens: number;
+}
+export interface SkillRuntimeState {
+    entry: SkillIndexEntry;
+    residency: SkillResidency;
+    loadedSections: SkillSection[];
+    lastActiveTurn: number;
+    tokenCost: number;
+    /** Full body text cached from discovery */
+    body: string;
+    /** Directory path for resolving relative references */
+    directory: string;
+}
+export interface SkillRuntimeSnapshot {
+    hot: SkillRuntimeState[];
+    warm: SkillRuntimeState[];
+    tokenUsage: number;
+    tokenBudget: number;
+}
+export interface SkillsRuntimeConfig {
+    enabled: boolean;
+    max_token_budget_ratio: number;
+    active_skill_idle_turns: number;
+    warm_skill_eviction_turns: number;
+    max_depth: number;
+    /** Override search paths for discovery (testing only). */
+    searchPaths?: string[];
+}
+export interface SkillTelemetryEvent {
+    type: "skill_discovered" | "skill_matched" | "skill_loaded" | "skill_promoted" | "skill_demoted" | "skill_evicted" | "skill_hydrated" | "skill_budget_exceeded" | "skill_neighbor_boosted";
+    skill_id: string;
+    residency?: SkillResidency;
+    sections?: string[];
+    token_cost?: number;
+    score?: number;
+    prev_residency?: SkillResidency;
+    timestamp: number;
+}

package/dist/skills/types.js

@@ -0,0 +1,8 @@
+// ---- Residency ----
+export const ALL_SKILL_SECTIONS = ["planner", "execution", "recovery", "examples"];
+export const SECTION_HEADINGS = {
+    planner: "## Planner",
+    execution: "## Execution",
+    recovery: "## Recovery",
+    examples: "## Examples",
+};

package/dist/slash-commands.d.ts

@@ -0,0 +1,14 @@
+import type { Session } from "./session.js";
+export type SlashCommandAction = "none" | "exit" | "refresh_status";
+/** toast = ephemeral feedback below input; transcript = scrollback (default). */
+export type SlashCommandDisplay = "transcript" | "toast";
+export interface SlashCommandResult {
+    action: SlashCommandAction;
+    lines: string[];
+    display?: SlashCommandDisplay;
+}
+export declare function executeSlashCommand(input: string, session: Session, handlers: {
+    setModel: (m?: string) => void;
+    setThinking: (v: boolean) => void;
+    getThinking: () => boolean;
+}): Promise<SlashCommandResult>;

package/dist/slash-commands.js

@@ -0,0 +1,301 @@
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { EVENT_LOG_FILENAME, migrateLegacyEventLog } from "./event-log.js";
+import { getHelpLines as bannerHelpLines } from "./app-banner.js";
+import { explainUnitScore } from "./context-engine/engine-compiler.js";
+import { resolveContextEngineConfig } from "./context-engine/index.js";
+export async function executeSlashCommand(input, session, handlers) {
+    const parts = input.split(/\s+/);
+    const cmd = parts[0].toLowerCase();
+    const lines = [];
+    const result = (action = "none", display = "transcript") => ({
+        action,
+        lines,
+        display,
+    });
+    switch (cmd) {
+        case "/exit":
+        case "/quit": {
+            lines.push("Ending session...");
+            return result("exit", "toast");
+        }
+        case "/state": {
+            const objects = session.stateGraph.list();
+            if (objects.length === 0) {
+                lines.push("No state objects yet this session. Use remember() or create_task() to start tracking.");
+            }
+            else {
+                lines.push(`State objects (${objects.length}):`);
+                for (const o of objects) {
+                    const tierIcon = o.tier === "active" ? "●" : o.tier === "soft" ? "○" : "·";
+                    lines.push(`  ${tierIcon} ${o.id} [${o.kind}] ${o.tier}: ${o.summary}`);
+                }
+            }
+            break;
+        }
+        case "/stats": {
+            const stats = session.getMemoryStats();
+            const startedAt = new Date(session.getStartedAt()).toISOString();
+            const uptimeSec = Math.floor(session.getUptimeMs() / 1000);
+            const persistentCount = session.getPersistentMemoryEntryCount();
+            lines.push("", "Session:");
+            lines.push(`  Session ID: ${session.id}`);
+            lines.push(`  Turns: ${session.getTurnCount()}`);
+            lines.push(`  Started at: ${startedAt}`);
+            lines.push(`  Uptime: ${uptimeSec}s`);
+            const inTokens = session.getInputTokens();
+            const outTokens = session.getOutputTokens();
+            if (inTokens > 0 || outTokens > 0) {
+                lines.push(`  Tokens (this boot): ${inTokens.toLocaleString()} in / ${outTokens.toLocaleString()} out`);
+            }
+            lines.push("", "Working memory (this session):");
+            lines.push(`  Total: ${stats.total}`);
+            lines.push(`  Active: ${stats.active}`);
+            lines.push(`  Soft: ${stats.soft}`);
+            lines.push(`  Hard: ${stats.hard}`);
+            const kindParts = Object.entries(stats.byKind)
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([kind, count]) => `${kind}:${count}`);
+            lines.push(`  By kind: ${kindParts.length ? kindParts.join(", ") : "(none)"}`);
+            if (session.memoryEnabled) {
+                lines.push("", "Persistent memory (SQLite):");
+                lines.push(`  Total memories: ${persistentCount ?? "(unavailable)"}`);
+                lines.push(`  Memory DB: ${session.getMemoryDbPath() ?? "(unknown)"}`);
+            }
+            if (session.isContextEngineEnabled() && session.contextEngine) {
+                const telemetry = session.contextEngine.finalizeTelemetry(session.getTurnCount());
+                lines.push("", "Context engine telemetry:");
+                lines.push(`  Artifacts: ${telemetry.artifactsProduced}`);
+                lines.push(`  Retrievals: ${telemetry.stats.artifactRetrievals} (${(telemetry.retrievalRate * 100).toFixed(1)}%)`);
+                lines.push(`  Distiller savings: ${Math.round(telemetry.stats.totalDistillerSavings)} tokens`);
+                lines.push(`  Pressure events: ${telemetry.stats.pressureEvents}`);
+                lines.push(`  Compaction triggers: ${telemetry.stats.compactionTriggers}`);
+            }
+            break;
+        }
+        case "/digest": {
+            if (session.digest) {
+                lines.push("", session.digest);
+            }
+            else {
+                lines.push("No digest available.");
+            }
+            break;
+        }
+        case "/events": {
+            const events = session.eventLog.readLast(20);
+            if (events.length === 0) {
+                lines.push("No events yet.");
+            }
+            else {
+                lines.push(``, `Last ${events.length} events:`);
+                for (const ev of events) {
+                    const time = new Date(ev.timestamp).toISOString().slice(11, 19);
+                    const summary = ev.kind === "user_message"
+                        ? `User: ${ev.payload.text?.slice(0, 60)}`
+                        : ev.kind === "agent_message"
+                            ? `Agent: ${ev.payload.text?.slice(0, 60)}`
+                            : ev.kind === "tool_call"
+                                ? `Tool: ${ev.payload.tool ?? "?"}`
+                                : ev.kind === "tool_result"
+                                    ? `Result: ${JSON.stringify(ev.payload.result)?.slice(0, 60)}`
+                                    : ev.kind === "context_action"
+                                        ? `Context: ${ev.payload.action}`
+                                        : ev.kind === "system_note" &&
+                                            ev.payload.type === "error"
+                                            ? `Error: ${String(ev.payload.message).slice(0, 60)}`
+                                            : ev.kind;
+                    lines.push(`  ${time} ${ev.kind.padEnd(16)} ${summary}`);
+                }
+            }
+            break;
+        }
+        case "/recall": {
+            const query = parts.slice(1).join(" ");
+            if (!query || !session.memoryEnabled || !session.memoryStore) {
+                lines.push("Usage: /recall <query> (requires memory enabled)");
+                break;
+            }
+            try {
+                const recallResult = await session.memoryStore.recall(query, { limit: 20 });
+                if (recallResult.entries.length === 0) {
+                    lines.push("No results found.");
+                }
+                else {
+                    lines.push(``, `Recall results for "${query}":`);
+                    for (const e of recallResult.entries) {
+                        lines.push(`  - [${e.kind}] ${e.content.slice(0, 100)} (match: ${e.match.toFixed(2)} | conf: ${e.confidence.toFixed(2)})`);
+                    }
+                }
+            }
+            catch (err) {
+                lines.push(`Recall error: ${err.message}`);
+            }
+            break;
+        }
+        case "/sessions": {
+            const logDir = session.config.session.log_dir;
+            if (!existsSync(logDir)) {
+                lines.push("No sessions directory found.");
+                break;
+            }
+            const dirs = readdirSync(logDir, { withFileTypes: true })
+                .filter((d) => d.isDirectory())
+                .sort((a, b) => b.name.localeCompare(a.name))
+                .slice(0, 15);
+            if (dirs.length === 0) {
+                lines.push("No sessions found.");
+                break;
+            }
+            lines.push("", "Recent sessions:");
+            for (const d of dirs) {
+                const sessionDir = join(logDir, d.name);
+                migrateLegacyEventLog(sessionDir);
+                const eventsPath = join(sessionDir, EVENT_LOG_FILENAME);
+                const metaPath = join(logDir, d.name, "meta.json");
+                let events = 0;
+                let cwdLabel = "?";
+                let time = "?";
+                try {
+                    const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+                    cwdLabel = meta.cwd?.split("/").pop() ?? meta.cwd ?? "?";
+                    time = new Date(meta.started_at).toISOString().slice(0, 16).replace("T", " ");
+                }
+                catch {
+                    /* ignore */
+                }
+                try {
+                    const content = readFileSync(eventsPath, "utf-8");
+                    events = content.split("\n").filter(Boolean).length;
+                }
+                catch {
+                    /* ignore */
+                }
+                const marker = d.name === session.id ? " ← current" : "";
+                lines.push(`  ${time}  ${d.name.slice(0, 12)}...  ${String(events).padStart(4)} events  ${cwdLabel}${marker}`);
+            }
+            lines.push("", "Resume with: aria resume <session-id>");
+            break;
+        }
+        case "/model": {
+            const model = parts[1];
+            if (!model) {
+                lines.push(`Current model: ${session.getModelOverride() ?? session.config.llm.model}`);
+                lines.push("Usage: /model <provider/model> (e.g., /model openai/gpt-4o)");
+                break;
+            }
+            const trimmed = model.trim();
+            handlers.setModel(trimmed);
+            session.setModelOverride(trimmed);
+            const contextWindow = await session.refreshModelContextWindow(trimmed);
+            session.eventLog.append({
+                kind: "system_note",
+                actor: "kernel",
+                payload: {
+                    type: "model_override",
+                    model: trimmed,
+                },
+            });
+            lines.push(`Model switched to: ${model} (${contextWindow.toLocaleString()} ctx)`);
+            return result("refresh_status", "toast");
+        }
+        case "/debug": {
+            session.debug = !session.debug;
+            lines.push(`Debug mode: ${session.debug ? "ON" : "OFF"}` +
+                ` (prompts saved to ${session.promptDir}` +
+                `${session.isContextEngineEnabled() ? ", scores to scores.jsonl" : ""})`);
+            return result("refresh_status", "toast");
+        }
+        case "/thinking": {
+            const arg = (parts[1] ?? "").toLowerCase();
+            if (!arg) {
+                lines.push(`Thinking: ${handlers.getThinking() ? "ON" : "OFF"}`);
+                lines.push("Usage: /thinking <on|off>");
+                break;
+            }
+            if (arg === "on") {
+                handlers.setThinking(true);
+                lines.push("Thinking enabled.");
+            }
+            else if (arg === "off") {
+                handlers.setThinking(false);
+                lines.push("Thinking disabled.");
+            }
+            else {
+                lines.push("Usage: /thinking <on|off>");
+            }
+            return result("refresh_status", "toast");
+        }
+        case "/incognito": {
+            const arg = (parts[1] ?? "").toLowerCase();
+            if (!arg) {
+                lines.push(`Incognito: ${session.isIncognito() ? "ON" : "OFF"}`);
+                lines.push("Usage: /incognito <on|off>");
+                return result("none", "toast");
+            }
+            if (arg === "on") {
+                await session.setIncognito(true);
+                lines.push("Incognito enabled — cross-session memory disabled.");
+            }
+            else if (arg === "off") {
+                await session.setIncognito(false);
+                lines.push(session.memoryEnabled
+                    ? "Incognito disabled — cross-session memory enabled."
+                    : "Incognito disabled — memory remains unavailable (check config.memory.enabled).");
+            }
+            else {
+                lines.push("Usage: /incognito <on|off>");
+                break;
+            }
+            return result("refresh_status", "toast");
+        }
+        case "/clear":
+        case "/new": {
+            session.clearState();
+            session.eventLog.append({
+                kind: "system_note",
+                actor: "kernel",
+                payload: {
+                    type: "state_reset",
+                    cleared: "all",
+                    command: cmd,
+                },
+            });
+            lines.push("State cleared. Starting fresh.");
+            return result("none", "toast");
+        }
+        case "/why": {
+            const unitId = parts.slice(1).join(" ").trim();
+            if (!unitId) {
+                lines.push("Usage: /why <unit-id> (e.g. /why art_abc123 or /why turn_3)");
+                break;
+            }
+            if (!session.isContextEngineEnabled()) {
+                lines.push("Context engine is disabled. Enable it to use /why.");
+                break;
+            }
+            const record = session.getCompileScoreRecord(unitId);
+            if (!record) {
+                lines.push(`No score record for "${unitId}" on the last compile.`);
+                lines.push("Run a turn with context_engine.enabled=true and debug mode for scores.jsonl.");
+                break;
+            }
+            const engineConfig = resolveContextEngineConfig(session.config);
+            const bandBudget = record.band <= 4 ? 3000 : 2000;
+            const bandUsed = session
+                .getLastCompileScoreRecords()
+                .filter((r) => r.band === record.band && r.included)
+                .reduce((sum, r) => sum + r.tokens, 0);
+            lines.push(...explainUnitScore(unitId, session.getLastCompileScoreRecords(), session.getTurnCount(), session.getLastUserInput(), engineConfig.scoring, bandBudget, bandUsed));
+            lines.push(`Pressure: ${(session.getLastPressureRatio() * 100).toFixed(1)}% (${session.getLastPressureMode()})`);
+            break;
+        }
+        case "/help": {
+            return { action: "none", lines: bannerHelpLines() };
+        }
+        default:
+            lines.push(`Unknown command: ${cmd}. Type /help for available commands.`);
+            return result("none", "toast");
+    }
+    return result();
+}

package/dist/state-graph.d.ts

@@ -0,0 +1,38 @@
+import type { StateObject, StateObjectKind, StateTier, StatePayload } from "./types.js";
+export declare class StateGraph {
+    private objects;
+    private touchedTurn;
+    private turnCount;
+    clear(): void;
+    create(kind: StateObjectKind, payload: StatePayload): StateObject;
+    update(id: string, patch: Partial<StatePayload>): StateObject | null;
+    setTier(id: string, tier: StateTier): boolean;
+    retractObject(id: string): boolean;
+    get(id: string): StateObject | undefined;
+    /** All active objects; focused object first, then by created asc, id asc. */
+    getActive(): StateObject[];
+    /** Pin one task/object as focused; clears focus on all others. */
+    setFocus(id: string): boolean;
+    /** All soft + hard objects, sorted by updated desc. */
+    getPeripheral(): StateObject[];
+    /** All objects with summary. */
+    list(): Array<{
+        id: string;
+        kind: StateObjectKind;
+        tier: StateTier;
+        summary: string;
+    }>;
+    /** Full snapshot including retracted objects — for event logging and audit. */
+    snapshot(): StateObject[];
+    getTouchedTurn(id: string): number;
+    incrementTurn(): void;
+    getTurnCount(): number;
+    /**
+     * Auto-promote peripheral objects whose payload matches keywords in the query.
+     * Returns IDs of objects that were hydrated.
+     */
+    autoHydrate(query: string): string[];
+    /** Rebuild state from context_action events during resume. */
+    replayAction(payload: Record<string, unknown>): void;
+}
+export declare function summarizePayloadFn(obj: StateObject): string;