dsh-project-mcp 0.4.2 → 0.4.3
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 +15 -0
- package/lib/index.d.ts +59 -0
- package/lib/index.js +64 -12
- package/lib/index.js.map +1 -1
- package/package.json +2 -2
- package/src/guidance.ts +33 -7
- package/src/runtime.ts +100 -1
package/README.md
CHANGED
|
@@ -448,6 +448,21 @@ the flags level — a search activation, a compaction boundary, a context advanc
|
|
|
448
448
|
and a policy edit each queue one coalesced bridge pass (`ForwardBatch.note`), and
|
|
449
449
|
a pass re-registers only when the names *or* the deferred subset moved.
|
|
450
450
|
|
|
451
|
+
**The route decides which of the two is even possible.** `deferLoading` only
|
|
452
|
+
hides a schema from a route that accepts tool declarations after its first
|
|
453
|
+
request (`LlmResolvedModelInfo.toolUpdate`, which the adapter reports and which
|
|
454
|
+
only catalog models declare): on a hand-declared provider — a custom
|
|
455
|
+
`llm-pi-ai` route, say — the harness strips the marker and sends the complete
|
|
456
|
+
declaration list, so a "deferred" tool costs its schema and hides nothing. The
|
|
457
|
+
runtime asks the `llm` service once per session route and re-presents on that
|
|
458
|
+
answer: where the capability is absent, the session's forwarders carry **only
|
|
459
|
+
the offered names**, the rest are not registered at all, and `mcp_search_tools`
|
|
460
|
+
is what makes one callable from the next step. The guidance says so in the same
|
|
461
|
+
words — its names line promises an exact-name call only where the tool is still
|
|
462
|
+
registered — and the per-session panel keeps reporting both tiers either way.
|
|
463
|
+
The first request of a session is always the wide one: the route is learned on
|
|
464
|
+
the first step, and the pass that follows trims the layer.
|
|
465
|
+
|
|
451
466
|
On an older harness the same module still rewrites the assembly list, through the
|
|
452
467
|
agent's own `system-prompt/assemble` waterfall, registered *prepended* so it runs
|
|
453
468
|
outermost and sees the list after other presentation plugins (for example
|
package/lib/index.d.ts
CHANGED
|
@@ -1582,6 +1582,16 @@ interface AgentEventLike {
|
|
|
1582
1582
|
agent: AgentLike;
|
|
1583
1583
|
/** `agent/status` only: whether a turn is currently running. */
|
|
1584
1584
|
status?: 'idle' | 'running';
|
|
1585
|
+
/**
|
|
1586
|
+
* `agent/pre-step` only: the model selection this step captured. Read to ask
|
|
1587
|
+
* the llm service what the route can do — a hand-declared provider cannot take
|
|
1588
|
+
* tool declarations after the first request, and the presentation has to know
|
|
1589
|
+
* before it decides how to hide anything.
|
|
1590
|
+
*/
|
|
1591
|
+
modelSelection?: {
|
|
1592
|
+
readonly provider: string;
|
|
1593
|
+
readonly model: string;
|
|
1594
|
+
};
|
|
1585
1595
|
}
|
|
1586
1596
|
/** The subset of the hosting scope used here. */
|
|
1587
1597
|
interface AgentScopeLike {
|
|
@@ -2041,6 +2051,27 @@ interface AgentState {
|
|
|
2041
2051
|
* state outlives an idle release.
|
|
2042
2052
|
*/
|
|
2043
2053
|
auto: AutoOfferState | undefined;
|
|
2054
|
+
/**
|
|
2055
|
+
* Identity of the model route the last resolved {@link AgentState.toolUpdate}
|
|
2056
|
+
* belongs to, as `provider/model`. A selection change re-asks the llm service
|
|
2057
|
+
* and nothing else does, so a session keeps one answer per route.
|
|
2058
|
+
*/
|
|
2059
|
+
routeKey: string | undefined;
|
|
2060
|
+
/**
|
|
2061
|
+
* Whether this session's route accepts tool declarations after its first
|
|
2062
|
+
* request (`LlmResolvedModelInfo.toolUpdate`), read from the llm service on
|
|
2063
|
+
* `agent/pre-step`.
|
|
2064
|
+
*
|
|
2065
|
+
* `undefined` until a route is resolved. `true` lets the presentation hide a
|
|
2066
|
+
* tool behind `deferLoading` — declared, invisible, still callable. `false`
|
|
2067
|
+
* means the harness sends the whole declaration list in the first request of
|
|
2068
|
+
* every series, so a deferred tool is not hidden at all: it costs its schema
|
|
2069
|
+
* and the presentation must not declare it, which is what makes its name
|
|
2070
|
+
* reachable only through the discovery tool. The difference is the difference
|
|
2071
|
+
* between "hidden but callable" and "not there", and only the route decides
|
|
2072
|
+
* which one is even possible.
|
|
2073
|
+
*/
|
|
2074
|
+
toolUpdate: boolean | undefined;
|
|
2044
2075
|
}
|
|
2045
2076
|
/**
|
|
2046
2077
|
* Owns every project-scoped mount, the config watchers, and the rescan timer.
|
|
@@ -2285,6 +2316,23 @@ export declare class ProjectMcpRuntime {
|
|
|
2285
2316
|
* @returns the offered public names.
|
|
2286
2317
|
*/
|
|
2287
2318
|
private offeredNamesOf;
|
|
2319
|
+
/**
|
|
2320
|
+
* Ask the llm service what the session's current route can do with tool
|
|
2321
|
+
* declarations, and re-present the session when the answer moves.
|
|
2322
|
+
*
|
|
2323
|
+
* One answer per route, keyed by `provider/model`: the service resolves it from
|
|
2324
|
+
* the adapter, which is not something to ask on every step. `toolUpdate` is the
|
|
2325
|
+
* one capability read here — `undefined` on a route means the harness sends the
|
|
2326
|
+
* complete current declaration list in every request and strips the deferral
|
|
2327
|
+
* marker, so the presentation cannot hide a tool that way at all.
|
|
2328
|
+
*
|
|
2329
|
+
* A service that is absent (a host without `ctx.llm`, a test composition) or an
|
|
2330
|
+
* answer that never arrives leaves the capability `undefined`, and the
|
|
2331
|
+
* presentation keeps the deferral path it shipped with rather than guessing.
|
|
2332
|
+
* @param state - the session whose route is being read.
|
|
2333
|
+
* @param selection - the step's captured selection; absent resolves nothing.
|
|
2334
|
+
*/
|
|
2335
|
+
private resolveRoute;
|
|
2288
2336
|
/**
|
|
2289
2337
|
* The names one session presents as deferred: what it mounts that it does not
|
|
2290
2338
|
* offer.
|
|
@@ -3350,6 +3398,17 @@ interface GuidanceInput {
|
|
|
3350
3398
|
readonly mostUsed?: readonly string[];
|
|
3351
3399
|
/** Whether the on-demand search surface is on; defaults to the activation default. */
|
|
3352
3400
|
readonly activationEnabled?: boolean;
|
|
3401
|
+
/**
|
|
3402
|
+
* Whether a deferred tool can still be called by its exact full name.
|
|
3403
|
+
*
|
|
3404
|
+
* It can on a route that accepts tool declarations after the first request:
|
|
3405
|
+
* the schema is hidden from the model and the registry keeps the tool
|
|
3406
|
+
* admitted, so `mcp__server__tool` executes. On a route without that
|
|
3407
|
+
* capability the tool is simply not declared, and a call by name answers
|
|
3408
|
+
* "unknown tool" — the names line must then send the model through the search
|
|
3409
|
+
* instead of promising the call. Defaults to `true`, the shipped capability.
|
|
3410
|
+
*/
|
|
3411
|
+
readonly directCalls?: boolean;
|
|
3353
3412
|
}
|
|
3354
3413
|
/**
|
|
3355
3414
|
* Build the project-MCP guidance section.
|
package/lib/index.js
CHANGED
|
@@ -1861,7 +1861,7 @@ function buildGuidance(input) {
|
|
|
1861
1861
|
if (activationEnabled && hot !== "") tail.push("", hot);
|
|
1862
1862
|
if (deferred.size > 0) {
|
|
1863
1863
|
tail.push("", onDemandParagraph(offered.size, deferred.size));
|
|
1864
|
-
tail.push("", hiddenNamesLine(deferred));
|
|
1864
|
+
tail.push("", hiddenNamesLine(deferred, input.directCalls ?? true));
|
|
1865
1865
|
}
|
|
1866
1866
|
const bullets = [];
|
|
1867
1867
|
let hidden = 0;
|
|
@@ -1980,17 +1980,27 @@ function serverBullet(server) {
|
|
|
1980
1980
|
* deduped, truncated to {@link MAX_GUIDANCE_HIDDEN_NAMES} with a `+N more`.
|
|
1981
1981
|
* Descriptions and schemas are the expensive part, so the line carries names
|
|
1982
1982
|
* only — the model picks the one it needs and runs a single targeted search
|
|
1983
|
-
* instead of rephrasing blind guesses.
|
|
1984
|
-
*
|
|
1985
|
-
*
|
|
1986
|
-
*
|
|
1987
|
-
*
|
|
1988
|
-
|
|
1989
|
-
|
|
1983
|
+
* instead of rephrasing blind guesses.
|
|
1984
|
+
*
|
|
1985
|
+
* The tail sentence is the one place the route changes the advice. Where the
|
|
1986
|
+
* harness can declare a tool after the first request, deferral only trims the
|
|
1987
|
+
* request list — the tool stays registered, so a call by its exact full name
|
|
1988
|
+
* still executes and the search is how the model reads the description, not a
|
|
1989
|
+
* gate. Where it cannot, the tool is not declared at all: the name no longer
|
|
1990
|
+
* exists for the turn, and the model has to search first, so promising the
|
|
1991
|
+
* direct call there would send it into an "unknown tool" error.
|
|
1992
|
+
* @param deferred - names reachable only through the discovery tool right now.
|
|
1993
|
+
* @param directCalls - whether an exact-name call still executes (§
|
|
1994
|
+
* `GuidanceInput.directCalls`).
|
|
1995
|
+
* @returns one line, or an empty string when nothing is deferred.
|
|
1996
|
+
*/
|
|
1997
|
+
function hiddenNamesLine(deferred, directCalls) {
|
|
1990
1998
|
const names = [...deferred].sort(compareNames);
|
|
1991
1999
|
const shown = names.slice(0, 12);
|
|
1992
2000
|
const hidden = names.length - shown.length;
|
|
1993
|
-
|
|
2001
|
+
const list = hidden === 0 ? shown.join(", ") : `${shown.join(", ")} +${hidden} more`;
|
|
2002
|
+
if (!directCalls) return `On demand right now: ${list} — none of them is in this request, so ask for one with \`${SEARCH_TOOL_NAME}\` (a keyword or the name) and it becomes callable from the next step on.`;
|
|
2003
|
+
return `On demand right now: ${list} — every one of them runs when called by its exact full name \`mcp__<server>__<tool>\`; search a name with \`${SEARCH_TOOL_NAME}\` first to see its description and parameters.`;
|
|
1994
2004
|
}
|
|
1995
2005
|
/** The paragraph that turns "a tool is missing" into "ask for it". */
|
|
1996
2006
|
function onDemandParagraph(offered, deferred) {
|
|
@@ -4370,6 +4380,38 @@ var ProjectMcpRuntime = class {
|
|
|
4370
4380
|
return names;
|
|
4371
4381
|
}
|
|
4372
4382
|
/**
|
|
4383
|
+
* Ask the llm service what the session's current route can do with tool
|
|
4384
|
+
* declarations, and re-present the session when the answer moves.
|
|
4385
|
+
*
|
|
4386
|
+
* One answer per route, keyed by `provider/model`: the service resolves it from
|
|
4387
|
+
* the adapter, which is not something to ask on every step. `toolUpdate` is the
|
|
4388
|
+
* one capability read here — `undefined` on a route means the harness sends the
|
|
4389
|
+
* complete current declaration list in every request and strips the deferral
|
|
4390
|
+
* marker, so the presentation cannot hide a tool that way at all.
|
|
4391
|
+
*
|
|
4392
|
+
* A service that is absent (a host without `ctx.llm`, a test composition) or an
|
|
4393
|
+
* answer that never arrives leaves the capability `undefined`, and the
|
|
4394
|
+
* presentation keeps the deferral path it shipped with rather than guessing.
|
|
4395
|
+
* @param state - the session whose route is being read.
|
|
4396
|
+
* @param selection - the step's captured selection; absent resolves nothing.
|
|
4397
|
+
*/
|
|
4398
|
+
async resolveRoute(state, selection) {
|
|
4399
|
+
if (selection === void 0 || this.disposed) return;
|
|
4400
|
+
const key = `${selection.provider}/${selection.model}`;
|
|
4401
|
+
if (state.routeKey === key) return;
|
|
4402
|
+
state.routeKey = key;
|
|
4403
|
+
const llm = this.ctx.get("llm");
|
|
4404
|
+
if (typeof llm?.resolveModelInfo !== "function") return;
|
|
4405
|
+
try {
|
|
4406
|
+
const supported = (await llm.resolveModelInfo(selection.provider, selection.model))?.toolUpdate !== void 0;
|
|
4407
|
+
if (supported === state.toolUpdate) return;
|
|
4408
|
+
state.toolUpdate = supported;
|
|
4409
|
+
state.bridge?.batch.note();
|
|
4410
|
+
} catch (error) {
|
|
4411
|
+
this.ctx.logger.debug?.(`project-mcp: reading the model route of session ${state.agent.id} failed: ${errorText(error)}`);
|
|
4412
|
+
}
|
|
4413
|
+
}
|
|
4414
|
+
/**
|
|
4373
4415
|
* The names one session presents as deferred: what it mounts that it does not
|
|
4374
4416
|
* offer.
|
|
4375
4417
|
*
|
|
@@ -4384,6 +4426,7 @@ var ProjectMcpRuntime = class {
|
|
|
4384
4426
|
*/
|
|
4385
4427
|
deferredNamesOf(state) {
|
|
4386
4428
|
if (!(this.config.activationEnabled ?? true)) return [];
|
|
4429
|
+
if (state.toolUpdate === false) return [];
|
|
4387
4430
|
const policy = this.policyFor(state.projectRoot);
|
|
4388
4431
|
if (policy.mode === "direct") return [];
|
|
4389
4432
|
const home = this.homeOf(state);
|
|
@@ -4709,7 +4752,9 @@ var ProjectMcpRuntime = class {
|
|
|
4709
4752
|
steps: /* @__PURE__ */ new Map(),
|
|
4710
4753
|
activationDispose: void 0,
|
|
4711
4754
|
guidanceDispose: void 0,
|
|
4712
|
-
auto: void 0
|
|
4755
|
+
auto: void 0,
|
|
4756
|
+
routeKey: void 0,
|
|
4757
|
+
toolUpdate: void 0
|
|
4713
4758
|
};
|
|
4714
4759
|
}
|
|
4715
4760
|
dropAgent(id) {
|
|
@@ -5047,6 +5092,7 @@ var ProjectMcpRuntime = class {
|
|
|
5047
5092
|
state.step += 1;
|
|
5048
5093
|
if (!this.disposed) {
|
|
5049
5094
|
this.touch(state, { activate: true });
|
|
5095
|
+
this.resolveRoute(state, event.modelSelection);
|
|
5050
5096
|
await this.awaitActivation(state);
|
|
5051
5097
|
}
|
|
5052
5098
|
}
|
|
@@ -5595,7 +5641,12 @@ var ProjectMcpRuntime = class {
|
|
|
5595
5641
|
const project = state.project;
|
|
5596
5642
|
if (project === void 0) return void 0;
|
|
5597
5643
|
try {
|
|
5598
|
-
|
|
5644
|
+
const names = projectToolNames(project.key, (scope) => this.bridgeSchemas(scope), servers());
|
|
5645
|
+
if (state.toolUpdate === false) {
|
|
5646
|
+
const offered = this.offeredNamesOf(state);
|
|
5647
|
+
return names.filter((name) => offered.has(name));
|
|
5648
|
+
}
|
|
5649
|
+
return names;
|
|
5599
5650
|
} catch (error) {
|
|
5600
5651
|
this.ctx.logger.warn(`project-mcp: reading the tools to forward to session ${state.agent.id} failed: ${errorText(error)}`);
|
|
5601
5652
|
return;
|
|
@@ -5986,7 +6037,8 @@ var ProjectMcpRuntime = class {
|
|
|
5986
6037
|
offered,
|
|
5987
6038
|
deferred,
|
|
5988
6039
|
mostUsed,
|
|
5989
|
-
activationEnabled
|
|
6040
|
+
activationEnabled,
|
|
6041
|
+
directCalls: state.toolUpdate !== false
|
|
5990
6042
|
});
|
|
5991
6043
|
} catch (error) {
|
|
5992
6044
|
this.ctx.logger.warn(`project-mcp: building guidance for session ${agent.id} failed: ${errorText(error)}`);
|