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/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.2",
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/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
@@ -152,6 +152,13 @@ export interface AgentEventLike {
152
152
  agent: AgentLike
153
153
  /** `agent/status` only: whether a turn is currently running. */
154
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 }
155
162
  }
156
163
 
157
164
  /** The subset of the hosting scope used here. */
@@ -779,6 +786,27 @@ interface AgentState {
779
786
  * state outlives an idle release.
780
787
  */
781
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
782
810
  }
783
811
 
784
812
  interface CachedDocument {
@@ -1427,6 +1455,52 @@ export class ProjectMcpRuntime {
1427
1455
  return names
1428
1456
  }
1429
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
+
1430
1504
  /**
1431
1505
  * The names one session presents as deferred: what it mounts that it does not
1432
1506
  * offer.
@@ -1442,6 +1516,11 @@ export class ProjectMcpRuntime {
1442
1516
  */
1443
1517
  private deferredNamesOf(state: AgentState): readonly string[] {
1444
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 []
1445
1524
  const policy = this.policyFor(state.projectRoot)
1446
1525
  if (policy.mode === 'direct') return []
1447
1526
  // The home's catalog, read without {@link mountedSchemas}: this runs inside a
@@ -1827,6 +1906,8 @@ export class ProjectMcpRuntime {
1827
1906
  activationDispose: undefined,
1828
1907
  guidanceDispose: undefined,
1829
1908
  auto: undefined,
1909
+ routeKey: undefined,
1910
+ toolUpdate: undefined,
1830
1911
  }
1831
1912
  }
1832
1913
 
@@ -2207,6 +2288,10 @@ export class ProjectMcpRuntime {
2207
2288
  state.step += 1
2208
2289
  if (!this.disposed) {
2209
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)
2210
2295
  await this.awaitActivation(state)
2211
2296
  }
2212
2297
  }
@@ -2940,11 +3025,21 @@ export class ProjectMcpRuntime {
2940
3025
  // pass would forward names this session's project never published.
2941
3026
  if (project === undefined) return undefined
2942
3027
  try {
2943
- return projectToolNames(
3028
+ const names = projectToolNames(
2944
3029
  project.key,
2945
3030
  (scope) => this.bridgeSchemas(scope),
2946
3031
  servers(),
2947
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
2948
3043
  } catch (error) {
2949
3044
  // A probe that failed says nothing about the project's set: the batch
2950
3045
  // it could not describe is the batch that stays live.
@@ -3434,6 +3529,10 @@ export class ProjectMcpRuntime {
3434
3529
  deferred,
3435
3530
  mostUsed,
3436
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,
3437
3536
  })
3438
3537
  } catch (error) {
3439
3538
  this.ctx.logger.warn(