@cruxy/cli 0.19.0 → 0.20.0

package/dist/cli/commands/run.js

@@ -11,6 +11,7 @@ import { buildHooksService } from "../../hooks/index.js";
 import { runInteractive } from "../repl.js";
 import { buildAgentSession } from "../session-factory.js";
 import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
+import { resetLspServices } from "../../lsp/index.js";
 export function runCommand() {
     return new Command("run")
         .description("run a task once, or start an interactive session")
@@ -92,7 +93,14 @@ export function runCommand() {
         });
         const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox, hooksService.runner);
         if (interactive) {
-            await runInteractive(session, undefined, renderer, checkpoints, hooksService.commands);
+            try {
+                await runInteractive(session, undefined, renderer, checkpoints, hooksService.commands);
+            }
+            finally {
+                // LSP (C.12): gracefully shut down any language servers spawned
+                // during the session (the process-exit kill-tree is the fail-safe).
+                await resetLspServices();
+            }
             return;
         }
         checkpoints?.beginRun(prompt);
@@ -110,6 +118,9 @@ export function runCommand() {
         }
         finally {
             renderer.close();
+            // LSP (C.12): gracefully shut down any language servers spawned during
+            // the run (the process-exit kill-tree is the fail-safe for a hard kill).
+            await resetLspServices();
         }
         // End-of-run usage summary (C.22): honest tokens + per-tier breakdown +
         // cost (only when priced). Printed after the live region is torn down.

package/dist/cli/session-factory.js

@@ -9,6 +9,7 @@ import { Session, } from "../agent/index.js";
 import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
 import { routerForConfig } from "../routing/index.js";
 import { MemoryService, rememberTool } from "../memory/index.js";
