praana 0.5.0

package/dist/event-log.d.ts

@@ -0,0 +1,56 @@
+import type { Event, EventActor, EventKind } from "./types.js";
+export interface EventSearchOptions {
+    kinds?: EventKind[];
+    limit?: number;
+}
+export interface EventSearchMatch {
+    event: Event;
+    excerpt: string;
+}
+export declare const EVENT_LOG_FILENAME = "events.jsonl";
+export declare const LEGACY_EVENT_LOG_FILENAME = "events.log";
+export declare function getEventLogPath(sessionDir: string): string;
+export declare function getLegacyEventLogPath(sessionDir: string): string;
+/** Rename or merge legacy events.log into events.jsonl when opening a session. */
+export declare function migrateLegacyEventLog(sessionDir: string): void;
+export declare class EventLog {
+    private fd;
+    private logPath;
+    private checkpointPath;
+    private sessionId;
+    private eventCount;
+    private closed;
+    private compressedIds;
+    constructor(sessionId: string, logDir: string);
+    private loadCompressionCheckpoint;
+    append(event: {
+        kind: EventKind;
+        actor: EventActor;
+        payload: Record<string, unknown>;
+        event_id?: string;
+        timestamp?: number;
+    }): void;
+    readLast(n: number): Event[];
+    readAll(): Event[];
+    /** All events excluding those marked compressed for prompt assembly. */
+    readAllUncompressed(): Event[];
+    replayContextActions(): Event[];
+    getLogPath(): string;
+    /**
+     * Search all events in this session. Terms are ANDed (case-insensitive).
+     * Use pipe (|) in query for OR alternatives, e.g. "issue|review".
+     */
+    search(query: string, options?: EventSearchOptions): EventSearchMatch[];
+    private internalRead;
+    getSessionId(): string;
+    /** Mark event IDs as compressed — they will be excluded from readLastUncompressed. */
+    markEventsAsCompressed(eventIds: string[]): void;
+    /** Read last n events, excluding compressed ones. */
+    readLastUncompressed(n: number): Event[];
+    /** Get the number of compressed events. */
+    getCompressedCount(): number;
+    close(): void;
+}
+import type { SessionMeta } from "./types.js";
+export declare function writeSessionMeta(logDir: string, meta: SessionMeta): void;
+export declare function readSessionMeta(logDir: string, sessionId: string): SessionMeta | null;

package/dist/event-log.js

