dsh-project-mcp 0.4.0 → 0.4.2

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/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "dsh-project-mcp",
3
3
  "description": "Per-project MCP servers for DeepSeek Harness: mounts the MCP servers a project declares into the sessions working in it",
4
- "version": "0.4.0",
4
+ "version": "0.4.2",
5
5
  "type": "module",
6
6
  "main": "lib/index.js",
7
7
  "types": "lib/index.d.ts",
package/src/activation.ts CHANGED
@@ -1333,6 +1333,18 @@ export interface ActivationWiringOptions {
1333
1333
  * the same name may carry the step of the offer the compaction removed.
1334
1334
  */
1335
1335
  readonly onCompaction?: () => void
1336
+ /**
1337
+ * Told that the offered set may have moved: a search activated names, a
1338
+ * compaction dropped the ones no call backed, or the context tier advanced.
1339
+ *
1340
+ * A harness whose assembly carries no tool list cannot be filtered from this
1341
+ * module at all (0.2.2 and later: declarations are provider-owned), so the
1342
+ * presentation lives in the caller's own registrations instead — the bridge's
1343
+ * `deferLoading` forwarders. This is the seat that keeps that copy level with
1344
+ * {@link ActivationState}; absent simply means nothing presents the set but the
1345
+ * assembly this module used to rewrite.
1346
+ */
1347
+ readonly onOfferedChanged?: () => void
1336
1348
  /** Context-driven state to start from; defaults to an empty state. */
1337
1349
  readonly autoState?: AutoOfferState
1338
1350
  /** Sink for the context-driven state after every advance that changed it. */
@@ -1432,6 +1444,9 @@ export function installActivation(options: ActivationWiringOptions): () => void
1432
1444
  if (next === tracker.state) return
1433
1445
  tracker.state = next
1434
1446
  options.setAutoState?.(next)
1447
+ // The offered set moved, so a presentation that lives outside this assembly —
1448
+ // the bridge's `deferLoading` forwarders — has to follow it.
1449
+ options.onOfferedChanged?.()
1435
1450
  }
1436
1451
 
1437
1452
  /** Every name the session's explicit activation and context-driven tiers offer. */
@@ -1489,6 +1504,7 @@ export function installActivation(options: ActivationWiringOptions): () => void
1489
1504
  * continuation's value comes back by identity.
1490
1505
  */
1491
1506
  const contain = (result: AssemblyLike): AssemblyLike => {
1507
+ if (!Array.isArray(result.tools)) return result
1492
1508
  const foreign = options.foreign?.() ?? NO_FOREIGN
1493
1509
  if (foreign.size === 0) return result
1494
1510
  const kept = result.tools.filter((tool) => !foreign.has(tool.name))
@@ -1511,10 +1527,23 @@ export function installActivation(options: ActivationWiringOptions): () => void
1511
1527
  }
1512
1528
 
1513
1529
  const merge = (result: AssemblyLike): AssemblyLike => {
1530
+ const policy = options.policy?.() ?? DEFAULT_TOOL_POLICY
1531
+ // A harness whose assembly carries no tool list cannot be shaped from here at
1532
+ // all. From 0.2.2 on, `system-prompt/assemble` transforms a presentation and
1533
+ // the declared schemas are provider-owned, so a listener that rewrote
1534
+ // `assembly.tools` would be writing into a field the harness discards — and
1535
+ // reading it would throw on every model request. The presentation lives in
1536
+ // the caller's `deferLoading` forwarders instead (`src/bridge.ts`), kept level
1537
+ // through {@link ActivationWiringOptions.onOfferedChanged}; this listener
1538
+ // still drives the context tier and degrades to the rest of the harness's
1539
+ // answer.
1540
+ if (!Array.isArray(result.tools)) {
1541
+ if (policy.mode === 'disclosure') advance()
1542
+ return result
1543
+ }
1514
1544
  const surface = wholeSurface()
1515
1545
  // Nothing is visible: there is nothing to find, so nothing is added.
1516
1546
  if (surface.length === 0) return contain(result)
1517
- const policy = options.policy?.() ?? DEFAULT_TOOL_POLICY
1518
1547
  // `off` promises that the project's tools are not offered, and the promise is
1519
1548
  // about the request, not only about what the panel says: the project plane
1520
1549
  // leaves the assembly here. Only this plugin's own mounts go — the profile
@@ -1594,6 +1623,9 @@ export function installActivation(options: ActivationWiringOptions): () => void
1594
1623
  tracker.state = resetAutoOffer(tracker.state)
1595
1624
  tracker.calls = []
1596
1625
  tracker.changed = false
1626
+ // The boundary is the one place that shrinks the offered set, so a
1627
+ // presentation outside this assembly re-applies it here.
1628
+ options.onOfferedChanged?.()
1597
1629
  return
1598
1630
  }
