@ptkl/toolkit 1.3.0 → 1.4.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.
Files changed (61) hide show
  1. package/README.md +37 -30
  2. package/dist/bin/toolkit.js +37 -3
  3. package/dist/commands/__tests__/apiUsers.test.js +16 -0
  4. package/dist/commands/__tests__/forge-requires.test.js +58 -0
  5. package/dist/commands/__tests__/profile.test.js +65 -0
  6. package/dist/commands/apiUsers.js +12 -0
  7. package/dist/commands/forge.js +82 -6
  8. package/dist/commands/profile.js +84 -76
  9. package/dist/lib/kortex/__tests__/fixtures/providers/conformance.test.js +120 -0
  10. package/dist/lib/kortex/__tests__/fixtures/sse-and-persistence.test.js +172 -0
  11. package/dist/lib/kortex/__tests__/legacy-compatibility.test.js +273 -0
  12. package/dist/lib/kortex/__tests__/phase-1-conversion.test.js +154 -0
  13. package/dist/lib/kortex/__tests__/phase-2-runtime.test.js +100 -0
  14. package/dist/lib/kortex/__tests__/phase-3-provider.test.js +48 -0
  15. package/dist/lib/kortex/config/loader.js +129 -0
  16. package/dist/lib/kortex/config/schema.js +60 -0
  17. package/dist/lib/kortex/controller.js +60 -0
  18. package/dist/lib/kortex/conversation/legacy-conversion.js +141 -0
  19. package/dist/lib/kortex/conversation/types.js +13 -0
  20. package/dist/lib/kortex/events/index.js +1 -0
  21. package/dist/lib/kortex/events/reducer.js +86 -0
  22. package/dist/lib/kortex/events/types.js +7 -0
  23. package/dist/lib/kortex/events/writer.js +76 -0
  24. package/dist/lib/kortex/mcp/index.js +1 -0
  25. package/dist/lib/kortex/orchestration/index.js +1 -0
  26. package/dist/lib/kortex/orchestration/manager-worker.js +88 -0
  27. package/dist/lib/kortex/orchestration/peer-collaboration.js +59 -0
  28. package/dist/lib/kortex/orchestration/plan.js +133 -0
  29. package/dist/lib/kortex/orchestration/scheduler.js +124 -0
  30. package/dist/lib/kortex/persistence/index.js +1 -0
  31. package/dist/lib/kortex/persistence/run-journal.js +94 -0
  32. package/dist/lib/kortex/providers/anthropic.js +34 -0
  33. package/dist/lib/kortex/providers/index.js +1 -0
  34. package/dist/lib/kortex/providers/openai-compatible.js +190 -0
  35. package/dist/lib/kortex/providers/protokol.js +204 -0
  36. package/dist/lib/kortex/providers/registry.js +61 -0
  37. package/dist/lib/kortex/providers/types.js +13 -0
  38. package/dist/lib/kortex/runtime/agent-runner.js +241 -0
  39. package/dist/lib/kortex/runtime/approval-queue.js +95 -0
  40. package/dist/lib/kortex/runtime/budget-controller.js +105 -0
  41. package/dist/lib/kortex/runtime/index.js +1 -0
  42. package/dist/lib/kortex/runtime/tool-runtime.js +66 -0
  43. package/dist/lib/kortex/runtime/workspace.js +52 -0
  44. package/dist/lib/kortex/tools/index.js +1 -0
  45. package/dist/lib/kortex/tools.js +226 -34
  46. package/dist/lib/kortex/types.js +7 -0
  47. package/dist/lib/kortex/ui/index.js +1 -0
  48. package/dist/lib/oauth/CallbackPages.js +82 -0
  49. package/dist/lib/oauth/CallbackServer.js +84 -0
  50. package/dist/lib/oauth/OAuthClient.js +81 -0
  51. package/dist/lib/oauth/OAuthError.js +17 -0
  52. package/dist/lib/oauth/OAuthLogin.js +60 -0
  53. package/dist/lib/oauth/OAuthSession.js +100 -0
  54. package/dist/lib/oauth/Pkce.js +19 -0
  55. package/dist/lib/oauth/ProfileLogin.js +76 -0
  56. package/dist/lib/oauth/RefreshLock.js +61 -0
  57. package/dist/lib/oauth/ScopePreset.js +38 -0
  58. package/dist/lib/oauth/__tests__/mockServer.js +29 -0
  59. package/dist/lib/oauth/__tests__/oauth.test.js +347 -0
  60. package/dist/lib/util.js +9 -2
  61. package/package.json +6 -4
