@martinloop/mcp 0.3.6 → 0.3.8

package/dist/vendor/adapters/core/src/repo-analyzer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Repo Style Analyzer
+ *
+ * Scans a repository to detect coding conventions, patterns, and style
+ * so that governed agent runs produce code matching the existing codebase.
+ *
+ * Detects:
+ * - Naming conventions (camelCase, snake_case, PascalCase, kebab-case)
+ * - Test framework (Vitest, Jest, Mocha, node:test)
+ * - Package manager (pnpm, npm, yarn, bun)
+ * - Module system (ESM, CJS, mixed)
+ * - File organization pattern (feature folders, type folders, flat)
+ * - TypeScript strictness level
+ * - Comment density
+ * - Formatting (tabs vs spaces, semicolons, quotes)
+ */
+export interface RepoStyleProfile {
+    /** Detected package manager */
+    packageManager: "pnpm" | "npm" | "yarn" | "bun" | "unknown";
+    /** Detected module system */
+    moduleSystem: "esm" | "cjs" | "mixed" | "unknown";
+    /** Detected test framework */
+    testFramework: "vitest" | "jest" | "mocha" | "node-test" | "unknown";
+    /** Primary language */
+    language: "typescript" | "javascript" | "mixed";
+    /** TypeScript strict mode enabled */
+    typescriptStrict: boolean;
+    /** Dominant naming convention for files */
+    fileNaming: "kebab-case" | "camelCase" | "PascalCase" | "snake_case" | "mixed";
+    /** Dominant naming convention for variables/functions */
+    codeNaming: "camelCase" | "snake_case" | "mixed";
+    /** Uses semicolons */
+    semicolons: boolean;
+    /** Single vs double quotes */
+    quotes: "single" | "double" | "mixed";
+    /** Indentation style */
+    indentation: "tabs" | "2-spaces" | "4-spaces" | "mixed";
+    /** Average lines per file (source files) */
+    avgLinesPerFile: number;
+    /** File organization pattern */
+    organization: "feature-folders" | "type-folders" | "flat" | "mixed";
+    /** Raw signals for prompt injection */
+    promptDirectives: string[];
+}
+/**
+ * Analyze a repository and return a style profile.
+ */
+export declare function analyzeRepoStyle(rootDir: string): RepoStyleProfile;
+/**
+ * Build prompt directives from the style profile.
+ * These get injected into the agent's prompt to match repo conventions.
+ */
+export declare function buildPromptDirectives(profile: RepoStyleProfile): string[];

package/dist/vendor/adapters/core/src/repo-analyzer.js

