pi-braid 0.44.5 → 0.45.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/AGENTS.md +1 -1
- package/CHANGELOG.md +31 -0
- package/README.md +1 -1
- package/TOOLS.md +3 -2
- package/build-info.json +4 -4
- package/dist/extensions/context-management/index.js +5 -0
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +2 -0
- package/dist/extensions/core/run-tool/index.d.ts +58 -0
- package/dist/extensions/core/run-tool/index.js +215 -0
- package/dist/extensions/core/run-tool/run.d.ts +122 -0
- package/dist/extensions/core/run-tool/run.js +394 -0
- package/dist/extensions/manifest.js +6 -0
- package/dist/lib/tools/tool-families.js +1 -0
- package/dist/lib/tools/workspace-guard.d.ts +70 -0
- package/dist/lib/tools/workspace-guard.js +111 -0
- package/docs/LOCAL_DEV.md +1 -1
- package/package.json +1 -1
- package/src/extensions/context-management/README.md +8 -8
- package/src/extensions/context-management/index.ts +5 -0
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +3 -0
- package/src/extensions/core/run-tool/index.ts +307 -0
- package/src/extensions/core/run-tool/run.ts +503 -0
- package/src/extensions/manifest.ts +6 -0
- package/src/lib/tools/tool-families.ts +1 -0
- package/src/lib/tools/workspace-guard.ts +134 -0
|
@@ -72,6 +72,7 @@ const PROFILES: Record<string, string[]> = {
|
|
|
72
72
|
"write",
|
|
73
73
|
// search & shell
|
|
74
74
|
"bash",
|
|
75
|
+
"run",
|
|
75
76
|
"grep",
|
|
76
77
|
"find",
|
|
77
78
|
"ls",
|
|
@@ -101,6 +102,7 @@ const PROFILES: Record<string, string[]> = {
|
|
|
101
102
|
"find",
|
|
102
103
|
"ls",
|
|
103
104
|
"bash",
|
|
105
|
+
"run",
|
|
104
106
|
"think",
|
|
105
107
|
"memory",
|
|
106
108
|
"scratchpad",
|
|
@@ -122,6 +124,7 @@ const PROFILES: Record<string, string[]> = {
|
|
|
122
124
|
"edit",
|
|
123
125
|
"write",
|
|
124
126
|
"bash",
|
|
127
|
+
"run",
|
|
125
128
|
"grep",
|
|
126
129
|
"find",
|
|
127
130
|
"ls",
|
|
@@ -149,6 +152,7 @@ const PROFILES: Record<string, string[]> = {
|
|
|
149
152
|
"browser_screenshot",
|
|
150
153
|
"read",
|
|
151
154
|
"bash",
|
|
155
|
+
"run",
|
|
152
156
|
"think",
|
|
153
157
|
"describe_image",
|
|
154
158
|
"fetch_content",
|
|
@@ -170,6 +174,7 @@ const PROFILES: Record<string, string[]> = {
|
|
|
170
174
|
"edit",
|
|
171
175
|
"write",
|
|
172
176
|
"bash",
|
|
177
|
+
"run",
|
|
173
178
|
"grep",
|
|
174
179
|
"find",
|
|
175
180
|
"ls",
|
|
@@ -94,6 +94,9 @@ export const TOOL_GUIDELINES: Record<string, string> = {
|
|
|
94
94
|
set_tool_profile:
|
|
95
95
|
"when: task scope is known — focused profiles cut prompt noise and token cost; args: lean/research/debugging/browser/deep",
|
|
96
96
|
|
|
97
|
+
// ── run-tool (default-enabled) ──
|
|
98
|
+
run: "when: one program and its argv, for tests, builds, git, wc, node, python; when-not: pipelines, redirection, heredocs, $(...) or globs (bash), or a destructive verb naming a path outside the workspace; args: argv + required timeout_ms (+ cwd/env/stdin/max_output_bytes); caveat: no TTY, no shell, no glob expansion; a stream past the cap keeps head and tail and names the file holding the rest",
|
|
99
|
+
|
|
97
100
|
// ── skills-tool (default-enabled) ──
|
|
98
101
|
list_skills:
|
|
99
102
|
"when: entering a domain that may have a skill; when-not: after the skill is loaded; args: page/pageSize/sectionsMax/rank; caveat: rows arrive ordered by relevance to the current task (rows with evidence carry relevance {score, reason}; the response carries ranking {tier, basis, policy}; rank: catalog for the plain order) and reach (reachable, lines, bytes, chars, estTokens, sectionCount, sections) prices the read — read the WHOLE SKILL.md before acting in the domain",
|
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* run — one program and its argument list, without a shell.
|
|
3
|
+
*
|
|
4
|
+
* The census behind this tool measured 223,137 bash calls out of 504,124 tool
|
|
5
|
+
* calls in a frozen session corpus, of which 24,793 (11.1%) carry no shell
|
|
6
|
+
* metacharacter at all: one program and its arguments. Those are the calls this
|
|
7
|
+
* tool replaces exactly; the rest need a shell (pipelines, redirection,
|
|
8
|
+
* heredocs, command substitution, loops), and this tool refuses the operators
|
|
9
|
+
* that would have made a call a shell program rather than growing into one.
|
|
10
|
+
*
|
|
11
|
+
* Shape: `argv` is the call; `cwd`, `env` and `stdin` carry its context; the
|
|
12
|
+
* timeout is required so no call can hang a session; `max_output_bytes` bounds
|
|
13
|
+
* each stream, and a stream past the cap keeps its head and its tail while the
|
|
14
|
+
* dropped byte count and the file holding the full text are named.
|
|
15
|
+
*
|
|
16
|
+
* The destructive guard is narrow on purpose: six verbs, and only when a path
|
|
17
|
+
* argument resolves outside the session workspace. The guard itself lives in
|
|
18
|
+
* `lib/tools/workspace-guard.ts`, so a later argv-shaped tool (`git`) passes its
|
|
19
|
+
* own verb set to the same mechanism instead of copying it.
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
import { copyFileSync, mkdirSync, statSync } from "node:fs";
|
|
23
|
+
import { dirname, resolve } from "node:path";
|
|
24
|
+
import type {
|
|
25
|
+
AgentToolUpdateCallback,
|
|
26
|
+
ExtensionAPI,
|
|
27
|
+
ExtensionToolContext,
|
|
28
|
+
ToolDefinition,
|
|
29
|
+
} from "@earendil-works/pi-coding-agent";
|
|
30
|
+
import { Type } from "typebox";
|
|
31
|
+
import type { Static } from "typebox";
|
|
32
|
+
import { getOffloadFilePath } from "../../../lib/config/braid-paths.js";
|
|
33
|
+
import {
|
|
34
|
+
DEFAULT_OUTPUT_BYTES,
|
|
35
|
+
MAX_OUTPUT_BYTES,
|
|
36
|
+
MAX_TIMEOUT_MS,
|
|
37
|
+
MIN_OUTPUT_BYTES,
|
|
38
|
+
boundStream,
|
|
39
|
+
capturePathFor,
|
|
40
|
+
discardCapture,
|
|
41
|
+
executeArgv,
|
|
42
|
+
findRefusal,
|
|
43
|
+
} from "./run.js";
|
|
44
|
+
import type { RunCapture, RunRequest, RunStream } from "./run.js";
|
|
45
|
+
|
|
46
|
+
/** Whether a path is a directory, with a missing path answering false. */
|
|
47
|
+
function isDirectory(path: string): boolean {
|
|
48
|
+
try {
|
|
49
|
+
return statSync(path).isDirectory();
|
|
50
|
+
} catch {
|
|
51
|
+
// A path that cannot be stat'd is not a directory this call can run in; the
|
|
52
|
+
// refusal below names it, which is more useful than the errno.
|
|
53
|
+
return false;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
const runParameters = Type.Object({
|
|
58
|
+
argv: Type.Array(Type.String(), {
|
|
59
|
+
minItems: 1,
|
|
60
|
+
description:
|
|
61
|
+
"The program and its arguments, one element each. argv[0] is the executable. No shell: pipes, redirection, heredocs and $(...) are refused.",
|
|
62
|
+
}),
|
|
63
|
+
cwd: Type.Optional(
|
|
64
|
+
Type.String({
|
|
65
|
+
description: "Working directory; relative to the session cwd. Defaults to the session cwd.",
|
|
66
|
+
}),
|
|
67
|
+
),
|
|
68
|
+
env: Type.Optional(
|
|
69
|
+
// A map of string to string, written as the keyword rather than a builder
|
|
70
|
+
// helper whose emitted schema the tool-surface gate would have to allow.
|
|
71
|
+
Type.Unsafe<Record<string, string>>({
|
|
72
|
+
type: "object",
|
|
73
|
+
additionalProperties: { type: "string" },
|
|
74
|
+
description: "Environment overrides merged over the session environment. Nothing is removed.",
|
|
75
|
+
}),
|
|
76
|
+
),
|
|
77
|
+
stdin: Type.Optional(
|
|
78
|
+
Type.String({ description: "Text written to the program's stdin; closed after writing." }),
|
|
79
|
+
),
|
|
80
|
+
timeout_ms: Type.Integer({
|
|
81
|
+
minimum: 1,
|
|
82
|
+
maximum: MAX_TIMEOUT_MS,
|
|
83
|
+
description: "Required. The program is killed when it outlives this many milliseconds.",
|
|
84
|
+
}),
|
|
85
|
+
max_output_bytes: Type.Optional(
|
|
86
|
+
Type.Integer({
|
|
87
|
+
minimum: MIN_OUTPUT_BYTES,
|
|
88
|
+
maximum: MAX_OUTPUT_BYTES,
|
|
89
|
+
description: `Byte cap per stream (stdout and stderr separately). Default ${DEFAULT_OUTPUT_BYTES}. Past the cap the head and tail are kept and the full text is written to a file named in the result.`,
|
|
90
|
+
}),
|
|
91
|
+
),
|
|
92
|
+
});
|
|
93
|
+
|
|
94
|
+
export type RunParameters = Static<typeof runParameters>;
|
|
95
|
+
|
|
96
|
+
/** Structured result for rendering and scripts. */
|
|
97
|
+
export interface RunToolDetails {
|
|
98
|
+
/** Present when the call was refused before a program started. */
|
|
99
|
+
refused?: string;
|
|
100
|
+
cwd?: string;
|
|
101
|
+
exit_code?: number | null;
|
|
102
|
+
signal?: string | null;
|
|
103
|
+
timed_out?: boolean;
|
|
104
|
+
aborted?: boolean;
|
|
105
|
+
duration_ms?: number;
|
|
106
|
+
stdout?: StreamDetails;
|
|
107
|
+
stderr?: StreamDetails;
|
|
108
|
+
/** Present when the child could not be started at all. */
|
|
109
|
+
spawn_error?: string;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
interface StreamDetails {
|
|
113
|
+
bytes: number;
|
|
114
|
+
shown_bytes: number;
|
|
115
|
+
dropped_bytes: number;
|
|
116
|
+
truncated: boolean;
|
|
117
|
+
full_text_path?: string;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
function streamDetails(stream: RunStream): StreamDetails {
|
|
121
|
+
return {
|
|
122
|
+
bytes: stream.bytes,
|
|
123
|
+
shown_bytes: stream.shownBytes,
|
|
124
|
+
dropped_bytes: stream.droppedBytes,
|
|
125
|
+
truncated: stream.truncated,
|
|
126
|
+
...(stream.fullTextPath ? { full_text_path: stream.fullTextPath } : {}),
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
function numberLine(bytes: number): string {
|
|
131
|
+
return bytes.toLocaleString("en-US");
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* The offload target for one truncated stream. The capture is copied, not moved:
|
|
136
|
+
* the temp file is the fallback when the copy fails, and the result names
|
|
137
|
+
* whichever path actually holds the text.
|
|
138
|
+
*/
|
|
139
|
+
function offload(
|
|
140
|
+
capture: RunCapture,
|
|
141
|
+
stream: "stdout" | "stderr",
|
|
142
|
+
sessionId: string,
|
|
143
|
+
toolCallId: string,
|
|
144
|
+
): string | undefined {
|
|
145
|
+
const source = capturePathFor(capture, stream);
|
|
146
|
+
const target = getOffloadFilePath(
|
|
147
|
+
sessionId,
|
|
148
|
+
toolCallId,
|
|
149
|
+
stream === "stdout" ? "run-stdout" : "run-stderr",
|
|
150
|
+
);
|
|
151
|
+
try {
|
|
152
|
+
mkdirSync(dirname(target), { recursive: true });
|
|
153
|
+
copyFileSync(source, target);
|
|
154
|
+
return target;
|
|
155
|
+
} catch {
|
|
156
|
+
// The full text is still in the capture directory; keeping it there and
|
|
157
|
+
// naming that path is better than losing it to a failed copy.
|
|
158
|
+
return undefined;
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** Render one stream as a labelled section, with its truncation note. */
|
|
163
|
+
function renderStream(label: "stdout" | "stderr", stream: RunStream): string {
|
|
164
|
+
const body = stream.text;
|
|
165
|
+
const sections: string[] = [];
|
|
166
|
+
const text = body.endsWith("\n") || body === "" ? body : `${body}\n`;
|
|
167
|
+
sections.push(`${label}:\n${text}`);
|
|
168
|
+
if (stream.truncated) {
|
|
169
|
+
sections.push(
|
|
170
|
+
`[${label}: showing ${numberLine(stream.shownBytes)} of ${numberLine(stream.bytes)} bytes ` +
|
|
171
|
+
`with ${numberLine(stream.droppedBytes)} omitted; full text: ${stream.fullTextPath}]`,
|
|
172
|
+
);
|
|
173
|
+
}
|
|
174
|
+
return sections.join("\n");
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** The one-line outcome, so a failure is readable before the output. */
|
|
178
|
+
function statusLine(params: RunParameters, capture: RunCapture): string {
|
|
179
|
+
if (capture.spawnError !== undefined) {
|
|
180
|
+
return `could not start ${params.argv[0]}: ${capture.spawnError}`;
|
|
181
|
+
}
|
|
182
|
+
if (capture.timedOut) {
|
|
183
|
+
return `timed out after ${params.timeout_ms}ms: killed`;
|
|
184
|
+
}
|
|
185
|
+
if (capture.aborted) {
|
|
186
|
+
return `aborted: killed after ${capture.durationMs}ms`;
|
|
187
|
+
}
|
|
188
|
+
if (capture.signal !== null) {
|
|
189
|
+
return `killed by ${capture.signal} after ${capture.durationMs}ms`;
|
|
190
|
+
}
|
|
191
|
+
const code = capture.exitCode ?? "none";
|
|
192
|
+
const cwd = params.cwd === undefined ? "" : ` · cwd ${capture.cwd}`;
|
|
193
|
+
return `exit ${code} · ${capture.durationMs}ms${cwd}`;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** Whether the call is an error for the model: a refusal, a timeout, or a non-zero exit. */
|
|
197
|
+
function isFailure(capture: RunCapture): boolean {
|
|
198
|
+
return (
|
|
199
|
+
capture.spawnError !== undefined ||
|
|
200
|
+
capture.timedOut ||
|
|
201
|
+
capture.aborted ||
|
|
202
|
+
capture.exitCode !== 0
|
|
203
|
+
);
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
export function createRunTool(): ToolDefinition<typeof runParameters, RunToolDetails> {
|
|
207
|
+
return {
|
|
208
|
+
name: "run",
|
|
209
|
+
label: "Run",
|
|
210
|
+
description:
|
|
211
|
+
"Execute one program with an argument list, without a shell. Returns stdout and stderr separately, each capped at max_output_bytes with the dropped bytes named and the full text in a file. Use for a single program and its arguments: tests, builds, git, wc, node, python, rg. A shell-only command keeps needing bash, and is refused here rather than reinterpreted: pipes, redirection, heredocs and command substitution (an argument carrying |, &&, ;, a backtick or $( is refused), glob expansion (a glob-shaped path such as *.md or src/* is refused; pass the paths or use find/grep), and a shell invoked with -c. argv[0] from a destructive set (rm, mv, dd, chmod, shred, truncate) is refused when a path argument resolves outside the session workspace. There is no TTY: a program that needs a terminal fails on its own terms. timeout_ms is required, and a program that outlives it is killed.",
|
|
212
|
+
parameters: runParameters,
|
|
213
|
+
async execute(
|
|
214
|
+
toolCallId: string,
|
|
215
|
+
params: RunParameters,
|
|
216
|
+
signal: AbortSignal | undefined,
|
|
217
|
+
_onUpdate: AgentToolUpdateCallback<RunToolDetails> | undefined,
|
|
218
|
+
ctx: ExtensionToolContext,
|
|
219
|
+
) {
|
|
220
|
+
const sessionCwd = ctx.cwd;
|
|
221
|
+
const workspaceRoot = sessionCwd;
|
|
222
|
+
const cwd = resolve(sessionCwd, params.cwd ?? ".");
|
|
223
|
+
const request: RunRequest = {
|
|
224
|
+
argv: params.argv,
|
|
225
|
+
...(params.cwd === undefined ? {} : { cwd: params.cwd }),
|
|
226
|
+
...(params.env === undefined ? {} : { env: params.env }),
|
|
227
|
+
...(params.stdin === undefined ? {} : { stdin: params.stdin }),
|
|
228
|
+
timeout_ms: params.timeout_ms,
|
|
229
|
+
...(params.max_output_bytes === undefined
|
|
230
|
+
? {}
|
|
231
|
+
: { max_output_bytes: params.max_output_bytes }),
|
|
232
|
+
};
|
|
233
|
+
|
|
234
|
+
// The cwd is a filesystem fact, so it is read before the pure refusals:
|
|
235
|
+
// every path in the guard is resolved against it.
|
|
236
|
+
if (!isDirectory(cwd)) {
|
|
237
|
+
const message = `refused: cwd ${cwd} does not exist or is not a directory. A call is not run against a missing directory.`;
|
|
238
|
+
return {
|
|
239
|
+
content: [{ type: "text" as const, text: message }],
|
|
240
|
+
details: { refused: "cwd", cwd } satisfies RunToolDetails,
|
|
241
|
+
isError: true,
|
|
242
|
+
};
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
const refusal = findRefusal(request, { cwd, workspaceRoot });
|
|
246
|
+
if (refusal) {
|
|
247
|
+
return {
|
|
248
|
+
content: [{ type: "text" as const, text: refusal.message }],
|
|
249
|
+
details: { refused: refusal.kind, cwd } satisfies RunToolDetails,
|
|
250
|
+
isError: true,
|
|
251
|
+
};
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
const capture = await executeArgv(request, { cwd, workspaceRoot }, signal);
|
|
255
|
+
const cap = params.max_output_bytes ?? DEFAULT_OUTPUT_BYTES;
|
|
256
|
+
const sessionId = ctx.sessionManager?.getSessionId?.() ?? "anonymous";
|
|
257
|
+
const stdoutPath =
|
|
258
|
+
capture.stdoutBytes > cap ? offload(capture, "stdout", sessionId, toolCallId) : undefined;
|
|
259
|
+
const stderrPath =
|
|
260
|
+
capture.stderrBytes > cap ? offload(capture, "stderr", sessionId, toolCallId) : undefined;
|
|
261
|
+
const offloadFailed =
|
|
262
|
+
(capture.stdoutBytes > cap && stdoutPath === undefined) ||
|
|
263
|
+
(capture.stderrBytes > cap && stderrPath === undefined);
|
|
264
|
+
const stdout = boundStream(
|
|
265
|
+
capture.stdoutPath,
|
|
266
|
+
cap,
|
|
267
|
+
stdoutPath ?? (capture.stdoutBytes > cap ? capture.stdoutPath : undefined),
|
|
268
|
+
);
|
|
269
|
+
const stderr = boundStream(
|
|
270
|
+
capture.stderrPath,
|
|
271
|
+
cap,
|
|
272
|
+
stderrPath ?? (capture.stderrBytes > cap ? capture.stderrPath : undefined),
|
|
273
|
+
);
|
|
274
|
+
// A failed offload keeps the capture directory: the result names that
|
|
275
|
+
// path, so it must still exist when the reader follows it.
|
|
276
|
+
if (!offloadFailed) discardCapture(capture);
|
|
277
|
+
|
|
278
|
+
const lines = [statusLine(params, capture)];
|
|
279
|
+
if (stdout.text === "" && stderr.text === "") {
|
|
280
|
+
lines.push("(no output)");
|
|
281
|
+
} else {
|
|
282
|
+
if (stdout.text !== "") lines.push(renderStream("stdout", stdout));
|
|
283
|
+
if (stderr.text !== "") lines.push(renderStream("stderr", stderr));
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
return {
|
|
287
|
+
content: [{ type: "text" as const, text: lines.join("\n\n") }],
|
|
288
|
+
details: {
|
|
289
|
+
cwd: capture.cwd,
|
|
290
|
+
exit_code: capture.exitCode,
|
|
291
|
+
signal: capture.signal,
|
|
292
|
+
timed_out: capture.timedOut,
|
|
293
|
+
aborted: capture.aborted,
|
|
294
|
+
duration_ms: capture.durationMs,
|
|
295
|
+
stdout: streamDetails(stdout),
|
|
296
|
+
stderr: streamDetails(stderr),
|
|
297
|
+
...(capture.spawnError === undefined ? {} : { spawn_error: capture.spawnError }),
|
|
298
|
+
} satisfies RunToolDetails,
|
|
299
|
+
isError: isFailure(capture),
|
|
300
|
+
};
|
|
301
|
+
},
|
|
302
|
+
};
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
export default function runToolExtension(pi: ExtensionAPI): void {
|
|
306
|
+
pi.registerTool(createRunTool());
|
|
307
|
+
}
|