@sixb/agent 0.2.3 → 0.2.5

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 (149) hide show
  1. package/README.md +3 -3
  2. package/dist/agent-prompt.d.ts.map +1 -1
  3. package/dist/artifacts/layout-check/layout-check.d.ts +21 -24
  4. package/dist/artifacts/layout-check/layout-check.d.ts.map +1 -1
  5. package/dist/artifacts/publish-tool.d.ts +26 -44
  6. package/dist/artifacts/publish-tool.d.ts.map +1 -1
  7. package/dist/ask-tool.d.ts +62 -0
  8. package/dist/ask-tool.d.ts.map +1 -0
  9. package/dist/attachments.d.ts +1 -1
  10. package/dist/attachments.d.ts.map +1 -1
  11. package/dist/background-commands.d.ts +3 -3
  12. package/dist/background-commands.d.ts.map +1 -1
  13. package/dist/background-notices.d.ts.map +1 -1
  14. package/dist/child-files.d.ts +1 -1
  15. package/dist/child-questions.d.ts +1 -1
  16. package/dist/index.d.ts +1 -2
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/index.js +10457 -7971
  19. package/dist/index.js.map +46 -38
  20. package/dist/run-agent-turn.d.ts +3 -14
  21. package/dist/run-agent-turn.d.ts.map +1 -1
  22. package/dist/run-conversation-turn.d.ts.map +1 -1
  23. package/dist/run-environment.d.ts +4 -1
  24. package/dist/run-environment.d.ts.map +1 -1
  25. package/dist/run-subagent.d.ts +1 -1
  26. package/dist/run-subagent.d.ts.map +1 -1
  27. package/dist/sandbox-api-context.d.ts.map +1 -1
  28. package/dist/search-script.d.ts +7 -0
  29. package/dist/search-script.d.ts.map +1 -0
  30. package/dist/skills/built-in.d.ts.map +1 -1
  31. package/dist/subagent-tools.d.ts +20 -1
  32. package/dist/subagent-tools.d.ts.map +1 -1
  33. package/dist/tools/background.d.ts +50 -18
  34. package/dist/tools/background.d.ts.map +1 -1
  35. package/dist/tools/bash.d.ts +1 -0
  36. package/dist/tools/bash.d.ts.map +1 -1
  37. package/dist/tools/edit-text.d.ts +22 -0
  38. package/dist/tools/edit-text.d.ts.map +1 -0
  39. package/dist/tools/edit.d.ts +54 -0
  40. package/dist/tools/edit.d.ts.map +1 -0
  41. package/dist/tools/file-writes.d.ts +52 -0
  42. package/dist/tools/file-writes.d.ts.map +1 -0
  43. package/dist/tools/glob.d.ts +41 -0
  44. package/dist/tools/glob.d.ts.map +1 -0
  45. package/dist/tools/grep.d.ts +64 -0
  46. package/dist/tools/grep.d.ts.map +1 -0
  47. package/dist/tools/model-spec.d.ts.map +1 -1
  48. package/dist/tools/read.d.ts +16 -3
  49. package/dist/tools/read.d.ts.map +1 -1
  50. package/dist/tools/sandbox-search.d.ts +26 -0
  51. package/dist/tools/sandbox-search.d.ts.map +1 -0
  52. package/dist/tools/search/command.d.ts +15 -0
  53. package/dist/tools/search/command.d.ts.map +1 -0
  54. package/dist/tools/search/gitignore.d.ts +28 -0
  55. package/dist/tools/search/gitignore.d.ts.map +1 -0
  56. package/dist/tools/search/glob.d.ts +15 -0
  57. package/dist/tools/search/glob.d.ts.map +1 -0
  58. package/dist/tools/search/main.d.ts +2 -0
  59. package/dist/tools/search/main.d.ts.map +1 -0
  60. package/dist/tools/search/match.d.ts +30 -0
  61. package/dist/tools/search/match.d.ts.map +1 -0
  62. package/dist/tools/search/pattern.d.ts +19 -0
  63. package/dist/tools/search/pattern.d.ts.map +1 -0
  64. package/dist/tools/search/read.d.ts +62 -0
  65. package/dist/tools/search/read.d.ts.map +1 -0
  66. package/dist/tools/search/request.d.ts +80 -0
  67. package/dist/tools/search/request.d.ts.map +1 -0
  68. package/dist/tools/search/search.d.ts +4 -0
  69. package/dist/tools/search/search.d.ts.map +1 -0
  70. package/dist/tools/search/walk.d.ts +43 -0
  71. package/dist/tools/search/walk.d.ts.map +1 -0
  72. package/dist/tools/tool-outputs.d.ts.map +1 -1
  73. package/dist/tools/view-file.d.ts +20 -23
  74. package/dist/tools/view-file.d.ts.map +1 -1
  75. package/dist/tools/web-fetch/tool.d.ts +1 -0
  76. package/dist/tools/web-fetch/tool.d.ts.map +1 -1
  77. package/dist/tools/web-search.d.ts +1 -0
  78. package/dist/tools/web-search.d.ts.map +1 -1
  79. package/dist/tools/write.d.ts +36 -0
  80. package/dist/tools/write.d.ts.map +1 -0
  81. package/dist/turn-inbox.d.ts +75 -0
  82. package/dist/turn-inbox.d.ts.map +1 -0
  83. package/package.json +6 -4
  84. package/src/agent-prompt.ts +10 -9
  85. package/src/agent-runtime/preflight.ts +1 -0
  86. package/src/artifacts/layout-check/check.cjs +176 -95
  87. package/src/artifacts/layout-check/layout-check.ts +118 -76
  88. package/src/artifacts/publish-tool.ts +123 -192
  89. package/src/ask-tool.ts +223 -0
  90. package/src/attachments.ts +7 -6
  91. package/src/background-commands.ts +5 -5
  92. package/src/background-notices.ts +5 -12
  93. package/src/child-files.ts +1 -1
  94. package/src/child-questions.ts +1 -1
  95. package/src/context-compaction.ts +4 -1
  96. package/src/generated/search.mjs +985 -0
  97. package/src/index.ts +1 -2
  98. package/src/run-agent-turn.ts +99 -133
  99. package/src/run-child.ts +1 -1
  100. package/src/run-conversation-turn.ts +8 -5
  101. package/src/run-environment.ts +40 -21
  102. package/src/run-subagent.ts +4 -4
  103. package/src/sandbox-api-context.ts +3 -0
  104. package/src/search-script-assets.d.ts +5 -0
  105. package/src/search-script.ts +9 -0
  106. package/src/skills/built-in.ts +16 -0
  107. package/src/skills/sixb-artifacts/SKILL.md +13 -13
  108. package/src/skills/sixb-artifacts/canvas.md +5 -4
  109. package/src/skills/sixb-artifacts/document.md +92 -5
  110. package/src/skills/sixb-artifacts/examples/document/service-proposal/design.css +114 -0
  111. package/src/skills/sixb-artifacts/examples/document/service-proposal/document.html +159 -0
  112. package/src/skills/sixb-artifacts/examples/document/service-proposal/images/fieldwise.svg +1 -0
  113. package/src/skills/sixb-artifacts/examples/document/service-proposal/images/harbor-pine.svg +1 -0
  114. package/src/skills/sixb-artifacts/page.md +2 -2
  115. package/src/skills/sixb-artifacts/queries.md +2 -1
  116. package/src/skills/sixb-artifacts/slides.md +2 -2
  117. package/src/subagent-tools.ts +115 -81
  118. package/src/tools/background.ts +227 -67
  119. package/src/tools/bash.ts +2 -1
  120. package/src/tools/edit-text.ts +241 -0
  121. package/src/tools/edit.ts +166 -0
  122. package/src/tools/file-writes.ts +270 -0
  123. package/src/tools/glob.ts +124 -0
  124. package/src/tools/grep.ts +190 -0
  125. package/src/tools/model-spec.ts +13 -13
  126. package/src/tools/read.ts +75 -9
  127. package/src/tools/sandbox-search.ts +219 -0
  128. package/src/tools/search/command.ts +116 -0
  129. package/src/tools/search/gitignore.ts +101 -0
  130. package/src/tools/search/glob.ts +90 -0
  131. package/src/tools/search/main.ts +9 -0
  132. package/src/tools/search/match.ts +278 -0
  133. package/src/tools/search/pattern.ts +178 -0
  134. package/src/tools/search/read.ts +237 -0
  135. package/src/tools/search/request.ts +101 -0
  136. package/src/tools/search/search.ts +297 -0
  137. package/src/tools/search/walk.ts +145 -0
  138. package/src/tools/tool-outputs.ts +9 -4
  139. package/src/tools/view-file.ts +78 -80
  140. package/src/tools/web-fetch/tool.ts +2 -1
  141. package/src/tools/web-search.ts +1 -0
  142. package/src/tools/write.ts +95 -0
  143. package/src/turn-inbox.ts +283 -0
  144. package/dist/artifacts/board-previews.d.ts +0 -41
  145. package/dist/artifacts/board-previews.d.ts.map +0 -1
  146. package/dist/ask-parent-tool.d.ts +0 -36
  147. package/dist/ask-parent-tool.d.ts.map +0 -1
  148. package/src/artifacts/board-previews.ts +0 -218
  149. package/src/ask-parent-tool.ts +0 -100
