dsh-project-mcp 0.2.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/src/bridge.ts ADDED
@@ -0,0 +1,486 @@
1
+ /**
2
+ * F-19 forwarding bridge: one `mcp-client` per project, a thin definition per
3
+ * session.
4
+ *
5
+ * A preset composition mounts each session's tools from its own preset subtree,
6
+ * and `agent-presets` binds every composed agent's scope key to the preset's
7
+ * standing key *before* the agent is published. `dsh-scope` binds a key to one
8
+ * parent exactly once, so the project's scope can never join that session's
9
+ * chain — `bindScopeParent` throws, and the runtime's only remaining option was
10
+ * to mount the same declarations again under the session's own scope: one child
11
+ * process per session.
12
+ *
13
+ * The bridge takes the other path. The project keeps its one instance mounted in
14
+ * the project's own scope; a session whose chain cannot reach that scope gets a
15
+ * *forwarding* definition registered in its own layer instead. The forwarder
16
+ * carries the project tool's model-facing surface, and each call resolves the
17
+ * project's live definition by name and runs it:
18
+ *
19
+ * ```
20
+ * project scope session scope (per session)
21
+ * ┌────────────────────────┐ ┌──────────────────────────────────┐
22
+ * │ mcp-client instance │ │ register("mcp__a__run") ──────┐ │
23
+ * │ register("mcp__a__run")│◄────────┼── get("mcp__a__run", project) │ │
24
+ * │ execute(args, exec) │ │ → projectDefinition.execute │ │
25
+ * └────────────────────────┘ └──────────────────────────────────┘
26
+ * ```
27
+ *
28
+ * The resolution is by name at call time, not a captured definition object,
29
+ * because `mcp-client` swaps its whole tool generation on every `tools/list`
30
+ * refresh: a captured definition would keep executing a disposed generation.
31
+ *
32
+ * One session owns one live batch of forwarders, and {@link ForwardBatch} keeps
33
+ * it level with the project's live set: the set is re-read on every trigger,
34
+ * the batch is replaced as a whole (released before the replacement is
35
+ * registered), and the re-entry every registration forces on the sync through
36
+ * `tools/change` is owned rather than left to tear the batch down.
37
+ *
38
+ * The module is import-free of `@deepseek-ai/dsh-tools` on purpose, exactly like
39
+ * {@link ./activation.ts}: the registry, definition and schema surfaces are
40
+ * described by the minimal structural types below, so the plugin stays
41
+ * installable in a deployment that does not carry the tools package.
42
+ *
43
+ * @module dsh-project-mcp/bridge
44
+ */
45
+
46
+ /**
47
+ * Minimal structural view of one model-facing content block.
48
+ *
49
+ * Deliberately open: every block the harness vocabulary carries has a `type` and
50
+ * its own fields, so this is a supertype of all of them. That is what lets a
51
+ * project definition typed against the real `ContentBlock` be copied into a
52
+ * forwarder without a cast at the seam.
53
+ */
54
+ export interface TextBlockLike {
55
+ /** Block discriminant, eg `text`. */
56
+ readonly type: string
57
+ /** Every other block field, unread here. */
58
+ readonly [key: string]: unknown
59
+ }
60
+
61
+ /**
62
+ * Minimal structural view of one model-facing tool schema.
63
+ *
64
+ * It is the shape of `ctx.tools.schemas(scope)` entries, described locally
65
+ * because `@deepseek-ai/dsh-tools` is a peer this plugin does not import.
66
+ */
67
+ export interface BridgeToolSchema {
68
+ /** Public registry name, eg `mcp__alpha__run`. */
69
+ readonly name: string
70
+ /** Model-facing description. */
71
+ readonly description: string
72
+ /** JSON Schema object arguments. */
73
+ readonly parameters: Record<string, unknown>
74
+ }
75
+
76
+ /**
77
+ * Minimal structural view of one registered tool definition.
78
+ *
79
+ * Every field except `execute` is carried over from the project's definition
80
+ * verbatim — copied as a whole (`forwarder` spreads the definition), never by
81
+ * enumerating the fields this module happens to know, so the forwarding entry is
82
+ * indistinguishable from the original to everything that reads a definition:
83
+ * schema projection, presentation metadata and callbacks, the concurrency
84
+ * classifier, the timeout budget, the output renderer and the last-mile
85
+ * `finalizeContent` the registry snapshots from the definition the session
86
+ * resolves.
87
+ */
88
+ export interface ForwardableDefinition extends BridgeToolSchema {
89
+ /** Canonical output contract: schema plus model-facing renderer. */
90
+ readonly output: {
91
+ /** Enforced JSON Schema of the canonical value `execute` returns. */
92
+ readonly schema: Record<string, unknown>
93
+ /**
94
+ * Project the canonical value onto model-facing content.
95
+ * @param args - parsed call arguments.
96
+ * @param value - the validated canonical value.
97
+ * @returns the content blocks the model sees.
98
+ */
99
+ render(args: unknown, value: never): readonly TextBlockLike[]
100
+ /**
101
+ * Optional presentation projection, preserved so a call renders the same
102
+ * card through either layer.
103
+ * @param args - parsed call arguments.
104
+ * @param value - the validated canonical value.
105
+ * @returns the presentation metadata.
106
+ */
107
+ presentationMeta?(args: unknown, value: never): unknown
108
+ }
109
+ /** Cooperative timeout budget, preserved for the timeout policy wrapper. */
110
+ readonly timeoutMs?: number
111
+ /**
112
+ * Pure sibling-overlap classifier. Preserved: a forwarder that dropped it
113
+ * would make every forwarded call exclusive while the project tool is
114
+ * parallel-safe.
115
+ * @param args - parsed call arguments.
116
+ * @returns whether this call may join a parallel group.
117
+ */
118
+ isConcurrencySafe?(args: unknown): boolean
119
+ /**
120
+ * Last-mile transform of the model-facing content, preserved.
121
+ *
122
+ * The registry snapshots this from the definition the *session* resolves —
123
+ * which is the forwarder, not the project's entry — and calls it once per
124
+ * normalized outcome. A forwarder that dropped it would silently degrade
125
+ * every provider result that relies on it: an MCP result's stored images, for
126
+ * one, would arrive as the adapter's plain text fallback.
127
+ * @param exec - the execution identity, passed through unchanged.
128
+ * @param result - the normalized outcome before materialization.
129
+ * @returns replacement content, or `undefined` to preserve the current one.
130
+ */
131
+ finalizeContent?(exec: unknown, result: unknown): readonly TextBlockLike[] | undefined
132
+ /**
133
+ * Pending-state presentation, preserved so a forwarded call renders the same
134
+ * card as the project's own entry.
135
+ * @param args - parsed call arguments.
136
+ * @returns the presentation intent, or `undefined` for the generic card.
137
+ */
138
+ presentCall?(args: unknown): unknown
139
+ /**
140
+ * Completed-state presentation, preserved for the same reason.
141
+ * @param args - parsed call arguments.
142
+ * @param result - the durable result projection.
143
+ * @returns the presentation intent, or `undefined` to keep the pending one.
144
+ */
145
+ presentResult?(args: unknown, result: unknown): unknown
146
+ /**
147
+ * Run one accepted call.
148
+ * @param args - parsed call arguments.
149
+ * @param exec - execution identity, cancellation, and context deferral.
150
+ * @returns the canonical value declared by `output.schema`.
151
+ */
152
+ execute(args: unknown, exec: never): Promise<unknown>
153
+ }
154
+
155
+ /**
156
+ * The registry surface the bridge reads: one scoped lookup and one scoped
157
+ * schema probe.
158
+ *
159
+ * `get(name, scope)` is the registry's public lookup and `schemas(scope)` its
160
+ * public schema projection (`@deepseek-ai/dsh-tools` `ToolRuntime`); passing the
161
+ * project's scope key reads the project's own layer and its ancestors, which is
162
+ * where the shared instance registered its tools.
163
+ */
164
+ export interface BridgeRegistryLike {
165
+ /**
166
+ * Resolve one tool as one scope sees it.
167
+ * @param name - registered tool name.
168
+ * @param scope - viewing scope key; omitted reads the global view.
169
+ * @returns the visible definition, or `undefined` when none is.
170
+ */
171
+ get(name: string, scope?: object): ForwardableDefinition | undefined
172
+ /**
173
+ * Project one scope's visible definitions onto their model-facing schemas.
174
+ * @param scope - viewing scope key; omitted reads the global view.
175
+ * @returns one schema per visible tool, in registry order.
176
+ */
177
+ schemas(scope?: object): readonly BridgeToolSchema[]
178
+ }
179
+
180
+ /**
181
+ * The registration context slices the bridge touches.
182
+ *
183
+ * A session's scope context is passed in, so `register` files every entry into
184
+ * that session's own layer — the one layer this session owns, where the name is
185
+ * visible to itself and to nobody else.
186
+ */
187
+ export interface BridgeContextLike {
188
+ /** Resolve one service, the injection-free read the plugin already uses. */
189
+ get(name: string): unknown
190
+ }
191
+
192
+ /** Options for {@link forwardProjectTools}. */
193
+ export interface ForwardProjectToolsOptions {
194
+ /** Session-scope context; every forwarder is registered through it. */
195
+ readonly ctx: BridgeContextLike
196
+ /** Project scope key whose definitions are executed. */
197
+ readonly project: object
198
+ /** Names to forward, as {@link projectToolNames} resolved them. */
199
+ readonly names: readonly string[]
200
+ /** Registry lookup used to resolve the live project definition per call. */
201
+ readonly registry: BridgeRegistryLike
202
+ }
203
+
204
+ /**
205
+ * Marker a forwarder carries, naming the definition it delegates to.
206
+ *
207
+ * The harness's registry has no "forwarded" concept and needs none — this is
208
+ * addressed only to a test double standing in for the registry, which must tell
209
+ * a forwarder from one of the session's own tools to resolve a call the way the
210
+ * registry would.
211
+ */
212
+ export const FORWARDED_TO = Symbol('dsh-project-mcp.forwarded-to')
213
+
214
+ /**
215
+ * Build one forwarding definition over a project's live definition.
216
+ *
217
+ * The schema fields are copied once, at registration time; the executable
218
+ * delegate is resolved per call, so a project re-sync (which disposes and
219
+ * re-registers every tool) never leaves a forwarder pointing at a dead
220
+ * generation. Calling the project's definition directly — rather than
221
+ * dispatching through the registry — is deliberate: the outer call already
222
+ * traversed the policy pipeline under this session's identity, and a second
223
+ * dispatch would apply pre-execute listeners and guards twice.
224
+ * @param project - the definition to forward, read for its surface.
225
+ * @param lookup - resolves the current project definition of this name.
226
+ * @returns the definition to register in a session's layer.
227
+ */
228
+ function forwarder(
229
+ project: ForwardableDefinition,
230
+ lookup: () => ForwardableDefinition | undefined,
231
+ ): ForwardableDefinition {
232
+ // The marker rides outside the definition's own surface: it is addressed to a
233
+ // test double standing in for the registry, never to the harness.
234
+ return Object.assign(
235
+ {
236
+ // Every field the project declared rides along verbatim, including the
237
+ // ones this module never reads — `finalizeContent`, `presentCall`,
238
+ // `presentResult`, and whatever a future provider adds. Enumerating them
239
+ // is what silently lost `dsh-mcp-client`'s finalizer: the registry takes
240
+ // it from the definition the session resolves, which is this one.
241
+ ...project,
242
+ async execute(args: unknown, exec: never): Promise<unknown> {
243
+ const live = lookup()
244
+ if (live === undefined) {
245
+ throw new Error(`the project's "${project.name}" is no longer registered; the shared instance was released or replaced`)
246
+ }
247
+ return await live.execute(args, exec)
248
+ },
249
+ },
250
+ { [FORWARDED_TO]: project },
251
+ )
252
+ }
253
+
254
+ /**
255
+ * Register one thin definition per name in the session's layer.
256
+ *
257
+ * A name the session already resolves to a definition of its own is skipped:
258
+ * registering over it would either shadow the session's registration (if the
259
+ * session's own layer holds it) or throw on a duplicate, and either way the
260
+ * session's own tool is the one it should call.
261
+ * @param options - session context, project key, names, and registry lookup.
262
+ * @returns the exact releaser that drops every forwarder this call added.
263
+ */
264
+ export function forwardProjectTools(options: ForwardProjectToolsOptions): () => void {
265
+ // `ctx.get(name)` rather than `ctx.tools`: the session's scope context is a
266
+ // raw extended context (the runtime mints it with `createScope`, not with a
267
+ // plugin that injects `tools`), and a dot-read there throws
268
+ // `cannot get property "tools" without inject`.
269
+ const tools = options.ctx.get('tools') as {
270
+ register(definition: ForwardableDefinition): () => void
271
+ }
272
+ const disposes: (() => void)[] = []
273
+ for (const name of options.names) {
274
+ const project = options.registry.get(name, options.project)
275
+ if (project === undefined) continue
276
+ try {
277
+ disposes.push(tools.register(forwarder(project, () => options.registry.get(name, options.project))))
278
+ } catch {
279
+ // A duplicate in this session's own layer is the session's own tool: it
280
+ // keeps the name, and the bridge steps aside rather than failing a mount.
281
+ continue
282
+ }
283
+ }
284
+ let released = false
285
+ return () => {
286
+ if (released) return
287
+ released = true
288
+ for (const dispose of disposes.reverse()) {
289
+ try {
290
+ dispose()
291
+ } catch {
292
+ // Disposal is idempotent at the registry, and a failure here must not
293
+ // keep the remaining forwarders registered.
294
+ }
295
+ }
296
+ }
297
+ }
298
+
299
+ /**
300
+ * The names to forward, and how to register one batch of them.
301
+ *
302
+ * Both are read fresh on every pass: `names` because a server publishing a late
303
+ * `tools/list` (or dropping one) is the ordinary life of a project, and
304
+ * `register` because a pass can be requested from inside a pass.
305
+ */
306
+ export interface ForwardBatchOptions {
307
+ /**
308
+ * The project's live tool names, probed on every pass.
309
+ *
310
+ * `undefined` reports a probe that failed: it says nothing about what the
311
+ * project publishes, so the batch it could not describe is the batch that
312
+ * stays live.
313
+ * @returns the names this session should forward, or `undefined` on failure.
314
+ */
315
+ readonly names: () => readonly string[] | undefined
316
+ /**
317
+ * Register one batch of forwarders over the session's layer, which this call
318
+ * reaches empty-handed: the batch it replaces is released first.
319
+ * @param names - the names to forward, in registry order.
320
+ * @returns the exact releaser that drops the whole batch.
321
+ */
322
+ readonly register: (names: readonly string[]) => () => void
323
+ }
324
+
325
+ /**
326
+ * One session's live forwarding batch, kept level with the project's live tools.
327
+ *
328
+ * The registry announces every registration by emitting `tools/change`
329
+ * synchronously from inside the insertion, and a bridged session is subscribed
330
+ * to exactly that event (`src/runtime.ts`, `installBridge`). A pass therefore
331
+ * re-enters itself once per forwarder it registers. Nothing else owns that
332
+ * re-entry, and left unowned it tears the batch down: the nested pass finds a
333
+ * batch still being built, releases it, and registers a second copy of it —
334
+ * which the live first copy refuses as a duplicate. A bridge that steps aside
335
+ * for a duplicate (it must, for the session's own tools) then drops those names
336
+ * silently, and a full pass records `namesIn` as the whole set, so the loss is
337
+ * frozen for every later pass. That is the defect this class exists to close.
338
+ *
339
+ * So: a pass requested from inside a pass only marks the batch dirty, and the
340
+ * frame that owns the batch runs one more pass when it is complete — which is
341
+ * also how a project set that changed mid-registration is still honoured. And
342
+ * the old batch is released **before** the new one is registered, because one
343
+ * layer holds one entry per name: registering over a live batch would refuse
344
+ * every name it already had.
345
+ */
346
+ export class ForwardBatch {
347
+ /** The names the live batch was registered for; `undefined` before the first pass. */
348
+ #namesIn: readonly string[] | undefined = undefined
349
+ /** Disposer of the live registration batch; `undefined` while none is live. */
350
+ #release: (() => void) | undefined = undefined
351
+ /** Whether an owning frame is inside {@link sync}, registering right now. */
352
+ #building = false
353
+ /** Whether a pass asked for while {@link #building} still needs a run. */
354
+ #again = false
355
+
356
+ constructor(private readonly options: ForwardBatchOptions) {}
357
+
358
+ /**
359
+ * The names the live batch was registered for.
360
+ *
361
+ * `undefined` before the first successful pass, and again after a pass whose
362
+ * registration failed: an unset state is what makes the next pass retry
363
+ * rather than short-circuit on a set that never landed.
364
+ */
365
+ get namesIn(): readonly string[] | undefined {
366
+ return this.#namesIn
367
+ }
368
+
369
+ /**
370
+ * Bring the session's layer level with the project's live tool set.
371
+ *
372
+ * Cheap when it already is: an unchanged set short-circuits and leaves the
373
+ * live batch — and its generation of definitions — untouched. Re-entrant
374
+ * while registering: see the class note.
375
+ * @returns nothing; a failure from the probe or the registry propagates.
376
+ */
377
+ sync(): void {
378
+ if (this.#building) {
379
+ this.#again = true
380
+ return
381
+ }
382
+ this.#building = true
383
+ try {
384
+ do {
385
+ this.#again = false
386
+ this.#syncOnce()
387
+ } while (this.#again)
388
+ } finally {
389
+ this.#building = false
390
+ }
391
+ }
392
+
393
+ /**
394
+ * Drop the live batch: the session keeps no forwarder, and the next
395
+ * {@link sync} starts from nothing rather than amending a stale set.
396
+ * Idempotent.
397
+ *
398
+ * The release announces itself (`tools/change`) once per entry, and the
399
+ * session is subscribed to that event; a pass re-entered from there must not
400
+ * resurrect the batch it is watching being dropped. So the guard is held for
401
+ * the whole release, and the pass it queues is discarded rather than run.
402
+ */
403
+ drop(): void {
404
+ this.#building = true
405
+ try {
406
+ this.#releaseBatch()
407
+ } finally {
408
+ this.#building = false
409
+ this.#again = false
410
+ }
411
+ }
412
+
413
+ /** One pass: read the project's set, then replace the batch when it moved. */
414
+ #syncOnce(): void {
415
+ const names = this.options.names()
416
+ if (names === undefined) return
417
+ if (this.#namesIn !== undefined && sameNames(this.#namesIn, names)) return
418
+ // Released first, and deliberately — see the class note. Until the new batch
419
+ // is registered the session's layer is empty for the length of one
420
+ // synchronous call, which is the price of every forwarded name being free.
421
+ try {
422
+ this.#releaseBatch()
423
+ } catch {
424
+ // The registry's disposer is exact and idempotent, and a failure here must
425
+ // not keep the new batch from registering.
426
+ }
427
+ this.#release = this.options.register(names)
428
+ this.#namesIn = names
429
+ }
430
+
431
+ /**
432
+ * Release the live batch and forget it.
433
+ *
434
+ * The fields are cleared before the disposer runs, so a throw leaves the batch
435
+ * in the retryable empty state rather than half-released and half-claimed.
436
+ */
437
+ #releaseBatch(): void {
438
+ const release = this.#release
439
+ this.#release = undefined
440
+ this.#namesIn = undefined
441
+ release?.()
442
+ }
443
+ }
444
+
445
+ /**
446
+ * The project scope's tool names, restricted to the servers the project
447
+ * actually mounted.
448
+ *
449
+ * The probe reads the PROJECT scope, not the session's: the shared instance
450
+ * registered its tools there, so a session's own view would also carry its own
451
+ * registrations (and could not tell them apart). `servers` keeps a name another
452
+ * scope's server happens to publish from being forwarded.
453
+ * @param project - project scope key whose view is probed.
454
+ * @param schemas - reads one scope's visible schemas, as `ctx.tools.schemas`.
455
+ * @param servers - server namespaces the project mounted.
456
+ * @returns the tool names to forward, in registry order.
457
+ */
458
+ export function projectToolNames(
459
+ project: object,
460
+ schemas: (scope: object) => readonly BridgeToolSchema[],
461
+ servers: ReadonlySet<string>,
462
+ ): string[] {
463
+ const names: string[] = []
464
+ for (const schema of schemas(project)) {
465
+ const match = /^mcp__([A-Za-z0-9_-]+?)__/.exec(schema.name)
466
+ if (match === null) continue
467
+ if (!servers.has(match[1] as string)) continue
468
+ names.push(schema.name)
469
+ }
470
+ return names
471
+ }
472
+
473
+ /**
474
+ * Whether two name lists are the same set in the same order.
475
+ *
476
+ * A sync is skipped when the project publishes exactly what the last one
477
+ * forwarded: re-registering an unchanged batch would dispose and rebuild every
478
+ * forwarder for nothing, and the registry announces each change to every
479
+ * watcher.
480
+ * @param left - the names the last sync forwarded.
481
+ * @param right - the names this sync found.
482
+ * @returns whether the two lists match entry for entry.
483
+ */
484
+ export function sameNames(left: readonly string[], right: readonly string[]): boolean {
485
+ return left.length === right.length && left.every((name, index) => name === right[index])
486
+ }