@cruxy/cli 0.19.0 → 0.21.0

package/dist/lsp/tools/find-definition.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { formatLocations, runLspTool } from "./common.js";
+const parameters = z.object({
+    file: z
+        .string()
+        .min(1)
+        .describe("Project-relative path to the file containing the symbol."),
+    line: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based line number of the symbol to resolve."),
+    column: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based column of the symbol (position of the identifier)."),
+});
+/**
+ * LSP go-to-definition (C.12). Read-only — no approval, like search_codebase.
+ * Returns the definition site(s) as `path:line:col-endLine:endCol`. A missing
+ * language server is a coded, actionable error (distinct from "no definition
+ * found", which is an honest empty result).
+ */
+export const findDefinitionTool = {
+    name: "find_definition",
+    description: "Resolve where a symbol is defined using the project's language server (go-to-definition). Give the file and the 1-based line/column of the identifier. Returns definition locations as 'path:line:col-endLine:endCol'. Read-only, no approval. Precise where grep is textual — prefer this to jump to a symbol's definition.",
+    parameters,
+    execute(input, ctx) {
+        return runLspTool(ctx, input.file, async (service, absFile) => {
+            const locations = await service.definition(absFile, input.line, input.column);
+            if (locations.length === 0) {
+                return { ok: true, output: "(no definition found)" };
+            }
+            return {
+                ok: true,
+                output: formatLocations(locations, ctx.config.lsp.maxResults),
+            };
+        });
+    },
+};

package/dist/lsp/tools/find-references.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { Tool } from "../../tools/types.js";
+declare const parameters: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    line: number;
+    column: number;
+}, {
+    file: string;
+    line: number;
+    column: number;
+}>;
+/**
+ * LSP find-references (C.12). Read-only — no approval. Returns every use of the
+ * symbol (declaration included) as `path:line:col-endLine:endCol`, capped to
+ * `lsp.maxResults` with an "N more" note so a hot symbol can't flood the output.
+ * A missing server is a coded error, distinct from an honest "no references".
+ */
+export declare const findReferencesTool: Tool<typeof parameters>;
+export {};

package/dist/lsp/tools/find-references.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { formatLocations, runLspTool } from "./common.js";
+const parameters = z.object({
+    file: z
+        .string()
+        .min(1)
+        .describe("Project-relative path to the file containing the symbol."),
+    line: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based line number of the symbol."),
+    column: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based column of the symbol (position of the identifier)."),
+});
+/**
+ * LSP find-references (C.12). Read-only — no approval. Returns every use of the
+ * symbol (declaration included) as `path:line:col-endLine:endCol`, capped to
+ * `lsp.maxResults` with an "N more" note so a hot symbol can't flood the output.
+ * A missing server is a coded error, distinct from an honest "no references".
+ */
+export const findReferencesTool = {
+    name: "find_references",
+    description: "Find all references to a symbol using the project's language server. Give the file and the 1-based line/column of the identifier. Returns use sites as 'path:line:col-endLine:endCol' (capped, with an 'N more' note). Read-only, no approval. Precise where grep is textual — prefer this to see every caller/user of a symbol.",
+    parameters,
+    execute(input, ctx) {
+        return runLspTool(ctx, input.file, async (service, absFile) => {
+            const locations = await service.references(absFile, input.line, input.column);
+            if (locations.length === 0) {
+                return { ok: true, output: "(no references found)" };
+            }
+            return {
+                ok: true,
+                output: formatLocations(locations, ctx.config.lsp.maxResults),
+            };
+        });
+    },
+};

package/dist/lsp/tools/get-diagnostics.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import type { Tool } from "../../tools/types.js";
+declare const parameters: z.ZodObject<{
+    file: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+}, {
+    file: string;
+}>;
+/**
+ * LSP diagnostics (C.12): the language server's errors/warnings for a file.
+ * Read-only — no approval. Returns each diagnostic as
+ * `severity path:line:col message [source]`, capped to `lsp.maxResults`. A
+ * missing server is a coded error; a clean file is an honest empty result.
+ */
+export declare const getDiagnosticsTool: Tool<typeof parameters>;
+export {};

