dsh-project-mcp 0.4.0 → 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/README.md CHANGED
@@ -430,12 +430,32 @@ request gets the registry's own tool list plus the active schemas, deduplicated
430
430
  by name, and `activationEnabled: false` turns the whole mechanism off (every
431
431
  mounted tool is listed exactly as before, and no search tool is registered).
432
432
 
433
- Implementation note — the presentation rides the agent's own
434
- `system-prompt/assemble` waterfall, registered *prepended* so it runs outermost
435
- and sees the list after other presentation plugins (for example
433
+ Implementation note — the mechanism depends on which harness runs it, because
434
+ DSH 0.2.2 moved declarations out of the prompt assembly. From 0.2.2 on,
435
+ `system-prompt/assemble` transforms a presentation (`sections`, `contexts`,
436
+ `variables`) and carries **no tool list**: the declared schemas come from
437
+ `systemPrompt.tools()` providers and the harness attaches them after the
438
+ waterfall, so a listener writing into `assembly.tools` writes into a field the
439
+ harness discards. The presentation therefore rides this plugin's own
440
+ registrations: the thin per-session forwarders of the F-19 bridge carry
441
+ `deferLoading`, the harness projects that flag onto the model-facing schema, and
442
+ an adapter that understands it (the shipped `dsh-llm-pi-ai` route) leaves the
443
+ definition out of the wire request while the registry keeps the tool admitted for
444
+ dispatch. That is what keeps the paragraph above true on the new harness: the
445
+ tool is invisible to the model and still callable by its exact full name, and
446
+ nothing is unregistered. `installActivation`'s `onOfferedChanged` is what keeps
447
+ the flags level — a search activation, a compaction boundary, a context advance
448
+ and a policy edit each queue one coalesced bridge pass (`ForwardBatch.note`), and
449
+ a pass re-registers only when the names *or* the deferred subset moved.
450
+
451
+ On an older harness the same module still rewrites the assembly list, through the
452
+ agent's own `system-prompt/assemble` waterfall, registered *prepended* so it runs
453
+ outermost and sees the list after other presentation plugins (for example
436
454
  `dsh-progressive-tools`) filtered it. That listener is contained: if this
437
455
  plugin's own work fails, the assembly the rest of the harness produced is
438
- returned unchanged, so a broken probe can never break a model request. One
456
+ returned unchanged, so a broken probe can never break a model request; on a
457
+ harness that hands it a presentation without `tools`, it leaves the document
458
+ alone by identity. One
439
459
  residual ordering risk remains: a presentation plugin that trims the list to its
440
460
  own allowlist and ends up *outside* this listener (it registered its own
441
461
  prepended listener later) drops the schemas this plugin added, leaving only the
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
@@ -111,6 +115,20 @@ interface ForwardableDefinition extends BridgeToolSchema {
111
115
  };
112
116
  /** Cooperative timeout budget, preserved for the timeout policy wrapper. */
113
117
  readonly timeoutMs?: number;
118
+ /**
119
+ * Deferred-loading request, owned by the presentation rather than by the
120
+ * project.
121
+ *
122
+ * The harness projects this flag onto the model-facing schema
123
+ * (`projectToolSchema`), and an adapter that understands it (the shipped
124
+ * `dsh-llm-pi-ai` route omits such a schema from the wire request) then leaves
125
+ * the definition out of the model's tool list while the registry keeps the
126
+ * tool admitted for dispatch — a tool the model does not see but can still
127
+ * call by its exact full name. It is set on the forwarder, never copied from
128
+ * the project, because which of a session's tools are offered is this plugin's
129
+ * presentation decision.
130
+ */
131
+ readonly deferLoading?: true;
114
132
  /**
115
133
  * Pure sibling-overlap classifier. Preserved: a forwarder that dropped it
116
134
  * would make every forwarded call exclusive while the project tool is
@@ -206,13 +224,36 @@ interface ForwardBatchOptions {
206
224
  * @returns the names this session should forward, or `undefined` on failure.
207
225
  */
208
226
  readonly names: () => readonly string[] | undefined;
227
+ /**
228
+ * The names this session presents as deferred — hidden from the model's tool
229
+ * list while the registry keeps them callable — read once on every pass.
230
+ *
231
+ * A pass whose names matched but whose deferred set moved still re-registers:
232
+ * `deferLoading` is baked into the definition at registration, so the flag a
233
+ * schema carries is exactly the flag its forwarder was registered with.
234
+ * Absent defers none, which is the presentation of a session with nothing
235
+ * hidden.
236
+ * @returns the deferred names, or none.
237
+ */
238
+ readonly deferred?: () => readonly string[];
209
239
  /**
210
240
  * Register one batch of forwarders over the session's layer, which this call
211
241
  * reaches empty-handed: the batch it replaces is released first.
212
242
  * @param names - the names to forward, in registry order.
243
+ * @param deferred - the names of this batch that carry `deferLoading`.
213
244
  * @returns the exact releaser that drops the whole batch.
214
245
  */
215
- readonly register: (names: readonly string[]) => () => void;
246
+ readonly register: (names: readonly string[], deferred: ReadonlySet<string>) => () => void;
247
+ /**
248
+ * Report a failure thrown by a pass this batch ran on its own.
249
+ *
250
+ * A pass requested by {@link ForwardBatch.note} runs off the caller's stack:
251
+ * the registry call that announced the change has already returned, and so
252
+ * has every frame that could have propagated the failure. Without this the
253
+ * batch would go quiet — no forwarder, and no trace of why.
254
+ * @param error - what the scheduled pass threw.
255
+ */
256
+ readonly onError?: (error: unknown) => void;
216
257
  }