1599
1631
  if (event?.type === 'user/message') {
@@ -1626,6 +1658,7 @@ export function installActivation(options: ActivationWiringOptions): () => void
1626
1658
  activate: (names) => {
1627
1659
  recordActivated(names)
1628
1660
  options.setState(activate(options.state(), names, Date.now()))
1661
+ options.onOfferedChanged?.()
1629
1662
  },
1630
1663
  ...(options.searchLimit === undefined ? {} : { defaultLimit: options.searchLimit }),
1631
1664
  })
package/src/bridge.ts CHANGED
@@ -33,7 +33,11 @@
33
33
  * it level with the project's live set: the set is re-read on every trigger,
34
34
  * the batch is replaced as a whole (released before the replacement is
35
35
  * registered), and the re-entry every registration forces on the sync through
36
- * `tools/change` is owned rather than left to tear the batch down.
36
+ * `tools/change` is owned rather than left to tear the batch down. Because that
37
+ * event is emitted once per entry registered and once per entry disposed, the
38
+ * subscription takes {@link ForwardBatch.note} — which folds a whole burst into
39
+ * one queued pass — and never {@link ForwardBatch.sync}, whose work belongs to
40
+ * the frame that asked for it.
37
41
  *
38
42
  * The module is import-free of `@deepseek-ai/dsh-tools` on purpose, exactly like
39
43
  * {@link ./activation.ts}: the registry, definition and schema surfaces are
@@ -108,6 +112,20 @@ export interface ForwardableDefinition extends BridgeToolSchema {
108
112
  }
109
113
  /** Cooperative timeout budget, preserved for the timeout policy wrapper. */
110
114
  readonly timeoutMs?: number
115
+ /**
116
+ * Deferred-loading request, owned by the presentation rather than by the
117
+ * project.
118
+ *
119
+ * The harness projects this flag onto the model-facing schema
120
+ * (`projectToolSchema`), and an adapter that understands it (the shipped
121
+ * `dsh-llm-pi-ai` route omits such a schema from the wire request) then leaves
122
+ * the definition out of the model's tool list while the registry keeps the
123
+ * tool admitted for dispatch — a tool the model does not see but can still
124
+ * call by its exact full name. It is set on the forwarder, never copied from
125
+ * the project, because which of a session's tools are offered is this plugin's
126
+ * presentation decision.
127
+ */
128
+ readonly deferLoading?: true
111
129
  /**
112
130
  * Pure sibling-overlap classifier. Preserved: a forwarder that dropped it
113
131
  * would make every forwarded call exclusive while the project tool is
@@ -197,6 +215,14 @@ export interface ForwardProjectToolsOptions {
197
215
  readonly project: object
198
216
  /** Names to forward, as {@link projectToolNames} resolved them. */
199
217
  readonly names: readonly string[]
218
+ /**
219
+ * Names this pass forwards as deferred, so their schemas stay out of the
220
+ * model's tool list while the registry keeps them callable. Absent defers
221
+ * none, which is what a session with nothing hidden gets.
222
+ * @param name - one forwarded name.
223
+ * @returns whether the forwarder of that name carries `deferLoading`.
224
+ */
225
+ readonly deferred?: (name: string) => boolean
200
226
  /** Registry lookup used to resolve the live project definition per call. */
201
227
  readonly registry: BridgeRegistryLike
202
228
  }
@@ -223,11 +249,14 @@ export const FORWARDED_TO = Symbol('dsh-project-mcp.forwarded-to')
223
249
  * dispatch would apply pre-execute listeners and guards twice.
224
250
  * @param project - the definition to forward, read for its surface.
225
251
  * @param lookup - resolves the current project definition of this name.
252
+ * @param deferred - whether this forwarder asks for deferred loading, so the
253
+ * model's tool list leaves it out while the registry keeps it callable.
226
254
  * @returns the definition to register in a session's layer.
227
255
  */
