praana 0.5.0

package/dist/context-engine/types.d.ts

@@ -0,0 +1,201 @@
+export type ContentType = "code" | "diff" | "log" | "json" | "test_output" | "build_output" | "search_results" | "error" | "prose" | "other";
+export interface ContextArtifact {
+    id: string;
+    sha256: string;
+    sessionId: string;
+    sourceTool: string;
+    command?: string;
+    createdTurn: number;
+    rawTokens: number;
+    rawText: string;
+    summary: string;
+    contentType: ContentType;
+    lastAccessedTurn: number;
+    accessCount: number;
+}
+export interface IngestToolResultInput {
+    sourceTool: string;
+    command?: string;
+    rawText: string;
+    contentType?: ContentType;
+    createdTurn: number;
+}
+export interface IngestToolResultOutput {
+    /** Text placed in LLM conversation history */
+    promptText: string;
+    artifactId?: string;
+    inlined: boolean;
+}
+export interface RetrieveArtifactOptions {
+    grep?: string;
+    lineStart?: number;
+    lineEnd?: number;
+    jsonPath?: string;
+}
+export interface ToolCallRecord {
+    tool: string;
+    args: Record<string, unknown>;
+    resultArtifactId?: string;
+    isError: boolean;
+    /** Truncated tool result text for deterministic activity rules (full text in artifact store) */
+    resultText?: string;
+}
+export interface TurnDigestDecision {
+    summary: string;
+    rationale?: string;
+}
+export interface TurnDigest {
+    turnId: number;
+    userIntent: string;
+    filesChanged: string[];
+    filesWritten: string[];
+    artifactRefs: string[];
+    decisions: TurnDigestDecision[];
+    constraints: string[];
+    errorsNew: string[];
+    errorsFixed: string[];
+    toolSummary: string;
+    /** Plan text extracted from the assistant message, if any */
+    extractedPlan?: string;
+}
+export type ActivityEntryType = "commit" | "test_pass" | "test_fail" | "error_fixed" | "file_written" | "decision_made";
+export interface ActivityEntry {
+    turn: number;
+    type: ActivityEntryType;
+    summary: string;
+    artifactRef?: string;
+}
+export interface StateSnapshot {
+    objects: Map<string, {
+        kind: string;
+        updated: number;
+        payloadJson: string;
+    }>;
+}
+export interface OpenError {
+    key: string;
+    message: string;
+    turn: number;
+    tool: string;
+    command?: string;
+}
+export interface CheckpointDraft {
+    lastUserIntent: string;
+    openErrors: OpenError[];
+    recentDecisions: Array<{
+        summary: string;
+        turn: number;
+    }>;
+    recentConstraints: string[];
+    recentActivity: ActivityEntry[];
+}
+/** When compact is true, summary renders as a one-liner; rationale is always retained. */
+export interface CheckpointDecisionEntry {
+    summary: string;
+    rationale?: string;
+    turn: number;
+    compact?: boolean;
+}
+export interface CheckpointNarrativeEntry {
+    turn: number;
+    text: string;
+}
+export interface CheckpointPlanEntry {
+    text: string;
+    turn: number;
+    superseded: boolean;
+    supersededTurn?: number;
+    completed?: string[];
+}
+export interface CheckpointFileEntry {
+    path: string;
+    turn: number;
+}
+export interface CheckpointErrorEntry {
+    key: string;
+    message: string;
+    turn: number;
+    fixed: boolean;
+    fixedTurn?: number;
+}
+export interface CheckpointFindingEntry {
+    summary: string;
+    artifactRef?: string;
+    turn: number;
+}
+export interface CheckpointQuestionEntry {
+    text: string;
+    turn: number;
+    closed: boolean;
+}
+export interface CheckpointState {
+    activeRequest: string;
+    plans: CheckpointPlanEntry[];
+    constraints: string[];
+    decisions: CheckpointDecisionEntry[];
+    files: CheckpointFileEntry[];
+    findings: CheckpointFindingEntry[];
+    errors: CheckpointErrorEntry[];
+    questions: CheckpointQuestionEntry[];
+    activity: ActivityEntry[];
+    narrative: CheckpointNarrativeEntry[];
+    lastReconciledTurn: number;
+}
+export interface SessionCheckpoint {
+    version: 1;
+    state: CheckpointState;
+}
+export type ContextUnitType = "verbatim_turn" | "turn_digest" | "checkpoint_section" | "artifact_card" | "activity_entry" | "memory_digest" | "active_state";
+export interface ContextUnit {
+    id: string;
+    type: ContextUnitType;
+    content: string;
+    tokens: number;
+    sourceTurn: number;
+    score: number;
+    pinned: boolean;
+    artifactRefs: string[];
+}
+export interface ScoreBreakdown {
+    pin: number;
+    recency: number;
+    relevance: number;
+}
+export interface ScoredContextUnit extends ContextUnit {
+    breakdown: ScoreBreakdown;
+}
+export type PressureMode = "normal" | "compact" | "emergency";
+export interface CompileScoreRecord {
+    turn: number;
+    unitId: string;
+    type: ContextUnitType;
+    score: number;
+    included: boolean;
+    band: number;
+    tokens: number;
+    breakdown: ScoreBreakdown;
+}
+export interface TurnRecord {
+    turn: number;
+    userMessage: string;
+    assistantMessage: string;
+    toolCalls: ToolCallRecord[];
+    artifactIds: string[];
+    filesRead: string[];
+    filesWritten: string[];
+    errors: string[];
+    tokenCount: number;
+    timestamp: number;
+}
+export interface TurnSearchMatch {
+    turn: number;
+    score: number;
+    userMessage: string;
+    assistantMessage: string;
+    excerpt: string;
+    artifactIds: string[];
+    filesRead: string[];
+    filesWritten: string[];
+    errors: string[];
+    timestamp: number;
+}