+import { findDefinitionTool, findReferencesTool, getDiagnosticsTool, hoverTool, } from "../lsp/index.js";
 import { appendRun } from "../usage/index.js";
 import { SubagentOrchestrator, makeSpawnSubagentTool, } from "../subagent/index.js";
 /**
@@ -136,6 +137,17 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             logger.warn(`memory: excluded ${e.scope} entry ${e.id} — ${e.message}`);
         }
     }
+    // Per-language LSP (C.12): register the four read-only introspection tools
+    // only when enabled. They spawn and manage EXTERNAL language-server processes,
+    // so — like the sandbox — the feature is opt-in; when off, none is registered
+    // and no server ever spawns. Read-only (no approval), so they bypass the U.3
+    // gate like search_codebase and are available to subagents and plan proposals.
+    if (config.lsp.enabled) {
+        execRegistry.register(findDefinitionTool);
+        execRegistry.register(findReferencesTool);
+        execRegistry.register(getDiagnosticsTool);
+        execRegistry.register(hoverTool);
+    }
     // One io shared by every prompt in the session (plan approval, the U.3 gate,
     // and any gate inside a subagent), so they all coordinate with the same live
     // region. The full wrapper stack around an ApprovalService is factored here

package/dist/config/schema.d.ts

@@ -236,8 +236,8 @@ export declare const TestConfigSchema: z.ZodObject<{
     captureBytes: number;
     command?: string | undefined;
 }, {
-    maxIterations?: number | undefined;
     command?: string | undefined;
+    maxIterations?: number | undefined;
     captureBytes?: number | undefined;
 }>;
 /**
@@ -264,9 +264,9 @@ export declare const SubagentConfigSchema: z.ZodObject<{
         maxIterations: number;
         timeoutMs?: number | undefined;
     }, {
+        timeoutMs?: number | undefined;
         maxTokens?: number | undefined;
         maxIterations?: number | undefined;
-        timeoutMs?: number | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
     maxDepth: number;
@@ -278,9 +278,9 @@ export declare const SubagentConfigSchema: z.ZodObject<{
 }, {
     maxDepth?: number | undefined;
     defaultBudget?: {
+        timeoutMs?: number | undefined;
         maxTokens?: number | undefined;
         maxIterations?: number | undefined;
-        timeoutMs?: number | undefined;
     } | undefined;
 }>;
 /**
@@ -408,6 +408,59 @@ export declare const MemoryConfigSchema: z.ZodObject<{
     maxRecallTokens?: number | undefined;
 }>;
 export type MemoryConfig = z.infer<typeof MemoryConfigSchema>;
+/**
+ * Per-language LSP integration (C.12): read-only, symbol-aware tools
+ * (find_definition, find_references, get_diagnostics, hover) backed by a
+ * managed pool of language servers. OFF by default — like the sandbox and
+ * hooks, it spawns and manages EXTERNAL server processes, a real execution
+ * surface the user opts into explicitly. When on, a missing server binary is
+ * an actionable, coded failure (CRUXY_E_LSP_SERVER_NOT_FOUND), never a silent
+ * empty result. Servers spawn lazily per language, are reused for the session,
+ * and are shut down cleanly (with a process-exit kill-tree backstop).
+ */
+export declare const LspConfigSchema: z.ZodObject<{
+    /** Master switch. When false, the four LSP tools are not registered and no
+     * server ever spawns (the feature stays fully inert). */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Per-language command overrides, keyed by language id (e.g. `typescript`,
+     * `python`, `go`, `rust`). The value is the full command line
+     * (`"gopls -remote=auto"`); it is split on whitespace. Anything omitted
+     * falls back to the built-in default table (see `lsp/registry.ts`).
+     */
+    servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /** Kill and fail (CRUXY_E_LSP_TIMEOUT) if the `initialize` handshake does
+     * not complete within this many ms. */
+    startupTimeout: z.ZodDefault<z.ZodNumber>;
+    /** Fail a single query (CRUXY_E_LSP_TIMEOUT) if the server does not respond
+     * within this many ms — the server is kept alive, only the request errors. */
+    requestTimeout: z.ZodDefault<z.ZodNumber>;
+    /** Maximum concurrently-running language servers; acquiring past the cap
+     * evicts the idle-oldest server first. */
+    maxServers: z.ZodDefault<z.ZodNumber>;
+    /** Shut a server down after it has been idle this many ms. */
+    idleTimeout: z.ZodDefault<z.ZodNumber>;
+    /** Cap on locations/diagnostics returned by a single tool call; the rest are
+     * summarized as an "N more" note (bounded output). */
+    maxResults: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    startupTimeout: number;
+    requestTimeout: number;
+    enabled: boolean;
+    servers: Record<string, string>;
+    maxServers: number;
+    idleTimeout: number;
+    maxResults: number;
+}, {
+    startupTimeout?: number | undefined;
+    requestTimeout?: number | undefined;
+    enabled?: boolean | undefined;
+    servers?: Record<string, string> | undefined;
+    maxServers?: number | undefined;
+    idleTimeout?: number | undefined;
+    maxResults?: number | undefined;
+}>;
+export type LspConfig = z.infer<typeof LspConfigSchema>;
 /** A per-tier price, in the user's own currency, PER MILLION TOKENS (C.22). */
 export declare const TierPriceSchema: z.ZodObject<{
     /** Price per 1,000,000 input tokens. */
@@ -547,12 +600,12 @@ export declare const McpServerSchema: z.ZodObject<{
     url: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     command?: string | undefined;
-    args?: string[] | undefined;
     url?: string | undefined;
+    args?: string[] | undefined;
 }, {
     command?: string | undefined;
-    args?: string[] | undefined;
     url?: string | undefined;
+    args?: string[] | undefined;
 }>;
 export declare const CruxyConfigSchema: z.ZodObject<{
     model: z.ZodDefault<z.ZodObject<{
@@ -742,6 +795,48 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines?: number | undefined;
         } | undefined;
     }>>;
+    lsp: z.ZodDefault<z.ZodObject<{
+        /** Master switch. When false, the four LSP tools are not registered and no
+         * server ever spawns (the feature stays fully inert). */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Per-language command overrides, keyed by language id (e.g. `typescript`,
+         * `python`, `go`, `rust`). The value is the full command line
+         * (`"gopls -remote=auto"`); it is split on whitespace. Anything omitted
+         * falls back to the built-in default table (see `lsp/registry.ts`).
+         */
+        servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        /** Kill and fail (CRUXY_E_LSP_TIMEOUT) if the `initialize` handshake does
+         * not complete within this many ms. */
+        startupTimeout: z.ZodDefault<z.ZodNumber>;
+        /** Fail a single query (CRUXY_E_LSP_TIMEOUT) if the server does not respond
+         * within this many ms — the server is kept alive, only the request errors. */
+        requestTimeout: z.ZodDefault<z.ZodNumber>;
+        /** Maximum concurrently-running language servers; acquiring past the cap
+         * evicts the idle-oldest server first. */
+        maxServers: z.ZodDefault<z.ZodNumber>;
+        /** Shut a server down after it has been idle this many ms. */
+        idleTimeout: z.ZodDefault<z.ZodNumber>;
+        /** Cap on locations/diagnostics returned by a single tool call; the rest are
+         * summarized as an "N more" note (bounded output). */
+        maxResults: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        startupTimeout: number;
+        requestTimeout: number;
+        enabled: boolean;
+        servers: Record<string, string>;
+        maxServers: number;
+        idleTimeout: number;
+        maxResults: number;
+    }, {
+        startupTimeout?: number | undefined;
+        requestTimeout?: number | undefined;
+        enabled?: boolean | undefined;
+        servers?: Record<string, string> | undefined;
+        maxServers?: number | undefined;
+        idleTimeout?: number | undefined;
+        maxResults?: number | undefined;
+    }>>;
     checkpoint: z.ZodDefault<z.ZodObject<{
         /** Auto-checkpoint before a run's first mutation (and enable `cruxy rollback`). */
         enabled: z.ZodDefault<z.ZodBoolean>;
@@ -773,9 +868,9 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             maxIterations: number;
             timeoutMs?: number | undefined;
         }, {
+            timeoutMs?: number | undefined;
             maxTokens?: number | undefined;
             maxIterations?: number | undefined;
-            timeoutMs?: number | undefined;
         }>>;
     }, "strict", z.ZodTypeAny, {
         maxDepth: number;
@@ -787,9 +882,9 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     }, {
         maxDepth?: number | undefined;
         defaultBudget?: {
+            timeoutMs?: number | undefined;
             maxTokens?: number | undefined;
             maxIterations?: number | undefined;
-            timeoutMs?: number | undefined;
         } | undefined;
     }>>;
     test: z.ZodDefault<z.ZodObject<{
@@ -804,8 +899,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         captureBytes: number;
         command?: string | undefined;
     }, {
-        maxIterations?: number | undefined;
         command?: string | undefined;
+        maxIterations?: number | undefined;
         captureBytes?: number | undefined;
     }>>;
     sandbox: z.ZodDefault<z.ZodObject<{
@@ -1015,12 +1110,12 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         url: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         command?: string | undefined;
-        args?: string[] | undefined;
         url?: string | undefined;
+        args?: string[] | undefined;
     }, {
         command?: string | undefined;
-        args?: string[] | undefined;
         url?: string | undefined;
+        args?: string[] | undefined;
     }>>>;
     logLevel: z.ZodDefault<z.ZodEnum<["debug", "info", "warn", "error", "silent"]>>;
 }, "strict", z.ZodTypeAny, {
@@ -1120,6 +1215,15 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines: number;
         };
     };
