@sixb/agent 0.2.6 → 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 (57) hide show
  1. package/dist/agent-prompt.d.ts +6 -0
  2. package/dist/agent-prompt.d.ts.map +1 -1
  3. package/dist/background-commands.d.ts +4 -0
  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/errors.d.ts +17 -2
  8. package/dist/errors.d.ts.map +1 -1
  9. package/dist/index.d.ts +2 -2
  10. package/dist/index.d.ts.map +1 -1
  11. package/dist/index.js +381 -152
  12. package/dist/index.js.map +20 -20
  13. package/dist/login-shell.d.ts +2 -2
  14. package/dist/model-adapters.d.ts +3 -1
  15. package/dist/model-adapters.d.ts.map +1 -1
  16. package/dist/run-agent-turn.d.ts +0 -4
  17. package/dist/run-agent-turn.d.ts.map +1 -1
  18. package/dist/run-child.d.ts +21 -4
  19. package/dist/run-child.d.ts.map +1 -1
  20. package/dist/run-conversation-turn.d.ts +10 -4
  21. package/dist/run-conversation-turn.d.ts.map +1 -1
  22. package/dist/run-environment.d.ts +15 -6
  23. package/dist/run-environment.d.ts.map +1 -1
  24. package/dist/run-fate.d.ts +2 -2
  25. package/dist/run-fate.d.ts.map +1 -1
  26. package/dist/run-sandbox.d.ts +28 -0
  27. package/dist/run-sandbox.d.ts.map +1 -1
  28. package/dist/run-subagent.d.ts.map +1 -1
  29. package/dist/subagent-continuation.d.ts +13 -4
  30. package/dist/subagent-continuation.d.ts.map +1 -1
  31. package/dist/subagent-tools.d.ts +20 -3
  32. package/dist/subagent-tools.d.ts.map +1 -1
  33. package/dist/tools/model-spec.d.ts +2 -1
  34. package/dist/tools/model-spec.d.ts.map +1 -1
  35. package/dist/types.d.ts +9 -0
  36. package/dist/types.d.ts.map +1 -1
  37. package/package.json +6 -6
  38. package/src/agent-prompt.ts +90 -16
  39. package/src/background-commands.ts +55 -13
  40. package/src/background-notices.ts +3 -2
  41. package/src/computer-runner.ts +135 -80
  42. package/src/errors.ts +18 -2
  43. package/src/index.ts +7 -2
  44. package/src/login-shell.ts +2 -2
  45. package/src/model-adapters.ts +11 -2
  46. package/src/run-agent-turn.ts +25 -3
  47. package/src/run-child.ts +52 -5
  48. package/src/run-conversation-turn.ts +43 -14
  49. package/src/run-environment.ts +57 -13
  50. package/src/run-fate.ts +8 -2
  51. package/src/run-sandbox.ts +50 -0
  52. package/src/run-subagent.ts +9 -6
  53. package/src/subagent-continuation.ts +33 -7
  54. package/src/subagent-tools.ts +128 -32
  55. package/src/tools/bash.ts +1 -1
  56. package/src/tools/model-spec.ts +3 -3
  57. package/src/types.ts +9 -0
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"
@@ -17,8 +17,8 @@ export const LOGIN_SHELL_SCRIPT = 'exec "$BASH" -c "$1" bash'
17
17
  /**
18
18
  * {@link LOGIN_SHELL_SCRIPT}, in a directory the shell changes to itself. A directory that does not
19
19
  * exist fails the command with bash's own message, which the model can read and correct. Given
20
- * to the sandbox instead, it would refuse to start the command, and a refused command leaves the
21
- * workspace unconfirmed. Falling off the end, unlike `exit`, does not run `~/.bash_logout`.
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
22
  *
23
23
  * Arguments: the directory, then the script.
24
24
  */
@@ -1,5 +1,9 @@
1
1
  import type { AgentMessagePart, JsonValue } from "@sixb/core"
2
- import { AgentToolPublicError, SandboxNotRunningError } 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,
@@ -273,11 +277,16 @@ const SANDBOX_STOPPED_TOOL_TEXT =
273
277
 
274
278
  /**
275
279
  * Expose only failures that the tool author explicitly marked as safe for the model and storage,
276
- * and a stopped sandbox, in fixed words, even when the tool wrapped it.
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.
277
283
  */
278
284
  export function agentToolErrorText(error: unknown, fallback = "An error occurred."): string {
279
285
  if (error instanceof AgentToolPublicError) return error.message
280
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
+ }
281
290
  return fallback
