@sixb/agent 0.2.3 → 0.2.4

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 (80) hide show
  1. package/README.md +2 -2
  2. package/dist/artifacts/publish-tool.d.ts +26 -44
  3. package/dist/artifacts/publish-tool.d.ts.map +1 -1
  4. package/dist/ask-tool.d.ts +62 -0
  5. package/dist/ask-tool.d.ts.map +1 -0
  6. package/dist/attachments.d.ts +1 -1
  7. package/dist/attachments.d.ts.map +1 -1
  8. package/dist/background-commands.d.ts +3 -3
  9. package/dist/background-commands.d.ts.map +1 -1
  10. package/dist/background-notices.d.ts.map +1 -1
  11. package/dist/child-files.d.ts +1 -1
  12. package/dist/child-questions.d.ts +1 -1
  13. package/dist/index.d.ts +1 -1
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js +1380 -596
  16. package/dist/index.js.map +30 -26
  17. package/dist/run-agent-turn.d.ts.map +1 -1
  18. package/dist/run-conversation-turn.d.ts.map +1 -1
  19. package/dist/run-environment.d.ts +4 -1
  20. package/dist/run-environment.d.ts.map +1 -1
  21. package/dist/run-subagent.d.ts +1 -1
  22. package/dist/subagent-tools.d.ts +20 -1
  23. package/dist/subagent-tools.d.ts.map +1 -1
  24. package/dist/tools/background.d.ts +50 -18
  25. package/dist/tools/background.d.ts.map +1 -1
  26. package/dist/tools/bash.d.ts +1 -0
  27. package/dist/tools/bash.d.ts.map +1 -1
  28. package/dist/tools/edit-text.d.ts +22 -0
  29. package/dist/tools/edit-text.d.ts.map +1 -0
  30. package/dist/tools/edit.d.ts +54 -0
  31. package/dist/tools/edit.d.ts.map +1 -0
  32. package/dist/tools/file-writes.d.ts +52 -0
  33. package/dist/tools/file-writes.d.ts.map +1 -0
  34. package/dist/tools/model-spec.d.ts.map +1 -1
  35. package/dist/tools/read.d.ts +16 -3
  36. package/dist/tools/read.d.ts.map +1 -1
  37. package/dist/tools/view-file.d.ts +20 -23
  38. package/dist/tools/view-file.d.ts.map +1 -1
  39. package/dist/tools/web-fetch/tool.d.ts +1 -0
  40. package/dist/tools/web-fetch/tool.d.ts.map +1 -1
  41. package/dist/tools/web-search.d.ts +1 -0
  42. package/dist/tools/web-search.d.ts.map +1 -1
  43. package/dist/tools/write.d.ts +36 -0
  44. package/dist/tools/write.d.ts.map +1 -0
  45. package/package.json +4 -4
  46. package/src/agent-prompt.ts +9 -9
  47. package/src/artifacts/publish-tool.ts +76 -94
  48. package/src/ask-tool.ts +223 -0
  49. package/src/attachments.ts +7 -6
  50. package/src/background-commands.ts +5 -5
  51. package/src/background-notices.ts +5 -12
  52. package/src/child-files.ts +1 -1
  53. package/src/child-questions.ts +1 -1
  54. package/src/context-compaction.ts +4 -1
  55. package/src/index.ts +1 -1
  56. package/src/run-agent-turn.ts +14 -4
  57. package/src/run-child.ts +1 -1
  58. package/src/run-conversation-turn.ts +4 -1
  59. package/src/run-environment.ts +36 -21
  60. package/src/run-subagent.ts +3 -3
  61. package/src/skills/sixb-artifacts/SKILL.md +7 -7
  62. package/src/skills/sixb-artifacts/canvas.md +2 -2
  63. package/src/skills/sixb-artifacts/page.md +2 -2
  64. package/src/skills/sixb-artifacts/slides.md +2 -2
  65. package/src/subagent-tools.ts +115 -81
  66. package/src/tools/background.ts +227 -67
  67. package/src/tools/bash.ts +2 -1
  68. package/src/tools/edit-text.ts +241 -0
  69. package/src/tools/edit.ts +166 -0
  70. package/src/tools/file-writes.ts +270 -0
  71. package/src/tools/model-spec.ts +9 -13
  72. package/src/tools/read.ts +75 -9
  73. package/src/tools/tool-outputs.ts +2 -2
  74. package/src/tools/view-file.ts +78 -80
  75. package/src/tools/web-fetch/tool.ts +2 -1
  76. package/src/tools/web-search.ts +1 -0
  77. package/src/tools/write.ts +95 -0
  78. package/dist/ask-parent-tool.d.ts +0 -36
  79. package/dist/ask-parent-tool.d.ts.map +0 -1
  80. package/src/ask-parent-tool.ts +0 -100
