@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/docs/preview.svg CHANGED
@@ -1,25 +1,25 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" width="640" height="300" viewBox="0 0 640 300" role="img" aria-label="A frozen tool declaration head beside a conversation that receives a new tool definition as a trailing message">
2
- <rect x="32" y="46" width="248" height="208" rx="14" fill="#176b5b" fill-opacity="0.08" stroke="#176b5b" stroke-width="3"/>
3
- <rect x="64" y="78" width="184" height="18" rx="9" fill="#176b5b" fill-opacity="0.8"/>
4
- <rect x="64" y="112" width="184" height="18" rx="9" fill="#176b5b" fill-opacity="0.55"/>
5
- <rect x="64" y="146" width="184" height="18" rx="9" fill="#176b5b" fill-opacity="0.35"/>
6
- <rect x="196" y="186" width="52" height="40" rx="8" fill="none" stroke="#176b5b" stroke-width="3"/>
7
- <path d="M208 186v-10a14 14 0 0 1 28 0v10" fill="none" stroke="#176b5b" stroke-width="3"/>
8
- <circle cx="222" cy="202" r="4" fill="#176b5b"/>
9
- <path d="M222 206v8" fill="none" stroke="#176b5b" stroke-width="3" stroke-linecap="round"/>
10
-
11
- <path d="M300 150h56" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round"/>
12
- <path d="M348 142l12 8-12 8" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
13
-
14
- <rect x="372" y="46" width="236" height="208" rx="14" fill="#db6b2c" fill-opacity="0.07" stroke="#db6b2c" stroke-width="3"/>
15
- <rect x="396" y="72" width="188" height="66" rx="12" fill="none" stroke="#db6b2c" stroke-width="3"/>
16
- <path d="M396 96h188" fill="none" stroke="#db6b2c" stroke-width="2" stroke-opacity="0.5"/>
17
- <rect x="414" y="84" width="64" height="12" rx="6" fill="#db6b2c" fill-opacity="0.6"/>
18
- <rect x="414" y="108" width="140" height="8" rx="4" fill="#db6b2c" fill-opacity="0.35"/>
19
- <rect x="414" y="122" width="104" height="8" rx="4" fill="#db6b2c" fill-opacity="0.35"/>
20
-
21
- <rect x="396" y="154" width="188" height="76" rx="12" fill="#db6b2c" fill-opacity="0.16" stroke="#db6b2c" stroke-width="3" stroke-dasharray="8 6"/>
22
- <rect x="414" y="168" width="72" height="12" rx="6" fill="#db6b2c" fill-opacity="0.7"/>
23
- <path d="M420 202h52M420 214h96" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round" stroke-opacity="0.6"/>
24
- <path d="M534 196h24M546 184v24" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round"/>
25
- </svg>
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="640" height="300" viewBox="0 0 640 300" role="img" aria-label="A frozen tool declaration head beside a conversation that receives a new tool definition as a trailing message">
2
+ <rect x="32" y="46" width="248" height="208" rx="14" fill="#176b5b" fill-opacity="0.08" stroke="#176b5b" stroke-width="3"/>
3
+ <rect x="64" y="78" width="184" height="18" rx="9" fill="#176b5b" fill-opacity="0.8"/>
4
+ <rect x="64" y="112" width="184" height="18" rx="9" fill="#176b5b" fill-opacity="0.55"/>
5
+ <rect x="64" y="146" width="184" height="18" rx="9" fill="#176b5b" fill-opacity="0.35"/>
6
+ <rect x="196" y="186" width="52" height="40" rx="8" fill="none" stroke="#176b5b" stroke-width="3"/>
7
+ <path d="M208 186v-10a14 14 0 0 1 28 0v10" fill="none" stroke="#176b5b" stroke-width="3"/>
8
+ <circle cx="222" cy="202" r="4" fill="#176b5b"/>
9
+ <path d="M222 206v8" fill="none" stroke="#176b5b" stroke-width="3" stroke-linecap="round"/>
10
+
11
+ <path d="M300 150h56" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round"/>
12
+ <path d="M348 142l12 8-12 8" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
13
+
14
+ <rect x="372" y="46" width="236" height="208" rx="14" fill="#db6b2c" fill-opacity="0.07" stroke="#db6b2c" stroke-width="3"/>
15
+ <rect x="396" y="72" width="188" height="66" rx="12" fill="none" stroke="#db6b2c" stroke-width="3"/>
16
+ <path d="M396 96h188" fill="none" stroke="#db6b2c" stroke-width="2" stroke-opacity="0.5"/>
17
+ <rect x="414" y="84" width="64" height="12" rx="6" fill="#db6b2c" fill-opacity="0.6"/>
18
+ <rect x="414" y="108" width="140" height="8" rx="4" fill="#db6b2c" fill-opacity="0.35"/>
19
+ <rect x="414" y="122" width="104" height="8" rx="4" fill="#db6b2c" fill-opacity="0.35"/>
20
+
21
+ <rect x="396" y="154" width="188" height="76" rx="12" fill="#db6b2c" fill-opacity="0.16" stroke="#db6b2c" stroke-width="3" stroke-dasharray="8 6"/>
22
+ <rect x="414" y="168" width="72" height="12" rx="6" fill="#db6b2c" fill-opacity="0.7"/>
23
+ <path d="M420 202h52M420 214h96" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round" stroke-opacity="0.6"/>
24
+ <path d="M534 196h24M546 184v24" fill="none" stroke="#db6b2c" stroke-width="4" stroke-linecap="round"/>
25
+ </svg>
package/icon.svg CHANGED
@@ -1,7 +1,7 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36" role="img" aria-label="Dynamic tools">
2
- <rect x="7.5" y="6" width="3.5" height="24" rx="1.75" fill="#176b5b"/>
3
- <rect x="13" y="7" width="16" height="5" rx="2.5" fill="#176b5b" fill-opacity="0.85"/>
4
- <rect x="13" y="14" width="16" height="5" rx="2.5" fill="#176b5b" fill-opacity="0.55"/>
5
- <rect x="13" y="21" width="16" height="9" rx="2.5" fill="none" stroke="#db6b2c" stroke-width="2"/>
6
- <path d="M18.5 25.5h5M21 23v5" fill="none" stroke="#db6b2c" stroke-width="2" stroke-linecap="round"/>
7
- </svg>
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36" role="img" aria-label="Dynamic tools">
2
+ <rect x="7.5" y="6" width="3.5" height="24" rx="1.75" fill="#176b5b"/>
3
+ <rect x="13" y="7" width="16" height="5" rx="2.5" fill="#176b5b" fill-opacity="0.85"/>
4
+ <rect x="13" y="14" width="16" height="5" rx="2.5" fill="#176b5b" fill-opacity="0.55"/>
5
+ <rect x="13" y="21" width="16" height="9" rx="2.5" fill="none" stroke="#db6b2c" stroke-width="2"/>
6
+ <path d="M18.5 25.5h5M21 23v5" fill="none" stroke="#db6b2c" stroke-width="2" stroke-linecap="round"/>
7
+ </svg>
package/lib/catalog.d.ts CHANGED
@@ -45,6 +45,17 @@ export declare function splitCatalog(definitions: readonly ToolSchemaLike[], rul
45
45
  inline: ToolSchemaLike[];
46
46
  dynamic: ToolSchemaLike[];
47
47
  };
