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.
Files changed (142) hide show
  1. package/README.md +1 -1
  2. package/package.json +2 -1
  3. package/src/agent/git-nudge.ts +2 -1
  4. package/src/agent/index.ts +44 -30
  5. package/src/agent/live-subagents.ts +18 -0
  6. package/src/agent/multimodal/index.ts +1 -1
  7. package/src/agent/multimodal/look-at.ts +78 -44
  8. package/src/agent/multimodal/looker.ts +151 -39
  9. package/src/agent/network/response-body.ts +26 -0
  10. package/src/agent/network/safe-http.ts +198 -0
  11. package/src/agent/plugin-tools.ts +379 -157
  12. package/src/agent/provider-error.ts +52 -1
  13. package/src/agent/restart/index.ts +61 -40
  14. package/src/agent/restart-handoff/index.ts +73 -4
  15. package/src/agent/reviewer-bash-policy.ts +42 -1
  16. package/src/agent/session-origin.ts +2 -0
  17. package/src/agent/subagent-drain.ts +117 -7
  18. package/src/agent/subagents.ts +49 -16
  19. package/src/agent/throttle-circuit.ts +25 -5
  20. package/src/agent/tool-error-remediation.ts +72 -0
  21. package/src/agent/tool-file-safety.ts +1050 -0
  22. package/src/agent/tools/channel-fetch-attachment.ts +10 -3
  23. package/src/agent/tools/ddg.ts +16 -2
  24. package/src/agent/tools/post-github-review.ts +199 -0
  25. package/src/agent/tools/spawn-subagent.ts +21 -18
  26. package/src/agent/tools/webfetch/fetch.ts +143 -183
  27. package/src/agent/tools/webfetch/tool.ts +2 -3
  28. package/src/agent/tools/websearch.ts +23 -2
  29. package/src/agent/tools-without-local-file-operands.ts +27 -0
  30. package/src/agent/turn-runner.ts +86 -6
  31. package/src/bundled-plugins/backup/index.ts +2 -1
  32. package/src/bundled-plugins/backup/runner.ts +2 -1
  33. package/src/bundled-plugins/doc-render/render.ts +93 -12
  34. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  35. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  36. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  37. package/src/bundled-plugins/github-cli-auth/index.ts +131 -135
  38. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  39. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  40. package/src/bundled-plugins/memory/README.md +23 -11
  41. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  42. package/src/bundled-plugins/memory/citations.ts +22 -9
  43. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  44. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  45. package/src/bundled-plugins/memory/index.ts +0 -4
  46. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  47. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  48. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  49. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  50. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  51. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  52. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  53. package/src/bundled-plugins/researcher/write-report.ts +6 -3
  54. package/src/bundled-plugins/reviewer/index.ts +2 -2
  55. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  56. package/src/bundled-plugins/reviewer/skills/code-review.ts +19 -9
  57. package/src/bundled-plugins/scout/scout.ts +8 -0
  58. package/src/bundled-plugins/security/index.ts +4 -4
  59. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  60. package/src/bundled-plugins/security/policies/private-surface-read.ts +220 -29
  61. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  62. package/src/bundled-plugins/security/policies/ssrf.ts +29 -9
  63. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  64. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  65. package/src/channels/adapters/discord-bot.ts +66 -6
  66. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  67. package/src/channels/adapters/discord-id.ts +4 -0
  68. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  69. package/src/channels/adapters/discord.ts +57 -7
  70. package/src/channels/adapters/github/auth-app.ts +41 -12
  71. package/src/channels/adapters/github/index.ts +23 -11
  72. package/src/channels/adapters/github/review-submitter.ts +302 -0
  73. package/src/channels/adapters/kakaotalk-channel-resolver.ts +5 -3
  74. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  75. package/src/channels/adapters/kakaotalk-typing.ts +17 -15
  76. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  77. package/src/channels/adapters/slack-bot.ts +19 -8
  78. package/src/channels/adapters/slack-classify.ts +21 -2
  79. package/src/channels/adapters/slack.ts +59 -7
  80. package/src/channels/adapters/telegram-bot.ts +18 -5
  81. package/src/channels/adapters/webex-bot.ts +8 -3
  82. package/src/channels/adapters/webex.ts +8 -3
  83. package/src/channels/fetch-attachment.ts +43 -0
  84. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  85. package/src/channels/github-token-bridge.ts +10 -3
  86. package/src/channels/manager.ts +9 -0
  87. package/src/channels/router.ts +248 -6
  88. package/src/channels/types.ts +28 -1
  89. package/src/cli/channel.ts +1 -1
  90. package/src/cli/init.ts +1 -1
  91. package/src/cli/model.ts +57 -7
  92. package/src/compose/stop.ts +17 -5
  93. package/src/config/config.ts +6 -6
  94. package/src/config/models-mutation.ts +13 -1
  95. package/src/config/providers.ts +176 -0
  96. package/src/container/start.ts +49 -10
  97. package/src/doctor/checks.ts +3 -1
  98. package/src/doctor/commit.ts +2 -1
  99. package/src/doctor/file-ownership.ts +52 -0
  100. package/src/dreams/git.ts +2 -1
  101. package/src/git/hookless.ts +5 -0
  102. package/src/git/reconcile-ignored.ts +18 -5
  103. package/src/git/secret-history.ts +371 -0
  104. package/src/git/system-commit.ts +12 -6
  105. package/src/init/dockerfile.ts +86 -5
  106. package/src/init/index.ts +17 -5
  107. package/src/init/models-dev.ts +4 -0
  108. package/src/init/validate-api-key.ts +2 -0
  109. package/src/mcp/tools.ts +16 -3
  110. package/src/permissions/builtins.ts +3 -1
  111. package/src/plugin/context.ts +2 -0
  112. package/src/plugin/index.ts +1 -0
  113. package/src/plugin/manager.ts +4 -0
  114. package/src/plugin/types.ts +21 -0
  115. package/src/run/index.ts +40 -0
  116. package/src/run/llm-fetch-observer.ts +41 -4
  117. package/src/sandbox/build.ts +37 -15
  118. package/src/sandbox/canonical-secrets.ts +18 -0
  119. package/src/sandbox/env-exposure.ts +80 -0
  120. package/src/sandbox/errors.ts +13 -6
  121. package/src/sandbox/hidden-paths.ts +102 -44
  122. package/src/sandbox/index.ts +22 -4
  123. package/src/sandbox/package-install.ts +3 -27
  124. package/src/sandbox/policy.ts +11 -25
  125. package/src/sandbox/privileged-runtime.ts +255 -0
  126. package/src/sandbox/session-tmp.ts +8 -2
  127. package/src/sandbox/writable-zones.ts +204 -140
  128. package/src/secrets/index.ts +8 -0
  129. package/src/secrets/refresh-provider-oauth.ts +128 -0
  130. package/src/server/command-runner.ts +48 -4
  131. package/src/server/index.ts +4 -0
  132. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  133. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  134. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  135. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  136. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  137. package/src/skills/typeclaw-config/SKILL.md +5 -5
  138. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  139. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  140. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  141. package/src/skills/typeclaw-permissions/SKILL.md +19 -15
  142. 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
+ }