dsh-project-mcp 0.4.1 → 0.4.2

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.1",
4
+ "version": "0.4.2",
5
5
  "type": "module",
6
6
  "main": "lib/index.js",
7
7
  "types": "lib/index.d.ts",
package/src/activation.ts CHANGED
@@ -1333,6 +1333,18 @@ export interface ActivationWiringOptions {
1333
1333
  * the same name may carry the step of the offer the compaction removed.
1334
1334
  */
1335
1335
  readonly onCompaction?: () => void
1336
+ /**
1337
+ * Told that the offered set may have moved: a search activated names, a
1338
+ * compaction dropped the ones no call backed, or the context tier advanced.
1339
+ *
1340
+ * A harness whose assembly carries no tool list cannot be filtered from this
1341
+ * module at all (0.2.2 and later: declarations are provider-owned), so the
1342
+ * presentation lives in the caller's own registrations instead — the bridge's
1343
+ * `deferLoading` forwarders. This is the seat that keeps that copy level with
1344
+ * {@link ActivationState}; absent simply means nothing presents the set but the
1345
+ * assembly this module used to rewrite.
1346
+ */
1347
+ readonly onOfferedChanged?: () => void
1336
1348
  /** Context-driven state to start from; defaults to an empty state. */
1337
1349
  readonly autoState?: AutoOfferState
1338
1350
  /** Sink for the context-driven state after every advance that changed it. */
@@ -1432,6 +1444,9 @@ export function installActivation(options: ActivationWiringOptions): () => void
1432
1444
  if (next === tracker.state) return
1433
1445
  tracker.state = next
1434
1446
  options.setAutoState?.(next)
1447
+ // The offered set moved, so a presentation that lives outside this assembly —
1448
+ // the bridge's `deferLoading` forwarders — has to follow it.
1449
+ options.onOfferedChanged?.()
1435
1450
  }
1436
1451
 
1437
1452
  /** Every name the session's explicit activation and context-driven tiers offer. */
@@ -1489,6 +1504,7 @@ export function installActivation(options: ActivationWiringOptions): () => void
1489
1504
  * continuation's value comes back by identity.
1490
1505
  */
1491
1506
  const contain = (result: AssemblyLike): AssemblyLike => {
1507
+ if (!Array.isArray(result.tools)) return result
1492
1508
  const foreign = options.foreign?.() ?? NO_FOREIGN
1493
1509
  if (foreign.size === 0) return result
1494
1510
  const kept = result.tools.filter((tool) => !foreign.has(tool.name))
@@ -1511,10 +1527,23 @@ export function installActivation(options: ActivationWiringOptions): () => void
1511
1527
  }
1512
1528
 
1513
1529
  const merge = (result: AssemblyLike): AssemblyLike => {
1530
+ const policy = options.policy?.() ?? DEFAULT_TOOL_POLICY
1531
+ // A harness whose assembly carries no tool list cannot be shaped from here at
1532
+ // all. From 0.2.2 on, `system-prompt/assemble` transforms a presentation and
1533
+ // the declared schemas are provider-owned, so a listener that rewrote
1534
+ // `assembly.tools` would be writing into a field the harness discards — and
1535
+ // reading it would throw on every model request. The presentation lives in
1536
+ // the caller's `deferLoading` forwarders instead (`src/bridge.ts`), kept level
1537
+ // through {@link ActivationWiringOptions.onOfferedChanged}; this listener
1538
+ // still drives the context tier and degrades to the rest of the harness's
1539
+ // answer.
1540
+ if (!Array.isArray(result.tools)) {
1541
+ if (policy.mode === 'disclosure') advance()
1542
+ return result
1543
+ }
1514
1544
  const surface = wholeSurface()
1515
1545
  // Nothing is visible: there is nothing to find, so nothing is added.
1516
1546
  if (surface.length === 0) return contain(result)
1517
- const policy = options.policy?.() ?? DEFAULT_TOOL_POLICY
1518
1547
  // `off` promises that the project's tools are not offered, and the promise is
1519
1548
  // about the request, not only about what the panel says: the project plane
1520
1549
  // leaves the assembly here. Only this plugin's own mounts go — the profile
@@ -1594,6 +1623,9 @@ export function installActivation(options: ActivationWiringOptions): () => void
1594
1623
  tracker.state = resetAutoOffer(tracker.state)
1595
1624
  tracker.calls = []
1596
1625
  tracker.changed = false
1626
+ // The boundary is the one place that shrinks the offered set, so a
1627
+ // presentation outside this assembly re-applies it here.
1628
+ options.onOfferedChanged?.()
1597
1629
  return
1598
1630
  }
