@sixb/agent 0.2.1 → 0.2.3

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 (107) hide show
  1. package/README.md +2 -1
  2. package/dist/agent-prompt.d.ts +13 -0
  3. package/dist/agent-prompt.d.ts.map +1 -1
  4. package/dist/agent-runtime/preflight.d.ts.map +1 -1
  5. package/dist/artifacts/board-previews.d.ts +41 -0
  6. package/dist/artifacts/board-previews.d.ts.map +1 -0
  7. package/dist/artifacts/layout-check/layout-check.d.ts +38 -6
  8. package/dist/artifacts/layout-check/layout-check.d.ts.map +1 -1
  9. package/dist/artifacts/layout-check/overview.d.ts +17 -0
  10. package/dist/artifacts/layout-check/overview.d.ts.map +1 -0
  11. package/dist/artifacts/materialize.d.ts +56 -24
  12. package/dist/artifacts/materialize.d.ts.map +1 -1
  13. package/dist/artifacts/publish-tool.d.ts +35 -9
  14. package/dist/artifacts/publish-tool.d.ts.map +1 -1
  15. package/dist/background-commands.d.ts +95 -0
  16. package/dist/background-commands.d.ts.map +1 -0
  17. package/dist/background-notices.d.ts +31 -0
  18. package/dist/background-notices.d.ts.map +1 -0
  19. package/dist/computer-runner.d.ts +63 -2
  20. package/dist/computer-runner.d.ts.map +1 -1
  21. package/dist/context-compaction.d.ts +3 -0
  22. package/dist/context-compaction.d.ts.map +1 -1
  23. package/dist/execution-plan.d.ts +12 -2
  24. package/dist/execution-plan.d.ts.map +1 -1
  25. package/dist/index.d.ts +3 -1
  26. package/dist/index.d.ts.map +1 -1
  27. package/dist/index.js +11814 -8722
  28. package/dist/index.js.map +35 -23
  29. package/dist/login-shell.d.ts +16 -0
  30. package/dist/login-shell.d.ts.map +1 -0
  31. package/dist/run-child.d.ts +3 -0
  32. package/dist/run-child.d.ts.map +1 -1
  33. package/dist/run-conversation-turn.d.ts +6 -2
  34. package/dist/run-conversation-turn.d.ts.map +1 -1
  35. package/dist/run-environment.d.ts +12 -2
  36. package/dist/run-environment.d.ts.map +1 -1
  37. package/dist/run-sandbox.d.ts +23 -0
  38. package/dist/run-sandbox.d.ts.map +1 -1
  39. package/dist/sandbox-files.d.ts +19 -0
  40. package/dist/sandbox-files.d.ts.map +1 -1
  41. package/dist/subagent-tools.d.ts +3 -1
  42. package/dist/subagent-tools.d.ts.map +1 -1
  43. package/dist/tools/background.d.ts +50 -0
  44. package/dist/tools/background.d.ts.map +1 -0
  45. package/dist/tools/bash.d.ts +12 -4
  46. package/dist/tools/bash.d.ts.map +1 -1
  47. package/dist/tools/model-spec.d.ts +9 -2
  48. package/dist/tools/model-spec.d.ts.map +1 -1
  49. package/dist/tools/tool-files.d.ts.map +1 -1
  50. package/dist/tools/tool-outputs.d.ts +12 -2
  51. package/dist/tools/tool-outputs.d.ts.map +1 -1
  52. package/dist/tools/web-fetch/cache.d.ts +33 -0
  53. package/dist/tools/web-fetch/cache.d.ts.map +1 -0
  54. package/dist/tools/web-fetch/html-markdown.d.ts +25 -0
  55. package/dist/tools/web-fetch/html-markdown.d.ts.map +1 -0
  56. package/dist/tools/web-fetch/network.d.ts +55 -0
  57. package/dist/tools/web-fetch/network.d.ts.map +1 -0
  58. package/dist/tools/web-fetch/tool.d.ts +96 -0
  59. package/dist/tools/web-fetch/tool.d.ts.map +1 -0
  60. package/dist/tools/web-search.d.ts +40 -0
  61. package/dist/tools/web-search.d.ts.map +1 -0
  62. package/dist/types.d.ts +5 -4
  63. package/dist/types.d.ts.map +1 -1
  64. package/dist/workspace-instructions.d.ts +15 -0
  65. package/dist/workspace-instructions.d.ts.map +1 -0
  66. package/package.json +15 -5
  67. package/src/agent-prompt.ts +64 -5
  68. package/src/agent-runtime/preflight.ts +2 -1
  69. package/src/artifacts/board-previews.ts +218 -0
  70. package/src/artifacts/layout-check/check.cjs +304 -80
  71. package/src/artifacts/layout-check/layout-check.ts +123 -13
  72. package/src/artifacts/layout-check/overview.ts +291 -0
  73. package/src/artifacts/materialize.ts +181 -55
  74. package/src/artifacts/publish-tool.ts +459 -129
  75. package/src/background-commands.ts +573 -0
  76. package/src/background-notices.ts +178 -0
  77. package/src/computer-runner.ts +211 -9
  78. package/src/context-compaction.ts +4 -1
  79. package/src/execution-plan.ts +15 -2
  80. package/src/index.ts +4 -0
  81. package/src/login-shell.ts +18 -0
  82. package/src/run-child.ts +5 -0
  83. package/src/run-conversation-turn.ts +23 -4
  84. package/src/run-environment.ts +96 -17
  85. package/src/run-sandbox.ts +41 -0
  86. package/src/sandbox-api-context.ts +1 -1
  87. package/src/sandbox-files.ts +88 -1
  88. package/src/skills/sixb-artifacts/SKILL.md +48 -25
  89. package/src/skills/sixb-artifacts/canvas.md +140 -18
  90. package/src/skills/sixb-artifacts/examples/canvas/onboarding-flow/canvas.json +1 -1
  91. package/src/skills/sixb-artifacts/page.md +1 -1
  92. package/src/skills/sixb-artifacts/references.md +15 -12
  93. package/src/skills/sixb-artifacts/sheet.md +1 -1
  94. package/src/skills/sixb-artifacts/slides.md +1 -1
  95. package/src/subagent-tools.ts +19 -7
  96. package/src/tools/background.ts +127 -0
  97. package/src/tools/bash.ts +80 -11
  98. package/src/tools/model-spec.ts +28 -5
  99. package/src/tools/tool-files.ts +3 -1
  100. package/src/tools/tool-outputs.ts +46 -6
  101. package/src/tools/web-fetch/cache.ts +91 -0
  102. package/src/tools/web-fetch/html-markdown.ts +479 -0
  103. package/src/tools/web-fetch/network.ts +452 -0
  104. package/src/tools/web-fetch/tool.ts +619 -0
  105. package/src/tools/web-search.ts +139 -0
  106. package/src/types.ts +5 -4
  107. package/src/workspace-instructions.ts +163 -0
