@geohar/pi-mcp-combiner 0.14.3 → 0.16.0-dev.1

package/dist/client/tool-matching.d.ts

@@ -0,0 +1,32 @@
+/** A combined-tool allowlist spec from the ladder's `combiner.directTools` key:
+ *  a glob allowlist, or "search" (legacy adapter semantics — deprecated in the
+ *  native mode, where tool_search replaces it). */
+export type DirectToolsSpec = string[] | "search";
+/** Names that must never be shadowed by a promoted/registered tool (pi builtins).
+ *  Callers add their own tool names on top. */
+export declare const RESERVED_TOOL_NAMES: readonly ["read", "bash", "edit", "write", "grep", "find", "ls", "mcp", "glob"];
+/** Apply a server allow/deny filter to a combined tool list. Server names may
+ *  contain underscores (gws_georgeharker), so matching is by PREFIX — a tool
+ *  belongs to entry E iff its name starts `E_` (subsumes first-segment equality). */
+export declare function toolServerMatches(toolName: string, serverEntry: string): boolean;
+/** Apply a server allow/deny filter to a combined tool list (`<server>_` prefix,
+ *  underscore-safe via toolServerMatches). */
+export declare function applyServerFilter(tools: ToolSummary[], filter: {
+    allow?: string[];
+    deny?: string[];
+} | undefined): ToolSummary[];
+/** fnmatch-lite: `*` → any run, `?` → one char, everything else literal. */
+export declare function globToRegExp(pattern: string): RegExp;
+export declare function matchesGlob(name: string, pattern: string): boolean;
+export type ToolSummary = {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+};
+//# sourceMappingURL=tool-matching.d.ts.map

package/dist/client/tool-matching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-matching.d.ts","sourceRoot":"","sources":["../../src/client/tool-matching.ts"],"names":[],"mappings":"AAUA;;mDAEmD;AACnD,MAAM,MAAM,eAAe,GAAG,MAAM,EAAE,GAAG,QAAQ,CAAA;AAEjD;+CAC+C;AAC/C,eAAO,MAAM,mBAAmB,iFAAkF,CAAA;AAElH;;qFAEqF;AACrF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAEhF;AAED;8CAC8C;AAC9C,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,WAAW,EAAE,EACpB,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,SAAS,GAC1D,WAAW,EAAE,CASf;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAElE;AAKD,MAAM,MAAM,WAAW,GAAG;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,WAAW,CAAC,EAAE;QACV,YAAY,CAAC,EAAE,OAAO,CAAA;QACtB,eAAe,CAAC,EAAE,OAAO,CAAA;QACzB,cAAc,CAAC,EAAE,OAAO,CAAA;QACxB,aAAa,CAAC,EAAE,OAAO,CAAA;KAC1B,CAAA;CACJ,CAAA"}

package/dist/client/tool-matching.js

@@ -0,0 +1,43 @@
+// Shared tool-name matching helpers — extracted from legacy-client/direct-tools.ts
+// during the legacy-client factoring so the NATIVE tool surface (src/native/) and the
+// client half (src/client/: config-ladder, panel) can use them without importing the
+// deprecated legacy-client/ directory. When legacy-client/ is deleted, this file
+// survives untouched.
+//
+// These are the stable contract:
+//   - tool names arrive with the combiner's baked `<server>_` prefix
+//   - server attribution is PREFIX-based (underscore-safe), not string equality
+/** Names that must never be shadowed by a promoted/registered tool (pi builtins).
+ *  Callers add their own tool names on top. */
+export const RESERVED_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls", "mcp", "glob"];
+/** Apply a server allow/deny filter to a combined tool list. Server names may
+ *  contain underscores (gws_georgeharker), so matching is by PREFIX — a tool
+ *  belongs to entry E iff its name starts `E_` (subsumes first-segment equality). */
+export function toolServerMatches(toolName, serverEntry) {
+    return toolName.startsWith(`${serverEntry}_`);
+}
+/** Apply a server allow/deny filter to a combined tool list (`<server>_` prefix,
+ *  underscore-safe via toolServerMatches). */
+export function applyServerFilter(tools, filter) {
+    if (!filter)
+        return tools;
+    if (filter.allow?.length) {
+        return tools.filter((t) => filter.allow.some((e) => toolServerMatches(t.name, e)));
+    }
+    if (filter.deny?.length) {
+        return tools.filter((t) => !filter.deny.some((e) => toolServerMatches(t.name, e)));
+    }
+    return tools;
+}
+/** fnmatch-lite: `*` → any run, `?` → one char, everything else literal. */
+export function globToRegExp(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*")
+        .replace(/\?/g, ".");
+    return new RegExp(`^${escaped}$`, "i");
+}
+export function matchesGlob(name, pattern) {
+    return globToRegExp(pattern).test(name);
+}
+//# sourceMappingURL=tool-matching.js.map

