@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.
Files changed (41) hide show
  1. package/CHANGELOG.md +101 -0
  2. package/dist/client/footer.d.ts +10 -2
  3. package/dist/client/footer.d.ts.map +1 -1
  4. package/dist/client/footer.js +15 -6
  5. package/dist/client/footer.js.map +1 -1
  6. package/dist/combiner-process.d.ts +160 -0
  7. package/dist/combiner-process.d.ts.map +1 -0
  8. package/dist/combiner-process.js +721 -0
  9. package/dist/combiner-process.js.map +1 -0
  10. package/dist/index.d.ts.map +1 -1
  11. package/dist/index.js +140 -306
  12. package/dist/index.js.map +1 -1
  13. package/dist/native/combiner-connection.d.ts +84 -0
  14. package/dist/native/combiner-connection.d.ts.map +1 -1
  15. package/dist/native/combiner-connection.js +194 -5
  16. package/dist/native/combiner-connection.js.map +1 -1
  17. package/dist/native/index.d.ts +32 -4
  18. package/dist/native/index.d.ts.map +1 -1
  19. package/dist/native/index.js +94 -6
  20. package/dist/native/index.js.map +1 -1
  21. package/dist/native/resources.d.ts +3 -0
  22. package/dist/native/resources.d.ts.map +1 -1
  23. package/dist/native/resources.js +6 -1
  24. package/dist/native/resources.js.map +1 -1
  25. package/dist/native/tool-surface.d.ts +31 -2
  26. package/dist/native/tool-surface.d.ts.map +1 -1
  27. package/dist/native/tool-surface.js +62 -18
  28. package/dist/native/tool-surface.js.map +1 -1
  29. package/dist/pi.d.ts +9 -1
  30. package/dist/pi.d.ts.map +1 -1
  31. package/package.json +5 -5
  32. package/src/client/footer.ts +16 -4
  33. package/src/client/panel.ts +1 -1
  34. package/src/client/renderers.ts +2 -2
  35. package/src/combiner-process.ts +813 -0
  36. package/src/index.ts +142 -355
  37. package/src/native/combiner-connection.ts +220 -10
  38. package/src/native/index.ts +119 -18
  39. package/src/native/resources.ts +8 -1
  40. package/src/native/tool-surface.ts +80 -18
  41. 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.2" }
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
- constructor(conn: ResolvedConnection, log: LogFn, opts?: { transportFactory?: (url: URL) => McpTransport }) {
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 connectPromise = (async (): Promise<McpClient> => {
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
- setTimeout(
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.log("warn", `combiner connect failed (${this.lastError})`)
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
@@ -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
- ): { run(): void; dispose(): void } {
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
- void activateNativeTools(pi, {
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
- }).catch((e) =>
71
- opts.log("warn", `native tool surface failed: ${e instanceof Error ? e.message : String(e)}`),
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
- if (opts.exposeResources !== false) {
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
  },
@@ -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
- opts.log("warn", `interactive resource discovery failed (${e instanceof Error ? e.message : String(e)})`)
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. Returns the names
189
- * currently active (for status/panel surfaces). */
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
- let fresh = 0
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
- // Removals: hide them (never unregister silently — pi has no unregister; a hidden
222
- // re-register at the same name retires the declaration).
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
- for (const goneName of [...state.names]) {
225
- if (currentNames.has(goneName)) continue
226
- pi.registerTool(removedToolDefinition(goneName))
227
- state.names.delete(goneName)
228
- state.signatures.delete(goneName)
229
- removed++
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