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
@@ -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")'