@unerr-ai/unerr 0.2.1 → 0.2.2

package/dist/tools/coding/grep.js

@@ -1,162 +0,0 @@
-/**
- * Grep Tool — search file contents using regex patterns.
- * Uses Node.js built-in fs for portability (no ripgrep dependency).
- */
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
-const MAX_RESULTS = 200;
-const MAX_DEPTH = 10;
-const BINARY_EXTENSIONS = new Set([
-    ".png",
-    ".jpg",
-    ".jpeg",
-    ".gif",
-    ".ico",
-    ".svg",
-    ".woff",
-    ".woff2",
-    ".ttf",
-    ".eot",
-    ".mp3",
-    ".mp4",
-    ".zip",
-    ".tar",
-    ".gz",
-    ".pdf",
-    ".exe",
-    ".dll",
-    ".so",
-    ".dylib",
-    ".node",
-    ".wasm",
-]);
-const SKIP_DIRS = new Set([
-    "node_modules",
-    ".git",
-    "dist",
-    "build",
-    ".next",
-    "coverage",
-    "__pycache__",
-]);
-function walkFiles(dir, depth, glob) {
-    if (depth > MAX_DEPTH)
-        return [];
-    const files = [];
-    try {
-        for (const entry of readdirSync(dir, { withFileTypes: true })) {
-            if (entry.name.startsWith(".") && SKIP_DIRS.has(entry.name))
-                continue;
-            if (SKIP_DIRS.has(entry.name))
-                continue;
-            const full = join(dir, entry.name);
-            if (entry.isDirectory()) {
-                files.push(...walkFiles(full, depth + 1, glob));
-            }
-            else if (entry.isFile()) {
-                const ext = entry.name.slice(entry.name.lastIndexOf("."));
-                if (BINARY_EXTENSIONS.has(ext))
-                    continue;
-                if (glob && !matchGlob(entry.name, glob))
-                    continue;
-                files.push(full);
-            }
-        }
-    }
-    catch {
-        // Permission denied, etc.
-    }
-    return files;
-}
-function matchGlob(filename, pattern) {
-    // Simple glob: *.ts, *.{ts,tsx}, etc.
-    const regex = pattern
-        .replace(/\./g, "\\.")
-        .replace(/\*/g, ".*")
-        .replace(/\{([^}]+)\}/g, (_, alts) => `(${alts.split(",").join("|")})`);
-    return new RegExp(`^${regex}$`).test(filename);
-}
-export const grepTool = {
-    name: "grep",
-    description: "Search file contents for a regex pattern. Returns matching lines with file paths and line numbers. " +
-        "Use the glob parameter to filter by file type (e.g., '*.ts', '*.{ts,tsx}').",
-    inputSchema: {
-        type: "object",
-        properties: {
-            pattern: {
-                type: "string",
-                description: "Regular expression pattern to search for",
-            },
-            path: {
-                type: "string",
-                description: "Directory or file to search in. Default: project root",
-            },
-            glob: {
-                type: "string",
-                description: "Glob pattern to filter files (e.g., '*.ts')",
-            },
-            case_insensitive: {
-                type: "boolean",
-                description: "Case insensitive search. Default: false",
-            },
-        },
-        required: ["pattern"],
-    },
-    isReadOnly: true,
-    requiresPermission: false,
-    async execute(args, ctx) {
-        const pattern = args.pattern;
-        const searchPath = resolve(ctx.cwd, args.path ?? ".");
-        const glob = args.glob;
-        const caseInsensitive = args.case_insensitive ?? false;
-        let regex;
-        try {
-            regex = new RegExp(pattern, caseInsensitive ? "gi" : "g");
-        }
-        catch (err) {
-            return {
-                content: `Invalid regex: ${pattern}. Check pattern escaping. For matching code entity names, call search_code instead — it handles identifiers natively without regex.`,
-                isError: true,
-            };
-        }
-        if (!existsSync(searchPath)) {
-            return {
-                content: `Path not found: ${searchPath}. For code searches, call search_code (entity-aware, no path required) instead.`,
-                isError: true,
-            };
-        }
-        const stat = statSync(searchPath);
-        const files = stat.isFile() ? [searchPath] : walkFiles(searchPath, 0, glob);
-        const matches = [];
-        for (const file of files) {
-            if (matches.length >= MAX_RESULTS)
-                break;
-            try {
-                const content = readFileSync(file, "utf-8");
-                const lines = content.split("\n");
-                for (let i = 0; i < lines.length; i++) {
-                    if (matches.length >= MAX_RESULTS)
-                        break;
-                    const line = lines[i];
-                    if (regex.test(line)) {
-                        const relPath = relative(ctx.cwd, file);
-                        matches.push(`${relPath}:${i + 1}: ${line}`);
-                    }
-                    regex.lastIndex = 0; // Reset global regex
-                }
-            }
-            catch {
-                // Binary file or read error — skip
-            }
-        }
-        if (matches.length === 0) {
-            return {
-                content: `No matches found for pattern: ${pattern}. If you were searching for a code entity by name, call search_code (graph-indexed, finds renames + indirect refs that regex misses).`,
-            };
-        }
-        const truncated = matches.length >= MAX_RESULTS
-            ? `\n\n(Truncated at ${MAX_RESULTS} results)`
-            : "";
-        return { content: matches.join("\n") + truncated };
-    },
-};