+    lsp: {
+        startupTimeout: number;
+        requestTimeout: number;
+        enabled: boolean;
+        servers: Record<string, string>;
+        maxServers: number;
+        idleTimeout: number;
+        maxResults: number;
+    };
     test: {
         maxIterations: number;
         captureBytes: number;
@@ -1135,8 +1239,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     };
     mcpServers: Record<string, {
         command?: string | undefined;
-        args?: string[] | undefined;
         url?: string | undefined;
+        args?: string[] | undefined;
     }>;
     logLevel: "debug" | "info" | "warn" | "error" | "silent";
 }, {
@@ -1186,9 +1290,9 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     subagent?: {
         maxDepth?: number | undefined;
         defaultBudget?: {
+            timeoutMs?: number | undefined;
             maxTokens?: number | undefined;
             maxIterations?: number | undefined;
-            timeoutMs?: number | undefined;
         } | undefined;
     } | undefined;
     model?: {
@@ -1236,9 +1340,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines?: number | undefined;
         } | undefined;
     } | undefined;
+    lsp?: {
+        startupTimeout?: number | undefined;
+        requestTimeout?: number | undefined;
+        enabled?: boolean | undefined;
+        servers?: Record<string, string> | undefined;
+        maxServers?: number | undefined;
+        idleTimeout?: number | undefined;
+        maxResults?: number | undefined;
+    } | undefined;
     test?: {
-        maxIterations?: number | undefined;
         command?: string | undefined;
+        maxIterations?: number | undefined;
         captureBytes?: number | undefined;
     } | undefined;
     hooks?: {
@@ -1251,8 +1364,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     } | undefined;
     mcpServers?: Record<string, {
         command?: string | undefined;
-        args?: string[] | undefined;
         url?: string | undefined;
+        args?: string[] | undefined;
     }> | undefined;
     logLevel?: "debug" | "info" | "warn" | "error" | "silent" | undefined;
 }>;

