@buildanagent/harness 0.1.0-alpha.28 → 0.1.0-alpha.29
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 +111 -5
- package/dist/context/file-spill.d.ts +11 -1
- package/dist/context/file-spill.js +23 -8
- package/dist/context/file-spill.js.map +1 -1
- package/dist/context/spill.d.ts +5 -1
- package/dist/context/spill.js +6 -2
- package/dist/context/spill.js.map +1 -1
- package/dist/credentials/allowlist.d.ts +22 -2
- package/dist/credentials/allowlist.js +74 -17
- package/dist/credentials/allowlist.js.map +1 -1
- package/dist/credentials/egress-policy.d.ts +69 -0
- package/dist/credentials/egress-policy.js +170 -0
- package/dist/credentials/egress-policy.js.map +1 -0
- package/dist/credentials/egress-proxy.d.ts +13 -1
- package/dist/credentials/egress-proxy.js +179 -11
- package/dist/credentials/egress-proxy.js.map +1 -1
- package/dist/credentials/git-route.d.ts +68 -0
- package/dist/credentials/git-route.js +288 -0
- package/dist/credentials/git-route.js.map +1 -0
- package/dist/credentials/index.d.ts +5 -1
- package/dist/credentials/index.js +5 -1
- package/dist/credentials/index.js.map +1 -1
- package/dist/credentials/scrub.d.ts +7 -0
- package/dist/credentials/scrub.js +22 -0
- package/dist/credentials/scrub.js.map +1 -1
- package/dist/errors.d.ts +9 -5
- package/dist/errors.js +8 -4
- package/dist/errors.js.map +1 -1
- package/dist/sandbox/base.d.ts +11 -1
- package/dist/sandbox/base.js +14 -0
- package/dist/sandbox/base.js.map +1 -1
- package/dist/sandbox/docker/index.d.ts +8 -2
- package/dist/sandbox/docker/index.js +63 -14
- package/dist/sandbox/docker/index.js.map +1 -1
- package/dist/sandbox/errors.d.ts +30 -2
- package/dist/sandbox/errors.js +36 -1
- package/dist/sandbox/errors.js.map +1 -1
- package/dist/sandbox/host-files.d.ts +2 -0
- package/dist/sandbox/host-files.js +10 -0
- package/dist/sandbox/host-files.js.map +1 -1
- package/dist/sandbox/index.d.ts +6 -4
- package/dist/sandbox/index.js +5 -3
- package/dist/sandbox/index.js.map +1 -1
- package/dist/sandbox/policy.d.ts +49 -0
- package/dist/sandbox/policy.js +149 -0
- package/dist/sandbox/policy.js.map +1 -0
- package/dist/sandbox/process.js +1 -1
- package/dist/sandbox/process.js.map +1 -1
- package/dist/sandbox/srt/index.d.ts +5 -2
- package/dist/sandbox/srt/index.js +27 -8
- package/dist/sandbox/srt/index.js.map +1 -1
- package/dist/sandbox/srt/settings.d.ts +17 -5
- package/dist/sandbox/srt/settings.js +53 -0
- package/dist/sandbox/srt/settings.js.map +1 -1
- package/dist/sandbox/types.d.ts +41 -4
- package/dist/sandbox/types.js.map +1 -1
- package/dist/testing/fake-sandbox.d.ts +21 -3
- package/dist/testing/fake-sandbox.js +157 -8
- package/dist/testing/fake-sandbox.js.map +1 -1
- package/dist/testing/sandbox-conformance.js +108 -1
- package/dist/testing/sandbox-conformance.js.map +1 -1
- package/dist/tools/builtins/bash.d.ts +9 -0
- package/dist/tools/builtins/bash.js +75 -0
- package/dist/tools/builtins/bash.js.map +1 -0
- package/dist/tools/builtins/builtins.d.ts +38 -0
- package/dist/tools/builtins/builtins.js +48 -0
- package/dist/tools/builtins/builtins.js.map +1 -0
- package/dist/tools/builtins/descriptions.d.ts +69 -0
- package/dist/tools/builtins/descriptions.js +94 -0
- package/dist/tools/builtins/descriptions.js.map +1 -0
- package/dist/tools/builtins/fetch.d.ts +12 -0
- package/dist/tools/builtins/fetch.js +157 -0
- package/dist/tools/builtins/fetch.js.map +1 -0
- package/dist/tools/builtins/files.d.ts +27 -0
- package/dist/tools/builtins/files.js +274 -0
- package/dist/tools/builtins/files.js.map +1 -0
- package/dist/tools/builtins/paths.d.ts +30 -0
- package/dist/tools/builtins/paths.js +62 -0
- package/dist/tools/builtins/paths.js.map +1 -0
- package/dist/tools/builtins/results.d.ts +15 -0
- package/dist/tools/builtins/results.js +31 -0
- package/dist/tools/builtins/results.js.map +1 -0
- package/dist/tools/builtins/search.d.ts +18 -0
- package/dist/tools/builtins/search.js +217 -0
- package/dist/tools/builtins/search.js.map +1 -0
- package/dist/tools/index.d.ts +6 -2
- package/dist/tools/index.js +5 -2
- package/dist/tools/index.js.map +1 -1
- package/llms.txt +34 -0
- package/package.json +5 -5
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `read`, `write` and `edit`: the file tools. Each checks its path against the policy's roots before it calls the
|
|
3
|
+
* sandbox, and reads and writes only through `Sandbox.readFile()` and `Sandbox.writeFile()`. `read` keeps the input
|
|
4
|
+
* names `path`, `file_path`, `offset` and `limit`, which the skill loader matches when it records a skill as loaded.
|
|
5
|
+
*/
|
|
6
|
+
import { defineTool } from "@buildanagent/sdk";
|
|
7
|
+
import { escapedBytes } from "../../context/write-cap.js";
|
|
8
|
+
import { normalizePath } from "../../permissions/match.js";
|
|
9
|
+
import { BUILTIN_TOOL_DEFAULTS } from "./descriptions.js";
|
|
10
|
+
import { checkPath, pathInput, unusablePath } from "./paths.js";
|
|
11
|
+
import { errorResult, failureResult, textResult } from "./results.js";
|
|
12
|
+
/**
|
|
13
|
+
* Every file and search tool returns this key, so the step scheduler treats the workspace as one resource: reads run
|
|
14
|
+
* together and wait for the writes the model sent before them, and a write waits for the reads before it.
|
|
15
|
+
*/
|
|
16
|
+
export const WORKSPACE_KEY = "workspace";
|
|
17
|
+
const ENCODER = new TextEncoder();
|
|
18
|
+
const DECODER = new TextDecoder();
|
|
19
|
+
// `edit` writes the whole file back, so it reads it strictly: a byte that is not UTF-8 refuses the edit instead of
|
|
20
|
+
// becoming U+FFFD, and a byte order mark stays in the text, so it is written back too.
|
|
21
|
+
const STRICT_DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
|
|
22
|
+
// A NUL byte in the first part of a file marks it as binary, as grep and git decide.
|
|
23
|
+
const BINARY_PROBE_BYTES = 8000;
|
|
24
|
+
const PATH_PROPERTIES = {
|
|
25
|
+
path: { type: "string", description: "The file, relative to the workspace root or absolute." },
|
|
26
|
+
file_path: { type: "string", description: "The same as `path`, under the name some models use." },
|
|
27
|
+
};
|
|
28
|
+
/**
|
|
29
|
+
* The longest start of `text` whose JSON-escaped form fits in `bytes`, without splitting a character, and never less
|
|
30
|
+
* than one character. Every character takes at least one byte, so the start is at most `bytes` characters long, and a
|
|
31
|
+
* binary search over that range finds it in a few measures.
|
|
32
|
+
*/
|
|
33
|
+
function headOf(text, bytes) {
|
|
34
|
+
let low = 0;
|
|
35
|
+
let high = Math.min(text.length, bytes);
|
|
36
|
+
while (low < high) {
|
|
37
|
+
const middle = (low + high + 1) >> 1;
|
|
38
|
+
if (escapedBytes(text.slice(0, middle)) <= bytes)
|
|
39
|
+
low = middle;
|
|
40
|
+
else
|
|
41
|
+
high = middle - 1;
|
|
42
|
+
}
|
|
43
|
+
// A start that ends on the first half of a surrogate pair would split its character.
|
|
44
|
+
const code = text.charCodeAt(low - 1);
|
|
45
|
+
const end = low > 0 && code >= 0xd800 && code <= 0xdbff ? low - 1 : low;
|
|
46
|
+
return end === 0 ? String.fromCodePoint(text.codePointAt(0) ?? 0) : text.slice(0, end);
|
|
47
|
+
}
|
|
48
|
+
// A page is measured as the write cap measures a result: by its bytes inside the log's JSON string. A quote, a
|
|
49
|
+
// backslash or a newline takes two bytes there and a control character six, so a page budgeted by raw bytes could pass
|
|
50
|
+
// the cap, be cut and spilled again, and a spill read that way would never show its whole text.
|
|
51
|
+
const NEWLINE_BYTES = escapedBytes("\n");
|
|
52
|
+
/**
|
|
53
|
+
* The lines of `span`, at most `maxBytes` of them once JSON-escaped, with a line that says where to read on when some
|
|
54
|
+
* are left. A first line longer than a page is shown in part, with the column the next part starts at.
|
|
55
|
+
*/
|
|
56
|
+
function pageOf(lines, path, span) {
|
|
57
|
+
const { start, column, last } = span;
|
|
58
|
+
const total = lines.length;
|
|
59
|
+
const from = column > 0 ? { column: column + 1 } : {};
|
|
60
|
+
let shown = "";
|
|
61
|
+
let budget = BUILTIN_TOOL_DEFAULTS.read.maxBytes;
|
|
62
|
+
let line = start;
|
|
63
|
+
for (; line < last; line += 1) {
|
|
64
|
+
const piece = line === start ? (lines[line] ?? "").slice(column) : (lines[line] ?? "");
|
|
65
|
+
const size = escapedBytes(piece) + NEWLINE_BYTES;
|
|
66
|
+
if (size > budget && line > start)
|
|
67
|
+
break;
|
|
68
|
+
if (size > budget) {
|
|
69
|
+
const part = headOf(piece, budget - NEWLINE_BYTES);
|
|
70
|
+
const more = `[line ${line + 1} of ${total} goes on; read on with offset ${line + 1} and column ${column + part.length + 1}]`;
|
|
71
|
+
return textResult(`${part}\n${more}`, { path, from: line + 1, to: line + 1, ...from, lines: total });
|
|
72
|
+
}
|
|
73
|
+
shown += `${piece}\n`;
|
|
74
|
+
budget -= size;
|
|
75
|
+
}
|
|
76
|
+
const more = line < total ? `[lines ${start + 1} to ${line} of ${total}; read on with offset ${line + 1}]` : "";
|
|
77
|
+
return textResult(`${shown}${more}`, { path, from: start + 1, to: line, ...from, lines: total });
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* The part of `text` that `offset`, `column` and `limit` select, at most `maxBytes` of it once JSON-escaped. A line
|
|
81
|
+
* longer than a page is shown in parts, each naming the column the next starts at, so every byte of a long result can
|
|
82
|
+
* be read, even one that is a single line.
|
|
83
|
+
*/
|
|
84
|
+
function page(text, path, input) {
|
|
85
|
+
const { defaultLimit, maxBytes } = BUILTIN_TOOL_DEFAULTS.read;
|
|
86
|
+
if (text === "")
|
|
87
|
+
return textResult(`(${path} is empty)`, { path, lines: 0 });
|
|
88
|
+
const lines = text.split("\n");
|
|
89
|
+
if (text.endsWith("\n"))
|
|
90
|
+
lines.pop();
|
|
91
|
+
const total = lines.length;
|
|
92
|
+
const unpaged = input.offset === undefined && input.limit === undefined && input.column === undefined;
|
|
93
|
+
if (unpaged && total <= defaultLimit && escapedBytes(text) <= maxBytes)
|
|
94
|
+
return textResult(text, { path, lines: total });
|
|
95
|
+
const start = (input.offset ?? 1) - 1;
|
|
96
|
+
if (start >= total)
|
|
97
|
+
return errorResult(`The offset ${start + 1} is past the end of ${path}, which has ${total} lines.`);
|
|
98
|
+
const column = (input.column ?? 1) - 1;
|
|
99
|
+
if (column > 0 && column >= (lines[start] ?? "").length) {
|
|
100
|
+
return errorResult(`The column ${column + 1} is past the end of line ${start + 1} of ${path}, which is shorter.`);
|
|
101
|
+
}
|
|
102
|
+
return pageOf(lines, path, { start, column, last: Math.min(total, start + (input.limit ?? defaultLimit)) });
|
|
103
|
+
}
|
|
104
|
+
async function readFile(deps, input) {
|
|
105
|
+
const chosen = pathInput(input);
|
|
106
|
+
if (typeof chosen !== "string")
|
|
107
|
+
return errorResult(chosen.refused);
|
|
108
|
+
const unusable = unusablePath(chosen);
|
|
109
|
+
if (unusable !== undefined)
|
|
110
|
+
return errorResult(unusable);
|
|
111
|
+
// A spill file is the harness's own copy of an earlier result, outside the sandbox, and the cap names it by an
|
|
112
|
+
// absolute path. Only such a path asks the spill reader, so a relative path always means a workspace file, never a
|
|
113
|
+
// spill that happens to share its name.
|
|
114
|
+
if (deps.spills !== undefined && chosen.startsWith("/")) {
|
|
115
|
+
const spillPath = normalizePath(chosen);
|
|
116
|
+
const spilled = await deps.spills(spillPath);
|
|
117
|
+
if (spilled !== undefined)
|
|
118
|
+
return page(spilled, spillPath, input);
|
|
119
|
+
}
|
|
120
|
+
const checked = checkPath(deps.bounds, chosen, "read");
|
|
121
|
+
if ("refused" in checked)
|
|
122
|
+
return errorResult(checked.refused);
|
|
123
|
+
let bytes;
|
|
124
|
+
try {
|
|
125
|
+
bytes = await deps.sandbox.readFile(checked.path);
|
|
126
|
+
}
|
|
127
|
+
catch (error) {
|
|
128
|
+
return failureResult(error);
|
|
129
|
+
}
|
|
130
|
+
if (bytes.subarray(0, BINARY_PROBE_BYTES).includes(0)) {
|
|
131
|
+
return errorResult(`${checked.path} is a binary file of ${bytes.length} bytes, and read returns only text.`);
|
|
132
|
+
}
|
|
133
|
+
return page(DECODER.decode(bytes), checked.path, input);
|
|
134
|
+
}
|
|
135
|
+
/** The `read` tool. */
|
|
136
|
+
export function readTool(deps) {
|
|
137
|
+
return defineTool({
|
|
138
|
+
name: "read",
|
|
139
|
+
description: BUILTIN_TOOL_DEFAULTS.read.description,
|
|
140
|
+
inputSchema: {
|
|
141
|
+
type: "object",
|
|
142
|
+
properties: {
|
|
143
|
+
...PATH_PROPERTIES,
|
|
144
|
+
offset: { type: "integer", minimum: 1, description: "The first line to read, counting from 1." },
|
|
145
|
+
column: {
|
|
146
|
+
type: "integer",
|
|
147
|
+
minimum: 1,
|
|
148
|
+
description: "Where to start in the first line, counting from 1, to read on in a line too long for one page.",
|
|
149
|
+
},
|
|
150
|
+
limit: { type: "integer", minimum: 1, description: "How many lines to read." },
|
|
151
|
+
},
|
|
152
|
+
additionalProperties: false,
|
|
153
|
+
},
|
|
154
|
+
firstParty: true,
|
|
155
|
+
annotations: { readOnlyHint: true },
|
|
156
|
+
resourceKey: () => WORKSPACE_KEY,
|
|
157
|
+
execute: (input) => readFile(deps, input),
|
|
158
|
+
});
|
|
159
|
+
}
|
|
160
|
+
/** The `write` tool. */
|
|
161
|
+
export function writeTool(deps) {
|
|
162
|
+
return defineTool({
|
|
163
|
+
name: "write",
|
|
164
|
+
description: BUILTIN_TOOL_DEFAULTS.write.description,
|
|
165
|
+
inputSchema: {
|
|
166
|
+
type: "object",
|
|
167
|
+
properties: { ...PATH_PROPERTIES, content: { type: "string", description: "The file's whole new text." } },
|
|
168
|
+
required: ["content"],
|
|
169
|
+
additionalProperties: false,
|
|
170
|
+
},
|
|
171
|
+
firstParty: true,
|
|
172
|
+
effect: { kind: "write" },
|
|
173
|
+
resourceKey: () => WORKSPACE_KEY,
|
|
174
|
+
async execute(input) {
|
|
175
|
+
const chosen = pathInput(input);
|
|
176
|
+
if (typeof chosen !== "string")
|
|
177
|
+
return errorResult(chosen.refused);
|
|
178
|
+
const checked = checkPath(deps.bounds, chosen, "write");
|
|
179
|
+
if ("refused" in checked)
|
|
180
|
+
return errorResult(checked.refused);
|
|
181
|
+
const bytes = ENCODER.encode(input.content);
|
|
182
|
+
try {
|
|
183
|
+
await deps.sandbox.writeFile(checked.path, bytes);
|
|
184
|
+
}
|
|
185
|
+
catch (error) {
|
|
186
|
+
return failureResult(error);
|
|
187
|
+
}
|
|
188
|
+
return textResult(`Wrote ${bytes.length} bytes to ${checked.path}.`, { path: checked.path, bytes: bytes.length });
|
|
189
|
+
},
|
|
190
|
+
});
|
|
191
|
+
}
|
|
192
|
+
/** How many times `needle` occurs in `text`, counting matches that don't overlap. */
|
|
193
|
+
function occurrences(text, needle) {
|
|
194
|
+
let count = 0;
|
|
195
|
+
for (let at = text.indexOf(needle); at >= 0; at = text.indexOf(needle, at + needle.length))
|
|
196
|
+
count += 1;
|
|
197
|
+
return count;
|
|
198
|
+
}
|
|
199
|
+
/** The edited text, or the sentence that says why the edit can't be made and nothing was changed. */
|
|
200
|
+
function edited(text, input, path) {
|
|
201
|
+
if (input.old_string === "")
|
|
202
|
+
return { refused: "`old_string` is empty; use write to create or replace a file." };
|
|
203
|
+
if (input.old_string === input.new_string)
|
|
204
|
+
return { refused: "`old_string` and `new_string` are the same." };
|
|
205
|
+
const count = occurrences(text, input.old_string);
|
|
206
|
+
if (count === 0)
|
|
207
|
+
return { refused: `\`old_string\` does not occur in ${path}, so nothing was changed.` };
|
|
208
|
+
if (count > 1 && input.replace_all !== true) {
|
|
209
|
+
return {
|
|
210
|
+
refused: `\`old_string\` occurs ${count} times in ${path}, so nothing was changed. Add surrounding lines until it ` +
|
|
211
|
+
"is unique, or set `replace_all` to replace every match.",
|
|
212
|
+
};
|
|
213
|
+
}
|
|
214
|
+
// A function replacement keeps `$&` and the other replacement patterns in `new_string` as written.
|
|
215
|
+
return input.replace_all === true
|
|
216
|
+
? text.replaceAll(input.old_string, () => input.new_string)
|
|
217
|
+
: text.replace(input.old_string, () => input.new_string);
|
|
218
|
+
}
|
|
219
|
+
async function editFile(deps, input) {
|
|
220
|
+
const chosen = pathInput(input);
|
|
221
|
+
if (typeof chosen !== "string")
|
|
222
|
+
return errorResult(chosen.refused);
|
|
223
|
+
const checked = checkPath(deps.bounds, chosen, "write");
|
|
224
|
+
if ("refused" in checked)
|
|
225
|
+
return errorResult(checked.refused);
|
|
226
|
+
try {
|
|
227
|
+
const bytes = await deps.sandbox.readFile(checked.path);
|
|
228
|
+
if (bytes.subarray(0, BINARY_PROBE_BYTES).includes(0)) {
|
|
229
|
+
return errorResult(`${checked.path} is a binary file, and edit changes only text, so nothing was changed.`);
|
|
230
|
+
}
|
|
231
|
+
let text;
|
|
232
|
+
try {
|
|
233
|
+
text = STRICT_DECODER.decode(bytes);
|
|
234
|
+
}
|
|
235
|
+
catch {
|
|
236
|
+
return errorResult(`${checked.path} is not UTF-8 text, and edit would corrupt it, so nothing was changed. Use bash to change it.`);
|
|
237
|
+
}
|
|
238
|
+
const next = edited(text, input, checked.path);
|
|
239
|
+
if (typeof next !== "string")
|
|
240
|
+
return errorResult(next.refused);
|
|
241
|
+
await deps.sandbox.writeFile(checked.path, ENCODER.encode(next));
|
|
242
|
+
const count = input.replace_all === true ? occurrences(text, input.old_string) : 1;
|
|
243
|
+
return textResult(`Replaced ${count} match${count === 1 ? "" : "es"} in ${checked.path}.`, {
|
|
244
|
+
path: checked.path,
|
|
245
|
+
replaced: count,
|
|
246
|
+
});
|
|
247
|
+
}
|
|
248
|
+
catch (error) {
|
|
249
|
+
return failureResult(error);
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
/** The `edit` tool. */
|
|
253
|
+
export function editTool(deps) {
|
|
254
|
+
return defineTool({
|
|
255
|
+
name: "edit",
|
|
256
|
+
description: BUILTIN_TOOL_DEFAULTS.edit.description,
|
|
257
|
+
inputSchema: {
|
|
258
|
+
type: "object",
|
|
259
|
+
properties: {
|
|
260
|
+
...PATH_PROPERTIES,
|
|
261
|
+
old_string: { type: "string", description: "The exact text to replace." },
|
|
262
|
+
new_string: { type: "string", description: "The text to put in its place." },
|
|
263
|
+
replace_all: { type: "boolean", description: "Replace every match instead of requiring exactly one." },
|
|
264
|
+
},
|
|
265
|
+
required: ["old_string", "new_string"],
|
|
266
|
+
additionalProperties: false,
|
|
267
|
+
},
|
|
268
|
+
firstParty: true,
|
|
269
|
+
effect: { kind: "write" },
|
|
270
|
+
resourceKey: () => WORKSPACE_KEY,
|
|
271
|
+
execute: (input) => editFile(deps, input),
|
|
272
|
+
});
|
|
273
|
+
}
|
|
274
|
+
//# sourceMappingURL=files.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"files.js","sourceRoot":"","sources":["../../../src/tools/builtins/files.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `read`, `write` and `edit`: the file tools. Each checks its path against the policy's roots before it calls the\n * sandbox, and reads and writes only through `Sandbox.readFile()` and `Sandbox.writeFile()`. `read` keeps the input\n * names `path`, `file_path`, `offset` and `limit`, which the skill loader matches when it records a skill as loaded.\n */\nimport { defineTool, type ToolDefinition, type ToolResult } from \"@buildanagent/sdk\";\nimport { escapedBytes } from \"../../context/write-cap.js\";\nimport { normalizePath } from \"../../permissions/match.js\";\nimport type { Sandbox } from \"../../sandbox/types.js\";\nimport { BUILTIN_TOOL_DEFAULTS } from \"./descriptions.js\";\nimport { type Bounds, checkPath, pathInput, unusablePath } from \"./paths.js\";\nimport { errorResult, failureResult, textResult } from \"./results.js\";\n\n/** What the file and search tools share: the sandbox, the bounds its policy sets, and the session's spill reader. */\nexport interface FileDeps {\n readonly sandbox: Sandbox;\n readonly bounds: Bounds;\n readonly spills?: (path: string) => string | undefined | Promise<string | undefined>;\n}\n\ntype AnyTool = ToolDefinition<unknown, unknown, unknown>;\n\n/**\n * Every file and search tool returns this key, so the step scheduler treats the workspace as one resource: reads run\n * together and wait for the writes the model sent before them, and a write waits for the reads before it.\n */\nexport const WORKSPACE_KEY = \"workspace\";\n\nconst ENCODER = new TextEncoder();\nconst DECODER = new TextDecoder();\n// `edit` writes the whole file back, so it reads it strictly: a byte that is not UTF-8 refuses the edit instead of\n// becoming U+FFFD, and a byte order mark stays in the text, so it is written back too.\nconst STRICT_DECODER = new TextDecoder(\"utf-8\", { fatal: true, ignoreBOM: true });\n// A NUL byte in the first part of a file marks it as binary, as grep and git decide.\nconst BINARY_PROBE_BYTES = 8000;\n\nconst PATH_PROPERTIES = {\n path: { type: \"string\", description: \"The file, relative to the workspace root or absolute.\" },\n file_path: { type: \"string\", description: \"The same as `path`, under the name some models use.\" },\n} as const;\n\ninterface ReadInput {\n readonly path?: string;\n readonly file_path?: string;\n readonly offset?: number;\n readonly column?: number;\n readonly limit?: number;\n}\n\n/**\n * The longest start of `text` whose JSON-escaped form fits in `bytes`, without splitting a character, and never less\n * than one character. Every character takes at least one byte, so the start is at most `bytes` characters long, and a\n * binary search over that range finds it in a few measures.\n */\nfunction headOf(text: string, bytes: number): string {\n let low = 0;\n let high = Math.min(text.length, bytes);\n while (low < high) {\n const middle = (low + high + 1) >> 1;\n if (escapedBytes(text.slice(0, middle)) <= bytes) low = middle;\n else high = middle - 1;\n }\n // A start that ends on the first half of a surrogate pair would split its character.\n const code = text.charCodeAt(low - 1);\n const end = low > 0 && code >= 0xd800 && code <= 0xdbff ? low - 1 : low;\n return end === 0 ? String.fromCodePoint(text.codePointAt(0) ?? 0) : text.slice(0, end);\n}\n\n/** Where a page starts and how far it may go: 0-based line indexes, and the column of the first line to start at. */\ninterface Span {\n readonly start: number;\n readonly column: number;\n readonly last: number;\n}\n\n// A page is measured as the write cap measures a result: by its bytes inside the log's JSON string. A quote, a\n// backslash or a newline takes two bytes there and a control character six, so a page budgeted by raw bytes could pass\n// the cap, be cut and spilled again, and a spill read that way would never show its whole text.\nconst NEWLINE_BYTES = escapedBytes(\"\\n\");\n\n/**\n * The lines of `span`, at most `maxBytes` of them once JSON-escaped, with a line that says where to read on when some\n * are left. A first line longer than a page is shown in part, with the column the next part starts at.\n */\nfunction pageOf(lines: readonly string[], path: string, span: Span): ToolResult {\n const { start, column, last } = span;\n const total = lines.length;\n const from = column > 0 ? { column: column + 1 } : {};\n let shown = \"\";\n let budget = BUILTIN_TOOL_DEFAULTS.read.maxBytes;\n let line = start;\n for (; line < last; line += 1) {\n const piece = line === start ? (lines[line] ?? \"\").slice(column) : (lines[line] ?? \"\");\n const size = escapedBytes(piece) + NEWLINE_BYTES;\n if (size > budget && line > start) break;\n if (size > budget) {\n const part = headOf(piece, budget - NEWLINE_BYTES);\n const more = `[line ${line + 1} of ${total} goes on; read on with offset ${line + 1} and column ${column + part.length + 1}]`;\n return textResult(`${part}\\n${more}`, { path, from: line + 1, to: line + 1, ...from, lines: total });\n }\n shown += `${piece}\\n`;\n budget -= size;\n }\n const more = line < total ? `[lines ${start + 1} to ${line} of ${total}; read on with offset ${line + 1}]` : \"\";\n return textResult(`${shown}${more}`, { path, from: start + 1, to: line, ...from, lines: total });\n}\n\n/**\n * The part of `text` that `offset`, `column` and `limit` select, at most `maxBytes` of it once JSON-escaped. A line\n * longer than a page is shown in parts, each naming the column the next starts at, so every byte of a long result can\n * be read, even one that is a single line.\n */\nfunction page(text: string, path: string, input: ReadInput): ToolResult {\n const { defaultLimit, maxBytes } = BUILTIN_TOOL_DEFAULTS.read;\n if (text === \"\") return textResult(`(${path} is empty)`, { path, lines: 0 });\n const lines = text.split(\"\\n\");\n if (text.endsWith(\"\\n\")) lines.pop();\n const total = lines.length;\n const unpaged = input.offset === undefined && input.limit === undefined && input.column === undefined;\n if (unpaged && total <= defaultLimit && escapedBytes(text) <= maxBytes)\n return textResult(text, { path, lines: total });\n const start = (input.offset ?? 1) - 1;\n if (start >= total)\n return errorResult(`The offset ${start + 1} is past the end of ${path}, which has ${total} lines.`);\n const column = (input.column ?? 1) - 1;\n if (column > 0 && column >= (lines[start] ?? \"\").length) {\n return errorResult(`The column ${column + 1} is past the end of line ${start + 1} of ${path}, which is shorter.`);\n }\n return pageOf(lines, path, { start, column, last: Math.min(total, start + (input.limit ?? defaultLimit)) });\n}\n\nasync function readFile(deps: FileDeps, input: ReadInput): Promise<ToolResult> {\n const chosen = pathInput(input);\n if (typeof chosen !== \"string\") return errorResult(chosen.refused);\n const unusable = unusablePath(chosen);\n if (unusable !== undefined) return errorResult(unusable);\n // A spill file is the harness's own copy of an earlier result, outside the sandbox, and the cap names it by an\n // absolute path. Only such a path asks the spill reader, so a relative path always means a workspace file, never a\n // spill that happens to share its name.\n if (deps.spills !== undefined && chosen.startsWith(\"/\")) {\n const spillPath = normalizePath(chosen);\n const spilled = await deps.spills(spillPath);\n if (spilled !== undefined) return page(spilled, spillPath, input);\n }\n const checked = checkPath(deps.bounds, chosen, \"read\");\n if (\"refused\" in checked) return errorResult(checked.refused);\n let bytes: Uint8Array;\n try {\n bytes = await deps.sandbox.readFile(checked.path);\n } catch (error) {\n return failureResult(error);\n }\n if (bytes.subarray(0, BINARY_PROBE_BYTES).includes(0)) {\n return errorResult(`${checked.path} is a binary file of ${bytes.length} bytes, and read returns only text.`);\n }\n return page(DECODER.decode(bytes), checked.path, input);\n}\n\n/** The `read` tool. */\nexport function readTool(deps: FileDeps): AnyTool {\n return defineTool<ReadInput>({\n name: \"read\",\n description: BUILTIN_TOOL_DEFAULTS.read.description,\n inputSchema: {\n type: \"object\",\n properties: {\n ...PATH_PROPERTIES,\n offset: { type: \"integer\", minimum: 1, description: \"The first line to read, counting from 1.\" },\n column: {\n type: \"integer\",\n minimum: 1,\n description: \"Where to start in the first line, counting from 1, to read on in a line too long for one page.\",\n },\n limit: { type: \"integer\", minimum: 1, description: \"How many lines to read.\" },\n },\n additionalProperties: false,\n },\n firstParty: true,\n annotations: { readOnlyHint: true },\n resourceKey: () => WORKSPACE_KEY,\n execute: (input) => readFile(deps, input),\n }) as AnyTool;\n}\n\ninterface WriteInput {\n readonly path?: string;\n readonly file_path?: string;\n readonly content: string;\n}\n\n/** The `write` tool. */\nexport function writeTool(deps: FileDeps): AnyTool {\n return defineTool<WriteInput>({\n name: \"write\",\n description: BUILTIN_TOOL_DEFAULTS.write.description,\n inputSchema: {\n type: \"object\",\n properties: { ...PATH_PROPERTIES, content: { type: \"string\", description: \"The file's whole new text.\" } },\n required: [\"content\"],\n additionalProperties: false,\n },\n firstParty: true,\n effect: { kind: \"write\" },\n resourceKey: () => WORKSPACE_KEY,\n async execute(input) {\n const chosen = pathInput(input);\n if (typeof chosen !== \"string\") return errorResult(chosen.refused);\n const checked = checkPath(deps.bounds, chosen, \"write\");\n if (\"refused\" in checked) return errorResult(checked.refused);\n const bytes = ENCODER.encode(input.content);\n try {\n await deps.sandbox.writeFile(checked.path, bytes);\n } catch (error) {\n return failureResult(error);\n }\n return textResult(`Wrote ${bytes.length} bytes to ${checked.path}.`, { path: checked.path, bytes: bytes.length });\n },\n }) as AnyTool;\n}\n\ninterface EditInput {\n readonly path?: string;\n readonly file_path?: string;\n readonly old_string: string;\n readonly new_string: string;\n readonly replace_all?: boolean;\n}\n\n/** How many times `needle` occurs in `text`, counting matches that don't overlap. */\nfunction occurrences(text: string, needle: string): number {\n let count = 0;\n for (let at = text.indexOf(needle); at >= 0; at = text.indexOf(needle, at + needle.length)) count += 1;\n return count;\n}\n\n/** The edited text, or the sentence that says why the edit can't be made and nothing was changed. */\nfunction edited(text: string, input: EditInput, path: string): string | { refused: string } {\n if (input.old_string === \"\") return { refused: \"`old_string` is empty; use write to create or replace a file.\" };\n if (input.old_string === input.new_string) return { refused: \"`old_string` and `new_string` are the same.\" };\n const count = occurrences(text, input.old_string);\n if (count === 0) return { refused: `\\`old_string\\` does not occur in ${path}, so nothing was changed.` };\n if (count > 1 && input.replace_all !== true) {\n return {\n refused:\n `\\`old_string\\` occurs ${count} times in ${path}, so nothing was changed. Add surrounding lines until it ` +\n \"is unique, or set `replace_all` to replace every match.\",\n };\n }\n // A function replacement keeps `$&` and the other replacement patterns in `new_string` as written.\n return input.replace_all === true\n ? text.replaceAll(input.old_string, () => input.new_string)\n : text.replace(input.old_string, () => input.new_string);\n}\n\nasync function editFile(deps: FileDeps, input: EditInput): Promise<ToolResult> {\n const chosen = pathInput(input);\n if (typeof chosen !== \"string\") return errorResult(chosen.refused);\n const checked = checkPath(deps.bounds, chosen, \"write\");\n if (\"refused\" in checked) return errorResult(checked.refused);\n try {\n const bytes = await deps.sandbox.readFile(checked.path);\n if (bytes.subarray(0, BINARY_PROBE_BYTES).includes(0)) {\n return errorResult(`${checked.path} is a binary file, and edit changes only text, so nothing was changed.`);\n }\n let text: string;\n try {\n text = STRICT_DECODER.decode(bytes);\n } catch {\n return errorResult(\n `${checked.path} is not UTF-8 text, and edit would corrupt it, so nothing was changed. Use bash to change it.`,\n );\n }\n const next = edited(text, input, checked.path);\n if (typeof next !== \"string\") return errorResult(next.refused);\n await deps.sandbox.writeFile(checked.path, ENCODER.encode(next));\n const count = input.replace_all === true ? occurrences(text, input.old_string) : 1;\n return textResult(`Replaced ${count} match${count === 1 ? \"\" : \"es\"} in ${checked.path}.`, {\n path: checked.path,\n replaced: count,\n });\n } catch (error) {\n return failureResult(error);\n }\n}\n\n/** The `edit` tool. */\nexport function editTool(deps: FileDeps): AnyTool {\n return defineTool<EditInput>({\n name: \"edit\",\n description: BUILTIN_TOOL_DEFAULTS.edit.description,\n inputSchema: {\n type: \"object\",\n properties: {\n ...PATH_PROPERTIES,\n old_string: { type: \"string\", description: \"The exact text to replace.\" },\n new_string: { type: \"string\", description: \"The text to put in its place.\" },\n replace_all: { type: \"boolean\", description: \"Replace every match instead of requiring exactly one.\" },\n },\n required: [\"old_string\", \"new_string\"],\n additionalProperties: false,\n },\n firstParty: true,\n effect: { kind: \"write\" },\n resourceKey: () => WORKSPACE_KEY,\n execute: (input) => editFile(deps, input),\n }) as AnyTool;\n}\n"]}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import type { SandboxPolicy } from "../../sandbox/types.js";
|
|
2
|
+
/** What a file tool may touch: the workspace root and the policy's roots, each absolute and without `.` or `..`. */
|
|
3
|
+
export interface Bounds {
|
|
4
|
+
readonly root: string;
|
|
5
|
+
readonly read: readonly string[];
|
|
6
|
+
readonly write: readonly string[];
|
|
7
|
+
}
|
|
8
|
+
/** A path inside the roots, or the sentence that tells the model why it is refused. */
|
|
9
|
+
export type Checked = {
|
|
10
|
+
readonly path: string;
|
|
11
|
+
} | {
|
|
12
|
+
readonly refused: string;
|
|
13
|
+
};
|
|
14
|
+
/** The bounds of a workspace, checked once, so a relative root can't make every path resolve somewhere unexpected. */
|
|
15
|
+
export declare function boundsOf(root: string, policy: SandboxPolicy): Bounds;
|
|
16
|
+
/**
|
|
17
|
+
* Why `path` can't name a file, or `undefined` when it can. A backslash is refused because the workspace is a POSIX
|
|
18
|
+
* one, where `\` is part of a name, while the permission rules' matcher reads it as a separator: refusing it keeps the
|
|
19
|
+
* path a rule checked, the path the skill loader matches and the file the sandbox opens the same.
|
|
20
|
+
*/
|
|
21
|
+
export declare function unusablePath(path: string): string | undefined;
|
|
22
|
+
/** The absolute form of `path` against the root, or a refusal when it is outside the roots for `access`. */
|
|
23
|
+
export declare function checkPath(bounds: Bounds, path: string, access: "read" | "write"): Checked;
|
|
24
|
+
/** The tool input's path, from `path` or `file_path`; both may be given only when they agree. */
|
|
25
|
+
export declare function pathInput(input: {
|
|
26
|
+
readonly path?: string;
|
|
27
|
+
readonly file_path?: string;
|
|
28
|
+
}): string | {
|
|
29
|
+
refused: string;
|
|
30
|
+
};
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The path check every file tool makes before it calls the sandbox. It works on the path's text: it joins a relative
|
|
3
|
+
* path to the workspace root, removes `.` and `..`, and refuses a path outside the roots.
|
|
4
|
+
*
|
|
5
|
+
* It can't see a symlink, because the sandbox interface has no call that resolves one, so the sandbox's own check of
|
|
6
|
+
* the real path stays the second line, and its denial becomes the tool's error result. The tool hands the sandbox the
|
|
7
|
+
* path it checked, never the model's text, so the two checks see the same path.
|
|
8
|
+
*/
|
|
9
|
+
import { HarnessError } from "../../errors.js";
|
|
10
|
+
import { normalizePath } from "../../permissions/match.js";
|
|
11
|
+
const within = (path, root) => root === "/" || path === root || path.startsWith(`${root}/`);
|
|
12
|
+
function absolute(path, what) {
|
|
13
|
+
if (typeof path !== "string" || !path.startsWith("/")) {
|
|
14
|
+
throw new HarnessError("invalid_tool_options", `${what} must be an absolute path, not ${JSON.stringify(path)}`);
|
|
15
|
+
}
|
|
16
|
+
return normalizePath(path);
|
|
17
|
+
}
|
|
18
|
+
/** The bounds of a workspace, checked once, so a relative root can't make every path resolve somewhere unexpected. */
|
|
19
|
+
export function boundsOf(root, policy) {
|
|
20
|
+
if (!Array.isArray(policy?.readRoots) || !Array.isArray(policy.writeRoots)) {
|
|
21
|
+
throw new HarnessError("invalid_tool_options", "the built-in tools need the sandbox policy's readRoots and writeRoots");
|
|
22
|
+
}
|
|
23
|
+
const write = policy.writeRoots.map((path) => absolute(path, "a write root"));
|
|
24
|
+
// The write roots are readable too, as the sandbox policy says.
|
|
25
|
+
const read = [...policy.readRoots.map((path) => absolute(path, "a read root")), ...write];
|
|
26
|
+
return { root: absolute(root, "the workspace root"), read, write };
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Why `path` can't name a file, or `undefined` when it can. A backslash is refused because the workspace is a POSIX
|
|
30
|
+
* one, where `\` is part of a name, while the permission rules' matcher reads it as a separator: refusing it keeps the
|
|
31
|
+
* path a rule checked, the path the skill loader matches and the file the sandbox opens the same.
|
|
32
|
+
*/
|
|
33
|
+
export function unusablePath(path) {
|
|
34
|
+
if (path === "" || path.includes("\u0000"))
|
|
35
|
+
return `The path ${JSON.stringify(path)} is not a usable path.`;
|
|
36
|
+
if (path.includes("\\")) {
|
|
37
|
+
return `The path ${path} holds a backslash; separate folders with \`/\`, because \`\\\` is not a separator here.`;
|
|
38
|
+
}
|
|
39
|
+
return undefined;
|
|
40
|
+
}
|
|
41
|
+
/** The absolute form of `path` against the root, or a refusal when it is outside the roots for `access`. */
|
|
42
|
+
export function checkPath(bounds, path, access) {
|
|
43
|
+
const unusable = unusablePath(path);
|
|
44
|
+
if (unusable !== undefined)
|
|
45
|
+
return { refused: unusable };
|
|
46
|
+
const resolved = normalizePath(path.startsWith("/") ? path : `${bounds.root}/${path}`);
|
|
47
|
+
const roots = access === "write" ? bounds.write : bounds.read;
|
|
48
|
+
if (roots.some((root) => within(resolved, root)))
|
|
49
|
+
return { path: resolved };
|
|
50
|
+
const where = roots.length === 0 ? "no folder" : roots.join(", ");
|
|
51
|
+
return { refused: `The path ${path} is outside the folders this tool may ${access}: ${where}.` };
|
|
52
|
+
}
|
|
53
|
+
/** The tool input's path, from `path` or `file_path`; both may be given only when they agree. */
|
|
54
|
+
export function pathInput(input) {
|
|
55
|
+
const { path, file_path: filePath } = input;
|
|
56
|
+
if (path !== undefined && filePath !== undefined && path !== filePath) {
|
|
57
|
+
return { refused: "Pass the file as `path` or as `file_path`, not two different paths." };
|
|
58
|
+
}
|
|
59
|
+
const chosen = filePath ?? path;
|
|
60
|
+
return chosen === undefined ? { refused: "Pass the file to use as `path`." } : chosen;
|
|
61
|
+
}
|
|
62
|
+
//# sourceMappingURL=paths.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/tools/builtins/paths.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The path check every file tool makes before it calls the sandbox. It works on the path's text: it joins a relative\n * path to the workspace root, removes `.` and `..`, and refuses a path outside the roots.\n *\n * It can't see a symlink, because the sandbox interface has no call that resolves one, so the sandbox's own check of\n * the real path stays the second line, and its denial becomes the tool's error result. The tool hands the sandbox the\n * path it checked, never the model's text, so the two checks see the same path.\n */\nimport { HarnessError } from \"../../errors.js\";\nimport { normalizePath } from \"../../permissions/match.js\";\nimport type { SandboxPolicy } from \"../../sandbox/types.js\";\n\n/** What a file tool may touch: the workspace root and the policy's roots, each absolute and without `.` or `..`. */\nexport interface Bounds {\n readonly root: string;\n readonly read: readonly string[];\n readonly write: readonly string[];\n}\n\n/** A path inside the roots, or the sentence that tells the model why it is refused. */\nexport type Checked = { readonly path: string } | { readonly refused: string };\n\nconst within = (path: string, root: string): boolean => root === \"/\" || path === root || path.startsWith(`${root}/`);\n\nfunction absolute(path: unknown, what: string): string {\n if (typeof path !== \"string\" || !path.startsWith(\"/\")) {\n throw new HarnessError(\"invalid_tool_options\", `${what} must be an absolute path, not ${JSON.stringify(path)}`);\n }\n return normalizePath(path);\n}\n\n/** The bounds of a workspace, checked once, so a relative root can't make every path resolve somewhere unexpected. */\nexport function boundsOf(root: string, policy: SandboxPolicy): Bounds {\n if (!Array.isArray(policy?.readRoots) || !Array.isArray(policy.writeRoots)) {\n throw new HarnessError(\n \"invalid_tool_options\",\n \"the built-in tools need the sandbox policy's readRoots and writeRoots\",\n );\n }\n const write = policy.writeRoots.map((path) => absolute(path, \"a write root\"));\n // The write roots are readable too, as the sandbox policy says.\n const read = [...policy.readRoots.map((path) => absolute(path, \"a read root\")), ...write];\n return { root: absolute(root, \"the workspace root\"), read, write };\n}\n\n/**\n * Why `path` can't name a file, or `undefined` when it can. A backslash is refused because the workspace is a POSIX\n * one, where `\\` is part of a name, while the permission rules' matcher reads it as a separator: refusing it keeps the\n * path a rule checked, the path the skill loader matches and the file the sandbox opens the same.\n */\nexport function unusablePath(path: string): string | undefined {\n if (path === \"\" || path.includes(\"\\u0000\")) return `The path ${JSON.stringify(path)} is not a usable path.`;\n if (path.includes(\"\\\\\")) {\n return `The path ${path} holds a backslash; separate folders with \\`/\\`, because \\`\\\\\\` is not a separator here.`;\n }\n return undefined;\n}\n\n/** The absolute form of `path` against the root, or a refusal when it is outside the roots for `access`. */\nexport function checkPath(bounds: Bounds, path: string, access: \"read\" | \"write\"): Checked {\n const unusable = unusablePath(path);\n if (unusable !== undefined) return { refused: unusable };\n const resolved = normalizePath(path.startsWith(\"/\") ? path : `${bounds.root}/${path}`);\n const roots = access === \"write\" ? bounds.write : bounds.read;\n if (roots.some((root) => within(resolved, root))) return { path: resolved };\n const where = roots.length === 0 ? \"no folder\" : roots.join(\", \");\n return { refused: `The path ${path} is outside the folders this tool may ${access}: ${where}.` };\n}\n\n/** The tool input's path, from `path` or `file_path`; both may be given only when they agree. */\nexport function pathInput(input: {\n readonly path?: string;\n readonly file_path?: string;\n}): string | { refused: string } {\n const { path, file_path: filePath } = input;\n if (path !== undefined && filePath !== undefined && path !== filePath) {\n return { refused: \"Pass the file as `path` or as `file_path`, not two different paths.\" };\n }\n const chosen = filePath ?? path;\n return chosen === undefined ? { refused: \"Pass the file to use as `path`.\" } : chosen;\n}\n"]}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The results the built-in tools return. A refusal or a failed file call is a result the model reads and can act on,
|
|
3
|
+
* not a thrown error, so the model sees one plain sentence instead of the SDK's generic failure text. A thrown error
|
|
4
|
+
* that is not one of those, such as a disposed sandbox, is a fault of the host and propagates.
|
|
5
|
+
*/
|
|
6
|
+
import type { ToolResult } from "@buildanagent/sdk";
|
|
7
|
+
import type { SandboxDenial } from "../../sandbox/types.js";
|
|
8
|
+
/** A result of one text block. */
|
|
9
|
+
export declare function textResult(text: string, details?: unknown): ToolResult;
|
|
10
|
+
/** An error result of one text block. */
|
|
11
|
+
export declare function errorResult(text: string): ToolResult;
|
|
12
|
+
/** The error result for a command the sandbox's policy stopped. */
|
|
13
|
+
export declare function deniedResult(denial: SandboxDenial): ToolResult;
|
|
14
|
+
/** The error result for a failure the model caused, or the error itself, rethrown, for any other. */
|
|
15
|
+
export declare function failureResult(error: unknown): ToolResult;
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { isHarnessError } from "../../errors.js";
|
|
2
|
+
/** A result of one text block. */
|
|
3
|
+
export function textResult(text, details) {
|
|
4
|
+
return { content: [{ type: "text", text }], ...(details === undefined ? {} : { details }) };
|
|
5
|
+
}
|
|
6
|
+
/** An error result of one text block. */
|
|
7
|
+
export function errorResult(text) {
|
|
8
|
+
return { content: [{ type: "text", text }], isError: true };
|
|
9
|
+
}
|
|
10
|
+
/** The error result for a command the sandbox's policy stopped. */
|
|
11
|
+
export function deniedResult(denial) {
|
|
12
|
+
return errorResult(`The sandbox denied a ${denial.kind.replace("_", " ")} of ${denial.target}: ${denial.reason}.`);
|
|
13
|
+
}
|
|
14
|
+
// The failures that come from what the model asked for: a path the policy refuses, a missing file, a file the call
|
|
15
|
+
// could not read, and a host the egress proxy refuses.
|
|
16
|
+
const MODEL_FAILURES = new Set([
|
|
17
|
+
"sandbox_denied",
|
|
18
|
+
"sandbox_not_found",
|
|
19
|
+
"sandbox_io_failed",
|
|
20
|
+
"egress_denied",
|
|
21
|
+
]);
|
|
22
|
+
/** The error result for a failure the model caused, or the error itself, rethrown, for any other. */
|
|
23
|
+
export function failureResult(error) {
|
|
24
|
+
if (isHarnessError(error) && MODEL_FAILURES.has(error.code)) {
|
|
25
|
+
const sentence = `${error.message.charAt(0).toUpperCase()}${error.message.slice(1)}`;
|
|
26
|
+
// A message that already ends a sentence keeps its own stop, so the model never reads "x..".
|
|
27
|
+
return errorResult(/[.!?]$/.test(sentence) ? sentence : `${sentence}.`);
|
|
28
|
+
}
|
|
29
|
+
throw error;
|
|
30
|
+
}
|
|
31
|
+
//# sourceMappingURL=results.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"results.js","sourceRoot":"","sources":["../../../src/tools/builtins/results.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGjD,kCAAkC;AAClC,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,OAAiB;IACxD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;AAC9F,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC9D,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,OAAO,WAAW,CAAC,wBAAwB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,OAAO,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;AACrH,CAAC;AAED,mHAAmH;AACnH,uDAAuD;AACvD,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC;IAClD,gBAAgB;IAChB,mBAAmB;IACnB,mBAAmB;IACnB,eAAe;CAChB,CAAC,CAAC;AAEH,qGAAqG;AACrG,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,cAAc,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5D,MAAM,QAAQ,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACrF,6FAA6F;QAC7F,OAAO,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,GAAG,CAAC,CAAC;IAC1E,CAAC;IACD,MAAM,KAAK,CAAC;AACd,CAAC","sourcesContent":["/**\n * The results the built-in tools return. A refusal or a failed file call is a result the model reads and can act on,\n * not a thrown error, so the model sees one plain sentence instead of the SDK's generic failure text. A thrown error\n * that is not one of those, such as a disposed sandbox, is a fault of the host and propagates.\n */\nimport type { ToolResult } from \"@buildanagent/sdk\";\nimport { isHarnessError } from \"../../errors.js\";\nimport type { SandboxDenial } from \"../../sandbox/types.js\";\n\n/** A result of one text block. */\nexport function textResult(text: string, details?: unknown): ToolResult {\n return { content: [{ type: \"text\", text }], ...(details === undefined ? {} : { details }) };\n}\n\n/** An error result of one text block. */\nexport function errorResult(text: string): ToolResult {\n return { content: [{ type: \"text\", text }], isError: true };\n}\n\n/** The error result for a command the sandbox's policy stopped. */\nexport function deniedResult(denial: SandboxDenial): ToolResult {\n return errorResult(`The sandbox denied a ${denial.kind.replace(\"_\", \" \")} of ${denial.target}: ${denial.reason}.`);\n}\n\n// The failures that come from what the model asked for: a path the policy refuses, a missing file, a file the call\n// could not read, and a host the egress proxy refuses.\nconst MODEL_FAILURES: ReadonlySet<string> = new Set([\n \"sandbox_denied\",\n \"sandbox_not_found\",\n \"sandbox_io_failed\",\n \"egress_denied\",\n]);\n\n/** The error result for a failure the model caused, or the error itself, rethrown, for any other. */\nexport function failureResult(error: unknown): ToolResult {\n if (isHarnessError(error) && MODEL_FAILURES.has(error.code)) {\n const sentence = `${error.message.charAt(0).toUpperCase()}${error.message.slice(1)}`;\n // A message that already ends a sentence keeps its own stop, so the model never reads \"x..\".\n return errorResult(/[.!?]$/.test(sentence) ? sentence : `${sentence}.`);\n }\n throw error;\n}\n"]}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `grep` and `glob`: read-only search, run inside the sandbox with `find` and `grep`, so a pattern the model wrote is
|
|
3
|
+
* matched by a sandboxed process with a timeout and never by a regular expression in the host's own loop. Both list
|
|
4
|
+
* files with `find`, which never follows a symlink, and filter the list here with the permission rules' own glob
|
|
5
|
+
* matcher, so `glob` and `grep`'s file filter read a pattern the same way on every backend.
|
|
6
|
+
*/
|
|
7
|
+
import { type ToolDefinition } from "@buildanagent/sdk";
|
|
8
|
+
import { type FileDeps } from "./files.js";
|
|
9
|
+
type AnyTool = ToolDefinition<unknown, unknown, unknown>;
|
|
10
|
+
/** What the search tools share with the file tools, plus the environment their commands run with. */
|
|
11
|
+
export interface SearchDeps extends FileDeps {
|
|
12
|
+
readonly env: Readonly<Record<string, string>>;
|
|
13
|
+
}
|
|
14
|
+
/** The `glob` tool. */
|
|
15
|
+
export declare function globTool(deps: SearchDeps): AnyTool;
|
|
16
|
+
/** The `grep` tool. */
|
|
17
|
+
export declare function grepTool(deps: SearchDeps): AnyTool;
|
|
18
|
+
export {};
|