clanka 0.28.1 → 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.
Files changed (42) hide show
  1. package/dist/Acp.test.js +4 -2
  2. package/dist/Acp.test.js.map +1 -1
  3. package/dist/Agent.d.ts.map +1 -1
  4. package/dist/Agent.js +4 -4
  5. package/dist/Agent.js.map +1 -1
  6. package/dist/Agent.test.js +4 -0
  7. package/dist/Agent.test.js.map +1 -1
  8. package/dist/AgentBashJobs.test.js +9 -9
  9. package/dist/AgentBashJobs.test.js.map +1 -1
  10. package/dist/AgentCallerConfig.test.js +13 -0
  11. package/dist/AgentCallerConfig.test.js.map +1 -1
  12. package/dist/AgentEnvironment.test.js +1 -1
  13. package/dist/AgentEnvironment.test.js.map +1 -1
  14. package/dist/AgentExecutor.d.ts +4 -0
  15. package/dist/AgentExecutor.d.ts.map +1 -1
  16. package/dist/AgentExecutor.js +3 -0
  17. package/dist/AgentExecutor.js.map +1 -1
  18. package/dist/AgentExecutor.test.js +46 -28
  19. package/dist/AgentExecutor.test.js.map +1 -1
  20. package/dist/AgentImage.test.js +1 -0
  21. package/dist/AgentImage.test.js.map +1 -1
  22. package/dist/AgentSubagents.test.js +23 -21
  23. package/dist/AgentSubagents.test.js.map +1 -1
  24. package/dist/AgentTools.d.ts +25 -17
  25. package/dist/AgentTools.d.ts.map +1 -1
  26. package/dist/AgentTools.js +24 -7
  27. package/dist/AgentTools.js.map +1 -1
  28. package/dist/McpServers.test.js +1 -1
  29. package/dist/bin/cli.mjs +19 -10
  30. package/package.json +1 -1
  31. package/src/Acp.test.ts +4 -2
  32. package/src/Agent.test.ts +4 -0
  33. package/src/Agent.ts +5 -4
  34. package/src/AgentBashJobs.test.ts +9 -9
  35. package/src/AgentCallerConfig.test.ts +16 -0
  36. package/src/AgentEnvironment.test.ts +3 -1
  37. package/src/AgentExecutor.test.ts +62 -28
  38. package/src/AgentExecutor.ts +4 -0
  39. package/src/AgentImage.test.ts +1 -0
  40. package/src/AgentSubagents.test.ts +24 -22
  41. package/src/AgentTools.ts +32 -11
  42. package/src/McpServers.test.ts +1 -1