@@ -0,0 +1,214 @@
+import { mkdirSync, openSync, writeSync, fsyncSync, closeSync, readFileSync, existsSync, renameSync, statSync, unlinkSync, appendFileSync, } from "node:fs";
+import { join } from "node:path";
+import { ulid } from "ulid";
+export const EVENT_LOG_FILENAME = "events.jsonl";
+export const LEGACY_EVENT_LOG_FILENAME = "events.log";
+export function getEventLogPath(sessionDir) {
+    return join(sessionDir, EVENT_LOG_FILENAME);
+}
+export function getLegacyEventLogPath(sessionDir) {
+    return join(sessionDir, LEGACY_EVENT_LOG_FILENAME);
+}
+/** Rename or merge legacy events.log into events.jsonl when opening a session. */
+export function migrateLegacyEventLog(sessionDir) {
+    const jsonlPath = getEventLogPath(sessionDir);
+    const legacyPath = getLegacyEventLogPath(sessionDir);
+    if (!existsSync(legacyPath))
+        return;
+    if (!existsSync(jsonlPath)) {
+        renameSync(legacyPath, jsonlPath);
+        return;
+    }
+    const legacySize = statSync(legacyPath).size;
+    if (legacySize === 0) {
+        unlinkSync(legacyPath);
+        return;
+    }
+    const jsonlSize = statSync(jsonlPath).size;
+    if (jsonlSize === 0) {
+        unlinkSync(jsonlPath);
+        renameSync(legacyPath, jsonlPath);
+        return;
+    }
+    const legacyContent = readFileSync(legacyPath, "utf-8");
+    if (legacyContent.trim()) {
+        // Ensure events.jsonl ends with newline before appending
+        const jsonlContent = readFileSync(jsonlPath, "utf-8");
+        const prefix = jsonlContent.endsWith("\n") ? "" : "\n";
+        const suffix = legacyContent.endsWith("\n") ? legacyContent : legacyContent + "\n";
+        appendFileSync(jsonlPath, prefix + suffix);
+    }
+    unlinkSync(legacyPath);
+}
+export class EventLog {
+    fd;
+    logPath;
+    checkpointPath;
+    sessionId;
+    eventCount = 0;
+    closed = false;
+    compressedIds = new Set();
+    constructor(sessionId, logDir) {
+        this.sessionId = sessionId;
+        const sessionDir = join(logDir, sessionId);
+        mkdirSync(sessionDir, { recursive: true });
+        migrateLegacyEventLog(sessionDir);
+        this.logPath = getEventLogPath(sessionDir);
+        this.checkpointPath = join(sessionDir, "compression_checkpoint.json");
+        this.fd = openSync(this.logPath, "a");
+        this.loadCompressionCheckpoint();
+    }
+    loadCompressionCheckpoint() {
+        try {
+            if (existsSync(this.checkpointPath)) {
+                const data = JSON.parse(readFileSync(this.checkpointPath, "utf-8"));
+                if (Array.isArray(data.compressed_ids)) {
+                    this.compressedIds = new Set(data.compressed_ids);
+                }
+            }
+        }
+        catch { /* ignore corrupted checkpoint */ }
+    }
+    append(event) {
+        const fullEvent = {
+            event_id: event.event_id ?? ulid(),
+            session_id: this.sessionId,
+            timestamp: event.timestamp ?? Date.now(),
+            kind: event.kind,
+            actor: event.actor,
+            payload: event.payload,
+        };
+        const line = JSON.stringify(fullEvent) + "\n";
+        writeSync(this.fd, line, undefined, "utf-8");
+        fsyncSync(this.fd);
+        this.eventCount++;
+    }
+    readLast(n) {
+        return this.internalRead().slice(-n);
+    }
+    readAll() {
+        return this.internalRead();
+    }
+    /** All events excluding those marked compressed for prompt assembly. */
+    readAllUncompressed() {
+        const all = this.internalRead();
+        if (this.compressedIds.size === 0)
+            return all;
+        return all.filter((e) => !this.compressedIds.has(e.event_id));
+    }
+    replayContextActions() {
+        return this.internalRead().filter((e) => e.kind === "context_action");
+    }
+    getLogPath() {
+        return this.logPath;
+    }
+    /**
+     * Search all events in this session. Terms are ANDed (case-insensitive).
+     * Use pipe (|) in query for OR alternatives, e.g. "issue|review".
+     */
+    search(query, options = {}) {
+        const trimmed = query.trim();
+        if (!trimmed)
+            return [];
+        const terms = trimmed.includes("|")
+            ? trimmed.split("|").map((t) => t.trim().toLowerCase()).filter(Boolean)
+            : trimmed.toLowerCase().split(/\s+/).filter(Boolean);
+        const kindSet = options.kinds ? new Set(options.kinds) : null;
+        const limit = options.limit ?? 20;
+        const matches = [];
+        for (const event of this.internalRead()) {
+            if (kindSet && !kindSet.has(event.kind))
+                continue;
+            const text = eventSearchText(event).toLowerCase();
+            const matched = trimmed.includes("|")
+                ? terms.some((term) => text.includes(term))
+                : terms.every((term) => text.includes(term));
+            if (!matched)
+                continue;
+            matches.push({ event, excerpt: buildExcerpt(event, 400) });
+            if (matches.length >= limit)
+                break;
+        }
+        return matches;
+    }
+    internalRead() {
+        try {
+            const content = readFileSync(this.logPath, "utf-8");
+            return content.trim().split("\n").filter(Boolean).map((line) => JSON.parse(line));
+        }
+        catch {
+            return [];
+        }
+    }
+    getSessionId() {
+        return this.sessionId;
+    }
+    /** Mark event IDs as compressed — they will be excluded from readLastUncompressed. */
+    markEventsAsCompressed(eventIds) {
+        for (const id of eventIds) {
+            this.compressedIds.add(id);
+        }
+        const data = { compressed_ids: Array.from(this.compressedIds), timestamp: Date.now() };
+        writeFileSync(this.checkpointPath, JSON.stringify(data) + "\n", "utf-8");
+    }
+    /** Read last n events, excluding compressed ones. */
+    readLastUncompressed(n) {
+        const all = this.internalRead();
+        if (this.compressedIds.size === 0)
+            return all.slice(-n);
+        const uncompressed = all.filter((e) => !this.compressedIds.has(e.event_id));
+        return uncompressed.slice(-n);
+    }
+    /** Get the number of compressed events. */
+    getCompressedCount() {
+        return this.compressedIds.size;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        closeSync(this.fd);
+    }
+}
+// ---- Session meta helpers ----
+import { writeFileSync } from "node:fs";
+import { join as pathJoin } from "node:path";
+export function writeSessionMeta(logDir, meta) {
+    const sessionDir = pathJoin(logDir, meta.session_id);
+    mkdirSync(sessionDir, { recursive: true });
+    writeFileSync(pathJoin(sessionDir, "meta.json"), JSON.stringify(meta, null, 2) + "\n");
+}
+function eventSearchText(event) {
+    const p = event.payload;
+    switch (event.kind) {
+        case "user_message":
+        case "agent_message":
+            return String(p.text ?? "");
+        case "tool_call":
+            return `${String(p.tool ?? "")} ${JSON.stringify(p.args ?? {})}`;
+        case "tool_result":
+            return `${String(p.tool ?? "")} ${JSON.stringify(p.result ?? {})}`;
+        case "context_action":
+            return JSON.stringify(p);
+        case "system_note":
+            return JSON.stringify(p);
+        default:
+            return JSON.stringify(p);
+    }
+}
+function buildExcerpt(event, maxLen) {
+    const text = eventSearchText(event).replace(/\s+/g, " ").trim();
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen - 3) + "...";
+}
+export function readSessionMeta(logDir, sessionId) {
+    try {
+        const metaPath = pathJoin(logDir, sessionId, "meta.json");
+        const content = readFileSync(metaPath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/llm.d.ts

@@ -0,0 +1,29 @@
+import type { PraanaConfig } from "./types.js";
+export { resolveContextWindowSync, fetchAndCacheContextWindow, DEFAULT_MODEL_CONTEXT_WINDOW, } from "./model-context.js";
+interface ProviderConfig {
+    /** pi-ai API type identifier */
+    api: string;
+    /** pi-ai provider identifier */
+    provider: string;
+    /** Env var to check for API key, or null if none needed */
+    envKey: string | null;
+    /** Default base URL for this provider's API */
+    baseUrl: string;
+    /** Optional HTTP headers sent with every request */
+    headers?: Record<string, string>;
+}
+/** Lookup a provider config. Falls back to openrouter for unknown values. */
+export declare function getProviderConfig(provider: string): ProviderConfig;
+/** Return all known provider IDs (for docs / help text). */
+export declare function listKnownProviders(): string[];
+/** Return the env var name required by a provider, or null. */
+export declare function getProviderEnvKey(provider: string): string | null;
+/** Check whether the provider's API key is available in the environment. */
+export declare function isProviderAvailable(provider: string): boolean;
+/** Human-readable message explaining which env var is missing. */
+export declare function getMissingKeyMessage(provider: string): string | null;
+type RuntimeModel = Record<string, unknown> & {
+    __piOptions?: Record<string, unknown>;
+};
+export declare function createProvider(config: PraanaConfig["llm"], contextWindow?: number): (modelId: string) => RuntimeModel;
+export declare function resolveModel(modelString: string): string;

package/dist/llm.js

@@ -0,0 +1,155 @@
+import { resolveContextWindowSync } from "./model-context.js";
+import { getAppLogger } from "./logger.js";
+export { resolveContextWindowSync, fetchAndCacheContextWindow, DEFAULT_MODEL_CONTEXT_WINDOW, } from "./model-context.js";
+const PROVIDER_REGISTRY = {
+    // ── OpenAI-compatible (use "openai-completions" API) ──
+    openrouter: {
+        api: "openai-completions",
+        provider: "openrouter",
+        envKey: "OPENROUTER_API_KEY",
+        baseUrl: "https://openrouter.ai/api/v1",
+        headers: {
+            "HTTP-Referer": "https://github.com/aria",
+            "X-Title": "PRAANA",
+        },
+    },
+    openai: {
+        api: "openai-completions",
+        provider: "openai",
+        envKey: "OPENAI_API_KEY",
+        baseUrl: "https://api.openai.com/v1",
+    },
+    deepseek: {
+        api: "openai-completions",
+        provider: "deepseek",
+        envKey: "DEEPSEEK_API_KEY",
+        baseUrl: "https://api.deepseek.com/v1",
+    },
+    groq: {
+        api: "openai-completions",
+        provider: "groq",
+        envKey: "GROQ_API_KEY",
+        baseUrl: "https://api.groq.com/openai/v1",
+    },
+    xai: {
+        api: "openai-completions",
+        provider: "xai",
+        envKey: "XAI_API_KEY",
+        baseUrl: "https://api.x.ai/v1",
+    },
+    fireworks: {
+        api: "openai-completions",
+        provider: "fireworks",
+        envKey: "FIREWORKS_API_KEY",
+        baseUrl: "https://api.fireworks.ai/inference/v1",
+    },
+    opencode: {
+        api: "openai-completions",
+        provider: "opencode",
+        envKey: "OPENCODE_API_KEY",
+        baseUrl: "https://opencode.ai/zen/v1",
+    },
+    together: {
+        api: "openai-completions",
+        provider: "together",
+        envKey: "TOGETHER_API_KEY",
+        baseUrl: "https://api.together.xyz/v1",
+    },
+    ollama: {
+        api: "openai-completions",
+        provider: "openai",
+        envKey: null, // local — no key needed
+        baseUrl: "http://127.0.0.1:11434/v1",
+    },
+    // ── Native API (different wire protocol) ──
+    anthropic: {
+        api: "anthropic-messages",
+        provider: "anthropic",
+        envKey: "ANTHROPIC_API_KEY",
+        baseUrl: "https://api.anthropic.com",
+    },
+    google: {
+        api: "google-generative-ai",
+        provider: "google",
+        envKey: "GOOGLE_GENERATIVE_AI_API_KEY",
+        baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+    },
+    mistral: {
+        api: "mistral-conversations",
+        provider: "mistral",
+        envKey: "MISTRAL_API_KEY",
+        baseUrl: "https://api.mistral.ai/v1",
+    },
+    "amazon-bedrock": {
+        api: "bedrock-converse-stream",
+        provider: "amazon-bedrock",
+        envKey: null, // uses AWS credentials (env / IAM / profile)
+        baseUrl: "",
+    },
+};
+// ── Exported helpers ───────────────────────────────────────────
+/** Lookup a provider config. Falls back to openrouter for unknown values. */
+export function getProviderConfig(provider) {
+    const entry = PROVIDER_REGISTRY[provider];
+    if (!entry) {
+        getAppLogger().child("llm").warn(`Unknown provider "${provider}", falling back to openrouter. Known providers: ${listKnownProviders().join(", ")}`);
+        return PROVIDER_REGISTRY["openrouter"];
+    }
+    return entry;
+}
+/** Return all known provider IDs (for docs / help text). */
+export function listKnownProviders() {
+    return Object.keys(PROVIDER_REGISTRY).sort();
+}
+/** Return the env var name required by a provider, or null. */
+export function getProviderEnvKey(provider) {
+    return getProviderConfig(provider).envKey;
+}
+/** Check whether the provider's API key is available in the environment. */
+export function isProviderAvailable(provider) {
+    const envKey = getProviderEnvKey(provider);
+    if (envKey === null)
+        return true; // no key needed (ollama, bedrock)
+    return !!process.env[envKey];
+}
+/** Human-readable message explaining which env var is missing. */
+export function getMissingKeyMessage(provider) {
+    const envKey = getProviderEnvKey(provider);
+    if (envKey === null)
+        return null;
+    if (process.env[envKey])
+        return null;
+    return `Missing required environment variable: ${envKey}`;
+}
+function buildModel(config, modelId, contextWindow) {
+    const pc = getProviderConfig(config.provider);
+    const baseUrl = config.base_url ?? pc.baseUrl;
+    const apiKey = pc.envKey ? (process.env[pc.envKey] ?? "") : "no-key";
+    const model = {
+        id: modelId,
+        name: modelId,
+        provider: pc.provider,
+        api: pc.api,
+        baseUrl,
+        input: ["text"],
+        reasoning: true,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: contextWindow ??
+            resolveContextWindowSync(config.provider, modelId, config.context_window),
+        maxTokens: 8192,
+    };
+    if (pc.headers) {
+        model.headers = { ...pc.headers };
+    }
+    model.__piOptions = {
+        apiKey,
+        headers: pc.headers ? { ...pc.headers } : undefined,
+    };
+    return model;
+}
+export function createProvider(config, contextWindow) {
+    return (modelId) => buildModel(config, modelId, contextWindow);
+}
+export function resolveModel(modelString) {
+    return modelString;
+}

package/dist/logger.d.ts

@@ -0,0 +1,94 @@
+import { type DestinationStream } from "pino";
+export type LogLevel = "error" | "warn" | "info" | "debug";
+export type LogDomain = "app" | "compiler" | "llm" | "session" | "memory" | "config" | "tool" | "skills" | "context_engine";
+export type ErrorCode = "LLM_STREAM_ERROR" | "LLM_EMPTY_RESPONSE" | "LLM_ABORTED" | "TURN_FAILED" | "SESSION_START_FAILED" | "MEMORY_INIT_FAILED" | "TOOL_EXECUTION_FAILED" | "CONFIG_INVALID" | "UNKNOWN";
+export interface LogEntry {
+    level: LogLevel;
+    domain: LogDomain;
+    message: string;
+    code?: ErrorCode;
+    details?: Record<string, unknown>;
+    cause?: Error;
+}
+export interface LoggerOptions {
+    domain?: LogDomain;
+    debug?: boolean;
+    sessionId?: string;
+    /** Base session directory from config (e.g. ~/.praana/sessions). */
+    sessionLogDir?: string;
+    /** Pre-built rolling file destination for ~/.praana/logs. */
+    appFileStream?: DestinationStream;
+    /** Pre-built rolling file destination for session system.log. */
+    sessionFileStream?: DestinationStream;
+    /** Test hook — capture formatted log lines instead of stderr/files. */
+    writeLine?: (line: string) => void;
+    /** TUI boot — capture notice lines instead of writing to stderr. */
+    captureNotice?: (line: string) => void;
+}
+/** Daily rotated logs; symlink at `current.log` points to today's file. */
+export declare const LOG_SYMLINK_FILENAME = "current.log";
+export declare const LOG_RETENTION_DAYS = 15;
+/** pino-roll retains `count` rotated files plus the active file. */
+export declare const LOG_RETENTION_COUNT: number;
+export declare function getAppLogDir(): string;
+/** Base path for pino-roll (extension added by rotator). */
+export declare function getAppLogBase(): string;
+/** Stable symlink path for tailing the active app log. */
+export declare function getAppLogPath(): string;
+export declare function getSessionLogBase(sessionLogDir: string, sessionId: string): string;
+/** Stable symlink path for tailing the active session system log. */
+export declare function getSessionSystemLogPath(sessionLogDir: string, sessionId: string): string;
+export declare class PraanaLogger {
+    private readonly pino;
+    private readonly options;
+    constructor(options?: LoggerOptions);
+    child(domain: LogDomain): PraanaLogger;
+    log(entry: LogEntry): void;
+    error(message: string, opts?: {
+        code?: ErrorCode;
+        details?: Record<string, unknown>;
+        cause?: Error;
+        domain?: LogDomain;
+    }): void;
+    warn(message: string, opts?: {
+        code?: ErrorCode;
+        details?: Record<string, unknown>;
+        cause?: Error;
+        domain?: LogDomain;
+    }): void;
+    info(message: string, opts?: {
+        details?: Record<string, unknown>;
+        domain?: LogDomain;
+    }): void;
+    debug(message: string, opts?: {
+        details?: Record<string, unknown>;
+        domain?: LogDomain;
+    }): void;
+    /** User-visible status — always on stderr; also written to system log files at info level. */
+    notice(message: string, opts?: {
+        domain?: LogDomain;
+        details?: Record<string, unknown>;
+    }): void;
+}
+export declare function getAppLogger(): PraanaLogger;
+export declare function setAppLogger(logger: PraanaLogger): void;
+/** Initialise daily-rotating app log under ~/.praana/logs (no-op in tests). */
+export declare function initAppLogFile(): Promise<void>;
+export declare function createSessionLogger(opts: {
+    sessionId: string;
+    sessionLogDir: string;
+    debug?: boolean;
+    captureNotice?: (line: string) => void;
+}): Promise<PraanaLogger>;
+export declare function createTestLogger(writeLine: (line: string) => void, opts?: {
+    debug?: boolean;
+}): PraanaLogger;
+/** Extract a human-readable message from a pi-ai assistant/error message object. */
+export declare function extractLlmErrorMessage(message: unknown): string | undefined;
+export declare function formatUserFacingLlmError(opts: {
+    reason: string;
+    llmMessage?: string;
+    model: string;
+    provider: string;
+}): string;
+export declare function isLogLevel(value: string): value is LogLevel;