217
258
  /**
218
259
  * One session's live forwarding batch, kept level with the project's live tools.
@@ -226,7 +267,8 @@ interface ForwardBatchOptions {
226
267
  * which the live first copy refuses as a duplicate. A bridge that steps aside
227
268
  * for a duplicate (it must, for the session's own tools) then drops those names
228
269
  * 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.
270
+ * frozen for every later pass. That is the first defect this class exists to
271
+ * close.
230
272
  *
231
273
  * So: a pass requested from inside a pass only marks the batch dirty, and the
232
274
  * frame that owns the batch runs one more pass when it is complete — which is
@@ -234,6 +276,23 @@ interface ForwardBatchOptions {
234
276
  * the old batch is released **before** the new one is registered, because one
235
277
  * layer holds one entry per name: registering over a live batch would refuse
236
278
  * every name it already had.
279
+ *
280
+ * Owning the re-entry is not enough on its own, and the shape of the event is
281
+ * why. Replacing a batch of N entries announces 2·N changes — one per disposal
282
+ * and one per registration — and the event carries no origin, so every session
283
+ * watching the stream runs a pass for every one of them, and every pass begins
284
+ * by projecting the project's whole catalog, which the registry answers by deep
285
+ * cloning each visible definition's JSON schema. The registry per pass is what
286
+ * makes that cost real: one MCP generation swap was measured holding the event
287
+ * loop for the full 54 seconds of a CPU profile (47% of its samples inside this
288
+ * sync, 52% in the collector the projections feed), while the plugin's own
289
+ * frames were 0.46% of it. So {@link note} is the seat a `tools/change`
290
+ * subscription takes, not {@link sync}: a change that arrives during a pass is
291
+ * absorbed by it, and a burst that arrives between passes costs **one** queued
292
+ * pass however many events it carries. A stale forwarder is safe in the window
293
+ * that opens — it resolves the project entry at call time and fails closed when
294
+ * there is none (`forwarder`) — and every read path brings the batch level
295
+ * before it reads, so a reader never waits for the queue.
237
296
  */
