@geohar/pi-mcp-combiner 0.13.4 → 0.14.1

package/README.md

@@ -1,161 +1,261 @@
 # @geohar/pi-mcp-combiner
 
-A [Pi](https://pi.dev) extension that makes the **`mcp-combiner`** MCP aggregator
-available to Pi: it starts the combiner (supervised by
-[`sharedserver`](https://github.com/georgeharker/sharedserver)) and appends the
-combiner's tool-discovery directive to the system prompt.
+A [Pi](https://pi.dev) extension that gives Pi the **`mcp-combiner`** MCP aggregator —
+end to end. It starts the combiner (supervised by
+[`sharedserver`](https://github.com/georgeharker/sharedserver)), **speaks MCP to it
+directly** (a built-in client half — no second package required), and surfaces every
+server, tool, resource, and prompt as first-class Pi UX.
+
+Use it **standalone** (recommended) or **alongside
+[`pi-mcp-adapter`](https://pi.dev/packages/pi-mcp-adapter)** — see
+[Two ways to run it](#two-ways-to-run-it).
 
 It is the Pi counterpart of the
 [Claude Code](https://github.com/georgeharker/mcp-companion/tree/main/plugins/claude)
-and
-[OpenCode](https://github.com/georgeharker/mcp-companion/tree/main/plugins/opencode)
+and [OpenCode](https://github.com/georgeharker/mcp-companion/tree/main/plugins/opencode)
 plugins, and shares the same combiner and the same `sharedserver` instance — so Pi,
 Claude Code, OpenCode, and Neovim can all talk to **one** refcounted combiner process.
 
 ## How it fits together
 
-Pi has no MCP of its own. Two pieces give it the combiner:
-
-1. **[`pi-mcp-adapter`](https://pi.dev/packages/pi-mcp-adapter)** — the Pi package that
-   actually speaks MCP. It reads its own `mcp.json` and connects to the combiner over
-   HTTP. **This extension does not replace it — you install both.**
-2. **This extension** — the process + instructions half, mirroring the sibling plugins:
-   - **Run the combiner** — on `session_start` it drives
-     ```
-     sharedserver use <name> --pid <pi-pid> --grace-period <g> \
-         -- <combiner> --mcp --config <servers.json> --port <port>
-     ```
-     `sharedserver` refcounts by PID with a grace period, so the combiner is shared
-     across clients and outlives any single one. It releases the refcount on
-     `session_shutdown` — but only when `reason === "quit"`, since reload/resume/fork
-     keep the same Pi process and a fresh `session_start` re-attaches.
-   - **Inject instructions** — on `before_agent_start` it appends the combiner's
-     `<server>_`-prefix / "discover before assuming" directive to the system prompt. The
-     combiner also serves the same text as its MCP `instructions`, which `pi-mcp-adapter`
-     surfaces on connect, so this is a belt to those braces.
-
-`sharedserver` itself is fetched automatically if it is not already installed (a pinned
-release via the cargo-dist installer — no Rust toolchain needed), using the exact same
-resolver as the other two plugins.
+Three halves, all in this one package:
 
-## Requirements
+1. **Process** — on `session_start` it drives
 
-- **`pi-mcp-adapter`** installed in Pi: `pi install npm:pi-mcp-adapter`.
-- **`mcp-combiner`** available as a command (`uv tool install mcp-combiner`), or just
-  **`uv`** on PATH — a pinned release is fetched from PyPI on demand. Requires combiner
-  ≥ 0.8.0 (the `--mcp` serve flag; version-gated automatically).
-- A combiner **`servers.json`** (see auto-probe locations below).
+   ```sh
+   sharedserver use <name> --pid <pi-pid> --grace-period <g> \
+       -- <combiner> --mcp --config <servers.json> --port <port>
+   ```
 
-## Install
+   `sharedserver` refcounts by PID with a grace period, so the combiner is shared
+   across clients and outlives any single one. The refcount releases on
+   `session_shutdown` only when `reason === "quit"` — reload/resume/fork keep the same
+   Pi process and a fresh `session_start` re-attaches.
 
-### 1. Point `pi-mcp-adapter` at the combiner
+2. **Client** — a thin, combiner-specific MCP client (streamable HTTP, per-Pi-session
+   identity, an elicitation bridge) that registers the agent-facing surface: the
+   `mcp()` proxy tool, a scripting tool, `read_*` resource tools, prompt slash
+   commands, a status footer, and an interactive panel. Everything the hundreds of
+   tool definitions would cost in context is replaced by two or three tool
+   definitions and on-demand discovery.
+3. **Instructions** — on `before_agent_start` it appends the combiner's
+   `<server>_`-prefix / "discover before assuming" directive to the system prompt.
 
-Drop the combiner entry into one of `pi-mcp-adapter`'s `mcp.json` locations — e.g.
-project-local `.pi/mcp.json`, or global `~/.config/mcp/mcp.json`:
+`sharedserver` itself is fetched automatically if not installed (pinned release via
+the cargo-dist installer), and the combiner is resolved from PATH / a checkout /
+a pinned PyPI release — same resolvers as the sibling plugins.
 
-```json
-{
-  "mcpServers": {
-    "mcp-combiner": {
-      "url": "http://127.0.0.1:9741/mcp",
-      "auth": "bearer",
-      "bearerTokenEnv": "MCP_COMBINER_AUTH_TOKEN"
-    }
-  }
-}
+## Two ways to run it
+
+### A. Standalone (recommended)
+
+Install only this extension. Nothing else needed — the client half connects to the
+combiner and registers everything:
+
+```sh
+pi install /path/to/mcp-companion/plugins/pi     # local checkout
+# or the published package under settings.json "packages"
 ```
 
-Or let the extension write it for you — **`/mcp-combiner install-config`** merges
-exactly this entry into `~/.config/mcp/mcp.json` (or a path you pass), preserving
-any other servers and any existing `url` you set. (It only writes when you ask —
-the extension never edits the adapter's config on its own.)
+On startup you get: the `mcp` tool (search → describe → call), `mcpScript`,
+`read_<resource>` tools, `/<server>__<prompt>` slash commands, a footer line
+(`14 servers enabled (13 ready) · 671 tools`), and `/mcp-combiner panel`.
+
+### B. Alongside pi-mcp-adapter
 
-`"auth": "bearer"` with `"bearerTokenEnv"` is the correct single pairing — it does
-two jobs at once:
+Already running pi-mcp-adapter (for other servers, or while evaluating)? The client
+half is gated by a **tri-state**:
 
-- **Sends the token.** `pi-mcp-adapter` only attaches `Authorization: Bearer …`
-  when `auth === "bearer"` (`server-manager.ts`); `bearerTokenEnv` names the env
-  var it reads at connect. So if you lock the combiner down with an inbound bearer
-  (`MCP_COMBINER_AUTH_TOKEN`, see the combiner README), the header is presented —
-  nothing is written to disk. **Note:** `bearerTokenEnv` alone, or with `auth:
-  false`, does **not** send the header — the adapter gates it on `auth === "bearer"`.
-- **Suppresses OAuth.** `auth: "bearer"` also makes the adapter's `supportsOAuth()`
-  false, so a wrong/missing-token 401 surfaces as an honest error instead of the
-  spurious `Failed to start OAuth … DCR rejected (HTTP 404)` probe.
+| Setting                         | Behaviour                                                                                                                                                                                                |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"adapter": "auto"` _(default)_ | client **off** when pi-mcp-adapter is detected installed, **on** otherwise — existing adapter setups upgrade with zero behaviour change                                                                  |
+| `"adapter": true`               | client on, adapter stays for other servers. Rename ours (`"toolName": "combiner"`) so both tools coexist, and remove the combiner entry from the shared `mcp.json` so the adapter doesn't double-connect |
+| `"adapter": false`              | legacy mode — process + instructions only; the adapter owns all MCP                                                                                                                                      |
 
-Harmless when the combiner is **open**: the env var is unset, so no header is sent,
-the endpoint returns 200, and OAuth still never fires. So this one entry is correct
-whether or not inbound auth is enabled.
+Env override: `PI_MCP_COMBINER_ADAPTER=off|on|auto`. `/mcp-combiner status` reports
+which mode is active and why.
 
-(See [`mcp.json.example`](./mcp.json.example).) To give this Pi instance its own chat
-identity toward the combiner — parking its isolated upstream sessions separately — add a
-path token: `"url": "http://127.0.0.1:9741/mcp/pi-<yourname>"`. The combiner gives URL
-tokens first priority.
+The legacy **`/mcp-combiner install-config`** verb (writes the combiner entry into the
+shared `mcp.json` for the adapter to read) still exists for mode B.
 
-If you edit `mcp.json` while Pi is running, run `/reload` (or `mcp({ connect:
-"mcp-combiner" })`) so the adapter re-reads it.
+## Requirements
+
+- **`mcp-combiner`** available as a command (`uv tool install mcp-combiner`), or just
+  **`uv`** on PATH — a pinned release is fetched from PyPI on demand. Requires
+  combiner ≥ 0.8.0 (version-gated automatically).
+- A combiner **`servers.json`** (auto-probe locations below).
+- pi-mcp-adapter **not** required.
 
-### 2. Install this extension
+## Configuration — three layers
 
-Any of Pi's extension-loading mechanisms — all support a **local directory**:
+### 1. Pi settings file — `$PI_CODING_AGENT_DIR/extensions/mcp-combiner.json`
 
-```sh
-# a) drop-in package dir (uses "main": dist/index.js — run `npm run build` first)
-npm --prefix plugins/pi run build
-ln -s "$PWD/plugins/pi" ~/.pi/agent/extensions/mcp-combiner
+Pi-side knobs (see [`settings.example.json`](./settings.example.json)):
+
+| Key               | Default  | Effect                                                                                                    |
+| ----------------- | -------- | --------------------------------------------------------------------------------------------------------- |
+| `toolName`        | `"mcp"`  | Name of the proxy tool. Rename (e.g. `"combiner"`) to coexist with pi-mcp-adapter's own `mcp`.            |
+| `adapter`         | `"auto"` | Client-half gate — see above.                                                                             |
+| `lazy`            | `"lazy"` | `"eager"` connects at session start; `"lazy"` on first use. Prompts/resources/directTools imply eager.    |
+| `exposeResources` | `true`   | Register `read_<resource>` tools.                                                                         |
+| `prompts`         | `true`   | Register prompt slash commands.                                                                           |
+| `scriptMode`      | `true`   | Register the `<toolName>Script` batching tool.                                                            |
+| `uiAutoOpen`      | `true`   | Auto-open interactive widget URLs in the browser (Stage 2 holds + resource reads).                        |
+| `mcpFooterStatus` | `"full"` | Footer text: `"full"` = `N servers enabled (M ready) · T tools`, `"compact"` = `MCP M/N`, `"off"` = none. |
+| `mcpFooterKey`    | `"mcp"`  | The `ctx.ui.setStatus` key the footer publishes under (the slot oh-my-posh-style footers aggregate).      |
+| `url`             | —        | Explicit combiner URL. Env wins.                                                                          |
+| `notify`          | `true`   | Surface lifecycle messages via the Pi UI.                                                                 |
+
+### 2. Shared MCP config ladder — read-only
+
+The extension **reads** the standard MCP files (same ladder and precedence as
+pi-mcp-adapter, later wins): `~/.config/mcp/mcp.json` → `~/.agents/mcp.json` →
+`~/.agents/mcp/mcp.json` → `<agent dir>/mcp.json` → `.mcp.json` → `.pi/mcp.json`
+(project). It **never writes them**.
 
-# b) one-off, build-free live dev — Pi loads the TS source directly
-pi -e ./plugins/pi/src/index.ts
+The recognized `mcp-combiner` entry carries connection + per-project exposure:
 
-# c) settings.json — list a local path under "extensions"
-#    { "extensions": ["/abs/path/to/mcp-companion/plugins/pi/src/index.ts"] }
+```jsonc
+{
+  "mcpServers": {
+    "mcp-combiner": {
+      "url": "http://127.0.0.1:9741/mcp",
+      "auth": "bearer",
+      "bearerTokenEnv": "MCP_COMBINER_AUTH_TOKEN",
+      "combiner": {
+        // extension-specific, ignored by other readers
+        "servers": { "allow": ["github", "svg-mcp"] }, // or "deny": [...]
+        "exposeResources": true,
+        "prompts": true,
+        "directTools": ["combiner__status", "github_search_*"], // or "search"
+      },
+    },
+  },
+}
+```
 
-# d) published package — list under "packages" in settings.json
-#    { "packages": ["@geohar/pi-mcp-combiner@latest"] }
+- **`servers.allow/deny`** — per-project exposure, enforced _at the combiner_ for this
+  chat's token (sees through scripting too) and mirrored client-side.
+- **`directTools`** — promote named tools (globs) to first-class Pi tools at session
+  start, or `"search"` to promote tools the first time `mcp({search})` matches them.
+  A >50-entry allowlist warns; `true` is deliberately not offered (context cost).
+- Project layers are read against the **session cwd** — worktree subagents and
+  project switches get their own `.pi/mcp.json`. Commit the `combiner` block if you
+  want worktree agents to honour it.
+- URL precedence: `MCP_COMPANION_COMBINER_URL` (host-owned) → `PI_MCP_COMBINER_URL` →
+  settings `url` → ladder entry `url` → `host:port/mcp`.
+
+### 3. Environment — `PI_MCP_COMBINER_*`
+
+| Variable                                        | Default           | Effect                                                             |
+| ----------------------------------------------- | ----------------- | ------------------------------------------------------------------ |
+| `PI_MCP_COMBINER_ADAPTER`                       | _(settings)_      | `off` / `on` / `auto` — client-half gate.                          |
+| `PI_MCP_COMBINER_TOOL_NAME`                     | _(settings)_      | Proxy tool name override.                                          |
+| `PI_MCP_COMBINER_URL`                           | —                 | Explicit combiner URL.                                             |
+| `PI_MCP_COMBINER_PORT`                          | `9741`            | HTTP port the combiner serves on.                                  |
+| `PI_MCP_COMBINER_HOST`                          | `127.0.0.1`       | HTTP host the combiner binds.                                      |
+| `PI_MCP_COMBINER_CONFIG`                        | _(auto-probed)_   | Path to the combiner's `servers.json`.                             |
+| `PI_MCP_COMBINER_COMMAND` / `_ARGS`             | _(auto-resolved)_ | Override the combiner invocation.                                  |
+| `PI_MCP_COMBINER_CHECKOUT`                      | —                 | Checkout for `uv run --project <checkout> python -m mcp_combiner`. |
+| `PI_MCP_COMBINER_NAME`                          | `mcp-combiner`    | `sharedserver` instance name.                                      |
+| `PI_MCP_COMBINER_GRACE`                         | `30m`             | `sharedserver` grace period.                                       |
+| `PI_MCP_COMBINER_LOG` / `_PYLOG` / `_LOG_LEVEL` | _(state dir)_     | Combiner logging; `"none"` disables.                               |
+| `PI_MCP_COMBINER_MANAGE`                        | `true`            | `false` → don't launch (combiner runs elsewhere).                  |
+| `PI_MCP_COMBINER_INSTRUCTIONS`                  | `true`            | `false` → skip the system-prompt directive.                        |
+| `PI_MCP_COMBINER_NOTIFY`                        | `true`            | `false` → don't surface messages via the Pi UI.                    |
+| `SHAREDSERVER_BIN` / `SHAREDSERVER_LOCKDIR`     | _(auto)_          | `sharedserver` binary / lock dir.                                  |
+
+`servers.json` auto-probe: `$PI_MCP_COMBINER_CONFIG` →
+`~/.cache/secrets/<user>.mcpservers.json` → `~/.config/mcp-combiner/servers.json` →
+`~/.config/mcp/servers.json`.
+
+## The UX
+
+**The proxy tool** (`mcp`, or your `toolName`) — one tool instead of hundreds:
+
+```ts
+mcp({search: "github search code"})     → ranked hits + describe-next hint
+mcp({describe: "github_search_code"})   → full schema (TS-shaped) + description
+mcp({tool: "github_search_code", args: {...}})  → the call
+mcp({})                                 → status
 ```
 
-## Configuration
-
-Everything is via the `PI_MCP_COMBINER_*` environment namespace, which mirrors the Claude
-plugin's `CLAUDE_MCP_COMBINER_*` and the OpenCode plugin's `OPENCODE_MCP_COMBINER_*` — so
-running several clients means one namespace per client.
-
-| Variable | Default | Effect |
-|----------|---------|--------|
-| `PI_MCP_COMBINER_PORT` | `9741` | HTTP port the combiner serves on. |
-| `PI_MCP_COMBINER_HOST` | `127.0.0.1` | HTTP host the combiner binds. |
-| `PI_MCP_COMBINER_CONFIG` | *(auto-probed)* | Path to the combiner's `servers.json`. |
-| `PI_MCP_COMBINER_COMMAND` / `_ARGS` | *(auto-resolved)* | Override the combiner invocation. |
-| `PI_MCP_COMBINER_CHECKOUT` | — | Checkout for `uv run --project <checkout> python -m mcp_combiner`. |
-| `PI_MCP_COMBINER_NAME` | `mcp-combiner` | `sharedserver` instance name. |
-| `PI_MCP_COMBINER_GRACE` | `30m` | `sharedserver` grace period. |
-| `PI_MCP_COMBINER_LOG` | `~/.local/state/mcp-combiner/mcp-combiner.log` | Capture the combiner's stdout/stderr; `"none"` disables. |
-| `PI_MCP_COMBINER_PYLOG` | `~/.local/state/mcp-combiner/mcp-combiner-py.log` | The combiner's own `--log-file`; `"none"` disables. |
-| `PI_MCP_COMBINER_LOG_LEVEL` | `info` | The combiner's `--log-level`. |
-| `PI_MCP_COMBINER_MANAGE` | `true` | `false` → don't launch (assume the combiner runs elsewhere); instructions only. |
-| `PI_MCP_COMBINER_INSTRUCTIONS` | `true` | `false` → don't append the directive to the system prompt. |
-| `PI_MCP_COMBINER_NOTIFY` | `true` | `false` → don't surface attach/health messages via the Pi UI. |
-| `SHAREDSERVER_BIN` | *(auto-resolved)* | Path to the `sharedserver` binary. |
-| `SHAREDSERVER_LOCKDIR` | — | `sharedserver` lock directory. |
-
-### `servers.json` auto-probe
-
-`$PI_MCP_COMBINER_CONFIG` → `~/.cache/secrets/<user>.mcpservers.json` →
-`~/.config/mcp-combiner/servers.json` → `~/.config/mcp/servers.json`.
-
-### Combiner command resolution
-
-`$PI_MCP_COMBINER_COMMAND` (+`$PI_MCP_COMBINER_ARGS`) → `mcp-combiner` on `PATH` (only
-when ≥ 0.8.0) → `uv run --project <checkout> python -m mcp_combiner` → a pinned release
-via `uvx`. If the `mcp-combiner` on PATH is older than 0.8.0, the extension warns and
-falls back to a pinned `uvx` release rather than silently using a stale binary.
+In `"directTools": "search"` mode, search matches are promoted to first-class tools
+and announced in the result.
+
+**`mcpScript`** — batch calls with trusted JavaScript:
+`{code: "const r = await tools.search('q'); emit(r); return await tools.call('t', {})"}`.
+
+**`read_<resource>` tools** — one zero-parameter tool per MCP resource; interactive
+`mcp-app` resources are flagged and their `read_*` results append the combiner UI-host URL (`/ui/<token>/?resource=…`), auto-opened in the browser — the interactive widget runs combiner-side.
+
+**Interactive widgets (mcp-app)** — when a widget-bound tool result arrives (e.g.
+`todoist_find-tasks-by-date`), the combiner **holds the call in flight**: the
+extension auto-opens the widget in your browser, the tool's data streams to it
+over SSE, and you interact while the call waits. Hit **Done** in the widget and
+the call resolves with a summary of what you did. Every widget action runs
+through the combiner's permission pipeline, and the full interaction stays
+retrievable: ask for `combiner__ui_messages` afterwards (the hold budget is 50s
+by default — `MCP_COMBINER_UI_HOLD_TIMEOUT` combiner-side; the widget URL stays
+valid after a timeout, you just lose the fold-into-result for that call).
+Widgets that self-fetch (svg-mcp's preview) work the same way.
+
+**Prompt slash commands** — `mcp__<server>__<name>` (e.g. `mcp__todoist__productivity_analysis`),
+positional + `name=value` args with bash quoting.
+
+**Footer** — `14 servers enabled (13 ready) · 671 tools` under the `mcp` status key;
+refreshed on connect/changes and every 30s; honest degradation when unreachable.
+
+**`/mcp-combiner` command**:
+
+| Verb                                          | Effect                                                       |
+| --------------------------------------------- | ------------------------------------------------------------ |
+| _(none)_ / `status`                           | Connection state, per-server glyph table, session view       |
+| `panel`                                       | Interactive panel (below)                                    |
+| `enable` / `disable` / `restart-server <srv>` | Drive the combiner's meta-tools                              |
+| `system-prompt`                               | Show the injected directive                                  |
+| `install-config [path]`                       | Legacy: write the shared-`mcp.json` entry for pi-mcp-adapter |
+
+**The panel** — `/mcp-combiner panel`: connection + port + session token, exposure
+filter, fuzzy search (`/`), per-server rows with state glyphs (`● ○ ⊘ ✗ ◌`) and the
+tools/resources/prompts counts trio, expandable tool lists with token estimates,
+`[session off]` labels for project-filtered servers, the combiner's own `⬢` meta-tools
+group. Keys: `↑↓/jk` move · `enter` expand/copy · `e` enable/disable · `c` copy ·
+`/` filter · `r` refresh · `q` close.
+
+## Chat identity
+
+Each Pi session mints its own grouping token (`pi-<sessionId>`) into the combiner URL
+path, so per-chat isolation (`isolate: true` servers), parked upstream sessions, and
+restart handover all key on the chat — subagents automatically get their own tokens
+(each child session binds fresh). A resumed chat continues its identity; a fork
+deliberately starts fresh. An explicit token in the configured URL always wins.
+
+## Permissions
+
+Tool-call policy is enforced **at the combiner** (`permissions` in `servers.json`:
+deny/elicit/allow per server, with interactive elicitation bridged to Pi's UI —
+subagents decline securely by default). If you also run
+[`pi-permission-system`](https://github.com/gotgenes/pi-packages), keep `toolName:
+"mcp"` for its `mcp`-surface rules (tool-glob patterns like `github_*` match out of
+the box).
+
+## Acknowledgments
+
+The client half began as a substantial reduction of
+[**pi-mcp-adapter**](https://github.com/nicobailon/pi-mcp-adapter) (MIT, © Nico Bailon) —
+the proxy-tool calling convention, search semantics, result-guard behavior, prompt
+command format, resource naming, the schema-signature renderer, and the HTML/JS
+widget contract derive from it, and the conformance cases in `test/` are ported from
+its suite. Everything OAuth, multi-server, and transport-related is deliberately
+_not_ here — the combiner owns that. This package would be a much worse tool
+without Nico's design work; go star it.
 
 ## Host-owned mode
 
 If **`$MCP_COMPANION_COMBINER_URL`** is set, an editor/host (e.g. Neovim) already owns
-and refcounts the combiner. The extension then **only injects instructions** and never
-starts or stops the process — the same early-exit as the sibling plugins. Equivalent to
-`PI_MCP_COMBINER_MANAGE=false`.
+and refcounts the combiner — this extension never launches it (the client still
+connects). Equivalent to `PI_MCP_COMBINER_MANAGE=false` for the process half.
 
 ## Development
 
@@ -163,12 +263,13 @@ starts or stops the process — the same early-exit as the sibling plugins. Equi
 npm install
 npm run typecheck
 npm run build      # emits dist/ (not committed; built on publish)
+npm run smoke      # live suite against the running combiner on :9741
 ```
 
-The `src/sharedserver-resolve.ts` file is **vendored byte-identical** from
+Design notes: [`docs/adapter-design.md`](./docs/adapter-design.md). The
+`src/sharedserver-resolve.ts` file is **vendored byte-identical** from
 [`georgeharker/sharedserver`](https://github.com/georgeharker/sharedserver) (via
-`scripts/sync-vendored.sh`), shared with the OpenCode plugin so both answer "which
-sharedserver, and why" identically. Edit it upstream; re-sync here.
+`scripts/sync-vendored.sh`). Edit upstream; re-sync here.
 
 ## License
 

package/dist/client/config-ladder.d.ts

@@ -0,0 +1,62 @@
+import type { DirectToolsSpec } from "./direct-tools.js";
+export type ServerFilter = {
+    allow?: string[];
+    deny?: string[];
+};
+export type CombinerBlock = {
+    servers?: ServerFilter;
+    exposeResources?: boolean;
+    prompts?: boolean;
+    /** Direct tool promotion: glob allowlist over combined tool names (e.g.
+     *  ["combiner__status", "github_search_*"]), or "search" to register tools as
+     *  first-class Pi tools the first time mcp({search}) matches them. */
+    directTools?: string[] | "search";
+};
+export type CombinerEntry = {
+    url?: string;
+    bearerTokenEnv?: string;
+    combiner?: CombinerBlock;
+};
+export type LadderResult = {
+    /** Merged combiner entry (later files win). Empty object when absent everywhere. */
+    entry: CombinerEntry;
+    /** Non-combiner server names seen in the ladder — reported (not connected) in v1. */
+    otherServers: string[];
+    /** Files that existed and were read, in ladder order. */
+    sources: string[];
+};
+/** The ladder, lowest precedence first. Mirrors pi-mcp-adapter's documented order. */
+export declare function ladderPaths(cwd: string): string[];
+/** Recognize "our" entry: explicit name, explicit marker, or url origin match. */
+export declare function isCombinerEntry(name: string, entry: Record<string, unknown>, combinerOrigin: string | undefined): boolean;
+/** Walk the ladder (cwd-relative project files included) and merge. */
+export declare function readLadder(cwd: string, combinerOrigin: string | undefined): LadderResult;
+export type SessionConfig = {
+    /** Token-stripped base URL incl. /mcp. */
+    baseUrl: string;
+    bearerTokenEnv: string | undefined;
+    /** Explicit token from the configured URL path (user override), if any. */
+    urlToken: string | undefined;
+    serverFilter: ServerFilter | undefined;
+    directSpec: DirectToolsSpec | undefined;
+    entry: CombinerEntry;
+    otherServers: string[];
+    sources: string[];
+};
+export type ResolveSessionConfigOptions = {
+    /** Session working directory (project layers read from here). */
+    cwd: string;
+    /** Explicit env URL (host-owned or PI_MCP_COMBINER_URL), highest precedence. */
+    envUrl: string | undefined;
+    /** Settings-file URL, next precedence. */
+    settingsUrl: string | undefined;
+    /** Serve-side default (host:port/mcp) for origin matching and the fallback. */
+    defaultUrl: string;
+};
+/** Extract an explicit /mcp/<token> path token from a URL, if present. */
+export declare function urlTokenOf(url: string): string | undefined;
+/** Normalize a URL back to bare /mcp (strip any token path). */
+export declare function stripUrlToken(url: string): string;
+/** Resolve the full per-session config. Pure — no env or settings reads inside. */
+export declare function resolveSessionConfig(opts: ResolveSessionConfigOptions): SessionConfig;
+//# sourceMappingURL=config-ladder.d.ts.map

package/dist/client/config-ladder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-ladder.d.ts","sourceRoot":"","sources":["../../src/client/config-ladder.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAExD,MAAM,MAAM,YAAY,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEhE,MAAM,MAAM,aAAa,GAAG;IACxB,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;0EAEsE;IACtE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IACxB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAE,aAAa,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACvB,oFAAoF;IACpF,KAAK,EAAE,aAAa,CAAA;IACpB,qFAAqF;IACrF,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,yDAAyD;IACzD,OAAO,EAAE,MAAM,EAAE,CAAA;CACpB,CAAA;AAED,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CASjD;AAmBD,kFAAkF;AAClF,wBAAgB,eAAe,CAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,cAAc,EAAE,MAAM,GAAG,SAAS,GACnC,OAAO,CAMT;AAqDD,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,CAUxF;AASD,MAAM,MAAM,aAAa,GAAG;IACxB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,YAAY,EAAE,YAAY,GAAG,SAAS,CAAA;IACtC,UAAU,EAAE,eAAe,GAAG,SAAS,CAAA;IACvC,KAAK,EAAE,aAAa,CAAA;IACpB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,OAAO,EAAE,MAAM,EAAE,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,2BAA2B,GAAG;IACtC,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAA;IACX,gFAAgF;IAChF,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,0CAA0C;IAC1C,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG1D;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AAUD,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,GAAG,aAAa,CAarF"}