@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,190 @@
1
+ import type { JsonObject, JsonValue, ModelTool } from "@sixb/core/models"
2
+ import { agentToolErrorText } from "../model-adapters"
3
+ import type { AgentSandboxHandle } from "../sandbox-handle"
4
+ import { objectInput } from "./edit"
5
+ import { publicError } from "./file-writes"
6
+ import {
7
+ INCOMPLETE_SEARCH_FOOTER,
8
+ isLeftOut,
9
+ isRecord,
10
+ optionalPathInput,
11
+ runSandboxSearch,
12
+ searchUnavailable,
13
+ } from "./sandbox-search"
14
+ import type { GrepMatch, GrepSearchResult } from "./search/request"
15
+
16
+ export const GREP_TOOL_SPEC = {
17
+ name: "grep",
18
+ strict: true,
19
+ description:
20
+ "Search file contents with a JavaScript regular expression, or with literal text. Case is ignored unless the pattern has an uppercase letter. Searches hidden files, and skips .git, node_modules, what .gitignore excludes, binary files and files over 10 MiB. Matches the first 4,000 characters of a line. Returns matching lines grouped by file, at most 100 in all and 20 per file, with line numbers that read takes as its offset. Prefer this over bash to search text.",
21
+ inputSchema: {
22
+ type: "object",
23
+ properties: {
24
+ pattern: {
25
+ type: "string",
26
+ description: "Regular expression, or the text itself with literal.",
27
+ },
28
+ path: {
29
+ type: "string",
30
+ description:
31
+ "File or folder to search: relative to the working directory, or an absolute path in the run's context directory. Default: the working directory.",
32
+ },
33
+ include: {
34
+ type: "string",
35
+ description: "Glob pattern the files must match, such as *.ts or *.{ts,tsx}.",
36
+ },
37
+ literal: {
38
+ type: "boolean",
39
+ description: "Search the pattern as written, not as a regular expression. Default: false.",
40
+ },
41
+ },
42
+ required: ["pattern"],
43
+ additionalProperties: false,
44
+ } satisfies JsonObject,
45
+ } as const
46
+
47
+ export interface GrepToolInput {
48
+ readonly pattern: string
49
+ readonly path?: string
50
+ readonly include?: string
51
+ readonly literal?: boolean
52
+ }
53
+
54
+ export interface GrepToolOutput {
55
+ readonly pattern: string
56
+ /** As the call named it; `.` for the working directory. */
57
+ readonly path: string
58
+ /** Paths relative to the working directory when under it, absolute otherwise. */
59
+ readonly matches: readonly GrepMatch[]
60
+ /** How many files the matches are in. */
61
+ readonly files: number
62
+ /** Matching lines past the 20 a file shows, by path. */
63
+ readonly more?: Readonly<Record<string, number>>
64
+ /** Another file matches past the 100 lines shown. */
65
+ readonly truncated: boolean
66
+ /** The search stopped at its deadline. */
67
+ readonly incomplete?: true
68
+ }
69
+
70
+ export function createGrepTool(
71
+ resolveSandbox: () => Promise<AgentSandboxHandle>
72
+ ): ModelTool<GrepToolInput> {
73
+ return {
74
+ ...GREP_TOOL_SPEC,
75
+ parseInput: parseGrepInput,
76
+ async execute(input, { signal }): Promise<JsonValue> {
77
+ const handle = await resolveSandbox()
78
+ const result = await runSandboxSearch(handle, { tool: "grep", ...input }, signal)
79
+ if (!isGrepResult(result)) {
80
+ throw searchUnavailable(
81
+ "grep",
82
+ "its output could not be read",
83
+ new Error("Invalid sandbox output.")
84
+ )
85
+ }
86
+
87
+ return {
88
+ pattern: input.pattern,
89
+ path: input.path ?? ".",
90
+ matches: result.matches.map(({ path, line, text }) => ({ path, line, text })),
91
+ files: result.files,
92
+ ...(result.more ? { more: result.more } : {}),
93
+ truncated: result.truncated,
94
+ ...(result.incomplete ? { incomplete: true } : {}),
95
+ } satisfies GrepToolOutput
96
+ },
97
+ toModelOutput(output) {
98
+ return { type: "text", value: grepModelText(output as unknown as GrepToolOutput) }
99
+ },
100
+ errorText: agentToolErrorText,
101
+ }
102
+ }
103
+
104
+ /**
105
+ * Matches grouped by file, each line with its number, then how many more the file holds:
106
+ *
107
+ * ```
108
+ * src/config.ts
109
+ * 12: const retries = 3
110
+ * … 7 more in this file
111
+ * ```
112
+ */
113
+ export function grepModelText(output: GrepToolOutput): string {
114
+ const groups: string[] = []
115
+ let group: string[] = []
116
+ let path: string | undefined
117
+
118
+ const close = () => {
119
+ if (path === undefined) return
120
+ const more = output.more?.[path]
121
+ if (more) group.push(` … ${more} more in this file`)
122
+ groups.push(group.join("\n"))
123
+ }
124
+
125
+ for (const match of output.matches) {
126
+ if (match.path !== path) {
127
+ close()
128
+ path = match.path
129
+ group = [match.path]
130
+ }
131
+ group.push(` ${match.line}: ${match.text}`)
132
+ }
133
+ close()
134
+
135
+ const footers = [
136
+ ...(output.truncated
137
+ ? [
138
+ `(${output.matches.length} matching lines shown, more match: narrow the pattern, the path or include)`,
139
+ ]
140
+ : []),
141
+ ...(output.incomplete ? [INCOMPLETE_SEARCH_FOOTER] : []),
142
+ ]
143
+ return [groups.length > 0 ? groups.join("\n\n") : "No matches", ...footers].join("\n\n")
144
+ }
145
+
146
+ function parseGrepInput(value: unknown): GrepToolInput {
147
+ const input = objectInput(value, "grep", ["pattern", "path", "include", "literal"])
148
+ if (typeof input.pattern !== "string" || input.pattern === "") {
149
+ throw publicError("grep", "pattern must be a non-empty pattern.")
150
+ }
151
+ if (input.literal !== undefined && input.literal !== null && typeof input.literal !== "boolean") {
152
+ throw publicError("grep", "literal must be true or false.")
153
+ }
154
+
155
+ const path = optionalPathInput(input.path, "grep")
156
+ const include = isLeftOut(input.include) ? undefined : input.include
157
+ if (include !== undefined && typeof include !== "string") {
158
+ throw publicError("grep", "include must be a glob pattern.")
159
+ }
160
+
161
+ return {
162
+ pattern: input.pattern,
163
+ ...(path === undefined ? {} : { path }),
164
+ ...(include === undefined ? {} : { include }),
165
+ ...(input.literal === true ? { literal: true } : {}),
166
+ }
167
+ }
168
+
169
+ function isGrepResult(value: unknown): value is GrepSearchResult {
170
+ return (
171
+ isRecord(value) &&
172
+ Array.isArray(value.matches) &&
173
+ value.matches.every(isGrepMatch) &&
174
+ typeof value.files === "number" &&
175
+ (value.more === undefined ||
176
+ (isRecord(value.more) &&
177
+ Object.values(value.more).every((count) => typeof count === "number"))) &&
178
+ typeof value.truncated === "boolean" &&
179
+ (value.incomplete === undefined || value.incomplete === true)
180
+ )
181
+ }
182
+
183
+ function isGrepMatch(value: unknown): value is GrepMatch {
184
+ return (
185
+ isRecord(value) &&
186
+ typeof value.path === "string" &&
187
+ typeof value.line === "number" &&
188
+ typeof value.text === "string"
189
+ )
190
+ }
@@ -1,16 +1,15 @@
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"
7
+ import { GLOB_TOOL_SPEC } from "./glob"
8
+ import { GREP_TOOL_SPEC } from "./grep"
10
9
  import { READ_TOOL_SPEC } from "./read"
