typeclaw 0.46.0 → 0.46.1

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 (52) hide show
  1. package/README.md +1 -1
  2. package/package.json +2 -2
  3. package/src/agent/multimodal/looker.ts +11 -1
  4. package/src/agent/network/safe-http.ts +17 -8
  5. package/src/agent/plugin-tools.ts +1 -3
  6. package/src/agent/tool-file-safety.ts +396 -136
  7. package/src/agent/tools/webfetch/fetch.ts +22 -2
  8. package/src/agent/tools-without-local-file-operands.ts +9 -6
  9. package/src/bundled-plugins/backup/README.md +23 -10
  10. package/src/bundled-plugins/backup/git-auth.ts +6 -4
  11. package/src/bundled-plugins/backup/index.ts +83 -43
  12. package/src/bundled-plugins/backup/runner.ts +83 -0
  13. package/src/bundled-plugins/github-cli-auth/git-askpass.ts +74 -26
  14. package/src/bundled-plugins/github-cli-auth/git-command.ts +224 -36
  15. package/src/bundled-plugins/github-cli-auth/graphql-auth-nudge.ts +9 -9
  16. package/src/bundled-plugins/github-cli-auth/index.ts +110 -31
  17. package/src/bundled-plugins/github-cli-auth/token-class.ts +4 -6
  18. package/src/bundled-plugins/memory/README.md +9 -0
  19. package/src/bundled-plugins/memory/vector/embed-threads.ts +36 -0
  20. package/src/bundled-plugins/memory/vector/embedder.ts +19 -1
  21. package/src/bundled-plugins/researcher/write-report.ts +3 -3
  22. package/src/bundled-plugins/security/policies/private-surface-read.ts +610 -50
  23. package/src/bundled-plugins/security/policies/ssrf.ts +119 -34
  24. package/src/channels/adapters/github/inbound.ts +11 -0
  25. package/src/channels/adapters/github/index.ts +48 -54
  26. package/src/channels/adapters/github/reconcile-cooldown-store.ts +178 -0
  27. package/src/channels/adapters/github/reconcile-open-prs.ts +31 -0
  28. package/src/channels/adapters/slack-bot-edit.ts +85 -20
  29. package/src/channels/adapters/slack-bot.ts +7 -2
  30. package/src/channels/adapters/slack-format.ts +245 -0
  31. package/src/channels/github-token-bridge.ts +2 -3
  32. package/src/container/docker-app.ts +42 -13
  33. package/src/container/start.ts +13 -0
  34. package/src/cron/bridge.ts +9 -2
  35. package/src/doctor/checks.ts +5 -2
  36. package/src/git/bound-gc-config.ts +82 -0
  37. package/src/hostd/spawn.ts +133 -47
  38. package/src/init/dockerfile.ts +13 -0
  39. package/src/inspect/replay.ts +21 -9
  40. package/src/inspect/session-list.ts +71 -33
  41. package/src/mcp/tools.ts +1 -0
  42. package/src/network/internal-destinations.ts +267 -0
  43. package/src/plugin/types.ts +3 -2
  44. package/src/sandbox/env-exposure.ts +18 -15
  45. package/src/sandbox/policy.ts +5 -3
  46. package/src/sandbox/privileged-runtime.ts +1 -0
  47. package/src/skills/typeclaw-config/SKILL.md +22 -6
  48. package/src/skills/typeclaw-permissions/SKILL.md +22 -9
  49. package/src/skills/typeclaw-plugins/SKILL.md +37 -0
  50. package/src/usage/scan.ts +11 -2
  51. package/typeclaw.schema.json +5 -0
  52. package/src/git/secret-history.ts +0 -371
@@ -1,13 +1,17 @@
1
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'
2
+ import { chmod, mkdir, mkdtemp, open, readdir, realpath, rm, stat, unlink, type FileHandle } from 'node:fs/promises'
3
3
  import { tmpdir } from 'node:os'
4
4
  import path from 'node:path'
5
5
  import { Transform } from 'node:stream'
6
6
  import { pipeline } from 'node:stream/promises'
7
7
  import { fileURLToPath, pathToFileURL } from 'node:url'
8
8
 
9
- import { checkPrivateSurfaceReadGuard } from '@/bundled-plugins/security/policies/private-surface-read'
10
- import type { ToolFileOperands, ToolResult } from '@/plugin'
9
+ import {
10
+ checkPrivateSurfaceReadGuard,
11
+ createPrivateSurfaceReadIdentityVerifier,
12
+ type PrivateSurfaceIdentityVerifier,
13
+ } from '@/bundled-plugins/security/policies/private-surface-read'
14
+ import type { ToolFileOperands, ToolLogger, ToolResult } from '@/plugin'
11
15
  import { CANONICAL_AGENT_SECRET_FILES } from '@/sandbox/canonical-secrets'
12
16
  import type { HiddenPaths } from '@/sandbox/hidden-paths'
13
17
 
@@ -17,6 +21,7 @@ export { TOOLS_WITHOUT_LOCAL_FILE_OPERANDS }
17
21
 
18
22
  type Rewrite = { original: string; pinned: string }
19
23
  type FileTarget = { get(): string; original: string; set(value: string): void; uri: boolean }