48
+ /**
49
+ * Append declared definitions to the frozen catalog, keeping both orders.
50
+ *
51
+ * A name the catalog already declares keeps its catalog position and
52
+ * definition: the head must not move because a tool became loadable.
53
+ *
54
+ * @param catalog - frozen declaration head.
55
+ * @param declared - definitions loaded on demand, in load order.
56
+ * @returns the head followed by every declared name it does not declare.
57
+ */
58
+ export declare function extendCatalog(catalog: readonly ToolSchemaLike[], declared: readonly ToolSchemaLike[]): ToolSchemaLike[];
48
59
  /**
49
60
  * JSON size of one definition as it would be disclosed.
50
61
  * @param schema - model-facing schema of the definition.
package/lib/catalog.js CHANGED
@@ -55,6 +55,27 @@ export function splitCatalog(definitions, rules) {
55
55
  }
56
56
  return { inline, dynamic };
57
57
  }
58
+ /**
59
+ * Append declared definitions to the frozen catalog, keeping both orders.
60
+ *
61
+ * A name the catalog already declares keeps its catalog position and
62
+ * definition: the head must not move because a tool became loadable.
63
+ *
64
+ * @param catalog - frozen declaration head.
65
+ * @param declared - definitions loaded on demand, in load order.
66
+ * @returns the head followed by every declared name it does not declare.
67
+ */
68
+ export function extendCatalog(catalog, declared) {
69
+ const names = new Set(catalog.map(schema => schema.name));
70
+ const extended = [...catalog];
71
+ for (const schema of declared) {
72
+ if (names.has(schema.name))
73
+ continue;
74
+ names.add(schema.name);
75
+ extended.push(schema);
76
+ }
77
+ return extended;
78
+ }
58
79
  const encoder = new TextEncoder();
