dsh-project-mcp 0.4.1 → 0.4.3

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.1",
4
+ "version": "0.4.3",
5
5
  "type": "module",
6
6
  "main": "lib/index.js",
7
7
  "types": "lib/index.d.ts",
@@ -87,7 +87,7 @@
87
87
  },
88
88
  "devDependencies": {
89
89
  "@deepseek-ai/cordis": "4.0.4",
90
- "@deepseek-ai/dsh-mcp-client": "0.2.0-rc.2",
90
+ "@deepseek-ai/dsh-mcp-client": "0.2.2-alpha.2",
91
91
  "@deepseek-ai/dsh-scope": "0.2.0-rc.2",
92
92
  "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
93
93
  "@types/node": "^22.20.4",
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
@@ -112,6 +112,20 @@ export interface ForwardableDefinition extends BridgeToolSchema {
112
112
  }
113
113
  /** Cooperative timeout budget, preserved for the timeout policy wrapper. */
114
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
115
129
  /**
116
130
  * Pure sibling-overlap classifier. Preserved: a forwarder that dropped it
117
131
  * would make every forwarded call exclusive while the project tool is
@@ -201,6 +215,14 @@ export interface ForwardProjectToolsOptions {
201
215
  readonly project: object
202
216
  /** Names to forward, as {@link projectToolNames} resolved them. */
203
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
204
226
  /** Registry lookup used to resolve the live project definition per call. */
205
227
  readonly registry: BridgeRegistryLike
206
228
  }
@@ -227,11 +249,14 @@ export const FORWARDED_TO = Symbol('dsh-project-mcp.forwarded-to')
227
249
  * dispatch would apply pre-execute listeners and guards twice.
228
250
  * @param project - the definition to forward, read for its surface.
229
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.
230
254
  * @returns the definition to register in a session's layer.
231
255
  */
