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/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.5.0",
5
5
  "type": "module",
6
6
  "main": "lib/index.js",
7
7
  "types": "lib/index.d.ts",
@@ -86,10 +86,10 @@
86
86
  }
87
87
  },
88
88
  "devDependencies": {
89
- "@deepseek-ai/cordis": "4.0.4",
90
- "@deepseek-ai/dsh-mcp-client": "0.2.0-rc.2",
91
- "@deepseek-ai/dsh-scope": "0.2.0-rc.2",
92
- "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
89
+ "@deepseek-ai/cordis": "4.1.0",
90
+ "@deepseek-ai/dsh-mcp-client": "0.2.2-rc.4",
91
+ "@deepseek-ai/dsh-scope": "0.2.2-rc.4",
92
+ "@deepseek-ai/dsh-tools": "0.2.2-rc.4",
93
93
  "@types/node": "^22.20.4",
94
94
  "@types/react": "^18.3.31",
95
95
  "@vitest/coverage-v8": "^5.0.2",
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
@@ -189,8 +200,42 @@ export interface GuidanceSectionLike {
189
200
  readonly order: number
190
201
  /** `false` preserves literal text; this section carries no variables. */
191
202
  readonly interpolate?: boolean
192
- /** Text, or a provider evaluated at each assembly. */
193
- readonly text: string | (() => string)
203
+ /** Text, or a provider evaluated at each assembly with that assembly's context. */
204
+ readonly text: string | ((assembly?: GuidanceAssemblyLike) => string)
205
+ }
206
+
207
+ /**
208
+ * The assembly-context slice this wiring reads: the step's frozen tool
209
+ * admission.
210
+ *
211
+ * `systemPrompt.assemble()` hands sections the same context the step was
212
+ * prepared with, including the `toolSet` that `ctx.tools.resolve()` produced —
213
+ * the definitions admitted for *this* step. Naming a tool in the guidance text
214
+ * while it is absent from that snapshot is the one way the section can promise
215
+ * a call that answers `unknown tool`, so the text is filtered against it.
216
+ * Declared structurally, like every other harness type in this module.
217
+ */
218
+ export interface GuidanceAssemblyLike {
219
+ /** Scope whose providers participate; `toolSet.view()` admits only this exact key. */
220
+ readonly scope?: unknown
221
+ /** Step-owned admission; absent on an older host or a bare test stub. */
222
+ readonly toolSet?: { view(scope: unknown): ReadonlyMap<string, unknown> }
223
+ }
224
+
225
+ /**
226
+ * The public tool names this step's admission actually carries.
227
+ *
228
+ * @param assembly - the section's assembly context, when the host hands one.
229
+ * @returns the admitted names, or `undefined` when there is no snapshot to
230
+ * judge by — then nothing is filtered and the text is built from live state.
231
+ */
232
+ export function admittedNames(assembly?: GuidanceAssemblyLike): ReadonlySet<string> | undefined {
233
+ const set = assembly?.toolSet
234
+ const scope = assembly?.scope
235
+ // `ResolvedToolSet.view()` admits only the exact requesting agent, so an
236
+ // assembly without its own scope has no admission this text may compare to.
237
+ if (set === undefined || scope === undefined) return undefined
238
+ return new Set(set.view(scope).keys())
194
239
  }
195
240
 
196
241
  /** The `systemPrompt` slice the wiring reads (structural view). */
@@ -234,8 +279,12 @@ export interface GuidanceContextLike {
234
279
  export interface GuidanceWiringOptions {
235
280
  /** Agent-scoped context; the section lives here. */
236
281
  readonly ctx: GuidanceContextLike
237
- /** Live section text; called at every assembly, so it may read changing state. */
238
- readonly text: () => string
282
+ /**
283
+ * Live section text; called at every assembly, so it may read changing state.
284
+ * The assembly context is passed through, so the text can judge its promises
285
+ * against that step's admission ({@link admittedNames}).
286
+ */
287
+ readonly text: (assembly?: GuidanceAssemblyLike) => string
239
288
  /** Section name override; defaults to {@link GUIDANCE_SECTION_NAME}. */
240
289
  readonly name?: string
241
290
  /** Sink for a contained failure of this plugin's own work. */
@@ -314,17 +363,32 @@ function serverBullet(server: GuidanceServer): string {
314
363
  * deduped, truncated to {@link MAX_GUIDANCE_HIDDEN_NAMES} with a `+N more`.
315
364
  * Descriptions and schemas are the expensive part, so the line carries names
316
365
  * 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.
366
+ * instead of rephrasing blind guesses.
367
+ *
368
+ * The tail sentence is the one place the route changes the advice. Where the
369
+ * harness can declare a tool after the first request, deferral only trims the
370
+ * request list — the tool stays registered, so a call by its exact full name
371
+ * still executes and the search is how the model reads the description, not a
372
+ * gate. Where it cannot, the tool is not declared at all: the name no longer
373
+ * exists for the turn, and the model has to search first, so promising the
374
+ * direct call there would send it into an "unknown tool" error.
375
+ * @param deferred - names reachable only through the discovery tool right now.
376
+ * @param directCalls - whether an exact-name call still executes (§
377
+ * `GuidanceInput.directCalls`).
378
+ * @returns one line, or an empty string when nothing is deferred.
322
379
  */
323
- function hiddenNamesLine(deferred: ReadonlySet<string>): string {
380
+ function hiddenNamesLine(deferred: ReadonlySet<string>, directCalls: boolean): string {
324
381
  const names = [...deferred].sort(compareNames)
325
382
  const shown = names.slice(0, MAX_GUIDANCE_HIDDEN_NAMES)
326
383
  const hidden = names.length - shown.length
327
384
  const list = hidden === 0 ? shown.join(', ') : `${shown.join(', ')} +${hidden} more`
385
+ if (!directCalls) {
386
+ return (
387
+ `On demand right now: ${list} — none of them is in this request, so ask for one with ` +
388
+ `\`${SEARCH_TOOL_NAME}\` (a keyword or the name) and it becomes callable from the next ` +
389
+ 'step on.'
390
+ )
391
+ }
328
392
  return (
329
393
  `On demand right now: ${list} — every one of them runs when called by its exact full ` +
330
394
  `name \`mcp__<server>__<tool>\`; search a name with \`${SEARCH_TOOL_NAME}\` first to see ` +
package/src/parse.ts CHANGED
@@ -38,6 +38,9 @@ const INPUT_PREFIX = 'input:'
38
38
  /** Maximum length of a generated `serverName`. */
39
39
  const MAX_SERVER_NAME_LENGTH = 32
40
40
 
41
+ /** `closeTimeoutMs` of a resolved mcp-client config; the client's own schema default, never overridden here. */
42
+ const MCP_CLOSE_TIMEOUT_MS = 5000
43
+
41
44
  /** Severity of a parse diagnostic. */
42
45
  export type IssueLevel = 'error' | 'warning'
43
46
 
@@ -436,6 +439,10 @@ function buildStdioEntry(
436
439
  env: expandedEnv.value,
437
440
  cwd: expandedCwd.value,
438
441
  toolCallTimeoutMs: ctx.toolCallTimeoutMs,
442
+ closeTimeoutMs: MCP_CLOSE_TIMEOUT_MS,
443
+ // This parser expands `${input:…}` itself and hands literals to the
444
+ // client, so the client's own `${credential:…}` templates stay off.
445
+ expandTemplates: false,
439
446
  failOnStartupError: ctx.failOnStartupError,
440
447
  },
441
448
  }
@@ -471,6 +478,8 @@ function buildHttpEntry(
471
478
  url: expandedUrl.value,
472
479
  headers: expandedHeaders.value,
473
480
  toolCallTimeoutMs: ctx.toolCallTimeoutMs,
481
+ closeTimeoutMs: MCP_CLOSE_TIMEOUT_MS,
482
+ expandTemplates: false,
474
483
  failOnStartupError: ctx.failOnStartupError,
475
484
  },
476
485
  }
package/src/runtime.ts CHANGED
@@ -64,11 +64,12 @@ import {
64
64
  } from './discovery.ts'
65
65
  import {
66
66
  DEFAULT_GUIDANCE_ENABLED,
67
+ admittedNames,
67
68
  buildGuidance,
68
69
  installGuidance,
69
70
  projectLabel,
70
71
  } from './guidance.ts'
71
- import type { GuidanceContextLike, GuidanceServer } from './guidance.ts'
72
+ import type { GuidanceAssemblyLike, GuidanceContextLike, GuidanceServer } from './guidance.ts'
72
73
  // The volatile key list lives at the entry (`src/index.ts`) because the schema
73
74
  // declares it; the import cycles back here, but it is read only inside
74
75
  // `applyLiveConfig`, long after both modules finished evaluating.
@@ -152,6 +153,13 @@ export interface AgentEventLike {
152
153
  agent: AgentLike
153
154
  /** `agent/status` only: whether a turn is currently running. */
154
155
  status?: 'idle' | 'running'
156
+ /**
157
+ * `agent/pre-step` only: the model selection this step captured. Read to ask
158
+ * the llm service what the route can do — a hand-declared provider cannot take
159
+ * tool declarations after the first request, and the presentation has to know
160
+ * before it decides how to hide anything.
161
+ */
162
+ modelSelection?: { readonly provider: string; readonly model: string }
155
163
  }
156
164
 
157
165
  /** The subset of the hosting scope used here. */
@@ -779,6 +787,27 @@ interface AgentState {
779
787
  * state outlives an idle release.
780
788
  */
781
789
  auto: AutoOfferState | undefined
790
+ /**
791
+ * Identity of the model route the last resolved {@link AgentState.toolUpdate}
792
+ * belongs to, as `provider/model`. A selection change re-asks the llm service
793
+ * and nothing else does, so a session keeps one answer per route.
794
+ */
795
+ routeKey: string | undefined
796
+ /**
797
+ * Whether this session's route accepts tool declarations after its first
798
+ * request (`LlmResolvedModelInfo.toolUpdate`), read from the llm service on
799
+ * `agent/pre-step`.
800
+ *
801
+ * `undefined` until a route is resolved. `true` lets the presentation hide a
802
+ * tool behind `deferLoading` — declared, invisible, still callable. `false`
803
+ * means the harness sends the whole declaration list in the first request of
804
+ * every series, so a deferred tool is not hidden at all: it costs its schema
805
+ * and the presentation must not declare it, which is what makes its name
806
+ * reachable only through the discovery tool. The difference is the difference
807
+ * between "hidden but callable" and "not there", and only the route decides
808
+ * which one is even possible.
809
+ */
810
+ toolUpdate: boolean | undefined
782
811
  }
783
812
 
784
813
  interface CachedDocument {
@@ -1427,6 +1456,52 @@ export class ProjectMcpRuntime {
1427
1456
  return names
1428
1457
  }
1429
1458
 
1459
+ /**
1460
+ * Ask the llm service what the session's current route can do with tool
1461
+ * declarations, and re-present the session when the answer moves.
1462
+ *
1463
+ * One answer per route, keyed by `provider/model`: the service resolves it from
1464
+ * the adapter, which is not something to ask on every step. `toolUpdate` is the
1465
+ * one capability read here — `undefined` on a route means the harness sends the
1466
+ * complete current declaration list in every request and strips the deferral
1467
+ * marker, so the presentation cannot hide a tool that way at all.
1468
+ *
1469
+ * A service that is absent (a host without `ctx.llm`, a test composition) or an
1470
+ * answer that never arrives leaves the capability `undefined`, and the
1471
+ * presentation keeps the deferral path it shipped with rather than guessing.
1472
+ * @param state - the session whose route is being read.
1473
+ * @param selection - the step's captured selection; absent resolves nothing.
1474
+ */
1475
+ private async resolveRoute(
1476
+ state: AgentState,
1477
+ selection: AgentEventLike['modelSelection'],
1478
+ ): Promise<void> {
1479
+ if (selection === undefined || this.disposed) return
1480
+ const key = `${selection.provider}/${selection.model}`
1481
+ if (state.routeKey === key) return
1482
+ state.routeKey = key
1483
+ const llm = this.ctx.get('llm') as
1484
+ | { resolveModelInfo?: (provider: string, model: string) => Promise<{ toolUpdate?: unknown }> }
1485
+ | undefined
1486
+ if (typeof llm?.resolveModelInfo !== 'function') return
1487
+ try {
1488
+ const info = await llm.resolveModelInfo(selection.provider, selection.model)
1489
+ const supported = info?.toolUpdate !== undefined
1490
+ if (supported === state.toolUpdate) return
1491
+ state.toolUpdate = supported
1492
+ // The presentation is built from this answer, so a route that changed its
1493
+ // mind — or a session that was mounted before its first step — re-presents
1494
+ // on the queue rather than inside whoever asked.
1495
+ state.bridge?.batch.note()
1496
+ } catch (error) {
1497
+ // A route that cannot describe itself is not a reason to fail a session;
1498
+ // the previous answer (or none) stands.
1499
+ this.ctx.logger.debug?.(
1500
+ `project-mcp: reading the model route of session ${state.agent.id} failed: ${errorText(error)}`,
1501
+ )
1502
+ }
1503
+ }
1504
+
1430
1505
  /**
1431
1506
  * The names one session presents as deferred: what it mounts that it does not
1432
1507
  * offer.
@@ -1442,6 +1517,11 @@ export class ProjectMcpRuntime {
1442
1517
  */
1443
1518
  private deferredNamesOf(state: AgentState): readonly string[] {
1444
1519
  if (!(this.config.activationEnabled ?? DEFAULT_ACTIVATION_ENABLED)) return []
1520
+ // A route without tool updates would send a deferred schema anyway (the
1521
+ // harness strips the marker), so "deferred" there means "declared": the
1522
+ // presentation gives way to the forwarder list itself, which carries only
1523
+ // what is offered.
1524
+ if (state.toolUpdate === false) return []
1445
1525
  const policy = this.policyFor(state.projectRoot)
1446
1526
  if (policy.mode === 'direct') return []
1447
1527
  // The home's catalog, read without {@link mountedSchemas}: this runs inside a
@@ -1827,6 +1907,8 @@ export class ProjectMcpRuntime {
1827
1907
  activationDispose: undefined,
1828
1908
  guidanceDispose: undefined,
1829
1909
  auto: undefined,
1910
+ routeKey: undefined,
1911
+ toolUpdate: undefined,
1830
1912
  }
1831
1913
  }
1832
1914
 
@@ -2207,6 +2289,10 @@ export class ProjectMcpRuntime {
2207
2289
  state.step += 1
2208
2290
  if (!this.disposed) {
2209
2291
  this.touch(state, { activate: true })
2292
+ // Route capability is asked for off this path: it is network-shaped on
2293
+ // some adapters, and a project MCP server is never a reason to hold up
2294
+ // an agent step.
2295
+ void this.resolveRoute(state, event.modelSelection)
2210
2296
  await this.awaitActivation(state)
2211
2297
  }
2212
2298
  }
@@ -2940,11 +3026,21 @@ export class ProjectMcpRuntime {
2940
3026
  // pass would forward names this session's project never published.
2941
3027
  if (project === undefined) return undefined
2942
3028
  try {
2943
- return projectToolNames(
3029
+ const names = projectToolNames(
2944
3030
  project.key,
2945
3031
  (scope) => this.bridgeSchemas(scope),
2946
3032
  servers(),
2947
3033
  )
3034
+ // A route that cannot take declarations after its first request cannot
3035
+ // carry a deferred tool either: the marker would be stripped and the
3036
+ // schema sent. So the forwarder list itself becomes the presentation —
3037
+ // only what the session offers is registered, and the discovery tool is
3038
+ // how the model gets another one for the next step.
3039
+ if (state.toolUpdate === false) {
3040
+ const offered = this.offeredNamesOf(state)
3041
+ return names.filter((name) => offered.has(name))
3042
+ }
3043
+ return names
2948
3044
  } catch (error) {
2949
3045
  // A probe that failed says nothing about the project's set: the batch
2950
3046
  // it could not describe is the batch that stays live.
@@ -3161,7 +3257,7 @@ export class ProjectMcpRuntime {
3161
3257
  try {
3162
3258
  state.guidanceDispose = installGuidance({
3163
3259
  ctx: scope.ctx as unknown as GuidanceContextLike,
3164
- text: () => this.guidanceText(agent, state),
3260
+ text: (assembly) => this.guidanceText(agent, state, assembly),
3165
3261
  onError: (error) => {
3166
3262
  this.ctx.logger.warn(
3167
3263
  `project-mcp: guidance section failed for session ${agent.id}: ${errorText(error)}`,
@@ -3382,14 +3478,25 @@ export class ProjectMcpRuntime {
3382
3478
  *
3383
3479
  * It reads the mount records and the registry at every assembly, so a rescan
3384
3480
  * that mounted or dropped a server — and a search that activated a tool — are
3385
- * reflected without re-registering the section. Total: any failure returns the
3386
- * empty string, because a section that throws would fail the model request
3387
- * that asked for the assembly.
3481
+ * reflected without re-registering the section. The assembly's own admission
3482
+ * snapshot is authoritative when it is present: a tool registered after the
3483
+ * step was prepared is already named by the registry but cannot be called in
3484
+ * that step, so the text does not promise it ({@link admittedNames}). Total:
3485
+ * any failure returns the empty string, because a section that throws would
3486
+ * fail the model request that asked for the assembly.
3487
+ *
3488
+ * @param agent - session whose scope the section belongs to.
3489
+ * @param state - the session's live state.
3490
+ * @param assembly - the assembly context, when the host hands one.
3491
+ * @returns the section text, or `''` when there is nothing true to say.
3388
3492
  */
3389
- private guidanceText(agent: AgentLike, state: AgentState): string {
3493
+ private guidanceText(agent: AgentLike, state: AgentState, assembly?: GuidanceAssemblyLike): string {
3390
3494
  try {
3391
3495
  const projectRoot = state.projectRoot
3392
3496
  if (projectRoot === undefined || this.mountsOf(state).size === 0) return ''
3497
+ // The step's frozen admission, when the host carries one: everything named
3498
+ // below is a callability promise, and only an admitted name can keep it.
3499
+ const admitted = admittedNames(assembly)
3393
3500
  const activationEnabled = this.config.activationEnabled ?? DEFAULT_ACTIVATION_ENABLED
3394
3501
  // With activation on, the presented set is the session's counter baseline
3395
3502
  // plus its activations; with it off, the registry lists every tool.
@@ -3402,6 +3509,7 @@ export class ProjectMcpRuntime {
3402
3509
  const offered: string[] = []
3403
3510
  const deferred: string[] = []
3404
3511
  for (const schema of this.mountedSchemas(state)) {
3512
+ if (admitted !== undefined && !admitted.has(schema.name)) continue
3405
3513
  const server = matchServer(schema.name, mounted)
3406
3514
  if (server === undefined) continue
3407
3515
  const name = schema.name.slice(`mcp__${server}__`.length)
@@ -3423,6 +3531,7 @@ export class ProjectMcpRuntime {
3423
3531
  const mostUsed: string[] = []
3424
3532
  if (activationEnabled) {
3425
3533
  for (const fullName of this.seedActivation(state).baseline) {
3534
+ if (admitted !== undefined && !admitted.has(fullName)) continue
3426
3535
  const server = matchServer(fullName, mounted)
3427
3536
  if (server !== undefined) mostUsed.push(fullName.slice(`mcp__${server}__`.length))
3428
3537
  }
@@ -3434,6 +3543,10 @@ export class ProjectMcpRuntime {
3434
3543
  deferred,
3435
3544
  mostUsed,
3436
3545
  activationEnabled,
3546
+ // Where the route cannot declare a tool after the first request, the
3547
+ // names line below must send the model through the search instead of
3548
+ // promising a call that would answer "unknown tool".
3549
+ directCalls: state.toolUpdate !== false,
3437
3550
  })
3438
3551
  } catch (error) {
3439
3552
  this.ctx.logger.warn(