@dsh-plugin/dsh-dynamic-tools 0.0.0-stage → 0.0.1
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 -0
- package/README.md +111 -3
- package/cordis.patch.yml +8 -0
- package/docs/DETAIL.md +1 -0
- package/docs/preview.svg +25 -0
- package/icon.svg +7 -0
- package/lib/catalog.d.ts +53 -0
- package/lib/catalog.js +66 -0
- package/lib/disclose.d.ts +69 -0
- package/lib/disclose.js +115 -0
- package/lib/disclosure.d.ts +64 -0
- package/lib/disclosure.js +99 -0
- package/lib/executor.d.ts +86 -0
- package/lib/executor.js +112 -0
- package/lib/fold.d.ts +28 -0
- package/lib/fold.js +97 -0
- package/lib/index.d.ts +60 -0
- package/lib/index.js +126 -0
- package/lib/install.d.ts +39 -0
- package/lib/install.js +68 -0
- package/lib/render.d.ts +55 -0
- package/lib/render.js +107 -0
- package/lib/source.d.ts +18 -0
- package/lib/source.js +8 -0
- package/lib/tool-load.d.ts +29 -0
- package/lib/tool-load.js +91 -0
- package/locale/en.json +7 -0
- package/locale/zh.json +7 -0
- package/package.json +75 -6
- package/src/catalog.ts +88 -0
- package/src/disclose.ts +151 -0
- package/src/disclosure.ts +147 -0
- package/src/executor.ts +145 -0
- package/src/fold.ts +104 -0
- package/src/index.ts +178 -0
- package/src/install.ts +91 -0
- package/src/render.ts +115 -0
- package/src/source.ts +20 -0
- package/src/tool-load.ts +105 -0
|
@@ -0,0 +1,64 @@
|
|
|
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
|
+
import { type ToolSchemaLike } from './catalog.ts';
|
|
8
|
+
/** Validated disclosure limits. */
|
|
9
|
+
export interface DisclosureLimits {
|
|
10
|
+
/** Whether definitions are attached to the disclosure message. */
|
|
11
|
+
readonly mode: 'schema' | 'names';
|
|
12
|
+
/** Maximum tools announced in one message. */
|
|
13
|
+
readonly maxToolsPerMessage: number;
|
|
14
|
+
/** Maximum UTF-8 bytes of one attached definition. */
|
|
15
|
+
readonly maxSchemaBytes: number;
|
|
16
|
+
/** Maximum UTF-8 bytes of one disclosure message. */
|
|
17
|
+
readonly maxMessageBytes: number;
|
|
18
|
+
}
|
|
19
|
+
/** One message's worth of disclosure. */
|
|
20
|
+
export interface DisclosureBatch {
|
|
21
|
+
/** Definitions whose full schema is attached. */
|
|
22
|
+
readonly added: readonly ToolSchemaLike[];
|
|
23
|
+
/** Names announced without a schema; the model must call `tool_load`. */
|
|
24
|
+
readonly names: readonly string[];
|
|
25
|
+
/** Names that are no longer available. */
|
|
26
|
+
readonly removed: readonly string[];
|
|
27
|
+
}
|
|
28
|
+
/** What was delivered for one name. */
|
|
29
|
+
export interface DisclosedEntry {
|
|
30
|
+
/** Signature of the delivered definition, or `null` when only the name was announced. */
|
|
31
|
+
readonly signature: string | null;
|
|
32
|
+
/** Whether the full schema was delivered. */
|
|
33
|
+
readonly schema: boolean;
|
|
34
|
+
}
|
|
35
|
+
/** What the model has already been told, folded from durable messages. */
|
|
36
|
+
export interface DisclosedState {
|
|
37
|
+
/** Delivered name → delivery record. */
|
|
38
|
+
readonly disclosed: ReadonlyMap<string, DisclosedEntry>;
|
|
39
|
+
/** Names whose full definition the model has read, attached or loaded on demand. */
|
|
40
|
+
readonly loaded: ReadonlySet<string>;
|
|
41
|
+
}
|
|
42
|
+
/** The empty state of a session that has disclosed nothing yet. */
|
|
43
|
+
export declare const EMPTY_DISCLOSED: DisclosedState;
|
|
44
|
+
/**
|
|
45
|
+
* Plan the disclosures one step needs.
|
|
46
|
+
*
|
|
47
|
+
* Adds a tool when it is newly admitted or its definition changed since a full
|
|
48
|
+
* delivery. A name announced without a schema stays announced: `tool_load`
|
|
49
|
+
* always serves the current definition, so re-announcing it would only add noise.
|
|
50
|
+
*
|
|
51
|
+
* @param admitted - dynamic definitions admitted for this step.
|
|
52
|
+
* @param removed - names previously disclosed that are no longer admitted.
|
|
53
|
+
* @param state - previously delivered state.
|
|
54
|
+
* @param limits - validated disclosure limits.
|
|
55
|
+
* @returns ordered batches, empty when the model already knows everything.
|
|
56
|
+
*/
|
|
57
|
+
export declare function planDisclosure(admitted: readonly ToolSchemaLike[], removed: readonly string[], state: DisclosedState, limits: DisclosureLimits): DisclosureBatch[];
|
|
58
|
+
/**
|
|
59
|
+
* Fold delivered batches into the delivered state.
|
|
60
|
+
* @param previous - state before these batches.
|
|
61
|
+
* @param batches - batches that were delivered.
|
|
62
|
+
* @returns the updated state.
|
|
63
|
+
*/
|
|
64
|
+
export declare function applyDisclosure(previous: DisclosedState, batches: readonly DisclosureBatch[]): DisclosedState;
|
|
@@ -0,0 +1,99 @@
|
|
|
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
|
+
import { schemaBytes, toolSignature } from "./catalog.js";
|
|
8
|
+
/** The empty state of a session that has disclosed nothing yet. */
|
|
9
|
+
export const EMPTY_DISCLOSED = { disclosed: new Map(), loaded: new Set() };
|
|
10
|
+
/**
|
|
11
|
+
* Plan the disclosures one step needs.
|
|
12
|
+
*
|
|
13
|
+
* Adds a tool when it is newly admitted or its definition changed since a full
|
|
14
|
+
* delivery. A name announced without a schema stays announced: `tool_load`
|
|
15
|
+
* always serves the current definition, so re-announcing it would only add noise.
|
|
16
|
+
*
|
|
17
|
+
* @param admitted - dynamic definitions admitted for this step.
|
|
18
|
+
* @param removed - names previously disclosed that are no longer admitted.
|
|
19
|
+
* @param state - previously delivered state.
|
|
20
|
+
* @param limits - validated disclosure limits.
|
|
21
|
+
* @returns ordered batches, empty when the model already knows everything.
|
|
22
|
+
*/
|
|
23
|
+
export function planDisclosure(admitted, removed, state, limits) {
|
|
24
|
+
const attached = [];
|
|
25
|
+
const namesOnly = [];
|
|
26
|
+
for (const schema of admitted) {
|
|
27
|
+
const entry = state.disclosed.get(schema.name);
|
|
28
|
+
if (entry !== undefined) {
|
|
29
|
+
if (!entry.schema)
|
|
30
|
+
continue;
|
|
31
|
+
if (entry.signature === toolSignature(schema))
|
|
32
|
+
continue;
|
|
33
|
+
}
|
|
34
|
+
if (limits.mode === 'schema' && schemaBytes(schema) <= limits.maxSchemaBytes)
|
|
35
|
+
attached.push(schema);
|
|
36
|
+
else
|
|
37
|
+
namesOnly.push(schema.name);
|
|
38
|
+
}
|
|
39
|
+
const batches = [];
|
|
40
|
+
let pendingAdded = [];
|
|
41
|
+
let pendingNames = [];
|
|
42
|
+
let pendingRemoved = [];
|
|
43
|
+
let usedBytes = 0;
|
|
44
|
+
let pendingCount = 0;
|
|
45
|
+
const flush = () => {
|
|
46
|
+
if (pendingCount === 0)
|
|
47
|
+
return;
|
|
48
|
+
batches.push({ added: pendingAdded, names: pendingNames, removed: pendingRemoved });
|
|
49
|
+
pendingAdded = [];
|
|
50
|
+
pendingNames = [];
|
|
51
|
+
pendingRemoved = [];
|
|
52
|
+
usedBytes = 0;
|
|
53
|
+
pendingCount = 0;
|
|
54
|
+
};
|
|
55
|
+
const reserve = (bytes) => {
|
|
56
|
+
if (pendingCount > 0 && (pendingCount >= limits.maxToolsPerMessage || usedBytes + bytes > limits.maxMessageBytes))
|
|
57
|
+
flush();
|
|
58
|
+
usedBytes += bytes;
|
|
59
|
+
pendingCount += 1;
|
|
60
|
+
};
|
|
61
|
+
for (const schema of attached) {
|
|
62
|
+
reserve(limits.mode === 'schema' ? schemaBytes(schema) : schema.name.length);
|
|
63
|
+
pendingAdded.push(schema);
|
|
64
|
+
}
|
|
65
|
+
for (const name of namesOnly) {
|
|
66
|
+
reserve(name.length);
|
|
67
|
+
pendingNames.push(name);
|
|
68
|
+
}
|
|
69
|
+
for (const name of removed) {
|
|
70
|
+
reserve(name.length);
|
|
71
|
+
pendingRemoved.push(name);
|
|
72
|
+
}
|
|
73
|
+
flush();
|
|
74
|
+
return batches;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Fold delivered batches into the delivered state.
|
|
78
|
+
* @param previous - state before these batches.
|
|
79
|
+
* @param batches - batches that were delivered.
|
|
80
|
+
* @returns the updated state.
|
|
81
|
+
*/
|
|
82
|
+
export function applyDisclosure(previous, batches) {
|
|
83
|
+
const disclosed = new Map(previous.disclosed);
|
|
84
|
+
const loaded = new Set(previous.loaded);
|
|
85
|
+
for (const batch of batches) {
|
|
86
|
+
for (const schema of batch.added) {
|
|
87
|
+
disclosed.set(schema.name, { signature: toolSignature(schema), schema: true });
|
|
88
|
+
loaded.add(schema.name);
|
|
89
|
+
}
|
|
90
|
+
for (const name of batch.names) {
|
|
91
|
+
disclosed.set(name, { signature: null, schema: false });
|
|
92
|
+
}
|
|
93
|
+
for (const name of batch.removed) {
|
|
94
|
+
disclosed.delete(name);
|
|
95
|
+
loaded.delete(name);
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
return { disclosed, loaded };
|
|
99
|
+
}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Frozen-catalog tool executor.
|
|
3
|
+
*
|
|
4
|
+
* The declaration head is captured once, when this executor is installed, and
|
|
5
|
+
* returned unchanged for every later step, so a mid-conversation tool change
|
|
6
|
+
* never rewrites the request prefix. Tools outside that head stay callable
|
|
7
|
+
* through tail disclosure, but only while the step admits them: an unadmitted
|
|
8
|
+
* call is reported as an executable denial before policy and approval run.
|
|
9
|
+
*
|
|
10
|
+
* @module dsh-dynamic-tools/executor
|
|
11
|
+
*/
|
|
12
|
+
import type { Context } from '@deepseek-ai/cordis';
|
|
13
|
+
import type { Agent } from '@deepseek-ai/dsh-agent';
|
|
14
|
+
import type { ToolBatchInput, ToolBatchResult, ToolDefinition, ToolExecutor, ToolModelInput } from '@deepseek-ai/dsh-tools';
|
|
15
|
+
import { type ClassificationRules } from './catalog.ts';
|
|
16
|
+
import type { DisclosedEntry } from './disclosure.ts';
|
|
17
|
+
/** Delivered disclosure state shared with the pre-step listener. */
|
|
18
|
+
export interface DisclosureStateHandle {
|
|
19
|
+
/** Definitions the model has been told about. */
|
|
20
|
+
disclosed(): ReadonlyMap<string, DisclosedEntry>;
|
|
21
|
+
/** Names whose definition was delivered through `tool_load`. */
|
|
22
|
+
loaded(): ReadonlySet<string>;
|
|
23
|
+
}
|
|
24
|
+
/** Runtime settings the executor reads on every step. */
|
|
25
|
+
export interface ExecutorOptions {
|
|
26
|
+
/** Whether a dynamic tool must be loaded before it may run. */
|
|
27
|
+
readonly requireLoad: boolean;
|
|
28
|
+
/** Configured denial reasons by tool name. */
|
|
29
|
+
readonly unavailableReasons: Readonly<Record<string, string>>;
|
|
30
|
+
/** Concurrency used when the loop supplies none. */
|
|
31
|
+
readonly maxParallelCalls: number;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Executes the frozen declaration head plus admitted dynamic tools.
|
|
35
|
+
*/
|
|
36
|
+
export declare class StableCatalogExecutor implements ToolExecutor {
|
|
37
|
+
private readonly ctx;
|
|
38
|
+
private readonly agent;
|
|
39
|
+
private readonly rules;
|
|
40
|
+
private readonly options;
|
|
41
|
+
private readonly state;
|
|
42
|
+
/** Declaration head, captured by the first assembly and never replaced. */
|
|
43
|
+
private catalog;
|
|
44
|
+
/** Names the head declares. */
|
|
45
|
+
private readonly catalogNames;
|
|
46
|
+
/** Definitions the current step admits, recorded by the last assembly. */
|
|
47
|
+
private lastAdmitted;
|
|
48
|
+
/** Names the current batch's step admits. */
|
|
49
|
+
private admittedNames;
|
|
50
|
+
constructor(ctx: Context, agent: Agent, rules: ClassificationRules, options: ExecutorOptions, state: DisclosureStateHandle);
|
|
51
|
+
/** Names the frozen head declares; empty before the first assembly. */
|
|
52
|
+
declaredNames(): ReadonlySet<string>;
|
|
53
|
+
/** Definitions the current step admits, captured by the last assembly. */
|
|
54
|
+
admittedDefinitions(): readonly ToolDefinition[];
|
|
55
|
+
/**
|
|
56
|
+
* Capture the head from the first assembly, then return it unchanged.
|
|
57
|
+
* The first assembly's admission is exactly the declaration set the session
|
|
58
|
+
* starts with, so the head matches what every later request would have
|
|
59
|
+
* declared while the tool set is unchanged.
|
|
60
|
+
* @param tools - definitions this step admits, in registry order.
|
|
61
|
+
* @returns the frozen model-facing catalog.
|
|
62
|
+
*/
|
|
63
|
+
describe(tools: readonly ToolDefinition[]): ToolModelInput;
|
|
64
|
+
/**
|
|
65
|
+
* Execute one batch against the frozen head and the admitted dynamic set.
|
|
66
|
+
* @param input - original calls, admission, agent, and logging step.
|
|
67
|
+
* @returns settled results in model order.
|
|
68
|
+
*/
|
|
69
|
+
execute(input: ToolBatchInput): Promise<ToolBatchResult>;
|
|
70
|
+
/**
|
|
71
|
+
* Resolve one call name: the step's admission first, then the registered
|
|
72
|
+
* definition for a name the head declares or the model was told about.
|
|
73
|
+
* @param name - tool name the model called.
|
|
74
|
+
* @param scope - calling agent scope.
|
|
75
|
+
* @param toolSet - step admission, when one exists.
|
|
76
|
+
* @returns the definition to run, or undefined for an unknown tool.
|
|
77
|
+
*/
|
|
78
|
+
private resolve;
|
|
79
|
+
/**
|
|
80
|
+
* Decide the model-facing denial for a declared but unadmitted name, and for a
|
|
81
|
+
* dynamic tool that must be loaded first. Runs before policy and approval.
|
|
82
|
+
* @param name - tool name the model called.
|
|
83
|
+
* @returns the denial, or undefined to let dispatch proceed.
|
|
84
|
+
*/
|
|
85
|
+
private reject;
|
|
86
|
+
}
|
package/lib/executor.js
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Frozen-catalog tool executor.
|
|
3
|
+
*
|
|
4
|
+
* The declaration head is captured once, when this executor is installed, and
|
|
5
|
+
* returned unchanged for every later step, so a mid-conversation tool change
|
|
6
|
+
* never rewrites the request prefix. Tools outside that head stay callable
|
|
7
|
+
* through tail disclosure, but only while the step admits them: an unadmitted
|
|
8
|
+
* call is reported as an executable denial before policy and approval run.
|
|
9
|
+
*
|
|
10
|
+
* @module dsh-dynamic-tools/executor
|
|
11
|
+
*/
|
|
12
|
+
import { executeToolBatch, ToolExecutionPipeline } from '@deepseek-ai/dsh-tools/pipeline';
|
|
13
|
+
import { projectToolSchema } from '@deepseek-ai/dsh-tools';
|
|
14
|
+
import { classifyTool } from "./catalog.js";
|
|
15
|
+
import { loadFirstReason, unavailableReason } from "./render.js";
|
|
16
|
+
/**
|
|
17
|
+
* Executes the frozen declaration head plus admitted dynamic tools.
|
|
18
|
+
*/
|
|
19
|
+
export class StableCatalogExecutor {
|
|
20
|
+
ctx;
|
|
21
|
+
agent;
|
|
22
|
+
rules;
|
|
23
|
+
options;
|
|
24
|
+
state;
|
|
25
|
+
/** Declaration head, captured by the first assembly and never replaced. */
|
|
26
|
+
catalog;
|
|
27
|
+
/** Names the head declares. */
|
|
28
|
+
catalogNames = new Set();
|
|
29
|
+
/** Definitions the current step admits, recorded by the last assembly. */
|
|
30
|
+
lastAdmitted = [];
|
|
31
|
+
/** Names the current batch's step admits. */
|
|
32
|
+
admittedNames = new Set();
|
|
33
|
+
constructor(ctx, agent, rules, options, state) {
|
|
34
|
+
this.ctx = ctx;
|
|
35
|
+
this.agent = agent;
|
|
36
|
+
this.rules = rules;
|
|
37
|
+
this.options = options;
|
|
38
|
+
this.state = state;
|
|
39
|
+
}
|
|
40
|
+
/** Names the frozen head declares; empty before the first assembly. */
|
|
41
|
+
declaredNames() {
|
|
42
|
+
return this.catalogNames;
|
|
43
|
+
}
|
|
44
|
+
/** Definitions the current step admits, captured by the last assembly. */
|
|
45
|
+
admittedDefinitions() {
|
|
46
|
+
return this.lastAdmitted;
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Capture the head from the first assembly, then return it unchanged.
|
|
50
|
+
* The first assembly's admission is exactly the declaration set the session
|
|
51
|
+
* starts with, so the head matches what every later request would have
|
|
52
|
+
* declared while the tool set is unchanged.
|
|
53
|
+
* @param tools - definitions this step admits, in registry order.
|
|
54
|
+
* @returns the frozen model-facing catalog.
|
|
55
|
+
*/
|
|
56
|
+
describe(tools) {
|
|
57
|
+
this.lastAdmitted = tools;
|
|
58
|
+
if (this.catalog === undefined) {
|
|
59
|
+
this.catalog = Object.freeze(tools
|
|
60
|
+
.filter(definition => classifyTool(definition.name, this.rules) === 'inline')
|
|
61
|
+
.map(definition => Object.freeze(projectToolSchema(definition, true))));
|
|
62
|
+
for (const schema of this.catalog)
|
|
63
|
+
this.catalogNames.add(schema.name);
|
|
64
|
+
}
|
|
65
|
+
return { schemas: [...this.catalog] };
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Execute one batch against the frozen head and the admitted dynamic set.
|
|
69
|
+
* @param input - original calls, admission, agent, and logging step.
|
|
70
|
+
* @returns settled results in model order.
|
|
71
|
+
*/
|
|
72
|
+
execute(input) {
|
|
73
|
+
this.admittedNames = new Set((input.toolSet?.view(this.agent) ?? new Map()).keys());
|
|
74
|
+
const pipeline = new ToolExecutionPipeline(this.ctx, {
|
|
75
|
+
get: (name, scope, toolSet) => this.resolve(name, scope, toolSet),
|
|
76
|
+
reject: (name) => this.reject(name),
|
|
77
|
+
});
|
|
78
|
+
return executeToolBatch(input, pipeline, () => input.maxParallelToolCalls ?? this.options.maxParallelCalls);
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Resolve one call name: the step's admission first, then the registered
|
|
82
|
+
* definition for a name the head declares or the model was told about.
|
|
83
|
+
* @param name - tool name the model called.
|
|
84
|
+
* @param scope - calling agent scope.
|
|
85
|
+
* @param toolSet - step admission, when one exists.
|
|
86
|
+
* @returns the definition to run, or undefined for an unknown tool.
|
|
87
|
+
*/
|
|
88
|
+
resolve(name, scope, toolSet) {
|
|
89
|
+
const admitted = toolSet?.view(scope).get(name);
|
|
90
|
+
if (admitted !== undefined)
|
|
91
|
+
return admitted;
|
|
92
|
+
if (!this.catalogNames.has(name) && !this.state.disclosed().has(name))
|
|
93
|
+
return undefined;
|
|
94
|
+
return this.ctx.tools.definitions(this.agent).find(definition => definition.name === name);
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Decide the model-facing denial for a declared but unadmitted name, and for a
|
|
98
|
+
* dynamic tool that must be loaded first. Runs before policy and approval.
|
|
99
|
+
* @param name - tool name the model called.
|
|
100
|
+
* @returns the denial, or undefined to let dispatch proceed.
|
|
101
|
+
*/
|
|
102
|
+
reject(name) {
|
|
103
|
+
if (this.admittedNames.has(name)) {
|
|
104
|
+
if (this.catalogNames.has(name) || !this.options.requireLoad)
|
|
105
|
+
return undefined;
|
|
106
|
+
return this.state.loaded().has(name) ? undefined : new Error(loadFirstReason(name));
|
|
107
|
+
}
|
|
108
|
+
if (!this.catalogNames.has(name) && !this.state.disclosed().has(name))
|
|
109
|
+
return undefined;
|
|
110
|
+
return new Error(unavailableReason(name, this.options.unavailableReasons[name]));
|
|
111
|
+
}
|
|
112
|
+
}
|
package/lib/fold.d.ts
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fold durable disclosure messages back into delivery state, so compaction,
|
|
3
|
+
* resume, and fork rebuild the comparison instead of trusting process memory.
|
|
4
|
+
*
|
|
5
|
+
* @module dsh-dynamic-tools/fold
|
|
6
|
+
*/
|
|
7
|
+
import type { DisclosedState } from './disclosure.ts';
|
|
8
|
+
/** The subset of a model message this fold reads. */
|
|
9
|
+
export interface FoldableMessage {
|
|
10
|
+
readonly role: string;
|
|
11
|
+
readonly content: readonly {
|
|
12
|
+
readonly type: string;
|
|
13
|
+
readonly text?: string;
|
|
14
|
+
}[];
|
|
15
|
+
readonly source?: {
|
|
16
|
+
readonly kind?: string;
|
|
17
|
+
};
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Fold every dynamic-tools message in delivery order.
|
|
21
|
+
* Damaged blocks are ignored: an unreadable disclosure only costs one
|
|
22
|
+
* re-announcement, never a wrong refusal.
|
|
23
|
+
*
|
|
24
|
+
* @param messages - derived session messages in model order.
|
|
25
|
+
* @param kind - message source kind owned by this plugin.
|
|
26
|
+
* @returns the delivered state at the end of the history.
|
|
27
|
+
*/
|
|
28
|
+
export declare function foldDisclosed(messages: readonly FoldableMessage[], kind: string): DisclosedState;
|
package/lib/fold.js
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fold durable disclosure messages back into delivery state, so compaction,
|
|
3
|
+
* resume, and fork rebuild the comparison instead of trusting process memory.
|
|
4
|
+
*
|
|
5
|
+
* @module dsh-dynamic-tools/fold
|
|
6
|
+
*/
|
|
7
|
+
import { toolSignature } from "./catalog.js";
|
|
8
|
+
const ADDED = /<tools_added>\n?([\s\S]*?)\n?<\/tools_added>/g;
|
|
9
|
+
const REMOVED = /<tools_removed>\n?([\s\S]*?)\n?<\/tools_removed>/g;
|
|
10
|
+
const DEFINITION = /<tool_definition name="([^"\n]+)">\n?([\s\S]*?)\n?<\/tool_definition>/g;
|
|
11
|
+
function textOf(message) {
|
|
12
|
+
return message.content.map(block => block.type === 'text' ? block.text ?? '' : '').join('');
|
|
13
|
+
}
|
|
14
|
+
function namesOf(body) {
|
|
15
|
+
const names = [];
|
|
16
|
+
for (const line of body.split('\n')) {
|
|
17
|
+
const trimmed = line.trim();
|
|
18
|
+
if (!trimmed.startsWith('- '))
|
|
19
|
+
continue;
|
|
20
|
+
const rest = trimmed.slice(2);
|
|
21
|
+
const colon = rest.indexOf(': ');
|
|
22
|
+
names.push(colon < 0 ? rest : rest.slice(0, colon));
|
|
23
|
+
}
|
|
24
|
+
return names.filter(name => name.length > 0);
|
|
25
|
+
}
|
|
26
|
+
function matches(text, pattern) {
|
|
27
|
+
const bodies = [];
|
|
28
|
+
pattern.lastIndex = 0;
|
|
29
|
+
for (const match of text.matchAll(pattern))
|
|
30
|
+
bodies.push(match[1] ?? '');
|
|
31
|
+
return bodies.flatMap(namesOf);
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Read one definition block, if it is a valid schema.
|
|
35
|
+
* @param json - the block body.
|
|
36
|
+
* @returns the parsed schema, or undefined when the text is not a schema object.
|
|
37
|
+
*/
|
|
38
|
+
function parseDefinition(json) {
|
|
39
|
+
try {
|
|
40
|
+
const value = JSON.parse(json);
|
|
41
|
+
if (typeof value !== 'object' || value === null || Array.isArray(value))
|
|
42
|
+
return undefined;
|
|
43
|
+
const candidate = value;
|
|
44
|
+
if (typeof candidate.name !== 'string' || typeof candidate.description !== 'string')
|
|
45
|
+
return undefined;
|
|
46
|
+
if (typeof candidate.parameters !== 'object' || candidate.parameters === null)
|
|
47
|
+
return undefined;
|
|
48
|
+
return candidate;
|
|
49
|
+
}
|
|
50
|
+
catch (error) {
|
|
51
|
+
void error;
|
|
52
|
+
return undefined;
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Fold every dynamic-tools message in delivery order.
|
|
57
|
+
* Damaged blocks are ignored: an unreadable disclosure only costs one
|
|
58
|
+
* re-announcement, never a wrong refusal.
|
|
59
|
+
*
|
|
60
|
+
* @param messages - derived session messages in model order.
|
|
61
|
+
* @param kind - message source kind owned by this plugin.
|
|
62
|
+
* @returns the delivered state at the end of the history.
|
|
63
|
+
*/
|
|
64
|
+
export function foldDisclosed(messages, kind) {
|
|
65
|
+
const disclosed = new Map();
|
|
66
|
+
const loaded = new Set();
|
|
67
|
+
for (const message of messages) {
|
|
68
|
+
if (message.source?.kind !== kind)
|
|
69
|
+
continue;
|
|
70
|
+
const text = textOf(message);
|
|
71
|
+
for (const name of matches(text, REMOVED)) {
|
|
72
|
+
disclosed.delete(name);
|
|
73
|
+
loaded.delete(name);
|
|
74
|
+
}
|
|
75
|
+
const definitions = new Map();
|
|
76
|
+
DEFINITION.lastIndex = 0;
|
|
77
|
+
for (const match of text.matchAll(DEFINITION)) {
|
|
78
|
+
const schema = parseDefinition(match[2] ?? '');
|
|
79
|
+
if (schema !== undefined)
|
|
80
|
+
definitions.set(schema.name, schema);
|
|
81
|
+
}
|
|
82
|
+
for (const name of matches(text, ADDED)) {
|
|
83
|
+
const schema = definitions.get(name);
|
|
84
|
+
if (schema === undefined) {
|
|
85
|
+
disclosed.set(name, { signature: null, schema: false });
|
|
86
|
+
continue;
|
|
87
|
+
}
|
|
88
|
+
disclosed.set(name, { signature: toolSignature(schema), schema: true });
|
|
89
|
+
loaded.add(name);
|
|
90
|
+
}
|
|
91
|
+
for (const schema of definitions.values()) {
|
|
92
|
+
disclosed.set(schema.name, { signature: toolSignature(schema), schema: true });
|
|
93
|
+
loaded.add(schema.name);
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
return { disclosed, loaded };
|
|
97
|
+
}
|
package/lib/index.d.ts
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
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
|
+
import z from '@deepseek-ai/schemastery';
|
|
15
|
+
import type { Context } from '@deepseek-ai/cordis';
|
|
16
|
+
/** Cordis plugin name. */
|
|
17
|
+
export declare const name = "@dsh-plugin/dsh-dynamic-tools";
|
|
18
|
+
/** Services the plugin registers into. */
|
|
19
|
+
export declare const inject: string[];
|
|
20
|
+
/** Tool-selection and disclosure settings. */
|
|
21
|
+
export interface Config {
|
|
22
|
+
/** Install for agents that already exist when this plugin loads. */
|
|
23
|
+
installExistingAgents: boolean;
|
|
24
|
+
/** Preset ids left untouched, so their own executor keeps the declaration path. */
|
|
25
|
+
skipPresets: string[];
|
|
26
|
+
dynamic: {
|
|
27
|
+
/** Exact tool names disclosed at the conversation tail. */
|
|
28
|
+
names: string[];
|
|
29
|
+
/** Tool-name prefixes disclosed at the conversation tail. */
|
|
30
|
+
prefixes: string[];
|
|
31
|
+
/** Exact names forced into the frozen head. */
|
|
32
|
+
inlineNames: string[];
|
|
33
|
+
};
|
|
34
|
+
disclosure: {
|
|
35
|
+
/** Attach definitions to the disclosure, or announce names for `tool_load`. */
|
|
36
|
+
mode: 'schema' | 'names';
|
|
37
|
+
/** Require `tool_load` before a dynamic tool may run. */
|
|
38
|
+
requireLoad: boolean;
|
|
39
|
+
/** Maximum tools announced in one message. */
|
|
40
|
+
maxToolsPerMessage: number;
|
|
41
|
+
/** Maximum bytes of one attached definition. */
|
|
42
|
+
maxSchemaBytes: number;
|
|
43
|
+
/** Maximum bytes of one disclosure message. */
|
|
44
|
+
maxMessageBytes: number;
|
|
45
|
+
/** Announce tools that stop being available. */
|
|
46
|
+
announceRemovals: boolean;
|
|
47
|
+
};
|
|
48
|
+
/** Model-facing reason reported when a declared tool is not admitted. */
|
|
49
|
+
unavailableReasons: Record<string, string>;
|
|
50
|
+
/** Concurrency used when the loop supplies no limit. */
|
|
51
|
+
maxParallelCalls: number;
|
|
52
|
+
}
|
|
53
|
+
/** Schemastery validation; invalid values fail at load. */
|
|
54
|
+
export declare const Config: z<Config>;
|
|
55
|
+
/**
|
|
56
|
+
* Register the load tool, the frozen catalog per agent, and tail disclosure.
|
|
57
|
+
* @param ctx - plugin context owning every registration.
|
|
58
|
+
* @param config - validated plugin configuration.
|
|
59
|
+
*/
|
|
60
|
+
export declare function apply(ctx: Context, config: Config): void;
|
package/lib/index.js
ADDED
|
@@ -0,0 +1,126 @@
|
|
|
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
|
+
import z from '@deepseek-ai/schemastery';
|
|
15
|
+
import { registerDisclosure } from "./disclose.js";
|
|
16
|
+
import { installAgent } from "./install.js";
|
|
17
|
+
import { SOURCE_KIND } from "./source.js";
|
|
18
|
+
import { createToolLoad, TOOL_LOAD_NAME } from "./tool-load.js";
|
|
19
|
+
/** Cordis plugin name. */
|
|
20
|
+
export const name = '@dsh-plugin/dsh-dynamic-tools';
|
|
21
|
+
/** Services the plugin registers into. */
|
|
22
|
+
export const inject = ['tools', 'systemPrompt'];
|
|
23
|
+
/** Schemastery validation; invalid values fail at load. */
|
|
24
|
+
export const Config = z.object({
|
|
25
|
+
installExistingAgents: z.boolean().default(true)
|
|
26
|
+
.description('Install for agents that already exist when this plugin loads.'),
|
|
27
|
+
skipPresets: z.array(z.string()).default(['ptc'])
|
|
28
|
+
.description('Preset ids whose own tool executor keeps the declaration path.'),
|
|
29
|
+
dynamic: z.object({
|
|
30
|
+
names: z.array(z.string()).default(['exit_plan_mode'])
|
|
31
|
+
.description('Exact tool names disclosed at the conversation tail.'),
|
|
32
|
+
prefixes: z.array(z.string()).default([])
|
|
33
|
+
.description('Tool-name prefixes disclosed at the conversation tail.'),
|
|
34
|
+
inlineNames: z.array(z.string()).default([])
|
|
35
|
+
.description('Exact names forced into the frozen head.'),
|
|
36
|
+
}).default({}),
|
|
37
|
+
disclosure: z.object({
|
|
38
|
+
mode: z.union(['schema', 'names']).default('schema')
|
|
39
|
+
.description('Attach definitions to the disclosure, or announce names for tool_load.'),
|
|
40
|
+
requireLoad: z.boolean().default(false)
|
|
41
|
+
.description('Require tool_load before a dynamic tool may run.'),
|
|
42
|
+
maxToolsPerMessage: z.number().min(1).default(8)
|
|
43
|
+
.description('Maximum tools announced in one message.'),
|
|
44
|
+
maxSchemaBytes: z.number().min(1).default(6000)
|
|
45
|
+
.description('Maximum bytes of one attached definition.'),
|
|
46
|
+
maxMessageBytes: z.number().min(1).default(20000)
|
|
47
|
+
.description('Maximum bytes of one disclosure message.'),
|
|
48
|
+
announceRemovals: z.boolean().default(true)
|
|
49
|
+
.description('Announce tools that stop being available.'),
|
|
50
|
+
}).default({}),
|
|
51
|
+
unavailableReasons: z.dict(z.string()).default({
|
|
52
|
+
exit_plan_mode: 'Plan mode is not active in this session. Ask the user to switch to plan mode, then call it again.',
|
|
53
|
+
}).description('Model-facing reason reported when a declared tool is not admitted.'),
|
|
54
|
+
maxParallelCalls: z.number().min(1).default(10)
|
|
55
|
+
.description('Concurrency used when the loop supplies no limit.'),
|
|
56
|
+
});
|
|
57
|
+
/**
|
|
58
|
+
* Compose validated settings into the two halves the plugin registers.
|
|
59
|
+
* @param config - validated plugin configuration.
|
|
60
|
+
* @returns classification, execution, and disclosure settings.
|
|
61
|
+
*/
|
|
62
|
+
function resolveSettings(config) {
|
|
63
|
+
const rules = {
|
|
64
|
+
dynamicNames: config.dynamic.names,
|
|
65
|
+
dynamicPrefixes: config.dynamic.prefixes,
|
|
66
|
+
inlineNames: config.dynamic.inlineNames,
|
|
67
|
+
};
|
|
68
|
+
return {
|
|
69
|
+
rules,
|
|
70
|
+
install: {
|
|
71
|
+
sourceKind: SOURCE_KIND,
|
|
72
|
+
rules,
|
|
73
|
+
executor: {
|
|
74
|
+
requireLoad: config.disclosure.requireLoad,
|
|
75
|
+
unavailableReasons: config.unavailableReasons,
|
|
76
|
+
maxParallelCalls: config.maxParallelCalls,
|
|
77
|
+
},
|
|
78
|
+
skipPresets: config.skipPresets,
|
|
79
|
+
},
|
|
80
|
+
disclose: {
|
|
81
|
+
sourceKind: SOURCE_KIND,
|
|
82
|
+
limits: {
|
|
83
|
+
mode: config.disclosure.mode,
|
|
84
|
+
maxToolsPerMessage: config.disclosure.maxToolsPerMessage,
|
|
85
|
+
maxSchemaBytes: config.disclosure.maxSchemaBytes,
|
|
86
|
+
maxMessageBytes: config.disclosure.maxMessageBytes,
|
|
87
|
+
},
|
|
88
|
+
announceRemovals: config.disclosure.announceRemovals,
|
|
89
|
+
},
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Register the load tool, the frozen catalog per agent, and tail disclosure.
|
|
94
|
+
* @param ctx - plugin context owning every registration.
|
|
95
|
+
* @param config - validated plugin configuration.
|
|
96
|
+
*/
|
|
97
|
+
export function apply(ctx, config) {
|
|
98
|
+
const settings = resolveSettings(config);
|
|
99
|
+
const executors = new WeakMap();
|
|
100
|
+
const release = new WeakMap();
|
|
101
|
+
const reported = new WeakSet();
|
|
102
|
+
const installOptions = { ...settings.install, executors, reported };
|
|
103
|
+
ctx.effect(() => ctx.tools.register(createToolLoad(ctx, {
|
|
104
|
+
sourceKind: SOURCE_KIND,
|
|
105
|
+
limits: settings.disclose.limits,
|
|
106
|
+
})), `dsh-dynamic-tools: register ${TOOL_LOAD_NAME}`);
|
|
107
|
+
ctx.on('agent/created', ({ agent }) => {
|
|
108
|
+
installAgent(ctx, agent, installOptions, release);
|
|
109
|
+
return undefined;
|
|
110
|
+
});
|
|
111
|
+
// An agent's executor belongs to that agent: release it with the agent instead
|
|
112
|
+
// of retaining every closed session's executor until this plugin unloads.
|
|
113
|
+
ctx.on('agent/disposed', ({ agent }) => {
|
|
114
|
+
release.get(agent)?.();
|
|
115
|
+
});
|
|
116
|
+
if (config.installExistingAgents) {
|
|
117
|
+
const agents = ctx.get('agents');
|
|
118
|
+
for (const agent of agents?.list() ?? [])
|
|
119
|
+
installAgent(ctx, agent, installOptions, release);
|
|
120
|
+
}
|
|
121
|
+
registerDisclosure(ctx, {
|
|
122
|
+
...settings.disclose,
|
|
123
|
+
catalogNames: agent => executors.get(agent)?.declaredNames() ?? new Set(),
|
|
124
|
+
admitted: agent => executors.get(agent)?.admittedDefinitions(),
|
|
125
|
+
});
|
|
126
|
+
}
|