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
package/src/AgentTools.ts CHANGED
@@ -221,8 +221,10 @@ export const BashJobStatus = Schema.Literals([
221
221
  export type BashJobStatus = typeof BashJobStatus.Type
222
222
 
223
223
  /**
224
- * A `bash` command running in the background, as returned by `jobOutput`
225
- * and `stopJob`.
224
+ * A `bash` command and its state: the task that `bash`, `jobOutput`,
225
+ * `waitJob` and `stopJob` return. `exitCode` is set once the command has
226
+ * exited; a non-zero exit is `failed`. A foreground `bash` command that
227
+ * fails rejects instead of returning a task.
226
228
  *
227
229
  * @since 1.0.0
228
230
  * @category Models
@@ -240,6 +242,39 @@ export const BashJob = Schema.Struct({
240
242
  */
241
243
  export type BashJob = typeof BashJob.Type
242
244
 
245
+ /**
246
+ * A background `bash` job, handed to the `JobWatcher` when it starts.
247
+ *
248
+ * @since 1.0.0
249
+ * @category Models
250
+ */
251
+ export interface BackgroundJob {
252
+ readonly id: string
253
+ /** Waits for the job to end and succeeds with its final state. */
254
+ readonly await: Effect.Effect<BashJob>
255
+ /**
256
+ * Marks the job's final state as reported. Succeeds with `false` when it
257
+ * already was: by `stopJob`, by a `jobOutput` call that returned it, or by
258
+ * an earlier `claim`.
259
+ */
260
+ readonly claim: Effect.Effect<boolean>
261
+ }
262
+
263
+ /**
264
+ * Receives every background `bash` job as it starts: those started with
265
+ * `background: true` and those moved to the background at their timeout. A
266
+ * command that `bash` returns finished is never handed over.
267
+ * The executor sets it from `ExecuteOptions.onJob`.
268
+ *
269
+ * @since 1.0.0
270
+ * @category Context
271
+ */
272
+ export class JobWatcher extends Context.Reference<
273
+ (job: BackgroundJob) => Effect.Effect<void>
274
+ >("clanka/AgentTools/JobWatcher", {
275
+ defaultValue: () => () => Effect.void,
276
+ }) {}
277
+
243
278
  /**
244
279
  * The `bash` timeout when the caller sets none.
245
280
  *
@@ -287,7 +322,7 @@ export class CommandLimits extends Context.Reference<{
287
322
  export const makeBashTool = (timeout: Duration.Duration) =>
288
323
  Tool.make("bash", {
289
324
  description:
290
- 'Run a bash command and return the output. With `background: true` it returns straight away with a job id while the command keeps running. A command still running at its timeout is not stopped: it is moved to the background, and the output so far is returned with its job id. Read a job with "jobOutput" and stop it with "stopJob".',
325
+ 'Run a bash command and return a task with its job id, status, exit code and output. A command that fails before it is returned rejects with its exit code and output. With `background: true` it returns straight away with status "running" while the command keeps going. A command still running at its timeout is not stopped: it is moved to the background and returned as "running" with the output so far. Wait for a job with "waitJob", read it with "jobOutput" and stop it with "stopJob"; a background job that fails is reported with status "failed" and its exitCode.',
291
326
  parameters: Schema.Struct({
292
327
  command: Schema.String,
293
328
  timeoutMs: Schema.optional(Schema.Finite).annotate({
@@ -295,12 +330,12 @@ export const makeBashTool = (timeout: Duration.Duration) =>
295
330
  }),
296
331
  background: Schema.optional(Schema.Boolean).annotate({
297
332
  documentation:
298
- "Start the command in the background and return its job id without waiting",
333
+ 'Start the command in the background and return it as "running" without waiting',
299
334
  }),
300
335
  }).annotate({
301
336
  identifier: "command",
302
337
  }),
303
- success: Schema.String,
338
+ success: BashJob,
304
339
  dependencies: [CurrentDirectory],
305
340
  })
306
341
 
@@ -436,13 +471,26 @@ export const AgentTools = Toolkit.make(
436
471
  makeBashTool(defaultBashTimeout),
437
472
  Tool.make("jobOutput", {
438
473
  description:
439
- 'Return the status and output so far of a background bash job.',
474
+ "Return the status and output so far of a background bash job.",
440
475
  parameters: Schema.String.annotate({
441
476
  identifier: "id",
442
477
  }),
443
478
  success: BashJob,
444
479
  failure: Schema.String,
445
480
  }),
481
+ Tool.make("waitJob", {
482
+ description:
483
+ 'Wait for a bash job to end and return its task. When the timeout passes first, the task is returned as "running" and the command keeps going.',
484
+ parameters: Schema.Struct({
485
+ id: Schema.String,
486
+ timeoutMs: Schema.optional(Schema.Finite).annotate({
487
+ documentation:
488
+ "How long to wait in ms (default and max: the bash timeout)",
489
+ }),
490
+ }),
491
+ success: BashJob,
492
+ failure: Schema.String,
493
+ }),
446
494
  Tool.make("stopJob", {
447
495
  description:
448
496
  "Stop a background bash job and return its final status and output.",
@@ -591,54 +639,58 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
591
639
  return { fiber, output: output.render }
592
640
  })
593
641
 
642
+ // Every `bash` command is a job, so it can be addressed by id. Only
643
+ // the ones still running when `bash` returns go to the `JobWatcher`.
594
644
  const jobs = new Map<string, RunningCommand>()
595
645
  let nextJobId = 1
596
- const addJob = (running: RunningCommand) => {
646
+ const addJob = (command: Omit<RunningCommand, "reported">) => {
597
647
  const id = String(nextJobId++)
648
+ const running: RunningCommand = { ...command, reported: false }
598
649
  jobs.set(id, running)
599
- return id
650
+ return { id, running }
600
651
  }
652
+ const watchJob = Effect.fnUntraced(function* (
653
+ id: string,
654
+ running: RunningCommand,
655
+ ) {
656
+ const watch = yield* JobWatcher
657
+ yield* watch({
658
+ id,
659
+ await: Fiber.await(running.fiber).pipe(
660
+ Effect.map(() => jobInfo(id, running)),
661
+ ),
662
+ claim: Effect.sync(() => {
663
+ if (running.reported) return false
664
+ running.reported = true
665
+ return true
666
+ }),
667
+ })
668
+ })
601
669
  const findJob = (id: string) => {
602
670
  const running = jobs.get(id)
603
671
  return running === undefined
604
672
  ? Effect.fail(`No background job with id "${id}"`)
605
673
  : Effect.succeed(running)
606
674
  }
607
-
608
- // A command still running at its timeout is stopped, or with
609
- // `background` handed over as a job. A caller that is interrupted first
610
- // stops it either way.
611
- const runCommand = Effect.fnUntraced(function* (
612
- command: ChildProcess.Command,
675
+ // The final state of a job the model has been given is not pushed.
676
+ const reportJob = (id: string, running: RunningCommand) => {
677
+ const job = jobInfo(id, running)
678
+ if (job.status !== "running") running.reported = true
679
+ return job
680
+ }
681
+ // Waits up to `timeout` for a command to exit. A caller that is
682
+ // interrupted first stops the command.
683
+ const awaitCommand = (
684
+ running: RunningCommand | Omit<RunningCommand, "reported">,
613
685
  timeout: Duration.Duration | undefined,
614
- onTimeout: "stop" | "background",
615
- ) {
616
- const running = yield* startCommand(command)
686
+ ) => {
617
687
  const awaited = Fiber.await(running.fiber)
618
- const exit = yield* (
688
+ return (
619
689
  timeout === undefined
620
690
  ? Effect.asSome(awaited)
621
691
  : Effect.timeoutOption(awaited, timeout)
622
692
  ).pipe(Effect.onInterrupt(() => Fiber.interrupt(running.fiber)))
623
- if (Option.isNone(exit)) {
624
- const timeoutMs = Duration.toMillis(timeout!)
625
- if (onTimeout === "stop") {
626
- yield* Fiber.interrupt(running.fiber)
627
- return yield* Effect.die(
628
- new Error(`Command timed out after ${timeoutMs}ms`),
629
- )
630
- }
631
- const id = addJob(running)
632
- const output = running.output()
633
- return `${output}${output === "" || output.endsWith("\n") ? "" : "\n"}[Still running after ${timeoutMs}ms, so it was moved to the background as job ${id}. ${jobUsage(id)}]`
634
- }
635
- const exitCode = yield* exit.value
636
- const output = running.output()
637
- if (exitCode === 0) return output
638
- return yield* Effect.die(
639
- new Error(`Command failed with exit code ${exitCode}: ${output}`),
640
- )
641
- })
693
+ }
642
694
 
643
695
  /**
644
696
  * Image branch of `readFile`: the bytes go to the `ImageAttacher` for
@@ -842,8 +894,7 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
842
894
  )
843
895
  }),
844
896
  bash: Effect.fn("AgentTools.bash")(function* (options) {
845
- const limits = yield* CommandLimits
846
- const maxMs = Duration.toMillis(limits.timeout ?? defaultBashTimeout)
897
+ const maxMs = bashTimeoutMs(yield* CommandLimits)
847
898
  const timeoutMs = Math.min(options.timeoutMs ?? maxMs, maxMs)
848
899
  yield* Effect.logInfo(`Calling "bash"`).pipe(
849
900
  Effect.annotateLogs({
@@ -856,18 +907,46 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
856
907
  cwd,
857
908
  stdin: "ignore",
858
909
  })
859
- if (options.background === true) {
860
- const id = addJob(yield* startCommand(cmd))
861
- return `Started background job ${id}. ${jobUsage(id)}`
910
+ const { id, running } = addJob(yield* startCommand(cmd))
911
+ if (options.background !== true) {
912
+ const exit = yield* awaitCommand(running, Duration.millis(timeoutMs))
913
+ if (Option.isSome(exit)) {
914
+ // A finished command is reported here, so it is never pushed.
915
+ const exitCode = yield* exit.value
916
+ const job = reportJob(id, running)
917
+ if (exitCode === 0) return job
918
+ return yield* Effect.die(
919
+ new Error(
920
+ `Command failed with exit code ${exitCode}: ${job.output}`,
921
+ ),
922
+ )
923
+ }
862
924
  }
863
- return yield* runCommand(cmd, Duration.millis(timeoutMs), "background")
925
+ // Snapshot the task before yielding to the watcher: the command can
926
+ // finish while it is being handed over, and its final state must
927
+ // reach the model only once. A finished task is never handed over.
928
+ const job = reportJob(id, running)
929
+ if (job.status === "running") yield* watchJob(id, running)
930
+ return job
864
931
  }, Effect.orDie),
865
932
  jobOutput: Effect.fn("AgentTools.jobOutput")(function* (input: unknown) {
866
933
  const id = yield* decodeJobOutput(input)
867
934
  yield* Effect.logInfo(`Calling "jobOutput"`).pipe(
868
935
  Effect.annotateLogs({ id }),
869
936
  )
870
- return jobInfo(id, yield* findJob(id))
937
+ return reportJob(id, yield* findJob(id))
938
+ }),
939
+ waitJob: Effect.fn("AgentTools.waitJob")(function* (input: unknown) {
940
+ const options = yield* decodeWaitJob(input)
941
+ const maxMs = bashTimeoutMs(yield* CommandLimits)
942
+ const timeoutMs = Math.min(options.timeoutMs ?? maxMs, maxMs)
943
+ yield* Effect.logInfo(`Calling "waitJob"`).pipe(
944
+ Effect.annotateLogs({ id: options.id, timeoutMs }),
945
+ )
946
+ const running = yield* findJob(options.id)
947
+ // Ending the wait leaves the job running.
948
+ yield* Effect.timeoutOption(Fiber.await(running.fiber), timeoutMs)
949
+ return reportJob(options.id, running)
871
950
  }),
872
951
  stopJob: Effect.fn("AgentTools.stopJob")(function* (input: unknown) {
873
952
  const id = yield* decodeStopJob(input)
@@ -876,6 +955,7 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
876
955
  )
877
956
  const running = yield* findJob(id)
878
957
  yield* Fiber.interrupt(running.fiber)
958
+ running.reported = true
879
959
  return jobInfo(id, running)
880
960
  }),
881
961
  gh: Effect.fn("AgentTools.gh")(function* (args) {
@@ -888,7 +968,22 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
888
968
  stdin: "ignore",
889
969
  })
890
970
  const { timeout } = yield* CommandLimits
891
- return yield* runCommand(cmd, timeout, "stop")
971
+ const running = yield* startCommand(cmd)
972
+ const exit = yield* awaitCommand(running, timeout)
973
+ if (Option.isNone(exit)) {
974
+ yield* Fiber.interrupt(running.fiber)
975
+ return yield* Effect.die(
976
+ new Error(
977
+ `Command timed out after ${Duration.toMillis(timeout!)}ms`,
978
+ ),
979
+ )
980
+ }
981
+ const exitCode = yield* exit.value
982
+ const output = running.output()
983
+ if (exitCode === 0) return output
984
+ return yield* Effect.die(
985
+ new Error(`Command failed with exit code ${exitCode}: ${output}`),
986
+ )
892
987
  }, Effect.orDie),
893
988
  webSearch: Effect.fn("AgentTools.webSearch")(function* (options) {
894
989
  yield* Effect.logInfo(`Calling "webSearch"`).pipe(
@@ -1157,6 +1252,14 @@ const decodeJobOutput = decodeParams(
1157
1252
  AgentTools.tools.jobOutput.parametersSchema,
1158
1253
  'jobOutput requires a job id, for example: jobOutput("1").',
1159
1254
  )
1255
+ /** The caller's `bash` timeout, which also bounds `waitJob`. */
1256
+ const bashTimeoutMs = (limits: typeof CommandLimits.Service) =>
1257
+ Duration.toMillis(limits.timeout ?? defaultBashTimeout)
1258
+
1259
+ const decodeWaitJob = decodeParams(
1260
+ AgentTools.tools.waitJob.parametersSchema,
1261
+ 'waitJob requires an options object, for example: waitJob({ id: "1" }) or waitJob({ id: "1", timeoutMs: 60000 }).',
1262
+ )
1160
1263
  const decodeStopJob = decodeParams(
1161
1264
  AgentTools.tools.stopJob.parametersSchema,
1162
1265
  'stopJob requires a job id, for example: stopJob("1").',
@@ -1168,11 +1271,13 @@ interface RunningCommand {
1168
1271
  PlatformError.PlatformError
1169
1272
  >
1170
1273
  readonly output: () => string
1274
+ /**
1275
+ * Whether the final state has been reported, so it is not pushed to the
1276
+ * model as well.
1277
+ */
1278
+ reported: boolean
1171
1279
  }
1172
1280
 
1173
- const jobUsage = (id: string) =>
1174
- `Use jobOutput("${id}") for its status and output, or stopJob("${id}") to stop it.`
1175
-
1176
1281
  const jobInfo = (id: string, running: RunningCommand): BashJob => {
1177
1282
  const exit = running.fiber.pollUnsafe()
1178
1283
  const output = running.output()
@@ -123,6 +123,13 @@ ${chalk.dim(output.summary)}\n\n`
123
123
  case "EnvironmentUpdated": {
124
124
  return `${prefix}${chalkInfoHeading(`${infoIcon} Environment update:`)}\n\n${chalk.dim(truncate(output.update))}\n\n`
125
125
  }
126
+ case "JobComplete": {
127
+ const exitCode =
128
+ output.exitCode === undefined
129
+ ? ""
130
+ : ` (exit code ${output.exitCode})`
131
+ return `${prefix}${chalkScriptHeading(`${scriptIcon} Background job ${output.id} ${output.status}${exitCode}`)}\n\n${chalk.dim(truncate(output.output))}\n\n`
132
+ }
126
133
  case "HistoryAppended":
127
134
  case "HistoryReplaced": {
128
135
  return ""