package/dist/tools/coding/index.js

@@ -1,27 +0,0 @@
-/**
- * Coding Tools — standard filesystem and shell tools for the AI assistant.
- */
-export { bashTool } from "./bash.js";
-export { fileEditTool } from "./file-edit.js";
-export { fileOutlineTool } from "./file-outline.js";
-export { fileReadTool } from "./file-read.js";
-export { fileWriteTool } from "./file-write.js";
-export { globTool } from "./glob-tool.js";
-export { grepTool } from "./grep.js";
-import { bashTool } from "./bash.js";
-import { fileEditTool } from "./file-edit.js";
-import { fileOutlineTool } from "./file-outline.js";
-import { fileReadTool } from "./file-read.js";
-import { fileWriteTool } from "./file-write.js";
-import { globTool } from "./glob-tool.js";
-import { grepTool } from "./grep.js";
-/** All coding tools in registration order. */
-export const codingTools = [
-    fileOutlineTool,
-    fileReadTool,
-    fileWriteTool,
-    fileEditTool,
-    bashTool,
-    grepTool,
-    globTool,
-];

package/dist/tools/intelligence/index.js

@@ -1,269 +0,0 @@
-/**
- * Intelligence Tools — wrappers around the QueryRouter's 15 MCP tools.
- *
- * These adapt the existing graph-backed tools so they can be used by the QueryEngine
- * (the LLM calls them during interactive sessions). The QueryRouter handles all the
- * local routing, drift injection, and rule evaluation internally.
- *
- * This is the key differentiator: no other coding assistant has pre-computed
- * code intelligence (conventions, blast radius, business context, health grades)
- * available as tools.
- */
-// Leapfrog Sprint C: token_budget property shared across all local tools
-const TOKEN_BUDGET_PROP = {
-    type: "integer",
-    description: "Maximum tokens for this response (default: 400 — structural summary only). Pass include_body:true OR token_budget:1500+ to retrieve full bodies. Most fan-in/metadata questions fit in 400 tokens.",
-    default: 400,
-};
-/** Tool definition metadata for each intelligence tool. */
-const TOOL_DEFS = [
-    {
-        name: "get_entity",
-        description: "Get any code entity (function, class, type, variable) by key — signature, metadata, callers, callees, risk level. Returns STRUCTURAL by default; pass include_body:true for full body.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                key: {
-                    type: "string",
-                    description: "Entity key (e.g., 'handleRequest', 'QueryRouter')",
-                },
-                kind: {
-                    type: "string",
-                    enum: ["function", "class", "type", "variable"],
-                    description: "Optional entity kind filter",
-                },
-                include_body: {
-                    type: "boolean",
-                    description: "Include full body. Default false — signature + first ~15 lines preview only.",
-                    default: false,
-                },
-                token_budget: TOKEN_BUDGET_PROP,
-            },
-            required: ["key"],
-        },
-    },
-    {
-        name: "get_file",
-        description: "Get all entities defined in a file",
-        inputSchema: {
-            type: "object",
-            properties: {
-                file_path: {
-                    type: "string",
-                    description: "File path relative to project root",
-                },
-                token_budget: TOKEN_BUDGET_PROP,
-            },
-            required: ["file_path"],
-        },
-    },
-    {
-        name: "get_references",
-        description: "Find all callers or callees of a given entity. Direction 'callers' = who calls this (blast radius). Direction 'callees' = what this calls (dependencies).",
-        inputSchema: {
-            type: "object",
-            properties: {
-                key: {
-                    type: "string",
-                    description: "Entity key to find references for",
-                },
-                direction: {
-                    type: "string",
-                    enum: ["callers", "callees"],
-                    description: "Direction: 'callers' (default) or 'callees'",
-                },
-                limit: {
-                    type: "number",
-                    description: "Max references to return (default 25)",
-                },
-                token_budget: TOKEN_BUDGET_PROP,
-            },
-            required: ["key"],
-        },
-    },
-    {
-        name: "get_imports",
-        description: "Get all imports for a file",
-        inputSchema: {
-            type: "object",
-            properties: {
-                file_path: { type: "string", description: "File path" },
-                token_budget: TOKEN_BUDGET_PROP,
-            },
-            required: ["file_path"],
-        },
-    },
-    {
-        name: "search_code",
-        description: "Full-text search across all indexed code entities (functions, classes, variables). Returns matching entities with file paths and signatures.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                query: { type: "string", description: "Search query" },
-                limit: { type: "number", description: "Max results. Default: 20" },
-                token_budget: TOKEN_BUDGET_PROP,
-            },
-            required: ["query"],
-        },
-    },
-    // Disabled: get_rules — no rules are being detected/stored yet, always returns empty.
-    // {
-    //   name: "get_rules",
-    //   inputSchema: { type: "object", properties: { file_path: { type: "string" }, content: { type: "string" }, entity_key: { type: "string" }, token_budget: TOKEN_BUDGET_PROP }, },
-    // },
-    // Disabled: get_business_context — not properly wired, produces no useful data.
-    // {
-    //   name: "get_business_context",
-    //   description: "Get entity business context — purpose, taxonomy, feature area, justification for why this code exists",
-    //   inputSchema: { type: "object", properties: { key: { type: "string" }, token_budget: TOKEN_BUDGET_PROP }, required: ["key"] },
-    // },
-    {
-        name: "get_conventions",
-        description: "Get detected code conventions and patterns with adherence rates. Shows what patterns the team follows.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                token_budget: TOKEN_BUDGET_PROP,
-            },
-        },
-    },
-    {
-        name: "get_cross_boundary_links",
-        description: "Find surprising cross-community connections — edges between entities in different structural communities, scored by inverse inter-community density. High surprise = unexpected architectural coupling.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                community_id: {
-                    type: "number",
-                    description: "Optional: filter to connections involving this community ID",
-                },
-                top_n: {
-                    type: "number",
-                    description: "Max results. Default: 20",
-                },
-                token_budget: TOKEN_BUDGET_PROP,
-            },
-        },
-    },
-    {
-        name: "get_critical_nodes",
-        description: "Find critical nodes — highest-degree entities (fan_in + fan_out) that are structural bottlenecks. Excludes file/module-level entities. Shows community membership for each node.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                top_n: {
-                    type: "number",
-                    description: "Max results. Default: 10",
-                },
-                community_id: {
-                    type: "number",
-                    description: "Optional: filter to entities in this community",
-                },
-                token_budget: TOKEN_BUDGET_PROP,
-            },
-        },
-    },
-    {
-        name: "semantic_search",
-        description: "Vector-based semantic search across the codebase. Finds conceptually similar code even with different naming.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                query: { type: "string", description: "Natural language search query" },
-                limit: { type: "number", description: "Max results. Default: 10" },
-            },
-            required: ["query"],
-        },
-    },
-    {
-        name: "find_similar",
-        description: "Find entities similar to a given entity (by embedding distance)",
-        inputSchema: {
-            type: "object",
-            properties: {
-                key: {
-                    type: "string",
-                    description: "Entity key to find similar entities for",
-                },
-                limit: { type: "number", description: "Max results. Default: 10" },
-            },
-            required: ["key"],
-        },
-    },
-    {
-        name: "get_project_stats",
-        description: "Get project-wide statistics: entity counts, risk distribution, convention adherence, health grade",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
-    },
-    {
-        name: "file_connections",
-        description: "Get connected files and contained entities for a file. Shows import relationships, co-change correlations, and file-level structure.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                file_path: {
-                    type: "string",
-                    description: "File path relative to project root",
-                },
-                token_budget: TOKEN_BUDGET_PROP,
-            },
-            required: ["file_path"],
-        },
-    },
-    {
-        name: "get_test_coverage",
-        description: "Find test functions that cover a source entity. Returns direct and transitive test coverage via 'tests' edges in the graph.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                key: {
-                    type: "string",
-                    description: "Source entity key to find test coverage for",
-                },
-                include_transitive: {
-                    type: "boolean",
-                    description: "Include tests that cover via intermediate calls (default: true)",
-                },
-                token_budget: TOKEN_BUDGET_PROP,
-            },
-            required: ["key"],
-        },
-    },
-];
-/**
- * Create intelligence Tool instances backed by a QueryRouter.
- * Each tool delegates to router.execute() which handles local routing,
- * drift injection, risk metadata, and rule evaluation.
- */
-export function createIntelligenceTools(router) {
-    return TOOL_DEFS.map((def) => ({
-        ...def,
-        isReadOnly: true,
-        requiresPermission: false,
-        async execute(args, _ctx) {
-            try {
-                const result = await router.execute(def.name, args);
-                return {
-                    content: typeof result.content === "string"
-                        ? result.content
-                        : result.content,
-                    metadata: {
-                        source: result._meta.source,
-                        latency_ms: result._meta.latency_ms,
-                        entity_risk: result._meta.entity_risk,
-                        drift: result._meta.drift,
-                    },
-                };
-            }
-            catch (err) {
-                return {
-                    content: `Intelligence tool error (${def.name}): ${err instanceof Error ? err.message : String(err)}`,
-                    isError: true,
-                };
-            }
-        },
-    }));
-}