package/dist/client/tool-matching.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-matching.js","sourceRoot":"","sources":["../../src/client/tool-matching.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,sFAAsF;AACtF,qFAAqF;AACrF,iFAAiF;AACjF,sBAAsB;AACtB,EAAE;AACF,iCAAiC;AACjC,qEAAqE;AACrE,gFAAgF;AAOhF;+CAC+C;AAC/C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAU,CAAA;AAElH;;qFAEqF;AACrF,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,WAAmB;IACnE,OAAO,QAAQ,CAAC,UAAU,CAAC,GAAG,WAAW,GAAG,CAAC,CAAA;AACjD,CAAC;AAED;8CAC8C;AAC9C,MAAM,UAAU,iBAAiB,CAC7B,KAAoB,EACpB,MAAyD;IAEzD,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IACzB,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,KAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;IACvF,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;IACvF,CAAC;IACD,OAAO,KAAK,CAAA;AAChB,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAC,OAAe;IACxC,MAAM,OAAO,GAAG,OAAO;SAClB,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC;SACpC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC;SACpB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IACxB,OAAO,IAAI,MAAM,CAAC,IAAI,OAAO,GAAG,EAAE,GAAG,CAAC,CAAA;AAC1C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,OAAe;IACrD,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAC3C,CAAC"}

package/dist/client/types.d.ts

@@ -0,0 +1,71 @@
+import type { ServerFilter } from "./config-ladder.js";
+import type { ElicitUi } from "./elicitation.js";
+export type LogFn = (level: "info" | "warn" | "error", message: string) => void;
+export type ResolvedConnection = {
+    /** Base URL including /mcp, WITHOUT any token path (e.g. http://127.0.0.1:9741/mcp). */
+    baseUrl: string;
+    /** Env var holding the inbound bearer token (read at connect time), if any. */
+    bearerTokenEnv?: string;
+    /** Explicit token already present in the configured URL path (user override). */
+    urlToken?: string;
+};
+export type ConnectionState = "disconnected" | "connecting" | "connected" | "failed";
+export type ToolSummary = {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+};
+export type PromptArgument = {
+    name: string;
+    description?: string;
+    required?: boolean;
+};
+export type PromptSummary = {
+    name: string;
+    title?: string;
+    description?: string;
+    arguments?: PromptArgument[];
+};
+export type ResourceSummary = {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+    _meta?: Record<string, unknown>;
+};
+/** Optional callbacks fired by the connection (set from index.ts wiring). */
+export type ConnectionHooks = {
+    /** tools/list_changed arrived — caches invalidated; refresh derived surfaces. */
+    onToolsChanged?: () => void;
+    /** connection state transitioned — refresh footer/status surfaces. */
+    onStateChange?: (state: ConnectionState) => void;
+    /** Stage 2: the combiner announced a widget UI URL while an agent tool call
+     *  is held in flight — the client should open it (gated by uiAutoOpen). */
+    onWidgetUrl?: (url: string) => void;
+};
+/** The connection surface every module types against — the duck-parity contract
+ *  both the retired SDK connection and the native pi-mcp connection implemented. */
+export interface CombinerConnection {
+    state: ConnectionState;
+    lastError: string | undefined;
+    sessionToken: string | undefined;
+    setToken(token: string): void;
+    rebind(conn: ResolvedConnection): boolean;
+    reset(reason: string): Promise<void>;
+    ensureConnected(): Promise<unknown>;
+    listTools(force?: boolean): Promise<ToolSummary[]>;
+    listPrompts(force?: boolean): Promise<PromptSummary[]>;
+    getPrompt(name: string, args: Record<string, string>): Promise<unknown>;
+    listResources(force?: boolean): Promise<ResourceSummary[]>;
+    readResource(uri: string): Promise<unknown>;
+    callTool(name: string, args: Record<string, unknown> | undefined): Promise<unknown>;
+    controlOrigin(): string;
+    uiUrlFor(resourceUri: string): string;
+    applyFilter(filter: ServerFilter): Promise<void>;
+    health(): Promise<unknown>;
+    setHooks(hooks: ConnectionHooks): void;
+    bindUi(ui: ElicitUi): void;
+}
+/** Build the tokened endpoint URL: <origin>/mcp/<token> (combiner's URL form). */
+export declare function tokenedUrl(baseUrl: string, token: string): string;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"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"}

