@geohar/pi-mcp-combiner 0.16.0-dev.2 → 0.16.0-dev.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -21,57 +21,74 @@
21
21
  // replaces it). Per-project allow/deny keeps flowing combiner-side via applyFilter.
22
22
  //
23
23
  // Wire shape: register once at session_start (tools list is stable modulo
24
- // list_changed, which re-registers on the same names). Tools the combiner offers
25
- // during a session surface via the connection's onToolsChanged hook → activate again.
24
+ // list_changed, which re-registers through this module again). Each pass diffs
25
+ // against the previous registration (schema signatures) so only CHANGED tools hit
26
+ // pi.registerTool (pi's replace-by-name path logs a warning per re-registration —
27
+ // a full re-register on every list_changed would churn hundreds of warnings);
28
+ // tools the server REMOVED are re-registered `hidden` so they stop being
29
+ // callable/declared rather than lingering as broken names.
26
30
 
27
31
  import type { ExtensionAPI, ToolDefinition, ToolParameters } from "../pi.js"
28
32
  import type { NativeCombinerConnection, ToolSummary } from "./combiner-connection.js"
29
33
  import { applyServerFilter, matchesGlob, RESERVED_TOOL_NAMES } from "../client/tool-matching.js"
34
+ import { renderSchemaSignature } from "../client/schema-signature.js"
35
+ import { toLlmContent, type CallToolResult } from "@earendil-works/pi-mcp"
30
36
  import type { ServerFilter } from "../client/config-ladder.js"
31
37
 
32
- function isRecord(v: unknown): v is Record<string, unknown> {
33
- return typeof v === "object" && v !== null && !Array.isArray(v)
34
- }
35
-
36
38
  export type NativeToolSurfaceOptions = {
37
39
  /** The resolved combiner connection (owns elicitation, filters, caches). */
38
40
  connection: NativeCombinerConnection
39
41
  /** The per-project server filter (same object index.ts passes to applyFilter);
40
- * applied defensively here too so a filter race never widens surface exposure. */
41
- serverFilter?: ServerFilter
42
+ * applied defensively here too so a filter race never widens surface exposure.
43
+ * A GETTER resolves per call — worktrees/project switches re-resolve session
44
+ * config, and a load-time snapshot would apply the wrong allow/deny set. */
45
+ serverFilter?: ServerFilter | (() => ServerFilter | undefined)
42
46
  /** The combiner block's directTools spec, as resolved from the ladder: a glob
43
- * allowlist → "direct" exposure for matches; "search" → everything codemode. */
44
- directSpec?: string[] | "search"
47
+ * allowlist → "direct" exposure for matches; "search" → everything codemode.
48
+ * A getter resolves per call (same reason as serverFilter). */
49
+ directSpec?: string[] | "search" | (() => string[] | "search" | undefined)
50
+ /** Cross-pass registration state (see activateNativeTools). A fresh object on
51
+ * first call; the SAME object on every pass so the diffing + hidden-removal
52
+ * work. native/index.ts owns one per activation. */
53
+ state?: NativeToolSurfaceState
45
54
  /** Warn when the direct-exposure set grows large (every declared schema rides in
46
55
  * every request). Settings kill-switch: warnLargeDirectExposure (default true). */
47
56
  warnLargeDirectExposure?: boolean
48
- /** Namespace shown in codemode's grouped listing (pi normalizes -/­_ alike). */
49
- namespaceName?: string
50
- /** Names that must never be shadowed by a combiner tool (pi builtins + ours). */
51
- reserved?: readonly string[]
52
57
  log: (level: "info" | "warn" | "error", message: string) => void
53
58
  }
54
59
 
