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

package/src/client/types.ts

@@ -0,0 +1,80 @@
+// 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.
+
+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 function tokenedUrl(baseUrl: string, token: string): string {
+    try {
+        const u = new URL(baseUrl)
+        u.pathname = `${u.pathname.replace(/\/+$/, "")}/${token}`
+        return u.toString()
+    } catch {
+        return `${baseUrl.replace(/\/+$/, "")}/${token}`
+    }
+}

package/src/client/widget-support.ts

@@ -0,0 +1,86 @@
+// 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"
+import type { ResourceSummary } from "./types.js"
+
+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: ResourceSummary): boolean {
+    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: string): void {
+    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: unknown): string | undefined {
+    const meta = (result as { _meta?: unknown })?._meta
+    if (typeof meta !== "object" || meta === null) return undefined
+    const m = meta as Record<string, unknown>
+    const nested = (m.ui as Record<string, unknown> | undefined)?.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: string, maxPrettyChars = maxPrettyCharsDefault): string {
+    const trimmed = text.trim()
+    if (trimmed.length === 0 || trimmed.length > maxPrettyChars) return text
+    if (!(trimmed.startsWith("{") || trimmed.startsWith("["))) return text
+    try {
+        const parsed: unknown = 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: unknown): string {
+    const contents = (result as { contents?: unknown[] })?.contents
+    if (!Array.isArray(contents) || contents.length === 0) return "(empty resource)"
+    const parts: string[] = []
+    for (const c of contents) {
+        if (typeof c !== "object" || c === null) continue
+        const item = c as Record<string, unknown>
+        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)`
+}

package/src/index.ts

@@ -38,25 +38,23 @@ import type {
     ExtensionContext,
     SessionShutdownEvent,
     SessionStartEvent,
+    CommandSpec,
 } from "./pi.js"
 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, type SessionConfig } 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,
-    type DirectToolDeps,
-} 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"
@@ -340,13 +338,24 @@ export default function mcpCombiner(pi: ExtensionAPI): void {
             let uiLevel: "info" | "warn" | "error" = "info"
             if (level === "warn") 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: CombinerConnection | undefined
+    let connection: NativeCombinerConnection | undefined
+    let nativeSurface: ReturnType<typeof activateNativeMode> | undefined
     // 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
@@ -358,17 +367,6 @@ export default function mcpCombiner(pi: ExtensionAPI): void {
         bearerTokenEnv: cfg.bearerTokenEnv ?? "MCP_COMBINER_AUTH_TOKEN",
         urlToken: cfg.urlToken,
     })
-    const registeredDirect = new Set<string>()
-    const directReserved = new Set<string>(RESERVED_TOOL_NAMES)
-    directReserved.add(toolName)
-    directReserved.add(`${toolName}Script`)
-    const directDepsFor = (conn: CombinerConnection): DirectToolDeps => ({
-        connection: conn,
-        registered: registeredDirect,
-        reserved: directReserved,
-        register: (tool) => pi.registerTool(tool),
-        log: clientLog,
-    })
     if (adapterEnabled) {
         sessionCfg = resolveSessionConfig({
             cwd: process.cwd(),
@@ -376,20 +374,48 @@ export default function mcpCombiner(pi: ExtensionAPI): void {
             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 as { __piMcpCombinerDispose?: Array<() => void> }
+        // 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",
@@ -410,10 +436,23 @@ export default function mcpCombiner(pi: ExtensionAPI): void {
     if (connection) {
         const conn = connection // captured non-optional for the handlers below
         const registeredPrompts = new Set<string>()
-        const registeredResources = new Set<string>()
         let footerTimer: NodeJS.Timeout | undefined
         let uiCtx: ExtensionContext["ui"] | undefined
 
+        // 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 as { __piMcpCombinerDispose?: Array<() => void> }
+        ;(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)
@@ -424,35 +463,26 @@ export default function mcpCombiner(pi: ExtensionAPI): void {
                 () => 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) openInBrowser(url)
@@ -474,6 +504,11 @@ export default function mcpCombiner(pi: ExtensionAPI): void {
                 })
                 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) {
@@ -504,8 +539,6 @@ export default function mcpCombiner(pi: ExtensionAPI): void {
                         .then(() => {
                             refreshFooter()
                             syncPrompts()
-                            syncResources()
-                            syncDirect()
                         })
                         .catch(() => undefined)
                 }
@@ -549,7 +582,7 @@ export default function mcpCombiner(pi: ExtensionAPI): void {
     // 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: CommandSpec = {
         description:
             "mcp-combiner — verbs: status, enable <srv>, disable <srv>, restart-server <srv>, system-prompt, install-config [path]",
         getArgumentCompletions: (prefix) => completeVerbs(prefix),
@@ -624,7 +657,16 @@ export default function mcpCombiner(pi: ExtensionAPI): void {
             }
             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:
@@ -636,10 +678,7 @@ export default function mcpCombiner(pi: ExtensionAPI): void {
     // 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: LogFn): void => {
         const binary = resolveSharedserver(
             {
                 label: "mcp-combiner",
@@ -728,6 +767,11 @@ export default function mcpCombiner(pi: ExtensionAPI): void {
 
         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: SessionShutdownEvent) => {