package/dist/client/types.js

@@ -0,0 +1,16 @@
+// Shared connection contract: the types every surface (router, panel, footer,
+// prompts, resources, the extension wiring) types against. The concrete class
+// lives in native/combiner-connection.ts (the pi-mcp transport); this module
+// owns the INTERFACE so no surface depends on the implementation.
+/** Build the tokened endpoint URL: <origin>/mcp/<token> (combiner's URL form). */
+export function tokenedUrl(baseUrl, token) {
+    try {
+        const u = new URL(baseUrl);
+        u.pathname = `${u.pathname.replace(/\/+$/, "")}/${token}`;
+        return u.toString();
+    }
+    catch {
+        return `${baseUrl.replace(/\/+$/, "")}/${token}`;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/client/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,8EAA8E;AAC9E,6EAA6E;AAC7E,kEAAkE;AAmElE,kFAAkF;AAClF,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,KAAa;IACrD,IAAI,CAAC;QACD,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAA;QAC1B,CAAC,CAAC,QAAQ,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAA;QACzD,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAA;IACvB,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAA;IACpD,CAAC;AACL,CAAC"}

package/dist/client/widget-support.d.ts

@@ -0,0 +1,17 @@
+import type { ResourceSummary } from "./types.js";
+export declare const MAX_RESULT_CHARS: number;
+export declare const MCP_APP_MIME = "text/html;profile=mcp-app";
+/** True for interactive ext-apps resources: read_* returns their markup AND
+ *  surfaces the combiner UI-host URL (which serves the live widget). */
+export declare function isInteractiveResource(r: ResourceSummary): boolean;
+/** Platform browser open — best-effort; failures are fine (the URL is in the
+ *  result text anyway). Spawned detached so pi退出 doesn't kill the browser. */
+export declare function openInBrowser(url: string): void;
+/** The ui:// resource a tool result carries (port of the adapter's
+ * getToolUiResourceUri): `_meta["ui/resourceUri"]` or `_meta.ui.resourceUri`. */
+export declare function toolUiResourceUri(result: unknown): string | undefined;
+/** MCP readResource result → guarded plain text: text contents pass through
+ *  (pretty-printed when small JSON; with the shared size guard), images become
+ *  markers, base64 blobs become byte notes. */
+export declare function renderResourceResult(result: unknown): string;
+//# sourceMappingURL=widget-support.d.ts.map

package/dist/client/widget-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-support.d.ts","sourceRoot":"","sources":["../../src/client/widget-support.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,eAAO,MAAM,gBAAgB,QAAY,CAAA;AAEzC,eAAO,MAAM,YAAY,8BAA8B,CAAA;AAEvD;wEACwE;AACxE,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,eAAe,GAAG,OAAO,CAEjE;AAED;8EAC8E;AAC9E,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAO/C;AAED;iFACiF;AACjF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAOrE;AAiBD;;+CAE+C;AAC/C,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAsB5D"}

package/dist/client/widget-support.js

@@ -0,0 +1,89 @@
+// Widget/interactive-resource support — extracted from legacy-client/render.ts,
+// proxy-tool.ts, and resources.ts during the legacy-client factoring.
+//
+// These pieces are NOT proxy-surface specific: they are the combiner UI-host,
+// mcp-app-resource, and browser-open mechanics that SURVIVE into the native mode
+// (widget holds via the connection's onWidgetUrl log-tap; read_* tools for ui://
+// resources, which pi's built-in read_mcp_resource deliberately does NOT cover).
+// When legacy-client/ is deleted, this file keeps them alive; legacy/resources.ts
+// imports them from here in the meantime.
+import { spawn } from "node:child_process";
+export const MAX_RESULT_CHARS = 16 * 1024;
+export const MCP_APP_MIME = "text/html;profile=mcp-app";
+/** True for interactive ext-apps resources: read_* returns their markup AND
+ *  surfaces the combiner UI-host URL (which serves the live widget). */
+export function isInteractiveResource(r) {
+    return r.mimeType === MCP_APP_MIME || r.uri.startsWith("ui://");
+}
+/** Platform browser open — best-effort; failures are fine (the URL is in the
+ *  result text anyway). Spawned detached so pi退出 doesn't kill the browser. */
+export function openInBrowser(url) {
+    const cmd = process.platform === "darwin" ? ["open"] : ["xdg-open"];
+    try {
+        spawn(cmd[0], [...cmd.slice(1), url], { stdio: "ignore", detached: true }).unref?.();
+    }
+    catch {
+        // no opener available — the URL is in the result text anyway
+    }
+}
+/** The ui:// resource a tool result carries (port of the adapter's
+ * getToolUiResourceUri): `_meta["ui/resourceUri"]` or `_meta.ui.resourceUri`. */
+export function toolUiResourceUri(result) {
+    const meta = result?._meta;
+    if (typeof meta !== "object" || meta === null)
+        return undefined;
+    const m = meta;
+    const nested = m.ui?.resourceUri;
+    const uri = typeof nested === "string" ? nested : m["ui/resourceUri"];
+    return typeof uri === "string" && uri.startsWith("ui://") ? uri : undefined;
+}
+const maxPrettyCharsDefault = 2048;
+function prettifyIfSmallJson(text, maxPrettyChars = maxPrettyCharsDefault) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0 || trimmed.length > maxPrettyChars)
+        return text;
+    if (!(trimmed.startsWith("{") || trimmed.startsWith("[")))
+        return text;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed !== "object" || parsed === null)
+            return text;
+        return JSON.stringify(parsed, null, 2);
+    }
+    catch {
+        return text;
+    }
+}
+/** MCP readResource result → guarded plain text: text contents pass through
+ *  (pretty-printed when small JSON; with the shared size guard), images become
+ *  markers, base64 blobs become byte notes. */
+export function renderResourceResult(result) {
+    const contents = result?.contents;
+    if (!Array.isArray(contents) || contents.length === 0)
+        return "(empty resource)";
+    const parts = [];
+    for (const c of contents) {
+        if (typeof c !== "object" || c === null)
+            continue;
+        const item = c;
+        const mime = typeof item.mimeType === "string" ? item.mimeType : "unknown";
+        if (typeof item.text === "string") {
+            parts.push(prettifyIfSmallJson(item.text));
+        }
+        else if (typeof item.blob === "string") {
+            const bytes = Math.floor((item.blob.length * 3) / 4); // base64 → approx decoded size
+            parts.push(`[binary ${mime}, ~${bytes} bytes — uri ${item.uri ?? "?"}]`);
+        }
+        else if (mime.startsWith("image/")) {
+            parts.push(`[image: ${mime} — uri ${item.uri ?? "?"}]`);
+        }
+        else {
+            parts.push(`[unreadable content: ${mime} — uri ${item.uri ?? "?"}]`);
+        }
+    }
+    const text = parts.join("\n").trim() || "(empty resource)";
+    if (text.length <= MAX_RESULT_CHARS)
+        return text;
+    return `${text.slice(0, MAX_RESULT_CHARS)}\n\n… (resource truncated at ${MAX_RESULT_CHARS} chars)`;
+}
+//# sourceMappingURL=widget-support.js.map

