@dsh-plugin/dsh-dynamic-tools 0.0.1 → 0.1.0-dev.43450988228
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 +111 -111
- package/docs/DETAIL.md +1 -1
- package/docs/preview.svg +25 -25
- package/icon.svg +7 -7
- package/locale/en.json +7 -7
- package/locale/zh.json +7 -7
- package/package.json +75 -75
- package/src/catalog.ts +88 -88
- package/src/disclose.ts +151 -151
- package/src/disclosure.ts +147 -147
- package/src/executor.ts +145 -145
- package/src/fold.ts +104 -104
- package/src/index.ts +178 -178
- package/src/install.ts +91 -91
- package/src/render.ts +115 -115
- package/src/source.ts +20 -20
- package/src/tool-load.ts +105 -105
package/src/disclose.ts
CHANGED
|
@@ -1,151 +1,151 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Trailing disclosure of dynamic tool definitions.
|
|
3
|
-
*
|
|
4
|
-
* Runs after the step's own pre-step listeners settle and appends recorded user
|
|
5
|
-
* messages, so the request head never changes. The disclosed set follows the
|
|
6
|
-
* registry, not the step's admission: a tool the model may not call right now
|
|
7
|
-
* is still worth naming, because the call itself reports why it is unavailable.
|
|
8
|
-
*
|
|
9
|
-
* @module dsh-dynamic-tools/disclose
|
|
10
|
-
*/
|
|
11
|
-
|
|
12
|
-
import type { Context } from '@deepseek-ai/cordis'
|
|
13
|
-
import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent'
|
|
14
|
-
import { createUserMessage } from '@deepseek-ai/dsh-llm'
|
|
15
|
-
import type { UserMessage } from '@deepseek-ai/dsh-llm'
|
|
16
|
-
import { projectToolSchema } from '@deepseek-ai/dsh-tools'
|
|
17
|
-
import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
|
|
18
|
-
import type { ToolSchemaLike } from './catalog.ts'
|
|
19
|
-
import { applyDisclosure, planDisclosure, type DisclosedState, type DisclosureLimits } from './disclosure.ts'
|
|
20
|
-
import { foldDisclosed } from './fold.ts'
|
|
21
|
-
import { renderDisclosure } from './render.ts'
|
|
22
|
-
import type { SourceKind } from './source.ts'
|
|
23
|
-
|
|
24
|
-
/** Everything the pre-step listener needs to plan one step's disclosure. */
|
|
25
|
-
export interface DiscloseOptions {
|
|
26
|
-
/** Message source kind owned by this plugin. */
|
|
27
|
-
readonly sourceKind: SourceKind
|
|
28
|
-
/** Validated disclosure limits. */
|
|
29
|
-
readonly limits: DisclosureLimits
|
|
30
|
-
/** Whether names that disappear from the registry are announced. */
|
|
31
|
-
readonly announceRemovals: boolean
|
|
32
|
-
/** Names the frozen head declares, per installed agent. */
|
|
33
|
-
readonly catalogNames: (agent: Agent) => ReadonlySet<string>
|
|
34
|
-
/** Definitions this step admits, recorded by the executor's last assembly. */
|
|
35
|
-
readonly admitted: (agent: Agent) => readonly ToolDefinition[] | undefined
|
|
36
|
-
}
|
|
37
|
-
|
|
38
|
-
/** Process-local delivery state, kept as a fast path beside the durable fold. */
|
|
39
|
-
interface HeldState {
|
|
40
|
-
state: DisclosedState
|
|
41
|
-
}
|
|
42
|
-
|
|
43
|
-
/** Per-Agent delivery state without retaining agents. */
|
|
44
|
-
const stateByAgent = new WeakMap<Agent, HeldState>()
|
|
45
|
-
|
|
46
|
-
/**
|
|
47
|
-
* Read the session's delivered state, rebuilding it from durable messages when
|
|
48
|
-
* the process-local holder is missing (resume, fork, compaction).
|
|
49
|
-
* @param agent - agent whose session is read.
|
|
50
|
-
* @param kind - message source kind owned by this plugin.
|
|
51
|
-
* @returns the folded state.
|
|
52
|
-
*/
|
|
53
|
-
export function currentState(agent: Agent, kind: SourceKind): DisclosedState {
|
|
54
|
-
const holder = stateByAgent.get(agent)
|
|
55
|
-
if (holder !== undefined) return holder.state
|
|
56
|
-
const folded = foldDisclosed(agent.session.deriveMessages(), kind)
|
|
57
|
-
stateByAgent.set(agent, { state: folded })
|
|
58
|
-
return folded
|
|
59
|
-
}
|
|
60
|
-
|
|
61
|
-
/**
|
|
62
|
-
* Replace the process-local state after a disclosure or a load.
|
|
63
|
-
* @param agent - agent whose session was updated.
|
|
64
|
-
* @param state - new state.
|
|
65
|
-
*/
|
|
66
|
-
export function storeState(agent: Agent, state: DisclosedState): void {
|
|
67
|
-
stateByAgent.set(agent, { state })
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
/**
|
|
71
|
-
* Drop process-local state so the next read folds the durable messages again.
|
|
72
|
-
* @param agent - agent whose session was compacted or replaced.
|
|
73
|
-
*/
|
|
74
|
-
export function invalidateState(agent: Agent): void {
|
|
75
|
-
stateByAgent.delete(agent)
|
|
76
|
-
}
|
|
77
|
-
|
|
78
|
-
function schemasOutsideCatalog(
|
|
79
|
-
definitions: readonly ToolDefinition[],
|
|
80
|
-
catalogNames: ReadonlySet<string>,
|
|
81
|
-
): ToolSchemaLike[] {
|
|
82
|
-
return definitions
|
|
83
|
-
.filter(definition => !catalogNames.has(definition.name))
|
|
84
|
-
.map(definition => projectToolSchema(definition, true))
|
|
85
|
-
}
|
|
86
|
-
|
|
87
|
-
/**
|
|
88
|
-
* Append this step's disclosure messages.
|
|
89
|
-
*
|
|
90
|
-
* Only definitions the step actually admits are candidates. A registered tool
|
|
91
|
-
* whose `when` condition is false is unavailable right now: announcing it would
|
|
92
|
-
* invite a call that can only be denied, so it is not disclosed at all.
|
|
93
|
-
*
|
|
94
|
-
* @param ctx - plugin context for diagnostics.
|
|
95
|
-
* @param agent - agent entering the step.
|
|
96
|
-
* @param admitted - definitions this step admits.
|
|
97
|
-
* @param executorCatalog - names the frozen head declares.
|
|
98
|
-
* @param options - disclosure settings.
|
|
99
|
-
* @returns the messages to append, in order.
|
|
100
|
-
*/
|
|
101
|
-
export function disclosureMessages(
|
|
102
|
-
ctx: Context,
|
|
103
|
-
agent: Agent,
|
|
104
|
-
admitted: readonly ToolDefinition[],
|
|
105
|
-
executorCatalog: ReadonlySet<string>,
|
|
106
|
-
options: DiscloseOptions,
|
|
107
|
-
): readonly UserMessage[] {
|
|
108
|
-
const candidates = schemasOutsideCatalog(admitted, executorCatalog)
|
|
109
|
-
const current = currentState(agent, options.sourceKind)
|
|
110
|
-
const available = new Set(candidates.map(schema => schema.name))
|
|
111
|
-
const removed = options.announceRemovals
|
|
112
|
-
? [...current.disclosed.keys()].filter(name => !available.has(name) && !executorCatalog.has(name))
|
|
113
|
-
: []
|
|
114
|
-
const batches = planDisclosure(candidates, removed, current, options.limits)
|
|
115
|
-
if (batches.length === 0) {
|
|
116
|
-
// A pruned history still needs its records re-linked for later comparisons.
|
|
117
|
-
const folded = foldDisclosed(agent.session.deriveMessages(), options.sourceKind)
|
|
118
|
-
if (folded.disclosed.size !== current.disclosed.size) storeState(agent, folded)
|
|
119
|
-
return []
|
|
120
|
-
}
|
|
121
|
-
const messages = batches.map(batch => createUserMessage({
|
|
122
|
-
content: [{ type: 'text', text: renderDisclosure(batch) }],
|
|
123
|
-
source: { kind: options.sourceKind, form: 'catalog' },
|
|
124
|
-
}))
|
|
125
|
-
storeState(agent, applyDisclosure(current, batches))
|
|
126
|
-
ctx.logger.debug('dsh-dynamic-tools: disclosed %d batch(es) at step start', batches.length)
|
|
127
|
-
return messages
|
|
128
|
-
}
|
|
129
|
-
|
|
130
|
-
/**
|
|
131
|
-
* Register the pre-step listener that appends disclosures.
|
|
132
|
-
* @param ctx - plugin context owning the listener.
|
|
133
|
-
* @param options - disclosure settings.
|
|
134
|
-
*/
|
|
135
|
-
export function registerDisclosure(ctx: Context, options: DiscloseOptions): void {
|
|
136
|
-
ctx.on('agent/pre-step', async ({ agent, signal }, next): Promise<PreStepDecision> => {
|
|
137
|
-
const decision = await next()
|
|
138
|
-
if (decision.kind === 'reject' || signal.aborted) return decision
|
|
139
|
-
try {
|
|
140
|
-
// The executor recorded this step's admission when assembly described the head.
|
|
141
|
-
const admitted = options.admitted(agent)
|
|
142
|
-
if (admitted === undefined) return decision
|
|
143
|
-
const messages = disclosureMessages(ctx, agent, admitted, options.catalogNames(agent), options)
|
|
144
|
-
if (messages.length === 0) return decision
|
|
145
|
-
return { ...decision, messages: [...decision.messages, ...messages] }
|
|
146
|
-
} catch (error: unknown) {
|
|
147
|
-
ctx.logger.warn('dsh-dynamic-tools: failed to disclose tool definitions at step start: %o', error)
|
|
148
|
-
return decision
|
|
149
|
-
}
|
|
150
|
-
})
|
|
151
|
-
}
|
|
1
|
+
/**
|
|
2
|
+
* Trailing disclosure of dynamic tool definitions.
|
|
3
|
+
*
|
|
4
|
+
* Runs after the step's own pre-step listeners settle and appends recorded user
|
|
5
|
+
* messages, so the request head never changes. The disclosed set follows the
|
|
6
|
+
* registry, not the step's admission: a tool the model may not call right now
|
|
7
|
+
* is still worth naming, because the call itself reports why it is unavailable.
|
|
8
|
+
*
|
|
9
|
+
* @module dsh-dynamic-tools/disclose
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import type { Context } from '@deepseek-ai/cordis'
|
|
13
|
+
import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent'
|
|
14
|
+
import { createUserMessage } from '@deepseek-ai/dsh-llm'
|
|
15
|
+
import type { UserMessage } from '@deepseek-ai/dsh-llm'
|
|
16
|
+
import { projectToolSchema } from '@deepseek-ai/dsh-tools'
|
|
17
|
+
import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
|
|
18
|
+
import type { ToolSchemaLike } from './catalog.ts'
|
|
19
|
+
import { applyDisclosure, planDisclosure, type DisclosedState, type DisclosureLimits } from './disclosure.ts'
|
|
20
|
+
import { foldDisclosed } from './fold.ts'
|
|
21
|
+
import { renderDisclosure } from './render.ts'
|
|
22
|
+
import type { SourceKind } from './source.ts'
|
|
23
|
+
|
|
24
|
+
/** Everything the pre-step listener needs to plan one step's disclosure. */
|
|
25
|
+
export interface DiscloseOptions {
|
|
26
|
+
/** Message source kind owned by this plugin. */
|
|
27
|
+
readonly sourceKind: SourceKind
|
|
28
|
+
/** Validated disclosure limits. */
|
|
29
|
+
readonly limits: DisclosureLimits
|
|
30
|
+
/** Whether names that disappear from the registry are announced. */
|
|
31
|
+
readonly announceRemovals: boolean
|
|
32
|
+
/** Names the frozen head declares, per installed agent. */
|
|
33
|
+
readonly catalogNames: (agent: Agent) => ReadonlySet<string>
|
|
34
|
+
/** Definitions this step admits, recorded by the executor's last assembly. */
|
|
35
|
+
readonly admitted: (agent: Agent) => readonly ToolDefinition[] | undefined
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** Process-local delivery state, kept as a fast path beside the durable fold. */
|
|
39
|
+
interface HeldState {
|
|
40
|
+
state: DisclosedState
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** Per-Agent delivery state without retaining agents. */
|
|
44
|
+
const stateByAgent = new WeakMap<Agent, HeldState>()
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Read the session's delivered state, rebuilding it from durable messages when
|
|
48
|
+
* the process-local holder is missing (resume, fork, compaction).
|
|
49
|
+
* @param agent - agent whose session is read.
|
|
50
|
+
* @param kind - message source kind owned by this plugin.
|
|
51
|
+
* @returns the folded state.
|
|
52
|
+
*/
|
|
53
|
+
export function currentState(agent: Agent, kind: SourceKind): DisclosedState {
|
|
54
|
+
const holder = stateByAgent.get(agent)
|
|
55
|
+
if (holder !== undefined) return holder.state
|
|
56
|
+
const folded = foldDisclosed(agent.session.deriveMessages(), kind)
|
|
57
|
+
stateByAgent.set(agent, { state: folded })
|
|
58
|
+
return folded
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Replace the process-local state after a disclosure or a load.
|
|
63
|
+
* @param agent - agent whose session was updated.
|
|
64
|
+
* @param state - new state.
|
|
65
|
+
*/
|
|
66
|
+
export function storeState(agent: Agent, state: DisclosedState): void {
|
|
67
|
+
stateByAgent.set(agent, { state })
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Drop process-local state so the next read folds the durable messages again.
|
|
72
|
+
* @param agent - agent whose session was compacted or replaced.
|
|
73
|
+
*/
|
|
74
|
+
export function invalidateState(agent: Agent): void {
|
|
75
|
+
stateByAgent.delete(agent)
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
function schemasOutsideCatalog(
|
|
79
|
+
definitions: readonly ToolDefinition[],
|
|
80
|
+
catalogNames: ReadonlySet<string>,
|
|
81
|
+
): ToolSchemaLike[] {
|
|
82
|
+
return definitions
|
|
83
|
+
.filter(definition => !catalogNames.has(definition.name))
|
|
84
|
+
.map(definition => projectToolSchema(definition, true))
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Append this step's disclosure messages.
|
|
89
|
+
*
|
|
90
|
+
* Only definitions the step actually admits are candidates. A registered tool
|
|
91
|
+
* whose `when` condition is false is unavailable right now: announcing it would
|
|
92
|
+
* invite a call that can only be denied, so it is not disclosed at all.
|
|
93
|
+
*
|
|
94
|
+
* @param ctx - plugin context for diagnostics.
|
|
95
|
+
* @param agent - agent entering the step.
|
|
96
|
+
* @param admitted - definitions this step admits.
|
|
97
|
+
* @param executorCatalog - names the frozen head declares.
|
|
98
|
+
* @param options - disclosure settings.
|
|
99
|
+
* @returns the messages to append, in order.
|
|
100
|
+
*/
|
|
101
|
+
export function disclosureMessages(
|
|
102
|
+
ctx: Context,
|
|
103
|
+
agent: Agent,
|
|
104
|
+
admitted: readonly ToolDefinition[],
|
|
105
|
+
executorCatalog: ReadonlySet<string>,
|
|
106
|
+
options: DiscloseOptions,
|
|
107
|
+
): readonly UserMessage[] {
|
|
108
|
+
const candidates = schemasOutsideCatalog(admitted, executorCatalog)
|
|
109
|
+
const current = currentState(agent, options.sourceKind)
|
|
110
|
+
const available = new Set(candidates.map(schema => schema.name))
|
|
111
|
+
const removed = options.announceRemovals
|
|
112
|
+
? [...current.disclosed.keys()].filter(name => !available.has(name) && !executorCatalog.has(name))
|
|
113
|
+
: []
|
|
114
|
+
const batches = planDisclosure(candidates, removed, current, options.limits)
|
|
115
|
+
if (batches.length === 0) {
|
|
116
|
+
// A pruned history still needs its records re-linked for later comparisons.
|
|
117
|
+
const folded = foldDisclosed(agent.session.deriveMessages(), options.sourceKind)
|
|
118
|
+
if (folded.disclosed.size !== current.disclosed.size) storeState(agent, folded)
|
|
119
|
+
return []
|
|
120
|
+
}
|
|
121
|
+
const messages = batches.map(batch => createUserMessage({
|
|
122
|
+
content: [{ type: 'text', text: renderDisclosure(batch) }],
|
|
123
|
+
source: { kind: options.sourceKind, form: 'catalog' },
|
|
124
|
+
}))
|
|
125
|
+
storeState(agent, applyDisclosure(current, batches))
|
|
126
|
+
ctx.logger.debug('dsh-dynamic-tools: disclosed %d batch(es) at step start', batches.length)
|
|
127
|
+
return messages
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Register the pre-step listener that appends disclosures.
|
|
132
|
+
* @param ctx - plugin context owning the listener.
|
|
133
|
+
* @param options - disclosure settings.
|
|
134
|
+
*/
|
|
135
|
+
export function registerDisclosure(ctx: Context, options: DiscloseOptions): void {
|
|
136
|
+
ctx.on('agent/pre-step', async ({ agent, signal }, next): Promise<PreStepDecision> => {
|
|
137
|
+
const decision = await next()
|
|
138
|
+
if (decision.kind === 'reject' || signal.aborted) return decision
|
|
139
|
+
try {
|
|
140
|
+
// The executor recorded this step's admission when assembly described the head.
|
|
141
|
+
const admitted = options.admitted(agent)
|
|
142
|
+
if (admitted === undefined) return decision
|
|
143
|
+
const messages = disclosureMessages(ctx, agent, admitted, options.catalogNames(agent), options)
|
|
144
|
+
if (messages.length === 0) return decision
|
|
145
|
+
return { ...decision, messages: [...decision.messages, ...messages] }
|
|
146
|
+
} catch (error: unknown) {
|
|
147
|
+
ctx.logger.warn('dsh-dynamic-tools: failed to disclose tool definitions at step start: %o', error)
|
|
148
|
+
return decision
|
|
149
|
+
}
|
|
150
|
+
})
|
|
151
|
+
}
|
package/src/disclosure.ts
CHANGED
|
@@ -1,147 +1,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
|
-
|
|
48
|
-
/** The empty state of a session that has disclosed nothing yet. */
|
|
49
|
-
export const EMPTY_DISCLOSED: DisclosedState = { disclosed: new Map(), loaded: new Set() }
|
|
50
|
-
|
|
51
|
-
/**
|
|
52
|
-
* Plan the disclosures one step needs.
|
|
53
|
-
*
|
|
54
|
-
* Adds a tool when it is newly admitted or its definition changed since a full
|
|
55
|
-
* delivery. A name announced without a schema stays announced: `tool_load`
|
|
56
|
-
* always serves the current definition, so re-announcing it would only add noise.
|
|
57
|
-
*
|
|
58
|
-
* @param admitted - dynamic definitions admitted for this step.
|
|
59
|
-
* @param removed - names previously disclosed that are no longer admitted.
|
|
60
|
-
* @param state - previously delivered state.
|
|
61
|
-
* @param limits - validated disclosure limits.
|
|
62
|
-
* @returns ordered batches, empty when the model already knows everything.
|
|
63
|
-
*/
|
|
64
|
-
export function planDisclosure(
|
|
65
|
-
admitted: readonly ToolSchemaLike[],
|
|
66
|
-
removed: readonly string[],
|
|
67
|
-
state: DisclosedState,
|
|
68
|
-
limits: DisclosureLimits,
|
|
69
|
-
): DisclosureBatch[] {
|
|
70
|
-
const attached: ToolSchemaLike[] = []
|
|
71
|
-
const namesOnly: string[] = []
|
|
72
|
-
for (const schema of admitted) {
|
|
73
|
-
const entry = state.disclosed.get(schema.name)
|
|
74
|
-
if (entry !== undefined) {
|
|
75
|
-
if (!entry.schema) continue
|
|
76
|
-
if (entry.signature === toolSignature(schema)) continue
|
|
77
|
-
}
|
|
78
|
-
if (limits.mode === 'schema' && schemaBytes(schema) <= limits.maxSchemaBytes) attached.push(schema)
|
|
79
|
-
else namesOnly.push(schema.name)
|
|
80
|
-
}
|
|
81
|
-
|
|
82
|
-
const batches: DisclosureBatch[] = []
|
|
83
|
-
let pendingAdded: ToolSchemaLike[] = []
|
|
84
|
-
let pendingNames: string[] = []
|
|
85
|
-
let pendingRemoved: string[] = []
|
|
86
|
-
let usedBytes = 0
|
|
87
|
-
let pendingCount = 0
|
|
88
|
-
|
|
89
|
-
const flush = (): void => {
|
|
90
|
-
if (pendingCount === 0) return
|
|
91
|
-
batches.push({ added: pendingAdded, names: pendingNames, removed: pendingRemoved })
|
|
92
|
-
pendingAdded = []
|
|
93
|
-
pendingNames = []
|
|
94
|
-
pendingRemoved = []
|
|
95
|
-
usedBytes = 0
|
|
96
|
-
pendingCount = 0
|
|
97
|
-
}
|
|
98
|
-
|
|
99
|
-
const reserve = (bytes: number): void => {
|
|
100
|
-
if (pendingCount > 0 && (pendingCount >= limits.maxToolsPerMessage || usedBytes + bytes > limits.maxMessageBytes)) flush()
|
|
101
|
-
usedBytes += bytes
|
|
102
|
-
pendingCount += 1
|
|
103
|
-
}
|
|
104
|
-
|
|
105
|
-
for (const schema of attached) {
|
|
106
|
-
reserve(limits.mode === 'schema' ? schemaBytes(schema) : schema.name.length)
|
|
107
|
-
pendingAdded.push(schema)
|
|
108
|
-
}
|
|
109
|
-
for (const name of namesOnly) {
|
|
110
|
-
reserve(name.length)
|
|
111
|
-
pendingNames.push(name)
|
|
112
|
-
}
|
|
113
|
-
for (const name of removed) {
|
|
114
|
-
reserve(name.length)
|
|
115
|
-
pendingRemoved.push(name)
|
|
116
|
-
}
|
|
117
|
-
flush()
|
|
118
|
-
return batches
|
|
119
|
-
}
|
|
120
|
-
|
|
121
|
-
/**
|
|
122
|
-
* Fold delivered batches into the delivered state.
|
|
123
|
-
* @param previous - state before these batches.
|
|
124
|
-
* @param batches - batches that were delivered.
|
|
125
|
-
* @returns the updated state.
|
|
126
|
-
*/
|
|
127
|
-
export function applyDisclosure(
|
|
128
|
-
previous: DisclosedState,
|
|
129
|
-
batches: readonly DisclosureBatch[],
|
|
130
|
-
): DisclosedState {
|
|
131
|
-
const disclosed = new Map(previous.disclosed)
|
|
132
|
-
const loaded = new Set(previous.loaded)
|
|
133
|
-
for (const batch of batches) {
|
|
134
|
-
for (const schema of batch.added) {
|
|
135
|
-
disclosed.set(schema.name, { signature: toolSignature(schema), schema: true })
|
|
136
|
-
loaded.add(schema.name)
|
|
137
|
-
}
|
|
138
|
-
for (const name of batch.names) {
|
|
139
|
-
disclosed.set(name, { signature: null, schema: false })
|
|
140
|
-
}
|
|
141
|
-
for (const name of batch.removed) {
|
|
142
|
-
disclosed.delete(name)
|
|
143
|
-
loaded.delete(name)
|
|
144
|
-
}
|
|
145
|
-
}
|
|
146
|
-
return { disclosed, loaded }
|
|
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
|
+
|
|
48
|
+
/** The empty state of a session that has disclosed nothing yet. */
|
|
49
|
+
export const EMPTY_DISCLOSED: DisclosedState = { disclosed: new Map(), loaded: new Set() }
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Plan the disclosures one step needs.
|
|
53
|
+
*
|
|
54
|
+
* Adds a tool when it is newly admitted or its definition changed since a full
|
|
55
|
+
* delivery. A name announced without a schema stays announced: `tool_load`
|
|
56
|
+
* always serves the current definition, so re-announcing it would only add noise.
|
|
57
|
+
*
|
|
58
|
+
* @param admitted - dynamic definitions admitted for this step.
|
|
59
|
+
* @param removed - names previously disclosed that are no longer admitted.
|
|
60
|
+
* @param state - previously delivered state.
|
|
61
|
+
* @param limits - validated disclosure limits.
|
|
62
|
+
* @returns ordered batches, empty when the model already knows everything.
|
|
63
|
+
*/
|
|
64
|
+
export function planDisclosure(
|
|
65
|
+
admitted: readonly ToolSchemaLike[],
|
|
66
|
+
removed: readonly string[],
|
|
67
|
+
state: DisclosedState,
|
|
68
|
+
limits: DisclosureLimits,
|
|
69
|
+
): DisclosureBatch[] {
|
|
70
|
+
const attached: ToolSchemaLike[] = []
|
|
71
|
+
const namesOnly: string[] = []
|
|
72
|
+
for (const schema of admitted) {
|
|
73
|
+
const entry = state.disclosed.get(schema.name)
|
|
74
|
+
if (entry !== undefined) {
|
|
75
|
+
if (!entry.schema) continue
|
|
76
|
+
if (entry.signature === toolSignature(schema)) continue
|
|
77
|
+
}
|
|
78
|
+
if (limits.mode === 'schema' && schemaBytes(schema) <= limits.maxSchemaBytes) attached.push(schema)
|
|
79
|
+
else namesOnly.push(schema.name)
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
const batches: DisclosureBatch[] = []
|
|
83
|
+
let pendingAdded: ToolSchemaLike[] = []
|
|
84
|
+
let pendingNames: string[] = []
|
|
85
|
+
let pendingRemoved: string[] = []
|
|
86
|
+
let usedBytes = 0
|
|
87
|
+
let pendingCount = 0
|
|
88
|
+
|
|
89
|
+
const flush = (): void => {
|
|
90
|
+
if (pendingCount === 0) return
|
|
91
|
+
batches.push({ added: pendingAdded, names: pendingNames, removed: pendingRemoved })
|
|
92
|
+
pendingAdded = []
|
|
93
|
+
pendingNames = []
|
|
94
|
+
pendingRemoved = []
|
|
95
|
+
usedBytes = 0
|
|
96
|
+
pendingCount = 0
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
const reserve = (bytes: number): void => {
|
|
100
|
+
if (pendingCount > 0 && (pendingCount >= limits.maxToolsPerMessage || usedBytes + bytes > limits.maxMessageBytes)) flush()
|
|
101
|
+
usedBytes += bytes
|
|
102
|
+
pendingCount += 1
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
for (const schema of attached) {
|
|
106
|
+
reserve(limits.mode === 'schema' ? schemaBytes(schema) : schema.name.length)
|
|
107
|
+
pendingAdded.push(schema)
|
|
108
|
+
}
|
|
109
|
+
for (const name of namesOnly) {
|
|
110
|
+
reserve(name.length)
|
|
111
|
+
pendingNames.push(name)
|
|
112
|
+
}
|
|
113
|
+
for (const name of removed) {
|
|
114
|
+
reserve(name.length)
|
|
115
|
+
pendingRemoved.push(name)
|
|
116
|
+
}
|
|
117
|
+
flush()
|
|
118
|
+
return batches
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* Fold delivered batches into the delivered state.
|
|
123
|
+
* @param previous - state before these batches.
|
|
124
|
+
* @param batches - batches that were delivered.
|
|
125
|
+
* @returns the updated state.
|
|
126
|
+
*/
|
|
127
|
+
export function applyDisclosure(
|
|
128
|
+
previous: DisclosedState,
|
|
129
|
+
batches: readonly DisclosureBatch[],
|
|
130
|
+
): DisclosedState {
|
|
131
|
+
const disclosed = new Map(previous.disclosed)
|
|
132
|
+
const loaded = new Set(previous.loaded)
|
|
133
|
+
for (const batch of batches) {
|
|
134
|
+
for (const schema of batch.added) {
|
|
135
|
+
disclosed.set(schema.name, { signature: toolSignature(schema), schema: true })
|
|
136
|
+
loaded.add(schema.name)
|
|
137
|
+
}
|
|
138
|
+
for (const name of batch.names) {
|
|
139
|
+
disclosed.set(name, { signature: null, schema: false })
|
|
140
|
+
}
|
|
141
|
+
for (const name of batch.removed) {
|
|
142
|
+
disclosed.delete(name)
|
|
143
|
+
loaded.delete(name)
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
return { disclosed, loaded }
|
|
147
|
+
}
|