@@ -0,0 +1,166 @@
1
+ import { posix } from "node:path"
2
+ import type { JsonObject, JsonValue, ModelTool } from "@sixb/core/models"
3
+ import { agentToolErrorText } from "../model-adapters"
4
+ import type { AgentSandboxHandle } from "../sandbox-handle"
5
+ import { editText } from "./edit-text"
6
+ import {
7
+ commitSandboxFile,
8
+ type FileReadLedger,
9
+ type LoadedSandboxFile,
10
+ loadSandboxFile,
11
+ publicError,
12
+ } from "./file-writes"
13
+
14
+ export const EDIT_TOOL_SPEC = {
15
+ name: "edit",
16
+ strict: true,
17
+ description:
18
+ "Replace text in a file. old_string must match the file exactly, once, unless replace_all is true. Read the file first: an edit refuses a file that changed since you read it. Returns the change as a diff, so there is no need to read the file again to check it.",
19
+ inputSchema: {
20
+ type: "object",
21
+ properties: {
22
+ path: {
23
+ type: "string",
24
+ description:
25
+ "Path relative to the working directory, or an absolute path in the run's context directory.",
26
+ },
27
+ old_string: { type: "string", description: "The exact text to replace." },
28
+ new_string: { type: "string", description: "The text to put in its place." },
29
+ replace_all: {
30
+ type: "boolean",
31
+ description: "Replace every match of old_string. Default: false.",
32
+ },
33
+ },
34
+ required: ["path", "old_string", "new_string"],
35
+ additionalProperties: false,
36
+ } satisfies JsonObject,
37
+ } as const
38
+
39
+ export interface EditToolInput {
40
+ readonly path: string
41
+ readonly old_string: string
42
+ readonly new_string: string
43
+ readonly replace_all?: boolean
44
+ }
45
+
46
+ export interface EditToolOutput {
47
+ readonly path: string
48
+ readonly replaced: number
49
+ /** Unified diff of the change, with line numbers; cut past a few thousand characters. */
50
+ readonly diff: string
51
+ /** Lines the change adds and removes, all of them, however short the diff was cut. */
52
+ readonly added: number
53
+ readonly removed: number
54
+ }
55
+
56
+ export function createEditTool(
57
+ resolveSandbox: () => Promise<AgentSandboxHandle>,
58
+ ledger: FileReadLedger
59
+ ): ModelTool<EditToolInput> {
60
+ return {
61
+ ...EDIT_TOOL_SPEC,
62
+ parseInput: parseEditInput,
63
+ async execute(input, { signal }): Promise<JsonValue> {
64
+ const handle = await resolveSandbox()
65
+ const loaded = await loadSandboxFile(handle, { path: input.path, tool: "edit", signal })
66
+ if (loaded.kind === "missing") {
67
+ throw publicError("edit", `'${input.path}' does not exist. Create it with write.`)
68
+ }
69
+ assertReadAsIs(ledger, loaded, input.path, "edit")
70
+
71
+ let text: string
72
+ try {
73
+ text = new TextDecoder("utf-8", { fatal: true }).decode(loaded.bytes)
74
+ } catch {
75
+ throw publicError("edit", `'${input.path}' is not UTF-8 text.`)
76
+ }
77
+ const edited = editText(text, {
78
+ old: input.old_string,
79
+ new: input.new_string,
80
+ all: input.replace_all === true,
81
+ })
82
+ if (!edited.ok) throw publicError("edit", edited.reason)
83
+
84
+ const written = await commitSandboxFile(handle, {
85
+ path: loaded.realPath,
86
+ expected: loaded.fingerprint,
87
+ bytes: new TextEncoder().encode(edited.text),
88
+ tool: "edit",
89
+ signal,
90
+ })
91
+ ledger.record(written.realPath, written.fingerprint)
92
+ return {
93
+ path: input.path,
94
+ replaced: edited.replaced,
95
+ diff: edited.diff,
96
+ added: edited.added,
97
+ removed: edited.removed,
98
+ } satisfies EditToolOutput
99
+ },
100
+ errorText: agentToolErrorText,
101
+ }
102
+ }
103
+
104
+ /** An existing file is changed only as the run last read or wrote it. */
105
+ export function assertReadAsIs(
106
+ ledger: FileReadLedger,
107
+ loaded: Extract<LoadedSandboxFile, { kind: "file" }>,
108
+ path: string,
109
+ tool: string
110
+ ): void {
111
+ const seen = ledger.get(loaded.realPath)
112
+ if (seen === undefined) {
113
+ throw publicError(tool, `read '${path}' with the read tool before changing it.`)
114
+ }
115
+ if (seen !== loaded.fingerprint) {
116
+ throw publicError(
117
+ tool,
118
+ `'${path}' changed since you read it. Read it again, then make your change.`
119
+ )
120
+ }
121
+ }
122
+
123
+ function parseEditInput(value: unknown): EditToolInput {
124
+ const input = objectInput(value, "edit", ["path", "old_string", "new_string", "replace_all"])
125
+ const path = pathInput(input.path, "edit")
126
+ if (typeof input.old_string !== "string" || input.old_string === "") {
127
+ throw publicError("edit", "old_string must be the non-empty text to replace.")
128
+ }
129
+ if (typeof input.new_string !== "string") {
130
+ throw publicError("edit", "new_string must be a string.")
131
+ }
132
+ if (input.old_string === input.new_string) {
133
+ throw publicError("edit", "new_string is the same as old_string: there is nothing to change.")
134
+ }
135
+ if (input.replace_all !== undefined && typeof input.replace_all !== "boolean") {
136
+ throw publicError("edit", "replace_all must be true or false.")
137
+ }
138
+ return {
139
+ path,
140
+ old_string: input.old_string,
141
+ new_string: input.new_string,
142
+ ...(input.replace_all === undefined ? {} : { replace_all: input.replace_all }),
143
+ }
144
+ }
145
+
146
+ export function objectInput(
147
+ value: unknown,
148
+ tool: string,
149
+ keys: readonly string[]
150
+ ): Record<string, unknown> {
151
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
152
+ throw publicError(tool, "input must be an object.")
153
+ }
154
+ const input = value as Record<string, unknown>
155
+ for (const key of Object.keys(input)) {
156
+ if (!keys.includes(key)) throw publicError(tool, `input has an unknown property '${key}'.`)
157
+ }
158
+ return input
159
+ }
160
+
161
+ export function pathInput(value: unknown, tool: string): string {
162
+ if (typeof value !== "string" || !value.trim() || value.includes("\0")) {
163
+ throw publicError(tool, "path must be a non-empty path.")
164
+ }
165
+ return posix.normalize(value)
166
+ }
@@ -0,0 +1,270 @@
1
+ import { AgentToolPublicError, type CommandResult } from "@sixb/core"
2
+ import { AgentToolExecutionError } from "../errors"
3
+ import { type AgentSandboxHandle, contextPath } from "../sandbox-handle"
4
+
5
+ /** The largest file `edit` changes and `write` writes: a whole file passes through the harness. */
6
+ export const MAX_EDITED_FILE_BYTES = 1024 * 1024
7
+
8
+ const COMMAND_TIMEOUT_MS = 30_000
9
+ /**
10
+ * Contents travel as base64 in an environment variable, a few calls for a large file: Linux caps
11
+ * one variable at 128 KiB, and a sandbox has no stdin or file API that reaches every root.
12
+ */
13
+ const CHUNK_CHARACTERS = 96 * 1024
14
+
15
+ /**
16
+ * What a run has read, by real path: the file's fingerprint (`cksum`: CRC and size) when it read
17
+ * it. `edit` and `write` change an existing file only when it is the file the run read, so a change
18
+ * made since, by the user, another process or the run's own `bash`, is never overwritten blind.
19
+ */
20
+ export class FileReadLedger {
21
+ readonly #fingerprints = new Map<string, string>()
22
+
23
+ record(realPath: string, fingerprint: string): void {
24
+ this.#fingerprints.set(realPath, fingerprint)
25
+ }
26
+
27
+ get(realPath: string): string | undefined {
28
+ return this.#fingerprints.get(realPath)
29
+ }
30
+ }
31
+
32
+ export type LoadedSandboxFile =
33
+ | { readonly kind: "missing" }
34
+ | {
35
+ readonly kind: "file"
36
+ readonly realPath: string
37
+ readonly fingerprint: string
38
+ readonly bytes: Uint8Array
39
+ }
40
+
41
+ /** Read a whole file for `edit` or `write`: where it really is, its fingerprint and its bytes. */
42
+ export async function loadSandboxFile(
43
+ handle: AgentSandboxHandle,
44
+ input: { readonly path: string; readonly tool: string; readonly signal: AbortSignal }
45
+ ): Promise<LoadedSandboxFile> {
46
+ const result = await run(handle, input.tool, input.signal, LOAD_SCRIPT, [
47
+ input.path,
48
+ contextPath(handle),
49
+ String(MAX_EDITED_FILE_BYTES),
50
+ ])
51
+ if (result.exitCode === 10) return { kind: "missing" }
52
+ if (result.exitCode !== 0) throw pathError(input.tool, input.path, result)
53
+
54
+ const [fingerprint = "", realPath = "", ...contents] = result.stdout.split("\n")
55
+ const bytes = Buffer.from(contents.join(""), "base64")
56
+ if (!isFingerprint(fingerprint) || bytes.byteLength !== Number(fingerprint.split(":")[1])) {
57
+ throw publicError(input.tool, `'${input.path}' changed while it was being read; try again.`)
58
+ }
59
+ return {
60
+ kind: "file",
61
+ realPath: realPath || input.path,
62
+ fingerprint,
63
+ bytes: new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength),
64
+ }
65
+ }
66
+
67
+ /**
68
+ * Write `bytes` to `path` when the file there is still `expected` (a fingerprint, or `missing`
69
+ * for a file to create), keeping an existing file's mode. Missing parent directories are created
70
+ * inside the run's roots. Returns where the file is and its new fingerprint.
71
+ */
72
+ export async function commitSandboxFile(
73
+ handle: AgentSandboxHandle,
74
+ input: {
75
+ readonly path: string
76
+ readonly expected: string
77
+ readonly bytes: Uint8Array
78
+ readonly tool: string
79
+ readonly signal: AbortSignal
80
+ }
81
+ ): Promise<{ readonly realPath: string; readonly fingerprint: string }> {
82
+ const encoded = Buffer.from(input.bytes).toString("base64")
83
+ let stage = ""
84
+ let offset = 0
85
+ for (; offset + CHUNK_CHARACTERS < encoded.length; offset += CHUNK_CHARACTERS) {
86
+ const result = await run(
87
+ handle,
88
+ input.tool,
89
+ input.signal,
90
+ STAGE_SCRIPT,
91
+ [stage],
92
+ encoded.slice(offset, offset + CHUNK_CHARACTERS)
93
+ )
94
+ if (result.exitCode !== 0 || !result.stdout.trim()) {
95
+ throw new AgentToolExecutionError(input.tool, {
96
+ cause: new Error(result.stderr.trim() || `Staging exited with code ${result.exitCode}.`),
97
+ })
98
+ }
99
+ stage = result.stdout.trim()
100
+ }
101
+
102
+ const result = await run(
103
+ handle,
104
+ input.tool,
105
+ input.signal,
106
+ COMMIT_SCRIPT,
107
+ [input.path, contextPath(handle), input.expected, stage],
108
+ encoded.slice(offset)
109
+ )
110
+ if (result.exitCode === 15) {
111
+ throw publicError(
112
+ input.tool,
113
+ result.stdout.trim() === "missing"
114
+ ? `'${input.path}' was deleted after you read it.`
115
+ : `'${input.path}' changed after you read it. Read it again, then make your change.`
116
+ )
117
+ }
118
+ if (result.exitCode !== 0) throw pathError(input.tool, input.path, result)
119
+
120
+ const [fingerprint = "", realPath = ""] = result.stdout.split("\n")
121
+ if (!isFingerprint(fingerprint)) {
122
+ throw new AgentToolExecutionError(input.tool, {
123
+ cause: new Error(`Unexpected output: ${result.stdout.slice(0, 200)}`),
124
+ })
125
+ }
126
+ return { realPath: realPath || input.path, fingerprint }
127
+ }
128
+
129
+ export function publicError(tool: string, message: string): AgentToolPublicError {
130
+ return new AgentToolPublicError(`[SixbAgent] ${tool}: ${message}`)
131
+ }
132
+
133
+ async function run(
134
+ handle: AgentSandboxHandle,
135
+ tool: string,
136
+ signal: AbortSignal,
137
+ script: string,
138
+ args: readonly string[],
139
+ chunk?: string
140
+ ): Promise<CommandResult> {
141
+ let result: CommandResult
142
+ try {
143
+ result = await handle.sandbox.runCommand("bash", ["-c", script, `sixb-${tool}`, ...args], {
144
+ cwd: handle.sandbox.workingDirectory,
145
+ env: { ...(handle.env ?? {}), ...(chunk === undefined ? {} : { SIXB_CHUNK: chunk }) },
146
+ timeout: COMMAND_TIMEOUT_MS,
147
+ signal,
148
+ })
149
+ } catch (error) {
150
+ signal.throwIfAborted()
151
+ throw new AgentToolExecutionError(tool, { cause: error })
152
+ }
153
+ signal.throwIfAborted()
154
+ return result
155
+ }
156
+
157
+ function pathError(tool: string, path: string, result: CommandResult): Error {
158
+ switch (result.exitCode) {
159
+ case 10:
160
+ return publicError(tool, `'${path}' does not exist.`)
161
+ case 11:
162
+ return publicError(
163
+ tool,
164
+ `'${path}' resolves outside the working directory and the run's context directory.`
165
+ )
166
+ case 12:
167
+ return publicError(tool, `'${path}' is a directory, not a file.`)
168
+ case 13:
169
+ return publicError(tool, `'${path}' is not a regular file.`)
170
+ case 14:
171
+ return publicError(
172
+ tool,
173
+ `'${path}' is larger than ${MAX_EDITED_FILE_BYTES / 1024 / 1024} MiB: change it with bash.`
174
+ )
175
+ default:
176
+ return new AgentToolExecutionError(tool, {
177
+ cause: new Error(
178
+ result.stderr.trim() || `Sandbox command exited with code ${result.exitCode}.`
179
+ ),
180
+ })
181
+ }
182
+ }
183
+
184
+ export function isFingerprint(value: string): boolean {
185
+ return /^\d+:\d+$/.test(value)
186
+ }
187
+
188
+ /**
189
+ * Bash functions shared with `read`: a file's fingerprint as `crc:size` from `cksum`, and a real
190
+ * path on one line (empty when the path holds a newline, which then goes unrecorded). Neither
191
+ * needs `tr` or `awk`, which some sandbox images lack.
192
+ */
193
+ export const FINGERPRINT_FUNCTIONS = `fingerprint() {
194
+ local sum rest
195
+ sum="$(cksum < "$1")" || return 1
196
+ rest="\${sum#* }"
197
+ printf '%s:%s\\n' "\${sum%% *}" "\${rest%% *}"
198
+ }
199
+ print_path() {
200
+ case "$1" in *$'\\n'*) printf '\\n' ;; *) printf '%s\\n' "$1" ;; esac
201
+ }`
202
+
203
+ // The run's roots, and the requested path made absolute.
204
+ const ROOTS = `root="$(pwd -P)"
205
+ context="$root"
206
+ if [ -d "$2" ]; then context="$(cd -P -- "$2" && pwd)"; fi
207
+ inside() { case "$1" in "$root"/*|"$context"/*) return 0 ;; esac; return 1; }
208
+ case "$1" in /*) requested="$1" ;; *) requested="$root/$1" ;; esac
209
+ ${FINGERPRINT_FUNCTIONS}`
210
+
211
+ // Prints the fingerprint, the real path, then the contents as base64 over as many lines as it takes.
212
+ const LOAD_SCRIPT = `set -u
213
+ ${ROOTS}
214
+ [ -e "$requested" ] || exit 10
215
+ target="$(realpath "$requested")" || exit 10
216
+ inside "$target" || exit 11
217
+ [ ! -d "$target" ] || exit 12
218
+ [ -f "$target" ] || exit 13
219
+ sum="$(fingerprint "$target")" || exit 19
220
+ [ "\${sum#*:}" -le "$3" ] || exit 14
221
+ printf '%s\\n' "$sum"
222
+ print_path "$target"
223
+ base64 < "$target"`
224
+
225
+ // Appends one chunk of base64 to a staging file, made on the first call; prints its path.
226
+ const STAGE_SCRIPT = `set -eu
227
+ stage="\${1:-}"
228
+ if [ -z "$stage" ]; then stage="$(mktemp "\${TMPDIR:-/tmp}/sixb-write.XXXXXX")"; fi
229
+ printf '%s' "$SIXB_CHUNK" >> "$stage"
230
+ printf '%s' "$stage"`
231
+
232
+ // Writes when the file is still what the run expects; exit 15 prints what it is instead. Decodes
233
+ // in full before touching the file, and writes through it (cat >) so its mode and links stay.
234
+ const COMMIT_SCRIPT = `set -u
235
+ ${ROOTS}
236
+ if [ -L "$requested" ] && [ ! -e "$requested" ]; then exit 11; fi
237
+ if [ -e "$requested" ]; then
238
+ target="$(realpath "$requested")" || exit 19
239
+ inside "$target" || exit 11
240
+ [ ! -d "$target" ] || exit 12
241
+ [ -f "$target" ] || exit 13
242
+ current="$(fingerprint "$target")" || exit 19
243
+ else
244
+ dir="$(dirname -- "$requested")"
245
+ while [ ! -d "$dir" ]; do dir="$(dirname -- "$dir")"; done
246
+ inside "$(cd -P -- "$dir" && pwd)/" || exit 11
247
+ mkdir -p -- "$(dirname -- "$requested")" || exit 19
248
+ parent="$(cd -P -- "$(dirname -- "$requested")" && pwd)"
249
+ inside "$parent/" || exit 11
250
+ target="$parent/$(basename -- "$requested")"
251
+ current=missing
252
+ fi
253
+ stage="\${4:-}"
254
+ if [ "$current" != "$3" ]; then
255
+ [ -z "$stage" ] || rm -f "$stage"
256
+ printf '%s' "$current"
257
+ exit 15
258
+ fi
259
+ decoded="$(mktemp "\${TMPDIR:-/tmp}/sixb-write.XXXXXX")" || exit 19
260
+ if [ -n "$stage" ]; then
261
+ printf '%s' "\${SIXB_CHUNK:-}" >> "$stage"
262
+ base64 -d < "$stage" > "$decoded" || { rm -f "$stage" "$decoded"; exit 19; }
263
+ rm -f "$stage"
264
+ else
265
+ printf '%s' "\${SIXB_CHUNK:-}" | base64 -d > "$decoded" || { rm -f "$decoded"; exit 19; }
266
+ fi
267
+ cat "$decoded" > "$target" || { rm -f "$decoded"; exit 19; }
268
+ rm -f "$decoded"
269
+ fingerprint "$target"
270
+ print_path "$target"`
@@ -1,16 +1,13 @@
1
1
  import type { AgentRunWebPlan, AgentToolSpec } from "@sixb/core/internal/agents"