package/dist/context-engine/types.js

@@ -0,0 +1,4 @@
+// ============================================================
+// ARIA Context Engine — Types
+// ============================================================
+export {};

package/dist/context-pressure.d.ts

@@ -0,0 +1,19 @@
+import type { CompilerConfig } from "./types.js";
+export { DEFAULT_MODEL_CONTEXT_WINDOW, resolveContextWindowSync, fetchAndCacheContextWindow, } from "./model-context.js";
+export declare function resolveCompactionConfig(config: CompilerConfig): {
+    autoCompactAt: number;
+    autoCompactClearAt: number;
+    compactChunkFraction: number;
+    verbatimOnly: boolean;
+};
+/** Prompt fill ratio against usable context (window minus reserved output). */
+export declare function computeContextPressureRatio(usedTokens: number, contextWindowTokens: number, reservedOutputTokens?: number): number;
+/**
+ * Hysteresis: arm at auto_compact_at, disarm below auto_compact_clear_at.
+ * Trigger compaction only while armed and still at/above compact_at.
+ */
+export declare function shouldTriggerAutoCompact(pressureRatio: number, config: CompilerConfig, armed: boolean): {
+    trigger: boolean;
+    armed: boolean;
+};
+export declare function effectiveCompileBudget(tokenBudget: number, contextWindowTokens: number, reservedOutputTokens?: number): number;

package/dist/context-pressure.js

