clanka 0.19.1 → 0.20.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 (40) 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 +77 -0
  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 +173 -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 +73 -3
  16. package/dist/AgentExecutor.js.map +1 -1
  17. package/dist/AgentOutput.d.ts +19 -4
  18. package/dist/AgentOutput.d.ts.map +1 -1
  19. package/dist/AgentOutput.js +15 -0
  20. package/dist/AgentOutput.js.map +1 -1
  21. package/dist/AgentTools.d.ts +28 -0
  22. package/dist/AgentTools.d.ts.map +1 -1
  23. package/dist/AgentTools.js +35 -6
  24. package/dist/AgentTools.js.map +1 -1
  25. package/dist/OutputFormatter.d.ts.map +1 -1
  26. package/dist/OutputFormatter.js +6 -0
  27. package/dist/OutputFormatter.js.map +1 -1
  28. package/dist/bin/{OutputFormatter-Dqxyk2qD.mjs → OutputFormatter-U02YKTfy.mjs} +5 -1
  29. package/dist/bin/{OutputFormatter-Dqxyk2qD.mjs.map → OutputFormatter-U02YKTfy.mjs.map} +1 -1
  30. package/dist/bin/cli.mjs +130 -17
  31. package/dist/bin/cli.mjs.map +1 -1
  32. package/package.json +1 -1
  33. package/src/Acp.test.ts +110 -0
  34. package/src/Acp.ts +15 -0
  35. package/src/Agent.ts +97 -1
  36. package/src/AgentBashJobs.test.ts +295 -0
  37. package/src/AgentExecutor.ts +86 -0
  38. package/src/AgentOutput.ts +19 -0
  39. package/src/AgentTools.ts +62 -6
  40. package/src/OutputFormatter.ts +7 -0
@@ -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,
@@ -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
  /**
package/src/AgentTools.ts CHANGED
@@ -240,6 +240,38 @@ export const BashJob = Schema.Struct({
240
240
  */
241
241
  export type BashJob = typeof BashJob.Type
242
242
 
243
+ /**
244
+ * A background `bash` job, handed to the `JobWatcher` when it starts.
245
+ *
246
+ * @since 1.0.0
247
+ * @category Models
248
+ */
249
+ export interface BackgroundJob {
250
+ readonly id: string
251
+ /** Waits for the job to end and succeeds with its final state. */
252
+ readonly await: Effect.Effect<BashJob>
253
+ /**
254
+ * Marks the job's final state as reported. Succeeds with `false` when it
255
+ * already was: by `stopJob`, by a `jobOutput` call that returned it, or by
256
+ * an earlier `claim`.
257
+ */
258
+ readonly claim: Effect.Effect<boolean>
259
+ }
260
+
261
+ /**
262
+ * Receives every background `bash` job as it starts: those started with
263
+ * `background: true` and those moved to the background at their timeout.
264
+ * The executor sets it from `ExecuteOptions.onJob`.
265
+ *
266
+ * @since 1.0.0
267
+ * @category Context
268
+ */
269
+ export class JobWatcher extends Context.Reference<
270
+ (job: BackgroundJob) => Effect.Effect<void>
271
+ >("clanka/AgentTools/JobWatcher", {
272
+ defaultValue: () => () => Effect.void,
273
+ }) {}
274
+
243
275
  /**
244
276
  * The `bash` timeout when the caller sets none.
245
277
  *
@@ -436,7 +468,7 @@ export const AgentTools = Toolkit.make(
436
468
  makeBashTool(defaultBashTimeout),
437
469
  Tool.make("jobOutput", {
438
470
  description:
439
- 'Return the status and output so far of a background bash job.',
471
+ "Return the status and output so far of a background bash job.",
440
472
  parameters: Schema.String.annotate({
441
473
  identifier: "id",
442
474
  }),
@@ -593,11 +625,26 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
593
625
 
594
626
  const jobs = new Map<string, RunningCommand>()
595
627
  let nextJobId = 1
596
- const addJob = (running: RunningCommand) => {
628
+ const addJob = Effect.fnUntraced(function* (
629
+ command: Omit<RunningCommand, "reported">,
630
+ ) {
597
631
  const id = String(nextJobId++)
632
+ const running: RunningCommand = { ...command, reported: false }
598
633
  jobs.set(id, running)
634
+ const watch = yield* JobWatcher
635
+ yield* watch({
636
+ id,
637
+ await: Fiber.await(running.fiber).pipe(
638
+ Effect.map(() => jobInfo(id, running)),
639
+ ),
640
+ claim: Effect.sync(() => {
641
+ if (running.reported) return false
642
+ running.reported = true
643
+ return true
644
+ }),
645
+ })
599
646
  return id
600
- }
647
+ })
601
648
  const findJob = (id: string) => {
602
649
  const running = jobs.get(id)
603
650
  return running === undefined
@@ -628,7 +675,7 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
628
675
  new Error(`Command timed out after ${timeoutMs}ms`),
629
676
  )
630
677
  }
631
- const id = addJob(running)
678
+ const id = yield* addJob(running)
632
679
  const output = running.output()
633
680
  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
681
  }
@@ -857,7 +904,7 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
857
904
  stdin: "ignore",
858
905
  })
859
906
  if (options.background === true) {
860
- const id = addJob(yield* startCommand(cmd))
907
+ const id = yield* addJob(yield* startCommand(cmd))
861
908
  return `Started background job ${id}. ${jobUsage(id)}`
862
909
  }
863
910
  return yield* runCommand(cmd, Duration.millis(timeoutMs), "background")
@@ -867,7 +914,10 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
867
914
  yield* Effect.logInfo(`Calling "jobOutput"`).pipe(
868
915
  Effect.annotateLogs({ id }),
869
916
  )
870
- return jobInfo(id, yield* findJob(id))
917
+ const running = yield* findJob(id)
918
+ const job = jobInfo(id, running)
919
+ if (job.status !== "running") running.reported = true
920
+ return job
871
921
  }),
872
922
  stopJob: Effect.fn("AgentTools.stopJob")(function* (input: unknown) {
873
923
  const id = yield* decodeStopJob(input)
@@ -876,6 +926,7 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
876
926
  )
877
927
  const running = yield* findJob(id)
878
928
  yield* Fiber.interrupt(running.fiber)
929
+ running.reported = true
879
930
  return jobInfo(id, running)
880
931
  }),
881
932
  gh: Effect.fn("AgentTools.gh")(function* (args) {
@@ -1168,6 +1219,11 @@ interface RunningCommand {
1168
1219
  PlatformError.PlatformError
1169
1220
  >
1170
1221
  readonly output: () => string
1222
+ /**
1223
+ * Whether the final state has been reported, so it is not pushed to the
1224
+ * model as well.
1225
+ */
1226
+ reported: boolean
1171
1227
  }
1172
1228
 
1173
1229
  const jobUsage = (id: string) =>
@@ -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 ""