@ptkl/toolkit 1.4.4 → 1.6.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 +34 -1
- package/dist/commands/__tests__/capabilities.test.js +83 -0
- package/dist/commands/__tests__/componentRunAs.test.js +65 -0
- package/dist/commands/__tests__/forge-bundle-layout.test.js +58 -0
- package/dist/commands/__tests__/forge-bundle-path.test.js +29 -0
- package/dist/commands/__tests__/forge-tools.test.js +64 -0
- package/dist/commands/__tests__/forge-variables.test.js +16 -0
- package/dist/commands/__tests__/kortexPlaybook.test.js +328 -0
- package/dist/commands/__tests__/role.test.js +83 -0
- package/dist/commands/__tests__/runAs.test.js +63 -0
- package/dist/commands/__tests__/thunder.test.js +46 -0
- package/dist/commands/component.js +9 -3
- package/dist/commands/forge.js +262 -202
- package/dist/commands/functions.js +11 -5
- package/dist/commands/integrations/payments.js +11 -7
- package/dist/commands/kortex.js +8 -6
- package/dist/commands/kortexPlaybook.js +396 -0
- package/dist/commands/role.js +45 -54
- package/dist/commands/satellite.js +0 -5
- package/dist/commands/thunder.js +19 -12
- package/dist/commands/workflow.js +10 -4
- package/dist/lib/__tests__/apiError.test.js +18 -0
- package/dist/lib/__tests__/apiErrorCapabilities.test.js +23 -0
- package/dist/lib/__tests__/forgeDevKernelPlugin.test.js +34 -0
- package/dist/lib/__tests__/forgeDevServiceExec.test.js +61 -0
- package/dist/lib/__tests__/forgeDevServiceServer.test.js +113 -0
- package/dist/lib/__tests__/forgeDevToken.test.js +85 -0
- package/dist/lib/__tests__/runIdentity.test.js +101 -0
- package/dist/lib/__tests__/thunder.test.js +101 -0
- package/dist/lib/apiError.js +94 -1
- package/dist/lib/forgeDevKernelPlugin.js +90 -4
- package/dist/lib/forgeDevServiceExec.js +49 -0
- package/dist/lib/forgeDevServiceServer.js +163 -0
- package/dist/lib/forgeDevToken.js +126 -0
- 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__/resultSchemaChecker.test.js +37 -0
- package/dist/lib/kortex/playbookValidator.js +297 -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/dist/lib/oauth/ScopePreset.js +4 -3
- package/dist/lib/oauth/__tests__/oauth.test.js +6 -3
- package/dist/lib/runIdentity.js +51 -0
- package/dist/lib/thunder.js +98 -0
- package/package.json +2 -2
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
const MAX_AGE_MS = 15 * 60 * 1000;
|
|
2
|
+
/**
|
|
3
|
+
* The forge app token a dev session runs as. One mint flow shared by the browser prelude and the
|
|
4
|
+
* dev service server: preflight for the revision, then mint. With submittedSource the actor is
|
|
5
|
+
* scoped to what the developer could do and nothing more, and it is NOT refreshable — a 401
|
|
6
|
+
* means mint again (renew()), never refresh. Without it the token is a normal view session.
|
|
7
|
+
*/
|
|
8
|
+
export class ForgeDevToken {
|
|
9
|
+
appRef;
|
|
10
|
+
env;
|
|
11
|
+
userToken;
|
|
12
|
+
submittedSource;
|
|
13
|
+
host;
|
|
14
|
+
token = '';
|
|
15
|
+
mintedAt = 0;
|
|
16
|
+
revisionValue = '';
|
|
17
|
+
appUuidValue = '';
|
|
18
|
+
permissionList = [];
|
|
19
|
+
lastErr = '';
|
|
20
|
+
lastStatus = 0;
|
|
21
|
+
constructor(host, appRef, env, userToken, submittedSource = false) {
|
|
22
|
+
this.appRef = appRef;
|
|
23
|
+
this.env = env;
|
|
24
|
+
this.userToken = userToken;
|
|
25
|
+
this.submittedSource = submittedSource;
|
|
26
|
+
this.host = (host ?? '').replace(/\/$/, '');
|
|
27
|
+
}
|
|
28
|
+
get configured() {
|
|
29
|
+
return !!(this.host && this.appRef && this.userToken);
|
|
30
|
+
}
|
|
31
|
+
get revision() {
|
|
32
|
+
return this.revisionValue;
|
|
33
|
+
}
|
|
34
|
+
get permissions() {
|
|
35
|
+
return this.permissionList;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* The app's uuid, as preflight reports it. The app's own permissions are scoped by it
|
|
39
|
+
* (`<perm> forge::<uuid>`), so the page needs it to test what it holds; the deployed runtime
|
|
40
|
+
* gets it from the launch URL. Empty when preflight did not send one (an app not installed yet).
|
|
41
|
+
*/
|
|
42
|
+
get appUuid() {
|
|
43
|
+
return this.appUuidValue;
|
|
44
|
+
}
|
|
45
|
+
/** Why the last mint failed, for the caller's warning. */
|
|
46
|
+
get lastError() {
|
|
47
|
+
return this.lastErr;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* The single message `ptkl forge dev` prints when it cannot mint. States only what the response
|
|
51
|
+
* established: the `ptkl init` line appears only when the platform answered 401.
|
|
52
|
+
*/
|
|
53
|
+
failureMessage() {
|
|
54
|
+
const lines = [
|
|
55
|
+
`Could not mint the app token for ${this.appRef || '(no app)'} in ${this.env} against ${this.host || '(no host)'}: ${this.lastErr}`,
|
|
56
|
+
'The app cannot run as itself, so `ptkl forge dev` will not start.',
|
|
57
|
+
];
|
|
58
|
+
if (this.lastStatus === 401) {
|
|
59
|
+
lines.push('The stored credential was rejected by the platform; `ptkl init` will re-authenticate.');
|
|
60
|
+
}
|
|
61
|
+
return lines.join('\n');
|
|
62
|
+
}
|
|
63
|
+
/** The cached token, minted when absent or older than 15 minutes. Null when it cannot mint. */
|
|
64
|
+
async current() {
|
|
65
|
+
if (this.token && Date.now() - this.mintedAt < MAX_AGE_MS)
|
|
66
|
+
return this.token;
|
|
67
|
+
return this.renew();
|
|
68
|
+
}
|
|
69
|
+
/** Force a fresh mint. Null (with lastError set) on an expected refusal. */
|
|
70
|
+
async renew() {
|
|
71
|
+
this.lastErr = '';
|
|
72
|
+
this.lastStatus = 0;
|
|
73
|
+
if (!this.configured) {
|
|
74
|
+
this.lastErr = 'no app name, API host or profile token';
|
|
75
|
+
return null;
|
|
76
|
+
}
|
|
77
|
+
const headers = {
|
|
78
|
+
'Content-Type': 'application/json',
|
|
79
|
+
'X-Project-Env': this.env,
|
|
80
|
+
Authorization: `Bearer ${this.userToken}`,
|
|
81
|
+
};
|
|
82
|
+
const read = async (res) => {
|
|
83
|
+
const body = await res.json().catch(() => ({}));
|
|
84
|
+
if (!res.ok) {
|
|
85
|
+
this.lastStatus = res.status;
|
|
86
|
+
throw new Error((body && body.message) || `HTTP ${res.status}`);
|
|
87
|
+
}
|
|
88
|
+
return body;
|
|
89
|
+
};
|
|
90
|
+
try {
|
|
91
|
+
const preflight = await fetch(`${this.host}/luma/appservice/v1/forge/${encodeURIComponent(this.appRef)}/preflight`, { headers }).then(read);
|
|
92
|
+
const revision = typeof preflight?.revision === 'string' ? preflight.revision : '';
|
|
93
|
+
this.appUuidValue = typeof preflight?.uuid === 'string' ? preflight.uuid : '';
|
|
94
|
+
if (!revision) {
|
|
95
|
+
throw new Error(`nothing is deployed to run in ${this.env} — deploy a version for ${this.env} first`);
|
|
96
|
+
}
|
|
97
|
+
const minted = await fetch(`${this.host}/v1/system/platform/forge/token`, {
|
|
98
|
+
method: 'POST',
|
|
99
|
+
headers,
|
|
100
|
+
body: JSON.stringify({
|
|
101
|
+
app_ref: this.appRef,
|
|
102
|
+
revision,
|
|
103
|
+
...(this.submittedSource ? { submitted_source: true } : {}),
|
|
104
|
+
}),
|
|
105
|
+
}).then(read);
|
|
106
|
+
if (!minted?.token)
|
|
107
|
+
throw new Error('the platform returned no token');
|
|
108
|
+
this.token = minted.token;
|
|
109
|
+
this.revisionValue = revision;
|
|
110
|
+
this.permissionList = minted.permissions ?? [];
|
|
111
|
+
this.mintedAt = Date.now();
|
|
112
|
+
return this.token;
|
|
113
|
+
}
|
|
114
|
+
catch (err) {
|
|
115
|
+
this.token = '';
|
|
116
|
+
const msg = err?.message ?? String(err);
|
|
117
|
+
// undici reports every transport failure (DNS, refused, TLS) as a bare "fetch failed" and
|
|
118
|
+
// keeps the real reason on err.cause.
|
|
119
|
+
const cause = err?.cause ? (err.cause.code ? `${err.cause.code}: ${err.cause.message}` : err.cause.message ?? String(err.cause)) : '';
|
|
120
|
+
this.lastErr = err instanceof TypeError || err?.cause
|
|
121
|
+
? `could not reach ${this.host}: ${msg}${cause ? ` (${cause})` : ''}`
|
|
122
|
+
: msg;
|
|
123
|
+
return null;
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
}
|
|
@@ -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,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
|
+
});
|
|
@@ -0,0 +1,297 @@
|
|
|
1
|
+
// Offline structural checks for a playbook drawing. They mirror the server's graph rules
|
|
2
|
+
// (no_nodes, duplicate_node, no_start, cycle, ...) so a file can be checked before pushing.
|
|
3
|
+
// Whether an agent exists or is enabled is only known to the server and is checked on deploy.
|
|
4
|
+
// The same goes for the syntax of a rule (`when`): only the server can compile it, so use
|
|
5
|
+
// `ptkl kortex playbook rule-check` to try one. Offline, a rule is only checked to be present
|
|
6
|
+
// and not too long. The rule messages are the server's, word for word.
|
|
7
|
+
// Rules on the version (`graph.rules`) are checked here in full, with the server's messages.
|
|
8
|
+
import ResultSchemaChecker, { MAX_RESULT_PROBLEMS, goQuote } from './resultSchemaChecker.js';
|
|
9
|
+
// Limits on rules, the same as the server's.
|
|
10
|
+
export const MAX_RULE_LENGTH = 1000;
|
|
11
|
+
export const MAX_RULE_LINES = 20;
|
|
12
|
+
// Limits on a version's rules, the same as the server's.
|
|
13
|
+
export const MAX_WORK_RULE_TEXT = 1000;
|
|
14
|
+
export const MAX_WORK_RULE_TITLE = 120;
|
|
15
|
+
export const MAX_WORK_RULE_WHY = 1000;
|
|
16
|
+
export const MAX_WORK_RULES = 20;
|
|
17
|
+
// Limits a save enforces (the server's checkSize), so a file that passes here is not refused at push.
|
|
18
|
+
export const MAX_PLAYBOOK_STEPS = 200;
|
|
19
|
+
export const MAX_PLAYBOOK_LINES = 400;
|
|
20
|
+
export const MAX_STEP_TEXT_BYTES = 8000;
|
|
21
|
+
export const MAX_STEP_TITLE_BYTES = 200;
|
|
22
|
+
export const MAX_RULE_ROWS = 100;
|
|
23
|
+
export const MAX_RULE_FIELD_BYTES = 20000;
|
|
24
|
+
export default class PlaybookValidator {
|
|
25
|
+
validate(graph) {
|
|
26
|
+
const problems = [];
|
|
27
|
+
const add = (code, message, node_id) => problems.push({ code, message, node_id });
|
|
28
|
+
const checker = new ResultSchemaChecker();
|
|
29
|
+
if (!graph || typeof graph !== 'object' || !Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) {
|
|
30
|
+
add('bad_graph', 'The graph must have a "nodes" list and an "edges" list.');
|
|
31
|
+
return problems;
|
|
32
|
+
}
|
|
33
|
+
if (graph.nodes.length === 0) {
|
|
34
|
+
add('no_nodes', 'The playbook has no steps.');
|
|
35
|
+
return problems;
|
|
36
|
+
}
|
|
37
|
+
this.sizeProblems(graph, problems);
|
|
38
|
+
// Like the server: an empty id is exact (no trimming), and only the first step with an id is checked.
|
|
39
|
+
const ids = new Set();
|
|
40
|
+
const dupReported = new Set();
|
|
41
|
+
for (const n of graph.nodes) {
|
|
42
|
+
const label = n?.title || n?.id || '(unnamed)';
|
|
43
|
+
if (!n || typeof n.id !== 'string' || n.id === '') {
|
|
44
|
+
add('empty_node_id', 'A step has no id.');
|
|
45
|
+
continue;
|
|
46
|
+
}
|
|
47
|
+
if (ids.has(n.id)) {
|
|
48
|
+
if (!dupReported.has(n.id))
|
|
49
|
+
add('duplicate_node', `Two steps share the id "${n.id}".`, n.id);
|
|
50
|
+
dupReported.add(n.id);
|
|
51
|
+
continue;
|
|
52
|
+
}
|
|
53
|
+
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);
|
|
56
|
+
}
|
|
57
|
+
const byRules = n.kind === 'condition' && n.decide_by === 'rules';
|
|
58
|
+
if (!byRules && (typeof n.text !== 'string' || n.text === '')) {
|
|
59
|
+
add('empty_text', `Step "${label}" has no text.`, n.id);
|
|
60
|
+
}
|
|
61
|
+
const l = `Step ${goQuote(label)}`;
|
|
62
|
+
if (n.decide_by !== undefined && n.decide_by !== null && n.decide_by !== '') {
|
|
63
|
+
if (n.kind !== 'condition') {
|
|
64
|
+
add('bad_decide_by', `${l} is not a choice, so it cannot decide by rules.`, n.id);
|
|
65
|
+
}
|
|
66
|
+
else if (n.decide_by !== 'agent' && n.decide_by !== 'rules') {
|
|
67
|
+
add('bad_decide_by', `${l} decides by ${goQuote(String(n.decide_by))}; it must be "agent" or "rules".`, n.id);
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
const hasAgent = typeof n.agent_uuid === 'string' && n.agent_uuid !== '';
|
|
71
|
+
if (byRules) {
|
|
72
|
+
if (hasAgent)
|
|
73
|
+
add('rules_no_agent', `${l} decides by rules, so it has no agent.`, n.id);
|
|
74
|
+
}
|
|
75
|
+
else if (!hasAgent) {
|
|
76
|
+
add('no_agent', `Step "${label}" has no agent.`, n.id);
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
const outgoingFrom = new Set(graph.edges.map((e) => e?.from));
|
|
80
|
+
for (const n of graph.nodes) {
|
|
81
|
+
if (!n || typeof n.id !== 'string' || n.id === '')
|
|
82
|
+
continue;
|
|
83
|
+
if (n.result_schema === undefined || n.result_schema === null)
|
|
84
|
+
continue;
|
|
85
|
+
const label = n.title || n.id;
|
|
86
|
+
if (n.kind === 'condition') {
|
|
87
|
+
add('result_schema_invalid', `Step ${goQuote(label)} is a choice and cannot return a result.`, n.id);
|
|
88
|
+
}
|
|
89
|
+
else if (outgoingFrom.has(n.id)) {
|
|
90
|
+
add('result_schema_not_at_end', 'Only a last step can return a result.', n.id);
|
|
91
|
+
}
|
|
92
|
+
else {
|
|
93
|
+
// Up to 20 per step, each prefixed with the step, like the server.
|
|
94
|
+
for (const rp of checker.problems(n.result_schema).slice(0, MAX_RESULT_PROBLEMS)) {
|
|
95
|
+
problems.push({ code: 'result_schema_invalid', node_id: n.id, field: rp.field, message: `Step ${goQuote(label)}: ${rp.message}` });
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
const incoming = new Map();
|
|
100
|
+
const outgoing = new Map();
|
|
101
|
+
const seenLines = new Set();
|
|
102
|
+
for (const e of graph.edges) {
|
|
103
|
+
if (!ids.has(e?.from) || !ids.has(e?.to)) {
|
|
104
|
+
add('unknown_node', `A line goes from "${e?.from}" to "${e?.to}", and one of those steps does not exist.`);
|
|
105
|
+
continue;
|
|
106
|
+
}
|
|
107
|
+
const key = `${e.from}->${e.to}`;
|
|
108
|
+
if (seenLines.has(key)) {
|
|
109
|
+
add('duplicate_line', `There are two lines from "${e.from}" to "${e.to}".`, e.from);
|
|
110
|
+
continue;
|
|
111
|
+
}
|
|
112
|
+
seenLines.add(key);
|
|
113
|
+
incoming.set(e.to, (incoming.get(e.to) ?? 0) + 1);
|
|
114
|
+
outgoing.set(e.from, [...(outgoing.get(e.from) ?? []), e]);
|
|
115
|
+
}
|
|
116
|
+
for (const n of graph.nodes) {
|
|
117
|
+
if (!n || !ids.has(n.id) || (n.kind === 'condition' && n.decide_by === 'rules'))
|
|
118
|
+
continue;
|
|
119
|
+
const label = n.title || n.id;
|
|
120
|
+
for (const e of outgoing.get(n.id) ?? []) {
|
|
121
|
+
if ((typeof e.when === 'string' && e.when !== '') || e.otherwise) {
|
|
122
|
+
problems.push({
|
|
123
|
+
code: 'when_on_agent_condition',
|
|
124
|
+
node_id: n.id,
|
|
125
|
+
field: e.name,
|
|
126
|
+
message: `The line ${this.lineLabel(e)} out of Step ${goQuote(label)} has a rule, but only a choice that decides by rules can have one.`,
|
|
127
|
+
});
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
for (const n of graph.nodes) {
|
|
132
|
+
if (n?.kind !== 'condition' || !ids.has(n.id))
|
|
133
|
+
continue;
|
|
134
|
+
const lines = outgoing.get(n.id) ?? [];
|
|
135
|
+
const label = n.title || n.id;
|
|
136
|
+
if (lines.length < 2) {
|
|
137
|
+
add('condition_few_lines', `Condition "${label}" needs at least two lines leaving it.`, n.id);
|
|
138
|
+
}
|
|
139
|
+
const names = new Set();
|
|
140
|
+
for (const l of lines) {
|
|
141
|
+
if (!l.name) {
|
|
142
|
+
add('unnamed_line', `A line leaving condition "${label}" to "${l.to}" has no name.`, n.id);
|
|
143
|
+
}
|
|
144
|
+
else if (names.has(l.name)) {
|
|
145
|
+
add('duplicate_line_name', `Condition "${label}" has two lines named "${l.name}".`, n.id);
|
|
146
|
+
}
|
|
147
|
+
names.add(l.name ?? '');
|
|
148
|
+
}
|
|
149
|
+
if (n.decide_by === 'rules')
|
|
150
|
+
this.ruleProblems(n, lines, problems);
|
|
151
|
+
}
|
|
152
|
+
const starts = [...ids].filter((id) => !incoming.has(id));
|
|
153
|
+
if (starts.length === 0) {
|
|
154
|
+
add('no_start', 'There is no starting step (every step has a line coming in).');
|
|
155
|
+
}
|
|
156
|
+
else if (starts.length > 1) {
|
|
157
|
+
add('several_starts', `There is more than one starting step: ${starts.join(', ')}.`);
|
|
158
|
+
}
|
|
159
|
+
else {
|
|
160
|
+
const reached = new Set([starts[0]]);
|
|
161
|
+
const queue = [starts[0]];
|
|
162
|
+
while (queue.length) {
|
|
163
|
+
for (const e of outgoing.get(queue.shift()) ?? []) {
|
|
164
|
+
if (!reached.has(e.to)) {
|
|
165
|
+
reached.add(e.to);
|
|
166
|
+
queue.push(e.to);
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
for (const id of ids) {
|
|
171
|
+
if (!reached.has(id))
|
|
172
|
+
add('unreachable', `Step "${id}" cannot be reached from the start.`, id);
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
if (this.hasCycle(ids, outgoing))
|
|
176
|
+
add('cycle', 'The lines form a loop; a playbook cannot go back to an earlier step.');
|
|
177
|
+
this.workRuleProblems(graph, ids, problems);
|
|
178
|
+
return problems;
|
|
179
|
+
}
|
|
180
|
+
sizeProblems(graph, problems) {
|
|
181
|
+
const add = (field, message) => problems.push({ code: 'too_large', field, message });
|
|
182
|
+
const bytes = (v) => (typeof v === 'string' ? Buffer.byteLength(v) : 0);
|
|
183
|
+
if (graph.nodes.length > MAX_PLAYBOOK_STEPS)
|
|
184
|
+
add('nodes', `At most ${MAX_PLAYBOOK_STEPS} steps.`);
|
|
185
|
+
if (graph.edges.length > MAX_PLAYBOOK_LINES)
|
|
186
|
+
add('edges', `At most ${MAX_PLAYBOOK_LINES} lines.`);
|
|
187
|
+
if (graph.nodes.some((n) => bytes(n?.text) > MAX_STEP_TEXT_BYTES))
|
|
188
|
+
add('nodes.text', `Step text is at most ${MAX_STEP_TEXT_BYTES} characters.`);
|
|
189
|
+
if (graph.nodes.some((n) => bytes(n?.title) > MAX_STEP_TITLE_BYTES))
|
|
190
|
+
add('nodes.title', `Step title is at most ${MAX_STEP_TITLE_BYTES} characters.`);
|
|
191
|
+
if (Array.isArray(graph.rules)) {
|
|
192
|
+
if (graph.rules.length > MAX_RULE_ROWS)
|
|
193
|
+
add('rules', `At most ${MAX_RULE_ROWS} rules.`);
|
|
194
|
+
if (graph.rules.some((r) => [r?.rule, r?.why, r?.title, r?.step].some((v) => bytes(v) > MAX_RULE_FIELD_BYTES)))
|
|
195
|
+
add('rules', 'A rule is too long.');
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
// Rules on the version: their text, their count and ids, and the step each is for.
|
|
199
|
+
workRuleProblems(graph, ids, problems) {
|
|
200
|
+
if (graph.rules === undefined || graph.rules === null)
|
|
201
|
+
return;
|
|
202
|
+
if (!Array.isArray(graph.rules)) {
|
|
203
|
+
problems.push({ code: 'bad_graph', message: 'The graph\'s "rules" must be a list.' });
|
|
204
|
+
return;
|
|
205
|
+
}
|
|
206
|
+
const rules = graph.rules;
|
|
207
|
+
const add = (code, field, message, node_id) => problems.push({ code, node_id, field, message });
|
|
208
|
+
const runes = (v) => (typeof v === 'string' ? [...v].length : 0);
|
|
209
|
+
const text = (v) => (typeof v === 'string' ? v : '');
|
|
210
|
+
if (rules.length > MAX_WORK_RULES) {
|
|
211
|
+
add('too_many_rules', 'rules', `There are ${rules.length} rules; at most ${MAX_WORK_RULES} are allowed.`);
|
|
212
|
+
}
|
|
213
|
+
const seen = new Set();
|
|
214
|
+
rules.forEach((r, i) => {
|
|
215
|
+
const n = i + 1;
|
|
216
|
+
if (text(r?.rule).trim() === '')
|
|
217
|
+
add('rule_no_text', `rules[${i}].rule`, `Rule ${n} has no text.`);
|
|
218
|
+
else if (runes(r.rule) > MAX_WORK_RULE_TEXT)
|
|
219
|
+
add('rule_too_long', `rules[${i}].rule`, `Rule ${n} is longer than ${MAX_WORK_RULE_TEXT} characters.`);
|
|
220
|
+
if (text(r?.title).trim() === '')
|
|
221
|
+
add('rule_no_title', `rules[${i}].title`, `Rule ${n} has no title.`);
|
|
222
|
+
else if (runes(r.title) > MAX_WORK_RULE_TITLE)
|
|
223
|
+
add('rule_title_too_long', `rules[${i}].title`, `The title of rule ${n} is longer than ${MAX_WORK_RULE_TITLE} characters.`);
|
|
224
|
+
if (runes(r?.why) > MAX_WORK_RULE_WHY)
|
|
225
|
+
add('rule_why_too_long', `rules[${i}].why`, `The reason on rule ${n} is longer than ${MAX_WORK_RULE_WHY} characters.`);
|
|
226
|
+
const id = text(r?.id);
|
|
227
|
+
if (id !== '') {
|
|
228
|
+
if (seen.has(id))
|
|
229
|
+
add('rule_id_twice', `rules[${i}].id`, `Two rules share the id ${goQuote(id)}.`);
|
|
230
|
+
seen.add(id);
|
|
231
|
+
}
|
|
232
|
+
});
|
|
233
|
+
rules.forEach((r, i) => {
|
|
234
|
+
const step = text(r?.step);
|
|
235
|
+
if (step === '')
|
|
236
|
+
return;
|
|
237
|
+
const field = `rules[${i}].step`;
|
|
238
|
+
if (!ids.has(step)) {
|
|
239
|
+
add('rule_unknown_step', field, `Rule ${i + 1} is for the step ${goQuote(step)}, but there is no such step.`);
|
|
240
|
+
return;
|
|
241
|
+
}
|
|
242
|
+
const node = graph.nodes.find((x) => x?.id === step);
|
|
243
|
+
if (node?.kind === 'condition' && node.decide_by === 'rules') {
|
|
244
|
+
add('rule_on_rules_condition', field, `Rule ${i + 1} is for Step ${goQuote(node.title || node.id)}, which decides by rules and never reads rules.`, step);
|
|
245
|
+
}
|
|
246
|
+
});
|
|
247
|
+
}
|
|
248
|
+
// Lines out of a rules condition: each has a rule or is the one "otherwise".
|
|
249
|
+
ruleProblems(n, lines, problems) {
|
|
250
|
+
const l = `Step ${goQuote(n.title || n.id)}`;
|
|
251
|
+
const add = (code, field, message) => problems.push({ code, node_id: n.id, field, message });
|
|
252
|
+
if (lines.length > MAX_RULE_LINES) {
|
|
253
|
+
add('rules_too_many_lines', undefined, `${l} has ${lines.length} lines out; a choice by rules can have at most ${MAX_RULE_LINES}.`);
|
|
254
|
+
}
|
|
255
|
+
let otherwise = 0;
|
|
256
|
+
for (const e of lines) {
|
|
257
|
+
const when = typeof e.when === 'string' ? e.when : '';
|
|
258
|
+
const lbl = this.lineLabel(e);
|
|
259
|
+
if (e.otherwise && when.trim() !== '') {
|
|
260
|
+
add('rules_when_and_otherwise', e.name, `The line ${lbl} out of ${l} has both a rule and "otherwise"; use one of them.`);
|
|
261
|
+
}
|
|
262
|
+
else if (e.otherwise) {
|
|
263
|
+
otherwise++;
|
|
264
|
+
if (otherwise === 2)
|
|
265
|
+
add('rules_otherwise_twice', e.name, `More than one line out of ${l} is "otherwise"; only one can be.`);
|
|
266
|
+
}
|
|
267
|
+
else if (when.trim() === '') {
|
|
268
|
+
add('rules_need_when', e.name, `The line ${lbl} out of ${l} has no rule; give it a rule or mark it "otherwise".`);
|
|
269
|
+
}
|
|
270
|
+
else if (Buffer.byteLength(when) > MAX_RULE_LENGTH) {
|
|
271
|
+
add('rules_when_invalid', e.name, `The rule on line ${lbl} out of ${l} is not valid: the rule is longer than ${MAX_RULE_LENGTH} characters.`);
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
lineLabel(e) {
|
|
276
|
+
return e.name ? goQuote(e.name) : `to ${goQuote(e.to)}`;
|
|
277
|
+
}
|
|
278
|
+
hasCycle(ids, outgoing) {
|
|
279
|
+
const state = new Map();
|
|
280
|
+
const visit = (id) => {
|
|
281
|
+
state.set(id, 1);
|
|
282
|
+
for (const e of outgoing.get(id) ?? []) {
|
|
283
|
+
const s = state.get(e.to);
|
|
284
|
+
if (s === 1)
|
|
285
|
+
return true;
|
|
286
|
+
if (!s && visit(e.to))
|
|
287
|
+
return true;
|
|
288
|
+
}
|
|
289
|
+
state.set(id, 2);
|
|
290
|
+
return false;
|
|
291
|
+
};
|
|
292
|
+
for (const id of ids)
|
|
293
|
+
if (!state.get(id) && visit(id))
|
|
294
|
+
return true;
|
|
295
|
+
return false;
|
|
296
|
+
}
|
|
297
|
+
}
|
|
@@ -43,7 +43,7 @@ export class ProtokolAdapter {
|
|
|
43
43
|
const messages = this.turnsToProtokolMessages(request.turns);
|
|
44
44
|
const agentUUID = request.target.type === 'provider_agent'
|
|
45
45
|
? request.target.id
|
|
46
|
-
: '
|
|
46
|
+
: 'prota';
|
|
47
47
|
try {
|
|
48
48
|
const response = await this.client.post('/luma/kortex/v1/chat', {
|
|
49
49
|
agent_uuid: agentUUID,
|