jeopi-cli 16.2.14 → 16.2.15

package/dist/types/irc/bus.d.ts

@@ -0,0 +1,85 @@
+/**
+ * IrcBus - Process-global mailbox bus for agent-to-agent messaging.
+ *
+ * Replaces the old auto-reply model: a `send` never blocks on the recipient
+ * generating anything. Delivery resolves the recipient via the global
+ * AgentRegistry — parked agents are revived through the
+ * AgentLifecycleManager, idle agents are woken with a real turn, and busy
+ * agents receive the message as a non-interrupting aside at the next step
+ * boundary (see AgentSession.deliverIrcMessage). Replies are real turns by
+ * the recipient, observed via `wait` — with one exception: when the sender
+ * awaits a reply and the recipient is mid-turn with async execution
+ * disabled, the recipient session generates an ephemeral side-channel
+ * auto-reply (it may be blocked in a synchronous task spawn whose batch
+ * includes the sender, so a real turn could never happen in time).
+ */
+import { AgentLifecycleManager } from "../registry/agent-lifecycle";
+import { AgentRegistry } from "../registry/agent-registry";
+export interface IrcMessage {
+    id: string;
+    /** Sender agent id. */
+    from: string;
+    /** Recipient agent id (resolved; "all" is expanded by the tool, not stored). */
+    to: string;
+    body: string;
+    ts: number;
+    /** Message id being answered. */
+    replyTo?: string;
+}
+export interface IrcDeliveryReceipt {
+    to: string;
+    outcome: "injected" | "woken" | "revived" | "failed";
+    error?: string;
+}
+export declare class IrcBus {
+    #private;
+    static global(): IrcBus;
+    /** Reset the global bus. Test-only. */
+    static resetGlobalForTests(): void;
+    constructor(registry?: AgentRegistry, lifecycle?: AgentLifecycleManager);
+    /**
+     * Fire-and-forget delivery. Never blocks on the recipient generating
+     * anything: the receipt reports how the message reached the recipient
+     * (waiter/aside = "injected", idle wake = "woken", park revival =
+     * "revived"), not what they did with it.
+     *
+     * Mailbox semantics: a successfully delivered message never lingers in
+     * the recipient's mailbox — injection/wake puts the full body into their
+     * context, so buffering it too would double-deliver via a later
+     * `wait`/`inbox` and inflate unread counts. Only a failed live hand-off
+     * is buffered for the recipient to drain later.
+     *
+     * `opts.expectsReply` marks sends whose caller is blocked on an answer
+     * (`send await:true`). It is forwarded to the recipient session so a
+     * mid-turn recipient that cannot reach a step boundary (async execution
+     * disabled — e.g. blocked in a synchronous task spawn awaiting the
+     * sender's own batch) can generate an ephemeral side-channel auto-reply
+     * instead of stranding the sender until timeout.
+     *
+     * `opts.suppressRelay` skips the display-only main-UI relay for this leg.
+     * Set by broadcast fan-out when the same broadcast also targets the main
+     * agent directly: the main agent then already sees the body as its own
+     * incoming card, so relaying the sibling legs would duplicate it.
+     */
+    send(msg: Omit<IrcMessage, "id" | "ts">, opts?: {
+        expectsReply?: boolean;
+        suppressRelay?: boolean;
+    }): Promise<IrcDeliveryReceipt>;
+    /**
+     * Block until a message for `agentId` (optionally from `filter.from`)
+     * arrives; consume + return it. Null on timeout (`timeoutMs <= 0` waits
+     * forever). Rejects when `signal` aborts. By default, already-buffered
+     * mail satisfies the wait before parking a future waiter; callers that
+     * need a strictly future reply can disable that drain.
+     */
+    wait(agentId: string, filter: {
+        from?: string;
+    }, timeoutMs: number, signal?: AbortSignal, options?: {
+        drainPending?: boolean;
+    }): Promise<IrcMessage | null>;
+    /** Drain (or peek) pending messages for `agentId`. */
+    inbox(agentId: string, opts?: {
+        peek?: boolean;
+    }): IrcMessage[];
+    unreadCount(agentId: string): number;
+}