package/dist/lsp/tools/get-diagnostics.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { runLspTool } from "./common.js";
+const parameters = z.object({
+    file: z
+        .string()
+        .min(1)
+        .describe("Project-relative path to the file to diagnose."),
+});
+/**
+ * LSP diagnostics (C.12): the language server's errors/warnings for a file.
+ * Read-only — no approval. Returns each diagnostic as
+ * `severity path:line:col message [source]`, capped to `lsp.maxResults`. A
+ * missing server is a coded error; a clean file is an honest empty result.
+ */
+export const getDiagnosticsTool = {
+    name: "get_diagnostics",
+    description: "Get the language server's diagnostics (errors, warnings) for a file. Give the project-relative path. Returns diagnostics as 'severity path:line:col message'. Read-only, no approval. Use this after an edit to see type errors the compiler/linter reports, without running a build.",
+    parameters,
+    execute(input, ctx) {
+        return runLspTool(ctx, input.file, async (service, absFile) => {
+            const diagnostics = await service.diagnostics(absFile);
+            if (diagnostics.length === 0) {
+                return { ok: true, output: "(no diagnostics)" };
+            }
+            return {
+                ok: true,
+                output: formatDiagnostics(diagnostics, ctx.config.lsp.maxResults),
+            };
+        });
+    },
+};
+function formatDiagnostics(diagnostics, max) {
+    const shown = diagnostics.slice(0, max);
+    const lines = shown.map((d) => {
+        const src = d.source ? ` [${d.source}]` : "";
+        return `${d.severity} ${d.path}:${d.range.startLine}:${d.range.startCol} ${d.message}${src}`;
+    });
+    const omitted = diagnostics.length - shown.length;
+    if (omitted > 0) {
+        lines.push(`… [${omitted} more diagnostic(s) omitted]`);
+    }
+    return lines.join("\n");
+}

package/dist/lsp/tools/hover.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { Tool } from "../../tools/types.js";
+declare const parameters: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    line: number;
+    column: number;
+}, {
+    file: string;
+    line: number;
+    column: number;
+}>;
+/**
+ * LSP hover (C.12): type signature / documentation for the symbol at a position.
+ * Read-only — no approval. Returns the server's hover text (markup flattened to
+ * plain text). A missing server is a coded error; a symbol with no hover info is
+ * an honest empty result.
+ */
+export declare const hoverTool: Tool<typeof parameters>;
+export {};

package/dist/lsp/tools/hover.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { runLspTool } from "./common.js";
+const parameters = z.object({
+    file: z
+        .string()
+        .min(1)
+        .describe("Project-relative path to the file containing the symbol."),
+    line: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based line number of the symbol."),
+    column: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based column of the symbol (position of the identifier)."),
+});
+/**
+ * LSP hover (C.12): type signature / documentation for the symbol at a position.
+ * Read-only — no approval. Returns the server's hover text (markup flattened to
+ * plain text). A missing server is a coded error; a symbol with no hover info is
+ * an honest empty result.
+ */
+export const hoverTool = {
+    name: "hover",
+    description: "Get type information and documentation for a symbol using the project's language server (hover). Give the file and the 1-based line/column of the identifier. Returns the symbol's type signature and docs. Read-only, no approval. Use this to learn a symbol's type without opening and reading its declaration.",
+    parameters,
+    execute(input, ctx) {
+        return runLspTool(ctx, input.file, async (service, absFile) => {
+            const hover = await service.hover(absFile, input.line, input.column);
+            if (!hover) {
+                return { ok: true, output: "(no hover information)" };
+            }
+            return { ok: true, output: hover.contents };
+        });
+    },
+};

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

@@ -0,0 +1,4 @@
+export { findDefinitionTool } from "./find-definition.js";
+export { findReferencesTool } from "./find-references.js";
+export { getDiagnosticsTool } from "./get-diagnostics.js";
+export { hoverTool } from "./hover.js";

package/dist/lsp/tools/index.js

