@sixb/agent 0.2.5 → 0.2.7

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 (70) hide show
  1. package/dist/agent-prompt.d.ts +19 -3
  2. package/dist/agent-prompt.d.ts.map +1 -1
  3. package/dist/background-commands.d.ts +6 -2
  4. package/dist/background-commands.d.ts.map +1 -1
  5. package/dist/computer-runner.d.ts +12 -3
  6. package/dist/computer-runner.d.ts.map +1 -1
  7. package/dist/context-compaction.d.ts.map +1 -1
  8. package/dist/conversation-messages.d.ts +1 -1
  9. package/dist/conversation-messages.d.ts.map +1 -1
  10. package/dist/errors.d.ts +17 -2
  11. package/dist/errors.d.ts.map +1 -1
  12. package/dist/index.d.ts +2 -2
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +693 -365
  15. package/dist/index.js.map +25 -25
  16. package/dist/login-shell.d.ts +18 -2
  17. package/dist/login-shell.d.ts.map +1 -1
  18. package/dist/model-adapters.d.ts +7 -2
  19. package/dist/model-adapters.d.ts.map +1 -1
  20. package/dist/model-lines.d.ts +1 -0
  21. package/dist/model-lines.d.ts.map +1 -1
  22. package/dist/run-agent-turn.d.ts +0 -4
  23. package/dist/run-agent-turn.d.ts.map +1 -1
  24. package/dist/run-child.d.ts +21 -4
  25. package/dist/run-child.d.ts.map +1 -1
  26. package/dist/run-conversation-turn.d.ts +10 -4
  27. package/dist/run-conversation-turn.d.ts.map +1 -1
  28. package/dist/run-environment.d.ts +15 -6
  29. package/dist/run-environment.d.ts.map +1 -1
  30. package/dist/run-fate.d.ts +2 -2
  31. package/dist/run-fate.d.ts.map +1 -1
  32. package/dist/run-sandbox.d.ts +39 -1
  33. package/dist/run-sandbox.d.ts.map +1 -1
  34. package/dist/run-subagent.d.ts.map +1 -1
  35. package/dist/sandbox-api-context.d.ts.map +1 -1
  36. package/dist/subagent-continuation.d.ts +13 -4
  37. package/dist/subagent-continuation.d.ts.map +1 -1
  38. package/dist/subagent-tools.d.ts +29 -2
  39. package/dist/subagent-tools.d.ts.map +1 -1
  40. package/dist/tools/bash.d.ts +1 -1
  41. package/dist/tools/bash.d.ts.map +1 -1
  42. package/dist/tools/model-spec.d.ts +2 -1
  43. package/dist/tools/model-spec.d.ts.map +1 -1
  44. package/dist/types.d.ts +9 -0
  45. package/dist/types.d.ts.map +1 -1
  46. package/package.json +6 -6
  47. package/src/agent-prompt.ts +150 -42
  48. package/src/background-commands.ts +63 -19
  49. package/src/background-notices.ts +3 -2
  50. package/src/computer-runner.ts +135 -80
  51. package/src/context-compaction.ts +1 -0
  52. package/src/conversation-messages.ts +11 -4
  53. package/src/errors.ts +18 -2
  54. package/src/index.ts +7 -2
  55. package/src/login-shell.ts +30 -3
  56. package/src/model-adapters.ts +32 -4
  57. package/src/model-lines.ts +1 -1
  58. package/src/run-agent-turn.ts +25 -3
  59. package/src/run-child.ts +52 -5
  60. package/src/run-conversation-turn.ts +50 -12
  61. package/src/run-environment.ts +95 -24
  62. package/src/run-fate.ts +8 -2
  63. package/src/run-sandbox.ts +110 -1
  64. package/src/run-subagent.ts +17 -7
  65. package/src/sandbox-api-context.ts +7 -1
  66. package/src/subagent-continuation.ts +33 -7
  67. package/src/subagent-tools.ts +141 -27
  68. package/src/tools/bash.ts +10 -11
  69. package/src/tools/model-spec.ts +3 -3
  70. package/src/types.ts +9 -0
@@ -30,7 +30,10 @@ import type { AgentRunSettings } from "./types"
30
30
 
31
31
  /** Opens the sandbox a computer's run works in. */