package/dist/types/jsonrpc/message-framing.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared Content-Length message framing for the JSON byte streams spoken by the
+ * LSP and DAP stdio clients. Both protocols use the same base-protocol framing:
+ * each message is a `Content-Length: <n>\r\n\r\n` header block followed by `<n>`
+ * bytes of UTF-8 JSON. This module owns the incremental decode so the two
+ * clients don't each reimplement chunk accumulation, header scanning, and the
+ * mid-message remainder handoff.
+ */
+/**
+ * Incremental Content-Length frame decoder for a JSON message byte stream.
+ *
+ * Incoming bytes are buffered as a list of chunks and only joined when a full
+ * message is framed — concatenating the accumulator on every read is O(n^2) for
+ * messages that span many reads (e.g. a large initial diagnostics burst). Feed
+ * raw chunks with {@link push}, pull every complete message with {@link drain},
+ * and persist {@link remainder} when the reader stops so a restarted reader
+ * resumes mid-message.
+ */
+export declare class MessageFramer {
+    #private;
+    /** Seed the buffer with any unparsed remainder left by a previous reader. */
+    constructor(seed: Buffer);
+    /** Append a freshly read chunk to the pending buffer. */
+    push(chunk: Buffer): void;
+    /**
+     * Yield the JSON text of every complete message currently buffered. A header
+     * block without a `Content-Length` is non-protocol noise (e.g. a server
+     * printing to stdout); `onResync` is invoked with the offending header text
+     * and the framer drops past the bogus terminator to recover instead of
+     * stalling on the same junk header forever.
+     */
+    drain(onResync: (headerText: string) => void): Generator<string>;
+    /** The unparsed remainder, to persist when the reader stops. */
+    remainder(): Buffer;
+}

package/dist/types/lib/xai-http.d.ts

@@ -0,0 +1,40 @@
+import type { ModelRegistry } from "../config/model-registry";
+interface XAICredentials {
+    provider: "xai-oauth" | "xai";
+    apiKey: string;
+    baseURL: string;
+}
+export declare function ohMyPiXAIUserAgent(): string;
+/**
+ * Resolve xAI credentials for HTTP tool calls.
+ *
+ * Credential priority:
+ *   1. xai-oauth — only when a *dedicated* xai-oauth source exists. Composed
+ *      of two checks against the registry layer:
+ *        a. `authStorage.hasNonEnvCredential("xai-oauth")` covers stored
+ *           credentials (OAuth or api_key), runtime overrides (CLI
+ *           `--api-key` for xai-oauth), config overrides (models.yml
+ *           `providers.xai-oauth.apiKey`), and fallback resolvers.
+ *        b. `$env.XAI_OAUTH_TOKEN` covers the xai-oauth-specific env var.
+ *      `XAI_API_KEY` is intentionally NOT a signal here, even though the
+ *      env-fallback map (`stream.ts: "xai-oauth"`) lets xai-oauth borrow it
+ *      as a back-compat convenience: the borrow lets API-key-only setups
+ *      satisfy the xai-oauth branch and then resolve baseUrl under
+ *      xai-oauth instead of xai, silently bypassing `providers.xai.baseUrl`
+ *      overrides for image/TTS traffic. The gate routes the borrow case to
+ *      step 2 while preserving every dedicated xai-oauth path.
+ *   2. xai (plain API key). Delegates to ModelRegistry.getApiKeyForProvider
+ *      which runs AuthStorage.getApiKey's full cascade: runtime override →
+ *      models.yml config override → stored api_key credential → OAuth
+ *      resolution → XAI_API_KEY env var → custom fallback resolver.
+ *
+ * baseURL: see `resolveXAIBaseURL` above. Resolved AFTER the credential
+ * decision so the scoped (provider, id) lookup is unambiguous. `modelId`
+ * is optional; probes / tool-availability checks pass `undefined` and fall
+ * through to env/default.
+ *
+ * Returns null when neither credential is available. Caller is responsible
+ * for surfacing an actionable error message in that case.
+ */
+export declare function resolveXAIHttpCredentials(modelRegistry: ModelRegistry, modelId?: string): Promise<XAICredentials | null>;
+export {};

package/dist/types/lsp/client.d.ts