@@ -0,0 +1,4 @@
+export { findDefinitionTool } from "./find-definition.js";
+export { findReferencesTool } from "./find-references.js";
+export { getDiagnosticsTool } from "./get-diagnostics.js";
+export { hoverTool } from "./hover.js";

package/dist/lsp/transport.d.ts

@@ -0,0 +1,39 @@
+import { killTree, killTrackedTrees, trackedTreeCount } from "../utils/child-tree.js";
+import type { LspTransport, ServerSpec } from "./types.js";
+export { killTree };
+/** @deprecated Use the shared backstop; kept for LSP tests. */
+export declare const killTrackedServers: typeof killTrackedTrees;
+/** @deprecated Use the shared backstop; kept for LSP tests. */
+export declare const trackedServerCount: typeof trackedTreeCount;
+export declare class StdioTransport implements LspTransport {
+    private readonly child;
+    private nextId;
+    private readonly pending;
+    private readonly notificationHandlers;
+    private crashHandler;
+    /** stdout parse buffer (header + body may arrive across chunks). */
+    private buffer;
+    private disposed;
+    /** Deregisters this process from the process-exit kill-tree backstop. */
+    private readonly unregisterCleanup;
+    constructor(spec: ServerSpec, root: string);
+    request(method: string, params: unknown, timeoutMs: number): Promise<unknown>;
+    notify(method: string, params: unknown): void;
+    onNotification(method: string, handler: (params: unknown) => void): void;
+    onCrash(handler: (info: {
+        code: number | null;
+        signal: string | null;
+    }) => void): void;
+    dispose(force?: boolean): Promise<void>;
+    private send;
+    private onStdout;
+    private dispatch;
+    private onExit;
+    private onSpawnError;
+}
+/** A per-request timeout, distinguishable from an ordinary LSP error response. */
+export declare class TransportTimeoutError extends Error {
+    readonly method: string;
+    readonly timeoutMs: number;
+    constructor(method: string, timeoutMs: number);
+}

package/dist/lsp/transport.js

