@dsh-plugin/dsh-dynamic-tools 0.0.1 → 0.1.0-dev.43582542989
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/LICENSE +165 -165
- package/README.md +151 -111
- package/docs/DETAIL.md +1 -1
- package/docs/preview.svg +25 -25
- package/icon.svg +7 -7
- package/lib/catalog.d.ts +11 -0
- package/lib/catalog.js +21 -0
- package/lib/disclose.d.ts +9 -6
- package/lib/disclose.js +51 -16
- package/lib/disclosure.d.ts +34 -0
- package/lib/disclosure.js +50 -3
- package/lib/executor.d.ts +53 -3
- package/lib/executor.js +87 -13
- package/lib/fold.d.ts +2 -2
- package/lib/fold.js +32 -21
- package/lib/index.d.ts +6 -0
- package/lib/index.js +26 -2
- package/lib/install.js +1 -0
- package/lib/render.d.ts +10 -2
- package/lib/render.js +20 -7
- package/lib/strategy.d.ts +52 -0
- package/lib/strategy.js +63 -0
- package/lib/tool-load.d.ts +16 -5
- package/lib/tool-load.js +29 -14
- package/locale/en.json +7 -7
- package/locale/zh.json +7 -7
- package/package.json +75 -75
- package/src/catalog.ts +112 -88
- package/src/disclose.ts +199 -151
- package/src/disclosure.ts +212 -147
- package/src/executor.ts +234 -145
- package/src/fold.ts +114 -104
- package/src/index.ts +209 -178
- package/src/install.ts +92 -91
- package/src/render.ts +129 -115
- package/src/source.ts +20 -20
- package/src/strategy.ts +79 -0
- package/src/tool-load.ts +126 -105
package/docs/preview.svg
CHANGED
|
@@ -1,25 +1,25 @@
|
|
|
1
|
-
<svg xmlns="http://www.w3.org/2000/svg" width="640" height="300" viewBox="0 0 640 300" role="img" aria-label="A frozen tool declaration head beside a conversation that receives a new tool definition as a trailing message">
|
|
2
|
-
<rect x="32" y="46" width="248" height="208" rx="14" fill="#176b5b" fill-opacity="0.08" stroke="#176b5b" stroke-width="3"/>
|
|
3
|
-
<rect x="64" y="78" width="184" height="18" rx="9" fill="#176b5b" fill-opacity="0.8"/>
|
|
4
|
-
<rect x="64" y="112" width="184" height="18" rx="9" fill="#176b5b" fill-opacity="0.55"/>
|
|
5
|
-
<rect x="64" y="146" width="184" height="18" rx="9" fill="#176b5b" fill-opacity="0.35"/>
|
|
6
|
-
<rect x="196" y="186" width="52" height="40" rx="8" fill="none" stroke="#176b5b" stroke-width="3"/>
|
|
7
|
-
<path d="M208 186v-10a14 14 0 0 1 28 0v10" fill="none" stroke="#176b5b" stroke-width="3"/>
|
|
8
|
-
<circle cx="222" cy="202" r="4" fill="#176b5b"/>
|
|
9
|
-
<path d="M222 206v8" fill="none" stroke="#176b5b" stroke-width="3" stroke-linecap="round"/>
|
|
10
|
-
|
|
11
|
-
<path d="M300 150h56" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round"/>
|
|
12
|
-
<path d="M348 142l12 8-12 8" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
|
|
13
|
-
|
|
14
|
-
<rect x="372" y="46" width="236" height="208" rx="14" fill="#db6b2c" fill-opacity="0.07" stroke="#db6b2c" stroke-width="3"/>
|
|
15
|
-
<rect x="396" y="72" width="188" height="66" rx="12" fill="none" stroke="#db6b2c" stroke-width="3"/>
|
|
16
|
-
<path d="M396 96h188" fill="none" stroke="#db6b2c" stroke-width="2" stroke-opacity="0.5"/>
|
|
17
|
-
<rect x="414" y="84" width="64" height="12" rx="6" fill="#db6b2c" fill-opacity="0.6"/>
|
|
18
|
-
<rect x="414" y="108" width="140" height="8" rx="4" fill="#db6b2c" fill-opacity="0.35"/>
|
|
19
|
-
<rect x="414" y="122" width="104" height="8" rx="4" fill="#db6b2c" fill-opacity="0.35"/>
|
|
20
|
-
|
|
21
|
-
<rect x="396" y="154" width="188" height="76" rx="12" fill="#db6b2c" fill-opacity="0.16" stroke="#db6b2c" stroke-width="3" stroke-dasharray="8 6"/>
|
|
22
|
-
<rect x="414" y="168" width="72" height="12" rx="6" fill="#db6b2c" fill-opacity="0.7"/>
|
|
23
|
-
<path d="M420 202h52M420 214h96" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round" stroke-opacity="0.6"/>
|
|
24
|
-
<path d="M534 196h24M546 184v24" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round"/>
|
|
25
|
-
</svg>
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="640" height="300" viewBox="0 0 640 300" role="img" aria-label="A frozen tool declaration head beside a conversation that receives a new tool definition as a trailing message">
|
|
2
|
+
<rect x="32" y="46" width="248" height="208" rx="14" fill="#176b5b" fill-opacity="0.08" stroke="#176b5b" stroke-width="3"/>
|
|
3
|
+
<rect x="64" y="78" width="184" height="18" rx="9" fill="#176b5b" fill-opacity="0.8"/>
|
|
4
|
+
<rect x="64" y="112" width="184" height="18" rx="9" fill="#176b5b" fill-opacity="0.55"/>
|
|
5
|
+
<rect x="64" y="146" width="184" height="18" rx="9" fill="#176b5b" fill-opacity="0.35"/>
|
|
6
|
+
<rect x="196" y="186" width="52" height="40" rx="8" fill="none" stroke="#176b5b" stroke-width="3"/>
|
|
7
|
+
<path d="M208 186v-10a14 14 0 0 1 28 0v10" fill="none" stroke="#176b5b" stroke-width="3"/>
|
|
8
|
+
<circle cx="222" cy="202" r="4" fill="#176b5b"/>
|
|
9
|
+
<path d="M222 206v8" fill="none" stroke="#176b5b" stroke-width="3" stroke-linecap="round"/>
|
|
10
|
+
|
|
11
|
+
<path d="M300 150h56" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round"/>
|
|
12
|
+
<path d="M348 142l12 8-12 8" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
|
|
13
|
+
|
|
14
|
+
<rect x="372" y="46" width="236" height="208" rx="14" fill="#db6b2c" fill-opacity="0.07" stroke="#db6b2c" stroke-width="3"/>
|
|
15
|
+
<rect x="396" y="72" width="188" height="66" rx="12" fill="none" stroke="#db6b2c" stroke-width="3"/>
|
|
16
|
+
<path d="M396 96h188" fill="none" stroke="#db6b2c" stroke-width="2" stroke-opacity="0.5"/>
|
|
17
|
+
<rect x="414" y="84" width="64" height="12" rx="6" fill="#db6b2c" fill-opacity="0.6"/>
|
|
18
|
+
<rect x="414" y="108" width="140" height="8" rx="4" fill="#db6b2c" fill-opacity="0.35"/>
|
|
19
|
+
<rect x="414" y="122" width="104" height="8" rx="4" fill="#db6b2c" fill-opacity="0.35"/>
|
|
20
|
+
|
|
21
|
+
<rect x="396" y="154" width="188" height="76" rx="12" fill="#db6b2c" fill-opacity="0.16" stroke="#db6b2c" stroke-width="3" stroke-dasharray="8 6"/>
|
|
22
|
+
<rect x="414" y="168" width="72" height="12" rx="6" fill="#db6b2c" fill-opacity="0.7"/>
|
|
23
|
+
<path d="M420 202h52M420 214h96" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round" stroke-opacity="0.6"/>
|
|
24
|
+
<path d="M534 196h24M546 184v24" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round"/>
|
|
25
|
+
</svg>
|
package/icon.svg
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36" role="img" aria-label="Dynamic tools">
|
|
2
|
-
<rect x="7.5" y="6" width="3.5" height="24" rx="1.75" fill="#176b5b"/>
|
|
3
|
-
<rect x="13" y="7" width="16" height="5" rx="2.5" fill="#176b5b" fill-opacity="0.85"/>
|
|
4
|
-
<rect x="13" y="14" width="16" height="5" rx="2.5" fill="#176b5b" fill-opacity="0.55"/>
|
|
5
|
-
<rect x="13" y="21" width="16" height="9" rx="2.5" fill="none" stroke="#db6b2c" stroke-width="2"/>
|
|
6
|
-
<path d="M18.5 25.5h5M21 23v5" fill="none" stroke="#db6b2c" stroke-width="2" stroke-linecap="round"/>
|
|
7
|
-
</svg>
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36" role="img" aria-label="Dynamic tools">
|
|
2
|
+
<rect x="7.5" y="6" width="3.5" height="24" rx="1.75" fill="#176b5b"/>
|
|
3
|
+
<rect x="13" y="7" width="16" height="5" rx="2.5" fill="#176b5b" fill-opacity="0.85"/>
|
|
4
|
+
<rect x="13" y="14" width="16" height="5" rx="2.5" fill="#176b5b" fill-opacity="0.55"/>
|
|
5
|
+
<rect x="13" y="21" width="16" height="9" rx="2.5" fill="none" stroke="#db6b2c" stroke-width="2"/>
|
|
6
|
+
<path d="M18.5 25.5h5M21 23v5" fill="none" stroke="#db6b2c" stroke-width="2" stroke-linecap="round"/>
|
|
7
|
+
</svg>
|
package/lib/catalog.d.ts
CHANGED
|
@@ -45,6 +45,17 @@ export declare function splitCatalog(definitions: readonly ToolSchemaLike[], rul
|
|
|
45
45
|
inline: ToolSchemaLike[];
|
|
46
46
|
dynamic: ToolSchemaLike[];
|
|
47
47
|
};
|
|
48
|
+
/**
|
|
49
|
+
* Append declared definitions to the frozen catalog, keeping both orders.
|
|
50
|
+
*
|
|
51
|
+
* A name the catalog already declares keeps its catalog position and
|
|
52
|
+
* definition: the head must not move because a tool became loadable.
|
|
53
|
+
*
|
|
54
|
+
* @param catalog - frozen declaration head.
|
|
55
|
+
* @param declared - definitions loaded on demand, in load order.
|
|
56
|
+
* @returns the head followed by every declared name it does not declare.
|
|
57
|
+
*/
|
|
58
|
+
export declare function extendCatalog(catalog: readonly ToolSchemaLike[], declared: readonly ToolSchemaLike[]): ToolSchemaLike[];
|
|
48
59
|
/**
|
|
49
60
|
* JSON size of one definition as it would be disclosed.
|
|
50
61
|
* @param schema - model-facing schema of the definition.
|
package/lib/catalog.js
CHANGED
|
@@ -55,6 +55,27 @@ export function splitCatalog(definitions, rules) {
|
|
|
55
55
|
}
|
|
56
56
|
return { inline, dynamic };
|
|
57
57
|
}
|
|
58
|
+
/**
|
|
59
|
+
* Append declared definitions to the frozen catalog, keeping both orders.
|
|
60
|
+
*
|
|
61
|
+
* A name the catalog already declares keeps its catalog position and
|
|
62
|
+
* definition: the head must not move because a tool became loadable.
|
|
63
|
+
*
|
|
64
|
+
* @param catalog - frozen declaration head.
|
|
65
|
+
* @param declared - definitions loaded on demand, in load order.
|
|
66
|
+
* @returns the head followed by every declared name it does not declare.
|
|
67
|
+
*/
|
|
68
|
+
export function extendCatalog(catalog, declared) {
|
|
69
|
+
const names = new Set(catalog.map(schema => schema.name));
|
|
70
|
+
const extended = [...catalog];
|
|
71
|
+
for (const schema of declared) {
|
|
72
|
+
if (names.has(schema.name))
|
|
73
|
+
continue;
|
|
74
|
+
names.add(schema.name);
|
|
75
|
+
extended.push(schema);
|
|
76
|
+
}
|
|
77
|
+
return extended;
|
|
78
|
+
}
|
|
58
79
|
const encoder = new TextEncoder();
|
|
59
80
|
/**
|
|
60
81
|
* JSON size of one definition as it would be disclosed.
|
package/lib/disclose.d.ts
CHANGED
|
@@ -6,6 +6,10 @@
|
|
|
6
6
|
* registry, not the step's admission: a tool the model may not call right now
|
|
7
7
|
* is still worth naming, because the call itself reports why it is unavailable.
|
|
8
8
|
*
|
|
9
|
+
* A route that reads only declared tool lists gets names instead of schemas:
|
|
10
|
+
* its definition can only take effect once `tool_load` added it to the head, so
|
|
11
|
+
* attaching it here would claim a callability the route does not have.
|
|
12
|
+
*
|
|
9
13
|
* @module dsh-dynamic-tools/disclose
|
|
10
14
|
*/
|
|
11
15
|
import type { Context } from '@deepseek-ai/cordis';
|
|
@@ -14,6 +18,7 @@ import type { UserMessage } from '@deepseek-ai/dsh-llm';
|
|
|
14
18
|
import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
|
|
15
19
|
import { type DisclosedState, type DisclosureLimits } from './disclosure.ts';
|
|
16
20
|
import type { SourceKind } from './source.ts';
|
|
21
|
+
import type { ToolStrategy } from './strategy.ts';
|
|
17
22
|
/** Everything the pre-step listener needs to plan one step's disclosure. */
|
|
18
23
|
export interface DiscloseOptions {
|
|
19
24
|
/** Message source kind owned by this plugin. */
|
|
@@ -22,6 +27,8 @@ export interface DiscloseOptions {
|
|
|
22
27
|
readonly limits: DisclosureLimits;
|
|
23
28
|
/** Whether names that disappear from the registry are announced. */
|
|
24
29
|
readonly announceRemovals: boolean;
|
|
30
|
+
/** Strategy this step's executor settled, per installed agent. */
|
|
31
|
+
readonly strategy: (agent: Agent) => ToolStrategy | undefined;
|
|
25
32
|
/** Names the frozen head declares, per installed agent. */
|
|
26
33
|
readonly catalogNames: (agent: Agent) => ReadonlySet<string>;
|
|
27
34
|
/** Definitions this step admits, recorded by the executor's last assembly. */
|
|
@@ -41,11 +48,6 @@ export declare function currentState(agent: Agent, kind: SourceKind): DisclosedS
|
|
|
41
48
|
* @param state - new state.
|
|
42
49
|
*/
|
|
43
50
|
export declare function storeState(agent: Agent, state: DisclosedState): void;
|
|
44
|
-
/**
|
|
45
|
-
* Drop process-local state so the next read folds the durable messages again.
|
|
46
|
-
* @param agent - agent whose session was compacted or replaced.
|
|
47
|
-
*/
|
|
48
|
-
export declare function invalidateState(agent: Agent): void;
|
|
49
51
|
/**
|
|
50
52
|
* Append this step's disclosure messages.
|
|
51
53
|
*
|
|
@@ -58,9 +60,10 @@ export declare function invalidateState(agent: Agent): void;
|
|
|
58
60
|
* @param admitted - definitions this step admits.
|
|
59
61
|
* @param executorCatalog - names the frozen head declares.
|
|
60
62
|
* @param options - disclosure settings.
|
|
63
|
+
* @param strategy - how this step's route receives dynamic tools.
|
|
61
64
|
* @returns the messages to append, in order.
|
|
62
65
|
*/
|
|
63
|
-
export declare function disclosureMessages(ctx: Context, agent: Agent, admitted: readonly ToolDefinition[], executorCatalog: ReadonlySet<string>, options: DiscloseOptions): readonly UserMessage[];
|
|
66
|
+
export declare function disclosureMessages(ctx: Context, agent: Agent, admitted: readonly ToolDefinition[], executorCatalog: ReadonlySet<string>, options: DiscloseOptions, strategy: ToolStrategy): readonly UserMessage[];
|
|
64
67
|
/**
|
|
65
68
|
* Register the pre-step listener that appends disclosures.
|
|
66
69
|
* @param ctx - plugin context owning the listener.
|
package/lib/disclose.js
CHANGED
|
@@ -6,15 +6,21 @@
|
|
|
6
6
|
* registry, not the step's admission: a tool the model may not call right now
|
|
7
7
|
* is still worth naming, because the call itself reports why it is unavailable.
|
|
8
8
|
*
|
|
9
|
+
* A route that reads only declared tool lists gets names instead of schemas:
|
|
10
|
+
* its definition can only take effect once `tool_load` added it to the head, so
|
|
11
|
+
* attaching it here would claim a callability the route does not have.
|
|
12
|
+
*
|
|
9
13
|
* @module dsh-dynamic-tools/disclose
|
|
10
14
|
*/
|
|
11
15
|
import { createUserMessage } from '@deepseek-ai/dsh-llm';
|
|
12
16
|
import { projectToolSchema } from '@deepseek-ai/dsh-tools';
|
|
13
|
-
import { applyDisclosure, planDisclosure } from "./disclosure.js";
|
|
17
|
+
import { applyDisclosure, oversizedNames, planDisclosure, } from "./disclosure.js";
|
|
14
18
|
import { foldDisclosed } from "./fold.js";
|
|
15
19
|
import { renderDisclosure } from "./render.js";
|
|
16
20
|
/** Per-Agent delivery state without retaining agents. */
|
|
17
21
|
const stateByAgent = new WeakMap();
|
|
22
|
+
/** Per-Agent diagnostics already reported, so each one appears once. */
|
|
23
|
+
const reportedByAgent = new WeakMap();
|
|
18
24
|
/**
|
|
19
25
|
* Read the session's delivered state, rebuilding it from durable messages when
|
|
20
26
|
* the process-local holder is missing (resume, fork, compaction).
|
|
@@ -23,11 +29,11 @@ const stateByAgent = new WeakMap();
|
|
|
23
29
|
* @returns the folded state.
|
|
24
30
|
*/
|
|
25
31
|
export function currentState(agent, kind) {
|
|
26
|
-
const
|
|
27
|
-
if (
|
|
28
|
-
return
|
|
32
|
+
const held = stateByAgent.get(agent);
|
|
33
|
+
if (held !== undefined)
|
|
34
|
+
return held;
|
|
29
35
|
const folded = foldDisclosed(agent.session.deriveMessages(), kind);
|
|
30
|
-
stateByAgent.set(agent,
|
|
36
|
+
stateByAgent.set(agent, folded);
|
|
31
37
|
return folded;
|
|
32
38
|
}
|
|
33
39
|
/**
|
|
@@ -36,14 +42,22 @@ export function currentState(agent, kind) {
|
|
|
36
42
|
* @param state - new state.
|
|
37
43
|
*/
|
|
38
44
|
export function storeState(agent, state) {
|
|
39
|
-
stateByAgent.set(agent,
|
|
45
|
+
stateByAgent.set(agent, state);
|
|
40
46
|
}
|
|
41
47
|
/**
|
|
42
|
-
*
|
|
43
|
-
*
|
|
48
|
+
* Report a per-agent diagnostic once, so a repeated condition does not repeat
|
|
49
|
+
* its log line on every step.
|
|
50
|
+
* @param agent - agent the condition belongs to.
|
|
51
|
+
* @param key - stable key for this condition.
|
|
52
|
+
* @param report - emitter, called only for a key not reported before.
|
|
44
53
|
*/
|
|
45
|
-
|
|
46
|
-
|
|
54
|
+
function reportOnce(agent, key, report) {
|
|
55
|
+
const reported = reportedByAgent.get(agent) ?? new Set();
|
|
56
|
+
if (reported.has(key))
|
|
57
|
+
return;
|
|
58
|
+
reported.add(key);
|
|
59
|
+
reportedByAgent.set(agent, reported);
|
|
60
|
+
report();
|
|
47
61
|
}
|
|
48
62
|
function schemasOutsideCatalog(definitions, catalogNames) {
|
|
49
63
|
return definitions
|
|
@@ -62,16 +76,30 @@ function schemasOutsideCatalog(definitions, catalogNames) {
|
|
|
62
76
|
* @param admitted - definitions this step admits.
|
|
63
77
|
* @param executorCatalog - names the frozen head declares.
|
|
64
78
|
* @param options - disclosure settings.
|
|
79
|
+
* @param strategy - how this step's route receives dynamic tools.
|
|
65
80
|
* @returns the messages to append, in order.
|
|
66
81
|
*/
|
|
67
|
-
export function disclosureMessages(ctx, agent, admitted, executorCatalog, options) {
|
|
82
|
+
export function disclosureMessages(ctx, agent, admitted, executorCatalog, options, strategy) {
|
|
68
83
|
const candidates = schemasOutsideCatalog(admitted, executorCatalog);
|
|
69
84
|
const current = currentState(agent, options.sourceKind);
|
|
85
|
+
for (const name of current.damaged) {
|
|
86
|
+
reportOnce(agent, `damaged:${name}`, () => {
|
|
87
|
+
ctx.logger.warn('dsh-dynamic-tools: recorded definition for "%s" could not be parsed; disclosing it again', name);
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
const limits = strategy === 'declare' ? { ...options.limits, mode: 'names' } : options.limits;
|
|
91
|
+
if (limits.mode === 'names') {
|
|
92
|
+
for (const name of oversizedNames(candidates, limits)) {
|
|
93
|
+
reportOnce(agent, `oversized:${name}`, () => {
|
|
94
|
+
ctx.logger.warn('dsh-dynamic-tools: "%s" exceeds maxSchemaBytes (%d) and cannot be loaded on this route; it is not announced', name, limits.maxSchemaBytes);
|
|
95
|
+
});
|
|
96
|
+
}
|
|
97
|
+
}
|
|
70
98
|
const available = new Set(candidates.map(schema => schema.name));
|
|
71
99
|
const removed = options.announceRemovals
|
|
72
100
|
? [...current.disclosed.keys()].filter(name => !available.has(name) && !executorCatalog.has(name))
|
|
73
101
|
: [];
|
|
74
|
-
const batches = planDisclosure(candidates, removed, current,
|
|
102
|
+
const batches = planDisclosure(candidates, removed, current, limits);
|
|
75
103
|
if (batches.length === 0) {
|
|
76
104
|
// A pruned history still needs its records re-linked for later comparisons.
|
|
77
105
|
const folded = foldDisclosed(agent.session.deriveMessages(), options.sourceKind);
|
|
@@ -80,7 +108,7 @@ export function disclosureMessages(ctx, agent, admitted, executorCatalog, option
|
|
|
80
108
|
return [];
|
|
81
109
|
}
|
|
82
110
|
const messages = batches.map(batch => createUserMessage({
|
|
83
|
-
content: [{ type: 'text', text: renderDisclosure(batch) }],
|
|
111
|
+
content: [{ type: 'text', text: renderDisclosure(batch, strategy) }],
|
|
84
112
|
source: { kind: options.sourceKind, form: 'catalog' },
|
|
85
113
|
}));
|
|
86
114
|
storeState(agent, applyDisclosure(current, batches));
|
|
@@ -93,16 +121,23 @@ export function disclosureMessages(ctx, agent, admitted, executorCatalog, option
|
|
|
93
121
|
* @param options - disclosure settings.
|
|
94
122
|
*/
|
|
95
123
|
export function registerDisclosure(ctx, options) {
|
|
96
|
-
ctx.on('agent/pre-step', async ({ agent, signal }, next) => {
|
|
124
|
+
ctx.on('agent/pre-step', async ({ agent, signal, modelSelection }, next) => {
|
|
97
125
|
const decision = await next();
|
|
98
126
|
if (decision.kind === 'reject' || signal.aborted)
|
|
99
127
|
return decision;
|
|
100
128
|
try {
|
|
101
|
-
// The executor recorded this step's admission when assembly
|
|
129
|
+
// The executor recorded this step's admission and strategy when assembly
|
|
130
|
+
// described the head, which happens before this listener runs.
|
|
102
131
|
const admitted = options.admitted(agent);
|
|
103
132
|
if (admitted === undefined)
|
|
104
133
|
return decision;
|
|
105
|
-
const
|
|
134
|
+
const strategy = options.strategy(agent) ?? 'tail';
|
|
135
|
+
if (strategy === 'declare') {
|
|
136
|
+
reportOnce(agent, 'declare', () => {
|
|
137
|
+
ctx.logger.info('dsh-dynamic-tools: announcing definitions by name only on %s/%s; a loaded tool is declared in the next request', modelSelection.provider, modelSelection.model);
|
|
138
|
+
});
|
|
139
|
+
}
|
|
140
|
+
const messages = disclosureMessages(ctx, agent, admitted, options.catalogNames(agent), options, strategy);
|
|
106
141
|
if (messages.length === 0)
|
|
107
142
|
return decision;
|
|
108
143
|
return { ...decision, messages: [...decision.messages, ...messages] };
|
package/lib/disclosure.d.ts
CHANGED
|
@@ -38,9 +38,36 @@ export interface DisclosedState {
|
|
|
38
38
|
readonly disclosed: ReadonlyMap<string, DisclosedEntry>;
|
|
39
39
|
/** Names whose full definition the model has read, attached or loaded on demand. */
|
|
40
40
|
readonly loaded: ReadonlySet<string>;
|
|
41
|
+
/**
|
|
42
|
+
* Definitions the model has read, in delivery order.
|
|
43
|
+
*
|
|
44
|
+
* The declare-on-load strategy turns these into tool-list declarations, so
|
|
45
|
+
* they outlive the announcement: a loaded tool stays declared even after the
|
|
46
|
+
* registry stops admitting it.
|
|
47
|
+
*/
|
|
48
|
+
readonly definitions: ReadonlyMap<string, ToolSchemaLike>;
|
|
49
|
+
/**
|
|
50
|
+
* Names whose recorded definition block could not be parsed, in delivery
|
|
51
|
+
* order. The caller reports them: the definition is disclosed again, and the
|
|
52
|
+
* damage must not stay silent.
|
|
53
|
+
*/
|
|
54
|
+
readonly damaged: readonly string[];
|
|
41
55
|
}
|
|
42
56
|
/** The empty state of a session that has disclosed nothing yet. */
|
|
43
57
|
export declare const EMPTY_DISCLOSED: DisclosedState;
|
|
58
|
+
/**
|
|
59
|
+
* Definitions that no route can deliver because they exceed the schema cap.
|
|
60
|
+
*
|
|
61
|
+
* A `tail` route can still announce such a tool by name — the model calls it
|
|
62
|
+
* without reading the schema, and `tool_load` reports the cap. A `names` route
|
|
63
|
+
* has no such fallback: the tool can only run after its definition was loaded,
|
|
64
|
+
* so announcing it would promise a load that must fail.
|
|
65
|
+
*
|
|
66
|
+
* @param schemas - dynamic definitions admitted for this step.
|
|
67
|
+
* @param limits - validated disclosure limits.
|
|
68
|
+
* @returns names whose definition exceeds `maxSchemaBytes`.
|
|
69
|
+
*/
|
|
70
|
+
export declare function oversizedNames(schemas: readonly ToolSchemaLike[], limits: DisclosureLimits): string[];
|
|
44
71
|
/**
|
|
45
72
|
* Plan the disclosures one step needs.
|
|
46
73
|
*
|
|
@@ -55,6 +82,13 @@ export declare const EMPTY_DISCLOSED: DisclosedState;
|
|
|
55
82
|
* @returns ordered batches, empty when the model already knows everything.
|
|
56
83
|
*/
|
|
57
84
|
export declare function planDisclosure(admitted: readonly ToolSchemaLike[], removed: readonly string[], state: DisclosedState, limits: DisclosureLimits): DisclosureBatch[];
|
|
85
|
+
/**
|
|
86
|
+
* Record one delivered definition, clearing any earlier damage for that name.
|
|
87
|
+
* @param state - state before this delivery.
|
|
88
|
+
* @param schema - definition the model has now read.
|
|
89
|
+
* @returns the updated state.
|
|
90
|
+
*/
|
|
91
|
+
export declare function withDefinition(state: DisclosedState, schema: ToolSchemaLike): DisclosedState;
|
|
58
92
|
/**
|
|
59
93
|
* Fold delivered batches into the delivered state.
|
|
60
94
|
* @param previous - state before these batches.
|
package/lib/disclosure.js
CHANGED
|
@@ -6,7 +6,27 @@
|
|
|
6
6
|
*/
|
|
7
7
|
import { schemaBytes, toolSignature } from "./catalog.js";
|
|
8
8
|
/** The empty state of a session that has disclosed nothing yet. */
|
|
9
|
-
export const EMPTY_DISCLOSED = {
|
|
9
|
+
export const EMPTY_DISCLOSED = {
|
|
10
|
+
disclosed: new Map(),
|
|
11
|
+
loaded: new Set(),
|
|
12
|
+
definitions: new Map(),
|
|
13
|
+
damaged: [],
|
|
14
|
+
};
|
|
15
|
+
/**
|
|
16
|
+
* Definitions that no route can deliver because they exceed the schema cap.
|
|
17
|
+
*
|
|
18
|
+
* A `tail` route can still announce such a tool by name — the model calls it
|
|
19
|
+
* without reading the schema, and `tool_load` reports the cap. A `names` route
|
|
20
|
+
* has no such fallback: the tool can only run after its definition was loaded,
|
|
21
|
+
* so announcing it would promise a load that must fail.
|
|
22
|
+
*
|
|
23
|
+
* @param schemas - dynamic definitions admitted for this step.
|
|
24
|
+
* @param limits - validated disclosure limits.
|
|
25
|
+
* @returns names whose definition exceeds `maxSchemaBytes`.
|
|
26
|
+
*/
|
|
27
|
+
export function oversizedNames(schemas, limits) {
|
|
28
|
+
return schemas.filter(schema => schemaBytes(schema) > limits.maxSchemaBytes).map(schema => schema.name);
|
|
29
|
+
}
|
|
10
30
|
/**
|
|
11
31
|
* Plan the disclosures one step needs.
|
|
12
32
|
*
|
|
@@ -31,7 +51,12 @@ export function planDisclosure(admitted, removed, state, limits) {
|
|
|
31
51
|
if (entry.signature === toolSignature(schema))
|
|
32
52
|
continue;
|
|
33
53
|
}
|
|
34
|
-
if (
|
|
54
|
+
if (schemaBytes(schema) > limits.maxSchemaBytes) {
|
|
55
|
+
if (limits.mode === 'schema')
|
|
56
|
+
namesOnly.push(schema.name);
|
|
57
|
+
continue;
|
|
58
|
+
}
|
|
59
|
+
if (limits.mode === 'schema')
|
|
35
60
|
attached.push(schema);
|
|
36
61
|
else
|
|
37
62
|
namesOnly.push(schema.name);
|
|
@@ -73,6 +98,22 @@ export function planDisclosure(admitted, removed, state, limits) {
|
|
|
73
98
|
flush();
|
|
74
99
|
return batches;
|
|
75
100
|
}
|
|
101
|
+
/**
|
|
102
|
+
* Record one delivered definition, clearing any earlier damage for that name.
|
|
103
|
+
* @param state - state before this delivery.
|
|
104
|
+
* @param schema - definition the model has now read.
|
|
105
|
+
* @returns the updated state.
|
|
106
|
+
*/
|
|
107
|
+
export function withDefinition(state, schema) {
|
|
108
|
+
const loaded = new Set(state.loaded).add(schema.name);
|
|
109
|
+
const definitions = new Map(state.definitions).set(schema.name, schema);
|
|
110
|
+
return {
|
|
111
|
+
disclosed: state.disclosed,
|
|
112
|
+
loaded,
|
|
113
|
+
definitions,
|
|
114
|
+
damaged: state.damaged.filter(name => name !== schema.name),
|
|
115
|
+
};
|
|
116
|
+
}
|
|
76
117
|
/**
|
|
77
118
|
* Fold delivered batches into the delivered state.
|
|
78
119
|
* @param previous - state before these batches.
|
|
@@ -82,10 +123,14 @@ export function planDisclosure(admitted, removed, state, limits) {
|
|
|
82
123
|
export function applyDisclosure(previous, batches) {
|
|
83
124
|
const disclosed = new Map(previous.disclosed);
|
|
84
125
|
const loaded = new Set(previous.loaded);
|
|
126
|
+
const definitions = new Map(previous.definitions);
|
|
127
|
+
const damaged = new Set(previous.damaged);
|
|
85
128
|
for (const batch of batches) {
|
|
86
129
|
for (const schema of batch.added) {
|
|
87
130
|
disclosed.set(schema.name, { signature: toolSignature(schema), schema: true });
|
|
88
131
|
loaded.add(schema.name);
|
|
132
|
+
definitions.set(schema.name, schema);
|
|
133
|
+
damaged.delete(schema.name);
|
|
89
134
|
}
|
|
90
135
|
for (const name of batch.names) {
|
|
91
136
|
disclosed.set(name, { signature: null, schema: false });
|
|
@@ -93,7 +138,9 @@ export function applyDisclosure(previous, batches) {
|
|
|
93
138
|
for (const name of batch.removed) {
|
|
94
139
|
disclosed.delete(name);
|
|
95
140
|
loaded.delete(name);
|
|
141
|
+
definitions.delete(name);
|
|
142
|
+
damaged.delete(name);
|
|
96
143
|
}
|
|
97
144
|
}
|
|
98
|
-
return { disclosed, loaded };
|
|
145
|
+
return { disclosed, loaded, definitions, damaged: [...damaged] };
|
|
99
146
|
}
|
package/lib/executor.d.ts
CHANGED
|
@@ -7,19 +7,28 @@
|
|
|
7
7
|
* through tail disclosure, but only while the step admits them: an unadmitted
|
|
8
8
|
* call is reported as an executable denial before policy and approval run.
|
|
9
9
|
*
|
|
10
|
+
* Routes that call only declared tools need the second half: a definition the
|
|
11
|
+
* model loaded through `tool_load` is appended to the declaration head, so the
|
|
12
|
+
* model can invoke it natively. The addition is monotone — a loaded tool keeps
|
|
13
|
+
* its declaration for the rest of the session — so the head changes once per
|
|
14
|
+
* loaded tool instead of once per admission change.
|
|
15
|
+
*
|
|
10
16
|
* @module dsh-dynamic-tools/executor
|
|
11
17
|
*/
|
|
12
18
|
import type { Context } from '@deepseek-ai/cordis';
|
|
13
19
|
import type { Agent } from '@deepseek-ai/dsh-agent';
|
|
14
20
|
import type { ToolBatchInput, ToolBatchResult, ToolDefinition, ToolExecutor, ToolModelInput } from '@deepseek-ai/dsh-tools';
|
|
15
|
-
import { type ClassificationRules } from './catalog.ts';
|
|
21
|
+
import { type ClassificationRules, type ToolSchemaLike } from './catalog.ts';
|
|
16
22
|
import type { DisclosedEntry } from './disclosure.ts';
|
|
23
|
+
import { type StrategyRules, type ToolStrategy } from './strategy.ts';
|
|
17
24
|
/** Delivered disclosure state shared with the pre-step listener. */
|
|
18
25
|
export interface DisclosureStateHandle {
|
|
19
26
|
/** Definitions the model has been told about. */
|
|
20
27
|
disclosed(): ReadonlyMap<string, DisclosedEntry>;
|
|
21
28
|
/** Names whose definition was delivered through `tool_load`. */
|
|
22
29
|
loaded(): ReadonlySet<string>;
|
|
30
|
+
/** Definitions the model has read, in delivery order. */
|
|
31
|
+
definitions(): ReadonlyMap<string, ToolSchemaLike>;
|
|
23
32
|
}
|
|
24
33
|
/** Runtime settings the executor reads on every step. */
|
|
25
34
|
export interface ExecutorOptions {
|
|
@@ -29,6 +38,10 @@ export interface ExecutorOptions {
|
|
|
29
38
|
readonly unavailableReasons: Readonly<Record<string, string>>;
|
|
30
39
|
/** Concurrency used when the loop supplies none. */
|
|
31
40
|
readonly maxParallelCalls: number;
|
|
41
|
+
/** Route matching rules for the declare-on-load strategy. */
|
|
42
|
+
readonly strategyRules: StrategyRules;
|
|
43
|
+
/** Name of the tool that delivers a definition on demand. */
|
|
44
|
+
readonly loadToolName: string;
|
|
32
45
|
}
|
|
33
46
|
/**
|
|
34
47
|
* Executes the frozen declaration head plus admitted dynamic tools.
|
|
@@ -47,13 +60,18 @@ export declare class StableCatalogExecutor implements ToolExecutor {
|
|
|
47
60
|
private lastAdmitted;
|
|
48
61
|
/** Names the current batch's step admits. */
|
|
49
62
|
private admittedNames;
|
|
63
|
+
/** Strategy settled by the current step's assembly, so every reader agrees. */
|
|
64
|
+
private stepStrategy;
|
|
65
|
+
/** Whether the missing-load-tool diagnostic was already reported. */
|
|
66
|
+
private loadWarningReported;
|
|
50
67
|
constructor(ctx: Context, agent: Agent, rules: ClassificationRules, options: ExecutorOptions, state: DisclosureStateHandle);
|
|
51
|
-
/** Names the frozen head declares
|
|
68
|
+
/** Names the frozen head declares, plus every loaded tool on a declare route. */
|
|
52
69
|
declaredNames(): ReadonlySet<string>;
|
|
53
70
|
/** Definitions the current step admits, captured by the last assembly. */
|
|
54
71
|
admittedDefinitions(): readonly ToolDefinition[];
|
|
55
72
|
/**
|
|
56
|
-
* Capture the head from the first assembly, then return it unchanged
|
|
73
|
+
* Capture the head from the first assembly, then return it unchanged, plus
|
|
74
|
+
* every loaded definition on a declare route.
|
|
57
75
|
* The first assembly's admission is exactly the declaration set the session
|
|
58
76
|
* starts with, so the head matches what every later request would have
|
|
59
77
|
* declared while the tool set is unchanged.
|
|
@@ -67,6 +85,36 @@ export declare class StableCatalogExecutor implements ToolExecutor {
|
|
|
67
85
|
* @returns settled results in model order.
|
|
68
86
|
*/
|
|
69
87
|
execute(input: ToolBatchInput): Promise<ToolBatchResult>;
|
|
88
|
+
/**
|
|
89
|
+
* How this step's route receives dynamic tools.
|
|
90
|
+
*
|
|
91
|
+
* The assembly that described this step's head fixes it once. Every later
|
|
92
|
+
* reader in the same step — declaration names, the load requirement, the
|
|
93
|
+
* disclosure listener — sees that one decision, so a model switch cannot make
|
|
94
|
+
* the head and the announcement disagree.
|
|
95
|
+
* @returns the recorded strategy, or the current route's before any assembly.
|
|
96
|
+
*/
|
|
97
|
+
planStrategy(): ToolStrategy;
|
|
98
|
+
/**
|
|
99
|
+
* Capture the declaration head from the first assembly.
|
|
100
|
+
* @param tools - definitions the first assembly admits.
|
|
101
|
+
* @returns the frozen model-facing catalog.
|
|
102
|
+
*/
|
|
103
|
+
private capture;
|
|
104
|
+
/**
|
|
105
|
+
* Append every loaded definition to the frozen head.
|
|
106
|
+
* A loaded tool the step still admits uses its live definition, so argument
|
|
107
|
+
* validation matches the call it will run; a tool that no longer admits keeps
|
|
108
|
+
* the definition the model read, because the head must not shrink.
|
|
109
|
+
* @param catalog - frozen declaration head.
|
|
110
|
+
* @returns the head followed by the loaded definitions, in load order.
|
|
111
|
+
*/
|
|
112
|
+
private withDeclared;
|
|
113
|
+
/**
|
|
114
|
+
* Report once that a declare route cannot load anything because the frozen
|
|
115
|
+
* head does not declare the load tool.
|
|
116
|
+
*/
|
|
117
|
+
private reportMissingLoadTool;
|
|
70
118
|
/**
|
|
71
119
|
* Resolve one call name: the step's admission first, then the registered
|
|
72
120
|
* definition for a name the head declares or the model was told about.
|
|
@@ -83,4 +131,6 @@ export declare class StableCatalogExecutor implements ToolExecutor {
|
|
|
83
131
|
* @returns the denial, or undefined to let dispatch proceed.
|
|
84
132
|
*/
|
|
85
133
|
private reject;
|
|
134
|
+
/** Whether a dynamic tool must be loaded before it may run on this route. */
|
|
135
|
+
private requiresLoad;
|
|
86
136
|
}
|