@@ -0,0 +1,84 @@
+import type { LspClient, ServerConfig } from "./types";
+/**
+ * Configure the idle timeout for LSP clients.
+ * @param ms - Timeout in milliseconds, or null/undefined to disable
+ */
+export declare function setIdleTimeout(ms: number | null | undefined): void;
+/** Timeout for warmup initialize requests (5 seconds) */
+export declare const WARMUP_TIMEOUT_MS = 5000;
+/**
+ * Get or create an LSP client for the given server configuration and working directory.
+ * @param config - Server configuration
+ * @param cwd - Working directory
+ * @param initTimeoutMs - Optional hard deadline for the initialize handshake (warmup / other
+ *   short-lived callers). When set it takes precedence over `signal` inside `sendRequest`.
+ * @param signal - Optional caller abort signal. Threaded into the initialize `sendRequest`
+ *   and the `initialized` notification so a wedged server surfaces the caller's
+ *   timeout/cancel instead of falling back to the internal 30s default.
+ */
+export declare function getOrCreateClient(config: ServerConfig, cwd: string, initTimeoutMs?: number, signal?: AbortSignal): Promise<LspClient>;
+/**
+ * Ensure a file is opened in the LSP client.
+ * Sends didOpen notification if the file is not already tracked.
+ */
+export declare function ensureFileOpen(client: LspClient, filePath: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Wait for the server's initial project loading to complete.
+ * Races the server's $/progress tracking against the abort signal.
+ * Returns immediately if loading already completed or timed out.
+ */
+export declare function waitForProjectLoaded(client: LspClient, signal?: AbortSignal): Promise<void>;
+/**
+ * Sync in-memory content to the LSP client without reading from disk.
+ * Use this to provide instant feedback during edits before the file is saved.
+ */
+export declare function syncContent(client: LspClient, filePath: string, content: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Notify LSP that a file was saved.
+ * Assumes content was already synced via syncContent - just sends didSave.
+ */
+export declare function notifySaved(client: LspClient, filePath: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Refresh a file in the LSP client.
+ * Increments version, sends didChange and didSave notifications.
+ */
+export declare function refreshFile(client: LspClient, filePath: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Shutdown a specific client by key.
+ */
+export declare function shutdownClient(key: string): Promise<void>;
+/**
+ * Send an LSP request and wait for response.
+ *
+ * Timeout policy:
+ * - If `timeoutMs` is explicitly provided, that value is used.
+ * - Else, if `signal` is provided, no internal timer is installed (the caller
+ *   owns the deadline via the signal — typically a wall-clock `AbortSignal.timeout`
+ *   from the LSP tool). Installing a second hard-coded 30s timer here used to
+ *   cause "timed out after 30000ms" errors even when the caller had requested
+ *   `timeout: 60`.
+ * - Else (no signal, no explicit timeout), fall back to `DEFAULT_REQUEST_TIMEOUT_MS`
+ *   to avoid leaking pending requests forever.
+ */
+export declare function sendRequest(client: LspClient, method: string, params: unknown, signal?: AbortSignal, timeoutMs?: number): Promise<unknown>;
+/**
+ * Send an LSP notification (no response expected).
+ * `signal` bounds the underlying `sink.flush()` — without it a server that
+ * stops draining stdin blocks every future write on the client's write queue.
+ */
+export declare function sendNotification(client: LspClient, method: string, params: unknown, signal?: AbortSignal): Promise<void>;
+/**
+ * Shutdown all LSP clients.
+ */
+export declare function shutdownAll(): Promise<void>;
+/** Status of an LSP server */
+export interface LspServerStatus {
+    name: string;
+    status: "connecting" | "ready" | "error";
+    fileTypes: string[];
+    error?: string;
+}
+/**
+ * Get status of all active LSP clients.
+ */
+export declare function getActiveClients(): LspServerStatus[];

package/dist/types/lsp/clients/biome-client.d.ts

@@ -0,0 +1,16 @@
+import type { Diagnostic, LinterClient, ServerConfig } from "../../lsp/types";
+/**
+ * Biome CLI-based linter client.
+ * Parses Biome's --reporter=json output into LSP Diagnostic format.
+ */
+export declare class BiomeClient implements LinterClient {
+    #private;
+    private readonly config;
+    private readonly cwd;
+    /** Factory method for creating BiomeClient instances */
+    static create(config: ServerConfig, cwd: string): LinterClient;
+    constructor(config: ServerConfig, cwd: string);
+    format(filePath: string, content: string): Promise<string>;
+    lint(filePath: string): Promise<Diagnostic[]>;
+    dispose(): void;
+}

package/dist/types/lsp/clients/index.d.ts

@@ -0,0 +1,19 @@
+import type { LinterClient, ServerConfig } from "../../lsp/types";
+/**
+ * Linter client implementations.
+ *
+ * The LinterClient interface provides a common API for formatters and linters.
+ * Different implementations can use LSP protocol, CLI tools, or other mechanisms.
+ */
+export { BiomeClient } from "./biome-client";
+export { LspLinterClient } from "./lsp-linter-client";
+export { SwiftLintClient } from "./swiftlint-client";
+/**
+ * Get or create a linter client for a server configuration.
+ * Uses the server's custom factory if provided, otherwise falls back to LSP.
+ */
+export declare function getLinterClient(serverName: string, config: ServerConfig, cwd: string): LinterClient;
+/**
+ * Clear all cached linter clients.
+ */
+export declare function clearLinterClientCache(): void;

package/dist/types/lsp/clients/lsp-linter-client.d.ts

@@ -0,0 +1,16 @@
+import type { Diagnostic, LinterClient, ServerConfig } from "../../lsp/types";
+/**
+ * LSP-based linter client implementation.
+ * Wraps the existing LSP client infrastructure.
+ */
+export declare class LspLinterClient implements LinterClient {
+    #private;
+    private readonly config;
+    private readonly cwd;
+    /** Factory method for creating LspLinterClient instances */
+    static create(config: ServerConfig, cwd: string): LinterClient;
+    constructor(config: ServerConfig, cwd: string);
+    format(filePath: string, content: string): Promise<string>;
+    lint(filePath: string): Promise<Diagnostic[]>;
+    dispose(): void;
+}

package/dist/types/lsp/clients/swiftlint-client.d.ts

@@ -0,0 +1,20 @@
+/**
+ * SwiftLint CLI-based linter client.
+ * Parses SwiftLint's JSON reporter output into LSP Diagnostic format.
+ */
+import type { Diagnostic, LinterClient, ServerConfig } from "../../lsp/types";
+/**
+ * SwiftLint CLI-based linter client.
+ * Runs `swiftlint lint --reporter json` and converts violations to LSP diagnostics.
+ */
+export declare class SwiftLintClient implements LinterClient {
+    #private;
+    private readonly config;
+    private readonly cwd;
+    /** Factory method for creating SwiftLintClient instances */
+    static create(config: ServerConfig, cwd: string): LinterClient;
+    constructor(config: ServerConfig, cwd: string);
+    format(_filePath: string, content: string): Promise<string>;
+    lint(filePath: string): Promise<Diagnostic[]>;
+    dispose(): void;
+}

package/dist/types/lsp/config.d.ts

@@ -0,0 +1,65 @@
+import type { ServerConfig } from "./types";
+export interface LspConfig {
+    servers: Record<string, ServerConfig>;
+    /** Idle timeout in milliseconds. If set, LSP clients will be shutdown after this period of inactivity. Disabled by default. */
+    idleTimeoutMs?: number;
+}
+/**
+ * Check if any root marker file exists in the directory
+ */
+export declare function hasRootMarkers(cwd: string, markers: string[]): boolean;
+/**
+ * Resolve a command to an executable path.
+ * Checks project-local bin directories first, then falls back to $PATH.
+ *
+ * @param command - The command name (e.g., "typescript-language-server")
+ * @param cwd - Working directory to search from
+ * @returns Absolute path to the executable, or null if not found
+ */
+export declare function resolveCommand(command: string, cwd: string): string | null;
+/**
+ * Load LSP configuration.
+ *
+ * Priority (highest to lowest):
+ * 1. Project root: lsp.json/.lsp.json/lsp.yml/.lsp.yml/lsp.yaml/.lsp.yaml
+ * 2. Project config dirs: .jeopi/lsp.*, .pi/lsp.*, .claude/lsp.* (+ hidden variants)
+ * 3. User config dirs: ~/.jeopi/agent/lsp.*, ~/.pi/agent/lsp.*, ~/.claude/lsp.* (+ hidden variants)
+ * 4. User home root: ~/lsp.*, ~/.lsp.*
+ * 5. Auto-detect from project markers + available binaries
+ *
+ * Config files are merged from lowest to highest priority; later files override earlier settings.
+ *
+ * Config file format (JSON or YAML):
+ * ```json
+ * {
+ *   "servers": {
+ *     "typescript-language-server": {
+ *       "command": "typescript-language-server",
+ *       "args": ["--stdio", "--log-level", "4"],
+ *       "disabled": false
+ *     },
+ *     "my-custom-server": {
+ *       "command": "/path/to/server",
+ *       "args": ["--stdio"],
+ *       "fileTypes": [".xyz"],
+ *       "rootMarkers": [".xyz-project"]
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare function loadConfig(cwd: string): LspConfig;
+/**
+ * Find all servers that can handle a file based on extension.
+ * Returns servers sorted with primary (non-linter) servers first.
+ */
+export declare function getServersForFile(config: LspConfig, filePath: string): Array<[string, ServerConfig]>;
+/**
+ * Find the primary server for a file (prefers type-checkers over linters).
+ * Used for operations like definition, hover, references that need type intelligence.
+ */
+export declare function getServerForFile(config: LspConfig, filePath: string): [string, ServerConfig] | null;
+/**
+ * Check if a server has a specific capability
+ */
+export declare function hasCapability(config: ServerConfig, capability: keyof NonNullable<ServerConfig["capabilities"]>): boolean;

package/dist/types/lsp/diagnostics-ledger.d.ts

@@ -0,0 +1,10 @@
+import type { FileDiagnosticsResult } from "./index";
+export declare function diagnosticIdentity(message: string): string;
+export declare class DiagnosticsLedger {
+    #private;
+    reduce(absPath: string, result: FileDiagnosticsResult): FileDiagnosticsResult;
+}
+export interface DiagnosticsLedgerOwner {
+    diagnosticsLedger?: DiagnosticsLedger;
+}
+export declare function getDiagnosticsLedger(owner: DiagnosticsLedgerOwner): DiagnosticsLedger;

package/dist/types/lsp/edits.d.ts

@@ -0,0 +1,32 @@
+import type { Range, TextEdit, WorkspaceEdit } from "./types";
+/**
+ * Apply text edits to a string in-memory.
+ * Edits are applied in reverse order (bottom-to-top) to preserve line/character indices.
+ */
+export declare function applyTextEditsToString(content: string, edits: TextEdit[]): string;
+/** True when two ranges overlap (share any position other than a touching boundary). */
+export declare function rangesOverlap(a: Range, b: Range): boolean;
+/**
+ * Sort edits bottom-to-top for in-place application and reject overlaps.
+ * Equal start positions tiebreak by original array index descending so that,
+ * applied bottom-up, inserts at the same position land in array order
+ * (LSP spec: the order of edits in the array defines the order in the result).
+ */
+export declare function sortAndValidateTextEdits(edits: TextEdit[]): TextEdit[];
+/**
+ * Flatten a WorkspaceEdit's text edits into a Map<uri, TextEdit[]>.
+ * Resource operations (create/rename/delete) are ignored — callers handle them separately.
+ */
+export declare function flattenWorkspaceTextEdits(edit: WorkspaceEdit): Map<string, TextEdit[]>;
+/**
+ * Apply text edits to a file.
+ * Edits are applied in reverse order (bottom-to-top) to preserve line/character indices.
+ */
+export declare function applyTextEdits(filePath: string, edits: TextEdit[]): Promise<void>;
+/**
+ * Apply a workspace edit (collection of file changes).
+ * All text-edit batches are overlap-validated before anything is written so a
+ * conflict throws without leaving the workspace half-applied.
+ * Returns array of applied change descriptions.
+ */
+export declare function applyWorkspaceEdit(edit: WorkspaceEdit, cwd: string): Promise<string[]>;

package/dist/types/lsp/format-options.d.ts

@@ -0,0 +1,32 @@
+/** Subset of the LSP `FormattingOptions` we send. */
+export interface LspFormattingOptions {
+    tabSize: number;
+    insertSpaces: boolean;
+    trimTrailingWhitespace: boolean;
+    insertFinalNewline: boolean;
+    trimFinalNewlines: boolean;
+}
+interface DetectedIndent {
+    tabSize?: number;
+    insertSpaces?: boolean;
+}
+/**
+ * Sniff `insertSpaces` and the indent unit from `content`.
+ *
+ * Walks the buffer once: the first indented line decides spaces vs tabs; for
+ * space indents, the GCD of all space-indent widths gives the stride (so a
+ * 2/4/6 file reports `2`, a 4/8 file reports `4`). Returns `undefined` for any
+ * field the content does not pin so a higher-precedence override (editorconfig)
+ * can win without being overwritten by sniffing noise.
+ */
+export declare function detectIndentFromContent(content: string): DetectedIndent;
+/**
+ * Resolve the `FormattingOptions` payload for a `textDocument/formatting` request
+ * targeting `filePath` with `content`.
+ *
+ * The two fields that actually affect on-disk bytes (`tabSize`, `insertSpaces`)
+ * are layered: editorconfig wins, then content sniffing, then the fallback.
+ * Trim/final-newline flags are static.
+ */
+export declare function resolveFormatOptions(filePath: string, content: string): LspFormattingOptions;
+export {};

package/dist/types/lsp/index.d.ts

@@ -0,0 +1,120 @@
+import type { BunFile } from "bun";
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback, ToolApprovalDecision } from "jeopi-agent-core";
+import { type Theme } from "../modes/theme/theme";
+import type { ToolSession } from "../tools";
+import { type LspServerStatus } from "./client";
+import { type LspParams, type LspToolDetails, lspSchema } from "./types";
+export type { LspServerStatus } from "./client";
+export type { LspToolDetails } from "./types";
+/**
+ * LSP actions that do not mutate the workspace or language-server state.
+ * Anything not in this set (rename, code_actions with apply, rename_file,
+ * reload, raw request, etc.) is classified as write-tier.
+ */
+export declare const LSP_READONLY_ACTIONS: ReadonlySet<string>;
+export interface LspStartupServerInfo {
+    name: string;
+    status: "connecting" | "ready" | "error" | "available";
+    fileTypes: string[];
+    error?: string;
+}
+/** Result from warming up LSP servers */
+export interface LspWarmupResult {
+    servers: Array<LspStartupServerInfo & {
+        status: "ready" | "error";
+    }>;
+}
+/** Options for warming up LSP servers */
+export interface LspWarmupOptions {
+    /** Called when starting to connect to servers */
+    onConnecting?: (serverNames: string[]) => void;
+}
+export declare function discoverStartupLspServers(cwd: string, status?: LspStartupServerInfo["status"]): LspStartupServerInfo[];
+/**
+ * Warm up LSP servers for a directory by connecting to all detected servers.
+ * This should be called at startup to avoid cold-start delays.
+ *
+ * @param cwd - Working directory to detect and start servers for
+ * @param options - Optional callbacks for progress reporting
+ * @returns Status of each server that was started
+ */
+export declare function warmupLspServers(cwd: string, options?: LspWarmupOptions): Promise<LspWarmupResult>;
+/**
+ * Get status of currently active LSP servers.
+ */
+export declare function getLspStatus(): LspServerStatus[];
+/** Result from getDiagnosticsForFile */
+export interface FileDiagnosticsResult {
+    /** Name of the LSP server used (if available) */
+    server?: string;
+    /** Formatted diagnostic messages */
+    messages: string[];
+    /** Summary string (e.g., "2 error(s), 1 warning(s)") */
+    summary: string;
+    /** Whether there are any errors (severity 1) */
+    errored: boolean;
+    /** Whether the file was formatted */
+    formatter?: FileFormatResult;
+}
+export declare enum FileFormatResult {
+    UNCHANGED = "unchanged",
+    FORMATTED = "formatted"
+}
+/** Options for creating the LSP writethrough callback */
+export interface WritethroughOptions {
+    /** Whether to format the file using LSP after writing */
+    enableFormat?: boolean;
+    /** Whether to get LSP diagnostics after writing */
+    enableDiagnostics?: boolean;
+    /** Called when diagnostics arrive after the main timeout. */
+    onDeferredDiagnostics?: (diagnostics: FileDiagnosticsResult) => void;
+    /** Signal to cancel a pending deferred diagnostics fetch. */
+    deferredSignal?: AbortSignal;
+    /** Transform diagnostics before surfacing them after a successful fetch. */
+    transformDiagnostics?: (absPath: string, result: FileDiagnosticsResult) => FileDiagnosticsResult;
+}
+/** Per-file deferred LSP diagnostics wiring for {@link WritethroughCallback}. */
+export type WritethroughDeferredHandle = {
+    onDeferredDiagnostics: (diagnostics: FileDiagnosticsResult) => void;
+    signal: AbortSignal;
+    finalize: (diagnostics: FileDiagnosticsResult | undefined) => void;
+};
+/** Callback type for the LSP writethrough */
+export type WritethroughCallback = (dst: string, content: string, signal?: AbortSignal, file?: BunFile, batch?: LspWritethroughBatchRequest, getDeferred?: (dst: string) => WritethroughDeferredHandle | undefined) => Promise<FileDiagnosticsResult | undefined>;
+/** No-op writethrough callback */
+export declare function writethroughNoop(dst: string, content: string, _signal?: AbortSignal, file?: BunFile, _batch?: LspWritethroughBatchRequest, _getDeferred?: (dst: string) => WritethroughDeferredHandle | undefined): Promise<FileDiagnosticsResult | undefined>;
+interface LspWritethroughBatchRequest {
+    id: string;
+    flush: boolean;
+}
+export declare function flushLspWritethroughBatch(id: string, cwd: string, signal?: AbortSignal): Promise<FileDiagnosticsResult | undefined>;
+/** Create a writethrough callback for LSP aware write operations */
+export declare function createLspWritethrough(cwd: string, options?: WritethroughOptions): WritethroughCallback;
+/**
+ * LSP tool for language server protocol operations.
+ */
+export declare class LspTool implements AgentTool<typeof lspSchema, LspToolDetails, Theme> {
+    private readonly session;
+    readonly name = "lsp";
+    readonly approval: (args: unknown) => ToolApprovalDecision;
+    readonly formatApprovalDetails: (args: unknown) => string[];
+    readonly label = "LSP";
+    readonly loadMode = "discoverable";
+    readonly summary = "Query LSP (language server) for diagnostics, hover info, and references";
+    readonly description: string;
+    readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
+        action: "capabilities" | "code_actions" | "definition" | "diagnostics" | "hover" | "implementation" | "references" | "reload" | "rename" | "rename_file" | "request" | "status" | "symbols" | "type_definition";
+        file?: string | undefined;
+        line?: number | undefined;
+        symbol?: string | undefined;
+        query?: string | undefined;
+        new_name?: string | undefined;
+        apply?: boolean | undefined;
+        timeout?: number | undefined;
+        payload?: string | undefined;
+    }, {}>;
+    readonly strict = true;
+    constructor(session: ToolSession);
+    static createIf(session: ToolSession): LspTool | null;
+    execute(_toolCallId: string, params: LspParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<LspToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<LspToolDetails>>;
+}

package/dist/types/lsp/lspmux.d.ts

@@ -0,0 +1,58 @@
+/**
+ * lspmux integration for LSP server multiplexing.
+ *
+ * When lspmux is available and running, this module wraps supported LSP server
+ * commands to use lspmux client mode, enabling server instance sharing across
+ * multiple editor windows.
+ *
+ * Integration is transparent: if lspmux is unavailable, falls back to direct spawning.
+ */
+interface LspmuxConfig {
+    instance_timeout?: number;
+    gc_interval?: number;
+    listen?: [string, number] | string;
+    connect?: [string, number] | string;
+    log_filters?: string;
+    pass_environment?: string[];
+}
+interface LspmuxState {
+    available: boolean;
+    running: boolean;
+    binaryPath: string | null;
+    config: LspmuxConfig | null;
+}
+/**
+ * Detect lspmux availability and state.
+ * Results are cached for STATE_CACHE_TTL_MS.
+ *
+ * Set PI_DISABLE_LSPMUX=1 to disable.
+ */
+export declare function detectLspmux(): Promise<LspmuxState>;
+/**
+ * Check if a server command is supported by lspmux.
+ */
+export declare function isLspmuxSupported(command: string): boolean;
+export interface LspmuxWrappedCommand {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+/**
+ * Wrap a server command to use lspmux client mode.
+ *
+ * @param originalCommand - The original LSP server command (e.g., "rust-analyzer")
+ * @param originalArgs - Original command arguments
+ * @param state - lspmux state from detectLspmux()
+ * @returns Wrapped command, args, and env vars; or original if lspmux unavailable
+ */
+export declare function wrapWithLspmux(originalCommand: string, originalArgs: string[] | undefined, state: LspmuxState): LspmuxWrappedCommand;
+/**
+ * Get lspmux-wrapped command if available, otherwise return original.
+ * This is the main entry point for config.ts integration.
+ *
+ * @param command - Original LSP server command
+ * @param args - Original command arguments
+ * @returns Command and args to use (possibly wrapped with lspmux)
+ */
+export declare function getLspmuxCommand(command: string, args?: string[]): Promise<LspmuxWrappedCommand>;
+export {};