@@ -0,0 +1,208 @@
+import { spawn } from "node:child_process";
+import { killTree, killTrackedTrees, registerForCleanup, trackedTreeCount, } from "../utils/child-tree.js";
+// Re-exported under their historical LSP names so callers and tests keep
+// importing them from here; the machinery now lives in the shared child-tree
+// backstop (also used by the C.27 MCP transport) so exit-time reaping is
+// unified across every managed process tree.
+export { killTree };
+/** @deprecated Use the shared backstop; kept for LSP tests. */
+export const killTrackedServers = killTrackedTrees;
+/** @deprecated Use the shared backstop; kept for LSP tests. */
+export const trackedServerCount = trackedTreeCount;
+/**
+ * JSON-RPC 2.0 over a language server's stdio (C.12). Owns the child process:
+ * spawns it in its OWN process group (`detached`) so the whole tree is killable,
+ * frames messages with `Content-Length` headers, correlates responses to
+ * requests by id, times out per request, and detects a crash (unexpected exit).
+ *
+ * This is the real {@link LspTransport}; tests inject a fake peer instead, so no
+ * real language-server binary is required in CI.
+ */
+const GRACE_MS = 2000;
+export class StdioTransport {
+    child;
+    nextId = 1;
+    pending = new Map();
+    notificationHandlers = new Map();
+    crashHandler = null;
+    /** stdout parse buffer (header + body may arrive across chunks). */
+    buffer = Buffer.alloc(0);
+    disposed = false;
+    /** Deregisters this process from the process-exit kill-tree backstop. */
+    unregisterCleanup;
+    constructor(spec, root) {
+        // `detached` makes the child a process-group leader so the whole tree can be
+        // killed via a negative-PID signal — same discipline as run_command (C.16).
+        this.child = spawn(spec.command, spec.args, {
+            cwd: root,
+            detached: true,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.unregisterCleanup = registerForCleanup(this.child.pid);
+        this.child.stdout?.on("data", (chunk) => this.onStdout(chunk));
+        // Server stderr is diagnostic only; surface nothing by default (it's noisy).
+        this.child.stderr?.on("data", () => { });
+        this.child.on("exit", (code, signal) => this.onExit(code, signal));
+        this.child.on("error", (err) => this.onSpawnError(err));
+    }
+    request(method, params, timeoutMs) {
+        if (this.disposed) {
+            return Promise.reject(new Error("transport disposed"));
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new TransportTimeoutError(method, timeoutMs));
+            }, timeoutMs);
+            // Don't let a pending request keep the event loop alive.
+            timer.unref?.();
+            this.pending.set(id, { resolve, reject, timer });
+            this.send({ jsonrpc: "2.0", id, method, params });
+        });
+    }
+    notify(method, params) {
+        if (this.disposed)
+            return;
+        this.send({ jsonrpc: "2.0", method, params });
+    }
+    onNotification(method, handler) {
+        const list = this.notificationHandlers.get(method) ?? [];
+        list.push(handler);
+        this.notificationHandlers.set(method, list);
+    }
+    onCrash(handler) {
+        this.crashHandler = handler;
+    }
+    async dispose(force = false) {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.unregisterCleanup();
+        // Reject anything still in flight so callers never hang on teardown.
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error("transport disposed"));
+        }
+        this.pending.clear();
+        if (!this.child.pid || this.child.exitCode !== null)
+            return;
+        if (force) {
+            killTree(this.child.pid);
+            return;
+        }
+        // Give the process a grace window to exit on its own (the caller has
+        // already sent the LSP `exit` notification), then force-kill the group.
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                killTree(this.child.pid);
+                resolve();
+            }, GRACE_MS);
+            timer.unref?.();
+            this.child.once("exit", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+    // ── framing ─────────────────────────────────────────────────────────────────
+    send(message) {
+        const body = Buffer.from(JSON.stringify(message), "utf8");
+        const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, "ascii");
+        this.child.stdin?.write(Buffer.concat([header, body]));
+    }
+    onStdout(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        // Drain every fully-received message currently in the buffer.
+        for (;;) {
+            const headerEnd = this.buffer.indexOf("\r\n\r\n");
+            if (headerEnd === -1)
+                return;
+            const header = this.buffer.subarray(0, headerEnd).toString("ascii");
+            const match = /content-length:\s*(\d+)/i.exec(header);
+            if (!match) {
+                // Malformed header — drop it and resync past the separator.
+                this.buffer = this.buffer.subarray(headerEnd + 4);
+                continue;
+            }
+            const length = Number(match[1]);
+            const bodyStart = headerEnd + 4;
+            if (this.buffer.length < bodyStart + length)
+                return; // body not complete yet
+            const body = this.buffer.subarray(bodyStart, bodyStart + length);
+            this.buffer = this.buffer.subarray(bodyStart + length);
+            this.dispatch(body.toString("utf8"));
+        }
+    }
+    dispatch(text) {
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch {
+            return; // ignore unparseable frames
+        }
+        // Response to one of our requests.
+        if (typeof msg.id === "number" && (msg.result !== undefined || msg.error)) {
+            const pending = this.pending.get(msg.id);
+            if (!pending)
+                return;
+            this.pending.delete(msg.id);
+            clearTimeout(pending.timer);
+            if (msg.error)
+                pending.reject(new Error(msg.error.message ?? "LSP error"));
+            else
+                pending.resolve(msg.result);
+            return;
+        }
+        // Server → client notification (e.g. textDocument/publishDiagnostics).
+        if (typeof msg.method === "string" && msg.id === undefined) {
+            for (const handler of this.notificationHandlers.get(msg.method) ?? []) {
+                handler(msg.params);
+            }
+        }
+        // Server → client requests (e.g. workspace/configuration) are unsupported;
+        // we intentionally don't reply — our advertised capabilities don't ask for
+        // features that require a mandatory response.
+    }
+    onExit(code, signal) {
+        this.unregisterCleanup();
+        if (this.disposed)
+            return; // an expected shutdown, not a crash
+        // Unexpected exit → a crash. The server's OWN child processes (e.g. gopls's
+        // `go`, rust-analyzer's `cargo`) can outlive it — reap the whole group so a
+        // crash never orphans them. The group persists as long as any member lives,
+        // so the negative-pid signal still lands even though the leader is gone.
+        killTree(this.child.pid);
+        // Reject everything in flight, then notify.
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error(`language server exited (code ${code}, signal ${signal})`));
+        }
+        this.pending.clear();
+        this.crashHandler?.({ code, signal });
+    }
+    onSpawnError(err) {
+        // The binary vanished between the presence check and spawn, or is not
+        // executable. Treat as a crash so the pool surfaces a coded error.
+        if (this.disposed)
+            return;
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(err);
+        }
+        this.pending.clear();
+        this.crashHandler?.({ code: null, signal: null });
+    }
+}
+/** A per-request timeout, distinguishable from an ordinary LSP error response. */
+export class TransportTimeoutError extends Error {
+    method;
+    timeoutMs;
+    constructor(method, timeoutMs) {
+        super(`LSP request "${method}" timed out after ${timeoutMs}ms`);
+        this.method = method;
+        this.timeoutMs = timeoutMs;
+        this.name = "TransportTimeoutError";
+    }
+}