@@ -0,0 +1,36 @@
+export { DEFAULT_MODEL_CONTEXT_WINDOW, resolveContextWindowSync, fetchAndCacheContextWindow, } from "./model-context.js";
+export function resolveCompactionConfig(config) {
+    return {
+        autoCompactAt: config.auto_compact_at ?? config.compression_watermark ?? 0.75,
+        autoCompactClearAt: config.auto_compact_clear_at ?? 0.55,
+        compactChunkFraction: config.compact_chunk_fraction ?? config.compression_flush_fraction ?? 0.25,
+        verbatimOnly: config.verbatim_only ?? false,
+    };
+}
+/** Prompt fill ratio against usable context (window minus reserved output). */
+export function computeContextPressureRatio(usedTokens, contextWindowTokens, reservedOutputTokens = 0) {
+    const usable = Math.max(1, contextWindowTokens - reservedOutputTokens);
+    return usedTokens / usable;
+}
+/**
+ * Hysteresis: arm at auto_compact_at, disarm below auto_compact_clear_at.
+ * Trigger compaction only while armed and still at/above compact_at.
+ */
+export function shouldTriggerAutoCompact(pressureRatio, config, armed) {
+    const { autoCompactAt, autoCompactClearAt, verbatimOnly } = resolveCompactionConfig(config);
+    if (verbatimOnly)
+        return { trigger: false, armed };
+    let nextArmed = armed;
+    if (pressureRatio >= autoCompactAt)
+        nextArmed = true;
+    else if (pressureRatio < autoCompactClearAt)
+        nextArmed = false;
+    return {
+        trigger: nextArmed && pressureRatio >= autoCompactAt,
+        armed: nextArmed,
+    };
+}
+export function effectiveCompileBudget(tokenBudget, contextWindowTokens, reservedOutputTokens = 0) {
+    const windowBudget = Math.max(0, contextWindowTokens - reservedOutputTokens);
+    return Math.max(0, Math.min(tokenBudget, windowBudget));
+}

package/dist/distillers/generic.d.ts

@@ -0,0 +1,14 @@
+import type { Distiller, DistillerIntensity } from "../context-engine/distiller.js";
+import type { ContentType } from "../context-engine/types.js";
+export declare class GenericDistiller implements Distiller {
+    readonly name = "generic";
+    readonly contentTypes: ContentType[];
+    readonly mode: "sync";
+    distill(input: string, intensity: DistillerIntensity, contentType?: ContentType): string;
+}
+export declare class LogDistiller implements Distiller {
+    readonly name = "log";
+    readonly contentTypes: ContentType[];
+    readonly mode: "sync";
+    distill(input: string, intensity: DistillerIntensity): string;
+}

package/dist/distillers/generic.js

@@ -0,0 +1,93 @@
+function headTail(input, headChars, tailChars) {
+    if (input.length <= headChars + tailChars + 40)
+        return input;
+    const head = input.slice(0, headChars).trimEnd();
+    const tail = input.slice(-tailChars).trimStart();
+    const omitted = input.length - head.length - tail.length;
+    return `${head}\n… [${omitted.toLocaleString()} chars omitted] …\n${tail}`;
+}
+function summarizeJson(input, intensity) {
+    try {
+        const parsed = JSON.parse(input);
+        const budget = intensity === "full" ? 8 : 16;
+        return JSON.stringify(compactJson(parsed, budget), null, 2);
+    }
+    catch {
+        return headTail(input, intensity === "full" ? 250 : 400, intensity === "full" ? 250 : 400);
+    }
+}
+function compactJson(value, budget) {
+    if (Array.isArray(value)) {
+        if (value.length <= budget)
+            return value.map((item) => compactJson(item, budget));
+        return [
+            ...value.slice(0, budget).map((item) => compactJson(item, budget)),
+            {
+                __aria_summary: `${value.length - budget} array item(s) omitted`,
+            },
+        ];
+    }
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value);
+        const out = {};
+        for (const [key, child] of entries.slice(0, budget)) {
+            out[key] = compactJson(child, budget);
+        }
+        if (entries.length > budget) {
+            out.__aria_summary = `${entries.length - budget} object field(s) omitted`;
+        }
+        return out;
+    }
+    return value;
+}
+export class GenericDistiller {
+    name = "generic";
+    contentTypes = ["other", "code", "prose", "json"];
+    mode = "sync";
+    distill(input, intensity, contentType) {
+        if (contentType === "json") {
+            return summarizeJson(input, intensity);
+        }
+        const head = intensity === "full" ? 250 : 400;
+        const tail = intensity === "full" ? 250 : 400;
+        return headTail(input, head, tail);
+    }
+}
+export class LogDistiller {
+    name = "log";
+    contentTypes = ["log"];
+    mode = "sync";
+    distill(input, intensity) {
+        const lines = input.split("\n");
+        const counts = new Map();
+        const errors = [];
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            counts.set(trimmed, (counts.get(trimmed) ?? 0) + 1);
+            if (/\b(error|exception|fatal)\b/i.test(trimmed)) {
+                errors.push(trimmed);
+            }
+        }
+        const maxUnique = intensity === "full" ? 8 : 15;
+        const uniqueLines = [];
+        for (const [line, count] of counts) {
+            if (count === 1)
+                uniqueLines.push(line);
+            else
+                uniqueLines.push(`${line} (×${count})`);
+            if (uniqueLines.length >= maxUnique)
+                break;
+        }
+        const tailErrors = errors.slice(-5);
+        const parts = [
+            `Log: ${lines.length} lines, ${counts.size} unique patterns`,
+            ...uniqueLines,
+        ];
+        if (tailErrors.length > 0) {
+            parts.push("Recent errors:", ...tailErrors);
+        }
+        return parts.join("\n");
+    }
+}

