dsh-project-mcp 0.4.2 → 0.5.0

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,27 @@ 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
+ Both lines are also judged against the step's own admission: `systemPrompt`
464
+ hands a section the context its step was prepared with, including the `toolSet`
465
+ `ctx.tools.resolve()` froze, and a tool registered between that snapshot and the
466
+ prompt assembly (a server that just connected) is named by the registry but not
467
+ callable in that step — so the section leaves it out rather than promising a
468
+ call that would answer `unknown tool`.
469
+ The first request of a session is always the wide one: the route is learned on
470
+ the first step, and the pass that follows trims the layer.
471
+
451
472
  On an older harness the same module still rewrites the assembly list, through the
452
473
  agent's own `system-prompt/assemble` waterfall, registered *prepended* so it runs
453
474
  outermost and sees the list after other presentation plugins (for example
@@ -511,7 +532,9 @@ description and parameters.
511
532
  probing blindly. The line also states the direct-call contract — deferral
512
533
  trims the assembled request list, it never unregisters the tool, so a call by
513
534
  the exact full name `mcp__<server>__<tool>` still executes; searching first
514
- is how the model sees the description and parameters, not a gate.
535
+ is how the model sees the description and parameters, not a gate. A name the
536
+ step did not admit is not listed at all, so the line never promises more than
537
+ the step's own tool set can answer.
515
538
  - **A most-used line from the durable counters.** When the seeded baseline is
516
539
  non-empty, the section names the project's hot tools (most-called first, up
517
540
  to four names with `+N more`) and says they are offered from the first step
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.
@@ -2869,9 +2917,17 @@ export declare class ProjectMcpRuntime {
2869
2917
  *
2870
2918
  * It reads the mount records and the registry at every assembly, so a rescan
2871
2919
  * that mounted or dropped a server — and a search that activated a tool — are
2872
- * reflected without re-registering the section. Total: any failure returns the
2873
- * empty string, because a section that throws would fail the model request
2874
- * that asked for the assembly.
2920
+ * reflected without re-registering the section. The assembly's own admission
2921
+ * snapshot is authoritative when it is present: a tool registered after the
2922
+ * step was prepared is already named by the registry but cannot be called in
2923
+ * that step, so the text does not promise it ({@link admittedNames}). Total:
2924
+ * any failure returns the empty string, because a section that throws would
2925
+ * fail the model request that asked for the assembly.
2926
+ *
2927
+ * @param agent - session whose scope the section belongs to.
2928
+ * @param state - the session's live state.
2929
+ * @param assembly - the assembly context, when the host hands one.
2930
+ * @returns the section text, or `''` when there is nothing true to say.
2875
2931
  */
2876
2932
  private guidanceText;
2877
2933
  /**
@@ -3350,6 +3406,17 @@ interface GuidanceInput {
3350
3406
  readonly mostUsed?: readonly string[];
3351
3407
  /** Whether the on-demand search surface is on; defaults to the activation default. */
3352
3408
  readonly activationEnabled?: boolean;
3409
+ /**
3410
+ * Whether a deferred tool can still be called by its exact full name.
3411
+ *
3412
+ * It can on a route that accepts tool declarations after the first request:
3413
+ * the schema is hidden from the model and the registry keeps the tool
3414
+ * admitted, so `mcp__server__tool` executes. On a route without that
3415
+ * capability the tool is simply not declared, and a call by name answers
3416
+ * "unknown tool" — the names line must then send the model through the search
3417
+ * instead of promising the call. Defaults to `true`, the shipped capability.
3418
+ */
3419
+ readonly directCalls?: boolean;
3353
3420
  }
3354
3421
  /**
3355
3422
  * Build the project-MCP guidance section.
@@ -3387,8 +3454,27 @@ interface GuidanceSectionLike {
3387
3454
  readonly order: number;
3388
3455
  /** `false` preserves literal text; this section carries no variables. */