32
32
  export type OpenComputerSandbox = (input: {
33
- /** The user's folder, for a turn; absent for a child, which works in a folder of its own. */
33
+ /**
34
+ * The user's folder, for a turn and for each child it starts there; absent for a sandbox of
35
+ * its own.
36
+ */
34
37
  readonly workingDirectory?: string
35
38
  /** Where the run's own files go, outside the folder: its commands may write there too. */
36
39
  readonly runFiles: string
@@ -166,15 +169,18 @@ export class ComputerRunner {
166
169
  this.sandbox({
167
170
  runId: run.id,
168
171
  threadId: run.threadId,
169
- executionToken: session.executionToken,
170
- projectId: run.projectId,
172
+ runToken: runTokenFor({
173
+ projectId: run.projectId,
174
+ runId: run.id,
175
+ executionToken: session.executionToken,
176
+ }),
171
177
  folder: this.options.folder,
172
178
  }),
173
- startChild: (child, family, networkPolicy) =>
179
+ startChild: (child, family, from) =>
174
180
  children.start(child, {
175
181
  signal: turnSignal,
176
182
  family,
177
- ...(networkPolicy ? { networkPolicy } : {}),
183
+ ...from,
178
184
  leaseExpiresAt: lease,
179
185
  holdLease: async (childSession) => {
180
186
  held.add(childSession)
@@ -187,6 +193,7 @@ export class ComputerRunner {
187
193
  return () => held.delete(childSession)
188
194
  },
189
195
  }),
196
+ stopChildren: (runId) => children.stopChildrenOf(runId),
190
197
  onDetachedTeardown: (teardown) => this.track(teardown),
191
198
  reportFailure: (error) => this.options.onFailure?.(error),
192
199
  },
@@ -317,12 +324,17 @@ export class ComputerRunner {
317
324
  if (stop.aborted) return null
318
325
  }
319
326
  },
327
+ // A turn always lends its children its folder: this opens one of their own only for a child
328
+ // whose turn lent none.
320
329
  openSandbox: ({ session }) =>
321
330
  this.sandbox({
322
331
  runId: session.run.id,
323
332
  threadId: session.run.threadId,
324
- executionToken: session.executionToken,
325
- projectId: session.run.projectId,
333
+ runToken: runTokenFor({
334
+ projectId: session.run.projectId,
335
+ runId: session.run.id,
336
+ executionToken: session.executionToken,
337
+ }),
326
338
  }),
327
339
  onDetachedTeardown: (teardown) => this.track(teardown),
328
340
  reportFailure: (error) => this.options.onFailure?.(error),
@@ -331,93 +343,136 @@ export class ComputerRunner {
331
343
 
332
344
  /**
333
345
  * A run's sandbox: the user's folder for a turn, which the prompt describes, or a blank folder
334
- * of its own for a child. Its own files go in its thread's directory, outside the folder: the
335
- * prompt names them, so each run of the thread names the same paths.
346
+ * of its own. Its own files go in its thread's directory, outside the folder: the prompt names
347
+ * them, so each run of the thread names the same paths.
336
348
  */
337
349
  private sandbox(input: {
338
350
  readonly runId: string
339
351
  readonly threadId: string
340
- readonly executionToken: string
341
- readonly projectId: string
352
+ readonly runToken: string
342
353
  readonly folder?: string
343
354
  }): OpenRunSandbox {
344
- const { apiUrl } = this.options
345
- const credential = runApiCredential(apiUrl, runTokenFor(input))
346
355
  return async ({ signal }) => {
347
356
  // Real paths: the OS sandbox compares them, and the agent names files by them.
348
357
  await mkdir(this.options.runFilesRoot, { recursive: true })
349
- const runDirectory = join(await realpath(this.options.runFilesRoot), threadDirectory(input))
350
- // Named as a cloud sandbox names them, so a path reads as the run's files wherever it ran.
351
- const runFiles = join(runDirectory, SANDBOX_CONTEXT_DIRECTORY)
358
+ const runFilesRoot = await realpath(this.options.runFilesRoot)
352
359
  const folder = input.folder === undefined ? undefined : await realpath(input.folder)
353
- let held: (() => Promise<void>) | undefined
354
-
355
- // A turn's background commands are its thread's, and so are their files, which every run
356
- // of the thread keeps; a child's end with it.
357
- const background = folder === undefined ? undefined : this.threadBackground(input.threadId)
358
- const kept = () =>
359
- background?.hasCommands ? join(runFiles, BACKGROUND_DIRECTORY) : undefined
360
-
361
- const sandbox: RunSandbox = {
362
- waitBeforeModel: folder !== undefined,
363
- contextDirectory: runFiles,
364
- // The person's own machine: its pages leave from there, and its dev servers are readable.
365
- webNetwork: "computer",
366
- ...(background ? { background } : {}),
367
- acquire: async () => {
368
- const giveBack = await holdRunFiles({
369
- directory: runDirectory,
370
- runId: input.runId,
371
- signal,
372
- })
373
- held = giveBack
374
- try {
375
- // What a sixb killed, or that crashed, left running is stopped before its files go.
376
- if (background && folder !== undefined) {
377
- await this.stopCommandsLeftRunning({
378
- runFiles,
379
- background,
380
- folder,
381
- credential,
382
- signal,
383
- })
384
- }
385
360
 
386
- // Each run starts empty, as with a directory of its own: nothing an earlier run, or
387
- // one that crashed, left there, but its thread's background commands.
388
- await emptyDirectory(runDirectory, kept())
389
- await mkdir(runFiles, { recursive: true })
390
- return {
391
- sandbox: await this.options.openSandbox({
392
- ...(folder === undefined ? {} : { workingDirectory: folder }),
393
- runFiles,
394
- credential,
395
- signal,
361
+ return {
362
+ sandbox: this.runSandbox({
363
+ ...input,
364
+ runFilesRoot,
365
+ ...(folder === undefined ? {} : { folder }),
366
+ signal,
367
+ }),
368
+ }
369
+ }
370
+ }
371
+
372
+ /**
373
+ * The sandbox a run works in, from real paths. A turn lends its folder to each child it starts:
374
+ * the child gets a sandbox of its own there, with the turn's token and its own files directory,
375
+ * and its background commands end with it.
376
+ */
377
+ private runSandbox(input: {
378
+ readonly runId: string
379
+ readonly threadId: string
380
+ readonly runToken: string
381
+ readonly runFilesRoot: string
382
+ readonly folder?: string
383
+ readonly signal: AbortSignal
384
+ /** A child's, in the folder its turn lent it. */
385
+ readonly lent?: boolean
386
+ }): RunSandbox {
387
+ const { apiUrl } = this.options
388
+ const { folder, signal } = input
389
+ const credential = runApiCredential(apiUrl, input.runToken)
390
+ const runDirectory = join(input.runFilesRoot, threadDirectory(input))
391
+ // Named as a cloud sandbox names them, so a path reads as the run's files wherever it ran.
392
+ const runFiles = join(runDirectory, SANDBOX_CONTEXT_DIRECTORY)
393
+ let held: (() => Promise<void>) | undefined
394
+
395
+ // A turn's background commands are its thread's, and so are their files, which every run of
396
+ // the thread keeps; a child's end with it.
397
+ const background =
398
+ folder === undefined || input.lent ? undefined : this.threadBackground(input.threadId)
399
+ const kept = () => (background?.hasCommands ? join(runFiles, BACKGROUND_DIRECTORY) : undefined)
400
+
401
+ return {
402
+ waitBeforeModel: folder !== undefined,
403
+ contextDirectory: runFiles,
404
+ // The person's own machine: its pages leave from there, and its dev servers are readable.
405
+ webNetwork: "computer",
406
+ ...(background ? { background } : {}),
407
+ ...(input.lent ? { lent: true } : {}),
408
+ ...(folder !== undefined && !input.lent
409
+ ? {
410
+ lend: (child) =>
411
+ this.runSandbox({
412
+ runId: child.runId,
413
+ threadId: child.threadId,
414
+ // As in a cloud workspace: the parent's token, which the child's commands narrow
415
+ // to its own run (`SIXB_RUN_ID`).
416
+ runToken: input.runToken,
417
+ runFilesRoot: input.runFilesRoot,
418
+ folder,
419
+ signal: child.signal,
420
+ lent: true,
396
421
  }),
397
- ...(folder === undefined
398
- ? {}
399
- : { promptContext: { workingDirectory: folder, retention: "computer" as const } }),
400
- }
401
- } catch (error) {
402
- await giveBack()
403
- throw error
404
422
  }
405
- },
406
- release: async ({ sandbox }) => {
407
- try {
408
- // A background command runs in the call that started it: its sandbox is torn down
409
- // once the last one it runs ended.
410
- const running = background?.endOf(sandbox)
411
- if (running) this.track(running.then(() => sandbox.destroy()))
412
- else await sandbox.destroy()
413
-
414
- await emptyDirectory(runDirectory, kept())
415
- } finally {
416
- await held?.()
423
+ : {}),
424
+ acquire: async () => {
425
+ const giveBack = await holdRunFiles({
426
+ directory: runDirectory,
427
+ runId: input.runId,
428
+ signal,
429
+ })
430
+ held = giveBack
431
+ try {
432
+ // What a sixb killed, or that crashed, left running is stopped before its files go.
433
+ if (background && folder !== undefined) {
434
+ await this.stopCommandsLeftRunning({
435
+ runFiles,
436
+ background,
437
+ folder,
438
+ credential,
439
+ signal,
440
+ })
417
441
  }
418
- },
419
- }
420
- return { sandbox }
442
+
443
+ // Each run starts empty, as with a directory of its own: nothing an earlier run, or
444
+ // one that crashed, left there, but its thread's background commands.
445
+ await emptyDirectory(runDirectory, kept())
446
+ await mkdir(runFiles, { recursive: true })
447
+ return {
448
+ sandbox: await this.options.openSandbox({
449
+ ...(folder === undefined ? {} : { workingDirectory: folder }),
450
+ runFiles,
451
+ credential,
452
+ signal,
453
+ }),
454
+ ...(folder === undefined
455
+ ? {}
456
+ : { promptContext: { workingDirectory: folder, retention: "computer" as const } }),
457
+ }
458
+ } catch (error) {
459
+ await giveBack()
460
+ throw error
461
+ }
462
+ },
463
+ release: async ({ sandbox }) => {
464
+ try {
465
+ // A background command runs in the call that started it: its sandbox is torn down
466
+ // once the last one it runs ended.
467
+ const running = background?.endOf(sandbox)
468
+ if (running) this.track(running.then(() => sandbox.destroy()))
469
+ else await sandbox.destroy()
470
+
471
+ await emptyDirectory(runDirectory, kept())
472
+ } finally {
473
+ await held?.()
474
+ }
475
+ },
421
476
  }
422
477
  }
423
478
 
@@ -374,6 +374,7 @@ function conversationEstimateShape(
374
374
  ...(authors?.section === undefined ? {} : { conversation: authors.section }),
375
375
  ...(plan.sandboxModels ? { sandboxModels: plan.sandboxModels } : {}),
376
376
  ...(memory ? { memory: memory.prompt } : {}),
377
+ runningModel: plan.model,
377
378
  }),
378
379
  authors ? conversationAuthorsText(authors) : "",
379
380
  ].join("\n"),
@@ -1,6 +1,6 @@
1
1
  import { toModelMessages } from "@sixb/core/internal/agents"
2
2
  import type { ModelCachingIntent, ModelMessage, ModelReasoning } from "@sixb/core/models"
3
- import type { SentSettings } from "./agent-prompt"
3
+ import { renderWorkspaceMovedTag, type SentSettings } from "./agent-prompt"
4
4
  import {
5
5
  attachmentKey,
6
6
  type PreparedAgentAttachmentContext,
@@ -28,6 +28,9 @@ export function conversationModelMessages(input: {
28
28
  }): ModelMessage[] {
29
29
  const { threadContext, attachmentContext } = input
30
30
  const sentTimes = userMessageTimes(threadContext.history, input.project)
31
+ const movedIds = threadContext.history.movedMessageIds
32
+ ? new Set(threadContext.history.movedMessageIds)
33
+ : undefined
31
34
  const authors = input.conversation
32
35
  ? conversationAuthors({
33
36
  conversation: input.conversation,
@@ -36,12 +39,16 @@ export function conversationModelMessages(input: {
36
39
  : undefined
37
40
 
38
41
  return toModelMessages(threadContext.modelMessages, {
39
- // When, then who wrote it: `<sixb_author>` stays the message's last tag. Who takes part is in
40
- // the system prompt, so no message changes when the next one comes.
42
+ // Workspace transition, then when, then who wrote it: `<sixb_author>` stays the message's last
43
+ // tag, and every piece comes from stored data so cached prefixes stay byte-exact across moves.
41
44
  userMessageSuffix: (message) => {
42
45
  if (!message.id) return undefined
43
46
 
44
- const closing = [sentTimes.get(message.id), authors?.byMessageId.get(message.id)]
47
+ const closing = [
48
+ movedIds?.has(message.id) ? renderWorkspaceMovedTag() : undefined,
49
+ sentTimes.get(message.id),
50
+ authors?.byMessageId.get(message.id),
51
+ ]
45
52
  return closing.filter(Boolean).join("\n") || undefined
46
53
  },
47
54
  fileText: ({ message, partIndex }) =>
package/src/errors.ts CHANGED
@@ -2,6 +2,7 @@ import { AgentToolPublicError } from "@sixb/core"
2
2
  import type { AgentCompactionFailureCode } from "@sixb/core/agents/streams"
3
3
  import { AgentExecutionLostError } from "@sixb/core/internal/agents"
4
4
  import { QueueDeliveryLeaseLostError } from "@sixb/core/internal/workers"
5
+ import type { AgentRunDiagnostic } from "@sixb/core/storage"
5
6
 
6
7
  /** A thread could not complete its required preflight compaction. */
7
8
  export class AgentContextCompactionError extends Error {
@@ -75,11 +76,26 @@ export class AgentToolOutputError extends AgentToolPublicError {
75
76
  }
76
77
  }
77
78
 
78
- /** Failed preservation is a failure even when the run was also cancelled. */
79
+ /**
80
+ * The workspace could not be saved as the run ended: it waits for recovery. The run's own outcome
81
+ * stands beside it, recorded with a `workspace_not_saved` diagnostic: an answer that finished is
82
+ * still an answer, and a turn that failed keeps its own error ({@link turnError}).
83
+ */
79
84
  export class AgentEnvironmentSaveError extends Error {
80
85
  readonly name = "AgentEnvironmentSaveError"
81
86
 
82
- constructor() {
87
+ constructor(
88
+ /** What ended the turn before its save failed, when something did. */
89
+ readonly turnError?: unknown
90
+ ) {
83
91
  super("[SixbAgent] Sandbox save or cleanup could not be confirmed. Recovery is required.")
84
92
  }
85
93
  }
94
+
95
+ /** What a run whose workspace could not be saved carries, whatever its outcome. */
96
+ export const WORKSPACE_NOT_SAVED_DIAGNOSTIC = {
97
+ code: "workspace_not_saved",
98
+ severity: "warning",
99
+ scope: "run",
100
+ message: "The workspace could not be saved when this run ended; it waits for recovery.",
101
+ } as const satisfies AgentRunDiagnostic
package/src/index.ts CHANGED
@@ -38,8 +38,13 @@ export {
38
38
  createWorkflowAgentNodeEnvironment,
39
39
  } from "./run-environment"
40
40
  export { agentRunFailureDetails, recordFate } from "./run-fate"
41
- export type { AcquiredRunSandbox, BeforeFinalizeOptions, RunSandbox } from "./run-sandbox"
42
- export { SANDBOX_CONTEXT_DIRECTORY } from "./run-sandbox"
41
+ export type {
42
+ AcquiredRunSandbox,
43
+ BeforeFinalizeOptions,
44
+ LentRunSandboxChild,
45
+ RunSandbox,
46
+ } from "./run-sandbox"
47
+ export { SANDBOX_CONTEXT_DIRECTORY, threadContextDirectory } from "./run-sandbox"
43
48
  export type { SubagentWork } from "./run-subagent"
44
49
  export { runSubagent } from "./run-subagent"
45
50
  export type { WorkflowAgentFailurePhase } from "./run-workflow-agent-node"
@@ -1,3 +1,5 @@
1
+ import { posix } from "node:path"
2
+
1
3
  /**
2
4
  * Runs a script in a bash that is not a login shell, once a login shell has loaded the profile:
3
5
  * the profile's exports reach the script, and its `exit` leaves the login shell alone.
@@ -12,7 +14,32 @@
12
14
  */
13
15
  export const LOGIN_SHELL_SCRIPT = 'exec "$BASH" -c "$1" bash'
14
16
 
15
- /** `bash` arguments that run `script` as {@link LOGIN_SHELL_SCRIPT} does. */
16
- export function loginShellArgs(script: string): string[] {
17
- return ["-lc", LOGIN_SHELL_SCRIPT, "bash", script]
17
+ /**
18
+ * {@link LOGIN_SHELL_SCRIPT}, in a directory the shell changes to itself. A directory that does not
19
+ * exist fails the command with bash's own message, which the model can read and correct. Given
20
+ * to the provider instead, a missing one fails the call itself, not the command. Falling off the
21
+ * end, unlike `exit`, does not run `~/.bash_logout`.
22
+ *
23
+ * Arguments: the directory, then the script.
24
+ */
25
+ export const LOGIN_SHELL_SCRIPT_IN_DIRECTORY = 'cd -- "$1" && exec "$BASH" -c "$2" bash'
26
+
27
+ /** `bash` arguments that run `script` as {@link LOGIN_SHELL_SCRIPT} does, in `directory` if given. */
28
+ export function loginShellArgs(script: string, directory?: string): string[] {
29
+ return directory === undefined
30
+ ? ["-lc", LOGIN_SHELL_SCRIPT, "bash", script]
31
+ : ["-lc", LOGIN_SHELL_SCRIPT_IN_DIRECTORY, "bash", directory, script]
32
+ }
33
+
34
+ /**
35
+ * The absolute directory a command's `cwd` names, for the shell to change to. A relative one
36
+ * resolves against the sandbox's working directory, as the bash tool describes it: in a workspace
37
+ * cloned from Git, that is the checkout, not the provider's own directory above it. A model's
38
+ * `cwd` never reaches the provider: see {@link LOGIN_SHELL_SCRIPT_IN_DIRECTORY}.
39
+ */
40
+ export function commandDirectory(
41
+ workingDirectory: string,
42
+ cwd: string | undefined
43
+ ): string | undefined {
44
+ return cwd === undefined ? undefined : posix.resolve(workingDirectory, cwd)
18
45
  }
@@ -1,5 +1,9 @@
1
1
  import type { AgentMessagePart, JsonValue } from "@sixb/core"
2
- import { AgentToolPublicError } from "@sixb/core"
2
+ import {
3
+ AgentToolPublicError,
4
+ SandboxNotRunningError,
5
+ SandboxRequestRefusedError,
6
+ } from "@sixb/core"
3
7
  import {
4
8
  type AgentToolCall,
5
9
  type AgentToolCallFile,
@@ -267,7 +271,31 @@ function assertUnreachableModelPart(part: never, errorDetails?: AgentErrorDetail
267
271
  )
268
272
  }
269
273
 
270
- /** Expose only failures that the tool author explicitly marked as safe for the model and storage. */
271
- export function agentToolErrorText(error: unknown): string {
272
- return error instanceof AgentToolPublicError ? error.message : "An error occurred."
274
+ /** What a tool says when its sandbox stopped: the run ends right after, so this is its last word. */
275
+ const SANDBOX_STOPPED_TOOL_TEXT =
276
+ "The sandbox stopped: commands and files are no longer available in it."
277
+
278
+ /**
279
+ * Expose only failures that the tool author explicitly marked as safe for the model and storage,
280
+ * a stopped sandbox, in fixed words, even when the tool wrapped it, and a request the sandbox
281
+ * refused, whose message providers keep safe to show: nothing ran, and the model can change what
282
+ * it asked for.
283
+ */
284
+ export function agentToolErrorText(error: unknown, fallback = "An error occurred."): string {
285
+ if (error instanceof AgentToolPublicError) return error.message
286
+ if (foundSandboxStopped(error)) return SANDBOX_STOPPED_TOOL_TEXT
287
+ if (error instanceof SandboxRequestRefusedError) {
288
+ return `The sandbox refused it, so nothing ran: ${error.message.replace(/^\[Sandbox\]\s*/, "")}`
289
+ }
290
+ return fallback
291
+ }
292
+
293
+ function foundSandboxStopped(error: unknown): boolean {
294
+ // Bounded: a cause chain can loop.
295
+ let cause = error
296
+ for (let depth = 0; depth < 8 && cause instanceof Error; depth++) {
297
+ if (cause instanceof SandboxNotRunningError) return true
298
+ cause = cause.cause
299
+ }
300
+ return false
273
301
  }
@@ -23,6 +23,6 @@ export function renderModelLine(input: {
23
23
  }
24
24
 
25
25
  // A provider's catalog text may span lines; each model keeps to one.
26
- function oneLine(text: string): string {
26
+ export function oneLine(text: string): string {
27
27
  return text.replace(/\s+/g, " ").trim()
28
28
  }
@@ -22,7 +22,12 @@ import {
22
22
  import { stepAskedUser } from "./ask-tool"
23
23
  import { createAgentContextGuard } from "./context-guard"
24
24
  import { conversationModelMessages, conversationModelSettings } from "./conversation-messages"
25
- import { AgentContextCompactionError, throwIfExecutionLost } from "./errors"
25
+ import {
26
+ AgentContextCompactionError,
27
+ AgentEnvironmentSaveError,
28
+ throwIfExecutionLost,
29
+ WORKSPACE_NOT_SAVED_DIAGNOSTIC,
30
+ } from "./errors"
26
31
  import type { ResolvedAgentExecutionPlan } from "./execution-plan"
27
32
  import type { ConversationReaders } from "./message-authors"
28
33
  import type { ConversationAgentExecutionEnvironment } from "./run-environment"
@@ -377,7 +382,8 @@ export async function runAgentTurn(input: RunAgentTurnInput): Promise<AgentRunRe
377
382
  const interruptedBeforeCommit = await finalizeIfInterrupted()
378
383
  if (interruptedBeforeCommit) return interruptedBeforeCommit
379
384
 
380
- await context.beforeFinalize?.()
385
+ const unsaved = await saveWorkspace(context)
386
+ if (unsaved) diagnostics.push(unsaved)
381
387
  const finalizedRun = await input.session.finish(
382
388
  {
383
389
  status: "succeeded",
@@ -403,6 +409,21 @@ export async function runAgentTurn(input: RunAgentTurnInput): Promise<AgentRunRe
403
409
  * waiting, or decided and not reported to the model yet, its children's included.
404
410
  */
405
411
 
412
+ /**
413
+ * Save the turn's workspace before its terminal write. One that could not be saved waits for
414
+ * recovery, and the turn ends as it would have, with a diagnostic that says so: the answer, or the
415
+ * stop, is what happened.
416
+ */
417
+ async function saveWorkspace(context: AgentTurnContext): Promise<AgentRunDiagnostic | undefined> {
418
+ try {
419
+ await context.beforeFinalize?.()
420
+ return undefined
421
+ } catch (error) {
422
+ if (error instanceof AgentEnvironmentSaveError) return WORKSPACE_NOT_SAVED_DIAGNOSTIC
423
+ throw error
424
+ }
425
+ }
426
+
406
427
  /**
407
428
  * Whether the worker's stop, rather than the user's, ended the turn. Whichever fired first wins:
408
429
  * the combined turn signal carries the reason of the first source that aborted it.
@@ -452,12 +473,13 @@ async function finalizeInterruptedTurn(input: {
452
473
  const { session, context, run, modelId, finishReason } = input
453
474
  const messages = input.messages && input.messages.length > 0 ? input.messages : undefined
454
475
 
455
- await context.beforeFinalize?.()
476
+ const unsaved = await saveWorkspace(context)
456
477
 
457
478
  const outcome = {
458
479
  status: "cancelled" as const,
459
480
  ...(modelId === undefined ? {} : { modelId }),
460
481
  ...(finishReason === undefined ? {} : { finishReason }),
482
+ ...(unsaved === undefined ? {} : { diagnostics: [unsaved] }),
461
483
  }
462
484
  if (!messages) {
463
485
  const finalizedRun = await session.finish(outcome)
package/src/run-child.ts CHANGED
@@ -28,6 +28,7 @@ import {
28
28
  type OpenRunSandbox,
29
29
  } from "./run-environment"
30
30
  import { agentRunFailureDetails, recordFate } from "./run-fate"
31
+ import { type RunSandbox, threadContextDirectory, withContextDirectory } from "./run-sandbox"
31
32
  import { runSubagent, type SubagentWork } from "./run-subagent"
32
33
  import { SubagentInbox } from "./subagent-inbox"
33
34
  import { type AgentTurnRuntime, createAgentTurnRuntime } from "./turn-runtime"
@@ -50,7 +51,10 @@ export interface ChildRunnerHost {
50
51
  run: SubagentRunRecord,
51
52
  claim: { readonly leaseExpiresAt: string; readonly stop: AbortSignal }
52
53
  ): Promise<AgentRunSession<SubagentRunRecord> | null>
53
- /** The sandbox the child works in, opened when it first needs one. */
54
+ /**
55
+ * The sandbox the child works in, opened when it first needs one: for a child whose parent
56
+ * lends it no workspace.
57
+ */
54
58
  openSandbox(child: {
55
59
  readonly session: AgentRunSession<SubagentRunRecord>
56
60
  readonly context: AgentExecutionContext
@@ -77,6 +81,11 @@ export interface ChildParent {
77
81
  readonly family: FamilyMailbox
78
82
  /** The network the turn's `web_fetch` follows, which the child's follows too. */
79
83
  readonly networkPolicy?: SandboxNetworkPolicy
84
+ /**
85
+ * The turn's workspace, which it lends its children (`RunSandbox.lend`): each runs its tools
86
+ * there instead of in a sandbox of its own. Absent when the turn has none to lend.
87
+ */
88
+ readonly workspace?: NonNullable<RunSandbox["lend"]>
80
89
  }
81
90
 
82
91
  interface RunningChild {
@@ -87,9 +96,10 @@ interface RunningChild {
87
96
  }
88
97
 
89
98
  /**
90
- * Runs the children of a runner's turns. A child holds its own run, session, token and sandbox,
91
- * but no lease of its own: its parent's renewals renew it, and a runner that stops takes its
92
- * children with it. A child left running once its parent ended is ended when its lease lapses.
99
+ * Runs the children of a runner's turns. A child holds its own run, session and token, and works in
100
+ * its parent's workspace when the turn lends it one, else in a sandbox of its own. It holds no
101
+ * lease of its own: its parent's renewals renew it, and a runner that stops takes its children
102
+ * with it. A child left running once its parent ended is ended when its lease lapses.
93
103
  */
94
104
  export class ChildRunner {
95
105
  /** Children running here, by run id: a child already running is never started twice. */
@@ -207,7 +217,12 @@ export class ChildRunner {
207
217
  const inbox = new SubagentInbox(parent.family.child(run.id), run)
208
218
  const childEnvironment = await createSubagentEnvironment({
209
219
  session,
210
- openSandbox: this.host.openSandbox({ session, context, execution, thread }),
220
+ openSandbox: parent.workspace
221
+ ? this.lentSandbox(session, parent.workspace)
222
+ : this.ownSandbox(
223
+ session,
224
+ this.host.openSandbox({ session, context, execution, thread })
225
+ ),
211
226
  context,
212
227
  plan,
213
228
  run,
@@ -283,6 +298,38 @@ export class ChildRunner {
283
298
  }
284
299
  }
285
300
 
301
+ /** The parent's workspace, lent to the child. */
302
+ private lentSandbox(
303
+ session: AgentRunSession<SubagentRunRecord>,
304
+ lend: NonNullable<RunSandbox["lend"]>
305
+ ): OpenRunSandbox {
306
+ const { run } = session
307
+
308
+ return async ({ signal }) => ({
309
+ sandbox: lend({ runId: run.id, threadId: run.threadId, signal }),
310
+ })
311
+ }
312
+
313
+ /**
314
+ * A sandbox of the child's own. A thread that worked in its parent's workspace keeps its run
315
+ * files where its earlier runs had them, so the paths its history names hold.
316
+ */
317
+ private ownSandbox(
318
+ session: AgentRunSession<SubagentRunRecord>,
319
+ open: OpenRunSandbox
320
+ ): OpenRunSandbox {
321
+ const { run } = session
322
+ if (!run.spec.inParentWorkspace) return open
323
+
324
+ return async (lifecycle) => {
325
+ const opened = await open(lifecycle)
326
+ return {
327
+ ...opened,
328
+ sandbox: withContextDirectory(opened.sandbox, threadContextDirectory(run.threadId)),
329
+ }
330
+ }
331
+ }
332
+
286
333
  /** Everything a child needs before its first model call, read through its session. */
287
334
  private async prepare(session: AgentRunSession<SubagentRunRecord>) {
288
335
  const { run } = session