@@ -0,0 +1,297 @@
1
+ import { Buffer } from "node:buffer"
2
+ import { lstatSync, realpathSync, statSync } from "node:fs"
3
+ import { basename, dirname, relative, resolve } from "node:path"
4
+ import type { IgnoreFile } from "./gitignore"
5
+ import { compileGlob, type GlobMatcher } from "./glob"
6
+ import { cutLine, lines, textMatcher } from "./match"
7
+ import { PatternError } from "./pattern"
8
+ import { type FileText, openText, ReadAhead } from "./read"
9
+ import {
10
+ type GlobSearchRequest,
11
+ type GlobSearchResult,
12
+ type GrepMatch,
13
+ type GrepSearchRequest,
14
+ type GrepSearchResult,
15
+ SEARCH_LIMITS,
16
+ SearchError,
17
+ type SearchErrorCode,
18
+ type SearchRequest,
19
+ } from "./request"
20
+ import { childPath, FileWalk, readIgnoreFile, type WalkedFile } from "./walk"
21
+
22
+ export function globFiles(request: GlobSearchRequest, workingDirectory: string): GlobSearchResult {
23
+ const scope = resolveScope(request, workingDirectory)
24
+ const matcher = compileGlobOrFail(request.pattern, "invalid_pattern")
25
+ if (scope.file) throw new SearchError("path_is_file", "The path is a file.")
26
+
27
+ const walk = scope.walk(matcher, matcher.namesHidden)
28
+ const files: string[] = []
29
+ let truncated = false
30
+
31
+ for (const file of walk.files()) {
32
+ if (!matcher.matches(file.relative)) continue
33
+ if (files.length === SEARCH_LIMITS.files) {
34
+ truncated = true
35
+ break
36
+ }
37
+ files.push(scope.display(file.path))
38
+ }
39
+
40
+ return { files, truncated, ...(walk.incomplete ? { incomplete: true as const } : {}) }
41
+ }
42
+
43
+ export async function grepFiles(
44
+ request: GrepSearchRequest,
45
+ workingDirectory: string
46
+ ): Promise<GrepSearchResult> {
47
+ const scope = resolveScope(request, workingDirectory)
48
+ const matcher = textMatcher(request.pattern, request.literal === true)
49
+ const include =
50
+ request.include === undefined
51
+ ? undefined
52
+ : compileGlobOrFail(request.include, "invalid_include")
53
+
54
+ // A file named as the path is searched alone, whatever include says.
55
+ const walk = scope.file ? undefined : scope.walk(include, true)
56
+ const searched = function* (): Generator<WalkedFile> {
57
+ if (!walk) {
58
+ yield { path: scope.target, relative: basename(scope.target), symlink: false }
59
+ return
60
+ }
61
+
62
+ for (const file of walk.files()) {
63
+ if (include && !include.matches(file.relative)) continue
64
+ if (file.symlink && !scope.holds(file.path)) continue
65
+ yield file
66
+ }
67
+ }
68
+ // Files are read ahead of the one searched, and come back in the walk's order.
69
+ const reads = new ReadAhead(
70
+ searched(),
71
+ (file: WalkedFile) => openText(file.path, walk === undefined),
72
+ (read: FileText) => !("text" in read)
73
+ )
74
+
75
+ const matches: GrepMatch[] = []
76
+ const more: Record<string, number> = {}
77
+ let files = 0
78
+ let textBytes = 0
79
+ let textFull = false
80
+ let truncated = false
81
+ let stopped = false
82
+
83
+ try {
84
+ for (let next = await reads.next(); next; next = await reads.next()) {
85
+ const { item: file, read } = next
86
+
87
+ if (!("text" in read)) {
88
+ // A file named as the path says why it was not searched, rather than "No matches".
89
+ if (walk === undefined && read.skipped !== "unreadable") throw unsearchedError(read.skipped)
90
+ continue
91
+ }
92
+
93
+ // Most files hold no match: one test of the whole text spares splitting them into lines.
94
+ if (!matcher.mayMatch(read.text)) continue
95
+
96
+ const path = scope.display(file.path)
97
+ let shown = 0
98
+ let counted = 0
99
+
100
+ for (const [index, line] of lines(read.text).entries()) {
101
+ // One file can hold enough lines, or slow enough ones, to outlast the deadline alone.
102
+ if (Date.now() >= scope.deadline) {
103
+ stopped = true
104
+ break
105
+ }
106
+ const match = matcher.line(line)
107
+ if (match === undefined) continue
108
+
109
+ const text = cutLine(line, match)
110
+ const bytes =
111
+ Buffer.byteLength(` ${index + 1}: ${text}\n`) +
112
+ (shown === 0 ? Buffer.byteLength(`${path}\n\n`) : 0)
113
+ if (textBytes + bytes > SEARCH_LIMITS.textBytes) textFull = true
114
+ const full = textFull || matches.length === SEARCH_LIMITS.lines
115
+
116
+ if (shown === 0 && full) {
117
+ truncated = true
118
+ break
119
+ }
120
+ if (shown > 0 && (shown === SEARCH_LIMITS.linesPerFile || full)) {
121
+ counted += 1
122
+ continue
123
+ }
124
+
125
+ matches.push({ path, line: index + 1, text })
126
+ textBytes += bytes
127
+ shown += 1
128
+ }
129
+
130
+ if (shown > 0) files += 1
131
+ if (counted > 0) more[path] = counted
132
+ if (truncated || stopped) break
133
+ }
134
+ } finally {
135
+ await reads.stop()
136
+ }
137
+
138
+ return {
139
+ matches,
140
+ files,
141
+ ...(Object.keys(more).length > 0 ? { more } : {}),
142
+ truncated,
143
+ ...(walk?.incomplete || stopped ? { incomplete: true as const } : {}),
144
+ }
145
+ }
146
+
147
+ interface SearchScope {
148
+ /** The real path searched. */
149
+ readonly target: string
150
+ /** The target is a file. */
151
+ readonly file: boolean
152
+ /** The time, in epoch milliseconds, at which the search stops with what it found. */
153
+ readonly deadline: number
154
+ /** Whether a path's target lies in the run's roots. */
155
+ holds(path: string): boolean
156
+ display(path: string): string
157
+ walk(matcher: GlobMatcher | undefined, hidden: boolean): FileWalk
158
+ }
159
+
160
+ /**
161
+ * Where a search starts, confined to the working directory and the run's context directory once
162
+ * links are resolved, as `read` confines a path.
163
+ */
164
+ function resolveScope(request: SearchRequest, workingDirectory: string): SearchScope {
165
+ const deadline = Date.now() + request.timeoutMs
166
+ const working = realpathSync(workingDirectory)
167
+ const context =
168
+ request.contextDirectory === undefined
169
+ ? undefined
170
+ : realPath(resolve(working, request.contextDirectory))
171
+
172
+ const target = realPath(resolve(working, request.path ?? "."))
173
+ if (target === undefined) throw new SearchError("path_missing", "The path does not exist.")
174
+
175
+ // The context directory may sit inside the working directory: the closer root is the one used.
176
+ const root =
177
+ context !== undefined && isWithin(target, context)
178
+ ? context
179
+ : isWithin(target, working)
180
+ ? working
181
+ : undefined
182
+ if (root === undefined) {
183
+ throw new SearchError("path_outside", "The path is outside the run's folders.")
184
+ }
185
+
186
+ const stats = statSync(target)
187
+ if (!stats.isFile() && !stats.isDirectory()) {
188
+ throw new SearchError("path_not_searchable", "The path is not a file or a folder.")
189
+ }
190
+
191
+ const holds = (path: string): boolean => {
192
+ const real = realPath(path)
193
+ return (
194
+ real !== undefined &&
195
+ (isWithin(real, working) || (context !== undefined && isWithin(real, context)))
196
+ )
197
+ }
198
+
199
+ const display = (path: string): string =>
200
+ isWithin(path, working) ? relative(working, path) || "." : path
201
+
202
+ const walk = (matcher: GlobMatcher | undefined, hidden: boolean): FileWalk => {
203
+ const namesNodeModules = relative(root, target).split("/").includes("node_modules")
204
+ return new FileWalk({
205
+ root: target,
206
+ ignoreFiles: [...repositoryIgnoreFiles(root), ...ancestorIgnoreFiles(root, target)],
207
+ hidden,
208
+ nodeModules: namesNodeModules || matcher?.namesNodeModules === true,
209
+ skipFolders: new Set(context !== undefined && !isWithin(target, context) ? [context] : []),
210
+ ...(matcher ? { mayContain: (folder: string) => matcher.mayContain(folder) } : {}),
211
+ deadline,
212
+ })
213
+ }
214
+
215
+ return { target, file: stats.isFile(), deadline, holds, display, walk }
216
+ }
217
+
218
+ /** How far above a root the git repository it lies in is looked for. */
219
+ const REPOSITORY_LEVELS = 20
220
+
221
+ /**
222
+ * The ignore rules of the git repository a root lies in, from above the root: its
223
+ * `.git/info/exclude`, then the `.gitignore` of each folder from the repository's top down to the
224
+ * folder above the root, as git applies them. Only those files are read; nothing outside the
225
+ * roots is walked. A root outside any repository gets none.
226
+ */
227
+ function repositoryIgnoreFiles(root: string): IgnoreFile[] {
228
+ const above: string[] = []
229
+ let folder = root
230
+
231
+ for (let level = 0; level <= REPOSITORY_LEVELS; level += 1) {
232
+ if (holdsGit(folder)) {
233
+ const exclude = readIgnoreFile(folder, ".git/info/exclude")
234
+ return [
235
+ ...(exclude ? [exclude] : []),
236
+ ...above.flatMap((parent) => readIgnoreFile(parent) ?? []),
237
+ ]
238
+ }
239
+
240
+ const parent = dirname(folder)
241
+ if (parent === folder) return []
242
+ folder = parent
243
+ above.unshift(folder)
244
+ }
245
+
246
+ return []
247
+ }
248
+
249
+ /** A folder holding `.git`: a repository's top, or a worktree's, where `.git` is a file. */
250
+ function holdsGit(folder: string): boolean {
251
+ try {
252
+ lstatSync(childPath(folder, ".git"))
253
+ return true
254
+ } catch {
255
+ return false
256
+ }
257
+ }
258
+
259
+ /** The `.gitignore` files from the root down to the folder above the target, outermost first. */
260
+ function ancestorIgnoreFiles(root: string, target: string): IgnoreFile[] {
261
+ if (target === root) return []
262
+
263
+ const folders: string[] = []
264
+ for (let folder = dirname(target); isWithin(folder, root); folder = dirname(folder)) {
265
+ folders.unshift(folder)
266
+ if (folder === root) break
267
+ }
268
+
269
+ return folders.flatMap((folder) => readIgnoreFile(folder) ?? [])
270
+ }
271
+
272
+ function compileGlobOrFail(pattern: string, code: SearchErrorCode): GlobMatcher {
273
+ try {
274
+ return compileGlob(pattern)
275
+ } catch (error) {
276
+ if (error instanceof PatternError) throw new SearchError(code, error.message)
277
+ throw error
278
+ }
279
+ }
280
+
281
+ function unsearchedError(reason: "binary" | "too_large"): SearchError {
282
+ return reason === "binary"
283
+ ? new SearchError("file_binary", "The file is binary, or not UTF-8 text.")
284
+ : new SearchError("file_too_large", "The file is over 10 MiB.")
285
+ }
286
+
287
+ function realPath(path: string): string | undefined {
288
+ try {
289
+ return realpathSync(path)
290
+ } catch {
291
+ return undefined
292
+ }
293
+ }
294
+
295
+ function isWithin(path: string, root: string): boolean {
296
+ return path === root || path.startsWith(root.endsWith("/") ? root : `${root}/`)
297
+ }
@@ -0,0 +1,145 @@
1
+ import { Buffer } from "node:buffer"
2
+ import { type Dirent, lstatSync, readdirSync, readFileSync, statSync } from "node:fs"
3
+ import { type IgnoreFile, isIgnored, parseGitignore } from "./gitignore"
4
+
5
+ export interface WalkOptions {
6
+ /** The folder to walk: a real, absolute path. */
7
+ readonly root: string
8
+ /** The `.gitignore` files of the folders above the root that apply, outermost first. */
9
+ readonly ignoreFiles: readonly IgnoreFile[]
10
+ /** Enter folders and list files whose name starts with `.`. */
11
+ readonly hidden: boolean
12
+ readonly nodeModules: boolean
13
+ /** Real, absolute paths of folders never entered: the run's context directory. */
14
+ readonly skipFolders: ReadonlySet<string>
15
+ /** Whether a folder, relative to the root, may hold what the search looks for. */
16
+ readonly mayContain?: (relativeFolder: string) => boolean
17
+ /** The time, in epoch milliseconds, at which the walk stops. */
18
+ readonly deadline: number
19
+ }
20
+
21
+ export interface WalkedFile {
22
+ readonly path: string
23
+ /** From the root, with `/`. */
24
+ readonly relative: string
25
+ /** A link to a file: listed, but its target may be anywhere. */
26
+ readonly symlink: boolean
27
+ }
28
+
29
+ /**
30
+ * The files under a folder, in byte order of their paths, so that the first results of a capped
31
+ * search are the same on every run. `.git`, hidden entries and `node_modules` unless asked for,
32
+ * what `.gitignore` files exclude, and unreadable entries are skipped. Links to folders are not
33
+ * followed. Past its deadline, the walk stops and says it is {@link incomplete}.
34
+ */
35
+ export class FileWalk {
36
+ #incomplete = false
37
+
38
+ constructor(private readonly options: WalkOptions) {}
39
+
40
+ get incomplete(): boolean {
41
+ return this.#incomplete
42
+ }
43
+
44
+ *files(): Generator<WalkedFile> {
45
+ yield* this.#folder(this.options.root, "", this.options.ignoreFiles)
46
+ }
47
+
48
+ *#folder(
49
+ folder: string,
50
+ relativeFolder: string,
51
+ ignoreFiles: readonly IgnoreFile[]
52
+ ): Generator<WalkedFile> {
53
+ if (this.#pastDeadline()) return
54
+
55
+ let entries: Dirent[]
56
+ try {
57
+ entries = readdirSync(folder, { withFileTypes: true })
58
+ } catch {
59
+ return
60
+ }
61
+
62
+ const own = entries.some((entry) => entry.name === ".gitignore")
63
+ ? readIgnoreFile(folder)
64
+ : undefined
65
+ const applying = own ? [...ignoreFiles, own] : ignoreFiles
66
+
67
+ for (const entry of sortedEntries(entries)) {
68
+ if (this.#incomplete) return
69
+
70
+ const { name } = entry
71
+ if (name === ".git") continue
72
+ if (!this.options.hidden && name.startsWith(".")) continue
73
+
74
+ const path = childPath(folder, name)
75
+ const relative = relativeFolder ? `${relativeFolder}/${name}` : name
76
+
77
+ if (entry.isDirectory()) {
78
+ if (name === "node_modules" && !this.options.nodeModules) continue
79
+ if (this.options.skipFolders.has(path)) continue
80
+ if (isIgnored(applying, path, true)) continue
81
+ if (this.options.mayContain && !this.options.mayContain(relative)) continue
82
+
83
+ yield* this.#folder(path, relative, applying)
84
+ continue
85
+ }
86
+
87
+ const symlink = entry.isSymbolicLink()
88
+ if (!entry.isFile() && !(symlink && isLinkToFile(path))) continue
89
+ if (isIgnored(applying, path, false)) continue
90
+ if (this.#pastDeadline()) return
91
+
92
+ yield { path, relative, symlink }
93
+ }
94
+ }
95
+
96
+ #pastDeadline(): boolean {
97
+ if (Date.now() >= this.options.deadline) this.#incomplete = true
98
+ return this.#incomplete
99
+ }
100
+ }
101
+
102
+ /** Past this size, an ignore file is not read. */
103
+ const IGNORE_FILE_BYTES = 1024 * 1024
104
+
105
+ /**
106
+ * A folder's `.gitignore`, or another ignore file applying from it, when it is a regular file it
107
+ * can read. A link is not followed, as git does not, and a device or a FIFO is never opened.
108
+ */
109
+ export function readIgnoreFile(folder: string, name = ".gitignore"): IgnoreFile | undefined {
110
+ try {
111
+ const path = childPath(folder, name)
112
+ const stats = lstatSync(path)
113
+ if (!stats.isFile() || stats.size > IGNORE_FILE_BYTES) return undefined
114
+
115
+ return { folder, rules: parseGitignore(readFileSync(path, "utf8")) }
116
+ } catch {
117
+ return undefined
118
+ }
119
+ }
120
+
121
+ /**
122
+ * Entries in the order their paths sort in, byte by byte: a folder as its name and a `/`, so that
123
+ * `a.txt` comes before `a/b.txt` as it does in a sorted list of paths.
124
+ */
125
+ function sortedEntries(entries: readonly Dirent[]): Dirent[] {
126
+ return entries
127
+ .map((entry) => ({
128
+ entry,
129
+ key: Buffer.from(entry.isDirectory() ? `${entry.name}/` : entry.name),
130
+ }))
131
+ .sort((left, right) => Buffer.compare(left.key, right.key))
132
+ .map(({ entry }) => entry)
133
+ }
134
+
135
+ export function childPath(folder: string, name: string): string {
136
+ return folder.endsWith("/") ? `${folder}${name}` : `${folder}/${name}`
137
+ }
138
+
139
+ function isLinkToFile(path: string): boolean {
140
+ try {
141
+ return statSync(path).isFile()
142
+ } catch {
143
+ return false
144
+ }
145
+ }
@@ -22,9 +22,11 @@ import type { AgentMessageRecord } from "@sixb/core/storage"
22
22
  import { listSandboxFiles } from "../sandbox-files"
23
23
  import { type AgentSandboxHandle, contextPath } from "../sandbox-handle"
24
24
  import { BASH_TOOL_SPEC, keptCommandOutput } from "./bash"
25
+ import { GLOB_TOOL_SPEC } from "./glob"
26
+ import { GREP_TOOL_SPEC } from "./grep"
25
27
  import { READ_TOOL_SPEC } from "./read"
26
28
  import { AgentFileBudget } from "./tool-files"
27
- import { VIEW_FILE_TOOL_SPEC } from "./view-file"
29
+ import { LEGACY_VIEW_FILE_TOOL } from "./view-file"
28
30
  import { WEB_FETCH_TOOL_SPEC } from "./web-fetch/tool"
29
31
 
30
32
  /**
@@ -65,12 +67,15 @@ const LISTED_OUTPUTS_MAX_FILES = 1_000
65
67
  const LIST_TIMEOUT_MS = 30_000
66
68
 
67
69
  /**
68
- * Never saved here: the readers page through files themselves, and `web_fetch` saves its page
69
- * itself ({@link ToolOutputFiles.store}).
70
+ * Never saved here: the readers page through files themselves, `glob` and `grep` cap what they
71
+ * return and show it as text a saved JSON would not be, and `web_fetch` saves its page itself
72
+ * ({@link ToolOutputFiles.store}).
70
73
  */
71
74
  const UNSAVED_TOOLS: ReadonlySet<string> = new Set([
72
75
  READ_TOOL_SPEC.name,
73
- VIEW_FILE_TOOL_SPEC.name,
76
+ GLOB_TOOL_SPEC.name,
77
+ GREP_TOOL_SPEC.name,
78
+ LEGACY_VIEW_FILE_TOOL,
74
79
  WEB_FETCH_TOOL_SPEC.name,
75
80
  ])
76
81
 
@@ -2,9 +2,7 @@ import { posix } from "node:path"
2
2
  import type { AgentToolFiles, FileRef, JsonValue } from "@sixb/core"
3
3
  import { AgentToolPublicError } from "@sixb/core"
4
4
  import { inferFileMediaType } from "@sixb/core/internal/blob-storage"
5
- import type { JsonObject, ModelTool } from "@sixb/core/models"
6
5
  import type { PreparedAgentAttachmentContext } from "../attachments"
7
- import { agentToolErrorText } from "../model-adapters"
8
6
  import type { AgentSandboxFileRegistry } from "../sandbox-file-registry"
9
7
  import { readSandboxFile, resolveSandboxPath, SandboxFileError } from "../sandbox-files"
10
8
  import type { AgentSandboxHandle } from "../sandbox-handle"
@@ -13,24 +11,14 @@ import { AGENT_FILE_MAX_BYTES } from "./tool-files"
13
11
 
14
12
  const VIEW_FILE_TIMEOUT_MS = 30_000
15
13
 
16
- export const VIEW_FILE_TOOL_SPEC = {
17
- name: "view_file",
18
- description:
19
- "Inspect a file in the current run sandbox. Use this for historical attachments and files created by bash. Paths must stay inside the working directory or the run's context directory. Images are prepared for visual input when supported; other formats return bounded text or metadata.",
20
- inputSchema: {
21
- type: "object",
22
- properties: { path: { type: "string", minLength: 1 } },
23
- required: ["path"],
24
- additionalProperties: false,
25
- } satisfies JsonObject,
26
- } as const
14
+ /**
15
+ * What `read` took over: earlier threads hold calls to `view_file`, and their results replay as
16
+ * they were stored, images included.
17
+ */
18
+ export const LEGACY_VIEW_FILE_TOOL = "view_file"
27
19
 
28
- interface ViewFileInput {
29
- readonly path: string
30
- }
31
-
32
- export function createViewFileTool(input: {
33
- readonly resolveSandbox: () => Promise<AgentSandboxHandle>
20
+ /** What `read` needs to show a file as itself, an image or a PDF, rather than as text. */
21
+ export interface SandboxFileViewer {
34
22
  readonly attachments: PreparedAgentAttachmentContext
35
23
  readonly registry: AgentSandboxFileRegistry
36
24
  readonly filesForToolCall: (options: {
@@ -42,67 +30,79 @@ export function createViewFileTool(input: {
42
30
  readonly signal: AbortSignal
43
31
  readonly toolCallId: string
44
32
  }) => AgentToolModelOutput | Promise<AgentToolModelOutput>
45
- }): ModelTool<ViewFileInput> {
46
- return {
47
- ...VIEW_FILE_TOOL_SPEC,
48
- parseInput: parseViewFileInput,
49
- async execute({ path }, { signal, toolCallId }): Promise<JsonValue> {
50
- signal.throwIfAborted()
51
- const handle = await input.resolveSandbox()
52
- let absolutePath: string
53
- try {
54
- absolutePath = resolveSandboxPath(handle, path)
55
- } catch (error) {
56
- throw toViewFileError(error)
57
- }
58
- const knownFileRef =
59
- input.registry.get(absolutePath) ??
60
- preparedFileRefAtPath(input.attachments, handle.sandbox.workingDirectory, absolutePath)
33
+ }
61
34
 
62
- let fileRef: FileRef
63
- if (knownFileRef) {
64
- fileRef = knownFileRef
65
- } else {
66
- const bytes = await readSandboxFile(handle, {
67
- path: absolutePath,
68
- maxBytes: AGENT_FILE_MAX_BYTES,
69
- signal,
70
- timeoutMs: VIEW_FILE_TIMEOUT_MS,
71
- }).catch((error: unknown) => {
72
- throw toViewFileError(error)
73
- })
74
- const fileName = safePublishedFileName(posix.basename(absolutePath))
75
- const file = await input.filesForToolCall({ toolCallId, signal }).put({
76
- body: bytes,
77
- fileName,
78
- mediaType: inferFileMediaType(fileName, bytes),
79
- })
80
- fileRef = file.fileRef
81
- }
35
+ /**
36
+ * A sandbox file as a rich result: the file itself, stored with the call, which the run's media
37
+ * bridge shows the model as an image or a document when it can, and as metadata otherwise. An
38
+ * attachment, or a file a tool stored, is the snapshot it already is.
39
+ */
40
+ export async function viewSandboxFile(
41
+ viewer: SandboxFileViewer,
42
+ handle: AgentSandboxHandle,
43
+ input: { readonly path: string; readonly toolCallId: string; readonly signal: AbortSignal }
44
+ ): Promise<JsonValue> {
45
+ input.signal.throwIfAborted()
46
+ let absolutePath: string
47
+ try {
48
+ absolutePath = resolveSandboxPath(handle, input.path)
49
+ } catch (error) {
50
+ throw toViewError(error)
51
+ }
52
+ const knownFileRef =
53
+ viewer.registry.get(absolutePath) ??
54
+ preparedFileRefAtPath(viewer.attachments, handle.sandbox.workingDirectory, absolutePath)
82
55
 
83
- // Prepared attachments and files tools stored are immutable snapshots and can be reused.
84
- // Arbitrary bash paths stay mutable, so do not cache their published snapshot at the source
85
- // path; a later view_file call must read the path again.
86
- if (knownFileRef) input.registry.register(absolutePath, fileRef)
87
- return richViewFileResult(fileRef)
88
- },
89
- toModelOutput(output, { toolCallId, signal }) {
90
- return input.toolResultToModelOutput({ output, toolCallId, signal })
91
- },
92
- errorText: agentToolErrorText,
56
+ let fileRef: FileRef
57
+ if (knownFileRef) {
58
+ fileRef = knownFileRef
59
+ } else {
60
+ const bytes = await readSandboxFile(handle, {
61
+ path: absolutePath,
62
+ maxBytes: AGENT_FILE_MAX_BYTES,
63
+ signal: input.signal,
64
+ timeoutMs: VIEW_FILE_TIMEOUT_MS,
65
+ }).catch((error: unknown) => {
66
+ throw toViewError(error)
67
+ })
68
+ const fileName = safePublishedFileName(posix.basename(absolutePath))
69
+ const file = await viewer
70
+ .filesForToolCall({ toolCallId: input.toolCallId, signal: input.signal })
71
+ .put({ body: bytes, fileName, mediaType: inferFileMediaType(fileName, bytes) })
72
+ fileRef = file.fileRef
93
73
  }
74
+
75
+ // Prepared attachments and files tools stored are immutable snapshots and can be reused.
76
+ // Arbitrary bash paths stay mutable, so do not cache their published snapshot at the source
77
+ // path; a later read must read the path again.
78
+ if (knownFileRef) viewer.registry.register(absolutePath, fileRef)
79
+ return richViewFileResult(fileRef)
94
80
  }
95
81
 
96
- function parseViewFileInput(value: unknown): ViewFileInput {
97
- if (typeof value !== "object" || value === null || Array.isArray(value)) {
98
- throw viewFileError("input must be an object")
82
+ /** Whether `path` names an attachment or a file a tool stored, which `read` shows as itself. */
83
+ export function isKnownSandboxFile(
84
+ viewer: SandboxFileViewer,
85
+ handle: AgentSandboxHandle,
86
+ path: string
87
+ ): boolean {
88
+ let absolutePath: string
89
+ try {
90
+ absolutePath = resolveSandboxPath(handle, path)
91
+ } catch {
92
+ return false
99
93
  }
100
- const input = value as Record<string, unknown>
101
- if (Object.keys(input).some((key) => key !== "path")) {
102
- throw viewFileError("input contains an unknown property")
103
- }
104
- if (typeof input.path !== "string") throw viewFileError("path must be a string")
105
- return { path: input.path }
94
+ const fileRef =
95
+ viewer.registry.get(absolutePath) ??
96
+ preparedFileRefAtPath(viewer.attachments, handle.sandbox.workingDirectory, absolutePath)
97
+ return fileRef !== undefined && !isTextMediaType(fileRef.mediaType)
98
+ }
99
+
100
+ function isTextMediaType(mediaType: string | undefined): boolean {
101
+ return (
102
+ mediaType !== undefined &&
103
+ (mediaType.startsWith("text/") ||
104
+ /^application\/(json|xml|yaml|x-yaml|javascript|typescript|csv|x-sh)\b/.test(mediaType))
105
+ )
106
106
  }
107
107
 
108
108
  function preparedFileRefAtPath(
@@ -146,10 +146,8 @@ function safePublishedFileName(value: string): string {
146
146
  }
147
147
 
148
148
  /** A sandbox file refusal becomes the message the Agent sees; anything else passes through. */
149
- function toViewFileError(error: unknown): unknown {
150
- return error instanceof SandboxFileError ? viewFileError(error.message) : error
151
- }
152
-
153
- function viewFileError(message: string): AgentToolPublicError {
154
- return new AgentToolPublicError(`[SixbAgent] view_file ${message}.`)
149
+ function toViewError(error: unknown): unknown {
150
+ return error instanceof SandboxFileError
151
+ ? new AgentToolPublicError(`[SixbAgent] read ${error.message}.`)
152
+ : error
155
153
  }
@@ -54,6 +54,7 @@ const ANSWER_INSTRUCTIONS = [
54
54
 
55
55
  export const WEB_FETCH_TOOL_SPEC = {
56
56
  name: "web_fetch",
57
+ strict: true,
57
58
  description:
58
59
  "Read a web page, PDF or image by URL. A large page is saved to a file. Pass a question to get an answer from the page.",
59
60
  inputSchema: {
@@ -266,7 +267,7 @@ function savedNote(output: WebFetchToolOutput): string {
266
267
  if (/\.(?:md|txt)$/.test(output.path ?? "")) {
267
268
  return `The page (${size} sent) is saved as text at ${output.path}: read it in pieces with the read tool, or search it with grep.`
268
269
  }
269
- return `The file (${output.contentType || "unknown type"}, ${size}) is saved at ${output.path}: open it with view_file.`
270
+ return `The file (${output.contentType || "unknown type"}, ${size}) is saved at ${output.path}: open it with read.`
270
271
  }
271
272
 
272
273
  function truncatedAnswerNote(output: WebFetchToolOutput): string {