3389
3456
  readonly interpolate?: boolean;
3390
- /** Text, or a provider evaluated at each assembly. */
3391
- readonly text: string | (() => string);
3457
+ /** Text, or a provider evaluated at each assembly with that assembly's context. */
3458
+ readonly text: string | ((assembly?: GuidanceAssemblyLike) => string);
3459
+ }
3460
+ /**
3461
+ * The assembly-context slice this wiring reads: the step's frozen tool
3462
+ * admission.
3463
+ *
3464
+ * `systemPrompt.assemble()` hands sections the same context the step was
3465
+ * prepared with, including the `toolSet` that `ctx.tools.resolve()` produced —
3466
+ * the definitions admitted for *this* step. Naming a tool in the guidance text
3467
+ * while it is absent from that snapshot is the one way the section can promise
3468
+ * a call that answers `unknown tool`, so the text is filtered against it.
3469
+ * Declared structurally, like every other harness type in this module.
3470
+ */
3471
+ interface GuidanceAssemblyLike {
3472
+ /** Scope whose providers participate; `toolSet.view()` admits only this exact key. */
3473
+ readonly scope?: unknown;
3474
+ /** Step-owned admission; absent on an older host or a bare test stub. */
3475
+ readonly toolSet?: {
3476
+ view(scope: unknown): ReadonlyMap<string, unknown>;
3477
+ };
3392
3478
  }
3393
3479
  /** The `systemPrompt` slice the wiring reads (structural view). */
