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/README.md CHANGED
@@ -430,12 +430,47 @@ request gets the registry's own tool list plus the active schemas, deduplicated
430
430
  by name, and `activationEnabled: false` turns the whole mechanism off (every
431
431
  mounted tool is listed exactly as before, and no search tool is registered).
432
432
 
433
- Implementation note — the presentation rides the agent's own
434
- `system-prompt/assemble` waterfall, registered *prepended* so it runs outermost
435
- and sees the list after other presentation plugins (for example
433
+ Implementation note — the mechanism depends on which harness runs it, because
434
+ DSH 0.2.2 moved declarations out of the prompt assembly. From 0.2.2 on,
435
+ `system-prompt/assemble` transforms a presentation (`sections`, `contexts`,
436
+ `variables`) and carries **no tool list**: the declared schemas come from
437
+ `systemPrompt.tools()` providers and the harness attaches them after the
438
+ waterfall, so a listener writing into `assembly.tools` writes into a field the
439
+ harness discards. The presentation therefore rides this plugin's own
440
+ registrations: the thin per-session forwarders of the F-19 bridge carry
441
+ `deferLoading`, the harness projects that flag onto the model-facing schema, and
442
+ an adapter that understands it (the shipped `dsh-llm-pi-ai` route) leaves the
443
+ definition out of the wire request while the registry keeps the tool admitted for
444
+ dispatch. That is what keeps the paragraph above true on the new harness: the
445
+ tool is invisible to the model and still callable by its exact full name, and
446
+ nothing is unregistered. `installActivation`'s `onOfferedChanged` is what keeps
447
+ the flags level — a search activation, a compaction boundary, a context advance
448
+ and a policy edit each queue one coalesced bridge pass (`ForwardBatch.note`), and
449
+ a pass re-registers only when the names *or* the deferred subset moved.
450
+
451
+ **The route decides which of the two is even possible.** `deferLoading` only
452
+ hides a schema from a route that accepts tool declarations after its first
453
+ request (`LlmResolvedModelInfo.toolUpdate`, which the adapter reports and which
454
+ only catalog models declare): on a hand-declared provider — a custom
455
+ `llm-pi-ai` route, say — the harness strips the marker and sends the complete
456
+ declaration list, so a "deferred" tool costs its schema and hides nothing. The
457
+ runtime asks the `llm` service once per session route and re-presents on that
458
+ answer: where the capability is absent, the session's forwarders carry **only
459
+ the offered names**, the rest are not registered at all, and `mcp_search_tools`
460
+ is what makes one callable from the next step. The guidance says so in the same
461
+ words — its names line promises an exact-name call only where the tool is still
462
+ registered — and the per-session panel keeps reporting both tiers either way.
463
+ The first request of a session is always the wide one: the route is learned on
464
+ the first step, and the pass that follows trims the layer.
465
+
466
+ On an older harness the same module still rewrites the assembly list, through the
467
+ agent's own `system-prompt/assemble` waterfall, registered *prepended* so it runs
468
+ outermost and sees the list after other presentation plugins (for example
436
469
  `dsh-progressive-tools`) filtered it. That listener is contained: if this
437
470
  plugin's own work fails, the assembly the rest of the harness produced is
438
- returned unchanged, so a broken probe can never break a model request. One
471
+ returned unchanged, so a broken probe can never break a model request; on a
472
+ harness that hands it a presentation without `tools`, it leaves the document
473
+ alone by identity. One
439
474
  residual ordering risk remains: a presentation plugin that trims the list to its
440
475
  own allowlist and ends up *outside* this listener (it registered its own
441
476
  prepended listener later) drops the schemas this plugin added, leaving only the
package/lib/index.d.ts CHANGED
@@ -115,6 +115,20 @@ interface ForwardableDefinition extends BridgeToolSchema {
115
115
  };
116
116
  /** Cooperative timeout budget, preserved for the timeout policy wrapper. */
117
117
  readonly timeoutMs?: number;
118
+ /**
119
+ * Deferred-loading request, owned by the presentation rather than by the
120
+ * project.
121
+ *
122
+ * The harness projects this flag onto the model-facing schema
123
+ * (`projectToolSchema`), and an adapter that understands it (the shipped
124
+ * `dsh-llm-pi-ai` route omits such a schema from the wire request) then leaves
125
+ * the definition out of the model's tool list while the registry keeps the
126
+ * tool admitted for dispatch — a tool the model does not see but can still
127
+ * call by its exact full name. It is set on the forwarder, never copied from
128
+ * the project, because which of a session's tools are offered is this plugin's
129
+ * presentation decision.
130
+ */
131
+ readonly deferLoading?: true;
118
132
  /**
119
133
  * Pure sibling-overlap classifier. Preserved: a forwarder that dropped it
120
134
  * would make every forwarded call exclusive while the project tool is
@@ -210,13 +224,26 @@ interface ForwardBatchOptions {
210
224
  * @returns the names this session should forward, or `undefined` on failure.
211
225
  */
212
226
  readonly names: () => readonly string[] | undefined;
227
+ /**
228
+ * The names this session presents as deferred — hidden from the model's tool
229
+ * list while the registry keeps them callable — read once on every pass.
230
+ *
231
+ * A pass whose names matched but whose deferred set moved still re-registers:
232
+ * `deferLoading` is baked into the definition at registration, so the flag a
233
+ * schema carries is exactly the flag its forwarder was registered with.
234
+ * Absent defers none, which is the presentation of a session with nothing
235
+ * hidden.
236
+ * @returns the deferred names, or none.
237
+ */
238
+ readonly deferred?: () => readonly string[];
213
239
  /**
214
240
  * Register one batch of forwarders over the session's layer, which this call
215
241
  * reaches empty-handed: the batch it replaces is released first.
216
242
  * @param names - the names to forward, in registry order.
243
+ * @param deferred - the names of this batch that carry `deferLoading`.
217
244
  * @returns the exact releaser that drops the whole batch.
218
245
  */
219
- readonly register: (names: readonly string[]) => () => void;
246
+ readonly register: (names: readonly string[], deferred: ReadonlySet<string>) => () => void;
220
247
  /**
221
248
  * Report a failure thrown by a pass this batch ran on its own.
222
249
  *
@@ -1413,6 +1440,18 @@ interface ActivationWiringOptions {
1413
1440
  * the same name may carry the step of the offer the compaction removed.
1414
1441
  */
1415
1442
  readonly onCompaction?: () => void;
1443
+ /**
1444
+ * Told that the offered set may have moved: a search activated names, a
1445
+ * compaction dropped the ones no call backed, or the context tier advanced.
1446
+ *
1447
+ * A harness whose assembly carries no tool list cannot be filtered from this
1448
+ * module at all (0.2.2 and later: declarations are provider-owned), so the
1449
+ * presentation lives in the caller's own registrations instead — the bridge's
1450
+ * `deferLoading` forwarders. This is the seat that keeps that copy level with
1451
+ * {@link ActivationState}; absent simply means nothing presents the set but the
1452
+ * assembly this module used to rewrite.
1453
+ */
1454
+ readonly onOfferedChanged?: () => void;
1416
1455
  /** Context-driven state to start from; defaults to an empty state. */
1417
1456
  readonly autoState?: AutoOfferState;
1418
1457
  /** Sink for the context-driven state after every advance that changed it. */
@@ -1543,6 +1582,16 @@ interface AgentEventLike {
1543
1582
  agent: AgentLike;
1544
1583
  /** `agent/status` only: whether a turn is currently running. */
1545
1584
  status?: 'idle' | 'running';
1585
+ /**
1586
+ * `agent/pre-step` only: the model selection this step captured. Read to ask
1587
+ * the llm service what the route can do — a hand-declared provider cannot take
1588
+ * tool declarations after the first request, and the presentation has to know
1589
+ * before it decides how to hide anything.
1590
+ */
1591
+ modelSelection?: {
1592
+ readonly provider: string;
1593
+ readonly model: string;
1594
+ };
1546
1595
  }
1547
1596
  /** The subset of the hosting scope used here. */
1548
1597
  interface AgentScopeLike {
@@ -2002,6 +2051,27 @@ interface AgentState {
2002
2051
  * state outlives an idle release.
2003
2052
  */
2004
2053
  auto: AutoOfferState | undefined;
2054
+ /**
2055
+ * Identity of the model route the last resolved {@link AgentState.toolUpdate}
2056
+ * belongs to, as `provider/model`. A selection change re-asks the llm service
2057
+ * and nothing else does, so a session keeps one answer per route.
2058
+ */
2059
+ routeKey: string | undefined;
2060
+ /**
2061
+ * Whether this session's route accepts tool declarations after its first
2062
+ * request (`LlmResolvedModelInfo.toolUpdate`), read from the llm service on
2063
+ * `agent/pre-step`.
2064
+ *
2065
+ * `undefined` until a route is resolved. `true` lets the presentation hide a
2066
+ * tool behind `deferLoading` — declared, invisible, still callable. `false`
2067
+ * means the harness sends the whole declaration list in the first request of
2068
+ * every series, so a deferred tool is not hidden at all: it costs its schema
2069
+ * and the presentation must not declare it, which is what makes its name
2070
+ * reachable only through the discovery tool. The difference is the difference
2071
+ * between "hidden but callable" and "not there", and only the route decides
2072
+ * which one is even possible.
2073
+ */
2074
+ toolUpdate: boolean | undefined;
2005
2075
  }
2006
2076
  /**
2007
2077
  * Owns every project-scoped mount, the config watchers, and the rescan timer.
@@ -2224,6 +2294,59 @@ export declare class ProjectMcpRuntime {
2224
2294
  * @returns the stored policy, or {@link DEFAULT_TOOL_POLICY} when there is none.
2225
2295
  */
2226
2296
  private policyFor;
2297
+ /**
2298
+ * Re-apply the presentation of every session working in one project.
2299
+ *
2300
+ * A pin or a mode is read live by the panel and by the guidance, but the
2301
+ * forwarders carry their `deferLoading` flag from the pass that registered
2302
+ * them, so the sessions of that project have to run one — off the caller's
2303
+ * stack, like every other change note.
2304
+ * @param projectRoot - the project whose policy just moved.
2305
+ */
2306
+ private refreshPresentation;
2307
+ /**
2308
+ * The names one session's presentation offers the model right now.
2309
+ *
2310
+ * The counterpart of the assembly wiring's own `offeredNames`, read where the
2311
+ * presentation lives outside that assembly — in the bridge's forwarders. It is
2312
+ * the counter-seeded baseline, the session's activations, the context tier's
2313
+ * window, and the project's pins; the same four sources the assembly-side
2314
+ * `wanted` set is built from, so the two cannot drift.
2315
+ * @param state - the session to read.
2316
+ * @returns the offered public names.
2317
+ */
2318
+ private offeredNamesOf;
2319
+ /**
2320
+ * Ask the llm service what the session's current route can do with tool
2321
+ * declarations, and re-present the session when the answer moves.
2322
+ *
2323
+ * One answer per route, keyed by `provider/model`: the service resolves it from
2324
+ * the adapter, which is not something to ask on every step. `toolUpdate` is the
2325
+ * one capability read here — `undefined` on a route means the harness sends the
2326
+ * complete current declaration list in every request and strips the deferral
2327
+ * marker, so the presentation cannot hide a tool that way at all.
2328
+ *
2329
+ * A service that is absent (a host without `ctx.llm`, a test composition) or an
2330
+ * answer that never arrives leaves the capability `undefined`, and the
2331
+ * presentation keeps the deferral path it shipped with rather than guessing.
2332
+ * @param state - the session whose route is being read.
2333
+ * @param selection - the step's captured selection; absent resolves nothing.
2334
+ */
2335
+ private resolveRoute;
2336
+ /**
2337
+ * The names one session presents as deferred: what it mounts that it does not
2338
+ * offer.
2339
+ *
2340
+ * Empty when there is nothing to defer — activation off, `direct`, or a
2341
+ * surface that fits the budget — because deferring a schema the request would
2342
+ * have carried anyway only makes the declaration list harder to read, and the
2343
+ * prefix-cache argument for it is gone. The budget is the same
2344
+ * {@link surfaceChars} reading the panel and the assembly gate use, so the
2345
+ * deferred set and the "hidden" number a panel shows are one decision.
2346
+ * @param state - the session whose presentation is being registered.
2347
+ * @returns the names whose forwarders carry `deferLoading`, in registry order.
2348
+ */
2349
+ private deferredNamesOf;
2227
2350
  /**
2228
2351
  * Whether one project root has a live session on this host.
2229
2352
  * @param projectRoot - project root a policy request names.
@@ -3275,6 +3398,17 @@ interface GuidanceInput {
3275
3398
  readonly mostUsed?: readonly string[];
3276
3399
  /** Whether the on-demand search surface is on; defaults to the activation default. */
3277
3400
  readonly activationEnabled?: boolean;
3401
+ /**
3402
+ * Whether a deferred tool can still be called by its exact full name.
3403
+ *
3404
+ * It can on a route that accepts tool declarations after the first request:
3405
+ * the schema is hidden from the model and the registry keeps the tool
3406
+ * admitted, so `mcp__server__tool` executes. On a route without that
3407
+ * capability the tool is simply not declared, and a call by name answers
3408
+ * "unknown tool" — the names line must then send the model through the search
3409
+ * instead of promising the call. Defaults to `true`, the shipped capability.
3410
+ */
3411
+ readonly directCalls?: boolean;
3278
3412
  }
3279
3413
  /**
3280
3414
  * Build the project-MCP guidance section.
package/lib/index.js CHANGED
@@ -882,6 +882,7 @@ function installActivation(options) {
882
882
  if (next === tracker.state) return;
883
883
  tracker.state = next;
884
884
  options.setAutoState?.(next);
885
+ options.onOfferedChanged?.();
885
886
  };
886
887
  /** Every name the session's explicit activation and context-driven tiers offer. */
887
888
  const offeredNames = () => {
@@ -931,6 +932,7 @@ function installActivation(options) {
931
932
  * continuation's value comes back by identity.
932
933
  */
933
934
  const contain = (result) => {
935
+ if (!Array.isArray(result.tools)) return result;
934
936
  const foreign = options.foreign?.() ?? NO_FOREIGN;
935
937
  if (foreign.size === 0) return result;
936
938
  const kept = result.tools.filter((tool) => !foreign.has(tool.name));
@@ -954,9 +956,13 @@ function installActivation(options) {
954
956
  return foreign.size === 0 ? surface : surface.filter((schema) => !foreign.has(schema.name));
955
957
  };
956
958
  const merge = (result) => {
959
+ const policy = options.policy?.() ?? DEFAULT_TOOL_POLICY;
960
+ if (!Array.isArray(result.tools)) {
961
+ if (policy.mode === "disclosure") advance();
962
+ return result;
963
+ }
957
964
  const surface = wholeSurface();
958
965
  if (surface.length === 0) return contain(result);
959
- const policy = options.policy?.() ?? DEFAULT_TOOL_POLICY;
960
966
  if (policy.mode === "off") {
961
967
  const mounted = options.available();
962
968
  if (mounted.length === 0) return contain(result);
@@ -998,6 +1004,7 @@ function installActivation(options) {
998
1004
  tracker.state = resetAutoOffer(tracker.state);
999
1005
  tracker.calls = [];
1000
1006
  tracker.changed = false;
1007
+ options.onOfferedChanged?.();
1001
1008
  return;
1002
1009
  }
1003
1010
  if (event?.type === "user/message") {
@@ -1025,6 +1032,7 @@ function installActivation(options) {
1025
1032
  activate: (names) => {
1026
1033
  recordActivated(names);
1027
1034
  options.setState(activate(options.state(), names, Date.now()));
1035
+ options.onOfferedChanged?.();
1028
1036
  },
1029
1037
  ...options.searchLimit === void 0 ? {} : { defaultLimit: options.searchLimit }
1030
1038
  });
@@ -1853,7 +1861,7 @@ function buildGuidance(input) {
1853
1861
  if (activationEnabled && hot !== "") tail.push("", hot);
1854
1862
  if (deferred.size > 0) {
1855
1863
  tail.push("", onDemandParagraph(offered.size, deferred.size));
1856
- tail.push("", hiddenNamesLine(deferred));
1864
+ tail.push("", hiddenNamesLine(deferred, input.directCalls ?? true));
1857
1865
  }
1858
1866
  const bullets = [];
1859
1867
  let hidden = 0;
@@ -1972,17 +1980,27 @@ function serverBullet(server) {
1972
1980
  * deduped, truncated to {@link MAX_GUIDANCE_HIDDEN_NAMES} with a `+N more`.
1973
1981
  * Descriptions and schemas are the expensive part, so the line carries names
1974
1982
  * only — the model picks the one it needs and runs a single targeted search
1975
- * instead of rephrasing blind guesses. The sentence also states the
1976
- * direct-call contract: deferral trims the assembled request list, it never
1977
- * unregisters the tool, so a call by the exact full name still executes;
1978
- * searching the name first is how the model sees the description and
1979
- * parameters, not a gate.
1980
- */
1981
- function hiddenNamesLine(deferred) {
1983
+ * instead of rephrasing blind guesses.
1984
+ *
1985
+ * The tail sentence is the one place the route changes the advice. Where the
1986
+ * harness can declare a tool after the first request, deferral only trims the
1987
+ * request list — the tool stays registered, so a call by its exact full name
1988
+ * still executes and the search is how the model reads the description, not a
1989
+ * gate. Where it cannot, the tool is not declared at all: the name no longer
1990
+ * exists for the turn, and the model has to search first, so promising the
1991
+ * direct call there would send it into an "unknown tool" error.
1992
+ * @param deferred - names reachable only through the discovery tool right now.
1993
+ * @param directCalls - whether an exact-name call still executes (§
1994
+ * `GuidanceInput.directCalls`).
1995
+ * @returns one line, or an empty string when nothing is deferred.
1996
+ */
1997
+ function hiddenNamesLine(deferred, directCalls) {
1982
1998
  const names = [...deferred].sort(compareNames);
1983
1999
  const shown = names.slice(0, 12);
1984
2000
  const hidden = names.length - shown.length;
1985
- return `On demand right now: ${hidden === 0 ? shown.join(", ") : `${shown.join(", ")} +${hidden} more`} — every one of them runs when called by its exact full name \`mcp__<server>__<tool>\`; search a name with \`${SEARCH_TOOL_NAME}\` first to see its description and parameters.`;
2001
+ const list = hidden === 0 ? shown.join(", ") : `${shown.join(", ")} +${hidden} more`;
2002
+ if (!directCalls) return `On demand right now: ${list} — none of them is in this request, so ask for one with \`${SEARCH_TOOL_NAME}\` (a keyword or the name) and it becomes callable from the next step on.`;
2003
+ return `On demand right now: ${list} — every one of them runs when called by its exact full name \`mcp__<server>__<tool>\`; search a name with \`${SEARCH_TOOL_NAME}\` first to see its description and parameters.`;
1986
2004
  }
1987
2005
  /** The paragraph that turns "a tool is missing" into "ask for it". */
1988
2006
  function onDemandParagraph(offered, deferred) {
@@ -2494,11 +2512,14 @@ const FORWARDED_TO = Symbol("dsh-project-mcp.forwarded-to");
2494
2512
  * dispatch would apply pre-execute listeners and guards twice.
2495
2513
  * @param project - the definition to forward, read for its surface.
2496
2514
  * @param lookup - resolves the current project definition of this name.
2515
+ * @param deferred - whether this forwarder asks for deferred loading, so the
2516
+ * model's tool list leaves it out while the registry keeps it callable.
2497
2517
  * @returns the definition to register in a session's layer.
2498
2518
  */
2499
- function forwarder(project, lookup) {
2519
+ function forwarder(project, lookup, deferred) {
2500
2520
  return Object.assign({
2501
2521
  ...project,
2522
+ ...deferred ? { deferLoading: true } : {},
2502
2523
  async execute(args, exec) {
2503
2524
  const live = lookup();
2504
2525
  if (live === void 0) throw new Error(`the project's "${project.name}" is no longer registered; the shared instance was released or replaced`);
@@ -2523,7 +2544,7 @@ function forwardProjectTools(options) {
2523
2544
  const project = options.registry.get(name, options.project);
2524
2545
  if (project === void 0) continue;
2525
2546
  try {
2526
- disposes.push(tools.register(forwarder(project, () => options.registry.get(name, options.project))));
2547
+ disposes.push(tools.register(forwarder(project, () => options.registry.get(name, options.project), options.deferred?.(name) === true)));
2527
2548
  } catch {
2528
2549
  continue;
2529
2550
  }
@@ -2580,6 +2601,8 @@ var ForwardBatch = class {
2580
2601
  options;
2581
2602
  /** The names the live batch was registered for; `undefined` before the first pass. */
2582
2603
  #namesIn = void 0;
2604
+ /** The names the live batch registered as deferred; `undefined` with no live batch. */
2605
+ #deferredIn = void 0;
2583
2606
  /** Disposer of the live registration batch; `undefined` while none is live. */
2584
2607
  #release = void 0;
2585
2608
  /** Whether an owning frame is inside {@link sync}, registering right now. */
@@ -2702,12 +2725,14 @@ var ForwardBatch = class {
2702
2725
  #syncOnce() {
2703
2726
  const names = this.options.names();
2704
2727
  if (names === void 0) return;
2705
- if (this.#namesIn !== void 0 && sameNames(this.#namesIn, names)) return;
2728
+ const deferred = new Set(this.options.deferred?.() ?? []);
2729
+ if (this.#namesIn !== void 0 && sameNames(this.#namesIn, names) && sameNameSet(this.#deferredIn, deferred)) return;
2706
2730
  try {
2707
2731
  this.#releaseBatch();
2708
2732
  } catch {}
2709
- this.#release = this.options.register(names);
2733
+ this.#release = this.options.register(names, deferred);
2710
2734
  this.#namesIn = names;
2735
+ this.#deferredIn = deferred;
2711
2736
  }
2712
2737
  /**
2713
2738
  * Release the live batch and forget it.
@@ -2719,6 +2744,7 @@ var ForwardBatch = class {
2719
2744
  const release = this.#release;
2720
2745
  this.#release = void 0;
2721
2746
  this.#namesIn = void 0;
2747
+ this.#deferredIn = void 0;
2722
2748
  release?.();
2723
2749
  }
2724
2750
  };
@@ -2760,6 +2786,22 @@ function sameNames(left, right) {
2760
2786
  return left.length === right.length && left.every((name, index) => name === right[index]);
2761
2787
  }
2762
2788
  /**
2789
+ * Whether two deferred-name sets are the same set.
2790
+ *
2791
+ * The batch short-circuits a pass whose forwarded names did not move, and it
2792
+ * must not do that when the *deferred* subset moved instead: the flag rides in
2793
+ * the registered definition, so a stale batch presents a stale answer. Order
2794
+ * carries no meaning here, hence a set comparison rather than {@link sameNames}.
2795
+ * @param left - the deferred set of the live batch; `undefined` with no live batch.
2796
+ * @param right - the deferred set this pass read.
2797
+ * @returns whether the two describe the same names.
2798
+ */
2799
+ function sameNameSet(left, right) {
2800
+ if (left === void 0 || left.size !== right.size) return false;
2801
+ for (const name of right) if (!left.has(name)) return false;
2802
+ return true;
2803
+ }
2804
+ /**
2763
2805
  * One ring per project root, oldest event first.
2764
2806
  *
2765
2807
  * Kept per root because two projects of one host are two histories; the history
@@ -4200,6 +4242,7 @@ var ProjectMcpRuntime = class {
4200
4242
  messageParams: { projectRoot: request.projectRoot }
4201
4243
  };
4202
4244
  policy.setPin(request.projectRoot, request.tool, request.pinned);
4245
+ this.refreshPresentation(request.projectRoot);
4203
4246
  this.notify();
4204
4247
  return {
4205
4248
  ok: true,
@@ -4238,6 +4281,7 @@ var ProjectMcpRuntime = class {
4238
4281
  messageParams: { projectRoot: request.projectRoot }
4239
4282
  };
4240
4283
  policy.setMode(request.projectRoot, request.mode);
4284
+ this.refreshPresentation(request.projectRoot);
4241
4285
  this.notify();
4242
4286
  return {
4243
4287
  ok: true,
@@ -4303,6 +4347,98 @@ var ProjectMcpRuntime = class {
4303
4347
  return this.options.policy?.forProject(projectRoot) ?? DEFAULT_TOOL_POLICY;
4304
4348
  }
4305
4349
  /**
4350
+ * Re-apply the presentation of every session working in one project.
4351
+ *
4352
+ * A pin or a mode is read live by the panel and by the guidance, but the
4353
+ * forwarders carry their `deferLoading` flag from the pass that registered
4354
+ * them, so the sessions of that project have to run one — off the caller's
4355
+ * stack, like every other change note.
4356
+ * @param projectRoot - the project whose policy just moved.
4357
+ */
4358
+ refreshPresentation(projectRoot) {
4359
+ for (const state of this.states.values()) {
4360
+ if (state.projectRoot !== projectRoot) continue;
4361
+ state.bridge?.batch.note();
4362
+ }
4363
+ }
4364
+ /**
4365
+ * The names one session's presentation offers the model right now.
4366
+ *
4367
+ * The counterpart of the assembly wiring's own `offeredNames`, read where the
4368
+ * presentation lives outside that assembly — in the bridge's forwarders. It is
4369
+ * the counter-seeded baseline, the session's activations, the context tier's
4370
+ * window, and the project's pins; the same four sources the assembly-side
4371
+ * `wanted` set is built from, so the two cannot drift.
4372
+ * @param state - the session to read.
4373
+ * @returns the offered public names.
4374
+ */
4375
+ offeredNamesOf(state) {
4376
+ const names = new Set(presentedNames(this.seedActivation(state)));
4377
+ const auto = state.auto;
4378
+ if (auto !== void 0) for (const name of autoPresentedNames(auto)) names.add(name);
4379
+ for (const pin of this.policyFor(state.projectRoot).pins) names.add(pin);
4380
+ return names;
4381
+ }
4382
+ /**
4383
+ * Ask the llm service what the session's current route can do with tool
4384
+ * declarations, and re-present the session when the answer moves.
4385
+ *
4386
+ * One answer per route, keyed by `provider/model`: the service resolves it from
4387
+ * the adapter, which is not something to ask on every step. `toolUpdate` is the
4388
+ * one capability read here — `undefined` on a route means the harness sends the
4389
+ * complete current declaration list in every request and strips the deferral
4390
+ * marker, so the presentation cannot hide a tool that way at all.
4391
+ *
4392
+ * A service that is absent (a host without `ctx.llm`, a test composition) or an
4393
+ * answer that never arrives leaves the capability `undefined`, and the
4394
+ * presentation keeps the deferral path it shipped with rather than guessing.
4395
+ * @param state - the session whose route is being read.
4396
+ * @param selection - the step's captured selection; absent resolves nothing.
4397
+ */
4398
+ async resolveRoute(state, selection) {
4399
+ if (selection === void 0 || this.disposed) return;
4400
+ const key = `${selection.provider}/${selection.model}`;
4401
+ if (state.routeKey === key) return;
4402
+ state.routeKey = key;
4403
+ const llm = this.ctx.get("llm");
4404
+ if (typeof llm?.resolveModelInfo !== "function") return;
4405
+ try {
4406
+ const supported = (await llm.resolveModelInfo(selection.provider, selection.model))?.toolUpdate !== void 0;
4407
+ if (supported === state.toolUpdate) return;
4408
+ state.toolUpdate = supported;
4409
+ state.bridge?.batch.note();
4410
+ } catch (error) {
4411
+ this.ctx.logger.debug?.(`project-mcp: reading the model route of session ${state.agent.id} failed: ${errorText(error)}`);
4412
+ }
4413
+ }
4414
+ /**
4415
+ * The names one session presents as deferred: what it mounts that it does not
4416
+ * offer.
4417
+ *
4418
+ * Empty when there is nothing to defer — activation off, `direct`, or a
4419
+ * surface that fits the budget — because deferring a schema the request would
4420
+ * have carried anyway only makes the declaration list harder to read, and the
4421
+ * prefix-cache argument for it is gone. The budget is the same
4422
+ * {@link surfaceChars} reading the panel and the assembly gate use, so the
4423
+ * deferred set and the "hidden" number a panel shows are one decision.
4424
+ * @param state - the session whose presentation is being registered.
4425
+ * @returns the names whose forwarders carry `deferLoading`, in registry order.
4426
+ */
4427
+ deferredNamesOf(state) {
4428
+ if (!(this.config.activationEnabled ?? true)) return [];
4429
+ if (state.toolUpdate === false) return [];
4430
+ const policy = this.policyFor(state.projectRoot);
4431
+ if (policy.mode === "direct") return [];
4432
+ const home = this.homeOf(state);
4433
+ const mounted = home === void 0 ? [] : this.schemasOf(home, state.agent.id);
4434
+ if (policy.mode === "disclosure") {
4435
+ const budget = this.config.activationToolBudgetChars ?? 4e4;
4436
+ if (!overToolBudget(surfaceChars(mounted), budget)) return [];
4437
+ }
4438
+ const offered = this.offeredNamesOf(state);
4439
+ return mounted.map((schema) => schema.name).filter((name) => !offered.has(name));
4440
+ }
4441
+ /**
4306
4442
  * Whether one project root has a live session on this host.
4307
4443
  * @param projectRoot - project root a policy request names.
4308
4444
  * @returns `true` when a bound session resolved to that root.
@@ -4616,7 +4752,9 @@ var ProjectMcpRuntime = class {
4616
4752
  steps: /* @__PURE__ */ new Map(),
4617
4753
  activationDispose: void 0,
4618
4754
  guidanceDispose: void 0,
4619
- auto: void 0
4755
+ auto: void 0,
4756
+ routeKey: void 0,
4757
+ toolUpdate: void 0
4620
4758
  };
4621
4759
  }
4622
4760
  dropAgent(id) {
@@ -4954,6 +5092,7 @@ var ProjectMcpRuntime = class {
4954
5092
  state.step += 1;
4955
5093
  if (!this.disposed) {
4956
5094
  this.touch(state, { activate: true });
5095
+ this.resolveRoute(state, event.modelSelection);
4957
5096
  await this.awaitActivation(state);
4958
5097
  }
4959
5098
  }
@@ -5502,19 +5641,26 @@ var ProjectMcpRuntime = class {
5502
5641
  const project = state.project;
5503
5642
  if (project === void 0) return void 0;
5504
5643
  try {
5505
- return projectToolNames(project.key, (scope) => this.bridgeSchemas(scope), servers());
5644
+ const names = projectToolNames(project.key, (scope) => this.bridgeSchemas(scope), servers());
5645
+ if (state.toolUpdate === false) {
5646
+ const offered = this.offeredNamesOf(state);
5647
+ return names.filter((name) => offered.has(name));
5648
+ }
5649
+ return names;
5506
5650
  } catch (error) {
5507
5651
  this.ctx.logger.warn(`project-mcp: reading the tools to forward to session ${state.agent.id} failed: ${errorText(error)}`);
5508
5652
  return;
5509
5653
  }
5510
5654
  },
5511
- register: (names) => {
5655
+ deferred: () => this.deferredNamesOf(state),
5656
+ register: (names, deferred) => {
5512
5657
  const project = state.project;
5513
5658
  if (project === void 0) return () => void 0;
5514
5659
  return forwardProjectTools({
5515
5660
  ctx: context,
5516
5661
  project: project.key,
5517
5662
  names,
5663
+ deferred: (name) => deferred.has(name),
5518
5664
  registry
5519
5665
  });
5520
5666
  },
@@ -5700,6 +5846,7 @@ var ProjectMcpRuntime = class {
5700
5846
  visible: () => this.visibleSchemas(state),
5701
5847
  foreign: () => this.foreignNamesOf(state),
5702
5848
  policy: () => this.policyFor(state.projectRoot),
5849
+ onOfferedChanged: () => state.bridge?.batch.note(),
5703
5850
  step: () => state.step,
5704
5851
  onActivated: (names, step) => {
5705
5852
  for (const name of names) state.steps.set(name, step);
@@ -5890,7 +6037,8 @@ var ProjectMcpRuntime = class {
5890
6037
  offered,
5891
6038
  deferred,
5892
6039
  mostUsed,
5893
- activationEnabled
6040
+ activationEnabled,
6041
+ directCalls: state.toolUpdate !== false
5894
6042
  });
5895
6043
  } catch (error) {
5896
6044
  this.ctx.logger.warn(`project-mcp: building guidance for session ${agent.id} failed: ${errorText(error)}`);