clanka 0.18.1 → 0.19.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.
package/src/AgentTools.ts CHANGED
@@ -6,9 +6,13 @@ import { parsePatch, patchChunks } from "./ApplyPatch.ts"
6
6
  import * as ExaSearch from "./ExaSearch.ts"
7
7
  import * as WebToMarkdown from "./WebToMarkdown.ts"
8
8
  import type * as HttpClient from "effect/http/HttpClient"
9
+ import type * as PlatformError from "effect/PlatformError"
9
10
  import * as Context from "effect/Context"
10
11
  import * as Duration from "effect/Duration"
11
12
  import * as Effect from "effect/Effect"
13
+ import * as Cause from "effect/Cause"
14
+ import * as Exit from "effect/Exit"
15
+ import * as Fiber from "effect/Fiber"
12
16
  import * as Toolkit from "effect/ai/Toolkit"
13
17
  import * as Tool from "effect/ai/Tool"
14
18
  import * as Schema from "effect/Schema"
@@ -199,6 +203,43 @@ export class ImageAttacher extends Context.Service<
199
203
  (image: ImageAttachment) => Effect.Effect<void>
200
204
  >()("clanka/AgentTools/ImageAttacher") {}
201
205
 
206
+ /**
207
+ * @since 1.0.0
208
+ * @category Models
209
+ */
210
+ export const BashJobStatus = Schema.Literals([
211
+ "running",
212
+ "completed",
213
+ "failed",
214
+ "stopped",
215
+ ])
216
+
217
+ /**
218
+ * @since 1.0.0
219
+ * @category Models
220
+ */
221
+ export type BashJobStatus = typeof BashJobStatus.Type
222
+
223
+ /**
224
+ * A `bash` command running in the background, as returned by `jobOutput`
225
+ * and `stopJob`.
226
+ *
227
+ * @since 1.0.0
228
+ * @category Models
229
+ */
230
+ export const BashJob = Schema.Struct({
231
+ id: Schema.String,
232
+ status: BashJobStatus,
233
+ exitCode: Schema.optional(Schema.Number),
234
+ output: Schema.String,
235
+ })
236
+
237
+ /**
238
+ * @since 1.0.0
239
+ * @category Models
240
+ */
241
+ export type BashJob = typeof BashJob.Type
242
+
202
243
  /**
203
244
  * The `bash` timeout when the caller sets none.
204
245
  *
@@ -245,11 +286,16 @@ export class CommandLimits extends Context.Reference<{
245
286
  */
246
287
  export const makeBashTool = (timeout: Duration.Duration) =>