package/dist/client/widget-support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-support.js","sourceRoot":"","sources":["../../src/client/widget-support.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAER,YAAY,EAKf,MAAM,SAAS,CAAA;AA4PhB,MAAM,CAAC,OAAO,UAAU,WAAW,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA8b1D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAER,YAAY,EAMf,MAAM,SAAS,CAAA;AAyPhB,MAAM,CAAC,OAAO,UAAU,WAAW,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA4e1D"}

package/dist/index.js

@@ -31,17 +31,20 @@ import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveSharedserver } from "./sharedserver-resolve.js";
-import { CombinerConnection } from "./client/connection.js";
-import { createMcpTool, openInBrowser } from "./client/proxy-tool.js";
+import { NativeCombinerConnection, activateNativeMode } from "./native/index.js";
+// ── TOOL SURFACE ───────────────────────────────────────────────────────────────
+// The mcp router (search/describe/call on the owned connection) + the native
+// per-tool registration (pi-1.0 exposure/namespace/annotations) + interactive
+// read_<resource> tools. Shared surface modules live in src/client/; the transport
+// is src/native/combiner-connection.ts (pi-mcp, peer dep).
+import { createMcpTool } from "./client/proxy-tool.js";
+import { openInBrowser } from "./client/widget-support.js";
 import { agentDir, loadSettings, settingsPath } from "./client/settings.js";
 import { resolveSessionConfig } from "./client/config-ladder.js";
 import { metaToolCall, statusText as controlStatusText } from "./client/control.js";
 import { openCombinerPanel } from "./client/panel.js";
 import { syncPromptCommands } from "./client/prompts.js";