package/dist/config/schema.js

@@ -290,6 +290,44 @@ export const MemoryConfigSchema = z
     maxRecallTokens: z.number().int().positive().default(1000),
 })
     .strict();
+/**
+ * Per-language LSP integration (C.12): read-only, symbol-aware tools
+ * (find_definition, find_references, get_diagnostics, hover) backed by a
+ * managed pool of language servers. OFF by default — like the sandbox and
+ * hooks, it spawns and manages EXTERNAL server processes, a real execution
+ * surface the user opts into explicitly. When on, a missing server binary is
+ * an actionable, coded failure (CRUXY_E_LSP_SERVER_NOT_FOUND), never a silent
+ * empty result. Servers spawn lazily per language, are reused for the session,
+ * and are shut down cleanly (with a process-exit kill-tree backstop).
+ */
+export const LspConfigSchema = z
+    .object({
+    /** Master switch. When false, the four LSP tools are not registered and no
+     * server ever spawns (the feature stays fully inert). */
+    enabled: z.boolean().default(false),
+    /**
+     * Per-language command overrides, keyed by language id (e.g. `typescript`,
+     * `python`, `go`, `rust`). The value is the full command line
+     * (`"gopls -remote=auto"`); it is split on whitespace. Anything omitted
+     * falls back to the built-in default table (see `lsp/registry.ts`).
+     */
+    servers: z.record(z.string(), z.string().min(1)).default({}),
+    /** Kill and fail (CRUXY_E_LSP_TIMEOUT) if the `initialize` handshake does
+     * not complete within this many ms. */
+    startupTimeout: z.number().int().positive().default(15000),
+    /** Fail a single query (CRUXY_E_LSP_TIMEOUT) if the server does not respond
+     * within this many ms — the server is kept alive, only the request errors. */
+    requestTimeout: z.number().int().positive().default(10000),
+    /** Maximum concurrently-running language servers; acquiring past the cap
+     * evicts the idle-oldest server first. */
+    maxServers: z.number().int().positive().default(4),
+    /** Shut a server down after it has been idle this many ms. */
+    idleTimeout: z.number().int().positive().default(300000),
+    /** Cap on locations/diagnostics returned by a single tool call; the rest are
+     * summarized as an "N more" note (bounded output). */
+    maxResults: z.number().int().positive().default(100),
+})
+    .strict();
 /** A per-tier price, in the user's own currency, PER MILLION TOKENS (C.22). */
 export const TierPriceSchema = z
     .object({
@@ -346,6 +384,7 @@ export const CruxyConfigSchema = z
     context: ContextConfigSchema.default({}),
     approval: ApprovalConfigSchema.default({}),
     index: IndexConfigSchema.default({}),
+    lsp: LspConfigSchema.default({}),
     checkpoint: CheckpointConfigSchema.default({}),
     subagent: SubagentConfigSchema.default({}),
     test: TestConfigSchema.default({}),

package/dist/errors/constructors.d.ts

@@ -157,6 +157,29 @@ export declare function memoryInvalid(detail: string): CruxyError;
  * is your own local usage history, so deleting it loses nothing but history.
  */
 export declare function usageRead(path: string, reason: string, underlying?: unknown): CruxyError;
+/**
+ * No language server is available for a query: either no server is configured
+ * for the file's language, or the configured/default binary is not installed.
+ * THE CORE HONESTY RULE for C.12: this is a coded, actionable failure — it must
+ * NEVER collapse into an empty result, because "no server" would then read as
+ * "no references found". `installHint` carries the concrete next step.
+ */
+export declare function lspServerNotFound(language: string, reason: "no-spec" | "binary-missing", detail?: {
+    command?: string;
+    installHint?: string;
+}): CruxyError;
+/**
+ * A language server's `initialize` handshake or a single request exceeded its
+ * timeout. The process is killed (startup) or the request rejected (per-request)
+ * — cruxy never hangs waiting on an unresponsive server.
+ */
+export declare function lspTimeout(language: string, phase: "startup" | "request", timeoutMs: number): CruxyError;
+/**
+ * A language server crashed (its process exited unexpectedly) and could not be
+ * recovered — the single automatic restart also died. Distinct from a server
+ * that answered with zero results (that is an ordinary, non-error outcome).
+ */
+export declare function lspCrashed(language: string, detail?: string): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed

package/dist/errors/constructors.js

@@ -666,6 +666,73 @@ export function usageRead(path, reason, underlying) {
         meta: { path },
     });
 }
