@ptkl/toolkit 1.6.0 → 1.7.0

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.
@@ -0,0 +1,31 @@
1
+ import { describe, it, expect } from 'vitest';
2
+ import PlaybookValidator from '../playbookValidator.js';
3
+ const agent = 'ag1';
4
+ const app = '0a1b2c3d-1111-4222-8333-444455556666';
5
+ const graph = (step) => ({
6
+ nodes: [
7
+ { id: 'read', kind: 'instruction', text: 'Read', agent_uuid: agent },
8
+ { id: 'send', kind: 'tool', title: 'Send it', text: 'Send the summary', agent_uuid: agent, tool: 'model_find', ...step },
9
+ ],
10
+ edges: [{ from: 'read', to: 'send' }],
11
+ });
12
+ const run = (g) => new PlaybookValidator().validate(g).map((p) => [p.code, p.message]);
13
+ describe('tool step', () => {
14
+ it('accepts a platform tool', () => expect(run(graph({}))).toEqual([]));
15
+ it('accepts a Forge app tool', () => expect(run(graph({ tool: `${app}/send_mail` }))).toEqual([]));
16
+ it('accepts a result schema at the end', () => expect(run(graph({ result_schema: { type: 'object', properties: { ok: { type: 'boolean', description: 'Done' } }, required: ['ok'] } }))).toEqual([]));
17
+ it('needs a tool', () => expect(run(graph({ tool: undefined }))).toEqual([
18
+ ['tool_missing', 'Step "Send it" uses a tool, but no tool is chosen.'],
19
+ ]));
20
+ it('needs text and an agent', () => expect(run(graph({ text: '', agent_uuid: '' })).map((p) => p[0])).toEqual(['empty_text', 'no_agent']));
21
+ it('refuses decide_by', () => expect(run(graph({ decide_by: 'rules' })).map((p) => p[0])).toEqual(['bad_decide_by']));
22
+ it('refuses a tool on an instruction', () => {
23
+ const g = graph({});
24
+ g.nodes[0].tool = 'model_find';
25
+ expect(run(g)).toEqual([['tool_not_on_kind', 'Step "read" is not a tool step, so it cannot name a tool.']]);
26
+ });
27
+ it.each(['bash', 'read_file', 'work_finish', 'forge_tools_list', 'forge_tool_call', 'nope/send', `${app}/Bad`, `${app}/a/b`])('refuses %s', (tool) => expect(run(graph({ tool }))).toEqual([['tool_invalid', `Step "Send it" names ${tool}, which is not a tool an agent can use.`]]));
28
+ it('lists three kinds in bad_kind', () => expect(run(graph({ kind: 'nope', tool: undefined }))[0]).toEqual([
29
+ 'bad_kind', 'Step "Send it" has kind "nope"; it must be an instruction, a condition or a tool.',
30
+ ]));
31
+ });
@@ -4,6 +4,7 @@
4
4
  // The same goes for the syntax of a rule (`when`): only the server can compile it, so use
5
5
  // `ptkl kortex playbook rule-check` to try one. Offline, a rule is only checked to be present
6
6
  // and not too long. The rule messages are the server's, word for word.
7
+ // Whether the step's agent can use its tool (tool_not_granted) is only known to the server.
7
8
  // Rules on the version (`graph.rules`) are checked here in full, with the server's messages.
8
9
  import ResultSchemaChecker, { MAX_RESULT_PROBLEMS, goQuote } from './resultSchemaChecker.js';
9
10
  // Limits on rules, the same as the server's.
@@ -51,8 +52,8 @@ export default class PlaybookValidator {
51
52
  continue;
52
53
  }
53
54
  ids.add(n.id);
54
- if (n.kind !== 'instruction' && n.kind !== 'condition') {
55
- add('bad_kind', `Step "${label}" must be an "instruction" or a "condition".`, n.id);
55
+ if (n.kind !== 'instruction' && n.kind !== 'condition' && n.kind !== 'tool') {
56
+ add('bad_kind', `Step ${goQuote(label)} has kind ${goQuote(String(n.kind ?? ''))}; it must be an instruction, a condition or a tool.`, n.id);
56
57
  }
57
58
  const byRules = n.kind === 'condition' && n.decide_by === 'rules';
58
59
  if (!byRules && (typeof n.text !== 'string' || n.text === '')) {
@@ -67,6 +68,7 @@ export default class PlaybookValidator {
67
68
  add('bad_decide_by', `${l} decides by ${goQuote(String(n.decide_by))}; it must be "agent" or "rules".`, n.id);
68
69
  }
69
70
  }
71
+ this.toolProblems(n, l, problems);
70
72
  const hasAgent = typeof n.agent_uuid === 'string' && n.agent_uuid !== '';
71
73
  if (byRules) {
72
74
  if (hasAgent)
@@ -177,6 +179,29 @@ export default class PlaybookValidator {
177
179
  this.workRuleProblems(graph, ids, problems);
178
180
  return problems;
179
181
  }
182
+ // A tool step names one tool; no other step may. The server also checks the agent can use it.
183
+ toolProblems(n, l, problems) {
184
+ const add = (code, message) => problems.push({ code, node_id: n.id, message });
185
+ const tool = typeof n.tool === 'string' ? n.tool : '';
186
+ if (n.kind === 'tool') {
187
+ if (tool === '')
188
+ add('tool_missing', `${l} uses a tool, but no tool is chosen.`);
189
+ else if (!this.toolUsable(tool))
190
+ add('tool_invalid', `${l} names ${tool}, which is not a tool an agent can use.`);
191
+ }
192
+ else if (tool !== '') {
193
+ add('tool_not_on_kind', `${l} is not a tool step, so it cannot name a tool.`);
194
+ }
195
+ }
196
+ // A platform tool name, or "<uuid>/<name>" for a Forge app tool; never a reserved tool.
197
+ toolUsable(tool) {
198
+ const reserved = ['bash', 'read_file', 'forge_tools_list', 'forge_tool_call'];
199
+ if (tool.includes('/')) {
200
+ const [uuid, name, ...rest] = tool.split('/');
201
+ return rest.length === 0 && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(uuid) && /^[a-z][a-z0-9_]{0,63}$/.test(name);
202
+ }
203
+ return !reserved.includes(tool) && !tool.startsWith('work_');
204
+ }
180
205
  sizeProblems(graph, problems) {
181
206
  const add = (field, message) => problems.push({ code: 'too_large', field, message });
182
207
  const bytes = (v) => (typeof v === 'string' ? Buffer.byteLength(v) : 0);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ptkl/toolkit",
3
- "version": "1.6.0",
3
+ "version": "1.7.0",
4
4
  "description": "A command-line toolkit for managing Protokol platform applications, profiles, functions, and components",
5
5
  "keywords": [
6
6
  "protokol",