3394
3480
  interface GuidancePromptLike {
@@ -3428,8 +3514,12 @@ interface GuidanceContextLike {
3428
3514
  interface GuidanceWiringOptions {
3429
3515
  /** Agent-scoped context; the section lives here. */
3430
3516
  readonly ctx: GuidanceContextLike;
3431
- /** Live section text; called at every assembly, so it may read changing state. */
3432
- readonly text: () => string;
3517
+ /**
3518
+ * Live section text; called at every assembly, so it may read changing state.
3519
+ * The assembly context is passed through, so the text can judge its promises
3520
+ * against that step's admission ({@link admittedNames}).
3521
+ */
3522
+ readonly text: (assembly?: GuidanceAssemblyLike) => string;
3433
3523
  /** Section name override; defaults to {@link GUIDANCE_SECTION_NAME}. */
3434
3524
  readonly name?: string;
3435
3525
  /** Sink for a contained failure of this plugin's own work. */
package/lib/index.js CHANGED
@@ -1167,6 +1167,8 @@ const REFERENCE_PATTERN = /\$\{([^}]+)\}/g;
1167
1167
  const INPUT_PREFIX = "input:";
1168
1168
  /** Maximum length of a generated `serverName`. */
1169
1169
  const MAX_SERVER_NAME_LENGTH$1 = 32;
1170
+ /** `closeTimeoutMs` of a resolved mcp-client config; the client's own schema default, never overridden here. */
1171
+ const MCP_CLOSE_TIMEOUT_MS = 5e3;
1170
1172
  /** Expand every `${...}` reference inside `value`. */
1171
1173
  function expandValue(value, ctx) {
1172
1174
  const whole = WHOLE_REF_PATTERN.exec(value);
@@ -1449,6 +1451,8 @@ function buildStdioEntry(name, record, source, ctx, issues, enabled) {
1449
1451
  env: expandedEnv.value,
1450
1452
  cwd: expandedCwd.value,
1451
1453
  toolCallTimeoutMs: ctx.toolCallTimeoutMs,
1454
+ closeTimeoutMs: MCP_CLOSE_TIMEOUT_MS,
1455
+ expandTemplates: false,
1452
1456
  failOnStartupError: ctx.failOnStartupError
1453
1457
  }
1454
1458
  };
@@ -1472,6 +1476,8 @@ function buildHttpEntry(name, record, source, ctx, issues, enabled) {
1472
1476
  url: expandedUrl.value,
1473
1477
  headers: expandedHeaders.value,
1474
1478
  toolCallTimeoutMs: ctx.toolCallTimeoutMs,
1479
+ closeTimeoutMs: MCP_CLOSE_TIMEOUT_MS,
1480
+ expandTemplates: false,
1475
1481
  failOnStartupError: ctx.failOnStartupError
1476
1482
  }
1477
1483
  };
@@ -1861,7 +1867,7 @@ function buildGuidance(input) {
1861
1867
  if (activationEnabled && hot !== "") tail.push("", hot);
1862
1868
  if (deferred.size > 0) {
1863
1869
  tail.push("", onDemandParagraph(offered.size, deferred.size));
1864
- tail.push("", hiddenNamesLine(deferred));
1870
+ tail.push("", hiddenNamesLine(deferred, input.directCalls ?? true));
1865
1871
  }
1866
1872
  const bullets = [];
1867
1873
  let hidden = 0;
@@ -1915,6 +1921,19 @@ function projectLabel(projectRoot, home) {
1915
1921
  return index === -1 ? root : root.slice(index + 1);
1916
1922
  }
1917
1923
  /**
1924
+ * The public tool names this step's admission actually carries.
1925
+ *
1926
+ * @param assembly - the section's assembly context, when the host hands one.
1927
+ * @returns the admitted names, or `undefined` when there is no snapshot to
1928
+ * judge by — then nothing is filtered and the text is built from live state.
1929
+ */
1930
+ function admittedNames(assembly) {
1931
+ const set = assembly?.toolSet;
1932
+ const scope = assembly?.scope;
1933
+ if (set === void 0 || scope === void 0) return void 0;
1934
+ return new Set(set.view(scope).keys());
1935
+ }
1936
+ /**
1918
1937
  * Register the guidance section on one agent scope.
1919
1938
  *
1920
1939
  * The section goes in through `ctx.inject(['systemPrompt'], …)`, so the scope
@@ -1980,17 +1999,27 @@ function serverBullet(server) {
1980
1999
  * deduped, truncated to {@link MAX_GUIDANCE_HIDDEN_NAMES} with a `+N more`.
1981
2000
  * Descriptions and schemas are the expensive part, so the line carries names
1982
2001
  * 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) {
2002
+ * instead of rephrasing blind guesses.
2003
+ *
2004
+ * The tail sentence is the one place the route changes the advice. Where the
2005
+ * harness can declare a tool after the first request, deferral only trims the
2006
+ * request list — the tool stays registered, so a call by its exact full name
2007
+ * still executes and the search is how the model reads the description, not a
2008
+ * gate. Where it cannot, the tool is not declared at all: the name no longer
2009
+ * exists for the turn, and the model has to search first, so promising the
2010
+ * direct call there would send it into an "unknown tool" error.
2011
+ * @param deferred - names reachable only through the discovery tool right now.
2012
+ * @param directCalls - whether an exact-name call still executes (§
2013
+ * `GuidanceInput.directCalls`).
2014
+ * @returns one line, or an empty string when nothing is deferred.
2015
+ */
2016
+ function hiddenNamesLine(deferred, directCalls) {
1990
2017
  const names = [...deferred].sort(compareNames);
1991
2018
  const shown = names.slice(0, 12);
1992
2019
  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.`;
2020
+ const list = hidden === 0 ? shown.join(", ") : `${shown.join(", ")} +${hidden} more`;
2021
+ 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.`;
2022
+ 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
2023
  }
1995
2024
  /** The paragraph that turns "a tool is missing" into "ask for it". */
1996
2025
  function onDemandParagraph(offered, deferred) {
@@ -4370,6 +4399,38 @@ var ProjectMcpRuntime = class {
4370
4399
  return names;
4371
4400
  }
4372
4401
  /**
4402
+ * Ask the llm service what the session's current route can do with tool
4403
+ * declarations, and re-present the session when the answer moves.
4404
+ *
4405
+ * One answer per route, keyed by `provider/model`: the service resolves it from
4406
+ * the adapter, which is not something to ask on every step. `toolUpdate` is the
4407
+ * one capability read here — `undefined` on a route means the harness sends the
4408
+ * complete current declaration list in every request and strips the deferral
4409
+ * marker, so the presentation cannot hide a tool that way at all.
4410
+ *
4411
+ * A service that is absent (a host without `ctx.llm`, a test composition) or an
4412
+ * answer that never arrives leaves the capability `undefined`, and the
4413
+ * presentation keeps the deferral path it shipped with rather than guessing.
4414
+ * @param state - the session whose route is being read.
4415
+ * @param selection - the step's captured selection; absent resolves nothing.
4416
+ */
4417
+ async resolveRoute(state, selection) {
4418
+ if (selection === void 0 || this.disposed) return;
4419
+ const key = `${selection.provider}/${selection.model}`;
4420
+ if (state.routeKey === key) return;
4421
+ state.routeKey = key;
4422
+ const llm = this.ctx.get("llm");
4423
+ if (typeof llm?.resolveModelInfo !== "function") return;
4424
+ try {
4425
+ const supported = (await llm.resolveModelInfo(selection.provider, selection.model))?.toolUpdate !== void 0;
4426
+ if (supported === state.toolUpdate) return;
4427
+ state.toolUpdate = supported;
4428
+ state.bridge?.batch.note();
4429
+ } catch (error) {
4430
+ this.ctx.logger.debug?.(`project-mcp: reading the model route of session ${state.agent.id} failed: ${errorText(error)}`);
4431
+ }
4432
+ }
4433
+ /**
4373
4434
  * The names one session presents as deferred: what it mounts that it does not
4374
4435
  * offer.
4375
4436
  *
@@ -4384,6 +4445,7 @@ var ProjectMcpRuntime = class {
4384
4445
  */
4385
4446
  deferredNamesOf(state) {
4386
4447
  if (!(this.config.activationEnabled ?? true)) return [];
4448
+ if (state.toolUpdate === false) return [];
4387
4449
  const policy = this.policyFor(state.projectRoot);
4388
4450
  if (policy.mode === "direct") return [];
4389
4451
  const home = this.homeOf(state);
@@ -4709,7 +4771,9 @@ var ProjectMcpRuntime = class {
4709
4771
  steps: /* @__PURE__ */ new Map(),
4710
4772
  activationDispose: void 0,
4711
4773
  guidanceDispose: void 0,
4712
- auto: void 0
4774
+ auto: void 0,
4775
+ routeKey: void 0,
4776
+ toolUpdate: void 0
4713
4777
  };
4714
4778
  }
4715
4779
  dropAgent(id) {
@@ -5047,6 +5111,7 @@ var ProjectMcpRuntime = class {
5047
5111
  state.step += 1;
5048
5112
  if (!this.disposed) {
5049
5113
  this.touch(state, { activate: true });
5114
+ this.resolveRoute(state, event.modelSelection);
5050
5115
  await this.awaitActivation(state);
5051
5116
  }
5052
5117
  }
@@ -5595,7 +5660,12 @@ var ProjectMcpRuntime = class {
5595
5660
  const project = state.project;
5596
5661
  if (project === void 0) return void 0;
5597
5662
  try {
5598
- return projectToolNames(project.key, (scope) => this.bridgeSchemas(scope), servers());
5663
+ const names = projectToolNames(project.key, (scope) => this.bridgeSchemas(scope), servers());
5664
+ if (state.toolUpdate === false) {
5665
+ const offered = this.offeredNamesOf(state);
5666
+ return names.filter((name) => offered.has(name));
5667
+ }
5668
+ return names;
5599
5669
  } catch (error) {
5600
5670
  this.ctx.logger.warn(`project-mcp: reading the tools to forward to session ${state.agent.id} failed: ${errorText(error)}`);
5601
5671
  return;
@@ -5775,7 +5845,7 @@ var ProjectMcpRuntime = class {
5775
5845
  if (this.config.guidanceEnabled ?? true) try {
5776
5846
  state.guidanceDispose = installGuidance({
5777
5847
  ctx: scope.ctx,
5778
- text: () => this.guidanceText(agent, state),
5848
+ text: (assembly) => this.guidanceText(agent, state, assembly),
5779
5849
  onError: (error) => {
5780
5850
  this.ctx.logger.warn(`project-mcp: guidance section failed for session ${agent.id}: ${errorText(error)}`);
5781
5851
  }
@@ -5945,14 +6015,23 @@ var ProjectMcpRuntime = class {
5945
6015
  *
5946
6016
  * It reads the mount records and the registry at every assembly, so a rescan
5947
6017
  * that mounted or dropped a server — and a search that activated a tool — are
5948
- * reflected without re-registering the section. Total: any failure returns the
5949
- * empty string, because a section that throws would fail the model request
5950
- * that asked for the assembly.
6018
+ * reflected without re-registering the section. The assembly's own admission
6019
+ * snapshot is authoritative when it is present: a tool registered after the
6020
+ * step was prepared is already named by the registry but cannot be called in
6021
+ * that step, so the text does not promise it ({@link admittedNames}). Total:
6022
+ * any failure returns the empty string, because a section that throws would
6023
+ * fail the model request that asked for the assembly.
6024
+ *
6025
+ * @param agent - session whose scope the section belongs to.
6026
+ * @param state - the session's live state.
6027
+ * @param assembly - the assembly context, when the host hands one.
6028
+ * @returns the section text, or `''` when there is nothing true to say.
5951
6029
  */
5952
- guidanceText(agent, state) {
6030
+ guidanceText(agent, state, assembly) {
5953
6031
  try {
5954
6032
  const projectRoot = state.projectRoot;
5955
6033
  if (projectRoot === void 0 || this.mountsOf(state).size === 0) return "";
6034
+ const admitted = admittedNames(assembly);
5956
6035
  const activationEnabled = this.config.activationEnabled ?? true;
5957
6036
  const presented = activationEnabled ? presentedNames(this.seedActivation(state)) : void 0;
5958
6037
  const mounted = new Set([...this.mountsOf(state).values()].map((mount) => mount.runtimeName));
@@ -5960,6 +6039,7 @@ var ProjectMcpRuntime = class {
5960
6039
  const offered = [];
5961
6040
  const deferred = [];
5962
6041
  for (const schema of this.mountedSchemas(state)) {
6042
+ if (admitted !== void 0 && !admitted.has(schema.name)) continue;
5963
6043
  const server = matchServer(schema.name, mounted);
5964
6044
  if (server === void 0) continue;
5965
6045
  const name = schema.name.slice(`mcp__${server}__`.length);
@@ -5977,6 +6057,7 @@ var ProjectMcpRuntime = class {
5977
6057
  }));
5978
6058
  const mostUsed = [];
5979
6059
  if (activationEnabled) for (const fullName of this.seedActivation(state).baseline) {
6060
+ if (admitted !== void 0 && !admitted.has(fullName)) continue;
5980
6061
  const server = matchServer(fullName, mounted);
5981
6062
  if (server !== void 0) mostUsed.push(fullName.slice(`mcp__${server}__`.length));
5982
6063
  }
@@ -5986,7 +6067,8 @@ var ProjectMcpRuntime = class {
5986
6067
  offered,
5987
6068
  deferred,
5988
6069
  mostUsed,
5989
- activationEnabled
6070
+ activationEnabled,
6071
+ directCalls: state.toolUpdate !== false
5990
6072
  });
5991
6073
  } catch (error) {
5992
6074
  this.ctx.logger.warn(`project-mcp: building guidance for session ${agent.id} failed: ${errorText(error)}`);