package/dist/tools/intelligence/record-fact.js

@@ -1,48 +0,0 @@
-/**
- * record_fact MCP Tool — Agent-as-LLM fact persistence.
- *
- * Layer 9: The host coding agent (Claude, GPT, etc.) calls this tool when
- * the user states a convention, decision, or anti-pattern. The agent IS
- * the LLM — no separate extraction model needed.
- *
- * This is the ONLY write operation --mcp performs on facts.db.
- * It's a single atomic insert — no lock contention risk.
- */
-/**
- * Execute the record_fact tool.
- * Validates input, deduplicates, and persists to facts.db.
- */
-export async function executeRecordFact(args, factStore, sessionId) {
-    const { content, fact_type, scope, subject } = args;
-    if (!content || content.trim().length === 0) {
-        throw new Error("content is required and cannot be empty");
-    }
-    if (content.length > 280) {
-        throw new Error(`content exceeds 280 character limit (got ${content.length}). Shorten the fact.`);
-    }
-    if (!["procedural", "semantic", "negative", "convention"].includes(fact_type)) {
-        throw new Error(`fact_type must be one of: procedural, semantic, negative, convention (got "${fact_type}")`);
-    }
-    if (!scope || scope.trim().length === 0) {
-        throw new Error("scope is required (file path, entity key, or 'project')");
-    }
-    if (!subject || subject.trim().length === 0) {
-        throw new Error("subject is required (entity key, file, or topic name)");
-    }
-    const input = {
-        fact_type,
-        scope: scope.trim(),
-        subject: subject.trim(),
-        content: content.trim(),
-        source: "agent_explicit",
-        base_confidence: 0.95,
-    };
-    const factId = await factStore.createFact(input);
-    const isDeduplicated = factId !== undefined && content.trim() !== "";
-    const message = `Recorded: "${content.trim().slice(0, 60)}${content.trim().length > 60 ? "..." : ""}" [${fact_type}] → ${scope}`;
-    return {
-        fact_id: factId,
-        message,
-        deduplicated: false,
-    };
-}