2
2
  import type { SandboxNetworkPolicy } from "@sixb/core/sandboxes"
3
- import {
4
- OPEN_ARTIFACT_TOOL_SPEC,
5
- PUBLISH_ARTIFACT_TOOL_SPEC,
6
- UPDATE_ARTIFACT_TOOL_SPEC,
7
- } from "../artifacts/publish-tool"
8
- import { BASH_OUTPUT_TOOL_SPEC, BASH_STOP_TOOL_SPEC } from "./background"
3
+ import { OPEN_ARTIFACT_TOOL_SPEC, PUBLISH_ARTIFACT_TOOL_SPEC } from "../artifacts/publish-tool"
4
+ import { STOP_TOOL_SPEC, WAIT_TOOL_SPEC } from "./background"
9
5
  import { BASH_TOOL_SPEC } from "./bash"
6
+ import { EDIT_TOOL_SPEC } from "./edit"
10
7
  import { READ_TOOL_SPEC } from "./read"
11
- import { VIEW_FILE_TOOL_SPEC } from "./view-file"
12
8
  import { WEB_FETCH_TOOL_SPEC } from "./web-fetch/tool"
13
9
  import { WEB_SEARCH_TOOL_SPEC } from "./web-search"
10
+ import { WRITE_TOOL_SPEC } from "./write"
14
11
 
