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 +24 -4
- package/lib/index.d.ts +159 -5
- package/lib/index.js +226 -20
- package/lib/index.js.map +1 -1
- package/package.json +1 -1
- package/src/activation.ts +34 -1
- package/src/bridge.ts +196 -11
- package/src/runtime.ts +131 -12
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
|
|
434
|
-
|
|
435
|
-
|
|
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
|
|
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
|
|
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
|
|
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. */
|