59
80
  /**
60
81
  * JSON size of one definition as it would be disclosed.
package/lib/disclose.d.ts CHANGED
@@ -6,6 +6,10 @@
6
6
  * registry, not the step's admission: a tool the model may not call right now
7
7
  * is still worth naming, because the call itself reports why it is unavailable.
8
8
  *
9
+ * A route that reads only declared tool lists gets names instead of schemas:
10
+ * its definition can only take effect once `tool_load` added it to the head, so
11
+ * attaching it here would claim a callability the route does not have.
12
+ *
9
13
  * @module dsh-dynamic-tools/disclose
10
14
  */
11
15
  import type { Context } from '@deepseek-ai/cordis';
@@ -14,6 +18,7 @@ import type { UserMessage } from '@deepseek-ai/dsh-llm';
14
18
  import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
15
19
  import { type DisclosedState, type DisclosureLimits } from './disclosure.ts';
16
20
  import type { SourceKind } from './source.ts';
21
+ import type { ToolStrategy } from './strategy.ts';
17
22
  /** Everything the pre-step listener needs to plan one step's disclosure. */
18
23
  export interface DiscloseOptions {
19
24
  /** Message source kind owned by this plugin. */
@@ -22,6 +27,8 @@ export interface DiscloseOptions {
22
27
  readonly limits: DisclosureLimits;
23
28
  /** Whether names that disappear from the registry are announced. */
24
29
  readonly announceRemovals: boolean;
30
+ /** Strategy this step's executor settled, per installed agent. */
31
+ readonly strategy: (agent: Agent) => ToolStrategy | undefined;
25
32
  /** Names the frozen head declares, per installed agent. */
26
33
  readonly catalogNames: (agent: Agent) => ReadonlySet<string>;
27
34
  /** Definitions this step admits, recorded by the executor's last assembly. */
@@ -41,11 +48,6 @@ export declare function currentState(agent: Agent, kind: SourceKind): DisclosedS
41
48
  * @param state - new state.
42
49
  */
43
50
  export declare function storeState(agent: Agent, state: DisclosedState): void;
44
- /**
45
- * Drop process-local state so the next read folds the durable messages again.
46
- * @param agent - agent whose session was compacted or replaced.
47
- */
48
- export declare function invalidateState(agent: Agent): void;
49
51
  /**
50
52
  * Append this step's disclosure messages.
51
53
  *
@@ -58,9 +60,10 @@ export declare function invalidateState(agent: Agent): void;
58
60
  * @param admitted - definitions this step admits.
59
61
  * @param executorCatalog - names the frozen head declares.
60
62
  * @param options - disclosure settings.
63
+ * @param strategy - how this step's route receives dynamic tools.
61
64
  * @returns the messages to append, in order.
62
65
  */
63
- export declare function disclosureMessages(ctx: Context, agent: Agent, admitted: readonly ToolDefinition[], executorCatalog: ReadonlySet<string>, options: DiscloseOptions): readonly UserMessage[];
66
+ export declare function disclosureMessages(ctx: Context, agent: Agent, admitted: readonly ToolDefinition[], executorCatalog: ReadonlySet<string>, options: DiscloseOptions, strategy: ToolStrategy): readonly UserMessage[];
64
67
  /**
65
68
  * Register the pre-step listener that appends disclosures.
66
69
  * @param ctx - plugin context owning the listener.
package/lib/disclose.js CHANGED
@@ -6,15 +6,21 @@
6
6
  * registry, not the step's admission: a tool the model may not call right now
7
7
  * is still worth naming, because the call itself reports why it is unavailable.
8
8
  *
9
+ * A route that reads only declared tool lists gets names instead of schemas:
10
+ * its definition can only take effect once `tool_load` added it to the head, so
11
+ * attaching it here would claim a callability the route does not have.
12
+ *
9
13
  * @module dsh-dynamic-tools/disclose
10
14
  */
11
15
  import { createUserMessage } from '@deepseek-ai/dsh-llm';
12
16
  import { projectToolSchema } from '@deepseek-ai/dsh-tools';
13
- import { applyDisclosure, planDisclosure } from "./disclosure.js";
17
+ import { applyDisclosure, oversizedNames, planDisclosure, } from "./disclosure.js";
14
18
  import { foldDisclosed } from "./fold.js";
15
19
  import { renderDisclosure } from "./render.js";
16
20
  /** Per-Agent delivery state without retaining agents. */
17
21
  const stateByAgent = new WeakMap();
22
+ /** Per-Agent diagnostics already reported, so each one appears once. */
23
+ const reportedByAgent = new WeakMap();
18
24
  /**
19
25
  * Read the session's delivered state, rebuilding it from durable messages when
20
26
  * the process-local holder is missing (resume, fork, compaction).
@@ -23,11 +29,11 @@ const stateByAgent = new WeakMap();
23
29
  * @returns the folded state.
24
30
  */
25
31
  export function currentState(agent, kind) {
26
- const holder = stateByAgent.get(agent);
27
- if (holder !== undefined)
28
- return holder.state;
32
+ const held = stateByAgent.get(agent);
33
+ if (held !== undefined)
34
+ return held;
29
35
  const folded = foldDisclosed(agent.session.deriveMessages(), kind);
30
- stateByAgent.set(agent, { state: folded });
36
+ stateByAgent.set(agent, folded);
31
37
  return folded;
32
38
  }
33
39
  /**
@@ -36,14 +42,22 @@ export function currentState(agent, kind) {
36
42
  * @param state - new state.
37
43
  */
38
44
  export function storeState(agent, state) {
39
- stateByAgent.set(agent, { state });
45
+ stateByAgent.set(agent, state);
40
46
  }
41
47
  /**
42
- * Drop process-local state so the next read folds the durable messages again.
43
- * @param agent - agent whose session was compacted or replaced.
48
+ * Report a per-agent diagnostic once, so a repeated condition does not repeat
49
+ * its log line on every step.
50
+ * @param agent - agent the condition belongs to.
51
+ * @param key - stable key for this condition.
52
+ * @param report - emitter, called only for a key not reported before.
44
53
  */
45
- export function invalidateState(agent) {
46
- stateByAgent.delete(agent);
54
+ function reportOnce(agent, key, report) {
55
+ const reported = reportedByAgent.get(agent) ?? new Set();
56
+ if (reported.has(key))
57
+ return;
58
+ reported.add(key);
59
+ reportedByAgent.set(agent, reported);
60
+ report();
47
61
  }
48
62
  function schemasOutsideCatalog(definitions, catalogNames) {
49
63
  return definitions
@@ -62,16 +76,30 @@ function schemasOutsideCatalog(definitions, catalogNames) {
62
76
  * @param admitted - definitions this step admits.
63
77
  * @param executorCatalog - names the frozen head declares.
64
78
  * @param options - disclosure settings.
79
+ * @param strategy - how this step's route receives dynamic tools.
65
80
  * @returns the messages to append, in order.
66
81
  */
67
- export function disclosureMessages(ctx, agent, admitted, executorCatalog, options) {
82
+ export function disclosureMessages(ctx, agent, admitted, executorCatalog, options, strategy) {
68
83
  const candidates = schemasOutsideCatalog(admitted, executorCatalog);
69
84
  const current = currentState(agent, options.sourceKind);
85
+ for (const name of current.damaged) {
86
+ reportOnce(agent, `damaged:${name}`, () => {
87
+ ctx.logger.warn('dsh-dynamic-tools: recorded definition for "%s" could not be parsed; disclosing it again', name);
88
+ });
89
+ }
90
+ const limits = strategy === 'declare' ? { ...options.limits, mode: 'names' } : options.limits;
91
+ if (limits.mode === 'names') {
92
+ for (const name of oversizedNames(candidates, limits)) {
93
+ reportOnce(agent, `oversized:${name}`, () => {
94
+ ctx.logger.warn('dsh-dynamic-tools: "%s" exceeds maxSchemaBytes (%d) and cannot be loaded on this route; it is not announced', name, limits.maxSchemaBytes);
95
+ });
96
+ }
97
+ }
70
98
  const available = new Set(candidates.map(schema => schema.name));
71
99
  const removed = options.announceRemovals
72
100
  ? [...current.disclosed.keys()].filter(name => !available.has(name) && !executorCatalog.has(name))
73
101
  : [];
74
- const batches = planDisclosure(candidates, removed, current, options.limits);
102
+ const batches = planDisclosure(candidates, removed, current, limits);
75
103
  if (batches.length === 0) {
76
104
  // A pruned history still needs its records re-linked for later comparisons.
77
105
  const folded = foldDisclosed(agent.session.deriveMessages(), options.sourceKind);
@@ -80,7 +108,7 @@ export function disclosureMessages(ctx, agent, admitted, executorCatalog, option
80
108
  return [];
81
109
  }
82
110
  const messages = batches.map(batch => createUserMessage({
83
- content: [{ type: 'text', text: renderDisclosure(batch) }],
111
+ content: [{ type: 'text', text: renderDisclosure(batch, strategy) }],
84
112
  source: { kind: options.sourceKind, form: 'catalog' },
85
113
  }));
86
114
  storeState(agent, applyDisclosure(current, batches));
@@ -93,16 +121,23 @@ export function disclosureMessages(ctx, agent, admitted, executorCatalog, option
93
121
  * @param options - disclosure settings.
94
122
  */
95
123
  export function registerDisclosure(ctx, options) {
96
- ctx.on('agent/pre-step', async ({ agent, signal }, next) => {
124
+ ctx.on('agent/pre-step', async ({ agent, signal, modelSelection }, next) => {
97
125
  const decision = await next();
98
126
  if (decision.kind === 'reject' || signal.aborted)
99
127
  return decision;
100
128
  try {
101
- // The executor recorded this step's admission when assembly described the head.
129
+ // The executor recorded this step's admission and strategy when assembly
130
+ // described the head, which happens before this listener runs.
102
131
  const admitted = options.admitted(agent);
103
132
  if (admitted === undefined)
104
133
  return decision;
105
- const messages = disclosureMessages(ctx, agent, admitted, options.catalogNames(agent), options);
134
+ const strategy = options.strategy(agent) ?? 'tail';
135
+ if (strategy === 'declare') {
136
+ reportOnce(agent, 'declare', () => {
137
+ ctx.logger.info('dsh-dynamic-tools: announcing definitions by name only on %s/%s; a loaded tool is declared in the next request', modelSelection.provider, modelSelection.model);
138
+ });
139
+ }
140
+ const messages = disclosureMessages(ctx, agent, admitted, options.catalogNames(agent), options, strategy);
106
141
  if (messages.length === 0)
107
142
  return decision;
108
143
  return { ...decision, messages: [...decision.messages, ...messages] };
@@ -38,9 +38,36 @@ export interface DisclosedState {
38
38
  readonly disclosed: ReadonlyMap<string, DisclosedEntry>;
39
39
  /** Names whose full definition the model has read, attached or loaded on demand. */
40
40
  readonly loaded: ReadonlySet<string>;
41
+ /**
42
+ * Definitions the model has read, in delivery order.
43
+ *
44
+ * The declare-on-load strategy turns these into tool-list declarations, so
45
+ * they outlive the announcement: a loaded tool stays declared even after the
46
+ * registry stops admitting it.
47
+ */
48
+ readonly definitions: ReadonlyMap<string, ToolSchemaLike>;
49
+ /**
50
+ * Names whose recorded definition block could not be parsed, in delivery
51
+ * order. The caller reports them: the definition is disclosed again, and the
52
+ * damage must not stay silent.
53
+ */
54
+ readonly damaged: readonly string[];
41
55
  }
42
56
  /** The empty state of a session that has disclosed nothing yet. */
43
57
  export declare const EMPTY_DISCLOSED: DisclosedState;
58
+ /**
59
+ * Definitions that no route can deliver because they exceed the schema cap.
60
+ *
61
+ * A `tail` route can still announce such a tool by name — the model calls it
62
+ * without reading the schema, and `tool_load` reports the cap. A `names` route
63
+ * has no such fallback: the tool can only run after its definition was loaded,
64
+ * so announcing it would promise a load that must fail.
65
+ *
66
+ * @param schemas - dynamic definitions admitted for this step.
67
+ * @param limits - validated disclosure limits.
68
+ * @returns names whose definition exceeds `maxSchemaBytes`.
69
+ */
70
+ export declare function oversizedNames(schemas: readonly ToolSchemaLike[], limits: DisclosureLimits): string[];
44
71
  /**
45
72
  * Plan the disclosures one step needs.
46
73
  *
@@ -55,6 +82,13 @@ export declare const EMPTY_DISCLOSED: DisclosedState;
55
82
  * @returns ordered batches, empty when the model already knows everything.
56
83
  */
57
84
  export declare function planDisclosure(admitted: readonly ToolSchemaLike[], removed: readonly string[], state: DisclosedState, limits: DisclosureLimits): DisclosureBatch[];
85
+ /**
86
+ * Record one delivered definition, clearing any earlier damage for that name.
87
+ * @param state - state before this delivery.
88
+ * @param schema - definition the model has now read.
89
+ * @returns the updated state.
90
+ */
91
+ export declare function withDefinition(state: DisclosedState, schema: ToolSchemaLike): DisclosedState;
58
92
  /**
59
93
  * Fold delivered batches into the delivered state.
60
94
  * @param previous - state before these batches.
package/lib/disclosure.js CHANGED
@@ -6,7 +6,27 @@
6
6
  */
7
7
  import { schemaBytes, toolSignature } from "./catalog.js";
8
8
  /** The empty state of a session that has disclosed nothing yet. */
9
- export const EMPTY_DISCLOSED = { disclosed: new Map(), loaded: new Set() };
9
+ export const EMPTY_DISCLOSED = {
10
+ disclosed: new Map(),
11
+ loaded: new Set(),
12
+ definitions: new Map(),
13
+ damaged: [],
14
+ };
15
+ /**
16
+ * Definitions that no route can deliver because they exceed the schema cap.
17
+ *
18
+ * A `tail` route can still announce such a tool by name — the model calls it
19
+ * without reading the schema, and `tool_load` reports the cap. A `names` route
20
+ * has no such fallback: the tool can only run after its definition was loaded,
21
+ * so announcing it would promise a load that must fail.
22
+ *
23
+ * @param schemas - dynamic definitions admitted for this step.
24
+ * @param limits - validated disclosure limits.
25
+ * @returns names whose definition exceeds `maxSchemaBytes`.
26
+ */
27
+ export function oversizedNames(schemas, limits) {
28
+ return schemas.filter(schema => schemaBytes(schema) > limits.maxSchemaBytes).map(schema => schema.name);
29
+ }
10
30
  /**
11
31
  * Plan the disclosures one step needs.
12
32
  *
@@ -31,7 +51,12 @@ export function planDisclosure(admitted, removed, state, limits) {
31
51
  if (entry.signature === toolSignature(schema))
32
52
  continue;
33
53
  }
34
- if (limits.mode === 'schema' && schemaBytes(schema) <= limits.maxSchemaBytes)
54
+ if (schemaBytes(schema) > limits.maxSchemaBytes) {
55
+ if (limits.mode === 'schema')
56
+ namesOnly.push(schema.name);
57
+ continue;
58
+ }
59
+ if (limits.mode === 'schema')
35
60
  attached.push(schema);
36
61
  else
37
62
  namesOnly.push(schema.name);
@@ -73,6 +98,22 @@ export function planDisclosure(admitted, removed, state, limits) {
73
98
  flush();
74
99
  return batches;
75
100
  }
101
+ /**
102
+ * Record one delivered definition, clearing any earlier damage for that name.
103
+ * @param state - state before this delivery.
104
+ * @param schema - definition the model has now read.
105
+ * @returns the updated state.
106
+ */
107
+ export function withDefinition(state, schema) {
108
+ const loaded = new Set(state.loaded).add(schema.name);
109
+ const definitions = new Map(state.definitions).set(schema.name, schema);
110
+ return {
111
+ disclosed: state.disclosed,
112
+ loaded,
113
+ definitions,
114
+ damaged: state.damaged.filter(name => name !== schema.name),
115
+ };
116
+ }
76
117
  /**
77
118
  * Fold delivered batches into the delivered state.
78
119
  * @param previous - state before these batches.
@@ -82,10 +123,14 @@ export function planDisclosure(admitted, removed, state, limits) {
82
123
  export function applyDisclosure(previous, batches) {
83
124
  const disclosed = new Map(previous.disclosed);
84
125
  const loaded = new Set(previous.loaded);
126
+ const definitions = new Map(previous.definitions);
127
+ const damaged = new Set(previous.damaged);
85
128
  for (const batch of batches) {
86
129
  for (const schema of batch.added) {
87
130
  disclosed.set(schema.name, { signature: toolSignature(schema), schema: true });
88
131
  loaded.add(schema.name);
132
+ definitions.set(schema.name, schema);
133
+ damaged.delete(schema.name);
89
134
  }
90
135
  for (const name of batch.names) {
91
136
  disclosed.set(name, { signature: null, schema: false });
@@ -93,7 +138,9 @@ export function applyDisclosure(previous, batches) {
93
138
  for (const name of batch.removed) {
94
139
  disclosed.delete(name);
95
140
  loaded.delete(name);
141
+ definitions.delete(name);
142
+ damaged.delete(name);
96
143
  }
97
144
  }
98
- return { disclosed, loaded };
145
+ return { disclosed, loaded, definitions, damaged: [...damaged] };
99
146
  }
package/lib/executor.d.ts CHANGED
@@ -7,19 +7,28 @@
7
7
  * through tail disclosure, but only while the step admits them: an unadmitted
8
8
  * call is reported as an executable denial before policy and approval run.
9
9
  *
10
+ * Routes that call only declared tools need the second half: a definition the
11
+ * model loaded through `tool_load` is appended to the declaration head, so the
12
+ * model can invoke it natively. The addition is monotone — a loaded tool keeps
13
+ * its declaration for the rest of the session — so the head changes once per
14
+ * loaded tool instead of once per admission change.
15
+ *
10
16
  * @module dsh-dynamic-tools/executor
11
17
  */
12
18
  import type { Context } from '@deepseek-ai/cordis';
13
19
  import type { Agent } from '@deepseek-ai/dsh-agent';
14
20
  import type { ToolBatchInput, ToolBatchResult, ToolDefinition, ToolExecutor, ToolModelInput } from '@deepseek-ai/dsh-tools';
15
- import { type ClassificationRules } from './catalog.ts';
21
+ import { type ClassificationRules, type ToolSchemaLike } from './catalog.ts';
16
22
  import type { DisclosedEntry } from './disclosure.ts';
23
+ import { type StrategyRules, type ToolStrategy } from './strategy.ts';
17
24
  /** Delivered disclosure state shared with the pre-step listener. */
18
25
  export interface DisclosureStateHandle {
19
26
  /** Definitions the model has been told about. */
20
27
  disclosed(): ReadonlyMap<string, DisclosedEntry>;
21
28
  /** Names whose definition was delivered through `tool_load`. */
22
29
  loaded(): ReadonlySet<string>;
30
+ /** Definitions the model has read, in delivery order. */
31
+ definitions(): ReadonlyMap<string, ToolSchemaLike>;
23
32
  }
24
33
  /** Runtime settings the executor reads on every step. */
25
34
  export interface ExecutorOptions {
@@ -29,6 +38,10 @@ export interface ExecutorOptions {
29
38
  readonly unavailableReasons: Readonly<Record<string, string>>;
30
39
  /** Concurrency used when the loop supplies none. */
31
40
  readonly maxParallelCalls: number;
41
+ /** Route matching rules for the declare-on-load strategy. */
42
+ readonly strategyRules: StrategyRules;
43
+ /** Name of the tool that delivers a definition on demand. */
44
+ readonly loadToolName: string;
32
45
  }
33
46
  /**
34
47
  * Executes the frozen declaration head plus admitted dynamic tools.
@@ -47,13 +60,18 @@ export declare class StableCatalogExecutor implements ToolExecutor {
47
60
  private lastAdmitted;
48
61
  /** Names the current batch's step admits. */
49
62
  private admittedNames;
63
+ /** Strategy settled by the current step's assembly, so every reader agrees. */
64
+ private stepStrategy;
65
+ /** Whether the missing-load-tool diagnostic was already reported. */
66
+ private loadWarningReported;
50
67
  constructor(ctx: Context, agent: Agent, rules: ClassificationRules, options: ExecutorOptions, state: DisclosureStateHandle);
51
- /** Names the frozen head declares; empty before the first assembly. */
68
+ /** Names the frozen head declares, plus every loaded tool on a declare route. */
52
69
  declaredNames(): ReadonlySet<string>;
53
70
  /** Definitions the current step admits, captured by the last assembly. */
54
71
  admittedDefinitions(): readonly ToolDefinition[];
55
72
  /**
56
- * Capture the head from the first assembly, then return it unchanged.
73
+ * Capture the head from the first assembly, then return it unchanged, plus
74
+ * every loaded definition on a declare route.
57
75
  * The first assembly's admission is exactly the declaration set the session
58
76
  * starts with, so the head matches what every later request would have
59
77
  * declared while the tool set is unchanged.
@@ -67,6 +85,36 @@ export declare class StableCatalogExecutor implements ToolExecutor {
67
85
  * @returns settled results in model order.
68
86
  */
69
87
  execute(input: ToolBatchInput): Promise<ToolBatchResult>;
88
+ /**
89
+ * How this step's route receives dynamic tools.
90
+ *
91
+ * The assembly that described this step's head fixes it once. Every later
92
+ * reader in the same step — declaration names, the load requirement, the
93
+ * disclosure listener — sees that one decision, so a model switch cannot make
94
+ * the head and the announcement disagree.
95
+ * @returns the recorded strategy, or the current route's before any assembly.
96
+ */
97
+ planStrategy(): ToolStrategy;
98
+ /**
99
+ * Capture the declaration head from the first assembly.
100
+ * @param tools - definitions the first assembly admits.
101
+ * @returns the frozen model-facing catalog.
102
+ */
103
+ private capture;
104
+ /**
105
+ * Append every loaded definition to the frozen head.
106
+ * A loaded tool the step still admits uses its live definition, so argument
107
+ * validation matches the call it will run; a tool that no longer admits keeps
108
+ * the definition the model read, because the head must not shrink.
109
+ * @param catalog - frozen declaration head.
110
+ * @returns the head followed by the loaded definitions, in load order.
111
+ */
112
+ private withDeclared;
113
+ /**
114
+ * Report once that a declare route cannot load anything because the frozen
115
+ * head does not declare the load tool.
116
+ */
117
+ private reportMissingLoadTool;
70
118
  /**
71
119
  * Resolve one call name: the step's admission first, then the registered
72
120
  * definition for a name the head declares or the model was told about.
@@ -83,4 +131,6 @@ export declare class StableCatalogExecutor implements ToolExecutor {
83
131
  * @returns the denial, or undefined to let dispatch proceed.
84
132
  */
85
133
  private reject;
134
+ /** Whether a dynamic tool must be loaded before it may run on this route. */
135
+ private requiresLoad;
86
136
  }