+// ── per-language LSP (exit 15) — C.12 ─────────────────────────────────────────
+/**
+ * No language server is available for a query: either no server is configured
+ * for the file's language, or the configured/default binary is not installed.
+ * THE CORE HONESTY RULE for C.12: this is a coded, actionable failure — it must
+ * NEVER collapse into an empty result, because "no server" would then read as
+ * "no references found". `installHint` carries the concrete next step.
+ */
+export function lspServerNotFound(language, reason, detail) {
+    const noSpec = reason === "no-spec";
+    return new CruxyError({
+        code: ErrorCode.LspServerNotFound,
+        title: noSpec
+            ? `no language server configured for "${language}"`
+            : `the "${language}" language server (${detail?.command ?? "?"}) is not installed`,
+        cause: noSpec
+            ? "this file's language has no entry in the default server table or `lsp.servers`"
+            : `\`${detail?.command ?? language}\` was not found on PATH`,
+        nextSteps: noSpec
+            ? [
+                `set a server command, e.g. \`cruxy config set lsp.servers.${language} "<command> --stdio"\``,
+            ]
+            : [
+                detail?.installHint ?? `install the ${language} language server`,
+                `or point cruxy at an installed one: \`cruxy config set lsp.servers.${language} "<command>"\``,
+            ],
+        meta: { language, reason, command: detail?.command },
+    });
+}
+/**
+ * A language server's `initialize` handshake or a single request exceeded its
+ * timeout. The process is killed (startup) or the request rejected (per-request)
+ * — cruxy never hangs waiting on an unresponsive server.
+ */
+export function lspTimeout(language, phase, timeoutMs) {
+    return new CruxyError({
+        code: ErrorCode.LspTimeout,
+        title: phase === "startup"
+            ? `the "${language}" language server did not start within ${timeoutMs}ms`
+            : `the "${language}" language server did not respond within ${timeoutMs}ms`,
+        cause: phase === "startup"
+            ? "the initialize handshake timed out; the process was killed"
+            : "the request timed out; the server was left running for later calls",
+        nextSteps: [
+            `raise the bound if the server is just slow to start: \`cruxy config set lsp.${phase === "startup" ? "startupTimeout" : "requestTimeout"} ${timeoutMs * 2}\``,
+            "re-run with --verbose to see the server's stderr",
+        ],
+        meta: { language, phase, timeoutMs },
+    });
+}
+/**
+ * A language server crashed (its process exited unexpectedly) and could not be
+ * recovered — the single automatic restart also died. Distinct from a server
+ * that answered with zero results (that is an ordinary, non-error outcome).
+ */
+export function lspCrashed(language, detail) {
+    return new CruxyError({
+        code: ErrorCode.LspCrashed,
+        title: `the "${language}" language server crashed`,
+        cause: detail ?? "the server process exited unexpectedly and did not recover",
+        nextSteps: [
+            "re-run with --verbose to see the server's stderr",
+            `verify the server runs standalone (the command in \`lsp.servers.${language}\` or the default)`,
+        ],
+        meta: { language },
+    });
+}
 // ── internal (exit 1) ─────────────────────────────────────────────────────────
 export function internal(underlying) {
     return new CruxyError({

package/dist/errors/types.d.ts

@@ -83,6 +83,16 @@ export declare const ErrorCode: {
     /** The local usage store is corrupt/unreadable — the read is SKIPPED and this
      * is surfaced; never fatal to a run (usage display is best-effort). */
     readonly UsageRead: "CRUXY_E_USAGE_READ";
+    /** A language server binary is not installed / not on PATH (or no server is
+     * configured for the file's language). Actionable, NEVER a silent empty
+     * result — "no server" must not read as "no references found". */
+    readonly LspServerNotFound: "CRUXY_E_LSP_SERVER_NOT_FOUND";
+    /** A server's `initialize` handshake or a single request exceeded its timeout
+     * — the process was killed / the request errored, never left to hang. */
+    readonly LspTimeout: "CRUXY_E_LSP_TIMEOUT";
+    /** A language server crashed (and, where applicable, a single restart also
+     * failed). Distinct from "server returned no results". */
+    readonly LspCrashed: "CRUXY_E_LSP_CRASHED";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -99,6 +99,17 @@ export const ErrorCode = {
     /** The local usage store is corrupt/unreadable — the read is SKIPPED and this
      * is surfaced; never fatal to a run (usage display is best-effort). */
     UsageRead: "CRUXY_E_USAGE_READ",
+    // per-language LSP (exit 15) — C.12
+    /** A language server binary is not installed / not on PATH (or no server is
+     * configured for the file's language). Actionable, NEVER a silent empty
+     * result — "no server" must not read as "no references found". */
+    LspServerNotFound: "CRUXY_E_LSP_SERVER_NOT_FOUND",
+    /** A server's `initialize` handshake or a single request exceeded its timeout
+     * — the process was killed / the request errored, never left to hang. */
+    LspTimeout: "CRUXY_E_LSP_TIMEOUT",
+    /** A language server crashed (and, where applicable, a single restart also
+     * failed). Distinct from "server returned no results". */
+    LspCrashed: "CRUXY_E_LSP_CRASHED",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -170,6 +181,12 @@ const EXIT_CODES = {
     // fix (delete the file); it shares the usage exit code and is never fatal to a
     // run — the aggregation just skips it.
     [ErrorCode.UsageRead]: 2,
+    // Per-language LSP (C.12). A missing server / timeout / crash surfaces inside
+    // a tool result (the agent reads and reroutes) and only exits the process if
+    // thrown directly; grouped for a greppable exit code.
+    [ErrorCode.LspServerNotFound]: 15,
+    [ErrorCode.LspTimeout]: 15,
+    [ErrorCode.LspCrashed]: 15,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/lsp/client.d.ts

@@ -0,0 +1,25 @@
+import type { LspPool } from "./pool.js";
+import type { LspDiagnostic, LspHover, LspLocation } from "./types.js";
+/**
+ * Typed, normalized LSP queries over a {@link LspPool} (C.12). Its only real
+ * job beyond delegating is the availability discipline: it resolves a file's
+ * language and acquires a server, letting the pool's coded errors (no server /
+ * timeout / crash) propagate — while a server's genuine `[]`/`null` answer flows
+ * back untouched. That keeps "couldn't ask" and "asked, nothing found" distinct
+ * all the way up to the tool boundary. Callers pass ABSOLUTE, in-root paths
+ * (validated by the tool via `resolveInRoot`); the server relativizes results.
+ */
+export declare class LspClient {
+    private readonly pool;
+    constructor(pool: LspPool);
+    definition(file: string, line: number, col: number): Promise<LspLocation[]>;
+    references(file: string, line: number, col: number): Promise<LspLocation[]>;
+    hover(file: string, line: number, col: number): Promise<LspHover | null>;
+    diagnostics(file: string): Promise<LspDiagnostic[]>;
+    /**
+     * Resolve the file's language and hand back a live server. An unmapped
+     * extension is a coded, actionable failure (`no-spec`) — NOT an empty result,
+     * so "unknown language" can never read as "no references found".
+     */
+    private serverFor;
+}

package/dist/lsp/client.js

@@ -0,0 +1,43 @@
+import path from "node:path";
+import { lspServerNotFound } from "../errors/index.js";
+import { languageForFile } from "./registry.js";
+/**
+ * Typed, normalized LSP queries over a {@link LspPool} (C.12). Its only real
+ * job beyond delegating is the availability discipline: it resolves a file's
+ * language and acquires a server, letting the pool's coded errors (no server /
+ * timeout / crash) propagate — while a server's genuine `[]`/`null` answer flows
+ * back untouched. That keeps "couldn't ask" and "asked, nothing found" distinct
+ * all the way up to the tool boundary. Callers pass ABSOLUTE, in-root paths
+ * (validated by the tool via `resolveInRoot`); the server relativizes results.
+ */
+export class LspClient {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async definition(file, line, col) {
+        return (await this.serverFor(file)).definition(file, line, col);
+    }
+    async references(file, line, col) {
+        return (await this.serverFor(file)).references(file, line, col);
+    }
+    async hover(file, line, col) {
+        return (await this.serverFor(file)).hover(file, line, col);
+    }
+    async diagnostics(file) {
+        return (await this.serverFor(file)).diagnostics(file);
+    }
+    /**
+     * Resolve the file's language and hand back a live server. An unmapped
+     * extension is a coded, actionable failure (`no-spec`) — NOT an empty result,
+     * so "unknown language" can never read as "no references found".
+     */
+    serverFor(file) {
+        const language = languageForFile(file);
+        if (!language) {
+            const ext = path.extname(file) || path.basename(file);
+            throw lspServerNotFound(ext, "no-spec");
+        }
+        return this.pool.acquire(language);
+    }
+}

package/dist/lsp/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export { DEFAULT_SPECS, EXT_TO_LANGUAGE, LspRegistry, binaryOnPath, languageForFile, } from "./registry.js";
+export { StdioTransport, TransportTimeoutError, killTree, } from "./transport.js";
+export { Server, type ServerTimeouts } from "./server.js";
+export { LspPool, type PoolOptions, type PoolDeps } from "./pool.js";
+export { LspClient } from "./client.js";
+export { getLspService, resetLspServices, type LspService, type LspServiceDeps, } from "./service.js";
+export { findDefinitionTool, findReferencesTool, getDiagnosticsTool, hoverTool, } from "./tools/index.js";

package/dist/lsp/index.js

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export { DEFAULT_SPECS, EXT_TO_LANGUAGE, LspRegistry, binaryOnPath, languageForFile, } from "./registry.js";
+export { StdioTransport, TransportTimeoutError, killTree, } from "./transport.js";
+export { Server } from "./server.js";
+export { LspPool } from "./pool.js";
+export { LspClient } from "./client.js";
+export { getLspService, resetLspServices, } from "./service.js";
+export { findDefinitionTool, findReferencesTool, getDiagnosticsTool, hoverTool, } from "./tools/index.js";