@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.
- package/README.md +2 -1
- package/dist/agent-prompt.d.ts +13 -0
- package/dist/agent-prompt.d.ts.map +1 -1
- package/dist/agent-runtime/preflight.d.ts.map +1 -1
- package/dist/artifacts/board-previews.d.ts +41 -0
- package/dist/artifacts/board-previews.d.ts.map +1 -0
- package/dist/artifacts/layout-check/layout-check.d.ts +38 -6
- package/dist/artifacts/layout-check/layout-check.d.ts.map +1 -1
- package/dist/artifacts/layout-check/overview.d.ts +17 -0
- package/dist/artifacts/layout-check/overview.d.ts.map +1 -0
- package/dist/artifacts/materialize.d.ts +56 -24
- package/dist/artifacts/materialize.d.ts.map +1 -1
- package/dist/artifacts/publish-tool.d.ts +35 -9
- package/dist/artifacts/publish-tool.d.ts.map +1 -1
- package/dist/background-commands.d.ts +95 -0
- package/dist/background-commands.d.ts.map +1 -0
- package/dist/background-notices.d.ts +31 -0
- package/dist/background-notices.d.ts.map +1 -0
- package/dist/computer-runner.d.ts +63 -2
- package/dist/computer-runner.d.ts.map +1 -1
- package/dist/context-compaction.d.ts +3 -0
- package/dist/context-compaction.d.ts.map +1 -1
- package/dist/execution-plan.d.ts +12 -2
- package/dist/execution-plan.d.ts.map +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +11814 -8722
- package/dist/index.js.map +35 -23
- package/dist/login-shell.d.ts +16 -0
- package/dist/login-shell.d.ts.map +1 -0
- package/dist/run-child.d.ts +3 -0
- package/dist/run-child.d.ts.map +1 -1
- package/dist/run-conversation-turn.d.ts +6 -2
- package/dist/run-conversation-turn.d.ts.map +1 -1
- package/dist/run-environment.d.ts +12 -2
- package/dist/run-environment.d.ts.map +1 -1
- package/dist/run-sandbox.d.ts +23 -0
- package/dist/run-sandbox.d.ts.map +1 -1
- package/dist/sandbox-files.d.ts +19 -0
- package/dist/sandbox-files.d.ts.map +1 -1
- package/dist/subagent-tools.d.ts +3 -1
- package/dist/subagent-tools.d.ts.map +1 -1
- package/dist/tools/background.d.ts +50 -0
- package/dist/tools/background.d.ts.map +1 -0
- package/dist/tools/bash.d.ts +12 -4
- package/dist/tools/bash.d.ts.map +1 -1
- package/dist/tools/model-spec.d.ts +9 -2
- package/dist/tools/model-spec.d.ts.map +1 -1
- package/dist/tools/tool-files.d.ts.map +1 -1
- package/dist/tools/tool-outputs.d.ts +12 -2
- package/dist/tools/tool-outputs.d.ts.map +1 -1
- package/dist/tools/web-fetch/cache.d.ts +33 -0
- package/dist/tools/web-fetch/cache.d.ts.map +1 -0
- package/dist/tools/web-fetch/html-markdown.d.ts +25 -0
- package/dist/tools/web-fetch/html-markdown.d.ts.map +1 -0
- package/dist/tools/web-fetch/network.d.ts +55 -0
- package/dist/tools/web-fetch/network.d.ts.map +1 -0
- package/dist/tools/web-fetch/tool.d.ts +96 -0
- package/dist/tools/web-fetch/tool.d.ts.map +1 -0
- package/dist/tools/web-search.d.ts +40 -0
- package/dist/tools/web-search.d.ts.map +1 -0
- package/dist/types.d.ts +5 -4
- package/dist/types.d.ts.map +1 -1
- package/dist/workspace-instructions.d.ts +15 -0
- package/dist/workspace-instructions.d.ts.map +1 -0
- package/package.json +15 -5
- package/src/agent-prompt.ts +64 -5
- package/src/agent-runtime/preflight.ts +2 -1
- package/src/artifacts/board-previews.ts +218 -0
- package/src/artifacts/layout-check/check.cjs +304 -80
- package/src/artifacts/layout-check/layout-check.ts +123 -13
- package/src/artifacts/layout-check/overview.ts +291 -0
- package/src/artifacts/materialize.ts +181 -55
- package/src/artifacts/publish-tool.ts +459 -129
- package/src/background-commands.ts +573 -0
- package/src/background-notices.ts +178 -0
- package/src/computer-runner.ts +211 -9
- package/src/context-compaction.ts +4 -1
- package/src/execution-plan.ts +15 -2
- package/src/index.ts +4 -0
- package/src/login-shell.ts +18 -0
- package/src/run-child.ts +5 -0
- package/src/run-conversation-turn.ts +23 -4
- package/src/run-environment.ts +96 -17
- package/src/run-sandbox.ts +41 -0
- package/src/sandbox-api-context.ts +1 -1
- package/src/sandbox-files.ts +88 -1
- package/src/skills/sixb-artifacts/SKILL.md +48 -25
- package/src/skills/sixb-artifacts/canvas.md +140 -18
- package/src/skills/sixb-artifacts/examples/canvas/onboarding-flow/canvas.json +1 -1
- package/src/skills/sixb-artifacts/page.md +1 -1
- package/src/skills/sixb-artifacts/references.md +15 -12
- package/src/skills/sixb-artifacts/sheet.md +1 -1
- package/src/skills/sixb-artifacts/slides.md +1 -1
- package/src/subagent-tools.ts +19 -7
- package/src/tools/background.ts +127 -0
- package/src/tools/bash.ts +80 -11
- package/src/tools/model-spec.ts +28 -5
- package/src/tools/tool-files.ts +3 -1
- package/src/tools/tool-outputs.ts +46 -6
- package/src/tools/web-fetch/cache.ts +91 -0
- package/src/tools/web-fetch/html-markdown.ts +479 -0
- package/src/tools/web-fetch/network.ts +452 -0
- package/src/tools/web-fetch/tool.ts +619 -0
- package/src/tools/web-search.ts +139 -0
- package/src/types.ts +5 -4
- 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
|
|
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
|
-
|
|
6
|
-
const
|
|
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:
|
|
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: {
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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.
|
package/src/tools/model-spec.ts
CHANGED
|
@@ -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
|
-
|
|
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: {
|
|
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,
|
|
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
|
+
}
|
package/src/tools/tool-files.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
/**
|
|
66
|
-
|
|
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) => (
|
|
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:
|
|
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
|
|
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
|
+
}
|