clanka 0.19.1 → 0.21.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.
Files changed (46) hide show
  1. package/dist/Acp.d.ts.map +1 -1
  2. package/dist/Acp.js +14 -0
  3. package/dist/Acp.js.map +1 -1
  4. package/dist/Acp.test.js +78 -1
  5. package/dist/Acp.test.js.map +1 -1
  6. package/dist/Agent.d.ts.map +1 -1
  7. package/dist/Agent.js +64 -3
  8. package/dist/Agent.js.map +1 -1
  9. package/dist/AgentBashJobs.test.d.ts +2 -0
  10. package/dist/AgentBashJobs.test.d.ts.map +1 -0
  11. package/dist/AgentBashJobs.test.js +177 -0
  12. package/dist/AgentBashJobs.test.js.map +1 -0
  13. package/dist/AgentExecutor.d.ts +35 -2
  14. package/dist/AgentExecutor.d.ts.map +1 -1
  15. package/dist/AgentExecutor.js +74 -3
  16. package/dist/AgentExecutor.js.map +1 -1
  17. package/dist/AgentExecutor.test.js +87 -11
  18. package/dist/AgentExecutor.test.js.map +1 -1
  19. package/dist/AgentOutput.d.ts +19 -4
  20. package/dist/AgentOutput.d.ts.map +1 -1
  21. package/dist/AgentOutput.js +15 -0
  22. package/dist/AgentOutput.js.map +1 -1
  23. package/dist/AgentSubagents.test.js +2 -2
  24. package/dist/AgentSubagents.test.js.map +1 -1
  25. package/dist/AgentTools.d.ts +119 -7
  26. package/dist/AgentTools.d.ts.map +1 -1
  27. package/dist/AgentTools.js +106 -39
  28. package/dist/AgentTools.js.map +1 -1
  29. package/dist/OutputFormatter.d.ts.map +1 -1
  30. package/dist/OutputFormatter.js +6 -0
  31. package/dist/OutputFormatter.js.map +1 -1
  32. package/dist/bin/{OutputFormatter-Dqxyk2qD.mjs → OutputFormatter-U02YKTfy.mjs} +5 -1
  33. package/dist/bin/{OutputFormatter-Dqxyk2qD.mjs.map → OutputFormatter-U02YKTfy.mjs.map} +1 -1
  34. package/dist/bin/cli.mjs +187 -44
  35. package/dist/bin/cli.mjs.map +1 -1
  36. package/package.json +1 -1
  37. package/src/Acp.test.ts +111 -1
  38. package/src/Acp.ts +15 -0
  39. package/src/Agent.ts +100 -1
  40. package/src/AgentBashJobs.test.ts +299 -0
  41. package/src/AgentExecutor.test.ts +127 -11
  42. package/src/AgentExecutor.ts +87 -0
  43. package/src/AgentOutput.ts +19 -0
  44. package/src/AgentSubagents.test.ts +2 -2
  45. package/src/AgentTools.ts +153 -48
  46. package/src/OutputFormatter.ts +7 -0
@@ -566,9 +566,11 @@ const result = await bash({
566
566
  command: ${JSON.stringify(gatedCommand(environment.cwd))},
567
567
  background: true,
568
568
  })
