clanka 0.22.5 → 0.23.0

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.
@@ -29,7 +29,7 @@ import * as Compaction from "./Compaction.ts"
29
29
  // Agent tasks: lifetime and completion delivery.
30
30
  //
31
31
  // These drive the real Agent loop and a real executor, so the model only
32
- // talks to the script API: `delegate({ prompt, background })`, `waitTasks`,
32
+ // talks to the script API: `subagent({ prompt, background })`, `waitTasks`,
33
33
  // `messageAgent`, `stopTask`, `listTasks` and `taskOutput`. One scripted
34
34
  // LanguageModel serves every agent; calls are routed by the task marker in
35
35
  // each agent's first user message. Task IDs come from the executor's counter,
@@ -159,7 +159,7 @@ const complete = (output: string) =>
159
159
  const spawnBackground = (task: string) =>
160
160
  toolCall(
161
161
  `spawn-${task}`,
162
- `const result = await delegate({ prompt: "${task}", background: true })
162
+ `const result = await subagent({ prompt: "${task}", background: true })
163
163
  console.log(JSON.stringify(result))`,
164
164
  )
165
165
 
@@ -459,7 +459,7 @@ for (const [executorName, executorLayer] of executors) {
459
459
  return Stream.make(
460
460
  toolCall(
461
461
  "too-early",
462
- `await delegate({ prompt: "TASK-CHILD", background: true })
462
+ `await subagent({ prompt: "TASK-CHILD", background: true })
463
463
  try {
464
464
  await taskComplete("too early")
465
465
  console.log("ACCEPTED")
@@ -603,8 +603,8 @@ await taskComplete("done")`,
603
603
  Stream.as(
604
604
  toolCall(
605
605
  "stop",
606
- `const result = await stopTask("1")
607
- console.log(JSON.stringify(result))`,
606
+ `console.log("STOP-VOID:", (await stopTask("1")) === undefined)
607
+ console.log(JSON.stringify(await taskOutput("1")))`,
608
608
  ),
609
609
  ),
610
610
  )
@@ -622,6 +622,7 @@ console.log(JSON.stringify(result))`,
622
622
  assert.deepStrictEqual(exit, Exit.succeed("stopped"))
623
623
  const root = calls.filter((call) => call.role === "root")
624
624
  const stopped = lastToolResult(root[2]!.prompt)
625
+ assert.include(stopped, "STOP-VOID: true")
625
626
  assert.include(stopped, '"id":"1"')
626
627
  assert.include(stopped, '"status":"stopped"')
627
628
  assert.isTrue(
@@ -630,6 +631,51 @@ console.log(JSON.stringify(result))`,
630
631
  )
631
632
  }))
632
633
 
634
+ test("messageAgent returns void when steering a running child", () =>
635
+ Effect.gen(function* () {
636
+ const childStarted = Latch.makeUnsafe(false)
637
+ const childRelease = Latch.makeUnsafe(false)
638
+ const { exit, calls } = yield* runAgent({
639
+ conversationMode: true,
640
+ respond: (call) => {
641
+ if (call.role === "child") {
642
+ if (call.index === 0) {
643
+ return Stream.fromEffect(
644
+ Effect.sync(() => childStarted.openUnsafe()).pipe(
645
+ Effect.andThen(childRelease.await),
646
+ ),
647
+ ).pipe(Stream.flatMap(() => Stream.fromIterable(text("ready"))))
648
+ }
649
+ return complete("STEERED-ANSWER")
650
+ }
651
+ if (call.index === 0) {
652
+ return Stream.make(spawnBackground("TASK-CHILD"))
653
+ }
654
+ if (call.index === 1) {
655
+ return Stream.fromEffect(childStarted.await).pipe(
656
+ Stream.as(
657
+ toolCall(
658
+ "message",
659
+ `console.log("MESSAGE-VOID:", (await messageAgent({ id: "1", message: "STEER" })) === undefined)`,
660
+ ),
661
+ ),
662
+ )
663
+ }
664
+ childRelease.openUnsafe()
665
+ return Stream.fromIterable(text("steered"))
666
+ },
667
+ })
668
+
669
+ assert.deepStrictEqual(exit, Exit.succeed("steered"))
670
+ const root = calls.filter((call) => call.role === "root")
671
+ assert.include(lastToolResult(root[2]!.prompt), "MESSAGE-VOID: true")
672
+ const steered = calls.find(
673
+ (call) => call.role === "child" && call.index === 1,
674
+ )
675
+ assert.isDefined(steered, "the running child received the message")
676
+ assert.include(JSON.stringify(steered!.prompt), "STEER")
677
+ }))
678
+
633
679
  test("messageAgent resumes a finished child on top of its history", () =>
634
680
  Effect.gen(function* () {
635
681
  let messageCall: number | undefined
@@ -666,7 +712,7 @@ console.log(JSON.stringify(result))`,
666
712
  toolCall(
667
713
  "message",
668
714
  `const result = await messageAgent({ id: "1", message: "FOLLOW-UP" })
669
- console.log(JSON.stringify(result))`,
715
+ console.log("MESSAGE-VOID:", result === undefined)`,
670
716
  ),
671
717
  )
672
718
  }