@@ -0,0 +1,263 @@
+/**
+ * Repo Style Analyzer
+ *
+ * Scans a repository to detect coding conventions, patterns, and style
+ * so that governed agent runs produce code matching the existing codebase.
+ *
+ * Detects:
+ * - Naming conventions (camelCase, snake_case, PascalCase, kebab-case)
+ * - Test framework (Vitest, Jest, Mocha, node:test)
+ * - Package manager (pnpm, npm, yarn, bun)
+ * - Module system (ESM, CJS, mixed)
+ * - File organization pattern (feature folders, type folders, flat)
+ * - TypeScript strictness level
+ * - Comment density
+ * - Formatting (tabs vs spaces, semicolons, quotes)
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, extname } from "node:path";
+/**
+ * Analyze a repository and return a style profile.
+ */
+export function analyzeRepoStyle(rootDir) {
+    const profile = {
+        packageManager: detectPackageManager(rootDir),
+        moduleSystem: detectModuleSystem(rootDir),
+        testFramework: detectTestFramework(rootDir),
+        language: detectLanguage(rootDir),
+        typescriptStrict: detectTypeScriptStrict(rootDir),
+        fileNaming: "kebab-case",
+        codeNaming: "camelCase",
+        semicolons: true,
+        quotes: "double",
+        indentation: "2-spaces",
+        avgLinesPerFile: 0,
+        organization: "mixed",
+        promptDirectives: []
+    };
+    // Sample source files for style detection
+    const sourceFiles = collectSourceFiles(rootDir, 50);
+    if (sourceFiles.length > 0) {
+        const styleSignals = analyzeSourceFiles(sourceFiles);
+        profile.fileNaming = styleSignals.fileNaming;
+        profile.codeNaming = styleSignals.codeNaming;
+        profile.semicolons = styleSignals.semicolons;
+        profile.quotes = styleSignals.quotes;
+        profile.indentation = styleSignals.indentation;
+        profile.avgLinesPerFile = styleSignals.avgLinesPerFile;
+    }
+    profile.organization = detectOrganization(rootDir);
+    profile.promptDirectives = buildPromptDirectives(profile);
+    return profile;
+}
+function detectPackageManager(rootDir) {
+    if (existsSync(join(rootDir, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (existsSync(join(rootDir, "bun.lockb")) || existsSync(join(rootDir, "bun.lock")))
+        return "bun";
+    if (existsSync(join(rootDir, "yarn.lock")))
+        return "yarn";
+    if (existsSync(join(rootDir, "package-lock.json")))
+        return "npm";
+    return "unknown";
+}
+function detectModuleSystem(rootDir) {
+    const pkgPath = join(rootDir, "package.json");
+    if (!existsSync(pkgPath))
+        return "unknown";
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        if (pkg.type === "module")
+            return "esm";
+        if (pkg.type === "commonjs")
+            return "cjs";
+    }
+    catch { /* ignore */ }
+    return "unknown";
+}
+function detectTestFramework(rootDir) {
+    const pkgPath = join(rootDir, "package.json");
+    if (!existsSync(pkgPath))
+        return "unknown";
+    try {
+        const raw = readFileSync(pkgPath, "utf8");
+        if (raw.includes("vitest"))
+            return "vitest";
+        if (raw.includes("jest"))
+            return "jest";
+        if (raw.includes("mocha"))
+            return "mocha";
+        if (raw.includes("node:test"))
+            return "node-test";
+    }
+    catch { /* ignore */ }
+    if (existsSync(join(rootDir, "vitest.config.ts")) || existsSync(join(rootDir, "vitest.config.js")))
+        return "vitest";
+    if (existsSync(join(rootDir, "jest.config.ts")) || existsSync(join(rootDir, "jest.config.js")))
+        return "jest";
+    return "unknown";
+}
+function detectLanguage(rootDir) {
+    if (existsSync(join(rootDir, "tsconfig.json")) ||
+        existsSync(join(rootDir, "tsconfig.base.json")) ||
+        existsSync(join(rootDir, "tsconfig.build.json"))) {
+        return "typescript";
+    }
+    return "javascript";
+}
+function detectTypeScriptStrict(rootDir) {
+    const candidates = ["tsconfig.json", "tsconfig.base.json", "tsconfig.build.json"];
+    for (const candidate of candidates) {
+        const tsConfigPath = join(rootDir, candidate);
+        if (!existsSync(tsConfigPath))
+            continue;
+        try {
+            const raw = readFileSync(tsConfigPath, "utf8");
+            if (raw.includes('"strict": true') || raw.includes('"strict":true'))
+                return true;
+        }
+        catch { /* skip */ }
+    }
+    return false;
+}
+function collectSourceFiles(rootDir, limit) {
+    const results = [];
+    const extensions = new Set([".ts", ".tsx", ".js", ".jsx"]);
+    function walk(dir, depth) {
+        if (depth > 5 || results.length >= limit)
+            return;
+        try {
+            const entries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (results.length >= limit)
+                    return;
+                if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist")
+                    continue;
+                const fullPath = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    walk(fullPath, depth + 1);
+                }
+                else if (entry.isFile() && extensions.has(extname(entry.name))) {
+                    results.push(fullPath);
+                }
+            }
+        }
+        catch { /* skip */ }
+    }
+    walk(rootDir, 0);
+    return results;
+}
+function analyzeSourceFiles(files) {
+    let semiCount = 0;
+    let noSemiCount = 0;
+    let singleQuoteCount = 0;
+    let doubleQuoteCount = 0;
+    let tabCount = 0;
+    let twoSpaceCount = 0;
+    let fourSpaceCount = 0;
+    let totalLines = 0;
+    for (const filePath of files) {
+        try {
+            const content = readFileSync(filePath, "utf8");
+            const lines = content.split("\n");
+            totalLines += lines.length;
+            for (const line of lines.slice(0, 100)) {
+                if (line.trimEnd().endsWith(";"))
+                    semiCount++;
+                else if (line.trim().length > 0)
+                    noSemiCount++;
+                if (/'\w/.test(line))
+                    singleQuoteCount++;
+                if (/"\w/.test(line))
+                    doubleQuoteCount++;
+                if (line.startsWith("\t"))
+                    tabCount++;
+                else if (line.startsWith("  ") && !line.startsWith("    "))
+                    twoSpaceCount++;
+                else if (line.startsWith("    "))
+                    fourSpaceCount++;
+            }
+        }
+        catch { /* skip */ }
+    }
+    const semicolons = semiCount > noSemiCount;
+    const quotes = singleQuoteCount > doubleQuoteCount * 2 ? "single" :
+        doubleQuoteCount > singleQuoteCount * 2 ? "double" : "mixed";
+    const indentation = tabCount > twoSpaceCount + fourSpaceCount ? "tabs" :
+        twoSpaceCount > fourSpaceCount * 2 ? "2-spaces" :
+            fourSpaceCount > twoSpaceCount * 2 ? "4-spaces" : "mixed";
+    return {
+        fileNaming: "kebab-case", // Default, hard to detect reliably without more files
+        codeNaming: "camelCase", // TypeScript default
+        semicolons,
+        quotes,
+        indentation,
+        avgLinesPerFile: files.length > 0 ? Math.round(totalLines / files.length) : 0
+    };
+}
+function detectOrganization(rootDir) {
+    const srcDir = join(rootDir, "src");
+    if (!existsSync(srcDir))
+        return "flat";
+    try {
+        const entries = readdirSync(srcDir, { withFileTypes: true });
+        const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+        const hasFeatureDirs = dirs.some((d) => !["utils", "lib", "types", "helpers", "common", "shared", "__tests__", "tests"].includes(d));
+        const hasTypeDirs = dirs.some((d) => ["components", "hooks", "services", "models", "controllers", "routes", "middleware"].includes(d));
+        if (hasFeatureDirs && !hasTypeDirs)
+            return "feature-folders";
+        if (hasTypeDirs && !hasFeatureDirs)
+            return "type-folders";
+        if (hasFeatureDirs && hasTypeDirs)
+            return "mixed";
+    }
+    catch { /* skip */ }
+    return "flat";
+}
+/**
+ * Build prompt directives from the style profile.
+ * These get injected into the agent's prompt to match repo conventions.
+ */
+export function buildPromptDirectives(profile) {
+    const directives = [];
+    if (profile.language === "typescript") {
+        directives.push("Write TypeScript, not JavaScript.");
+        if (profile.typescriptStrict) {
+            directives.push("TypeScript strict mode is enabled. Use explicit types, avoid any.");
+        }
+    }
+    if (profile.moduleSystem === "esm") {
+        directives.push("Use ES module imports (import/export), not require().");
+    }
+    else if (profile.moduleSystem === "cjs") {
+        directives.push("Use CommonJS (require/module.exports), not ES module imports.");
+    }
+    if (profile.testFramework !== "unknown") {
+        directives.push(`Use ${profile.testFramework} for tests. Do not introduce a different test framework.`);
+    }
+    if (profile.semicolons) {
+        directives.push("Use semicolons at the end of statements.");
+    }
+    else {
+        directives.push("Do not use semicolons at the end of statements.");
+    }
+    if (profile.quotes === "single") {
+        directives.push("Use single quotes for strings.");
+    }
+    else if (profile.quotes === "double") {
+        directives.push("Use double quotes for strings.");
+    }
+    if (profile.indentation === "tabs") {
+        directives.push("Use tabs for indentation.");
+    }
+    else if (profile.indentation === "2-spaces") {
+        directives.push("Use 2-space indentation.");
+    }
+    else if (profile.indentation === "4-spaces") {
+        directives.push("Use 4-space indentation.");
+    }
+    if (profile.packageManager !== "unknown") {
+        directives.push(`This project uses ${profile.packageManager}. Do not use other package managers.`);
+    }
+    return directives;
+}

package/dist/vendor/adapters/core/src/rollback.d.ts

@@ -0,0 +1,15 @@
+import type { PatchDecision, RollbackBoundaryArtifact, RollbackOutcomeArtifact } from "../../../contracts/index.js";
+export declare function listAttemptChangedFilesSinceBoundary(input: {
+    repoRoot?: string;
+    boundary?: RollbackBoundaryArtifact;
+}): string[];
+export declare function captureRollbackBoundary(input: {
+    repoRoot?: string;
+    capturedAt: string;
+}): Promise<RollbackBoundaryArtifact | undefined>;
+export declare function restoreRollbackBoundary(input: {
+    repoRoot?: string;
+    boundary?: RollbackBoundaryArtifact;
+    restoredAt: string;
+    decision: PatchDecision;
+}): Promise<RollbackOutcomeArtifact | undefined>;

package/dist/vendor/adapters/core/src/rollback.js

@@ -0,0 +1,253 @@
+import { spawnSync } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+export function listAttemptChangedFilesSinceBoundary(input) {
+    if (!input.repoRoot) {
+        return [];
+    }
+    const repoState = readRepoState(input.repoRoot);
+    if (!input.boundary) {
+        return uniqueSorted([...repoState.trackedDirtyFiles, ...repoState.untrackedFiles]);
+    }
+    const baselineTracked = new Set(input.boundary.trackedDirtyFiles);
+    const baselineUntracked = new Set(input.boundary.untrackedFiles);
+    return uniqueSorted([
+        ...repoState.trackedDirtyFiles.filter((filePath) => !baselineTracked.has(filePath)),
+        ...repoState.untrackedFiles.filter((filePath) => !baselineUntracked.has(filePath))
+    ]);
+}
+export async function captureRollbackBoundary(input) {
+    if (!input.repoRoot) {
+        return undefined;
+    }
+    const repoState = readRepoState(input.repoRoot);
+    const snapshotPaths = uniqueSorted([
+        ...repoState.trackedDirtyFiles,
+        ...repoState.untrackedFiles
+    ]);
+    const snapshots = [];
+    for (const filePath of snapshotPaths) {
+        snapshots.push(await readRollbackSnapshot(input.repoRoot, filePath));
+    }
+    return {
+        strategy: "git_head_plus_snapshot",
+        capturedAt: input.capturedAt,
+        ...(readGitScalar(input.repoRoot, ["rev-parse", "HEAD"])
+            ? { headRef: readGitScalar(input.repoRoot, ["rev-parse", "HEAD"]) }
+            : {}),
+        trackedDirtyFiles: repoState.trackedDirtyFiles,
+        untrackedFiles: repoState.untrackedFiles,
+        snapshots
+    };
+}
+export async function restoreRollbackBoundary(input) {
+    if (!input.repoRoot) {
+        return undefined;
+    }
+    if (!input.boundary) {
+        return {
+            attempted: false,
+            status: "unavailable",
+            restoredAt: input.restoredAt,
+            decision: input.decision,
+            before: emptyRepoState(),
+            after: emptyRepoState(),
+            restoredFiles: [],
+            deletedFiles: [],
+            error: "Rollback boundary was unavailable for this attempt."
+        };
+    }
+    const before = readRepoState(input.repoRoot);
+    if (repoStateMatchesBoundary(before, input.boundary)) {
+        return {
+            attempted: false,
+            status: "not_required",
+            restoredAt: input.restoredAt,
+            decision: input.decision,
+            before,
+            after: before,
+            restoredFiles: [],
+            deletedFiles: []
+        };
+    }
+    const restoredFiles = new Set();
+    const deletedFiles = new Set();
+    try {
+        const baselineTracked = new Set(input.boundary.trackedDirtyFiles);
+        const baselineUntracked = new Set(input.boundary.untrackedFiles);
+        for (const filePath of before.trackedDirtyFiles) {
+            if (!baselineTracked.has(filePath)) {
+                restoreTrackedFileFromHead(input.repoRoot, filePath);
+                restoredFiles.add(filePath);
+            }
+        }
+        for (const filePath of before.untrackedFiles) {
+            if (!baselineUntracked.has(filePath)) {
+                await removeRepoPath(input.repoRoot, filePath);
+                deletedFiles.add(filePath);
+            }
+        }
+        for (const snapshot of input.boundary.snapshots) {
+            await restoreRollbackSnapshot(input.repoRoot, snapshot);
+            if (snapshot.existed) {
+                restoredFiles.add(snapshot.path);
+            }
+            else {
+                deletedFiles.add(snapshot.path);
+            }
+        }
+        const after = readRepoState(input.repoRoot);
+        const restored = repoStateMatchesBoundary(after, input.boundary);
+        return {
+            attempted: true,
+            status: restored ? "restored" : "failed",
+            restoredAt: input.restoredAt,
+            decision: input.decision,
+            before,
+            after,
+            restoredFiles: [...restoredFiles].sort(),
+            deletedFiles: [...deletedFiles].sort(),
+            ...(restored
+                ? {}
+                : { error: "Repo state still diverged from the recorded rollback boundary after restore." })
+        };
+    }
+    catch (error) {
+        const after = readRepoState(input.repoRoot);
+        return {
+            attempted: true,
+            status: "failed",
+            restoredAt: input.restoredAt,
+            decision: input.decision,
+            before,
+            after,
+            restoredFiles: [...restoredFiles].sort(),
+            deletedFiles: [...deletedFiles].sort(),
+            error: toErrorMessage(error)
+        };
+    }
+}
+function readRepoState(repoRoot) {
+    return {
+        trackedDirtyFiles: readGitLines(repoRoot, ["diff", "--name-only", "HEAD", "--", "."]),
+        untrackedFiles: readGitLines(repoRoot, ["ls-files", "--others", "--exclude-standard", "--", "."])
+    };
+}
+function readGitLines(repoRoot, args) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const result = spawnSync("git", args, {
+            cwd: repoRoot,
+            encoding: "utf8"
+        });
+        if (result.status === 0 && typeof result.stdout === "string") {
+            return uniqueSorted(result.stdout
+                .split(/\r?\n/u)
+                .map((line) => normalizeRepoPath(line))
+                .filter(Boolean));
+        }
+        // Retry once after a short delay — handles git lock-file contention
+        // that occurs when another process holds .git/index.lock.
+        if (attempt === 0 && result.status !== 0) {
+            spawnSync("sleep", ["0.5"], { encoding: "utf8" });
+        }
+    }
+    return [];
+}
+function readGitScalar(repoRoot, args) {
+    const result = spawnSync("git", args, {
+        cwd: repoRoot,
+        encoding: "utf8"
+    });
+    if (result.status !== 0 || typeof result.stdout !== "string") {
+        return undefined;
+    }
+    const value = result.stdout.trim();
+    return value.length > 0 ? value : undefined;
+}
+async function readRollbackSnapshot(repoRoot, filePath) {
+    const absolutePath = resolveRepoPath(repoRoot, filePath);
+    try {
+        const contents = await readFile(absolutePath);
+        return {
+            path: normalizeRepoPath(filePath),
+            existed: true,
+            encoding: "base64",
+            contentBase64: contents.toString("base64")
+        };
+    }
+    catch {
+        return {
+            path: normalizeRepoPath(filePath),
+            existed: false,
+            encoding: "base64"
+        };
+    }
+}
+async function restoreRollbackSnapshot(repoRoot, snapshot) {
+    const absolutePath = resolveRepoPath(repoRoot, snapshot.path);
+    if (!snapshot.existed || !snapshot.contentBase64) {
+        await rm(absolutePath, { recursive: true, force: true });
+        return;
+    }
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, Buffer.from(snapshot.contentBase64, "base64"));
+}
+function restoreTrackedFileFromHead(repoRoot, filePath) {
+    const result = spawnSync("git", ["restore", "--staged", "--worktree", "--source=HEAD", "--", filePath], {
+        cwd: repoRoot,
+        encoding: "utf8"
+    });
+    if (result.status === 0) {
+        return;
+    }
+    // Retry once after a short delay (git lock-file contention)
+    spawnSync("sleep", ["0.5"], { encoding: "utf8" });
+    const retry = spawnSync("git", ["restore", "--staged", "--worktree", "--source=HEAD", "--", filePath], { cwd: repoRoot, encoding: "utf8" });
+    if (retry.status === 0) {
+        return;
+    }
+    // Fallback: try git checkout which works on older git versions
+    const fallback = spawnSync("git", ["checkout", "HEAD", "--", filePath], { cwd: repoRoot, encoding: "utf8" });
+    if (fallback.status === 0) {
+        return;
+    }
+    throw new Error(result.stderr?.trim() ||
+        `git restore failed for ${filePath} (retry and checkout fallback also failed)`);
+}
+async function removeRepoPath(repoRoot, filePath) {
+    await rm(resolveRepoPath(repoRoot, filePath), { recursive: true, force: true });
+}
+function resolveRepoPath(repoRoot, filePath) {
+    const resolvedRoot = resolve(repoRoot);
+    const resolvedPath = resolve(resolvedRoot, filePath);
+    const relativePath = relative(resolvedRoot, resolvedPath);
+    if (relativePath.startsWith("..") || relativePath === "") {
+        throw new Error(`Refusing to access a rollback path outside repo root: ${filePath}`);
+    }
+    return resolvedPath;
+}
+function repoStateMatchesBoundary(state, boundary) {
+    return arraysEqual(state.trackedDirtyFiles, boundary.trackedDirtyFiles) &&
+        arraysEqual(state.untrackedFiles, boundary.untrackedFiles);
+}
+function arraysEqual(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    return left.every((value, index) => value === right[index]);
+}
+function uniqueSorted(values) {
+    return [...new Set(values.map((value) => normalizeRepoPath(value)).filter(Boolean))].sort();
+}
+function normalizeRepoPath(value) {
+    return value.trim().replace(/\\/gu, "/");
+}
+function emptyRepoState() {
+    return {
+        trackedDirtyFiles: [],
+        untrackedFiles: []
+    };
+}
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/vendor/adapters/core/src/routing.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Route classification and compression for governed agent runs.
+ *
+ * Decides whether a task needs manager/planner orchestration or can go
+ * directly to a worker, based on task complexity signals. Prevents
+ * wasted coordination cost (Pre Work Burn) on simple tasks.
+ */
+import type { RoutingMode, RoutingPolicy } from "../../../contracts/index.js";
+export interface RouteDecision {
+    selectedMode: RoutingMode;
+    confidence: number;
+    expectedCostUsd: number;
+    expectedPreworkBurnPct: number;
+    reason: string[];
+    blockedSteps: string[];
+    compressed: boolean;
+    compressionSummary?: string;
+    /**
+     * Recommended model tier based on task complexity and route.
+     * Follows cost-aware routing: direct → haiku/sonnet, manager → sonnet,
+     * consensus → opus. Never use a more expensive model than the task needs.
+     */
+    recommendedModelTier: "haiku" | "sonnet" | "opus";
+    /** Estimated cost saving vs always using sonnet */
+    estimatedSavingVsSonnetUsd: number;
+}
+export interface RouteClassificationInput {
+    objective: string;
+    verificationPlan: string[];
+    repoRoot?: string;
+    allowedPaths?: string[];
+    deniedPaths?: string[];
+    budgetUsd: number;
+    policy?: Partial<RoutingPolicy>;
+    /** Number of files the task references or is scoped to. */
+    scopedFileCount?: number;
+    /** Historical success rate for similar tasks with direct execution (0-1). */
+    historicalDirectSuccessRate?: number;
+}
+/**
+ * Resolve a tier to a concrete model ID for a specific engine.
+ * Allows downstream adapters to switch models automatically.
+ */
+export declare function resolveModelForTier(tier: RouteDecision["recommendedModelTier"], engine: "claude" | "codex" | "gemini" | "openai" | string): string;
+/**
+ * Available engine registry — describes what's installed and its capability.
+ * Populated by doctor/preflight from PATH and env var detection.
+ */
+export interface AvailableEngine {
+    id: string;
+    available: boolean;
+    /** Cost tier: cheap < mid < expensive */
+    costTier: "cheap" | "mid" | "expensive";
+    /** Capability tier: determines which task types this engine can handle */
+    capabilityTier: "haiku" | "sonnet" | "opus";
+}
+/**
+ * Select the best available engine for a given tier requirement.
+ *
+ * When multiple engines are available, picks the cheapest that meets
+ * the capability requirement. Falls back gracefully:
+ * - If required tier unavailable, upgrades to next tier of same engine
+ * - If only one engine family available, uses its best equivalent
+ *
+ * @param requiredTier - Minimum capability tier needed
+ * @param availableEngines - What's installed and authenticated
+ * @returns Best engine ID and concrete model to use
+ */
+export declare function selectBestEngine(requiredTier: RouteDecision["recommendedModelTier"], availableEngines: AvailableEngine[]): {
+    engineId: string;
+    model: string;
+    reasoning: string;
+};
+export declare function classifyRoute(input: RouteClassificationInput): RouteDecision;
+/**
+ * Checks whether a run's Pre Work Burn exceeds the routing policy limits.
+ * Returns a block reason if exceeded, undefined if within bounds.
+ */
+export declare function evaluatePreworkBurnPolicy(preworkCostUsd: number, totalCostUsd: number, policy?: Partial<RoutingPolicy>): {
+    exceeded: boolean;
+    reason?: string;
+};