praana 0.5.0

package/dist/memory/summarizer.d.ts

@@ -0,0 +1,4 @@
+import type { ExtractedLearning, SessionEvent, SummarizerLLM } from "./types.js";
+export declare function extractLearnings(llm: SummarizerLLM, events: SessionEvent[]): Promise<ExtractedLearning[]>;
+/** Summarize a batch of old turns into episodic memories for history compression. */
+export declare function summarizeTurns(llm: SummarizerLLM, events: SessionEvent[]): Promise<ExtractedLearning[]>;

package/dist/memory/summarizer.js

@@ -0,0 +1,112 @@
+// ============================================================
+// ARIA Memory — Summarizer
+//
+// One LLM call per session end: "what did we learn?"
+// No extract→consolidate→gate pipeline. Just ask.
+// ============================================================
+import { isMemoryKind } from "./types.js";
+const SYSTEM_PROMPT = `You are a memory extractor for a coding agent.
+Given a session transcript, extract 0-5 concise learnings.
+Output ONLY a JSON array. No prose outside the array.
+
+Each entry: { "kind": "fact" | "preference" | "decision" | "pattern" | "mistake" | "constraint", "content": "...", "certainty": "high" | "medium" | "low" }
+
+Rules:
+- "fact": verifiable project knowledge ("uses Vitest for testing")
+- "preference": user or agent preference ("prefers dark mode UI")
+- "decision": architectural choice ("chose JWT over session cookies")
+- "pattern": recurring approach ("validates with Zod before DB writes")
+- "mistake": failure + lesson learned ("forgot await on verify() → 401s")
+- "constraint": hard rule ("never commits .env files")
+- Be conservative. Skip vague or low-signal items.
+- Content should be one sentence, max 120 characters.
+- certainty reflects how strongly the transcript supports this.`;
+function transcriptToPrompt(events) {
+    const lines = ["Session transcript:"];
+    for (const e of events) {
+        if (e.type === "user_message")
+            lines.push(`User: ${e.content}`);
+        else if (e.type === "agent_message")
+            lines.push(`Agent: ${e.content}`);
+        else if (e.type === "tool_use")
+            lines.push(`[tool] ${e.tool_name}(${JSON.stringify(e.args ?? {})})`);
+        else if (e.type === "tool_result")
+            lines.push(`[result] ${JSON.stringify(e.result).slice(0, 200)}`);
+    }
+    return lines.join("\n");
+}
+export async function extractLearnings(llm, events) {
+    if (events.length === 0)
+        return [];
+    if (!(await llm.available()))
+        return [];
+    const raw = await llm.complete({
+        system: SYSTEM_PROMPT,
+        prompt: transcriptToPrompt(events),
+        temperature: 0.3,
+        maxTokens: 1500,
+        json: true,
+        timeoutMs: 30_000,
+    });
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed
+            .filter((p) => isMemoryKind(p.kind))
+            .map((p) => ({
+            kind: p.kind,
+            content: p.content.slice(0, 200),
+            certainty: (p.certainty === "high" || p.certainty === "medium" || p.certainty === "low")
+                ? p.certainty
+                : "medium",
+            scope_hints: p.scope_hints,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+const TURN_COMPRESSION_PROMPT = `You are a memory compressor for a coding agent.
+Given a batch of old conversation turns, extract 1-5 concise episodic facts.
+Output ONLY a JSON array. No prose outside the array.
+
+Each entry: { "kind": "fact" | "pattern" | "decision", "content": "...", "certainty": "high" | "medium" | "low" }
+
+Rules:
+- Focus on verifiable facts, patterns, and decisions — not activity logs.
+- Content should be one sentence, max 120 characters.
+- Be conservative. Skip vague or low-signal items.
+- These memories will replace the raw turns in the agent's context.`;
+/** Summarize a batch of old turns into episodic memories for history compression. */
+export async function summarizeTurns(llm, events) {
+    if (events.length === 0)
+        return [];
+    if (!(await llm.available()))
+        return [];
+    const raw = await llm.complete({
+        system: TURN_COMPRESSION_PROMPT,
+        prompt: transcriptToPrompt(events),
+        temperature: 0.3,
+        maxTokens: 1000,
+        json: true,
+        timeoutMs: 30_000,
+    });
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed
+            .filter((p) => isMemoryKind(p.kind))
+            .map((p) => ({
+            kind: p.kind,
+            content: p.content.slice(0, 200),
+            certainty: (p.certainty === "high" || p.certainty === "medium" || p.certainty === "low")
+                ? p.certainty
+                : "medium",
+        }));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/memory/types.d.ts

@@ -0,0 +1,87 @@
+export declare const MEMORY_KINDS: readonly ["fact", "preference", "decision", "pattern", "mistake", "constraint"];
+export type MemoryKind = "fact" | "preference" | "decision" | "pattern" | "mistake" | "constraint";
+export declare function isMemoryKind(value: string): value is MemoryKind;
+export type Certainty = "high" | "medium" | "low";
+export type MemoryLayer = 1 | 2;
+export interface MemoryEntry {
+    id: string;
+    kind: MemoryKind;
+    content: string;
+    confidence: number;
+    pinned: boolean;
+    layer: MemoryLayer;
+    confirmation_count: number;
+    created_at: number;
+    last_seen_at: number;
+    session_id: string;
+    scopes: string[];
+    retracted: boolean;
+    embedding?: Buffer;
+}
+export interface SessionContext {
+    agent: string;
+    user_id: string;
+    time: number;
+    context_id: string;
+    context_label: string;
+    working_context?: Record<string, unknown>;
+    recall_min_score?: number;
+}
+export interface Digest {
+    markdown: string;
+    empty: boolean;
+    entriesIncluded: string[];
+}
+export interface RecallOptions {
+    limit?: number;
+    scope?: string[];
+    mode?: "standard" | "causal_chain";
+    kinds?: MemoryKind[];
+}
+export interface RecallResult {
+    entries: Array<{
+        id: string;
+        kind: MemoryKind;
+        content: string;
+        confidence: number;
+        match: number;
+        scopes: string[];
+        score: number;
+    }>;
+}
+export interface RememberOptions {
+    kind?: MemoryKind;
+    certainty?: Certainty;
+    pinned?: boolean;
+    scope?: string[];
+}
+export interface Embedder {
+    dim: number;
+    embed(text: string): Promise<Float32Array>;
+}
+export interface SummarizerLLM {
+    name: string;
+    available(): Promise<boolean>;
+    complete(opts: {
+        system?: string;
+        prompt: string;
+        temperature?: number;
+        maxTokens?: number;
+        json?: boolean;
+        timeoutMs?: number;
+    }): Promise<string>;
+}
+export interface SessionEvent {
+    type: "user_message" | "agent_message" | "tool_use" | "tool_result";
+    timestamp: number;
+    content?: string;
+    tool_name?: string;
+    args?: Record<string, unknown>;
+    result?: unknown;
+}
+export interface ExtractedLearning {
+    kind: MemoryKind;
+    content: string;
+    certainty: Certainty;
+    scope_hints?: string[];
+}

package/dist/memory/types.js

@@ -0,0 +1,17 @@
+// ============================================================
+// ARIA Memory — Core Types
+//
+// A simplified, purpose-built cross-session memory layer.
+// Replaces bodha dependency with ~600 lines of focused code.
+// ============================================================
+export const MEMORY_KINDS = [
+    "fact",
+    "preference",
+    "decision",
+    "pattern",
+    "mistake",
+    "constraint",
+];
+export function isMemoryKind(value) {
+    return MEMORY_KINDS.includes(value);
+}

package/dist/model-context.d.ts

@@ -0,0 +1,15 @@
+export declare const DEFAULT_MODEL_CONTEXT_WINDOW = 128000;
+export declare function mapAriaProviderToPiAi(provider: string): string | null;
+export declare function lookupPiAiContextWindow(provider: string, modelId: string): number | null;
+/**
+ * Synchronous best-effort resolution: override → cache → pi-ai catalog → default.
+ */
+export declare function resolveContextWindowSync(provider: string, modelId: string, override?: number): number;
+/**
+ * Fetch and cache context window for a model. Never throws — falls back to sync resolution.
+ */
+export declare function fetchAndCacheContextWindow(provider: string, modelId: string, override?: number): Promise<number>;
+/** @deprecated Use resolveContextWindowSync with provider, or session.getContextWindowTokens(). */
+export declare function resolveContextWindow(modelId: string, override?: number): number;
+/** Test helper — reset in-memory/disk cache state. */
+export declare function resetModelContextCacheForTests(): void;

package/dist/model-context.js

@@ -0,0 +1,212 @@
+import { getModel, getProviders } from "@earendil-works/pi-ai";
+import { dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolveAppHomePath } from "./app-identity.js";
+export const DEFAULT_MODEL_CONTEXT_WINDOW = 128_000;
+const CACHE_VERSION = 1;
+const OPENROUTER_CATALOG_TTL_MS = 6 * 60 * 60 * 1000;
+const CACHE_FILE = resolveAppHomePath("model-context-cache.json");
+/** PRAANA config provider → pi-ai MODELS registry key (when available). */
+const PI_AI_PROVIDER_MAP = {
+    openrouter: "openrouter",
+    openai: "openai",
+    anthropic: "anthropic",
+    google: "google",
+    deepseek: "deepseek",
+    groq: "groq",
+    xai: "xai",
+    fireworks: "fireworks",
+    together: "together",
+    mistral: "mistral",
+    "amazon-bedrock": "amazon-bedrock",
+};
+const memoryEntries = new Map();
+let diskCache = null;
+let openRouterFetchPromise = null;
+function cacheKey(provider, modelId) {
+    return `${provider}:${modelId}`;
+}
+function isValidWindow(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 1000;
+}
+function applyOverride(override) {
+    if (override !== undefined && isValidWindow(override))
+        return override;
+    return null;
+}
+function loadDiskCache() {
+    if (diskCache)
+        return diskCache;
+    diskCache = { version: CACHE_VERSION, entries: {} };
+    if (!existsSync(CACHE_FILE))
+        return diskCache;
+    try {
+        const raw = JSON.parse(readFileSync(CACHE_FILE, "utf-8"));
+        if (raw.version === CACHE_VERSION && raw.entries && typeof raw.entries === "object") {
+            diskCache = raw;
+        }
+    }
+    catch {
+        diskCache = { version: CACHE_VERSION, entries: {} };
+    }
+    return diskCache;
+}
+function persistDiskCache() {
+    const dir = dirname(CACHE_FILE);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(CACHE_FILE, JSON.stringify(loadDiskCache(), null, 2), "utf-8");
+}
+function rememberContextWindow(provider, modelId, contextWindow) {
+    const key = cacheKey(provider, modelId);
+    memoryEntries.set(key, contextWindow);
+    const file = loadDiskCache();
+    file.entries[key] = { contextWindow, fetchedAt: Date.now() };
+    persistDiskCache();
+}
+export function mapAriaProviderToPiAi(provider) {
+    const mapped = PI_AI_PROVIDER_MAP[provider];
+    if (mapped)
+        return mapped;
+    const known = getProviders();
+    return known.includes(provider) ? provider : null;
+}
+export function lookupPiAiContextWindow(provider, modelId) {
+    const piProvider = mapAriaProviderToPiAi(provider);
+    if (!piProvider)
+        return null;
+    const model = getModel(piProvider, modelId);
+    return isValidWindow(model?.contextWindow) ? model.contextWindow : null;
+}
+function readCachedContextWindow(provider, modelId) {
+    const key = cacheKey(provider, modelId);
+    const mem = memoryEntries.get(key);
+    if (isValidWindow(mem))
+        return mem;
+    const entry = loadDiskCache().entries[key];
+    if (entry && isValidWindow(entry.contextWindow)) {
+        memoryEntries.set(key, entry.contextWindow);
+        return entry.contextWindow;
+    }
+    return null;
+}
+function readOpenRouterCatalogEntry(modelId) {
+    const catalog = loadDiskCache().openRouterCatalog;
+    if (!catalog)
+        return null;
+    if (Date.now() - catalog.fetchedAt > OPENROUTER_CATALOG_TTL_MS)
+        return null;
+    const value = catalog.models[modelId];
+    return isValidWindow(value) ? value : null;
+}
+async function fetchOpenRouterCatalog() {
+    const file = loadDiskCache();
+    const existing = file.openRouterCatalog;
+    if (existing &&
+        Date.now() - existing.fetchedAt <= OPENROUTER_CATALOG_TTL_MS &&
+        Object.keys(existing.models).length > 0) {
+        return existing.models;
+    }
+    if (openRouterFetchPromise)
+        return openRouterFetchPromise;
+    openRouterFetchPromise = (async () => {
+        const headers = { Accept: "application/json" };
+        const apiKey = process.env.OPENROUTER_API_KEY;
+        if (apiKey)
+            headers.Authorization = `Bearer ${apiKey}`;
+        const response = await fetch("https://openrouter.ai/api/v1/models", { headers });
+        if (!response.ok) {
+            throw new Error(`OpenRouter models API returned ${response.status}`);
+        }
+        const body = (await response.json());
+        const models = {};
+        for (const item of body.data ?? []) {
+            if (item.id && isValidWindow(item.context_length)) {
+                models[item.id] = item.context_length;
+            }
+        }
+        file.openRouterCatalog = { fetchedAt: Date.now(), models };
+        persistDiskCache();
+        return models;
+    })().finally(() => {
+        openRouterFetchPromise = null;
+    });
+    return openRouterFetchPromise;
+}
+async function lookupOpenRouterContextWindow(modelId) {
+    const cached = readOpenRouterCatalogEntry(modelId);
+    if (cached !== null)
+        return cached;
+    try {
+        const catalog = await fetchOpenRouterCatalog();
+        const value = catalog[modelId];
+        return isValidWindow(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Synchronous best-effort resolution: override → cache → pi-ai catalog → default.
+ */
+export function resolveContextWindowSync(provider, modelId, override) {
+    const fromOverride = applyOverride(override);
+    if (fromOverride !== null)
+        return fromOverride;
+    const cached = readCachedContextWindow(provider, modelId);
+    if (cached !== null)
+        return cached;
+    const fromCatalog = readOpenRouterCatalogEntry(modelId);
+    if (fromCatalog !== null)
+        return fromCatalog;
+    const fromPiAi = lookupPiAiContextWindow(provider, modelId);
+    if (fromPiAi !== null)
+        return fromPiAi;
+    // OpenRouter-style ids may live under the openrouter provider in pi-ai.
+    if (provider !== "openrouter" && modelId.includes("/")) {
+        const fromOpenRouterPiAi = lookupPiAiContextWindow("openrouter", modelId);
+        if (fromOpenRouterPiAi !== null)
+            return fromOpenRouterPiAi;
+    }
+    return DEFAULT_MODEL_CONTEXT_WINDOW;
+}
+/**
+ * Fetch and cache context window for a model. Never throws — falls back to sync resolution.
+ */
+export async function fetchAndCacheContextWindow(provider, modelId, override) {
+    const fromOverride = applyOverride(override);
+    if (fromOverride !== null)
+        return fromOverride;
+    const cached = readCachedContextWindow(provider, modelId);
+    if (cached !== null)
+        return cached;
+    const sources = [
+        lookupPiAiContextWindow(provider, modelId),
+        provider !== "openrouter" && modelId.includes("/")
+            ? lookupPiAiContextWindow("openrouter", modelId)
+            : null,
+        await lookupOpenRouterContextWindow(modelId),
+    ];
+    for (const value of sources) {
+        if (value !== null) {
+            rememberContextWindow(provider, modelId, value);
+            return value;
+        }
+    }
+    const fallback = DEFAULT_MODEL_CONTEXT_WINDOW;
+    rememberContextWindow(provider, modelId, fallback);
+    return fallback;
+}
+/** @deprecated Use resolveContextWindowSync with provider, or session.getContextWindowTokens(). */
+export function resolveContextWindow(modelId, override) {
+    return resolveContextWindowSync("openrouter", modelId, override);
+}
+/** Test helper — reset in-memory/disk cache state. */
+export function resetModelContextCacheForTests() {
+    memoryEntries.clear();
+    diskCache = null;
+    openRouterFetchPromise = null;
+    if (existsSync(CACHE_FILE)) {
+        unlinkSync(CACHE_FILE);
+    }
+}

package/dist/project-detector.d.ts

@@ -0,0 +1,37 @@
+export interface ProjectDetectionResult {
+    projectName?: string;
+    description?: string;
+    languages: string[];
+    frameworks: string[];
+    packageManagers: string[];
+    scripts?: Record<string, string>;
+    dependencies?: string[];
+    monorepoTool?: string;
+    ciCd: string[];
+    hasDocker: boolean;
+    hasGitignore: boolean;
+    readme?: string;
+}
+export interface ProjectDetectionOptions {
+    languages?: string[];
+    frameworks?: string[];
+}
+export declare class ProjectDetector {
+    static detect(cwd: string, opts?: ProjectDetectionOptions): ProjectDetectionResult | null;
+}
+/**
+ * Convert a ProjectDetectionResult into the compact string used by the prompt
+ * compiler's ## Project Stack section. Returns null when result is null.
+ */
+export declare function formatProjectContext(result: ProjectDetectionResult, opts?: {
+    maxChars?: number;
+}): string;
+/**
+ * Detect project context and return a formatted string summary.
+ * Returns null when no meaningful signals are found.
+ * This is the main entry point consumed by session.ts.
+ */
+export declare function buildProjectContext(cwd: string, opts?: {
+    languages?: string[];
+    frameworks?: string[];
+}): string | null;