@geohar/pi-mcp-combiner 0.16.0-dev.3 → 0.16.0
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.
- package/README.md +7 -0
- package/dist/client/types.d.ts +6 -1
- package/dist/client/types.d.ts.map +1 -1
- package/dist/client/types.js.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +30 -52
- package/dist/index.js.map +1 -1
- package/dist/native/combiner-connection.d.ts +31 -9
- package/dist/native/combiner-connection.d.ts.map +1 -1
- package/dist/native/combiner-connection.js +131 -80
- package/dist/native/combiner-connection.js.map +1 -1
- package/dist/native/index.d.ts +8 -4
- package/dist/native/index.d.ts.map +1 -1
- package/dist/native/index.js +24 -18
- package/dist/native/index.js.map +1 -1
- package/dist/native/resources.d.ts +7 -2
- package/dist/native/resources.d.ts.map +1 -1
- package/dist/native/resources.js +21 -3
- package/dist/native/resources.js.map +1 -1
- package/dist/native/tool-surface.d.ts +24 -11
- package/dist/native/tool-surface.d.ts.map +1 -1
- package/dist/native/tool-surface.js +71 -34
- package/dist/native/tool-surface.js.map +1 -1
- package/dist/pi.d.ts +9 -1
- package/dist/pi.d.ts.map +1 -1
- package/package.json +6 -2
- package/src/client/types.ts +4 -1
- package/src/index.ts +31 -51
- package/src/native/combiner-connection.ts +155 -83
- package/src/native/index.ts +34 -24
- package/src/native/resources.ts +34 -5
- package/src/native/tool-surface.ts +103 -46
- package/src/pi.ts +5 -1
|
@@ -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
|
|
25
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
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
|
-
|
|
68
|
-
|
|
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
|
-
|
|
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:
|
|
108
|
+
namespace: COMBINER_NAMESPACE,
|
|
92
109
|
annotations: sum.annotations,
|
|
93
110
|
execute: async (_toolCallId, params, signal) => {
|
|
94
|
-
// The abort signal rides into the transport
|
|
95
|
-
// upstream work, and widget holds respect it
|
|
96
|
-
|
|
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
|
-
/**
|
|
110
|
-
*
|
|
111
|
-
* a
|
|
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
|
|
114
|
-
const
|
|
115
|
-
const
|
|
116
|
-
const
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
146
|
-
|
|
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
|
-
|
|
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
|
}
|