package/dist/distillers/git-diff.d.ts

@@ -0,0 +1,8 @@
+import type { Distiller, DistillerIntensity } from "../context-engine/distiller.js";
+import type { ContentType } from "../context-engine/types.js";
+export declare class DiffDistiller implements Distiller {
+    readonly name = "git-diff";
+    readonly contentTypes: ContentType[];
+    readonly mode: "sync";
+    distill(input: string, intensity: DistillerIntensity): string;
+}

package/dist/distillers/git-diff.js

@@ -0,0 +1,119 @@
+const CONTEXT_LINES = 2;
+export class DiffDistiller {
+    name = "git-diff";
+    contentTypes = ["diff"];
+    mode = "sync";
+    distill(input, intensity) {
+        const context = intensity === "full" ? 1 : CONTEXT_LINES;
+        const lines = input.split("\n");
+        const out = [];
+        let inHunk = false;
+        let hunkBuffer = [];
+        let hunkHasChange = false;
+        let metadataBuffer = [];
+        const flushMetadata = () => {
+            if (metadataBuffer.length > 0) {
+                out.push(...metadataBuffer);
+                metadataBuffer = [];
+            }
+        };
+        const flushHunk = () => {
+            if (!hunkHasChange) {
+                inHunk = false;
+                hunkBuffer = [];
+                return;
+            }
+            flushMetadata();
+            const compact = compactHunk(hunkBuffer, context);
+            if (compact.length > 0)
+                out.push(...compact);
+            inHunk = false;
+            hunkBuffer = [];
+            hunkHasChange = false;
+        };
+        for (const line of lines) {
+            if (line.startsWith("diff --git ")) {
+                flushHunk();
+                flushMetadata();
+                out.push(line);
+                metadataBuffer = [];
+                continue;
+            }
+            if (line.startsWith("@@")) {
+                flushHunk();
+                flushMetadata();
+                inHunk = true;
+                hunkBuffer = [line];
+                hunkHasChange = false;
+                continue;
+            }
+            if (inHunk) {
+                if (line.startsWith("+") && !line.startsWith("+++"))
+                    hunkHasChange = true;
+                if (line.startsWith("-") && !line.startsWith("---"))
+                    hunkHasChange = true;
+                hunkBuffer.push(line);
+                continue;
+            }
+            if (intensity !== "full") {
+                out.push(line);
+            }
+            else if (isDiffMetadata(line)) {
+                metadataBuffer.push(line);
+            }
+        }
+        flushHunk();
+        flushMetadata();
+        if (out.length === 0)
+            return input.slice(0, 1200);
+        return out.join("\n");
+    }
+}
+function isDiffMetadata(line) {
+    return (line.startsWith("index ") ||
+        line.startsWith("old mode ") ||
+        line.startsWith("new mode ") ||
+        line.startsWith("deleted file mode ") ||
+        line.startsWith("new file mode ") ||
+        line.startsWith("similarity index ") ||
+        line.startsWith("dissimilarity index ") ||
+        line.startsWith("rename from ") ||
+        line.startsWith("rename to ") ||
+        line.startsWith("copy from ") ||
+        line.startsWith("copy to ") ||
+        line.startsWith("Binary files ") ||
+        line.startsWith("--- ") ||
+        line.startsWith("+++ "));
+}
+function compactHunk(lines, context) {
+    const changeIndexes = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith("+") || line.startsWith("-")) {
+            if (!line.startsWith("+++") && !line.startsWith("---")) {
+                changeIndexes.push(i);
+            }
+        }
+    }
+    if (changeIndexes.length === 0)
+        return [];
+    const keep = new Set();
+    keep.add(0);
+    for (const idx of changeIndexes) {
+        for (let d = -context; d <= context; d++) {
+            const pos = idx + d;
+            if (pos >= 0 && pos < lines.length)
+                keep.add(pos);
+        }
+    }
+    const sorted = [...keep].sort((a, b) => a - b);
+    const out = [];
+    let prev = -2;
+    for (const idx of sorted) {
+        if (idx > prev + 1)
+            out.push("…");
+        out.push(lines[idx]);
+        prev = idx;
+    }
+    return out;
+}

