@unerr-ai/unerr 0.2.0 → 0.2.2

package/dist/behaviors/incomplete-work.js

@@ -1,270 +0,0 @@
-/**
- * Incomplete Work Detection — BA-2.1
- *
- * Session-end scan that verifies:
- *   1. Broken callers — entity signature changed but callers not all updated
- *   2. Orphaned imports — import targets deleted during session
- *   3. Untested exports — new exported symbols with no test reference
- *
- * Persists incomplete items to disk so Session Continuity (BA-1.2) can
- * inject them as resume context in the next session.
- *
- * Trigger: session_end (proxy shutdown)
- * Assertiveness: suggestion (surface as checklist, don't block)
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { Behavior, } from "./framework.js";
-const PERSISTENCE_FILE = "incomplete-work.json";
-export class IncompleteWorkDetector extends Behavior {
-    id = "incomplete_work";
-    hooks = ["session_end"];
-    defaultLevel = "suggestion";
-    graph = null;
-    ledger = null;
-    cascadeGuard = null;
-    unerrDir = null;
-    constructor(config) {
-        super(config, "suggestion");
-    }
-    attachGraph(graph) {
-        this.graph = graph;
-    }
-    attachLedger(ledger) {
-        this.ledger = ledger;
-    }
-    attachCascadeGuard(cascadeGuard) {
-        this.cascadeGuard = cascadeGuard;
-    }
-    setUnerrDir(dir) {
-        this.unerrDir = dir;
-    }
-    async onSessionEnd(_ctx) {
-        const items = [];
-        const brokenCallers = this.detectBrokenCallers();
-        items.push(...brokenCallers);
-        const orphanedImports = await this.detectOrphanedImports();
-        items.push(...orphanedImports);
-        const untestedExports = await this.detectUntestedExports();
-        items.push(...untestedExports);
-        if (items.length === 0)
-            return null;
-        items.sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
-        const highCount = items.filter((i) => i.severity === "high").length;
-        const summary = highCount > 0
-            ? `${highCount} item(s) will cause immediate errors. Fix before committing.`
-            : `${items.length} potential issue(s) detected. Review before your next session.`;
-        const persisted = this.persistItems(items);
-        return {
-            behaviorId: this.id,
-            level: this.level,
-            relatedSkillId: "dependency-aware-refactor",
-            _meta: {
-                behavior: this.id,
-                items_found: items.length,
-                high_severity: highCount,
-                persisted,
-            },
-            _context: {
-                incomplete_items: items,
-                summary,
-            },
-        };
-    }
-    /**
-     * Check cascade guard for signature changes where not all callers were updated.
-     */
-    detectBrokenCallers() {
-        if (!this.cascadeGuard)
-            return [];
-        const incompleteChanges = this.cascadeGuard.getIncompleteChanges();
-        const items = [];
-        for (const change of incompleteChanges) {
-            const remaining = change.callersAtRisk
-                .filter((c) => !change.callersUpdated.has(c.entity))
-                .map((c) => `${c.file}:${c.entity}`);
-            if (remaining.length === 0)
-                continue;
-            items.push({
-                severity: "high",
-                type: "broken_callers",
-                entity: change.entityKey,
-                detail: `Signature changed (${change.changeType}) but ${remaining.length}/${change.callersAtRisk.length} callers not updated`,
-                remaining,
-                impact: "Callers will fail at runtime or compile time",
-            });
-        }
-        return items;
-    }
-    /**
-     * Check shadow ledger for files that were deleted but are still imported.
-     * Uses the graph to find import edges pointing to deleted files.
-     */
-    async detectOrphanedImports() {
-        if (!this.ledger || !this.graph)
-            return [];
-        const sessionEntries = this.ledger.getRecentEntries(100);
-        const deletedFiles = new Set();
-        for (const entry of sessionEntries) {
-            if (entry.tool === "delete_file" || entry.tool === "remove_file") {
-                const path = extractPathFromArgs(entry.args_summary);
-                if (path)
-                    deletedFiles.add(path);
-            }
-        }
-        if (deletedFiles.size === 0)
-            return [];
-        const items = [];
-        for (const deletedFile of deletedFiles) {
-            const importers = await this.findImportersOf(deletedFile);
-            if (importers.length > 0) {
-                items.push({
-                    severity: "medium",
-                    type: "orphaned_import",
-                    file: deletedFile,
-                    detail: `File deleted this session but still imported by ${importers.length} file(s)`,
-                    remaining: importers.slice(0, 5),
-                    impact: "Runtime import error",
-                });
-            }
-        }
-        return items;
-    }
-    /**
-     * Find new exports added this session that have no test coverage.
-     */
-    async detectUntestedExports() {
-        if (!this.ledger || !this.graph)
-            return [];
-        const sessionEntries = this.ledger.getRecentEntries(100);
-        const modifiedFiles = new Set();
-        for (const entry of sessionEntries) {
-            if (isEditTool(entry.tool)) {
-                const path = extractPathFromArgs(entry.args_summary);
-                if (path && !isTestFile(path))
-                    modifiedFiles.add(path);
-            }
-        }
-        const items = [];
-        for (const file of modifiedFiles) {
-            const entities = await this.graph.getEntitiesByFile(file);
-            for (const entity of entities) {
-                if (entity.kind !== "function" && entity.kind !== "class")
-                    continue;
-                if (entity.fan_in === 0) {
-                    const hasTestRef = await this.hasTestReference(entity);
-                    if (!hasTestRef) {
-                        items.push({
-                            severity: "low",
-                            type: "untested_path",
-                            entity: entity.name,
-                            file: entity.file_path,
-                            detail: `Exported ${entity.kind} "${entity.name}" has no test references`,
-                            impact: "Regression risk — no test coverage",
-                        });
-                    }
-                }
-            }
-        }
-        return items;
-    }
-    async findImportersOf(filePath) {
-        if (!this.graph)
-            return [];
-        const entities = await this.graph.getEntitiesByFile(filePath);
-        const importerFiles = new Set();
-        for (const entity of entities) {
-            const callers = await this.graph.getCallersOf(entity.key);
-            for (const caller of callers) {
-                if (caller.file_path !== filePath) {
-                    importerFiles.add(caller.file_path);
-                }
-            }
-        }
-        return [...importerFiles];
-    }
-    async hasTestReference(entity) {
-        if (!this.graph)
-            return false;
-        const callers = await this.graph.getCallersOf(entity.key);
-        return callers.some((c) => isTestFile(c.file_path));
-    }
-    persistItems(items) {
-        if (!this.unerrDir)
-            return false;
-        try {
-            const stateDir = join(this.unerrDir, "state");
-            if (!existsSync(stateDir))
-                mkdirSync(stateDir, { recursive: true });
-            const filePath = join(stateDir, PERSISTENCE_FILE);
-            writeFileSync(filePath, JSON.stringify({
-                timestamp: new Date().toISOString(),
-                items,
-            }), "utf-8");
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-    /**
-     * Read persisted incomplete items from the previous session.
-     * Used by Session Continuity (BA-1.2).
-     */
-    static readPersistedItems(unerrDir) {
-        try {
-            const filePath = join(unerrDir, "state", PERSISTENCE_FILE);
-            if (!existsSync(filePath))
-                return [];
-            const data = JSON.parse(readFileSync(filePath, "utf-8"));
-            return data.items ?? [];
-        }
-        catch {
-            return [];
-        }
-    }
-}
-function severityRank(severity) {
-    switch (severity) {
-        case "high":
-            return 0;
-        case "medium":
-            return 1;
-        case "low":
-            return 2;
-    }
-}
-const TEST_FILE_PATTERNS = [
-    /\.test\.[jt]sx?$/,
-    /\.spec\.[jt]sx?$/,
-    /__tests__\//,
-    /test\//,
-    /tests\//,
-];
-const EDIT_TOOLS = new Set([
-    "file_write",
-    "write_file",
-    "edit_file",
-    "str_replace_editor",
-    "insert_code",
-    "replace_code",
-    "sync_local_diff",
-]);
-function isTestFile(filePath) {
-    return TEST_FILE_PATTERNS.some((p) => p.test(filePath));
-}
-function isEditTool(toolName) {
-    return EDIT_TOOLS.has(toolName);
-}
-function extractPathFromArgs(args) {
-    if (typeof args.path === "string")
-        return args.path;
-    if (typeof args.file_path === "string")
-        return args.file_path;
-    if (typeof args.file === "string")
-        return args.file;
-    if (typeof args.key === "string" && args.key.includes("/")) {
-        return args.key.includes("::") ? args.key.split("::")[0] : args.key;
-    }
-    return null;
-}

package/dist/behaviors/loop-breaker.js

@@ -1,300 +0,0 @@
-/**
- * Loop Detection & Cost Circuit Breaker — BA-1.1
- *
- * Monitors every tool call in real-time via a per-entity ring buffer.
- * Detects 3 stuck-loop patterns:
- *   1. Repetitive failure — same approach with minor variations
- *   2. Context poisoning — wrong assumption contaminates reasoning
- *   3. Over-planning — long reasoning, no converging action
- *
- * Circuit breaker states: CLOSED → OPEN → HALF_OPEN
- *   CLOSED: normal operation
- *   OPEN: halted — no further attempts on this entity for cooldown period
- *   HALF_OPEN: one retry allowed after cooldown expires
- *
- * TDD exemption: test file modifications are excluded from entity-retry count.
- * $0.50 gate: guard moment only fires when estimated savings > $0.50.
- */
-import { calculateDollarSavings, formatDollars, } from "../proxy/model-pricing.js";
-import { Behavior, estimateWastedTokens, evaluateGate, } from "./framework.js";
-const RING_BUFFER_SIZE = 20;
-const DEFAULT_MAX_FAILURES = 4;
-const DEFAULT_COOLDOWN_MS = 60_000;
-const AVG_TOKENS_PER_FAILED_ATTEMPT = 8_000;
-const EXPECTED_REMAINING_MULTIPLIER = 10;
-const TEST_FILE_PATTERNS = [
-    /\.test\.[jt]sx?$/,
-    /\.spec\.[jt]sx?$/,
-    /__tests__\//,
-    /test\//,
-    /tests\//,
-];
-export class LoopCircuitBreaker extends Behavior {
-    id = "loop_circuit_breaker";
-    hooks = ["pre_tool_use", "post_tool_use"];
-    defaultLevel = "enforcement";
-    circuits = new Map();
-    loopsPrevented = 0;
-    totalTokensSaved = 0;
-    breakerConfig;
-    constructor(config) {
-        super(config, "enforcement");
-        this.breakerConfig = {
-            enabled: true,
-            level: "enforcement",
-            maxAttemptsPerEntity: DEFAULT_MAX_FAILURES,
-            cooldownMs: DEFAULT_COOLDOWN_MS,
-            ...config,
-        };
-    }
-    /**
-     * PreToolUse: check if entity is in OPEN state (circuit tripped).
-     * If HALF_OPEN, allow one retry and watch the result.
-     */
-    async onPreToolUse(ctx) {
-        const entityKey = ctx.entityKey;
-        if (!entityKey)
-            return null;
-        if (isTestFile(ctx.filePath))
-            return null;
-        const circuit = this.circuits.get(entityKey);
-        if (!circuit)
-            return null;
-        if (circuit.state === "open") {
-            const elapsed = Date.now() - circuit.openedAt;
-            if (elapsed >= this.breakerConfig.cooldownMs) {
-                circuit.state = "half_open";
-                return null;
-            }
-            const remainingMs = this.breakerConfig.cooldownMs - elapsed;
-            return {
-                behaviorId: this.id,
-                level: "enforcement",
-                halt: true,
-                _meta: {
-                    behavior: this.id,
-                    loops_prevented_session: this.loopsPrevented,
-                    tokens_saved: this.totalTokensSaved,
-                    dollars_saved: formatDollars(calculateDollarSavings(this.totalTokensSaved, ctx.modelId)),
-                },
-                _context: {
-                    halt: true,
-                    reason: `Circuit breaker OPEN for "${entityKey}" — ${circuit.attempts.length} consecutive failed attempts detected`,
-                    pattern: circuit.detectedPattern,
-                    cooldown_remaining_s: Math.ceil(remainingMs / 1000),
-                    suggestion: "Wait for cooldown or try a fundamentally different approach on a different entity.",
-                },
-            };
-        }
-        return null;
-    }
-    /**
-     * PostToolUse: record attempt outcome, detect patterns, trip breaker.
-     */
-    async onPostToolUse(ctx) {
-        const entityKey = ctx.entityKey;
-        if (!entityKey)
-            return null;
-        if (isTestFile(ctx.filePath))
-            return null;
-        const attempt = {
-            toolName: ctx.toolName,
-            filePath: ctx.filePath ?? "",
-            entityKey,
-            timestamp: Date.now(),
-            hasError: detectError(ctx.result),
-            argFingerprint: fingerprint(ctx.args),
-            resultFingerprint: fingerprint(ctx.result),
-        };
-        if (!this.circuits.has(entityKey)) {
-            this.circuits.set(entityKey, {
-                state: "closed",
-                attempts: [],
-                openedAt: 0,
-                detectedPattern: null,
-                totalTokensWasted: 0,
-            });
-        }
-        const circuit = this.circuits.get(entityKey);
-        circuit.attempts.push(attempt);
-        if (circuit.attempts.length > RING_BUFFER_SIZE) {
-            circuit.attempts.shift();
-        }
-        if (circuit.state === "half_open") {
-            if (attempt.hasError) {
-                circuit.state = "open";
-                circuit.openedAt = Date.now();
-                return null;
-            }
-            circuit.state = "closed";
-            circuit.detectedPattern = null;
-            return null;
-        }
-        if (circuit.state !== "closed")
-            return null;
-        const detection = this.detectStuckPattern(circuit);
-        if (!detection)
-            return null;
-        const failCount = detection.failedAttempts;
-        const estimatedFutureWaste = estimateWastedTokens(failCount * EXPECTED_REMAINING_MULTIPLIER, AVG_TOKENS_PER_FAILED_ATTEMPT);
-        const totalWasted = failCount * AVG_TOKENS_PER_FAILED_ATTEMPT;
-        const gate = evaluateGate(estimatedFutureWaste, `Loop detected: ${failCount} consecutive failures on ${entityKey} (${detection.pattern})`, ctx.modelId, entityKey);
-        if (!gate.passes)
-            return null;
-        circuit.state = "open";
-        circuit.openedAt = Date.now();
-        circuit.detectedPattern = detection.pattern;
-        circuit.totalTokensWasted += totalWasted;
-        this.loopsPrevented++;
-        this.totalTokensSaved += estimatedFutureWaste;
-        return {
-            behaviorId: this.id,
-            level: "enforcement",
-            halt: true,
-            guardMoment: gate.guardMoment,
-            _meta: {
-                behavior: this.id,
-                loops_prevented_session: this.loopsPrevented,
-                tokens_saved: this.totalTokensSaved,
-                dollars_saved: formatDollars(calculateDollarSavings(this.totalTokensSaved, ctx.modelId)),
-            },
-            _context: {
-                halt: true,
-                reason: `${failCount} consecutive failed attempts on ${entityKey}`,
-                pattern: detection.pattern,
-                attempts_summary: detection.summaries,
-                root_cause_hint: detection.hint,
-                suggestion: detection.suggestion,
-            },
-        };
-    }
-    getSessionStats() {
-        let openCount = 0;
-        for (const c of this.circuits.values()) {
-            if (c.state === "open")
-                openCount++;
-        }
-        return {
-            loopsPrevented: this.loopsPrevented,
-            totalTokensSaved: this.totalTokensSaved,
-            activeCircuits: this.circuits.size,
-            openCircuits: openCount,
-        };
-    }
-    getCircuitState(entityKey) {
-        return this.circuits.get(entityKey)?.state ?? null;
-    }
-    detectStuckPattern(circuit) {
-        const attempts = circuit.attempts;
-        const threshold = this.breakerConfig.maxAttemptsPerEntity;
-        const recentFailures = this.getConsecutiveFailures(attempts);
-        if (recentFailures.length < threshold)
-            return null;
-        const pattern = this.classifyPattern(recentFailures);
-        const summaries = recentFailures
-            .slice(-threshold)
-            .map((a, i) => `Attempt ${i + 1}: ${a.toolName} on ${a.filePath.split("/").pop()} — ${a.hasError ? "error" : "no visible progress"}`);
-        return {
-            pattern: pattern.type,
-            failedAttempts: recentFailures.length,
-            summaries,
-            hint: pattern.hint,
-            suggestion: pattern.suggestion,
-        };
-    }
-    getConsecutiveFailures(attempts) {
-        const failures = [];
-        for (let i = attempts.length - 1; i >= 0; i--) {
-            if (!attempts[i]?.hasError)
-                break;
-            failures.unshift(attempts[i]);
-        }
-        return failures;
-    }
-    classifyPattern(failures) {
-        if (failures.length < 2) {
-            return {
-                type: "repetitive_failure",
-                hint: "Repeated failures on the same entity.",
-                suggestion: "Step back and analyze the root cause before retrying.",
-            };
-        }
-        const fingerprints = failures.map((f) => f.argFingerprint);
-        const uniqueFingerprints = new Set(fingerprints).size;
-        const similarity = 1 - uniqueFingerprints / fingerprints.length;
-        if (similarity > 0.6) {
-            return {
-                type: "repetitive_failure",
-                hint: `All ${failures.length} attempts use similar arguments — the approach isn't changing meaningfully between retries.`,
-                suggestion: "Stop retrying the same approach. Examine the error output from attempt 1 and identify the root cause before acting.",
-            };
-        }
-        const resultFingerprints = failures.map((f) => f.resultFingerprint);
-        const uniqueResults = new Set(resultFingerprints).size;
-        if (uniqueResults === 1) {
-            return {
-                type: "context_poisoning",
-                hint: "Every attempt produces the exact same error — a wrong assumption is poisoning all reasoning.",
-                suggestion: "Discard your current hypothesis entirely. Re-read the original error message and the surrounding code with fresh eyes.",
-            };
-        }
-        const timespans = failures.map((f) => f.timestamp);
-        const totalTime = (timespans[timespans.length - 1] - timespans[0]) / 1000;
-        const avgTimePerAttempt = totalTime / failures.length;
-        if (avgTimePerAttempt > 15) {
-            return {
-                type: "over_planning",
-                hint: "Long gaps between attempts suggest extensive reasoning without convergence.",
-                suggestion: "Take the simplest possible action to test your hypothesis. Write a minimal reproduction first.",
-            };
-        }
-        return {
-            type: "repetitive_failure",
-            hint: `${failures.length} failed attempts with varied approaches — none resolved the underlying issue.`,
-            suggestion: "Step back. The issue may be in a dependency, mock, or configuration rather than in this entity.",
-        };
-    }
-}
-function isTestFile(filePath) {
-    if (!filePath)
-        return false;
-    return TEST_FILE_PATTERNS.some((p) => p.test(filePath));
-}
-function detectError(result) {
-    if (!result)
-        return true;
-    if (result.error)
-        return true;
-    if (result.isError === true)
-        return true;
-    if (typeof result.content === "string" &&
-        /error|fail|exception/i.test(result.content))
-        return true;
-    if (Array.isArray(result.content)) {
-        for (const item of result.content) {
-            if (typeof item === "object" &&
-                item !== null &&
-                "type" in item &&
-                "text" in item) {
-                const text = item.text;
-                if (/error|fail|exception/i.test(text))
-                    return true;
-            }
-        }
-    }
-    return false;
-}
-function fingerprint(obj) {
-    if (!obj)
-        return "empty";
-    const keys = Object.keys(obj).sort();
-    const significant = keys.slice(0, 5).map((k) => {
-        const v = obj[k];
-        if (typeof v === "string")
-            return `${k}:${v.slice(0, 50)}`;
-        if (typeof v === "number" || typeof v === "boolean")
-            return `${k}:${v}`;
-        return `${k}:${typeof v}`;
-    });
-    return significant.join("|");
-}