@@ -678,12 +724,7 @@ console.log(JSON.stringify(result))`,
678
724
  assert.isDefined(messageCall, "the first answer was pushed")
679
725
  const root = calls.filter((call) => call.role === "root")
680
726
  const messaged = lastToolResult(root[messageCall! + 1]!.prompt)
681
- assert.include(messaged, '"id":"1"')
682
- assert.include(
683
- messaged,
684
- '"status":"running"',
685
- "messageAgent returns without waiting for the new turn",
686
- )
727
+ assert.include(messaged, "MESSAGE-VOID: true")
687
728
 
688
729
  assert.isDefined(resumedPrompt, "the finished child was resumed")
689
730
  const resumed = messageJsons(resumedPrompt!)
@@ -727,7 +768,7 @@ console.log(JSON.stringify(result))`,
727
768
  return Stream.make(
728
769
  toolCall(
729
770
  "foreground",
730
- `const result = await delegate({ prompt: "TASK-CHILD" })
771
+ `const result = await subagent({ prompt: "TASK-CHILD" })
731
772
  console.log(JSON.stringify(result))`,
732
773
  ),
733
774
  )
@@ -793,8 +834,8 @@ await taskComplete("${name.toUpperCase()}:" + pwd.output.trim())`,
793
834
  "spawn",
794
835
  `await bash({ command: "mkdir -p a/one a/two" })
795
836
  await changeDirectory("a")
796
- const one = await delegate({ prompt: "TASK-CHILD-ONE", background: true })
797
- const two = await delegate({ prompt: "TASK-CHILD-TWO", background: true })
837
+ const one = await subagent({ prompt: "TASK-CHILD-ONE", background: true })
838
+ const two = await subagent({ prompt: "TASK-CHILD-TWO", background: true })
798
839
  console.log(JSON.stringify(await waitTasks({ ids: [one.id, two.id] })))
799
840
  console.log("ROOT:" + (await bash({ command: "pwd" })).output.trim())`,
800
841
  ),
@@ -827,7 +868,7 @@ console.log("ROOT:" + (await bash({ command: "pwd" })).output.trim())`,
827
868
  toolCall(
828
869
  "mixed",
829
870
  `const bashTask = await bash({ command: "echo BASH-OUT", background: true })
830
- const agentTask = await delegate({ prompt: "TASK-CHILD", background: true })
871
+ const agentTask = await subagent({ prompt: "TASK-CHILD", background: true })
831
872
  const ended = await waitTasks({ ids: [bashTask.id, agentTask.id] })
832
873
  console.log(JSON.stringify(ended.map(({ kind, status, output }) => ({ kind, status, output: output.trim() }))))`,
833
874
  ),
@@ -890,7 +931,7 @@ await taskComplete(JSON.stringify({ seen, attempts }))`,
890
931
  toolCall(
891
932
  "spawn",
892
933
  `const server = await bash({ command: "sleep 30", background: true })
893
- const child = await delegate({ prompt: "TASK-CHILD BASH-ID:" + server.id })
934
+ const child = await subagent({ prompt: "TASK-CHILD BASH-ID:" + server.id })
894
935
  console.log("CHILD:" + child.output)
895
936
  const mine = await listTasks()
896
937
  console.log("ROOT:" + JSON.stringify(mine.map((task) => task.kind + ":" + task.status).sort()))`,
@@ -947,7 +988,7 @@ console.log("ROOT:" + JSON.stringify(mine.map((task) => task.kind + ":" + task.s
947
988
  return Stream.make(
948
989
  toolCall(
949
990
  "wait",
950
- `const child = await delegate({ prompt: "TASK-CHILD", background: true })
991
+ `const child = await subagent({ prompt: "TASK-CHILD", background: true })
951
992
  const [task] = await waitTasks({ ids: [child.id], timeoutMs: 200 })
952
993
  console.log("WAITED:" + task.status)`,
953
994
  ),
@@ -994,7 +1035,7 @@ console.log("WAITED:" + task.status)`,
994
1035
  toolCall(
995
1036
  "wait",
996
1037
  `const quick = await bash({ command: "echo BASH-OUT", background: true })
997
- const child = await delegate({ prompt: "TASK-CHILD", background: true })
1038
+ const child = await subagent({ prompt: "TASK-CHILD", background: true })
998
1039
  const slow = await bash({ command: "sleep 30", background: true })
999
1040
  await waitTasks({ ids: [quick.id, child.id, slow.id] })
1000
1041
  console.log("RETURNED")`,
@@ -1077,8 +1118,8 @@ describe("agent tasks (rpc executor, slow callbacks)", () => {
1077
1118
  return Stream.make(
1078
1119
  toolCall(
1079
1120
  "wait",
1080
- `const a = await delegate({ prompt: "TASK-CHILD-A", background: true })
1081
- const b = await delegate({ prompt: "TASK-CHILD-B", background: true })
1121
+ `const a = await subagent({ prompt: "TASK-CHILD-A", background: true })
1122
+ const b = await subagent({ prompt: "TASK-CHILD-B", background: true })
1082
1123
  const ended = await waitTasks({ ids: [a.id, b.id] })
1083
1124
  console.log(ended.map((task) => task.output).join(" "))`,
1084
1125
  ),
package/src/AgentTools.ts CHANGED
@@ -59,7 +59,7 @@ export class TaskCompleter extends Context.Service<
59
59
 
60
60
  /**
61
61
  * What a task is: a background `bash` command or a sub-agent started with
62
- * `delegate`.
62
+ * `subagent`.
63
63
  *
64
64
  * @since 1.0.0
65
65
  * @category Models
@@ -130,7 +130,7 @@ export interface AgentTasks {
130
130
  * it resolves once the agent has finished, and dies if the agent failed.
131
131
  * In the background it resolves straight away with `status: "running"`.
132
132
  */
133
- readonly delegate: (options: {
133
+ readonly subagent: (options: {
134
134
  readonly id: string
135
135
  readonly prompt: string
136
136
  readonly background: boolean
@@ -161,7 +161,7 @@ export interface AgentTasks {
161
161
  /**
162
162
  * Interrupt an agent and everything it spawned.
163
163
  */
164
- readonly stopTask: (id: string) => Effect.Effect<Task, string>
164
+ readonly stopTask: (id: string) => Effect.Effect<void, string>
165
165
  /**
166
166
  * The agents this agent started.
167
167
  */
@@ -184,7 +184,7 @@ export class AgentTaskExecutor extends Context.Service<
184
184
  * @category Context
185
185
  */
186
186
  export const agentTasksUnavailable: AgentTasks = {
187
- delegate: () => Effect.die(new Error("Sub-agents are not available here")),
187
+ subagent: () => Effect.die(new Error("Sub-agents are not available here")),
188
188
  taskOutput: () => Effect.fail("Sub-agents are not available here"),
189
189
  waitTasks: () => Effect.fail("Sub-agents are not available here"),
190
190
  messageAgent: () => Effect.fail("Sub-agents are not available here"),
@@ -387,7 +387,7 @@ export const AgentTools = Toolkit.make(
387
387
  success: Schema.String,
388
388
  dependencies: [CurrentDirectory],
389
389
  }),
390
- Tool.make("delegate", {
390
+ Tool.make("subagent", {
391
391
  description:
392
392
  "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.",
393
393
  parameters: Schema.Struct({
@@ -454,7 +454,6 @@ export const AgentTools = Toolkit.make(
454
454
  parameters: Schema.String.annotate({
455
455
  identifier: "id",
456
456
  }),
457
- success: Task,
458
457
  failure: Schema.String,
459
458
  dependencies: [AgentTaskExecutor],
460
459
  }),
@@ -979,7 +978,7 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
979
978
  return yield* agentTasks.stopTask(id)
980
979
  }
981
980
  yield* Fiber.interrupt(entry.command.fiber)
982
- return reportBash(entry)
981
+ entry.command.reported = true
983
982
  }),
984
983
  listTasks: Effect.fn("AgentTools.listTasks")(function* () {
985
984
  yield* Effect.logInfo(`Calling "listTasks"`)
@@ -1175,14 +1174,14 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
1175
1174
 
1176
1175
  return `Success. Updated the following files:\n${out.join("\n")}`
1177
1176
  }, Effect.orDie),
1178
- delegate: Effect.fn("AgentTools.delegate")(function* (options: unknown) {
1179
- const { prompt, background = false } = yield* decodeDelegate(options)
1180
- yield* Effect.logInfo(`Calling "delegate"`).pipe(
1177
+ subagent: Effect.fn("AgentTools.subagent")(function* (options: unknown) {
1178
+ const { prompt, background = false } = yield* decodeSubagent(options)
1179
+ yield* Effect.logInfo(`Calling "subagent"`).pipe(
1181
1180
  Effect.annotateLogs({ background }),
1182
1181
  )
1183
1182
  const id = yield* registerAgentTask()
1184
1183
  const agentTasks = yield* AgentTaskExecutor
1185
- return yield* agentTasks.delegate({ id, prompt, background })
1184
+ return yield* agentTasks.subagent({ id, prompt, background })
1186
1185
  }),
1187
1186
  messageAgent: Effect.fn("AgentTools.messageAgent")(function* (
1188
1187
  input: unknown,
@@ -1251,9 +1250,9 @@ const decodeParams = <S extends Schema.Decoder<unknown>>(
1251
1250
  return (input: unknown) => Effect.mapError(decode(input), () => usage)
1252
1251
  }
1253
1252
 
1254
- const decodeDelegate = decodeParams(
1255
- AgentTools.tools.delegate.parametersSchema,
1256
- 'delegate requires an options object, for example: delegate({ prompt: "..." }) or delegate({ prompt: "...", background: true }).',
1253
+ const decodeSubagent = decodeParams(
1254
+ AgentTools.tools.subagent.parametersSchema,
1255
+ 'subagent requires an options object, for example: subagent({ prompt: "..." }) or subagent({ prompt: "...", background: true }).',
1257
1256
  )
1258
1257
  const decodeMessageAgent = decodeParams(
1259
1258
  AgentTools.tools.messageAgent.parametersSchema,
@@ -853,7 +853,7 @@ await taskComplete(JSON.stringify({ crashed, after: await attempt(mcp.fake.echo(
853
853
  return "await taskComplete(await mcp.fake.ping({}))"
854
854
  }
855
855
  return call.index === 0
856
- ? `const child = await delegate({ prompt: "TASK-CHILD" })
856
+ ? `const child = await subagent({ prompt: "TASK-CHILD" })
857
857
  console.log(JSON.stringify(child))
858
858
  console.log(await mcp.fake.screenshot({}))`
859
859
  : 'await taskComplete("done")'