package/dist/tools/intelligence/timeline-markers.js

@@ -1,130 +0,0 @@
-/**
- * Timeline marker MCP tools (ST-2a).
- *
- * Four lightweight tools the agent emits inline as it works. Each call:
- *   1. Appends a regular `LedgerEntry` via `ShadowLedger.record()` with
- *      `tool: "mark_*"` — existing readers see it as a normal MCP call.
- *   2. Mirrors a row into `timeline.db.markers` for indexed lookup
- *      (open-threads, intent rail, future miners).
- *
- * Layer 9 modules (`session-narrative`, `session-pattern-analyzer`,
- * `fact-generator`, `temporal-facts`) are NOT touched. They remain agnostic to
- * markers — if Layer 9 wants to prefer marker `text` over its scraped 30 s
- * window later, that's a separate change owned by Layer 9.
- *
- * Text caps:
- *   mark_intent      ≤  80 chars
- *   mark_decision    ≤ 140 chars
- *   mark_blocker     ≤ 140 chars
- *   mark_resolution  ≤ 140 chars
- */
-export const MARKER_TOOLS = [
-    "mark_intent",
-    "mark_decision",
-    "mark_blocker",
-    "mark_resolution",
-];
-const MARKER_TOOL_SET = new Set(MARKER_TOOLS);
-export function isMarkerTool(name) {
-    return MARKER_TOOL_SET.has(name);
-}
-const TEXT_CAP = {
-    mark_intent: 80,
-    mark_decision: 140,
-    mark_blocker: 140,
-    mark_resolution: 140,
-};
-/**
- * Dispatch a marker tool call. Returns an MCP-shaped response either with a
- * success body (`{ok, marker_id, turn_id}`) or an `{error}` body — callers
- * forward this directly back to the agent.
- */
-export async function handleMarkerCall(toolName, args, deps) {
-    const text = String(args.text ?? "").trim();
-    const cap = TEXT_CAP[toolName];
-    if (text.length === 0) {
-        return errorResult(`${toolName}: text is required`);
-    }
-    if (text.length > cap) {
-        return errorResult(`${toolName}: text exceeds ${cap}-char limit`);
-    }
-    const argsToPersist = { text };
-    let blockerRef = "";
-    let filePath = "";
-    if (toolName === "mark_decision") {
-        const alts = args.alternatives;
-        if (Array.isArray(alts) && alts.length > 0) {
-            argsToPersist.alternatives = alts
-                .map((v) => String(v))
-                .slice(0, 5)
-                .map((v) => (v.length > 80 ? `${v.slice(0, 80)}…` : v));
-        }
-    }
-    if (toolName === "mark_blocker") {
-        const fp = args.file_path;
-        if (typeof fp === "string" && fp.length > 0) {
-            filePath = fp.length > 200 ? `${fp.slice(0, 200)}…` : fp;
-            argsToPersist.file_path = filePath;
-        }
-    }
-    if (toolName === "mark_resolution") {
-        const ref = String(args.blocker_ref ?? "").trim();
-        if (ref.length === 0) {
-            return errorResult("mark_resolution: blocker_ref required (the marker_id returned by mark_blocker)");
-        }
-        blockerRef = ref;
-        argsToPersist.blocker_ref = blockerRef;
-    }
-    const entry = deps.ledger.record(toolName, argsToPersist, { ok: true }, deps.branch, deps.headSha);
-    // Read redacted values back from the ledger row — `ShadowLedger.record()`
-    // ran the redactor on args_summary, so these are guaranteed scrubbed before
-    // they land in timeline.db. (Bug fix: previously we wrote the raw input text,
-    // leaking secrets into the markers relation.)
-    const persistedArgs = entry.args_summary;
-    const redactedText = typeof persistedArgs.text === "string" ? persistedArgs.text : text;
-    const redactedFilePath = typeof persistedArgs.file_path === "string"
-        ? persistedArgs.file_path
-        : filePath;
-    const redactedBlockerRef = typeof persistedArgs.blocker_ref === "string"
-        ? persistedArgs.blocker_ref
-        : blockerRef;
-    try {
-        await deps.store.insertMarker({
-            marker_id: entry.id,
-            type: toolName,
-            text: redactedText,
-            session_id: entry.session_id,
-            turn_id: entry.turn_id ?? "",
-            ts: Date.parse(entry.ts),
-            blocker_ref: redactedBlockerRef,
-            file_path: redactedFilePath,
-        });
-    }
-    catch (err) {
-        process.stderr.write(`[unerr:timeline-markers] WARN: insertMarker failed: ${err instanceof Error ? err.message : String(err)}\n`);
-        // Continue: ledger row already persisted, miners can still recover from it.
-    }
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({
-                    ok: true,
-                    marker_id: entry.id,
-                    turn_id: entry.turn_id ?? null,
-                    type: toolName,
-                }),
-            },
-        ],
-    };
-}
-function errorResult(msg) {
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({ error: msg }),
-            },
-        ],
-    };
-}