package/dist/lsp/types.d.ts

@@ -0,0 +1,107 @@
+import type { LspConfig } from "../config/index.js";
+/**
+ * Per-language LSP integration (C.12) — the shared vocabulary. Results here are
+ * NORMALIZED (1-based lines/columns, project-relative paths, plain severities):
+ * the LSP wire format's 0-based positions and `file://` URIs are converted at
+ * the edge (`server.ts`) so nothing downstream speaks raw LSP.
+ */
+export type { LspConfig };
+/**
+ * A source range, normalized to 1-based lines and columns (LSP is 0-based; we
+ * add 1 at the boundary). `path` is project-relative for display.
+ */
+export interface LspLocation {
+    /** Project-relative file path. */
+    path: string;
+    /** 1-based start line. */
+    startLine: number;
+    /** 1-based start column. */
+    startCol: number;
+    /** 1-based end line. */
+    endLine: number;
+    /** 1-based end column. */
+    endCol: number;
+}
+/** A normalized diagnostic (severity mapped off the LSP 1–4 integer scale). */
+export interface LspDiagnostic {
+    /** Project-relative file path. */
+    path: string;
+    /** Where the diagnostic applies (1-based). */
+    range: LspLocation;
+    severity: "error" | "warning" | "info" | "hint";
+    message: string;
+    /** The producing tool, when the server reports it (e.g. "tsc", "gopls"). */
+    source?: string;
+}
+/** A normalized hover result — markdown/markup flattened to plain text. */
+export interface LspHover {
+    contents: string;
+    /** The symbol range the hover describes, when the server reports it. */
+    range?: LspLocation;
+}
+/**
+ * A single, initialized language server (≈ one live child process). Queries are
+ * absolute-path in / normalized-out; the client relativizes paths against the
+ * workspace root. A method resolving to `[]`/`null` is an honest "no result" —
+ * unavailability is signalled by a thrown coded error from the pool, never here.
+ */
+export interface LanguageServer {
+    readonly language: string;
+    /** True until the process exits (crash detection flips this to false). */
+    readonly alive: boolean;
+    definition(file: string, line: number, col: number): Promise<LspLocation[]>;
+    references(file: string, line: number, col: number): Promise<LspLocation[]>;
+    diagnostics(file: string): Promise<LspDiagnostic[]>;
+    hover(file: string, line: number, col: number): Promise<LspHover | null>;
+    /** LSP `shutdown` → `exit`, then force-kill the process group after a grace. */
+    shutdown(force?: boolean): Promise<void>;
+}
+/** How to launch one language's server, resolved from config ∪ the default table. */
+export interface ServerSpec {
+    language: string;
+    /** Executable name or absolute path. */
+    command: string;
+    /** Argument vector (e.g. `["--stdio"]`). */
+    args: string[];
+    /** Concrete install instruction, surfaced when the binary is missing. */
+    installHint?: string;
+}
+/**
+ * The registry's answer for a language. Availability is EXPLICIT: an
+ * unavailable server carries the reason so the caller raises a coded,
+ * actionable error rather than silently returning nothing.
+ */
+export type ServerResolution = {
+    available: true;
+    spec: ServerSpec;
+} | {
+    available: false;
+    language: string;
+    spec: ServerSpec | null;
+    reason: "no-spec" | "binary-missing";
+};
+/**
+ * The one seam tests replace: a live JSON-RPC peer over the server's stdio. A
+ * fake implementation lets the whole stack run with NO real language-server
+ * binary (mirroring `RecordingRuntime` for the sandbox).
+ */
+export interface LspTransport {
+    /** Send a request and await its response, rejecting after `timeoutMs`. */
+    request(method: string, params: unknown, timeoutMs: number): Promise<unknown>;
+    /** Fire-and-forget notification (no response expected). */
+    notify(method: string, params: unknown): void;
+    /** Register a handler for a server→client notification (e.g. diagnostics). */
+    onNotification(method: string, handler: (params: unknown) => void): void;
+    /** Register a one-shot crash callback (process exited unexpectedly). */
+    onCrash(handler: (info: {
+        code: number | null;
+        signal: string | null;
+    }) => void): void;
+    /** LSP graceful path already sent by the caller; drop the transport,
+     * force-killing the process group after the grace when `force` is set. */
+    dispose(force?: boolean): Promise<void>;
+}
+/** Builds a transport for a resolved spec, rooted at `root`. Injectable in tests. */
+export type TransportFactory = (spec: ServerSpec, root: string) => LspTransport;
+/** Predicate: is `command` runnable (on PATH, or an existing executable path)? */
+export type BinaryPresent = (command: string) => boolean;