228
256
  function forwarder(
229
257
  project: ForwardableDefinition,
230
258
  lookup: () => ForwardableDefinition | undefined,
259
+ deferred: boolean,
231
260
  ): ForwardableDefinition {
232
261
  // The marker rides outside the definition's own surface: it is addressed to a
233
262
  // test double standing in for the registry, never to the harness.
@@ -239,6 +268,11 @@ function forwarder(
239
268
  // is what silently lost `dsh-mcp-client`'s finalizer: the registry takes
240
269
  // it from the definition the session resolves, which is this one.
241
270
  ...project,
271
+ // After the spread, because the presentation decides this flag and the
272
+ // project has no say in it. A forwarder that is not deferred carries no
273
+ // flag at all rather than `deferLoading: false`, which is not part of the
274
+ // harness's schema vocabulary.
275
+ ...deferred ? { deferLoading: true as const } : {},
242
276
  async execute(args: unknown, exec: never): Promise<unknown> {
243
277
  const live = lookup()
244
278
  if (live === undefined) {
@@ -274,7 +308,11 @@ export function forwardProjectTools(options: ForwardProjectToolsOptions): () =>
274
308
  const project = options.registry.get(name, options.project)
275
309
  if (project === undefined) continue
276
310
  try {
277
- disposes.push(tools.register(forwarder(project, () => options.registry.get(name, options.project))))
311
+ disposes.push(tools.register(forwarder(
312
+ project,
313
+ () => options.registry.get(name, options.project),
314
+ options.deferred?.(name) === true,
315
+ )))
278
316
  } catch {
279
317
  // A duplicate in this session's own layer is the session's own tool: it
280
318
  // keeps the name, and the bridge steps aside rather than failing a mount.
@@ -313,15 +351,50 @@ export interface ForwardBatchOptions {
313
351
  * @returns the names this session should forward, or `undefined` on failure.
314
352
  */
315
353
  readonly names: () => readonly string[] | undefined
354
+ /**
355
+ * The names this session presents as deferred — hidden from the model's tool
356
+ * list while the registry keeps them callable — read once on every pass.
357
+ *
358
+ * A pass whose names matched but whose deferred set moved still re-registers:
359
+ * `deferLoading` is baked into the definition at registration, so the flag a
360
+ * schema carries is exactly the flag its forwarder was registered with.
361
+ * Absent defers none, which is the presentation of a session with nothing
362
+ * hidden.
363
+ * @returns the deferred names, or none.
364
+ */
365
+ readonly deferred?: () => readonly string[]
316
366
  /**
317
367
  * Register one batch of forwarders over the session's layer, which this call
318
368
  * reaches empty-handed: the batch it replaces is released first.
319
369
  * @param names - the names to forward, in registry order.
370
+ * @param deferred - the names of this batch that carry `deferLoading`.
320
371
  * @returns the exact releaser that drops the whole batch.
321
372
  */
322
- readonly register: (names: readonly string[]) => () => void
373
+ readonly register: (names: readonly string[], deferred: ReadonlySet<string>) => () => void
374
+ /**
375
+ * Report a failure thrown by a pass this batch ran on its own.
376
+ *
377
+ * A pass requested by {@link ForwardBatch.note} runs off the caller's stack:
378
+ * the registry call that announced the change has already returned, and so
379
+ * has every frame that could have propagated the failure. Without this the
380
+ * batch would go quiet — no forwarder, and no trace of why.
381
+ * @param error - what the scheduled pass threw.
382
+ */
383
+ readonly onError?: (error: unknown) => void
323
384
  }
324
385
 
386
+ /**
387
+ * How many synchronous passes one {@link ForwardBatch.sync} may run.
388
+ *
389
+ * Two is the ordinary ceiling: a pass that replaced the batch is re-entered once
390
+ * by its own announcements and short-circuits on the second round, and a pass
391
+ * that found the set unchanged exits on the first. The extra room is for a set
392
+ * that genuinely moved while the batch was registering — and the ceiling itself
393
+ * is what stops a registry that keeps moving under the batch from holding the
394
+ * event loop for as long as it likes.
395
+ */
396
+ export const MAX_SYNC_PASSES = 4
397
+
325
398
  /**
326
399
  * One session's live forwarding batch, kept level with the project's live tools.
327
400
  *
@@ -334,7 +407,8 @@ export interface ForwardBatchOptions {
334
407
  * which the live first copy refuses as a duplicate. A bridge that steps aside
335
408
  * for a duplicate (it must, for the session's own tools) then drops those names
336
409
  * silently, and a full pass records `namesIn` as the whole set, so the loss is
337
- * frozen for every later pass. That is the defect this class exists to close.
410
+ * frozen for every later pass. That is the first defect this class exists to
411
+ * close.
338
412
  *
339
413
  * So: a pass requested from inside a pass only marks the batch dirty, and the
340
414
  * frame that owns the batch runs one more pass when it is complete — which is
@@ -342,16 +416,37 @@ export interface ForwardBatchOptions {
342
416
  * the old batch is released **before** the new one is registered, because one
343
417
  * layer holds one entry per name: registering over a live batch would refuse
344
418
  * every name it already had.
419
+ *
420
+ * Owning the re-entry is not enough on its own, and the shape of the event is
421
+ * why. Replacing a batch of N entries announces 2·N changes — one per disposal
422
+ * and one per registration — and the event carries no origin, so every session
423
+ * watching the stream runs a pass for every one of them, and every pass begins
424
+ * by projecting the project's whole catalog, which the registry answers by deep
425
+ * cloning each visible definition's JSON schema. The registry per pass is what
426
+ * makes that cost real: one MCP generation swap was measured holding the event
427
+ * loop for the full 54 seconds of a CPU profile (47% of its samples inside this
428
+ * sync, 52% in the collector the projections feed), while the plugin's own
429
+ * frames were 0.46% of it. So {@link note} is the seat a `tools/change`
430
+ * subscription takes, not {@link sync}: a change that arrives during a pass is
431
+ * absorbed by it, and a burst that arrives between passes costs **one** queued
432
+ * pass however many events it carries. A stale forwarder is safe in the window
433
+ * that opens — it resolves the project entry at call time and fails closed when
434
+ * there is none (`forwarder`) — and every read path brings the batch level
435
+ * before it reads, so a reader never waits for the queue.
345
436
  */
346
437
  export class ForwardBatch {
347
438
  /** The names the live batch was registered for; `undefined` before the first pass. */
348
439
  #namesIn: readonly string[] | undefined = undefined
440
+ /** The names the live batch registered as deferred; `undefined` with no live batch. */
441
+ #deferredIn: ReadonlySet<string> | undefined = undefined
349
442
  /** Disposer of the live registration batch; `undefined` while none is live. */
350
443
  #release: (() => void) | undefined = undefined
351
444
  /** Whether an owning frame is inside {@link sync}, registering right now. */
352
445
  #building = false
353
446
  /** Whether a pass asked for while {@link #building} still needs a run. */
354
447
  #again = false
448
+ /** Whether a scheduled pass is already waiting for a burst of changes. */
449
+ #queued = false
355
450
 
356
451
  constructor(private readonly options: ForwardBatchOptions) {}
357
452
 
@@ -367,11 +462,12 @@ export class ForwardBatch {
367
462
  }
368
463
 
369
464
  /**
370
- * Bring the session's layer level with the project's live tool set.
465
+ * Bring the session's layer level with the project's live tool set, now.
371
466
  *
372
467
  * Cheap when it already is: an unchanged set short-circuits and leaves the
373
468
  * live batch — and its generation of definitions — untouched. Re-entrant
374
- * while registering: see the class note.
469
+ * while registering, and bounded to {@link MAX_SYNC_PASSES} synchronous
470
+ * rounds so no registry state can hold the caller's frame: see the class note.
375
471
  * @returns nothing; a failure from the probe or the registry propagates.
376
472
  */
377
473
  sync(): void {
@@ -379,17 +475,47 @@ export class ForwardBatch {
379
475
  this.#again = true
380
476
  return
381
477
  }
478
+ // A queued pass would read the very registry this one is about to read, so
479
+ // it is dropped here rather than left to repeat the probe.
480
+ this.#queued = false
382
481
  this.#building = true
383
482
  try {
384
- do {
483
+ for (let pass = 0; pass < MAX_SYNC_PASSES; pass += 1) {
385
484
  this.#again = false
386
485
  this.#syncOnce()
387
- } while (this.#again)
486
+ if (!this.#again) return
487
+ }
488
+ // Still moving after a full round: hand the rest to the queue. A registry
489
+ // that keeps changing under the batch must not hold the caller's frame.
490
+ this.#schedule(true)
388
491
  } finally {
389
492
  this.#building = false
390
493
  }
391
494
  }
392
495
 
496
+ /**
497
+ * Note that the registry changed, and bring the batch level — off this stack.
498
+ *
499
+ * This is the seat a `tools/change` subscription takes, and the reason it is
500
+ * not {@link sync}: the event is emitted once per entry registered and once
501
+ * per entry disposed, from inside the registry's own insertion and removal,
502
+ * so one MCP generation swap is a burst of thousands. A change that arrives
503
+ * while a pass is running is absorbed by that pass — it re-reads the set it is
504
+ * replacing before it returns — and a burst that arrives between passes costs
505
+ * one pass: the first queues, every later one folds into it.
506
+ *
507
+ * Nothing reads a stale layer for it. Every read path brings the batch level
508
+ * first (`src/runtime.ts`, `mountedSchemas`), and the queued pass has run
509
+ * before any turn that could read the layer at all.
510
+ */
511
+ note(): void {
512
+ if (this.#building) {
513
+ this.#again = true
514
+ return
515
+ }
516
+ this.#schedule(false)
517
+ }
518
+
393
519
  /**
394
520
  * Drop the live batch: the session keeps no forwarder, and the next
395
521
  * {@link sync} starts from nothing rather than amending a stale set.
@@ -399,22 +525,59 @@ export class ForwardBatch {
399
525
  * session is subscribed to that event; a pass re-entered from there must not
400
526
  * resurrect the batch it is watching being dropped. So the guard is held for
401
527
  * the whole release, and the pass it queues is discarded rather than run.
528
+ *
529
+ * The guard is *held*, not taken: a drop that runs inside a pass — a detach
530
+ * driven from a listener, a scope torn down under a registration — restores
531
+ * the pass's own `building` rather than clearing it. Clearing it there would
532
+ * let the next `tools/change` start a nested pass inside a frame that still
533
+ * owns one, which is exactly the re-entry this class exists to own.
402
534
  */
403
535
  drop(): void {
536
+ const building = this.#building
404
537
  this.#building = true
405
538
  try {
406
539
  this.#releaseBatch()
407
540
  } finally {
408
- this.#building = false
541
+ this.#building = building
409
542
  this.#again = false
543
+ this.#queued = false
544
+ }
545
+ }
546
+
547
+ /**
548
+ * Queue the one deferred pass a burst of changes needs.
549
+ * @param yielding - run it on the timer queue rather than the microtask queue.
550
+ * A pass that overran {@link MAX_SYNC_PASSES} asks for this: a chain of
551
+ * microtasks still starves timers and I/O, a round of timers does not.
552
+ */
553
+ #schedule(yielding: boolean): void {
554
+ if (this.#queued) return
555
+ this.#queued = true
556
+ const run = (): void => {
557
+ if (!this.#queued) return
558
+ this.#queued = false
559
+ try {
560
+ this.sync()
561
+ } catch (error) {
562
+ this.options.onError?.(error)
563
+ }
410
564
  }
565
+ if (yielding) setTimeout(run, 0)
566
+ else queueMicrotask(run)
411
567
  }
412
568
 
413
569
  /** One pass: read the project's set, then replace the batch when it moved. */
414
570
  #syncOnce(): void {
415
571
  const names = this.options.names()
416
572
  if (names === undefined) return
417
- if (this.#namesIn !== undefined && sameNames(this.#namesIn, names)) return
573
+ // A name that enters or leaves the deferred set is a definition change even
574
+ // when the name set itself is identical: the flag is part of the schema the
575
+ // registry projects, so a batch registered before the flip would keep
576
+ // presenting the old answer for every later request.
577
+ const deferred = new Set(this.options.deferred?.() ?? [])
578
+ if (this.#namesIn !== undefined
579
+ && sameNames(this.#namesIn, names)
580
+ && sameNameSet(this.#deferredIn, deferred)) return
418
581
  // Released first, and deliberately — see the class note. Until the new batch
419
582
  // is registered the session's layer is empty for the length of one
420
583
  // synchronous call, which is the price of every forwarded name being free.
@@ -424,8 +587,9 @@ export class ForwardBatch {
424
587
  // The registry's disposer is exact and idempotent, and a failure here must
425
588
  // not keep the new batch from registering.
426
589
  }
427
- this.#release = this.options.register(names)
590
+ this.#release = this.options.register(names, deferred)
428
591
  this.#namesIn = names
592
+ this.#deferredIn = deferred
429
593
  }
430
594
 
431
595
  /**
@@ -438,6 +602,7 @@ export class ForwardBatch {
438
602
  const release = this.#release
439
603
  this.#release = undefined
440
604
  this.#namesIn = undefined
605
+ this.#deferredIn = undefined
441
606
  release?.()
442
607
  }
443
608
  }
@@ -484,3 +649,23 @@ export function projectToolNames(
484
649
  export function sameNames(left: readonly string[], right: readonly string[]): boolean {
485
650
  return left.length === right.length && left.every((name, index) => name === right[index])
486
651
  }
652
+
653
+ /**
654
+ * Whether two deferred-name sets are the same set.
655
+ *
656
+ * The batch short-circuits a pass whose forwarded names did not move, and it
657
+ * must not do that when the *deferred* subset moved instead: the flag rides in
658
+ * the registered definition, so a stale batch presents a stale answer. Order
659
+ * carries no meaning here, hence a set comparison rather than {@link sameNames}.
660
+ * @param left - the deferred set of the live batch; `undefined` with no live batch.
661
+ * @param right - the deferred set this pass read.
662
+ * @returns whether the two describe the same names.
663
+ */
664
+ export function sameNameSet(
665
+ left: ReadonlySet<string> | undefined,
666
+ right: ReadonlySet<string>,
667
+ ): boolean {
668
+ if (left === undefined || left.size !== right.size) return false
669
+ for (const name of right) if (!left.has(name)) return false
670
+ return true
671
+ }
package/src/runtime.ts CHANGED
@@ -31,16 +31,20 @@ import {
31
31
  DEFAULT_ACTIVATION_ENABLED,
32
32
  DEFAULT_ACTIVATION_MIN_CALLS,
33
33
  DEFAULT_ACTIVATION_SEEDED,
34
+ DEFAULT_TOOL_BUDGET_CHARS,
34
35
  DEFAULT_TOOL_IDLE_MS,
35
36
  SEARCH_TOOL_NAME,
37
+ autoPresentedNames,
36
38
  createActivationState,
37
39
  createAutoOfferState,
38
40
  installActivation,
39
41
  noteUse,
42
+ overToolBudget,
40
43
  presentedNames,
41
44
  pruneIdle,
42
45
  schemaChars,
43
46
  seedFromUsage,
47
+ surfaceChars,
44
48
  toolsFor,
45
49
  } from './activation.ts'
46
50
  import type {
@@ -1274,6 +1278,7 @@ export class ProjectMcpRuntime {
1274
1278
  }
1275
1279
  }
1276
1280
  policy.setPin(request.projectRoot, request.tool, request.pinned)
1281
+ this.refreshPresentation(request.projectRoot)
1277
1282
  this.notify()
1278
1283
  return { ok: true, snapshot: this.snapshot() }
1279
1284
  }
@@ -1316,6 +1321,7 @@ export class ProjectMcpRuntime {
1316
1321
  }
1317
1322
  }
1318
1323
  policy.setMode(request.projectRoot, request.mode)
1324
+ this.refreshPresentation(request.projectRoot)
1319
1325
  this.notify()
1320
1326
  return { ok: true, snapshot: this.snapshot() }
1321
1327
  }
@@ -1386,6 +1392,70 @@ export class ProjectMcpRuntime {
1386
1392
  return this.options.policy?.forProject(projectRoot) ?? DEFAULT_TOOL_POLICY
1387
1393
  }
1388
1394
 
1395
+ /**
1396
+ * Re-apply the presentation of every session working in one project.
1397
+ *
1398
+ * A pin or a mode is read live by the panel and by the guidance, but the
1399
+ * forwarders carry their `deferLoading` flag from the pass that registered
1400
+ * them, so the sessions of that project have to run one — off the caller's
1401
+ * stack, like every other change note.
1402
+ * @param projectRoot - the project whose policy just moved.
1403
+ */
1404
+ private refreshPresentation(projectRoot: string): void {
1405
+ for (const state of this.states.values()) {
1406
+ if (state.projectRoot !== projectRoot) continue
1407
+ state.bridge?.batch.note()
1408
+ }
1409
+ }
1410
+
1411
+ /**
1412
+ * The names one session's presentation offers the model right now.
1413
+ *
1414
+ * The counterpart of the assembly wiring's own `offeredNames`, read where the
1415
+ * presentation lives outside that assembly — in the bridge's forwarders. It is
1416
+ * the counter-seeded baseline, the session's activations, the context tier's
1417
+ * window, and the project's pins; the same four sources the assembly-side
1418
+ * `wanted` set is built from, so the two cannot drift.
1419
+ * @param state - the session to read.
1420
+ * @returns the offered public names.
1421
+ */
1422
+ private offeredNamesOf(state: AgentState): ReadonlySet<string> {
1423
+ const names = new Set<string>(presentedNames(this.seedActivation(state)))
1424
+ const auto = state.auto
1425
+ if (auto !== undefined) for (const name of autoPresentedNames(auto)) names.add(name)
1426
+ for (const pin of this.policyFor(state.projectRoot).pins) names.add(pin)
1427
+ return names
1428
+ }
1429
+
1430
+ /**
1431
+ * The names one session presents as deferred: what it mounts that it does not
1432
+ * offer.
1433
+ *
1434
+ * Empty when there is nothing to defer — activation off, `direct`, or a
1435
+ * surface that fits the budget — because deferring a schema the request would
1436
+ * have carried anyway only makes the declaration list harder to read, and the
1437
+ * prefix-cache argument for it is gone. The budget is the same
1438
+ * {@link surfaceChars} reading the panel and the assembly gate use, so the
1439
+ * deferred set and the "hidden" number a panel shows are one decision.
1440
+ * @param state - the session whose presentation is being registered.
1441
+ * @returns the names whose forwarders carry `deferLoading`, in registry order.
1442
+ */
1443
+ private deferredNamesOf(state: AgentState): readonly string[] {
1444
+ if (!(this.config.activationEnabled ?? DEFAULT_ACTIVATION_ENABLED)) return []
1445
+ const policy = this.policyFor(state.projectRoot)
1446
+ if (policy.mode === 'direct') return []
1447
+ // The home's catalog, read without {@link mountedSchemas}: this runs inside a
1448
+ // bridge pass, and that read syncs the very batch the pass is building.
1449
+ const home = this.homeOf(state)
1450
+ const mounted = home === undefined ? [] : this.schemasOf(home, state.agent.id)
1451
+ if (policy.mode === 'disclosure') {
1452
+ const budget = this.config.activationToolBudgetChars ?? DEFAULT_TOOL_BUDGET_CHARS
1453
+ if (!overToolBudget(surfaceChars(mounted), budget)) return []
1454
+ }
1455
+ const offered = this.offeredNamesOf(state)
1456
+ return mounted.map((schema) => schema.name).filter((name) => !offered.has(name))
1457
+ }
1458
+
1389
1459
  /**
1390
1460
  * Whether one project root has a live session on this host.
1391
1461
  * @param projectRoot - project root a policy request names.
@@ -2864,9 +2934,14 @@ export class ProjectMcpRuntime {
2864
2934
  const servers = (): ReadonlySet<string> => this.runtimeNamesOf(state)
2865
2935
  const batch = new ForwardBatch({
2866
2936
  names: () => {
2937
+ const project = state.project
2938
+ // No project, nothing to probe. An empty key here would read the
2939
+ // *global* view instead — every tool any scope registered — and each
2940
+ // pass would forward names this session's project never published.
2941
+ if (project === undefined) return undefined
2867
2942
  try {
2868
2943
  return projectToolNames(
2869
- state.project?.key ?? {},
2944
+ project.key,
2870
2945
  (scope) => this.bridgeSchemas(scope),
2871
2946
  servers(),
2872
2947
  )
@@ -2879,20 +2954,29 @@ export class ProjectMcpRuntime {
2879
2954
  return undefined
2880
2955
  }
2881
2956
  },
2882
- register: (names) => forwardProjectTools({
2883
- ctx: context,
2884
- project: state.project?.key ?? {},
2885
- names,
2886
- registry,
2887
- }),
2957
+ deferred: () => this.deferredNamesOf(state),
2958
+ register: (names, deferred) => {
2959
+ const project = state.project
2960
+ if (project === undefined) return () => undefined
2961
+ return forwardProjectTools({
2962
+ ctx: context,
2963
+ project: project.key,
2964
+ names,
2965
+ deferred: (name) => deferred.has(name),
2966
+ registry,
2967
+ })
2968
+ },
2969
+ onError: (error) => this.reportBridgeFailure(state, error),
2888
2970
  })
2889
2971
  const bridge: BridgeForwarders = {
2890
2972
  batch,
2891
2973
  detach: () => undefined,
2892
2974
  }
2893
2975
  // The listener lives on the session scope and is dropped with it, so a
2894
- // released session never keeps syncing against a project it left.
2895
- const detach = state.scope.ctx.on('tools/change', () => this.syncBridge(state))
2976
+ // released session never keeps syncing against a project it left. It only
2977
+ // *notes* the change: the registry emits this once per entry registered and
2978
+ // once per entry disposed, and a pass per event is what held the event loop.
2979
+ const detach = state.scope.ctx.on('tools/change', () => this.noteBridge(state))
2896
2980
  bridge.detach = typeof detach === 'function' ? (detach as () => void) : () => undefined
2897
2981
  state.bridge = bridge
2898
2982
  this.syncBridge(state)
@@ -2914,12 +2998,42 @@ export class ProjectMcpRuntime {
2914
2998
  try {
2915
2999
  bridge.batch.sync()
2916
3000
  } catch (error) {
2917
- this.ctx.logger.warn(
2918
- `project-mcp: forwarding the tools of ${state.project?.projectRoot ?? 'the project'} into session ${state.agent.id} failed: ${errorText(error)}`,
2919
- )
3001
+ this.reportBridgeFailure(state, error)
2920
3002
  }
2921
3003
  }
2922
3004
 
3005
+ /**
3006
+ * Note one registry change for one session's bridge, off the emitter's stack.
3007
+ *
3008
+ * The event this answers is emitted synchronously from inside the registry's
3009
+ * own insertion and removal — once per entry in, once per entry out — so one
3010
+ * MCP generation swap is a burst of thousands. Running the pass here would
3011
+ * make whoever registered a tool pay for every session watching the project,
3012
+ * and each pass projects the project's whole catalog. The batch folds the
3013
+ * burst into one queued pass instead, which is also why this is not
3014
+ * {@link syncBridge}: the read paths, the mount settle and the scope wiring
3015
+ * all bring the batch level synchronously, before anything reads the layer.
3016
+ * @param state - the session whose bridge noticed the change.
3017
+ */
3018
+ private noteBridge(state: AgentState): void {
3019
+ state.bridge?.batch.note()
3020
+ }
3021
+
3022
+ /**
3023
+ * Write the one warning line a failed bridge pass is allowed.
3024
+ *
3025
+ * Shared by the synchronous pass and by the one a batch runs on its own: a
3026
+ * scheduled pass has no caller left to propagate its failure to, so the batch
3027
+ * hands it here through `onError` rather than swallowing it.
3028
+ * @param state - the session whose bridge failed.
3029
+ * @param error - what the pass threw.
3030
+ */
3031
+ private reportBridgeFailure(state: AgentState, error: unknown): void {
3032
+ this.ctx.logger.warn(
3033
+ `project-mcp: forwarding the tools of ${state.project?.projectRoot ?? 'the project'} into session ${state.agent.id} failed: ${errorText(error)}`,
3034
+ )
3035
+ }
3036
+
2923
3037
  /** The project scope's visible schemas, as {@link projectToolNames} reads them. */
2924
3038
  private bridgeSchemas(scope: object): ReturnType<BridgeRegistryLike['schemas']> {
2925
3039
  return this.bridgeRegistry().schemas(scope)
@@ -3075,6 +3189,11 @@ export class ProjectMcpRuntime {
3075
3189
  // mode or pin stored from the panel applies from the next model step on
3076
3190
  // without re-minting the scope the listener lives in.
3077
3191
  policy: () => this.policyFor(state.projectRoot),
3192
+ // The presentation lives in this session's own forwarders (they carry
3193
+ // `deferLoading`), so every move of the offered set re-applies it there.
3194
+ // `note` and not `sync`: the pass belongs off the caller's stack, and a
3195
+ // burst of activation settles in one queued pass.
3196
+ onOfferedChanged: () => state.bridge?.batch.note(),
3078
3197
  // The step the session is on, read when a search activates names: the
3079
3198
  // wiring keeps no counter of its own, because an activation outlives
3080
3199
  // the scope the wiring lives in and its stamp has to outlive it too.