15
12
  /**
16
13
  * Describe exactly the tools a conversational model receives, in its order, without starting its
@@ -28,16 +25,15 @@ export function agentModelToolSpecs(
28
25
  ): readonly AgentToolSpec[] {
29
26
  return [
30
27
  ...projectTools,
31
- VIEW_FILE_TOOL_SPEC,
32
28
  READ_TOOL_SPEC,
29
+ EDIT_TOOL_SPEC,
30
+ WRITE_TOOL_SPEC,
33
31
  BASH_TOOL_SPEC,
34
- BASH_OUTPUT_TOOL_SPEC,
35
- BASH_STOP_TOOL_SPEC,
32
+ WAIT_TOOL_SPEC,
33
+ STOP_TOOL_SPEC,
36
34
  ...(options.web?.search ? [WEB_SEARCH_TOOL_SPEC] : []),
37
35
  ...(fetchesWeb(options.web, options.networkPolicy) ? [WEB_FETCH_TOOL_SPEC] : []),
38
- ...(options.publishes === false
39
- ? []
40
- : [PUBLISH_ARTIFACT_TOOL_SPEC, UPDATE_ARTIFACT_TOOL_SPEC, OPEN_ARTIFACT_TOOL_SPEC]),
36
+ ...(options.publishes === false ? [] : [PUBLISH_ARTIFACT_TOOL_SPEC, OPEN_ARTIFACT_TOOL_SPEC]),
41
37
  ]
42
38
  }
43
39
 
package/src/tools/read.ts CHANGED
@@ -1,19 +1,26 @@
1
1
  import { posix } from "node:path"
2
2
  import { AgentToolPublicError, type CommandResult } from "@sixb/core"
3
+ import { isAgentToolResult } from "@sixb/core/internal/agents"
3
4
  import type { JsonObject, JsonValue, ModelTool } from "@sixb/core/models"
4
5
  import { AgentToolExecutionError } from "../errors"
5
6
  import { agentToolErrorText } from "../model-adapters"
6
7
  import { type AgentSandboxHandle, contextPath } from "../sandbox-handle"
8
+ import { FINGERPRINT_FUNCTIONS, type FileReadLedger, isFingerprint } from "./file-writes"
9
+ import { isKnownSandboxFile, type SandboxFileViewer, viewSandboxFile } from "./view-file"
7
10
 
8
11
  const DEFAULT_LIMIT = 2_000
9
12
  const MAX_BYTES = 50 * 1024
10
13
  const PROBE_BYTES = MAX_BYTES + 5
11
14
  const READ_TIMEOUT_MS = 30_000
15
+ const MAX_DIRECTORY_ENTRIES = 500
16
+ /** Shown as themselves, never paged as text. */
17
+ const VIEWED_FILE = /\.(png|jpe?g|gif|webp|pdf)$/i
12
18
 