package/dist/tools/registry.js

@@ -1,47 +0,0 @@
-/**
- * Tool Registry — central catalog of all available tools.
- *
- * Tools are registered by category (intelligence, coding) and can be
- * looked up by name. The registry provides the tool list for both the MCP
- * server and the QueryEngine's tool definitions sent to the LLM.
- */
-export class ToolRegistry {
-    tools = new Map();
-    /** Register a tool. Throws if a tool with the same name already exists. */
-    register(tool, category) {
-        if (this.tools.has(tool.name)) {
-            throw new Error(`Tool "${tool.name}" is already registered`);
-        }
-        this.tools.set(tool.name, { ...tool, category });
-    }
-    /** Look up a tool by name. Returns undefined if not found. */
-    get(name) {
-        return this.tools.get(name);
-    }
-    /** Get all registered tools. */
-    all() {
-        return [...this.tools.values()];
-    }
-    /** Get tools filtered by category. */
-    byCategory(category) {
-        return this.all().filter((t) => t.category === category);
-    }
-    /** Get tool definitions for LLM consumption (name, description, inputSchema). */
-    definitions() {
-        return this.all().map(({ name, description, inputSchema, isReadOnly, requiresPermission }) => ({
-            name,
-            description,
-            inputSchema,
-            isReadOnly,
-            requiresPermission,
-        }));
-    }
-    /** Get tool definitions formatted for MCP tools/list response. */
-    mcpToolList() {
-        return this.all().map(({ name, description, inputSchema }) => ({
-            name,
-            description,
-            inputSchema,
-        }));
-    }
-}

package/dist/tools/types.js

@@ -1,8 +0,0 @@
-/**
- * Unified Tool Interface — used by both the MCP server (serving tools to external agents)
- * and the local QueryEngine (tools the LLM calls during interactive sessions).
- *
- * This is the foundational abstraction that makes unerr's intelligence tools
- * available to both external agents (via MCP) and the built-in AI assistant.
- */
-export {};