@geohar/pi-mcp-combiner 0.24.2 → 0.24.5
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/CHANGELOG.md +101 -0
- package/dist/client/footer.d.ts +10 -2
- package/dist/client/footer.d.ts.map +1 -1
- package/dist/client/footer.js +15 -6
- package/dist/client/footer.js.map +1 -1
- package/dist/combiner-process.d.ts +160 -0
- package/dist/combiner-process.d.ts.map +1 -0
- package/dist/combiner-process.js +721 -0
- package/dist/combiner-process.js.map +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +140 -306
- package/dist/index.js.map +1 -1
- package/dist/native/combiner-connection.d.ts +84 -0
- package/dist/native/combiner-connection.d.ts.map +1 -1
- package/dist/native/combiner-connection.js +194 -5
- package/dist/native/combiner-connection.js.map +1 -1
- package/dist/native/index.d.ts +32 -4
- package/dist/native/index.d.ts.map +1 -1
- package/dist/native/index.js +94 -6
- package/dist/native/index.js.map +1 -1
- package/dist/native/resources.d.ts +3 -0
- package/dist/native/resources.d.ts.map +1 -1
- package/dist/native/resources.js +6 -1
- package/dist/native/resources.js.map +1 -1
- package/dist/native/tool-surface.d.ts +31 -2
- package/dist/native/tool-surface.d.ts.map +1 -1
- package/dist/native/tool-surface.js +62 -18
- 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 +5 -5
- package/src/client/footer.ts +16 -4
- package/src/client/panel.ts +1 -1
- package/src/client/renderers.ts +2 -2
- package/src/combiner-process.ts +813 -0
- package/src/index.ts +142 -355
- package/src/native/combiner-connection.ts +220 -10
- package/src/native/index.ts +119 -18
- package/src/native/resources.ts +8 -1
- package/src/native/tool-surface.ts +80 -18
- package/src/pi.ts +6 -1
|
@@ -109,8 +109,57 @@ function ncDbg(s: string): void {
|
|
|
109
109
|
|
|
110
110
|
// Keep in sync with plugins/pi/package.json "version": scripts/bump-version.sh stamps
|
|
111
111
|
// this line alongside the package files (the string is what this client declares).
|
|
112
|
-
const CLIENT_INFO = { name: "pi-mcp-combiner", version: "0.24.
|
|
112
|
+
const CLIENT_INFO = { name: "pi-mcp-combiner", version: "0.24.5" }
|
|
113
113
|
const CONNECT_TIMEOUT_MS = 8_000
|
|
114
|
+
|
|
115
|
+
/** Retry schedule for a REFUSED connect (nothing listening on the port yet). The
|
|
116
|
+
* combiner's launcher, `sharedserver use`, returns once the process is launched,
|
|
117
|
+
* not once it listens, and a combiner another client launched a moment ago may
|
|
118
|
+
* still be booting. So a refused connect right after an attach is expected, and
|
|
119
|
+
* this retry is what waits for the port. Backoff doubles from `firstMs` to `maxMs`
|
|
120
|
+
* within `budgetMs` until the first successful connect; after that, a refused
|
|
121
|
+
* connect means the combiner went away (a restart, or it's down), so callers (tool
|
|
122
|
+
* calls, footer refreshes) wait only `reconnectBudgetMs`: enough to ride out a
|
|
123
|
+
* restart, short enough not to stall when it's down. Other errors (timeouts, HTTP
|
|
124
|
+
* errors) are not retried here. */
|
|
125
|
+
export type ConnectRetry = { budgetMs: number; reconnectBudgetMs: number; firstMs: number; maxMs: number }
|
|
126
|
+
const DEFAULT_CONNECT_RETRY: ConnectRetry = { budgetMs: 15_000, reconnectBudgetMs: 3_000, firstMs: 100, maxMs: 1_000 }
|
|
127
|
+
|
|
128
|
+
/** Staying connected on its own (setAutoReconnect): after a dropped connection,
|
|
129
|
+
* reconnect after `dropMs`, doubling to `dropMaxMs` while connections keep dropping
|
|
130
|
+
* within `stableMs` of connecting (a combiner that accepts and then closes must not
|
|
131
|
+
* be hammered). After a failed connect, try again in the background after
|
|
132
|
+
* `failMs`, doubling to `failMaxMs`, until it succeeds or the connection is closed. */
|
|
133
|
+
export type AutoReconnect = { dropMs: number; dropMaxMs: number; stableMs: number; failMs: number; failMaxMs: number }
|
|
134
|
+
const DEFAULT_AUTO_RECONNECT: AutoReconnect = {
|
|
135
|
+
dropMs: 500,
|
|
136
|
+
dropMaxMs: 30_000,
|
|
137
|
+
stableMs: 10_000,
|
|
138
|
+
failMs: 1_000,
|
|
139
|
+
failMaxMs: 10_000,
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** The liveness check's answer (NativeCombinerConnection.setLivenessCheck). */
|
|
143
|
+
export type Liveness = "alive" | "gone" | "relaunched"
|
|
144
|
+
|
|
145
|
+
/** True for a connect refused at the socket (Node's fetch: TypeError "fetch failed"
|
|
146
|
+
* whose cause chain carries code ECONNREFUSED). */
|
|
147
|
+
export function isConnectionRefused(e: unknown): boolean {
|
|
148
|
+
let cur: unknown = e
|
|
149
|
+
for (let depth = 0; depth < 5 && typeof cur === "object" && cur !== null; depth++) {
|
|
150
|
+
if ((cur as { code?: unknown }).code === "ECONNREFUSED") return true
|
|
151
|
+
cur = (cur as { cause?: unknown }).cause
|
|
152
|
+
}
|
|
153
|
+
return false
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/** setTimeout as a promise, unref'd so a pending retry never holds pi open. */
|
|
157
|
+
function sleep(ms: number): Promise<void> {
|
|
158
|
+
return new Promise((resolve) => {
|
|
159
|
+
const t = setTimeout(resolve, ms)
|
|
160
|
+
t.unref?.()
|
|
161
|
+
})
|
|
162
|
+
}
|
|
114
163
|
const LIST_CACHE_MS = 5_000
|
|
115
164
|
|
|
116
165
|
function isRecord(v: unknown): v is Record<string, unknown> {
|
|
@@ -153,11 +202,98 @@ export class NativeCombinerConnection implements CombinerConnection {
|
|
|
153
202
|
* StreamableHttpTransport). Injection lets tests drive the connection over an
|
|
154
203
|
* in-memory pair instead of HTTP. */
|
|
155
204
|
private readonly transportFactory: ((url: URL) => McpTransport) | undefined
|
|
156
|
-
|
|
157
|
-
|
|
205
|
+
private readonly retry: ConnectRetry
|
|
206
|
+
/** Resolved once the combiner has been attached (launched, or found running).
|
|
207
|
+
* Every connect waits on it, so a connect never races the launch. Unset when
|
|
208
|
+
* someone else owns the combiner (host-owned / unmanaged): nothing to wait for. */
|
|
209
|
+
private startGate: Promise<void> | undefined
|
|
210
|
+
/** Between refused-connect retries (CombinerProcess.onRefused): "alive" keeps
|
|
211
|
+
* retrying; "gone" stops now instead of waiting out the budget; "relaunched"
|
|
212
|
+
* (a dead combiner was respawned) keeps retrying with the cold-start budget. */
|
|
213
|
+
private livenessCheck: (() => Promise<Liveness>) | undefined
|
|
214
|
+
/** Set by the first successful connect; switches refused-connect retries to the
|
|
215
|
+
* short reconnect budget (see ConnectRetry). */
|
|
216
|
+
private everConnected = false
|
|
217
|
+
/** Auto-reconnect (see AutoReconnect): off until setAutoReconnect(); `closed`
|
|
218
|
+
* (close()) stops it for good. */
|
|
219
|
+
private auto: AutoReconnect | undefined
|
|
220
|
+
private closed = false
|
|
221
|
+
private reconnectTimer: ReturnType<typeof setTimeout> | undefined
|
|
222
|
+
private dropDelayMs = 0
|
|
223
|
+
private failDelayMs = 0
|
|
224
|
+
private connectedAt = 0
|
|
225
|
+
/** Consecutive failed connects: only the first of an outage is reported. */
|
|
226
|
+
private failStreak = 0
|
|
227
|
+
|
|
228
|
+
constructor(
|
|
229
|
+
conn: ResolvedConnection,
|
|
230
|
+
log: LogFn,
|
|
231
|
+
opts?: { transportFactory?: (url: URL) => McpTransport; retry?: ConnectRetry; autoReconnect?: AutoReconnect },
|
|
232
|
+
) {
|
|
158
233
|
this.conn = conn
|
|
159
234
|
this.log = log
|
|
160
235
|
this.transportFactory = opts?.transportFactory
|
|
236
|
+
this.retry = opts?.retry ?? DEFAULT_CONNECT_RETRY
|
|
237
|
+
this.autoDefaults = opts?.autoReconnect ?? DEFAULT_AUTO_RECONNECT
|
|
238
|
+
}
|
|
239
|
+
private readonly autoDefaults: AutoReconnect
|
|
240
|
+
|
|
241
|
+
/** Keep this connection up on its own: reconnect after a drop, and retry a failed
|
|
242
|
+
* connect in the background (see AutoReconnect). index.ts turns it on per
|
|
243
|
+
* extension instance; close() turns it off for good. */
|
|
244
|
+
setAutoReconnect(on: boolean): void {
|
|
245
|
+
this.auto = on ? this.autoDefaults : undefined
|
|
246
|
+
if (!on) this.clearReconnectTimer()
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/** Reconnect now, e.g. because the combiner process went away (CombinerProcess's
|
|
250
|
+
* watch). A connect already in progress is left alone: its refused-connect
|
|
251
|
+
* retry asks the same questions, and a reset would throw away its budget. */
|
|
252
|
+
reconnect(reason: string): void {
|
|
253
|
+
if (this.closed || this.state === "connecting") return
|
|
254
|
+
void this.reset(reason).then(() => {
|
|
255
|
+
if (!this.closed) void this.ensureConnected().catch(() => undefined)
|
|
256
|
+
})
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
/** Undo close() for a host that reuses the extension instance across sessions
|
|
260
|
+
* (pi 1.6 doesn't; harmless when nothing was closed). */
|
|
261
|
+
reopen(): void {
|
|
262
|
+
this.closed = false
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
/** Session shutdown / reload teardown: stop auto-reconnect for good and drop the
|
|
266
|
+
* connection. Nothing reconnects this instance afterwards (until reopen()). */
|
|
267
|
+
async close(reason: string): Promise<void> {
|
|
268
|
+
this.closed = true
|
|
269
|
+
this.auto = undefined
|
|
270
|
+
this.clearReconnectTimer()
|
|
271
|
+
await this.reset(reason)
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
private clearReconnectTimer(): void {
|
|
275
|
+
if (this.reconnectTimer) clearTimeout(this.reconnectTimer)
|
|
276
|
+
this.reconnectTimer = undefined
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/** Schedule a background reconnect after `delayMs` (one at a time; unref'd). */
|
|
280
|
+
private scheduleReconnect(delayMs: number): void {
|
|
281
|
+
if (!this.auto || this.closed || this.reconnectTimer) return
|
|
282
|
+
this.reconnectTimer = setTimeout(() => {
|
|
283
|
+
this.reconnectTimer = undefined
|
|
284
|
+
if (this.auto && !this.closed) void this.ensureConnected().catch(() => undefined)
|
|
285
|
+
}, delayMs)
|
|
286
|
+
this.reconnectTimer.unref?.()
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/** Make every connect wait for `gate` (the manage half's attach). */
|
|
290
|
+
setStartGate(gate: Promise<void>): void {
|
|
291
|
+
this.startGate = gate
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/** Install the between-retries liveness check (see livenessCheck). */
|
|
295
|
+
setLivenessCheck(check: () => Promise<Liveness>): void {
|
|
296
|
+
this.livenessCheck = check
|
|
161
297
|
}
|
|
162
298
|
|
|
163
299
|
setHooks(hooks: ConnectionHooks): void {
|
|
@@ -184,6 +320,11 @@ export class NativeCombinerConnection implements CombinerConnection {
|
|
|
184
320
|
return false
|
|
185
321
|
}
|
|
186
322
|
this.conn = conn
|
|
323
|
+
// A different combiner: the first-connect budget and a fresh outage record.
|
|
324
|
+
this.everConnected = false
|
|
325
|
+
this.failStreak = 0
|
|
326
|
+
this.failDelayMs = 0
|
|
327
|
+
this.dropDelayMs = 0
|
|
187
328
|
void this.reset("connection rebound (session config changed)")
|
|
188
329
|
return true
|
|
189
330
|
}
|
|
@@ -195,6 +336,52 @@ export class NativeCombinerConnection implements CombinerConnection {
|
|
|
195
336
|
void this.reset("token changed")
|
|
196
337
|
}
|
|
197
338
|
|
|
339
|
+
/** Wait for the attach, then connect, retrying a REFUSED connect on the
|
|
340
|
+
* ConnectRetry schedule. Stops retrying when the budget is spent, a reset
|
|
341
|
+
* supersedes this connect, or the liveness check says the combiner is gone;
|
|
342
|
+
* the last error is rethrown for ensureConnected's failure path. */
|
|
343
|
+
private async connectWithRetry(attempt: () => Promise<McpClient>, genAtStart: number): Promise<McpClient> {
|
|
344
|
+
if (this.startGate) await this.startGate
|
|
345
|
+
// A reset while we waited at the gate (token or config changed) makes this
|
|
346
|
+
// connect stale: don't open a session for the old token.
|
|
347
|
+
if (this.generation !== genAtStart) throw new Error("connect superseded by a connection reset (token/config changed)")
|
|
348
|
+
let deadline = Date.now() + (this.everConnected ? this.retry.reconnectBudgetMs : this.retry.budgetMs)
|
|
349
|
+
let extended = false
|
|
350
|
+
let delay = this.retry.firstMs
|
|
351
|
+
let announced = false
|
|
352
|
+
for (;;) {
|
|
353
|
+
try {
|
|
354
|
+
const client = await attempt()
|
|
355
|
+
this.everConnected = true
|
|
356
|
+
this.connectedAt = Date.now()
|
|
357
|
+
this.failDelayMs = 0
|
|
358
|
+
if (this.failStreak > 0) this.log("info", `combiner reachable again at ${this.conn.baseUrl}`)
|
|
359
|
+
this.failStreak = 0
|
|
360
|
+
return client
|
|
361
|
+
} catch (e) {
|
|
362
|
+
if (!isConnectionRefused(e) || this.generation !== genAtStart) throw e
|
|
363
|
+
// A failing check counts as alive: it must never stop a retry that would work.
|
|
364
|
+
const liveness = this.livenessCheck ? await this.livenessCheck().catch((): Liveness => "alive") : "alive"
|
|
365
|
+
if (liveness === "gone") throw e
|
|
366
|
+
if (liveness === "relaunched" && !extended) {
|
|
367
|
+
deadline = Date.now() + this.retry.budgetMs // a cold start again
|
|
368
|
+
extended = true
|
|
369
|
+
}
|
|
370
|
+
if (Date.now() + delay > deadline) throw e
|
|
371
|
+
if (!announced && this.failStreak === 0) {
|
|
372
|
+
announced = true
|
|
373
|
+
this.log(
|
|
374
|
+
"info",
|
|
375
|
+
`combiner not listening at ${this.conn.baseUrl}; retrying for up to ${Math.round((deadline - Date.now()) / 1000)} s`,
|
|
376
|
+
)
|
|
377
|
+
}
|
|
378
|
+
await sleep(delay)
|
|
379
|
+
if (this.generation !== genAtStart) throw e
|
|
380
|
+
delay = Math.min(delay * 2, this.retry.maxMs)
|
|
381
|
+
}
|
|
382
|
+
}
|
|
383
|
+
}
|
|
384
|
+
|
|
198
385
|
/** Drop the connection + caches (session reset / shutdown). Never throws. */
|
|
199
386
|
async reset(reason: string): Promise<void> {
|
|
200
387
|
this.generation++
|
|
@@ -220,6 +407,7 @@ export class NativeCombinerConnection implements CombinerConnection {
|
|
|
220
407
|
/** Connect (idempotent, single-flight). THE elicitation-relevant site: the
|
|
221
408
|
* capability + request handler live HERE, on a client we own. */
|
|
222
409
|
async ensureConnected(): Promise<McpClient> {
|
|
410
|
+
if (this.closed) throw new Error("the combiner connection is closed (session ended)")
|
|
223
411
|
if (this.client) return this.client
|
|
224
412
|
if (this.connecting) return this.connecting
|
|
225
413
|
|
|
@@ -236,7 +424,7 @@ export class NativeCombinerConnection implements CombinerConnection {
|
|
|
236
424
|
|
|
237
425
|
this.state = "connecting"
|
|
238
426
|
const genAtStart = this.generation
|
|
239
|
-
const
|
|
427
|
+
const attempt = async (): Promise<McpClient> => {
|
|
240
428
|
const client = new McpClient({
|
|
241
429
|
name: CLIENT_INFO.name,
|
|
242
430
|
version: CLIENT_INFO.version,
|
|
@@ -299,6 +487,15 @@ export class NativeCombinerConnection implements CombinerConnection {
|
|
|
299
487
|
this.client = undefined
|
|
300
488
|
this.state = "disconnected"
|
|
301
489
|
this.hooks.onStateChange?.(this.state)
|
|
490
|
+
// A genuine drop (a reset clears this.client first, so it never gets
|
|
491
|
+
// here): reconnect on our own, backing off while drops come quickly.
|
|
492
|
+
if (this.auto) {
|
|
493
|
+
const quick = Date.now() - this.connectedAt < this.auto.stableMs
|
|
494
|
+
this.dropDelayMs = quick && this.dropDelayMs
|
|
495
|
+
? Math.min(this.dropDelayMs * 2, this.auto.dropMaxMs)
|
|
496
|
+
: this.auto.dropMs
|
|
497
|
+
this.scheduleReconnect(this.dropDelayMs)
|
|
498
|
+
}
|
|
302
499
|
}
|
|
303
500
|
})
|
|
304
501
|
|
|
@@ -317,12 +514,16 @@ export class NativeCombinerConnection implements CombinerConnection {
|
|
|
317
514
|
try {
|
|
318
515
|
await Promise.race([
|
|
319
516
|
settle,
|
|
320
|
-
new Promise((_, reject) =>
|
|
321
|
-
|
|
517
|
+
new Promise((_, reject) => {
|
|
518
|
+
// Stored so `finally` clears it, and unref'd: a pending
|
|
519
|
+
// timeout must never keep pi's process alive (it held
|
|
520
|
+
// pi open for 8s after every connect when unstored).
|
|
521
|
+
timer = setTimeout(
|
|
322
522
|
() => reject(new Error(`connect timeout after ${CONNECT_TIMEOUT_MS}ms`)),
|
|
323
523
|
CONNECT_TIMEOUT_MS,
|
|
324
|
-
)
|
|
325
|
-
|
|
524
|
+
)
|
|
525
|
+
timer.unref?.()
|
|
526
|
+
}),
|
|
326
527
|
])
|
|
327
528
|
} catch (e) {
|
|
328
529
|
// The client may STILL complete its connect after this failure (the
|
|
@@ -362,7 +563,8 @@ export class NativeCombinerConnection implements CombinerConnection {
|
|
|
362
563
|
}
|
|
363
564
|
this.hooks.onStateChange?.(this.state)
|
|
364
565
|
return client
|
|
365
|
-
}
|
|
566
|
+
}
|
|
567
|
+
const connectPromise = this.connectWithRetry(attempt, genAtStart)
|
|
366
568
|
this.connecting = connectPromise
|
|
367
569
|
|
|
368
570
|
try {
|
|
@@ -372,8 +574,16 @@ export class NativeCombinerConnection implements CombinerConnection {
|
|
|
372
574
|
if (!superseded) {
|
|
373
575
|
this.state = "failed"
|
|
374
576
|
this.lastError = e instanceof Error ? e.message : String(e)
|
|
375
|
-
this.
|
|
577
|
+
this.failStreak++
|
|
578
|
+
// Once per outage: background retries must not repeat the warning.
|
|
579
|
+
if (this.failStreak === 1) this.log("warn", `combiner connect failed (${this.lastError})`)
|
|
376
580
|
this.hooks.onStateChange?.(this.state)
|
|
581
|
+
if (this.auto) {
|
|
582
|
+
this.failDelayMs = this.failDelayMs
|
|
583
|
+
? Math.min(this.failDelayMs * 2, this.auto.failMaxMs)
|
|
584
|
+
: this.auto.failMs
|
|
585
|
+
this.scheduleReconnect(this.failDelayMs)
|
|
586
|
+
}
|
|
377
587
|
}
|
|
378
588
|
throw superseded
|
|
379
589
|
? e
|
package/src/native/index.ts
CHANGED
|
@@ -40,9 +40,70 @@ export type NativeActivationOptions = {
|
|
|
40
40
|
/** Cap on guarded tool-result text before spill-to-file (maxResultChars setting);
|
|
41
41
|
* forwarded to the tool surface and the interactive read_* tools. */
|
|
42
42
|
maxResultChars?: number
|
|
43
|
+
/** Tool-registration progress for the current pass (registered, total); see
|
|
44
|
+
* NativeToolSurfaceOptions.onProgress. index.ts drives the footer from it. */
|
|
45
|
+
onToolProgress?: (done: number, total: number) => void
|
|
43
46
|
log: (level: "info" | "warn" | "error", message: string) => void
|
|
44
47
|
}
|
|
45
48
|
|
|
49
|
+
/** The native surface's lifecycle, as returned by activateNativeMode. */
|
|
50
|
+
export type NativeSurface = {
|
|
51
|
+
/** Start a registration pass against the current catalog (supersedes one in flight). */
|
|
52
|
+
run(): void
|
|
53
|
+
/** True while a tool registration pass is running (connecting, listing, or
|
|
54
|
+
* registering). */
|
|
55
|
+
busy(): boolean
|
|
56
|
+
/** Resolves when no tool pass is running: the newest pass has ended, however it
|
|
57
|
+
* ended (finished, failed, stopped). Never rejects. */
|
|
58
|
+
settled(): Promise<void>
|
|
59
|
+
/** Stop: in-flight passes end at their next check; run() becomes a no-op. */
|
|
60
|
+
dispose(): void
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** How long a turn waits for tool registration before starting with what it has.
|
|
64
|
+
* Covers the worst cold start: the connect retry (15 s budget) plus a full
|
|
65
|
+
* registration pass (~10 s for ~1,000 tools). */
|
|
66
|
+
export const TURN_WAIT_MS = 30_000
|
|
67
|
+
|
|
68
|
+
/** Wait until `surface` has no registration pass running, at most `timeoutMs`, or
|
|
69
|
+
* until `signal` aborts or `onInterrupt` fires (it receives a callback that ends
|
|
70
|
+
* the wait and returns an unsubscribe; index.ts wires it to Esc / Ctrl+C / Ctrl+D,
|
|
71
|
+
* since pi has no abort signal at before_agent_start). Never rejects; the timer is
|
|
72
|
+
* cleared (and unref'd) and the listeners removed, so a wait that ends early never
|
|
73
|
+
* holds pi open. */
|
|
74
|
+
export async function waitForRegistration(
|
|
75
|
+
surface: Pick<NativeSurface, "busy" | "settled">,
|
|
76
|
+
opts: { timeoutMs?: number; signal?: AbortSignal; onInterrupt?: (interrupt: () => void) => () => void } = {},
|
|
77
|
+
): Promise<"idle" | "settled" | "timeout" | "aborted"> {
|
|
78
|
+
if (!surface.busy()) return "idle"
|
|
79
|
+
if (opts.signal?.aborted) return "aborted"
|
|
80
|
+
let timer: ReturnType<typeof setTimeout> | undefined
|
|
81
|
+
let onAbort: (() => void) | undefined
|
|
82
|
+
let unsubscribe: (() => void) | undefined
|
|
83
|
+
try {
|
|
84
|
+
return await Promise.race([
|
|
85
|
+
surface.settled().then(() => "settled" as const),
|
|
86
|
+
new Promise<"timeout">((resolve) => {
|
|
87
|
+
timer = setTimeout(() => resolve("timeout"), opts.timeoutMs ?? TURN_WAIT_MS)
|
|
88
|
+
timer.unref?.()
|
|
89
|
+
}),
|
|
90
|
+
new Promise<"aborted">((resolve) => {
|
|
91
|
+
onAbort = () => resolve("aborted")
|
|
92
|
+
opts.signal?.addEventListener("abort", onAbort, { once: true })
|
|
93
|
+
try {
|
|
94
|
+
unsubscribe = opts.onInterrupt?.(onAbort)
|
|
95
|
+
} catch {
|
|
96
|
+
// an interrupt source that fails just isn't one
|
|
97
|
+
}
|
|
98
|
+
}),
|
|
99
|
+
])
|
|
100
|
+
} finally {
|
|
101
|
+
if (timer) clearTimeout(timer)
|
|
102
|
+
if (onAbort) opts.signal?.removeEventListener("abort", onAbort)
|
|
103
|
+
unsubscribe?.()
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
|
|
46
107
|
/** Register the declared tool surface + interactive-resource read_* tools + the
|
|
47
108
|
* list_changed re-registration handler. Called once at session_start; the
|
|
48
109
|
* list_changed hook re-syncs both surfaces on the same names. One shared
|
|
@@ -51,39 +112,73 @@ export type NativeActivationOptions = {
|
|
|
51
112
|
export function activateNativeMode(
|
|
52
113
|
pi: ExtensionAPI,
|
|
53
114
|
opts: NativeActivationOptions,
|
|
54
|
-
):
|
|
115
|
+
): NativeSurface {
|
|
55
116
|
let active = true
|
|
56
117
|
const toolState: NativeToolSurfaceState = { names: new Set(), signatures: new Map() }
|
|
57
118
|
// Cross-pass memory for the read_* tools (skip re-registration of unchanged
|
|
58
119
|
// names — pi.registerTool replaces-by-name with a warning).
|
|
59
120
|
const resourceRegistered = new Set<string>()
|
|
121
|
+
// Only the NEWEST tool pass may change toolState. activateNativeTools yields
|
|
122
|
+
// between registration slices, so passes can overlap in time; each run() bumps
|
|
123
|
+
// `generation`, and a pass whose generation is stale stops at its next check.
|
|
124
|
+
// That is enough on its own: a pass checks shouldContinue() after every await
|
|
125
|
+
// (listTools and each slice yield), and every state change happens synchronously
|
|
126
|
+
// between those checks, so a superseded pass never touches state again.
|
|
127
|
+
// index.ts calls dispose() at session_shutdown and on reload teardown, which
|
|
128
|
+
// stops a pass the same way before pi retires the session's extension API.
|
|
129
|
+
let generation = 0
|
|
130
|
+
// The newest tool pass, until it ends; undefined when no pass is running. A
|
|
131
|
+
// superseded pass doesn't count: settled() follows whichever pass is newest.
|
|
132
|
+
let latest: Promise<void> | undefined
|
|
60
133
|
const run = () => {
|
|
61
134
|
if (!active) return
|
|
62
|
-
|
|
135
|
+
const mine = ++generation
|
|
136
|
+
const current = () => active && generation === mine
|
|
137
|
+
// A pass that fails after this surface was disposed or superseded (pi's
|
|
138
|
+
// registerTool throws once the session's extension API is retired) is not
|
|
139
|
+
// news: only the newest live pass reports failures.
|
|
140
|
+
const failed = (what: string) => (e: unknown) => {
|
|
141
|
+
if (current()) opts.log("warn", `${what} failed: ${e instanceof Error ? e.message : String(e)}`)
|
|
142
|
+
}
|
|
143
|
+
const tools = activateNativeTools(pi, {
|
|
63
144
|
connection: opts.connection,
|
|
64
145
|
serverFilter: opts.serverFilter,
|
|
65
146
|
directSpec: opts.directSpec,
|
|
66
147
|
state: toolState,
|
|
67
148
|
warnLargeDirectExposure: opts.warnLargeDirectExposure,
|
|
68
149
|
maxResultChars: opts.maxResultChars,
|
|
150
|
+
shouldContinue: current,
|
|
151
|
+
onProgress: opts.onToolProgress,
|
|
69
152
|
log: opts.log,
|
|
70
|
-
}).
|
|
71
|
-
|
|
153
|
+
}).then(() => undefined, failed("native tool surface"))
|
|
154
|
+
const resources =
|
|
155
|
+
opts.exposeResources !== false
|
|
156
|
+
? activateNativeResources(
|
|
157
|
+
pi,
|
|
158
|
+
{
|
|
159
|
+
connection: opts.connection,
|
|
160
|
+
serverFilter: opts.serverFilter,
|
|
161
|
+
directSpec: opts.directSpec,
|
|
162
|
+
uiAutoOpen: opts.uiAutoOpen,
|
|
163
|
+
maxResultChars: opts.maxResultChars,
|
|
164
|
+
shouldContinue: current,
|
|
165
|
+
log: opts.log,
|
|
166
|
+
},
|
|
167
|
+
resourceRegistered,
|
|
168
|
+
).then(() => undefined, failed("native resource surface"))
|
|
169
|
+
: Promise.resolve()
|
|
170
|
+
// The pass is both surfaces: a turn that waits on settled() gets the read_*
|
|
171
|
+
// tools too. The newest pass always ends with a "done" report, even when it
|
|
172
|
+
// had nothing to register or failed, so a "registering" left by a superseded
|
|
173
|
+
// pass never sticks in the footer.
|
|
174
|
+
const pass: Promise<void> = Promise.all([tools, resources]).then(
|
|
175
|
+
() => {
|
|
176
|
+
// Clear first: a throwing progress hook must not leave busy() true.
|
|
177
|
+
if (latest === pass) latest = undefined
|
|
178
|
+
if (current()) opts.onToolProgress?.(0, 0)
|
|
179
|
+
},
|
|
72
180
|
)
|
|
73
|
-
|
|
74
|
-
void activateNativeResources(
|
|
75
|
-
pi,
|
|
76
|
-
{
|
|
77
|
-
connection: opts.connection,
|
|
78
|
-
serverFilter: opts.serverFilter,
|
|
79
|
-
directSpec: opts.directSpec,
|
|
80
|
-
uiAutoOpen: opts.uiAutoOpen,
|
|
81
|
-
maxResultChars: opts.maxResultChars,
|
|
82
|
-
log: opts.log,
|
|
83
|
-
},
|
|
84
|
-
resourceRegistered,
|
|
85
|
-
).catch((e) => opts.log("warn", `native resource surface failed: ${e instanceof Error ? e.message : String(e)}`))
|
|
86
|
-
}
|
|
181
|
+
latest = pass
|
|
87
182
|
}
|
|
88
183
|
// The FIRST run is the caller's to schedule: the grouping token only exists
|
|
89
184
|
// after session_start (the connection refuses to connect without it), so a
|
|
@@ -95,6 +190,12 @@ export function activateNativeMode(
|
|
|
95
190
|
// ONE hook set, index.ts's.
|
|
96
191
|
return {
|
|
97
192
|
run,
|
|
193
|
+
busy: () => latest !== undefined,
|
|
194
|
+
async settled() {
|
|
195
|
+
// A pass that ends because a newer one superseded it hands over: keep
|
|
196
|
+
// waiting until no pass is running.
|
|
197
|
+
while (latest) await latest
|
|
198
|
+
},
|
|
98
199
|
dispose() {
|
|
99
200
|
active = false
|
|
100
201
|
},
|
package/src/native/resources.ts
CHANGED
|
@@ -28,6 +28,9 @@ import type { ServerFilter } from "../client/config-ladder.js"
|
|
|
28
28
|
|
|
29
29
|
export type NativeResourceOptions = {
|
|
30
30
|
connection: NativeCombinerConnection
|
|
31
|
+
/** Checked after listing: false means this pass should stop (see
|
|
32
|
+
* NativeToolSurfaceOptions.shouldContinue). */
|
|
33
|
+
shouldContinue?: () => boolean
|
|
31
34
|
/** Per-project server filter, same semantics as legacy filterResources; a getter
|
|
32
35
|
* resolves per call (worktrees/project switches re-resolve session config). */
|
|
33
36
|
serverFilter?: ServerFilter | (() => ServerFilter | undefined)
|
|
@@ -136,9 +139,13 @@ export async function activateNativeResources(
|
|
|
136
139
|
try {
|
|
137
140
|
resources = filterInteractiveResources(await opts.connection.listResources(true), resolveFilter(opts.serverFilter))
|
|
138
141
|
} catch (e) {
|
|
139
|
-
|
|
142
|
+
// A pass stopped by dispose() or a newer pass fails here harmlessly
|
|
143
|
+
// (e.g. "connect superseded"): not news.
|
|
144
|
+
if (!opts.shouldContinue || opts.shouldContinue())
|
|
145
|
+
opts.log("warn", `interactive resource discovery failed (${e instanceof Error ? e.message : String(e)})`)
|
|
140
146
|
return []
|
|
141
147
|
}
|
|
148
|
+
if (opts.shouldContinue && !opts.shouldContinue()) return []
|
|
142
149
|
const added: string[] = []
|
|
143
150
|
for (const resource of resources) {
|
|
144
151
|
const toolName = `read_${resourceNameToToolName(resource.name ?? resource.uri)}`
|
|
@@ -60,9 +60,35 @@ export type NativeToolSurfaceOptions = {
|
|
|
60
60
|
/** Warn when the direct-exposure set grows large (every declared schema rides in
|
|
61
61
|
* every request). Settings kill-switch: warnLargeDirectExposure (default true). */
|
|
62
62
|
warnLargeDirectExposure?: boolean
|
|
63
|
+
/** Checked after every yield between registration slices: false means this
|
|
64
|
+
* pass should stop (the session ended, or a newer pass superseded it). pi's
|
|
65
|
+
* registerTool throws once the extension API is invalidated (/new, /resume,
|
|
66
|
+
* /reload), and a superseded pass would only redo work the next one does. */
|
|
67
|
+
shouldContinue?: () => boolean
|
|
68
|
+
/** Registration progress for this pass: (changes applied so far, total changes;
|
|
69
|
+
* a change is a registration or a removal).
|
|
70
|
+
* Called after each slice; not called when the pass has nothing to register.
|
|
71
|
+
* done >= total means finished (activateNativeMode also reports (0, 0) when its
|
|
72
|
+
* newest pass ends, however it ends). */
|
|
73
|
+
onProgress?: (done: number, total: number) => void
|
|
63
74
|
log: (level: "info" | "warn" | "error", message: string) => void
|
|
64
75
|
}
|
|
65
76
|
|
|
77
|
+
/** Main-thread time a registration slice may use before yielding to the event
|
|
78
|
+
* loop. Every pi.registerTool rebuilds pi's whole tool registry, and with codemode
|
|
79
|
+
* active that re-renders a declaration for every codemode tool registered so far.
|
|
80
|
+
* So a pass is O(n²) and the per-call cost grows as the pass goes (from ~2 ms to
|
|
81
|
+
* ~12–18 ms at ~1,000 tools). A fixed tool COUNT per slice made the last slices
|
|
82
|
+
* about six times longer than the first; a time budget keeps every slice about
|
|
83
|
+
* the same length. Registering a 1,000-tool catalog in one go froze typing for
|
|
84
|
+
* ~10 s. A slice always registers at least one tool, so a call slower than the
|
|
85
|
+
* budget still makes progress. */
|
|
86
|
+
export const REGISTER_SLICE_MS = 50
|
|
87
|
+
|
|
88
|
+
/** Yield to the event loop with a MACROTASK. A microtask (await Promise.resolve())
|
|
89
|
+
* runs before pi reads stdin, so typing would stay frozen across the whole pass. */
|
|
90
|
+
const yieldToEventLoop = (): Promise<void> => new Promise((resolve) => setImmediate(resolve))
|
|
91
|
+
|
|
66
92
|
/** Registration memory across passes: currently-declared names + each tool's schema
|
|
67
93
|
* signature, so a changed schema re-registers and an unchanged one doesn't (pi's
|
|
68
94
|
* re-register = replace-with-warning; skipping unchanged declarations avoids the
|
|
@@ -185,17 +211,28 @@ function removedToolDefinition(name: string): ToolDefinition {
|
|
|
185
211
|
/** Register the combiner's tools natively, DIFFING against `state` (which the caller
|
|
186
212
|
* reuses across passes): unchanged declarations are skipped (pi.registerTool
|
|
187
213
|
* replaces-by-name with a warning — churn on every list_changed would spam), changed
|
|
188
|
-
* schemas re-register, and removed tools are re-registered hidden.
|
|
189
|
-
*
|
|
214
|
+
* schemas re-register, and removed tools are re-registered hidden.
|
|
215
|
+
*
|
|
216
|
+
* Registration runs in time-boxed slices (REGISTER_SLICE_MS) with an event-loop
|
|
217
|
+
* yield between them, so a large catalog never holds pi's main thread for long. `state` is updated per registerTool, never ahead of it, so a
|
|
218
|
+
* pass that stops early (shouldContinue() false) leaves state matching exactly what
|
|
219
|
+
* pi holds and the next pass's diff resumes from there. Two passes over the same
|
|
220
|
+
* state may overlap in time only if the older one's shouldContinue() turns false
|
|
221
|
+
* once the newer starts (native/index.ts's generation check); every state change
|
|
222
|
+
* happens between those checks. Returns the names currently active (for
|
|
223
|
+
* status/panel surfaces). */
|
|
190
224
|
export async function activateNativeTools(pi: ExtensionAPI, opts: NativeToolSurfaceOptions): Promise<string[]> {
|
|
191
225
|
const state: NativeToolSurfaceState = opts.state ?? { names: new Set(), signatures: new Map() }
|
|
226
|
+
const keepGoing = opts.shouldContinue ?? (() => true)
|
|
192
227
|
const tools = applyServerFilter(await opts.connection.listTools(true), resolveFilter(opts.serverFilter))
|
|
228
|
+
if (!keepGoing()) return [...state.names]
|
|
193
229
|
const allowlist = Array.isArray(resolveDirectSpec(opts.directSpec)) ? (resolveDirectSpec(opts.directSpec) as string[]) : []
|
|
194
230
|
const reserved: ReadonlySet<string> = new Set(RESERVED_TOOL_NAMES)
|
|
195
231
|
|
|
232
|
+
// Diff first, register second: the slices then hold only real changes.
|
|
196
233
|
const currentNames = new Set(tools.map((t) => t.name))
|
|
197
234
|
const directNames: string[] = []
|
|
198
|
-
|
|
235
|
+
const toRegister: Array<{ def: ToolDefinition; sig: string | null }> = []
|
|
199
236
|
for (const sum of tools) {
|
|
200
237
|
if (reserved.has(sum.name)) {
|
|
201
238
|
opts.log("warn", `skipping combiner tool "${sum.name}" — collides with a reserved name`)
|
|
@@ -209,24 +246,49 @@ export async function activateNativeTools(pi: ExtensionAPI, opts: NativeToolSurf
|
|
|
209
246
|
// Diff: skip the re-register when the schema signature is unchanged (pi keeps
|
|
210
247
|
// the existing declaration; re-registering would log its warning for nothing).
|
|
211
248
|
const sig = renderSchemaSignature(sum.inputSchema)
|
|
212
|
-
if (state.names.has(sum.name) && state.signatures.get(sum.name) === sig)
|
|
213
|
-
continue
|
|
214
|
-
}
|
|
215
|
-
pi.registerTool(toNativeTool(sum, opts.connection, exposure, opts.maxResultChars))
|
|
216
|
-
state.signatures.set(sum.name, sig)
|
|
217
|
-
state.names.add(sum.name)
|
|
218
|
-
fresh++
|
|
249
|
+
if (state.names.has(sum.name) && state.signatures.get(sum.name) === sig) continue
|
|
219
250
|
if (exposure === "direct") directNames.push(sum.name)
|
|
251
|
+
toRegister.push({ def: toNativeTool(sum, opts.connection, exposure, opts.maxResultChars), sig })
|
|
220
252
|
}
|
|
221
|
-
|
|
222
|
-
//
|
|
253
|
+
|
|
254
|
+
// One queue, removals first: a removal is a hidden re-register (pi has no
|
|
255
|
+
// unregister; a hidden re-register at the same name retires the declaration).
|
|
256
|
+
// It replaces the registry entry rather than deleting it, so it costs a full
|
|
257
|
+
// rebuild like any registration, and a large removal (a disabled server, a
|
|
258
|
+
// narrower filter) must be time-boxed too.
|
|
259
|
+
type Op = { kind: "remove"; name: string } | { kind: "register"; def: ToolDefinition; sig: string | null }
|
|
260
|
+
const ops: Op[] = [
|
|
261
|
+
...[...state.names].filter((n) => !currentNames.has(n)).map((name): Op => ({ kind: "remove", name })),
|
|
262
|
+
...toRegister.map(({ def, sig }): Op => ({ kind: "register", def, sig })),
|
|
263
|
+
]
|
|
264
|
+
let done = 0
|
|
265
|
+
let fresh = 0
|
|
223
266
|
let removed = 0
|
|
224
|
-
|
|
225
|
-
if (
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
267
|
+
while (done < ops.length) {
|
|
268
|
+
if (done > 0) {
|
|
269
|
+
await yieldToEventLoop()
|
|
270
|
+
if (!keepGoing()) {
|
|
271
|
+
opts.log("info", `native tool surface: pass stopped after ${done}/${ops.length} (superseded or session ended)`)
|
|
272
|
+
return [...state.names]
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
const sliceStart = performance.now()
|
|
276
|
+
do {
|
|
277
|
+
const op = ops[done]
|
|
278
|
+
if (op.kind === "remove") {
|
|
279
|
+
pi.registerTool(removedToolDefinition(op.name))
|
|
280
|
+
state.names.delete(op.name)
|
|
281
|
+
state.signatures.delete(op.name)
|
|
282
|
+
removed++
|
|
283
|
+
} else {
|
|
284
|
+
pi.registerTool(op.def)
|
|
285
|
+
state.signatures.set(op.def.name, op.sig)
|
|
286
|
+
state.names.add(op.def.name)
|
|
287
|
+
fresh++
|
|
288
|
+
}
|
|
289
|
+
done++
|
|
290
|
+
} while (done < ops.length && performance.now() - sliceStart < REGISTER_SLICE_MS)
|
|
291
|
+
opts.onProgress?.(done, ops.length)
|
|
230
292
|
}
|
|
231
293
|
if (
|
|
232
294
|
directNames.length > DIRECT_EXPOSURE_WARN_THRESHOLD &&
|
package/src/pi.ts
CHANGED
|
@@ -37,6 +37,11 @@ export type ExtensionUIContext = {
|
|
|
37
37
|
input?: (title: string, placeholder?: string, opts?: unknown) => Promise<string | undefined>
|
|
38
38
|
/** Set footer/status-bar text; undefined clears the slot. */
|
|
39
39
|
setStatus?: (key: string, text: string | undefined) => void
|
|
40
|
+
/** Raw terminal input (interactive mode only; a no-op elsewhere). Return
|
|
41
|
+
* undefined to leave the key to pi. Returns an unsubscribe function. */
|
|
42
|
+
onTerminalInput?: (handler: (data: string) => { consume?: boolean; data?: string } | undefined) => () => void
|
|
43
|
+
/** The editor's current text (pi ≥ 1.0). */
|
|
44
|
+
getEditorText?: () => string
|
|
40
45
|
}
|
|
41
46
|
|
|
42
47
|
/** Context handed to a command handler. Superset of ExtensionContext in practice; we
|
|
@@ -80,7 +85,7 @@ export type ImageBlock = { type: "image"; data: string; mimeType: string }
|
|
|
80
85
|
* time the transcript invalidates (session restore, theme change, resize).
|
|
81
86
|
* Renderers must at minimum no-op it / drop any width cache. */
|
|
82
87
|
export type TuiComponent = {
|
|
83
|
-
render(width: number): string[]
|
|
88
|
+
render(width: number): readonly string[]
|
|
84
89
|
invalidate(): void
|
|
85
90
|
}
|
|
86
91
|
|