11
- import { VIEW_FILE_TOOL_SPEC } from "./view-file"
12
10
  import { WEB_FETCH_TOOL_SPEC } from "./web-fetch/tool"
13
11
  import { WEB_SEARCH_TOOL_SPEC } from "./web-search"
12
+ import { WRITE_TOOL_SPEC } from "./write"
14
13
 
15
14
  /**
16
15
  * Describe exactly the tools a conversational model receives, in its order, without starting its
@@ -28,16 +27,17 @@ export function agentModelToolSpecs(
28
27
  ): readonly AgentToolSpec[] {
29
28
  return [
30
29
  ...projectTools,
31
- VIEW_FILE_TOOL_SPEC,
32
30
  READ_TOOL_SPEC,
31
+ EDIT_TOOL_SPEC,
32
+ WRITE_TOOL_SPEC,
33
+ GLOB_TOOL_SPEC,
34
+ GREP_TOOL_SPEC,
33
35
  BASH_TOOL_SPEC,
34
- BASH_OUTPUT_TOOL_SPEC,
35
- BASH_STOP_TOOL_SPEC,
36
+ WAIT_TOOL_SPEC,
37
+ STOP_TOOL_SPEC,
36
38
  ...(options.web?.search ? [WEB_SEARCH_TOOL_SPEC] : []),
37
39
  ...(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]),
40
+ ...(options.publishes === false ? [] : [PUBLISH_ARTIFACT_TOOL_SPEC, OPEN_ARTIFACT_TOOL_SPEC]),
41
41
  ]
42
42
  }
43
43
 
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
  }
@@ -0,0 +1,219 @@
1
+ import { AgentToolPublicError, type CommandResult } from "@sixb/core"
2
+ import { AgentToolExecutionError } from "../errors"
3
+ import { type AgentSandboxHandle, contextPath } from "../sandbox-handle"
4
+ import { pathInput } from "./edit"
5
+ import { publicError } from "./file-writes"
6
+ import type { GlobSearchRequest, GrepSearchRequest, SearchErrorCode } from "./search/request"
7
+
8
+ /** How long a search walks before it returns what it found, marked incomplete. */
9
+ const SEARCH_DEADLINE_MS = 20_000
10
+ /** The walk's deadline, plus the time to start the script. */
11
+ const COMMAND_TIMEOUT_MS = 30_000
12
+
13
+ type SearchTool = "glob" | "grep"
14
+
15
+ type SandboxSearchRequest =
16
+ | Omit<GlobSearchRequest, "contextDirectory" | "timeoutMs">
17
+ | Omit<GrepSearchRequest, "contextDirectory" | "timeoutMs">
18
+
19
+ /**
20
+ * Search with the run's `lib/search.mjs`, the same in every sandbox and on a computer. The script
21
+ * confines the search to the working directory and the context directory, as `read` does, and
22
+ * prints one JSON line. Returns that result, unchecked.
23
+ *
24
+ * A search that ran too long, or a script that could not search, is the model's to know: it can
25
+ * narrow the search, or fall back to bash.
26
+ */
27
+ export async function runSandboxSearch(
28
+ handle: AgentSandboxHandle,
29
+ request: SandboxSearchRequest,
30
+ signal: AbortSignal
31
+ ): Promise<unknown> {
32
+ const tool = request.tool
33
+ const body = JSON.stringify({
34
+ ...request,
35
+ contextDirectory: contextPath(handle),
36
+ timeoutMs: SEARCH_DEADLINE_MS,
37
+ })
38
+
39
+ let result: CommandResult
40
+ try {
41
+ result = await handle.sandbox.runCommand(
42
+ "bash",
43
+ ["-c", RUN_SEARCH, `sixb-${tool}`, contextPath(handle, "lib", "search.mjs"), body],
44
+ {
45
+ cwd: handle.sandbox.workingDirectory,
46
+ env: handle.env ?? {},
47
+ timeout: COMMAND_TIMEOUT_MS,
48
+ signal,
49
+ }
50
+ )
51
+ } catch (error) {
52
+ signal.throwIfAborted()
53
+ throw new AgentToolExecutionError(tool, { cause: error })
54
+ }
55
+ signal.throwIfAborted()
56
+
57
+ const cause = new Error(result.stderr.trim() || `search.mjs exited with code ${result.exitCode}.`)
58
+
59
+ if (result.timedOut) {
60
+ throw new AgentToolPublicError(
61
+ `[SixbAgent] ${tool}: The search took too long: ${
62
+ tool === "grep"
63
+ ? "narrow the path, simplify the pattern, or pass literal: true."
64
+ : "narrow the path or the pattern."
65
+ }`,
66
+ { cause }
67
+ )
68
+ }
69
+
70
+ if (result.exitCode === 0) {
71
+ const output = lastJsonLine(result.stdout)
72
+ if (output !== undefined) return output
73
+ throw searchUnavailable(tool, "its output could not be read", cause)
74
+ }
75
+
76
+ const failure = scriptFailure(lastJsonLine(result.stderr))
77
+ if (result.exitCode === 2 && failure && isSearchErrorCode(failure.code)) {
78
+ throw searchError(tool, request.path ?? ".", failure.code, failure.message)
79
+ }
80
+ throw searchUnavailable(tool, unavailableReason(result.exitCode, failure), cause)
81
+ }
82
+
83
+ /**
84
+ * A search the run's script could not make: the model reads why, in words of ours rather than the
85
+ * sandbox's, and the way out. The script's own words stay in the cause.
86
+ */
87
+ export function searchUnavailable(
88
+ tool: SearchTool,
89
+ reason: string,
90
+ cause: unknown
91
+ ): AgentToolPublicError {
92
+ return new AgentToolPublicError(
93
+ `[SixbAgent] ${tool}: The search could not run in this sandbox (${reason}): use bash with find and grep instead.`,
94
+ { cause }
95
+ )
96
+ }
97
+
98
+ function unavailableReason(
99
+ exitCode: number,
100
+ failure: { readonly code: string; readonly message: string } | undefined
101
+ ): string {
102
+ if (failure?.code === "runtime_unavailable") return "the search script needs Bun or Node.js"
103
+ if (failure?.code === "script_missing") return "the run has no search script"
104
+ return `the search script exited with code ${exitCode}`
105
+ }
106
+
107
+ /** An optional value left out: models send `"null"` or `"undefined"` for one. */
108
+ export function isLeftOut(value: unknown): boolean {
109
+ return (
110
+ value === undefined ||
111
+ value === null ||
112
+ value === "" ||
113
+ value === "null" ||
114
+ value === "undefined"
115
+ )
116
+ }
117
+
118
+ export function optionalPathInput(value: unknown, tool: SearchTool): string | undefined {
119
+ return isLeftOut(value) ? undefined : pathInput(value, tool)
120
+ }
121
+
122
+ export const INCOMPLETE_SEARCH_FOOTER =
123
+ "(The search stopped after 20 seconds, before it looked everywhere: narrow the pattern or the path)"
124
+
125
+ function searchError(tool: SearchTool, path: string, code: SearchErrorCode, reason: string): Error {
126
+ switch (code) {
127
+ case "path_missing":
128
+ return publicError(tool, `'${path}' does not exist.`)
129
+ case "path_outside":
130
+ return publicError(
131
+ tool,
132
+ `'${path}' resolves outside the working directory and the run's context directory.`
133
+ )
134
+ case "path_is_file":
135
+ return publicError(tool, `'${path}' is a file: read it, or grep it.`)
136
+ case "path_not_searchable":
137
+ return publicError(tool, `'${path}' is not a file or a directory.`)
138
+ case "invalid_pattern":
139
+ return publicError(
140
+ tool,
141
+ tool === "grep"
142
+ ? `Invalid pattern: ${reason}. Pass literal: true to search the text as written.`
143
+ : `Invalid pattern: ${reason}.`
144
+ )
145
+ case "invalid_include":
146
+ return publicError(tool, `Invalid include: ${reason}.`)
147
+ case "file_binary":
148
+ return publicError(tool, `'${path}' is binary, or not UTF-8 text: ${tool} searches text.`)
149
+ case "file_too_large":
150
+ return publicError(tool, `'${path}' is over 10 MiB: search it with bash.`)
151
+ }
152
+ }
153
+
154
+ const SEARCH_ERROR_CODES: readonly SearchErrorCode[] = [
155
+ "path_missing",
156
+ "path_outside",
157
+ "path_is_file",
158
+ "path_not_searchable",
159
+ "invalid_pattern",
160
+ "invalid_include",
161
+ "file_binary",
162
+ "file_too_large",
163
+ ]
164
+
165
+ function isSearchErrorCode(value: unknown): value is SearchErrorCode {
166
+ return SEARCH_ERROR_CODES.some((code) => code === value)
167
+ }
168
+
169
+ /** The script's `{ error: { code, message } }`. */
170
+ function scriptFailure(
171
+ value: unknown
172
+ ): { readonly code: string; readonly message: string } | undefined {
173
+ const error = isRecord(value) ? value.error : undefined
174
+ if (!isRecord(error) || typeof error.code !== "string" || typeof error.message !== "string") {
175
+ return undefined
176
+ }
177
+ return { code: error.code, message: error.message }
178
+ }
179
+
180
+ /**
181
+ * The last line that parses as JSON: in the login-shell fallback, a profile may print before the
182
+ * script does.
183
+ */
184
+ function lastJsonLine(text: string): unknown {
185
+ const lines = text.split("\n").filter((line) => line.trim() !== "")
186
+ const last = lines.at(-1)
187
+ if (last === undefined) return undefined
188
+
189
+ try {
190
+ return JSON.parse(last)
191
+ } catch {
192
+ return undefined
193
+ }
194
+ }
195
+
196
+ export function isRecord(value: unknown): value is Record<string, unknown> {
197
+ return typeof value === "object" && value !== null && !Array.isArray(value)
198
+ }
199
+
200
+ /**
201
+ * Runs the script at its absolute path on Bun, or else Node. Preflight found one of them in a
202
+ * login shell: when this shell's PATH has neither, the search runs in one, as `exec` so no logout
203
+ * script runs. A missing script, or a login shell with neither, prints an error as the script
204
+ * does.
205
+ *
206
+ * Arguments: the script's path, the request.
207
+ */
208
+ const RUN_SEARCH = `set -u
209
+ if [ ! -r "$1" ]; then
210
+ echo '{"error":{"code":"script_missing","message":"The search script is missing."}}' >&2
211
+ exit 2
212
+ fi
213
+ command -v bun >/dev/null 2>&1 && exec bun "$1" "$2"
214
+ command -v node >/dev/null 2>&1 && exec node "$1" "$2"
215
+ exec "$BASH" -lc '
216
+ command -v bun >/dev/null 2>&1 && exec bun "$0" "$1"
217
+ command -v node >/dev/null 2>&1 && exec node "$0" "$1"
218
+ echo "{\\"error\\":{\\"code\\":\\"runtime_unavailable\\",\\"message\\":\\"The search needs Bun or Node.js.\\"}}" >&2
219
+ exit 2' "$1" "$2"`