@sixb/agent 0.1.0 → 0.2.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 (102) hide show
  1. package/dist/agent-prompt.d.ts +34 -28
  2. package/dist/agent-prompt.d.ts.map +1 -1
  3. package/dist/artifacts/publish-tool.d.ts +1 -1
  4. package/dist/attachments.d.ts +42 -1
  5. package/dist/attachments.d.ts.map +1 -1
  6. package/dist/child-files.d.ts +0 -5
  7. package/dist/child-files.d.ts.map +1 -1
  8. package/dist/computer-runner.d.ts +16 -7
  9. package/dist/computer-runner.d.ts.map +1 -1
  10. package/dist/context-budget.d.ts +23 -17
  11. package/dist/context-budget.d.ts.map +1 -1
  12. package/dist/context-compaction.d.ts +118 -18
  13. package/dist/context-compaction.d.ts.map +1 -1
  14. package/dist/context-guard.d.ts +69 -0
  15. package/dist/context-guard.d.ts.map +1 -0
  16. package/dist/conversation-messages.d.ts +33 -0
  17. package/dist/conversation-messages.d.ts.map +1 -0
  18. package/dist/execution-plan.d.ts +5 -1
  19. package/dist/execution-plan.d.ts.map +1 -1
  20. package/dist/failure.d.ts.map +1 -1
  21. package/dist/index.js +4916 -2697
  22. package/dist/index.js.map +41 -34
  23. package/dist/inline-images.d.ts +28 -0
  24. package/dist/inline-images.d.ts.map +1 -0
  25. package/dist/message-authors.d.ts +4 -4
  26. package/dist/message-authors.d.ts.map +1 -1
  27. package/dist/message-times.d.ts +4 -3
  28. package/dist/message-times.d.ts.map +1 -1
  29. package/dist/model-adapters.d.ts +6 -2
  30. package/dist/model-adapters.d.ts.map +1 -1
  31. package/dist/prompt-cache.d.ts +28 -0
  32. package/dist/prompt-cache.d.ts.map +1 -0
  33. package/dist/run-agent-turn.d.ts +33 -3
  34. package/dist/run-agent-turn.d.ts.map +1 -1
  35. package/dist/run-child.d.ts.map +1 -1
  36. package/dist/run-conversation-turn.d.ts.map +1 -1
  37. package/dist/run-environment.d.ts +35 -5
  38. package/dist/run-environment.d.ts.map +1 -1
  39. package/dist/run-files-lock.d.ts +16 -0
  40. package/dist/run-files-lock.d.ts.map +1 -0
  41. package/dist/run-subagent.d.ts +15 -1
  42. package/dist/run-subagent.d.ts.map +1 -1
  43. package/dist/run-workflow-agent-node.d.ts +5 -0
  44. package/dist/run-workflow-agent-node.d.ts.map +1 -1
  45. package/dist/sandbox-api-context.d.ts.map +1 -1
  46. package/dist/subagent-context.d.ts +50 -0
  47. package/dist/subagent-context.d.ts.map +1 -0
  48. package/dist/subagent-continuation.d.ts +10 -4
  49. package/dist/subagent-continuation.d.ts.map +1 -1
  50. package/dist/subagent-tools.d.ts +11 -0
  51. package/dist/subagent-tools.d.ts.map +1 -1
  52. package/dist/thread-context.d.ts +7 -2
  53. package/dist/thread-context.d.ts.map +1 -1
  54. package/dist/tools/bash.d.ts +8 -0
  55. package/dist/tools/bash.d.ts.map +1 -1
  56. package/dist/tools/model-spec.d.ts +7 -2
  57. package/dist/tools/model-spec.d.ts.map +1 -1
  58. package/dist/tools/result-media.d.ts +53 -10
  59. package/dist/tools/result-media.d.ts.map +1 -1
  60. package/dist/tools/result-output.d.ts +1 -1
  61. package/dist/tools/result-output.d.ts.map +1 -1
  62. package/dist/tools/tool-outputs.d.ts +63 -0
  63. package/dist/tools/tool-outputs.d.ts.map +1 -0
  64. package/dist/types.d.ts +9 -2
  65. package/dist/types.d.ts.map +1 -1
  66. package/package.json +4 -4
  67. package/src/agent-prompt.ts +178 -76
  68. package/src/attachments.ts +275 -84
  69. package/src/child-files.ts +1 -6
  70. package/src/computer-runner.ts +75 -23
  71. package/src/context-budget.ts +110 -94
  72. package/src/context-compaction.ts +1007 -187
  73. package/src/context-guard.ts +826 -0
  74. package/src/conversation-messages.ts +86 -0
  75. package/src/execution-plan.ts +22 -2
  76. package/src/failure.ts +11 -0
  77. package/src/inline-images.ts +69 -0
  78. package/src/message-authors.ts +5 -5
  79. package/src/message-times.ts +8 -5
  80. package/src/model-adapters.ts +59 -13
  81. package/src/prompt-cache.ts +40 -0
  82. package/src/run-agent-turn.ts +234 -72
  83. package/src/run-child.ts +30 -5
  84. package/src/run-conversation-turn.ts +16 -1
  85. package/src/run-environment.ts +553 -106
  86. package/src/run-files-lock.ts +118 -0
  87. package/src/run-subagent.ts +132 -46
  88. package/src/run-workflow-agent-node.ts +84 -10
  89. package/src/sandbox-api-context.ts +3 -0
  90. package/src/skills/sixb-artifacts/canvas.md +1 -1
  91. package/src/skills/sixb-artifacts/page.md +1 -1
  92. package/src/skills/sixb-artifacts/slides.md +1 -1
  93. package/src/subagent-context.ts +182 -0
  94. package/src/subagent-continuation.ts +11 -6
  95. package/src/subagent-tools.ts +73 -11
  96. package/src/thread-context.ts +9 -3
  97. package/src/tools/bash.ts +17 -1
  98. package/src/tools/model-spec.ts +9 -4
  99. package/src/tools/result-media.ts +286 -82
  100. package/src/tools/result-output.ts +4 -2
  101. package/src/tools/tool-outputs.ts +464 -0
  102. package/src/types.ts +14 -2