24
+ type OutputTarget = { target: FileTarget; mode: 'reserved' | 'exclusive-create' }
20
25
  type VerifiedInput = {
21
26
  target: FileTarget
22
27
  original: string
@@ -46,6 +51,7 @@ export const TOOL_INPUT_MAX_COUNT = {
46
51
  export const PINNED_SNAPSHOT_GLOBAL_MAX_BYTES = TOOL_INPUT_MAX_BYTES.channel_upload
47
52
  export const PINNED_SNAPSHOT_GLOBAL_MAX_COUNT = TOOL_INPUT_MAX_COUNT.channel_upload
48
53
  export const PINNED_SNAPSHOT_MAX_WAITERS = 32
54
+ const TOOL_OUTPUT_MAX_COUNT = 32
49
55
  const TREE_SNAPSHOT_MAX_ENTRIES = 4096
50
56
  const AGENT_ROOT_SNAPSHOT_EXCLUDED_DIRS = new Set(['.git', '.gitstore', 'node_modules'])
51
57
 
@@ -56,16 +62,31 @@ export type PinnedToolFiles = {
56
62
  cleanup(): Promise<void>
57
63
  }
58
64
 
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> {
65
+ type PinnedOutputTarget = PinnedToolFiles & {
66
+ rollback(): Promise<void>
67
+ }
68
+
69
+ // Test-only seam: pauses between budget acquisition and source open/stream so a
70
+ // test can grow a file post-authorization deterministically, without racing the
71
+ // scheduler. Production never passes hooks.
72
+ export type EnforceAndPinToolFilesHooks = {
73
+ afterBudgetAcquire?(): void | Promise<void>
74
+ }
75
+
76
+ export async function enforceAndPinToolFiles(
77
+ options: {
78
+ tool: string
79
+ args: Record<string, unknown>
80
+ agentDir: string
81
+ tempRoot?: string
82
+ genericInputs?: boolean
83
+ fileOperands?: ToolFileOperands
84
+ hidden?: HiddenPaths
85
+ logger?: Pick<ToolLogger, 'warn'>
86
+ signal?: AbortSignal
87
+ },
88
+ hooks: EnforceAndPinToolFilesHooks = {},
89
+ ): Promise<PinnedToolFiles> {
69
90
  if (options.signal?.aborted === true) throw abortError(options.signal)
70
91
  const maxCount = maxInputCount(options.tool)
71
92
  const targets = fileTargets(
@@ -75,16 +96,22 @@ export async function enforceAndPinToolFiles(options: {
75
96
  options.genericInputs === true,
76
97
  options.fileOperands,
77
98
  options.agentDir,
99
+ options.logger,
78
100
  )
79
101
  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()
102
+ const outputs = outputTargets(options.tool, options.args, TOOL_OUTPUT_MAX_COUNT, options.fileOperands)
103
+ if (targets.length === 0) return outputs.length === 0 ? noPinnedFiles() : await pinOutputTargets(options, outputs)
83
104
 
84
105
  let dir: string | undefined
85
106
  const rewrites: Rewrite[] = []
86
107
  const verified: VerifiedInput[] = []
87
108
  const maxBytes = maxInputBytes(options.tool)
109
+ const identityOptions = {
110
+ tool: options.tool,
111
+ agentDir: options.agentDir,
112
+ hidden: options.hidden ?? { dirs: [], files: [] },
113
+ }
114
+ const initialIdentityVerifier = createPrivateSurfaceReadIdentityVerifier(identityOptions)
88
115
  let lease: BudgetLease | undefined
89
116
  try {
90
117
  let declaredBytes = 0
@@ -103,7 +130,10 @@ export async function enforceAndPinToolFiles(options: {
103
130
  ? 'directory'
104
131
  : undefined
105
132
  if (kind === undefined) throw new Error(`tool input is not a supported regular file or directory: ${original}`)
106
- if (kind === 'file') assertSingleLinkRegularFile(inspected, original)
133
+ if (kind === 'file') {
134
+ assertRegularInputFile(inspected, original)
135
+ enforceInputIdentityDenial(initialIdentityVerifier, inspected)
136
+ }
107
137
  if (kind === 'file' && inspected.size > maxBytes) throw inputTooLarge(original, inspected.size, maxBytes)
108
138
  declaredBytes += kind === 'file' ? inspected.size : 0
109
139
  if (declaredBytes > maxBytes) throw aggregateInputTooLarge(declaredBytes, maxBytes)
@@ -111,6 +141,8 @@ export async function enforceAndPinToolFiles(options: {
111
141
  }
112
142
 
113
143
  lease = await pinnedSnapshotBudget.acquire(declaredBytes, verified.length, options.signal)
144
+ await hooks.afterBudgetAcquire?.()
145
+ const openedIdentityVerifier = createPrivateSurfaceReadIdentityVerifier(identityOptions)
114
146
 
115
147
  dir = await mkdtemp(path.join(options.tempRoot ?? tmpdir(), TOOL_INPUT_TEMP_PREFIX))
116
148
  let copiedBytes = 0
@@ -121,10 +153,11 @@ export async function enforceAndPinToolFiles(options: {
121
153
  const source = await openInput(input.resolved, input.original)
122
154
  try {
123
155
  const opened = await source.stat()
124
- assertSingleLinkRegularFile(opened, input.original)
156
+ assertRegularInputFile(opened, input.original)
125
157
  if (opened.dev !== input.dev || opened.ino !== input.ino) {
126
158
  throw new Error(`tool input changed while waiting for snapshot capacity: ${input.original}`)
127
159
  }
160
+ enforceInputIdentityDenial(openedIdentityVerifier, opened)
128
161
  copiedBytes += await streamSnapshot(
129
162
  source,
130
163
  pinned,
@@ -171,7 +204,7 @@ export async function enforceAndPinToolFiles(options: {
171
204
 
172
205
  let cleaned = false
173
206
 
174
- return {
207
+ const inputPinned: PinnedToolFiles = {
175
208
  restoreResult(result) {
176
209
  let restored = result
177
210
  for (const rewrite of rewrites) restored = replaceResultPath(restored, rewrite)
@@ -187,6 +220,15 @@ export async function enforceAndPinToolFiles(options: {
187
220
  }
188
221
  },
189
222
  }
223
+ if (outputs.length === 0) return inputPinned
224
+
225
+ try {
226
+ const outputPinned = await pinOutputTargets(options, outputs)
227
+ return composePinnedFiles([inputPinned, outputPinned])
228
+ } catch (error) {
229
+ await cleanupPinnedFilesReverse([inputPinned], true)
230
+ throw error
231
+ }
190
232
  }
191
233
 
192
234
  async function removePinnedSnapshot(root: string): Promise<void> {
@@ -219,6 +261,7 @@ function fileTargets(
219
261
  genericInputs: boolean,
220
262
  fileOperands: ToolFileOperands | undefined,
221
263
  agentDir: string,
264
+ logger: Pick<ToolLogger, 'warn'> | undefined,
222
265
  ): FileTarget[] {
223
266
  if (isOutputTool(tool)) return []
224
267
  if (TOOLS_WITHOUT_LOCAL_FILE_OPERANDS.has(tool)) return []
@@ -251,7 +294,7 @@ function fileTargets(
251
294
  // generic operands either pins a real-repo anchor into a /tmp file:// path that
252
295
  // leaks into the posted review, or throws "ambiguous local file operand".
253
296
  if (tool === 'post_github_review') return targets
254
- if (genericInputs) collectGenericFileTargets(tool, args, targets, maxCount, fileOperands, agentDir)
297
+ if (genericInputs) collectGenericFileTargets(tool, args, targets, maxCount, fileOperands, agentDir, logger)
255
298
  return targets
256
299
  }
257
300
 
@@ -259,8 +302,8 @@ function fileTargets(
259
302
  // bodies, prompts, queries, regex/CSS/jq strings) that are never a local file.
260
303
  // This table is for tools that ALSO have a real file operand and so cannot be
261
304
  // 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,
305
+ // `url` (non-file URLs are exempt while file: URIs still snapshot) and treats
306
+ // `query`/`selector`/`pattern` as prose. Pure control-token tools (reload, grant_role, stream_snapshot,
264
307
  // channel_edit, …) live in that set instead, so they are absent here.
265
308
  //
266
309
  // Scoped by full operand path, NOT key name — this is the fail-closed invariant:
@@ -271,7 +314,7 @@ function fileTargets(
271
314
  const NON_FILE_OPERANDS: Readonly<Record<string, ReadonlySet<string>>> = {
272
315
  skip_response: new Set(['reason']),
273
316
  web_search: new Set(['query']),
274
- web_fetch: new Set(['query', 'selector', 'pattern']),
317
+ web_fetch: new Set(['url', 'query', 'selector', 'pattern']),
275
318
  todo_write: new Set(['todos.content']),
276
319
  }
277
320
 
@@ -317,19 +360,29 @@ function outputTargets(
317
360
  args: Record<string, unknown>,
318
361
  maxCount: number,
319
362
  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))
363
+ ): OutputTarget[] {
364
+ if (isOutputTool(tool)) {
365
+ return typeof args.path === 'string' ? [{ target: propertyTarget(args, 'path'), mode: 'reserved' }] : []
366
+ }
367
+ const outputPaths = new Set(operands?.output ?? [])
368
+ const createPaths = new Set(operands?.create ?? [])
369
+ for (const operandPath of outputPaths) {
370
+ if (createPaths.has(operandPath)) {
371
+ throw new Error(`file operand ${JSON.stringify(operandPath)} cannot be both output and create`)
372
+ }
373
+ }
374
+ const targets: OutputTarget[] = []
375
+ collectDeclaredOutputTargets(args, targets, maxCount, outputPaths, 'reserved')
376
+ collectDeclaredOutputTargets(args, targets, maxCount, createPaths, 'exclusive-create')
325
377
  return targets
326
378
  }
327
379
 
328
380
  function collectDeclaredOutputTargets(
329
381
  value: unknown,
330
- out: FileTarget[],
382
+ out: OutputTarget[],
331
383
  maxCount: number,
332
384
  declared: ReadonlySet<string>,
385
+ mode: OutputTarget['mode'],
333
386
  parentPath = '',
334
387
  ): void {
335
388
  if (Array.isArray(value)) {
@@ -337,12 +390,12 @@ function collectDeclaredOutputTargets(
337
390
  for (const [index, item] of value.entries()) {
338
391
  if (typeof item === 'string') {
339
392
  if (declaredOutput) {
340
- out.push(arrayTarget(value, index))
341
- if (out.length > maxCount) throw inputCountTooLarge(out.length, maxCount)
393
+ out.push({ target: arrayTarget(value, index), mode })
394
+ if (out.length > maxCount) throw outputCountTooLarge(out.length, maxCount)
342
395
  }
343
396
  continue
344
397
  }
345
- collectDeclaredOutputTargets(item, out, maxCount, declared, parentPath)
398
+ collectDeclaredOutputTargets(item, out, maxCount, declared, mode, parentPath)
346
399
  }
347
400
  return
348
401
  }
@@ -350,11 +403,11 @@ function collectDeclaredOutputTargets(
350
403
  for (const [childKey, item] of Object.entries(value)) {
351
404
  const operandPath = parentPath === '' ? childKey : `${parentPath}.${childKey}`
352
405
  if (typeof item === 'string' && declared.has(operandPath)) {
353
- out.push(propertyTarget(value, childKey))
354
- if (out.length > maxCount) throw inputCountTooLarge(out.length, maxCount)
406
+ out.push({ target: propertyTarget(value, childKey), mode })
407
+ if (out.length > maxCount) throw outputCountTooLarge(out.length, maxCount)
355
408
  continue
356
409
  }
357
- collectDeclaredOutputTargets(item, out, maxCount, declared, operandPath)
410
+ collectDeclaredOutputTargets(item, out, maxCount, declared, mode, operandPath)
358
411
  }
359
412
  }
360
413
 
@@ -365,12 +418,15 @@ function collectGenericFileTargets(
365
418
  maxCount: number,
366
419
  operands: ToolFileOperands | undefined,
367
420
  agentDir: string,
421
+ logger: Pick<ToolLogger, 'warn'> | undefined,
368
422
  parentPath = '',
369
423
  ): void {
370
424
  if (Array.isArray(value)) {
371
425
  const declaredInput = operands?.input?.includes(parentPath) === true
372
426
  const nonInput =
373
- operands?.output?.includes(parentPath) === true || operands?.destructive?.includes(parentPath) === true
427
+ operands?.output?.includes(parentPath) === true ||
428
+ operands?.create?.includes(parentPath) === true ||
429
+ operands?.destructive?.includes(parentPath) === true
374
430
  const key = parentPath.split('.').at(-1) ?? parentPath
375
431
  // Precedence: declared input pins; declared output/destructive is not an
376
432
  // input; a known non-file operand is opaque (skipped, even a file: URI);
@@ -378,26 +434,23 @@ function collectGenericFileTargets(
378
434
  // fails closed. Both the static first-party table and a plugin's declared
379
435
  // `fileOperands.nonFile` are tool+operand-path scoped, so an unknown tool
380
436
  // never inherits an exemption from a common key name.
381
- const knownNonFile =
382
- !declaredInput && (operands?.nonFile?.includes(parentPath) === true || isKnownNonFileOperand(tool, parentPath))
437
+ const declaredNonFile = !declaredInput && operands?.nonFile?.includes(parentPath) === true
438
+ const knownNonFile = !declaredInput && isKnownNonFileOperand(tool, parentPath)
383
439
  for (const [index, item] of value.entries()) {
384
440
  if (typeof item === 'string') {
385
- if (knownNonFile) continue
441
+ if (declaredNonFile || (knownNonFile && !isFileUri(item))) continue
386
442
  if (!nonInput && (isFileUri(item) || declaredInput)) {
387
443
  out.push(arrayTarget(value, index))
388
444
  if (out.length > maxCount) throw inputCountTooLarge(out.length, maxCount)
389
- } else if (
390
- !nonInput &&
391
- !isSemanticGenericString(key, item) &&
392
- isAmbiguousUndeclaredLocalOperand(item, agentDir, key)
393
- ) {
445
+ } else if (!nonInput && isAmbiguousUndeclaredLocalOperand(item, agentDir, key)) {
446
+ warnForUndeclaredExistingLocalOperand(logger, tool, parentPath, item, agentDir)
394
447
  throw new Error(
395
448
  `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
449
  )
397
450
  }
398
451
  continue
399
452
  }
400
- collectGenericFileTargets(tool, item, out, maxCount, operands, agentDir, parentPath)
453
+ collectGenericFileTargets(tool, item, out, maxCount, operands, agentDir, logger, parentPath)
401
454
  }
402
455
  return
403
456
  }
@@ -407,35 +460,31 @@ function collectGenericFileTargets(
407
460
  if (typeof item === 'string') {
408
461
  const declaredInput = operands?.input?.includes(operandPath) === true
409
462
  const nonInput =
410
- operands?.output?.includes(operandPath) === true || operands?.destructive?.includes(operandPath) === true
463
+ operands?.output?.includes(operandPath) === true ||
464
+ operands?.create?.includes(operandPath) === true ||
465
+ operands?.destructive?.includes(operandPath) === true
411
466
  // Declared input wins; a known non-file operand (web_search.query,
412
467
  // web_fetch.selector, a plugin's declared `fileOperands.nonFile`, …) is
413
468
  // opaque and skipped even when its value is a file: URI; everything else
414
469
  // falls to the file:/heuristic scan below. Scoped by exact tool+operand-
415
470
  // path so an undeclared plugin reader using `content`/`prompt` still
416
471
  // fails closed.
417
- if (
418
- !declaredInput &&
419
- (operands?.nonFile?.includes(operandPath) === true || isKnownNonFileOperand(tool, operandPath))
420
- ) {
421
- continue
422
- }
472
+ const declaredNonFile = !declaredInput && operands?.nonFile?.includes(operandPath) === true
473
+ const knownNonFile = !declaredInput && isKnownNonFileOperand(tool, operandPath)
474
+ if (declaredNonFile || (knownNonFile && !isFileUri(item))) continue
423
475
  if (!nonInput && (isFileUri(item) || declaredInput)) {
424
476
  out.push(propertyTarget(value, childKey))
425
477
  if (out.length > maxCount) throw inputCountTooLarge(out.length, maxCount)
426
478
  continue
427
479
  }
428
- if (
429
- !nonInput &&
430
- !isSemanticGenericString(childKey, item) &&
431
- isAmbiguousUndeclaredLocalOperand(item, agentDir, childKey)
432
- ) {
480
+ if (!nonInput && isAmbiguousUndeclaredLocalOperand(item, agentDir, childKey)) {
481
+ warnForUndeclaredExistingLocalOperand(logger, tool, operandPath, item, agentDir)
433
482
  throw new Error(
434
483
  `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
484
  )
436
485
  }
437
486
  }
438
- collectGenericFileTargets(tool, item, out, maxCount, operands, agentDir, operandPath)
487
+ collectGenericFileTargets(tool, item, out, maxCount, operands, agentDir, logger, operandPath)
439
488
  }
440
489
  }
441
490
 
@@ -443,6 +492,29 @@ function noPinnedFiles(): PinnedToolFiles {
443
492
  return { restoreResult: (result) => result, cleanup: async () => {} }
444
493
  }
445
494
 
495
+ function composePinnedFiles(pinned: readonly PinnedToolFiles[]): PinnedToolFiles {
496
+ return {
497
+ restoreResult(result) {
498
+ return pinned.reduceRight((restored, entry) => entry.restoreResult(restored), result)
499
+ },
500
+ async cleanup() {
501
+ await cleanupPinnedFilesReverse(pinned)
502
+ },
503
+ }
504
+ }
505
+
506
+ async function cleanupPinnedFilesReverse(pinned: readonly PinnedToolFiles[], suppressErrors = false): Promise<void> {
507
+ let firstError: unknown
508
+ for (let index = pinned.length - 1; index >= 0; index -= 1) {
509
+ try {
510
+ await pinned[index]?.cleanup()
511
+ } catch (error) {
512
+ firstError ??= error
513
+ }
514
+ }
515
+ if (!suppressErrors && firstError !== undefined) throw firstError
516
+ }
517
+
446
518
  async function openInput(absolute: string, original: string): Promise<FileHandle> {
447
519
  try {
448
520
  return await open(absolute, constants.O_RDONLY)
@@ -461,25 +533,18 @@ async function pinOutputTargets(
461
533
  agentDir: string
462
534
  signal?: AbortSignal
463
535
  },
464
- targets: FileTarget[],
536
+ targets: OutputTarget[],
465
537
  ): Promise<PinnedToolFiles> {
466
- const pinned: PinnedToolFiles[] = []
538
+ const pinned: PinnedOutputTarget[] = []
467
539
  try {
468
540
  for (const target of targets) pinned.push(await pinOutputTarget(options, target))
469
541
  } catch (error) {
470
- await Promise.allSettled([...pinned].reverse().map(async (entry) => await entry.cleanup()))
542
+ for (let index = pinned.length - 1; index >= 0; index -= 1) {
543
+ await pinned[index]?.rollback().catch(() => {})
544
+ }
471
545
  throw error
472
546
  }
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
- }
547
+ return composePinnedFiles(pinned)
483
548
  }
484
549
 
485
550
  async function pinOutputTarget(
@@ -489,8 +554,9 @@ async function pinOutputTarget(
489
554
  agentDir: string
490
555
  signal?: AbortSignal
491
556
  },
492
- target: FileTarget,
493
- ): Promise<PinnedToolFiles> {
557
+ output: OutputTarget,
558
+ ): Promise<PinnedOutputTarget> {
559
+ const { target } = output
494
560
  if (options.signal?.aborted === true) throw abortError(options.signal)
495
561
  const original = target.get()
496
562
  const absolute = path.resolve(options.agentDir, original)
@@ -508,6 +574,8 @@ async function pinOutputTarget(
508
574
  })
509
575
  let targetHandle: FileHandle | undefined
510
576
  let targetIdentity: { dev: number; ino: number } | undefined
577
+ let created = false
578
+ let anchored: string | undefined
511
579
  try {
512
580
  const fdRoot = '/proc/self/fd'
513
581
  const resolvedParent = await realpath(`${fdRoot}/${directory.fd}`)
@@ -516,62 +584,176 @@ async function pinOutputTarget(
516
584
  args: { path: path.join(resolvedParent, basename) },
517
585
  agentDir: options.agentDir,
518
586
  })
519
- const anchored = `${fdRoot}/${directory.fd}/${basename}`
520
- targetHandle = await open(anchored, constants.O_RDWR | noFollow).catch((error) => {
587
+ const anchoredOutput = `${fdRoot}/${directory.fd}/${basename}`
588
+ anchored = anchoredOutput
589
+ if (output.mode === 'exclusive-create') {
590
+ const existing = await open(anchoredOutput, constants.O_RDONLY | noFollow).catch((error) => {
591
+ if (isNotFoundError(error)) return undefined
592
+ throw error
593
+ })
594
+ if (existing !== undefined) {
595
+ await existing.close()
596
+ throw new Error(`write/edit output must not already exist: ${original}`)
597
+ }
598
+ target.set(anchoredOutput)
599
+ let cleaned = false
600
+ const finalize = async (verifyCreated: boolean): Promise<void> => {
601
+ if (cleaned) return
602
+ cleaned = true
603
+ let verifyError: unknown
604
+ if (verifyCreated) {
605
+ try {
606
+ await verifyExclusiveCreatedOutput({
607
+ anchored: anchoredOutput,
608
+ original,
609
+ noFollow,
610
+ tool: options.tool,
611
+ agentDir: options.agentDir,
612
+ })
613
+ } catch (error) {
614
+ verifyError = error
615
+ }
616
+ }
617
+ const closeError = await directory.close().catch((error) => error)
618
+ if (verifyError !== undefined) throw verifyError
619
+ if (closeError !== undefined) throw closeError
620
+ }
621
+ return {
622
+ restoreResult(result) {
623
+ return replaceResultPath(result, { original, pinned: anchoredOutput })
624
+ },
625
+ async cleanup() {
626
+ await finalize(true)
627
+ },
628
+ async rollback() {
629
+ await finalize(false)
630
+ },
631
+ }
632
+ }
633
+ targetHandle = await open(anchoredOutput, constants.O_RDWR | noFollow).catch((error) => {
521
634
  if (isNotFoundError(error)) return undefined
522
635
  throw error
523
636
  })
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}`
637
+ if (targetHandle === undefined) {
638
+ targetHandle = await open(
639
+ anchoredOutput,
640
+ constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | noFollow,
641
+ 0o666,
642
+ ).catch((error) => {
643
+ if (error instanceof Error && 'code' in error && (error.code === 'EEXIST' || error.code === 'ELOOP')) {
644
+ throw new Error(`write/edit output destination changed while being authorized: ${original}`)
645
+ }
646
+ throw error
647
+ })
648
+ created = true
534
649
  }
650
+ const inspected = await targetHandle.stat()
651
+ if (!inspected.isFile() || inspected.nlink !== 1) {
652
+ throw new Error(`write/edit output is not a single-link regular file: ${original}`)
653
+ }
654
+ const authorizedIdentity = { dev: inspected.dev, ino: inspected.ino }
655
+ targetIdentity = authorizedIdentity
656
+ const resolved = await realpath(`${fdRoot}/${targetHandle.fd}`)
657
+ enforceCanonicalSecretDenial({ tool: options.tool, args: { path: resolved }, agentDir: options.agentDir })
658
+ const executionPath = `${fdRoot}/${targetHandle.fd}`
535
659
  target.set(executionPath)
536
660
  let cleaned = false
661
+ const finalize = async (removeCreated: boolean): Promise<void> => {
662
+ if (cleaned) return
663
+ cleaned = true
664
+ let verifyError: unknown
665
+ try {
666
+ await verifyOutputEntry({
667
+ anchored: anchoredOutput,
668
+ original,
669
+ identity: authorizedIdentity,
670
+ noFollow,
671
+ remove: removeCreated && created,
672
+ tool: options.tool,
673
+ agentDir: options.agentDir,
674
+ })
675
+ } catch (error) {
676
+ verifyError = error
677
+ }
678
+ const outcomes = await Promise.allSettled([targetHandle?.close(), directory.close()])
679
+ const failed = outcomes.find((outcome) => outcome.status === 'rejected')
680
+ if (verifyError !== undefined) throw verifyError
681
+ if (failed?.status === 'rejected') throw failed.reason
682
+ }
537
683
  return {
538
684
  restoreResult(result) {
539
685
  return replaceResultPath(result, { original, pinned: executionPath })
540
686
  },
541
687
  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
688
+ await finalize(false)
689
+ },
690
+ async rollback() {
691
+ await finalize(true)
567
692
  },
568
693
  }
569
694
  } catch (error) {
695
+ if (created && anchored !== undefined && targetIdentity !== undefined) {
696
+ await verifyOutputEntry({
697
+ anchored,
698
+ original,
699
+ identity: targetIdentity,
700
+ noFollow,
701
+ remove: true,
702
+ tool: options.tool,
703
+ agentDir: options.agentDir,
704
+ }).catch(() => {})
705
+ }
570
706
  await Promise.allSettled([targetHandle?.close(), directory.close()])
571
707
  throw error
572
708
  }
573
709
  }
574
710
 
711
+ async function verifyExclusiveCreatedOutput(options: {
712
+ anchored: string
713
+ original: string
714
+ noFollow: number
715
+ tool: string
716
+ agentDir: string
717
+ }): Promise<void> {
718
+ const verified = await open(options.anchored, constants.O_RDONLY | options.noFollow)
719
+ try {
720
+ const inspected = await verified.stat()
721
+ if (!inspected.isFile() || inspected.nlink !== 1) {
722
+ throw new Error(`write/edit output is not a single-link regular file: ${options.original}`)
723
+ }
724
+ const resolved = await realpath(`/proc/self/fd/${verified.fd}`)
725
+ enforceCanonicalSecretDenial({ tool: options.tool, args: { path: resolved }, agentDir: options.agentDir })
726
+ } finally {
727
+ await verified.close()
728
+ }
729
+ }
730
+
731
+ async function verifyOutputEntry(options: {
732
+ anchored: string
733
+ original: string
734
+ identity: { dev: number; ino: number }
735
+ noFollow: number
736
+ remove: boolean
737
+ tool: string
738
+ agentDir: string
739
+ }): Promise<void> {
740
+ const verified = await open(options.anchored, constants.O_RDONLY | options.noFollow)
741
+ try {
742
+ const inspected = await verified.stat()
743
+ if (!inspected.isFile() || inspected.nlink !== 1) {
744
+ throw new Error(`write/edit output is not a single-link regular file: ${options.original}`)
745
+ }
746
+ if (inspected.dev !== options.identity.dev || inspected.ino !== options.identity.ino) {
747
+ throw new Error(`write/edit output destination changed during execution: ${options.original}`)
748
+ }
749
+ const resolved = await realpath(`/proc/self/fd/${verified.fd}`)
750
+ enforceCanonicalSecretDenial({ tool: options.tool, args: { path: resolved }, agentDir: options.agentDir })
751
+ if (options.remove) await unlink(options.anchored)
752
+ } finally {
753
+ await verified.close()
754
+ }
755
+ }
756
+
575
757
  export async function writeFileAnchored(options: {
576
758
  targetPath: string
577
759
  data: Uint8Array
@@ -714,9 +896,21 @@ async function snapshotDirectoryTree(options: {
714
896
  }
715
897
  await mkdir(options.destination, { mode: 0o700 })
716
898
  const state = { copied: 0, entries: 0 }
899
+ const identityVerifier = createPrivateSurfaceReadIdentityVerifier({
900
+ tool: options.tool,
901
+ agentDir: options.agentDir,
902
+ hidden: options.hidden ?? { dirs: [], files: [] },
903
+ })
717
904
  const openedRoot = await realpath(`/proc/self/fd/${root.fd}`)
718
905
  const realAgentDir = await realpath(options.agentDir)
719
- await snapshotOpenedDirectory(root, options.destination, options, state, openedRoot === realAgentDir)
906
+ await snapshotOpenedDirectory(
907
+ root,
908
+ options.destination,
909
+ options,
910
+ state,
911
+ identityVerifier,
912
+ openedRoot === realAgentDir,
913
+ )
720
914
  await chmod(options.destination, 0o500)
721
915
  return state.copied
722
916
  } finally {
@@ -729,6 +923,7 @@ async function snapshotOpenedDirectory(
729
923
  destination: string,
730
924
  options: Parameters<typeof snapshotDirectoryTree>[0],
731
925
  state: { copied: number; entries: number },
926
+ identityVerifier: PrivateSurfaceIdentityVerifier,
732
927
  isAgentRoot: boolean,
733
928
  ): Promise<void> {
734
929
  const sourceRoot = `/proc/self/fd/${directory.fd}`
@@ -755,7 +950,7 @@ async function snapshotOpenedDirectory(
755
950
  const resolved = await realpath(`/proc/self/fd/${child.fd}`)
756
951
  if (isDeniedSnapshotPath(resolved, options)) continue
757
952
  await mkdir(target, { mode: 0o700 })
758
- await snapshotOpenedDirectory(child, target, options, state, false)
953
+ await snapshotOpenedDirectory(child, target, options, state, identityVerifier, false)
759
954
  await chmod(target, 0o500)
760
955
  } finally {
761
956
  await child.close()
@@ -769,7 +964,8 @@ async function snapshotOpenedDirectory(
769
964
  const source = await open(anchored, constants.O_RDONLY | constants.O_NOFOLLOW)
770
965
  try {
771
966
  const opened = await source.stat()
772
- assertSingleLinkRegularFile(opened, candidate)
967
+ assertRegularInputFile(opened, candidate)
968
+ enforceInputIdentityDenial(identityVerifier, opened)
773
969
  const resolved = await realpath(`/proc/self/fd/${source.fd}`)
774
970
  if (isDeniedSnapshotPath(resolved, options)) continue
775
971
  state.copied += await streamSnapshot(
@@ -789,13 +985,8 @@ async function snapshotOpenedDirectory(
789
985
  }
790
986
  }
791
987
 
792
- function assertSingleLinkRegularFile(stats: Stats, original: string): void {
988
+ function assertRegularInputFile(stats: Stats, original: string): void {
793
989
  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
990
  }
800
991
 
801
992
  function maxInputBytes(tool: string): number {
@@ -819,25 +1010,31 @@ function isTreeInputTool(tool: string): boolean {
819
1010
  }
820
1011
 
821
1012
  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
-
1013
+ // Filesystem reality wins over semantic spelling: an existing entry named
1014
+ // like a repository slug, date, URL, or package coordinate is still a local
1015
+ // operand and must be declared so it is authorized and pinned.
830
1016
  const resolved = path.resolve(agentDir, value)
831
1017
  try {
832
1018
  lstatSync(resolved)
833
1019
  return true
834
1020
  } catch (error) {
835
- return !isNotFoundError(error)
1021
+ if (!isNotFoundError(error)) return true
836
1022
  }
1023
+
1024
+ const basename = path.posix.basename(value.replaceAll('\\', '/'))
1025
+ if (CANONICAL_AGENT_SECRET_FILES.includes(basename as (typeof CANONICAL_AGENT_SECRET_FILES)[number])) return true
1026
+
1027
+ if (isFileShapedKey(key)) return !(normalizedKey(key) === 'path' && isSafeApiRoute(value))
1028
+ if (value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value) || /^(?:\\\\|\/\/)[^\\/]/.test(value)) return true
1029
+ if (value.startsWith('./') || value.startsWith('../')) return true
1030
+ if (isSemanticGenericString(key, value)) return false
1031
+ if (/[\\/]/.test(value)) return true
1032
+ if (/^[^./\\\s][^/\\\s]*\.[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) return true
1033
+ return false
837
1034
  }
838
1035
 
839
1036
  function isFileShapedKey(key: string): boolean {
840
- const normalized = key.replaceAll(/[-_]/g, '').toLocaleLowerCase()
1037
+ const normalized = normalizedKey(key)
841
1038
  return (
842
1039
  normalized === 'path' ||
843
1040
  normalized === 'file' ||
@@ -849,16 +1046,24 @@ function isFileShapedKey(key: string): boolean {
849
1046
  )
850
1047
  }
851
1048
 
1049
+ function normalizedKey(key: string): string {
1050
+ return key.replaceAll(/[-_]/g, '').toLocaleLowerCase()
1051
+ }
1052
+
852
1053
  function isSemanticGenericString(key: string, value: string): boolean {
853
1054
  if (isExplicitNonFileUrl(value)) return true
854
- if (key === 'path' && isSafeApiRoute(value)) return true
855
- return key === 'repository' && isSafeRepositorySlug(value)
1055
+ const normalized = normalizedKey(key)
1056
+ if (
1057
+ (normalized === 'repository' || normalized === 'repositoryslug' || normalized === 'reposlug') &&
1058
+ isSafeRepositorySlug(value)
1059
+ ) {
1060
+ return true
1061
+ }
1062
+ if ((normalized === 'date' || normalized === 'fraction') && isSafeNumericDateOrFraction(value)) return true
1063
+ return isPackageCoordinateKey(normalized) && isSafePackageCoordinate(value)
856
1064
  }
857
1065
 
858
1066
  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
1067
  const trimmed = value.trim()
863
1068
  if (/^[A-Za-z]:[\\/]/.test(trimmed)) return false
864
1069
  if (!/^[A-Za-z][A-Za-z0-9+.-]*:/.test(trimmed) || trimmed.toLocaleLowerCase().startsWith('file:')) return false
@@ -871,8 +1076,7 @@ function isExplicitNonFileUrl(value: string): boolean {
871
1076
 
872
1077
  function isSafeApiRoute(value: string): boolean {
873
1078
  if (!/^\/v\d+\//.test(value) || value.includes('\\') || value.includes('//')) return false
874
- const segments = value.split('/')
875
- for (const segment of segments.slice(1)) {
1079
+ for (const segment of value.split('/').slice(1)) {
876
1080
  if (segment.length === 0) return false
877
1081
  let decoded: string
878
1082
  try {
@@ -892,6 +1096,58 @@ function isSafeRepositorySlug(value: string): boolean {
892
1096
  return match !== null && match[1] !== '.' && match[1] !== '..' && match[2] !== '.' && match[2] !== '..'
893
1097
  }
894
1098
 
1099
+ function isSafeNumericDateOrFraction(value: string): boolean {
1100
+ return /^\d{1,4}([/-])\d{1,2}(?:\1\d{1,4})?$/.test(value)
1101
+ }
1102
+
1103
+ function isPackageCoordinateKey(normalized: string): boolean {
1104
+ return (
1105
+ normalized === 'package' ||
1106
+ normalized === 'packagename' ||
1107
+ normalized === 'packagespec' ||
1108
+ normalized === 'packagecoordinate'
1109
+ )
1110
+ }
1111
+
1112
+ function isSafePackageCoordinate(value: string): boolean {
1113
+ if (/^@[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*(?:@[^\s/]+)?$/.test(value)) return true
1114
+ if (/^[A-Za-z0-9][A-Za-z0-9._-]*@[^\s/@]+$/.test(value)) return true
1115
+ if (/^[A-Za-z0-9_.-]+:[A-Za-z0-9_.-]+(?::[A-Za-z0-9_.+-]+){0,3}$/.test(value)) return true
1116
+ if (/^(?:[A-Za-z_][A-Za-z0-9_-]*\.)+[A-Za-z_][A-Za-z0-9_-]*$/.test(value)) return true
1117
+ const segments = value.split('/')
1118
+ return segments.length > 1 && segments.every((segment) => /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(segment))
1119
+ }
1120
+
1121
+ function warnForUndeclaredExistingLocalOperand(
1122
+ logger: Pick<ToolLogger, 'warn'> | undefined,
1123
+ tool: string,
1124
+ operandPath: string,
1125
+ value: string,
1126
+ agentDir: string,
1127
+ ): void {
1128
+ if (logger === undefined) return
1129
+ try {
1130
+ lstatSync(path.resolve(agentDir, value))
1131
+ } catch {
1132
+ return
1133
+ }
1134
+ try {
1135
+ logger.warn(
1136
+ `[tool-file-safety] ${tool} received an undeclared existing local operand at ${JSON.stringify(operandPath)}; declare fileOperands.input to authorize immutable snapshotting`,
1137
+ )
1138
+ } catch {
1139
+ // Diagnostics must never change authorization behavior.
1140
+ }
1141
+ }
1142
+
1143
+ function enforceInputIdentityDenial(
1144
+ verifier: PrivateSurfaceIdentityVerifier,
1145
+ identity: Pick<Stats, 'dev' | 'ino' | 'nlink'>,
1146
+ ): void {
1147
+ const blocked = verifier.check(identity)
1148
+ if (blocked !== undefined) throw new Error(`blocked: ${blocked.reason}`)
1149
+ }
1150
+
895
1151
  function isDeniedSnapshotPath(
896
1152
  candidate: string,
897
1153
  options: { agentDir: string; tool: string; hidden?: HiddenPaths },
@@ -932,6 +1188,10 @@ function inputCountTooLarge(count: number, maxCount: number): Error {
932
1188
  return new Error(`tool input count exceeds the per-invocation limit (${count} > ${maxCount})`)
933
1189
  }
934
1190
 
1191
+ function outputCountTooLarge(count: number, maxCount: number): Error {
1192
+ return new Error(`tool output count exceeds the per-invocation limit (${count} > ${maxCount})`)
1193
+ }
1194
+
935
1195
  function replaceResultPath(result: ToolResult, rewrite: Rewrite): ToolResult {
936
1196
  const content = result.content.map((part) =>
937
1197
  part.type === 'text' ? { ...part, text: part.text.split(rewrite.pinned).join(rewrite.original) } : part,