@dsh-plugin/dsh-dynamic-tools 0.1.0-dev.43450988228 → 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/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
- const value: unknown = JSON.parse(json)
53
- if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
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
- * Damaged blocks are ignored: an unreadable disclosure only costs one
67
- * re-announcement, never a wrong refusal.
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 definitions = new Map<string, ToolSchemaLike>()
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 !== undefined) definitions.set(schema.name, 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 = definitions.get(name)
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 definitions.values()) {
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: config.dynamic.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
- catalogNames: agent => executors.get(agent)?.declaredNames() ?? new Set(),
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('Call tool_load with the names under tools_load_required before calling those tools.')
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
- return `<system-reminder>\n<tool_definition name="${schema.name}">\n${escapeReminderText(JSON.stringify(schema))}\n</tool_definition>\nThese tools are callable directly by name even though they are not in your tool list; match the definitions above.\n</system-reminder>`
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
  /**
@@ -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 model was told about but
3
- * whose schema it cannot see in the declaration head.
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 { DisclosureLimits } from './disclosure.ts'
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 limits.
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; call the tool in a later step.',
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
- const state = currentState(agent, options.sourceKind)
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
- if (!state.disclosed.has(name)) alreadyAvailable.push(name)
92
- else loaded.push(name)
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, { disclosed: state.disclosed, loaded: nextLoaded })
121
+ storeState(agent, state)
100
122
  return { loaded, alreadyAvailable, unavailable, tooLarge }
101
123
  },
102
124
  isConcurrencySafe: () => false,
103
125
  })
104
126
  }
105
-