232
256
  function forwarder(
233
257
  project: ForwardableDefinition,
234
258
  lookup: () => ForwardableDefinition | undefined,
259
+ deferred: boolean,
235
260
  ): ForwardableDefinition {
236
261
  // The marker rides outside the definition's own surface: it is addressed to a
237
262
  // test double standing in for the registry, never to the harness.
@@ -243,6 +268,11 @@ function forwarder(
243
268
  // is what silently lost `dsh-mcp-client`'s finalizer: the registry takes
244
269
  // it from the definition the session resolves, which is this one.
245
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 } : {},
246
276
  async execute(args: unknown, exec: never): Promise<unknown> {
247
277
  const live = lookup()
248
278
  if (live === undefined) {
@@ -278,7 +308,11 @@ export function forwardProjectTools(options: ForwardProjectToolsOptions): () =>
278
308
  const project = options.registry.get(name, options.project)
279
309
  if (project === undefined) continue
280
310
  try {
281
- 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
+ )))
282
316
  } catch {
283
317
  // A duplicate in this session's own layer is the session's own tool: it
284
318
  // keeps the name, and the bridge steps aside rather than failing a mount.
@@ -317,13 +351,26 @@ export interface ForwardBatchOptions {
317
351
  * @returns the names this session should forward, or `undefined` on failure.
318
352
  */
319
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[]
320
366
  /**
321
367
  * Register one batch of forwarders over the session's layer, which this call
322
368
  * reaches empty-handed: the batch it replaces is released first.
323
369
  * @param names - the names to forward, in registry order.
370
+ * @param deferred - the names of this batch that carry `deferLoading`.
324
371
  * @returns the exact releaser that drops the whole batch.
325
372
  */
326
- readonly register: (names: readonly string[]) => () => void
373
+ readonly register: (names: readonly string[], deferred: ReadonlySet<string>) => () => void
327
374
  /**
328
375
  * Report a failure thrown by a pass this batch ran on its own.
329
376
  *
@@ -390,6 +437,8 @@ export const MAX_SYNC_PASSES = 4
390
437
  export class ForwardBatch {
391
438
  /** The names the live batch was registered for; `undefined` before the first pass. */
392
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
393
442
  /** Disposer of the live registration batch; `undefined` while none is live. */
394
443
  #release: (() => void) | undefined = undefined
395
444
  /** Whether an owning frame is inside {@link sync}, registering right now. */
@@ -521,7 +570,14 @@ export class ForwardBatch {
521
570
  #syncOnce(): void {
522
571
  const names = this.options.names()
523
572
  if (names === undefined) return
524
- 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
525
581
  // Released first, and deliberately — see the class note. Until the new batch
526
582
  // is registered the session's layer is empty for the length of one
527
583
  // synchronous call, which is the price of every forwarded name being free.
@@ -531,8 +587,9 @@ export class ForwardBatch {
531
587
  // The registry's disposer is exact and idempotent, and a failure here must
532
588
  // not keep the new batch from registering.
533
589
  }
534
- this.#release = this.options.register(names)
590
+ this.#release = this.options.register(names, deferred)
535
591
  this.#namesIn = names
592
+ this.#deferredIn = deferred
536
593
  }
537
594
 
538
595
  /**
@@ -545,6 +602,7 @@ export class ForwardBatch {
545
602
  const release = this.#release
546
603
  this.#release = undefined
547
604
  this.#namesIn = undefined
605
+ this.#deferredIn = undefined
548
606
  release?.()
549
607
  }
550
608
  }
@@ -591,3 +649,23 @@ export function projectToolNames(
591
649
  export function sameNames(left: readonly string[], right: readonly string[]): boolean {
592
650
  return left.length === right.length && left.every((name, index) => name === right[index])
593
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/guidance.ts CHANGED
@@ -95,6 +95,17 @@ export interface GuidanceInput {
95
95
  readonly mostUsed?: readonly string[]
96
96
  /** Whether the on-demand search surface is on; defaults to the activation default. */
97
97
  readonly activationEnabled?: boolean
98
+ /**
99
+ * Whether a deferred tool can still be called by its exact full name.
100
+ *
101
+ * It can on a route that accepts tool declarations after the first request:
102
+ * the schema is hidden from the model and the registry keeps the tool
103
+ * admitted, so `mcp__server__tool` executes. On a route without that
104
+ * capability the tool is simply not declared, and a call by name answers
105
+ * "unknown tool" — the names line must then send the model through the search
106
+ * instead of promising the call. Defaults to `true`, the shipped capability.
107
+ */
108
+ readonly directCalls?: boolean
98
109
  }
99
110
 
100
111
  /**
@@ -134,7 +145,7 @@ export function buildGuidance(input: GuidanceInput): string {
134
145
  if (activationEnabled && hot !== '') tail.push('', hot)
135
146
  if (deferred.size > 0) {
136
147
  tail.push('', onDemandParagraph(offered.size, deferred.size))
137
- tail.push('', hiddenNamesLine(deferred))
148
+ tail.push('', hiddenNamesLine(deferred, input.directCalls ?? true))
138
149
  }
139
150
  const bullets: string[] = []
140
151
  let hidden = 0
@@ -314,17 +325,32 @@ function serverBullet(server: GuidanceServer): string {
314
325
  * deduped, truncated to {@link MAX_GUIDANCE_HIDDEN_NAMES} with a `+N more`.
315
326
  * Descriptions and schemas are the expensive part, so the line carries names
316
327
  * only — the model picks the one it needs and runs a single targeted search
317
- * instead of rephrasing blind guesses. The sentence also states the
318
- * direct-call contract: deferral trims the assembled request list, it never
319
- * unregisters the tool, so a call by the exact full name still executes;
320
- * searching the name first is how the model sees the description and
321
- * parameters, not a gate.
328
+ * instead of rephrasing blind guesses.
329
+ *
330
+ * The tail sentence is the one place the route changes the advice. Where the
331
+ * harness can declare a tool after the first request, deferral only trims the
332
+ * request list — the tool stays registered, so a call by its exact full name
333
+ * still executes and the search is how the model reads the description, not a
334
+ * gate. Where it cannot, the tool is not declared at all: the name no longer
335
+ * exists for the turn, and the model has to search first, so promising the
336
+ * direct call there would send it into an "unknown tool" error.
337
+ * @param deferred - names reachable only through the discovery tool right now.
338
+ * @param directCalls - whether an exact-name call still executes (§
339
+ * `GuidanceInput.directCalls`).
340
+ * @returns one line, or an empty string when nothing is deferred.
322
341
  */
323
- function hiddenNamesLine(deferred: ReadonlySet<string>): string {
342
+ function hiddenNamesLine(deferred: ReadonlySet<string>, directCalls: boolean): string {
324
343
  const names = [...deferred].sort(compareNames)
325
344
  const shown = names.slice(0, MAX_GUIDANCE_HIDDEN_NAMES)
326
345
  const hidden = names.length - shown.length
327
346
  const list = hidden === 0 ? shown.join(', ') : `${shown.join(', ')} +${hidden} more`
347
+ if (!directCalls) {
348
+ return (
349
+ `On demand right now: ${list} — none of them is in this request, so ask for one with ` +
350
+ `\`${SEARCH_TOOL_NAME}\` (a keyword or the name) and it becomes callable from the next ` +
351
+ 'step on.'
352
+ )
353
+ }
328
354
  return (
329
355
  `On demand right now: ${list} — every one of them runs when called by its exact full ` +
330
356
  `name \`mcp__<server>__<tool>\`; search a name with \`${SEARCH_TOOL_NAME}\` first to see ` +
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 {
@@ -148,6 +152,13 @@ export interface AgentEventLike {
148
152
  agent: AgentLike
149
153
  /** `agent/status` only: whether a turn is currently running. */
150
154
  status?: 'idle' | 'running'
155
+ /**
156
+ * `agent/pre-step` only: the model selection this step captured. Read to ask
157
+ * the llm service what the route can do — a hand-declared provider cannot take
158
+ * tool declarations after the first request, and the presentation has to know
159
+ * before it decides how to hide anything.
160
+ */
161
+ modelSelection?: { readonly provider: string; readonly model: string }
151
162
  }
152
163
 
153
164
  /** The subset of the hosting scope used here. */
@@ -775,6 +786,27 @@ interface AgentState {
775
786
  * state outlives an idle release.
776
787
  */
777
788
  auto: AutoOfferState | undefined
789
+ /**
790
+ * Identity of the model route the last resolved {@link AgentState.toolUpdate}
791
+ * belongs to, as `provider/model`. A selection change re-asks the llm service
792
+ * and nothing else does, so a session keeps one answer per route.
793
+ */
794
+ routeKey: string | undefined
795
+ /**
796
+ * Whether this session's route accepts tool declarations after its first
797
+ * request (`LlmResolvedModelInfo.toolUpdate`), read from the llm service on
798
+ * `agent/pre-step`.
799
+ *
800
+ * `undefined` until a route is resolved. `true` lets the presentation hide a
801
+ * tool behind `deferLoading` — declared, invisible, still callable. `false`
802
+ * means the harness sends the whole declaration list in the first request of
803
+ * every series, so a deferred tool is not hidden at all: it costs its schema
804
+ * and the presentation must not declare it, which is what makes its name
805
+ * reachable only through the discovery tool. The difference is the difference
806
+ * between "hidden but callable" and "not there", and only the route decides
807
+ * which one is even possible.
808
+ */
809
+ toolUpdate: boolean | undefined
778
810
  }
779
811
 
780
812
  interface CachedDocument {
@@ -1274,6 +1306,7 @@ export class ProjectMcpRuntime {
1274
1306
  }
1275
1307
  }
1276
1308
  policy.setPin(request.projectRoot, request.tool, request.pinned)
1309
+ this.refreshPresentation(request.projectRoot)
1277
1310
  this.notify()
1278
1311
  return { ok: true, snapshot: this.snapshot() }
1279
1312
  }
@@ -1316,6 +1349,7 @@ export class ProjectMcpRuntime {
1316
1349
  }
1317
1350
  }
1318
1351
  policy.setMode(request.projectRoot, request.mode)
1352
+ this.refreshPresentation(request.projectRoot)
1319
1353
  this.notify()
1320
1354
  return { ok: true, snapshot: this.snapshot() }
1321
1355
  }
@@ -1386,6 +1420,121 @@ export class ProjectMcpRuntime {
1386
1420
  return this.options.policy?.forProject(projectRoot) ?? DEFAULT_TOOL_POLICY
1387
1421
  }
1388
1422
 
1423
+ /**
1424
+ * Re-apply the presentation of every session working in one project.
1425
+ *
1426
+ * A pin or a mode is read live by the panel and by the guidance, but the
1427
+ * forwarders carry their `deferLoading` flag from the pass that registered
1428
+ * them, so the sessions of that project have to run one — off the caller's
1429
+ * stack, like every other change note.
1430
+ * @param projectRoot - the project whose policy just moved.
1431
+ */
1432
+ private refreshPresentation(projectRoot: string): void {
1433
+ for (const state of this.states.values()) {
1434
+ if (state.projectRoot !== projectRoot) continue
1435
+ state.bridge?.batch.note()
1436
+ }
1437
+ }
1438
+
1439
+ /**
1440
+ * The names one session's presentation offers the model right now.
1441
+ *
1442
+ * The counterpart of the assembly wiring's own `offeredNames`, read where the
1443
+ * presentation lives outside that assembly — in the bridge's forwarders. It is
1444
+ * the counter-seeded baseline, the session's activations, the context tier's
1445
+ * window, and the project's pins; the same four sources the assembly-side
1446
+ * `wanted` set is built from, so the two cannot drift.
1447
+ * @param state - the session to read.
1448
+ * @returns the offered public names.
1449
+ */
1450
+ private offeredNamesOf(state: AgentState): ReadonlySet<string> {
1451
+ const names = new Set<string>(presentedNames(this.seedActivation(state)))
1452
+ const auto = state.auto
1453
+ if (auto !== undefined) for (const name of autoPresentedNames(auto)) names.add(name)
1454
+ for (const pin of this.policyFor(state.projectRoot).pins) names.add(pin)
1455
+ return names
1456
+ }
1457
+
1458
+ /**
1459
+ * Ask the llm service what the session's current route can do with tool
1460
+ * declarations, and re-present the session when the answer moves.
1461
+ *
1462
+ * One answer per route, keyed by `provider/model`: the service resolves it from
1463
+ * the adapter, which is not something to ask on every step. `toolUpdate` is the
1464
+ * one capability read here — `undefined` on a route means the harness sends the
1465
+ * complete current declaration list in every request and strips the deferral
1466
+ * marker, so the presentation cannot hide a tool that way at all.
1467
+ *
1468
+ * A service that is absent (a host without `ctx.llm`, a test composition) or an
1469
+ * answer that never arrives leaves the capability `undefined`, and the
1470
+ * presentation keeps the deferral path it shipped with rather than guessing.
1471
+ * @param state - the session whose route is being read.
1472
+ * @param selection - the step's captured selection; absent resolves nothing.
1473
+ */
1474
+ private async resolveRoute(
1475
+ state: AgentState,
1476
+ selection: AgentEventLike['modelSelection'],
1477
+ ): Promise<void> {
1478
+ if (selection === undefined || this.disposed) return
1479
+ const key = `${selection.provider}/${selection.model}`
1480
+ if (state.routeKey === key) return
1481
+ state.routeKey = key
1482
+ const llm = this.ctx.get('llm') as
1483
+ | { resolveModelInfo?: (provider: string, model: string) => Promise<{ toolUpdate?: unknown }> }
1484
+ | undefined
1485
+ if (typeof llm?.resolveModelInfo !== 'function') return
1486
+ try {
1487
+ const info = await llm.resolveModelInfo(selection.provider, selection.model)
1488
+ const supported = info?.toolUpdate !== undefined
1489
+ if (supported === state.toolUpdate) return
1490
+ state.toolUpdate = supported
1491
+ // The presentation is built from this answer, so a route that changed its
1492
+ // mind — or a session that was mounted before its first step — re-presents
1493
+ // on the queue rather than inside whoever asked.
1494
+ state.bridge?.batch.note()
1495
+ } catch (error) {
1496
+ // A route that cannot describe itself is not a reason to fail a session;
1497
+ // the previous answer (or none) stands.
1498
+ this.ctx.logger.debug?.(
1499
+ `project-mcp: reading the model route of session ${state.agent.id} failed: ${errorText(error)}`,
1500
+ )
1501
+ }
1502
+ }
1503
+
1504
+ /**
1505
+ * The names one session presents as deferred: what it mounts that it does not
1506
+ * offer.
1507
+ *
1508
+ * Empty when there is nothing to defer — activation off, `direct`, or a
1509
+ * surface that fits the budget — because deferring a schema the request would
1510
+ * have carried anyway only makes the declaration list harder to read, and the
1511
+ * prefix-cache argument for it is gone. The budget is the same
1512
+ * {@link surfaceChars} reading the panel and the assembly gate use, so the
1513
+ * deferred set and the "hidden" number a panel shows are one decision.
1514
+ * @param state - the session whose presentation is being registered.
1515
+ * @returns the names whose forwarders carry `deferLoading`, in registry order.
1516
+ */
1517
+ private deferredNamesOf(state: AgentState): readonly string[] {
1518
+ if (!(this.config.activationEnabled ?? DEFAULT_ACTIVATION_ENABLED)) return []
1519
+ // A route without tool updates would send a deferred schema anyway (the
1520
+ // harness strips the marker), so "deferred" there means "declared": the
1521
+ // presentation gives way to the forwarder list itself, which carries only
1522
+ // what is offered.
1523
+ if (state.toolUpdate === false) return []
1524
+ const policy = this.policyFor(state.projectRoot)
1525
+ if (policy.mode === 'direct') return []
1526
+ // The home's catalog, read without {@link mountedSchemas}: this runs inside a
1527
+ // bridge pass, and that read syncs the very batch the pass is building.
1528
+ const home = this.homeOf(state)
1529
+ const mounted = home === undefined ? [] : this.schemasOf(home, state.agent.id)
1530
+ if (policy.mode === 'disclosure') {
1531
+ const budget = this.config.activationToolBudgetChars ?? DEFAULT_TOOL_BUDGET_CHARS
1532
+ if (!overToolBudget(surfaceChars(mounted), budget)) return []
1533
+ }
1534
+ const offered = this.offeredNamesOf(state)
1535
+ return mounted.map((schema) => schema.name).filter((name) => !offered.has(name))
1536
+ }
1537
+
1389
1538
  /**
1390
1539
  * Whether one project root has a live session on this host.
1391
1540
  * @param projectRoot - project root a policy request names.
@@ -1757,6 +1906,8 @@ export class ProjectMcpRuntime {
1757
1906
  activationDispose: undefined,
1758
1907
  guidanceDispose: undefined,
1759
1908
  auto: undefined,
1909
+ routeKey: undefined,
1910
+ toolUpdate: undefined,
1760
1911
  }
1761
1912
  }
1762
1913
 
@@ -2137,6 +2288,10 @@ export class ProjectMcpRuntime {
2137
2288
  state.step += 1
2138
2289
  if (!this.disposed) {
2139
2290
  this.touch(state, { activate: true })
2291
+ // Route capability is asked for off this path: it is network-shaped on
2292
+ // some adapters, and a project MCP server is never a reason to hold up
2293
+ // an agent step.
2294
+ void this.resolveRoute(state, event.modelSelection)
2140
2295
  await this.awaitActivation(state)
2141
2296
  }
2142
2297
  }
@@ -2870,11 +3025,21 @@ export class ProjectMcpRuntime {
2870
3025
  // pass would forward names this session's project never published.
2871
3026
  if (project === undefined) return undefined
2872
3027
  try {
2873
- return projectToolNames(
3028
+ const names = projectToolNames(
2874
3029
  project.key,
2875
3030
  (scope) => this.bridgeSchemas(scope),
2876
3031
  servers(),
2877
3032
  )
3033
+ // A route that cannot take declarations after its first request cannot
3034
+ // carry a deferred tool either: the marker would be stripped and the
3035
+ // schema sent. So the forwarder list itself becomes the presentation —
3036
+ // only what the session offers is registered, and the discovery tool is
3037
+ // how the model gets another one for the next step.
3038
+ if (state.toolUpdate === false) {
3039
+ const offered = this.offeredNamesOf(state)
3040
+ return names.filter((name) => offered.has(name))
3041
+ }
3042
+ return names
2878
3043
  } catch (error) {
2879
3044
  // A probe that failed says nothing about the project's set: the batch
2880
3045
  // it could not describe is the batch that stays live.
@@ -2884,13 +3049,15 @@ export class ProjectMcpRuntime {
2884
3049
  return undefined
2885
3050
  }
2886
3051
  },
2887
- register: (names) => {
3052
+ deferred: () => this.deferredNamesOf(state),
3053
+ register: (names, deferred) => {
2888
3054
  const project = state.project
2889
3055
  if (project === undefined) return () => undefined
2890
3056
  return forwardProjectTools({
2891
3057
  ctx: context,
2892
3058
  project: project.key,
2893
3059
  names,
3060
+ deferred: (name) => deferred.has(name),
2894
3061
  registry,
2895
3062
  })
2896
3063
  },
@@ -3117,6 +3284,11 @@ export class ProjectMcpRuntime {
3117
3284
  // mode or pin stored from the panel applies from the next model step on
3118
3285
  // without re-minting the scope the listener lives in.
3119
3286
  policy: () => this.policyFor(state.projectRoot),
3287
+ // The presentation lives in this session's own forwarders (they carry
3288
+ // `deferLoading`), so every move of the offered set re-applies it there.
3289
+ // `note` and not `sync`: the pass belongs off the caller's stack, and a
3290
+ // burst of activation settles in one queued pass.
3291
+ onOfferedChanged: () => state.bridge?.batch.note(),
3120
3292
  // The step the session is on, read when a search activates names: the
3121
3293
  // wiring keeps no counter of its own, because an activation outlives
3122
3294
  // the scope the wiring lives in and its stamp has to outlive it too.
@@ -3357,6 +3529,10 @@ export class ProjectMcpRuntime {
3357
3529
  deferred,
3358
3530
  mostUsed,
3359
3531
  activationEnabled,
3532
+ // Where the route cannot declare a tool after the first request, the
3533
+ // names line below must send the model through the search instead of
3534
+ // promising a call that would answer "unknown tool".
3535
+ directCalls: state.toolUpdate !== false,
3360
3536
  })
3361
3537
  } catch (error) {
3362
3538
  this.ctx.logger.warn(