@aiwayds/dsh-mcp-adapter 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# dsh-mcp-adapter
+
+English | [简体中文](README.zh.md)
+
+Token-efficient MCP adapter for [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) — a **prompt-side shim** inspired by [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter).
+
+## The problem
+
+The official `@deepseek-ai/dsh-mcp-client` plugin registers every discovered MCP tool natively (`mcp__<server>__<tool>`), so **every request pays the full JSON Schema of every MCP tool** — the upstream README states this outright: *"Data-dependent schema cost is paid on every request while the tools are registered."* With a handful of servers and dozens of tools, that is thousands of tokens burned per message, whether or not the model ever calls them.
+
+## The approach
+
+This plugin keeps the official `dsh-mcp-client` as the connection layer (transports, reconnect, `tools/list_changed` re-sync — all upstream) and intervenes only at prompt assembly:
+
+- every `mcp__*` tool schema is **folded out** of the assembled prompt (`system-prompt/assemble` waterfall);
+- two **constant meta-tools** take their place, so standing prompt cost is O(1) in the number of servers/tools:
+  - **`mcp_list`** — compact catalog (tool names + truncated descriptions, no schemas); pass `tool` to expand one tool's full schema on demand, `server` to filter, `verbose` for everything;
+  - **`mcp_call`** — dispatch `{ tool, arguments }` to the still-registered definition, passing the run context through.
+
+Tools stay registered in `ctx.tools`, so TUI rendering and `tools.restrict()` masking keep working — only the prompt payload changes. A folded, constant tool list is also friendlier to KV-prefix caching than upstream's per-resync generation swap.
+
+One pipeline nuance: pre-execute / guard / post-execute stages that match by the child tool's name (`mcp__server__tool`) never fire for folded calls — the registry only sees the outer `mcp_call`. To gate MCP usage (approvals, policy), guard **`mcp_call` itself**.
+
+Image results keep their native behavior: `mcp_call` delegates `output.render` to the dispatched child and forwards the child's `finalizeContent` with the exact same run-execution object, so image-bearing MCP results still project to durable attachment references instead of inlining base64 into the context.
+
+**Fail-open:** if the meta-tools are not registered (name collision, partial startup), the adapter leaves the assembly untouched — you fall back to official full passthrough, never to undiscoverable tools.
+
+**Code Mode:** under `mode: 'code'` the wire already collapses to `run_code`; this plugin is a no-op there.
+
+**Load position:** loaded through host composition (the `cordis.patch.yml` `insert` below) the adapter is global — every agent's assemblies are folded. Loaded through an agent-scoped context instead, it applies only to that agent.
+
+## Setup
+
+Keep (or add) your `@deepseek-ai/dsh-mcp-client` lines in `cordis.patch.yml`, then add this plugin next to them:
+
+```yaml
+- insert:
+    - id: dsh-mcp-adapter
+      name: '@aiwayds/dsh-mcp-adapter'
+      config: {}
+```
+
+Install:
+
+```
+dsh plugin --profile <name> add @aiwayds/dsh-mcp-adapter
+```
+
+Or directly from git:
+
+```
+dsh plugin --profile <name> add github:fan56/dsh-mcp-adapter
+```
+
+## Config
+
+| key | default | meaning |
+|---|---|---|
+| `prefix` | `"mcp__"` | tool-name prefix to fold |
+| `keep` | `[]` | name patterns (`*` wildcard) kept native — pi-mcp-adapter's "direct mode", for high-frequency tools that deserve first-class schemas |
+| `servers` | `[]` | server-name whitelist: when non-empty, only these servers' tools are folded / cataloged / dispatchable (all three consult the same list) |
+| `descriptionLimit` | `200` | max chars per tool description in the `mcp_list` catalog |
+
+```yaml
+config:
+  keep:
+    - mcp__fs__read_file
+    - mcp__github__*
+  servers:
+    - fs
+    - github
+```
+
+**Trust boundary:** by default every `prefix`-matching tool is folded — the prefix is a naming convention, not a security boundary, so tools registered by third-party plugins that happen to use `mcp__*` names fold too. To trust only the official client's servers, list them explicitly in `servers`; everything else stays native (still callable directly, just outside the meta-tools).
+
+## Notes
+
+- `mcp_call` only accepts `prefix`-matching tools (and, when `servers` is set, whitelisted servers) — it can never be used to bypass another tool's own pre-execute pipeline.
+- Known boundary (waterfall order): an assemble listener registered **before** this plugin that adds `mcp__*` schemas after its own `next()` would escape the fold — this plugin folds what the assembled prompt contains when its listener runs. No such listener exists upstream today.
+- Server names in the catalog are derived heuristically as the first `__`-delimited segment after the prefix (server names are `[A-Za-z0-9_-]{1,32}`, so a literal `__` inside a server name would mis-group).
+- Coexists with [ben7am1n/dsh-mcp-proxy](https://github.com/ben7am1n/dsh-mcp-proxy) (connection-side proxy with its own servers — different, non-colliding tool names). That project credits pi-mcp-adapter as prior art too; this repo is an independent prompt-side take that reuses the official client instead of re-implementing connections.
+- Trade-offs (same as pi-mcp-adapter): one extra discovery round-trip before the first call, and expanded schemas still occupy context once the model pulls them in.
+
+## Development
+
+```
+npm install && npm run check && npm test
+```
+
+`@deepseek-ai/*` types resolve from the global dsh closure via `scripts/link-dsh-closure.mjs` (run automatically by `precheck`) — they are deliberately absent from `package.json` so a single cordis instance exists in the type graph. See `DESIGN.md` for the full design rationale and upstream references.

package/README.zh.md

@@ -0,0 +1,82 @@
+# dsh-mcp-adapter
+
+[English](README.md) | 简体中文
+
+面向 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 的省 token MCP 适配器——一个受 [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) 启发的 **prompt-side shim**（提示词侧垫片）。
+
+## 问题
+
+官方 `@deepseek-ai/dsh-mcp-client` 插件把发现的每个 MCP 工具都原生注册进工具表（`mcp__<server>__<tool>`），于是**每次请求都要为每个 MCP 工具的完整 JSON Schema 付费**——上游 README 原话：*"Data-dependent schema cost is paid on every request while the tools are registered."* 几个 server、几十个工具下来，就是每条消息烧掉数千 token，无论模型是否真的调用它们。
+
+## 思路
+
+本插件完全保留官方 `dsh-mcp-client` 作为连接层（transport、自动重连、`tools/list_changed` 重同步——全是上游现成的），只在提示词装配这一处介入：
+
+- 每个匹配的 `mcp__*` 工具 schema 被**折叠出**装配后的 prompt（`system-prompt/assemble` waterfall）；
+- 原位换上两个**恒定 meta-tool**，常驻 prompt 成本对 server/工具数量而言是 O(1)：
+  - **`mcp_list`** — 紧凑目录（工具名 + 截断描述，不含 schema）；传 `tool` 按需展开单个工具的完整 schema，传 `server` 过滤，传 `verbose` 全量内联；
+  - **`mcp_call`** — 按 `{ tool, arguments }` 把调用分发到仍然注册着的定义上，运行上下文原样透传。
+
+工具本身仍注册在 `ctx.tools` 里，所以 TUI 渲染、`tools.restrict()` 掩蔽照常工作——变的只是 prompt 载荷。折叠后恒定的工具列表也比上游"每次重同步就换代"的模式更利于 KV 前缀缓存。
+
+一个管线细节：按子工具名（`mcp__server__tool`）匹配的 pre-execute / guard / post-execute 阶段不会在折叠调用上触发——注册表只会看到外层的 `mcp_call`。要管控 MCP 使用（审批、策略），请 guard **`mcp_call` 本身**。
+
+图片结果保持原生行为：`mcp_call` 把 `output.render` 委托给被分发的子工具，并以同一个执行对象转发子工具的 `finalizeContent`——带图 MCP 结果仍会投影为持久附件引用，而不是把 base64 内联进上下文。
+
+**故障放行（fail-open）：** 若两个 meta-tool 未成功注册（重名冲突、启动中断），本插件不动装配结果——退回官方全量直通，绝不会让 MCP 工具变得不可发现。
+
+**Code Mode：** 在 `mode: 'code'` 下线上本来就折叠为 `run_code`，本插件天然 no-op。
+
+**加载位置：** 经宿主组合加载（即下方 `cordis.patch.yml` 的 `insert` 行）时全局生效——所有 agent 的装配都会被折叠；若经某个 agent 的 scoped context 加载，则只对该 agent 生效。
+
+## 安装
+
+保留（或新增）你的 `@deepseek-ai/dsh-mcp-client` 配置行，然后把本插件加在同处：
+
+```yaml
+- insert:
+    - id: dsh-mcp-adapter
+      name: '@aiwayds/dsh-mcp-adapter'
+      config: {}
+```
+
+```
+dsh plugin --profile <name> add @aiwayds/dsh-mcp-adapter
+```
+
+## 配置
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `prefix` | `"mcp__"` | 要折叠的工具名前缀 |
+| `keep` | `[]` | 保持原生进 prompt 的名字模式（`*` 通配）——对应 pi-mcp-adapter 的 direct 模式，适合高频、值得占一等座 schema 的工具 |
+| `servers` | `[]` | server 白名单：非空时只有这些 server 的工具会被折叠 / 进目录 / 可分发（三处共用同一份名单） |
+| `descriptionLimit` | `200` | `mcp_list` 目录里每条工具描述的最大字符数 |
+
+```yaml
+config:
+  keep:
+    - mcp__fs__read_file
+    - mcp__github__*
+  servers:
+    - fs
+    - github
+```
+
+**信任边界：** 默认所有匹配 `prefix` 的工具都会被折叠——前缀只是命名约定而非安全边界，第三方插件恰好用 `mcp__*` 注册的工具同样会折叠。若只信任官方 client 的 server，请在 `servers` 里显式列出；其余保持原生（仍可直调，只是不走 meta-tool）。
+
+## 备注
+
+- `mcp_call` 只接受匹配 `prefix` 的工具（配置了 `servers` 时还须在白名单内）——它不可能被用来绕过其它工具自己的 pre-execute 管线。
+- 已知边界（waterfall 次序）：若某 listener 注册**早于**本插件、并在自己的 `next()` 之后补插 `mcp__*` schema，该 schema 会逃过折叠——本插件折叠的是它运行时装配结果里的内容。当前上游不存在这样的 listener。
+- 目录里的 server 名是启发式提取：前缀后第一段 `__` 分隔段（server 名规范为 `[A-Za-z0-9_-]{1,32}`，不会含字面 `__`，故不会错分组）。
+- 与 [ben7am1n/dsh-mcp-proxy](https://github.com/ben7am1n/dsh-mcp-proxy) 可共存（它是 connection-side 代理、自带连接管理，工具名互不冲突）。该项目同样致谢 pi-mcp-adapter；本仓库是独立的 prompt-side 实现：复用官方 client 而不是重造连接层。
+- 权衡（与 pi-mcp-adapter 相同）：首次调用多一次发现往返；模型展开过的 schema 会占据后续上下文。
+
+## 开发
+
+```
+npm install && npm run check && npm test
+```
+
+`@deepseek-ai/*` 类型由 `scripts/link-dsh-closure.mjs` 从全局 dsh 闭包软链解析（`precheck` 自动执行）——它们被刻意排除在 `package.json` 之外，以保证类型图中只存在一份 cordis 实例。完整设计依据与上游参考见 `DESIGN.md`。

package/cordis.patch.yml

@@ -0,0 +1,33 @@
+# dsh-mcp-adapter bundle patch: mounts the prompt-side MCP folding shim
+# under the stable id `dsh-mcp-adapter`.
+#
+# It keeps the official @deepseek-ai/dsh-mcp-client plugin instances as the
+# connection layer (transports, reconnect, list_changed re-sync all stay
+# upstream), but folds every `mcp__<server>__<tool>` schema out of each
+# assembled prompt and exposes two constant meta-tools (`mcp_list` /
+# `mcp_call`) instead — the model expands schemas on demand, so standing
+# prompt cost is O(1) in the number of MCP servers and tools.
+#
+# Load order does not matter: folding happens per prompt assembly, and the
+# adapter degrades to official passthrough when its own meta-tools are not
+# registered. List it next to your dsh-mcp-client lines for clarity. Under
+# Code Mode the wire already collapses to `run_code`, so this plugin is a
+# no-op there.
+#
+# Config (all optional):
+#   prefix:             tool-name prefix to fold (default "mcp__")
+#   keep:               name patterns ("*" wildcard) kept native, e.g.
+#                       ["mcp__fs__read_file", "mcp__github__*"]
+#   servers:            server-name whitelist; when non-empty only these
+#                       servers' tools are folded/cataloged/dispatchable
+#                       (default [] = every prefix-matching tool; the
+#                       prefix alone is a naming convention, not a trust
+#                       boundary — list servers to trust only the official
+#                       client's registrations)
+#   descriptionLimit:   max chars per tool description in the mcp_list
+#                       catalog (default 200)
+
+- insert:
+    - id: dsh-mcp-adapter
+      name: '@aiwayds/dsh-mcp-adapter'
+      config: {}

package/lib/index.d.ts

@@ -0,0 +1,342 @@
+/**
+ * dsh-mcp-adapter — prompt-side MCP folding shim for dsh.
+ *
+ * The official `@deepseek-ai/dsh-mcp-client` registers every discovered MCP
+ * tool natively (`mcp__<server>__<tool>`), so every assembled prompt carries
+ * the full JSON Schema of every MCP tool. This plugin keeps that client as
+ * the connection layer (transport, reconnect, `list_changed` re-sync — all
+ * upstream) and intervenes only at prompt assembly:
+ *
+ * - every prefix-matching tool schema is folded out of the assembled prompt
+ *   (`system-prompt/assemble` waterfall), so standing prompt cost is O(1) in
+ *   the number of servers and tools, and the tool list stays KV-prefix
+ *   stable across server re-syncs. The prefix is a naming convention, not a
+ *   trust boundary — third-party tools that happen to use it fold too; set
+ *   `servers` to restrict folding (and cataloging/dispatch) to named servers;
+ * - two constant meta-tools replace them:
+ *   - `mcp_list` — compact catalog grouped by server; `tool` expands one
+ *     full schema on demand, `server` filters, `verbose` inlines everything;
+ *   - `mcp_call` — dispatches `{ tool, arguments }` to the still-registered
+ *     definition, forwarding the run context.
+ *
+ * Tools stay registered in `ctx.tools`, so TUI rendering and
+ * `tools.restrict()` masking keep working — only the prompt payload changes.
+ * Pipeline nuance: pre-execute/guard/post-execute stages that match by the
+ * child tool's name never fire for folded calls (the registry only sees the
+ * outer `mcp_call`) — gate MCP usage by guarding `mcp_call` itself.
+ *
+ * Child-owned projections are preserved: `mcp_call` delegates its
+ * `output.render` to the dispatched child and forwards the child's
+ * `finalizeContent` with the exact same run-execution object, so
+ * image-bearing MCP results still project to durable attachment references
+ * instead of inlining base64 into the context.
+ *
+ * Fail-open: unless BOTH meta-tools resolve (in the assembling scope) to
+ * exactly this plugin's definitions, assemblies pass through untouched — a
+ * broken adapter must never make MCP tools undiscoverable. Under Code Mode
+ * the wire already collapses to `run_code`, so this plugin is a natural no-op.
+ *
+ * All decision logic is exported as pure functions; the only Cordis calls
+ * live in {@link apply}.
+ *
+ * @module @aiwayds/dsh-mcp-adapter
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm';
+import type { ToolDefinition, ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools';
+import type { ScopeKey } from '@deepseek-ai/dsh-scope';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "mcp-adapter";
+/** Services required by this plugin. */
+export declare const inject: string[];
+/** Registered name of the catalog meta-tool. */
+export declare const MCP_LIST_TOOL_NAME = "mcp_list";
+/** Registered name of the dispatch meta-tool. */
+export declare const MCP_CALL_TOOL_NAME = "mcp_call";
+/** Resolved adapter configuration. */
+export interface AdapterConfig {
+    /** Tool-name prefix to fold out of assembled prompts. */
+    prefix: string;
+    /** Name patterns ("*" wildcard) kept native in the prompt. */
+    keep: string[];
+    /**
+     * Server-name whitelist. Empty (default) folds every prefix-matching tool —
+     * the prefix is then a naming convention, not a trust boundary. Non-empty
+     * folds/catalogs/dispatches ONLY tools of the listed servers; fold, catalog
+     * and dispatch all consult the same list.
+     */
+    servers: string[];
+    /** Max chars per tool description in the mcp_list catalog. */
+    descriptionLimit: number;
+}
+export declare const Config: z<AdapterConfig>;
+/**
+ * Whether a tool name matches any keep pattern ("*" wildcard, anchored;
+ * a pattern without wildcards is an exact name).
+ * @param name - the registered tool name.
+ * @param patterns - keep patterns from config.
+ * @returns whether the tool stays native in the prompt.
+ */
+export declare function matchesKeep(name: string, patterns: readonly string[]): boolean;
+/**
+ * Whether the server segment of one prefix-matching tool name passes the
+ * optional servers whitelist. An empty list admits every server (the prefix
+ * is a naming convention, not a trust boundary); a non-empty list admits
+ * only the named servers.
+ * @param name - the registered tool name.
+ * @param prefix - the configured MCP prefix.
+ * @param servers - server-name whitelist from config.
+ * @returns whether the tool's server is admitted.
+ */
+export declare function isAllowedServer(name: string, prefix: string, servers: readonly string[]): boolean;
+/**
+ * Whether one tool's schema should be folded out of the prompt: it must
+ * carry the configured prefix, belong to a whitelisted server, not match the
+ * keep list — and it must never be one of this plugin's own meta-tools,
+ * whatever the prefix is configured to (folding them would make every folded
+ * MCP tool undiscoverable).
+ * @param name - the registered tool name.
+ * @param prefix - tool-name prefix to fold.
+ * @param keep - keep patterns from config.
+ * @param servers - server-name whitelist from config (default: no filtering).
+ * @returns whether the schema leaves the prompt (the tool stays callable).
+ */
+export declare function shouldFold(name: string, prefix: string, keep: readonly string[], servers?: readonly string[]): boolean;
+/** Folding knobs resolved from config. */
+export interface FoldOptions {
+    /** Tool-name prefix to fold. */
+    prefix: string;
+    /** Name patterns kept native. */
+    keep: readonly string[];
+    /** Server-name whitelist; empty or omitted admits every server. */
+    servers?: readonly string[];
+}
+/**
+ * Structural subset of `PromptAssembly` the folding operates on, so tests
+ * can drive it without importing prompt-assembly types.
+ */
+export interface AssemblyWithTools {
+    sections: unknown[];
+    contexts: unknown[];
+    tools: ToolSchema[];
+    variables: Record<string, string | undefined>;
+}
+/**
+ * Rewrite one assembled prompt: drop the schemas of foldable tools, keep
+ * everything else (sections, contexts, variables, non-MCP tools, meta-tools)
+ * untouched.
+ *
+ * Fail-open contract: with `metaToolsLive` false the assembly object is
+ * returned AS-IS (same reference) — folding is only safe while the model can
+ * still discover MCP tools through the meta-tools.
+ *
+ * @param assembly - the post-waterfall assembly.
+ * @param options - folding knobs.
+ * @param metaToolsLive - whether both meta-tools currently resolve to this
+ *   plugin's own definitions in the assembling scope.
+ * @returns the folded assembly, or the input unchanged when nothing folds.
+ */
+export declare function foldPromptAssembly<T extends AssemblyWithTools>(assembly: T, options: FoldOptions, metaToolsLive: boolean): T;
+/** Options for the catalog builder. */
+export interface McpListOptions {
+    /** Tool-name prefix identifying MCP tools. */
+    prefix: string;
+    /** Max chars per tool description in the catalog. */
+    descriptionLimit: number;
+    /** Server-name whitelist; empty or omitted admits every server. */
+    servers?: readonly string[];
+}
+/** Normalized `mcp_list` arguments. */
+export interface McpListArgs {
+    /** Expand this tool's full schema (highest priority when set). */
+    tool?: string;
+    /** Filter the catalog to one server. */
+    server?: string;
+    /** Inline every tool's schema in the catalog. */
+    verbose?: boolean;
+}
+/** One catalog entry; `parameters` is present only when expanded. */
+export interface CatalogToolEntry {
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+}
+/** One server group in the compact catalog. */
+export interface CatalogServerEntry {
+    server: string;
+    tools: CatalogToolEntry[];
+}
+/** `mcp_list`'s canonical result: catalog, single expansion, or error. */
+export type McpListResult = {
+    servers: CatalogServerEntry[];
+} | {
+    tool: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+} | {
+    error: string;
+};
+/**
+ * Narrow arbitrary model arguments to the `mcp_list` shape, dropping
+ * unknown or mistyped keys instead of throwing (the model misbehaves).
+ * @param args - raw model arguments.
+ * @returns the normalized catalog query.
+ */
+export declare function normalizeMcpListArgs(args: unknown): McpListArgs;
+/**
+ * Derive the server segment of a registered MCP tool name: the first
+ * `__`-delimited segment after the prefix. Heuristic, not a parse: server
+ * names are constrained to `[A-Za-z0-9_-]{1,32}` by the official client, so
+ * a literal `__` inside a server name (impossible there) would mis-group.
+ * @param name - the registered tool name.
+ * @param prefix - the configured MCP prefix.
+ * @returns the server segment ('' for degenerate names).
+ */
+export declare function serverOfToolName(name: string, prefix: string): string;
+/**
+ * Truncate one description to the catalog limit, marking the cut with an
+ * ellipsis character (so one char of headroom is reserved). A cut that would
+ * land on the LOW half of a surrogate pair backs off one code unit so no
+ * orphaned high surrogate is emitted.
+ * @param text - the full tool description.
+ * @param limit - max chars in the catalog.
+ * @returns the truncated description.
+ */
+export declare function truncateDescription(text: string, limit: number): string;
+/**
+ * Build the `mcp_list` result over the currently visible schemas.
+ *
+ * Priority: `tool` (full single-tool expansion) > catalog (optionally
+ * filtered by `server`, optionally `verbose`). Unknown or non-MCP `tool`,
+ * and any query that selects nothing, return a structured error — never a
+ * throw — so the model can correct itself.
+ *
+ * @param args - the normalized catalog query.
+ * @param schemas - schemas visible to the calling agent.
+ * @param options - catalog knobs.
+ * @returns the canonical result value.
+ */
+export declare function buildMcpListResult(args: McpListArgs, schemas: readonly ToolSchema[], options: McpListOptions): McpListResult;
+/** Structural slice of a resolvable tool: what dispatch actually consumes. */
+export interface DispatchableTool<E> {
+    /** Cooperative timeout budget declared by the tool, if any. */
+    readonly timeoutMs?: number;
+    /** The tool body dispatch invokes. */
+    execute(args: unknown, exec: E): Promise<unknown>;
+}
+/**
+ * Dispatch one `mcp_call` to the resolved child tool.
+ *
+ * Validation: `tool` must be a non-empty string matching the configured
+ * prefix, must not name a meta-tool, must belong to a whitelisted server
+ * (when `servers` is non-empty), and must resolve through `resolve`
+ * (scope-aware — a restricted-away tool does not resolve, so whitelists are
+ * respected naturally). Non-MCP tools are REFUSED outright: dispatching them
+ * here would bypass their own pre-execute pipeline (guards, approvals).
+ *
+ * Execution: `definition.execute(args.arguments ?? {}, exec)` with the
+ * meta-tool's own run context passed through verbatim — the official MCP
+ * executor consumes `exec.signal` (per-request abort) and `exec.agent`
+ * (model-route resolution for image admission), both carried by that same
+ * context object.
+ *
+ * Timeout: no timer is raced for the official mcp-client tools — their
+ * executor already self-times every MCP request (`tools/call` is sent with
+ * `timeout: toolCallTimeoutMs`, verified in the upstream bridge source), and
+ * they never declare `timeoutMs`. Only a definition that DECLARED
+ * `timeoutMs` gets a raced deadline, because calling `definition.execute()`
+ * directly bypasses the registry's timeout policy wrapper.
+ *
+ * Errors never throw out of dispatch: a child rejection (or raced timeout)
+ * is wrapped into a structured `{ error }` the model can correct and retry.
+ *
+ * @param args - raw model arguments (`{ tool, arguments? }`, validated here).
+ * @param prefix - the configured MCP prefix.
+ * @param resolve - scope-aware tool resolver (production: `ctx.tools.get`).
+ * @param exec - the meta-tool's run context, forwarded to the child.
+ * @param servers - server-name whitelist (default: no filtering).
+ * @returns the child's resolved value verbatim, or a structured error.
+ */
+export declare function dispatchMcpCall<E>(args: unknown, prefix: string, resolve: (name: string) => DispatchableTool<E> | undefined, exec: E, servers?: readonly string[]): Promise<unknown>;
+/**
+ * Render one mcp_call outcome by delegating to the dispatched child's own
+ * `output.render`, so model-facing text is exactly what a native call of the
+ * child would produce. Falls back to the generic JSON rendering whenever the
+ * value is this plugin's structured-error wrap, the child cannot be resolved
+ * from the arguments, or the child's render throws (the value's shape is the
+ * child's contract, not this tool's).
+ * @param metaArgs - the frozen mcp_call arguments (`{ tool, arguments? }`).
+ * @param value - the dispatched child's resolved value (or an error wrap).
+ * @param resolveChild - definition resolver (unscoped view is fine here —
+ *   render is a pure display projection).
+ * @returns the model-facing content blocks.
+ */
+export declare function renderDispatched(metaArgs: unknown, value: unknown, resolveChild: (name: string) => ToolDefinition | undefined): ContentBlock[];
+/**
+ * Forward one successful mcp_call outcome to the dispatched child's own
+ * `finalizeContent`, restoring child-owned rich projections (image
+ * attachments).
+ *
+ * Why this is needed: the official mcp-client stages image projections in a
+ * `WeakMap<ToolExecution, PreparedProjection>` filled by its executor
+ * (`packages/mcp/mcp-client/src/tools.ts:255`, `:354-358`) and hands them
+ * back from `finalizeContent` (`:262-270`) — but the registry invokes
+ * `finalizeContent` only for the OUTER executed definition
+ * (`packages/core/tools/src/index.ts:1649-1654`), which here is `mcp_call`.
+ * Without forwarding, the child's projection never runs and image results
+ * degrade to their base64-in-text fallback.
+ *
+ * Mechanics: the child is re-resolved from `metaArgs.tool`; a child-view
+ * success result is synthesized with `content` computed by the child's own
+ * `output.render` (the same fallback the registry would have produced for a
+ * native call, so the child's value/fallback equality guards still pass);
+ * and the child's `finalizeContent` is invoked with the EXACT `exec` object
+ * dispatch forwarded to `child.execute` — same object identity, so the
+ * child's WeakMap lookup hits.
+ *
+ * Failure paths never project: an `isError` result and this plugin's
+ * structured-error wraps return `undefined` immediately; a child without
+ * `finalizeContent`, an unresolvable child, or a throwing child callback
+ * (the contract demands total callbacks) also degrade to `undefined`, which
+ * preserves the registry-computed content.
+ *
+ * @param metaArgs - the frozen mcp_call arguments (`{ tool, arguments? }`).
+ * @param result - the registry-normalized mcp_call outcome.
+ * @param exec - the mcp_call execution object that was forwarded verbatim
+ *   to the child body — the child's projection WeakMap key.
+ * @param resolveChild - scope-aware definition resolver.
+ * @returns replacement content from the child's finalizer, or `undefined`
+ *   to preserve the registry-computed content.
+ */
+export declare function delegateFinalizeContent(metaArgs: unknown, result: Readonly<ToolExecutionResult>, exec: Readonly<ToolExecution>, resolveChild: (name: string) => ToolDefinition | undefined): ContentBlock[] | undefined;
+/**
+ * Build the `mcp_list` meta-tool definition.
+ * @param options - catalog knobs (prefix, description limit).
+ * @param listSchemas - visible-schemas source (production: `ctx.tools.schemas`,
+ *   called with the calling agent so restrictions are respected).
+ * @returns the complete tool definition.
+ */
+export declare function createMcpListTool(options: McpListOptions, listSchemas: (scope?: ScopeKey) => readonly ToolSchema[]): ToolDefinition;
+/**
+ * Build the `mcp_call` meta-tool definition.
+ * @param prefix - the configured MCP prefix (dispatch boundary).
+ * @param resolve - scope-aware definition resolver (production:
+ *   `ctx.tools.get`, called with the calling agent).
+ * @param servers - server-name whitelist (default: no filtering).
+ * @returns the complete tool definition.
+ */
+export declare function createMcpCallTool(prefix: string, resolve: (name: string, scope?: ScopeKey) => ToolDefinition | undefined, servers?: readonly string[]): ToolDefinition;
+/**
+ * Register the two meta-tools and install the assembly folding listener.
+ *
+ * Failure safety: if either meta-tool registration fails (name collision),
+ * both registrations are rolled back, a warning is logged, and NO listener
+ * is installed — the official full-schema passthrough stays intact.
+ *
+ * @param ctx - plugin context carrying the tool registry.
+ * @param config - resolved adapter configuration.
+ */
+export declare function apply(ctx: Context, config: AdapterConfig): void;