247
288
  Tool.make("bash", {
248
- description: "Run a bash command and return the output",
289
+ 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".',
249
291
  parameters: Schema.Struct({
250
292
  command: Schema.String,
251
293
  timeoutMs: Schema.optional(Schema.Finite).annotate({
252
- documentation: `Timeout in ms (default and max: ${Duration.toMillis(timeout)})`,
294
+ documentation: `How long to wait in ms before moving the command to the background (default and max: ${Duration.toMillis(timeout)})`,
295
+ }),
296
+ background: Schema.optional(Schema.Boolean).annotate({
297
+ documentation:
298
+ "Start the command in the background and return its job id without waiting",
253
299
  }),
254
300
  }).annotate({
255
301
  identifier: "command",
@@ -388,6 +434,24 @@ export const AgentTools = Toolkit.make(
388
434
  dependencies: [CurrentDirectory],
389
435
  }),
390
436
  makeBashTool(defaultBashTimeout),
437
+ Tool.make("jobOutput", {
438
+ description:
439
+ 'Return the status and output so far of a background bash job.',
440
+ parameters: Schema.String.annotate({
441
+ identifier: "id",
442
+ }),
443
+ success: BashJob,
444
+ failure: Schema.String,
445
+ }),
446
+ Tool.make("stopJob", {
447
+ description:
448
+ "Stop a background bash job and return its final status and output.",
449
+ parameters: Schema.String.annotate({
450
+ identifier: "id",
451
+ }),
452
+ success: BashJob,
453
+ failure: Schema.String,
454
+ }),
391
455
  Tool.make("applyPatch", {
392
456
  description:
393
457
  "Add, update or remove multiple files with a git diff / unified diff / wrapped patch.",
@@ -502,45 +566,79 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
502
566
  const pathService = yield* Path.Path
503
567
  const webSearch = yield* ExaSearch.ExaSearch
504
568
  const fetchMarkdown = yield* WebToMarkdown.WebToMarkdown
505
- const execute = Effect.fn(
506
- function* (
507
- command: ChildProcess.Command,
508
- _timeout: Duration.Duration | undefined,
509
- ) {
510
- const { outputChars } = yield* CommandLimits
511
- const handle = yield* spawner.spawn(command)
512
- return yield* handle.all.pipe(
513
- Stream.decodeText,
514
- outputChars === undefined
515
- ? Stream.mkString
516
- : collectBounded(outputChars),
517
- Effect.flatMap(
518
- Effect.fnUntraced(function* (output) {
519
- const exitCode = yield* handle.exitCode
520
- if (exitCode === 0) return output
521
- return yield* Effect.die(
522
- new Error(
523
- `Command failed with exit code ${exitCode}: ${output}`,
524
- ),
525
- )
526
- }),
569
+ // Commands run in fibers owned by the executor rather than the tool call,
570
+ // so one that is moved to the background outlives the script that
571
+ // started it. Closing the executor stops them all.
572
+ const commandScope = yield* Effect.scope
573
+ const startCommand = Effect.fnUntraced(function* (
574
+ command: ChildProcess.Command,
575
+ ) {
576
+ const { outputChars } = yield* CommandLimits
577
+ const output = makeOutputBuffer(outputChars)
578
+ const fiber = yield* spawner.spawn(command).pipe(
579
+ Effect.flatMap((handle) =>
580
+ handle.all.pipe(
581
+ Stream.decodeText,
582
+ Stream.runForEach((chunk) =>
583
+ Effect.sync(() => output.append(chunk)),
584
+ ),
585
+ Effect.andThen(handle.exitCode),
527
586
  ),
528
- )
529
- },
530
- (effect, _command, timeout) =>
587
+ ),
588
+ Effect.scoped,
589
+ Effect.forkIn(commandScope),
590
+ )
591
+ return { fiber, output: output.render }
592
+ })
593
+
594
+ const jobs = new Map<string, RunningCommand>()
595
+ let nextJobId = 1
596
+ const addJob = (running: RunningCommand) => {
597
+ const id = String(nextJobId++)
598
+ jobs.set(id, running)
599
+ return id
600
+ }
601
+ const findJob = (id: string) => {
602
+ const running = jobs.get(id)
603
+ return running === undefined
604
+ ? Effect.fail(`No background job with id "${id}"`)
605
+ : Effect.succeed(running)
606
+ }
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,
613
+ timeout: Duration.Duration | undefined,
614
+ onTimeout: "stop" | "background",
615
+ ) {
616
+ const running = yield* startCommand(command)
617
+ const awaited = Fiber.await(running.fiber)
618
+ const exit = yield* (
531
619
  timeout === undefined
532
- ? effect
533
- : Effect.timeoutOrElse(effect, {
534
- duration: timeout,
535
- orElse: () =>
536
- Effect.die(
537
- new Error(
538
- `Command timed out after ${Duration.toMillis(timeout)}ms`,
539
- ),
540
- ),
541
- }),
542
- Effect.scoped,
543
- )
620
+ ? Effect.asSome(awaited)
621
+ : Effect.timeoutOption(awaited, timeout)
622
+ ).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
+ })
544
642
 
545
643
  /**
546
644
  * Image branch of `readFile`: the bytes go to the `ImageAttacher` for
@@ -758,8 +856,28 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
758
856
  cwd,
759
857
  stdin: "ignore",
760
858
  })
761
- return yield* execute(cmd, Duration.millis(timeoutMs))
859
+ if (options.background === true) {
860
+ const id = addJob(yield* startCommand(cmd))
861
+ return `Started background job ${id}. ${jobUsage(id)}`
862
+ }
863
+ return yield* runCommand(cmd, Duration.millis(timeoutMs), "background")
762
864
  }, Effect.orDie),
865
+ jobOutput: Effect.fn("AgentTools.jobOutput")(function* (input: unknown) {
866
+ const id = yield* decodeJobOutput(input)
867
+ yield* Effect.logInfo(`Calling "jobOutput"`).pipe(
868
+ Effect.annotateLogs({ id }),
869
+ )
870
+ return jobInfo(id, yield* findJob(id))
871
+ }),
872
+ stopJob: Effect.fn("AgentTools.stopJob")(function* (input: unknown) {
873
+ const id = yield* decodeStopJob(input)
874
+ yield* Effect.logInfo(`Calling "stopJob"`).pipe(
875
+ Effect.annotateLogs({ id }),
876
+ )
877
+ const running = yield* findJob(id)
878
+ yield* Fiber.interrupt(running.fiber)
879
+ return jobInfo(id, running)
880
+ }),
763
881
  gh: Effect.fn("AgentTools.gh")(function* (args) {
764
882
  yield* Effect.logInfo(`Calling "gh"`).pipe(
765
883
  Effect.annotateLogs({ args }),
@@ -770,7 +888,7 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
770
888
  stdin: "ignore",
771
889
  })
772
890
  const { timeout } = yield* CommandLimits
773
- return yield* execute(cmd, timeout)
891
+ return yield* runCommand(cmd, timeout, "stop")
774
892
  }, Effect.orDie),
775
893
  webSearch: Effect.fn("AgentTools.webSearch")(function* (options) {
776
894
  yield* Effect.logInfo(`Calling "webSearch"`).pipe(
@@ -1035,41 +1153,80 @@ const decodeStopAgent = decodeParams(
1035
1153
  'stopAgent requires an agent id, for example: stopAgent("3").',
1036
1154
  )
1037
1155
 
1156
+ const decodeJobOutput = decodeParams(
1157
+ AgentTools.tools.jobOutput.parametersSchema,
1158
+ 'jobOutput requires a job id, for example: jobOutput("1").',
1159
+ )
1160
+ const decodeStopJob = decodeParams(
1161
+ AgentTools.tools.stopJob.parametersSchema,
1162
+ 'stopJob requires a job id, for example: stopJob("1").',
1163
+ )
1164
+
1165
+ interface RunningCommand {
1166
+ readonly fiber: Fiber.Fiber<
1167
+ ChildProcessSpawner.ExitCode,
1168
+ PlatformError.PlatformError
1169
+ >
1170
+ readonly output: () => string
1171
+ }
1172
+
1173
+ const jobUsage = (id: string) =>
1174
+ `Use jobOutput("${id}") for its status and output, or stopJob("${id}") to stop it.`
1175
+
1176
+ const jobInfo = (id: string, running: RunningCommand): BashJob => {
1177
+ const exit = running.fiber.pollUnsafe()
1178
+ const output = running.output()
1179
+ if (exit === undefined) return { id, status: "running", output }
1180
+ if (Exit.isSuccess(exit)) {
1181
+ return {
1182
+ id,
1183
+ status: exit.value === 0 ? "completed" : "failed",
1184
+ exitCode: exit.value,
1185
+ output,
1186
+ }
1187
+ }
1188
+ if (Cause.hasInterruptsOnly(exit.cause)) {
1189
+ return { id, status: "stopped", output }
1190
+ }
1191
+ return {
1192
+ id,
1193
+ status: "failed",
1194
+ output: `${output}${output === "" ? "" : "\n"}${Cause.pretty(exit.cause)}`,
1195
+ }
1196
+ }
1197
+
1038
1198
  /**
1039
- * Collects text output keeping at most `maxChars` characters: the start, the
1040
- * end, and a marker in place of the middle. Only the kept text is held in
1041
- * memory while the stream runs.
1199
+ * Accumulates text output keeping at most `maxChars` characters: the start,
1200
+ * the end, and a marker in place of the middle. Only the kept text is held in
1201
+ * memory. Without a limit everything is kept.
1042
1202
  */
1043
- const collectBounded =
1044
- (maxChars: number) =>
1045
- <E, R>(stream: Stream.Stream<string, E, R>): Effect.Effect<string, E, R> => {
1046
- const headChars = Math.floor(maxChars / 2)
1047
- const tailChars = maxChars - headChars
1048
- let head = ""
1049
- let tail = ""
1050
- let total = 0
1051
- return stream.pipe(
1052
- Stream.runForEach((chunk) =>
1053
- Effect.sync(() => {
1054
- total += chunk.length
1055
- let rest = chunk
1056
- if (head.length < headChars) {
1057
- const take = headChars - head.length
1058
- head += rest.slice(0, take)
1059
- rest = rest.slice(take)
1060
- }
1061
- if (rest.length > 0 && tailChars > 0) {
1062
- tail = (tail + rest).slice(-tailChars)
1063
- }
1064
- }),
1065
- ),
1066
- Effect.map(() => {
1067
- const omitted = total - head.length - tail.length
1068
- if (omitted <= 0) return head + tail
1069
- return `${head}\n\n[... ${omitted} of ${total} chars omitted from the middle of the output ...]\n\n${tail}`
1070
- }),
1071
- )
1203
+ const makeOutputBuffer = (maxChars: number | undefined) => {
1204
+ const headChars =
1205
+ maxChars === undefined ? Number.POSITIVE_INFINITY : Math.floor(maxChars / 2)
1206
+ const tailChars = maxChars === undefined ? 0 : maxChars - headChars
1207
+ let head = ""
1208
+ let tail = ""
1209
+ let total = 0
1210
+ return {
1211
+ append(chunk: string) {
1212
+ total += chunk.length
1213
+ let rest = chunk
1214
+ if (head.length < headChars) {
1215
+ const take = headChars - head.length
1216
+ head += rest.slice(0, take)
1217
+ rest = rest.slice(take)
1218
+ }
1219
+ if (rest.length > 0 && tailChars > 0) {
1220
+ tail = (tail + rest).slice(-tailChars)
1221
+ }
1222
+ },
1223
+ render() {
1224
+ const omitted = total - head.length - tail.length
1225
+ if (omitted <= 0) return head + tail
1226
+ return `${head}\n\n[... ${omitted} of ${total} chars omitted from the middle of the output ...]\n\n${tail}`
1227
+ },
1072
1228
  }
1229
+ }
1073
1230
 
1074
1231
  class ApplyPatchError extends Data.TaggedClass("ApplyPatchError")<{
1075
1232
  readonly message: string