238
297
  declare class ForwardBatch {
239
298
  #private;
@@ -248,14 +307,31 @@ declare class ForwardBatch {
248
307
  */
249
308
  get namesIn(): readonly string[] | undefined;
250
309
  /**
251
- * Bring the session's layer level with the project's live tool set.
310
+ * Bring the session's layer level with the project's live tool set, now.
252
311
  *
253
312
  * Cheap when it already is: an unchanged set short-circuits and leaves the
254
313
  * live batch — and its generation of definitions — untouched. Re-entrant
255
- * while registering: see the class note.
314
+ * while registering, and bounded to {@link MAX_SYNC_PASSES} synchronous
315
+ * rounds so no registry state can hold the caller's frame: see the class note.
256
316
  * @returns nothing; a failure from the probe or the registry propagates.
257
317
  */
258
318
  sync(): void;
319
+ /**
320
+ * Note that the registry changed, and bring the batch level — off this stack.
321
+ *
322
+ * This is the seat a `tools/change` subscription takes, and the reason it is
323
+ * not {@link sync}: the event is emitted once per entry registered and once
324
+ * per entry disposed, from inside the registry's own insertion and removal,
325
+ * so one MCP generation swap is a burst of thousands. A change that arrives
326
+ * while a pass is running is absorbed by that pass — it re-reads the set it is
327
+ * replacing before it returns — and a burst that arrives between passes costs
328
+ * one pass: the first queues, every later one folds into it.
329
+ *
330
+ * Nothing reads a stale layer for it. Every read path brings the batch level
331
+ * first (`src/runtime.ts`, `mountedSchemas`), and the queued pass has run
332
+ * before any turn that could read the layer at all.
333
+ */
334
+ note(): void;
259
335
  /**
260
336
  * Drop the live batch: the session keeps no forwarder, and the next
261
337
  * {@link sync} starts from nothing rather than amending a stale set.
@@ -265,6 +341,12 @@ declare class ForwardBatch {
265
341
  * session is subscribed to that event; a pass re-entered from there must not
266
342
  * resurrect the batch it is watching being dropped. So the guard is held for
267
343
  * the whole release, and the pass it queues is discarded rather than run.
344
+ *
345
+ * The guard is *held*, not taken: a drop that runs inside a pass — a detach
346
+ * driven from a listener, a scope torn down under a registration — restores
347
+ * the pass's own `building` rather than clearing it. Clearing it there would
348
+ * let the next `tools/change` start a nested pass inside a frame that still
349
+ * owns one, which is exactly the re-entry this class exists to own.
268
350
  */
269
351
  drop(): void;
270
352
  }
@@ -1358,6 +1440,18 @@ interface ActivationWiringOptions {
1358
1440
  * the same name may carry the step of the offer the compaction removed.
1359
1441
  */
1360
1442
  readonly onCompaction?: () => void;
1443
+ /**
1444
+ * Told that the offered set may have moved: a search activated names, a
1445
+ * compaction dropped the ones no call backed, or the context tier advanced.
1446
+ *
1447
+ * A harness whose assembly carries no tool list cannot be filtered from this
1448
+ * module at all (0.2.2 and later: declarations are provider-owned), so the
1449
+ * presentation lives in the caller's own registrations instead — the bridge's
1450
+ * `deferLoading` forwarders. This is the seat that keeps that copy level with
1451
+ * {@link ActivationState}; absent simply means nothing presents the set but the
1452
+ * assembly this module used to rewrite.
1453
+ */
1454
+ readonly onOfferedChanged?: () => void;
1361
1455
  /** Context-driven state to start from; defaults to an empty state. */
1362
1456
  readonly autoState?: AutoOfferState;
1363
1457
  /** Sink for the context-driven state after every advance that changed it. */
@@ -2169,6 +2263,42 @@ export declare class ProjectMcpRuntime {
2169
2263
  * @returns the stored policy, or {@link DEFAULT_TOOL_POLICY} when there is none.
2170
2264
  */
2171
2265
  private policyFor;
2266
+ /**
2267
+ * Re-apply the presentation of every session working in one project.
2268
+ *
2269
+ * A pin or a mode is read live by the panel and by the guidance, but the
2270
+ * forwarders carry their `deferLoading` flag from the pass that registered
2271
+ * them, so the sessions of that project have to run one — off the caller's
2272
+ * stack, like every other change note.
2273
+ * @param projectRoot - the project whose policy just moved.
2274
+ */
2275
+ private refreshPresentation;
2276
+ /**
2277
+ * The names one session's presentation offers the model right now.
2278
+ *
2279
+ * The counterpart of the assembly wiring's own `offeredNames`, read where the
2280
+ * presentation lives outside that assembly — in the bridge's forwarders. It is
2281
+ * the counter-seeded baseline, the session's activations, the context tier's
2282
+ * window, and the project's pins; the same four sources the assembly-side
2283
+ * `wanted` set is built from, so the two cannot drift.
2284
+ * @param state - the session to read.
2285
+ * @returns the offered public names.
2286
+ */
2287
+ private offeredNamesOf;
2288
+ /**
2289
+ * The names one session presents as deferred: what it mounts that it does not
2290
+ * offer.
2291
+ *
2292
+ * Empty when there is nothing to defer — activation off, `direct`, or a
2293
+ * surface that fits the budget — because deferring a schema the request would
2294
+ * have carried anyway only makes the declaration list harder to read, and the
2295
+ * prefix-cache argument for it is gone. The budget is the same
2296
+ * {@link surfaceChars} reading the panel and the assembly gate use, so the
2297
+ * deferred set and the "hidden" number a panel shows are one decision.
2298
+ * @param state - the session whose presentation is being registered.
2299
+ * @returns the names whose forwarders carry `deferLoading`, in registry order.
2300
+ */
2301
+ private deferredNamesOf;
2172
2302
  /**
2173
2303
  * Whether one project root has a live session on this host.
2174
2304
  * @param projectRoot - project root a policy request names.
@@ -2590,6 +2720,30 @@ export declare class ProjectMcpRuntime {
2590
2720
  * @param state - the session whose bridge to sync.
2591
2721
  */
2592
2722
  private syncBridge;
2723
+ /**
2724
+ * Note one registry change for one session's bridge, off the emitter's stack.
2725
+ *
2726
+ * The event this answers is emitted synchronously from inside the registry's
2727
+ * own insertion and removal — once per entry in, once per entry out — so one
2728
+ * MCP generation swap is a burst of thousands. Running the pass here would
2729
+ * make whoever registered a tool pay for every session watching the project,
2730
+ * and each pass projects the project's whole catalog. The batch folds the
2731
+ * burst into one queued pass instead, which is also why this is not
2732
+ * {@link syncBridge}: the read paths, the mount settle and the scope wiring
2733
+ * all bring the batch level synchronously, before anything reads the layer.
2734
+ * @param state - the session whose bridge noticed the change.
2735
+ */
2736
+ private noteBridge;
2737
+ /**
2738
+ * Write the one warning line a failed bridge pass is allowed.
2739
+ *
2740
+ * Shared by the synchronous pass and by the one a batch runs on its own: a
2741
+ * scheduled pass has no caller left to propagate its failure to, so the batch
2742
+ * hands it here through `onError` rather than swallowing it.
2743
+ * @param state - the session whose bridge failed.
2744
+ * @param error - what the pass threw.
2745
+ */
2746
+ private reportBridgeFailure;
2593
2747
  /** The project scope's visible schemas, as {@link projectToolNames} reads them. */
2594
2748
  private bridgeSchemas;
2595
2749
  /** Drop one session's bridge: its forwarders and its subscription. Idempotent. */