@@ -0,0 +1,273 @@
1
+ /**
2
+ * Baseline compatibility tests for existing Kortex tools.
3
+ *
4
+ * These capture the current behavior of the built-in tool executors
5
+ * before the orchestration refactor. They serve as regression guards:
6
+ * any refactored tool must produce the same observable output for the
7
+ * same inputs, on a known fixture directory.
8
+ *
9
+ * Run with: `npx vitest run src/lib/kortex/__tests__/legacy-compatibility.test.ts`
10
+ */
11
+ import { describe, it, expect, beforeAll } from 'vitest';
12
+ import { mkdtempSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
13
+ import { tmpdir } from 'node:os';
14
+ import { join } from 'node:path';
15
+ // The tools module — imported directly; any refactor that moves or renames
16
+ // this file must update this import path.
17
+ import { getToolDefinitions, executeTool, getToolRisk, validateToolArgs } from '../tools.js';
18
+ let cwd;
19
+ beforeAll(() => {
20
+ // Create a sandbox directory for each test file
21
+ cwd = mkdtempSync(join(tmpdir(), 'kortex-baseline-'));
22
+ // Seed with known content
23
+ writeFileSync(join(cwd, 'hello.txt'), 'Hello, world!', 'utf-8');
24
+ writeFileSync(join(cwd, 'data.json'), JSON.stringify({ key: 'value', nested: { a: 1 } }), 'utf-8');
25
+ // A small subdirectory
26
+ mkdirSync(join(cwd, 'subdir'));
27
+ writeFileSync(join(cwd, 'subdir', 'deep.txt'), 'deep content', 'utf-8');
28
+ });
29
+ // ── Smoke: tool definitions ──
30
+ describe('getToolDefinitions', () => {
31
+ it('returns at least 11 built-in tools', () => {
32
+ const tools = getToolDefinitions();
33
+ expect(tools.length).toBeGreaterThanOrEqual(11);
34
+ });
35
+ it('every tool has name, description, parameters', () => {
36
+ for (const t of getToolDefinitions()) {
37
+ expect(t.function.name).toBeTruthy();
38
+ expect(t.function.description).toBeTruthy();
39
+ expect(t.function.parameters).toBeTruthy();
40
+ }
41
+ });
42
+ it('includes read_file, write_file, edit_file, bash, git_status', () => {
43
+ const names = getToolDefinitions().map(t => t.function.name);
44
+ expect(names).toContain('read_file');
45
+ expect(names).toContain('write_file');
46
+ expect(names).toContain('edit_file');
47
+ expect(names).toContain('bash');
48
+ expect(names).toContain('git_status');
49
+ expect(names).toContain('git_diff');
50
+ expect(names).toContain('git_log');
51
+ expect(names).toContain('git_commit');
52
+ expect(names).toContain('git_branch');
53
+ expect(names).toContain('list_directory');
54
+ expect(names).toContain('search_files');
55
+ });
56
+ });
57
+ // ── File read ──
58
+ describe('read_file', () => {
59
+ const name = 'read_file';
60
+ function call(args) {
61
+ return { id: 'test-1', type: 'function', function: { name, arguments: JSON.stringify(args) } };
62
+ }
63
+ it('reads an existing file', () => {
64
+ const result = executeTool(cwd, call({ path: 'hello.txt' }));
65
+ expect(result.content).toContain('Hello, world!');
66
+ expect(result.tool_call_id).toBe('test-1');
67
+ });
68
+ it('returns line-numbered output', () => {
69
+ const result = executeTool(cwd, call({ path: 'hello.txt' }));
70
+ expect(result.content).toMatch(/^\d+\t/);
71
+ });
72
+ it('supports offset and limit', () => {
73
+ writeFileSync(join(cwd, 'lines.txt'), 'a\nb\nc\nd\ne\n', 'utf-8');
74
+ const result = executeTool(cwd, call({ path: 'lines.txt', offset: 2, limit: 3 }));
75
+ expect(result.content).toContain('b');
76
+ expect(result.content).toContain('d');
77
+ });
78
+ it('returns error for non-existent file', () => {
79
+ const result = executeTool(cwd, call({ path: 'nonexistent.txt' }));
80
+ expect(result.content).toStrictEqual(expect.stringContaining('Error:'));
81
+ });
82
+ it('returns error for directory path', () => {
83
+ const result = executeTool(cwd, call({ path: 'subdir' }));
84
+ expect(result.content).toStrictEqual(expect.stringContaining('Error:'));
85
+ });
86
+ it('truncates output beyond MAX_OUTPUT limit', () => {
87
+ const longContent = 'x'.repeat(200_000);
88
+ writeFileSync(join(cwd, 'long.txt'), longContent, 'utf-8');
89
+ const result = executeTool(cwd, call({ path: 'long.txt' }));
90
+ expect(result.content.length).toBeLessThan(150_000);
91
+ expect(result.content).toContain('(truncated)');
92
+ });
93
+ });
94
+ // ── File write ──
95
+ describe('write_file', () => {
96
+ const name = 'write_file';
97
+ function call(args) {
98
+ return { id: 'test-w', type: 'function', function: { name, arguments: JSON.stringify(args) } };
99
+ }
100
+ it('creates a new file', () => {
101
+ const result = executeTool(cwd, call({ path: 'new.txt', content: 'new content' }));
102
+ expect(result.content).toContain('File written');
103
+ expect(existsSync(join(cwd, 'new.txt'))).toBe(true);
104
+ });
105
+ it('overwrites an existing file', () => {
106
+ writeFileSync(join(cwd, 'overwrite.txt'), 'old', 'utf-8');
107
+ executeTool(cwd, call({ path: 'overwrite.txt', content: 'new' }));
108
+ const content = require('node:fs').readFileSync(join(cwd, 'overwrite.txt'), 'utf-8');
109
+ expect(content).toBe('new');
110
+ });
111
+ it('creates intermediate directories', () => {
112
+ executeTool(cwd, call({ path: 'a/b/c/deep.txt', content: 'nested' }));
113
+ expect(existsSync(join(cwd, 'a', 'b', 'c', 'deep.txt'))).toBe(true);
114
+ });
115
+ });
116
+ // ── File edit ──
117
+ describe('edit_file', () => {
118
+ const name = 'edit_file';
119
+ function call(args) {
120
+ return { id: 'test-e', type: 'function', function: { name, arguments: JSON.stringify(args) } };
121
+ }
122
+ it('replaces an exact string match', () => {
123
+ writeFileSync(join(cwd, 'edit.txt'), 'Hello, world!', 'utf-8');
124
+ const result = executeTool(cwd, call({ path: 'edit.txt', old_string: 'world', new_string: 'Kortex' }));
125
+ expect(result.content).toContain('File edited');
126
+ const content = require('node:fs').readFileSync(join(cwd, 'edit.txt'), 'utf-8');
127
+ expect(content).toBe('Hello, Kortex!');
128
+ });
129
+ it('returns error when old_string not found', () => {
130
+ const result = executeTool(cwd, call({ path: 'hello.txt', old_string: 'nonexistent', new_string: 'x' }));
131
+ expect(result.content).toStrictEqual(expect.stringContaining('Error:'));
132
+ });
133
+ it('returns error when old_string appears multiple times', () => {
134
+ writeFileSync(join(cwd, 'multi.txt'), 'a a a', 'utf-8');
135
+ const result = executeTool(cwd, call({ path: 'multi.txt', old_string: 'a', new_string: 'b' }));
136
+ expect(result.content).toStrictEqual(expect.stringContaining('Error:'));
137
+ });
138
+ });
139
+ // ── List directory ──
140
+ describe('list_directory', () => {
141
+ const name = 'list_directory';
142
+ function call(args) {
143
+ return { id: 'test-ls', type: 'function', function: { name, arguments: JSON.stringify(args) } };
144
+ }
145
+ it('lists root directory', () => {
146
+ const result = executeTool(cwd, call({}));
147
+ expect(result.content).toContain('hello.txt');
148
+ expect(result.content).toContain('subdir/');
149
+ });
150
+ it('respects depth parameter', () => {
151
+ const result = executeTool(cwd, call({ depth: 1 }));
152
+ expect(result.content).toContain('subdir/');
153
+ });
154
+ it('returns error for non-existent path', () => {
155
+ const result = executeTool(cwd, call({ path: 'nonexistent' }));
156
+ expect(result.content).toStrictEqual(expect.stringContaining('Error:'));
157
+ });
158
+ });
159
+ // ── Shell tools ──
160
+ describe('bash', () => {
161
+ const name = 'bash';
162
+ function call(args) {
163
+ return { id: 'test-sh', type: 'function', function: { name, arguments: JSON.stringify(args) } };
164
+ }
165
+ it('executes a simple command', () => {
166
+ const result = executeTool(cwd, call({ command: 'echo "hello from bash"' }));
167
+ expect(result.content).toContain('hello from bash');
168
+ });
169
+ it('captures exit code on failure', () => {
170
+ const result = executeTool(cwd, call({ command: 'exit 42' }));
171
+ expect(result.content).toContain('Exit code: 42');
172
+ });
173
+ it('clamps long output', () => {
174
+ const result = executeTool(cwd, call({ command: 'yes | head -c 200000' }));
175
+ expect(result.content.length).toBeLessThan(150_000);
176
+ });
177
+ });
178
+ describe('search_files', () => {
179
+ const name = 'search_files';
180
+ function call(args) {
181
+ return { id: 'test-grep', type: 'function', function: { name, arguments: JSON.stringify(args) } };
182
+ }
183
+ it('finds matching patterns', () => {
184
+ const result = executeTool(cwd, call({ pattern: 'Hello' }));
185
+ expect(result.content).toContain('hello.txt');
186
+ });
187
+ it('returns no matches for absent pattern', () => {
188
+ const result = executeTool(cwd, call({ pattern: 'XYZZY_NONEXISTENT' }));
189
+ expect(result.content).toContain('No matches');
190
+ });
191
+ });
192
+ // ── Security / path containment ──
193
+ describe('path containment', () => {
194
+ const readCall = {
195
+ id: 'sec-1',
196
+ type: 'function',
197
+ function: { name: 'read_file', arguments: JSON.stringify({ path: '../etc/passwd' }) },
198
+ };
199
+ const writeCall = {
200
+ id: 'sec-2',
201
+ type: 'function',
202
+ function: { name: 'write_file', arguments: JSON.stringify({ path: '../../tmp/escape_test', content: 'escaped' }) },
203
+ };
204
+ it('read_file rejects traversal outside cwd', () => {
205
+ const result = executeTool(cwd, readCall);
206
+ expect(result.content).toStrictEqual(expect.stringContaining('escapes the working directory'));
207
+ });
208
+ it('write_file rejects traversal outside cwd', () => {
209
+ const result = executeTool(cwd, writeCall);
210
+ expect(result.content).toStrictEqual(expect.stringContaining('escapes the working directory'));
211
+ });
212
+ it('write_file rejects absolute paths outside cwd', () => {
213
+ const result = executeTool(cwd, {
214
+ id: 'sec-3',
215
+ type: 'function',
216
+ function: { name: 'write_file', arguments: JSON.stringify({ path: '/tmp/kortex-escape-test', content: 'x' }) },
217
+ });
218
+ expect(result.content).toStrictEqual(expect.stringContaining('escapes the working directory'));
219
+ });
220
+ });
221
+ // ── Tool risk classification ──
222
+ describe('getToolRisk', () => {
223
+ it('classifies read tools', () => {
224
+ expect(getToolRisk('read_file')).toBe('read');
225
+ expect(getToolRisk('list_directory')).toBe('read');
226
+ expect(getToolRisk('search_files')).toBe('read');
227
+ expect(getToolRisk('git_status')).toBe('read');
228
+ expect(getToolRisk('git_diff')).toBe('read');
229
+ expect(getToolRisk('git_log')).toBe('read');
230
+ });
231
+ it('classifies write tools', () => {
232
+ expect(getToolRisk('write_file')).toBe('write');
233
+ expect(getToolRisk('edit_file')).toBe('write');
234
+ });
235
+ it('classifies bash as execute', () => {
236
+ expect(getToolRisk('bash')).toBe('execute');
237
+ expect(getToolRisk('git_branch')).toBe('write');
238
+ });
239
+ it('classifies git_commit as destructive', () => {
240
+ expect(getToolRisk('git_commit')).toBe('destructive');
241
+ });
242
+ it('classifies MCP tools as external', () => {
243
+ expect(getToolRisk('mcp_filesystem_read')).toBe('external');
244
+ expect(getToolRisk('mcp_protokol_component_list')).toBe('external');
245
+ });
246
+ it('defaults unknown tools to execute', () => {
247
+ expect(getToolRisk('unknown_tool')).toBe('execute');
248
+ });
249
+ });
250
+ // ── Argument validation ──
251
+ describe('validateToolArgs', () => {
252
+ const readFileSchema = {
253
+ type: 'object',
254
+ properties: {
255
+ path: { type: 'string' },
256
+ offset: { type: 'number' },
257
+ limit: { type: 'number' },
258
+ },
259
+ required: ['path'],
260
+ };
261
+ it('passes valid args', () => {
262
+ const errs = validateToolArgs('read_file', { path: 'file.txt', offset: 1 }, readFileSchema);
263
+ expect(errs).toHaveLength(0);
264
+ });
265
+ it('reports missing required field', () => {
266
+ const errs = validateToolArgs('read_file', {}, readFileSchema);
267
+ expect(errs.map(e => e.message).join(' ')).toContain('path');
268
+ });
269
+ it('reports type mismatch', () => {
270
+ const errs = validateToolArgs('read_file', { path: 'file.txt', offset: 'not-a-number' }, readFileSchema);
271
+ expect(errs.map(e => e.message).join(' ')).toContain('Expected number');
272
+ });
273
+ });
@@ -0,0 +1,154 @@
1
+ /**
2
+ * Phase 1 tests: canonical conversation model, legacy conversion, event reducer.
3
+ */
4
+ import { describe, it, expect } from 'vitest';
5
+ import { storedMessagesToTurns, turnsToStoredMessages } from '../conversation/legacy-conversion.js';
6
+ import { RunEventReducer } from '../events/reducer.js';
7
+ // ── Legacy conversion ──
8
+ describe('legacy conversation conversion', () => {
9
+ it('converts a simple user message', () => {
10
+ const msgs = [{ role: 'user', content: 'Hello' }];
11
+ const turns = storedMessagesToTurns(msgs);
12
+ expect(turns).toHaveLength(1);
13
+ expect(turns[0].role).toBe('user');
14
+ expect(turns[0].blocks).toHaveLength(1);
15
+ expect(turns[0].blocks[0]).toMatchObject({ type: 'text', text: 'Hello' });
16
+ });
17
+ it('converts an assistant message with tool calls', () => {
18
+ const msgs = [{
19
+ role: 'assistant',
20
+ content: 'Let me check that file.',
21
+ tool_calls: [{
22
+ id: 'call-1',
23
+ type: 'function',
24
+ function: { name: 'read_file', arguments: '{"path":"test.txt"}' },
25
+ }],
26
+ }];
27
+ const turns = storedMessagesToTurns(msgs);
28
+ expect(turns).toHaveLength(1);
29
+ expect(turns[0].blocks).toHaveLength(2); // text + tool_call
30
+ expect(turns[0].blocks[1]).toMatchObject({ type: 'tool_call', name: 'read_file' });
31
+ });
32
+ it('converts a tool result message', () => {
33
+ const msgs = [{
34
+ role: 'tool',
35
+ content: 'File contents: hello',
36
+ tool_call_id: 'call-1',
37
+ }];
38
+ const turns = storedMessagesToTurns(msgs);
39
+ expect(turns).toHaveLength(1);
40
+ expect(turns[0].role).toBe('tool');
41
+ expect(turns[0].blocks[0]).toMatchObject({
42
+ type: 'tool_result',
43
+ callId: 'call-1',
44
+ });
45
+ });
46
+ it('converts a context message to system role', () => {
47
+ const msgs = [{ role: 'context', content: 'Working directory: /tmp' }];
48
+ const turns = storedMessagesToTurns(msgs);
49
+ expect(turns).toHaveLength(1);
50
+ expect(turns[0].role).toBe('system');
51
+ });
52
+ it('round-trips with no data loss: user+assistant+tool', () => {
53
+ const original = [
54
+ { role: 'context', content: 'cwd: /test' },
55
+ { role: 'user', content: 'Read file.txt' },
56
+ {
57
+ role: 'assistant', content: 'Reading...',
58
+ tool_calls: [{ id: 'tc-1', type: 'function', function: { name: 'read_file', arguments: '{"path":"file.txt"}' } }],
59
+ },
60
+ { role: 'tool', content: 'file content', tool_call_id: 'tc-1' },
61
+ { role: 'assistant', content: 'Here is the content.' },
62
+ ];
63
+ const turns = storedMessagesToTurns(original);
64
+ const back = turnsToStoredMessages(turns);
65
+ // The round-trip may not be byte-identical (tool_calls arguments formatting)
66
+ // but the semantic content should be preserved
67
+ expect(back.filter(m => m.role === 'user')).toHaveLength(1);
68
+ expect(back.filter(m => m.role === 'assistant')).toHaveLength(2);
69
+ expect(back.filter(m => m.role === 'tool')).toHaveLength(1);
70
+ expect(back.filter(m => m.role === 'context')).toHaveLength(1);
71
+ const userMsg = back.find(m => m.role === 'user');
72
+ expect(userMsg?.content).toBe('Read file.txt');
73
+ const assistantToolMsg = back.find(m => m.role === 'assistant' && m.tool_calls);
74
+ expect(assistantToolMsg?.tool_calls?.[0].function.name).toBe('read_file');
75
+ const toolMsg = back.find(m => m.role === 'tool');
76
+ expect(toolMsg?.content).toBe('file content');
77
+ expect(toolMsg?.tool_call_id).toBe('tc-1');
78
+ });
79
+ });
80
+ // ── Event reducer ──
81
+ describe('RunEventReducer', () => {
82
+ const baseEvent = (overrides) => ({
83
+ schemaVersion: 1,
84
+ runId: 'test-run-001',
85
+ at: new Date().toISOString(),
86
+ durability: 'ephemeral',
87
+ ...overrides,
88
+ event: overrides.event,
89
+ });
90
+ it('tracks plan approval state', () => {
91
+ const r = new RunEventReducer();
92
+ r.apply(baseEvent({ event: { type: 'run.created' } }));
93
+ expect(r['state']?.planApproved).toBe(false);
94
+ r.apply(baseEvent({ event: { type: 'plan.approved', planHash: 'abc' } }));
95
+ expect(r['state']?.planApproved).toBe(true);
96
+ });
97
+ it('tracks task state transitions', () => {
98
+ const r = new RunEventReducer();
99
+ r.apply(baseEvent({ event: { type: 'task.state', taskId: 't1', attempt: 1, state: 'running' } }));
100
+ const s1 = r['state'];
101
+ expect(s1?.tasks.get('t1')?.state).toBe('running');
102
+ r.apply(baseEvent({ event: { type: 'task.state', taskId: 't1', attempt: 1, state: 'succeeded' } }));
103
+ const s2 = r['state'];
104
+ expect(s2?.tasks.get('t1')?.state).toBe('succeeded');
105
+ });
106
+ it('accumulates tool call counts', () => {
107
+ const r = new RunEventReducer();
108
+ for (let i = 0; i < 3; i++) {
109
+ r.apply(baseEvent({ event: { type: 'tool.completed', taskId: 't1', attempt: 1, callId: `c${i}`, resultRef: `/tmp/r${i}`, digest: `d${i}` } }));
110
+ }
111
+ expect(r['state']?.totalToolCalls).toBe(3);
112
+ });
113
+ it('accumulates token usage', () => {
114
+ const r = new RunEventReducer();
115
+ r.apply(baseEvent({
116
+ event: {
117
+ type: 'usage.updated',
118
+ taskId: 't1',
119
+ attempt: 1,
120
+ usage: { inputTokens: 100, outputTokens: 50, estimated: false },
121
+ },
122
+ }));
123
+ r.apply(baseEvent({
124
+ event: {
125
+ type: 'usage.updated',
126
+ taskId: 't2',
127
+ attempt: 1,
128
+ usage: { inputTokens: 200, outputTokens: 75, estimated: false },
129
+ },
130
+ }));
131
+ const s = r['state'];
132
+ expect(s?.totalTokens.input).toBe(300);
133
+ expect(s?.totalTokens.output).toBe(125);
134
+ });
135
+ it('tracks run finished state', () => {
136
+ const r = new RunEventReducer();
137
+ r.apply(baseEvent({ event: { type: 'run.created' } }));
138
+ r.apply(baseEvent({ event: { type: 'run.finished', outcome: { kind: 'succeeded' } } }));
139
+ expect(r['state']?.status).toBe('finished');
140
+ expect(r['state']?.outcome?.kind).toBe('succeeded');
141
+ });
142
+ it('produces a non-empty summary', () => {
143
+ const r = new RunEventReducer();
144
+ r.apply(baseEvent({ event: { type: 'run.created' } }));
145
+ r.apply(baseEvent({ event: { type: 'plan.approved', planHash: 'abc' } }));
146
+ r.apply(baseEvent({ event: { type: 'task.state', taskId: 't1', attempt: 1, state: 'succeeded' } }));
147
+ r.apply(baseEvent({ event: { type: 'task.state', taskId: 't2', attempt: 1, state: 'failed', error: 'OOM' } }));
148
+ const summary = r.summary();
149
+ expect(summary).toContain('test-run');
150
+ expect(summary).toContain('succeeded');
151
+ expect(summary).toContain('t1');
152
+ expect(summary).toContain('t2');
153
+ });
154
+ });
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Phase 2 tests: BudgetController, ApprovalQueue, and the Protokol adapter contract.
3
+ *
4
+ * These tests verify the new runtime components in isolation.
5
+ * Full end-to-end tests with a live backend require a staging environment.
6
+ */
7
+ import { describe, it, expect } from 'vitest';
8
+ import { BudgetController, DEFAULT_RUN_BUDGETS } from '../runtime/budget-controller.js';
9
+ import { ApprovalQueue } from '../runtime/approval-queue.js';
10
+ // ── BudgetController ──
11
+ describe('BudgetController', () => {
12
+ it('acquires a lease within budget', () => {
13
+ const bc = new BudgetController(DEFAULT_RUN_BUDGETS);
14
+ const lease = bc.acquire({ modelCalls: 1 });
15
+ expect(lease.modelCalls).toBe(1);
16
+ expect(lease.deadlineMs).toBeGreaterThan(0);
17
+ });
18
+ it('throws when exceeding max model calls', () => {
19
+ const bc = new BudgetController({ ...DEFAULT_RUN_BUDGETS, maxModelCalls: 1 });
20
+ bc.acquire({ modelCalls: 1 });
21
+ bc.recordUsage({ estimated: false });
22
+ expect(() => bc.acquire({ modelCalls: 1 })).toThrow('Budget exceeded');
23
+ });
24
+ it('records usage and tracks tokens', () => {
25
+ const bc = new BudgetController(DEFAULT_RUN_BUDGETS);
26
+ bc.recordUsage({ inputTokens: 100, outputTokens: 50, estimated: false });
27
+ const state = bc.getState();
28
+ expect(state.inputTokens).toBe(100);
29
+ expect(state.outputTokens).toBe(50);
30
+ expect(state.modelCallsUsed).toBe(1);
31
+ });
32
+ it('throws when exceeding input token budget', () => {
33
+ const bc = new BudgetController({ ...DEFAULT_RUN_BUDGETS, maxInputTokens: 500 });
34
+ expect(() => bc.recordUsage({ inputTokens: 600, outputTokens: 0, estimated: false })).toThrow('Budget exceeded');
35
+ });
36
+ it('records tool calls', () => {
37
+ const bc = new BudgetController({ ...DEFAULT_RUN_BUDGETS, maxToolCalls: 5 });
38
+ for (let i = 0; i < 5; i++)
39
+ bc.recordToolCall();
40
+ expect(() => bc.recordToolCall()).toThrow('Budget exceeded');
41
+ });
42
+ it('isExceeded returns true when over budget', () => {
43
+ const bc = new BudgetController({ ...DEFAULT_RUN_BUDGETS, maxModelCalls: 1 });
44
+ bc.acquire({ modelCalls: 1 });
45
+ bc.recordUsage({ estimated: false });
46
+ expect(bc.isExceeded()).toBe(false);
47
+ // Exceed by trying to acquire more
48
+ expect(() => bc.acquire({ modelCalls: 1 })).toThrow();
49
+ });
50
+ it('remainingPercent returns a value between 0 and 100', () => {
51
+ const bc = new BudgetController(DEFAULT_RUN_BUDGETS);
52
+ expect(bc.remainingPercent).toBe(100); // 0/50 = 100%
53
+ bc.acquire({ modelCalls: 25 });
54
+ bc.recordUsage({ estimated: false });
55
+ expect(bc.remainingPercent).toBe(98); // 1/50 = 2% used
56
+ });
57
+ });
58
+ // ── ApprovalQueue ──
59
+ describe('ApprovalQueue', () => {
60
+ function makeCall(overrides) {
61
+ return { id: 'call-1', name: 'bash', arguments: { command: 'test' }, ...overrides };
62
+ }
63
+ it('queues a consent request and resolves it', async () => {
64
+ const aq = new ApprovalQueue();
65
+ const promise = aq.requestConsent('run-1', 'task-1', 1, 'agent-1', makeCall(), 'execute', 'Run test');
66
+ aq.resolvePending({ requestId: 'run-1::task-1::call-1', outcome: 'approved', scope: 'once', decidedAt: new Date().toISOString() });
67
+ const decision = await promise;
68
+ expect(decision.outcome).toBe('approved');
69
+ expect(decision.scope).toBe('once');
70
+ });
71
+ it('returns a scoped decision without queuing', async () => {
72
+ const aq = new ApprovalQueue();
73
+ // First request: approve with 'task' scope
74
+ const p1 = aq.requestConsent('run-1', 'task-1', 1, 'agent-1', makeCall(), 'execute', 'Test');
75
+ aq.resolvePending({ requestId: 'run-1::task-1::call-1', outcome: 'approved', scope: 'task', decidedAt: new Date().toISOString() });
76
+ await p1;
77
+ // Second request for same task/tool: should auto-approve
78
+ const p2 = aq.requestConsent('run-1', 'task-1', 2, 'agent-1', makeCall({ id: 'call-2' }), 'execute', 'Test 2');
79
+ const decision = await p2;
80
+ expect(decision.outcome).toBe('approved');
81
+ expect(decision.scope).toBe('task'); // Matches the stored scoped decision
82
+ });
83
+ it('clears all pending requests', () => {
84
+ const aq = new ApprovalQueue();
85
+ aq.requestConsent('run-1', 'task-1', 1, 'agent-1', makeCall(), 'execute', 'Test');
86
+ expect(aq.pending).toHaveLength(1);
87
+ aq.clear();
88
+ expect(aq.pending).toHaveLength(0);
89
+ });
90
+ });
91
+ // ── Provider adapter contract (unit-level, no backend) ──
92
+ describe('ProtokolAdapter (static contract)', () => {
93
+ it('has correct id and family', async () => {
94
+ const { ProtokolAdapter } = await import('../providers/protokol.js');
95
+ // Can't instantiate without credentials in tests, but we can check the static shape
96
+ const instance = new ProtokolAdapter({ host: 'https://test.com', token: 'test', agentUUID: 'test' });
97
+ expect(instance.id).toBe('protokol');
98
+ expect(instance.family).toBe('protokol');
99
+ });
100
+ });
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Phase 3 adapter contract tests — verify OpenAI-compatible adapter
3
+ * coverage as a second provider family.
4
+ */
5
+ import { describe, it, expect } from 'vitest';
6
+ import { OpenAICompatibleAdapter } from '../providers/openai-compatible.js';
7
+ describe('OpenAICompatibleAdapter (structural contract)', () => {
8
+ const adapter = new OpenAICompatibleAdapter('test-openai', {
9
+ apiKey: 'sk-test',
10
+ });
11
+ it('has correct id and family', () => {
12
+ expect(adapter.id).toBe('test-openai');
13
+ expect(adapter.family).toBe('openai');
14
+ });
15
+ it('resolves capabilities for gpt-4o', async () => {
16
+ const caps = await adapter.resolveCapabilities({ type: 'model', model: 'gpt-4o' });
17
+ expect(caps.streaming).toBe(true);
18
+ expect(caps.toolUse).toBe(true);
19
+ expect(caps.parallelToolCalls).toBe(true);
20
+ expect(caps.contextWindow).toBe(128_000);
21
+ });
22
+ it('resolves capabilities for deepseek-chat', async () => {
23
+ const caps = await adapter.resolveCapabilities({ type: 'model', model: 'deepseek-chat' });
24
+ expect(caps.tokenCounting).toBe('estimated');
25
+ });
26
+ it('resolves capabilities for o1-mini (reasoning model)', async () => {
27
+ const caps = await adapter.resolveCapabilities({ type: 'model', model: 'o1-mini' });
28
+ expect(caps.toolUse).toBe(false);
29
+ expect(caps.maxOutputTokens).toBe(100_000);
30
+ });
31
+ it('stream rejects on invalid API key', async () => {
32
+ const badAdapter = new OpenAICompatibleAdapter('bad-key', { apiKey: 'invalid-key-will-401' });
33
+ const request = {
34
+ target: { type: 'model', model: 'gpt-4o' },
35
+ turns: [],
36
+ tools: [],
37
+ limits: { maxOutputTokens: 100 },
38
+ };
39
+ const controller = new AbortController();
40
+ const events = [];
41
+ for await (const event of badAdapter.stream(request, controller.signal)) {
42
+ events.push(event);
43
+ }
44
+ // Should error cleanly (401) rather than hanging or crashing
45
+ expect(events.length).toBeGreaterThan(0);
46
+ expect(events.some(e => e.type === 'error')).toBe(true);
47
+ });
48
+ });