@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/lib/tool-load.js
CHANGED
|
@@ -1,15 +1,21 @@
|
|
|
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
|
import { createUserMessage } from '@deepseek-ai/dsh-llm';
|
|
11
16
|
import { defineTool, projectToolSchema, ToolContextUnavailableError } from '@deepseek-ai/dsh-tools';
|
|
12
17
|
import { schemaBytes } from "./catalog.js";
|
|
18
|
+
import { withDefinition } from "./disclosure.js";
|
|
13
19
|
import { renderLoadedDefinition, renderLoadResult } from "./render.js";
|
|
14
20
|
import { currentState, storeState } from "./disclose.js";
|
|
15
21
|
/** Names this plugin owns; a deployment cannot shadow them. */
|
|
@@ -17,13 +23,13 @@ export const TOOL_LOAD_NAME = 'tool_load';
|
|
|
17
23
|
/**
|
|
18
24
|
* Create the `tool_load` definition.
|
|
19
25
|
* @param ctx - plugin context, used to read the agent's visible tools.
|
|
20
|
-
* @param options - source kind and
|
|
26
|
+
* @param options - source kind, limits, and the agent's declaration facts.
|
|
21
27
|
* @returns the unregistered definition.
|
|
22
28
|
*/
|
|
23
29
|
export function createToolLoad(ctx, options) {
|
|
24
30
|
return defineTool({
|
|
25
31
|
name: TOOL_LOAD_NAME,
|
|
26
|
-
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;
|
|
32
|
+
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.',
|
|
27
33
|
parameters: {
|
|
28
34
|
names: {
|
|
29
35
|
type: 'array',
|
|
@@ -54,13 +60,14 @@ export function createToolLoad(ctx, options) {
|
|
|
54
60
|
if (agent === undefined) {
|
|
55
61
|
throw new ToolContextUnavailableError(`${TOOL_LOAD_NAME} requires a calling Agent`);
|
|
56
62
|
}
|
|
63
|
+
const strategy = options.strategy(agent) ?? 'tail';
|
|
64
|
+
const declared = options.declaredNames(agent);
|
|
57
65
|
const loaded = [];
|
|
58
66
|
const alreadyAvailable = [];
|
|
59
67
|
const unavailable = [];
|
|
60
68
|
const tooLarge = [];
|
|
61
69
|
const definitions = new Map(ctx.tools.definitions(agent).map(definition => [definition.name, definition]));
|
|
62
|
-
|
|
63
|
-
const nextLoaded = new Set(state.loaded);
|
|
70
|
+
let state = currentState(agent, options.sourceKind);
|
|
64
71
|
const wanted = [...new Set(args.names.map(name => name.trim()).filter(name => name.length > 0))];
|
|
65
72
|
for (const name of wanted) {
|
|
66
73
|
const definition = definitions.get(name);
|
|
@@ -68,22 +75,30 @@ export function createToolLoad(ctx, options) {
|
|
|
68
75
|
unavailable.push(name);
|
|
69
76
|
continue;
|
|
70
77
|
}
|
|
78
|
+
if (declared.has(name)) {
|
|
79
|
+
// The definition is already in the tool list; repeating it adds nothing.
|
|
80
|
+
alreadyAvailable.push(name);
|
|
81
|
+
continue;
|
|
82
|
+
}
|
|
83
|
+
if (!state.disclosed.has(name)) {
|
|
84
|
+
// A registered name nobody announced: bringing it in would declare a
|
|
85
|
+
// tool the model was never told about.
|
|
86
|
+
unavailable.push(name);
|
|
87
|
+
continue;
|
|
88
|
+
}
|
|
71
89
|
const schema = projectToolSchema(definition, true);
|
|
72
90
|
if (schemaBytes(schema) > options.limits.maxSchemaBytes) {
|
|
73
91
|
tooLarge.push(name);
|
|
74
92
|
continue;
|
|
75
93
|
}
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
else
|
|
79
|
-
loaded.push(name);
|
|
80
|
-
nextLoaded.add(name);
|
|
94
|
+
loaded.push(name);
|
|
95
|
+
state = withDefinition(state, schema);
|
|
81
96
|
exec.deferContext(createUserMessage({
|
|
82
|
-
content: [{ type: 'text', text: renderLoadedDefinition(schema) }],
|
|
97
|
+
content: [{ type: 'text', text: renderLoadedDefinition(schema, strategy) }],
|
|
83
98
|
source: { kind: options.sourceKind, form: 'catalog' },
|
|
84
99
|
}));
|
|
85
100
|
}
|
|
86
|
-
storeState(agent,
|
|
101
|
+
storeState(agent, state);
|
|
87
102
|
return { loaded, alreadyAvailable, unavailable, tooLarge };
|
|
88
103
|
},
|
|
89
104
|
isConcurrencySafe: () => false,
|
package/locale/en.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
{
|
|
2
|
-
"meta": {
|
|
3
|
-
"title": "Dynamic tools",
|
|
4
|
-
"description": "Freezes the request tool list after a session's first step and delivers later tools as trailing context, so a mid-conversation tool change no longer rewrites the cached prompt prefix. Applies to the native tool executor; tools are classified by name, and a tool that the step does not admit fails with an actionable error instead of running.",
|
|
5
|
-
"detail": "docs/DETAIL.md"
|
|
6
|
-
}
|
|
7
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"meta": {
|
|
3
|
+
"title": "Dynamic tools",
|
|
4
|
+
"description": "Freezes the request tool list after a session's first step and delivers later tools as trailing context, so a mid-conversation tool change no longer rewrites the cached prompt prefix. Applies to the native tool executor; tools are classified by name, and a tool that the step does not admit fails with an actionable error instead of running.",
|
|
5
|
+
"detail": "docs/DETAIL.md"
|
|
6
|
+
}
|
|
7
|
+
}
|
package/locale/zh.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
{
|
|
2
|
-
"meta": {
|
|
3
|
-
"title": "动态工具加载",
|
|
4
|
-
"description": "会话首步之后冻结请求中的工具列表,之后出现的工具以对话尾部消息下发,中途的工具变化不再重写已缓存的前缀。仅作用于原生工具执行器;按工具名分类,未在本步准入的工具会得到可执行的错误而不是被执行。",
|
|
5
|
-
"detail": "docs/DETAIL.md"
|
|
6
|
-
}
|
|
7
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"meta": {
|
|
3
|
+
"title": "动态工具加载",
|
|
4
|
+
"description": "会话首步之后冻结请求中的工具列表,之后出现的工具以对话尾部消息下发,中途的工具变化不再重写已缓存的前缀。仅作用于原生工具执行器;按工具名分类,未在本步准入的工具会得到可执行的错误而不是被执行。",
|
|
5
|
+
"detail": "docs/DETAIL.md"
|
|
6
|
+
}
|
|
7
|
+
}
|
package/package.json
CHANGED
|
@@ -1,75 +1,75 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@dsh-plugin/dsh-dynamic-tools",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"type": "module",
|
|
5
|
-
"description": "Keeps the tool declaration head of a request frozen and discloses tools registered later as trailing context, so mid-conversation tool changes stop invalidating the cached prompt prefix.",
|
|
6
|
-
"exports": {
|
|
7
|
-
".": {
|
|
8
|
-
"types": "./lib/index.d.ts",
|
|
9
|
-
"default": "./lib/index.js"
|
|
10
|
-
},
|
|
11
|
-
"./locale/*.json": "./locale/*.json",
|
|
12
|
-
"./icon": "./icon.svg"
|
|
13
|
-
},
|
|
14
|
-
"files": [
|
|
15
|
-
"lib/**/*.js",
|
|
16
|
-
"lib/**/*.d.ts",
|
|
17
|
-
"src/**/*.ts",
|
|
18
|
-
"cordis.patch.yml",
|
|
19
|
-
"locale/*.json",
|
|
20
|
-
"docs",
|
|
21
|
-
"icon.svg",
|
|
22
|
-
"README.md",
|
|
23
|
-
"LICENSE"
|
|
24
|
-
],
|
|
25
|
-
"scripts": {
|
|
26
|
-
"build": "tsc -p tsconfig.json",
|
|
27
|
-
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
28
|
-
"test": "node --test \"tests/*.test.ts\"",
|
|
29
|
-
"prepack": "npm run build"
|
|
30
|
-
},
|
|
31
|
-
"license": "LGPL-3.0-only",
|
|
32
|
-
"repository": {
|
|
33
|
-
"type": "git",
|
|
34
|
-
"url": "git+https://github.com/dsh-plugins/dsh-dynamic-tools.git"
|
|
35
|
-
},
|
|
36
|
-
"publishConfig": {
|
|
37
|
-
"access": "public"
|
|
38
|
-
},
|
|
39
|
-
"keywords": [
|
|
40
|
-
"deepseek-harness",
|
|
41
|
-
"dsh",
|
|
42
|
-
"plugin",
|
|
43
|
-
"tools",
|
|
44
|
-
"prompt-cache"
|
|
45
|
-
],
|
|
46
|
-
"peerDependencies": {
|
|
47
|
-
"@deepseek-ai/cordis": "~4.1.0",
|
|
48
|
-
"@deepseek-ai/dsh-agent": "^0.2.2-rc.2",
|
|
49
|
-
"@deepseek-ai/dsh-llm": "^0.2.2-rc.2",
|
|
50
|
-
"@deepseek-ai/dsh-scope": "^0.2.2-rc.2",
|
|
51
|
-
"@deepseek-ai/dsh-session": "^0.2.2-rc.2",
|
|
52
|
-
"@deepseek-ai/dsh-system-prompt": "^0.2.2-rc.2",
|
|
53
|
-
"@deepseek-ai/dsh-tools": "^0.2.2-rc.2",
|
|
54
|
-
"@deepseek-ai/schemastery": "~3.19.0"
|
|
55
|
-
},
|
|
56
|
-
"devDependencies": {
|
|
57
|
-
"@deepseek-ai/cordis": "4.1.0",
|
|
58
|
-
"@deepseek-ai/dsh-agent": "0.2.2-rc.2",
|
|
59
|
-
"@deepseek-ai/dsh-llm": "0.2.2-rc.2",
|
|
60
|
-
"@deepseek-ai/dsh-scope": "0.2.2-rc.2",
|
|
61
|
-
"@deepseek-ai/dsh-session": "0.2.2-rc.2",
|
|
62
|
-
"@deepseek-ai/dsh-system-prompt": "0.2.2-rc.2",
|
|
63
|
-
"@deepseek-ai/dsh-tools": "0.2.2-rc.2",
|
|
64
|
-
"@deepseek-ai/schemastery": "3.19.0",
|
|
65
|
-
"typescript": "5.9.3"
|
|
66
|
-
},
|
|
67
|
-
"engines": {
|
|
68
|
-
"dsh": ">=0.2.2-rc.2 <0.3.0"
|
|
69
|
-
},
|
|
70
|
-
"dsh": {
|
|
71
|
-
"bundle": {
|
|
72
|
-
"patch": "./cordis.patch.yml"
|
|
73
|
-
}
|
|
74
|
-
}
|
|
75
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@dsh-plugin/dsh-dynamic-tools",
|
|
3
|
+
"version": "0.1.0-dev.43582542989",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"description": "Keeps the tool declaration head of a request frozen and discloses tools registered later as trailing context, so mid-conversation tool changes stop invalidating the cached prompt prefix; routes that call only declared tools load those definitions on demand and get them declared instead.",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": {
|
|
8
|
+
"types": "./lib/index.d.ts",
|
|
9
|
+
"default": "./lib/index.js"
|
|
10
|
+
},
|
|
11
|
+
"./locale/*.json": "./locale/*.json",
|
|
12
|
+
"./icon": "./icon.svg"
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"lib/**/*.js",
|
|
16
|
+
"lib/**/*.d.ts",
|
|
17
|
+
"src/**/*.ts",
|
|
18
|
+
"cordis.patch.yml",
|
|
19
|
+
"locale/*.json",
|
|
20
|
+
"docs",
|
|
21
|
+
"icon.svg",
|
|
22
|
+
"README.md",
|
|
23
|
+
"LICENSE"
|
|
24
|
+
],
|
|
25
|
+
"scripts": {
|
|
26
|
+
"build": "tsc -p tsconfig.json",
|
|
27
|
+
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
28
|
+
"test": "node --test \"tests/*.test.ts\"",
|
|
29
|
+
"prepack": "npm run build"
|
|
30
|
+
},
|
|
31
|
+
"license": "LGPL-3.0-only",
|
|
32
|
+
"repository": {
|
|
33
|
+
"type": "git",
|
|
34
|
+
"url": "git+https://github.com/dsh-plugins/dsh-dynamic-tools.git"
|
|
35
|
+
},
|
|
36
|
+
"publishConfig": {
|
|
37
|
+
"access": "public"
|
|
38
|
+
},
|
|
39
|
+
"keywords": [
|
|
40
|
+
"deepseek-harness",
|
|
41
|
+
"dsh",
|
|
42
|
+
"plugin",
|
|
43
|
+
"tools",
|
|
44
|
+
"prompt-cache"
|
|
45
|
+
],
|
|
46
|
+
"peerDependencies": {
|
|
47
|
+
"@deepseek-ai/cordis": "~4.1.0",
|
|
48
|
+
"@deepseek-ai/dsh-agent": "^0.2.2-rc.2",
|
|
49
|
+
"@deepseek-ai/dsh-llm": "^0.2.2-rc.2",
|
|
50
|
+
"@deepseek-ai/dsh-scope": "^0.2.2-rc.2",
|
|
51
|
+
"@deepseek-ai/dsh-session": "^0.2.2-rc.2",
|
|
52
|
+
"@deepseek-ai/dsh-system-prompt": "^0.2.2-rc.2",
|
|
53
|
+
"@deepseek-ai/dsh-tools": "^0.2.2-rc.2",
|
|
54
|
+
"@deepseek-ai/schemastery": "~3.19.0"
|
|
55
|
+
},
|
|
56
|
+
"devDependencies": {
|
|
57
|
+
"@deepseek-ai/cordis": "4.1.0",
|
|
58
|
+
"@deepseek-ai/dsh-agent": "0.2.2-rc.2",
|
|
59
|
+
"@deepseek-ai/dsh-llm": "0.2.2-rc.2",
|
|
60
|
+
"@deepseek-ai/dsh-scope": "0.2.2-rc.2",
|
|
61
|
+
"@deepseek-ai/dsh-session": "0.2.2-rc.2",
|
|
62
|
+
"@deepseek-ai/dsh-system-prompt": "0.2.2-rc.2",
|
|
63
|
+
"@deepseek-ai/dsh-tools": "0.2.2-rc.2",
|
|
64
|
+
"@deepseek-ai/schemastery": "3.19.0",
|
|
65
|
+
"typescript": "5.9.3"
|
|
66
|
+
},
|
|
67
|
+
"engines": {
|
|
68
|
+
"dsh": ">=0.2.2-rc.2 <0.3.0"
|
|
69
|
+
},
|
|
70
|
+
"dsh": {
|
|
71
|
+
"bundle": {
|
|
72
|
+
"patch": "./cordis.patch.yml"
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
package/src/catalog.ts
CHANGED
|
@@ -1,88 +1,112 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Pure classification and signature helpers for the frozen tool catalog.
|
|
3
|
-
* No Harness imports: these run under the Node type-stripping loader in tests.
|
|
4
|
-
*
|
|
5
|
-
* @module dsh-dynamic-tools/catalog
|
|
6
|
-
*/
|
|
7
|
-
|
|
8
|
-
/** Model-facing tool schema fields this plugin reads without Harness types. */
|
|
9
|
-
export interface ToolSchemaLike {
|
|
10
|
-
readonly name: string
|
|
11
|
-
readonly description: string
|
|
12
|
-
readonly parameters: Record<string, unknown>
|
|
13
|
-
}
|
|
14
|
-
|
|
15
|
-
/** How one registered tool name is disclosed. */
|
|
16
|
-
export type ToolClass = 'inline' | 'dynamic'
|
|
17
|
-
|
|
18
|
-
/** Rules that decide which tools belong in the frozen declaration head. */
|
|
19
|
-
export interface ClassificationRules {
|
|
20
|
-
/** Exact names that never enter the frozen catalog. */
|
|
21
|
-
readonly dynamicNames: readonly string[]
|
|
22
|
-
/** Name prefixes that never enter the frozen catalog. */
|
|
23
|
-
readonly dynamicPrefixes: readonly string[]
|
|
24
|
-
/** Exact names forced into the catalog, overriding the rules above. */
|
|
25
|
-
readonly inlineNames: readonly string[]
|
|
26
|
-
}
|
|
27
|
-
|
|
28
|
-
/**
|
|
29
|
-
* Decide how one tool name is disclosed.
|
|
30
|
-
* @param name - registered tool name.
|
|
31
|
-
* @param rules - configured classification rules.
|
|
32
|
-
* @returns `inline` for the frozen catalog, `dynamic` for tail disclosure.
|
|
33
|
-
*/
|
|
34
|
-
export function classifyTool(name: string, rules: ClassificationRules): ToolClass {
|
|
35
|
-
if (rules.inlineNames.includes(name)) return 'inline'
|
|
36
|
-
if (rules.dynamicNames.includes(name)) return 'dynamic'
|
|
37
|
-
if (rules.dynamicPrefixes.some(prefix => name.startsWith(prefix))) return 'dynamic'
|
|
38
|
-
return 'inline'
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
/** Deterministic JSON text with object keys sorted, so equal schemas compare equal. */
|
|
42
|
-
function stableJson(value: unknown): string {
|
|
43
|
-
if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
|
|
44
|
-
if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`
|
|
45
|
-
const entries = Object.keys(value as Record<string, unknown>).sort()
|
|
46
|
-
.map(key => `${JSON.stringify(key)}:${stableJson((value as Record<string, unknown>)[key])}`)
|
|
47
|
-
return `{${entries.join(',')}}`
|
|
48
|
-
}
|
|
49
|
-
|
|
50
|
-
/**
|
|
51
|
-
* Identity of one tool definition for change detection.
|
|
52
|
-
* Same-name registrations that differ only in key order share a signature.
|
|
53
|
-
* @param schema - model-facing schema of the definition.
|
|
54
|
-
* @returns a comparable signature string.
|
|
55
|
-
*/
|
|
56
|
-
export function toolSignature(schema: ToolSchemaLike): string {
|
|
57
|
-
return `${schema.name}\u0000${schema.description}\u0000${stableJson(schema.parameters)}`
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
/**
|
|
61
|
-
* Split the registered definitions into the frozen catalog and tail disclosures.
|
|
62
|
-
* @param definitions - every definition visible to the agent at capture time.
|
|
63
|
-
* @param rules - configured classification rules.
|
|
64
|
-
* @returns inline schemas for the head and configured dynamic schemas.
|
|
65
|
-
*/
|
|
66
|
-
export function splitCatalog(
|
|
67
|
-
definitions: readonly ToolSchemaLike[],
|
|
68
|
-
rules: ClassificationRules,
|
|
69
|
-
): { inline: ToolSchemaLike[], dynamic: ToolSchemaLike[] } {
|
|
70
|
-
const inline: ToolSchemaLike[] = []
|
|
71
|
-
const dynamic: ToolSchemaLike[] = []
|
|
72
|
-
for (const definition of definitions) {
|
|
73
|
-
if (classifyTool(definition.name, rules) === 'inline') inline.push(definition)
|
|
74
|
-
else dynamic.push(definition)
|
|
75
|
-
}
|
|
76
|
-
return { inline, dynamic }
|
|
77
|
-
}
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
1
|
+
/**
|
|
2
|
+
* Pure classification and signature helpers for the frozen tool catalog.
|
|
3
|
+
* No Harness imports: these run under the Node type-stripping loader in tests.
|
|
4
|
+
*
|
|
5
|
+
* @module dsh-dynamic-tools/catalog
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
/** Model-facing tool schema fields this plugin reads without Harness types. */
|
|
9
|
+
export interface ToolSchemaLike {
|
|
10
|
+
readonly name: string
|
|
11
|
+
readonly description: string
|
|
12
|
+
readonly parameters: Record<string, unknown>
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** How one registered tool name is disclosed. */
|
|
16
|
+
export type ToolClass = 'inline' | 'dynamic'
|
|
17
|
+
|
|
18
|
+
/** Rules that decide which tools belong in the frozen declaration head. */
|
|
19
|
+
export interface ClassificationRules {
|
|
20
|
+
/** Exact names that never enter the frozen catalog. */
|
|
21
|
+
readonly dynamicNames: readonly string[]
|
|
22
|
+
/** Name prefixes that never enter the frozen catalog. */
|
|
23
|
+
readonly dynamicPrefixes: readonly string[]
|
|
24
|
+
/** Exact names forced into the catalog, overriding the rules above. */
|
|
25
|
+
readonly inlineNames: readonly string[]
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Decide how one tool name is disclosed.
|
|
30
|
+
* @param name - registered tool name.
|
|
31
|
+
* @param rules - configured classification rules.
|
|
32
|
+
* @returns `inline` for the frozen catalog, `dynamic` for tail disclosure.
|
|
33
|
+
*/
|
|
34
|
+
export function classifyTool(name: string, rules: ClassificationRules): ToolClass {
|
|
35
|
+
if (rules.inlineNames.includes(name)) return 'inline'
|
|
36
|
+
if (rules.dynamicNames.includes(name)) return 'dynamic'
|
|
37
|
+
if (rules.dynamicPrefixes.some(prefix => name.startsWith(prefix))) return 'dynamic'
|
|
38
|
+
return 'inline'
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** Deterministic JSON text with object keys sorted, so equal schemas compare equal. */
|
|
42
|
+
function stableJson(value: unknown): string {
|
|
43
|
+
if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
|
|
44
|
+
if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`
|
|
45
|
+
const entries = Object.keys(value as Record<string, unknown>).sort()
|
|
46
|
+
.map(key => `${JSON.stringify(key)}:${stableJson((value as Record<string, unknown>)[key])}`)
|
|
47
|
+
return `{${entries.join(',')}}`
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Identity of one tool definition for change detection.
|
|
52
|
+
* Same-name registrations that differ only in key order share a signature.
|
|
53
|
+
* @param schema - model-facing schema of the definition.
|
|
54
|
+
* @returns a comparable signature string.
|
|
55
|
+
*/
|
|
56
|
+
export function toolSignature(schema: ToolSchemaLike): string {
|
|
57
|
+
return `${schema.name}\u0000${schema.description}\u0000${stableJson(schema.parameters)}`
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Split the registered definitions into the frozen catalog and tail disclosures.
|
|
62
|
+
* @param definitions - every definition visible to the agent at capture time.
|
|
63
|
+
* @param rules - configured classification rules.
|
|
64
|
+
* @returns inline schemas for the head and configured dynamic schemas.
|
|
65
|
+
*/
|
|
66
|
+
export function splitCatalog(
|
|
67
|
+
definitions: readonly ToolSchemaLike[],
|
|
68
|
+
rules: ClassificationRules,
|
|
69
|
+
): { inline: ToolSchemaLike[], dynamic: ToolSchemaLike[] } {
|
|
70
|
+
const inline: ToolSchemaLike[] = []
|
|
71
|
+
const dynamic: ToolSchemaLike[] = []
|
|
72
|
+
for (const definition of definitions) {
|
|
73
|
+
if (classifyTool(definition.name, rules) === 'inline') inline.push(definition)
|
|
74
|
+
else dynamic.push(definition)
|
|
75
|
+
}
|
|
76
|
+
return { inline, dynamic }
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Append declared definitions to the frozen catalog, keeping both orders.
|
|
81
|
+
*
|
|
82
|
+
* A name the catalog already declares keeps its catalog position and
|
|
83
|
+
* definition: the head must not move because a tool became loadable.
|
|
84
|
+
*
|
|
85
|
+
* @param catalog - frozen declaration head.
|
|
86
|
+
* @param declared - definitions loaded on demand, in load order.
|
|
87
|
+
* @returns the head followed by every declared name it does not declare.
|
|
88
|
+
*/
|
|
89
|
+
export function extendCatalog(
|
|
90
|
+
catalog: readonly ToolSchemaLike[],
|
|
91
|
+
declared: readonly ToolSchemaLike[],
|
|
92
|
+
): ToolSchemaLike[] {
|
|
93
|
+
const names = new Set(catalog.map(schema => schema.name))
|
|
94
|
+
const extended = [...catalog]
|
|
95
|
+
for (const schema of declared) {
|
|
96
|
+
if (names.has(schema.name)) continue
|
|
97
|
+
names.add(schema.name)
|
|
98
|
+
extended.push(schema)
|
|
99
|
+
}
|
|
100
|
+
return extended
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
const encoder = new TextEncoder()
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* JSON size of one definition as it would be disclosed.
|
|
107
|
+
* @param schema - model-facing schema of the definition.
|
|
108
|
+
* @returns UTF-8 byte length of its JSON encoding.
|
|
109
|
+
*/
|
|
110
|
+
export function schemaBytes(schema: ToolSchemaLike): number {
|
|
111
|
+
return encoder.encode(JSON.stringify(schema)).length
|
|
112
|
+
}
|