package/dist/bin/cli.mjs CHANGED
@@ -13882,6 +13882,7 @@ const makeBashTool = (timeout) => make$16("bash", {
13882
13882
  description: "Run a bash command and return a task.",
13883
13883
  parameters: Struct({
13884
13884
  command: String$8,
13885
+ description: String$8.annotate({ description: "What the command is doing" }),
13885
13886
  timeoutMs: optional$2(Finite).annotate({ documentation: `How long to wait in ms before moving the task to the background (default and max: ${toMillis(timeout)})` }),
13886
13887
  background: optional$2(Boolean$4).annotate({ documentation: "Start the command in the background. Defaults to false which always returns 'completed' tasks." })
13887
13888
  }).annotate({ identifier: "command" }),
@@ -13923,6 +13924,7 @@ const AgentTools = make$15(make$16("changeDirectory", {
13923
13924
  description: "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.",
13924
13925
  parameters: Struct({
13925
13926
  prompt: String$8,
13927
+ description: String$8.annotate({ description: "What the subagent is doing" }),
13926
13928
  background: optional$2(Boolean$4)
13927
13929
  }),
13928
13930
  success: Task,
@@ -14101,7 +14103,8 @@ const AgentToolHandlersNoDeps = AgentTools.toLayer(gen(function* () {
14101
14103
  });
14102
14104
  return `Image attached: ${fileName}`;
14103
14105
  });
14104
- const bash = fn("AgentTools.bash")(function* (options) {
14106
+ const bash = fn("AgentTools.bash")(function* (input) {
14107
+ const options = yield* decodeBash(input);
14105
14108
  const maxMs = bashTimeoutMs(yield* CommandLimits);
14106
14109
  const timeoutMs = Math.min(options.timeoutMs ?? maxMs, maxMs);
14107
14110
  yield* logInfo(`Calling "bash"`).pipe(annotateLogs({
@@ -14113,7 +14116,7 @@ const AgentToolHandlersNoDeps = AgentTools.toLayer(gen(function* () {
14113
14116
  cwd,
14114
14117
  stdin: "ignore"
14115
14118
  });
14116
- const entry = yield* addBashTask(options.command, yield* startCommand(cmd, true));
14119
+ const entry = yield* addBashTask(options.description, yield* startCommand(cmd, true));
14117
14120
  if (options.background !== true) {
14118
14121
  const exit = yield* awaitCommand(entry.command, millis(timeoutMs));
14119
14122
  if (isSome(exit)) {
@@ -14202,6 +14205,7 @@ const AgentToolHandlersNoDeps = AgentTools.toLayer(gen(function* () {
14202
14205
  run: fn("AgentTools.run")(function* (command) {
14203
14206
  return (yield* bash({
14204
14207
  command,
14208
+ description: "",
14205
14209
  timeoutMs: 12e4
14206
14210
  })).output;
14207
14211
  }),
@@ -14363,13 +14367,14 @@ const AgentToolHandlersNoDeps = AgentTools.toLayer(gen(function* () {
14363
14367
  return `Success. Updated the following files:\n${out.join("\n")}`;
14364
14368
  }, orDie$2),
14365
14369
  subagent: fn("AgentTools.subagent")(function* (options) {
14366
- const { prompt, background = false } = yield* decodeSubagent(options);
14370
+ const { prompt, description, background = false } = yield* decodeSubagent(options);
14367
14371
  yield* logInfo(`Calling "subagent"`).pipe(annotateLogs({ background }));
14368
14372
  const id = yield* registerAgentTask;
14369
14373
  return yield* (yield* AgentTaskExecutor).subagent({
14370
14374
  id,
14371
14375
  prompt,
14372
- background
14376
+ background,
14377
+ description
14373
14378
  });
14374
14379
  }),
14375
14380
  messageAgent: fn("AgentTools.messageAgent")(function* (input) {
@@ -14391,7 +14396,8 @@ const decodeParams$1 = (schema, usage) => {
14391
14396
  const decode = decodeUnknownEffect$1(schema);
14392
14397
  return (input) => mapError$2(decode(input), () => usage);
14393
14398
  };
14394
- const decodeSubagent = decodeParams$1(AgentTools.tools.subagent.parametersSchema, "subagent requires an options object, for example: subagent({ prompt: \"...\" }) or subagent({ prompt: \"...\", background: true }).");
14399
+ const decodeBash = decodeParams$1(AgentTools.tools.bash.parametersSchema, "bash requires an options object, for example: bash({ command: \"...\", description: \"...\" }).");
14400
+ const decodeSubagent = decodeParams$1(AgentTools.tools.subagent.parametersSchema, "subagent requires an options object, for example: subagent({ prompt: \"...\", description: \"...\", background: true }).");
14395
14401
  const decodeMessageAgent = decodeParams$1(AgentTools.tools.messageAgent.parametersSchema, "messageAgent requires an options object, for example: messageAgent({ id: \"subagent_3\", message: \"...\" }).");
14396
14402
  const decodeTaskOutput = decodeParams$1(AgentTools.tools.taskOutput.parametersSchema, "taskOutput requires a task id, for example: taskOutput(\"bash_1\").");
14397
14403
  const decodeWaitTasks = decodeParams$1(AgentTools.tools.waitTasks.parametersSchema, "waitTasks requires an options object, for example: waitTasks({ ids: [\"subagent_3\", \"bash_4\"] }) or waitTasks({ ids: [\"subagent_3\"], timeoutMs: 60000 }).");
@@ -16724,6 +16730,7 @@ const AgentRequest = TaggedUnion({
16724
16730
  Subagent: {
16725
16731
  id: String$8,
16726
16732
  prompt: String$8,
16733
+ description: String$8,
16727
16734
  background: Boolean$4,
16728
16735
  environment: EnvironmentUpdate
16729
16736
  },
@@ -16960,6 +16967,8 @@ function runScriptWorker(load) {
16960
16967
  ...data.offersFetch ? { fetch } : {},
16961
16968
  AbortSignal,
16962
16969
  AbortController,
16970
+ TextEncoder,
16971
+ TextDecoder,
16963
16972
  process: void 0
16964
16973
  };
16965
16974
  const mcp = Object.create(null);
@@ -23564,11 +23573,11 @@ const makeWith = fnUntraced(function* (options) {
23564
23573
  }), as(""), catchTag("AgentFinished", (finished) => succeed$3(finished.summary)));
23565
23574
  }).pipe(onExit$2((exit) => finishTurn(child, turn, exit)), provideSubagentModel, provideContext$2(runContext), forkIn(runScope, { startImmediately: true }));
23566
23575
  });
23567
- const childTask = ({ taskId, prompt, turn }) => ({
23576
+ const childTask = ({ taskId, description, turn }) => ({
23568
23577
  id: taskId,
23569
23578
  kind: "agent",
23570
23579
  status: turn.status,
23571
- description: prompt,
23580
+ description,
23572
23581
  output: turn.output ?? ""
23573
23582
  });
23574
23583
  const reportChild = (child) => {
@@ -23580,12 +23589,12 @@ const makeWith = fnUntraced(function* (options) {
23580
23589
  return child ? succeed$3(child) : fail$4(`No task with id ${JSON.stringify(id)}. You can only address tasks you started; call listTasks() to see them.`);
23581
23590
  });
23582
23591
  const agentTasks = {
23583
- subagent: fnUntraced(function* ({ id, prompt, background, environment }) {
23592
+ subagent: fnUntraced(function* ({ id, prompt, description, background, environment }) {
23584
23593
  const child = {
23585
23594
  id: Number(id.slice(9)),
23586
23595
  taskId: id,
23587
23596
  taskOwner: crypto.randomUUID(),
23588
- prompt,
23597
+ description,
23589
23598
  history: make$41(empty$1),
23590
23599
  environment: make$41(environment.environment),
23591
23600
  mailbox: makeMailbox(),
@@ -31211,7 +31220,7 @@ const transformToolCallParams$1 = fnUntraced(function* (options, toolName, toolP
31211
31220
  return yield* decodeEffect(codec)(toolParams).pipe(flatMap$3((decoded) => encodeUnknownEffect(toCodecJson(tool.parametersSchema))(decoded)), orElseSucceed(() => toolParams));
31212
31221
  });
31213
31222
  // package.json
31214
- var version$1 = "0.28.1";
31223
+ var version$1 = "0.28.3";
31215
31224
  // src/ClaudeAgent.ts
31216
31225
  const minimumClaudeCodeVersion = "2.1.248";
31217
31226
  const serverName = "clanka";
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "clanka",
3
3
  "type": "module",
4
- "version": "0.28.1",
4
+ "version": "0.28.3",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
package/src/Acp.test.ts CHANGED
@@ -671,6 +671,7 @@ describe("Acp", () => {
671
671
  execute: ({ agentTasks, environment }) =>
672
672
  Stream.fromEffect(
673
673
  agentTasks.subagent({
674
+ description: "Handle child request",
674
675
  id: "subagent_1",
675
676
  prompt,
676
677
  background: false,
@@ -770,6 +771,7 @@ describe("Acp", () => {
770
771
  executions++ === 0
771
772
  ? agentTasks
772
773
  .subagent({
774
+ description: "Handle child request",
773
775
  id: "subagent_1",
774
776
  prompt: "TASK-CHILD",
775
777
  background: true,
@@ -1035,7 +1037,7 @@ describe("Acp", () => {
1035
1037
  const sessionId = yield* Effect.scoped(
1036
1038
  Effect.gen(function* () {
1037
1039
  const server = yield* makeServer(
1038
- runsScript(`await bash({ command: "mkdir sub" })
1040
+ runsScript(`await bash({ description: "Create test directories", command: "mkdir sub" })
1039
1041
  await changeDirectory("sub")`),
1040
1042
  yield* localExecutor(cwd),
1041
1043
  )
@@ -1053,7 +1055,7 @@ await changeDirectory("sub")`),
1053
1055
  Effect.gen(function* () {
1054
1056
  const server = yield* makeServer(
1055
1057
  runsScript(
1056
- `console.log("PWD:" + (await bash({ command: "pwd" })).output.trim())`,
1058
+ `console.log("PWD:" + (await bash({ description: "Locate working directory", command: "pwd" })).output.trim())`,
1057
1059
  ),
1058
1060
  yield* localExecutor(cwd),
1059
1061
  )
package/src/Agent.test.ts CHANGED
@@ -182,6 +182,7 @@ describe("Agent", () => {
182
182
  (script === "done"
183
183
  ? onTaskComplete("done")
184
184
  : agentTasks.subagent({
185
+ description: "Handle child request",
185
186
  id: "subagent_1",
186
187
  prompt: "TASK-CHILD",
187
188
  background: false,
@@ -632,6 +633,7 @@ describe("Agent usage", () => {
632
633
  Stream.fromEffect(
633
634
  Effect.gen(function* () {
634
635
  const task = yield* agentTasks.subagent({
636
+ description: "Handle child request",
635
637
  id: script,
636
638
  prompt: "nested task",
637
639
  background,
@@ -741,6 +743,7 @@ describe("Agent usage", () => {
741
743
  update: Option.none(),
742
744
  })
743
745
  const background = yield* agentTasks.subagent({
746
+ description: "Handle child request",
744
747
  id: "subagent_1",
745
748
  prompt: "sibling-b",
746
749
  background: true,
@@ -753,6 +756,7 @@ describe("Agent usage", () => {
753
756
  Effect.forkScoped,
754
757
  )
755
758
  yield* agentTasks.subagent({
759
+ description: "Handle child request",
756
760
  id: "subagent_2",
757
761
  prompt: "sibling-a",
758
762
  background: false,
package/src/Agent.ts CHANGED
@@ -623,11 +623,11 @@ export const makeWith = Effect.fnUntraced(function* <
623
623
  )
624
624
  })
625
625
 
626
- const childTask = ({ taskId, prompt, turn }: Child): Task => ({
626
+ const childTask = ({ taskId, description, turn }: Child): Task => ({
627
627
  id: taskId,
628
628
  kind: "agent",
629
629
  status: turn.status,
630
- description: prompt,
630
+ description,
631
631
  output: turn.output ?? "",
632
632
  })
633
633
  // A final status returned to the script is not pushed as well.
@@ -650,6 +650,7 @@ export const makeWith = Effect.fnUntraced(function* <
650
650
  subagent: Effect.fnUntraced(function* ({
651
651
  id,
652
652
  prompt,
653
+ description,
653
654
  background,
654
655
  environment,
655
656
  }) {
@@ -657,7 +658,7 @@ export const makeWith = Effect.fnUntraced(function* <
657
658
  id: Number(id.slice("subagent_".length)),
658
659
  taskId: id,
659
660
  taskOwner: crypto.randomUUID(),
660
- prompt,
661
+ description,
661
662
  history: MutableRef.make(Prompt.empty),
662
663
  environment: MutableRef.make(environment.environment),
663
664
  mailbox: makeMailbox(),
@@ -1646,7 +1647,7 @@ interface Child {
1646
1647
  readonly id: number
1647
1648
  /** The agent's own owner id for the tasks it starts. */
1648
1649
  readonly taskOwner: string
1649
- readonly prompt: string
1650
+ readonly description: string
1650
1651
  /** Kept for the whole run so `messageAgent` can resume the agent. */
1651
1652
  readonly history: MutableRef.MutableRef<Prompt.Prompt>
1652
1653
  /** Starts as a copy of the parent's at the moment it was delegated. */
@@ -171,7 +171,7 @@ for (const [executorName, executorLayer] of executors) {
171
171
  // next model call.
172
172
  return execute(
173
173
  "start",
174
- `await bash({ command: "echo JOB-OUTPUT && exit 3", background: true })
174
+ `await bash({ description: "Simulate failure", command: "echo JOB-OUTPUT && exit 3", background: true })
175
175
  await sleep(500)`,
176
176
  )
177
177
  case 1:
@@ -218,17 +218,17 @@ await sleep(500)`,
218
218
  // Task 3 is never read, so it is the only push.
219
219
  return execute(
220
220
  "start",
221
- `await bash({ command: "sleep 30", background: true })
222
- await bash({ command: "echo READ", background: true })
223
- await bash({ command: "echo UNREAD", background: true })
221
+ `await bash({ description: "Keep server running", command: "sleep 30", background: true })
222
+ await bash({ description: "Print test output", command: "echo READ", background: true })
223
+ await bash({ description: "Print test output", command: "echo UNREAD", background: true })
224
224
  await stopTask("bash_1")
225
225
  let task = await taskOutput("bash_2")
226
226
  while (task.status === "running") {
227
227
  await sleep(20)
228
228
  task = await taskOutput("bash_2")
229
229
  }
230
- await bash({ command: "echo FOREGROUND" })
231
- await waitTasks({ ids: [(await bash({ command: "echo WAITED", background: true })).id] })
230
+ await bash({ description: "Print test output", command: "echo FOREGROUND" })
231
+ await waitTasks({ ids: [(await bash({ description: "Print test output", command: "echo WAITED", background: true })).id] })
232
232
  await sleep(500)
233
233
  console.log("SCRIPT" + "-DONE")`,
234
234
  )
@@ -259,7 +259,7 @@ console.log("SCRIPT" + "-DONE")`,
259
259
  index === 0
260
260
  ? execute(
261
261
  "start",
262
- `await bash({ command: "sleep 30", background: true })`,
262
+ `await bash({ description: "Keep server running", command: "sleep 30", background: true })`,
263
263
  )
264
264
  : text("idle"),
265
265
  )
@@ -270,7 +270,7 @@ console.log("SCRIPT" + "-DONE")`,
270
270
  index === 0
271
271
  ? execute(
272
272
  "complete",
273
- `await bash({ command: "sleep 30", background: true })
273
+ `await bash({ description: "Keep server running", command: "sleep 30", background: true })
274
274
  await taskComplete("done")`,
275
275
  )
276
276
  : text("taskComplete was rejected"),
@@ -329,7 +329,7 @@ describe("background bash tasks across versions", () => {
329
329
  const { environment } = yield* client.capabilities()
330
330
  const parts = yield* client
331
331
  .execute({
332
- script: `await bash({ command: "true", background: true })`,
332
+ script: `await bash({ description: "Check shell status", command: "true", background: true })`,
333
333
  environment,
334
334
  loopTools: [],
335
335
  })
@@ -229,6 +229,22 @@ const execute = (
229
229
  // Where the RPC executor takes its own path.
230
230
  for (const mode of modes) {
231
231
  describe(`${mode} executor`, () => {
232
+ it.live("scripts can encode and decode text without type docs", () =>
233
+ Effect.gen(function* () {
234
+ const { summary, system } = yield* runAgent({
235
+ mode,
236
+ script: `const bytes = new TextEncoder().encode("héllo 🌍")
237
+ const decoded = new TextDecoder().decode(bytes)
238
+ await taskComplete(JSON.stringify({ bytes: Array.from(bytes), decoded }))`,
239
+ })
240
+ assert.deepStrictEqual(JSON.parse(summary), {
241
+ bytes: [104, 195, 169, 108, 108, 111, 32, 240, 159, 140, 141],
242
+ decoded: "héllo 🌍",
243
+ })
244
+ assert.notMatch(system, /TextEncoder|TextDecoder/)
245
+ }),
246
+ )
247
+
232
248
  it.live("scripts can cancel fetches and create timeout signals", () =>
233
249
  Effect.gen(function* () {
234
250
  const { summary } = yield* runAgent({
@@ -277,7 +277,9 @@ for (const [mode, executorLayer] of Object.entries(executors)) {
277
277
  return Stream.make(toolCall(`await changeDirectory("pkg")`))
278
278
  case 3:
279
279
  return Stream.make(
280
- toolCall(`await subagent({ prompt: "TASK-CHILD" })`),
280
+ toolCall(
281
+ `await subagent({ description: "Handle child request", prompt: "TASK-CHILD" })`,
282
+ ),
281
283
  )
282
284
  default:
283
285
  return Stream.fromIterable(text("done"))
@@ -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
  },
@@ -1578,6 +1580,8 @@ function runScriptWorker(load: (id: string) => unknown): void {
1578
1580
  ...(data.offersFetch ? { fetch } : {}),
1579
1581
  AbortSignal,
1580
1582
  AbortController,
1583
+ TextEncoder,
1584
+ TextDecoder,
1581
1585
  process: undefined,
1582
1586
  }
1583
1587
  // MCP tools are named "<server>.<tool>" and bound as `mcp[server][tool]`.
@@ -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,