@ptkl/toolkit 0.11.0 → 0.14.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 +101 -0
- package/dist/bin/toolkit.js +0 -0
- package/dist/commands/forge.js +582 -28
- package/dist/commands/index.js +4 -0
- package/dist/commands/kortex.js +106 -0
- package/dist/commands/logs.js +109 -0
- package/dist/lib/kortex/bridge.js +113 -0
- package/dist/lib/kortex/config.js +21 -0
- package/dist/lib/kortex/conversations.js +84 -0
- package/dist/lib/kortex/mcp.js +193 -0
- package/dist/lib/kortex/session.js +759 -0
- package/dist/lib/kortex/tools.js +406 -0
- package/dist/lib/kortex/ui/App.js +455 -0
- package/dist/lib/kortex/ui/SelectAgent.js +23 -0
- package/package.json +11 -2
|
@@ -0,0 +1,406 @@
|
|
|
1
|
+
import { readFileSync, writeFileSync, existsSync, statSync, readdirSync, mkdirSync } from 'node:fs';
|
|
2
|
+
import { execSync } from 'node:child_process';
|
|
3
|
+
import { resolve, dirname, relative } from 'node:path';
|
|
4
|
+
const MAX_OUTPUT = 100_000;
|
|
5
|
+
function clampOutput(text) {
|
|
6
|
+
if (text.length <= MAX_OUTPUT)
|
|
7
|
+
return text;
|
|
8
|
+
return text.slice(0, MAX_OUTPUT) + '\n... (truncated)';
|
|
9
|
+
}
|
|
10
|
+
function resolvePath(cwd, filePath) {
|
|
11
|
+
return resolve(cwd, filePath);
|
|
12
|
+
}
|
|
13
|
+
export function getToolDefinitions() {
|
|
14
|
+
return [
|
|
15
|
+
// ── File system ──
|
|
16
|
+
{
|
|
17
|
+
type: 'function',
|
|
18
|
+
function: {
|
|
19
|
+
name: 'read_file',
|
|
20
|
+
description: 'Read the contents of a file. Returns the file content with line numbers.',
|
|
21
|
+
parameters: {
|
|
22
|
+
type: 'object',
|
|
23
|
+
properties: {
|
|
24
|
+
path: { type: 'string', description: 'File path relative to the working directory' },
|
|
25
|
+
offset: { type: 'number', description: 'Start reading from this line number (1-based). Optional.' },
|
|
26
|
+
limit: { type: 'number', description: 'Maximum number of lines to read. Optional.' },
|
|
27
|
+
},
|
|
28
|
+
required: ['path'],
|
|
29
|
+
},
|
|
30
|
+
},
|
|
31
|
+
},
|
|
32
|
+
{
|
|
33
|
+
type: 'function',
|
|
34
|
+
function: {
|
|
35
|
+
name: 'write_file',
|
|
36
|
+
description: 'Create a new file or completely overwrite an existing file with the provided content.',
|
|
37
|
+
parameters: {
|
|
38
|
+
type: 'object',
|
|
39
|
+
properties: {
|
|
40
|
+
path: { type: 'string', description: 'File path relative to the working directory' },
|
|
41
|
+
content: { type: 'string', description: 'The full file content to write' },
|
|
42
|
+
},
|
|
43
|
+
required: ['path', 'content'],
|
|
44
|
+
},
|
|
45
|
+
},
|
|
46
|
+
},
|
|
47
|
+
{
|
|
48
|
+
type: 'function',
|
|
49
|
+
function: {
|
|
50
|
+
name: 'edit_file',
|
|
51
|
+
description: 'Edit a file by replacing an exact string match with new content. The old_string must appear exactly once in the file. Use this for surgical edits instead of rewriting entire files.',
|
|
52
|
+
parameters: {
|
|
53
|
+
type: 'object',
|
|
54
|
+
properties: {
|
|
55
|
+
path: { type: 'string', description: 'File path relative to the working directory' },
|
|
56
|
+
old_string: { type: 'string', description: 'The exact string to find and replace. Must be unique in the file.' },
|
|
57
|
+
new_string: { type: 'string', description: 'The replacement string' },
|
|
58
|
+
},
|
|
59
|
+
required: ['path', 'old_string', 'new_string'],
|
|
60
|
+
},
|
|
61
|
+
},
|
|
62
|
+
},
|
|
63
|
+
{
|
|
64
|
+
type: 'function',
|
|
65
|
+
function: {
|
|
66
|
+
name: 'list_directory',
|
|
67
|
+
description: 'List files and directories in a given path. Returns a tree-like listing.',
|
|
68
|
+
parameters: {
|
|
69
|
+
type: 'object',
|
|
70
|
+
properties: {
|
|
71
|
+
path: { type: 'string', description: 'Directory path relative to the working directory. Defaults to "."' },
|
|
72
|
+
depth: { type: 'number', description: 'Maximum depth to recurse. Defaults to 3.' },
|
|
73
|
+
},
|
|
74
|
+
required: [],
|
|
75
|
+
},
|
|
76
|
+
},
|
|
77
|
+
},
|
|
78
|
+
{
|
|
79
|
+
type: 'function',
|
|
80
|
+
function: {
|
|
81
|
+
name: 'search_files',
|
|
82
|
+
description: 'Search for a pattern across files using grep. Returns matching lines with file paths and line numbers.',
|
|
83
|
+
parameters: {
|
|
84
|
+
type: 'object',
|
|
85
|
+
properties: {
|
|
86
|
+
pattern: { type: 'string', description: 'The search pattern (regex)' },
|
|
87
|
+
path: { type: 'string', description: 'Directory to search in. Defaults to "."' },
|
|
88
|
+
include: { type: 'string', description: 'File glob pattern to include, e.g. "*.ts"' },
|
|
89
|
+
},
|
|
90
|
+
required: ['pattern'],
|
|
91
|
+
},
|
|
92
|
+
},
|
|
93
|
+
},
|
|
94
|
+
// ── Shell ──
|
|
95
|
+
{
|
|
96
|
+
type: 'function',
|
|
97
|
+
function: {
|
|
98
|
+
name: 'bash',
|
|
99
|
+
description: 'Execute a shell command and return its stdout and stderr. Use for running tests, build commands, installing packages, etc.',
|
|
100
|
+
parameters: {
|
|
101
|
+
type: 'object',
|
|
102
|
+
properties: {
|
|
103
|
+
command: { type: 'string', description: 'The shell command to execute' },
|
|
104
|
+
timeout: { type: 'number', description: 'Timeout in milliseconds. Defaults to 30000.' },
|
|
105
|
+
},
|
|
106
|
+
required: ['command'],
|
|
107
|
+
},
|
|
108
|
+
},
|
|
109
|
+
},
|
|
110
|
+
// ── Git ──
|
|
111
|
+
{
|
|
112
|
+
type: 'function',
|
|
113
|
+
function: {
|
|
114
|
+
name: 'git_status',
|
|
115
|
+
description: 'Show the working tree status: staged, unstaged, and untracked files.',
|
|
116
|
+
parameters: { type: 'object', properties: {}, required: [] },
|
|
117
|
+
},
|
|
118
|
+
},
|
|
119
|
+
{
|
|
120
|
+
type: 'function',
|
|
121
|
+
function: {
|
|
122
|
+
name: 'git_diff',
|
|
123
|
+
description: 'Show changes in the working directory. Can diff staged changes, unstaged changes, or compare branches/commits.',
|
|
124
|
+
parameters: {
|
|
125
|
+
type: 'object',
|
|
126
|
+
properties: {
|
|
127
|
+
target: { type: 'string', description: 'What to diff: "staged", "unstaged" (default), a branch name, or a commit hash.' },
|
|
128
|
+
path: { type: 'string', description: 'Limit diff to a specific file or directory.' },
|
|
129
|
+
},
|
|
130
|
+
required: [],
|
|
131
|
+
},
|
|
132
|
+
},
|
|
133
|
+
},
|
|
134
|
+
{
|
|
135
|
+
type: 'function',
|
|
136
|
+
function: {
|
|
137
|
+
name: 'git_log',
|
|
138
|
+
description: 'Show recent commit history with hash, author, date, and message.',
|
|
139
|
+
parameters: {
|
|
140
|
+
type: 'object',
|
|
141
|
+
properties: {
|
|
142
|
+
count: { type: 'number', description: 'Number of commits to show. Defaults to 10.' },
|
|
143
|
+
branch: { type: 'string', description: 'Branch to show history for. Defaults to current branch.' },
|
|
144
|
+
path: { type: 'string', description: 'Limit history to a specific file or directory.' },
|
|
145
|
+
},
|
|
146
|
+
required: [],
|
|
147
|
+
},
|
|
148
|
+
},
|
|
149
|
+
},
|
|
150
|
+
{
|
|
151
|
+
type: 'function',
|
|
152
|
+
function: {
|
|
153
|
+
name: 'git_commit',
|
|
154
|
+
description: 'Stage files and create a commit. If no files are specified, stages all modified and new files.',
|
|
155
|
+
parameters: {
|
|
156
|
+
type: 'object',
|
|
157
|
+
properties: {
|
|
158
|
+
message: { type: 'string', description: 'The commit message.' },
|
|
159
|
+
files: { type: 'array', items: { type: 'string' }, description: 'Specific files to stage. If empty, stages all changes.' },
|
|
160
|
+
},
|
|
161
|
+
required: ['message'],
|
|
162
|
+
},
|
|
163
|
+
},
|
|
164
|
+
},
|
|
165
|
+
{
|
|
166
|
+
type: 'function',
|
|
167
|
+
function: {
|
|
168
|
+
name: 'git_branch',
|
|
169
|
+
description: 'List branches, create a new branch, or switch branches.',
|
|
170
|
+
parameters: {
|
|
171
|
+
type: 'object',
|
|
172
|
+
properties: {
|
|
173
|
+
action: { type: 'string', enum: ['list', 'create', 'switch'], description: 'Action to perform. Defaults to "list".' },
|
|
174
|
+
name: { type: 'string', description: 'Branch name (required for create/switch).' },
|
|
175
|
+
},
|
|
176
|
+
required: [],
|
|
177
|
+
},
|
|
178
|
+
},
|
|
179
|
+
},
|
|
180
|
+
];
|
|
181
|
+
}
|
|
182
|
+
// ── File system executors ──
|
|
183
|
+
function execReadFile(cwd, args) {
|
|
184
|
+
const fullPath = resolvePath(cwd, args.path.replace(/[<>]/g, '').trim());
|
|
185
|
+
if (!existsSync(fullPath))
|
|
186
|
+
return `Error: file not found: ${args.path}`;
|
|
187
|
+
const stat = statSync(fullPath);
|
|
188
|
+
if (stat.isDirectory())
|
|
189
|
+
return `Error: ${args.path} is a directory, not a file`;
|
|
190
|
+
const content = readFileSync(fullPath, 'utf-8');
|
|
191
|
+
const lines = content.split('\n');
|
|
192
|
+
const offset = Math.max(0, (args.offset ?? 1) - 1);
|
|
193
|
+
const limit = args.limit ?? lines.length;
|
|
194
|
+
const slice = lines.slice(offset, offset + limit);
|
|
195
|
+
const numbered = slice.map((line, i) => `${offset + i + 1}\t${line}`).join('\n');
|
|
196
|
+
return clampOutput(numbered);
|
|
197
|
+
}
|
|
198
|
+
function execWriteFile(cwd, args) {
|
|
199
|
+
const fullPath = resolvePath(cwd, args.path.replace(/[<>]/g, '').trim());
|
|
200
|
+
const dir = dirname(fullPath);
|
|
201
|
+
if (!existsSync(dir))
|
|
202
|
+
mkdirSync(dir, { recursive: true });
|
|
203
|
+
writeFileSync(fullPath, args.content, 'utf-8');
|
|
204
|
+
return `File written: ${args.path}`;
|
|
205
|
+
}
|
|
206
|
+
function execEditFile(cwd, args) {
|
|
207
|
+
const fullPath = resolvePath(cwd, args.path.replace(/[<>]/g, '').trim());
|
|
208
|
+
if (!existsSync(fullPath))
|
|
209
|
+
return `Error: file not found: ${args.path}`;
|
|
210
|
+
const content = readFileSync(fullPath, 'utf-8');
|
|
211
|
+
const count = content.split(args.old_string).length - 1;
|
|
212
|
+
if (count === 0)
|
|
213
|
+
return `Error: old_string not found in ${args.path}`;
|
|
214
|
+
if (count > 1)
|
|
215
|
+
return `Error: old_string found ${count} times in ${args.path} — must be unique. Add more surrounding context.`;
|
|
216
|
+
const updated = content.replace(args.old_string, args.new_string);
|
|
217
|
+
writeFileSync(fullPath, updated, 'utf-8');
|
|
218
|
+
return `File edited: ${args.path}`;
|
|
219
|
+
}
|
|
220
|
+
function execListDirectory(cwd, args) {
|
|
221
|
+
const rawPath = (args.path || '.').replace(/[<>]/g, '').trim() || '.';
|
|
222
|
+
const targetPath = resolvePath(cwd, rawPath);
|
|
223
|
+
if (!existsSync(targetPath))
|
|
224
|
+
return `Error: path not found: ${args.path || '.'}`;
|
|
225
|
+
const maxDepth = args.depth ?? 3;
|
|
226
|
+
const lines = [];
|
|
227
|
+
const ignoreDirs = new Set(['.git', 'node_modules', '__pycache__', '.venv', 'dist', 'build', '.next', 'vendor']);
|
|
228
|
+
function walk(dir, prefix, depth) {
|
|
229
|
+
if (depth > maxDepth)
|
|
230
|
+
return;
|
|
231
|
+
let entries;
|
|
232
|
+
try {
|
|
233
|
+
entries = readdirSync(dir).sort();
|
|
234
|
+
}
|
|
235
|
+
catch {
|
|
236
|
+
return;
|
|
237
|
+
}
|
|
238
|
+
entries = entries.filter(e => !ignoreDirs.has(e));
|
|
239
|
+
for (let i = 0; i < entries.length; i++) {
|
|
240
|
+
const entry = entries[i];
|
|
241
|
+
const fullEntry = resolve(dir, entry);
|
|
242
|
+
const isLast = i === entries.length - 1;
|
|
243
|
+
const connector = isLast ? '└── ' : '├── ';
|
|
244
|
+
const childPrefix = isLast ? ' ' : '│ ';
|
|
245
|
+
let isDir = false;
|
|
246
|
+
try {
|
|
247
|
+
isDir = statSync(fullEntry).isDirectory();
|
|
248
|
+
}
|
|
249
|
+
catch {
|
|
250
|
+
continue;
|
|
251
|
+
}
|
|
252
|
+
lines.push(prefix + connector + entry + (isDir ? '/' : ''));
|
|
253
|
+
if (isDir)
|
|
254
|
+
walk(fullEntry, prefix + childPrefix, depth + 1);
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
const relTarget = relative(cwd, targetPath) || '.';
|
|
258
|
+
lines.push(relTarget + '/');
|
|
259
|
+
walk(targetPath, '', 1);
|
|
260
|
+
return clampOutput(lines.join('\n'));
|
|
261
|
+
}
|
|
262
|
+
function execSearchFiles(cwd, args) {
|
|
263
|
+
const searchPath = args.path || '.';
|
|
264
|
+
let cmd = `grep -rn "${args.pattern.replace(/"/g, '\\"')}" ${searchPath}`;
|
|
265
|
+
if (args.include)
|
|
266
|
+
cmd += ` --include="${args.include}"`;
|
|
267
|
+
cmd += ' 2>/dev/null | head -100';
|
|
268
|
+
try {
|
|
269
|
+
const output = execSync(cmd, { cwd, timeout: 15_000, encoding: 'utf-8', maxBuffer: 1024 * 1024 * 5 });
|
|
270
|
+
return clampOutput(output || 'No matches found.');
|
|
271
|
+
}
|
|
272
|
+
catch {
|
|
273
|
+
return 'No matches found.';
|
|
274
|
+
}
|
|
275
|
+
}
|
|
276
|
+
function execBash(cwd, args) {
|
|
277
|
+
const timeout = args.timeout ?? 30_000;
|
|
278
|
+
try {
|
|
279
|
+
const output = execSync(args.command, {
|
|
280
|
+
cwd,
|
|
281
|
+
timeout,
|
|
282
|
+
maxBuffer: 1024 * 1024 * 10,
|
|
283
|
+
encoding: 'utf-8',
|
|
284
|
+
stdio: ['pipe', 'pipe', 'pipe'],
|
|
285
|
+
});
|
|
286
|
+
return clampOutput(output || '(no output)');
|
|
287
|
+
}
|
|
288
|
+
catch (err) {
|
|
289
|
+
const stdout = err.stdout || '';
|
|
290
|
+
const stderr = err.stderr || '';
|
|
291
|
+
const code = err.status ?? 1;
|
|
292
|
+
return clampOutput(`Exit code: ${code}\n${stdout}\n${stderr}`.trim());
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
// ── Git executors ──
|
|
296
|
+
function git(cwd, args) {
|
|
297
|
+
try {
|
|
298
|
+
const output = execSync(`git ${args}`, {
|
|
299
|
+
cwd,
|
|
300
|
+
timeout: 15_000,
|
|
301
|
+
encoding: 'utf-8',
|
|
302
|
+
maxBuffer: 1024 * 1024 * 5,
|
|
303
|
+
stdio: ['pipe', 'pipe', 'pipe'],
|
|
304
|
+
});
|
|
305
|
+
return clampOutput(output || '(no output)');
|
|
306
|
+
}
|
|
307
|
+
catch (err) {
|
|
308
|
+
const stdout = err.stdout || '';
|
|
309
|
+
const stderr = err.stderr || '';
|
|
310
|
+
return clampOutput(`Error: ${stderr || stdout}`.trim());
|
|
311
|
+
}
|
|
312
|
+
}
|
|
313
|
+
function execGitStatus(cwd) {
|
|
314
|
+
return git(cwd, 'status');
|
|
315
|
+
}
|
|
316
|
+
function execGitDiff(cwd, args) {
|
|
317
|
+
const target = args.target || 'unstaged';
|
|
318
|
+
const pathSpec = args.path ? ` -- "${args.path}"` : '';
|
|
319
|
+
if (target === 'staged')
|
|
320
|
+
return git(cwd, `diff --cached${pathSpec}`);
|
|
321
|
+
if (target === 'unstaged')
|
|
322
|
+
return git(cwd, `diff${pathSpec}`);
|
|
323
|
+
return git(cwd, `diff ${target}${pathSpec}`);
|
|
324
|
+
}
|
|
325
|
+
function execGitLog(cwd, args) {
|
|
326
|
+
const count = args.count ?? 10;
|
|
327
|
+
const branch = args.branch || '';
|
|
328
|
+
const pathSpec = args.path ? ` -- "${args.path}"` : '';
|
|
329
|
+
return git(cwd, `log --oneline --decorate -n ${count} ${branch}${pathSpec}`);
|
|
330
|
+
}
|
|
331
|
+
function execGitCommit(cwd, args) {
|
|
332
|
+
if (args.files && args.files.length > 0) {
|
|
333
|
+
const fileList = args.files.map(f => `"${f}"`).join(' ');
|
|
334
|
+
git(cwd, `add ${fileList}`);
|
|
335
|
+
}
|
|
336
|
+
else {
|
|
337
|
+
git(cwd, 'add -A');
|
|
338
|
+
}
|
|
339
|
+
return git(cwd, `commit -m "${args.message.replace(/"/g, '\\"')}"`);
|
|
340
|
+
}
|
|
341
|
+
function execGitBranch(cwd, args) {
|
|
342
|
+
const action = args.action || 'list';
|
|
343
|
+
switch (action) {
|
|
344
|
+
case 'list':
|
|
345
|
+
return git(cwd, 'branch -a');
|
|
346
|
+
case 'create':
|
|
347
|
+
if (!args.name)
|
|
348
|
+
return 'Error: branch name is required';
|
|
349
|
+
return git(cwd, `checkout -b ${args.name}`);
|
|
350
|
+
case 'switch':
|
|
351
|
+
if (!args.name)
|
|
352
|
+
return 'Error: branch name is required';
|
|
353
|
+
return git(cwd, `checkout ${args.name}`);
|
|
354
|
+
default:
|
|
355
|
+
return `Error: unknown action "${action}"`;
|
|
356
|
+
}
|
|
357
|
+
}
|
|
358
|
+
// ── Executor dispatch ──
|
|
359
|
+
export function executeTool(cwd, call) {
|
|
360
|
+
let args;
|
|
361
|
+
try {
|
|
362
|
+
args = JSON.parse(call.function.arguments);
|
|
363
|
+
}
|
|
364
|
+
catch {
|
|
365
|
+
return { tool_call_id: call.id, name: call.function.name, content: 'Error: invalid JSON arguments' };
|
|
366
|
+
}
|
|
367
|
+
let content;
|
|
368
|
+
switch (call.function.name) {
|
|
369
|
+
case 'read_file':
|
|
370
|
+
content = execReadFile(cwd, args);
|
|
371
|
+
break;
|
|
372
|
+
case 'write_file':
|
|
373
|
+
content = execWriteFile(cwd, args);
|
|
374
|
+
break;
|
|
375
|
+
case 'edit_file':
|
|
376
|
+
content = execEditFile(cwd, args);
|
|
377
|
+
break;
|
|
378
|
+
case 'list_directory':
|
|
379
|
+
content = execListDirectory(cwd, args);
|
|
380
|
+
break;
|
|
381
|
+
case 'search_files':
|
|
382
|
+
content = execSearchFiles(cwd, args);
|
|
383
|
+
break;
|
|
384
|
+
case 'bash':
|
|
385
|
+
content = execBash(cwd, args);
|
|
386
|
+
break;
|
|
387
|
+
case 'git_status':
|
|
388
|
+
content = execGitStatus(cwd);
|
|
389
|
+
break;
|
|
390
|
+
case 'git_diff':
|
|
391
|
+
content = execGitDiff(cwd, args);
|
|
392
|
+
break;
|
|
393
|
+
case 'git_log':
|
|
394
|
+
content = execGitLog(cwd, args);
|
|
395
|
+
break;
|
|
396
|
+
case 'git_commit':
|
|
397
|
+
content = execGitCommit(cwd, args);
|
|
398
|
+
break;
|
|
399
|
+
case 'git_branch':
|
|
400
|
+
content = execGitBranch(cwd, args);
|
|
401
|
+
break;
|
|
402
|
+
default:
|
|
403
|
+
content = `Error: unknown tool "${call.function.name}"`;
|
|
404
|
+
}
|
|
405
|
+
return { tool_call_id: call.id, name: call.function.name, content };
|
|
406
|
+
}
|