@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/src/disclosure.ts
CHANGED
|
@@ -1,147 +1,212 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Pure disclosure planning: which dynamic tool definitions become trailing
|
|
3
|
-
* messages on this step, how they are batched, and which names stop applying.
|
|
4
|
-
*
|
|
5
|
-
* @module dsh-dynamic-tools/disclosure
|
|
6
|
-
*/
|
|
7
|
-
|
|
8
|
-
import { schemaBytes, toolSignature, type ToolSchemaLike } from './catalog.ts'
|
|
9
|
-
|
|
10
|
-
/** Validated disclosure limits. */
|
|
11
|
-
export interface DisclosureLimits {
|
|
12
|
-
/** Whether definitions are attached to the disclosure message. */
|
|
13
|
-
readonly mode: 'schema' | 'names'
|
|
14
|
-
/** Maximum tools announced in one message. */
|
|
15
|
-
readonly maxToolsPerMessage: number
|
|
16
|
-
/** Maximum UTF-8 bytes of one attached definition. */
|
|
17
|
-
readonly maxSchemaBytes: number
|
|
18
|
-
/** Maximum UTF-8 bytes of one disclosure message. */
|
|
19
|
-
readonly maxMessageBytes: number
|
|
20
|
-
}
|
|
21
|
-
|
|
22
|
-
/** One message's worth of disclosure. */
|
|
23
|
-
export interface DisclosureBatch {
|
|
24
|
-
/** Definitions whose full schema is attached. */
|
|
25
|
-
readonly added: readonly ToolSchemaLike[]
|
|
26
|
-
/** Names announced without a schema; the model must call `tool_load`. */
|
|
27
|
-
readonly names: readonly string[]
|
|
28
|
-
/** Names that are no longer available. */
|
|
29
|
-
readonly removed: readonly string[]
|
|
30
|
-
}
|
|
31
|
-
|
|
32
|
-
/** What was delivered for one name. */
|
|
33
|
-
export interface DisclosedEntry {
|
|
34
|
-
/** Signature of the delivered definition, or `null` when only the name was announced. */
|
|
35
|
-
readonly signature: string | null
|
|
36
|
-
/** Whether the full schema was delivered. */
|
|
37
|
-
readonly schema: boolean
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
/** What the model has already been told, folded from durable messages. */
|
|
41
|
-
export interface DisclosedState {
|
|
42
|
-
/** Delivered name → delivery record. */
|
|
43
|
-
readonly disclosed: ReadonlyMap<string, DisclosedEntry>
|
|
44
|
-
/** Names whose full definition the model has read, attached or loaded on demand. */
|
|
45
|
-
readonly loaded: ReadonlySet<string>
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
}
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
const
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
}
|
|
146
|
-
|
|
147
|
-
|
|
1
|
+
/**
|
|
2
|
+
* Pure disclosure planning: which dynamic tool definitions become trailing
|
|
3
|
+
* messages on this step, how they are batched, and which names stop applying.
|
|
4
|
+
*
|
|
5
|
+
* @module dsh-dynamic-tools/disclosure
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { schemaBytes, toolSignature, type ToolSchemaLike } from './catalog.ts'
|
|
9
|
+
|
|
10
|
+
/** Validated disclosure limits. */
|
|
11
|
+
export interface DisclosureLimits {
|
|
12
|
+
/** Whether definitions are attached to the disclosure message. */
|
|
13
|
+
readonly mode: 'schema' | 'names'
|
|
14
|
+
/** Maximum tools announced in one message. */
|
|
15
|
+
readonly maxToolsPerMessage: number
|
|
16
|
+
/** Maximum UTF-8 bytes of one attached definition. */
|
|
17
|
+
readonly maxSchemaBytes: number
|
|
18
|
+
/** Maximum UTF-8 bytes of one disclosure message. */
|
|
19
|
+
readonly maxMessageBytes: number
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** One message's worth of disclosure. */
|
|
23
|
+
export interface DisclosureBatch {
|
|
24
|
+
/** Definitions whose full schema is attached. */
|
|
25
|
+
readonly added: readonly ToolSchemaLike[]
|
|
26
|
+
/** Names announced without a schema; the model must call `tool_load`. */
|
|
27
|
+
readonly names: readonly string[]
|
|
28
|
+
/** Names that are no longer available. */
|
|
29
|
+
readonly removed: readonly string[]
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** What was delivered for one name. */
|
|
33
|
+
export interface DisclosedEntry {
|
|
34
|
+
/** Signature of the delivered definition, or `null` when only the name was announced. */
|
|
35
|
+
readonly signature: string | null
|
|
36
|
+
/** Whether the full schema was delivered. */
|
|
37
|
+
readonly schema: boolean
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** What the model has already been told, folded from durable messages. */
|
|
41
|
+
export interface DisclosedState {
|
|
42
|
+
/** Delivered name → delivery record. */
|
|
43
|
+
readonly disclosed: ReadonlyMap<string, DisclosedEntry>
|
|
44
|
+
/** Names whose full definition the model has read, attached or loaded on demand. */
|
|
45
|
+
readonly loaded: ReadonlySet<string>
|
|
46
|
+
/**
|
|
47
|
+
* Definitions the model has read, in delivery order.
|
|
48
|
+
*
|
|
49
|
+
* The declare-on-load strategy turns these into tool-list declarations, so
|
|
50
|
+
* they outlive the announcement: a loaded tool stays declared even after the
|
|
51
|
+
* registry stops admitting it.
|
|
52
|
+
*/
|
|
53
|
+
readonly definitions: ReadonlyMap<string, ToolSchemaLike>
|
|
54
|
+
/**
|
|
55
|
+
* Names whose recorded definition block could not be parsed, in delivery
|
|
56
|
+
* order. The caller reports them: the definition is disclosed again, and the
|
|
57
|
+
* damage must not stay silent.
|
|
58
|
+
*/
|
|
59
|
+
readonly damaged: readonly string[]
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** The empty state of a session that has disclosed nothing yet. */
|
|
63
|
+
export const EMPTY_DISCLOSED: DisclosedState = {
|
|
64
|
+
disclosed: new Map(),
|
|
65
|
+
loaded: new Set(),
|
|
66
|
+
definitions: new Map(),
|
|
67
|
+
damaged: [],
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Definitions that no route can deliver because they exceed the schema cap.
|
|
72
|
+
*
|
|
73
|
+
* A `tail` route can still announce such a tool by name — the model calls it
|
|
74
|
+
* without reading the schema, and `tool_load` reports the cap. A `names` route
|
|
75
|
+
* has no such fallback: the tool can only run after its definition was loaded,
|
|
76
|
+
* so announcing it would promise a load that must fail.
|
|
77
|
+
*
|
|
78
|
+
* @param schemas - dynamic definitions admitted for this step.
|
|
79
|
+
* @param limits - validated disclosure limits.
|
|
80
|
+
* @returns names whose definition exceeds `maxSchemaBytes`.
|
|
81
|
+
*/
|
|
82
|
+
export function oversizedNames(
|
|
83
|
+
schemas: readonly ToolSchemaLike[],
|
|
84
|
+
limits: DisclosureLimits,
|
|
85
|
+
): string[] {
|
|
86
|
+
return schemas.filter(schema => schemaBytes(schema) > limits.maxSchemaBytes).map(schema => schema.name)
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* Plan the disclosures one step needs.
|
|
91
|
+
*
|
|
92
|
+
* Adds a tool when it is newly admitted or its definition changed since a full
|
|
93
|
+
* delivery. A name announced without a schema stays announced: `tool_load`
|
|
94
|
+
* always serves the current definition, so re-announcing it would only add noise.
|
|
95
|
+
*
|
|
96
|
+
* @param admitted - dynamic definitions admitted for this step.
|
|
97
|
+
* @param removed - names previously disclosed that are no longer admitted.
|
|
98
|
+
* @param state - previously delivered state.
|
|
99
|
+
* @param limits - validated disclosure limits.
|
|
100
|
+
* @returns ordered batches, empty when the model already knows everything.
|
|
101
|
+
*/
|
|
102
|
+
export function planDisclosure(
|
|
103
|
+
admitted: readonly ToolSchemaLike[],
|
|
104
|
+
removed: readonly string[],
|
|
105
|
+
state: DisclosedState,
|
|
106
|
+
limits: DisclosureLimits,
|
|
107
|
+
): DisclosureBatch[] {
|
|
108
|
+
const attached: ToolSchemaLike[] = []
|
|
109
|
+
const namesOnly: string[] = []
|
|
110
|
+
for (const schema of admitted) {
|
|
111
|
+
const entry = state.disclosed.get(schema.name)
|
|
112
|
+
if (entry !== undefined) {
|
|
113
|
+
if (!entry.schema) continue
|
|
114
|
+
if (entry.signature === toolSignature(schema)) continue
|
|
115
|
+
}
|
|
116
|
+
if (schemaBytes(schema) > limits.maxSchemaBytes) {
|
|
117
|
+
if (limits.mode === 'schema') namesOnly.push(schema.name)
|
|
118
|
+
continue
|
|
119
|
+
}
|
|
120
|
+
if (limits.mode === 'schema') attached.push(schema)
|
|
121
|
+
else namesOnly.push(schema.name)
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
const batches: DisclosureBatch[] = []
|
|
125
|
+
let pendingAdded: ToolSchemaLike[] = []
|
|
126
|
+
let pendingNames: string[] = []
|
|
127
|
+
let pendingRemoved: string[] = []
|
|
128
|
+
let usedBytes = 0
|
|
129
|
+
let pendingCount = 0
|
|
130
|
+
|
|
131
|
+
const flush = (): void => {
|
|
132
|
+
if (pendingCount === 0) return
|
|
133
|
+
batches.push({ added: pendingAdded, names: pendingNames, removed: pendingRemoved })
|
|
134
|
+
pendingAdded = []
|
|
135
|
+
pendingNames = []
|
|
136
|
+
pendingRemoved = []
|
|
137
|
+
usedBytes = 0
|
|
138
|
+
pendingCount = 0
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
const reserve = (bytes: number): void => {
|
|
142
|
+
if (pendingCount > 0 && (pendingCount >= limits.maxToolsPerMessage || usedBytes + bytes > limits.maxMessageBytes)) flush()
|
|
143
|
+
usedBytes += bytes
|
|
144
|
+
pendingCount += 1
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
for (const schema of attached) {
|
|
148
|
+
reserve(limits.mode === 'schema' ? schemaBytes(schema) : schema.name.length)
|
|
149
|
+
pendingAdded.push(schema)
|
|
150
|
+
}
|
|
151
|
+
for (const name of namesOnly) {
|
|
152
|
+
reserve(name.length)
|
|
153
|
+
pendingNames.push(name)
|
|
154
|
+
}
|
|
155
|
+
for (const name of removed) {
|
|
156
|
+
reserve(name.length)
|
|
157
|
+
pendingRemoved.push(name)
|
|
158
|
+
}
|
|
159
|
+
flush()
|
|
160
|
+
return batches
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/**
|
|
164
|
+
* Record one delivered definition, clearing any earlier damage for that name.
|
|
165
|
+
* @param state - state before this delivery.
|
|
166
|
+
* @param schema - definition the model has now read.
|
|
167
|
+
* @returns the updated state.
|
|
168
|
+
*/
|
|
169
|
+
export function withDefinition(state: DisclosedState, schema: ToolSchemaLike): DisclosedState {
|
|
170
|
+
const loaded = new Set(state.loaded).add(schema.name)
|
|
171
|
+
const definitions = new Map(state.definitions).set(schema.name, schema)
|
|
172
|
+
return {
|
|
173
|
+
disclosed: state.disclosed,
|
|
174
|
+
loaded,
|
|
175
|
+
definitions,
|
|
176
|
+
damaged: state.damaged.filter(name => name !== schema.name),
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* Fold delivered batches into the delivered state.
|
|
182
|
+
* @param previous - state before these batches.
|
|
183
|
+
* @param batches - batches that were delivered.
|
|
184
|
+
* @returns the updated state.
|
|
185
|
+
*/
|
|
186
|
+
export function applyDisclosure(
|
|
187
|
+
previous: DisclosedState,
|
|
188
|
+
batches: readonly DisclosureBatch[],
|
|
189
|
+
): DisclosedState {
|
|
190
|
+
const disclosed = new Map(previous.disclosed)
|
|
191
|
+
const loaded = new Set(previous.loaded)
|
|
192
|
+
const definitions = new Map(previous.definitions)
|
|
193
|
+
const damaged = new Set(previous.damaged)
|
|
194
|
+
for (const batch of batches) {
|
|
195
|
+
for (const schema of batch.added) {
|
|
196
|
+
disclosed.set(schema.name, { signature: toolSignature(schema), schema: true })
|
|
197
|
+
loaded.add(schema.name)
|
|
198
|
+
definitions.set(schema.name, schema)
|
|
199
|
+
damaged.delete(schema.name)
|
|
200
|
+
}
|
|
201
|
+
for (const name of batch.names) {
|
|
202
|
+
disclosed.set(name, { signature: null, schema: false })
|
|
203
|
+
}
|
|
204
|
+
for (const name of batch.removed) {
|
|
205
|
+
disclosed.delete(name)
|
|
206
|
+
loaded.delete(name)
|
|
207
|
+
definitions.delete(name)
|
|
208
|
+
damaged.delete(name)
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
return { disclosed, loaded, definitions, damaged: [...damaged] }
|
|
212
|
+
}
|