13
19
  export const READ_TOOL_SPEC = {
14
20
  name: "read",
21
+ strict: true,
15
22
  description:
16
- "Read a UTF-8 text file relative to the sandbox working directory. Returns at most 2,000 lines or 50 KiB and includes nextOffset when more content remains. Prefer this over bash for reading files.",
23
+ "Read a file, or list a directory. Text comes as at most 2,000 lines or 50 KiB, with nextOffset when more remains; an image or a PDF comes as itself; a directory as its entries, folders ending in /. Prefer this over bash for reading files.",
17
24
  inputSchema: {
18
25
  type: "object",
19
26
  properties: {
@@ -40,6 +47,13 @@ export interface ReadToolInput {
40
47
  readonly limit?: number
41
48
  }
42
49
 
50
+ /** A directory's entries, names only, folders ending in `/`. */
51
+ export interface ReadDirectoryOutput {
52
+ readonly path: string
53
+ readonly entries: readonly string[]
54
+ readonly truncated?: true
55
+ }
56
+
43
57
  export interface ReadToolOutput {
44
58
  readonly path: string
45
59
  readonly content: string
@@ -49,21 +63,29 @@ export interface ReadToolOutput {
49
63
  readonly nextOffset?: number
50
64
  }
51
65
 
52
- /** Build the bounded UTF-8 file reader from the run's lazy sandbox resolver. */
66
+ /** Build the reader from the run's lazy sandbox resolver. */
53
67
  export function createReadTool(
54
- resolveSandbox: () => Promise<AgentSandboxHandle>
68
+ resolveSandbox: () => Promise<AgentSandboxHandle>,
69
+ /** Where each read is recorded, so `edit` and `write` change only a file the run has read. */
70
+ ledger?: FileReadLedger,
71
+ /** Shows images, PDFs and other files that are not text; without it, they are refused. */
72
+ viewer?: SandboxFileViewer
55
73
  ): ModelTool<ReadToolInput> {
56
74
  return {
57
75
  ...READ_TOOL_SPEC,
58
76
  parseInput: parseReadToolInput,
59
- async execute(input, { signal }): Promise<JsonValue> {
77
+ async execute(input, { signal, toolCallId }): Promise<JsonValue> {
60
78
  const path = normalizePath(input.path)
61
79
  const offset = positiveInteger(input.offset, 1, "offset")
62
80
  const limit = Math.min(positiveInteger(input.limit, DEFAULT_LIMIT, "limit"), DEFAULT_LIMIT)
63
81
 
82
+ let handle: AgentSandboxHandle
64
83
  let result: CommandResult
65
84
  try {
66
- const handle = await resolveSandbox()
85
+ handle = await resolveSandbox()
86
+ if (viewer && (VIEWED_FILE.test(path) || isKnownSandboxFile(viewer, handle, path))) {
87
+ return await viewSandboxFile(viewer, handle, { path, toolCallId, signal })
88
+ }
67
89
  const { sandbox, env } = handle
68
90
  result = await sandbox.runCommand(
69
91
  "bash",
@@ -76,6 +98,7 @@ export function createReadTool(
76
98
  String(limit),
77
99
  String(PROBE_BYTES),
78
100
  contextPath(handle),
101
+ String(MAX_DIRECTORY_ENTRIES + 1),
79
102
  ],
80
103
  {
81
104
  cwd: sandbox.workingDirectory,
@@ -86,13 +109,24 @@ export function createReadTool(
86
109
  )
87
110
  } catch (error) {
88
111
  signal.throwIfAborted()
112
+ if (error instanceof AgentToolPublicError) throw error
89
113
  throw new AgentToolExecutionError("read", { cause: error })
90
114
  }
91
115
 
92
116
  signal.throwIfAborted()
93
117
  if (result.exitCode !== 0) throwReadError(path, result.exitCode, result.stderr)
94
118
 
95
- const page = paginate(decodeBase64(result.stdout), path, offset, limit)
119
+ const [first = "", second = "", ...rest] = result.stdout.split("\n")
120
+ if (first === "directory") return directoryListing(path, [second, ...rest])
121
+
122
+ if (isFingerprint(first) && second) ledger?.record(second, first)
123
+ let page: ReturnType<typeof paginate>
124
+ try {
125
+ page = paginate(decodeBase64(rest.join("\n")), path, offset, limit)
126
+ } catch (error) {
127
+ if (!(error instanceof NotTextError) || !viewer) throw error
128
+ return viewSandboxFile(viewer, handle, { path, toolCallId, signal })
129
+ }
96
130
  const endLine = offset + page.lineCount - 1
97
131
  return {
98
132
  path,
@@ -103,10 +137,29 @@ export function createReadTool(
103
137
  ...(page.truncated ? { nextOffset: endLine + 1 } : {}),
104
138
  } as JsonValue
105
139
  },
140
+ // A file shown as itself reaches the model through the run's media bridge; text as it is.
141
+ toModelOutput(output, { signal, toolCallId }) {
142
+ return viewer && isAgentToolResult(output)
143
+ ? viewer.toolResultToModelOutput({ output, signal, toolCallId })
144
+ : { type: "json", value: output }
145
+ },
106
146
  errorText: agentToolErrorText,
107
147
  }
108
148
  }
109
149
 
150
+ function directoryListing(path: string, lines: readonly string[]): JsonValue {
151
+ const entries = lines.filter((line) => line !== "")
152
+ const truncated = entries.length > MAX_DIRECTORY_ENTRIES
153
+ return {
154
+ path,
155
+ entries: entries.slice(0, MAX_DIRECTORY_ENTRIES),
156
+ ...(truncated ? { truncated: true } : {}),
157
+ } satisfies ReadDirectoryOutput
158
+ }
159
+
160
+ /** A file that is not UTF-8 text: shown as itself when the run can, refused otherwise. */
161
+ class NotTextError extends AgentToolPublicError {}
162
+
110
163
  function parseReadToolInput(value: unknown): ReadToolInput {
111
164
  if (typeof value !== "object" || value === null || Array.isArray(value)) {
112
165
  throw publicError("input must be an object.")
@@ -165,7 +218,7 @@ function paginate(
165
218
  if (offset > 1) throw publicError(`offset ${offset} is beyond the end of '${path}'.`)
166
219
  return { content: "", lineCount: 1, truncated: false }
167
220
  }
168
- if (bytes.includes(0)) throw publicError(`'${path}' is binary, not UTF-8 text.`)
221
+ if (bytes.includes(0)) throw notText(path)
169
222
 
170
223
  let cursor = 0
171
224
  let lineCount = 0
@@ -206,7 +259,7 @@ function paginate(
206
259
  try {
207
260
  content = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, selectedEnd))
208
261
  } catch {
209
- throw publicError(`'${path}' is binary, not UTF-8 text.`)
262
+ throw notText(path)
210
263
  }
211
264
  return { content, lineCount, truncated }
212
265
  }
@@ -229,6 +282,10 @@ function throwReadError(path: string, exitCode: number, stderr: string): never {
229
282
  })
230
283
  }
231
284
 
285
+ function notText(path: string): NotTextError {
286
+ return new NotTextError(`[SixbAgent] read '${path}' is binary, not UTF-8 text.`)
287
+ }
288
+
232
289
  function publicError(message: string): AgentToolPublicError {
233
290
  return new AgentToolPublicError(`[SixbAgent] read ${message}`)
234
291
  }
@@ -245,10 +302,18 @@ case "$1" in /*) requested="$1" ;; *) requested="$root/$1" ;; esac
245
302
  target="$("$realpath_bin" "$requested")" || exit 10
246
303
  case "$target" in "$root"|"$root"/*|"$context"/*) ;; *) exit 11 ;; esac
247
304
  [ -e "$target" ] || exit 10
248
- [ ! -d "$target" ] || exit 12
305
+ if [ -d "$target" ]; then
306
+ printf 'directory\\n'
307
+ LC_ALL=C ls -1Ap -- "$target" | "$head_bin" -n "$6"
308
+ exit 0
309
+ fi
249
310
  [ -f "$target" ] || exit 13
250
311
  [ -r "$target" ] || exit 14
312
+ cksum_bin="$(command -v cksum)" || exit 20
313
+ ${FINGERPRINT_FUNCTIONS}
251
314
  export LC_ALL=C
315
+ fingerprint "$target" || printf '\\n'
316
+ print_path "$target"
252
317
  "$tail_bin" -n "+$2" -- "$target" | "$head_bin" -n "$(($3 + 1))" | "$head_bin" -c "$4" | "$base64_bin"
253
318
  for status in "\${PIPESTATUS[@]}"; do
254
319
  case "$status" in 0|141) ;; *) exit 19 ;; esac
@@ -259,4 +324,5 @@ const READ_COMMAND_BY_EXIT_CODE: Readonly<Record<number, string>> = {
259
324
  16: "tail",
260
325
  17: "head",
261
326
  18: "base64",
327
+ 20: "cksum",
262
328
  }
@@ -24,7 +24,7 @@ import { type AgentSandboxHandle, contextPath } from "../sandbox-handle"
24
24
  import { BASH_TOOL_SPEC, keptCommandOutput } from "./bash"
25
25
  import { READ_TOOL_SPEC } from "./read"
26
26
  import { AgentFileBudget } from "./tool-files"
27
- import { VIEW_FILE_TOOL_SPEC } from "./view-file"
27
+ import { LEGACY_VIEW_FILE_TOOL } from "./view-file"
28
28
  import { WEB_FETCH_TOOL_SPEC } from "./web-fetch/tool"
29
29
 
30
30
  /**
@@ -70,7 +70,7 @@ const LIST_TIMEOUT_MS = 30_000
70
70
  */
71
71
  const UNSAVED_TOOLS: ReadonlySet<string> = new Set([
72
72
  READ_TOOL_SPEC.name,
73
- VIEW_FILE_TOOL_SPEC.name,
73
+ LEGACY_VIEW_FILE_TOOL,
74
74
  WEB_FETCH_TOOL_SPEC.name,
75
75
  ])
76
76