-import { syncResourceTools } from "./client/resources.js";
-import { activateFromSearch, applyServerFilter, RESERVED_TOOL_NAMES, syncAllowlistTools, } from "./client/direct-tools.js";
 import { updateFooter } from "./client/footer.js";
-import { createScriptTool } from "./client/script.js";
 const DEFAULT_PORT = 9741;
 const DEFAULT_NAME = "mcp-combiner";
 const DEFAULT_GRACE = "30m";
@@ -288,13 +291,25 @@ export default function mcpCombiner(pi) {
                 uiLevel = "warn";
             else if (level === "error")
                 uiLevel = "error";
-            uiNotify(line, uiLevel);
+            try {
+                uiNotify(line, uiLevel);
+            }
+            catch {
+                // The captured ctx went stale (reload/session replacement kills
+                // extension ctxs — pi 1.0 asserts on use). Degrade to stderr and
+                // drop the capture so later logs skip the dead path entirely:
+                // an async log line (e.g. a superseded connection's reset) must
+                // NEVER crash the process.
+                uiNotify = undefined;
+                process.stderr.write(`${line}\n`);
+            }
         }
         else if (level !== "info") {
             process.stderr.write(`${line}\n`);
         }
     };
     let connection;
+    let nativeSurface;
     // Session-config HOLDER: everything the ladder shapes, resolved against a SESSION
     // cwd (worktree subagents / project switches get their own project layers).
     // Factory-time resolution with process.cwd() is the pre-session default; every
@@ -306,17 +321,6 @@ export default function mcpCombiner(pi) {
         bearerTokenEnv: cfg.bearerTokenEnv ?? "MCP_COMBINER_AUTH_TOKEN",
         urlToken: cfg.urlToken,
     });
