typeclaw 0.45.1 → 0.46.0
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 +1 -1
- package/package.json +2 -1
- package/src/agent/git-nudge.ts +2 -1
- package/src/agent/index.ts +44 -30
- package/src/agent/live-subagents.ts +18 -0
- package/src/agent/multimodal/index.ts +1 -1
- package/src/agent/multimodal/look-at.ts +78 -44
- package/src/agent/multimodal/looker.ts +151 -39
- package/src/agent/network/response-body.ts +26 -0
- package/src/agent/network/safe-http.ts +198 -0
- package/src/agent/plugin-tools.ts +379 -157
- package/src/agent/provider-error.ts +52 -1
- package/src/agent/restart/index.ts +61 -40
- package/src/agent/restart-handoff/index.ts +73 -4
- package/src/agent/reviewer-bash-policy.ts +42 -1
- package/src/agent/session-origin.ts +2 -0
- package/src/agent/subagent-drain.ts +117 -7
- package/src/agent/subagents.ts +49 -16
- package/src/agent/throttle-circuit.ts +25 -5
- package/src/agent/tool-error-remediation.ts +72 -0
- package/src/agent/tool-file-safety.ts +1050 -0
- package/src/agent/tools/channel-fetch-attachment.ts +10 -3
- package/src/agent/tools/ddg.ts +16 -2
- package/src/agent/tools/post-github-review.ts +199 -0
- package/src/agent/tools/spawn-subagent.ts +21 -18
- package/src/agent/tools/webfetch/fetch.ts +143 -183
- package/src/agent/tools/webfetch/tool.ts +2 -3
- package/src/agent/tools/websearch.ts +23 -2
- package/src/agent/tools-without-local-file-operands.ts +27 -0
- package/src/agent/turn-runner.ts +86 -6
- package/src/bundled-plugins/backup/index.ts +2 -1
- package/src/bundled-plugins/backup/runner.ts +2 -1
- package/src/bundled-plugins/doc-render/render.ts +93 -12
- package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
- package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
- package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
- package/src/bundled-plugins/github-cli-auth/index.ts +131 -135
- package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
- package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
- package/src/bundled-plugins/memory/README.md +23 -11
- package/src/bundled-plugins/memory/append-tool.ts +15 -8
- package/src/bundled-plugins/memory/citations.ts +22 -9
- package/src/bundled-plugins/memory/dreaming.ts +13 -8
- package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
- package/src/bundled-plugins/memory/index.ts +0 -4
- package/src/bundled-plugins/memory/load-memory.ts +8 -3
- package/src/bundled-plugins/memory/provenance-index.ts +717 -0
- package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
- package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
- package/src/bundled-plugins/memory/search-tool.ts +163 -60
- package/src/bundled-plugins/memory/stream-events.ts +2 -0
- package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
- package/src/bundled-plugins/researcher/write-report.ts +6 -3
- package/src/bundled-plugins/reviewer/index.ts +2 -2
- package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
- package/src/bundled-plugins/reviewer/skills/code-review.ts +19 -9
- package/src/bundled-plugins/scout/scout.ts +8 -0
- package/src/bundled-plugins/security/index.ts +4 -4
- package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
- package/src/bundled-plugins/security/policies/private-surface-read.ts +220 -29
- package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
- package/src/bundled-plugins/security/policies/ssrf.ts +29 -9
- package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
- package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
- package/src/channels/adapters/discord-bot.ts +66 -6
- package/src/channels/adapters/discord-channel-resolver.ts +91 -23
- package/src/channels/adapters/discord-id.ts +4 -0
- package/src/channels/adapters/discord-resolver-cache.ts +41 -0
- package/src/channels/adapters/discord.ts +57 -7
- package/src/channels/adapters/github/auth-app.ts +41 -12
- package/src/channels/adapters/github/index.ts +23 -11
- package/src/channels/adapters/github/review-submitter.ts +302 -0
- package/src/channels/adapters/kakaotalk-channel-resolver.ts +5 -3
- package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
- package/src/channels/adapters/kakaotalk-typing.ts +17 -15
- package/src/channels/adapters/slack-attachment-download.ts +71 -0
- package/src/channels/adapters/slack-bot.ts +19 -8
- package/src/channels/adapters/slack-classify.ts +21 -2
- package/src/channels/adapters/slack.ts +59 -7
- package/src/channels/adapters/telegram-bot.ts +18 -5
- package/src/channels/adapters/webex-bot.ts +8 -3
- package/src/channels/adapters/webex.ts +8 -3
- package/src/channels/fetch-attachment.ts +43 -0
- package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
- package/src/channels/github-token-bridge.ts +10 -3
- package/src/channels/manager.ts +9 -0
- package/src/channels/router.ts +248 -6
- package/src/channels/types.ts +28 -1
- package/src/cli/channel.ts +1 -1
- package/src/cli/init.ts +1 -1
- package/src/cli/model.ts +57 -7
- package/src/compose/stop.ts +17 -5
- package/src/config/config.ts +6 -6
- package/src/config/models-mutation.ts +13 -1
- package/src/config/providers.ts +176 -0
- package/src/container/start.ts +49 -10
- package/src/doctor/checks.ts +3 -1
- package/src/doctor/commit.ts +2 -1
- package/src/doctor/file-ownership.ts +52 -0
- package/src/dreams/git.ts +2 -1
- package/src/git/hookless.ts +5 -0
- package/src/git/reconcile-ignored.ts +18 -5
- package/src/git/secret-history.ts +371 -0
- package/src/git/system-commit.ts +12 -6
- package/src/init/dockerfile.ts +86 -5
- package/src/init/index.ts +17 -5
- package/src/init/models-dev.ts +4 -0
- package/src/init/validate-api-key.ts +2 -0
- package/src/mcp/tools.ts +16 -3
- package/src/permissions/builtins.ts +3 -1
- package/src/plugin/context.ts +2 -0
- package/src/plugin/index.ts +1 -0
- package/src/plugin/manager.ts +4 -0
- package/src/plugin/types.ts +21 -0
- package/src/run/index.ts +40 -0
- package/src/run/llm-fetch-observer.ts +41 -4
- package/src/sandbox/build.ts +37 -15
- package/src/sandbox/canonical-secrets.ts +18 -0
- package/src/sandbox/env-exposure.ts +80 -0
- package/src/sandbox/errors.ts +13 -6
- package/src/sandbox/hidden-paths.ts +102 -44
- package/src/sandbox/index.ts +22 -4
- package/src/sandbox/package-install.ts +3 -27
- package/src/sandbox/policy.ts +11 -25
- package/src/sandbox/privileged-runtime.ts +255 -0
- package/src/sandbox/session-tmp.ts +8 -2
- package/src/sandbox/writable-zones.ts +204 -140
- package/src/secrets/index.ts +8 -0
- package/src/secrets/refresh-provider-oauth.ts +128 -0
- package/src/server/command-runner.ts +48 -4
- package/src/server/index.ts +4 -0
- package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
- package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
- package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
- package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
- package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
- package/src/skills/typeclaw-config/SKILL.md +5 -5
- package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
- package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
- package/src/skills/typeclaw-memory/SKILL.md +9 -3
- package/src/skills/typeclaw-permissions/SKILL.md +19 -15
- package/typeclaw.schema.json +20 -0
|
@@ -0,0 +1,1050 @@
|
|
|
1
|
+
import { constants, createWriteStream, lstatSync, type Stats } from 'node:fs'
|
|
2
|
+
import { chmod, mkdir, mkdtemp, open, readdir, realpath, rm, stat, type FileHandle } from 'node:fs/promises'
|
|
3
|
+
import { tmpdir } from 'node:os'
|
|
4
|
+
import path from 'node:path'
|
|
5
|
+
import { Transform } from 'node:stream'
|
|
6
|
+
import { pipeline } from 'node:stream/promises'
|
|
7
|
+
import { fileURLToPath, pathToFileURL } from 'node:url'
|
|
8
|
+
|
|
9
|
+
import { checkPrivateSurfaceReadGuard } from '@/bundled-plugins/security/policies/private-surface-read'
|
|
10
|
+
import type { ToolFileOperands, ToolResult } from '@/plugin'
|
|
11
|
+
import { CANONICAL_AGENT_SECRET_FILES } from '@/sandbox/canonical-secrets'
|
|
12
|
+
import type { HiddenPaths } from '@/sandbox/hidden-paths'
|
|
13
|
+
|
|
14
|
+
import { TOOLS_WITHOUT_LOCAL_FILE_OPERANDS } from './tools-without-local-file-operands'
|
|
15
|
+
|
|
16
|
+
export { TOOLS_WITHOUT_LOCAL_FILE_OPERANDS }
|
|
17
|
+
|
|
18
|
+
type Rewrite = { original: string; pinned: string }
|
|
19
|
+
type FileTarget = { get(): string; original: string; set(value: string): void; uri: boolean }
|
|
20
|
+
type VerifiedInput = {
|
|
21
|
+
target: FileTarget
|
|
22
|
+
original: string
|
|
23
|
+
resolved: string
|
|
24
|
+
dev: number
|
|
25
|
+
ino: number
|
|
26
|
+
size: number
|
|
27
|
+
kind: 'file' | 'directory'
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export const TOOL_INPUT_MAX_BYTES = {
|
|
31
|
+
// read supports offset/limit browsing, so permit large source files while
|
|
32
|
+
// bounding the immutable whole-object snapshot.
|
|
33
|
+
read: 64 * 1024 * 1024,
|
|
34
|
+
// Keep local images on the same budget as look_at's bounded URL fetch.
|
|
35
|
+
look_at: 20 * 1024 * 1024,
|
|
36
|
+
// Preserve common channel upload sizes without allowing unbounded copies.
|
|
37
|
+
channel_upload: 100 * 1024 * 1024,
|
|
38
|
+
} as const
|
|
39
|
+
|
|
40
|
+
export const TOOL_INPUT_MAX_COUNT = {
|
|
41
|
+
read: 1,
|
|
42
|
+
look_at: 16,
|
|
43
|
+
channel_upload: 32,
|
|
44
|
+
} as const
|
|
45
|
+
|
|
46
|
+
export const PINNED_SNAPSHOT_GLOBAL_MAX_BYTES = TOOL_INPUT_MAX_BYTES.channel_upload
|
|
47
|
+
export const PINNED_SNAPSHOT_GLOBAL_MAX_COUNT = TOOL_INPUT_MAX_COUNT.channel_upload
|
|
48
|
+
export const PINNED_SNAPSHOT_MAX_WAITERS = 32
|
|
49
|
+
const TREE_SNAPSHOT_MAX_ENTRIES = 4096
|
|
50
|
+
const AGENT_ROOT_SNAPSHOT_EXCLUDED_DIRS = new Set(['.git', '.gitstore', 'node_modules'])
|
|
51
|
+
|
|
52
|
+
export const TOOL_INPUT_TEMP_PREFIX = 'typeclaw-tool-input-'
|
|
53
|
+
|
|
54
|
+
export type PinnedToolFiles = {
|
|
55
|
+
restoreResult(result: ToolResult): ToolResult
|
|
56
|
+
cleanup(): Promise<void>
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export async function enforceAndPinToolFiles(options: {
|
|
60
|
+
tool: string
|
|
61
|
+
args: Record<string, unknown>
|
|
62
|
+
agentDir: string
|
|
63
|
+
tempRoot?: string
|
|
64
|
+
genericInputs?: boolean
|
|
65
|
+
fileOperands?: ToolFileOperands
|
|
66
|
+
hidden?: HiddenPaths
|
|
67
|
+
signal?: AbortSignal
|
|
68
|
+
}): Promise<PinnedToolFiles> {
|
|
69
|
+
if (options.signal?.aborted === true) throw abortError(options.signal)
|
|
70
|
+
const maxCount = maxInputCount(options.tool)
|
|
71
|
+
const targets = fileTargets(
|
|
72
|
+
options.tool,
|
|
73
|
+
options.args,
|
|
74
|
+
maxCount,
|
|
75
|
+
options.genericInputs === true,
|
|
76
|
+
options.fileOperands,
|
|
77
|
+
options.agentDir,
|
|
78
|
+
)
|
|
79
|
+
enforceCanonicalSecretDenial(options)
|
|
80
|
+
const outputs = outputTargets(options.tool, options.args, maxCount, options.fileOperands)
|
|
81
|
+
if (outputs.length > 0) return await pinOutputTargets(options, outputs)
|
|
82
|
+
if (targets.length === 0) return noPinnedFiles()
|
|
83
|
+
|
|
84
|
+
let dir: string | undefined
|
|
85
|
+
const rewrites: Rewrite[] = []
|
|
86
|
+
const verified: VerifiedInput[] = []
|
|
87
|
+
const maxBytes = maxInputBytes(options.tool)
|
|
88
|
+
let lease: BudgetLease | undefined
|
|
89
|
+
try {
|
|
90
|
+
let declaredBytes = 0
|
|
91
|
+
for (const target of targets) {
|
|
92
|
+
const original = target.get()
|
|
93
|
+
const absolute = path.resolve(options.agentDir, original)
|
|
94
|
+
const resolved = await realpath(absolute).catch((error) => {
|
|
95
|
+
if (isNotFoundError(error)) throw new Error(`tool input did not exist while being authorized: ${original}`)
|
|
96
|
+
throw error
|
|
97
|
+
})
|
|
98
|
+
enforceCanonicalSecretDenial({ tool: options.tool, args: { path: resolved }, agentDir: options.agentDir })
|
|
99
|
+
const inspected = await stat(resolved)
|
|
100
|
+
const kind = inspected.isFile()
|
|
101
|
+
? 'file'
|
|
102
|
+
: inspected.isDirectory() && isTreeInputTool(options.tool)
|
|
103
|
+
? 'directory'
|
|
104
|
+
: undefined
|
|
105
|
+
if (kind === undefined) throw new Error(`tool input is not a supported regular file or directory: ${original}`)
|
|
106
|
+
if (kind === 'file') assertSingleLinkRegularFile(inspected, original)
|
|
107
|
+
if (kind === 'file' && inspected.size > maxBytes) throw inputTooLarge(original, inspected.size, maxBytes)
|
|
108
|
+
declaredBytes += kind === 'file' ? inspected.size : 0
|
|
109
|
+
if (declaredBytes > maxBytes) throw aggregateInputTooLarge(declaredBytes, maxBytes)
|
|
110
|
+
verified.push({ target, original, resolved, dev: inspected.dev, ino: inspected.ino, size: inspected.size, kind })
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
lease = await pinnedSnapshotBudget.acquire(declaredBytes, verified.length, options.signal)
|
|
114
|
+
|
|
115
|
+
dir = await mkdtemp(path.join(options.tempRoot ?? tmpdir(), TOOL_INPUT_TEMP_PREFIX))
|
|
116
|
+
let copiedBytes = 0
|
|
117
|
+
for (let i = 0; i < verified.length; i++) {
|
|
118
|
+
const input = verified[i] as VerifiedInput
|
|
119
|
+
const pinned = path.join(dir, String(i))
|
|
120
|
+
if (input.kind === 'file') {
|
|
121
|
+
const source = await openInput(input.resolved, input.original)
|
|
122
|
+
try {
|
|
123
|
+
const opened = await source.stat()
|
|
124
|
+
assertSingleLinkRegularFile(opened, input.original)
|
|
125
|
+
if (opened.dev !== input.dev || opened.ino !== input.ino) {
|
|
126
|
+
throw new Error(`tool input changed while waiting for snapshot capacity: ${input.original}`)
|
|
127
|
+
}
|
|
128
|
+
copiedBytes += await streamSnapshot(
|
|
129
|
+
source,
|
|
130
|
+
pinned,
|
|
131
|
+
input.original,
|
|
132
|
+
maxBytes,
|
|
133
|
+
copiedBytes,
|
|
134
|
+
lease,
|
|
135
|
+
verified.length,
|
|
136
|
+
options.signal,
|
|
137
|
+
)
|
|
138
|
+
await chmod(pinned, 0o400)
|
|
139
|
+
} finally {
|
|
140
|
+
await source.close()
|
|
141
|
+
}
|
|
142
|
+
} else {
|
|
143
|
+
copiedBytes += await snapshotDirectoryTree({
|
|
144
|
+
source: input,
|
|
145
|
+
destination: pinned,
|
|
146
|
+
agentDir: options.agentDir,
|
|
147
|
+
tool: options.tool,
|
|
148
|
+
maxBytes,
|
|
149
|
+
previouslyCopied: copiedBytes,
|
|
150
|
+
lease,
|
|
151
|
+
operandCount: verified.length,
|
|
152
|
+
hidden: options.hidden,
|
|
153
|
+
signal: options.signal,
|
|
154
|
+
})
|
|
155
|
+
}
|
|
156
|
+
const executionValue = input.target.uri ? pathToFileURL(pinned).href : pinned
|
|
157
|
+
input.target.set(executionValue)
|
|
158
|
+
rewrites.push({ original: input.target.original, pinned: executionValue })
|
|
159
|
+
}
|
|
160
|
+
if (!lease.resize(copiedBytes, verified.length)) throw processBudgetGrowthExceeded(copiedBytes)
|
|
161
|
+
} catch (error) {
|
|
162
|
+
try {
|
|
163
|
+
if (dir !== undefined) await removePinnedSnapshot(dir)
|
|
164
|
+
} finally {
|
|
165
|
+
lease?.release()
|
|
166
|
+
}
|
|
167
|
+
throw error
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
if (dir === undefined) return noPinnedFiles()
|
|
171
|
+
|
|
172
|
+
let cleaned = false
|
|
173
|
+
|
|
174
|
+
return {
|
|
175
|
+
restoreResult(result) {
|
|
176
|
+
let restored = result
|
|
177
|
+
for (const rewrite of rewrites) restored = replaceResultPath(restored, rewrite)
|
|
178
|
+
return restored
|
|
179
|
+
},
|
|
180
|
+
async cleanup() {
|
|
181
|
+
if (cleaned) return
|
|
182
|
+
cleaned = true
|
|
183
|
+
try {
|
|
184
|
+
await removePinnedSnapshot(dir)
|
|
185
|
+
} finally {
|
|
186
|
+
lease?.release()
|
|
187
|
+
}
|
|
188
|
+
},
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
async function removePinnedSnapshot(root: string): Promise<void> {
|
|
193
|
+
const pending = [root]
|
|
194
|
+
while (pending.length > 0) {
|
|
195
|
+
const directory = pending.pop()
|
|
196
|
+
if (directory === undefined) break
|
|
197
|
+
await chmod(directory, 0o700)
|
|
198
|
+
const entries = await readdir(directory, { withFileTypes: true })
|
|
199
|
+
for (const entry of entries) {
|
|
200
|
+
if (entry.isDirectory()) pending.push(path.join(directory, entry.name))
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
await rm(root, { recursive: true, force: true })
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
export function enforceCanonicalSecretDenial(options: {
|
|
207
|
+
tool: string
|
|
208
|
+
args: Record<string, unknown>
|
|
209
|
+
agentDir: string
|
|
210
|
+
}): void {
|
|
211
|
+
const blocked = checkPrivateSurfaceReadGuard({ ...options, hidden: { dirs: [], files: [] } })
|
|
212
|
+
if (blocked !== undefined) throw new Error(`blocked: ${blocked.reason}`)
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
function fileTargets(
|
|
216
|
+
tool: string,
|
|
217
|
+
args: Record<string, unknown>,
|
|
218
|
+
maxCount: number,
|
|
219
|
+
genericInputs: boolean,
|
|
220
|
+
fileOperands: ToolFileOperands | undefined,
|
|
221
|
+
agentDir: string,
|
|
222
|
+
): FileTarget[] {
|
|
223
|
+
if (isOutputTool(tool)) return []
|
|
224
|
+
if (TOOLS_WITHOUT_LOCAL_FILE_OPERANDS.has(tool)) return []
|
|
225
|
+
if (tool === 'read' && typeof args.path === 'string') return [propertyTarget(args, 'path')]
|
|
226
|
+
if (isTreeInputTool(tool)) {
|
|
227
|
+
if (typeof args.path !== 'string') args.path = '.'
|
|
228
|
+
return [propertyTarget(args, 'path')]
|
|
229
|
+
}
|
|
230
|
+
const targets: FileTarget[] = []
|
|
231
|
+
const addPath = (value: unknown): void => {
|
|
232
|
+
if (!isRecord(value) || typeof value.path !== 'string') return
|
|
233
|
+
targets.push(propertyTarget(value, 'path'))
|
|
234
|
+
if (targets.length > maxCount) throw inputCountTooLarge(targets.length, maxCount)
|
|
235
|
+
}
|
|
236
|
+
if (tool === 'look_at') {
|
|
237
|
+
if (Array.isArray(args.images)) for (const image of args.images) addPath(image)
|
|
238
|
+
return targets
|
|
239
|
+
}
|
|
240
|
+
// The only file operand for these tools is `attachments[].path`; `text` is free-form
|
|
241
|
+
// prose (dates like "7/16", URLs, fractions) that must never reach the generic scan,
|
|
242
|
+
// which rejects any value carrying a `/` or `\`. Return early even without attachments
|
|
243
|
+
// so a text-only message is never misread as a path. Attachment pinning is unchanged.
|
|
244
|
+
if (tool === 'channel_send' || tool === 'channel_reply') {
|
|
245
|
+
if (Array.isArray(args.attachments)) for (const attachment of args.attachments) addPath(attachment)
|
|
246
|
+
return targets
|
|
247
|
+
}
|
|
248
|
+
if (tool === 'channel_fetch_attachment') return targets
|
|
249
|
+
// post_github_review has no local file operands: `comments[].path` are remote
|
|
250
|
+
// GitHub diff anchors and the `body` fields are markdown. Scanning them as
|
|
251
|
+
// generic operands either pins a real-repo anchor into a /tmp file:// path that
|
|
252
|
+
// leaks into the posted review, or throws "ambiguous local file operand".
|
|
253
|
+
if (tool === 'post_github_review') return targets
|
|
254
|
+
if (genericInputs) collectGenericFileTargets(tool, args, targets, maxCount, fileOperands, agentDir)
|
|
255
|
+
return targets
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
// Exact tool + operand-path pairs for first-party PROSE operands (message
|
|
259
|
+
// bodies, prompts, queries, regex/CSS/jq strings) that are never a local file.
|
|
260
|
+
// This table is for tools that ALSO have a real file operand and so cannot be
|
|
261
|
+
// whole-tool exempt via TOOLS_WITHOUT_LOCAL_FILE_OPERANDS: web_fetch pins its
|
|
262
|
+
// `url` (a file: URI there still snapshots) while `query`/`selector`/`pattern`
|
|
263
|
+
// are prose. Pure control-token tools (reload, grant_role, stream_snapshot,
|
|
264
|
+
// channel_edit, …) live in that set instead, so they are absent here.
|
|
265
|
+
//
|
|
266
|
+
// Scoped by full operand path, NOT key name — this is the fail-closed invariant:
|
|
267
|
+
// an undeclared plugin/MCP reader that reuses `content`/`prompt`/`query` must
|
|
268
|
+
// still hit the scan and cannot inherit an exemption from a common key name.
|
|
269
|
+
// Plugin/MCP tools declare their own via `fileOperands.nonFile` (survives the
|
|
270
|
+
// runtime `__plugin_*` name prefix, which a static table here would not).
|
|
271
|
+
const NON_FILE_OPERANDS: Readonly<Record<string, ReadonlySet<string>>> = {
|
|
272
|
+
skip_response: new Set(['reason']),
|
|
273
|
+
web_search: new Set(['query']),
|
|
274
|
+
web_fetch: new Set(['query', 'selector', 'pattern']),
|
|
275
|
+
todo_write: new Set(['todos.content']),
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
function isKnownNonFileOperand(tool: string, operandPath: string): boolean {
|
|
279
|
+
return NON_FILE_OPERANDS[tool]?.has(operandPath) === true
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
// Detection trims first: a leading-whitespace ` file://…` is still a file
|
|
283
|
+
// reference to any consumer that trims before parsing, so it must be pinned or
|
|
284
|
+
// denied, never passed through untouched. The original untrimmed string is
|
|
285
|
+
// preserved on the target for result restoration; the trimmed URI is what gets
|
|
286
|
+
// normalized and snapshotted.
|
|
287
|
+
function isFileUri(value: string): boolean {
|
|
288
|
+
return value.trim().toLocaleLowerCase().startsWith('file:')
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
function propertyTarget(object: Record<string, unknown>, key: string): FileTarget {
|
|
292
|
+
const raw = object[key] as string
|
|
293
|
+
return {
|
|
294
|
+
get: () => normalizeFileReference(object[key] as string),
|
|
295
|
+
original: raw,
|
|
296
|
+
set: (value) => {
|
|
297
|
+
object[key] = value
|
|
298
|
+
},
|
|
299
|
+
uri: isFileUri(raw),
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
function arrayTarget(array: unknown[], index: number): FileTarget {
|
|
304
|
+
const raw = array[index] as string
|
|
305
|
+
return {
|
|
306
|
+
get: () => normalizeFileReference(array[index] as string),
|
|
307
|
+
original: raw,
|
|
308
|
+
set: (value) => {
|
|
309
|
+
array[index] = value
|
|
310
|
+
},
|
|
311
|
+
uri: isFileUri(raw),
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
function outputTargets(
|
|
316
|
+
tool: string,
|
|
317
|
+
args: Record<string, unknown>,
|
|
318
|
+
maxCount: number,
|
|
319
|
+
operands: ToolFileOperands | undefined,
|
|
320
|
+
): FileTarget[] {
|
|
321
|
+
if (isOutputTool(tool)) return typeof args.path === 'string' ? [propertyTarget(args, 'path')] : []
|
|
322
|
+
if (operands?.output === undefined || operands.output.length === 0) return []
|
|
323
|
+
const targets: FileTarget[] = []
|
|
324
|
+
collectDeclaredOutputTargets(args, targets, maxCount, new Set(operands.output))
|
|
325
|
+
return targets
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
function collectDeclaredOutputTargets(
|
|
329
|
+
value: unknown,
|
|
330
|
+
out: FileTarget[],
|
|
331
|
+
maxCount: number,
|
|
332
|
+
declared: ReadonlySet<string>,
|
|
333
|
+
parentPath = '',
|
|
334
|
+
): void {
|
|
335
|
+
if (Array.isArray(value)) {
|
|
336
|
+
const declaredOutput = declared.has(parentPath)
|
|
337
|
+
for (const [index, item] of value.entries()) {
|
|
338
|
+
if (typeof item === 'string') {
|
|
339
|
+
if (declaredOutput) {
|
|
340
|
+
out.push(arrayTarget(value, index))
|
|
341
|
+
if (out.length > maxCount) throw inputCountTooLarge(out.length, maxCount)
|
|
342
|
+
}
|
|
343
|
+
continue
|
|
344
|
+
}
|
|
345
|
+
collectDeclaredOutputTargets(item, out, maxCount, declared, parentPath)
|
|
346
|
+
}
|
|
347
|
+
return
|
|
348
|
+
}
|
|
349
|
+
if (!isRecord(value)) return
|
|
350
|
+
for (const [childKey, item] of Object.entries(value)) {
|
|
351
|
+
const operandPath = parentPath === '' ? childKey : `${parentPath}.${childKey}`
|
|
352
|
+
if (typeof item === 'string' && declared.has(operandPath)) {
|
|
353
|
+
out.push(propertyTarget(value, childKey))
|
|
354
|
+
if (out.length > maxCount) throw inputCountTooLarge(out.length, maxCount)
|
|
355
|
+
continue
|
|
356
|
+
}
|
|
357
|
+
collectDeclaredOutputTargets(item, out, maxCount, declared, operandPath)
|
|
358
|
+
}
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
function collectGenericFileTargets(
|
|
362
|
+
tool: string,
|
|
363
|
+
value: unknown,
|
|
364
|
+
out: FileTarget[],
|
|
365
|
+
maxCount: number,
|
|
366
|
+
operands: ToolFileOperands | undefined,
|
|
367
|
+
agentDir: string,
|
|
368
|
+
parentPath = '',
|
|
369
|
+
): void {
|
|
370
|
+
if (Array.isArray(value)) {
|
|
371
|
+
const declaredInput = operands?.input?.includes(parentPath) === true
|
|
372
|
+
const nonInput =
|
|
373
|
+
operands?.output?.includes(parentPath) === true || operands?.destructive?.includes(parentPath) === true
|
|
374
|
+
const key = parentPath.split('.').at(-1) ?? parentPath
|
|
375
|
+
// Precedence: declared input pins; declared output/destructive is not an
|
|
376
|
+
// input; a known non-file operand is opaque (skipped, even a file: URI);
|
|
377
|
+
// otherwise an explicit file: URI pins and an undeclared path-shaped value
|
|
378
|
+
// fails closed. Both the static first-party table and a plugin's declared
|
|
379
|
+
// `fileOperands.nonFile` are tool+operand-path scoped, so an unknown tool
|
|
380
|
+
// never inherits an exemption from a common key name.
|
|
381
|
+
const knownNonFile =
|
|
382
|
+
!declaredInput && (operands?.nonFile?.includes(parentPath) === true || isKnownNonFileOperand(tool, parentPath))
|
|
383
|
+
for (const [index, item] of value.entries()) {
|
|
384
|
+
if (typeof item === 'string') {
|
|
385
|
+
if (knownNonFile) continue
|
|
386
|
+
if (!nonInput && (isFileUri(item) || declaredInput)) {
|
|
387
|
+
out.push(arrayTarget(value, index))
|
|
388
|
+
if (out.length > maxCount) throw inputCountTooLarge(out.length, maxCount)
|
|
389
|
+
} else if (
|
|
390
|
+
!nonInput &&
|
|
391
|
+
!isSemanticGenericString(key, item) &&
|
|
392
|
+
isAmbiguousUndeclaredLocalOperand(item, agentDir, key)
|
|
393
|
+
) {
|
|
394
|
+
throw new Error(
|
|
395
|
+
`ambiguous local file operand at key ${JSON.stringify(parentPath)}; the tool author must declare fileOperands.input or the caller must use a file: URI`,
|
|
396
|
+
)
|
|
397
|
+
}
|
|
398
|
+
continue
|
|
399
|
+
}
|
|
400
|
+
collectGenericFileTargets(tool, item, out, maxCount, operands, agentDir, parentPath)
|
|
401
|
+
}
|
|
402
|
+
return
|
|
403
|
+
}
|
|
404
|
+
if (!isRecord(value)) return
|
|
405
|
+
for (const [childKey, item] of Object.entries(value)) {
|
|
406
|
+
const operandPath = parentPath === '' ? childKey : `${parentPath}.${childKey}`
|
|
407
|
+
if (typeof item === 'string') {
|
|
408
|
+
const declaredInput = operands?.input?.includes(operandPath) === true
|
|
409
|
+
const nonInput =
|
|
410
|
+
operands?.output?.includes(operandPath) === true || operands?.destructive?.includes(operandPath) === true
|
|
411
|
+
// Declared input wins; a known non-file operand (web_search.query,
|
|
412
|
+
// web_fetch.selector, a plugin's declared `fileOperands.nonFile`, …) is
|
|
413
|
+
// opaque and skipped even when its value is a file: URI; everything else
|
|
414
|
+
// falls to the file:/heuristic scan below. Scoped by exact tool+operand-
|
|
415
|
+
// path so an undeclared plugin reader using `content`/`prompt` still
|
|
416
|
+
// fails closed.
|
|
417
|
+
if (
|
|
418
|
+
!declaredInput &&
|
|
419
|
+
(operands?.nonFile?.includes(operandPath) === true || isKnownNonFileOperand(tool, operandPath))
|
|
420
|
+
) {
|
|
421
|
+
continue
|
|
422
|
+
}
|
|
423
|
+
if (!nonInput && (isFileUri(item) || declaredInput)) {
|
|
424
|
+
out.push(propertyTarget(value, childKey))
|
|
425
|
+
if (out.length > maxCount) throw inputCountTooLarge(out.length, maxCount)
|
|
426
|
+
continue
|
|
427
|
+
}
|
|
428
|
+
if (
|
|
429
|
+
!nonInput &&
|
|
430
|
+
!isSemanticGenericString(childKey, item) &&
|
|
431
|
+
isAmbiguousUndeclaredLocalOperand(item, agentDir, childKey)
|
|
432
|
+
) {
|
|
433
|
+
throw new Error(
|
|
434
|
+
`ambiguous local file operand at key ${JSON.stringify(operandPath)}; the tool author must declare fileOperands.input or the caller must use a file: URI`,
|
|
435
|
+
)
|
|
436
|
+
}
|
|
437
|
+
}
|
|
438
|
+
collectGenericFileTargets(tool, item, out, maxCount, operands, agentDir, operandPath)
|
|
439
|
+
}
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
function noPinnedFiles(): PinnedToolFiles {
|
|
443
|
+
return { restoreResult: (result) => result, cleanup: async () => {} }
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
async function openInput(absolute: string, original: string): Promise<FileHandle> {
|
|
447
|
+
try {
|
|
448
|
+
return await open(absolute, constants.O_RDONLY)
|
|
449
|
+
} catch (error) {
|
|
450
|
+
if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
|
|
451
|
+
throw new Error(`tool input did not exist while being authorized: ${original}`)
|
|
452
|
+
}
|
|
453
|
+
throw error
|
|
454
|
+
}
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
async function pinOutputTargets(
|
|
458
|
+
options: {
|
|
459
|
+
tool: string
|
|
460
|
+
args: Record<string, unknown>
|
|
461
|
+
agentDir: string
|
|
462
|
+
signal?: AbortSignal
|
|
463
|
+
},
|
|
464
|
+
targets: FileTarget[],
|
|
465
|
+
): Promise<PinnedToolFiles> {
|
|
466
|
+
const pinned: PinnedToolFiles[] = []
|
|
467
|
+
try {
|
|
468
|
+
for (const target of targets) pinned.push(await pinOutputTarget(options, target))
|
|
469
|
+
} catch (error) {
|
|
470
|
+
await Promise.allSettled([...pinned].reverse().map(async (entry) => await entry.cleanup()))
|
|
471
|
+
throw error
|
|
472
|
+
}
|
|
473
|
+
return {
|
|
474
|
+
restoreResult(result) {
|
|
475
|
+
return pinned.reduce((restored, entry) => entry.restoreResult(restored), result)
|
|
476
|
+
},
|
|
477
|
+
async cleanup() {
|
|
478
|
+
const outcomes = await Promise.allSettled([...pinned].reverse().map(async (entry) => await entry.cleanup()))
|
|
479
|
+
const failed = outcomes.find((outcome) => outcome.status === 'rejected')
|
|
480
|
+
if (failed?.status === 'rejected') throw failed.reason
|
|
481
|
+
},
|
|
482
|
+
}
|
|
483
|
+
}
|
|
484
|
+
|
|
485
|
+
async function pinOutputTarget(
|
|
486
|
+
options: {
|
|
487
|
+
tool: string
|
|
488
|
+
args: Record<string, unknown>
|
|
489
|
+
agentDir: string
|
|
490
|
+
signal?: AbortSignal
|
|
491
|
+
},
|
|
492
|
+
target: FileTarget,
|
|
493
|
+
): Promise<PinnedToolFiles> {
|
|
494
|
+
if (options.signal?.aborted === true) throw abortError(options.signal)
|
|
495
|
+
const original = target.get()
|
|
496
|
+
const absolute = path.resolve(options.agentDir, original)
|
|
497
|
+
enforceCanonicalSecretDenial({ tool: options.tool, args: { path: absolute }, agentDir: options.agentDir })
|
|
498
|
+
if (process.platform !== 'linux') {
|
|
499
|
+
throw new Error('write/edit output authorization requires Linux inode anchoring; refusing an unanchored path')
|
|
500
|
+
}
|
|
501
|
+
const parent = path.dirname(absolute)
|
|
502
|
+
const basename = path.basename(absolute)
|
|
503
|
+
const noFollow = constants.O_NOFOLLOW ?? 0
|
|
504
|
+
const directory = await open(parent, constants.O_RDONLY | constants.O_DIRECTORY | noFollow).catch((error) => {
|
|
505
|
+
if (isNotFoundError(error))
|
|
506
|
+
throw new Error(`write/edit parent directory does not exist for anchored output: ${parent}`)
|
|
507
|
+
throw error
|
|
508
|
+
})
|
|
509
|
+
let targetHandle: FileHandle | undefined
|
|
510
|
+
let targetIdentity: { dev: number; ino: number } | undefined
|
|
511
|
+
try {
|
|
512
|
+
const fdRoot = '/proc/self/fd'
|
|
513
|
+
const resolvedParent = await realpath(`${fdRoot}/${directory.fd}`)
|
|
514
|
+
enforceCanonicalSecretDenial({
|
|
515
|
+
tool: options.tool,
|
|
516
|
+
args: { path: path.join(resolvedParent, basename) },
|
|
517
|
+
agentDir: options.agentDir,
|
|
518
|
+
})
|
|
519
|
+
const anchored = `${fdRoot}/${directory.fd}/${basename}`
|
|
520
|
+
targetHandle = await open(anchored, constants.O_RDWR | noFollow).catch((error) => {
|
|
521
|
+
if (isNotFoundError(error)) return undefined
|
|
522
|
+
throw error
|
|
523
|
+
})
|
|
524
|
+
let executionPath = anchored
|
|
525
|
+
if (targetHandle !== undefined) {
|
|
526
|
+
const inspected = await targetHandle.stat()
|
|
527
|
+
if (!inspected.isFile() || inspected.nlink !== 1) {
|
|
528
|
+
throw new Error(`write/edit output is not a single-link regular file: ${original}`)
|
|
529
|
+
}
|
|
530
|
+
targetIdentity = { dev: inspected.dev, ino: inspected.ino }
|
|
531
|
+
const resolved = await realpath(`${fdRoot}/${targetHandle.fd}`)
|
|
532
|
+
enforceCanonicalSecretDenial({ tool: options.tool, args: { path: resolved }, agentDir: options.agentDir })
|
|
533
|
+
executionPath = `${fdRoot}/${targetHandle.fd}`
|
|
534
|
+
}
|
|
535
|
+
target.set(executionPath)
|
|
536
|
+
let cleaned = false
|
|
537
|
+
return {
|
|
538
|
+
restoreResult(result) {
|
|
539
|
+
return replaceResultPath(result, { original, pinned: executionPath })
|
|
540
|
+
},
|
|
541
|
+
async cleanup() {
|
|
542
|
+
if (cleaned) return
|
|
543
|
+
cleaned = true
|
|
544
|
+
let verified: FileHandle | undefined
|
|
545
|
+
let verifyError: unknown
|
|
546
|
+
try {
|
|
547
|
+
verified = await open(anchored, constants.O_RDONLY | noFollow)
|
|
548
|
+
const inspected = await verified.stat()
|
|
549
|
+
if (!inspected.isFile() || inspected.nlink !== 1) {
|
|
550
|
+
throw new Error(`write/edit output is not a single-link regular file: ${original}`)
|
|
551
|
+
}
|
|
552
|
+
if (
|
|
553
|
+
targetIdentity !== undefined &&
|
|
554
|
+
(inspected.dev !== targetIdentity.dev || inspected.ino !== targetIdentity.ino)
|
|
555
|
+
) {
|
|
556
|
+
throw new Error(`write/edit output destination changed during execution: ${original}`)
|
|
557
|
+
}
|
|
558
|
+
const resolved = await realpath(`${fdRoot}/${verified.fd}`)
|
|
559
|
+
enforceCanonicalSecretDenial({ tool: options.tool, args: { path: resolved }, agentDir: options.agentDir })
|
|
560
|
+
} catch (error) {
|
|
561
|
+
if (!(targetIdentity === undefined && isNotFoundError(error))) verifyError = error
|
|
562
|
+
}
|
|
563
|
+
const outcomes = await Promise.allSettled([verified?.close(), targetHandle?.close(), directory.close()])
|
|
564
|
+
const failed = outcomes.find((outcome) => outcome.status === 'rejected')
|
|
565
|
+
if (verifyError !== undefined) throw verifyError
|
|
566
|
+
if (failed?.status === 'rejected') throw failed.reason
|
|
567
|
+
},
|
|
568
|
+
}
|
|
569
|
+
} catch (error) {
|
|
570
|
+
await Promise.allSettled([targetHandle?.close(), directory.close()])
|
|
571
|
+
throw error
|
|
572
|
+
}
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
export async function writeFileAnchored(options: {
|
|
576
|
+
targetPath: string
|
|
577
|
+
data: Uint8Array
|
|
578
|
+
agentDir: string
|
|
579
|
+
tool: string
|
|
580
|
+
}): Promise<void> {
|
|
581
|
+
const absolute = path.resolve(options.targetPath)
|
|
582
|
+
enforceCanonicalSecretDenial({ tool: options.tool, args: { path: absolute }, agentDir: options.agentDir })
|
|
583
|
+
if (process.platform !== 'linux') {
|
|
584
|
+
throw new Error('safe attachment writes require Linux inode anchoring; refusing an unanchored destination')
|
|
585
|
+
}
|
|
586
|
+
const parent = await createAndOpenAnchoredDirectory(path.dirname(absolute))
|
|
587
|
+
let output: FileHandle | undefined
|
|
588
|
+
let operationError: unknown
|
|
589
|
+
let cleanupError: unknown
|
|
590
|
+
try {
|
|
591
|
+
const anchored = `/proc/self/fd/${parent.fd}/${path.basename(absolute)}`
|
|
592
|
+
output = await open(anchored, constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW, 0o600)
|
|
593
|
+
const opened = await output.stat()
|
|
594
|
+
if (!opened.isFile() || opened.nlink !== 1)
|
|
595
|
+
throw new Error('attachment destination is not a single-link regular file')
|
|
596
|
+
const resolved = await realpath(`/proc/self/fd/${output.fd}`)
|
|
597
|
+
enforceCanonicalSecretDenial({ tool: options.tool, args: { path: resolved }, agentDir: options.agentDir })
|
|
598
|
+
await output.truncate(0)
|
|
599
|
+
await output.writeFile(options.data)
|
|
600
|
+
} catch (error) {
|
|
601
|
+
operationError = error
|
|
602
|
+
} finally {
|
|
603
|
+
const outcomes = await Promise.allSettled([output?.close(), parent.close()])
|
|
604
|
+
const failed = outcomes.find((outcome) => outcome.status === 'rejected')
|
|
605
|
+
if (failed?.status === 'rejected') cleanupError = failed.reason
|
|
606
|
+
}
|
|
607
|
+
if (operationError !== undefined) throw operationError
|
|
608
|
+
if (cleanupError !== undefined) throw cleanupError
|
|
609
|
+
}
|
|
610
|
+
|
|
611
|
+
export async function writeToolOutputNoFollow(targetPath: string, content: string): Promise<void> {
|
|
612
|
+
const trustedDescriptorPath = /^\/proc\/self\/fd\/\d+$/.test(targetPath)
|
|
613
|
+
const flags = trustedDescriptorPath
|
|
614
|
+
? constants.O_WRONLY | constants.O_TRUNC
|
|
615
|
+
: constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW
|
|
616
|
+
const output = await open(targetPath, flags, 0o666)
|
|
617
|
+
try {
|
|
618
|
+
await output.writeFile(content, 'utf8')
|
|
619
|
+
} finally {
|
|
620
|
+
await output.close()
|
|
621
|
+
}
|
|
622
|
+
}
|
|
623
|
+
|
|
624
|
+
async function createAndOpenAnchoredDirectory(absolute: string): Promise<FileHandle> {
|
|
625
|
+
if (!path.isAbsolute(absolute)) throw new Error(`anchored directory must be absolute: ${absolute}`)
|
|
626
|
+
const components = absolute.split(path.sep).filter(Boolean)
|
|
627
|
+
let current = await open(path.parse(absolute).root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
|
|
628
|
+
try {
|
|
629
|
+
for (const component of components) {
|
|
630
|
+
const anchored = `/proc/self/fd/${current.fd}/${component}`
|
|
631
|
+
let next: FileHandle
|
|
632
|
+
try {
|
|
633
|
+
next = await open(anchored, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
|
|
634
|
+
} catch (error) {
|
|
635
|
+
if (!isNotFoundError(error)) throw error
|
|
636
|
+
await mkdir(anchored, { mode: 0o700 })
|
|
637
|
+
next = await open(anchored, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
|
|
638
|
+
}
|
|
639
|
+
await current.close()
|
|
640
|
+
current = next
|
|
641
|
+
}
|
|
642
|
+
return current
|
|
643
|
+
} catch (error) {
|
|
644
|
+
await current.close()
|
|
645
|
+
throw error
|
|
646
|
+
}
|
|
647
|
+
}
|
|
648
|
+
|
|
649
|
+
function isNotFoundError(error: unknown): boolean {
|
|
650
|
+
return error instanceof Error && 'code' in error && error.code === 'ENOENT'
|
|
651
|
+
}
|
|
652
|
+
|
|
653
|
+
async function streamSnapshot(
|
|
654
|
+
source: FileHandle,
|
|
655
|
+
destination: string,
|
|
656
|
+
original: string,
|
|
657
|
+
maxBytes: number,
|
|
658
|
+
previouslyCopied: number,
|
|
659
|
+
lease: BudgetLease,
|
|
660
|
+
operandCount: number,
|
|
661
|
+
signal?: AbortSignal,
|
|
662
|
+
): Promise<number> {
|
|
663
|
+
let copied = 0
|
|
664
|
+
const limiter = new Transform({
|
|
665
|
+
transform(chunk: Buffer, _encoding, callback) {
|
|
666
|
+
copied += chunk.byteLength
|
|
667
|
+
if (copied > maxBytes) {
|
|
668
|
+
callback(inputTooLarge(original, copied, maxBytes))
|
|
669
|
+
return
|
|
670
|
+
}
|
|
671
|
+
if (previouslyCopied + copied > maxBytes) {
|
|
672
|
+
callback(aggregateInputTooLarge(previouslyCopied + copied, maxBytes))
|
|
673
|
+
return
|
|
674
|
+
}
|
|
675
|
+
if (!lease.resize(previouslyCopied + copied, operandCount)) {
|
|
676
|
+
callback(processBudgetGrowthExceeded(previouslyCopied + copied))
|
|
677
|
+
return
|
|
678
|
+
}
|
|
679
|
+
callback(null, chunk)
|
|
680
|
+
},
|
|
681
|
+
})
|
|
682
|
+
await pipeline(
|
|
683
|
+
source.createReadStream({ autoClose: false, start: 0 }),
|
|
684
|
+
limiter,
|
|
685
|
+
createWriteStream(destination, {
|
|
686
|
+
flags: 'wx',
|
|
687
|
+
mode: 0o400,
|
|
688
|
+
}),
|
|
689
|
+
{ signal },
|
|
690
|
+
)
|
|
691
|
+
return copied
|
|
692
|
+
}
|
|
693
|
+
|
|
694
|
+
async function snapshotDirectoryTree(options: {
|
|
695
|
+
source: VerifiedInput
|
|
696
|
+
destination: string
|
|
697
|
+
agentDir: string
|
|
698
|
+
tool: string
|
|
699
|
+
maxBytes: number
|
|
700
|
+
previouslyCopied: number
|
|
701
|
+
lease: BudgetLease
|
|
702
|
+
operandCount: number
|
|
703
|
+
hidden?: HiddenPaths
|
|
704
|
+
signal?: AbortSignal
|
|
705
|
+
}): Promise<number> {
|
|
706
|
+
if (process.platform !== 'linux') {
|
|
707
|
+
throw new Error('directory tool inputs require Linux inode anchoring; refusing an unanchored traversal')
|
|
708
|
+
}
|
|
709
|
+
const root = await open(options.source.resolved, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
|
|
710
|
+
try {
|
|
711
|
+
const opened = await root.stat()
|
|
712
|
+
if (opened.dev !== options.source.dev || opened.ino !== options.source.ino) {
|
|
713
|
+
throw new Error(`tool input changed while waiting for snapshot capacity: ${options.source.original}`)
|
|
714
|
+
}
|
|
715
|
+
await mkdir(options.destination, { mode: 0o700 })
|
|
716
|
+
const state = { copied: 0, entries: 0 }
|
|
717
|
+
const openedRoot = await realpath(`/proc/self/fd/${root.fd}`)
|
|
718
|
+
const realAgentDir = await realpath(options.agentDir)
|
|
719
|
+
await snapshotOpenedDirectory(root, options.destination, options, state, openedRoot === realAgentDir)
|
|
720
|
+
await chmod(options.destination, 0o500)
|
|
721
|
+
return state.copied
|
|
722
|
+
} finally {
|
|
723
|
+
await root.close()
|
|
724
|
+
}
|
|
725
|
+
}
|
|
726
|
+
|
|
727
|
+
async function snapshotOpenedDirectory(
|
|
728
|
+
directory: FileHandle,
|
|
729
|
+
destination: string,
|
|
730
|
+
options: Parameters<typeof snapshotDirectoryTree>[0],
|
|
731
|
+
state: { copied: number; entries: number },
|
|
732
|
+
isAgentRoot: boolean,
|
|
733
|
+
): Promise<void> {
|
|
734
|
+
const sourceRoot = `/proc/self/fd/${directory.fd}`
|
|
735
|
+
const sourcePath = await realpath(sourceRoot)
|
|
736
|
+
const entries = await readdir(sourceRoot, { withFileTypes: true })
|
|
737
|
+
for (const entry of entries) {
|
|
738
|
+
if (options.signal?.aborted === true) throw abortError(options.signal)
|
|
739
|
+
if (isAgentRoot && AGENT_ROOT_SNAPSHOT_EXCLUDED_DIRS.has(entry.name)) continue
|
|
740
|
+
state.entries += 1
|
|
741
|
+
if (state.entries > TREE_SNAPSHOT_MAX_ENTRIES) {
|
|
742
|
+
throw new Error(`directory snapshot exceeds entry limit (${state.entries} > ${TREE_SNAPSHOT_MAX_ENTRIES})`)
|
|
743
|
+
}
|
|
744
|
+
const anchored = `${sourceRoot}/${entry.name}`
|
|
745
|
+
const target = path.join(destination, entry.name)
|
|
746
|
+
const candidate = path.join(sourcePath, entry.name)
|
|
747
|
+
if (entry.isSymbolicLink()) {
|
|
748
|
+
if (isDeniedSnapshotPath(candidate, options)) continue
|
|
749
|
+
throw new Error(`directory snapshot refuses symbolic link: ${entry.name}`)
|
|
750
|
+
}
|
|
751
|
+
if (entry.isDirectory()) {
|
|
752
|
+
if (isDeniedSnapshotPath(candidate, options)) continue
|
|
753
|
+
const child = await open(anchored, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
|
|
754
|
+
try {
|
|
755
|
+
const resolved = await realpath(`/proc/self/fd/${child.fd}`)
|
|
756
|
+
if (isDeniedSnapshotPath(resolved, options)) continue
|
|
757
|
+
await mkdir(target, { mode: 0o700 })
|
|
758
|
+
await snapshotOpenedDirectory(child, target, options, state, false)
|
|
759
|
+
await chmod(target, 0o500)
|
|
760
|
+
} finally {
|
|
761
|
+
await child.close()
|
|
762
|
+
}
|
|
763
|
+
continue
|
|
764
|
+
}
|
|
765
|
+
if (!entry.isFile()) {
|
|
766
|
+
if (isDeniedSnapshotPath(candidate, options)) continue
|
|
767
|
+
throw new Error(`directory snapshot refuses non-regular entry: ${entry.name}`)
|
|
768
|
+
}
|
|
769
|
+
const source = await open(anchored, constants.O_RDONLY | constants.O_NOFOLLOW)
|
|
770
|
+
try {
|
|
771
|
+
const opened = await source.stat()
|
|
772
|
+
assertSingleLinkRegularFile(opened, candidate)
|
|
773
|
+
const resolved = await realpath(`/proc/self/fd/${source.fd}`)
|
|
774
|
+
if (isDeniedSnapshotPath(resolved, options)) continue
|
|
775
|
+
state.copied += await streamSnapshot(
|
|
776
|
+
source,
|
|
777
|
+
target,
|
|
778
|
+
resolved,
|
|
779
|
+
options.maxBytes,
|
|
780
|
+
options.previouslyCopied + state.copied,
|
|
781
|
+
options.lease,
|
|
782
|
+
options.operandCount,
|
|
783
|
+
options.signal,
|
|
784
|
+
)
|
|
785
|
+
await chmod(target, 0o400)
|
|
786
|
+
} finally {
|
|
787
|
+
await source.close()
|
|
788
|
+
}
|
|
789
|
+
}
|
|
790
|
+
}
|
|
791
|
+
|
|
792
|
+
function assertSingleLinkRegularFile(stats: Stats, original: string): void {
|
|
793
|
+
if (!stats.isFile()) throw new Error(`tool input changed to a non-regular file before snapshot: ${original}`)
|
|
794
|
+
if (stats.nlink !== 1) {
|
|
795
|
+
throw new Error(
|
|
796
|
+
`tool input has ${stats.nlink} hard links and cannot be snapshotted safely; copy it to a unique regular file before retrying: ${original}`,
|
|
797
|
+
)
|
|
798
|
+
}
|
|
799
|
+
}
|
|
800
|
+
|
|
801
|
+
function maxInputBytes(tool: string): number {
|
|
802
|
+
if (tool === 'look_at') return TOOL_INPUT_MAX_BYTES.look_at
|
|
803
|
+
if (tool === 'channel_send' || tool === 'channel_reply') return TOOL_INPUT_MAX_BYTES.channel_upload
|
|
804
|
+
return TOOL_INPUT_MAX_BYTES.read
|
|
805
|
+
}
|
|
806
|
+
|
|
807
|
+
function maxInputCount(tool: string): number {
|
|
808
|
+
if (tool === 'look_at') return TOOL_INPUT_MAX_COUNT.look_at
|
|
809
|
+
if (tool === 'channel_send' || tool === 'channel_reply') return TOOL_INPUT_MAX_COUNT.channel_upload
|
|
810
|
+
return TOOL_INPUT_MAX_COUNT.read
|
|
811
|
+
}
|
|
812
|
+
|
|
813
|
+
function isOutputTool(tool: string): boolean {
|
|
814
|
+
return tool === 'write' || tool === 'edit'
|
|
815
|
+
}
|
|
816
|
+
|
|
817
|
+
function isTreeInputTool(tool: string): boolean {
|
|
818
|
+
return tool === 'grep' || tool === 'find' || tool === 'ls'
|
|
819
|
+
}
|
|
820
|
+
|
|
821
|
+
function isAmbiguousUndeclaredLocalOperand(value: string, agentDir: string, key: string): boolean {
|
|
822
|
+
if (isFileShapedKey(key)) return true
|
|
823
|
+
if (value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value) || /^(?:\\\\|\/\/)[^\\/]/.test(value)) return true
|
|
824
|
+
if (value.startsWith('./') || value.startsWith('../')) return true
|
|
825
|
+
if (/[\\/]/.test(value)) return true
|
|
826
|
+
const basename = path.posix.basename(value.replaceAll('\\', '/'))
|
|
827
|
+
if (CANONICAL_AGENT_SECRET_FILES.includes(basename as (typeof CANONICAL_AGENT_SECRET_FILES)[number])) return true
|
|
828
|
+
if (/^[^./\\\s][^/\\\s]*\.[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) return true
|
|
829
|
+
|
|
830
|
+
const resolved = path.resolve(agentDir, value)
|
|
831
|
+
try {
|
|
832
|
+
lstatSync(resolved)
|
|
833
|
+
return true
|
|
834
|
+
} catch (error) {
|
|
835
|
+
return !isNotFoundError(error)
|
|
836
|
+
}
|
|
837
|
+
}
|
|
838
|
+
|
|
839
|
+
function isFileShapedKey(key: string): boolean {
|
|
840
|
+
const normalized = key.replaceAll(/[-_]/g, '').toLocaleLowerCase()
|
|
841
|
+
return (
|
|
842
|
+
normalized === 'path' ||
|
|
843
|
+
normalized === 'file' ||
|
|
844
|
+
normalized === 'filepath' ||
|
|
845
|
+
normalized === 'filename' ||
|
|
846
|
+
normalized.endsWith('path') ||
|
|
847
|
+
normalized.endsWith('filepath') ||
|
|
848
|
+
normalized.endsWith('filename')
|
|
849
|
+
)
|
|
850
|
+
}
|
|
851
|
+
|
|
852
|
+
function isSemanticGenericString(key: string, value: string): boolean {
|
|
853
|
+
if (isExplicitNonFileUrl(value)) return true
|
|
854
|
+
if (key === 'path' && isSafeApiRoute(value)) return true
|
|
855
|
+
return key === 'repository' && isSafeRepositorySlug(value)
|
|
856
|
+
}
|
|
857
|
+
|
|
858
|
+
function isExplicitNonFileUrl(value: string): boolean {
|
|
859
|
+
// Trim to match the file:/URL detection elsewhere: a leading-whitespace
|
|
860
|
+
// " https://…" is still a non-file URL, and a " file://…" must NOT be
|
|
861
|
+
// treated as one (it pins). Windows-drive and file: exclusions run on trimmed.
|
|
862
|
+
const trimmed = value.trim()
|
|
863
|
+
if (/^[A-Za-z]:[\\/]/.test(trimmed)) return false
|
|
864
|
+
if (!/^[A-Za-z][A-Za-z0-9+.-]*:/.test(trimmed) || trimmed.toLocaleLowerCase().startsWith('file:')) return false
|
|
865
|
+
try {
|
|
866
|
+
return new URL(trimmed).protocol !== 'file:'
|
|
867
|
+
} catch {
|
|
868
|
+
return false
|
|
869
|
+
}
|
|
870
|
+
}
|
|
871
|
+
|
|
872
|
+
function isSafeApiRoute(value: string): boolean {
|
|
873
|
+
if (!/^\/v\d+\//.test(value) || value.includes('\\') || value.includes('//')) return false
|
|
874
|
+
const segments = value.split('/')
|
|
875
|
+
for (const segment of segments.slice(1)) {
|
|
876
|
+
if (segment.length === 0) return false
|
|
877
|
+
let decoded: string
|
|
878
|
+
try {
|
|
879
|
+
decoded = decodeURIComponent(segment)
|
|
880
|
+
} catch {
|
|
881
|
+
return false
|
|
882
|
+
}
|
|
883
|
+
if (decoded === '.' || decoded === '..' || decoded.includes('/') || decoded.includes('\\')) return false
|
|
884
|
+
}
|
|
885
|
+
return true
|
|
886
|
+
}
|
|
887
|
+
|
|
888
|
+
function isSafeRepositorySlug(value: string): boolean {
|
|
889
|
+
const match = /^([A-Za-z0-9](?:[A-Za-z0-9_.-]*[A-Za-z0-9])?)\/([A-Za-z0-9](?:[A-Za-z0-9_.-]*[A-Za-z0-9])?)$/.exec(
|
|
890
|
+
value,
|
|
891
|
+
)
|
|
892
|
+
return match !== null && match[1] !== '.' && match[1] !== '..' && match[2] !== '.' && match[2] !== '..'
|
|
893
|
+
}
|
|
894
|
+
|
|
895
|
+
function isDeniedSnapshotPath(
|
|
896
|
+
candidate: string,
|
|
897
|
+
options: { agentDir: string; tool: string; hidden?: HiddenPaths },
|
|
898
|
+
): boolean {
|
|
899
|
+
return (
|
|
900
|
+
checkPrivateSurfaceReadGuard({
|
|
901
|
+
tool: options.tool,
|
|
902
|
+
args: { path: candidate },
|
|
903
|
+
agentDir: options.agentDir,
|
|
904
|
+
hidden: options.hidden ?? { dirs: [], files: [] },
|
|
905
|
+
}) !== undefined
|
|
906
|
+
)
|
|
907
|
+
}
|
|
908
|
+
|
|
909
|
+
function normalizeFileReference(value: string): string {
|
|
910
|
+
const trimmed = value.trim()
|
|
911
|
+
if (!trimmed.toLocaleLowerCase().startsWith('file:')) return value
|
|
912
|
+
try {
|
|
913
|
+
return fileURLToPath(trimmed)
|
|
914
|
+
} catch {
|
|
915
|
+
throw new Error(`invalid file URI: ${value}`)
|
|
916
|
+
}
|
|
917
|
+
}
|
|
918
|
+
|
|
919
|
+
function inputTooLarge(original: string, size: number, maxBytes: number): Error {
|
|
920
|
+
return new Error(`tool input is too large: ${original} (${size} bytes > ${maxBytes} byte limit)`)
|
|
921
|
+
}
|
|
922
|
+
|
|
923
|
+
function aggregateInputTooLarge(size: number, maxBytes: number): Error {
|
|
924
|
+
return new Error(`tool inputs exceed the aggregate byte limit (${size} bytes > ${maxBytes} byte limit)`)
|
|
925
|
+
}
|
|
926
|
+
|
|
927
|
+
function processBudgetGrowthExceeded(size: number): Error {
|
|
928
|
+
return new Error(`tool snapshot growth exceeds the process-wide pinned byte budget (${size} bytes requested)`)
|
|
929
|
+
}
|
|
930
|
+
|
|
931
|
+
function inputCountTooLarge(count: number, maxCount: number): Error {
|
|
932
|
+
return new Error(`tool input count exceeds the per-invocation limit (${count} > ${maxCount})`)
|
|
933
|
+
}
|
|
934
|
+
|
|
935
|
+
function replaceResultPath(result: ToolResult, rewrite: Rewrite): ToolResult {
|
|
936
|
+
const content = result.content.map((part) =>
|
|
937
|
+
part.type === 'text' ? { ...part, text: part.text.split(rewrite.pinned).join(rewrite.original) } : part,
|
|
938
|
+
)
|
|
939
|
+
const details = replaceDeep(result.details, rewrite)
|
|
940
|
+
return { content, details }
|
|
941
|
+
}
|
|
942
|
+
|
|
943
|
+
function replaceDeep(value: unknown, rewrite: Rewrite): unknown {
|
|
944
|
+
if (typeof value === 'string') return value.split(rewrite.pinned).join(rewrite.original)
|
|
945
|
+
if (Array.isArray(value)) return value.map((item) => replaceDeep(item, rewrite))
|
|
946
|
+
if (isRecord(value))
|
|
947
|
+
return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, replaceDeep(item, rewrite)]))
|
|
948
|
+
return value
|
|
949
|
+
}
|
|
950
|
+
|
|
951
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
952
|
+
return value !== null && typeof value === 'object'
|
|
953
|
+
}
|
|
954
|
+
|
|
955
|
+
type BudgetRequest = {
|
|
956
|
+
bytes: number
|
|
957
|
+
count: number
|
|
958
|
+
signal?: AbortSignal
|
|
959
|
+
resolve(lease: BudgetLease): void
|
|
960
|
+
reject(error: Error): void
|
|
961
|
+
onAbort?: () => void
|
|
962
|
+
}
|
|
963
|
+
|
|
964
|
+
type BudgetLease = {
|
|
965
|
+
resize(bytes: number, count: number): boolean
|
|
966
|
+
release(): void
|
|
967
|
+
}
|
|
968
|
+
|
|
969
|
+
class PinnedSnapshotBudget {
|
|
970
|
+
private bytes = 0
|
|
971
|
+
private count = 0
|
|
972
|
+
private readonly queue: BudgetRequest[] = []
|
|
973
|
+
|
|
974
|
+
async acquire(bytes: number, count: number, signal?: AbortSignal): Promise<BudgetLease> {
|
|
975
|
+
if (bytes > PINNED_SNAPSHOT_GLOBAL_MAX_BYTES || count > PINNED_SNAPSHOT_GLOBAL_MAX_COUNT) {
|
|
976
|
+
throw new Error('tool inputs exceed the process-wide pinned snapshot budget')
|
|
977
|
+
}
|
|
978
|
+
if (signal?.aborted === true) throw abortError(signal)
|
|
979
|
+
if (this.queue.length >= PINNED_SNAPSHOT_MAX_WAITERS) {
|
|
980
|
+
throw new Error(`pinned snapshot waiter queue is full (${PINNED_SNAPSHOT_MAX_WAITERS} waiters)`)
|
|
981
|
+
}
|
|
982
|
+
return await new Promise<BudgetLease>((resolve, reject) => {
|
|
983
|
+
const request: BudgetRequest = { bytes, count, signal, resolve, reject }
|
|
984
|
+
if (signal !== undefined) {
|
|
985
|
+
request.onAbort = () => {
|
|
986
|
+
const index = this.queue.indexOf(request)
|
|
987
|
+
if (index === -1) return
|
|
988
|
+
this.queue.splice(index, 1)
|
|
989
|
+
reject(abortError(signal))
|
|
990
|
+
this.drain()
|
|
991
|
+
}
|
|
992
|
+
signal.addEventListener('abort', request.onAbort, { once: true })
|
|
993
|
+
}
|
|
994
|
+
this.queue.push(request)
|
|
995
|
+
this.drain()
|
|
996
|
+
})
|
|
997
|
+
}
|
|
998
|
+
|
|
999
|
+
private drain(): void {
|
|
1000
|
+
while (this.queue.length > 0) {
|
|
1001
|
+
const next = this.queue[0] as BudgetRequest
|
|
1002
|
+
if (
|
|
1003
|
+
this.bytes + next.bytes > PINNED_SNAPSHOT_GLOBAL_MAX_BYTES ||
|
|
1004
|
+
this.count + next.count > PINNED_SNAPSHOT_GLOBAL_MAX_COUNT
|
|
1005
|
+
) {
|
|
1006
|
+
return
|
|
1007
|
+
}
|
|
1008
|
+
this.queue.shift()
|
|
1009
|
+
if (next.onAbort !== undefined) next.signal?.removeEventListener('abort', next.onAbort)
|
|
1010
|
+
this.bytes += next.bytes
|
|
1011
|
+
this.count += next.count
|
|
1012
|
+
let released = false
|
|
1013
|
+
let leasedBytes = next.bytes
|
|
1014
|
+
let leasedCount = next.count
|
|
1015
|
+
next.resolve({
|
|
1016
|
+
resize: (bytes, count) => {
|
|
1017
|
+
if (released) return false
|
|
1018
|
+
const byteDelta = bytes - leasedBytes
|
|
1019
|
+
const countDelta = count - leasedCount
|
|
1020
|
+
if (
|
|
1021
|
+
this.bytes + byteDelta > PINNED_SNAPSHOT_GLOBAL_MAX_BYTES ||
|
|
1022
|
+
this.count + countDelta > PINNED_SNAPSHOT_GLOBAL_MAX_COUNT
|
|
1023
|
+
) {
|
|
1024
|
+
return false
|
|
1025
|
+
}
|
|
1026
|
+
this.bytes += byteDelta
|
|
1027
|
+
this.count += countDelta
|
|
1028
|
+
leasedBytes = bytes
|
|
1029
|
+
leasedCount = count
|
|
1030
|
+
this.drain()
|
|
1031
|
+
return true
|
|
1032
|
+
},
|
|
1033
|
+
release: () => {
|
|
1034
|
+
if (released) return
|
|
1035
|
+
released = true
|
|
1036
|
+
this.bytes -= leasedBytes
|
|
1037
|
+
this.count -= leasedCount
|
|
1038
|
+
this.drain()
|
|
1039
|
+
},
|
|
1040
|
+
})
|
|
1041
|
+
}
|
|
1042
|
+
}
|
|
1043
|
+
}
|
|
1044
|
+
|
|
1045
|
+
const pinnedSnapshotBudget = new PinnedSnapshotBudget()
|
|
1046
|
+
|
|
1047
|
+
function abortError(signal: AbortSignal): Error {
|
|
1048
|
+
const reason = signal.reason
|
|
1049
|
+
return new Error(`pinned snapshot wait aborted${reason === undefined ? '' : `: ${String(reason)}`}`)
|
|
1050
|
+
}
|