dsh-project-mcp 0.4.1 → 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
@@ -115,6 +115,20 @@ interface ForwardableDefinition extends BridgeToolSchema {
115
115
  };
116
116
  /** Cooperative timeout budget, preserved for the timeout policy wrapper. */
117
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;
118
132
  /**
119
133
  * Pure sibling-overlap classifier. Preserved: a forwarder that dropped it
120
134
  * would make every forwarded call exclusive while the project tool is
@@ -210,13 +224,26 @@ interface ForwardBatchOptions {
210
224
  * @returns the names this session should forward, or `undefined` on failure.
211
225
  */
212
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[];
213
239
  /**
214
240
  * Register one batch of forwarders over the session's layer, which this call
215
241
  * reaches empty-handed: the batch it replaces is released first.
216
242
  * @param names - the names to forward, in registry order.
243
+ * @param deferred - the names of this batch that carry `deferLoading`.
217
244
  * @returns the exact releaser that drops the whole batch.
218
245
  */
219
- readonly register: (names: readonly string[]) => () => void;
246
+ readonly register: (names: readonly string[], deferred: ReadonlySet<string>) => () => void;
220
247
  /**
221
248
  * Report a failure thrown by a pass this batch ran on its own.
222
249
  *
@@ -1413,6 +1440,18 @@ interface ActivationWiringOptions {
1413
1440
  * the same name may carry the step of the offer the compaction removed.
1414
1441
  */
1415
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;
1416
1455
  /** Context-driven state to start from; defaults to an empty state. */
1417
1456
  readonly autoState?: AutoOfferState;
1418
1457
  /** Sink for the context-driven state after every advance that changed it. */
