@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/src/index.ts CHANGED
@@ -1,178 +1,178 @@
1
- /**
2
- * Freeze the tool declaration head and disclose later tools at the conversation
3
- * tail.
4
- *
5
- * A model request whose tool list changes forces the agent loop to resend the
6
- * complete system prompt and declarations, which discards the provider's cached
7
- * prefix. This plugin keeps the head constant: the first step's declaration set
8
- * is captured, later admissions are delivered as recorded user messages, and a
9
- * call to a tool the step does not admit fails through an executable denial
10
- * instead of running.
11
- *
12
- * @module dsh-dynamic-tools
13
- */
14
-
15
- import z from '@deepseek-ai/schemastery'
16
- import type { Context } from '@deepseek-ai/cordis'
17
- import type { Agent } from '@deepseek-ai/dsh-agent'
18
- import type { ClassificationRules } from './catalog.ts'
19
- import { registerDisclosure, type DiscloseOptions } from './disclose.ts'
20
- import type { StableCatalogExecutor } from './executor.ts'
21
- import { installAgent, type InstallOptions } from './install.ts'
22
- import { SOURCE_KIND } from './source.ts'
23
- import { createToolLoad, TOOL_LOAD_NAME } from './tool-load.ts'
24
-
25
- /** Cordis plugin name. */
26
- export const name = '@dsh-plugin/dsh-dynamic-tools'
27
-
28
- /** Services the plugin registers into. */
29
- export const inject = ['tools', 'systemPrompt']
30
-
31
- /** Tool-selection and disclosure settings. */
32
- export interface Config {
33
- /** Install for agents that already exist when this plugin loads. */
34
- installExistingAgents: boolean
35
- /** Preset ids left untouched, so their own executor keeps the declaration path. */
36
- skipPresets: string[]
37
- dynamic: {
38
- /** Exact tool names disclosed at the conversation tail. */
39
- names: string[]
40
- /** Tool-name prefixes disclosed at the conversation tail. */
41
- prefixes: string[]
42
- /** Exact names forced into the frozen head. */
43
- inlineNames: string[]
44
- }
45
- disclosure: {
46
- /** Attach definitions to the disclosure, or announce names for `tool_load`. */
47
- mode: 'schema' | 'names'
48
- /** Require `tool_load` before a dynamic tool may run. */
49
- requireLoad: boolean
50
- /** Maximum tools announced in one message. */
51
- maxToolsPerMessage: number
52
- /** Maximum bytes of one attached definition. */
53
- maxSchemaBytes: number
54
- /** Maximum bytes of one disclosure message. */
55
- maxMessageBytes: number
56
- /** Announce tools that stop being available. */
57
- announceRemovals: boolean
58
- }
59
- /** Model-facing reason reported when a declared tool is not admitted. */
60
- unavailableReasons: Record<string, string>
61
- /** Concurrency used when the loop supplies no limit. */
62
- maxParallelCalls: number
63
- }
64
-
65
- /** Schemastery validation; invalid values fail at load. */
66
- export const Config: z<Config> = z.object({
67
- installExistingAgents: z.boolean().default(true)
68
- .description('Install for agents that already exist when this plugin loads.'),
69
- skipPresets: z.array(z.string()).default(['ptc'])
70
- .description('Preset ids whose own tool executor keeps the declaration path.'),
71
- dynamic: z.object({
72
- names: z.array(z.string()).default(['exit_plan_mode'])
73
- .description('Exact tool names disclosed at the conversation tail.'),
74
- prefixes: z.array(z.string()).default([])
75
- .description('Tool-name prefixes disclosed at the conversation tail.'),
76
- inlineNames: z.array(z.string()).default([])
77
- .description('Exact names forced into the frozen head.'),
78
- }).default({}),
79
- disclosure: z.object({
80
- mode: z.union(['schema', 'names']).default('schema')
81
- .description('Attach definitions to the disclosure, or announce names for tool_load.'),
82
- requireLoad: z.boolean().default(false)
83
- .description('Require tool_load before a dynamic tool may run.'),
84
- maxToolsPerMessage: z.number().min(1).default(8)
85
- .description('Maximum tools announced in one message.'),
86
- maxSchemaBytes: z.number().min(1).default(6000)
87
- .description('Maximum bytes of one attached definition.'),
88
- maxMessageBytes: z.number().min(1).default(20000)
89
- .description('Maximum bytes of one disclosure message.'),
90
- announceRemovals: z.boolean().default(true)
91
- .description('Announce tools that stop being available.'),
92
- }).default({}),
93
- unavailableReasons: z.dict(z.string()).default({
94
- exit_plan_mode: 'Plan mode is not active in this session. Ask the user to switch to plan mode, then call it again.',
95
- }).description('Model-facing reason reported when a declared tool is not admitted.'),
96
- maxParallelCalls: z.number().min(1).default(10)
97
- .description('Concurrency used when the loop supplies no limit.'),
98
- })
99
-
100
- /**
101
- * Compose validated settings into the two halves the plugin registers.
102
- * @param config - validated plugin configuration.
103
- * @returns classification, execution, and disclosure settings.
104
- */
105
- function resolveSettings(config: Config): {
106
- rules: ClassificationRules
107
- install: Omit<InstallOptions, 'executors' | 'reported'>
108
- disclose: Omit<DiscloseOptions, 'catalogNames' | 'admitted'>
109
- } {
110
- const rules: ClassificationRules = {
111
- dynamicNames: config.dynamic.names,
112
- dynamicPrefixes: config.dynamic.prefixes,
113
- inlineNames: config.dynamic.inlineNames,
114
- }
115
- return {
116
- rules,
117
- install: {
118
- sourceKind: SOURCE_KIND,
119
- rules,
120
- executor: {
121
- requireLoad: config.disclosure.requireLoad,
122
- unavailableReasons: config.unavailableReasons,
123
- maxParallelCalls: config.maxParallelCalls,
124
- },
125
- skipPresets: config.skipPresets,
126
- },
127
- disclose: {
128
- sourceKind: SOURCE_KIND,
129
- limits: {
130
- mode: config.disclosure.mode,
131
- maxToolsPerMessage: config.disclosure.maxToolsPerMessage,
132
- maxSchemaBytes: config.disclosure.maxSchemaBytes,
133
- maxMessageBytes: config.disclosure.maxMessageBytes,
134
- },
135
- announceRemovals: config.disclosure.announceRemovals,
136
- },
137
- }
138
- }
139
-
140
- /**
141
- * Register the load tool, the frozen catalog per agent, and tail disclosure.
142
- * @param ctx - plugin context owning every registration.
143
- * @param config - validated plugin configuration.
144
- */
145
- export function apply(ctx: Context, config: Config): void {
146
- const settings = resolveSettings(config)
147
- const executors = new WeakMap<Agent, StableCatalogExecutor>()
148
- const release = new WeakMap<Agent, () => void>()
149
- const reported = new WeakSet<Agent>()
150
- const installOptions: InstallOptions = { ...settings.install, executors, reported }
151
-
152
- ctx.effect(() => ctx.tools.register(createToolLoad(ctx, {
153
- sourceKind: SOURCE_KIND,
154
- limits: settings.disclose.limits,
155
- })), `dsh-dynamic-tools: register ${TOOL_LOAD_NAME}`)
156
-
157
- ctx.on('agent/created', ({ agent }) => {
158
- installAgent(ctx, agent, installOptions, release)
159
- return undefined
160
- })
161
-
162
- // An agent's executor belongs to that agent: release it with the agent instead
163
- // of retaining every closed session's executor until this plugin unloads.
164
- ctx.on('agent/disposed', ({ agent }) => {
165
- release.get(agent)?.()
166
- })
167
-
168
- if (config.installExistingAgents) {
169
- const agents = ctx.get('agents')
170
- for (const agent of agents?.list() ?? []) installAgent(ctx, agent, installOptions, release)
171
- }
172
-
173
- registerDisclosure(ctx, {
174
- ...settings.disclose,
175
- catalogNames: agent => executors.get(agent)?.declaredNames() ?? new Set(),
176
- admitted: agent => executors.get(agent)?.admittedDefinitions(),
177
- })
178
- }
1
+ /**
2
+ * Freeze the tool declaration head and disclose later tools at the conversation
3
+ * tail.
4
+ *
5
+ * A model request whose tool list changes forces the agent loop to resend the
6
+ * complete system prompt and declarations, which discards the provider's cached
7
+ * prefix. This plugin keeps the head constant: the first step's declaration set
8
+ * is captured, later admissions are delivered as recorded user messages, and a
9
+ * call to a tool the step does not admit fails through an executable denial
10
+ * instead of running.
11
+ *
12
+ * @module dsh-dynamic-tools
13
+ */
14
+
15
+ import z from '@deepseek-ai/schemastery'
16
+ import type { Context } from '@deepseek-ai/cordis'
17
+ import type { Agent } from '@deepseek-ai/dsh-agent'
18
+ import type { ClassificationRules } from './catalog.ts'
19
+ import { registerDisclosure, type DiscloseOptions } from './disclose.ts'
20
+ import type { StableCatalogExecutor } from './executor.ts'
21
+ import { installAgent, type InstallOptions } from './install.ts'
22
+ import { SOURCE_KIND } from './source.ts'
23
+ import { createToolLoad, TOOL_LOAD_NAME } from './tool-load.ts'
24
+
25
+ /** Cordis plugin name. */
26
+ export const name = '@dsh-plugin/dsh-dynamic-tools'
27
+
28
+ /** Services the plugin registers into. */
29
+ export const inject = ['tools', 'systemPrompt']
30
+
31
+ /** Tool-selection and disclosure settings. */
32
+ export interface Config {
33
+ /** Install for agents that already exist when this plugin loads. */
34
+ installExistingAgents: boolean
35
+ /** Preset ids left untouched, so their own executor keeps the declaration path. */
36
+ skipPresets: string[]
37
+ dynamic: {
38
+ /** Exact tool names disclosed at the conversation tail. */
39
+ names: string[]
40
+ /** Tool-name prefixes disclosed at the conversation tail. */
41
+ prefixes: string[]
42
+ /** Exact names forced into the frozen head. */
43
+ inlineNames: string[]
44
+ }
45
+ disclosure: {
46
+ /** Attach definitions to the disclosure, or announce names for `tool_load`. */
47
+ mode: 'schema' | 'names'
48
+ /** Require `tool_load` before a dynamic tool may run. */
49
+ requireLoad: boolean
50
+ /** Maximum tools announced in one message. */
51
+ maxToolsPerMessage: number
52
+ /** Maximum bytes of one attached definition. */
53
+ maxSchemaBytes: number
54
+ /** Maximum bytes of one disclosure message. */
55
+ maxMessageBytes: number
56
+ /** Announce tools that stop being available. */
57
+ announceRemovals: boolean
58
+ }
59
+ /** Model-facing reason reported when a declared tool is not admitted. */
60
+ unavailableReasons: Record<string, string>
61
+ /** Concurrency used when the loop supplies no limit. */
62
+ maxParallelCalls: number
63
+ }
64
+
65
+ /** Schemastery validation; invalid values fail at load. */
66
+ export const Config: z<Config> = z.object({
67
+ installExistingAgents: z.boolean().default(true)
68
+ .description('Install for agents that already exist when this plugin loads.'),
69
+ skipPresets: z.array(z.string()).default(['ptc'])
70
+ .description('Preset ids whose own tool executor keeps the declaration path.'),
71
+ dynamic: z.object({
72
+ names: z.array(z.string()).default(['exit_plan_mode'])
73
+ .description('Exact tool names disclosed at the conversation tail.'),
74
+ prefixes: z.array(z.string()).default([])
75
+ .description('Tool-name prefixes disclosed at the conversation tail.'),
76
+ inlineNames: z.array(z.string()).default([])
77
+ .description('Exact names forced into the frozen head.'),
78
+ }).default({}),
79
+ disclosure: z.object({
80
+ mode: z.union(['schema', 'names']).default('schema')
81
+ .description('Attach definitions to the disclosure, or announce names for tool_load.'),
82
+ requireLoad: z.boolean().default(false)
83
+ .description('Require tool_load before a dynamic tool may run.'),
84
+ maxToolsPerMessage: z.number().min(1).default(8)
85
+ .description('Maximum tools announced in one message.'),
86
+ maxSchemaBytes: z.number().min(1).default(6000)
87
+ .description('Maximum bytes of one attached definition.'),
88
+ maxMessageBytes: z.number().min(1).default(20000)
89
+ .description('Maximum bytes of one disclosure message.'),
90
+ announceRemovals: z.boolean().default(true)
91
+ .description('Announce tools that stop being available.'),
92
+ }).default({}),
93
+ unavailableReasons: z.dict(z.string()).default({
94
+ exit_plan_mode: 'Plan mode is not active in this session. Ask the user to switch to plan mode, then call it again.',
95
+ }).description('Model-facing reason reported when a declared tool is not admitted.'),
96
+ maxParallelCalls: z.number().min(1).default(10)
97
+ .description('Concurrency used when the loop supplies no limit.'),
98
+ })
99
+
100
+ /**
101
+ * Compose validated settings into the two halves the plugin registers.
102
+ * @param config - validated plugin configuration.
103
+ * @returns classification, execution, and disclosure settings.
104
+ */
105
+ function resolveSettings(config: Config): {
106
+ rules: ClassificationRules
107
+ install: Omit<InstallOptions, 'executors' | 'reported'>
108
+ disclose: Omit<DiscloseOptions, 'catalogNames' | 'admitted'>
109
+ } {
110
+ const rules: ClassificationRules = {
111
+ dynamicNames: config.dynamic.names,
112
+ dynamicPrefixes: config.dynamic.prefixes,
113
+ inlineNames: config.dynamic.inlineNames,
114
+ }
115
+ return {
116
+ rules,
117
+ install: {
118
+ sourceKind: SOURCE_KIND,
119
+ rules,
120
+ executor: {
121
+ requireLoad: config.disclosure.requireLoad,
122
+ unavailableReasons: config.unavailableReasons,
123
+ maxParallelCalls: config.maxParallelCalls,
124
+ },
125
+ skipPresets: config.skipPresets,
126
+ },
127
+ disclose: {
128
+ sourceKind: SOURCE_KIND,
129
+ limits: {
130
+ mode: config.disclosure.mode,
131
+ maxToolsPerMessage: config.disclosure.maxToolsPerMessage,
132
+ maxSchemaBytes: config.disclosure.maxSchemaBytes,
133
+ maxMessageBytes: config.disclosure.maxMessageBytes,
134
+ },
135
+ announceRemovals: config.disclosure.announceRemovals,
136
+ },
137
+ }
138
+ }
139
+
140
+ /**
141
+ * Register the load tool, the frozen catalog per agent, and tail disclosure.
142
+ * @param ctx - plugin context owning every registration.
143
+ * @param config - validated plugin configuration.
144
+ */
145
+ export function apply(ctx: Context, config: Config): void {
146
+ const settings = resolveSettings(config)
147
+ const executors = new WeakMap<Agent, StableCatalogExecutor>()
148
+ const release = new WeakMap<Agent, () => void>()
149
+ const reported = new WeakSet<Agent>()
150
+ const installOptions: InstallOptions = { ...settings.install, executors, reported }
151
+
152
+ ctx.effect(() => ctx.tools.register(createToolLoad(ctx, {
153
+ sourceKind: SOURCE_KIND,
154
+ limits: settings.disclose.limits,
155
+ })), `dsh-dynamic-tools: register ${TOOL_LOAD_NAME}`)
156
+
157
+ ctx.on('agent/created', ({ agent }) => {
158
+ installAgent(ctx, agent, installOptions, release)
159
+ return undefined
160
+ })
161
+
162
+ // An agent's executor belongs to that agent: release it with the agent instead
163
+ // of retaining every closed session's executor until this plugin unloads.
164
+ ctx.on('agent/disposed', ({ agent }) => {
165
+ release.get(agent)?.()
166
+ })
167
+
168
+ if (config.installExistingAgents) {
169
+ const agents = ctx.get('agents')
170
+ for (const agent of agents?.list() ?? []) installAgent(ctx, agent, installOptions, release)
171
+ }
172
+
173
+ registerDisclosure(ctx, {
174
+ ...settings.disclose,
175
+ catalogNames: agent => executors.get(agent)?.declaredNames() ?? new Set(),
176
+ admitted: agent => executors.get(agent)?.admittedDefinitions(),
177
+ })
178
+ }
package/src/install.ts CHANGED
@@ -1,91 +1,91 @@
1
- /**
2
- * Per-Agent installation of the frozen-catalog executor.
3
- *
4
- * Every installation is one plugin-owned effect, so unload releases exactly the
5
- * registrations this plugin made, and an agent's disposal releases its executor
6
- * immediately instead of retaining it until the plugin unloads. A scope that
7
- * already selected another executor keeps it: this plugin then stays out of the
8
- * declaration path instead of replacing that selection.
9
- *
10
- * @module dsh-dynamic-tools/install
11
- */
12
-
13
- import type { Context } from '@deepseek-ai/cordis'
14
- import type { Agent } from '@deepseek-ai/dsh-agent'
15
- import type { ClassificationRules } from './catalog.ts'
16
- import { StableCatalogExecutor, type ExecutorOptions } from './executor.ts'
17
- import { currentState } from './disclose.ts'
18
- import type { SourceKind } from './source.ts'
19
-
20
- /** Settings shared by every installed agent. */
21
- export interface InstallOptions {
22
- /** Message source kind owned by this plugin. */
23
- readonly sourceKind: SourceKind
24
- /** Classification rules for the frozen head. */
25
- readonly rules: ClassificationRules
26
- /** Execution settings. */
27
- readonly executor: ExecutorOptions
28
- /** Preset ids this plugin leaves alone. */
29
- readonly skipPresets: readonly string[]
30
- /** Executors by agent, shared with the disclosure listener. */
31
- readonly executors: WeakMap<Agent, StableCatalogExecutor>
32
- /** Agents already reported, so each diagnostic appears once. */
33
- readonly reported: WeakSet<Agent>
34
- }
35
-
36
- /** Read the preset id an agent runs under, when a registry is composed. */
37
- function presetOf(ctx: Context, agent: Agent): string | undefined {
38
- const registry = ctx.get('agentPresets')
39
- if (registry === undefined) return undefined
40
- return registry.presetForSession(agent.session) ?? undefined
41
- }
42
-
43
- /**
44
- * Install the frozen-catalog executor for one agent.
45
- * @param ctx - plugin context that owns the registration.
46
- * @param agent - agent whose scope receives the executor.
47
- * @param options - installation settings.
48
- * @param release - disposer registry, so agent disposal can release the executor.
49
- */
50
- export function installAgent(
51
- ctx: Context,
52
- agent: Agent,
53
- options: InstallOptions,
54
- release: WeakMap<Agent, () => void>,
55
- ): void {
56
- if (options.executors.has(agent)) return
57
- const preset = presetOf(ctx, agent)
58
- if (preset !== undefined && options.skipPresets.includes(preset)) {
59
- if (!options.reported.has(agent)) {
60
- options.reported.add(agent)
61
- ctx.logger.info('dsh-dynamic-tools: leaving preset "%s" alone; tool declarations stay as composed', preset)
62
- }
63
- return
64
- }
65
- const holder = {
66
- disclosed: () => currentState(agent, options.sourceKind).disclosed,
67
- loaded: () => currentState(agent, options.sourceKind).loaded,
68
- }
69
- const executor = new StableCatalogExecutor(ctx, agent, options.rules, options.executor, holder)
70
- try {
71
- const dispose = ctx.effect(() => {
72
- const uninstall = agent.ctx.tools.setExecutor(executor)
73
- options.executors.set(agent, executor)
74
- return () => {
75
- options.executors.delete(agent)
76
- uninstall()
77
- }
78
- }, 'dsh-dynamic-tools: install frozen-catalog executor')
79
- let released = false
80
- release.set(agent, () => {
81
- if (released) return
82
- released = true
83
- release.delete(agent)
84
- dispose()
85
- })
86
- } catch (error: unknown) {
87
- if (options.reported.has(agent)) return
88
- options.reported.add(agent)
89
- ctx.logger.warn('dsh-dynamic-tools: cannot install for agent "%s": %o', agent.id, error)
90
- }
91
- }
1
+ /**
2
+ * Per-Agent installation of the frozen-catalog executor.
3
+ *
4
+ * Every installation is one plugin-owned effect, so unload releases exactly the
5
+ * registrations this plugin made, and an agent's disposal releases its executor
6
+ * immediately instead of retaining it until the plugin unloads. A scope that
7
+ * already selected another executor keeps it: this plugin then stays out of the
8
+ * declaration path instead of replacing that selection.
9
+ *
10
+ * @module dsh-dynamic-tools/install
11
+ */
12
+
13
+ import type { Context } from '@deepseek-ai/cordis'
14
+ import type { Agent } from '@deepseek-ai/dsh-agent'
15
+ import type { ClassificationRules } from './catalog.ts'
16
+ import { StableCatalogExecutor, type ExecutorOptions } from './executor.ts'
17
+ import { currentState } from './disclose.ts'
18
+ import type { SourceKind } from './source.ts'
19
+
20
+ /** Settings shared by every installed agent. */
21
+ export interface InstallOptions {
22
+ /** Message source kind owned by this plugin. */
23
+ readonly sourceKind: SourceKind
24
+ /** Classification rules for the frozen head. */
25
+ readonly rules: ClassificationRules
26
+ /** Execution settings. */
27
+ readonly executor: ExecutorOptions
28
+ /** Preset ids this plugin leaves alone. */
29
+ readonly skipPresets: readonly string[]
30
+ /** Executors by agent, shared with the disclosure listener. */
31
+ readonly executors: WeakMap<Agent, StableCatalogExecutor>
32
+ /** Agents already reported, so each diagnostic appears once. */
33
+ readonly reported: WeakSet<Agent>
34
+ }
35
+
36
+ /** Read the preset id an agent runs under, when a registry is composed. */
37
+ function presetOf(ctx: Context, agent: Agent): string | undefined {
38
+ const registry = ctx.get('agentPresets')
39
+ if (registry === undefined) return undefined
40
+ return registry.presetForSession(agent.session) ?? undefined
41
+ }
42
+
43
+ /**
44
+ * Install the frozen-catalog executor for one agent.
45
+ * @param ctx - plugin context that owns the registration.
46
+ * @param agent - agent whose scope receives the executor.
47
+ * @param options - installation settings.
48
+ * @param release - disposer registry, so agent disposal can release the executor.
49
+ */
50
+ export function installAgent(
51
+ ctx: Context,
52
+ agent: Agent,
53
+ options: InstallOptions,
54
+ release: WeakMap<Agent, () => void>,
55
+ ): void {
56
+ if (options.executors.has(agent)) return
57
+ const preset = presetOf(ctx, agent)
58
+ if (preset !== undefined && options.skipPresets.includes(preset)) {
59
+ if (!options.reported.has(agent)) {
60
+ options.reported.add(agent)
61
+ ctx.logger.info('dsh-dynamic-tools: leaving preset "%s" alone; tool declarations stay as composed', preset)
62
+ }
63
+ return
64
+ }
65
+ const holder = {
66
+ disclosed: () => currentState(agent, options.sourceKind).disclosed,
67
+ loaded: () => currentState(agent, options.sourceKind).loaded,
68
+ }
69
+ const executor = new StableCatalogExecutor(ctx, agent, options.rules, options.executor, holder)
70
+ try {
71
+ const dispose = ctx.effect(() => {
72
+ const uninstall = agent.ctx.tools.setExecutor(executor)
73
+ options.executors.set(agent, executor)
74
+ return () => {
75
+ options.executors.delete(agent)
76
+ uninstall()
77
+ }
78
+ }, 'dsh-dynamic-tools: install frozen-catalog executor')
79
+ let released = false
80
+ release.set(agent, () => {
81
+ if (released) return
82
+ released = true
83
+ release.delete(agent)
84
+ dispose()
85
+ })
86
+ } catch (error: unknown) {
87
+ if (options.reported.has(agent)) return
88
+ options.reported.add(agent)
89
+ ctx.logger.warn('dsh-dynamic-tools: cannot install for agent "%s": %o', agent.id, error)
90
+ }
91
+ }