@@ -1,10 +1,16 @@
1
1
  import { posix } from "node:path"
2
2
  import type { AgentFileDataProjection, BlobInfo, FileRef } from "@sixb/core"
3
- import { type AgentRunFileStore, listMessageAttachments } from "@sixb/core/internal/agents"
4
- import type { LanguageModel } from "@sixb/core/models"
3
+ import {
4
+ type AgentRunFileStore,
5
+ agentToolFilePath,
6
+ listMessageAttachments,
7
+ } from "@sixb/core/internal/agents"
8
+ import type { LanguageModel, ModelMessage } from "@sixb/core/models"
5
9
  import type { AgentMessageRecord } from "@sixb/core/storage"
6
10
  import { NEVER_ABORTED_SIGNAL, waitForAbort } from "./abort"
11
+ import { fileRefKey } from "./file-ref"
7
12
  import { type AgentAttachmentLimits, processAgentImageAttachment } from "./image-attachments"
13
+ import { INLINE_IMAGE_BUDGET_NOTE } from "./inline-images"
8
14
 
9
15
  const DEFAULT_AGENT_ATTACHMENT_LIMITS: AgentAttachmentLimits = {
10
16
  textInlineMaxBytes: 50 * 1024,
@@ -20,6 +26,13 @@ const DEFAULT_AGENT_ATTACHMENT_LIMITS: AgentAttachmentLimits = {
20
26
  const TEXT_INLINE_TOTAL_MAX_BYTES = 200 * 1024
21
27
  const MAX_ASSISTANT_ATTACHMENTS = 50
22
28
 
29
+ /**
30
+ * Where a parent finds what its children wrote to `out/`, a directory per spawn key, in the context
31
+ * directory: `wait_agent` copies them there, and later turns materialize them there again.
32
+ */
33
+ export const CHILD_FILES_DIRECTORY = "children"
34
+ const WAIT_AGENT_TOOL = "wait_agent"
35
+
23
36
  /**
24
37
  * How many files, and bytes, a sandbox receives of a run's attachments: also what a parent Agent
25
38
  * and its child hand each other.
@@ -36,6 +49,37 @@ export interface PreparedAgentAttachmentContext {
36
49
  readonly modelFileDataByPartKey: ReadonlyMap<string, AgentFileDataProjection>
37
50
  readonly sandboxFiles: readonly PreparedSandboxAttachmentFile[]
38
51
  readonly manifestJson: string
52
+ /** The images each stored step's tools returned, as the model read them after that step. */
53
+ readonly toolFilesByStep?: ReadonlyMap<string, ModelMessage>
54
+ /**
55
+ * The user attachments the request may inline as images, projected only once the request's
56
+ * inline image budget decides them ({@link settleAttachmentImages}). Until then each reads as
57
+ * the budget had no room for it.
58
+ */
59
+ readonly pendingImages?: ReadonlyMap<string, PendingAttachmentImage>
60
+ }
61
+
62
+ /** What projecting an attachment as an image gave: its inline data, or why there is none. */
63
+ export type AttachmentImageProjection =
64
+ | {
65
+ readonly kind: "inline"
66
+ readonly data: AgentFileDataProjection
67
+ readonly notes: readonly string[]
68
+ }
69
+ | { readonly kind: "not-inlined"; readonly notes: readonly string[] }
70
+
71
+ /** An image's fate in the request: projected, or left out because the budget was used up. */
72
+ export type AttachmentImageOutcome = AttachmentImageProjection | { readonly kind: "budget" }
73
+
74
+ /** A user attachment the request may inline as an image, decoded and encoded only on demand. */
75
+ export interface PendingAttachmentImage {
76
+ project(signal: AbortSignal): Promise<AttachmentImageProjection>
77
+ /** The attachment as the request reads it once its image's fate is known. */
78
+ settle(outcome: AttachmentImageOutcome): {
79
+ readonly entry: PreparedAgentAttachment
80
+ readonly promptText: string
81
+ readonly modelFileData?: AgentFileDataProjection
82
+ }
39
83
  }
40
84
 
41
85
  export interface PreparedAgentAttachment {
@@ -74,6 +118,8 @@ interface AttachmentWorkItem {
74
118
  readonly sandboxName: string
75
119
  readonly inlineContent: boolean
76
120
  readonly origin: "message-file" | "tool-result-file"
121
+ /** For a tool-result file, the call that returned it. */
122
+ readonly toolCall?: { readonly toolName: string; readonly toolCallId: string }
77
123
  }
78
124
 
79
125
  export async function prepareAgentAttachments(input: {
@@ -90,40 +136,58 @@ export async function prepareAgentAttachments(input: {
90
136
  const promptTextByPartKey = new Map<string, string>()
91
137
  const modelFileDataByPartKey = new Map<string, AgentFileDataProjection>()
92
138
  const sandboxFiles: PreparedSandboxAttachmentFile[] = []
93
- const entries: PreparedAgentAttachment[] = []
139
+ const entries: { readonly order: number; readonly entry: PreparedAgentAttachment }[] = []
140
+ const materialized = new Map<string, string>()
141
+ const textInlineBytesByMessage = new Map<string, number>()
142
+ const pendingImages = new Map<string, PendingAttachmentImage>()
94
143
  let sandboxBytes = 0
95
- let textInlineBytes = 0
96
144
 
97
- for (const item of fileWorkItems(input.messages)) {
145
+ // The user's files take the sandbox budget first, in message order: what a user message reads
146
+ // then depends only on the messages before it, never on the tool files the window keeps.
147
+ const items = fileWorkItems(input.messages).map((item, order) => ({ item, order }))
148
+ const userFirst = [
149
+ ...items.filter(({ item }) => item.message.role === "user"),
150
+ ...items.filter(({ item }) => item.message.role !== "user"),
151
+ ]
152
+
153
+ for (const { item, order } of userFirst) {
98
154
  input.signal?.throwIfAborted()
99
155
  const prepared = await prepareOneAttachment({
100
156
  ...input,
101
157
  item,
102
158
  sandboxBytes,
103
- textInlineBytes,
159
+ textInlineBytes: textInlineBytesByMessage.get(item.message.id) ?? 0,
160
+ materialized,
104
161
  })
105
162
  sandboxBytes += prepared.sandboxBytesAdded
106
- textInlineBytes += prepared.textInlineBytesAdded
107
- entries.push(prepared.entry)
163
+ textInlineBytesByMessage.set(
164
+ item.message.id,
165
+ (textInlineBytesByMessage.get(item.message.id) ?? 0) + prepared.textInlineBytesAdded
166
+ )
167
+ entries.push({ order, entry: prepared.entry })
108
168
  promptTextByPartKey.set(prepared.entry.key, prepared.promptText)
109
169
  if (prepared.modelFileData) {
110
170
  modelFileDataByPartKey.set(prepared.entry.key, prepared.modelFileData)
111
171
  }
112
172
  if (prepared.sandboxFile) {
113
173
  sandboxFiles.push(prepared.sandboxFile)
174
+ materialized.set(fileRefKey(prepared.sandboxFile.fileRef), prepared.sandboxFile.path)
114
175
  }
176
+ if (prepared.pendingImage) pendingImages.set(prepared.entry.key, prepared.pendingImage)
115
177
  }
116
178
 
179
+ const ordered = entries.sort((left, right) => left.order - right.order).map(({ entry }) => entry)
117
180
  return {
118
- entries,
181
+ entries: ordered,
119
182
  promptTextByPartKey,
120
183
  modelFileDataByPartKey,
121
184
  sandboxFiles,
185
+ ...(pendingImages.size === 0 ? {} : { pendingImages }),
122
186
  manifestJson: JSON.stringify(
123
187
  {
124
188
  projectId: input.projectId,
125
189
  threadId: input.threadId,
126
- attachments: entries.map((entry) => manifestEntry(entry)),
190
+ attachments: ordered.map((entry) => manifestEntry(entry)),
127
191
  },
128
192
  null,
129
193
  2
@@ -227,18 +291,23 @@ export async function prepareAgentToolFileProjection(input: {
227
291
  }
228
292
  }
229
293
 
294
+ /**
295
+ * Every retained user message keeps its files inline, as its own turn read them, until compaction
296
+ * summarizes it: later turns then send the same bytes. Tool files are metadata in the manifest; the
297
+ * model reads what their call's output showed.
298
+ */
230
299
  function fileWorkItems(messages: readonly AgentMessageRecord[]): AttachmentWorkItem[] {
231
300
  const items: AttachmentWorkItem[] = []
232
- const currentUserMessageId = latestUserMessageId(messages)
233
301
  for (const message of messages) {
234
302
  for (const file of listMessageAttachments(message)) {
303
+ const part = message.parts[file.partIndex]
235
304
  items.push({
236
305
  message,
237
306
  ...file,
238
- inlineContent:
239
- file.origin === "message-file" &&
240
- message.role === "user" &&
241
- message.id === currentUserMessageId,
307
+ inlineContent: file.origin === "message-file" && message.role === "user",
308
+ ...(file.origin === "tool-result-file" && part?.type === "tool-call"
309
+ ? { toolCall: { toolName: part.toolName, toolCallId: part.toolCallId } }
310
+ : {}),
242
311
  })
243
312
  }
244
313
  }
@@ -254,14 +323,6 @@ function fileWorkItems(messages: readonly AgentMessageRecord[]): AttachmentWorkI
254
323
  )
255
324
  }
256
325
 
257
- function latestUserMessageId(messages: readonly AgentMessageRecord[]): string | undefined {
258
- for (let index = messages.length - 1; index >= 0; index -= 1) {
259
- const message = messages[index]
260
- if (message?.role === "user") return message.id
261
- }
262
- return undefined
263
- }
264
-
265
326
  async function prepareOneAttachment(input: {
266
327
  readonly projectId: string
267
328
  readonly threadId: string
@@ -271,13 +332,17 @@ async function prepareOneAttachment(input: {
271
332
  readonly contextDirectory: string
272
333
  readonly inlineImages: boolean
273
334
  readonly sandboxBytes: number
335
+ /** What the message's earlier files took of its inline text budget. */
274
336
  readonly textInlineBytes: number
337
+ /** Where the files already prepared went in the sandbox, by file. */
338
+ readonly materialized: ReadonlyMap<string, string>
275
339
  readonly signal?: AbortSignal
276
340
  }): Promise<{
277
341
  readonly entry: PreparedAgentAttachment
278
342
  readonly promptText: string
279
343
  readonly modelFileData?: AgentFileDataProjection
280
344
  readonly sandboxFile?: PreparedSandboxAttachmentFile
345
+ readonly pendingImage?: PendingAttachmentImage
281
346
  readonly sandboxBytesAdded: number
282
347
  readonly textInlineBytesAdded: number
283
348
  }> {
@@ -303,7 +368,8 @@ async function prepareOneAttachment(input: {
303
368
  let sandboxBytesAdded = 0
304
369
  let textExcerpt: string | undefined
305
370
  let textInlineBytesAdded = 0
306
- let modelFileData: AgentFileDataProjection | undefined
371
+ let projectImage: ((signal: AbortSignal) => Promise<AttachmentImageProjection>) | undefined
372
+ let metadataNote: string | undefined
307
373
 
308
374
  const stat = await safeBlobStat(input.blobStorage, fileRef, notes, signal)
309
375
  if (!stat) {
@@ -319,16 +385,16 @@ async function prepareOneAttachment(input: {
319
385
  mayInlineContent &&
320
386
  remainingTextBytes > 0 &&
321
387
  shouldAttemptTextInline(mediaType, fileName, stat.sizeBytes)
322
- const shouldReadForImage =
323
- mayInlineContent && input.inlineImages && shouldAttemptImageInline(mediaType, fileName)
324
- const needsFullBytes = canMaterializeFile && canMaterializeTotal
388
+ // A tool can return a file the sandbox holds already, such as an attachment view_file showed:
389
+ // its output named that path, and the file stays there once.
390
+ const alreadyAt =
391
+ item.origin === "tool-result-file" ? input.materialized.get(fileRefKey(fileRef)) : undefined
392
+ const needsFullBytes = alreadyAt === undefined && canMaterializeFile && canMaterializeTotal
325
393
  const readLimit = needsFullBytes
326
394
  ? stat.sizeBytes
327
395
  : shouldReadForText
328
396
  ? Math.min(DEFAULT_AGENT_ATTACHMENT_LIMITS.textInlineMaxBytes, remainingTextBytes) + 4
329
- : shouldReadForImage
330
- ? DEFAULT_AGENT_ATTACHMENT_LIMITS.sandboxFileMaxBytes
331
- : 0
397
+ : 0
332
398
 
333
399
  if (needsFullBytes || readLimit > 0) {
334
400
  const read = await readBlobBytes(input.blobStorage, fileRef.blobId, readLimit, signal, {
@@ -343,13 +409,12 @@ async function prepareOneAttachment(input: {
343
409
  }
344
410
  }
345
411
 
346
- if (bytes && needsFullBytes && bytes.byteLength === stat.sizeBytes) {
347
- sandboxPath = sandboxAttachmentPath(
348
- input.contextDirectory,
349
- item.message.id,
350
- item.sandboxName,
351
- fileName
352
- )
412
+ if (alreadyAt !== undefined) {
413
+ sandboxPath = alreadyAt
414
+ } else if (bytes && needsFullBytes && bytes.byteLength === stat.sizeBytes) {
415
+ sandboxPath =
416
+ toolResultSandboxPath(input.contextDirectory, item) ??
417
+ sandboxAttachmentPath(input.contextDirectory, item.message.id, item.sandboxName, fileName)
353
418
  sandboxFile = { key, path: sandboxPath, bytes, fileRef }
354
419
  sandboxBytesAdded = stat.sizeBytes
355
420
  } else if (!canMaterializeFile) {
@@ -376,73 +441,136 @@ async function prepareOneAttachment(input: {
376
441
  }
377
442
  }
378
443
 
379
- if (!textExcerpt) {
380
- const image = await maybeImageData({
381
- bytes,
382
- mediaType,
383
- fileName,
384
- inlineImages: mayInlineContent && input.inlineImages,
385
- hasImageHint: hasImageHint(mediaType, fileName),
386
- signal,
387
- })
388
- if (image) {
389
- if (image.ok) {
390
- inlineDisposition = "image"
391
- notes.push(...image.notes)
392
- modelFileData = {
393
- data: image.dataUrl,
394
- mediaType: image.mediaType,
395
- filename: fileName,
396
- }
397
- } else if (image.notes.length > 0) {
398
- notes.push(...image.notes)
399
- }
400
- }
401
- } else if (hasImageHint(mediaType, fileName)) {
444
+ if (textExcerpt && hasImageHint(mediaType, fileName)) {
402
445
  notes.push("[Image not inlined: attachment was treated as text based on its content.]")
403
446
  }
404
447
  }
405
448
 
449
+ // An image is decoded and encoded only once the request's inline image budget has room for
450
+ // it: see settleAttachmentImages.
451
+ const fullBytes = bytes?.byteLength === stat.sizeBytes ? bytes : undefined
452
+ if (!textExcerpt && mayInlineContent && input.inlineImages) {
453
+ projectImage = (projectSignal) =>
454
+ projectAttachmentImage({
455
+ ...input,
456
+ fileRef,
457
+ fileName,
458
+ mediaType,
459
+ ...(fullBytes === undefined ? {} : { bytes: fullBytes }),
460
+ signal: projectSignal,
461
+ })
462
+ }
463
+
406
464
  if (mayInlineContent && !input.inlineImages && hasImageHint(mediaType, fileName)) {
407
465
  notes.push("[Image not inlined: the selected model does not advertise image input support.]")
408
466
  }
409
467
 
410
- if (inlineDisposition === "metadata-only" && notes.length === 0) {
411
- notes.push(
412
- !item.inlineContent
413
- ? "[Historical file kept as metadata: use view_file with the sandbox path when its contents are needed.]"
414
- : remainingTextBytes === 0 && shouldAttemptTextInline(mediaType, fileName, stat.sizeBytes)
415
- ? "[File not inlined: the attachment text budget is exhausted; use the sandbox path or content URL.]"
416
- : "[File not inlined: available through the sandbox path or content URL.]"
417
- )
468
+ metadataNote = !item.inlineContent
469
+ ? "[Historical file kept as metadata: use view_file with the sandbox path when its contents are needed.]"
470
+ : remainingTextBytes === 0 && shouldAttemptTextInline(mediaType, fileName, stat.sizeBytes)
471
+ ? "[File not inlined: the attachment text budget is exhausted; use the sandbox path or content URL.]"
472
+ : "[File not inlined: available through the sandbox path or content URL.]"
473
+ }
474
+
475
+ const attachment = (
476
+ imageNotes: readonly string[],
477
+ image?: AgentFileDataProjection
478
+ ): { readonly entry: PreparedAgentAttachment; readonly promptText: string } => {
479
+ const disposition = image ? "image" : inlineDisposition
480
+ const allNotes = [...notes, ...imageNotes]
481
+ if (disposition === "metadata-only" && allNotes.length === 0 && metadataNote) {
482
+ allNotes.push(metadataNote)
483
+ }
484
+
485
+ const entry: PreparedAgentAttachment = {
486
+ key,
487
+ messageId: item.message.id,
488
+ partIndex: item.partIndex,
489
+ fileRef,
490
+ fileName,
491
+ mediaType,
492
+ sizeBytes: fileRef.sizeBytes,
493
+ contentPath,
494
+ contentUrl,
495
+ ...(sandboxPath === undefined ? {} : { sandboxPath }),
496
+ inlineDisposition: disposition,
497
+ notes: allNotes,
418
498
  }
499
+ return { entry, promptText: attachmentPromptText(entry, textExcerpt) }
419
500
  }
420
501
 
421
- const entry: PreparedAgentAttachment = {
422
- key,
423
- messageId: item.message.id,
424
- partIndex: item.partIndex,
425
- fileRef,
426
- fileName,
427
- mediaType,
428
- sizeBytes: fileRef.sizeBytes,
429
- contentPath,
430
- contentUrl,
431
- ...(sandboxPath === undefined ? {} : { sandboxPath }),
432
- inlineDisposition,
433
- notes,
502
+ const imageHint = hasImageHint(mediaType, fileName)
503
+ const pendingImage: PendingAttachmentImage | undefined = projectImage && {
504
+ project: projectImage,
505
+ settle: (outcome) => {
506
+ if (outcome.kind === "inline") {
507
+ return { ...attachment(outcome.notes, outcome.data), modelFileData: outcome.data }
508
+ }
509
+ if (outcome.kind === "not-inlined") return attachment(outcome.notes)
510
+ return attachment(imageHint ? [INLINE_IMAGE_BUDGET_NOTE] : [])
511
+ },
434
512
  }
435
513
 
436
514
  return {
437
- entry,
438
- promptText: attachmentPromptText(entry, textExcerpt),
439
- ...(modelFileData === undefined ? {} : { modelFileData }),
515
+ ...(pendingImage ? pendingImage.settle({ kind: "budget" }) : attachment([])),
440
516
  ...(sandboxFile === undefined ? {} : { sandboxFile }),
517
+ ...(pendingImage === undefined ? {} : { pendingImage }),
441
518
  sandboxBytesAdded,
442
519
  textInlineBytesAdded,
443
520
  }
444
521
  }
445
522
 
523
+ /**
524
+ * Decode and encode a user attachment as the request inlines an image, from the bytes already read
525
+ * for the sandbox or from its blob. A file whose bytes are no image is not inlined, without a note
526
+ * unless it was named as one.
527
+ */
528
+ async function projectAttachmentImage(input: {
529
+ readonly blobStorage: AgentRunFileStore
530
+ readonly fileRef: FileRef
531
+ readonly fileName: string
532
+ readonly mediaType: string
533
+ readonly bytes?: Uint8Array
534
+ readonly signal: AbortSignal
535
+ }): Promise<AttachmentImageProjection> {
536
+ let bytes = input.bytes
537
+ if (!bytes) {
538
+ const read = await readBlobBytes(
539
+ input.blobStorage,
540
+ input.fileRef.blobId,
541
+ DEFAULT_AGENT_ATTACHMENT_LIMITS.sandboxFileMaxBytes,
542
+ input.signal
543
+ )
544
+ if (!read.ok) {
545
+ return {
546
+ kind: "not-inlined",
547
+ notes: [
548
+ read.reason === "too_large"
549
+ ? "[File not read inline: file exceeds the attachment read limit.]"
550
+ : `[File not read inline: ${read.reason}.]`,
551
+ ],
552
+ }
553
+ }
554
+ bytes = read.bytes
555
+ }
556
+
557
+ const image = await maybeImageData({
558
+ bytes,
559
+ mediaType: input.mediaType,
560
+ fileName: input.fileName,
561
+ inlineImages: true,
562
+ hasImageHint: hasImageHint(input.mediaType, input.fileName),
563
+ signal: input.signal,
564
+ })
565
+ if (!image) return { kind: "not-inlined", notes: [] }
566
+ if (!image.ok) return { kind: "not-inlined", notes: image.notes }
567
+ return {
568
+ kind: "inline",
569
+ data: { data: image.dataUrl, mediaType: image.mediaType, filename: input.fileName },
570
+ notes: image.notes,
571
+ }
572
+ }
573
+
446
574
  async function safeBlobStat(
447
575
  blobStorage: AgentRunFileStore,
448
576
  fileRef: FileRef,
@@ -674,6 +802,43 @@ export function modelSupportsInlineImages(model: LanguageModel): boolean {
674
802
  )
675
803
  }
676
804
 
805
+ /**
806
+ * The context once the request's inline image budget decided its pending images: each reads inline,
807
+ * or as metadata with the note that says why, in the prompt and in the manifest.
808
+ */
809
+ export function settleAttachmentImages(
810
+ context: PreparedAgentAttachmentContext,
811
+ outcomes: ReadonlyMap<string, AttachmentImageOutcome>
812
+ ): PreparedAgentAttachmentContext {
813
+ const { pendingImages, ...settled } = context
814
+ if (!pendingImages) return context
815
+
816
+ const promptTextByPartKey = new Map(context.promptTextByPartKey)
817
+ const modelFileDataByPartKey = new Map(context.modelFileDataByPartKey)
818
+ const entries = context.entries.map((entry) => {
819
+ const pending = pendingImages.get(entry.key)
820
+ if (!pending) return entry
821
+
822
+ const attachment = pending.settle(outcomes.get(entry.key) ?? { kind: "budget" })
823
+ promptTextByPartKey.set(entry.key, attachment.promptText)
824
+ if (attachment.modelFileData) modelFileDataByPartKey.set(entry.key, attachment.modelFileData)
825
+ return attachment.entry
826
+ })
827
+
828
+ const manifest = JSON.parse(context.manifestJson) as Record<string, unknown>
829
+ return {
830
+ ...settled,
831
+ entries,
832
+ promptTextByPartKey,
833
+ modelFileDataByPartKey,
834
+ manifestJson: JSON.stringify(
835
+ { ...manifest, attachments: entries.map((entry) => manifestEntry(entry)) },
836
+ null,
837
+ 2
838
+ ),
839
+ }
840
+ }
841
+
677
842
  function attachmentPromptText(
678
843
  entry: PreparedAgentAttachment,
679
844
  textExcerpt: string | undefined
@@ -744,6 +909,32 @@ function sandboxAttachmentPath(
744
909
  )
745
910
  }
746
911
 
912
+ /**
913
+ * Where the call that returned a tool file put it in the sandbox, as its output showed: a later
914
+ * turn materializes it there again, so the replayed output still names a file that exists.
915
+ * `wait_agent` copies a child's file under `children/<key>/`, its `logicalPath`; a tool that
916
+ * stored a file put it at its call's tool-file path.
917
+ */
918
+ function toolResultSandboxPath(
919
+ contextDirectory: string,
920
+ item: AttachmentWorkItem
921
+ ): string | undefined {
922
+ const { toolCall, fileRef } = item
923
+ if (!toolCall) return undefined
924
+
925
+ if (toolCall.toolName === WAIT_AGENT_TOOL) {
926
+ const path =
927
+ fileRef.logicalPath === undefined ? undefined : posix.normalize(fileRef.logicalPath)
928
+ if (!path || path.startsWith("/") || path === ".." || path.startsWith("../")) return undefined
929
+ return posix.join(contextDirectory, CHILD_FILES_DIRECTORY, path)
930
+ }
931
+
932
+ const name = fileRef.fileName
933
+ if (!name || name === "." || name === ".." || /[\\/\u0000-\u001f\u007f]/.test(name))
934
+ return undefined
935
+ return posix.join(contextDirectory, agentToolFilePath(toolCall.toolCallId, fileRef, name))
936
+ }
937
+
747
938
  function fileNameFor(fileRef: FileRef): string {
748
939
  const fromFileName = lastPathSegment(fileRef.fileName)
749
940
  if (fromFileName) return fromFileName
@@ -8,6 +8,7 @@ import type { SubagentRunFile } from "@sixb/core/storage"
8
8
  import { NEVER_ABORTED_SIGNAL, waitForAbort } from "./abort"
9
9
  import { readBlob } from "./artifacts/materialize"
10
10
  import {
11
+ CHILD_FILES_DIRECTORY,
11
12
  formatBytes,
12
13
  type PreparedAgentAttachmentContext,
13
14
  SANDBOX_ATTACHMENT_LIMITS,
@@ -33,12 +34,6 @@ import type { AgentRunFiles } from "./types"
33
34
  /** Where a child writes the files its parent gets back, relative to its working directory. */
34
35
  const CHILD_OUTPUT_DIRECTORY = "out"
35
36
 
36
- /**
37
- * Where a parent finds them, a directory per spawn key, in the context directory. They last for
38
- * the turn, like the run's attachments and artifacts.
39
- */
40
- export const CHILD_FILES_DIRECTORY = "children"
41
-
42
37
  /** What a run installs in its context directory that holds files worth handing over. */
43
38
  const HANDED_RUN_DIRECTORIES = ["attachments", "artifacts", "tool-files", CHILD_FILES_DIRECTORY]
44
39
  const SANDBOX_TIMEOUT_MS = 30_000