@@ -0,0 +1,127 @@
1
+ import { AgentToolPublicError } from "@sixb/core"
2
+ import type { JsonObject, JsonValue, ModelTool } from "@sixb/core/models"
3
+ import type { BackgroundCommandOutput, BackgroundCommands } from "../background-commands"
4
+ import { agentToolErrorText } from "../model-adapters"
5
+ import type { AgentSandboxHandle } from "../sandbox-handle"
6
+
7
+ /** The longest `bash_output` waits for a command to end. */
8
+ const MAX_WAIT_MS = 600_000
9
+
10
+ export const BASH_OUTPUT_TOOL_SPEC = {
11
+ name: "bash_output",
12
+ description:
13
+ "A background command's status (running, exited with its code, or stopped) and its output since your last read: the newest 20,000 bytes, the rest in its file. wait blocks until it ends, at most that many ms. You are told when one ends: do not poll.",
14
+ inputSchema: {
15
+ type: "object",
16
+ properties: {
17
+ id: { type: "string", description: "The id bash returned, like bg_3f9a1c." },
18
+ wait: {
19
+ type: "number",
20
+ description: "Milliseconds to wait for its end, up to 600000.",
21
+ },
22
+ },
23
+ required: ["id"],
24
+ additionalProperties: false,
25
+ } satisfies JsonObject,
26
+ } as const
27
+
28
+ export const BASH_STOP_TOOL_SPEC = {
29
+ name: "bash_stop",
30
+ description:
31
+ "Stop a background command and all it started: SIGTERM, then SIGKILL after 3 s. Returns its final status and output since your last read.",
32
+ inputSchema: {
33
+ type: "object",
34
+ properties: {
35
+ id: { type: "string", description: "The id bash returned, like bg_3f9a1c." },
36
+ },
37
+ required: ["id"],
38
+ additionalProperties: false,
39
+ } satisfies JsonObject,
40
+ } as const
41
+
42
+ interface BashOutputToolInput {
43
+ readonly id: string
44
+ readonly wait?: number
45
+ }
46
+
47
+ interface BashStopToolInput {
48
+ readonly id: string
49
+ }
50
+
51
+ /** `bash_output`: a background command's status and new output, after waiting when asked. */
52
+ export function createBashOutputTool(
53
+ resolveSandbox: () => Promise<AgentSandboxHandle>,
54
+ commands: BackgroundCommands
55
+ ): ModelTool<BashOutputToolInput> {
56
+ return {
57
+ ...BASH_OUTPUT_TOOL_SPEC,
58
+ parseInput: (value) => {
59
+ const input = parseInput(BASH_OUTPUT_TOOL_SPEC.name, value, ["id", "wait"])
60
+ if (input.wait !== undefined && (typeof input.wait !== "number" || input.wait < 0)) {
61
+ throw publicError(BASH_OUTPUT_TOOL_SPEC.name, "wait must be a number of milliseconds.")
62
+ }
63
+ return {
64
+ id: input.id as string,
65
+ ...(input.wait === undefined ? {} : { wait: Math.min(input.wait as number, MAX_WAIT_MS) }),
66
+ }
67
+ },
68
+ async execute(input, { signal }): Promise<JsonValue> {
69
+ commands.get(input.id)
70
+ if (input.wait) await commands.wait(input.id, input.wait, signal)
71
+
72
+ const output: BackgroundCommandOutput = await commands.read(
73
+ input.id,
74
+ await resolveSandbox(),
75
+ signal
76
+ )
77
+ return output as unknown as JsonValue
78
+ },
79
+ errorText: agentToolErrorText,
80
+ }
81
+ }
82
+
83
+ /** `bash_stop`: stop a background command, then report how it ended and its last output. */
84
+ export function createBashStopTool(
85
+ resolveSandbox: () => Promise<AgentSandboxHandle>,
86
+ commands: BackgroundCommands
87
+ ): ModelTool<BashStopToolInput> {
88
+ return {
89
+ ...BASH_STOP_TOOL_SPEC,
90
+ parseInput: (value) => ({
91
+ id: parseInput(BASH_STOP_TOOL_SPEC.name, value, ["id"]).id as string,
92
+ }),
93
+ async execute(input, { signal }): Promise<JsonValue> {
94
+ await commands.stop(input.id)
95
+
96
+ const output: BackgroundCommandOutput = await commands.read(
97
+ input.id,
98
+ await resolveSandbox(),
99
+ signal
100
+ )
101
+ return output as unknown as JsonValue
102
+ },
103
+ errorText: agentToolErrorText,
104
+ }
105
+ }
106
+
107
+ function parseInput(
108
+ tool: string,
109
+ value: unknown,
110
+ keys: readonly string[]
111
+ ): Record<string, unknown> & { readonly id: string } {
112
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
113
+ throw publicError(tool, "input must be an object.")
114
+ }
115
+ const input = value as Record<string, unknown>
116
+ for (const key of Object.keys(input)) {
117
+ if (!keys.includes(key)) throw publicError(tool, `input contains unknown property '${key}'.`)
118
+ }
119
+ if (typeof input.id !== "string" || !input.id) {
120
+ throw publicError(tool, "id must be a background command's id, such as bg_3f9a1c.")
121
+ }
122
+ return input as Record<string, unknown> & { readonly id: string }
123
+ }
124
+
125
+ function publicError(tool: string, message: string): AgentToolPublicError {
126
+ return new AgentToolPublicError(`[SixbAgent] ${tool} ${message}`)
127
+ }
package/src/tools/bash.ts CHANGED
@@ -1,14 +1,20 @@
1
- import type { CommandResult } from "@sixb/core"
1
+ import { AgentToolPublicError, type CommandResult } from "@sixb/core"
2
2
  import type { JsonObject, JsonValue, ModelTool } from "@sixb/core/models"
