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 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 close.
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: see the class note.
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 close.
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: see the class note.
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
- do {
2621
+ for (let pass = 0; pass < 4; pass += 1) {
2600
2622
  this.#again = false;
2601
2623
  this.#syncOnce();
2602
- } while (this.#again);
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 = false;
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(state.project?.key ?? {}, (scope) => this.bridgeSchemas(scope), servers());
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) => forwardProjectTools({
5435
- ctx: context,
5436
- project: state.project?.key ?? {},
5437
- names,
5438
- registry
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.syncBridge(state));
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.ctx.logger.warn(`project-mcp: forwarding the tools of ${state.project?.projectRoot ?? "the project"} into session ${state.agent.id} failed: ${errorText(error)}`);
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);