55
- /** Map a CallToolResult content block to pi's text-block contract. pi tool results
56
- * are arrays of text blocks today; image/other blocks are summarized to text and the
57
- * full result rides `details` for renderers (same shape the SDK client half uses). */
58
- function textBlockOf(b: unknown): { type: "text"; text: string } {
59
- const block = isRecord(b) ? b : undefined
60
- if (block && block.type === "text") {
61
- return { type: "text", text: String(block.text) }
62
- }
63
- const kind = block?.type ?? (block ? "content" : b)
64
- return { type: "text", text: `[${String(kind)} block]` }
60
+ /** Registration memory across passes: currently-declared names + each tool's schema
61
+ * signature, so a changed schema re-registers and an unchanged one doesn't (pi's
62
+ * re-register = replace-with-warning; skipping unchanged declarations avoids the
63
+ * warning churn and keeps pi's tool identity stable). */
64
+ export type NativeToolSurfaceState = {
65
+ names: Set<string>
66
+ signatures: Map<string, string | null>
67
+ }
68
+
69
+ const COMBINER_NAMESPACE = { name: "mcp_combiner", description: "mcp-combiner aggregated tools" } as const
70
+
71
+ function resolveFilter(f: NativeToolSurfaceOptions["serverFilter"]): ServerFilter | undefined {
72
+ return typeof f === "function" ? f() : f
73
+ }
74
+ function resolveDirectSpec(d: NativeToolSurfaceOptions["directSpec"]): string[] | "search" | undefined {
75
+ return typeof d === "function" ? d() : d
65
76
  }
66
77
 
67
- function toToolResult(call: { content?: unknown; structuredContent?: unknown }): {
68
- content: { type: "text"; text: string }[]
78
+ /** Map a `CallToolResult` to pi's tool-result contract via pi-mcp's own converter —
79
+ * text stays text, images become real image blocks (base64 + mime), resource
80
+ * blocks flatten, structured-only results stringify. The full result rides
81
+ * `details` for renderers regardless. */
82
+ // SAFETY: LlmContent (pi-mcp) is { type:"text"; text } | { type:"image"; data; mimeType }
83
+ // — the same elementwise shape src/pi.ts's ToolResult content block union accepts;
84
+ // elementwise-identical, so the assignment is asserted (not a structural re-check).
85
+ type ToolResultContentBlock = { type: "text"; text: string } | { type: "image"; data: string; mimeType: string }
86
+ function toToolResult(call: Pick<CallToolResult, "content" | "structuredContent">): {
87
+ content: ToolResultContentBlock[]
69
88
  } {
70
- const blocks = Array.isArray(call.content) ? call.content : []
71
- return { content: blocks.map((b) => textBlockOf(b)) }
89
+ return { content: toLlmContent(call) as ToolResultContentBlock[] }
72
90
  }
73
91
 
74
- /** Register the combiner's tools natively. */
75
92
  const DIRECT_EXPOSURE_WARN_THRESHOLD = 50
76
93
 
77
94
  /** Turn one combiner ToolSummary into pi's ToolDefinition, plus the native-only fields
@@ -88,14 +105,14 @@ function toNativeTool(sum: ToolSummary, conn: NativeCombinerConnection, exposure
88
105
  // pi-permission-system's classification. Kept optional on ToolDefinition so the
89
106
  // extension stays load-compatible with pi 0.99.x where these fields are ignored.
90
107
  exposure,
91
- namespace: { name: "mcp_combiner", description: "mcp-combiner aggregated tools" },
108
+ namespace: COMBINER_NAMESPACE,
92
109
  annotations: sum.annotations,
93
110
  execute: async (_toolCallId, params, signal) => {
94
- // The abort signal rides into the transport; the combiner can cancel
95
- // upstream work, and widget holds respect it (notifications/cancelled).
96
- void signal
111
+ // The abort signal rides into the transport (callTool's options.signal):
112
+ // cancellation cancels upstream work, and widget holds respect it
113
+ // (notifications/cancelled).
97
114
  try {
98
- const result = await conn.callTool(name, params)
115
+ const result = await conn.callTool(name, params, { signal })
99
116
  return { ...toToolResult(result), details: result }
100
117
  } catch (e) {
101
118
  // pi's error convention: THROWING marks the call an error (no isError
@@ -106,17 +123,37 @@ function toNativeTool(sum: ToolSummary, conn: NativeCombinerConnection, exposure
106
123
  }
107
124
  }
108
125
 
109
- /** Register the combiner's tools natively. Returns the names it registered (for
110
- * status/panel surfaces). Idempotent by name — pi.registerTool replaces by name with
111
- * a warning, so re-registration on list_changed must pass the same names. */
126
+ /** Registration for a tool the combiner no longer offers: same name (replaces the old
127
+ * declaration), exposure `hidden` (not declared to the model/codemode; calling it
128
+ * surfaces a clear error instead of a stale upstream call). */
129
+ function removedToolDefinition(name: string): ToolDefinition {
130
+ return {
131
+ name,
132
+ label: name,
133
+ description: "(unavailable: the combiner no longer offers this tool)",
134
+ parameters: { type: "object", properties: {} },
135
+ exposure: "hidden",
136
+ namespace: COMBINER_NAMESPACE,
137
+ execute: async () => {
138
+ throw new Error(`"${name}" is no longer offered by the combiner; use tool_search or the mcp discovery tool to find its replacement`)
139
+ },
140
+ }
141
+ }
142
+
143
+ /** Register the combiner's tools natively, DIFFING against `state` (which the caller
144
+ * reuses across passes): unchanged declarations are skipped (pi.registerTool
145
+ * replaces-by-name with a warning — churn on every list_changed would spam), changed
146
+ * schemas re-register, and removed tools are re-registered hidden. Returns the names
147
+ * currently active (for status/panel surfaces). */
112
148
  export async function activateNativeTools(pi: ExtensionAPI, opts: NativeToolSurfaceOptions): Promise<string[]> {
113
- const registered = [] as string[]
114
- const cachedNames: string[] = registered
115
- const tools = applyServerFilter(await opts.connection.listTools(true), opts.serverFilter)
116
- const allowlist = Array.isArray(opts.directSpec) ? opts.directSpec : []
117
- const reserved = new Set<string>([...(opts.reserved ?? []), ...RESERVED_TOOL_NAMES])
149
+ const state: NativeToolSurfaceState = opts.state ?? { names: new Set(), signatures: new Map() }
150
+ const tools = applyServerFilter(await opts.connection.listTools(true), resolveFilter(opts.serverFilter))
151
+ const allowlist = Array.isArray(resolveDirectSpec(opts.directSpec)) ? (resolveDirectSpec(opts.directSpec) as string[]) : []
152
+ const reserved: ReadonlySet<string> = new Set(RESERVED_TOOL_NAMES)
118
153
 
154
+ const currentNames = new Set(tools.map((t) => t.name))
119
155
  const directNames: string[] = []
156
+ let fresh = 0
120
157
  for (const sum of tools) {
121
158
  if (reserved.has(sum.name)) {
122
159
  opts.log("warn", `skipping combiner tool "${sum.name}" — collides with a reserved name`)
@@ -127,9 +164,27 @@ export async function activateNativeTools(pi: ExtensionAPI, opts: NativeToolSurf
127
164
  // near-zero declaration cost. "search" degrades to the same codemode mapping
128
165
  // (pi's tool_search replaces the adapter's search-promote semantics).
129
166
  const exposure = allowlist.some((p) => matchesGlob(sum.name, p)) ? "direct" : "codemode"
130
- if (exposure === "direct") directNames.push(sum.name)
167
+ // Diff: skip the re-register when the schema signature is unchanged (pi keeps
168
+ // the existing declaration; re-registering would log its warning for nothing).
169
+ const sig = renderSchemaSignature(sum.inputSchema)
170
+ if (state.names.has(sum.name) && state.signatures.get(sum.name) === sig) {
171
+ continue
172
+ }
131
173
  pi.registerTool(toNativeTool(sum, opts.connection, exposure))
132
- cachedNames.push(sum.name)
174
+ state.signatures.set(sum.name, sig)
175
+ state.names.add(sum.name)
176
+ fresh++
177
+ if (exposure === "direct") directNames.push(sum.name)
178
+ }
179
+ // Removals: hide them (never unregister silently — pi has no unregister; a hidden
180
+ // re-register at the same name retires the declaration).
181
+ let removed = 0
182
+ for (const goneName of [...state.names]) {
183
+ if (currentNames.has(goneName)) continue
184
+ pi.registerTool(removedToolDefinition(goneName))
185
+ state.names.delete(goneName)
186
+ state.signatures.delete(goneName)
187
+ removed++
133
188
  }
134
189
  if (
135
190
  directNames.length > DIRECT_EXPOSURE_WARN_THRESHOLD &&
@@ -142,6 +197,8 @@ export async function activateNativeTools(pi: ExtensionAPI, opts: NativeToolSurf
142
197
  `with "warnLargeDirectExposure": false in extensions/mcp-combiner.json.`,
143
198
  )
144
199
  }
145
- opts.log("info", `native tool surface: ${cachedNames.length} tools registered`)
146
- return cachedNames
200
+ if (fresh || removed) {
201
+ opts.log("info", `native tool surface: ${fresh} registered, ${removed} hidden (removed), ${state.names.size} active`)
202
+ }
203
+ return [...state.names]
147
204
  }
package/src/pi.ts CHANGED
@@ -67,6 +67,8 @@ export type ToolCallContext = ExtensionContext & {
67
67
  }
68
68
 
69
69
  export type TextBlock = { type: "text"; text: string }
70
+ /** Image block as pi-ai accepts it (tool results may carry images — see toLlmContent). */
71
+ export type ImageBlock = { type: "image"; data: string; mimeType: string }
70
72
 
71
73
  /** pi's TUI Component contract (pi-tui's Component). invalidate() is REQUIRED,
72
74
  * not optional: MouseRegion.invalidate calls it unconditionally, and a component
@@ -87,7 +89,9 @@ export type ToolRenderResultOptions = { expanded: boolean; isPartial: boolean }
87
89
  /** pi's real tool-result contract: content is an ARRAY of blocks; the error flag is
88
90
  * set by THROWING from execute, never by returning a property. */
89
91
  export type ToolResult = {
90
- content: TextBlock[]
92
+ /** SAFETY: content blocks follow pi-ai's block union — text or base64 image. The
93
+ * wider-than-TextBlock shape keeps MCP image results lossless (toLlmContent). */
94
+ content: (TextBlock | ImageBlock)[]
91
95
  details?: unknown
92
96
  terminate?: boolean
93
97
  }