1599
1631
  if (event?.type === 'user/message') {
@@ -1626,6 +1658,7 @@ export function installActivation(options: ActivationWiringOptions): () => void
1626
1658
  activate: (names) => {
1627
1659
  recordActivated(names)
1628
1660
  options.setState(activate(options.state(), names, Date.now()))
1661
+ options.onOfferedChanged?.()
1629
1662
  },
1630
1663
  ...(options.searchLimit === undefined ? {} : { defaultLimit: options.searchLimit }),
1631
1664
  })
package/src/bridge.ts CHANGED
@@ -112,6 +112,20 @@ export interface ForwardableDefinition extends BridgeToolSchema {
112
112
  }
113
113
  /** Cooperative timeout budget, preserved for the timeout policy wrapper. */
114
114
  readonly timeoutMs?: number
115
+ /**
116
+ * Deferred-loading request, owned by the presentation rather than by the
117
+ * project.
118
+ *
119
+ * The harness projects this flag onto the model-facing schema
120
+ * (`projectToolSchema`), and an adapter that understands it (the shipped
121
+ * `dsh-llm-pi-ai` route omits such a schema from the wire request) then leaves
122
+ * the definition out of the model's tool list while the registry keeps the
123
+ * tool admitted for dispatch — a tool the model does not see but can still
124
+ * call by its exact full name. It is set on the forwarder, never copied from
125
+ * the project, because which of a session's tools are offered is this plugin's
126
+ * presentation decision.
127
+ */
128
+ readonly deferLoading?: true
115
129
  /**
116
130
  * Pure sibling-overlap classifier. Preserved: a forwarder that dropped it
117
131
  * would make every forwarded call exclusive while the project tool is
@@ -201,6 +215,14 @@ export interface ForwardProjectToolsOptions {
201
215
  readonly project: object
202
216
  /** Names to forward, as {@link projectToolNames} resolved them. */
203
217
  readonly names: readonly string[]
218
+ /**
219
+ * Names this pass forwards as deferred, so their schemas stay out of the
220
+ * model's tool list while the registry keeps them callable. Absent defers
221
+ * none, which is what a session with nothing hidden gets.
222
+ * @param name - one forwarded name.
223
+ * @returns whether the forwarder of that name carries `deferLoading`.
224
+ */
225
+ readonly deferred?: (name: string) => boolean
204
226
  /** Registry lookup used to resolve the live project definition per call. */
205
227
  readonly registry: BridgeRegistryLike
206
228
  }
@@ -227,11 +249,14 @@ export const FORWARDED_TO = Symbol('dsh-project-mcp.forwarded-to')
227
249
  * dispatch would apply pre-execute listeners and guards twice.
228
250
  * @param project - the definition to forward, read for its surface.
229
251
  * @param lookup - resolves the current project definition of this name.
252
+ * @param deferred - whether this forwarder asks for deferred loading, so the
253
+ * model's tool list leaves it out while the registry keeps it callable.
230
254
  * @returns the definition to register in a session's layer.
231
255
  */
