clanka 0.28.2 → 0.28.3

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.
@@ -24,11 +24,15 @@ import * as AgentExecutor from "./AgentExecutor.ts"
24
24
  import { agentTasksUnavailable, type Task } from "./AgentTools.ts"
25
25
 
26
26
  // The task a stub `subagent` resolves with once its agent has finished.
27
- const completedAgent = (id: string, prompt: string, output: string): Task => ({
27
+ const completedAgent = (
28
+ id: string,
29
+ description: string,
30
+ output: string,
31
+ ): Task => ({
28
32
  id,
29
33
  kind: "agent",
30
34
  status: "completed",
31
- description: prompt,
35
+ description,
32
36
  output,
33
37
  })
34
38
 
@@ -87,17 +91,17 @@ describe("RPC subagent executor", () => {
87
91
  environment,
88
92
  onEnvironment: () => Effect.void,
89
93
  script:
90
- 'console.log("first:" + (await subagent({ prompt: "first" })).output)',
94
+ 'console.log("first:" + (await subagent({ description: "Handle child request", prompt: "first" })).output)',
91
95
  onTaskComplete: () => Effect.void,
92
96
  onImage: () => Effect.void,
93
97
  agentTasks: {
94
98
  ...agentTasksUnavailable,
95
- subagent: ({ id, prompt }) =>
99
+ subagent: ({ id, prompt, description }) =>
96
100
  Effect.gen(function* () {
97
101
  assert.strictEqual(prompt, "first")
98
102
  yield* Deferred.succeed(firstStarted, undefined)
99
103
  yield* Deferred.await(secondStarted)
100
- return completedAgent(id, prompt, "first-output")
104
+ return completedAgent(id, description, "first-output")
101
105
  }),
102
106
  },
103
107
  })
@@ -107,17 +111,17 @@ describe("RPC subagent executor", () => {
107
111
  environment,
108
112
  onEnvironment: () => Effect.void,
109
113
  script:
110
- 'console.log("second:" + (await subagent({ prompt: "second" })).output)',
114
+ 'console.log("second:" + (await subagent({ description: "Handle child request", prompt: "second" })).output)',
111
115
  onTaskComplete: () => Effect.void,
112
116
  onImage: () => Effect.void,
113
117
  agentTasks: {
114
118
  ...agentTasksUnavailable,
115
- subagent: ({ id, prompt }) =>
119
+ subagent: ({ id, prompt, description }) =>
116
120
  Effect.gen(function* () {
117
121
  assert.strictEqual(prompt, "second")
118
122
  yield* Deferred.succeed(secondStarted, undefined)
119
123
  yield* Deferred.await(firstStarted)
120
- return completedAgent(id, prompt, "second-output")
124
+ return completedAgent(id, description, "second-output")
121
125
  }),
122
126
  },
123
127
  })
@@ -142,12 +146,12 @@ describe("RPC subagent executor", () => {
142
146
  environment,
143
147
  onEnvironment: () => Effect.void,
144
148
  script:
145
- 'console.log("parent:" + (await subagent({ prompt: "outer" })).output)',
149
+ 'console.log("parent:" + (await subagent({ description: "Handle child request", prompt: "outer" })).output)',
146
150
  onTaskComplete: () => Effect.void,
147
151
  onImage: () => Effect.void,
148
152
  agentTasks: {
149
153
  ...agentTasksUnavailable,
150
- subagent: ({ id, prompt }) =>
154
+ subagent: ({ id, prompt, description }) =>
151
155
  Effect.gen(function* () {
152
156
  assert.strictEqual(prompt, "outer")
153
157
  const childOutput = yield* executor
@@ -155,17 +159,21 @@ describe("RPC subagent executor", () => {
155
159
  environment,
156
160
  onEnvironment: () => Effect.void,
157
161
  script:
158
- 'console.log("child:" + (await subagent({ prompt: "inner" })).output)',
162
+ 'console.log("child:" + (await subagent({ description: "Handle child request", prompt: "inner" })).output)',
159
163
  onTaskComplete: () => Effect.void,
160
164
  onImage: () => Effect.void,
161
165
  agentTasks: {
162
166
  ...agentTasksUnavailable,
163
- subagent: ({ id: innerId, prompt: innerPrompt }) =>
167
+ subagent: ({
168
+ id: innerId,
169
+ prompt: innerPrompt,
170
+ description: innerDescription,
171
+ }) =>
164
172
  Effect.sync(() => {
165
173
  assert.strictEqual(innerPrompt, "inner")
166
174
  return completedAgent(
167
175
  innerId,
168
- innerPrompt,
176
+ innerDescription,
169
177
  "inner-output",
170
178
  )
171
179
  }),
@@ -177,7 +185,7 @@ describe("RPC subagent executor", () => {
177
185
  )
178
186
  return completedAgent(
179
187
  id,
180
- prompt,
188
+ description,
181
189
  childOutput.join("").trim().split("\n").at(-1)!,
182
190
  )
183
191
  }),
@@ -558,6 +566,19 @@ await sleep(60000)`,
558
566
  })
559
567
 
560
568
  describe(`${mode} executor limits`, () => {
569
+ it.live("rejects bash and subagent calls without descriptions", () =>
570
+ Effect.gen(function* () {
571
+ const output = yield* runScript(`for (const [name, start] of [
572
+ ["bash", () => bash({ command: "true" })],
573
+ ["subagent", () => subagent({ prompt: "child" })],
574
+ ]) {
575
+ try { await start() } catch (error) { console.log(name + ":" + String(error)) }
576
+ }`)
577
+ assert.match(output, /bash:.*description/)
578
+ assert.match(output, /subagent:.*description/)
579
+ }).pipe(Effect.provide(executorLayer({}))),
580
+ )
581
+
561
582
  it.live("run accepts only a string and returns command output", () =>
562
583
  Effect.gen(function* () {
563
584
  const output = yield* runScript(
@@ -581,6 +602,12 @@ await sleep(60000)`,
581
602
  JSON.parse(output.split("OUTPUT:")[1]!),
582
603
  'Task "bash_1" is still running in the background',
583
604
  )
605
+ assert.include(
606
+ yield* runScript(
607
+ 'console.log("DESCRIPTION:" + JSON.stringify((await taskOutput("bash_1")).description))',
608
+ ),
609
+ 'DESCRIPTION:""',
610
+ )
584
611
  assert.strictEqual(
585
612
  yield* waitForLog(environment.cwd, started),
586
613
  "start\n",
@@ -602,6 +629,7 @@ await sleep(60000)`,
602
629
  const { environment } = yield* executor.capabilities
603
630
  const output = yield* runScript(`
604
631
  const task = await bash({
632
+ description: "Wait for test signal",
605
633
  command: ${JSON.stringify(gatedCommand(environment.cwd))},
606
634
  background: true,
607
635
  })
@@ -611,7 +639,7 @@ console.log("RETURNED:", JSON.stringify(task))`)
611
639
  id: "bash_1",
612
640
  kind: "bash",
613
641
  status: "running",
614
- description: gatedCommand(environment.cwd),
642
+ description: "Wait for test signal",
615
643
  output: "",
616
644
  })
617
645
  assert.strictEqual(
@@ -635,6 +663,7 @@ console.log("RETURNED:", JSON.stringify(task))`)
635
663
  const output = yield* runScript(`
636
664
  try {
637
665
  const result = await bash({
666
+ description: "Wait for test signal",
638
667
  command: ${JSON.stringify(command)},
639
668
  timeoutMs: 60000,
640
669
  })
@@ -647,7 +676,7 @@ try {
647
676
  id: "bash_1",
648
677
  kind: "bash",
649
678
  status: "running",
650
- description: command,
679
+ description: "Wait for test signal",
651
680
  output: 'Task "bash_1" is still running in the background',
652
681
  })
653
682
  assert.strictEqual(
@@ -680,8 +709,8 @@ try {
680
709
  Effect.gen(function* () {
681
710
  const output = yield* runScript(`
682
711
  try {
683
- console.log("OK:", JSON.stringify(await bash({ command: "echo hi" })))
684
- console.log("RETURNED:", JSON.stringify(await bash({ command: "echo out && exit 3" })))
712
+ console.log("OK:", JSON.stringify(await bash({ description: "Print greeting", command: "echo hi" })))
713
+ console.log("RETURNED:", JSON.stringify(await bash({ description: "Simulate failure", command: "echo out && exit 3" })))
685
714
  } catch (error) {
686
715
  console.log("REJECTED:", String(error))
687
716
  }`)
@@ -691,7 +720,7 @@ try {
691
720
  id: "bash_1",
692
721
  kind: "bash",
693
722
  status: "completed",
694
- description: "echo hi",
723
+ description: "Print greeting",
695
724
  output: "hi\n",
696
725
  exitCode: 0,
697
726
  },
@@ -712,6 +741,7 @@ try {
712
741
  const show = ({ id, kind, status, exitCode, output }) =>
713
742
  JSON.stringify({ id, kind, status, exitCode, output })
714
743
  const task = await bash({
744
+ description: "Wait for test signal",
715
745
  command: ${JSON.stringify(`${gatedCommand(environment.cwd)} && echo done`)},
716
746
  background: true,
717
747
  })
@@ -732,6 +762,7 @@ console.log("WAITED:", (await waitTasks({ ids: [task.id] })).map(show).join())`)
732
762
  const { environment } = yield* executor.capabilities
733
763
  const output = yield* runScript(`
734
764
  const task = await bash({
765
+ description: "Wait for test signal",
735
766
  command: ${JSON.stringify(`echo early && ${gatedCommand(environment.cwd)}`)},
736
767
  background: true,
737
768
  })
@@ -782,8 +813,8 @@ console.log("OUTPUTS:", JSON.stringify(waits.map((task) => task.output)))`)
782
813
  environment,
783
814
  onEnvironment: () => Effect.void,
784
815
  script: `
785
- await bash({ command: "true" })
786
- const { id, kind, status } = await bash({ command: "true", background: true })
816
+ await bash({ description: "Check shell status", command: "true" })
817
+ const { id, kind, status } = await bash({ description: "Check shell status", command: "true", background: true })
787
818
  console.log("RETURNED:", JSON.stringify({ id, kind, status }))`,
788
819
  onTaskComplete: () => Effect.void,
789
820
  agentTasks: agentTasksUnavailable,
@@ -820,8 +851,8 @@ const done = async (id) => {
820
851
  }
821
852
  return task
822
853
  }
823
- await bash({ command: ${JSON.stringify(gatedCommand(environment.cwd))}, background: true })
824
- await bash({ command: "echo out && exit 3", background: true })
854
+ await bash({ description: "Wait for test signal", command: ${JSON.stringify(gatedCommand(environment.cwd))}, background: true })
855
+ await bash({ description: "Simulate failure", command: "echo out && exit 3", background: true })
825
856
  console.log("RUNNING:", show(await taskOutput("bash_1")))
826
857
  await writeFile({ path: "gate", content: "" })
827
858
  console.log("COMPLETED:", show(await done("bash_1")))
@@ -847,7 +878,7 @@ console.log("FAILED:", show(await done("bash_2")))`)
847
878
  const { environment } = yield* executor.capabilities
848
879
  const output = yield* runScript(`
849
880
  const show = ({ id, kind, status }) => JSON.stringify({ id, kind, status })
850
- await bash({ command: ${JSON.stringify(gatedCommand(environment.cwd))}, background: true })
881
+ await bash({ description: "Wait for test signal", command: ${JSON.stringify(gatedCommand(environment.cwd))}, background: true })
851
882
  try {
852
883
  await messageAgent({ id: "bash_1", message: "hello" })
853
884
  } catch (error) {
@@ -890,7 +921,7 @@ try {
890
921
  const executor = yield* AgentExecutor.AgentExecutor
891
922
  const { environment } = yield* executor.capabilities
892
923
  const fiber = yield* runScript(
893
- `await bash({ command: ${JSON.stringify(gatedCommand(environment.cwd))} })`,
924
+ `await bash({ description: "Wait for test signal", command: ${JSON.stringify(gatedCommand(environment.cwd))} })`,
894
925
  ).pipe(Effect.forkScoped)
895
926
  yield* waitForLog(environment.cwd, started)
896
927
  yield* Fiber.interrupt(fiber)
@@ -914,7 +945,7 @@ try {
914
945
  const fs = yield* FileSystem.FileSystem
915
946
  const directory = yield* fs.makeTempDirectoryScoped()
916
947
  yield* runScript(
917
- `await bash({ command: ${JSON.stringify(gatedCommand(directory))}, background: true })`,
948
+ `await bash({ description: "Wait for test signal", command: ${JSON.stringify(gatedCommand(directory))}, background: true })`,
918
949
  ).pipe(
919
950
  Effect.andThen(waitForLog(directory, started)),
920
951
  Effect.provide(executorLayer({})),
@@ -1049,7 +1080,7 @@ console.log("MAIN" + "_DONE")`)
1049
1080
  // `subagent` never finishes. The worker then exits through
1050
1081
  // the host's `process`, the way a crashed worker would.
1051
1082
  script: `
1052
- subagent({ prompt: "never finishes" })
1083
+ subagent({ description: "Handle child request", prompt: "never finishes" })
1053
1084
  sleep(100).then(() => console.constructor.constructor("return process")().exit(7))`,
1054
1085
  onTaskComplete: () => Effect.void,
1055
1086
  agentTasks: {
@@ -1068,7 +1099,10 @@ sleep(100).then(() => console.constructor.constructor("return process")().exit(7
1068
1099
  const executor = yield* AgentExecutor.AgentExecutor
1069
1100
  const output = yield* executor.executeUnsafe({
1070
1101
  tool: "bash",
1071
- params: { command: "seq 1 1000000" },
1102
+ params: {
1103
+ command: "seq 1 1000000",
1104
+ description: "Generate long output",
1105
+ },
1072
1106
  })
1073
1107
  const { output: text } = output as { readonly output: string }
1074
1108
  assert.isBelow(text.length, 10_000 + 500)
@@ -168,6 +168,7 @@ export interface ExecuteAgentTasks extends Omit<AgentTasks, "subagent"> {
168
168
  readonly subagent: (options: {
169
169
  readonly id: string
170
170
  readonly prompt: string
171
+ readonly description: string
171
172
  readonly background: boolean
172
173
  readonly environment: EnvironmentUpdate
173
174
  }) => Effect.Effect<Task>
@@ -1101,6 +1102,7 @@ export const AgentRequest = Schema.TaggedUnion({
1101
1102
  Subagent: {
1102
1103
  id: Schema.String,
1103
1104
  prompt: Schema.String,
1105
+ description: Schema.String,
1104
1106
  background: Schema.Boolean,
1105
1107
  environment: EnvironmentUpdate,
1106
1108
  },
@@ -272,6 +272,7 @@ describe("Agent images", () => {
272
272
  const executor = makeExecutor(({ agentTasks, environment }) =>
273
273
  Stream.fromEffect(
274
274
  agentTasks.subagent({
275
+ description: "Handle child request",
275
276
  id: "subagent_1",
276
277
  prompt: "child task: describe the layout",
277
278
  background: false,
@@ -28,7 +28,7 @@ import type { Output } from "./AgentOutput.ts"
28
28
  // Agent tasks: lifetime and completion delivery.
29
29
  //
30
30
  // These drive the real Agent loop and a real executor, so the model only
31
- // talks to the script API: `subagent({ prompt, background })`, `waitTasks`,
31
+ // talks to the script API: `subagent({ prompt, description, background })`, `waitTasks`,
32
32
  // `messageAgent`, `stopTask`, `listTasks` and `taskOutput`. One scripted
33
33
  // LanguageModel serves every agent; calls are routed by the task marker in
34
34
  // each agent's first user message. Task IDs come from the executor's counter,
@@ -158,7 +158,7 @@ const complete = (output: string) =>
158
158
  const spawnBackground = (task: string) =>
159
159
  toolCall(
160
160
  `spawn-${task}`,
161
- `const result = await subagent({ prompt: "${task}", background: true })
161
+ `const result = await subagent({ description: "Handle child request", prompt: "${task}", background: true })
162
162
  console.log(JSON.stringify(result))`,
163
163
  )
164
164
 
@@ -319,7 +319,7 @@ for (const [executorName, executorLayer] of executors) {
319
319
  assert.include(started, '"id":"subagent_1"')
320
320
  assert.include(started, '"kind":"agent"')
321
321
  assert.include(started, '"status":"running"')
322
- assert.include(started, '"description":"TASK-CHILD"')
322
+ assert.include(started, '"description":"Handle child request"')
323
323
 
324
324
  const push = findPush(root[2]!.prompt, "subagent_1", "completed")
325
325
  assert.notStrictEqual(push.index, -1, "completion push delivered")
@@ -423,7 +423,7 @@ for (const [executorName, executorLayer] of executors) {
423
423
  return Stream.make(
424
424
  toolCall(
425
425
  "foreground",
426
- 'await subagent({ prompt: "TASK-CHILD" })',
426
+ 'await subagent({ description: "Handle child request", prompt: "TASK-CHILD" })',
427
427
  ),
428
428
  )
429
429
  }
@@ -490,7 +490,7 @@ for (const [executorName, executorLayer] of executors) {
490
490
  return Stream.make(
491
491
  toolCall(
492
492
  "too-early",
493
- `await subagent({ prompt: "TASK-CHILD", background: true })
493
+ `await subagent({ description: "Handle child request", prompt: "TASK-CHILD", background: true })
494
494
  try {
495
495
  await taskComplete("too early")
496
496
  console.log("ACCEPTED")
@@ -798,7 +798,7 @@ console.log("MESSAGE-VOID:", result === undefined)`,
798
798
  return Stream.make(
799
799
  toolCall(
800
800
  "foreground",
801
- `const result = await subagent({ prompt: "TASK-CHILD" })
801
+ `const result = await subagent({ description: "Handle child request", prompt: "TASK-CHILD" })
802
802
  console.log(JSON.stringify(result))`,
803
803
  ),
804
804
  )
@@ -850,7 +850,7 @@ console.log(JSON.stringify(result))`,
850
850
  Stream.make(
851
851
  toolCall(
852
852
  `pwd-${name}`,
853
- `const pwd = await bash({ command: "pwd" })
853
+ `const pwd = await bash({ description: "Locate working directory", command: "pwd" })
854
854
  await taskComplete("${name.toUpperCase()}:" + pwd.output.trim())`,
855
855
  ),
856
856
  ),
@@ -862,12 +862,12 @@ await taskComplete("${name.toUpperCase()}:" + pwd.output.trim())`,
862
862
  return Stream.make(
863
863
  toolCall(
864
864
  "spawn",
865
- `await bash({ command: "mkdir -p a/one a/two" })
865
+ `await bash({ description: "Create test directories", command: "mkdir -p a/one a/two" })
866
866
  await changeDirectory("a")
867
- const one = await subagent({ prompt: "TASK-CHILD-ONE", background: true })
868
- const two = await subagent({ prompt: "TASK-CHILD-TWO", background: true })
867
+ const one = await subagent({ description: "Handle child request", prompt: "TASK-CHILD-ONE", background: true })
868
+ const two = await subagent({ description: "Handle child request", prompt: "TASK-CHILD-TWO", background: true })
869
869
  console.log(JSON.stringify(await waitTasks({ ids: [one.id, two.id] })))
870
- console.log("ROOT:" + (await bash({ command: "pwd" })).output.trim())`,
870
+ console.log("ROOT:" + (await bash({ description: "Locate working directory", command: "pwd" })).output.trim())`,
871
871
  ),
872
872
  )
873
873
  case 1:
@@ -897,11 +897,11 @@ console.log("ROOT:" + (await bash({ command: "pwd" })).output.trim())`,
897
897
  return Stream.make(
898
898
  toolCall(
899
899
  "mixed",
900
- `const agentTask = await subagent({ prompt: "TASK-CHILD", background: true })
901
- const bashTask = await bash({ command: "echo BASH-OUT", background: true })
900
+ `const agentTask = await subagent({ description: "Handle child request", prompt: "TASK-CHILD", background: true })
901
+ const bashTask = await bash({ description: "Print test output", command: "echo BASH-OUT", background: true })
902
902
  console.log("IDS:" + JSON.stringify((await listTasks()).map(task => task.id)))
903
903
  const ended = await waitTasks({ ids: [bashTask.id, agentTask.id] })
904
- console.log(JSON.stringify(ended.map(({ id, kind, status, output }) => ({ id, kind, status, output: output.trim() }))))`,
904
+ console.log(JSON.stringify(ended.map(({ id, kind, description, status, output }) => ({ id, kind, description, status, output: output.trim() }))))`,
905
905
  ),
906
906
  )
907
907
  case 1:
@@ -925,12 +925,14 @@ console.log(JSON.stringify(ended.map(({ id, kind, status, output }) => ({ id, ki
925
925
  {
926
926
  id: "bash_2",
927
927
  kind: "bash",
928
+ description: "Print test output",
928
929
  status: "completed",
929
930
  output: "BASH-OUT",
930
931
  },
931
932
  {
932
933
  id: "subagent_1",
933
934
  kind: "agent",
935
+ description: "Handle child request",
934
936
  status: "completed",
935
937
  output: "CHILD-OUT",
936
938
  },
@@ -975,8 +977,8 @@ await taskComplete(JSON.stringify({ seen, attempts }))`,
975
977
  return Stream.make(
976
978
  toolCall(
977
979
  "spawn",
978
- `const server = await bash({ command: "sleep 30", background: true })
979
- const child = await subagent({ prompt: "TASK-CHILD BASH-ID:" + server.id })
980
+ `const server = await bash({ description: "Keep server running", command: "sleep 30", background: true })
981
+ const child = await subagent({ description: "Handle child request", prompt: "TASK-CHILD BASH-ID:" + server.id })
980
982
  console.log("CHILD:" + child.output)
981
983
  const mine = await listTasks()
982
984
  console.log("ROOT:" + JSON.stringify(mine.map((task) => task.kind + ":" + task.status).sort()))`,
@@ -1033,7 +1035,7 @@ console.log("ROOT:" + JSON.stringify(mine.map((task) => task.kind + ":" + task.s
1033
1035
  return Stream.make(
1034
1036
  toolCall(
1035
1037
  "wait",
1036
- `const child = await subagent({ prompt: "TASK-CHILD", background: true })
1038
+ `const child = await subagent({ description: "Handle child request", prompt: "TASK-CHILD", background: true })
1037
1039
  const [task] = await waitTasks({ ids: [child.id], timeoutMs: 200 })
1038
1040
  console.log("WAITED:" + task.status)
1039
1041
  console.log("OUTPUT:" + task.output)`,
@@ -1084,9 +1086,9 @@ console.log("OUTPUT:" + task.output)`,
1084
1086
  return Stream.make(
1085
1087
  toolCall(
1086
1088
  "wait",
1087
- `const quick = await bash({ command: "echo BASH-OUT", background: true })
1088
- const child = await subagent({ prompt: "TASK-CHILD", background: true })
1089
- const slow = await bash({ command: "sleep 30", background: true })
1089
+ `const quick = await bash({ description: "Print test output", command: "echo BASH-OUT", background: true })
1090
+ const child = await subagent({ description: "Handle child request", prompt: "TASK-CHILD", background: true })
1091
+ const slow = await bash({ description: "Keep server running", command: "sleep 30", background: true })
1090
1092
  await waitTasks({ ids: [quick.id, child.id, slow.id] })
1091
1093
  console.log("RETURNED")`,
1092
1094
  ),
@@ -1168,8 +1170,8 @@ describe("agent tasks (rpc executor, slow callbacks)", () => {
1168
1170
  return Stream.make(
1169
1171
  toolCall(
1170
1172
  "wait",
1171
- `const a = await subagent({ prompt: "TASK-CHILD-A", background: true })
1172
- const b = await subagent({ prompt: "TASK-CHILD-B", background: true })
1173
+ `const a = await subagent({ description: "Handle child request", prompt: "TASK-CHILD-A", background: true })
1174
+ const b = await subagent({ description: "Handle child request", prompt: "TASK-CHILD-B", background: true })
1173
1175
  const ended = await waitTasks({ ids: [a.id, b.id] })
1174
1176
  console.log(ended.map((task) => task.output).join(" "))`,
1175
1177
  ),
package/src/AgentTools.ts CHANGED
@@ -102,7 +102,7 @@ export const Task = Schema.Struct({
102
102
  }),
103
103
  kind: TaskKind,
104
104
  status: TaskStatus,
105
- /** The bash command, or the sub-agent's prompt. */
105
+ /** The description supplied when the task was started. */
106
106
  description: Schema.String,
107
107
  /** Output so far, a background-running notice after a timeout, or the final output/error. */
108
108
  output: Schema.String,
@@ -134,6 +134,7 @@ export interface AgentTasks {
134
134
  readonly subagent: (options: {
135
135
  readonly id: string
136
136
  readonly prompt: string
137
+ readonly description: string
137
138
  readonly background: boolean
138
139
  }) => Effect.Effect<Task>
139
140
  /**
@@ -311,6 +312,9 @@ export const makeBashTool = (timeout: Duration.Duration) =>
311
312
  description: "Run a bash command and return a task.",
312
313
  parameters: Schema.Struct({
313
314
  command: Schema.String,
315
+ description: Schema.String.annotate({
316
+ description: "What the command is doing",
317
+ }),
314
318
  timeoutMs: Schema.optional(Schema.Finite).annotate({
315
319
  documentation: `How long to wait in ms before moving the task to the background (default and max: ${Duration.toMillis(timeout)})`,
316
320
  }),
@@ -400,6 +404,9 @@ export const AgentTools = Toolkit.make(
400
404
  "Delegate a task to another software engineer / sub-agent. With `background: true` the sub-agent works in the background, and its result is sent to you when it finishes.",
401
405
  parameters: Schema.Struct({
402
406
  prompt: Schema.String,
407
+ description: Schema.String.annotate({
408
+ description: "What the subagent is doing",
409
+ }),
403
410
  background: Schema.optional(Schema.Boolean),
404
411
  }),
405
412
  success: Task,
@@ -702,11 +709,8 @@ export const AgentToolHandlersNoDeps = AgentTools.toLayer(
702
709
  return `Image attached: ${fileName}`
703
710
  })
704
711
 
705
- const bash = Effect.fn("AgentTools.bash")(function* (options: {
706
- readonly command: string
707
- readonly timeoutMs?: number | undefined
708
- readonly background?: boolean | undefined
709
- }) {
712
+ const bash = Effect.fn("AgentTools.bash")(function* (input: unknown) {
713
+ const options = yield* decodeBash(input)
710
714
  const maxMs = bashTimeoutMs(yield* CommandLimits)
711
715
  const timeoutMs = Math.min(options.timeoutMs ?? maxMs, maxMs)
712
716
  yield* Effect.logInfo(`Calling "bash"`).pipe(
@@ -721,7 +725,7 @@ export const AgentToolHandlersNoDeps = AgentTools.toLayer(
721
725
  stdin: "ignore",
722
726
  })
723
727
  const entry = yield* addBashTask(
724
- options.command,
728
+ options.description,
725
729
  yield* startCommand(cmd, true),
726
730
  )
727
731
  if (options.background !== true) {
@@ -898,7 +902,11 @@ export const AgentToolHandlersNoDeps = AgentTools.toLayer(
898
902
  }),
899
903
  bash,
900
904
  run: Effect.fn("AgentTools.run")(function* (command) {
901
- const task = yield* bash({ command, timeoutMs: 120_000 })
905
+ const task = yield* bash({
906
+ command,
907
+ description: "",
908
+ timeoutMs: 120_000,
909
+ })
902
910
  return task.output
903
911
  }),
904
912
  taskOutput: Effect.fn("AgentTools.taskOutput")(function* (
@@ -1163,13 +1171,22 @@ export const AgentToolHandlersNoDeps = AgentTools.toLayer(
1163
1171
  return `Success. Updated the following files:\n${out.join("\n")}`
1164
1172
  }, Effect.orDie),
1165
1173
  subagent: Effect.fn("AgentTools.subagent")(function* (options: unknown) {
1166
- const { prompt, background = false } = yield* decodeSubagent(options)
1174
+ const {
1175
+ prompt,
1176
+ description,
1177
+ background = false,
1178
+ } = yield* decodeSubagent(options)
1167
1179
  yield* Effect.logInfo(`Calling "subagent"`).pipe(
1168
1180
  Effect.annotateLogs({ background }),
1169
1181
  )
1170
1182
  const id = yield* registerAgentTask
1171
1183
  const agentTasks = yield* AgentTaskExecutor
1172
- return yield* agentTasks.subagent({ id, prompt, background })
1184
+ return yield* agentTasks.subagent({
1185
+ id,
1186
+ prompt,
1187
+ background,
1188
+ description,
1189
+ })
1173
1190
  }),
1174
1191
  messageAgent: Effect.fn("AgentTools.messageAgent")(function* (
1175
1192
  input: unknown,
@@ -1238,9 +1255,13 @@ const decodeParams = <S extends Schema.Decoder<unknown>>(
1238
1255
  return (input: unknown) => Effect.mapError(decode(input), () => usage)
1239
1256
  }
1240
1257
 
1258
+ const decodeBash = decodeParams(
1259
+ AgentTools.tools.bash.parametersSchema,
1260
+ 'bash requires an options object, for example: bash({ command: "...", description: "..." }).',
1261
+ )
1241
1262
  const decodeSubagent = decodeParams(
1242
1263
  AgentTools.tools.subagent.parametersSchema,
1243
- 'subagent requires an options object, for example: subagent({ prompt: "..." }) or subagent({ prompt: "...", background: true }).',
1264
+ 'subagent requires an options object, for example: subagent({ prompt: "...", description: "...", background: true }).',
1244
1265
  )
1245
1266
  const decodeMessageAgent = decodeParams(
1246
1267
  AgentTools.tools.messageAgent.parametersSchema,
@@ -881,7 +881,7 @@ await taskComplete(JSON.stringify({ crashed, after: await attempt(mcp.fake.echo(
881
881
  return "await taskComplete(await mcp.fake.ping({}))"
882
882
  }
883
883
  return call.index === 0
884
- ? `const child = await subagent({ prompt: "TASK-CHILD" })
884
+ ? `const child = await subagent({ description: "Handle child request", prompt: "TASK-CHILD" })
885
885
  console.log(JSON.stringify(child))
886
886
  console.log(await mcp.fake.screenshot({}))`
887
887
  : 'await taskComplete("done")'