@ptkl/toolkit 1.5.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.
- package/README.md +20 -0
- package/dist/commands/__tests__/forge-bundle-layout.test.js +12 -0
- package/dist/commands/__tests__/forge-tools.test.js +64 -0
- package/dist/commands/__tests__/kortexPlaybook.test.js +328 -0
- package/dist/commands/forge.js +159 -70
- package/dist/commands/kortex.js +8 -6
- package/dist/commands/kortexPlaybook.js +396 -0
- package/dist/lib/__tests__/apiError.test.js +4 -0
- package/dist/lib/apiError.js +12 -1
- package/dist/lib/kortex/__tests__/fixtures/sse-and-persistence.test.js +1 -1
- package/dist/lib/kortex/__tests__/playbookRules.test.js +120 -0
- package/dist/lib/kortex/__tests__/playbookToolStep.test.js +31 -0
- package/dist/lib/kortex/__tests__/resultSchemaChecker.test.js +37 -0
- package/dist/lib/kortex/playbookValidator.js +322 -0
- package/dist/lib/kortex/providers/protokol.js +1 -1
- package/dist/lib/kortex/resultSchemaChecker.js +188 -0
- package/dist/lib/kortex/session.js +1 -3
- package/package.json +2 -2
|
@@ -0,0 +1,396 @@
|
|
|
1
|
+
import { Command } from "commander";
|
|
2
|
+
import { readFileSync, writeFileSync } from "fs";
|
|
3
|
+
import { kortex as kortexClient } from "../lib/sdk.js";
|
|
4
|
+
import { registerCommand, withProfile } from "../lib/scaffold.js";
|
|
5
|
+
import PlaybookValidator, { MAX_RULE_LENGTH } from "../lib/kortex/playbookValidator.js";
|
|
6
|
+
// The first @ptkl/sdk release with the Workforce methods.
|
|
7
|
+
export const MIN_SDK_VERSION = '1.23.0';
|
|
8
|
+
const DONE_STATUSES = ['completed', 'failed', 'killed', 'timeout', 'expired'];
|
|
9
|
+
const NEEDS_PERSON_STATUSES = ['awaiting_approval', 'awaiting_answer', 'paused'];
|
|
10
|
+
// `ptkl kortex playbook`: playbooks as files. Pull to JSON, edit, validate, push a version,
|
|
11
|
+
// deploy, run. Exit codes for `run --wait`: 0 completed, 1 failed/killed/timeout/expired (including result_invalid), 2 needs a person, 3 still waiting after --timeout.
|
|
12
|
+
export default class KortexPlaybookCommand {
|
|
13
|
+
validator = new PlaybookValidator();
|
|
14
|
+
// The Workforce methods come with @ptkl/sdk MIN_SDK_VERSION. An older install would fail with
|
|
15
|
+
// "x is not a function", so say what to do instead.
|
|
16
|
+
client(profile) {
|
|
17
|
+
const client = kortexClient(profile);
|
|
18
|
+
if (typeof client.listPlaybooks !== 'function' || typeof client.checkWorkforceRule !== 'function') {
|
|
19
|
+
throw new Error(`This version of ptkl was installed with an older @ptkl/sdk that cannot manage playbooks. Update ptkl (it needs @ptkl/sdk ${MIN_SDK_VERSION} or newer).`);
|
|
20
|
+
}
|
|
21
|
+
return client;
|
|
22
|
+
}
|
|
23
|
+
register() {
|
|
24
|
+
const playbook = new Command('playbook')
|
|
25
|
+
.description('Manage Workforce playbooks as files: pull, edit, validate, push, deploy, run');
|
|
26
|
+
playbook.addCommand(this.list());
|
|
27
|
+
playbook.addCommand(this.get());
|
|
28
|
+
playbook.addCommand(this.versions());
|
|
29
|
+
playbook.addCommand(this.pull());
|
|
30
|
+
playbook.addCommand(this.validate());
|
|
31
|
+
playbook.addCommand(this.ruleCheck());
|
|
32
|
+
playbook.addCommand(this.push());
|
|
33
|
+
playbook.addCommand(this.deploy());
|
|
34
|
+
playbook.addCommand(this.rollback());
|
|
35
|
+
playbook.addCommand(this.deployments());
|
|
36
|
+
playbook.addCommand(this.run());
|
|
37
|
+
playbook.addCommand(this.runs());
|
|
38
|
+
playbook.addCommand(this.runGet());
|
|
39
|
+
return playbook;
|
|
40
|
+
}
|
|
41
|
+
list() {
|
|
42
|
+
return registerCommand(new Command('list')
|
|
43
|
+
.description('List playbooks')
|
|
44
|
+
.option('-p, --page <page>', 'Page number')
|
|
45
|
+
.option('-l, --limit <limit>', 'Page size')).action(withProfile(async (profile, opts) => {
|
|
46
|
+
return (await this.client(profile).listPlaybooks(this.paging(opts))).data;
|
|
47
|
+
}));
|
|
48
|
+
}
|
|
49
|
+
get() {
|
|
50
|
+
return registerCommand(new Command('get')
|
|
51
|
+
.description('Show a playbook and which version runs in dev and live')
|
|
52
|
+
.requiredOption('-u, --uuid <uuid>', 'Playbook UUID')).action(withProfile(async (profile, opts) => {
|
|
53
|
+
return (await this.client(profile).getPlaybook(opts.uuid)).data;
|
|
54
|
+
}));
|
|
55
|
+
}
|
|
56
|
+
versions() {
|
|
57
|
+
return registerCommand(new Command('versions')
|
|
58
|
+
.description('List the saved versions of a playbook')
|
|
59
|
+
.requiredOption('-u, --uuid <uuid>', 'Playbook UUID')).action(withProfile(async (profile, opts) => {
|
|
60
|
+
return (await this.client(profile).listPlaybookVersions(opts.uuid)).data;
|
|
61
|
+
}));
|
|
62
|
+
}
|
|
63
|
+
// Plain Command (not registerCommand): `-o` here is the playbook file, not the output flag.
|
|
64
|
+
pull() {
|
|
65
|
+
return new Command('pull')
|
|
66
|
+
.description('Write a playbook to a JSON file ({uuid, name, description, version, graph}); uses the live, else dev, else newest version')
|
|
67
|
+
.requiredOption('-u, --uuid <uuid>', 'Playbook UUID')
|
|
68
|
+
.option('--version <version>', 'Version to pull (default: deployed in live, else dev, else the newest)')
|
|
69
|
+
.option('-o, --output <file>', 'File to write (default: print to stdout)')
|
|
70
|
+
.action(withProfile(async (profile, opts) => {
|
|
71
|
+
const client = this.client(profile);
|
|
72
|
+
const pb = (await client.getPlaybook(opts.uuid)).data;
|
|
73
|
+
let version = opts.version || pb.live_version || pb.dev_version;
|
|
74
|
+
if (!version) {
|
|
75
|
+
const all = (await client.listPlaybookVersions(opts.uuid)).data.data ?? [];
|
|
76
|
+
if (all.length === 0)
|
|
77
|
+
throw new Error('This playbook has no versions.');
|
|
78
|
+
version = [...all].sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)))[0].version;
|
|
79
|
+
}
|
|
80
|
+
const v = (await client.getPlaybookVersion(opts.uuid, version)).data;
|
|
81
|
+
const file = {
|
|
82
|
+
uuid: pb.uuid,
|
|
83
|
+
name: pb.name,
|
|
84
|
+
description: pb.description ?? '',
|
|
85
|
+
version: v.version,
|
|
86
|
+
graph: v.graph,
|
|
87
|
+
};
|
|
88
|
+
const text = JSON.stringify(file, null, 2) + '\n';
|
|
89
|
+
if (opts.output) {
|
|
90
|
+
writeFileSync(opts.output, text);
|
|
91
|
+
console.log(`Wrote ${opts.output} (${pb.name}, version ${v.version}).`);
|
|
92
|
+
}
|
|
93
|
+
else {
|
|
94
|
+
process.stdout.write(text);
|
|
95
|
+
}
|
|
96
|
+
}));
|
|
97
|
+
}
|
|
98
|
+
// Local checks only (rule syntax is the server's to check: use rule-check): the server validates a saved version, so checking a draft there would
|
|
99
|
+
// mean pushing it first. With -u and --version it also asks the server about that saved version.
|
|
100
|
+
validate() {
|
|
101
|
+
return new Command('validate')
|
|
102
|
+
.description('Check a playbook file for problems (offline; the syntax of rules is only checked by the server, see rule-check). Exits 1 when there are problems')
|
|
103
|
+
.option('-f, --file <file>', 'Playbook file')
|
|
104
|
+
.option('-u, --uuid <uuid>', 'With --version, also ask the server to check that saved version (it also checks agents)')
|
|
105
|
+
.option('--version <version>', 'Saved version to check on the server')
|
|
106
|
+
.action(withProfile(async (profile, opts) => {
|
|
107
|
+
if (!opts.file && !(opts.uuid && opts.version)) {
|
|
108
|
+
throw new Error('Pass -f <file>, or -u <uuid> with --version.');
|
|
109
|
+
}
|
|
110
|
+
let problems = [];
|
|
111
|
+
let summary = '';
|
|
112
|
+
if (opts.file) {
|
|
113
|
+
const file = this.readFile(opts.file);
|
|
114
|
+
problems = this.validator.validate(file.graph);
|
|
115
|
+
summary = `${file.graph?.nodes?.length ?? 0} steps, ${file.graph?.edges?.length ?? 0} lines`;
|
|
116
|
+
}
|
|
117
|
+
if (opts.uuid && opts.version) {
|
|
118
|
+
const res = (await this.client(profile).validatePlaybook(opts.uuid, opts.version)).data;
|
|
119
|
+
problems = [...problems, ...(res.problems ?? [])];
|
|
120
|
+
}
|
|
121
|
+
if (problems.length === 0) {
|
|
122
|
+
console.log(`No problems found${summary ? ` (${summary})` : ''}.`);
|
|
123
|
+
return;
|
|
124
|
+
}
|
|
125
|
+
console.error(`${problems.length} problem${problems.length === 1 ? '' : 's'} found:`);
|
|
126
|
+
for (const p of problems)
|
|
127
|
+
console.error(` - ${p.message}${p.field ? ` (field: ${p.field})` : ''}`);
|
|
128
|
+
process.exitCode = 1;
|
|
129
|
+
}));
|
|
130
|
+
}
|
|
131
|
+
// Plain Command: `--input` is a file. Only the server can read a rule's syntax, so this asks it.
|
|
132
|
+
ruleCheck() {
|
|
133
|
+
return new Command('rule-check')
|
|
134
|
+
.description('Check one rule of a condition that decides by rules, and optionally try it on a sample input. The server checks the rule syntax; `playbook validate` does not. Exits 1 when the rule is not valid or cannot give an answer')
|
|
135
|
+
.requiredOption('--when <expression>', `The rule, in CEL syntax over input, at most ${MAX_RULE_LENGTH} characters, e.g. 'input.amount > 500 && input.currency == "RSD"'`)
|
|
136
|
+
.option('--input <file>', 'JSON file with a sample input to try the rule on (at most 64 KB)')
|
|
137
|
+
.action(withProfile(async (profile, opts) => {
|
|
138
|
+
const client = this.client(profile);
|
|
139
|
+
const body = { when: opts.when };
|
|
140
|
+
if (opts.input)
|
|
141
|
+
body.input = this.readJSON(opts.input);
|
|
142
|
+
const res = await client.checkWorkforceRule(body);
|
|
143
|
+
const out = res.data;
|
|
144
|
+
if (!out.valid) {
|
|
145
|
+
console.error(`The rule is not valid: ${out.message}`);
|
|
146
|
+
process.exitCode = 1;
|
|
147
|
+
}
|
|
148
|
+
else if (out.error) {
|
|
149
|
+
console.error(`The rule is valid, but it gives no answer for this input: ${out.error}`);
|
|
150
|
+
process.exitCode = 1;
|
|
151
|
+
}
|
|
152
|
+
else if (typeof out.result === 'boolean') {
|
|
153
|
+
console.log(`The rule is valid. For this input it is ${out.result}.`);
|
|
154
|
+
}
|
|
155
|
+
else {
|
|
156
|
+
console.log('The rule is valid.');
|
|
157
|
+
}
|
|
158
|
+
}));
|
|
159
|
+
}
|
|
160
|
+
push() {
|
|
161
|
+
return new Command('push')
|
|
162
|
+
.description('Create the playbook (no uuid) or save the file as a new version of it')
|
|
163
|
+
.requiredOption('-f, --file <file>', 'Playbook file')
|
|
164
|
+
.option('-u, --uuid <uuid>', 'Playbook to add a version to (default: "uuid" in the file)')
|
|
165
|
+
.option('--version <version>', 'Name for the new version (default: the newest version with its patch number plus one, e.g. 0.1.0 -> 0.1.1)')
|
|
166
|
+
.option('--note <note>', 'Note saved with the version')
|
|
167
|
+
.action(withProfile(async (profile, opts) => {
|
|
168
|
+
const file = this.readFile(opts.file);
|
|
169
|
+
const problems = this.validator.validate(file.graph);
|
|
170
|
+
if (problems.length > 0) {
|
|
171
|
+
console.error(`Not pushed. ${problems.length} problem${problems.length === 1 ? '' : 's'} found:`);
|
|
172
|
+
for (const p of problems)
|
|
173
|
+
console.error(` - ${p.message}${p.field ? ` (field: ${p.field})` : ''}`);
|
|
174
|
+
process.exitCode = 1;
|
|
175
|
+
return;
|
|
176
|
+
}
|
|
177
|
+
const client = this.client(profile);
|
|
178
|
+
const uuid = opts.uuid || file.uuid;
|
|
179
|
+
let playbookUUID;
|
|
180
|
+
let versionName;
|
|
181
|
+
if (!uuid) {
|
|
182
|
+
if (!file.name)
|
|
183
|
+
throw new Error('The file needs a "name" to create a playbook.');
|
|
184
|
+
const created = (await client.createPlaybook({
|
|
185
|
+
name: file.name,
|
|
186
|
+
description: file.description,
|
|
187
|
+
version: opts.version || file.version || undefined,
|
|
188
|
+
})).data;
|
|
189
|
+
playbookUUID = created.uuid;
|
|
190
|
+
versionName = opts.version || file.version || created.dev_version || '0.1.0';
|
|
191
|
+
console.log(`Created playbook ${playbookUUID}`);
|
|
192
|
+
}
|
|
193
|
+
else {
|
|
194
|
+
playbookUUID = uuid;
|
|
195
|
+
const name = opts.version || await this.nextVersionName(client, uuid);
|
|
196
|
+
const created = (await client.createPlaybookVersion(uuid, {
|
|
197
|
+
version: name,
|
|
198
|
+
note: opts.note || undefined,
|
|
199
|
+
})).data;
|
|
200
|
+
versionName = created?.version ?? name;
|
|
201
|
+
}
|
|
202
|
+
let saved;
|
|
203
|
+
try {
|
|
204
|
+
saved = (await client.savePlaybookVersion(playbookUUID, versionName, {
|
|
205
|
+
graph: file.graph,
|
|
206
|
+
note: opts.note || undefined,
|
|
207
|
+
})).data;
|
|
208
|
+
}
|
|
209
|
+
catch (e) {
|
|
210
|
+
// The playbook or version already exists; say so, so a retry adds to it instead of duplicating it.
|
|
211
|
+
console.error(`The drawing was not saved. Playbook ${playbookUUID}, version ${versionName} exists and is empty. Fix the file and run push again with -u ${playbookUUID}.`);
|
|
212
|
+
throw e;
|
|
213
|
+
}
|
|
214
|
+
console.log(`Saved version ${saved?.version ?? versionName} of ${playbookUUID}`);
|
|
215
|
+
}));
|
|
216
|
+
}
|
|
217
|
+
deploy() {
|
|
218
|
+
return registerCommand(new Command('deploy')
|
|
219
|
+
.description('Put a version to work in dev or live')
|
|
220
|
+
.requiredOption('-u, --uuid <uuid>', 'Playbook UUID')
|
|
221
|
+
.requiredOption('--version <version>', 'Version to deploy')).action(withProfile(async (profile, opts) => {
|
|
222
|
+
this.checkEnv(opts.env);
|
|
223
|
+
return (await this.client(profile).deployPlaybook(opts.uuid, { version: opts.version, env: opts.env })).data;
|
|
224
|
+
}));
|
|
225
|
+
}
|
|
226
|
+
rollback() {
|
|
227
|
+
return registerCommand(new Command('rollback')
|
|
228
|
+
.description('Go back to the previous version in dev or live')
|
|
229
|
+
.requiredOption('-u, --uuid <uuid>', 'Playbook UUID')).action(withProfile(async (profile, opts) => {
|
|
230
|
+
this.checkEnv(opts.env);
|
|
231
|
+
return (await this.client(profile).rollbackPlaybook(opts.uuid, { env: opts.env })).data;
|
|
232
|
+
}));
|
|
233
|
+
}
|
|
234
|
+
deployments() {
|
|
235
|
+
return registerCommand(new Command('deployments')
|
|
236
|
+
.description('List the deploys and rollbacks of a playbook')
|
|
237
|
+
.requiredOption('-u, --uuid <uuid>', 'Playbook UUID')
|
|
238
|
+
.option('-p, --page <page>', 'Page number')
|
|
239
|
+
.option('-l, --limit <limit>', 'Page size')).action(withProfile(async (profile, opts) => {
|
|
240
|
+
return (await this.client(profile).listPlaybookDeployments(opts.uuid, this.paging(opts))).data;
|
|
241
|
+
}));
|
|
242
|
+
}
|
|
243
|
+
// Plain Command: `-f`/`-o` are not needed here and `--input` is a file.
|
|
244
|
+
run() {
|
|
245
|
+
return new Command('run')
|
|
246
|
+
.description('Start a run of the version deployed to --env (default dev). Exit: 0 done, 1 failed, 2 needs a person, 3 still waiting after --timeout (with --wait)')
|
|
247
|
+
.requiredOption('-u, --uuid <uuid>', 'Playbook UUID')
|
|
248
|
+
.option('--env <env>', 'dev | live', 'dev')
|
|
249
|
+
.option('--instructions <text>', 'Instructions for this run')
|
|
250
|
+
.option('--input <file>', 'JSON file passed to the run as input')
|
|
251
|
+
.option('--wait', 'Wait until the run ends or needs a person, then print the outcome')
|
|
252
|
+
.option('--interval <seconds>', 'Seconds between checks with --wait', '3')
|
|
253
|
+
.option('--timeout <seconds>', 'Stop waiting after this long (0 = no limit)', '0')
|
|
254
|
+
.action(withProfile(async (profile, opts) => {
|
|
255
|
+
this.checkEnv(opts.env);
|
|
256
|
+
const client = this.client(profile);
|
|
257
|
+
const body = { env: opts.env };
|
|
258
|
+
if (opts.instructions)
|
|
259
|
+
body.instructions = opts.instructions;
|
|
260
|
+
if (opts.input)
|
|
261
|
+
body.input = this.readJSON(opts.input);
|
|
262
|
+
const started = (await client.startPlaybookRun(opts.uuid, body)).data;
|
|
263
|
+
console.log(`Run ${started.uuid} ${started.status}`);
|
|
264
|
+
if (!opts.wait)
|
|
265
|
+
return;
|
|
266
|
+
const seconds = Number(opts.interval);
|
|
267
|
+
if (!Number.isFinite(seconds))
|
|
268
|
+
throw new Error('--interval must be a number of seconds.');
|
|
269
|
+
const interval = Math.max(1, seconds) * 1000;
|
|
270
|
+
const limit = Number(opts.timeout) * 1000;
|
|
271
|
+
if (!Number.isFinite(limit) || limit < 0)
|
|
272
|
+
throw new Error('--timeout must be a number of seconds (0 = no limit).');
|
|
273
|
+
const t0 = Date.now();
|
|
274
|
+
let detail = await this.pollRun(client, started.uuid, interval);
|
|
275
|
+
while (!DONE_STATUSES.includes(detail.run.status) && !NEEDS_PERSON_STATUSES.includes(detail.run.status)) {
|
|
276
|
+
if (limit > 0 && Date.now() - t0 > limit) {
|
|
277
|
+
console.error(`Still ${detail.run.status} after ${opts.timeout}s. Check with: ptkl kortex playbook run-get -u ${started.uuid}`);
|
|
278
|
+
process.exitCode = 3;
|
|
279
|
+
return;
|
|
280
|
+
}
|
|
281
|
+
await new Promise((r) => setTimeout(r, interval));
|
|
282
|
+
detail = await this.pollRun(client, started.uuid, interval);
|
|
283
|
+
}
|
|
284
|
+
this.printOutcome(detail);
|
|
285
|
+
}));
|
|
286
|
+
}
|
|
287
|
+
// A network error or a 5xx while waiting is retried a few times: the run itself is still going.
|
|
288
|
+
async pollRun(client, uuid, interval) {
|
|
289
|
+
for (let attempt = 1;; attempt++) {
|
|
290
|
+
try {
|
|
291
|
+
return (await client.getRun(uuid)).data;
|
|
292
|
+
}
|
|
293
|
+
catch (e) {
|
|
294
|
+
const status = e?.response?.status;
|
|
295
|
+
const transient = !e?.response || status >= 500;
|
|
296
|
+
if (!transient || attempt >= 5)
|
|
297
|
+
throw e;
|
|
298
|
+
await new Promise((r) => setTimeout(r, interval));
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
runs() {
|
|
303
|
+
return registerCommand(new Command('runs')
|
|
304
|
+
.description('List runs, newest first')
|
|
305
|
+
.option('--playbook <uuid>', 'Only runs of this playbook')
|
|
306
|
+
.option('--status <status>', 'Only runs in this status (queued, running, awaiting_approval, awaiting_answer, paused, completed, failed, killed, timeout, expired)')
|
|
307
|
+
.option('-p, --page <page>', 'Page number')
|
|
308
|
+
.option('-l, --limit <limit>', 'Page size')).action(withProfile(async (profile, opts) => {
|
|
309
|
+
const params = { ...this.paging(opts), playbook: opts.playbook, status: opts.status };
|
|
310
|
+
return (await this.client(profile).listRuns(params)).data;
|
|
311
|
+
}));
|
|
312
|
+
}
|
|
313
|
+
runGet() {
|
|
314
|
+
return registerCommand(new Command('run-get')
|
|
315
|
+
.description('Show a run with its steps')
|
|
316
|
+
.requiredOption('-u, --uuid <uuid>', 'Run UUID')).action(withProfile(async (profile, opts) => {
|
|
317
|
+
const detail = (await this.client(profile).getRun(opts.uuid)).data;
|
|
318
|
+
const run = detail?.run;
|
|
319
|
+
// The default print cuts nested objects short, so show the result in full.
|
|
320
|
+
if (!opts.format && !opts.output && run?.result && Object.keys(run.result).length > 0) {
|
|
321
|
+
console.log('Result:');
|
|
322
|
+
console.log(JSON.stringify(run.result, null, 2));
|
|
323
|
+
}
|
|
324
|
+
if (run?.stop_reason === 'result_invalid')
|
|
325
|
+
process.exitCode = 1;
|
|
326
|
+
return detail;
|
|
327
|
+
}));
|
|
328
|
+
}
|
|
329
|
+
printOutcome(detail) {
|
|
330
|
+
const run = detail.run;
|
|
331
|
+
console.log(`Run ${run.uuid} ${run.status}`);
|
|
332
|
+
if (run.summary)
|
|
333
|
+
console.log(run.summary);
|
|
334
|
+
if (run.error_message)
|
|
335
|
+
console.error(run.error_message);
|
|
336
|
+
if (run.result && Object.keys(run.result).length > 0) {
|
|
337
|
+
console.log('Result:');
|
|
338
|
+
console.log(JSON.stringify(run.result, null, 2));
|
|
339
|
+
}
|
|
340
|
+
if (NEEDS_PERSON_STATUSES.includes(run.status)) {
|
|
341
|
+
const waiting = [...detail.steps].reverse().find((s) => (s.kind === 'approval' || s.kind === 'question' || s.approval?.decision === 'pending') &&
|
|
342
|
+
s.status !== 'completed' && s.status !== 'denied');
|
|
343
|
+
if (waiting) {
|
|
344
|
+
console.log(`Waiting on you at step ${waiting.index}: ${waiting.label || waiting.name || waiting.kind}`);
|
|
345
|
+
}
|
|
346
|
+
else if (run.status === 'paused') {
|
|
347
|
+
console.log('The run is paused.');
|
|
348
|
+
}
|
|
349
|
+
process.exitCode = 2;
|
|
350
|
+
}
|
|
351
|
+
else if (run.status !== 'completed') {
|
|
352
|
+
process.exitCode = 1;
|
|
353
|
+
}
|
|
354
|
+
}
|
|
355
|
+
// Newest version by created_at, patch bumped; keeps bumping while the name is taken.
|
|
356
|
+
async nextVersionName(client, uuid) {
|
|
357
|
+
const all = (await client.listPlaybookVersions(uuid)).data.data ?? [];
|
|
358
|
+
if (all.length === 0)
|
|
359
|
+
throw new Error('This playbook has no versions to count from. Pass --version <name>.');
|
|
360
|
+
const newest = [...all].sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)))[0];
|
|
361
|
+
const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(newest.version);
|
|
362
|
+
if (!m)
|
|
363
|
+
throw new Error(`The newest version "${newest.version}" is not MAJOR.MINOR.PATCH, so the next name cannot be worked out. Pass --version <name>.`);
|
|
364
|
+
const taken = new Set(all.map((v) => v.version));
|
|
365
|
+
let patch = Number(m[3]) + 1;
|
|
366
|
+
while (taken.has(`${m[1]}.${m[2]}.${patch}`))
|
|
367
|
+
patch++;
|
|
368
|
+
const name = `${m[1]}.${m[2]}.${patch}`;
|
|
369
|
+
console.log(`New version name: ${name}`);
|
|
370
|
+
return name;
|
|
371
|
+
}
|
|
372
|
+
checkEnv(env) {
|
|
373
|
+
if (env !== 'dev' && env !== 'live')
|
|
374
|
+
throw new Error('--env must be dev or live.');
|
|
375
|
+
}
|
|
376
|
+
paging(opts) {
|
|
377
|
+
return {
|
|
378
|
+
page: opts.page ? Number(opts.page) : undefined,
|
|
379
|
+
limit: opts.limit ? Number(opts.limit) : undefined,
|
|
380
|
+
};
|
|
381
|
+
}
|
|
382
|
+
readJSON(path) {
|
|
383
|
+
try {
|
|
384
|
+
return JSON.parse(readFileSync(path, 'utf8'));
|
|
385
|
+
}
|
|
386
|
+
catch (err) {
|
|
387
|
+
throw new Error(`Cannot read ${path} as JSON: ${err.message}`);
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
readFile(path) {
|
|
391
|
+
const file = this.readJSON(path);
|
|
392
|
+
if (!file || typeof file !== 'object' || !file.graph)
|
|
393
|
+
throw new Error(`${path} is not a playbook file (no "graph").`);
|
|
394
|
+
return file;
|
|
395
|
+
}
|
|
396
|
+
}
|
|
@@ -29,6 +29,10 @@ describe("apiErrorMessage", () => {
|
|
|
29
29
|
expect(apiErrorMessage(http(400, { message: "plain" }))).toBe("plain");
|
|
30
30
|
expect(apiErrorMessage(http(500, "boom"))).toBe("boom");
|
|
31
31
|
});
|
|
32
|
+
it("prints the problems of a refused deploy", () => {
|
|
33
|
+
const body = { message: "workforce: playbook version has 1 problem(s)", problems: [{ code: "agent_disabled", node_id: "s1", message: "The agent on Step \"A\" is disabled." }] };
|
|
34
|
+
expect(apiErrorMessage(http(422, body))).toBe("workforce: playbook version has 1 problem(s)\n - The agent on Step \"A\" is disabled. (step: s1)");
|
|
35
|
+
});
|
|
32
36
|
it("falls back to the HTTP status", () => {
|
|
33
37
|
expect(apiErrorMessage(http(404, Buffer.from("")))).toBe("HTTP 404");
|
|
34
38
|
expect(apiErrorMessage(http(502, {}))).toBe("HTTP 502");
|
package/dist/lib/apiError.js
CHANGED
|
@@ -103,6 +103,17 @@ function reauthorizeHint(data, profile) {
|
|
|
103
103
|
return `${forbiddenDetails(body)}\nThis profile's OAuth grant lacks ${lacking.join(", ")}. `
|
|
104
104
|
+ `Re-authorize it once with \`ptkl profile auth ${profile.name} --add-scope "${lacking.join(",")}"\` (or create a new one with \`ptkl profile new\`).`;
|
|
105
105
|
}
|
|
106
|
+
/** A refused deploy or rollback answers 422 with the list of problems; print each one after the message. */
|
|
107
|
+
function withProblems(message, data) {
|
|
108
|
+
const body = parseBody(data);
|
|
109
|
+
if (!message || !Array.isArray(body?.problems) || body.problems.length === 0)
|
|
110
|
+
return message;
|
|
111
|
+
const lines = body.problems.map((p) => {
|
|
112
|
+
const where = [p?.node_id ? `step: ${p.node_id}` : "", p?.field ? `field: ${p.field}` : ""].filter(Boolean).join(", ");
|
|
113
|
+
return ` - ${p?.message ?? p?.code ?? "problem"}${where ? ` (${where})` : ""}`;
|
|
114
|
+
});
|
|
115
|
+
return `${message}\n${lines.join("\n")}`;
|
|
116
|
+
}
|
|
106
117
|
/** One-line, user-facing text for a failed command. Never includes headers, request config or tokens. */
|
|
107
118
|
export function apiErrorMessage(err, profile) {
|
|
108
119
|
const reauth = err?.response?.status === 403 ? reauthorizeHint(err.response.data, profile) : undefined;
|
|
@@ -113,7 +124,7 @@ export function apiErrorMessage(err, profile) {
|
|
|
113
124
|
return hint;
|
|
114
125
|
const response = err?.response;
|
|
115
126
|
if (response) {
|
|
116
|
-
return forbiddenDetails(response.data) ?? bodyMessage(response.data) ?? `HTTP ${response.status}`;
|
|
127
|
+
return forbiddenDetails(response.data) ?? withProblems(bodyMessage(response.data), response.data) ?? `HTTP ${response.status}`;
|
|
117
128
|
}
|
|
118
129
|
return err?.message || String(err);
|
|
119
130
|
}
|
|
@@ -64,7 +64,7 @@ describe('SSE parsing (current protocol)', () => {
|
|
|
64
64
|
it('parses multiple events', async () => {
|
|
65
65
|
const stream = stringToStream('event: content_delta\ndata: {"delta":"Hello"}\n\n' +
|
|
66
66
|
'event: content_delta\ndata: {"delta":" world"}\n\n' +
|
|
67
|
-
'event: message_complete\ndata: {"agent_name":"
|
|
67
|
+
'event: message_complete\ndata: {"agent_name":"Prota"}\n\n');
|
|
68
68
|
const events = [];
|
|
69
69
|
for await (const e of parseSSE(stream))
|
|
70
70
|
events.push(e);
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
import { describe, it, expect } from 'vitest';
|
|
2
|
+
import PlaybookValidator from '../playbookValidator.js';
|
|
3
|
+
const agent = 'ag1';
|
|
4
|
+
const graph = (cond, edges) => ({
|
|
5
|
+
nodes: [
|
|
6
|
+
{ id: 'read', kind: 'instruction', text: 'Read', agent_uuid: agent },
|
|
7
|
+
{ id: 'route', kind: 'condition', title: 'Route', text: '', agent_uuid: '', decide_by: 'rules', ...cond },
|
|
8
|
+
{ id: 'sef', kind: 'instruction', text: 'Send', agent_uuid: agent },
|
|
9
|
+
{ id: 'pdf', kind: 'instruction', text: 'Make', agent_uuid: agent },
|
|
10
|
+
],
|
|
11
|
+
edges: [{ from: 'read', to: 'route' }, ...edges],
|
|
12
|
+
});
|
|
13
|
+
const sef = { from: 'route', to: 'sef', name: 'sef', when: 'input.amount > 500 && input.currency == "RSD"' };
|
|
14
|
+
const pdf = { from: 'route', to: 'pdf', name: 'pdf', otherwise: true };
|
|
15
|
+
const run = (g) => new PlaybookValidator().validate(g).map((p) => [p.code, p.message]);
|
|
16
|
+
describe('rules conditions', () => {
|
|
17
|
+
it('accepts a valid one without text or agent', () => expect(run(graph({}, [sef, pdf]))).toEqual([]));
|
|
18
|
+
it('needs when', () => expect(run(graph({}, [{ ...sef, when: ' ' }, pdf]))).toEqual([
|
|
19
|
+
['rules_need_when', 'The line "sef" out of Step "Route" has no rule; give it a rule or mark it "otherwise".'],
|
|
20
|
+
]));
|
|
21
|
+
it('refuses otherwise twice', () => expect(run(graph({}, [{ ...sef, when: undefined, otherwise: true }, pdf]))).toEqual([
|
|
22
|
+
['rules_otherwise_twice', 'More than one line out of Step "Route" is "otherwise"; only one can be.'],
|
|
23
|
+
]));
|
|
24
|
+
it('refuses when and otherwise', () => expect(run(graph({}, [sef, { ...pdf, when: 'true' }]))).toEqual([
|
|
25
|
+
['rules_when_and_otherwise', 'The line "pdf" out of Step "Route" has both a rule and "otherwise"; use one of them.'],
|
|
26
|
+
]));
|
|
27
|
+
it('refuses an agent', () => expect(run(graph({ agent_uuid: agent }, [sef, pdf]))).toEqual([
|
|
28
|
+
['rules_no_agent', 'Step "Route" decides by rules, so it has no agent.'],
|
|
29
|
+
]));
|
|
30
|
+
it('refuses a rule over 1000 characters', () => expect(run(graph({}, [{ ...sef, when: 'input.a == "' + 'x'.repeat(1000) + '"' }, pdf]))).toEqual([
|
|
31
|
+
['rules_when_invalid', 'The rule on line "sef" out of Step "Route" is not valid: the rule is longer than 1000 characters.'],
|
|
32
|
+
]));
|
|
33
|
+
it('refuses more than 20 lines', () => {
|
|
34
|
+
const g = graph({}, []);
|
|
35
|
+
const edges = [];
|
|
36
|
+
for (let i = 0; i < 21; i++) {
|
|
37
|
+
g.nodes.push({ id: `t${i}`, kind: 'instruction', text: 'x', agent_uuid: agent });
|
|
38
|
+
edges.push({ from: 'route', to: `t${i}`, name: `l${i}`, when: 'true' });
|
|
39
|
+
}
|
|
40
|
+
g.edges.push(...edges);
|
|
41
|
+
g.nodes = g.nodes.filter((n) => n.id !== 'sef' && n.id !== 'pdf');
|
|
42
|
+
expect(run(g)).toEqual([['rules_too_many_lines', 'Step "Route" has 21 lines out; a choice by rules can have at most 20.']]);
|
|
43
|
+
});
|
|
44
|
+
it('refuses a rule on an agent condition', () => {
|
|
45
|
+
const g = graph({ decide_by: 'agent', text: 'Pick', agent_uuid: agent }, [sef, pdf]);
|
|
46
|
+
expect(run(g)).toEqual([
|
|
47
|
+
['when_on_agent_condition', 'The line "sef" out of Step "Route" has a rule, but only a choice that decides by rules can have one.'],
|
|
48
|
+
['when_on_agent_condition', 'The line "pdf" out of Step "Route" has a rule, but only a choice that decides by rules can have one.'],
|
|
49
|
+
]);
|
|
50
|
+
});
|
|
51
|
+
it('refuses a bad decide_by', () => {
|
|
52
|
+
expect(run(graph({ decide_by: 'dice', text: 'Pick', agent_uuid: agent }, [{ from: 'route', to: 'sef', name: 'a' }, { from: 'route', to: 'pdf', name: 'b' }]))).toEqual([
|
|
53
|
+
['bad_decide_by', 'Step "Route" decides by "dice"; it must be "agent" or "rules".'],
|
|
54
|
+
]);
|
|
55
|
+
const g = graph({}, [sef, pdf]);
|
|
56
|
+
g.nodes[0].decide_by = 'rules';
|
|
57
|
+
expect(run(g)).toEqual([['bad_decide_by', 'Step "read" is not a choice, so it cannot decide by rules.']]);
|
|
58
|
+
});
|
|
59
|
+
});
|
|
60
|
+
describe('rules on the version', () => {
|
|
61
|
+
const base = () => ({
|
|
62
|
+
nodes: [
|
|
63
|
+
{ id: 'a', kind: 'instruction', text: 'x', agent_uuid: agent },
|
|
64
|
+
{ id: 'c', kind: 'condition', title: 'Where', text: '', agent_uuid: '', decide_by: 'rules' },
|
|
65
|
+
{ id: 's', kind: 'instruction', text: 'x', agent_uuid: agent },
|
|
66
|
+
{ id: 'p', kind: 'instruction', text: 'x', agent_uuid: agent },
|
|
67
|
+
],
|
|
68
|
+
edges: [{ from: 'a', to: 'c' }, { from: 'c', to: 's', name: 's', when: 'true' }, { from: 'c', to: 'p', name: 'p', otherwise: true }],
|
|
69
|
+
rules: [],
|
|
70
|
+
});
|
|
71
|
+
const withRules = (...rules) => ({ ...base(), rules });
|
|
72
|
+
const r = (id, title = 'T', rule = 'R', extra = {}) => ({ id, title, rule, ...extra });
|
|
73
|
+
const out = (g) => new PlaybookValidator().validate(g).map((p) => [p.code, p.field, p.message]);
|
|
74
|
+
it('accepts none, and good ones on a step and on every step', () => {
|
|
75
|
+
expect(out(base())).toEqual([]);
|
|
76
|
+
expect(out(withRules(r('1'), r('2', 'T', 'R', { step: 'a' })))).toEqual([]);
|
|
77
|
+
});
|
|
78
|
+
it('needs text and a title', () => expect(out(withRules(r('1'), r('2', '', ' ')))).toEqual([
|
|
79
|
+
['rule_no_text', 'rules[1].rule', 'Rule 2 has no text.'],
|
|
80
|
+
['rule_no_title', 'rules[1].title', 'Rule 2 has no title.'],
|
|
81
|
+
]));
|
|
82
|
+
it('counts characters, not bytes', () => {
|
|
83
|
+
expect(out(withRules(r('1', 'T', 'é'.repeat(1000))))).toEqual([]);
|
|
84
|
+
expect(out(withRules(r('1', 'T', 'é'.repeat(1001))))).toEqual([['rule_too_long', 'rules[0].rule', 'Rule 1 is longer than 1000 characters.']]);
|
|
85
|
+
});
|
|
86
|
+
it('limits the title and the reason', () => expect(out(withRules(r('1', 't'.repeat(121), 'R', { why: 'w'.repeat(1001) })))).toEqual([
|
|
87
|
+
['rule_title_too_long', 'rules[0].title', 'The title of rule 1 is longer than 120 characters.'],
|
|
88
|
+
['rule_why_too_long', 'rules[0].why', 'The reason on rule 1 is longer than 1000 characters.'],
|
|
89
|
+
]));
|
|
90
|
+
it('allows at most 20', () => expect(out(withRules(...Array.from({ length: 21 }, (_, i) => r(String(i)))))).toEqual([
|
|
91
|
+
['too_many_rules', 'rules', 'There are 21 rules; at most 20 are allowed.'],
|
|
92
|
+
]));
|
|
93
|
+
it('refuses an unknown step and a rules condition', () => expect(out(withRules(r('1', 'T', 'R', { step: 'zz' }), r('2', 'T', 'R', { step: 'c' })))).toEqual([
|
|
94
|
+
['rule_unknown_step', 'rules[0].step', 'Rule 1 is for the step "zz", but there is no such step.'],
|
|
95
|
+
['rule_on_rules_condition', 'rules[1].step', 'Rule 2 is for Step "Where", which decides by rules and never reads rules.'],
|
|
96
|
+
]));
|
|
97
|
+
it('refuses an id used twice', () => expect(out(withRules(r('1'), r('1', 'T2', 'R2')))).toEqual([
|
|
98
|
+
['rule_id_twice', 'rules[1].id', 'Two rules share the id "1".'],
|
|
99
|
+
]));
|
|
100
|
+
});
|
|
101
|
+
describe('checks the server applies on its own', () => {
|
|
102
|
+
const v = new PlaybookValidator();
|
|
103
|
+
const two = (a) => ({ nodes: [{ id: 'a', kind: 'instruction', text: 'x', agent_uuid: 'g', ...a }, { id: 'b', kind: 'instruction', text: 'y', agent_uuid: 'g' }], edges: [{ from: 'a', to: 'b' }] });
|
|
104
|
+
it('compares to the empty string exactly, like the server', () => {
|
|
105
|
+
expect(v.validate(two({ text: ' ' }))).toEqual([]);
|
|
106
|
+
});
|
|
107
|
+
it('refuses what a save refuses', () => {
|
|
108
|
+
const codes = (g) => v.validate(g).map((p) => p.code);
|
|
109
|
+
expect(codes(two({ text: 'x'.repeat(8001) }))).toContain('too_large');
|
|
110
|
+
expect(codes(two({ title: 'x'.repeat(201) }))).toContain('too_large');
|
|
111
|
+
expect(codes({ ...two({}), rules: Array.from({ length: 101 }, () => ({ title: 't', rule: 'r' })) })).toContain('too_large');
|
|
112
|
+
});
|
|
113
|
+
it('reports a duplicate id once and checks only the first step with it', () => {
|
|
114
|
+
const g = two({});
|
|
115
|
+
g.nodes.push({ id: 'a', kind: 'instruction', text: '', agent_uuid: '' }, { id: 'a', kind: 'instruction', text: '', agent_uuid: '' });
|
|
116
|
+
const ps = v.validate(g);
|
|
117
|
+
expect(ps.filter((p) => p.code === 'duplicate_node')).toHaveLength(1);
|
|
118
|
+
expect(ps.filter((p) => p.code === 'empty_text' || p.code === 'no_agent')).toEqual([]);
|
|
119
|
+
});
|
|
120
|
+
});
|
|
@@ -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
|
+
});
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { describe, it, expect } from 'vitest';
|
|
2
|
+
import { readFileSync } from 'fs';
|
|
3
|
+
import { join, dirname } from 'path';
|
|
4
|
+
import { fileURLToPath } from 'url';
|
|
5
|
+
import PlaybookValidator from '../playbookValidator.js';
|
|
6
|
+
import ResultSchemaChecker from '../resultSchemaChecker.js';
|
|
7
|
+
const dir = dirname(fileURLToPath(import.meta.url));
|
|
8
|
+
// Copied verbatim from Kortex (commit f35ce00); see fixtures/result_schema_cases.README.md.
|
|
9
|
+
const cases = JSON.parse(readFileSync(join(dir, 'fixtures', 'result_schema_cases.json'), 'utf8'));
|
|
10
|
+
describe('result schema cases (copied from Kortex)', () => {
|
|
11
|
+
it('has the whole file', () => expect(cases.length).toBeGreaterThanOrEqual(55));
|
|
12
|
+
for (const tc of cases) {
|
|
13
|
+
it(tc.name, () => {
|
|
14
|
+
const got = new ResultSchemaChecker().problems(tc.schema);
|
|
15
|
+
expect(got.length === 0).toBe(tc.valid);
|
|
16
|
+
expect(got).toEqual(tc.problems ?? []);
|
|
17
|
+
});
|
|
18
|
+
it(`${tc.name}: through the playbook validator`, () => {
|
|
19
|
+
const graph = {
|
|
20
|
+
nodes: [{ id: 'a', kind: 'instruction', title: 'Done', text: 't', agent_uuid: 'x', result_schema: tc.schema }],
|
|
21
|
+
edges: [],
|
|
22
|
+
};
|
|
23
|
+
const got = new PlaybookValidator().validate(graph).filter((p) => p.code === 'result_schema_invalid');
|
|
24
|
+
expect(got.map((p) => p.message)).toEqual((tc.problems ?? []).slice(0, 20).map((p) => `Step "Done": ${p.message}`));
|
|
25
|
+
expect(got.map((p) => p.field)).toEqual((tc.problems ?? []).slice(0, 20).map((p) => p.field));
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
it('reports at most 20 problems per step', () => {
|
|
29
|
+
const properties = {};
|
|
30
|
+
for (let i = 0; i < 30; i++)
|
|
31
|
+
properties[`f${String(i).padStart(2, '0')}`] = { type: 'date' };
|
|
32
|
+
const graph = { nodes: [{ id: 'a', kind: 'instruction', text: 't', agent_uuid: 'x', result_schema: { type: 'object', properties } }], edges: [] };
|
|
33
|
+
const got = new PlaybookValidator().validate(graph).filter((p) => p.code === 'result_schema_invalid');
|
|
34
|
+
expect(got).toHaveLength(20);
|
|
35
|
+
expect(got[0].message).toBe(`Step "a": field 'f00': unknown type 'date'; use object, array, string, number, integer or boolean.`);
|
|
36
|
+
});
|
|
37
|
+
});
|