232
256
  function forwarder(
233
257
  project: ForwardableDefinition,
234
258
  lookup: () => ForwardableDefinition | undefined,
259
+ deferred: boolean,
235
260
  ): ForwardableDefinition {
236
261
  // The marker rides outside the definition's own surface: it is addressed to a
237
262
  // test double standing in for the registry, never to the harness.
@@ -243,6 +268,11 @@ function forwarder(
243
268
  // is what silently lost `dsh-mcp-client`'s finalizer: the registry takes
244
269
  // it from the definition the session resolves, which is this one.
245
270
  ...project,
271
+ // After the spread, because the presentation decides this flag and the
272
+ // project has no say in it. A forwarder that is not deferred carries no
273
+ // flag at all rather than `deferLoading: false`, which is not part of the
274
+ // harness's schema vocabulary.
275
+ ...deferred ? { deferLoading: true as const } : {},
246
276
  async execute(args: unknown, exec: never): Promise<unknown> {
247
277
  const live = lookup()
248
278
  if (live === undefined) {
@@ -278,7 +308,11 @@ export function forwardProjectTools(options: ForwardProjectToolsOptions): () =>
278
308
  const project = options.registry.get(name, options.project)
279
309
  if (project === undefined) continue
280
310
  try {
281
- disposes.push(tools.register(forwarder(project, () => options.registry.get(name, options.project))))
311
+ disposes.push(tools.register(forwarder(
312
+ project,
313
+ () => options.registry.get(name, options.project),
314
+ options.deferred?.(name) === true,
315
+ )))
282
316
  } catch {
283
317
  // A duplicate in this session's own layer is the session's own tool: it
284
318
  // keeps the name, and the bridge steps aside rather than failing a mount.
@@ -317,13 +351,26 @@ export interface ForwardBatchOptions {
317
351
  * @returns the names this session should forward, or `undefined` on failure.
318
352
  */
319
353
  readonly names: () => readonly string[] | undefined
354
+ /**
355
+ * The names this session presents as deferred — hidden from the model's tool
356
+ * list while the registry keeps them callable — read once on every pass.
357
+ *
358
+ * A pass whose names matched but whose deferred set moved still re-registers:
359
+ * `deferLoading` is baked into the definition at registration, so the flag a
360
+ * schema carries is exactly the flag its forwarder was registered with.
361
+ * Absent defers none, which is the presentation of a session with nothing
362
+ * hidden.
363
+ * @returns the deferred names, or none.
364
+ */
365
+ readonly deferred?: () => readonly string[]
320
366
  /**
321
367
  * Register one batch of forwarders over the session's layer, which this call
322
368
  * reaches empty-handed: the batch it replaces is released first.
323
369
  * @param names - the names to forward, in registry order.
370
+ * @param deferred - the names of this batch that carry `deferLoading`.
324
371
  * @returns the exact releaser that drops the whole batch.
325
372
  */
326
- readonly register: (names: readonly string[]) => () => void
373
+ readonly register: (names: readonly string[], deferred: ReadonlySet<string>) => () => void
327
374
  /**
328
375
  * Report a failure thrown by a pass this batch ran on its own.
329
376
  *
@@ -390,6 +437,8 @@ export const MAX_SYNC_PASSES = 4
390
437
  export class ForwardBatch {
391
438
  /** The names the live batch was registered for; `undefined` before the first pass. */
392
439
  #namesIn: readonly string[] | undefined = undefined
440
+ /** The names the live batch registered as deferred; `undefined` with no live batch. */
441
+ #deferredIn: ReadonlySet<string> | undefined = undefined
393
442
  /** Disposer of the live registration batch; `undefined` while none is live. */
394
443
  #release: (() => void) | undefined = undefined
395
444
  /** Whether an owning frame is inside {@link sync}, registering right now. */
@@ -521,7 +570,14 @@ export class ForwardBatch {
521
570
  #syncOnce(): void {
522
571
  const names = this.options.names()
523
572
  if (names === undefined) return
524
- if (this.#namesIn !== undefined && sameNames(this.#namesIn, names)) return
573
+ // A name that enters or leaves the deferred set is a definition change even
574
+ // when the name set itself is identical: the flag is part of the schema the
575
+ // registry projects, so a batch registered before the flip would keep
576
+ // presenting the old answer for every later request.
577
+ const deferred = new Set(this.options.deferred?.() ?? [])
578
+ if (this.#namesIn !== undefined
579
+ && sameNames(this.#namesIn, names)
580
+ && sameNameSet(this.#deferredIn, deferred)) return
525
581
  // Released first, and deliberately — see the class note. Until the new batch
526
582
  // is registered the session's layer is empty for the length of one
527
583
  // synchronous call, which is the price of every forwarded name being free.
@@ -531,8 +587,9 @@ export class ForwardBatch {
531
587
  // The registry's disposer is exact and idempotent, and a failure here must
532
588
  // not keep the new batch from registering.
533
589
  }
534
- this.#release = this.options.register(names)
590
+ this.#release = this.options.register(names, deferred)
535
591
  this.#namesIn = names
592
+ this.#deferredIn = deferred
536
593
  }
537
594
 
538
595
  /**
@@ -545,6 +602,7 @@ export class ForwardBatch {
545
602
  const release = this.#release
546
603
  this.#release = undefined
547
604
  this.#namesIn = undefined
605
+ this.#deferredIn = undefined
548
606
  release?.()
549
607
  }
550
608
  }
@@ -591,3 +649,23 @@ export function projectToolNames(
591
649
  export function sameNames(left: readonly string[], right: readonly string[]): boolean {
592
650
  return left.length === right.length && left.every((name, index) => name === right[index])
593
651
  }
652
+
653
+ /**
654
+ * Whether two deferred-name sets are the same set.
655
+ *
656
+ * The batch short-circuits a pass whose forwarded names did not move, and it
657
+ * must not do that when the *deferred* subset moved instead: the flag rides in
658
+ * the registered definition, so a stale batch presents a stale answer. Order
659
+ * carries no meaning here, hence a set comparison rather than {@link sameNames}.
660
+ * @param left - the deferred set of the live batch; `undefined` with no live batch.
661
+ * @param right - the deferred set this pass read.
662
+ * @returns whether the two describe the same names.
663
+ */
664
+ export function sameNameSet(
665
+ left: ReadonlySet<string> | undefined,
666
+ right: ReadonlySet<string>,
667
+ ): boolean {
668
+ if (left === undefined || left.size !== right.size) return false
669
+ for (const name of right) if (!left.has(name)) return false
670
+ return true
671
+ }
package/src/runtime.ts CHANGED
@@ -31,16 +31,20 @@ import {
31
31
  DEFAULT_ACTIVATION_ENABLED,
32
32
  DEFAULT_ACTIVATION_MIN_CALLS,
33
33
  DEFAULT_ACTIVATION_SEEDED,
34
+ DEFAULT_TOOL_BUDGET_CHARS,
34
35
  DEFAULT_TOOL_IDLE_MS,
35
36
  SEARCH_TOOL_NAME,
37
+ autoPresentedNames,
36
38
  createActivationState,
37
39
  createAutoOfferState,
38
40
  installActivation,
39
41
  noteUse,
42
+ overToolBudget,
40
43
  presentedNames,
41
44
  pruneIdle,
42
45
  schemaChars,
43
46
  seedFromUsage,
47
+ surfaceChars,
44
48
  toolsFor,
45
49
  } from './activation.ts'
46
50
  import type {
@@ -1274,6 +1278,7 @@ export class ProjectMcpRuntime {
1274
1278
  }
1275
1279
  }
1276
1280
  policy.setPin(request.projectRoot, request.tool, request.pinned)
1281
+ this.refreshPresentation(request.projectRoot)
1277
1282
  this.notify()
1278
1283
  return { ok: true, snapshot: this.snapshot() }
1279
1284
  }
@@ -1316,6 +1321,7 @@ export class ProjectMcpRuntime {
1316
1321
  }
1317
1322
  }
1318
1323
  policy.setMode(request.projectRoot, request.mode)
1324
+ this.refreshPresentation(request.projectRoot)
1319
1325
  this.notify()
1320
1326
  return { ok: true, snapshot: this.snapshot() }
1321
1327
  }
@@ -1386,6 +1392,70 @@ export class ProjectMcpRuntime {
1386
1392
  return this.options.policy?.forProject(projectRoot) ?? DEFAULT_TOOL_POLICY
1387
1393
  }
1388
1394
 
1395
+ /**
1396
+ * Re-apply the presentation of every session working in one project.
1397
+ *
1398
+ * A pin or a mode is read live by the panel and by the guidance, but the
1399
+ * forwarders carry their `deferLoading` flag from the pass that registered
1400
+ * them, so the sessions of that project have to run one — off the caller's
1401
+ * stack, like every other change note.
1402
+ * @param projectRoot - the project whose policy just moved.
1403
+ */
1404
+ private refreshPresentation(projectRoot: string): void {
1405
+ for (const state of this.states.values()) {
1406
+ if (state.projectRoot !== projectRoot) continue
1407
+ state.bridge?.batch.note()
1408
+ }
1409
+ }
1410
+
1411
+ /**
1412
+ * The names one session's presentation offers the model right now.
1413
+ *
1414
+ * The counterpart of the assembly wiring's own `offeredNames`, read where the
1415
+ * presentation lives outside that assembly — in the bridge's forwarders. It is
1416
+ * the counter-seeded baseline, the session's activations, the context tier's
1417
+ * window, and the project's pins; the same four sources the assembly-side
1418
+ * `wanted` set is built from, so the two cannot drift.
1419
+ * @param state - the session to read.
1420
+ * @returns the offered public names.
1421
+ */
1422
+ private offeredNamesOf(state: AgentState): ReadonlySet<string> {
1423
+ const names = new Set<string>(presentedNames(this.seedActivation(state)))
1424
+ const auto = state.auto
1425
+ if (auto !== undefined) for (const name of autoPresentedNames(auto)) names.add(name)
1426
+ for (const pin of this.policyFor(state.projectRoot).pins) names.add(pin)
1427
+ return names
1428
+ }
1429
+
1430
+ /**
1431
+ * The names one session presents as deferred: what it mounts that it does not
1432
+ * offer.
1433
+ *
1434
+ * Empty when there is nothing to defer — activation off, `direct`, or a
1435
+ * surface that fits the budget — because deferring a schema the request would
1436
+ * have carried anyway only makes the declaration list harder to read, and the
1437
+ * prefix-cache argument for it is gone. The budget is the same
1438
+ * {@link surfaceChars} reading the panel and the assembly gate use, so the
1439
+ * deferred set and the "hidden" number a panel shows are one decision.
1440
+ * @param state - the session whose presentation is being registered.
1441
+ * @returns the names whose forwarders carry `deferLoading`, in registry order.
1442
+ */
1443
+ private deferredNamesOf(state: AgentState): readonly string[] {
1444
+ if (!(this.config.activationEnabled ?? DEFAULT_ACTIVATION_ENABLED)) return []
1445
+ const policy = this.policyFor(state.projectRoot)
1446
+ if (policy.mode === 'direct') return []
1447
+ // The home's catalog, read without {@link mountedSchemas}: this runs inside a
1448
+ // bridge pass, and that read syncs the very batch the pass is building.
1449
+ const home = this.homeOf(state)
1450
+ const mounted = home === undefined ? [] : this.schemasOf(home, state.agent.id)
1451
+ if (policy.mode === 'disclosure') {
1452
+ const budget = this.config.activationToolBudgetChars ?? DEFAULT_TOOL_BUDGET_CHARS
1453
+ if (!overToolBudget(surfaceChars(mounted), budget)) return []
1454
+ }
1455
+ const offered = this.offeredNamesOf(state)
1456
+ return mounted.map((schema) => schema.name).filter((name) => !offered.has(name))
1457
+ }
1458
+
1389
1459
  /**
1390
1460
  * Whether one project root has a live session on this host.
1391
1461
  * @param projectRoot - project root a policy request names.
@@ -2884,13 +2954,15 @@ export class ProjectMcpRuntime {
2884
2954
  return undefined
2885
2955
  }
2886
2956
  },
2887
- register: (names) => {
2957
+ deferred: () => this.deferredNamesOf(state),
2958
+ register: (names, deferred) => {
2888
2959
  const project = state.project
2889
2960
  if (project === undefined) return () => undefined
2890
2961
  return forwardProjectTools({
2891
2962
  ctx: context,
2892
2963
  project: project.key,
2893
2964
  names,
2965
+ deferred: (name) => deferred.has(name),
2894
2966
  registry,
2895
2967
  })
2896
2968
  },
@@ -3117,6 +3189,11 @@ export class ProjectMcpRuntime {
3117
3189
  // mode or pin stored from the panel applies from the next model step on
3118
3190
  // without re-minting the scope the listener lives in.
3119
3191
  policy: () => this.policyFor(state.projectRoot),
3192
+ // The presentation lives in this session's own forwarders (they carry
3193
+ // `deferLoading`), so every move of the offered set re-applies it there.
3194
+ // `note` and not `sync`: the pass belongs off the caller's stack, and a
3195
+ // burst of activation settles in one queued pass.
3196
+ onOfferedChanged: () => state.bridge?.batch.note(),
3120
3197
  // The step the session is on, read when a search activates names: the
3121
3198
  // wiring keeps no counter of its own, because an activation outlives
3122
3199
  // the scope the wiring lives in and its stamp has to outlive it too.