-    const registeredDirect = new Set();
-    const directReserved = new Set(RESERVED_TOOL_NAMES);
-    directReserved.add(toolName);
-    directReserved.add(`${toolName}Script`);
-    const directDepsFor = (conn) => ({
-        connection: conn,
-        registered: registeredDirect,
-        reserved: directReserved,
-        register: (tool) => pi.registerTool(tool),
-        log: clientLog,
-    });
     if (adapterEnabled) {
         sessionCfg = resolveSessionConfig({
             cwd: process.cwd(),
@@ -324,17 +328,47 @@ export default function mcpCombiner(pi) {
             settingsUrl: settings.url,
             defaultUrl: defaultCombinerUrl(),
         });
-        connection = new CombinerConnection(connInputsFor(sessionCfg), clientLog);
-        const activeConn = connection; // narrowed for the activation closure below
+        // Zombie teardown: pi re-imports the extension module on /reload WITHOUT
+        // firing session_shutdown (the session persists, no unload hook exists), so
+        // the previous instance's McpClient + SSE stream would live on and compete
+        // for the token's elicit routing. A process-global registry survives module
+        // re-imports: the fresh factory closes every prior live connection first.
+        const g = globalThis;
+        // The teardown closures below (from prior factory runs, orphaned by pi's
+        // reload-without-session_shutdown) know how to fully retire their instance:
+        // clear the footer timer, drop the captured UI ctx (stale-ctx reads on it
+        // are a hard pi-1.0 assertion), and close the connection.
+        for (const dispose of g.__piMcpCombinerDispose ?? []) {
+            try {
+                dispose();
+            }
+            catch {
+                // teardown must never break the fresh instance's load
+            }
+        }
+        g.__piMcpCombinerDispose = [];
+        connection = new NativeCombinerConnection(connInputsFor(sessionCfg), clientLog);
+        // The mcp router registers alongside the per-tool native surface (the same
+        // owned connection — not a second proxy): tool_call gates such as
+        // pi-permission-system and pi-subagents recognize MCP calls by the tool
+        // name "mcp", and the router keeps a discovery/search surface.
         pi.registerTool(createMcpTool({
             connection,
             toolName,
             getServerFilter: () => sessionCfg?.serverFilter,
-            onSearchMatches: (tools) => sessionCfg?.directSpec === "search" ? activateFromSearch(tools, directDepsFor(activeConn)) : [],
         }));
-        if (settings.scriptMode) {
-            pi.registerTool(createScriptTool({ connection, name: `${toolName}Script` }));
-        }
+        // Per-tool surface + interactive read_*. The FIRST registration runs at
+        // session_start (post-setToken — the connection refuses to connect
+        // without a grouping token); list_changed re-syncs ride resyncAll below.
+        nativeSurface = activateNativeMode(pi, {
+            connection,
+            directSpec: sessionCfg?.directSpec ?? [],
+            serverFilter: sessionCfg?.serverFilter,
+            exposeResources: settings.exposeResources !== false,
+            uiAutoOpen: settings.uiAutoOpen !== false,
+            warnLargeDirectExposure: settings.warnLargeDirectExposure,
+            log: clientLog,
+        });
         if (sessionCfg.otherServers.length && !adapterPackageInstalled()) {
             clientLog("info", `note: ${sessionCfg.otherServers.length} non-combiner server(s) in the mcp.json ladder are not ` +
                 `connected by this extension (${sessionCfg.otherServers.join(", ")})`);
@@ -350,9 +384,22 @@ export default function mcpCombiner(pi) {
     if (connection) {
         const conn = connection; // captured non-optional for the handlers below
         const registeredPrompts = new Set();
-        const registeredResources = new Set();
         let footerTimer;
         let uiCtx;
+        // Full instance teardown, callable from a LATER factory run (pi re-imports
+        // the module on /reload without firing session_shutdown): clears this
+        // instance's footer timer, drops its captured UI ctx (stale-ctx reads are
+        // a hard pi-1.0 assertion), and closes its connection. The registry lives
+        // on globalThis — the one thing that survives a module re-import.
+        const teardownGlobal = globalThis;
+        (teardownGlobal.__piMcpCombinerDispose ??= []).push(() => {
+            if (footerTimer)
+                clearInterval(footerTimer);
+            footerTimer = undefined;
+            uiCtx = undefined;
+            uiNotify = undefined;
+            void conn.reset("superseded by a newer extension instance (reload)");
+        });
         const refreshFooter = () => {
             if (uiCtx)
                 void updateFooter(conn, uiCtx, settings.mcpFooterKey, settings.mcpFooterStatus).catch(() => undefined);
@@ -362,31 +409,27 @@ export default function mcpCombiner(pi) {
                 return;
             void syncPromptCommands(pi, conn, toolName, registeredPrompts, (m, l) => clientLog(l, m)).catch(() => undefined);
         };
-        const syncResources = () => {
-            if (!settings.exposeResources)
-                return;
-            void syncResourceTools((tool) => pi.registerTool(tool), conn, registeredResources, sessionCfg?.serverFilter, (m, l) => clientLog(l, m)).catch(() => undefined);
-        };
-        const syncDirect = () => {
-            // Allowlist mode only — "search" registers nothing upfront.
-            const spec = sessionCfg?.directSpec;
-            if (!Array.isArray(spec) || spec.length === 0)
-                return;
-            void conn
-                .listTools()
-                .then((tools) => {
-                syncAllowlistTools(applyServerFilter(tools, sessionCfg?.serverFilter), spec, directDepsFor(conn));
-            })
-                .catch(() => undefined);
+        const resyncAll = () => {
+            // Prompts + footer re-sync on: list_changed notifications, reconnect
+            // catch-up (fired by the connection itself), AND session_start — a
+            // reload/re-enter with an UNCHANGED token skips any reconnect, so
+            // without this the surfaces would only ever update on notifications.
+            nativeSurface?.run();
+            syncPrompts();
+            refreshFooter();
         };
         conn.setHooks({
-            onToolsChanged: () => {
-                syncPrompts();
-                syncResources();
-                syncDirect();
+            onToolsChanged: resyncAll,
+            onStateChange: (state) => {
+                // Re-attach on (re)connect: a combiner bounce kills the instance our
+                // sharedserver reference was attached to, and nothing else re-takes
+                // ownership until the next session_start — an orphaned combiner then
+                // grace-stops 30m later (sharedserver `use` is idempotent per pid, so
+                // re-attaching on every connect is safe and cheap).
+                if (state === "connected")
+                    attachCombiner(clientLog);
                 refreshFooter();
             },
-            onStateChange: () => refreshFooter(),
             // Stage 2: the widget hold announces its UI URL mid-call — open it.
             onWidgetUrl: (url) => {
                 if (settings.uiAutoOpen !== false)
@@ -408,6 +451,11 @@ export default function mcpCombiner(pi) {
                 });
                 conn.rebind(connInputsFor(sessionCfg));
                 conn.setToken(sessionToken(event, ctx));
+                // The native per-tool/resource registration runs HERE — post-setToken,
+                // the first moment the grouping token exists (a factory-time run
+                // would fail with "no grouping token set"). Subsequent re-syncs ride
+                // resyncAll via onToolsChanged.
+                nativeSurface?.run();
                 // Per-project exposure: pending filters apply server-side before first connect.
                 const filter = sessionCfg.serverFilter;
                 if (filter) {
@@ -431,8 +479,6 @@ export default function mcpCombiner(pi) {
                         .then(() => {
                         refreshFooter();
                         syncPrompts();
-                        syncResources();
-                        syncDirect();
                     })
                         .catch(() => undefined);
                 }
@@ -475,7 +521,7 @@ export default function mcpCombiner(pi) {
     // restart-server <srv> (combiner meta-tools through our client), system-prompt
     // (show the injected directive), install-config [path] (write the shared mcp.json
     // combiner entry — legacy pairing with pi-mcp-adapter, now also read by our ladder).
-    pi.registerCommand("mcp-combiner", {
+    const combinerCommandSpec = {
         description: "mcp-combiner — verbs: status, enable <srv>, disable <srv>, restart-server <srv>, system-prompt, install-config [path]",
         getArgumentCompletions: (prefix) => completeVerbs(prefix),
         handler: (args, ctx) => {
@@ -530,7 +576,15 @@ export default function mcpCombiner(pi) {
             }
             ctx.ui?.notify?.(`mcp-combiner: unknown verb "${v}". Try: ${COMMAND_VERBS.join(", ")}`, "warn");
         },
-    });
+    };
+    pi.registerCommand("mcp-combiner", combinerCommandSpec);
+    // NOTE: we deliberately do NOT register "/mcp" — pi's built-in MCP extension
+    // owns that command and stays the native-mode transport; our surfaces ("mcp"
+    // router tool, direct <server>_<tool>, read_*) don't collide with the builtin's
+    // (codemode / tool-search / read_mcp_resource). Registering "/mcp" would
+    // displace the builtin at load (pi's loader drops replaceable built-ins on
+    // command-name collision) and with it the native support we're migrating
+    // toward.
     if (hostOwned || !manage) {
         // Registration is static (mcp.json) and the combiner is someone else's to run:
         // nothing to launch. The instructions handler above still applies.
@@ -540,10 +594,7 @@ export default function mcpCombiner(pi) {
     // Pi forbids starting background resources from the factory, so all of this is
     // deferred to session_start. session_start fires again on reload/new/resume/fork
     // within the same process; the `attachment` guard makes re-entry a no-op attach.
-    pi.on("session_start", (_event, ctx) => {
-        if (attachment)
-            return; // already attached in this process
-        const log = makeLog(ctx, notify);
+    const attachCombiner = (log) => {
         const binary = resolveSharedserver({
             label: "mcp-combiner",
             minVersion: SHAREDSERVER_MIN_VERSION,
@@ -620,6 +671,11 @@ export default function mcpCombiner(pi) {
         }
         attachment = { binary, name };
         log("info", `combiner "${name}" attached on port ${port} (${combiner.cmd} ${wrappedArgs.join(" ")})`);
+    };
+    pi.on("session_start", (_event, ctx) => {
+        if (attachment)
+            return; // already attached in this process
+        attachCombiner(makeLog(ctx, notify));
     });
     pi.on("session_shutdown", (event) => {
         // Only "quit" means the Pi process is actually leaving. reload/new/resume/fork