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/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
  }
@@ -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
- /** Tools seeded into the baseline from the durable counters. */
968
- export declare const DEFAULT_ACTIVATION_SEEDED = 8;
969
- /** Calls one tool needs in the counters before it is seeded. */
970
- export declare const DEFAULT_ACTIVATION_MIN_CALLS = 5;
971
- /** How long a session-activated tool survives without a call (`0` disables). */
972
- export declare const DEFAULT_TOOL_IDLE_MS = 1800000;
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 the epoch
1087
- * milliseconds of its last touch, and is what idle pruning and compaction clear.
1088
- * Both are read-only because every transition returns a new state.
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
- * Refresh the freshness of a tool the session actually called. A call is what
1138
- * keeps a session-activated tool offered; a name that is not active (a baseline
1139
- * tool, or a tool the model called by name without activating it) is untouched.
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 — a compaction rewrote the conversation they
1160
- * belonged to — while keeping the counter baseline.
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
- * @returns the updated state, or the input when no session tool was active.
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 caller can
1292
- * drop the step records that belong to them. Absent leaves the records in
1293
- * place, which only means a later activation of the same name may carry the
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
- * Refresh the freshness of a tool a session actually called. It rides the same
2661
- * `tools/result` subscription the counters use, so no second observer exists.
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.