@dsh-plugin/dsh-dynamic-tools 0.1.0-dev.43450988228 → 0.1.0-dev.43611140243
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 +44 -4
- package/icon.svg +6 -6
- 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/package.json +2 -2
- package/src/catalog.ts +24 -0
- package/src/disclose.ts +68 -20
- package/src/disclosure.ts +68 -3
- package/src/executor.ts +101 -12
- package/src/fold.ts +27 -17
- package/src/index.ts +34 -3
- package/src/install.ts +1 -0
- package/src/render.ts +21 -7
- package/src/strategy.ts +79 -0
- package/src/tool-load.ts +35 -14
package/src/fold.ts
CHANGED
|
@@ -37,34 +37,37 @@ function namesOf(body: string): string[] {
|
|
|
37
37
|
|
|
38
38
|
function matches(text: string, pattern: RegExp): string[] {
|
|
39
39
|
const bodies: string[] = []
|
|
40
|
-
pattern.lastIndex = 0
|
|
41
40
|
for (const match of text.matchAll(pattern)) bodies.push(match[1] ?? '')
|
|
42
41
|
return bodies.flatMap(namesOf)
|
|
43
42
|
}
|
|
44
43
|
|
|
45
44
|
/**
|
|
46
45
|
* Read one definition block, if it is a valid schema.
|
|
46
|
+
*
|
|
47
|
+
* A malformed block is not an error here: the fold reports it as damage, so the
|
|
48
|
+
* next step re-announces the tool instead of trusting a wrong record.
|
|
49
|
+
*
|
|
47
50
|
* @param json - the block body.
|
|
48
51
|
* @returns the parsed schema, or undefined when the text is not a schema object.
|
|
49
52
|
*/
|
|
50
53
|
function parseDefinition(json: string): ToolSchemaLike | undefined {
|
|
54
|
+
let value: unknown
|
|
51
55
|
try {
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
const candidate = value as Partial<ToolSchemaLike>
|
|
55
|
-
if (typeof candidate.name !== 'string' || typeof candidate.description !== 'string') return undefined
|
|
56
|
-
if (typeof candidate.parameters !== 'object' || candidate.parameters === null) return undefined
|
|
57
|
-
return candidate as ToolSchemaLike
|
|
58
|
-
} catch (error: unknown) {
|
|
59
|
-
void error
|
|
56
|
+
value = JSON.parse(json)
|
|
57
|
+
} catch {
|
|
60
58
|
return undefined
|
|
61
59
|
}
|
|
60
|
+
if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
|
|
61
|
+
const candidate = value as Partial<ToolSchemaLike>
|
|
62
|
+
if (typeof candidate.name !== 'string' || typeof candidate.description !== 'string') return undefined
|
|
63
|
+
if (typeof candidate.parameters !== 'object' || candidate.parameters === null) return undefined
|
|
64
|
+
return candidate as ToolSchemaLike
|
|
62
65
|
}
|
|
63
66
|
|
|
64
67
|
/**
|
|
65
68
|
* Fold every dynamic-tools message in delivery order.
|
|
66
|
-
*
|
|
67
|
-
* re-
|
|
69
|
+
* A damaged block still marks its name as announced, so the model keeps seeing
|
|
70
|
+
* the name; the definition is re-disclosed because it was never recorded.
|
|
68
71
|
*
|
|
69
72
|
* @param messages - derived session messages in model order.
|
|
70
73
|
* @param kind - message source kind owned by this plugin.
|
|
@@ -73,32 +76,39 @@ function parseDefinition(json: string): ToolSchemaLike | undefined {
|
|
|
73
76
|
export function foldDisclosed(messages: readonly FoldableMessage[], kind: string): DisclosedState {
|
|
74
77
|
const disclosed = new Map<string, DisclosedEntry>()
|
|
75
78
|
const loaded = new Set<string>()
|
|
79
|
+
const definitions = new Map<string, ToolSchemaLike>()
|
|
80
|
+
const damaged = new Set<string>()
|
|
76
81
|
for (const message of messages) {
|
|
77
82
|
if (message.source?.kind !== kind) continue
|
|
78
83
|
const text = textOf(message)
|
|
79
84
|
for (const name of matches(text, REMOVED)) {
|
|
80
85
|
disclosed.delete(name)
|
|
81
86
|
loaded.delete(name)
|
|
87
|
+
definitions.delete(name)
|
|
88
|
+
damaged.delete(name)
|
|
82
89
|
}
|
|
83
|
-
const
|
|
84
|
-
DEFINITION.lastIndex = 0
|
|
90
|
+
const parsed = new Map<string, ToolSchemaLike>()
|
|
85
91
|
for (const match of text.matchAll(DEFINITION)) {
|
|
86
92
|
const schema = parseDefinition(match[2] ?? '')
|
|
87
|
-
if (schema
|
|
93
|
+
if (schema === undefined) damaged.add(match[1] ?? '')
|
|
94
|
+
else parsed.set(schema.name, schema)
|
|
88
95
|
}
|
|
89
96
|
for (const name of matches(text, ADDED)) {
|
|
90
|
-
const schema =
|
|
97
|
+
const schema = parsed.get(name)
|
|
91
98
|
if (schema === undefined) {
|
|
92
99
|
disclosed.set(name, { signature: null, schema: false })
|
|
93
100
|
continue
|
|
94
101
|
}
|
|
95
102
|
disclosed.set(name, { signature: toolSignature(schema), schema: true })
|
|
96
103
|
loaded.add(name)
|
|
104
|
+
definitions.set(name, schema)
|
|
105
|
+
damaged.delete(name)
|
|
97
106
|
}
|
|
98
|
-
for (const schema of
|
|
107
|
+
for (const schema of parsed.values()) {
|
|
99
108
|
disclosed.set(schema.name, { signature: toolSignature(schema), schema: true })
|
|
100
109
|
loaded.add(schema.name)
|
|
110
|
+
definitions.set(schema.name, schema)
|
|
101
111
|
}
|
|
102
112
|
}
|
|
103
|
-
return { disclosed, loaded }
|
|
113
|
+
return { disclosed, loaded, definitions, damaged: [...damaged] }
|
|
104
114
|
}
|
package/src/index.ts
CHANGED
|
@@ -20,6 +20,7 @@ import { registerDisclosure, type DiscloseOptions } from './disclose.ts'
|
|
|
20
20
|
import type { StableCatalogExecutor } from './executor.ts'
|
|
21
21
|
import { installAgent, type InstallOptions } from './install.ts'
|
|
22
22
|
import { SOURCE_KIND } from './source.ts'
|
|
23
|
+
import { DEFAULT_DECLARE_MODELS, type StrategyRules, type ToolStrategy } from './strategy.ts'
|
|
23
24
|
import { createToolLoad, TOOL_LOAD_NAME } from './tool-load.ts'
|
|
24
25
|
|
|
25
26
|
/** Cordis plugin name. */
|
|
@@ -56,6 +57,12 @@ export interface Config {
|
|
|
56
57
|
/** Announce tools that stop being available. */
|
|
57
58
|
announceRemovals: boolean
|
|
58
59
|
}
|
|
60
|
+
declareOnLoad: {
|
|
61
|
+
/** Model-id patterns whose routes declare loaded tools instead of reading the tail. */
|
|
62
|
+
models: string[]
|
|
63
|
+
/** Provider-route patterns restricted to that handling; empty matches every provider. */
|
|
64
|
+
providers: string[]
|
|
65
|
+
}
|
|
59
66
|
/** Model-facing reason reported when a declared tool is not admitted. */
|
|
60
67
|
unavailableReasons: Record<string, string>
|
|
61
68
|
/** Concurrency used when the loop supplies no limit. */
|
|
@@ -90,6 +97,12 @@ export const Config: z<Config> = z.object({
|
|
|
90
97
|
announceRemovals: z.boolean().default(true)
|
|
91
98
|
.description('Announce tools that stop being available.'),
|
|
92
99
|
}).default({}),
|
|
100
|
+
declareOnLoad: z.object({
|
|
101
|
+
models: z.array(z.string()).default([...DEFAULT_DECLARE_MODELS])
|
|
102
|
+
.description('Model-id patterns whose routes call only declared tools; dynamic tools are loaded on demand there.'),
|
|
103
|
+
providers: z.array(z.string()).default([])
|
|
104
|
+
.description('Provider-route patterns restricted to that handling; empty matches every provider.'),
|
|
105
|
+
}).default({}),
|
|
93
106
|
unavailableReasons: z.dict(z.string()).default({
|
|
94
107
|
exit_plan_mode: 'Plan mode is not active in this session. Ask the user to switch to plan mode, then call it again.',
|
|
95
108
|
}).description('Model-facing reason reported when a declared tool is not admitted.'),
|
|
@@ -104,16 +117,27 @@ export const Config: z<Config> = z.object({
|
|
|
104
117
|
*/
|
|
105
118
|
function resolveSettings(config: Config): {
|
|
106
119
|
rules: ClassificationRules
|
|
120
|
+
strategyRules: StrategyRules
|
|
107
121
|
install: Omit<InstallOptions, 'executors' | 'reported'>
|
|
108
|
-
disclose: Omit<DiscloseOptions, 'catalogNames' | 'admitted'>
|
|
122
|
+
disclose: Omit<DiscloseOptions, 'strategy' | 'catalogNames' | 'admitted'>
|
|
109
123
|
} {
|
|
124
|
+
const strategyRules: StrategyRules = {
|
|
125
|
+
models: config.declareOnLoad.models,
|
|
126
|
+
providers: config.declareOnLoad.providers,
|
|
127
|
+
}
|
|
128
|
+
// A route that declares loaded tools needs the loader in its head, so a
|
|
129
|
+
// deployment cannot classify it onto the tail and lose the only path in.
|
|
130
|
+
const inlineNames = config.dynamic.inlineNames.includes(TOOL_LOAD_NAME)
|
|
131
|
+
? config.dynamic.inlineNames
|
|
132
|
+
: [...config.dynamic.inlineNames, TOOL_LOAD_NAME]
|
|
110
133
|
const rules: ClassificationRules = {
|
|
111
134
|
dynamicNames: config.dynamic.names,
|
|
112
135
|
dynamicPrefixes: config.dynamic.prefixes,
|
|
113
|
-
inlineNames
|
|
136
|
+
inlineNames,
|
|
114
137
|
}
|
|
115
138
|
return {
|
|
116
139
|
rules,
|
|
140
|
+
strategyRules,
|
|
117
141
|
install: {
|
|
118
142
|
sourceKind: SOURCE_KIND,
|
|
119
143
|
rules,
|
|
@@ -121,6 +145,8 @@ function resolveSettings(config: Config): {
|
|
|
121
145
|
requireLoad: config.disclosure.requireLoad,
|
|
122
146
|
unavailableReasons: config.unavailableReasons,
|
|
123
147
|
maxParallelCalls: config.maxParallelCalls,
|
|
148
|
+
strategyRules,
|
|
149
|
+
loadToolName: TOOL_LOAD_NAME,
|
|
124
150
|
},
|
|
125
151
|
skipPresets: config.skipPresets,
|
|
126
152
|
},
|
|
@@ -148,10 +174,14 @@ export function apply(ctx: Context, config: Config): void {
|
|
|
148
174
|
const release = new WeakMap<Agent, () => void>()
|
|
149
175
|
const reported = new WeakSet<Agent>()
|
|
150
176
|
const installOptions: InstallOptions = { ...settings.install, executors, reported }
|
|
177
|
+
const strategyOf = (agent: Agent): ToolStrategy | undefined => executors.get(agent)?.planStrategy()
|
|
178
|
+
const declaredNamesOf = (agent: Agent): ReadonlySet<string> => executors.get(agent)?.declaredNames() ?? new Set()
|
|
151
179
|
|
|
152
180
|
ctx.effect(() => ctx.tools.register(createToolLoad(ctx, {
|
|
153
181
|
sourceKind: SOURCE_KIND,
|
|
154
182
|
limits: settings.disclose.limits,
|
|
183
|
+
strategy: strategyOf,
|
|
184
|
+
declaredNames: declaredNamesOf,
|
|
155
185
|
})), `dsh-dynamic-tools: register ${TOOL_LOAD_NAME}`)
|
|
156
186
|
|
|
157
187
|
ctx.on('agent/created', ({ agent }) => {
|
|
@@ -172,7 +202,8 @@ export function apply(ctx: Context, config: Config): void {
|
|
|
172
202
|
|
|
173
203
|
registerDisclosure(ctx, {
|
|
174
204
|
...settings.disclose,
|
|
175
|
-
|
|
205
|
+
strategy: strategyOf,
|
|
206
|
+
catalogNames: declaredNamesOf,
|
|
176
207
|
admitted: agent => executors.get(agent)?.admittedDefinitions(),
|
|
177
208
|
})
|
|
178
209
|
}
|
package/src/install.ts
CHANGED
|
@@ -65,6 +65,7 @@ export function installAgent(
|
|
|
65
65
|
const holder = {
|
|
66
66
|
disclosed: () => currentState(agent, options.sourceKind).disclosed,
|
|
67
67
|
loaded: () => currentState(agent, options.sourceKind).loaded,
|
|
68
|
+
definitions: () => currentState(agent, options.sourceKind).definitions,
|
|
68
69
|
}
|
|
69
70
|
const executor = new StableCatalogExecutor(ctx, agent, options.rules, options.executor, holder)
|
|
70
71
|
try {
|
package/src/render.ts
CHANGED
|
@@ -7,9 +7,13 @@
|
|
|
7
7
|
|
|
8
8
|
import type { ToolSchemaLike } from './catalog.ts'
|
|
9
9
|
import type { DisclosureBatch } from './disclosure.ts'
|
|
10
|
+
import type { ToolStrategy } from './strategy.ts'
|
|
10
11
|
|
|
11
12
|
const CLOSING_TAG = /<\//g
|
|
12
13
|
|
|
14
|
+
/** What the model must do with a definition attached to the disclosure. */
|
|
15
|
+
const DIRECT_CALL_TRAILER = 'These tools are callable directly by name even though they are not in your tool list; match the definitions above.'
|
|
16
|
+
|
|
13
17
|
/**
|
|
14
18
|
* Keep tool prose from closing a wrapper or block early. JSON accepts the
|
|
15
19
|
* resulting backslash-slash escape, so a definition body stays parseable.
|
|
@@ -31,10 +35,16 @@ export function oneLine(text: string): string {
|
|
|
31
35
|
|
|
32
36
|
/**
|
|
33
37
|
* Render one disclosure batch.
|
|
38
|
+
*
|
|
39
|
+
* An attached definition is only ever planned in `schema` mode, which the
|
|
40
|
+
* declare-on-load strategy never uses, so it always carries the direct-call
|
|
41
|
+
* instruction.
|
|
42
|
+
*
|
|
34
43
|
* @param batch - definitions, name-only entries, and removals.
|
|
44
|
+
* @param strategy - how this route receives dynamic tools.
|
|
35
45
|
* @returns the complete user-message text.
|
|
36
46
|
*/
|
|
37
|
-
export function renderDisclosure(batch: DisclosureBatch): string {
|
|
47
|
+
export function renderDisclosure(batch: DisclosureBatch, strategy: ToolStrategy): string {
|
|
38
48
|
const sections: string[] = []
|
|
39
49
|
const announced: string[] = []
|
|
40
50
|
for (const schema of batch.added) announced.push(`- ${schema.name}: ${oneLine(escapeReminderText(schema.description))}`)
|
|
@@ -50,11 +60,11 @@ export function renderDisclosure(batch: DisclosureBatch): string {
|
|
|
50
60
|
sections.push(`<tools_removed>\n${batch.removed.map(name => `- ${name}`).join('\n')}\n</tools_removed>`)
|
|
51
61
|
}
|
|
52
62
|
const trailers: string[] = []
|
|
53
|
-
if (batch.added.length > 0)
|
|
54
|
-
trailers.push('These tools are callable directly by name even though they are not in your tool list; match the definitions above.')
|
|
55
|
-
}
|
|
63
|
+
if (batch.added.length > 0) trailers.push(DIRECT_CALL_TRAILER)
|
|
56
64
|
if (batch.names.length > 0) {
|
|
57
|
-
trailers.push(
|
|
65
|
+
trailers.push(strategy === 'declare'
|
|
66
|
+
? 'Call tool_load with the names under tools_load_required — also when you need to read what a tool does. A loaded tool is added to your tool list for later steps.'
|
|
67
|
+
: 'Call tool_load with the names under tools_load_required before calling those tools.')
|
|
58
68
|
}
|
|
59
69
|
if (batch.removed.length > 0) {
|
|
60
70
|
trailers.push('Removed tools are unavailable; they fail if called.')
|
|
@@ -66,10 +76,14 @@ export function renderDisclosure(batch: DisclosureBatch): string {
|
|
|
66
76
|
/**
|
|
67
77
|
* Render the definitions `tool_load` returns for one tool.
|
|
68
78
|
* @param schema - the definition to deliver.
|
|
79
|
+
* @param strategy - how this route receives dynamic tools.
|
|
69
80
|
* @returns the complete user-message text.
|
|
70
81
|
*/
|
|
71
|
-
export function renderLoadedDefinition(schema: ToolSchemaLike): string {
|
|
72
|
-
|
|
82
|
+
export function renderLoadedDefinition(schema: ToolSchemaLike, strategy: ToolStrategy): string {
|
|
83
|
+
const trailer = strategy === 'declare'
|
|
84
|
+
? 'This tool is declared in your tool list from the next step on; call it directly by name.'
|
|
85
|
+
: DIRECT_CALL_TRAILER
|
|
86
|
+
return `<system-reminder>\n<tool_definition name="${schema.name}">\n${escapeReminderText(JSON.stringify(schema))}\n</tool_definition>\n${trailer}\n</system-reminder>`
|
|
73
87
|
}
|
|
74
88
|
|
|
75
89
|
/**
|
package/src/strategy.ts
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How one route receives dynamic tools: at the conversation tail, or declared
|
|
3
|
+
* in the tool list after an explicit load.
|
|
4
|
+
*
|
|
5
|
+
* OpenAI Responses routes call only the functions present in the request's
|
|
6
|
+
* `tools` array, so a definition delivered as conversation text is never
|
|
7
|
+
* invoked. Those routes need the definition loaded through `tool_load` and
|
|
8
|
+
* declared on the following request. Every other route reads the tail
|
|
9
|
+
* disclosure and calls the tool directly, which needs no declaration change.
|
|
10
|
+
*
|
|
11
|
+
* Pure module: no Harness imports, so it runs under the Node type-stripping
|
|
12
|
+
* loader in tests.
|
|
13
|
+
*
|
|
14
|
+
* @module dsh-dynamic-tools/strategy
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
/** How one Agent's dynamic tools reach the model. */
|
|
18
|
+
export type ToolStrategy = 'tail' | 'declare'
|
|
19
|
+
|
|
20
|
+
/** Route matching rules for the declare-on-load strategy. */
|
|
21
|
+
export interface StrategyRules {
|
|
22
|
+
/** Model-id patterns; an empty list matches every model. */
|
|
23
|
+
readonly models: readonly string[]
|
|
24
|
+
/** Provider-route patterns; an empty list matches every provider. */
|
|
25
|
+
readonly providers: readonly string[]
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** Model families whose routes call only tools declared in the request. */
|
|
29
|
+
export const DEFAULT_DECLARE_MODELS: readonly string[] = Object.freeze([
|
|
30
|
+
'gpt*',
|
|
31
|
+
'o1*',
|
|
32
|
+
'o3*',
|
|
33
|
+
'o4*',
|
|
34
|
+
'chatgpt*',
|
|
35
|
+
'codex*',
|
|
36
|
+
])
|
|
37
|
+
|
|
38
|
+
/** Everything a pattern-match treats literally, apart from `*`. */
|
|
39
|
+
const REGEX_SPECIALS = /[.+?^${}()|[\]\\]/g
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Match one identifier against a `*` wildcard pattern, ignoring case.
|
|
43
|
+
*
|
|
44
|
+
* The `*` is the only metacharacter; every other character is literal, so a
|
|
45
|
+
* model id containing `.` or `-` matches only itself. The pattern is anchored,
|
|
46
|
+
* so `gpt*` does not match `x-gpt-6`.
|
|
47
|
+
*
|
|
48
|
+
* @param pattern - glob-like pattern from configuration.
|
|
49
|
+
* @param value - model id or provider route to test.
|
|
50
|
+
* @returns whether the whole value matches the whole pattern.
|
|
51
|
+
*/
|
|
52
|
+
export function patternMatches(pattern: string, value: string): boolean {
|
|
53
|
+
const source = pattern.replace(REGEX_SPECIALS, '\\$&').split('*').join('.*')
|
|
54
|
+
return new RegExp(`^${source}$`, 'i').test(value)
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function matchesAny(patterns: readonly string[], value: string): boolean {
|
|
58
|
+
return patterns.length === 0 || patterns.some(pattern => patternMatches(pattern, value))
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Decide how one step's route receives dynamic tools.
|
|
63
|
+
*
|
|
64
|
+
* A missing selection cannot be classified, so it keeps the tail strategy: the
|
|
65
|
+
* declaration head must never be guessed into a different shape.
|
|
66
|
+
*
|
|
67
|
+
* @param selection - route the step fixed for its request, when one is recorded.
|
|
68
|
+
* @param rules - configured declare-on-load matching rules.
|
|
69
|
+
* @returns `declare` only when both the model and the provider match.
|
|
70
|
+
*/
|
|
71
|
+
export function selectStrategy(
|
|
72
|
+
selection: { readonly provider: string, readonly model: string } | undefined,
|
|
73
|
+
rules: StrategyRules,
|
|
74
|
+
): ToolStrategy {
|
|
75
|
+
if (selection === undefined) return 'tail'
|
|
76
|
+
if (!matchesAny(rules.models, selection.model)) return 'tail'
|
|
77
|
+
if (!matchesAny(rules.providers, selection.provider)) return 'tail'
|
|
78
|
+
return 'declare'
|
|
79
|
+
}
|
package/src/tool-load.ts
CHANGED
|
@@ -1,22 +1,29 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* `tool_load`: deliver the definition of a tool the
|
|
3
|
-
*
|
|
2
|
+
* `tool_load`: deliver the definition of a tool the conversation announced but
|
|
3
|
+
* the declaration head does not contain.
|
|
4
4
|
*
|
|
5
5
|
* The definition rides `exec.deferContext()`, so the loop logs it after this
|
|
6
|
-
* tool's result and the next request carries it at the tail.
|
|
6
|
+
* tool's result and the next request carries it at the tail. On a route that
|
|
7
|
+
* reads only declared tool lists, the next request also declares it.
|
|
8
|
+
*
|
|
9
|
+
* Only a name the model was actually told about is served: announcing is what
|
|
10
|
+
* makes a definition fair game. Serving any registered name would let a guessed
|
|
11
|
+
* name pull an unannounced definition into the head and keep it there.
|
|
7
12
|
*
|
|
8
13
|
* @module dsh-dynamic-tools/tool-load
|
|
9
14
|
*/
|
|
10
15
|
|
|
11
16
|
import type { Context } from '@deepseek-ai/cordis'
|
|
17
|
+
import type { Agent } from '@deepseek-ai/dsh-agent'
|
|
12
18
|
import { createUserMessage } from '@deepseek-ai/dsh-llm'
|
|
13
19
|
import { defineTool, projectToolSchema, ToolContextUnavailableError } from '@deepseek-ai/dsh-tools'
|
|
14
20
|
import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
|
|
15
21
|
import { schemaBytes } from './catalog.ts'
|
|
16
|
-
import type
|
|
22
|
+
import { withDefinition, type DisclosureLimits } from './disclosure.ts'
|
|
17
23
|
import { renderLoadedDefinition, renderLoadResult } from './render.ts'
|
|
18
24
|
import { currentState, storeState } from './disclose.ts'
|
|
19
25
|
import type { SourceKind } from './source.ts'
|
|
26
|
+
import type { ToolStrategy } from './strategy.ts'
|
|
20
27
|
|
|
21
28
|
/** Names this plugin owns; a deployment cannot shadow them. */
|
|
22
29
|
export const TOOL_LOAD_NAME = 'tool_load'
|
|
@@ -27,18 +34,22 @@ export interface ToolLoadOptions {
|
|
|
27
34
|
readonly sourceKind: SourceKind
|
|
28
35
|
/** Validated disclosure limits; `maxSchemaBytes` caps a loaded definition. */
|
|
29
36
|
readonly limits: DisclosureLimits
|
|
37
|
+
/** Strategy this step's executor settled, per installed agent. */
|
|
38
|
+
readonly strategy: (agent: Agent) => ToolStrategy | undefined
|
|
39
|
+
/** Names the frozen head declares, per installed agent. */
|
|
40
|
+
readonly declaredNames: (agent: Agent) => ReadonlySet<string>
|
|
30
41
|
}
|
|
31
42
|
|
|
32
43
|
/**
|
|
33
44
|
* Create the `tool_load` definition.
|
|
34
45
|
* @param ctx - plugin context, used to read the agent's visible tools.
|
|
35
|
-
* @param options - source kind and
|
|
46
|
+
* @param options - source kind, limits, and the agent's declaration facts.
|
|
36
47
|
* @returns the unregistered definition.
|
|
37
48
|
*/
|
|
38
49
|
export function createToolLoad(ctx: Context, options: ToolLoadOptions): ToolDefinition {
|
|
39
50
|
return defineTool({
|
|
40
51
|
name: TOOL_LOAD_NAME,
|
|
41
|
-
description: 'Read the full definition of tools that are announced in this conversation but absent from your tool list. Pass their exact names. Definitions arrive as a user message after this result;
|
|
52
|
+
description: 'Read the full definition of tools that are announced in this conversation but absent from your tool list. Pass their exact names. Definitions arrive as a user message after this result; on a route that loads tools on demand the tool is declared in your tool list from the next step on.',
|
|
42
53
|
parameters: {
|
|
43
54
|
names: {
|
|
44
55
|
type: 'array',
|
|
@@ -69,13 +80,14 @@ export function createToolLoad(ctx: Context, options: ToolLoadOptions): ToolDefi
|
|
|
69
80
|
if (agent === undefined) {
|
|
70
81
|
throw new ToolContextUnavailableError(`${TOOL_LOAD_NAME} requires a calling Agent`)
|
|
71
82
|
}
|
|
83
|
+
const strategy = options.strategy(agent) ?? 'tail'
|
|
84
|
+
const declared = options.declaredNames(agent)
|
|
72
85
|
const loaded: string[] = []
|
|
73
86
|
const alreadyAvailable: string[] = []
|
|
74
87
|
const unavailable: string[] = []
|
|
75
88
|
const tooLarge: string[] = []
|
|
76
89
|
const definitions = new Map(ctx.tools.definitions(agent).map(definition => [definition.name, definition]))
|
|
77
|
-
|
|
78
|
-
const nextLoaded = new Set(state.loaded)
|
|
90
|
+
let state = currentState(agent, options.sourceKind)
|
|
79
91
|
const wanted = [...new Set(args.names.map(name => name.trim()).filter(name => name.length > 0))]
|
|
80
92
|
for (const name of wanted) {
|
|
81
93
|
const definition = definitions.get(name)
|
|
@@ -83,23 +95,32 @@ export function createToolLoad(ctx: Context, options: ToolLoadOptions): ToolDefi
|
|
|
83
95
|
unavailable.push(name)
|
|
84
96
|
continue
|
|
85
97
|
}
|
|
98
|
+
if (declared.has(name)) {
|
|
99
|
+
// The definition is already in the tool list; repeating it adds nothing.
|
|
100
|
+
alreadyAvailable.push(name)
|
|
101
|
+
continue
|
|
102
|
+
}
|
|
103
|
+
if (!state.disclosed.has(name)) {
|
|
104
|
+
// A registered name nobody announced: bringing it in would declare a
|
|
105
|
+
// tool the model was never told about.
|
|
106
|
+
unavailable.push(name)
|
|
107
|
+
continue
|
|
108
|
+
}
|
|
86
109
|
const schema = projectToolSchema(definition, true)
|
|
87
110
|
if (schemaBytes(schema) > options.limits.maxSchemaBytes) {
|
|
88
111
|
tooLarge.push(name)
|
|
89
112
|
continue
|
|
90
113
|
}
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
nextLoaded.add(name)
|
|
114
|
+
loaded.push(name)
|
|
115
|
+
state = withDefinition(state, schema)
|
|
94
116
|
exec.deferContext(createUserMessage({
|
|
95
|
-
content: [{ type: 'text', text: renderLoadedDefinition(schema) }],
|
|
117
|
+
content: [{ type: 'text', text: renderLoadedDefinition(schema, strategy) }],
|
|
96
118
|
source: { kind: options.sourceKind, form: 'catalog' },
|
|
97
119
|
}))
|
|
98
120
|
}
|
|
99
|
-
storeState(agent,
|
|
121
|
+
storeState(agent, state)
|
|
100
122
|
return { loaded, alreadyAvailable, unavailable, tooLarge }
|
|
101
123
|
},
|
|
102
124
|
isConcurrencySafe: () => false,
|
|
103
125
|
})
|
|
104
126
|
}
|
|
105
|
-
|