569
- console.log("RETURNED:", result)`)
570
- assert.include(output, "RETURNED:")
571
- assert.match(output, /background/i)
569
+ console.log("RETURNED:", JSON.stringify(result))`)
570
+ assert.include(
571
+ output,
572
+ 'RETURNED: {"id":"1","status":"running","output":""}',
573
+ )
572
574
  assert.strictEqual(
573
575
  yield* waitForLog(environment.cwd, started),
574
576
  "start\n",
@@ -589,16 +591,18 @@ console.log("RETURNED:", result)`)
589
591
  const output = yield* runScript(`
590
592
  try {
591
593
  const result = await bash({
592
- command: ${JSON.stringify(gatedCommand(environment.cwd))},
594
+ command: ${JSON.stringify(`echo early && ${gatedCommand(environment.cwd)}`)},
593
595
  timeoutMs: 60000,
594
596
  })
595
- console.log("RETURNED:", result)
597
+ console.log("RETURNED:", JSON.stringify(result))
596
598
  } catch (error) {
597
599
  console.log("REJECTED:", String(error))
598
600
  }`)
599
- assert.include(output, "RETURNED:")
601
+ assert.include(
602
+ output,
603
+ 'RETURNED: {"id":"1","status":"running","output":"early\\n"}',
604
+ )
600
605
  assert.notInclude(output, "REJECTED:")
601
- assert.match(output, /background/i)
602
606
  assert.strictEqual(
603
607
  yield* waitForLog(environment.cwd, started),
604
608
  "start\n",
@@ -615,6 +619,118 @@ try {
615
619
  ),
616
620
  )
617
621
 
622
+ // A foreground command that succeeds returns a task with an id from the
623
+ // same counter as background jobs; one that fails still rejects.
624
+ it.live(
625
+ "returns a task from a foreground bash command, or rejects on failure",
626
+ () =>
627
+ Effect.gen(function* () {
628
+ const output = yield* runScript(`
629
+ try {
630
+ console.log("OK:", JSON.stringify(await bash({ command: "echo hi" })))
631
+ console.log("RETURNED:", JSON.stringify(await bash({ command: "echo out && exit 3" })))
632
+ } catch (error) {
633
+ console.log("REJECTED:", String(error))
634
+ }`)
635
+ assert.include(
636
+ output,
637
+ 'OK: {"id":"1","status":"completed","exitCode":0,"output":"hi\\n"}',
638
+ )
639
+ assert.match(
640
+ output,
641
+ /REJECTED:.*Command failed with exit code 3: out/,
642
+ )
643
+ assert.notInclude(output, "RETURNED:")
644
+ }).pipe(Effect.timeout("5 seconds"), Effect.provide(executorLayer({}))),
645
+ )
646
+
647
+ it.live("waits for a background task with waitJob", () =>
648
+ Effect.gen(function* () {
649
+ const executor = yield* AgentExecutor.AgentExecutor
650
+ const { environment } = yield* executor.capabilities
651
+ const output = yield* runScript(`
652
+ const task = await bash({
653
+ command: ${JSON.stringify(`${gatedCommand(environment.cwd)} && echo done`)},
654
+ background: true,
655
+ })
656
+ await writeFile({ path: "gate", content: "" })
657
+ console.log("WAITED:", JSON.stringify(await waitJob({ id: task.id })))`)
658
+ assert.include(
659
+ output,
660
+ 'WAITED: {"id":"1","status":"completed","exitCode":0,"output":"done\\n"}',
661
+ )
662
+ }).pipe(Effect.timeout("5 seconds"), Effect.provide(executorLayer({}))),
663
+ )
664
+
665
+ // Without `timeoutMs` the wait uses the caller's command timeout, which
666
+ // also caps it. The test timeout catches a wait that never ends.
667
+ it.live("stops waiting at the timeout and leaves the task running", () =>
668
+ Effect.gen(function* () {
669
+ const executor = yield* AgentExecutor.AgentExecutor
670
+ const { environment } = yield* executor.capabilities
671
+ const output = yield* runScript(`
672
+ const task = await bash({
673
+ command: ${JSON.stringify(gatedCommand(environment.cwd))},
674
+ background: true,
675
+ })
676
+ const waits = [
677
+ await waitJob({ id: task.id, timeoutMs: 100 }),
678
+ await waitJob({ id: task.id }),
679
+ await waitJob({ id: task.id, timeoutMs: 60000 }),
680
+ ]
681
+ console.log("WAITS:", JSON.stringify(waits.map((job) => job.status)))`)
682
+ assert.include(output, 'WAITS: ["running","running","running"]')
683
+ assert.strictEqual(
684
+ yield* waitForLog(environment.cwd, started),
685
+ "start\n",
686
+ "still running after the waits",
687
+ )
688
+ openGate(environment.cwd)
689
+ assert.strictEqual(
690
+ yield* waitForLog(environment.cwd, finished),
691
+ "start\nfinish\n",
692
+ )
693
+ }).pipe(
694
+ Effect.timeout("5 seconds"),
695
+ Effect.provide(executorLayer({ commandTimeout: "300 millis" })),
696
+ ),
697
+ )
698
+
699
+ // The watcher returns only after the job has ended, so the job always
700
+ // finishes before `bash` returns. `bash` must return the snapshot it
701
+ // handed over, leaving the final state to the watcher alone. Over RPC the
702
+ // server's watcher does not wait for the client's, so only local mode
703
+ // forces the ordering.
704
+ it.live("returns the task it hands to the job watcher", () =>
705
+ Effect.gen(function* () {
706
+ const executor = yield* AgentExecutor.AgentExecutor
707
+ const { environment } = yield* executor.capabilities
708
+ const watched: Array<string> = []
709
+ const claims: Array<boolean> = []
710
+ const output = yield* executor
711
+ .execute({
712
+ environment,
713
+ onEnvironment: () => Effect.void,
714
+ script: `
715
+ await bash({ command: "true" })
716
+ console.log("RETURNED:", JSON.stringify(await bash({ command: "true", background: true })))`,
717
+ onTaskComplete: () => Effect.void,
718
+ subagents: subagentsUnavailable,
719
+ onImage: () => Effect.void,
720
+ onJob: (job) =>
721
+ Effect.gen(function* () {
722
+ watched.push(job.id)
723
+ yield* job.await
724
+ claims.push(yield* job.claim)
725
+ }),
726
+ })
727
+ .pipe(Stream.mkString)
728
+ assert.include(output, 'RETURNED: {"id":"2","status":"running"')
729
+ assert.deepStrictEqual(watched, ["2"], "only the running task")
730
+ assert.deepStrictEqual(claims, [true], "reported once, by the watcher")
731
+ }).pipe(Effect.timeout("5 seconds"), Effect.provide(executorLayer({}))),
732
+ )
733
+
618
734
  it.live("reports background jobs through jobOutput", () =>
619
735
  Effect.gen(function* () {
620
736
  const executor = yield* AgentExecutor.AgentExecutor
@@ -859,10 +975,10 @@ sleep(100).then(() => console.constructor.constructor("return process")().exit(7
859
975
  tool: "bash",
860
976
  params: { command: "seq 1 1000000" },
861
977
  })
862
- assert(typeof output === "string")
863
- assert.isBelow(output.length, 10_000 + 500)
864
- assert.isTrue(output.startsWith("1\n2\n3\n"), "start kept")
865
- assert.isTrue(output.trimEnd().endsWith("999999\n1000000"), "end kept")
978
+ const { output: text } = output as { readonly output: string }
979
+ assert.isBelow(text.length, 10_000 + 500)
980
+ assert.isTrue(text.startsWith("1\n2\n3\n"), "start kept")
981
+ assert.isTrue(text.trimEnd().endsWith("999999\n1000000"), "end kept")
866
982
  }).pipe(
867
983
  Effect.timeout("10 seconds"),
868
984
  Effect.provide(executorLayer({ commandOutputChars: 10_000 })),
@@ -9,6 +9,8 @@ import { Worker } from "node:worker_threads"
9
9
  import type * as NodeWorkerThreads from "node:worker_threads"
10
10
  import {
11
11
  AgentToolHandlers,
12
+ type BackgroundJob,
13
+ BashJob,
12
14
  type DelegateResult,
13
15
  type SubagentInfo,
14
16
  type SubagentResult,
@@ -21,6 +23,7 @@ import {
21
23
  type ExcludableTool,
22
24
  ImageAttacher,
23
25
  type ImageAttachment,
26
+ JobWatcher,
24
27
  makeBashTool,
25
28
  SubagentExecutor,
26
29
  type Subagents,
@@ -136,6 +139,12 @@ export interface ExecuteOptions {
136
139
  * Receives every image `readFile` attached while the script ran.
137
140
  */
138
141
  readonly onImage: (image: ImageAttachment) => Effect.Effect<void>
142
+ /**
143
+ * Receives every background `bash` job the script starts, including a
144
+ * command moved to the background at its timeout. The job can outlive the
145
+ * script, so `await` and `claim` stay usable after it ends.
146
+ */
147
+ readonly onJob?: ((job: BackgroundJob) => Effect.Effect<void>) | undefined
139
148
  /**
140
149
  * Functions added to the script sandbox whose handlers run on the loop
141
150
  * side, next to the Agent.
@@ -240,6 +249,16 @@ export class Capabilities extends Schema.Class<Capabilities>("Capabilities")({
240
249
  Schema.withDecodingDefaultKey(Effect.succeed([])),
241
250
  Schema.withConstructorDefault(Effect.succeed([])),
242
251
  ),
252
+ /**
253
+ * Whether the executor hands background `bash` jobs to
254
+ * `ExecuteOptions.onJob`, so the agent can push their results. Executors
255
+ * and executor servers from before job pushes leave it out, and then the
256
+ * model is told to poll with `jobOutput`.
257
+ */
258
+ jobPushes: Schema.Boolean.pipe(
259
+ Schema.withDecodingDefaultKey(Effect.succeed(false)),
260
+ Schema.withConstructorDefault(Effect.succeed(false)),
261
+ ),
243
262
  }) {}
244
263
 
245
264
  /**
@@ -500,6 +519,7 @@ const makeLocalWith = Effect.fnUntraced(function* <
500
519
  ),
501
520
  }),
502
521
  Context.add(ImageAttacher, opts.onImage),
522
+ Context.add(JobWatcher, opts.onJob ?? (() => Effect.void)),
503
523
  Context.add(CommandLimits, commandLimits),
504
524
  Context.add(Console.Console, console),
505
525
  Context.add(References.CurrentLogAnnotations, {}),
@@ -661,6 +681,7 @@ const makeLocalWith = Effect.fnUntraced(function* <
661
681
  }),
662
682
  tools: Object.keys(tools.tools),
663
683
  skills,
684
+ jobPushes: true,
664
685
  })
665
686
  }),
666
687
  execute: (opts) => execute(opts),
@@ -729,6 +750,7 @@ export const makeRpc = Effect.gen(function* () {
729
750
  script: opts.script,
730
751
  environment: opts.environment,
731
752
  loopTools: Object.keys(opts.loopTools ?? {}),
753
+ ...(opts.onJob === undefined ? {} : { watchJobs: true }),
732
754
  })
733
755
  .pipe(
734
756
  Stream.tap((part) => {
@@ -761,6 +783,15 @@ export const makeRpc = Effect.gen(function* () {
761
783
  latest = part.environment
762
784
  return Effect.void
763
785
  }
786
+ case "Job": {
787
+ if (opts.onJob === undefined) return Effect.void
788
+ const id = part.id
789
+ return opts.onJob({
790
+ id,
791
+ await: Effect.orDie(client.awaitJob({ id })),
792
+ claim: Effect.orDie(client.claimJob({ id })),
793
+ })
794
+ }
764
795
  }
765
796
  }),
766
797
  Stream.orDie,
@@ -871,11 +902,25 @@ export const layerRpcServer = <Toolkit extends Toolkit.Any = never>(
871
902
  (effect: Effect.Effect<unknown, string>) => void
872
903
  >()
873
904
  let requestId = 0
905
+ // Background jobs started by any script, for `awaitJob` and
906
+ // `claimJob`.
907
+ const jobs = new Map<string, BackgroundJob>()
908
+ const findJob = (id: string) =>
909
+ Effect.suspend(() => {
910
+ const job = jobs.get(id)
911
+ return job === undefined
912
+ ? Effect.fail(`No background job with id "${id}"`)
913
+ : Effect.succeed(job)
914
+ })
874
915
 
875
916
  return Rpcs.of({
876
917
  capabilities: () => local.executor.capabilities,
877
918
  renderEnvironment: ({ environment, reset }) =>
878
919
  local.renderEnvironment(environment, { reset }),
920
+ awaitJob: ({ id }) =>
921
+ Effect.flatMap(findJob(id), (job) => job.await),
922
+ claimJob: ({ id }) =>
923
+ Effect.flatMap(findJob(id), (job) => job.claim),
879
924
  respond: ({ id, response }) => {
880
925
  const resume = requestResumes.get(id)
881
926
  if (resume) {
@@ -892,6 +937,7 @@ export const layerRpcServer = <Toolkit extends Toolkit.Any = never>(
892
937
  script,
893
938
  environment,
894
939
  loopTools,
940
+ watchJobs,
895
941
  }) {
896
942
  const queue = yield* Queue.unbounded<
897
943
  typeof ExecuteOutput.Type,
@@ -956,6 +1002,18 @@ export const layerRpcServer = <Toolkit extends Toolkit.Any = never>(
956
1002
  data: image.data,
957
1003
  })
958
1004
  },
1005
+ // Older clients cannot decode a `Job` part.
1006
+ ...(watchJobs === true
1007
+ ? {
1008
+ onJob: (job: BackgroundJob) => {
1009
+ jobs.set(job.id, job)
1010
+ return Queue.offer(queue, {
1011
+ _tag: "Job",
1012
+ id: job.id,
1013
+ })
1014
+ },
1015
+ }
1016
+ : {}),
959
1017
  loopTools: Object.fromEntries(
960
1018
  loopTools.map((name) => [
961
1019
  name,
@@ -1067,6 +1125,12 @@ export const ExecuteOutput = Schema.TaggedUnion({
1067
1125
  * `EnvironmentChanged` requests.
1068
1126
  */
1069
1127
  Environment: { environment: ExecutionEnvironment },
1128
+ /**
1129
+ * The script started a background `bash` job. Only sent when the client
1130
+ * asked with `watchJobs`. The client follows it with `awaitJob` and
1131
+ * `claimJob`.
1132
+ */
1133
+ Job: { id: Schema.String },
1070
1134
  })
1071
1135
 
1072
1136
  /**
@@ -1093,10 +1157,32 @@ export class Rpcs extends RpcGroup.make(
1093
1157
  loopTools: Schema.Array(Schema.String).pipe(
1094
1158
  Schema.withDecodingDefaultKey(Effect.succeed([])),
1095
1159
  ),
1160
+ /**
1161
+ * Send a `Job` part for each background job the script starts. Older
1162
+ * clients leave it out, as they cannot decode those parts.
1163
+ */
1164
+ watchJobs: Schema.optionalKey(Schema.Boolean),
1096
1165
  }),
1097
1166
  success: ExecuteOutput,
1098
1167
  stream: true,
1099
1168
  }),
1169
+ /**
1170
+ * Waits for a background job to end and returns its final state.
1171
+ */
1172
+ Rpc.make("awaitJob", {
1173
+ payload: { id: Schema.String },
1174
+ success: BashJob,
1175
+ error: Schema.String,
1176
+ }),
1177
+ /**
1178
+ * Marks a background job's final state as reported. Returns `false` when
1179
+ * it already was.
1180
+ */
1181
+ Rpc.make("claimJob", {
1182
+ payload: { id: Schema.String },
1183
+ success: Schema.Boolean,
1184
+ error: Schema.String,
1185
+ }),
1100
1186
  Rpc.make("renderEnvironment", {
1101
1187
  payload: { environment: ExecutionEnvironment, reset: Schema.Boolean },
1102
1188
  success: EnvironmentUpdate,
@@ -1275,6 +1361,7 @@ const excludedToolNames = (
1275
1361
  }
1276
1362
  if (names.has("bash")) {
1277
1363
  names.add("jobOutput")
1364
+ names.add("waitJob")
1278
1365
  names.add("stopJob")
1279
1366
  }
1280
1367
  return names
@@ -250,6 +250,23 @@ export class EnvironmentUpdated extends Schema.TaggedClass<EnvironmentUpdated>()
250
250
  },
251
251
  ) {}
252
252
 
253
+ /**
254
+ * Emitted when a background `bash` job the agent started ends, whether or not
255
+ * the model is told about it.
256
+ *
257
+ * @since 1.0.0
258
+ * @category Output
259
+ */
260
+ export class JobComplete extends Schema.TaggedClass<JobComplete>()(
261
+ "JobComplete",
262
+ {
263
+ id: Schema.String,
264
+ status: Schema.Literals(["completed", "failed", "stopped"]),
265
+ exitCode: Schema.optional(Schema.Number),
266
+ output: Schema.String,
267
+ },
268
+ ) {}
269
+
253
270
  export type ContentPart =
254
271
  | ReasoningStart
255
272
  | ReasoningDelta
@@ -265,6 +282,7 @@ export type ContentPart =
265
282
  | CompactionEnded
266
283
  | SessionRestarted
267
284
  | EnvironmentUpdated
285
+ | JobComplete
268
286
 
269
287
  export const ContentPart = Schema.Union([
270
288
  ReasoningStart,
@@ -281,6 +299,7 @@ export const ContentPart = Schema.Union([
281
299
  CompactionEnded,
282
300
  SessionRestarted,
283
301
  EnvironmentUpdated,
302
+ JobComplete,
284
303
  ])
285
304
 
286
305
  /**
@@ -798,7 +798,7 @@ console.log(JSON.stringify(result))`,
798
798
  toolCall(
799
799
  `pwd-${name}`,
800
800
  `const pwd = await bash({ command: "pwd" })
801
- await taskComplete("${name.toUpperCase()}:" + pwd.trim())`,
801
+ await taskComplete("${name.toUpperCase()}:" + pwd.output.trim())`,
802
802
  ),
803
803
  ),
804
804
  ),
@@ -814,7 +814,7 @@ await changeDirectory("a")
814
814
  await delegate({ prompt: "TASK-CHILD-ONE", background: true })
815
815
  await delegate({ prompt: "TASK-CHILD-TWO", background: true })
816
816
  console.log(JSON.stringify(await waitAgents()))
817
- console.log("ROOT:" + (await bash({ command: "pwd" })).trim())`,
817
+ console.log("ROOT:" + (await bash({ command: "pwd" })).output.trim())`,
818
818
  ),
819
819
  )
820
820
  case 1: