dsh-project-mcp 0.3.1 → 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/README.md +38 -23
- package/lib/client.js +15 -15
- package/lib/client.js.map +1 -1
- package/lib/index.d.ts +181 -27
- package/lib/index.js +273 -61
- package/lib/index.js.map +1 -1
- package/package.json +18 -17
- package/src/activation.ts +164 -43
- package/src/bridge.ts +114 -7
- package/src/client/locales/ui.ts +6 -6
- package/src/client/plugin-config.ts +9 -9
- package/src/runtime.ts +77 -19
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
|
}
|
|
@@ -964,12 +1019,28 @@ interface SnapshotChange {
|
|
|
964
1019
|
//#region src/activation.d.ts
|
|
965
1020
|
/** `true` while the session may offer MCP tools through search + activation. */
|
|
966
1021
|
export declare const DEFAULT_ACTIVATION_ENABLED = true;
|
|
967
|
-
/**
|
|
968
|
-
|
|
969
|
-
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
export declare const
|
|
1022
|
+
/**
|
|
1023
|
+
* Tools seeded into the baseline from the durable counters. A project with a
|
|
1024
|
+
* few dozen mounted tools calls more than a handful of them, so the cap sits
|
|
1025
|
+
* above the narrow window that used to evict a tool the project really uses.
|
|
1026
|
+
*/
|
|
1027
|
+
export declare const DEFAULT_ACTIVATION_SEEDED = 16;
|
|
1028
|
+
/**
|
|
1029
|
+
* Calls one tool needs in the counters before it is seeded. One call is enough:
|
|
1030
|
+
* a tool the project actually uses enters the durable baseline the first time it
|
|
1031
|
+
* is called, so the baseline grows from real usage instead of waiting for the
|
|
1032
|
+
* counters to reach an arbitrary threshold.
|
|
1033
|
+
*/
|
|
1034
|
+
export declare const DEFAULT_ACTIVATION_MIN_CALLS = 1;
|
|
1035
|
+
/**
|
|
1036
|
+
* How long a session-activated tool survives without a call (`0` disables).
|
|
1037
|
+
*
|
|
1038
|
+
* The shipped `0` keeps a searched tool offered for the rest of the session:
|
|
1039
|
+
* dropping it mid-session shrinks the request and rewrites the prompt prefix,
|
|
1040
|
+
* which invalidates the provider's prefix cache, so time-based removal stays an
|
|
1041
|
+
* explicit opt-in.
|
|
1042
|
+
*/
|
|
1043
|
+
export declare const DEFAULT_TOOL_IDLE_MS = 0;
|
|
973
1044
|
/** Matches one `mcp_search_tools` call activates when it omits `limit`. */
|
|
974
1045
|
export declare const DEFAULT_SEARCH_LIMIT = 8;
|
|
975
1046
|
/** Hard cap on matches one `mcp_search_tools` call may activate. */
|
|
@@ -1083,20 +1154,35 @@ interface SessionEventLike {
|
|
|
1083
1154
|
* One session's activation state.
|
|
1084
1155
|
*
|
|
1085
1156
|
* `baseline` is the counter-seeded set and outlives a compaction; `active` holds
|
|
1086
|
-
* the names this session activated through search, each with
|
|
1087
|
-
* milliseconds of its last touch, and is what idle pruning and
|
|
1088
|
-
*
|
|
1157
|
+
* the names this session activated through search or the context tier, each with
|
|
1158
|
+
* the epoch milliseconds of its last touch, and is what idle pruning and
|
|
1159
|
+
* compaction trim. `used` records the calls the session made for this plugin's
|
|
1160
|
+
* own namespace — the evidence a compaction keeps an activation by, because a
|
|
1161
|
+
* tool the model called is one the session really uses. It is cumulative for the
|
|
1162
|
+
* session and never bounded, so the compaction boundary shrinks the offers no
|
|
1163
|
+
* call backs and never shrinks a used tool again.
|
|
1164
|
+
*
|
|
1165
|
+
* Every field is read-only because every transition returns a new state.
|
|
1089
1166
|
*/
|
|
1090
1167
|
interface ActivationState {
|
|
1091
1168
|
/** Public names the durable counters proved hot; always offered. */
|
|
1092
1169
|
readonly baseline: ReadonlySet<string>;
|
|
1093
1170
|
/** Session-activated public names mapped to their last touch. */
|
|
1094
1171
|
readonly active: ReadonlyMap<string, number>;
|
|
1172
|
+
/**
|
|
1173
|
+
* `mcp__` names this session called at least once and the durable baseline
|
|
1174
|
+
* does not already keep. Read by nothing but {@link onCompaction}, and
|
|
1175
|
+
* cumulative for the session: it is deliberately never bounded, so with the
|
|
1176
|
+
* shipped `DEFAULT_TOOL_IDLE_MS` of `0` nothing else removes a name and a tool
|
|
1177
|
+
* the session used stays offered for the rest of the session, across every
|
|
1178
|
+
* further compaction.
|
|
1179
|
+
*/
|
|
1180
|
+
readonly used: ReadonlySet<string>;
|
|
1095
1181
|
}
|
|
1096
1182
|
/**
|
|
1097
1183
|
* Build one session's state.
|
|
1098
1184
|
* @param baseline - counter-seeded public names; defaults to none.
|
|
1099
|
-
* @returns an empty active set over that baseline.
|
|
1185
|
+
* @returns an empty active set and an empty used record over that baseline.
|
|
1100
1186
|
*/
|
|
1101
1187
|
export declare function createActivationState(baseline?: Iterable<string>): ActivationState;
|
|
1102
1188
|
/** How {@link seedFromUsage} reads the durable counters. */
|
|
@@ -1134,9 +1220,16 @@ export declare function seedFromUsage(usage: Record<string, ServerUsage> | undef
|
|
|
1134
1220
|
*/
|
|
1135
1221
|
export declare function activate(state: ActivationState, names: Iterable<string>, at: number): ActivationState;
|
|
1136
1222
|
/**
|
|
1137
|
-
*
|
|
1138
|
-
* keeps
|
|
1139
|
-
*
|
|
1223
|
+
* Record a call — the freshness of a session-activated tool and the evidence a
|
|
1224
|
+
* compaction keeps it by.
|
|
1225
|
+
*
|
|
1226
|
+
* `active` is refreshed exactly as before: a call is what keeps a
|
|
1227
|
+
* session-activated tool offered. `used` records the call itself, but only for
|
|
1228
|
+
* this plugin's own namespace: the core tools (`read`, `bash`, …) ride the same
|
|
1229
|
+
* `tools/result` hook, and they are no part of a session's MCP activation state.
|
|
1230
|
+
* A baseline name is not recorded either — the durable baseline already keeps it
|
|
1231
|
+
* offered, so recording the call would only make a compaction look like it
|
|
1232
|
+
* changed something.
|
|
1140
1233
|
*
|
|
1141
1234
|
* @param state - activation state before the call.
|
|
1142
1235
|
* @param name - public name of the called tool.
|
|
@@ -1149,6 +1242,13 @@ export declare function noteUse(state: ActivationState, name: string, at: number
|
|
|
1149
1242
|
* The baseline is never pruned: it comes from the durable counters, not from the
|
|
1150
1243
|
* session. `idleMs <= 0` disables pruning.
|
|
1151
1244
|
*
|
|
1245
|
+
* A positive `idleMs` is an explicit opt-in to *forgetting*: an evicted name
|
|
1246
|
+
* leaves the used record with the offer it was about, so the sweep is final —
|
|
1247
|
+
* a later compaction cannot read the call back and resurrect what time already
|
|
1248
|
+
* dropped. A name the model needs again is activated again through search. The
|
|
1249
|
+
* names still inside the window keep their record, and a sweep that evicts
|
|
1250
|
+
* nothing returns its input.
|
|
1251
|
+
*
|
|
1152
1252
|
* @param state - activation state at `now`.
|
|
1153
1253
|
* @param now - epoch milliseconds of the sweep.
|
|
1154
1254
|
* @param idleMs - age at which a tool falls out.
|
|
@@ -1156,12 +1256,31 @@ export declare function noteUse(state: ActivationState, name: string, at: number
|
|
|
1156
1256
|
*/
|
|
1157
1257
|
export declare function pruneIdle(state: ActivationState, now: number, idleMs: number): ActivationState;
|
|
1158
1258
|
/**
|
|
1159
|
-
* End the session's activations
|
|
1160
|
-
*
|
|
1259
|
+
* End the session's activations that no call backs, at the compaction boundary.
|
|
1260
|
+
*
|
|
1261
|
+
* A compaction rewrites the conversation, so the provider's prompt prefix is
|
|
1262
|
+
* recomputed anyway: this is the one boundary where dropping a tool costs no
|
|
1263
|
+
* cache, which is why idle time is off by default and why this is the only place
|
|
1264
|
+
* the offered set shrinks. Only the part the session never used goes — an offer
|
|
1265
|
+
* from a context match or a search that the model did not act on. A tool this
|
|
1266
|
+
* session did call is one it really uses, so it stays active, stamped with its
|
|
1267
|
+
* last touch; evicting it would charge a re-discovery step for a tool the
|
|
1268
|
+
* session demonstrably needs. A used name that was never activated falls back to
|
|
1269
|
+
* the compaction's own clock. The counter baseline is never pruned.
|
|
1270
|
+
*
|
|
1271
|
+
* The used record is cumulative for the session and deliberately never bounded:
|
|
1272
|
+
* with the shipped `DEFAULT_TOOL_IDLE_MS` of `0` nothing else removes a name, so
|
|
1273
|
+
* a tool the session used stays offered for the rest of the session, across every
|
|
1274
|
+
* further compaction. This boundary shrinks the offers no call backs — it never
|
|
1275
|
+
* shrinks one the session used again.
|
|
1276
|
+
*
|
|
1161
1277
|
* @param state - activation state before the compaction.
|
|
1162
|
-
* @
|
|
1278
|
+
* @param at - epoch milliseconds of the compaction.
|
|
1279
|
+
* @returns the updated state, or the input when nothing was active or used, or
|
|
1280
|
+
* when the rebuild is equivalent to what is already there — a caller compares
|
|
1281
|
+
* by identity to tell a real change from a boundary that changed nothing.
|
|
1163
1282
|
*/
|
|
1164
|
-
export declare function onCompaction(state: ActivationState): ActivationState;
|
|
1283
|
+
export declare function onCompaction(state: ActivationState, at: number): ActivationState;
|
|
1165
1284
|
/**
|
|
1166
1285
|
* Every name this session currently offers: the baseline plus the session's own
|
|
1167
1286
|
* activations.
|
|
@@ -1288,10 +1407,10 @@ interface ActivationWiringOptions {
|
|
|
1288
1407
|
*/
|
|
1289
1408
|
readonly onActivated?: (names: readonly string[], step: number) => void;
|
|
1290
1409
|
/**
|
|
1291
|
-
* Told that a compaction ended the session's activations, so the
|
|
1292
|
-
* drop the step records that
|
|
1293
|
-
* place, which only means a later activation of
|
|
1294
|
-
* step of the offer the compaction removed.
|
|
1410
|
+
* Told that a compaction ended some of the session's activations, so the
|
|
1411
|
+
* caller can drop the step records that belonged to the ones it removed.
|
|
1412
|
+
* Absent leaves the records in place, which only means a later activation of
|
|
1413
|
+
* the same name may carry the step of the offer the compaction removed.
|
|
1295
1414
|
*/
|
|
1296
1415
|
readonly onCompaction?: () => void;
|
|
1297
1416
|
/** Context-driven state to start from; defaults to an empty state. */
|
|
@@ -2526,6 +2645,30 @@ export declare class ProjectMcpRuntime {
|
|
|
2526
2645
|
* @param state - the session whose bridge to sync.
|
|
2527
2646
|
*/
|
|
2528
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;
|
|
2529
2672
|
/** The project scope's visible schemas, as {@link projectToolNames} reads them. */
|
|
2530
2673
|
private bridgeSchemas;
|
|
2531
2674
|
/** Drop one session's bridge: its forwarders and its subscription. Idempotent. */
|
|
@@ -2657,14 +2800,25 @@ export declare class ProjectMcpRuntime {
|
|
|
2657
2800
|
*/
|
|
2658
2801
|
private guidanceText;
|
|
2659
2802
|
/**
|
|
2660
|
-
*
|
|
2661
|
-
*
|
|
2803
|
+
* Record a call against the session's activation state: it refreshes the
|
|
2804
|
+
* freshness of a session-activated tool, and it is the evidence a later
|
|
2805
|
+
* compaction keeps that activation by. It rides the same `tools/result`
|
|
2806
|
+
* subscription the counters use, so no second observer exists.
|
|
2662
2807
|
* @param agentId - calling agent, when the call was agent-scoped.
|
|
2663
2808
|
* @param toolName - public registry name of the call.
|
|
2664
2809
|
*/
|
|
2665
2810
|
noteToolUse(agentId: string | undefined, toolName: string): void;
|
|
2666
2811
|
/** Drop the session-activated tools that outlived `toolIdleMs` without a call. */
|
|
2667
2812
|
private pruneActivation;
|
|
2813
|
+
/**
|
|
2814
|
+
* Drop the step records whose activation the session no longer holds.
|
|
2815
|
+
*
|
|
2816
|
+
* Called wherever activations end — the idle sweep and a compaction — so a
|
|
2817
|
+
* record never outlives the offer it was made for, and a name the session
|
|
2818
|
+
* still offers keeps the step its offer happened on.
|
|
2819
|
+
* @param state - the session whose records are reconciled.
|
|
2820
|
+
*/
|
|
2821
|
+
private pruneStepRecords;
|
|
2668
2822
|
private unmount;
|
|
2669
2823
|
/**
|
|
2670
2824
|
* The line that closes a mount's life, the pair of the `mounting` line.
|