package/dist/distillers/index.d.ts

@@ -0,0 +1,2 @@
+import { DistillerRegistry } from "../context-engine/distiller.js";
+export declare function createDefaultDistillerRegistry(): DistillerRegistry;

package/dist/distillers/index.js

@@ -0,0 +1,16 @@
+import { DiffDistiller } from "./git-diff.js";
+import { GenericDistiller, LogDistiller } from "./generic.js";
+import { TestDistiller } from "./npm-test.js";
+import { SearchDistiller } from "./rg-results.js";
+import { BuildDistiller } from "./tsc-errors.js";
+import { DistillerRegistry } from "../context-engine/distiller.js";
+export function createDefaultDistillerRegistry() {
+    const registry = new DistillerRegistry();
+    registry.register(new DiffDistiller());
+    registry.register(new TestDistiller());
+    registry.register(new BuildDistiller());
+    registry.register(new SearchDistiller());
+    registry.register(new LogDistiller());
+    registry.register(new GenericDistiller());
+    return registry;
+}

package/dist/distillers/npm-test.d.ts

@@ -0,0 +1,8 @@
+import type { Distiller, DistillerIntensity } from "../context-engine/distiller.js";
+import type { ContentType } from "../context-engine/types.js";
+export declare class TestDistiller implements Distiller {
+    readonly name = "npm-test";
+    readonly contentTypes: ContentType[];
+    readonly mode: "sync";
+    distill(input: string, intensity: DistillerIntensity): string;
+}

package/dist/distillers/npm-test.js

@@ -0,0 +1,50 @@
+export class TestDistiller {
+    name = "npm-test";
+    contentTypes = ["test_output"];
+    mode = "sync";
+    distill(input, intensity) {
+        const lines = input.split("\n");
+        const failures = [];
+        const summaries = [];
+        let captureFailure = false;
+        const failureLimit = intensity === "full" ? 80 : 140;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            const isFailureStart = /^\s*(FAIL|✕|×)\s/.test(line) ||
+                /\bFAIL\b/.test(line) ||
+                /^AssertionError\b/.test(trimmed) ||
+                /^(TypeError|ReferenceError|Error):/.test(trimmed);
+            const isPassingSuite = /^\s*(PASS|✓)\s/.test(line);
+            const isSummary = /^(Test Files|Tests|Test Suites|Snapshots|Time):/.test(trimmed) ||
+                /^Tests:\s+/.test(trimmed) ||
+                /^\d+\s+(passed|failed)\b/i.test(trimmed);
+            if (isSummary) {
+                summaries.push(line);
+                if (/failed/i.test(line))
+                    captureFailure = true;
+                continue;
+            }
+            if (isPassingSuite) {
+                captureFailure = false;
+                continue;
+            }
+            if (isFailureStart) {
+                captureFailure = true;
+            }
+            if (captureFailure && failures.length < failureLimit) {
+                failures.push(line);
+            }
+        }
+        const parts = [];
+        if (failures.length > 0) {
+            parts.push(`${failures.length} failure detail line(s):`, ...failures);
+        }
+        if (summaries.length > 0) {
+            parts.push("Summary:", ...summaries.slice(-6));
+        }
+        else {
+            parts.push(`Test output: ${lines.length} lines`);
+        }
+        return parts.join("\n");
+    }
+}

package/dist/distillers/rg-results.d.ts

