dsh-project-mcp 0.4.0 → 0.4.1
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/lib/index.d.ts +83 -4
- package/lib/index.js +125 -15
- package/lib/index.js.map +1 -1
- package/package.json +1 -1
- package/src/bridge.ts +114 -7
- package/src/runtime.ts +54 -12
package/lib/index.d.ts
CHANGED
|
@@ -39,7 +39,11 @@ import { IncomingMessage, ServerResponse } from "node:http";
|
|
|
39
39
|
* it level with the project's live set: the set is re-read on every trigger,
|
|
40
40
|
* the batch is replaced as a whole (released before the replacement is
|
|
41
41
|
* registered), and the re-entry every registration forces on the sync through
|
|
42
|
-
* `tools/change` is owned rather than left to tear the batch down.
|
|
42
|
+
* `tools/change` is owned rather than left to tear the batch down. Because that
|
|
43
|
+
* event is emitted once per entry registered and once per entry disposed, the
|
|
44
|
+
* subscription takes {@link ForwardBatch.note} — which folds a whole burst into
|
|
45
|
+
* one queued pass — and never {@link ForwardBatch.sync}, whose work belongs to
|
|
46
|
+
* the frame that asked for it.
|
|
43
47
|
*
|
|
44
48
|
* The module is import-free of `@deepseek-ai/dsh-tools` on purpose, exactly like
|
|
45
49
|
* {@link ./activation.ts}: the registry, definition and schema surfaces are
|
|
@@ -213,6 +217,16 @@ interface ForwardBatchOptions {
|
|
|
213
217
|
* @returns the exact releaser that drops the whole batch.
|
|
214
218
|
*/
|
|
215
219
|
readonly register: (names: readonly string[]) => () => void;
|
|
220
|
+
/**
|
|
221
|
+
* Report a failure thrown by a pass this batch ran on its own.
|
|
222
|
+
*
|
|
223
|
+
* A pass requested by {@link ForwardBatch.note} runs off the caller's stack:
|
|
224
|
+
* the registry call that announced the change has already returned, and so
|
|
225
|
+
* has every frame that could have propagated the failure. Without this the
|
|
226
|
+
* batch would go quiet — no forwarder, and no trace of why.
|
|
227
|
+
* @param error - what the scheduled pass threw.
|
|
228
|
+
*/
|
|
229
|
+
readonly onError?: (error: unknown) => void;
|
|
216
230
|
}
|
|
217
231
|
/**
|
|
218
232
|
* One session's live forwarding batch, kept level with the project's live tools.
|
|
@@ -226,7 +240,8 @@ interface ForwardBatchOptions {
|
|
|
226
240
|
* which the live first copy refuses as a duplicate. A bridge that steps aside
|
|
227
241
|
* for a duplicate (it must, for the session's own tools) then drops those names
|
|
228
242
|
* silently, and a full pass records `namesIn` as the whole set, so the loss is
|
|
229
|
-
* frozen for every later pass. That is the defect this class exists to
|
|
243
|
+
* frozen for every later pass. That is the first defect this class exists to
|
|
244
|
+
* close.
|
|
230
245
|
*
|
|
231
246
|
* So: a pass requested from inside a pass only marks the batch dirty, and the
|
|
232
247
|
* frame that owns the batch runs one more pass when it is complete — which is
|
|
@@ -234,6 +249,23 @@ interface ForwardBatchOptions {
|
|
|
234
249
|
* the old batch is released **before** the new one is registered, because one
|
|
235
250
|
* layer holds one entry per name: registering over a live batch would refuse
|
|
236
251
|
* every name it already had.
|
|
252
|
+
*
|
|
253
|
+
* Owning the re-entry is not enough on its own, and the shape of the event is
|
|
254
|
+
* why. Replacing a batch of N entries announces 2·N changes — one per disposal
|
|
255
|
+
* and one per registration — and the event carries no origin, so every session
|
|
256
|
+
* watching the stream runs a pass for every one of them, and every pass begins
|
|
257
|
+
* by projecting the project's whole catalog, which the registry answers by deep
|
|
258
|
+
* cloning each visible definition's JSON schema. The registry per pass is what
|
|
259
|
+
* makes that cost real: one MCP generation swap was measured holding the event
|
|
260
|
+
* loop for the full 54 seconds of a CPU profile (47% of its samples inside this
|
|
261
|
+
* sync, 52% in the collector the projections feed), while the plugin's own
|
|
262
|
+
* frames were 0.46% of it. So {@link note} is the seat a `tools/change`
|
|
263
|
+
* subscription takes, not {@link sync}: a change that arrives during a pass is
|
|
264
|
+
* absorbed by it, and a burst that arrives between passes costs **one** queued
|
|
265
|
+
* pass however many events it carries. A stale forwarder is safe in the window
|
|
266
|
+
* that opens — it resolves the project entry at call time and fails closed when
|
|
267
|
+
* there is none (`forwarder`) — and every read path brings the batch level
|
|
268
|
+
* before it reads, so a reader never waits for the queue.
|
|
237
269
|
*/
|
|
238
270
|
declare class ForwardBatch {
|
|
239
271
|
#private;
|
|
@@ -248,14 +280,31 @@ declare class ForwardBatch {
|
|
|
248
280
|
*/
|
|
249
281
|
get namesIn(): readonly string[] | undefined;
|
|
250
282
|
/**
|
|
251
|
-
* Bring the session's layer level with the project's live tool set.
|
|
283
|
+
* Bring the session's layer level with the project's live tool set, now.
|
|
252
284
|
*
|
|
253
285
|
* Cheap when it already is: an unchanged set short-circuits and leaves the
|
|
254
286
|
* live batch — and its generation of definitions — untouched. Re-entrant
|
|
255
|
-
* while registering
|
|
287
|
+
* while registering, and bounded to {@link MAX_SYNC_PASSES} synchronous
|
|
288
|
+
* rounds so no registry state can hold the caller's frame: see the class note.
|
|
256
289
|
* @returns nothing; a failure from the probe or the registry propagates.
|
|
257
290
|
*/
|
|
258
291
|
sync(): void;
|
|
292
|
+
/**
|
|
293
|
+
* Note that the registry changed, and bring the batch level — off this stack.
|
|
294
|
+
*
|
|
295
|
+
* This is the seat a `tools/change` subscription takes, and the reason it is
|
|
296
|
+
* not {@link sync}: the event is emitted once per entry registered and once
|
|
297
|
+
* per entry disposed, from inside the registry's own insertion and removal,
|
|
298
|
+
* so one MCP generation swap is a burst of thousands. A change that arrives
|
|
299
|
+
* while a pass is running is absorbed by that pass — it re-reads the set it is
|
|
300
|
+
* replacing before it returns — and a burst that arrives between passes costs
|
|
301
|
+
* one pass: the first queues, every later one folds into it.
|
|
302
|
+
*
|
|
303
|
+
* Nothing reads a stale layer for it. Every read path brings the batch level
|
|
304
|
+
* first (`src/runtime.ts`, `mountedSchemas`), and the queued pass has run
|
|
305
|
+
* before any turn that could read the layer at all.
|
|
306
|
+
*/
|
|
307
|
+
note(): void;
|
|
259
308
|
/**
|
|
260
309
|
* Drop the live batch: the session keeps no forwarder, and the next
|
|
261
310
|
* {@link sync} starts from nothing rather than amending a stale set.
|
|
@@ -265,6 +314,12 @@ declare class ForwardBatch {
|
|
|
265
314
|
* session is subscribed to that event; a pass re-entered from there must not
|
|
266
315
|
* resurrect the batch it is watching being dropped. So the guard is held for
|
|
267
316
|
* the whole release, and the pass it queues is discarded rather than run.
|
|
317
|
+
*
|
|
318
|
+
* The guard is *held*, not taken: a drop that runs inside a pass — a detach
|
|
319
|
+
* driven from a listener, a scope torn down under a registration — restores
|
|
320
|
+
* the pass's own `building` rather than clearing it. Clearing it there would
|
|
321
|
+
* let the next `tools/change` start a nested pass inside a frame that still
|
|
322
|
+
* owns one, which is exactly the re-entry this class exists to own.
|
|
268
323
|
*/
|
|
269
324
|
drop(): void;
|
|
270
325
|
}
|
|
@@ -2590,6 +2645,30 @@ export declare class ProjectMcpRuntime {
|
|
|
2590
2645
|
* @param state - the session whose bridge to sync.
|
|
2591
2646
|
*/
|
|
2592
2647
|
private syncBridge;
|
|
2648
|
+
/**
|
|
2649
|
+
* Note one registry change for one session's bridge, off the emitter's stack.
|
|
2650
|
+
*
|
|
2651
|
+
* The event this answers is emitted synchronously from inside the registry's
|
|
2652
|
+
* own insertion and removal — once per entry in, once per entry out — so one
|
|
2653
|
+
* MCP generation swap is a burst of thousands. Running the pass here would
|
|
2654
|
+
* make whoever registered a tool pay for every session watching the project,
|
|
2655
|
+
* and each pass projects the project's whole catalog. The batch folds the
|
|
2656
|
+
* burst into one queued pass instead, which is also why this is not
|
|
2657
|
+
* {@link syncBridge}: the read paths, the mount settle and the scope wiring
|
|
2658
|
+
* all bring the batch level synchronously, before anything reads the layer.
|
|
2659
|
+
* @param state - the session whose bridge noticed the change.
|
|
2660
|
+
*/
|
|
2661
|
+
private noteBridge;
|
|
2662
|
+
/**
|
|
2663
|
+
* Write the one warning line a failed bridge pass is allowed.
|
|
2664
|
+
*
|
|
2665
|
+
* Shared by the synchronous pass and by the one a batch runs on its own: a
|
|
2666
|
+
* scheduled pass has no caller left to propagate its failure to, so the batch
|
|
2667
|
+
* hands it here through `onError` rather than swallowing it.
|
|
2668
|
+
* @param state - the session whose bridge failed.
|
|
2669
|
+
* @param error - what the pass threw.
|
|
2670
|
+
*/
|
|
2671
|
+
private reportBridgeFailure;
|
|
2593
2672
|
/** The project scope's visible schemas, as {@link projectToolNames} reads them. */
|
|
2594
2673
|
private bridgeSchemas;
|
|
2595
2674
|
/** Drop one session's bridge: its forwarders and its subscription. Idempotent. */
|
package/lib/index.js
CHANGED
|
@@ -2549,7 +2549,8 @@ function forwardProjectTools(options) {
|
|
|
2549
2549
|
* which the live first copy refuses as a duplicate. A bridge that steps aside
|
|
2550
2550
|
* for a duplicate (it must, for the session's own tools) then drops those names
|
|
2551
2551
|
* silently, and a full pass records `namesIn` as the whole set, so the loss is
|
|
2552
|
-
* frozen for every later pass. That is the defect this class exists to
|
|
2552
|
+
* frozen for every later pass. That is the first defect this class exists to
|
|
2553
|
+
* close.
|
|
2553
2554
|
*
|
|
2554
2555
|
* So: a pass requested from inside a pass only marks the batch dirty, and the
|
|
2555
2556
|
* frame that owns the batch runs one more pass when it is complete — which is
|
|
@@ -2557,6 +2558,23 @@ function forwardProjectTools(options) {
|
|
|
2557
2558
|
* the old batch is released **before** the new one is registered, because one
|
|
2558
2559
|
* layer holds one entry per name: registering over a live batch would refuse
|
|
2559
2560
|
* every name it already had.
|
|
2561
|
+
*
|
|
2562
|
+
* Owning the re-entry is not enough on its own, and the shape of the event is
|
|
2563
|
+
* why. Replacing a batch of N entries announces 2·N changes — one per disposal
|
|
2564
|
+
* and one per registration — and the event carries no origin, so every session
|
|
2565
|
+
* watching the stream runs a pass for every one of them, and every pass begins
|
|
2566
|
+
* by projecting the project's whole catalog, which the registry answers by deep
|
|
2567
|
+
* cloning each visible definition's JSON schema. The registry per pass is what
|
|
2568
|
+
* makes that cost real: one MCP generation swap was measured holding the event
|
|
2569
|
+
* loop for the full 54 seconds of a CPU profile (47% of its samples inside this
|
|
2570
|
+
* sync, 52% in the collector the projections feed), while the plugin's own
|
|
2571
|
+
* frames were 0.46% of it. So {@link note} is the seat a `tools/change`
|
|
2572
|
+
* subscription takes, not {@link sync}: a change that arrives during a pass is
|
|
2573
|
+
* absorbed by it, and a burst that arrives between passes costs **one** queued
|
|
2574
|
+
* pass however many events it carries. A stale forwarder is safe in the window
|
|
2575
|
+
* that opens — it resolves the project entry at call time and fails closed when
|
|
2576
|
+
* there is none (`forwarder`) — and every read path brings the batch level
|
|
2577
|
+
* before it reads, so a reader never waits for the queue.
|
|
2560
2578
|
*/
|
|
2561
2579
|
var ForwardBatch = class {
|
|
2562
2580
|
options;
|
|
@@ -2568,6 +2586,8 @@ var ForwardBatch = class {
|
|
|
2568
2586
|
#building = false;
|
|
2569
2587
|
/** Whether a pass asked for while {@link #building} still needs a run. */
|
|
2570
2588
|
#again = false;
|
|
2589
|
+
/** Whether a scheduled pass is already waiting for a burst of changes. */
|
|
2590
|
+
#queued = false;
|
|
2571
2591
|
constructor(options) {
|
|
2572
2592
|
this.options = options;
|
|
2573
2593
|
}
|
|
@@ -2582,11 +2602,12 @@ var ForwardBatch = class {
|
|
|
2582
2602
|
return this.#namesIn;
|
|
2583
2603
|
}
|
|
2584
2604
|
/**
|
|
2585
|
-
* Bring the session's layer level with the project's live tool set.
|
|
2605
|
+
* Bring the session's layer level with the project's live tool set, now.
|
|
2586
2606
|
*
|
|
2587
2607
|
* Cheap when it already is: an unchanged set short-circuits and leaves the
|
|
2588
2608
|
* live batch — and its generation of definitions — untouched. Re-entrant
|
|
2589
|
-
* while registering
|
|
2609
|
+
* while registering, and bounded to {@link MAX_SYNC_PASSES} synchronous
|
|
2610
|
+
* rounds so no registry state can hold the caller's frame: see the class note.
|
|
2590
2611
|
* @returns nothing; a failure from the probe or the registry propagates.
|
|
2591
2612
|
*/
|
|
2592
2613
|
sync() {
|
|
@@ -2594,17 +2615,42 @@ var ForwardBatch = class {
|
|
|
2594
2615
|
this.#again = true;
|
|
2595
2616
|
return;
|
|
2596
2617
|
}
|
|
2618
|
+
this.#queued = false;
|
|
2597
2619
|
this.#building = true;
|
|
2598
2620
|
try {
|
|
2599
|
-
|
|
2621
|
+
for (let pass = 0; pass < 4; pass += 1) {
|
|
2600
2622
|
this.#again = false;
|
|
2601
2623
|
this.#syncOnce();
|
|
2602
|
-
|
|
2624
|
+
if (!this.#again) return;
|
|
2625
|
+
}
|
|
2626
|
+
this.#schedule(true);
|
|
2603
2627
|
} finally {
|
|
2604
2628
|
this.#building = false;
|
|
2605
2629
|
}
|
|
2606
2630
|
}
|
|
2607
2631
|
/**
|
|
2632
|
+
* Note that the registry changed, and bring the batch level — off this stack.
|
|
2633
|
+
*
|
|
2634
|
+
* This is the seat a `tools/change` subscription takes, and the reason it is
|
|
2635
|
+
* not {@link sync}: the event is emitted once per entry registered and once
|
|
2636
|
+
* per entry disposed, from inside the registry's own insertion and removal,
|
|
2637
|
+
* so one MCP generation swap is a burst of thousands. A change that arrives
|
|
2638
|
+
* while a pass is running is absorbed by that pass — it re-reads the set it is
|
|
2639
|
+
* replacing before it returns — and a burst that arrives between passes costs
|
|
2640
|
+
* one pass: the first queues, every later one folds into it.
|
|
2641
|
+
*
|
|
2642
|
+
* Nothing reads a stale layer for it. Every read path brings the batch level
|
|
2643
|
+
* first (`src/runtime.ts`, `mountedSchemas`), and the queued pass has run
|
|
2644
|
+
* before any turn that could read the layer at all.
|
|
2645
|
+
*/
|
|
2646
|
+
note() {
|
|
2647
|
+
if (this.#building) {
|
|
2648
|
+
this.#again = true;
|
|
2649
|
+
return;
|
|
2650
|
+
}
|
|
2651
|
+
this.#schedule(false);
|
|
2652
|
+
}
|
|
2653
|
+
/**
|
|
2608
2654
|
* Drop the live batch: the session keeps no forwarder, and the next
|
|
2609
2655
|
* {@link sync} starts from nothing rather than amending a stale set.
|
|
2610
2656
|
* Idempotent.
|
|
@@ -2613,16 +2659,45 @@ var ForwardBatch = class {
|
|
|
2613
2659
|
* session is subscribed to that event; a pass re-entered from there must not
|
|
2614
2660
|
* resurrect the batch it is watching being dropped. So the guard is held for
|
|
2615
2661
|
* the whole release, and the pass it queues is discarded rather than run.
|
|
2662
|
+
*
|
|
2663
|
+
* The guard is *held*, not taken: a drop that runs inside a pass — a detach
|
|
2664
|
+
* driven from a listener, a scope torn down under a registration — restores
|
|
2665
|
+
* the pass's own `building` rather than clearing it. Clearing it there would
|
|
2666
|
+
* let the next `tools/change` start a nested pass inside a frame that still
|
|
2667
|
+
* owns one, which is exactly the re-entry this class exists to own.
|
|
2616
2668
|
*/
|
|
2617
2669
|
drop() {
|
|
2670
|
+
const building = this.#building;
|
|
2618
2671
|
this.#building = true;
|
|
2619
2672
|
try {
|
|
2620
2673
|
this.#releaseBatch();
|
|
2621
2674
|
} finally {
|
|
2622
|
-
this.#building =
|
|
2675
|
+
this.#building = building;
|
|
2623
2676
|
this.#again = false;
|
|
2677
|
+
this.#queued = false;
|
|
2624
2678
|
}
|
|
2625
2679
|
}
|
|
2680
|
+
/**
|
|
2681
|
+
* Queue the one deferred pass a burst of changes needs.
|
|
2682
|
+
* @param yielding - run it on the timer queue rather than the microtask queue.
|
|
2683
|
+
* A pass that overran {@link MAX_SYNC_PASSES} asks for this: a chain of
|
|
2684
|
+
* microtasks still starves timers and I/O, a round of timers does not.
|
|
2685
|
+
*/
|
|
2686
|
+
#schedule(yielding) {
|
|
2687
|
+
if (this.#queued) return;
|
|
2688
|
+
this.#queued = true;
|
|
2689
|
+
const run = () => {
|
|
2690
|
+
if (!this.#queued) return;
|
|
2691
|
+
this.#queued = false;
|
|
2692
|
+
try {
|
|
2693
|
+
this.sync();
|
|
2694
|
+
} catch (error) {
|
|
2695
|
+
this.options.onError?.(error);
|
|
2696
|
+
}
|
|
2697
|
+
};
|
|
2698
|
+
if (yielding) setTimeout(run, 0);
|
|
2699
|
+
else queueMicrotask(run);
|
|
2700
|
+
}
|
|
2626
2701
|
/** One pass: read the project's set, then replace the batch when it moved. */
|
|
2627
2702
|
#syncOnce() {
|
|
2628
2703
|
const names = this.options.names();
|
|
@@ -5424,23 +5499,30 @@ var ProjectMcpRuntime = class {
|
|
|
5424
5499
|
const bridge = {
|
|
5425
5500
|
batch: new ForwardBatch({
|
|
5426
5501
|
names: () => {
|
|
5502
|
+
const project = state.project;
|
|
5503
|
+
if (project === void 0) return void 0;
|
|
5427
5504
|
try {
|
|
5428
|
-
return projectToolNames(
|
|
5505
|
+
return projectToolNames(project.key, (scope) => this.bridgeSchemas(scope), servers());
|
|
5429
5506
|
} catch (error) {
|
|
5430
5507
|
this.ctx.logger.warn(`project-mcp: reading the tools to forward to session ${state.agent.id} failed: ${errorText(error)}`);
|
|
5431
5508
|
return;
|
|
5432
5509
|
}
|
|
5433
5510
|
},
|
|
5434
|
-
register: (names) =>
|
|
5435
|
-
|
|
5436
|
-
|
|
5437
|
-
|
|
5438
|
-
|
|
5439
|
-
|
|
5511
|
+
register: (names) => {
|
|
5512
|
+
const project = state.project;
|
|
5513
|
+
if (project === void 0) return () => void 0;
|
|
5514
|
+
return forwardProjectTools({
|
|
5515
|
+
ctx: context,
|
|
5516
|
+
project: project.key,
|
|
5517
|
+
names,
|
|
5518
|
+
registry
|
|
5519
|
+
});
|
|
5520
|
+
},
|
|
5521
|
+
onError: (error) => this.reportBridgeFailure(state, error)
|
|
5440
5522
|
}),
|
|
5441
5523
|
detach: () => void 0
|
|
5442
5524
|
};
|
|
5443
|
-
const detach = state.scope.ctx.on("tools/change", () => this.
|
|
5525
|
+
const detach = state.scope.ctx.on("tools/change", () => this.noteBridge(state));
|
|
5444
5526
|
bridge.detach = typeof detach === "function" ? detach : () => void 0;
|
|
5445
5527
|
state.bridge = bridge;
|
|
5446
5528
|
this.syncBridge(state);
|
|
@@ -5461,9 +5543,37 @@ var ProjectMcpRuntime = class {
|
|
|
5461
5543
|
try {
|
|
5462
5544
|
bridge.batch.sync();
|
|
5463
5545
|
} catch (error) {
|
|
5464
|
-
this.
|
|
5546
|
+
this.reportBridgeFailure(state, error);
|
|
5465
5547
|
}
|
|
5466
5548
|
}
|
|
5549
|
+
/**
|
|
5550
|
+
* Note one registry change for one session's bridge, off the emitter's stack.
|
|
5551
|
+
*
|
|
5552
|
+
* The event this answers is emitted synchronously from inside the registry's
|
|
5553
|
+
* own insertion and removal — once per entry in, once per entry out — so one
|
|
5554
|
+
* MCP generation swap is a burst of thousands. Running the pass here would
|
|
5555
|
+
* make whoever registered a tool pay for every session watching the project,
|
|
5556
|
+
* and each pass projects the project's whole catalog. The batch folds the
|
|
5557
|
+
* burst into one queued pass instead, which is also why this is not
|
|
5558
|
+
* {@link syncBridge}: the read paths, the mount settle and the scope wiring
|
|
5559
|
+
* all bring the batch level synchronously, before anything reads the layer.
|
|
5560
|
+
* @param state - the session whose bridge noticed the change.
|
|
5561
|
+
*/
|
|
5562
|
+
noteBridge(state) {
|
|
5563
|
+
state.bridge?.batch.note();
|
|
5564
|
+
}
|
|
5565
|
+
/**
|
|
5566
|
+
* Write the one warning line a failed bridge pass is allowed.
|
|
5567
|
+
*
|
|
5568
|
+
* Shared by the synchronous pass and by the one a batch runs on its own: a
|
|
5569
|
+
* scheduled pass has no caller left to propagate its failure to, so the batch
|
|
5570
|
+
* hands it here through `onError` rather than swallowing it.
|
|
5571
|
+
* @param state - the session whose bridge failed.
|
|
5572
|
+
* @param error - what the pass threw.
|
|
5573
|
+
*/
|
|
5574
|
+
reportBridgeFailure(state, error) {
|
|
5575
|
+
this.ctx.logger.warn(`project-mcp: forwarding the tools of ${state.project?.projectRoot ?? "the project"} into session ${state.agent.id} failed: ${errorText(error)}`);
|
|
5576
|
+
}
|
|
5467
5577
|
/** The project scope's visible schemas, as {@link projectToolNames} reads them. */
|
|
5468
5578
|
bridgeSchemas(scope) {
|
|
5469
5579
|
return this.bridgeRegistry().schemas(scope);
|