dsh-project-mcp 0.4.2 → 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
@@ -448,6 +448,21 @@ the flags level — a search activation, a compaction boundary, a context advanc
448
448
  and a policy edit each queue one coalesced bridge pass (`ForwardBatch.note`), and
449
449
  a pass re-registers only when the names *or* the deferred subset moved.
450
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
+
451
466
  On an older harness the same module still rewrites the assembly list, through the
452
467
  agent's own `system-prompt/assemble` waterfall, registered *prepended* so it runs
453
468
  outermost and sees the list after other presentation plugins (for example
package/lib/index.d.ts CHANGED
@@ -1582,6 +1582,16 @@ interface AgentEventLike {
1582
1582
  agent: AgentLike;
1583
1583
  /** `agent/status` only: whether a turn is currently running. */
1584
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
+ };
1585
1595
  }
1586
1596
  /** The subset of the hosting scope used here. */
1587
1597
  interface AgentScopeLike {
@@ -2041,6 +2051,27 @@ interface AgentState {
2041
2051
  * state outlives an idle release.
2042
2052
  */
2043
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;
2044
2075
  }
2045
2076
  /**
2046
2077
  * Owns every project-scoped mount, the config watchers, and the rescan timer.
@@ -2285,6 +2316,23 @@ export declare class ProjectMcpRuntime {
2285
2316
  * @returns the offered public names.
2286
2317
  */
2287
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;
2288
2336
  /**
2289
2337
  * The names one session presents as deferred: what it mounts that it does not
2290
2338
  * offer.
@@ -3350,6 +3398,17 @@ interface GuidanceInput {
3350
3398
  readonly mostUsed?: readonly string[];
3351
3399
  /** Whether the on-demand search surface is on; defaults to the activation default. */
3352
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;
3353
3412
  }
3354
3413
  /**
3355
3414
  * Build the project-MCP guidance section.
package/lib/index.js CHANGED
@@ -1861,7 +1861,7 @@ function buildGuidance(input) {
1861
1861
  if (activationEnabled && hot !== "") tail.push("", hot);
1862
1862
  if (deferred.size > 0) {
1863
1863
  tail.push("", onDemandParagraph(offered.size, deferred.size));
1864
- tail.push("", hiddenNamesLine(deferred));
1864
+ tail.push("", hiddenNamesLine(deferred, input.directCalls ?? true));
1865
1865
  }
1866
1866
  const bullets = [];
1867
1867
  let hidden = 0;
@@ -1980,17 +1980,27 @@ function serverBullet(server) {
1980
1980
  * deduped, truncated to {@link MAX_GUIDANCE_HIDDEN_NAMES} with a `+N more`.
1981
1981
  * Descriptions and schemas are the expensive part, so the line carries names
1982
1982
  * only — the model picks the one it needs and runs a single targeted search
1983
- * instead of rephrasing blind guesses. The sentence also states the
1984
- * direct-call contract: deferral trims the assembled request list, it never
1985
- * unregisters the tool, so a call by the exact full name still executes;
1986
- * searching the name first is how the model sees the description and
1987
- * parameters, not a gate.
1988
- */
1989
- 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) {
1990
1998
  const names = [...deferred].sort(compareNames);
1991
1999
  const shown = names.slice(0, 12);
1992
2000
  const hidden = names.length - shown.length;
1993
- 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.`;
1994
2004
  }
1995
2005
  /** The paragraph that turns "a tool is missing" into "ask for it". */
1996
2006
  function onDemandParagraph(offered, deferred) {
@@ -4370,6 +4380,38 @@ var ProjectMcpRuntime = class {
4370
4380
  return names;
4371
4381
  }
4372
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
+ /**
4373
4415
  * The names one session presents as deferred: what it mounts that it does not
4374
4416
  * offer.
4375
4417
  *
@@ -4384,6 +4426,7 @@ var ProjectMcpRuntime = class {
4384
4426
  */
4385
4427
  deferredNamesOf(state) {
4386
4428
  if (!(this.config.activationEnabled ?? true)) return [];
4429
+ if (state.toolUpdate === false) return [];
4387
4430
  const policy = this.policyFor(state.projectRoot);
4388
4431
  if (policy.mode === "direct") return [];
4389
4432
  const home = this.homeOf(state);
@@ -4709,7 +4752,9 @@ var ProjectMcpRuntime = class {
4709
4752
  steps: /* @__PURE__ */ new Map(),
4710
4753
  activationDispose: void 0,
4711
4754
  guidanceDispose: void 0,
4712
- auto: void 0
4755
+ auto: void 0,
4756
+ routeKey: void 0,
4757
+ toolUpdate: void 0
4713
4758
  };
4714
4759
  }
4715
4760
  dropAgent(id) {
@@ -5047,6 +5092,7 @@ var ProjectMcpRuntime = class {
5047
5092
  state.step += 1;
5048
5093
  if (!this.disposed) {
5049
5094
  this.touch(state, { activate: true });
5095
+ this.resolveRoute(state, event.modelSelection);
5050
5096
  await this.awaitActivation(state);
5051
5097
  }
5052
5098
  }
@@ -5595,7 +5641,12 @@ var ProjectMcpRuntime = class {
5595
5641
  const project = state.project;
5596
5642
  if (project === void 0) return void 0;
5597
5643
  try {
5598
- 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;
5599
5650
  } catch (error) {
5600
5651
  this.ctx.logger.warn(`project-mcp: reading the tools to forward to session ${state.agent.id} failed: ${errorText(error)}`);
5601
5652
  return;
@@ -5986,7 +6037,8 @@ var ProjectMcpRuntime = class {
5986
6037
  offered,
5987
6038
  deferred,
5988
6039
  mostUsed,
5989
- activationEnabled
6040
+ activationEnabled,
6041
+ directCalls: state.toolUpdate !== false
5990
6042
  });
5991
6043
  } catch (error) {
5992
6044
  this.ctx.logger.warn(`project-mcp: building guidance for session ${agent.id} failed: ${errorText(error)}`);