@@ -0,0 +1,8 @@
+import type { Distiller, DistillerIntensity } from "../context-engine/distiller.js";
+import type { ContentType } from "../context-engine/types.js";
+export declare class SearchDistiller implements Distiller {
+    readonly name = "rg-search";
+    readonly contentTypes: ContentType[];
+    readonly mode: "sync";
+    distill(input: string, intensity: DistillerIntensity): string;
+}

package/dist/distillers/rg-results.js

@@ -0,0 +1,28 @@
+export class SearchDistiller {
+    name = "rg-search";
+    contentTypes = ["search_results"];
+    mode = "sync";
+    distill(input, intensity) {
+        const lines = input.split("\n").filter((l) => l.trim().length > 0);
+        const limit = intensity === "full" ? 15 : 30;
+        const seen = new Set();
+        const kept = [];
+        for (const line of lines) {
+            const normalized = line.replace(/\s+/g, " ").trim();
+            const key = normalized.slice(0, 120);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            kept.push(line);
+            if (kept.length >= limit)
+                break;
+        }
+        if (kept.length === 0)
+            return input.slice(0, 800);
+        const omitted = Math.max(0, lines.length - kept.length);
+        const header = omitted > 0
+            ? `Search results: showing ${kept.length} of ${lines.length} lines`
+            : `Search results: ${kept.length} lines`;
+        return [header, ...kept].join("\n");
+    }
+}

package/dist/distillers/tsc-errors.d.ts

@@ -0,0 +1,8 @@
+import type { Distiller, DistillerIntensity } from "../context-engine/distiller.js";
+import type { ContentType } from "../context-engine/types.js";
+export declare class BuildDistiller implements Distiller {
+    readonly name = "tsc-errors";
+    readonly contentTypes: ContentType[];
+    readonly mode: "sync";
+    distill(input: string, intensity: DistillerIntensity): string;
+}

package/dist/distillers/tsc-errors.js

@@ -0,0 +1,52 @@
+const ERROR_LINE = /^(.+?)\((\d+),(\d+)\):\s+error\s+(TS\d+):\s+(.+)$/;
+export class BuildDistiller {
+    name = "tsc-errors";
+    contentTypes = ["build_output"];
+    mode = "sync";
+    distill(input, intensity) {
+        const lines = input.split("\n");
+        const groups = new Map();
+        const genericErrors = [];
+        for (const line of lines) {
+            const match = line.match(ERROR_LINE);
+            if (match) {
+                const [, file, lineNo, , code, message] = match;
+                const key = `${code}:${message.trim()}`;
+                const existing = groups.get(key);
+                if (existing) {
+                    existing.locations.push(`${file}:${lineNo}`);
+                }
+                else {
+                    groups.set(key, {
+                        code,
+                        message: message.trim(),
+                        locations: [`${file}:${lineNo}`],
+                    });
+                }
+                continue;
+            }
+            if (/^error\b/i.test(line.trim()) && line.length < 300) {
+                genericErrors.push(line.trim());
+            }
+        }
+        if (groups.size === 0 && genericErrors.length === 0) {
+            return lines.slice(0, intensity === "full" ? 20 : 40).join("\n");
+        }
+        const maxGroups = intensity === "full" ? 25 : 50;
+        const maxLocationsPerGroup = intensity === "full" ? 20 : 50;
+        const rendered = [];
+        for (const group of groups.values()) {
+            const shownLocations = group.locations.slice(0, maxLocationsPerGroup);
+            const omitted = group.locations.length - shownLocations.length;
+            rendered.push(`${group.code} ${group.message}`, `  ${group.locations.length} location(s): ${shownLocations.join(", ")}${omitted > 0 ? `, ... ${omitted} more` : ""}`);
+            if (rendered.length / 2 >= maxGroups)
+                break;
+        }
+        const totalLocations = [...groups.values()].reduce((sum, group) => sum + group.locations.length, 0) +
+            genericErrors.length;
+        const header = groups.size > 0
+            ? `${groups.size} unique build error(s), ${totalLocations} location(s)`
+            : `${genericErrors.length} build error(s)`;
+        return [header, ...rendered, ...genericErrors].join("\n");
+    }
+}