knodin 0.5.0

package/dist/src/tools/knodin-tools.js

@@ -0,0 +1,1438 @@
+/**
+ * The `knodin` gateway tool.
+ *
+ * Following the AtlasMCP pattern: a single low-level tool with an `operation`
+ * enum, registered via a hand-written JSON Schema literal (no high-level
+ * `server.tool()` / Zod-to-handler inference — that path OOMs `tsc`). One flat
+ * gateway keeps the client LLM's context small.
+ */
+import nodePath from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveCliRuntimeCommand } from "../cli-args.js";
+import { compactExplainResult, compactQueryResult, compactSearchResult, expandCompactIdentity, } from "../compact-structural.js";
+import { buildKnodinContext } from "../context.js";
+import { exportContext, grepPackedArtifact, readPackedArtifact } from "../context-export.js";
+import { getDocSection, listDocTopics } from "../docs-sections.js";
+import { diagnoseInstallation } from "../doctor.js";
+import { createEngine, REPO_WIDE_QUERY_PATTERNS, } from "../engine/index.js";
+import { measurePerfPhaseSync } from "../engine/perf.js";
+import { diagnoseFailure, } from "../failure-diagnosis.js";
+import { decorateGraphQueryResult, inspectGraphQueryHealth } from "../graph-query-health.js";
+import { inspectRepositoryIntegrationStatus } from "../init.js";
+import { attachLifecycleHealth } from "../lifecycle-health.js";
+import { compressOutput, compressOutputFile, deleteOutputArtifact, readOutputArtifact, } from "../output-compression.js";
+import { appendTelemetryRecord, clearTelemetry, countOutputTokens, exportTelemetry, measureOutput, readTelemetryRecords, telemetryStatus, writeTelemetryReport, } from "../output-telemetry.js";
+import { auditPullRequests, ghUnavailableReason, triagePrDetail } from "../pr-triage.js";
+import { createRepairPlan } from "../repair-progress.js";
+import { runRepositoryInitializationProcess } from "../repository-init-process.js";
+import { discoverRepositories, initializeRepositories, inventoryRepository, searchRepositories, } from "../repository-management.js";
+import { applyResponseBudget } from "../response-budget.js";
+import { enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, systemMembershipsForPath, validateSystemHealth, } from "../system-config.js";
+import { trustedUpdateStatus } from "../update-policy.js";
+import { waitForFresh } from "../wait-for-fresh.js";
+import { inspectWorktrees, reconcileWorktrees, removeManagedWorktree, } from "../worktree-lifecycle.js";
+const engine = createEngine();
+function gatewayCliCommand() {
+    const extension = import.meta.url.endsWith(".ts") ? "ts" : "js";
+    const entry = nodePath.resolve(nodePath.dirname(fileURLToPath(import.meta.url)), `../../bin/cli.${extension}`);
+    return resolveCliRuntimeCommand({
+        argv: [process.argv[0] ?? process.execPath, entry],
+        cwd: () => process.cwd(),
+        execArgv: process.execArgv,
+        execPath: process.execPath,
+    });
+}
+/** Release the gateway engine's local watcher and database resources. */
+export async function closeKnodinToolEngine() {
+    await engine.close();
+    compactReadyRepos.clear();
+}
+const localTelemetry = [];
+const compactReadyRepos = new Set();
+let cachedSchemaTokens;
+function gatewaySchemaTokens() {
+    cachedSchemaTokens ??= countOutputTokens(JSON.stringify(buildDocumentedKnodinTools()[0]?.inputSchema ?? {}));
+    return cachedSchemaTokens;
+}
+function inspectGatewayGraphHealth(repo) {
+    return inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })));
+}
+async function compactGraphUnavailable(repo) {
+    const key = nodePath.resolve(repo);
+    if (compactReadyRepos.has(key))
+        return null;
+    const health = await inspectGatewayGraphHealth(repo);
+    if (!health.available)
+        return health;
+    compactReadyRepos.add(key);
+    return null;
+}
+/** Runs `fn`, converting any thrown error into a structured `{ error }` result
+ * instead of letting it escape into the stdio transport. Extracted from the
+ * `prs` case (R22's "never throw into MCP" rule) so a future operation that
+ * needs the same guarantee can reuse it by name rather than re-implementing
+ * its own try/catch. Deliberately scoped to `prs` only for now — `explain`,
+ * `review`, `map`, `search`, and `query` keep their existing throwing
+ * behavior; wrapping them is out of scope here. */
+async function withStructuredError(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        return { error: err.message };
+    }
+}
+const QUERY_PATTERNS = [
+    "lsp_diagnostics",
+    "lsp_definitions",
+    "lsp_declarations",
+    "lsp_implementations",
+    "callers_of",
+    "callees_of",
+    "imports_of",
+    "importers_of",
+    "import_cycles",
+    "inheritors_of",
+    "structural_implementations_of",
+    "tests_for",
+    "file_summary",
+    "batch_outline",
+    "project_overview",
+    "shortest_path",
+    "impact",
+    "dead_code",
+    "large_functions",
+    "large_files",
+    "rename_preview",
+    "flows",
+    "flow_of",
+    "stats",
+    "traverse",
+    "feature_path",
+    "flow_analysis",
+    "knowledge_gaps",
+    "surprising_connections",
+    "suggested_questions",
+    "architecture_overview",
+    "triggers_of",
+    "publishers_of",
+    "listeners_of",
+    "handlers_of",
+    "endpoints_for",
+    "consumers_of",
+    "children_of",
+    "community",
+    "federated_repos",
+    "mcp_tools",
+    "api_contract_mismatches",
+];
+const GRAPH_INDEPENDENT_QUERY_PATTERNS = new Set([
+    "lsp_diagnostics",
+    "lsp_definitions",
+    "lsp_declarations",
+    "lsp_implementations",
+]);
+function buildDocumentedKnodinTools() {
+    return [
+        {
+            name: "knodin",
+            description: "Primary local code-intelligence gateway. Start with context when unsure; use explain before editing a symbol, review for diffs, map for boundaries, search for fuzzy discovery, query for structured graph questions/outlines, pack for bounded source context, compress for hard-budgeted recoverable diagnostic output, and prs for authenticated GitHub audits. Explain/source results are already Read-equivalent. Prefer grep for exact literals and direct reads for non-code or just-edited files. Every graph answer carries freshness evidence.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    operation: {
+                        type: "string",
+                        enum: [
+                            "explain",
+                            "review",
+                            "map",
+                            "search",
+                            "query",
+                            "prs",
+                            "context",
+                            "wiki",
+                            "docs",
+                            "doctor",
+                            "pack",
+                            "compress",
+                            "status",
+                            "wait",
+                            "worktrees",
+                            "repair",
+                            "repositories",
+                            "system",
+                            "telemetry",
+                        ],
+                        description: "Which knodin capability to run. context: call this FIRST when starting any investigation and unsure which operation to reach for — one ultra-compact orientation (repo stats + top subsystems/hubs/flows + a risk score if there's a diff + a heuristic next-operation suggestion); the suggestion is only a hint and never blocks calling any operation directly. explain: use when orienting on a symbol/file or before editing it — returns edit-ready source + call paths + blast radius. review: use before writing a PR description or approving a diff — risk-scored context (changed symbols, affected flows, test gaps). map: use before a cross-cutting refactor or to understand subsystem boundaries — communities + hub/bridge nodes + confidence-tagged edges. search: use when you don't know the exact symbol name — hybrid semantic + keyword lookup over code symbols. query: use for a structured question about a known symbol — callers_of, tests_for, shortest_path, dead_code, rename_preview, flows, and more (see `pattern`). pack: create deterministic Markdown/JSON/XML source context under hard budgets, or bounded-read/exact-regex-grep a saved artifact. compress: reduce already-produced diagnostic text under exact line/content-byte budgets, preserve exit metadata and detected signals, retain private local drill-down data by default, and never label insufficient-fidelity output complete. prs: use to triage open GitHub PRs (via your local authenticated `gh`) — per-PR status, CI, and blast radius sorted ready-small-impact first; pass `prNumber` for one PR's impacted files + community names. wiki: write a static markdown documentation site for the repository's logical subsystems to `.reckon/wiki/`. Generates an index plus one page per mapped community. Reuses the `map` output. Idempotent: unchanged pages are untouched on disk unless `force` is true. docs: call this to retrieve curated, focused markdown usage guidance directly over MCP.",
+                    },
+                    symbol: {
+                        type: "string",
+                        description: "explain: the symbol (function/class/file) to explain. query: the target symbol/file (symbol selector for impact by default; comma-separated files only with impactMode=file; file-substring filter for dead_code/large_functions/large_files; entry-point name for flow_of; unused for flows).",
+                    },
+                    identity: {
+                        type: "string",
+                        description: "Stable identity selecting one same-named definition.",
+                    },
+                    file: {
+                        type: "string",
+                        description: "Repo-relative definition file selector.",
+                    },
+                    kind: {
+                        type: "string",
+                        description: "Definition kind selector (function, class, method, etc.).",
+                    },
+                    toIdentity: {
+                        type: "string",
+                        description: "shortest_path destination identity selector.",
+                    },
+                    toFile: {
+                        type: "string",
+                        description: "shortest_path destination file selector.",
+                    },
+                    toKind: {
+                        type: "string",
+                        description: "shortest_path destination kind selector.",
+                    },
+                    pattern: {
+                        type: "string",
+                        enum: [...QUERY_PATTERNS],
+                        description: "feature_path — deterministic downstream DFS over resolved source references. It is bounded by depth and item limits, source-evidenced per hop, cycle-guarded, and never claims runtime execution; dynamic dispatch and unresolved calls are omitted. " +
+                            "lsp_diagnostics accepts a repo-relative TypeScript/JavaScript file; lsp_definitions, lsp_declarations, and lsp_implementations accept file:line:column. These use an optional local TypeScript language-service adapter, never start a daemon or write files, and return an explicit unavailable result when no local adapter supports the file type. " +
+                            "api_contract_mismatches — bounded, source-evidenced static mismatch findings for literal Express/Fastify routes and literal fetch/Axios clients. Matching requires method and normalized path, and requires exact origin equality when a client uses an absolute origin; dynamic routes remain explicitly unresolved. mcp_tools — list indexed TypeScript MCP SDK tool registrations, or pass symbol to look up one exact tool name; returns description/schema/handler/file and exact versus heuristic confidence. import_cycles — repo-wide canonical directed file-import cycles; no symbol required, type-only imports included, non-import lineage/ORM edges excluded, and limit/truncated bounds output. " +
+                            "query: the graph pattern to run (callers_of, callees_of, imports_of, importers_of, inheritors_of, structural_implementations_of, tests_for, file_summary, shortest_path, impact, dead_code, large_functions, large_files, rename_preview, flows, flow_of, stats, traverse, knowledge_gaps, community, federated_repos). structural_implementations_of returns TypeScript structurally typed object implementations separately from nominal extends/implements results. federated_repos — discover and list all registered/configured repository paths that this engine federates queries across. community — fetch a single community's full detail (name, size, cohesion, files, and symbols) by name or substring filter; empty `symbol` = all communities. large_files — whole-file line counts (min 200), sorted descending — the file-level counterpart to large_functions, for spotting god files rather than god functions; same optional path-substring filter, empty `symbol` = all files. stats — repo-level index size + health in one call (per-repo symbol/reference/dependency/embedding/file counts, per-kind and per-language breakdowns, orphaned-embedding count, schema version, last-indexed HEAD, and cached community/hub/bridge/flow totals); federated, empty `symbol`. traverse — typed BFS from `symbol` within `depth` hops (default 3, 1–6), selectable upstream/downstream/both and explicit edge kinds; every discovered edge includes direction, kind, provenance, confidence, files, and source line, with optional Tree-sitter-grounded argument expressions honestly marked heuristic. Sets `truncated` when the `limit` cap binds; single-repo. knowledge_gaps — repo-health weaknesses in one call: thin communities (<3 symbols), single-file communities, isolated (zero-degree) symbols, and untested hub/bridge hotspots; sourced from the cached map(), federated, empty `symbol`, one row carrying a `knowledgeGaps` block. surprising_connections — resolved edges scored by a composite surprise formula (cross-community, cross-language, peripheral-to-hub, cross-test-boundary, unusual edge kind) to surface unexpected coupling; sorted highest-first, top 15 by default, federated, empty `symbol`, each row carrying a `surprise` block. suggested_questions — prioritized, human-readable review prompts synthesized from knowledge_gaps + surprising_connections (untested hotspots first, then surprising edges, then thin/single-file communities); federated, empty `symbol`, each row a `question` string citing the real symbol/file, top 10 by default. architecture_overview — a federated architecture view with scoped community coupling and independently selectable packages, layers, boundaries, hotspots, entry points, and language facets; `path` is segment-safe and applies consistently. `detailLevel` 'minimal' omits per-edge coupling; 'standard' includes it. Spring/event patterns (Java): triggers_of — the schedule edge between a @Scheduled method and its synthetic scheduler (pass the method to get its scheduler, or the scheduler to list scheduled methods). publishers_of — methods that publish a given event type (ApplicationEventPublisher.publishEvent). listeners_of — @EventListener methods that listen for a given event type. handlers_of — methods that handle a given HTTP endpoint path (Spring @*Mapping + the existing JS/Python endpoints). endpoints_for — the inverse: endpoint path(s) a given method handles. consumers_of — classes/methods consuming a given @Value config property. children_of — symbols contained in a file path (same as file_summary) or, for a class name, its member symbols by line-range containment. All seven require `symbol` (the target); single-repo, not federated.",
+                    },
+                    depth: {
+                        type: "number",
+                        description: "query traverse/feature_path/impact: maximum hops from `symbol` (default 3, clamped to 1–6).",
+                    },
+                    impactMode: {
+                        type: "string",
+                        enum: ["symbol", "file"],
+                        description: "query impact only: stable symbol reach (default) or explicitly labeled changed-file blast radius.",
+                    },
+                    direction: {
+                        type: "string",
+                        enum: ["upstream", "downstream", "both"],
+                        description: "query impact/traverse: inbound/upstream, outbound/downstream, or both (default).",
+                    },
+                    architectureFacets: {
+                        type: "array",
+                        items: {
+                            type: "string",
+                            enum: ["packages", "layers", "boundaries", "hotspots", "entryPoints", "languages"],
+                        },
+                        description: "query architecture_overview: independently select architecture dimensions; omitted selects all.",
+                    },
+                    relationKinds: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "query impact/traverse/feature_path: only include these exact edge kinds (for example call).",
+                    },
+                    minConfidence: {
+                        type: "number",
+                        minimum: 0,
+                        maximum: 1,
+                        description: "query impact: minimum edge confidence (extracted calls are 1.0).",
+                    },
+                    includeTests: {
+                        type: "boolean",
+                        description: "query impact: include test/spec files (default true).",
+                    },
+                    includeDataFlow: {
+                        type: "boolean",
+                        description: "query impact/traverse: attach bounded call-site argument evidence when parsed syntax supports it; never claims runtime proof.",
+                    },
+                    flowVariable: {
+                        type: "string",
+                        description: "query flow_analysis only: optional simple local variable name to filter compact source-evidenced facts.",
+                    },
+                    to: {
+                        type: "string",
+                        description: "query shortest_path: destination symbol (start symbol goes in `symbol`). query rename_preview: the new name (old name goes in `symbol`). Read-only by default (returns edit sites + a unified diff); pass `apply: true` to write the rename to disk.",
+                    },
+                    apply: {
+                        type: "boolean",
+                        description: "query rename_preview only: when true, perform the rename on disk (line-scoped word-boundary edits, atomic writes, reindex of touched files). Omitted/false is a dry-run that returns the preview plus a unified diff of what would change. Refuses (no writes) on ambiguous definitions, out-of-repo paths, or a name collision with an existing symbol.",
+                    },
+                    base: {
+                        type: "string",
+                        description: "review/context: compatibility base ref (default HEAD~1). For review this maps to scope=all versus the base; compare uses it as the default older ref. context uses it only for risk.",
+                    },
+                    diffScope: {
+                        type: "string",
+                        enum: ["unstaged", "staged", "all", "compare"],
+                        description: "review: unstaged=index vs worktree; staged=HEAD vs index; all=base (default HEAD~1) vs worktree; compare=base/from vs HEAD/to.",
+                    },
+                    from: {
+                        type: "string",
+                        description: "review: older ref of an explicit revision pair; requires `to`.",
+                    },
+                    toRevision: {
+                        type: "string",
+                        description: "review: newer ref of an explicit revision pair; requires `from`.",
+                    },
+                    reviewFiles: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "review: explicit repo-relative file list, independent of live git state.",
+                    },
+                    force: {
+                        type: "boolean",
+                        description: "wiki only: force rewriting all wiki pages even if unchanged.",
+                    },
+                    detailLevel: {
+                        type: "string",
+                        enum: ["standard", "minimal", "source", "compact"],
+                        description: "Structural explain/search/file_summary/batch_outline/project_overview: 'compact' returns the terse stable-identity contract. explain/review: 'minimal' caps each list and returns total counts for a token-efficient structured summary; 'standard' returns fuller arrays. compress: compact auditable metadata is the default; 'standard' returns the complete compression/omission envelope. query architecture_overview: 'minimal' aggregates cross-community edges; 'standard' adds the full per-edge list. map: 'minimal' drops member lists and aggregates edges; 'standard' returns the full map.",
+                    },
+                    query: {
+                        type: "string",
+                        description: "search: natural language query or keyword to find code symbols (e.g., 'session verification' or 'auth').",
+                    },
+                    limit: {
+                        type: "number",
+                        description: "search: maximum number of search results to return (default is 5, capped at 100). prs: maximum number of open PRs to list (default 50).",
+                    },
+                    byteBudget: {
+                        type: "number",
+                        minimum: 256,
+                        description: "Maximum serialized UTF-8 response bytes (operation defaults apply).",
+                    },
+                    tokenBudget: {
+                        type: "number",
+                        minimum: 64,
+                        description: "Maximum estimated tokens, using a deterministic four-bytes-per-token estimate.",
+                    },
+                    itemBudget: {
+                        type: "number",
+                        description: "Maximum items retained in every returned collection.",
+                    },
+                    includeSource: {
+                        type: "boolean",
+                        description: "explain minimal only: explicitly opt in to verbatim source (false by default).",
+                    },
+                    languages: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "search: language filters.",
+                    },
+                    extensions: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "search: file-extension filters.",
+                    },
+                    kinds: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "search/large-code: symbol-kind filters.",
+                    },
+                    path: {
+                        type: "string",
+                        description: "search/large-code path filter; architecture_overview path scope.",
+                    },
+                    testScope: {
+                        type: "string",
+                        enum: ["all", "test", "production"],
+                        description: "search: include all, test-only, or production-only symbols.",
+                    },
+                    offset: {
+                        type: "number",
+                        minimum: 0,
+                        description: "search pagination offset.",
+                    },
+                    minLines: {
+                        type: "number",
+                        minimum: 0,
+                        description: "large-code minimum line count.",
+                    },
+                    minComplexity: {
+                        type: "number",
+                        minimum: 0,
+                        description: "large-functions minimum cyclomatic complexity.",
+                    },
+                    topN: {
+                        type: "number",
+                        minimum: 1,
+                        maximum: 1000,
+                        description: "map/query drill-down top-N cap.",
+                    },
+                    sort: {
+                        type: "string",
+                        enum: ["relevance", "name", "size", "degree", "complexity"],
+                        description: "map/query drill-down sort.",
+                    },
+                    prNumber: {
+                        type: "number",
+                        description: "prs only: when set, return that single PR's detailed impact (impacted file list + community names) instead of the ranked summary table.",
+                    },
+                    prState: {
+                        type: "string",
+                        enum: ["open", "merged", "closed", "all"],
+                        description: "prs audit only: GitHub pull-request state to inspect.",
+                    },
+                    branches: {
+                        type: "string",
+                        description: "prs audit only: bounded glob matched against head branches (`*` any text, `?` one character).",
+                    },
+                    auditRange: {
+                        type: "string",
+                        description: "prs audit only: inclusive pull-request number range such as 723..739.",
+                    },
+                    auditBase: {
+                        type: "string",
+                        description: "prs audit only: base revision for merge-commit range filtering.",
+                    },
+                    auditHead: {
+                        type: "string",
+                        description: "prs audit only: head revision for merge-commit range filtering.",
+                    },
+                    expectedLogin: {
+                        type: "string",
+                        description: "prs audit only: require this GitHub login; a mismatch returns unavailable without changing gh account state.",
+                    },
+                    worktreeAction: {
+                        type: "string",
+                        enum: ["status", "reconcile", "remove"],
+                        description: "worktrees only: inspect, reconcile registry, or remove one linked checkout.",
+                    },
+                    worktreePath: {
+                        type: "string",
+                        description: "worktrees remove only: exact linked-worktree path.",
+                    },
+                    telemetryAction: {
+                        type: "string",
+                        enum: ["records", "status", "report", "export", "clear"],
+                        description: "telemetry action.",
+                    },
+                    telemetryRetentionDays: {
+                        type: "integer",
+                        description: "telemetry retention days; default 30.",
+                    },
+                    task: {
+                        type: "string",
+                        description: "context only (required): free-text description of what you're doing (e.g. 'review PR #42', 'debug login timeout', 'how does auth work'). Drives a keyword heuristic that suggests which operation to run next — a hint only, never a constraint.",
+                    },
+                    changedFiles: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "context only (optional): repo-relative paths the caller already knows changed. The engine's risk-score path always re-derives the diff from `git diff base`, so this is only a hint — an explicit empty array means 'no changes, skip the risk score'; omit it to auto-detect from git.",
+                    },
+                    repoPath: {
+                        type: "string",
+                        description: "Absolute path to the repo. Defaults to the current working directory.",
+                    },
+                    section: {
+                        type: "string",
+                        enum: [
+                            "quickstart",
+                            "query-patterns",
+                            "federation",
+                            "rename-safety",
+                            "language-support",
+                            "troubleshooting",
+                            "installation",
+                            "mcp",
+                            "repositories",
+                            "systems",
+                            "provenance",
+                            "dead-code",
+                            "doctor",
+                        ],
+                        description: "docs only (required): which documentation section to retrieve.",
+                    },
+                    systemAction: {
+                        type: "string",
+                        enum: ["list", "show", "validate", "query"],
+                        description: "system only: list configured systems, show or validate one system, or query its declared relationships.",
+                    },
+                    repositoryAction: {
+                        type: "string",
+                        enum: ["discover", "init", "status", "doctor", "search"],
+                        description: "repositories only: discover, initialize, inspect, diagnose, or independently search local checkouts.",
+                    },
+                    roots: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "repositories only: local discovery roots; defaults to repoPath/current directory.",
+                    },
+                    linkedWorktrees: {
+                        type: "string",
+                        enum: ["skip", "include"],
+                        description: "repositories only: explicit linked-worktree discovery policy.",
+                    },
+                    cursor: {
+                        type: "string",
+                        description: "repositories search only: opaque continuation cursor.",
+                    },
+                    allowPartial: {
+                        type: "boolean",
+                        description: "system/repository query: return partial results and name omissions.",
+                    },
+                    dryRun: {
+                        type: "boolean",
+                        description: "repositories init only: report planned changes without writing repositories.",
+                    },
+                    manifestPath: {
+                        type: "string",
+                        description: "repositories init: resumability manifest path for matching retries.",
+                    },
+                    packAction: {
+                        type: "string",
+                        enum: ["export", "read", "grep"],
+                        description: "pack only: export context (default), read a bounded artifact range, or exact-regex grep an artifact.",
+                    },
+                    compressionAction: {
+                        type: "string",
+                        enum: ["create", "read", "diagnose", "delete"],
+                        description: "compress: create, read, graph-diagnose, or delete a retained output artifact.",
+                    },
+                    text: {
+                        type: "string",
+                        description: "compress create: already-produced combined diagnostic text. Prefer artifactPath when the data is already on disk so it does not cross the tool boundary first.",
+                    },
+                    exitCode: {
+                        type: ["number", "null"],
+                        description: "compress create: original process exit code, preserved as metadata.",
+                    },
+                    lineBudget: {
+                        type: "number",
+                        minimum: 1,
+                        maximum: 10000,
+                        description: "compress create: hard maximum rendered content lines.",
+                    },
+                    compressionByteBudget: {
+                        type: "number",
+                        minimum: 256,
+                        maximum: 4194304,
+                        description: "compress create/read: hard UTF-8 content budget, separate from byteBudget for the whole gateway envelope.",
+                    },
+                    artifactId: {
+                        type: "string",
+                        description: "compress read/diagnose/delete: retained SHA-256 artifact identity.",
+                    },
+                    format: {
+                        type: "string",
+                        enum: ["markdown", "json", "xml"],
+                        description: "pack export: deterministic artifact format.",
+                    },
+                    include: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "pack export: composable repo-relative glob includes.",
+                    },
+                    exclude: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "pack export: composable repo-relative glob excludes.",
+                    },
+                    filePolicies: {
+                        type: "object",
+                        additionalProperties: {
+                            type: "string",
+                            enum: ["full", "summary", "structure-only"],
+                        },
+                        description: "pack export: glob-to-policy map.",
+                    },
+                    alreadyPresent: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "pack export: files already in caller context; omitted from source.",
+                    },
+                    chatFiles: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "pack export: chat-mentioned file paths to omit.",
+                    },
+                    lineNumbers: {
+                        type: "boolean",
+                        description: "pack export: prefix source with line numbers.",
+                    },
+                    includeTree: {
+                        type: "boolean",
+                        description: "pack export: include deterministic relative-path tree.",
+                    },
+                    outputPath: {
+                        type: "string",
+                        description: "pack export: optional repo-contained artifact path.",
+                    },
+                    artifactPath: {
+                        type: "string",
+                        description: "pack read/grep: repo-contained artifact path. compress create: repo-contained regular input file; symlinks are refused.",
+                    },
+                    startLine: {
+                        type: "number",
+                        minimum: 1,
+                        description: "pack read: first line (1-based).",
+                    },
+                    endLine: {
+                        type: "number",
+                        minimum: 1,
+                        description: "pack read: last line (max 1000 lines).",
+                    },
+                    regex: {
+                        type: "string",
+                        description: "pack grep: exact JavaScript regular expression.",
+                    },
+                    regexFlags: {
+                        type: "string",
+                        description: "pack grep: optional gimsuy flags.",
+                    },
+                    gitDiffScope: {
+                        type: "string",
+                        enum: ["unstaged", "staged", "all", "compare"],
+                        description: "pack export: optional C5-compatible diff scope.",
+                    },
+                    gitLog: {
+                        type: "number",
+                        minimum: 0,
+                        maximum: 100,
+                        description: "pack export: optional number of local one-line commits.",
+                    },
+                    statusAudit: {
+                        type: "string",
+                        enum: ["cached", "deep"],
+                        description: "status only: cached (default) reuses a warm deep audit only after a bounded freshness probe; deep forces a complete filesystem/schema/orphan audit.",
+                    },
+                    timeoutMs: {
+                        type: "number",
+                        minimum: 0,
+                        maximum: 300000,
+                        description: "wait: maximum milliseconds to wait for freshness.",
+                    },
+                    client: {
+                        type: "string",
+                        enum: ["claude", "codex", "gemini", "antigravity"],
+                        description: "doctor: optionally return one client-specific integration diagnosis.",
+                    },
+                    repairPlan: {
+                        type: "boolean",
+                        description: "repair: return a non-mutating auditable plan instead of applying it.",
+                    },
+                    persistTelemetry: {
+                        type: "boolean",
+                        description: "Opt in to local metadata-only JSONL persistence at .reckon-telemetry.jsonl; never records source.",
+                    },
+                },
+                required: ["operation"],
+            },
+        },
+    ];
+}
+/** @internal Baseline schema used only by the checked-in equivalence proof. */
+export function getDocumentedKnodinToolsForSchemaProof() {
+    return buildDocumentedKnodinTools();
+}
+const COMPACT_TOOL_DESCRIPTION = "Local code intelligence with freshness evidence. Start with context; use docs for guidance.";
+const COMPACT_PARAMETER_DESCRIPTIONS = {
+    operation: "Capability to run. Use docs for complete operation guidance.",
+    symbol: "Target symbol or file; exact meaning depends on operation.",
+    pattern: "Query pattern; applies only when operation is query.",
+    impactMode: "Impact by stable symbol identity or explicitly labeled files.",
+    apply: "Apply rename_preview edits; false returns a dry-run.",
+    diffScope: "Review scope: unstaged, staged, all, or compare.",
+    section: "Docs section; quickstart includes the complete parameter reference.",
+    persistTelemetry: "Persist metadata-only telemetry locally; never source.",
+};
+function compactParameterDescription(name, description) {
+    void description;
+    return COMPACT_PARAMETER_DESCRIPTIONS[name];
+}
+/** The compact, always-on MCP surface. Full prose remains available via docs. */
+export function getKnodinTools() {
+    const tools = buildDocumentedKnodinTools();
+    for (const tool of tools) {
+        tool.description = COMPACT_TOOL_DESCRIPTION;
+        const properties = tool.inputSchema.properties;
+        for (const [name, property] of Object.entries(properties)) {
+            property.description = compactParameterDescription(name, property.description);
+        }
+    }
+    return tools;
+}
+function renderParameterDocumentation() {
+    const [tool] = buildDocumentedKnodinTools();
+    const properties = tool.inputSchema.properties;
+    const lines = ["# knodin operation and parameter reference", "", tool.description ?? "", ""];
+    for (const [name, property] of Object.entries(properties)) {
+        lines.push(`## ${name}`, "", property.description ?? "No additional guidance.", "");
+    }
+    return lines.join("\n");
+}
+const RESPONSE_DEFAULTS = {
+    explain: { bytes: 65_536, tokens: 16_384, items: 200 },
+    "explain:minimal": { bytes: 16_384, tokens: 4_096, items: 25 },
+    map: { bytes: 131_072, tokens: 32_768, items: 200 },
+    "map:minimal": { bytes: 32_768, tokens: 8_192, items: 15 },
+    default: { bytes: 65_536, tokens: 16_384, items: 100 },
+};
+async function populateRepositoryDiagnoses(records, repositories, configRoot) {
+    repositories.length = 0;
+    for (const record of records) {
+        try {
+            const graph = attachLifecycleHealth(record.path, await engine.status(record.path, { audit: "deep" }));
+            const repository = await inventoryRepository(record, {
+                status: async () => graph,
+                systemMemberships: (target) => systemMembershipsForPath(loadSystemConfiguration(configRoot), target),
+            });
+            repositories.push({
+                ...repository,
+                diagnosis: await diagnoseInstallation(record.path, {
+                    currentVersion: graph.version,
+                    runtimeCommand: [process.execPath, process.argv[1] ?? "", "serve"],
+                    graph,
+                }),
+            });
+        }
+        catch (error) {
+            repositories.push({
+                schemaVersion: 1,
+                path: record.path,
+                classification: record.classification,
+                health: "unknown",
+                errors: [error instanceof Error ? error.message : String(error)],
+                remediation: ["knodin doctor"],
+            });
+        }
+    }
+}
+async function handleRepositoriesOperation(options) {
+    const { repositoryAction, roots, repo, depth, linkedWorktrees, query, include, exclude, allowPartial, dryRun, manifestPath, itemBudget, byteBudget, tokenBudget, cursor, bounded, } = options;
+    const discoveryRoots = roots?.length ? roots : [repo];
+    const discoveryOptions = {
+        depth,
+        linkedWorktrees: linkedWorktrees ?? "skip",
+    };
+    const inventory = async () => {
+        const discovery = await discoverRepositories(discoveryRoots, discoveryOptions);
+        const systemConfig = loadSystemConfiguration(discoveryRoots[0] ?? repo);
+        const repositories = [];
+        for (const record of discovery.repositories) {
+            repositories.push(await inventoryRepository(record, {
+                status: async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })),
+                systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
+            }));
+        }
+        return { discovery, repositories };
+    };
+    if (repositoryAction === "init") {
+        const command = gatewayCliCommand();
+        const systemConfig = loadSystemConfiguration(discoveryRoots[0] ?? repo);
+        const summary = await initializeRepositories(discoveryRoots, {
+            command,
+            index: (target) => engine.index(target),
+            status: (target) => engine.status(target),
+            depth,
+            worktrees: linkedWorktrees,
+            dryRun,
+            manifestPath,
+            indexMode: (target) => indexModeForPath(systemConfig, target),
+            isolatedInitialize: (target) => runRepositoryInitializationProcess({ repository: target, command }),
+        });
+        const { repositories } = await inventory();
+        return bounded({ schemaVersion: 1, ...summary, repositories }, "repositories:init");
+    }
+    if (repositoryAction === "search") {
+        if (!query?.trim())
+            throw new Error("knodin repositories search requires a non-empty `query`");
+        const systemConfig = loadSystemConfiguration(discoveryRoots[0] ?? repo);
+        return searchRepositories(discoveryRoots, query, {
+            ...discoveryOptions,
+            include,
+            exclude,
+            allowPartial,
+            itemBudget,
+            byteBudget,
+            tokenBudget,
+            cursor,
+            status: async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })),
+            search: (searchQuery, target, searchLimit, searchOffset) => engine.search(searchQuery, target, searchLimit, {
+                offset: searchOffset,
+                includeSource: true,
+                federate: false,
+            }),
+            systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
+        });
+    }
+    const { discovery, repositories } = await inventory();
+    if (repositoryAction === "doctor")
+        await populateRepositoryDiagnoses(discovery.repositories, repositories, discoveryRoots[0] ?? repo);
+    return bounded({
+        schemaVersion: 1,
+        linkedWorktrees: discoveryOptions.linkedWorktrees,
+        repositories,
+        issues: discovery.issues,
+        emptyRoots: discovery.emptyRoots,
+        staleLinkedWorktrees: discovery.staleLinkedWorktrees,
+    }, `repositories:${repositoryAction}`);
+}
+async function handleSystemOperation(options) {
+    const { systemAction, symbol, repo, allowPartial, bounded } = options;
+    const config = await enrichSystemRelationships(loadSystemConfiguration(repo));
+    if (systemAction === "list") {
+        return bounded({
+            schemaVersion: config.schemaVersion,
+            systems: config.systems.map(({ id, components }) => ({
+                id,
+                componentCount: components.length,
+            })),
+        }, "system:list");
+    }
+    if (!symbol)
+        throw new Error(`knodin system ${systemAction} requires \`symbol\``);
+    const system = config.systems.find(({ id }) => id === symbol);
+    if (!system) {
+        return bounded({
+            status: "not-found",
+            systemId: symbol,
+            available: config.systems.map(({ id }) => id),
+        }, `system:${systemAction}`);
+    }
+    if (systemAction === "show")
+        return bounded({ status: "ok", system, repositories: config.repositories }, "system:show");
+    const validation = await validateSystemHealth(config, symbol, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })), repo);
+    if (systemAction === "validate")
+        return bounded({ systemId: symbol, ...validation }, "system:validate");
+    return bounded(queryConfiguredSystem(config, symbol, allowPartial === true, validation), "system:query");
+}
+async function handlePullRequestsOperation(options) {
+    const { repo, engine, limit, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, } = options;
+    const prNum = prNumber === undefined || prNumber === null ? undefined : Number(prNumber);
+    if (prNum !== undefined && Number.isNaN(prNum))
+        return { error: "knodin prs: prNumber must be a number" };
+    if (prNum !== undefined) {
+        const reason = ghUnavailableReason();
+        if (reason)
+            return { error: reason };
+        return withStructuredError(() => triagePrDetail(repo, engine, prNum, limit));
+    }
+    return withStructuredError(() => auditPullRequests(repo, engine, {
+        state: prState,
+        limit,
+        branches,
+        range: auditRange,
+        base: auditBase,
+        head: auditHead,
+        expectedLogin,
+    }));
+}
+function validateKnodinArgs(args) {
+    const requireStringArray = (name, value) => {
+        if (value !== undefined &&
+            (!Array.isArray(value) || value.some((item) => typeof item !== "string")))
+            throw new Error(`knodin: ${name} must be an array of strings`);
+    };
+    for (const name of [
+        "languages",
+        "extensions",
+        "kinds",
+        "relationKinds",
+        "include",
+        "exclude",
+        "roots",
+        "alreadyPresent",
+        "chatFiles",
+    ])
+        requireStringArray(name, args[name]);
+    requireStringArray("architectureFacets", args.architectureFacets);
+    if (args.direction !== undefined && !["upstream", "downstream", "both"].includes(args.direction))
+        throw new Error("knodin: invalid direction");
+    if (args.architectureFacets?.some((facet) => !["packages", "layers", "boundaries", "hotspots", "entryPoints", "languages"].includes(facet)))
+        throw new Error("knodin: invalid architectureFacets");
+    for (const [name, value, min] of [
+        ["offset", args.offset, 0],
+        ["minLines", args.minLines, 0],
+        ["minComplexity", args.minComplexity, 0],
+        ["topN", args.topN, 1],
+    ])
+        if (value !== undefined && (!Number.isInteger(value) || value < min))
+            throw new Error(`knodin: ${name} must be an integer >= ${min}`);
+    if (args.topN !== undefined && args.topN > 1000)
+        throw new Error("knodin: topN must be <= 1000");
+    if (args.sort !== undefined &&
+        !["relevance", "name", "size", "degree", "complexity"].includes(args.sort))
+        throw new Error("knodin: invalid sort");
+    if (args.testScope !== undefined && !["all", "test", "production"].includes(args.testScope))
+        throw new Error("knodin: invalid testScope");
+    if (args.statusAudit !== undefined && !["cached", "deep"].includes(args.statusAudit))
+        throw new Error("knodin: invalid statusAudit");
+    if (args.timeoutMs !== undefined &&
+        (!Number.isInteger(args.timeoutMs) || args.timeoutMs < 0 || args.timeoutMs > 300_000))
+        throw new Error("knodin: timeoutMs must be an integer between 0 and 300000");
+    if (args.client !== undefined &&
+        !["claude", "codex", "gemini", "antigravity"].includes(args.client))
+        throw new Error("knodin: invalid client");
+}
+function compactExplainSource(result) {
+    const source = result.source
+        ?.split("\n")
+        .map((line) => {
+        const separator = line.indexOf(": ");
+        if (separator <= 0)
+            return line;
+        const prefix = line.slice(0, separator);
+        return /^\d+$/.test(prefix) ? line.slice(separator + 2) : line;
+    })
+        .join("\n");
+    return {
+        mode: "source",
+        identity: result.identity,
+        symbol: result.symbol,
+        source,
+        staleness: result.staleness,
+    };
+}
+function compactCompression(result) {
+    return {
+        status: result.status,
+        content: result.content,
+        // Compact tuples keep the default agent response small. `exit` is
+        // [code, signal], `budget` is [used lines, line limit, used UTF-8 bytes,
+        // byte limit], and `fidelity` is [detected, preserved, unpreserved ids].
+        exit: [result.exit.code, result.exit.signal],
+        artifactId: result.artifact.retained ? result.artifact.id : null,
+        budget: [
+            result.output.lines,
+            result.output.lineBudget,
+            result.output.bytes,
+            result.output.byteBudget,
+        ],
+        fidelity: [
+            result.fidelity.detectedSignals,
+            result.fidelity.preservedSignals,
+            result.fidelity.unpreservedSignals,
+        ],
+        // Omission tuples are [inclusive start line, inclusive end line, exact
+        // source bytes including original line delimiters].
+        omitted: result.omittedRanges.map(({ startLine, endLine, byteCount }) => [
+            startLine,
+            endLine,
+            byteCount,
+        ]),
+    };
+}
+function compactFailureRelation(relation) {
+    return [
+        relation.identity,
+        relation.symbol,
+        relation.file,
+        relation.kind,
+        relation.line,
+        relation.confidence,
+    ];
+}
+function compactFailureDiagnosis(result) {
+    return {
+        status: result.status,
+        input: [result.input.kind, result.input.artifactId, result.input.bytes, result.input.complete],
+        // `reference` is [reported path, line, column]. `owner` is
+        // [stable identity, symbol, kind, start, end, signature].
+        diagnostics: result.diagnostics.map((diagnostic) => ({
+            reference: [
+                diagnostic.reference.path,
+                diagnostic.reference.line,
+                diagnostic.reference.column,
+            ],
+            file: diagnostic.file,
+            package: diagnostic.package
+                ? [diagnostic.package.name, diagnostic.package.manifest, diagnostic.package.kind]
+                : null,
+            owner: diagnostic.owner
+                ? [
+                    diagnostic.owner.identity,
+                    diagnostic.owner.symbol,
+                    diagnostic.owner.kind,
+                    diagnostic.owner.line,
+                    diagnostic.owner.endLine,
+                    diagnostic.owner.signature,
+                ]
+                : null,
+            tests: diagnostic.tests.map(compactFailureRelation),
+            upstream: diagnostic.upstream.map(compactFailureRelation),
+            downstream: diagnostic.downstream.map(compactFailureRelation),
+            recent: diagnostic.recentChanges.map(({ commit, at, subject }) => [
+                commit.slice(0, 12),
+                at,
+                subject,
+            ]),
+        })),
+        unresolved: result.unresolved,
+        context: result.contextBundle,
+        freshness: [result.freshness.state, result.freshness.indexedHead, result.freshness.currentHead],
+        limitations: result.limitations,
+    };
+}
+function hasCompressionResponseBudget(args) {
+    return (args.byteBudget !== undefined || args.tokenBudget !== undefined || args.itemBudget !== undefined);
+}
+async function handleCompressionDiagnosis(repo, args, engine, graphRead) {
+    const sources = [args.artifactId !== undefined, args.text !== undefined].filter(Boolean).length;
+    if (sources !== 1)
+        throw new Error("knodin compress diagnose requires exactly one of artifactId or text");
+    return graphRead("compress:diagnose", async () => {
+        const result = await diagnoseFailure(engine, repo, {
+            artifactId: args.artifactId,
+            text: args.text,
+            maxDiagnostics: args.limit ?? args.itemBudget,
+            contextLines: args.contextLines,
+            contextByteBudget: args.compressionByteBudget,
+        });
+        return args.detailLevel === "standard" ? result : compactFailureDiagnosis(result);
+    }, args.detailLevel !== "standard");
+}
+function handleCompressionRead(repo, args, observe, bounded) {
+    if (!args.artifactId)
+        throw new Error("knodin compress read requires `artifactId`");
+    const result = readOutputArtifact(repo, args.artifactId, {
+        startLine: args.startLine,
+        endLine: args.endLine,
+        byteBudget: args.compressionByteBudget,
+        raw: args.raw,
+    });
+    return hasCompressionResponseBudget(args)
+        ? bounded(result, "compress:read")
+        : observe(result, "compress:read", true);
+}
+function handleCompressionCreate(repo, args, observe, bounded) {
+    const request = {
+        exitCode: args.exitCode,
+        signal: args.signal,
+        strategy: args.strategy,
+        adapter: args.adapter,
+        lineBudget: args.lineBudget,
+        byteBudget: args.compressionByteBudget,
+        contextLines: args.contextLines,
+        retain: args.retain,
+        redactSecrets: args.redactSecrets,
+        maxInputBytes: args.maxInputBytes,
+    };
+    const sources = [
+        args.text !== undefined,
+        args.events !== undefined,
+        args.artifactPath !== undefined,
+    ].filter(Boolean).length;
+    if (sources !== 1)
+        throw new Error("knodin compress create requires exactly one of text, events, artifactPath");
+    let result;
+    if (args.artifactPath)
+        result = compressOutputFile(repo, args.artifactPath, request);
+    else if (args.events)
+        result = compressOutput(repo, { ...request, events: args.events });
+    else
+        result = compressOutput(repo, { ...request, text: args.text });
+    const minimal = args.detailLevel !== "standard";
+    const presentation = minimal ? compactCompression(result) : result;
+    return hasCompressionResponseBudget(args)
+        ? bounded(presentation, "compress:create", minimal)
+        : observe(presentation, "compress:create", minimal);
+}
+async function handleCompressionOperation(repo, args, engine, observe, bounded, graphRead) {
+    const action = args.compressionAction ?? "create";
+    switch (action) {
+        case "diagnose":
+            return handleCompressionDiagnosis(repo, args, engine, graphRead);
+        case "read":
+            return handleCompressionRead(repo, args, observe, bounded);
+        case "delete":
+            if (!args.artifactId)
+                throw new Error("knodin compress delete requires `artifactId`");
+            return observe(deleteOutputArtifact(repo, args.artifactId), "compress:delete", true);
+        case "create":
+            return handleCompressionCreate(repo, args, observe, bounded);
+        default:
+            throw new Error("knodin compress: invalid compressionAction");
+    }
+}
+async function runCompactExplain(symbol, repo, selector, file, byteBudget) {
+    const result = await engine.explain(symbol, repo, "minimal", selector);
+    let sourceFile = file;
+    if (!sourceFile && result.identity && !result.ambiguity) {
+        const locations = await engine.search(symbol, repo, 100, {
+            includeSource: false,
+            structural: true,
+        });
+        sourceFile = locations.results.find((row) => row.identity === result.identity)?.filePath;
+    }
+    return compactExplainResult(result, sourceFile, byteBudget);
+}
+async function runCompactSearch(query, repo, limit, options, byteBudget) {
+    const result = await engine.search(query, repo, limit, {
+        ...options,
+        includeSource: false,
+        structural: true,
+    });
+    return compactSearchResult(result, query, byteBudget);
+}
+async function runCompactQuery(pattern, target, repo, limit, depth, selector, byteBudget) {
+    const result = await engine.query(pattern, target, repo, undefined, limit, depth, undefined, selector, undefined, {});
+    return compactQueryResult(result, byteBudget);
+}
+const NOT_COMPACT_STRUCTURAL = Symbol("not-compact-structural");
+function handleDocsOperation(section, bounded) {
+    const topics = listDocTopics();
+    if (!section)
+        return bounded({
+            error: `knodin docs requires \`section\` parameter. Valid sections: ${topics.join(", ")}`,
+        }, "docs");
+    const sectionContent = getDocSection(section);
+    const content = section === "quickstart" && sectionContent !== undefined
+        ? `${sectionContent}\n\n${renderParameterDocumentation()}`
+        : sectionContent;
+    return content === undefined
+        ? bounded({ error: `unknown docs section. Valid sections: ${topics.join(", ")}` }, "docs")
+        : bounded({ status: "ok", section, content }, "docs");
+}
+async function tryCompactStructural(args, repo, selector, bounded) {
+    const { operation, detailLevel, includeSource, symbol, file, byteBudget } = args;
+    const unavailable = async (op) => {
+        const health = await compactGraphUnavailable(repo);
+        return health ? bounded(health, op, true) : null;
+    };
+    if (operation === "explain" && detailLevel === "compact" && includeSource === true && symbol) {
+        const blocked = await unavailable("explain");
+        return {
+            handled: true,
+            value: blocked ?? (await runCompactExplain(symbol, repo, selector, file, byteBudget)),
+        };
+    }
+    if (operation === "search" && detailLevel === "compact" && args.query) {
+        const blocked = await unavailable("search");
+        return {
+            handled: true,
+            value: blocked ??
+                (await runCompactSearch(args.query, repo, Math.min(args.limit ?? args.itemBudget ?? 5, args.itemBudget ?? 100), {
+                    languages: args.languages,
+                    extensions: args.extensions,
+                    kinds: args.kinds,
+                    path: args.path,
+                    testScope: args.testScope,
+                    offset: args.offset,
+                }, byteBudget)),
+        };
+    }
+    const compactPattern = operation === "query" &&
+        detailLevel === "compact" &&
+        (args.pattern === "file_summary" ||
+            args.pattern === "batch_outline" ||
+            args.pattern === "project_overview")
+        ? args.pattern
+        : null;
+    if (!compactPattern)
+        return { handled: false, value: NOT_COMPACT_STRUCTURAL };
+    const blocked = await unavailable(`query:${compactPattern}`);
+    return {
+        handled: true,
+        value: blocked ??
+            (await runCompactQuery(compactPattern, symbol ?? "", repo, Math.min(args.limit ?? args.itemBudget ?? 100, args.itemBudget ?? 1000), args.depth, selector, byteBudget)),
+    };
+}
+export async function handleKnodinTool(args) {
+    const startedAt = performance.now();
+    const parsedArgs = (args ?? {});
+    const { operation, symbol, base, diffScope, from, toRevision, reviewFiles, query, pattern, to, limit, depth, impactMode, direction, relationKinds, minConfidence, includeTests, includeDataFlow, flowVariable, apply, force, detailLevel, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, worktreeAction, worktreePath, telemetryAction, telemetryRetentionDays, task, changedFiles, repoPath, section, systemAction, repositoryAction, roots, linkedWorktrees, cursor, allowPartial, dryRun, manifestPath, identity, file, kind, toIdentity, toFile, toKind, byteBudget, tokenBudget, itemBudget, includeSource, languages, extensions, kinds, path, architectureFacets, testScope, offset, minLines, minComplexity, topN, sort, packAction, format, include, exclude, filePolicies, alreadyPresent, chatFiles, lineNumbers, includeTree, outputPath, artifactPath, startLine, endLine, regex, regexFlags, gitDiffScope, gitLog, statusAudit, timeoutMs, client, repairPlan, persistTelemetry, } = parsedArgs;
+    const repo = repoPath ?? process.cwd();
+    const selector = {
+        identity: expandCompactIdentity(identity),
+        file,
+        kind,
+        toIdentity: expandCompactIdentity(toIdentity),
+        toFile,
+        toKind,
+    };
+    const budget = {
+        bytes: byteBudget,
+        tokens: tokenBudget,
+        items: itemBudget,
+    };
+    const observe = (output, op, minimal = false) => {
+        const root = output;
+        const budgetMeta = root.responseBudget;
+        if (op === "review") {
+            measurePerfPhaseSync("review_serialization", () => JSON.stringify(output));
+        }
+        const telemetry = measureOutput({
+            repo,
+            operation: op,
+            output: root,
+            startedAt,
+            detailMode: minimal ? "minimal" : (detailLevel ?? "standard"),
+            truncated: budgetMeta?.truncated === true ||
+                root.telemetry?.truncated === true,
+            schemaTokens: gatewaySchemaTokens(),
+        });
+        telemetry.temperature = localTelemetry.some(({ operation, repositoryId }) => operation === op && repositoryId === telemetry.repositoryId)
+            ? "warm"
+            : "cold";
+        localTelemetry.push(telemetry);
+        if (localTelemetry.length > 1000)
+            localTelemetry.shift();
+        if (persistTelemetry === true) {
+            appendTelemetryRecord(repo, telemetry, telemetryRetentionDays);
+        }
+        return root;
+    };
+    const bounded = (result, op = String(operation), minimal = false) => {
+        const key = `${op}${minimal ? ":minimal" : ""}`;
+        const output = applyResponseBudget(result, op, budget, RESPONSE_DEFAULTS[key] ?? RESPONSE_DEFAULTS.default);
+        return observe(output, op, minimal);
+    };
+    const graphRead = async (op, run, minimal = false) => {
+        const health = await inspectGatewayGraphHealth(repo);
+        if (!health.available)
+            return bounded(health, op, minimal);
+        const result = await run();
+        const verified = await inspectGatewayGraphHealth(repo);
+        if (!verified.available)
+            return bounded(verified, op, minimal);
+        return bounded(decorateGraphQueryResult(result, verified.state, verified.graph.freshness), op, minimal);
+    };
+    validateKnodinArgs(parsedArgs);
+    const compactStructural = await tryCompactStructural(parsedArgs, repo, selector, bounded);
+    if (compactStructural.handled)
+        return compactStructural.value;
+    if (detailLevel === "compact")
+        throw new Error("knodin: compact detail is unsupported here");
+    switch (operation) {
+        case "telemetry": {
+            const action = telemetryAction ?? "records";
+            if (action === "records")
+                return bounded({ records: localTelemetry.slice() }, "telemetry");
+            if (action === "status")
+                return bounded(telemetryStatus(repo, artifactPath, telemetryRetentionDays), "telemetry:status");
+            const records = readTelemetryRecords(repo, artifactPath, telemetryRetentionDays);
+            if (action === "report")
+                return bounded(writeTelemetryReport(repo, records, outputPath), "telemetry:report");
+            if (action === "export")
+                return bounded(exportTelemetry(repo, records, outputPath), "telemetry:export");
+            return bounded(clearTelemetry(repo, artifactPath), "telemetry:clear");
+        }
+        case "doctor": {
+            const graph = await engine.status(repo);
+            return bounded(await diagnoseInstallation(repo, {
+                currentVersion: graph.version,
+                runtimeCommand: [process.execPath, process.argv[1] ?? "", "serve"],
+                graph,
+                client,
+            }), "doctor");
+        }
+        case "status":
+            return engine.status(repo, { audit: statusAudit }).then((result) => bounded({
+                ...attachLifecycleHealth(repo, result),
+                integration: inspectRepositoryIntegrationStatus(repo),
+                update: trustedUpdateStatus({
+                    currentVersion: result.version,
+                    installMethod: "unknown",
+                    env: process.env,
+                }),
+            }, "status"));
+        case "wait":
+            return bounded(await waitForFresh(engine, repo, timeoutMs), "wait");
+        case "worktrees":
+            if (!worktreeAction || worktreeAction === "status")
+                return bounded(await inspectWorktrees(repo, (worktree) => engine.status(worktree, { audit: "cached" })), "worktrees:status");
+            if (worktreeAction === "reconcile")
+                return bounded(reconcileWorktrees(repo), "worktrees:reconcile");
+            if (!worktreePath)
+                throw new Error("knodin worktrees remove requires `worktreePath`");
+            return bounded(removeManagedWorktree(repo, worktreePath, dryRun !== false), "worktrees:remove");
+        case "repair":
+            if (repairPlan)
+                return bounded(createRepairPlan(await engine.status(repo, { audit: "deep" })), "repair:plan");
+            return engine.repair(repo).then((result) => bounded(result, "repair"));
+        case "repositories": {
+            if (!repositoryAction)
+                throw new Error("knodin repositories requires `repositoryAction`");
+            return handleRepositoriesOperation({
+                repositoryAction,
+                roots,
+                repo,
+                depth,
+                linkedWorktrees,
+                query,
+                include,
+                exclude,
+                allowPartial,
+                dryRun,
+                manifestPath,
+                itemBudget,
+                byteBudget,
+                tokenBudget,
+                cursor,
+                bounded,
+            });
+        }
+        case "system": {
+            if (!systemAction)
+                throw new Error("knodin system requires `systemAction`");
+            return handleSystemOperation({
+                systemAction,
+                symbol,
+                repo,
+                allowPartial,
+                bounded,
+            });
+        }
+        case "compress":
+            return handleCompressionOperation(repo, parsedArgs, engine, observe, bounded, graphRead);
+        case "pack": {
+            if (packAction !== undefined && !["export", "read", "grep"].includes(packAction))
+                throw new Error("knodin pack: invalid packAction");
+            if (packAction === "read") {
+                if (!artifactPath)
+                    throw new Error("knodin pack read requires `artifactPath`");
+                return bounded(readPackedArtifact(repo, artifactPath, startLine, endLine, byteBudget), "pack:read");
+            }
+            if (packAction === "grep") {
+                if (!artifactPath || !regex)
+                    throw new Error("knodin pack grep requires `artifactPath` and `regex`");
+                return bounded(grepPackedArtifact(repo, artifactPath, regex, regexFlags, limit), "pack:grep");
+            }
+            return observe(exportContext(repo, {
+                format,
+                include,
+                exclude,
+                policies: filePolicies,
+                alreadyPresent,
+                chatFiles,
+                lineNumbers,
+                includeTree,
+                outputPath,
+                byteBudget,
+                tokenBudget,
+                git: gitDiffScope || gitLog !== undefined
+                    ? { diffScope: gitDiffScope, from, to: toRevision, log: gitLog }
+                    : undefined,
+            }), "pack:export");
+        }
+        case "docs":
+            return handleDocsOperation(section, bounded);
+        case "explain":
+            if (!symbol)
+                throw new Error("knodin explain requires `symbol`");
+            return graphRead("explain", async () => {
+                const result = await engine.explain(symbol, repo, detailLevel === "minimal" ? "minimal" : "standard", selector);
+                if (detailLevel === "source" && !result.ambiguity)
+                    return compactExplainSource(result);
+                if (detailLevel === "minimal" && includeSource !== true && result && !result.ambiguity) {
+                    delete result.source;
+                    result.sourceOmitted = true;
+                    result.sourceContinuation = {
+                        operation: "explain",
+                        symbol,
+                        includeSource: true,
+                    };
+                }
+                return result;
+            }, detailLevel === "minimal");
+        case "review":
+            return graphRead("review", () => engine.review(base ?? "HEAD~1", repo, detailLevel === "minimal" ? "minimal" : "standard", {
+                scope: diffScope,
+                files: reviewFiles,
+                from,
+                to: toRevision,
+            }), detailLevel === "minimal");
+        case "map":
+            return graphRead("map", () => engine.map(repo, detailLevel === "standard" ? "standard" : "minimal", {
+                topN,
+                sort,
+                relationKinds,
+            }));
+        case "wiki":
+            return graphRead("wiki", () => engine.wiki(repo, force));
+        case "context": {
+            if (!task)
+                throw new Error("knodin context requires `task`");
+            return graphRead("context", () => buildKnodinContext(engine, task, repo, base, changedFiles));
+        }
+        case "search":
+            if (!query)
+                throw new Error("knodin search requires `query`");
+            if (offset !== undefined && (!Number.isInteger(offset) || offset < 0))
+                throw new Error("knodin search: offset must be a non-negative integer");
+            return graphRead("search", () => engine.search(query, repo, Math.min(limit ?? itemBudget ?? 5, itemBudget ?? 100), {
+                languages,
+                extensions,
+                kinds,
+                path,
+                testScope,
+                includeSource,
+                offset,
+            }));
+        case "prs": {
+            return bounded(await handlePullRequestsOperation({
+                repo,
+                engine,
+                limit,
+                prNumber,
+                prState,
+                branches,
+                auditRange,
+                auditBase,
+                auditHead,
+                expectedLogin,
+            }), "prs");
+        }
+        case "query": {
+            if (!pattern)
+                throw new Error("knodin query requires `pattern`");
+            if (!QUERY_PATTERNS.includes(pattern))
+                throw new Error(`knodin query: unknown pattern ${String(pattern)}`);
+            if (limit !== undefined && (!Number.isFinite(limit) || !Number.isInteger(limit) || limit < 1))
+                throw new Error("knodin query: limit must be a positive integer");
+            const repoWide = REPO_WIDE_QUERY_PATTERNS.includes(pattern);
+            if (!symbol && !repoWide)
+                throw new Error(`knodin query ${pattern} requires \`symbol\``);
+            if (pattern === "shortest_path" && !to)
+                throw new Error("knodin query shortest_path requires `to`");
+            if (pattern === "rename_preview" && !to)
+                throw new Error("knodin query rename_preview requires `symbol` and `to`");
+            const queryHealth = GRAPH_INDEPENDENT_QUERY_PATTERNS.has(pattern)
+                ? null
+                : await inspectGatewayGraphHealth(repo);
+            if (queryHealth && !queryHealth.available)
+                return bounded(queryHealth, `query:${pattern}`);
+            if (pattern === "rename_preview") {
+                // rename_preview routes through the rename engine: dry-run (preview +
+                // unified diff) by default, writing to disk only when `apply` is true.
+                return engine
+                    .rename(symbol ?? "", to ?? "", repo, apply === true, true, selector)
+                    .then((result) => bounded(decorateGraphQueryResult(result, queryHealth?.available ? queryHealth.state : "healthy", queryHealth?.available ? queryHealth.graph.freshness : undefined), "query:rename_preview"));
+            }
+            const queryResult = await engine.query(pattern, symbol ?? "", repo, to, Math.min(limit ?? itemBudget ?? 100, itemBudget ?? 1000), depth, detailLevel === "source" ? undefined : detailLevel, selector, pattern === "impact"
+                ? {
+                    mode: impactMode ?? "symbol",
+                    direction,
+                    relationKinds,
+                    minConfidence,
+                    includeTests,
+                    includeDataFlow,
+                }
+                : undefined, {
+                minLines,
+                minComplexity,
+                kinds,
+                path,
+                direction: pattern === "traverse" ? direction : undefined,
+                includeDataFlow: pattern === "traverse" ? includeDataFlow : undefined,
+                flowVariable: pattern === "flow_analysis" ? flowVariable : undefined,
+                architectureFacets,
+                topN,
+                sort,
+                relationKinds: pattern === "impact" ? undefined : relationKinds,
+                detailLevel: detailLevel === "source" ? undefined : detailLevel,
+            });
+            const verifiedQueryHealth = queryHealth ? await inspectGatewayGraphHealth(repo) : null;
+            if (verifiedQueryHealth && !verifiedQueryHealth.available)
+                return bounded(verifiedQueryHealth, `query:${pattern}`);
+            const result = pattern === "impact" || pattern === "dead_code"
+                ? incorporateSystemQueryEvidence(await enrichSystemRelationships(loadSystemConfiguration(repo)), repo, pattern, symbol ?? "", queryResult)
+                : queryResult;
+            return bounded(queryHealth?.available
+                ? decorateGraphQueryResult(result, verifiedQueryHealth?.available ? verifiedQueryHealth.state : queryHealth.state, verifiedQueryHealth?.available
+                    ? verifiedQueryHealth.graph.freshness
+                    : queryHealth.graph.freshness)
+                : result, `query:${pattern}`);
+        }
+        default:
+            throw new Error(`unknown knodin operation: ${String(operation)}`);
+    }
+}