@@ -2224,6 +2263,42 @@ export declare class ProjectMcpRuntime {
2224
2263
  * @returns the stored policy, or {@link DEFAULT_TOOL_POLICY} when there is none.
2225
2264
  */
2226
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;
2227
2302
  /**
2228
2303
  * Whether one project root has a live session on this host.
2229
2304
  * @param projectRoot - project root a policy request names.
package/lib/index.js CHANGED
@@ -882,6 +882,7 @@ function installActivation(options) {
882
882
  if (next === tracker.state) return;
883
883
  tracker.state = next;
884
884
  options.setAutoState?.(next);
885
+ options.onOfferedChanged?.();
885
886
  };
886
887
  /** Every name the session's explicit activation and context-driven tiers offer. */
887
888
  const offeredNames = () => {
@@ -931,6 +932,7 @@ function installActivation(options) {
931
932
  * continuation's value comes back by identity.
932
933
  */
933
934
  const contain = (result) => {
935
+ if (!Array.isArray(result.tools)) return result;
934
936
  const foreign = options.foreign?.() ?? NO_FOREIGN;
935
937
  if (foreign.size === 0) return result;
936
938
  const kept = result.tools.filter((tool) => !foreign.has(tool.name));
@@ -954,9 +956,13 @@ function installActivation(options) {
954
956
  return foreign.size === 0 ? surface : surface.filter((schema) => !foreign.has(schema.name));
955
957
  };
956
958
  const merge = (result) => {
959
+ const policy = options.policy?.() ?? DEFAULT_TOOL_POLICY;
960
+ if (!Array.isArray(result.tools)) {
961
+ if (policy.mode === "disclosure") advance();
962
+ return result;
963
+ }
957
964
  const surface = wholeSurface();
958
965
  if (surface.length === 0) return contain(result);
959
- const policy = options.policy?.() ?? DEFAULT_TOOL_POLICY;
960
966
  if (policy.mode === "off") {
961
967
  const mounted = options.available();
962
968
  if (mounted.length === 0) return contain(result);
@@ -998,6 +1004,7 @@ function installActivation(options) {
998
1004
  tracker.state = resetAutoOffer(tracker.state);
999
1005
  tracker.calls = [];
1000
1006
  tracker.changed = false;
1007
+ options.onOfferedChanged?.();
1001
1008
  return;
1002
1009
  }
1003
1010
  if (event?.type === "user/message") {
@@ -1025,6 +1032,7 @@ function installActivation(options) {
1025
1032
  activate: (names) => {
1026
1033
  recordActivated(names);
1027
1034
  options.setState(activate(options.state(), names, Date.now()));
1035
+ options.onOfferedChanged?.();
1028
1036
  },
1029
1037
  ...options.searchLimit === void 0 ? {} : { defaultLimit: options.searchLimit }
1030
1038
  });
@@ -2494,11 +2502,14 @@ const FORWARDED_TO = Symbol("dsh-project-mcp.forwarded-to");
2494
2502
  * dispatch would apply pre-execute listeners and guards twice.
2495
2503
  * @param project - the definition to forward, read for its surface.
2496
2504
  * @param lookup - resolves the current project definition of this name.
2505
+ * @param deferred - whether this forwarder asks for deferred loading, so the
2506
+ * model's tool list leaves it out while the registry keeps it callable.
2497
2507
  * @returns the definition to register in a session's layer.
2498
2508
  */
2499
- function forwarder(project, lookup) {
2509
+ function forwarder(project, lookup, deferred) {
2500
2510
  return Object.assign({
2501
2511
  ...project,
2512
+ ...deferred ? { deferLoading: true } : {},
2502
2513
  async execute(args, exec) {
2503
2514
  const live = lookup();
2504
2515
  if (live === void 0) throw new Error(`the project's "${project.name}" is no longer registered; the shared instance was released or replaced`);
@@ -2523,7 +2534,7 @@ function forwardProjectTools(options) {
2523
2534
  const project = options.registry.get(name, options.project);
2524
2535
  if (project === void 0) continue;
2525
2536
  try {
2526
- disposes.push(tools.register(forwarder(project, () => options.registry.get(name, options.project))));
2537
+ disposes.push(tools.register(forwarder(project, () => options.registry.get(name, options.project), options.deferred?.(name) === true)));
2527
2538
  } catch {
2528
2539
  continue;
2529
2540
  }
@@ -2580,6 +2591,8 @@ var ForwardBatch = class {
2580
2591
  options;
2581
2592
  /** The names the live batch was registered for; `undefined` before the first pass. */
2582
2593
  #namesIn = void 0;
2594
+ /** The names the live batch registered as deferred; `undefined` with no live batch. */
2595
+ #deferredIn = void 0;
2583
2596
  /** Disposer of the live registration batch; `undefined` while none is live. */
2584
2597
  #release = void 0;
2585
2598
  /** Whether an owning frame is inside {@link sync}, registering right now. */
@@ -2702,12 +2715,14 @@ var ForwardBatch = class {
2702
2715
  #syncOnce() {
2703
2716
  const names = this.options.names();
2704
2717
  if (names === void 0) return;
2705
- if (this.#namesIn !== void 0 && sameNames(this.#namesIn, names)) return;
2718
+ const deferred = new Set(this.options.deferred?.() ?? []);
2719
+ if (this.#namesIn !== void 0 && sameNames(this.#namesIn, names) && sameNameSet(this.#deferredIn, deferred)) return;
2706
2720
  try {
2707
2721
  this.#releaseBatch();
2708
2722
  } catch {}
2709
- this.#release = this.options.register(names);
2723
+ this.#release = this.options.register(names, deferred);
2710
2724
  this.#namesIn = names;
2725
+ this.#deferredIn = deferred;
2711
2726
  }
2712
2727
  /**
2713
2728
  * Release the live batch and forget it.
@@ -2719,6 +2734,7 @@ var ForwardBatch = class {
2719
2734
  const release = this.#release;
2720
2735
  this.#release = void 0;
2721
2736
  this.#namesIn = void 0;
2737
+ this.#deferredIn = void 0;
2722
2738
  release?.();
2723
2739
  }
2724
2740
  };
@@ -2760,6 +2776,22 @@ function sameNames(left, right) {
2760
2776
  return left.length === right.length && left.every((name, index) => name === right[index]);
2761
2777
  }
2762
2778
  /**
2779
+ * Whether two deferred-name sets are the same set.
2780
+ *
2781
+ * The batch short-circuits a pass whose forwarded names did not move, and it
2782
+ * must not do that when the *deferred* subset moved instead: the flag rides in
2783
+ * the registered definition, so a stale batch presents a stale answer. Order
2784
+ * carries no meaning here, hence a set comparison rather than {@link sameNames}.
2785
+ * @param left - the deferred set of the live batch; `undefined` with no live batch.
2786
+ * @param right - the deferred set this pass read.
2787
+ * @returns whether the two describe the same names.
2788
+ */
2789
+ function sameNameSet(left, right) {
2790
+ if (left === void 0 || left.size !== right.size) return false;
2791
+ for (const name of right) if (!left.has(name)) return false;
2792
+ return true;
2793
+ }
2794
+ /**
2763
2795
  * One ring per project root, oldest event first.
2764
2796
  *
2765
2797
  * Kept per root because two projects of one host are two histories; the history
@@ -4200,6 +4232,7 @@ var ProjectMcpRuntime = class {
4200
4232
  messageParams: { projectRoot: request.projectRoot }
4201
4233
  };
4202
4234
  policy.setPin(request.projectRoot, request.tool, request.pinned);
4235
+ this.refreshPresentation(request.projectRoot);
4203
4236
  this.notify();
4204
4237
  return {
4205
4238
  ok: true,
@@ -4238,6 +4271,7 @@ var ProjectMcpRuntime = class {
4238
4271
  messageParams: { projectRoot: request.projectRoot }
4239
4272
  };
4240
4273
  policy.setMode(request.projectRoot, request.mode);
4274
+ this.refreshPresentation(request.projectRoot);
4241
4275
  this.notify();
4242
4276
  return {
4243
4277
  ok: true,
@@ -4303,6 +4337,65 @@ var ProjectMcpRuntime = class {
4303
4337
  return this.options.policy?.forProject(projectRoot) ?? DEFAULT_TOOL_POLICY;
4304
4338
  }
4305
4339
  /**
4340
+ * Re-apply the presentation of every session working in one project.
4341
+ *
4342
+ * A pin or a mode is read live by the panel and by the guidance, but the
4343
+ * forwarders carry their `deferLoading` flag from the pass that registered
4344
+ * them, so the sessions of that project have to run one — off the caller's
4345
+ * stack, like every other change note.
4346
+ * @param projectRoot - the project whose policy just moved.
4347
+ */
4348
+ refreshPresentation(projectRoot) {
4349
+ for (const state of this.states.values()) {
4350
+ if (state.projectRoot !== projectRoot) continue;
4351
+ state.bridge?.batch.note();
4352
+ }
4353
+ }
4354
+ /**
4355
+ * The names one session's presentation offers the model right now.
4356
+ *
4357
+ * The counterpart of the assembly wiring's own `offeredNames`, read where the
4358
+ * presentation lives outside that assembly — in the bridge's forwarders. It is
4359
+ * the counter-seeded baseline, the session's activations, the context tier's
4360
+ * window, and the project's pins; the same four sources the assembly-side
4361
+ * `wanted` set is built from, so the two cannot drift.
4362
+ * @param state - the session to read.
4363
+ * @returns the offered public names.
4364
+ */
4365
+ offeredNamesOf(state) {
4366
+ const names = new Set(presentedNames(this.seedActivation(state)));
4367
+ const auto = state.auto;
4368
+ if (auto !== void 0) for (const name of autoPresentedNames(auto)) names.add(name);
4369
+ for (const pin of this.policyFor(state.projectRoot).pins) names.add(pin);
4370
+ return names;
4371
+ }
4372
+ /**
4373
+ * The names one session presents as deferred: what it mounts that it does not
4374
+ * offer.
4375
+ *
4376
+ * Empty when there is nothing to defer — activation off, `direct`, or a
4377
+ * surface that fits the budget — because deferring a schema the request would
4378
+ * have carried anyway only makes the declaration list harder to read, and the
4379
+ * prefix-cache argument for it is gone. The budget is the same
4380
+ * {@link surfaceChars} reading the panel and the assembly gate use, so the
4381
+ * deferred set and the "hidden" number a panel shows are one decision.
4382
+ * @param state - the session whose presentation is being registered.
4383
+ * @returns the names whose forwarders carry `deferLoading`, in registry order.
4384
+ */
4385
+ deferredNamesOf(state) {
4386
+ if (!(this.config.activationEnabled ?? true)) return [];
4387
+ const policy = this.policyFor(state.projectRoot);
4388
+ if (policy.mode === "direct") return [];
4389
+ const home = this.homeOf(state);
4390
+ const mounted = home === void 0 ? [] : this.schemasOf(home, state.agent.id);
4391
+ if (policy.mode === "disclosure") {
4392
+ const budget = this.config.activationToolBudgetChars ?? 4e4;
4393
+ if (!overToolBudget(surfaceChars(mounted), budget)) return [];
4394
+ }
4395
+ const offered = this.offeredNamesOf(state);
4396
+ return mounted.map((schema) => schema.name).filter((name) => !offered.has(name));
4397
+ }
4398
+ /**
4306
4399
  * Whether one project root has a live session on this host.
4307
4400
  * @param projectRoot - project root a policy request names.
4308
4401
  * @returns `true` when a bound session resolved to that root.
@@ -5508,13 +5601,15 @@ var ProjectMcpRuntime = class {
5508
5601
  return;
5509
5602
  }
5510
5603
  },
5511
- register: (names) => {
5604
+ deferred: () => this.deferredNamesOf(state),
5605
+ register: (names, deferred) => {
5512
5606
  const project = state.project;
5513
5607
  if (project === void 0) return () => void 0;
5514
5608
  return forwardProjectTools({
5515
5609
  ctx: context,
5516
5610
  project: project.key,
5517
5611
  names,
5612
+ deferred: (name) => deferred.has(name),
5518
5613
  registry
5519
5614
  });
5520
5615
  },
@@ -5700,6 +5795,7 @@ var ProjectMcpRuntime = class {
5700
5795
  visible: () => this.visibleSchemas(state),
5701
5796
  foreign: () => this.foreignNamesOf(state),
5702
5797
  policy: () => this.policyFor(state.projectRoot),
5798
+ onOfferedChanged: () => state.bridge?.batch.note(),
5703
5799
  step: () => state.step,
5704
5800
  onActivated: (names, step) => {
5705
5801
  for (const name of names) state.steps.set(name, step);