282
291
  }
283
292
 
@@ -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
@@ -8,7 +8,6 @@ import {
8
8
  import { createSixbError } from "@sixb/core/internal/errors"
9
9
  import { ModelUsageRecordingError } from "@sixb/core/internal/model-execution"
10
10
  import { isAbortError } from "@sixb/core/internal/workers"
11
- import type { SandboxNetworkPolicy } from "@sixb/core/sandboxes"
12
11
  import type {
13
12
  AgentRunRecord,
14
13
  AgentThreadParticipantRecord,
@@ -20,12 +19,18 @@ import type {
20
19
  } from "@sixb/core/storage"
21
20
  import { createAskUserTool } from "./ask-tool"
22
21
  import { prepareAgentModel } from "./context-budget"
23
- import { AgentEnvironmentSaveError, AgentRequesterLeftThreadError, isLostExecution } from "./errors"
22
+ import {
23
+ AgentEnvironmentSaveError,
24
+ AgentRequesterLeftThreadError,
25
+ isLostExecution,
26
+ WORKSPACE_NOT_SAVED_DIAGNOSTIC,
27
+ } from "./errors"
24
28
  import { resolveRunPlan } from "./execution-plan"
25
29
  import type { AgentRunFailure } from "./failure"
26
30
  import type { FamilyMailbox } from "./family-mailbox"
27
31
  import { agentRequester } from "./requester"
28
32
  import { runAgentTurn, stoppedByWorker } from "./run-agent-turn"
33
+ import type { ChildParent } from "./run-child"
29
34
  import {
30
35
  type ConversationAgentExecutionEnvironment,
31
36
  createConversationAgentEnvironment,
@@ -57,14 +62,20 @@ export interface ConversationTurnRunner {
57
62
  readonly thread: AgentThreadRecord | null
58
63
  }): OpenRunSandbox
59
64
  /**
60
- * Run a child the turn spawned or continues, beside the turn, on the turn's mailbox, its
61
- * `web_fetch` following the network the turn's sandbox declared.
65
+ * Run a child the turn spawned or continues, beside the turn, on the turn's mailbox: in the
66
+ * turn's workspace when it lends one, its `web_fetch` following the network the turn's sandbox
67
+ * declared.
62
68
  */
63
69
  startChild(
64
70
  run: SubagentRunRecord,
65
71
  family: FamilyMailbox,
66
- networkPolicy: SandboxNetworkPolicy | undefined
72
+ turn: Pick<ChildParent, "networkPolicy" | "workspace">
67
73
  ): void
74
+ /**
75
+ * Stop the turn's children still running, and wait for them to record it. A turn that lends its
76
+ * workspace calls it before saving it, so no child works in a workspace being saved.
77
+ */
78
+ stopChildren(runId: string): Promise<void>
68
79
  /** A sandbox teardown that outlives the turn: the runner waits for it before it stops. */
69
80
  onDetachedTeardown(teardown: Promise<void>): void
70
81
  /** A turn that failed: the runner reports it, once its end is recorded. */
@@ -110,14 +121,19 @@ export async function runConversationTurn(input: {
110
121
  runner.settings,
111
122
  run,
112
123
  session,
113
- (child, family) => {
124
+ (child, family, inParentWorkspace) => {
114
125
  // Children start from the turn's tools, once its environment holds its sandbox.
115
126
  if (!environment) {
116
127
  throw new Error(
117
128
  `[SixbAgent] Agent run '${run.id}' started a sub-agent before its sandbox.`
118
129
  )
119
130
  }
120
- runner.startChild(child, family, environment.networkPolicy)
131
+ runner.startChild(child, family, {
132
+ ...(environment.networkPolicy ? { networkPolicy: environment.networkPolicy } : {}),
133
+ ...(inParentWorkspace && environment.lendWorkspace
134
+ ? { workspace: environment.lendWorkspace }
135
+ : {}),
136
+ })
121
137
  },
122
138
  prepared.thread?.movedAt
123
139
  )
@@ -139,6 +155,7 @@ export async function runConversationTurn(input: {
139
155
  execution: prepared.execution,
140
156
  thread: prepared.thread,
141
157
  }),
158
+ stopChildren: () => runner.stopChildren(run.id),
142
159
  preflight: { budget: prepared.model.budget, runtime },
143
160
  context: prepared.context,
144
161
  plan,
@@ -176,7 +193,12 @@ export async function runConversationTurn(input: {
176
193
  })
177
194
  } catch (caughtError) {
178
195
  let error = caughtError
196
+ // A workspace that could not be saved leaves the turn's own error standing, when it had one:
197
+ // the run says what went wrong, and a diagnostic says the workspace waits for recovery.
179
198
  let environmentSaveFailed = error instanceof AgentEnvironmentSaveError
199
+ if (error instanceof AgentEnvironmentSaveError && error.turnError !== undefined) {
200
+ error = error.turnError
201
+ }
180
202
  // Its runner lost the run: touch nothing; whoever holds it now ends it.
181
203
  if (isLostExecution(error, signal)) return
182
204
  // It ended, but its end could not be recorded (storage down): its runner tries again.
@@ -186,18 +208,24 @@ export async function runConversationTurn(input: {
186
208
  await environment.beforeFinalize()
187
209
  } catch (saveError) {
188
210
  if (saveError instanceof AgentExecutionLostError) return
189
- // A workspace its provider stopped cannot be cleaned and saved: it waits for its owner, and
190
- // the run still says why it ended.
191
- const stop = sandboxStopOf(error)
192
- error = stop ? sandboxStoppedError(stop, SANDBOX_STOPPED_UNSAVED_MESSAGE) : saveError
193
- environmentSaveFailed = true
211
+ if (saveError instanceof AgentEnvironmentSaveError) environmentSaveFailed = true
212
+ else
213
+ console.error(
214
+ `[SixbAgent] Agent run '${run.id}' could not finalize its environment:`,
215
+ saveError
216
+ )
194
217
  }
195
218
  }
219
+
220
+ // A workspace its provider stopped cannot be cleaned and saved: it waits for its owner, and
221
+ // the run says why it ended and what to do.
222
+ const stop = environmentSaveFailed ? sandboxStopOf(error) : undefined
223
+ if (stop) error = sandboxStoppedError(stop, SANDBOX_STOPPED_UNSAVED_MESSAGE)
196
224
  // A user cancel is read off its own signal, so it records `cancelled` however the aborted
197
225
  // stream surfaced. `recordFate` retries a blip, and throws AgentFinalizationError past it.
198
226
  const aborted =
199
227
  error instanceof AgentRequesterLeftThreadError ||
200
- (!environmentSaveFailed &&
228
+ (!(error instanceof AgentEnvironmentSaveError) &&
201
229
  !(error instanceof ModelUsageRecordingError) &&
202
230
  (signal.aborted || session.cancelled.aborted || isAbortError(error)))
203
231
  // A runner that stops, unlike a user cancel, leaves the user something to resume.
@@ -206,7 +234,8 @@ export async function runConversationTurn(input: {
206
234
  session,
207
235
  aborted ? "cancelled" : "failed",
208
236
  interrupted ? new AgentTurnInterruptedError(run.id) : error,
209
- !aborted && work && work.length > 0 ? work : undefined
237
+ !aborted && work && work.length > 0 ? work : undefined,
238
+ environmentSaveFailed ? [WORKSPACE_NOT_SAVED_DIAGNOSTIC] : []
210
239
  )
211
240
  if (finalized) {
212
241
  if (finalized.run.status === "failed") {
@@ -58,7 +58,7 @@ import {
58
58
  } from "./context-compaction"
59
59
  import { type ConversationMemory, loadConversationMemory } from "./conversation-memory"
60
60
  import { conversationModelMessages } from "./conversation-messages"
61
- import { isLostExecution } from "./errors"
61
+ import { AgentEnvironmentSaveError, isLostExecution } from "./errors"
62
62
  import type { ResolvedAgentExecutionPlan } from "./execution-plan"
63
63
  import { InlineImageBudget } from "./inline-images"
64
64
  import { type ConversationReaders, conversationAuthors } from "./message-authors"
@@ -148,6 +148,8 @@ export interface ConversationAgentExecutionEnvironment extends AgentExecutionEnv
148
148
  readonly bytesPerToken?: number
149
149
  /** The network its sandbox declared, which `web_fetch` follows: its children's too. */
150
150
  readonly networkPolicy?: SandboxNetworkPolicy
151
+ /** Its workspace, which its children work in (`RunSandbox.lend`), when it has one to lend. */
152
+ readonly lendWorkspace?: NonNullable<RunSandbox["lend"]>
151
153
  }
152
154
 
153
155
  /**
@@ -200,6 +202,11 @@ export interface CreateConversationAgentEnvironmentInput extends CreateAgentEnvi
200
202
  readonly frameworkTools?: readonly ModelTool[]
201
203
  /** Its children, which `wait` and `stop` reach beside its background commands. */
202
204
  readonly children?: WaitableChildren
205
+ /**
206
+ * Stop its children still running, and wait for them to record it: called before a workspace
207
+ * it lends them is saved, so none of them works in it meanwhile.
208
+ */
209
+ readonly stopChildren?: () => Promise<void>
203
210
  }
204
211
 
205
212
  export interface CreateSubagentEnvironmentInput extends CreateAgentEnvironmentInput {
@@ -431,6 +438,7 @@ export async function createConversationAgentEnvironment(
431
438
  ontologyDocs,
432
439
  frameworkTools: input.frameworkTools,
433
440
  ...(input.children ? { children: input.children } : {}),
441
+ ...(sandbox.lend && input.stopChildren ? { beforeSave: input.stopChildren } : {}),
434
442
  ...(memory ? { memory } : {}),
435
443
  ...(conversation === undefined ? {} : { conversation }),
436
444
  onDetachedTeardown: input.onDetachedTeardown,
@@ -458,12 +466,17 @@ export async function createConversationAgentEnvironment(
458
466
  ...(compactInTurn ? { compactInTurn } : {}),
459
467
  ...(prepared?.bytesPerToken === undefined ? {} : { bytesPerToken: prepared.bytesPerToken }),
460
468
  ...(sandbox.networkPolicy ? { networkPolicy: sandbox.networkPolicy } : {}),
469
+ ...(sandbox.lend ? { lendWorkspace: sandbox.lend.bind(sandbox) } : {}),
461
470
  }
462
471
  } catch (error) {
463
472
  // Preparation can fail before the worker receives this environment. Preserve here, before
464
473
  // the worker records the run's terminal outcome; a lost execution must touch nothing.
465
474
  try {
466
475
  if (!isLostExecution(error, input.signal)) await sandbox.beforeFinalize?.()
476
+ } catch (saveError) {
477
+ // The preparation's own error is what ended the turn: it stays, beside the failed save.
478
+ if (saveError instanceof AgentEnvironmentSaveError) throw new AgentEnvironmentSaveError(error)
479
+ throw saveError
467
480
  } finally {
468
481
  // A workspace the summary acquired goes back as the environment would have given it.
469
482
  if (environment) await environment.dispose()
@@ -474,13 +487,15 @@ export async function createConversationAgentEnvironment(
474
487
  }
475
488
 
476
489
  /**
477
- * Build an isolated environment for one headless child Agent. It knows the project as its parent
478
- * does (ontology docs, memory to read), holds the files its parent handed over at their paths, and
479
- * publishes into its conversation, as its own run.
490
+ * Build the environment of one headless child Agent. It knows the project as its parent does
491
+ * (ontology docs, memory to read), and publishes into its conversation, as its own run.
480
492
  *
481
- * On a provider that resumes sandboxes, its thread keeps its workspace while it pauses: the run
482
- * that continues it finds every file where it was. Elsewhere, or once those files were lost, it
483
- * starts blank, with the handed files and what the paused run left in `out/` given back.
493
+ * A child whose parent lends it its workspace works there, on the parent's files: it is handed
494
+ * none and hands none back. Otherwise it works in a sandbox of its own, which holds the files its
495
+ * parent handed over at their paths. On a provider that resumes sandboxes, its thread keeps that
496
+ * workspace while it pauses: the run that continues it finds every file where it was. Elsewhere,
497
+ * or once those files were lost, it starts blank, with the handed files and what the paused run
498
+ * left in `out/` given back.
484
499
  */
485
500
  export async function createSubagentEnvironment(
486
501
  input: CreateSubagentEnvironmentInput
@@ -546,8 +561,15 @@ async function startSubagentEnvironment(
546
561
  const { context, plan, run, conversation, sandbox, resumed, preflight } = input
547
562
  const signal = input.signal ?? NEVER_ABORTED_SIGNAL
548
563
  const networkPolicy = input.parentNetworkPolicy ?? sandbox.networkPolicy
549
- // Still listed, as handed over, but never copied over what the child made of them.
550
- const files = resumed ? (run.spec.files ?? []) : subagentSandboxFiles(run, input.history.paused)
564
+ const readOnly = run.spec.readOnly === true
565
+
566
+ // Still listed, as handed over, but never copied over what the child made of them. A child in
567
+ // its parent's workspace has the parent's files already.
568
+ const files = sandbox.lent
569
+ ? []
570
+ : resumed
571
+ ? (run.spec.files ?? [])
572
+ : subagentSandboxFiles(run, input.history.paused)
551
573
  const inlineImages = modelSupportsInlineImages(plan.model)
552
574
  const [memory, handedContext] = await Promise.all([
553
575
  // As of the thread's start, as a conversation's: each run of the child reads the same memory.
@@ -625,6 +647,7 @@ async function startSubagentEnvironment(
625
647
  publishes: publishing !== undefined,
626
648
  web: plan.web,
627
649
  networkPolicy,
650
+ readOnly,
628
651
  }),
629
652
  ...(input.frameworkTools ?? []),
630
653
  ]
@@ -641,6 +664,7 @@ async function startSubagentEnvironment(
641
664
  context,
642
665
  plan,
643
666
  ontologyDocs: plan.ontologyDocs,
667
+ readOnly,
644
668
  ...(workspace ? { workspace } : {}),
645
669
  ...(memory ? { memory } : {}),
646
670
  }),
@@ -662,6 +686,7 @@ async function startSubagentEnvironment(
662
686
  context,
663
687
  plan,
664
688
  ontologyDocs: plan.ontologyDocs,
689
+ readOnly,
665
690
  ...(memory ? { memory } : {}),
666
691
  }),
667
692
  tools: contextEstimateTools(tools),
@@ -697,6 +722,7 @@ async function startSubagentEnvironment(
697
722
  mode: "subagent",
698
723
  sandbox,
699
724
  ...(networkPolicy ? { networkPolicy } : {}),
725
+ readOnly,
700
726
  acquire: input.acquire,
701
727
  sandboxSignal: input.signal,
702
728
  failureSignal: input.failureSignal,
@@ -849,6 +875,10 @@ interface AgentEnvironmentSetup
849
875
  readonly frameworkTools?: readonly ModelTool[]
850
876
  /** The Agent's children, which `wait` and `stop` reach beside its background commands. */
851
877
  readonly children?: WaitableChildren
878
+ /** Runs before the workspace is saved, as the run ends: its children leave the one it lends. */
879
+ readonly beforeSave?: () => Promise<void>
880
+ /** A child that must leave the files as they are: no `edit` and no `write`. */
881
+ readonly readOnly?: boolean
852
882
  /**
853
883
  * A conversation, or a child of one, publishes artifacts into its conversation, through its
854
884
  * session, and edits them from their installed copies; other runs return text.
@@ -952,8 +982,11 @@ async function startAgentEnvironment(
952
982
  // One per run: `edit` and `write` change only files this run read, as it read them.
953
983
  const fileReads = new FileReadLedger()
954
984
  appendBuiltInTool(tools, createReadTool(resolveSandbox, fileReads, fileViewer))
955
- appendBuiltInTool(tools, createEditTool(resolveSandbox, fileReads))
956
- appendBuiltInTool(tools, createWriteTool(resolveSandbox, fileReads))
985
+ // As agentModelToolSpecs advertises them.
986
+ if (!input.readOnly) {
987
+ appendBuiltInTool(tools, createEditTool(resolveSandbox, fileReads))
988
+ appendBuiltInTool(tools, createWriteTool(resolveSandbox, fileReads))
989
+ }
957
990
  appendBuiltInTool(tools, createGlobTool(resolveSandbox))
958
991
  appendBuiltInTool(tools, createGrepTool(resolveSandbox))
959
992
  appendBuiltInTool(tools, createBashTool(resolveSandbox, background))
@@ -1046,6 +1079,7 @@ async function startAgentEnvironment(
1046
1079
  sandbox,
1047
1080
  context,
1048
1081
  plan,
1082
+ ...(input.readOnly ? { readOnly: true } : {}),
1049
1083
  ...(input.ontologyDocs ? { ontologyDocs: input.ontologyDocs } : {}),
1050
1084
  ...(workspace ? { workspace } : {}),
1051
1085
  ...(input.conversation === undefined ? {} : { conversation: input.conversation }),
@@ -1057,8 +1091,9 @@ async function startAgentEnvironment(
1057
1091
  throw error
1058
1092
  }
1059
1093
 
1060
- // A workspace saved as the run ends keeps no command of it running.
1094
+ // A workspace saved as the run ends keeps no command of it running, its children's included.
1061
1095
  const beforeFinalize = async (options?: BeforeFinalizeOptions) => {
1096
+ await input.beforeSave?.()
1062
1097
  await stopBackground()
1063
1098
  await sandbox.beforeFinalize?.(options)
1064
1099
  }
@@ -1070,6 +1105,10 @@ async function startAgentEnvironment(
1070
1105
  sandbox: resolveSandbox,
1071
1106
  blobStorage: context.blobStorage,
1072
1107
  budget: fileBudget,
1108
+ ...(sandbox.lend
1109
+ ? { lendsWorkspace: true, workspaceResetAt: async () => (await ready).resetAt }
1110
+ : {}),
1111
+ ...(sandbox.lent ? { inParentWorkspace: true } : {}),
1073
1112
  async installTurnArtifacts(signal) {
1074
1113
  if (!artifacts) return []
1075
1114
 
@@ -1087,7 +1126,7 @@ async function startAgentEnvironment(
1087
1126
  runFiles,
1088
1127
  turnContext: {
1089
1128
  environmentFailureSignal: input.failureSignal,
1090
- ...(sandbox.beforeFinalize ? { beforeFinalize } : {}),
1129
+ ...(sandbox.beforeFinalize || input.beforeSave ? { beforeFinalize } : {}),
1091
1130
  id: context.id,
1092
1131
  ...(context.authorPrincipal === undefined
1093
1132
  ? {}
@@ -1133,6 +1172,8 @@ function measureEnvironmentSystemPrompt(input: {
1133
1172
  readonly workspace?: Pick<AcquiredRunSandbox, "promptContext" | "resetAt">
1134
1173
  readonly conversation?: string
1135
1174
  readonly memory?: ConversationMemory
1175
+ /** A child with no `edit` and no `write`. */
1176
+ readonly readOnly?: boolean
1136
1177
  }): AgentSystemPromptSize {
1137
1178
  const { mode, plan, workspace } = input
1138
1179
  const { requester } = input.context
@@ -1148,6 +1189,9 @@ function measureEnvironmentSystemPrompt(input: {
1148
1189
  : {}),
1149
1190
  sandboxResetAt: workspace?.resetAt,
1150
1191
  workspace: workspace?.promptContext,
1192
+ ...(mode === "conversation" && input.sandbox.lend ? { lendsWorkspace: true } : {}),
1193
+ ...(mode === "subagent" && input.sandbox.lent ? { inParentWorkspace: true } : {}),
1194
+ ...(input.readOnly ? { readOnly: true } : {}),
1151
1195
  facts: requester === undefined ? {} : { requester },
1152
1196
  ...(input.conversation === undefined ? {} : { conversation: input.conversation }),
1153
1197
  ...(plan.sandboxModels ? { sandboxModels: plan.sandboxModels } : {}),
package/src/run-fate.ts CHANGED
@@ -3,7 +3,11 @@ import {
3
3
  type AgentRunSession,
4
4
  AgentTurnInterruptedError,
5
5
  } from "@sixb/core/internal/agents"
6
- import type { AgentRunRecord, AppendAgentMessageInput } from "@sixb/core/storage"
6
+ import type {
7
+ AgentRunDiagnostic,
8
+ AgentRunRecord,
9
+ AppendAgentMessageInput,
10
+ } from "@sixb/core/storage"
7
11
  import { type AgentRunFailure, toAgentExecutionFailure } from "./failure"
8
12
 
9
13
  /**
@@ -15,7 +19,8 @@ export async function recordFate(
15
19
  session: AgentRunSession,
16
20
  status: "failed" | "cancelled",
17
21
  error: unknown,
18
- messages?: readonly AppendAgentMessageInput[]
22
+ messages?: readonly AppendAgentMessageInput[],
23
+ diagnostics: readonly AgentRunDiagnostic[] = []
19
24
  ): Promise<{ readonly run: AgentRunRecord; readonly failure: AgentRunFailure } | undefined> {
20
25
  const { run } = session
21
26
  const completedAt = new Date()
@@ -30,6 +35,7 @@ export async function recordFate(
30
35
  status,
31
36
  error: failure,
32
37
  completedAt,
38
+ ...(diagnostics.length === 0 ? {} : { diagnostics }),
33
39
  ...(error instanceof AgentTurnInterruptedError
34
40
  ? { finishReason: "interrupted" as const }
35
41
  : {}),