3
+ import type { BackgroundCommandState, BackgroundCommands } from "../background-commands"
4
+ import { loginShellArgs } from "../login-shell"
3
5
  import type { AgentSandboxHandle } from "../sandbox-handle"
4
6
 
5
- const DEFAULT_COMMAND_TIMEOUT_MS = 30_000
6
- const MAX_COMMAND_TIMEOUT_MS = 120_000
7
+ /** Long enough for a build or a test suite; the model asks for more when it expects longer. */
8
+ const DEFAULT_COMMAND_TIMEOUT_MS = 2 * 60_000
9
+ const MAX_COMMAND_TIMEOUT_MS = 10 * 60_000
7
10
  const DEFAULT_MAX_OUTPUT_CHARS = 20_000
8
11
 
9
12
  export const BASH_TOOL_SPEC = {
10
13
  name: "bash",
11
- description: "Run a Bash command in the agent run sandbox.",
14
+ description:
15
+ `Run a Bash command in the agent run sandbox. A command is stopped after ${durationText(DEFAULT_COMMAND_TIMEOUT_MS)} ` +
16
+ `(${DEFAULT_COMMAND_TIMEOUT_MS} ms); pass timeoutMs to give it up to ${durationText(MAX_COMMAND_TIMEOUT_MS)} ` +
17
+ `(${MAX_COMMAND_TIMEOUT_MS} ms). A stopped command returns timedOut: true with what it printed until then.`,
12
18
  inputSchema: {
13
19
  type: "object",
14
20
  properties: {
@@ -18,7 +24,17 @@ export const BASH_TOOL_SPEC = {
18
24
  description:
19
25
  "Directory to run the command in. Defaults to the sandbox workspace. Accepts absolute paths or paths relative to the workspace.",
20
26
  },
21
- timeoutMs: { type: "number" },
27
+ timeoutMs: {
28
+ type: "number",
29
+ description:
30
+ `Milliseconds before the command is stopped. Defaults to ${DEFAULT_COMMAND_TIMEOUT_MS} ` +
31
+ `(${durationText(DEFAULT_COMMAND_TIMEOUT_MS)}); at most ${MAX_COMMAND_TIMEOUT_MS} (${durationText(MAX_COMMAND_TIMEOUT_MS)}).`,
32
+ },
33
+ run_in_background: {
34
+ type: "boolean",
35
+ description:
36
+ "Run it in the background, returning at once with its id and output file: for servers, watchers, long builds. You are told when it ends; read it with bash_output, stop it with bash_stop. No timeout. It ends with the run, a pause for approval too, and its file with it; in the user's folder on their computer it runs until it exits, is stopped, or sixb quits.",
37
+ },
22
38
  },
23
39
  required: ["command"],
24
40
  additionalProperties: false,
@@ -29,6 +45,7 @@ interface BashToolInput {
29
45
  readonly command: string
30
46
  readonly cwd?: string
31
47
  readonly timeoutMs?: number
48
+ readonly run_in_background?: boolean
32
49
  }
33
50
 
34
51
  export interface BashToolOutput extends CommandResult {
@@ -43,30 +60,47 @@ export interface BashToolOutput extends CommandResult {
43
60
  * of blocking the turn. A resolver rejection surfaces as a failed command.
44
61
  *
45
62
  * Its output holds the command's streams whole: the run's tools save an output too large for the
46
- * context to a file and keep {@link keptCommandOutput} of it (see tool-outputs.ts).
63
+ * context to a file and keep {@link keptCommandOutput} of it (see tool-outputs.ts). A command run
64
+ * in the background returns its {@link BackgroundCommandState} instead.
47
65
  */
48
66
  export function createBashTool(
49
- resolveSandbox: () => Promise<AgentSandboxHandle>
67
+ resolveSandbox: () => Promise<AgentSandboxHandle>,
68
+ background: BackgroundCommands
50
69
  ): ModelTool<BashToolInput> {
51
70
  return {
52
71
  ...BASH_TOOL_SPEC,
53
72
  parseInput: parseBashToolInput,
54
73
  async execute(input, { signal }): Promise<JsonValue> {
74
+ if (input.run_in_background) {
75
+ const started: BackgroundCommandState = await background.start({
76
+ handle: await resolveSandbox(),
77
+ command: input.command,
78
+ ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
79
+ signal,
80
+ })
81
+ return started as unknown as JsonValue
82
+ }
83
+
55
84
  const { sandbox, env } = await resolveSandbox()
56
- const result = await sandbox.runCommand("bash", ["-lc", input.command], {
85
+ const timeout = normalizeTimeout(input.timeoutMs)
86
+ const result = await sandbox.runCommand("bash", loginShellArgs(input.command), {
57
87
  cwd: input.cwd,
58
88
  env,
59
- timeout: normalizeTimeout(input.timeoutMs),
89
+ timeout,
60
90
  signal,
61
91
  })
92
+
62
93
  const output: BashToolOutput = {
63
94
  ...result,
95
+ ...(result.timedOut ? { stderr: withTimeoutNotice(result.stderr, timeout) } : {}),
64
96
  stdoutTruncated: false,
65
97
  stderrTruncated: false,
66
98
  }
67
99
  return output as unknown as JsonValue
68
100
  },
69
- errorText: () => "The command failed.",
101
+ // A background start says why it refused, such as too many running already.
102
+ errorText: (error) =>
103
+ error instanceof AgentToolPublicError ? error.message : "The command failed.",
70
104
  }
71
105
  }
72
106
 
@@ -84,8 +118,11 @@ function parseBashToolInput(value: unknown): BashToolInput {
84
118
  if (input.timeoutMs !== undefined && typeof input.timeoutMs !== "number") {
85
119
  throw new TypeError("Bash tool input.timeoutMs must be a number when provided.")
86
120
  }
121
+ if (input.run_in_background !== undefined && typeof input.run_in_background !== "boolean") {
122
+ throw new TypeError("Bash tool input.run_in_background must be a boolean when provided.")
123
+ }
87
124
  for (const key of Object.keys(input)) {
88
- if (key !== "command" && key !== "cwd" && key !== "timeoutMs") {
125
+ if (!BASH_INPUT_KEYS.has(key)) {
89
126
  throw new TypeError(`Bash tool input contains unknown property '${key}'.`)
90
127
  }
91
128
  }
@@ -93,9 +130,17 @@ function parseBashToolInput(value: unknown): BashToolInput {
93
130
  command: input.command,
94
131
  ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
95
132
  ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
133
+ ...(input.run_in_background ? { run_in_background: true } : {}),
96
134
  }
97
135
  }
98
136
 
137
+ const BASH_INPUT_KEYS: ReadonlySet<string> = new Set([
138
+ "command",
139
+ "cwd",
140
+ "timeoutMs",
141
+ "run_in_background",
142
+ ])
143
+
99
144
  function normalizeTimeout(timeoutMs: number | undefined): number {
100
145
  if (timeoutMs === undefined || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
101
146
  return DEFAULT_COMMAND_TIMEOUT_MS
@@ -103,6 +148,30 @@ function normalizeTimeout(timeoutMs: number | undefined): number {
103
148
  return Math.min(Math.floor(timeoutMs), MAX_COMMAND_TIMEOUT_MS)
104
149
  }
105
150
 
151
+ /**
152
+ * Say why a command ended without its verdict, last, where the tail of a truncated stream keeps it:
153
+ * the result's `timedOut` alone does not tell the model how long it had or that it can ask for more.
154
+ */
155
+ function withTimeoutNotice(stderr: string, timeoutMs: number): string {
156
+ const limit = durationText(timeoutMs)
157
+ const more =
158
+ timeoutMs < MAX_COMMAND_TIMEOUT_MS
159
+ ? ` Pass a larger timeoutMs, up to ${MAX_COMMAND_TIMEOUT_MS}, to give it longer.`
160
+ : " That is the most a command can have: split the work or make it faster."
161
+ const notice = `[SixbAgent] The command was stopped after ${limit}, its timeout.${more}`
162
+
163
+ return stderr === "" || stderr.endsWith("\n") ? `${stderr}${notice}` : `${stderr}\n${notice}`
164
+ }
165
+
166
+ /** `2 minutes`, or `90 seconds` when it is not a whole number of minutes. */
167
+ function durationText(ms: number): string {
168
+ return ms % 60_000 === 0 ? plural(ms / 60_000, "minute") : plural(ms / 1000, "second")
169
+ }
170
+
171
+ function plural(count: number, unit: string): string {
172
+ return `${count} ${unit}${count === 1 ? "" : "s"}`
173
+ }
174
+
106
175
  /**
107
176
  * What a command's message part keeps of an output saved to a file: each stream within
108
177
  * 20,000 characters, as the app, the TUI and `sixb history` show it.
@@ -1,27 +1,50 @@
1
- import type { AgentToolSpec } from "@sixb/core/internal/agents"
1
+ import type { AgentRunWebPlan, AgentToolSpec } from "@sixb/core/internal/agents"
2
+ import type { SandboxNetworkPolicy } from "@sixb/core/sandboxes"
2
3
  import {
4
+ OPEN_ARTIFACT_TOOL_SPEC,
3
5
  PUBLISH_ARTIFACT_TOOL_SPEC,
4
- PUBLISH_ARTIFACT_VERSION_TOOL_SPEC,
6
+ UPDATE_ARTIFACT_TOOL_SPEC,
5
7
  } from "../artifacts/publish-tool"
8
+ import { BASH_OUTPUT_TOOL_SPEC, BASH_STOP_TOOL_SPEC } from "./background"
6
9
  import { BASH_TOOL_SPEC } from "./bash"
7
10
  import { READ_TOOL_SPEC } from "./read"
8
11
  import { VIEW_FILE_TOOL_SPEC } from "./view-file"
12
+ import { WEB_FETCH_TOOL_SPEC } from "./web-fetch/tool"
13
+ import { WEB_SEARCH_TOOL_SPEC } from "./web-search"
9
14
 
10
15
  /**
11
16
  * Describe exactly the tools a conversational model receives, in its order, without starting its
12
- * sandbox. A conversation publishes artifacts once its run executes in a thread.
17
+ * sandbox. A conversation publishes artifacts once its run executes in a thread; it searches the
18
+ * web when its plan names a search model, and fetches pages when its plan has web tools at all,
19
+ * unless its sandbox's network is `none`.
13
20
  */
14
21
  export function agentModelToolSpecs(
15
22
  projectTools: readonly AgentToolSpec[],
16
- options: { readonly publishes?: boolean } = {}
23
+ options: {
24
+ readonly publishes?: boolean
25
+ readonly web?: AgentRunWebPlan
26
+ readonly networkPolicy?: SandboxNetworkPolicy
27
+ } = {}
17
28
  ): readonly AgentToolSpec[] {
18
29
  return [
19
30
  ...projectTools,
20
31
  VIEW_FILE_TOOL_SPEC,
21
32
  READ_TOOL_SPEC,
22
33
  BASH_TOOL_SPEC,
34
+ BASH_OUTPUT_TOOL_SPEC,
35
+ BASH_STOP_TOOL_SPEC,
36
+ ...(options.web?.search ? [WEB_SEARCH_TOOL_SPEC] : []),
37
+ ...(fetchesWeb(options.web, options.networkPolicy) ? [WEB_FETCH_TOOL_SPEC] : []),
23
38
  ...(options.publishes === false
24
39
  ? []
25
- : [PUBLISH_ARTIFACT_TOOL_SPEC, PUBLISH_ARTIFACT_VERSION_TOOL_SPEC]),
40
+ : [PUBLISH_ARTIFACT_TOOL_SPEC, UPDATE_ARTIFACT_TOOL_SPEC, OPEN_ARTIFACT_TOOL_SPEC]),
26
41
  ]
27
42
  }
43
+
44
+ /** Whether a run has `web_fetch`: web tools are on, and its sandbox may reach the network. */
45
+ export function fetchesWeb(
46
+ web: AgentRunWebPlan | undefined,
47
+ networkPolicy: SandboxNetworkPolicy | undefined
48
+ ): boolean {
49
+ return web !== undefined && networkPolicy?.mode !== "none"
50
+ }
@@ -1,6 +1,7 @@
1
1
  import { posix } from "node:path"
2
2
  import type { AgentToolFile, AgentToolFilePutInput, AgentToolFiles } from "@sixb/core"
3
3
  import { AgentToolPublicError } from "@sixb/core"
4
+ import { ARTIFACT_LIMITS } from "@sixb/core/artifacts"
4
5
  import {
5
6
  AGENT_FILE_MAX_BYTES,
6
7
  type AgentRunFileStore,
@@ -10,7 +11,8 @@ import {
10
11
  import type { AgentSandboxHandle } from "../sandbox-handle"
11
12
 
12
13
  export { AGENT_FILE_MAX_BYTES }
13
- const DEFAULT_RUN_MAX_BYTES = 100 * 1024 * 1024
14
+ /** What a run stores in all: at least an artifact's version as large as one may be. */
15
+ const DEFAULT_RUN_MAX_BYTES = ARTIFACT_LIMITS.maxVersionBytes
14
16
 
15
17
  interface CreateAgentToolFilesInput {
16
18
  readonly toolName: string
@@ -6,6 +6,7 @@ import {
6
6
  AGENT_TOOL_OUTPUTS_DIRECTORY,
7
7
  type AgentRunFileStore,
8
8
  type AgentToolCallFile,
9
+ type AgentToolOutputExtension,
9
10
  agentToolOutputPath,
10
11
  isAgentToolOutputFile,
11
12
  isAgentToolResult,
@@ -24,6 +25,7 @@ import { BASH_TOOL_SPEC, keptCommandOutput } from "./bash"
24
25
  import { READ_TOOL_SPEC } from "./read"
25
26
  import { AgentFileBudget } from "./tool-files"
26
27
  import { VIEW_FILE_TOOL_SPEC } from "./view-file"
28
+ import { WEB_FETCH_TOOL_SPEC } from "./web-fetch/tool"
27
29
 
28
30
  /**
29
31
  * Past this, a tool's output reaches the model as a preview, and the whole of it as a file in the
@@ -62,8 +64,15 @@ const RESTORED_OUTPUTS_CONCURRENCY = 4
62
64
  const LISTED_OUTPUTS_MAX_FILES = 1_000
63
65
  const LIST_TIMEOUT_MS = 30_000
64
66
 
65
- /** The readers: they page through files themselves, so their output is never saved to another. */
66
- const FILE_READERS: ReadonlySet<string> = new Set([READ_TOOL_SPEC.name, VIEW_FILE_TOOL_SPEC.name])
67
+ /**
68
+ * Never saved here: the readers page through files themselves, and `web_fetch` saves its page
69
+ * itself ({@link ToolOutputFiles.store}).
70
+ */
71
+ const UNSAVED_TOOLS: ReadonlySet<string> = new Set([
72
+ READ_TOOL_SPEC.name,
73
+ VIEW_FILE_TOOL_SPEC.name,
74
+ WEB_FETCH_TOOL_SPEC.name,
75
+ ])
67
76
 
68
77
  const NOTICE_TAG = "tool_output_file"
69
78
  const NOTICE_OPENING = new RegExp(`^<${NOTICE_TAG} sandboxPath="([^"]*)"`)
@@ -98,7 +107,7 @@ export class ToolOutputFiles {
98
107
  }
99
108
 
100
109
  wrap(tools: readonly ModelTool[]): ModelTool[] {
101
- return tools.map((tool) => (FILE_READERS.has(tool.name) ? tool : this.saving(tool)))
110
+ return tools.map((tool) => (UNSAVED_TOOLS.has(tool.name) ? tool : this.saving(tool)))
102
111
  }
103
112
 
104
113
  /** The stored file of a call whose output was saved, for its message part. */
@@ -149,12 +158,43 @@ export class ToolOutputFiles {
149
158
  }
150
159
  }
151
160
 
161
+ /**
162
+ * Save a call's output that its tool shows the model itself, such as a fetched page: stored and
163
+ * written back as an output saved here is, under the same budget, and its call's
164
+ * {@link fileOf}. Returns the path the agent reads it at.
165
+ */
166
+ async store(
167
+ toolName: string,
168
+ bytes: Uint8Array,
169
+ type: { readonly extension: AgentToolOutputExtension; readonly mediaType: string },
170
+ context: ModelToolExecutionContext
171
+ ): Promise<string> {
172
+ const saved = await this.write(toolName, bytes, type, context)
173
+ this.#saved.set(context.toolCallId, saved)
174
+ return saved.sandboxPath
175
+ }
176
+
152
177
  private async save(
153
178
  toolName: string,
154
179
  contents: string,
155
180
  context: ModelToolExecutionContext
156
181
  ): Promise<SavedCall> {
157
182
  const bytes = new TextEncoder().encode(contents)
183
+ const saved = await this.write(
184
+ toolName,
185
+ bytes,
186
+ { extension: "txt", mediaType: "text/plain" },
187
+ context
188
+ )
189
+ return { ...saved, contents }
190
+ }
191
+
192
+ private async write(
193
+ toolName: string,
194
+ bytes: Uint8Array,
195
+ type: { readonly extension: AgentToolOutputExtension; readonly mediaType: string },
196
+ context: ModelToolExecutionContext
197
+ ): Promise<SavedCall> {
158
198
  if (bytes.byteLength > AGENT_FILE_MAX_BYTES) {
159
199
  throw new Error(`the output exceeds the ${AGENT_FILE_MAX_BYTES}-byte file limit`)
160
200
  }
@@ -162,13 +202,13 @@ export class ToolOutputFiles {
162
202
  this.#budget.holdContent(`sha256:${sha256}`, bytes.byteLength, toolName)
163
203
 
164
204
  try {
165
- const path = agentToolOutputPath(context.toolCallId, sha256)
205
+ const path = agentToolOutputPath(context.toolCallId, sha256, type.extension)
166
206
  const fileRef = await this.input.blobStorage.put({
167
207
  body: bytes,
168
208
  expectedSizeBytes: bytes.byteLength,
169
209
  signal: context.signal,
170
210
  fileName: posix.basename(path),
171
- mediaType: "text/plain",
211
+ mediaType: type.mediaType,
172
212
  })
173
213
 
174
214
  const handle = await this.input.sandbox()
@@ -177,7 +217,7 @@ export class ToolOutputFiles {
177
217
  await handle.sandbox.writeFiles([
178
218
  { path: posix.resolve(handle.sandbox.workingDirectory, sandboxPath), contents: bytes },
179
219
  ])
180
- return { file: { fileRef, path }, sandboxPath, contents }
220
+ return { file: { fileRef, path }, sandboxPath }
181
221
  } catch (error) {
182
222
  this.#budget.releaseContent(`sha256:${sha256}`)
183
223
  throw error
@@ -0,0 +1,91 @@
1
+ /** A page as `web_fetch` read it: what it saves, never what a question made of it. */
2
+ export interface CachedWebPage {
3
+ /** The final URL, after the same-host redirects that were followed. */
4
+ readonly url: string
5
+ readonly title: string
6
+ readonly status: number
7
+ /** The media type the server sent, lowercased, or empty when it sent none. */
8
+ readonly contentType: string
9
+ /** The page as it is saved: markdown or text, or a PDF or image as it came. */
10
+ readonly body: Uint8Array
11
+ readonly kind: WebPageKind
12
+ /** How many bytes the server sent, up to the fetch cap. */
13
+ readonly size: number
14
+ /** The body stopped at the fetch cap, or an HTML page was converted only up to its own. */
15
+ readonly truncated: boolean
16
+ }
17
+
18
+ /** What a saved page is, by its file's extension and media type. */
19
+ export interface WebPageKind {
20
+ readonly extension: "md" | "txt" | "pdf" | "png" | "jpg" | "gif" | "webp"
21
+ readonly mediaType: string
22
+ }
23
+
24
+ const MAX_BYTES = 64 * 1024 * 1024
25
+ const TTL_MS = 15 * 60_000
26
+
27
+ /** What an entry weighs beyond its body: its strings, roughly. */
28
+ const ENTRY_OVERHEAD_BYTES = 1_024
29
+
30
+ interface Entry {
31
+ readonly page: CachedWebPage
32
+ readonly bytes: number
33
+ readonly expiresAt: number
34
+ }
35
+
36
+ /**
37
+ * The pages a runner process fetched in the last 15 minutes, by URL, up to 64 MB: a run that
38
+ * reads a page again, or another run that reads it, does not fetch it again. Least recently used
39
+ * pages go first.
40
+ */
41
+ export class WebFetchCache {
42
+ readonly #entries = new Map<string, Entry>()
43
+ #bytes = 0
44
+
45
+ get(url: URL): CachedWebPage | undefined {
46
+ const key = cacheKey(url)
47
+ const entry = this.#entries.get(key)
48
+ if (!entry) return undefined
49
+
50
+ this.#entries.delete(key)
51
+ if (entry.expiresAt <= Date.now()) {
52
+ this.#bytes -= entry.bytes
53
+ return undefined
54
+ }
55
+
56
+ // Read last, so it goes last.
57
+ this.#entries.set(key, entry)
58
+ return entry.page
59
+ }
60
+
61
+ set(url: URL, page: CachedWebPage): void {
62
+ const key = cacheKey(url)
63
+ const bytes = page.body.byteLength + page.url.length + page.title.length + ENTRY_OVERHEAD_BYTES
64
+
65
+ this.delete(key)
66
+ if (bytes > MAX_BYTES) return
67
+
68
+ this.#entries.set(key, { page, bytes, expiresAt: Date.now() + TTL_MS })
69
+ this.#bytes += bytes
70
+
71
+ for (const [oldest] of this.#entries) {
72
+ if (this.#bytes <= MAX_BYTES) break
73
+ this.delete(oldest)
74
+ }
75
+ }
76
+
77
+ private delete(key: string): void {
78
+ const entry = this.#entries.get(key)
79
+ if (!entry) return
80
+
81
+ this.#entries.delete(key)
82
+ this.#bytes -= entry.bytes
83
+ }
84
+ }
85
+
86
+ /** The URL as a server reads it: without its fragment. The URL parser already lowercases the host. */
87
+ function cacheKey(url: URL): string {
88
+ const key = new URL(url.href)
89
+ key.hash = ""
90
+ return key.href
91
+ }