@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
@@ -1,4 +1,6 @@
1
+ import { posix } from "node:path"
1
2
  import { type Sandbox, SandboxNotRunningError } from "@sixb/core"
3
+ import { SANDBOX_CONTEXT_DIRECTORY } from "@sixb/core/internal/agents"
2
4
  import { createSixbError, withFailureMessage } from "@sixb/core/internal/errors"
3
5
  import type { SandboxNetworkPolicy } from "@sixb/core/sandboxes"
4
6
  import type { AgentWorkspacePromptContext } from "./agent-prompt"
@@ -61,6 +63,19 @@ export interface RunSandbox {
61
63
  readonly networkPolicy?: SandboxNetworkPolicy
62
64
  /** Where `web_fetch` reads pages from. Absent: Sixb's servers. */
63
65
  readonly webNetwork?: WebFetchNetwork
66
+ /**
67
+ * The workspace of the run's parent, lent by its `lend`: the run hands back no files, as its
68
+ * parent sees what it changes, and its commands call the API with the parent's token, saying
69
+ * which run they are (`SIXB_RUN_ID`).
70
+ */
71
+ readonly lent?: boolean
72
+ /**
73
+ * Lend this workspace to a child the run spawns: the child runs its tools here, on the same
74
+ * files, and the parent still decides when the workspace is saved. The child keeps everything
75
+ * else of its own: its run, its token, its context directory. Absent when the run has no
76
+ * workspace to lend, such as a blank sandbox: each child then gets a sandbox of its own.
77
+ */
78
+ readonly lend?: (child: LentRunSandboxChild) => RunSandbox
64
79
  /** Called once, when the run environment starts. */
65
80
  acquire(): Promise<AcquiredRunSandbox>
66
81
  /**
@@ -72,6 +87,41 @@ export interface RunSandbox {
72
87
  beforeFinalize?(options?: BeforeFinalizeOptions): Promise<void>
73
88
  }
74
89
 
90
+ /** The child a run lends its workspace to. */
91
+ export interface LentRunSandboxChild {
92
+ readonly runId: string
93
+ readonly threadId: string
94
+ /** Stops the child's provisioning: its cancellation, or its runner stopping. */
95
+ readonly signal: AbortSignal
96
+ }
97
+
98
+ /**
99
+ * Where a child's run files go when its thread works in its parent's workspace, in whatever sandbox
100
+ * a run of the thread works in: beside the parent's, and the same for each of its runs, so the
101
+ * paths its history names hold. The directory a Git checkout excludes covers it.
102
+ */
103
+ export function threadContextDirectory(threadId: string): string {
104
+ return posix.join(SANDBOX_CONTEXT_DIRECTORY, "threads", threadId)
105
+ }
106
+
107
+ /** `sandbox` with its run's files in `contextDirectory` instead. */
108
+ export function withContextDirectory(sandbox: RunSandbox, contextDirectory: string): RunSandbox {
109
+ return {
110
+ waitBeforeModel: sandbox.waitBeforeModel,
111
+ contextDirectory,
112
+ ...(sandbox.background ? { background: sandbox.background } : {}),
113
+ ...(sandbox.networkPolicy ? { networkPolicy: sandbox.networkPolicy } : {}),
114
+ ...(sandbox.webNetwork ? { webNetwork: sandbox.webNetwork } : {}),
115
+ acquire: () => sandbox.acquire(),
116
+ ...(sandbox.release
117
+ ? { release: (acquired) => sandbox.release?.(acquired) ?? Promise.resolve() }
118
+ : {}),
119
+ ...(sandbox.beforeFinalize
120
+ ? { beforeFinalize: (options) => sandbox.beforeFinalize?.(options) ?? Promise.resolve() }
121
+ : {}),
122
+ }
123
+ }
124
+
75
125
  /** How a run's end leaves its thread's workspace. */
76
126
  export interface BeforeFinalizeOptions {
77
127
  /**
@@ -269,7 +269,8 @@ async function settleSubagent(
269
269
  * Keep the child's outcome: its answer, what it wrote under `out/`, and what it did as its thread's
270
270
  * next message. A paused child keeps its files too, for the run that continues it; `wait`
271
271
  * hands over only a finished child's, as an unfinished one's would pass for complete. Its `out/`
272
- * is stored even when its workspace is kept: a continuation that finds it lost gets it back.
272
+ * is stored even when its workspace is kept: a continuation that finds it lost gets it back. A
273
+ * child in its parent's workspace stores none: what it changed is there already.
273
274
  */
274
275
  async function finishSubagent(input: {
275
276
  readonly context: AgentTurnContext
@@ -286,11 +287,13 @@ async function finishSubagent(input: {
286
287
  readonly text?: string
287
288
  }): Promise<SubagentRunRecord> {
288
289
  const { context, run } = input
289
- const outputs = await storeChildOutputs({
290
- files: input.runFiles,
291
- handed: run.spec.files ?? [],
292
- signal: input.abortSignal,
293
- })
290
+ const outputs: Awaited<ReturnType<typeof storeChildOutputs>> = input.runFiles.inParentWorkspace
291
+ ? { files: [] }
292
+ : await storeChildOutputs({
293
+ files: input.runFiles,
294
+ handed: run.spec.files ?? [],
295
+ signal: input.abortSignal,
296
+ })
294
297
  input.runtime.assertCanContinue()
295
298
 
296
299
  // Before the terminal write, and after out/ was read: a paused child's workspace is kept for
@@ -26,28 +26,54 @@ export interface SubagentHistory extends AgentTurnHistory {
26
26
  * back to its new sandbox, and when it continues. It stays in
27
27
  * the thread, so a later continuation replays the same bytes.
28
28
  *
29
- * A child whose workspace is kept finds it as it left it, and is told nothing about it here. If
30
- * its files turn out lost, its system prompt says so, as a turn's does.
29
+ * A child whose workspace is kept, its own or its parent's, finds it as it left it, and is told
30
+ * nothing about it here. If its own workspace's files turn out lost, its system prompt says so, as
31
+ * a turn's does; if its parent's was recreated after it paused, this message says so.
31
32
  */
32
33
  export function continuationTrigger(input: {
33
34
  /** The outcomes as the child reads them, without their caller, or the answer's `mail` part. */
34
35
  readonly goesOnWith: readonly AgentMessagePart[]
35
36
  readonly paused: SubagentRunRecord
36
- /** Whether the sandbox provider keeps the child's workspace while it pauses. */
37
- readonly keepsWorkspace: boolean
37
+ readonly workspace: ContinuationWorkspace
38
38
  readonly createdAt: Date
39
39
  readonly settings: SentSettings
40
40
  }): readonly AgentMessagePart[] {
41
+ const told =
42
+ input.workspace === "restarted"
43
+ ? sandboxRestarted(input.paused)
44
+ : input.workspace === "left-parent"
45
+ ? LEFT_PARENT_WORKSPACE
46
+ : input.workspace === "parent-reset"
47
+ ? PARENT_WORKSPACE_RESET
48
+ : undefined
49
+
41
50
  return [
42
51
  ...input.goesOnWith,
43
52
  ...(input.paused.result?.unread ?? []).map((mail) => mailPart(mail)),
44
- ...(input.keepsWorkspace
45
- ? []
46
- : [{ type: "text" as const, text: sandboxRestarted(input.paused) }]),
53
+ ...(told === undefined ? [] : [{ type: "text" as const, text: told }]),
47
54
  { type: "text", text: `\n\n${renderCurrentTime(input.createdAt, input.settings)}` },
48
55
  ]
49
56
  }
50
57
 
58
+ /**
59
+ * Where a paused child continues: in its parent's workspace again, as it left it (`parent`) or
60
+ * recreated since (`parent-reset`); in its own sandbox, kept as it left it (`kept`) or started
61
+ * again (`restarted`); or, after working in its parent's workspace, in a blank sandbox of its own
62
+ * (`left-parent`), as once the conversation moved.
63
+ */
64
+ export type ContinuationWorkspace = "parent" | "parent-reset" | "kept" | "restarted" | "left-parent"
65
+
66
+ /** Whether a continuation runs in its parent's workspace, which the turn lends it. */
67
+ export function continuesInParentWorkspace(workspace: ContinuationWorkspace): boolean {
68
+ return workspace === "parent" || workspace === "parent-reset"
69
+ }
70
+
71
+ const PARENT_WORKSPACE_RESET =
72
+ "Your parent's workspace was recreated while you were paused: the changes you made there are gone. You still work in it, on its files as they are now: inspect them before relying on earlier tool results."
73
+
74
+ const LEFT_PARENT_WORKSPACE =
75
+ "You no longer work in your parent's workspace: you continue in a blank sandbox of your own, and the changes you made there are not here."
76
+
51
77
  function sandboxRestarted(paused: SubagentRunRecord): string {
52
78
  const outputsError = paused.result?.filesError
53
79
  return outputsError === undefined
@@ -56,7 +56,11 @@ import { ChildMailClosedError, FamilyMailbox } from "./family-mailbox"
56
56
  import { agentToolErrorText } from "./model-adapters"
57
57
  import { renderModelLine } from "./model-lines"
58
58
  import type { TurnChildren } from "./run-agent-turn"
59
- import { continuationTrigger } from "./subagent-continuation"
59
+ import {
60
+ type ContinuationWorkspace,
61
+ continuationTrigger,
62
+ continuesInParentWorkspace,
63
+ } from "./subagent-continuation"
60
64
  import type { WaitableChildren } from "./tools/background"
61
65
  import type { AgentRunFiles, AgentRunSettings } from "./types"
62
66
 
@@ -106,6 +110,8 @@ export interface SpawnSubagentInput {
106
110
  readonly maxSteps?: number
107
111
  /** Files and directories in the parent's sandbox, copied into the child's at the same paths. */
108
112
  readonly files?: readonly string[]
113
+ /** The child gets no `edit` and no `write` tool: it leaves the files as they are. */
114
+ readonly readOnly?: boolean
109
115
  }
110
116
 
111
117
  export interface SpawnSubagentOutput {
@@ -240,7 +246,12 @@ export class SubagentCoordinator {
240
246
  * it claims the child's run, opens its session and environment, and records its fate.
241
247
  * Starting a run already running is a no-op.
242
248
  */
243
- private readonly startChild: (run: SubagentRunRecord, family: FamilyMailbox) => void,
249
+ private readonly startChild: (
250
+ run: SubagentRunRecord,
251
+ family: FamilyMailbox,
252
+ /** It runs in the turn's workspace, which the turn lends it. */
253
+ inParentWorkspace: boolean
254
+ ) => void,
244
255
  /** When the parent conversation last moved workspaces, so paused child sandboxes know. */
245
256
  private readonly movedAt?: Date
246
257
  ) {
@@ -295,15 +306,15 @@ export class SubagentCoordinator {
295
306
  for (const { child, outcomes } of paused) {
296
307
  signal.throwIfAborted()
297
308
  await this.clearDeadAttempts(child, signal)
298
- const keepsWorkspace = await this.childKeepsWorkspace(child)
299
- const { spec, continuation } = this.continuationOf(child, outcomes, keepsWorkspace)
309
+ const workspace = await this.continuationWorkspace(child)
310
+ const { spec, continuation } = this.continuationOf(child, outcomes, workspace)
300
311
  await this.admitInTurn(() =>
301
312
  this.admit(
302
313
  createSubagentRunId(this.parentRun.id, child.spawnKey),
303
314
  child.spawnKey,
304
315
  spec,
305
316
  signal,
306
- continuation
317
+ { ...continuation, lends: continuesInParentWorkspace(workspace) }
307
318
  )
308
319
  )
309
320
  }
@@ -392,6 +403,7 @@ export class SubagentCoordinator {
392
403
  ...modelChoice(this.models).advice,
393
404
  OMIT_MODEL,
394
405
  `Pass files to copy files or directories of your sandbox into the child's, at the same paths, before it starts. What the child writes to out/ comes back with wait's result when it finishes, which lists where each file is.`,
406
+ "Pass readOnly for a review or an investigation that must leave the files as they are: the child gets no edit or write tool; its commands still run.",
395
407
  `A child that has not answered after ${this.models.maxSteps} steps (model calls) stops and fails with agent.step_limit_reached; pass maxSteps to stop it sooner.`,
396
408
  `At most ${this.context.subagentConcurrencyPerRun} child agents may be active for this run.`,
397
409
  ].join("\n"),
@@ -624,9 +636,12 @@ export class SubagentCoordinator {
624
636
  )
625
637
  }
626
638
  await this.clearDeadAttempts(paused, signal)
627
- const keepsWorkspace = await this.childKeepsWorkspace(paused)
628
- const { spec, continuation } = this.continuationOf(paused, [answer], keepsWorkspace)
629
- return this.admit(runId, key, spec, signal, continuation)
639
+ const workspace = await this.continuationWorkspace(paused)
640
+ const { spec, continuation } = this.continuationOf(paused, [answer], workspace)
641
+ return this.admit(runId, key, spec, signal, {
642
+ ...continuation,
643
+ lends: continuesInParentWorkspace(workspace),
644
+ })
630
645
  })
631
646
 
632
647
  const output: MessageSubagentOutput = {
@@ -799,12 +814,30 @@ export class SubagentCoordinator {
799
814
  const model = this.resolveModel(input.model)
800
815
  const reasoning = input.reasoning ?? model.defaultReasoning
801
816
  const maxSteps = this.resolveMaxSteps(input.maxSteps)
817
+ const readOnly = input.readOnly === true
818
+ // Recorded, so its continuations keep the kind of sandbox it started with.
819
+ const inParentWorkspace = this.lendsWorkspace()
820
+ // A child that works in this turn's workspace sees its files already.
821
+ if (input.files?.length && inParentWorkspace) {
822
+ throw new AgentToolPublicError(
823
+ "[SixbAgent] spawn_agent takes no files here: the child works in your workspace, on the same files. Name the paths it needs in its task instead."
824
+ )
825
+ }
802
826
  const sources = input.files?.length
803
827
  ? await listHandedSources({ files: this.runFiles(), paths: input.files, signal })
804
828
  : undefined
805
829
  const runId = createSubagentRunId(this.parentRun.id, key)
806
830
  const specWith = (files: readonly SubagentRunFile[] | undefined) =>
807
- this.childSpec({ task, model, tier: model.tier, reasoning, maxSteps, files })
831
+ this.childSpec({
832
+ task,
833
+ model,
834
+ tier: model.tier,
835
+ reasoning,
836
+ maxSteps,
837
+ files,
838
+ readOnly,
839
+ inParentWorkspace,
840
+ })
808
841
 
809
842
  // One admission at a time: only this turn adds children to it, so admission's answer is known
810
843
  // before any file is read, and a refused spawn reads and stores none.
@@ -891,7 +924,27 @@ export class SubagentCoordinator {
891
924
  }
892
925
 
893
926
  /**
894
- * Whether a paused child finds its workspace where it left it: its provider keeps them, the
927
+ * Where a paused child continues: in the kind of sandbox it started with. One that worked in its
928
+ * parent's workspace goes on there while this turn lends it and the conversation did not move
929
+ * since it paused, and is told when the workspace was recreated meanwhile; otherwise it gets a
930
+ * blank sandbox of its own, and is told. One with a sandbox of its own keeps it, as
931
+ * `childKeepsWorkspace` says, whether this turn lends or not.
932
+ */
933
+ private async continuationWorkspace(paused: SubagentRunRecord): Promise<ContinuationWorkspace> {
934
+ if (paused.spec.inParentWorkspace) {
935
+ if (!this.lendsWorkspace() || this.movedSince(paused)) return "left-parent"
936
+
937
+ // Recreated after it paused: what it changed there is gone, and it is told.
938
+ const resetAt = await this.runFiles().workspaceResetAt?.()
939
+ return resetAt !== undefined && new Date(resetAt).getTime() > pausedAt(paused).getTime()
940
+ ? "parent-reset"
941
+ : "parent"
942
+ }
943
+ return (await this.childKeepsWorkspace(paused)) ? "kept" : "restarted"
944
+ }
945
+
946
+ /**
947
+ * Whether a paused child finds its own workspace where it left it: its provider keeps them, the
895
948
  * conversation did not move to a computer since it paused, and it did not move to another
896
949
  * workspace before that pause ended.
897
950
  */
@@ -899,8 +952,12 @@ export class SubagentCoordinator {
899
952
  if (!this.context.keepsChildWorkspaces) return false
900
953
  const parent = await this.session.children.get(paused.parentRunId)
901
954
  if (parent?.kind === "conversation" && parent.spec?.runsOn === "computer") return false
902
- const pausedAt = paused.completedAt ?? paused.startedAt ?? paused.createdAt
903
- return !this.movedAt || this.movedAt.getTime() <= pausedAt.getTime()
955
+ return !this.movedSince(paused)
956
+ }
957
+
958
+ /** Whether the conversation moved to another workspace after `paused` paused. */
959
+ private movedSince(paused: SubagentRunRecord): boolean {
960
+ return this.movedAt !== undefined && this.movedAt.getTime() > pausedAt(paused).getTime()
904
961
  }
905
962
 
906
963
  /**
@@ -911,7 +968,7 @@ export class SubagentCoordinator {
911
968
  private continuationOf(
912
969
  paused: SubagentRunRecord,
913
970
  goesOnWith: readonly AgentMessagePart[],
914
- keepsWorkspace: boolean
971
+ workspace: ContinuationWorkspace
915
972
  ): {
916
973
  readonly spec: SubagentRunSpec
917
974
  readonly continuation: Pick<AgentChildDraft, "thread" | "trigger" | "createdAt">
@@ -923,12 +980,15 @@ export class SubagentCoordinator {
923
980
  reasoning: paused.spec.reasoning,
924
981
  maxSteps: paused.spec.maxSteps,
925
982
  files: paused.spec.files,
983
+ readOnly: paused.spec.readOnly === true,
984
+ // Its thread's: where it works, and the run files its history names, wherever it continues.
985
+ inParentWorkspace: paused.spec.inParentWorkspace === true,
926
986
  })
927
987
  const createdAt = new Date()
928
988
  const parts = continuationTrigger({
929
989
  goesOnWith,
930
990
  paused,
931
- keepsWorkspace,
991
+ workspace,
932
992
  createdAt,
933
993
  settings: sentSettings(spec, this.context),
934
994
  })
@@ -950,8 +1010,11 @@ export class SubagentCoordinator {
950
1010
  readonly reasoning: AgentReasoning | undefined
951
1011
  readonly maxSteps: number | undefined
952
1012
  readonly files: readonly SubagentRunFile[] | undefined
1013
+ readonly readOnly: boolean
1014
+ /** Its thread works in its parent's workspace (`SubagentRunSpec.inParentWorkspace`). */
1015
+ readonly inParentWorkspace: boolean
953
1016
  }): SubagentRunSpec {
954
- const { task, model, tier, reasoning, maxSteps, files } = input
1017
+ const { task, model, tier, reasoning, maxSteps, files, readOnly, inParentWorkspace } = input
955
1018
  const { approvalMode, timeZone, locale } = this.parentRun.spec ?? {}
956
1019
  return {
957
1020
  model: { provider: model.provider, modelId: model.modelId },
@@ -964,37 +1027,51 @@ export class SubagentCoordinator {
964
1027
  ...(timeZone === undefined ? {} : { timeZone }),
965
1028
  ...(locale === undefined ? {} : { locale }),
966
1029
  ...(files === undefined ? {} : { files }),
1030
+ ...(readOnly ? { readOnly: true } : {}),
1031
+ ...(inParentWorkspace ? { inParentWorkspace: true } : {}),
967
1032
  }
968
1033
  }
969
1034
 
970
1035
  /**
971
1036
  * Admit a child of this turn. A spawned child works in a thread of its own, which starts with its
972
- * task and its files; a continuation goes into its thread with the outcomes it continues with.
1037
+ * task and its files, and in the turn's workspace when its spec says so; a continuation goes into
1038
+ * its thread with the outcomes it continues with, in the turn's workspace when `lends` says so.
973
1039
  */
974
1040
  private async admit(
975
1041
  runId: string,
976
1042
  key: string,
977
1043
  spec: SubagentRunSpec,
978
1044
  signal: AbortSignal,
979
- continuation?: Pick<AgentChildDraft, "thread" | "trigger" | "createdAt">
1045
+ continuation?: Pick<AgentChildDraft, "thread" | "trigger" | "createdAt"> & {
1046
+ readonly lends: boolean
1047
+ }
980
1048
  ): Promise<SpawnSubagentOutput> {
1049
+ const lends = continuation ? continuation.lends : spec.inParentWorkspace === true
981
1050
  let run: SubagentRunRecord
982
1051
  try {
983
1052
  run = await this.session.children.spawn({
984
1053
  spawnKey: key,
985
1054
  spec,
986
- ...(continuation ?? {
987
- thread: { create: true },
988
- trigger: {
989
- id: createAgentMessageId(),
990
- parts: [
991
- { type: "text", text: spec.task },
992
- ...(spec.files === undefined
993
- ? []
994
- : [{ type: "text" as const, text: renderHandedFiles(spec.files) }]),
995
- ],
996
- },
997
- }),
1055
+ ...(continuation
1056
+ ? {
1057
+ thread: continuation.thread,
1058
+ trigger: continuation.trigger,
1059
+ ...(continuation.createdAt === undefined
1060
+ ? {}
1061
+ : { createdAt: continuation.createdAt }),
1062
+ }
1063
+ : {
1064
+ thread: { create: true },
1065
+ trigger: {
1066
+ id: createAgentMessageId(),
1067
+ parts: [
1068
+ { type: "text", text: spec.task },
1069
+ ...(spec.files === undefined
1070
+ ? []
1071
+ : [{ type: "text" as const, text: renderHandedFiles(spec.files) }]),
1072
+ ],
1073
+ },
1074
+ }),
998
1075
  })
999
1076
  if (run.id !== runId) {
1000
1077
  throw new Error(`[SixbAgent] Child '${key}' was admitted as '${run.id}', not '${runId}'.`)
@@ -1004,7 +1081,7 @@ export class SubagentCoordinator {
1004
1081
  }
1005
1082
 
1006
1083
  signal.throwIfAborted()
1007
- if (run.status === "queued") this.startChild(run, this.#family)
1084
+ if (run.status === "queued") this.startChild(run, this.#family, lends)
1008
1085
 
1009
1086
  return {
1010
1087
  runId: run.id,
@@ -1271,6 +1348,11 @@ export class SubagentCoordinator {
1271
1348
  }
1272
1349
  }
1273
1350
 
1351
+ /** Whether the turn lends its children its workspace: never before its environment started. */
1352
+ private lendsWorkspace(): boolean {
1353
+ return this.#runFiles?.lendsWorkspace === true
1354
+ }
1355
+
1274
1356
  private runFiles(): AgentRunFiles {
1275
1357
  if (!this.#runFiles) {
1276
1358
  throw new Error("[SixbAgent] Delegation tools ran before their run's environment.")
@@ -1429,6 +1511,11 @@ function spawnInputSchema(models: AgentRunDelegation): JsonObject {
1429
1511
  description:
1430
1512
  "Paths of files or directories in your sandbox, such as an attachment from $SIXB_ATTACHMENTS or out/chart.png.",
1431
1513
  },
1514
+ readOnly: {
1515
+ type: "boolean",
1516
+ description:
1517
+ "The child gets no edit or write tool, for a review or an investigation that must leave the files as they are; its commands still run.",
1518
+ },
1432
1519
  },
1433
1520
  required: ["key", "task"],
1434
1521
  additionalProperties: false,
@@ -1649,11 +1736,11 @@ function parseSpawnInput(value: unknown): SpawnSubagentInput {
1649
1736
  if (
1650
1737
  !isJsonObject(value) ||
1651
1738
  Object.keys(value).some(
1652
- (key) => !["key", "task", "model", "reasoning", "maxSteps", "files"].includes(key)
1739
+ (key) => !["key", "task", "model", "reasoning", "maxSteps", "files", "readOnly"].includes(key)
1653
1740
  )
1654
1741
  ) {
1655
1742
  throw new AgentToolPublicError(
1656
- "[SixbAgent] spawn_agent expects key, task, and optional model/reasoning/maxSteps/files."
1743
+ "[SixbAgent] spawn_agent expects key, task, and optional model/reasoning/maxSteps/files/readOnly."
1657
1744
  )
1658
1745
  }
1659
1746
  const key = requireNonEmpty("spawn_agent", value.key, "key", 128)
@@ -1689,6 +1776,9 @@ function parseSpawnInput(value: unknown): SpawnSubagentInput {
1689
1776
  ) {
1690
1777
  throw new AgentToolPublicError("[SixbAgent] spawn_agent maxSteps must be a positive integer.")
1691
1778
  }
1779
+ if (value.readOnly !== undefined && typeof value.readOnly !== "boolean") {
1780
+ throw new AgentToolPublicError("[SixbAgent] spawn_agent readOnly must be true or false.")
1781
+ }
1692
1782
  const files = parseSpawnFiles(value.files)
1693
1783
  return {
1694
1784
  key,
@@ -1697,6 +1787,7 @@ function parseSpawnInput(value: unknown): SpawnSubagentInput {
1697
1787
  ...(value.reasoning === undefined ? {} : { reasoning: value.reasoning }),
1698
1788
  ...(value.maxSteps === undefined ? {} : { maxSteps: value.maxSteps }),
1699
1789
  ...(files === undefined ? {} : { files }),
1790
+ ...(value.readOnly === true ? { readOnly: true } : {}),
1700
1791
  }
1701
1792
  }
1702
1793
 
@@ -1733,3 +1824,8 @@ function stoppedReading(error: unknown, key: string): unknown {
1733
1824
  `[SixbAgent] '${key}' stopped as you sent this, so it will not read it: it paused or ended. Wait for it with wait to see which.`
1734
1825
  )
1735
1826
  }
1827
+
1828
+ /** When a paused child stopped. */
1829
+ function pausedAt(paused: SubagentRunRecord): Date {
1830
+ return paused.completedAt ?? paused.startedAt ?? paused.createdAt
1831
+ }
package/src/tools/bash.ts CHANGED
@@ -35,7 +35,7 @@ export const BASH_TOOL_SPEC = {
35
35
  run_in_background: {
36
36
  type: "boolean",
37
37
  description:
38
- "Run it in the background, returning at once with its id and output file: for servers, watchers, long builds. You are told when it ends; wait for it with wait, stop it with stop, or read its file. No timeout. It ends with the run, a pause for approval too, and its file with it; in the user's folder on their computer it runs until it exits, is stopped, or sixb quits.",
38
+ "Run it in the background, returning at once with its id and output file: for servers, watchers, long builds. You are told when it ends; wait for it with wait, stop it with stop, or read its file. No timeout, unless the sandbox limits how long a command runs: you are told if it stops there. It ends with the run, a pause for approval too, and its file with it; in the user's folder on their computer it runs until it exits, is stopped, or sixb quits.",
39
39
  },
40
40
  },
41
41
  required: ["command"],
@@ -15,7 +15,7 @@ import { WRITE_TOOL_SPEC } from "./write"
15
15
  * Describe exactly the tools a conversational model receives, in its order, without starting its
16
16
  * sandbox. A conversation publishes artifacts once its run executes in a thread; it searches the
17
17
  * web when its plan names a search model, and fetches pages when its plan has web tools at all,
18
- * unless its sandbox's network is `none`.
18
+ * unless its sandbox's network is `none`. A read-only child has no `edit` and no `write`.
19
19
  */
20
20
  export function agentModelToolSpecs(
21
21
  projectTools: readonly AgentToolSpec[],
@@ -23,13 +23,13 @@ export function agentModelToolSpecs(
23
23
  readonly publishes?: boolean
24
24
  readonly web?: AgentRunWebPlan
25
25
  readonly networkPolicy?: SandboxNetworkPolicy
26
+ readonly readOnly?: boolean
26
27
  } = {}
27
28
  ): readonly AgentToolSpec[] {
28
29
  return [
29
30
  ...projectTools,
30
31
  READ_TOOL_SPEC,
31
- EDIT_TOOL_SPEC,
32
- WRITE_TOOL_SPEC,
32
+ ...(options.readOnly ? [] : [EDIT_TOOL_SPEC, WRITE_TOOL_SPEC]),
33
33
  GLOB_TOOL_SPEC,
34
34
  GREP_TOOL_SPEC,
35
35
  BASH_TOOL_SPEC,
package/src/types.ts CHANGED
@@ -82,6 +82,15 @@ export interface AgentRunFiles {
82
82
  readonly blobStorage: AgentRunFileStore
83
83
  /** Shared with every other file the run stores. */
84
84
  readonly budget: AgentFileBudget
85
+ /** Its children work in its workspace: they need no files handed over, and hand none back. */
86
+ readonly lendsWorkspace?: boolean
87
+ /** It works in its parent's workspace, which sees what it changes: it hands no files back. */
88
+ readonly inParentWorkspace?: boolean
89
+ /**
90
+ * When the workspace it lends was last recreated, as its opening read it: a child that paused
91
+ * before then finds none of its changes there.
92
+ */
93
+ workspaceResetAt?(): Promise<string | undefined>
85
94
  /**
86
95
  * Install the latest revision of each thread artifact the run's turn wrote, its children's
87
96
  * writes among them, in the run's `$SIXB_ARTIFACTS`, and in the folder the Agent last published