package/dist/lsp/types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/adapter.d.ts

@@ -0,0 +1,44 @@
+import type { Tool } from "../tools/types.js";
+import { type McpBounds } from "./bounds.js";
+import type { McpCallResult, RawMcpTool } from "./types.js";
+/**
+ * THE SINGLE SEAM (C.27). `mcpToolsFrom` is the ONE and ONLY place an MCP server
+ * becomes an agent {@link Tool}. Nothing else in the codebase constructs an
+ * MCP-backed tool, so every security property is enforced here, by construction:
+ *
+ * - GATE. Every produced tool's `execute` calls `ctx.requestApproval({kind:"mcp",
+ *   …})` BEFORE it ever calls the server. A rejection returns the feedback as the
+ *   tool result and `tools/call` never fires. The action is classified
+ *   `destructive` and the classifier never reads the server's `readOnlyHint`
+ *   (which this adapter deliberately does not even forward) — a server cannot
+ *   self-declare its tool safe. A session grant is keyed on the exact server+tool
+ *   pair, so approving one tool never covers another.
+ * - DEMARCATE + GAG. Both the advertised description and every result are wrapped
+ *   as untrusted external data with upstream model names scrubbed
+ *   ({@link demarcateDescription} / {@link demarcateResult}) — the model never
+ *   sees a raw, un-boxed description or result.
+ * - BOUNDS. The server's tool list is capped in count and per-tool size
+ *   ({@link boundToolList}); overflow is truncated with a visible note, never a
+ *   silent drop or an unbounded context blow-up.
+ * - NON-PERSISTENCE. `execute` returns a plain {@link ToolResult}; it writes to
+ *   no store. Results live only in the in-memory conversation (asserted by test).
+ *
+ * Trust is enforced UPSTREAM (the service never calls this until the server is
+ * trusted), so reaching this function already means "the user accepted running
+ * this server's code unsandboxed".
+ */
+export interface McpToolSource {
+    /** The configured server id (the tool-name prefix and gate key). */
+    server: string;
+    /** Tools exactly as the server advertised them (untrusted). */
+    tools: readonly RawMcpTool[];
+    /** Invoke a tool on the server by its ORIGINAL name. Adapter-internal only. */
+    call(toolName: string, args: unknown): Promise<McpCallResult>;
+    /** Size/count caps for the advertised list. */
+    bounds: McpBounds;
+    /** Where the visible "N tools dropped" note is surfaced. */
+    logger?: {
+        warn(message: string): void;
+    };
+}
+export declare function mcpToolsFrom(source: McpToolSource): Tool[];