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/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "clanka",
3
3
  "type": "module",
4
- "version": "0.18.1",
4
+ "version": "0.19.0",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
package/src/Agent.ts CHANGED
@@ -1421,7 +1421,8 @@ const generateSystemTools = (
1421
1421
  )}${when(
1422
1422
  tools.offers("bash"),
1423
1423
  `
1424
- - Avoid passing scripts into the "bash" function, and instead write javascript.`,
1424
+ - Avoid passing scripts into the "bash" function, and instead write javascript.
1425
+ - Pass \`background: true\` to "bash" for commands that keep running, such as dev servers or watchers. A command still running at its timeout is moved to the background instead of being stopped. Use "jobOutput" and "stopJob" with the returned job id.`,
1425
1426
  )}
1426
1427
  - Variables are not shared between executions.
1427
1428
  - Do not use \`require\`, \`import\`, \`process\`, or any other Node.js apis.${when(
@@ -207,6 +207,29 @@ describe("RPC executeUnsafe", () => {
207
207
  ),
208
208
  )
209
209
 
210
+ it.live("accepts undefined params and undefined param properties", () =>
211
+ withRpc((executor) =>
212
+ Effect.gen(function* () {
213
+ const fs = yield* FileSystem.FileSystem
214
+ const { environment } = yield* executor.capabilities
215
+ yield* fs.writeFileString(
216
+ NodePath.join(environment.cwd, "x.txt"),
217
+ "hello",
218
+ )
219
+ const agents = yield* executor.executeUnsafe({
220
+ tool: "listAgents",
221
+ params: undefined,
222
+ })
223
+ assert.deepStrictEqual(agents, [])
224
+ const content = yield* executor.executeUnsafe({
225
+ tool: "readFile",
226
+ params: { path: "x.txt", startLine: undefined, lineNumbers: false },
227
+ })
228
+ assert.strictEqual(content, "hello")
229
+ }),
230
+ ),
231
+ )
232
+
210
233
  it.live("passes a caller's tool params shaped like bytes unchanged", () => {
211
234
  const payload = { _tag: "Bytes", base64: "AA==" } as const
212
235
  const Echo = Toolkit.make(
@@ -236,6 +259,38 @@ describe("RPC executeUnsafe", () => {
236
259
  ),
237
260
  )
238
261
  })
262
+
263
+ it.live("passes a caller's null params and __proto__ keys unchanged", () => {
264
+ const Echo = Toolkit.make(
265
+ Tool.make("echo", { parameters: Schema.Json, success: Schema.Json }),
266
+ )
267
+ return withRpc(
268
+ (executor) =>
269
+ Effect.gen(function* () {
270
+ const nullOutput = yield* executor.executeUnsafe({
271
+ tool: "echo" as never,
272
+ params: null as never,
273
+ })
274
+ assert.strictEqual(nullOutput, null)
275
+ const output = (yield* executor.executeUnsafe({
276
+ tool: "echo" as never,
277
+ params: JSON.parse('{"__proto__":{"x":1}}') as never,
278
+ })) as object
279
+ // An own `__proto__` key, not a prototype.
280
+ assert.deepStrictEqual(Object.keys(output), ["__proto__"])
281
+ assert.deepStrictEqual(
282
+ Object.getOwnPropertyDescriptor(output, "__proto__")?.value,
283
+ { x: 1 },
284
+ )
285
+ }),
286
+ (directory) =>
287
+ AgentExecutor.layerRpcServer({ directory, tools: Echo }).pipe(
288
+ Layer.provide(
289
+ Echo.toLayer({ echo: (params) => Effect.succeed(params) }),
290
+ ),
291
+ ),
292
+ )
293
+ })
239
294
  })
240
295
 
241
296
  // Both executor modes with the same limits. The RPC mode serves
@@ -301,6 +356,61 @@ const runScript = (script: string) =>
301
356
  .pipe(Stream.mkString)
302
357
  })
303
358
 
359
+ const readLog = (path: string) =>
360
+ NodeFs.existsSync(path) ? NodeFs.readFileSync(path, "utf8") : ""
361
+
362
+ // A command that records its shell's pid and logs its start, then waits for
363
+ // `openGate` before it logs its finish. The log shows whether it was killed
364
+ // or started twice, without racing a sleep.
365
+ const gatedCommand = (directory: string) => {
366
+ const pid = NodePath.join(directory, "pid")
367
+ const log = NodePath.join(directory, "runs.log")
368
+ const gate = NodePath.join(directory, "gate")
369
+ return `echo $$ > ${pid} && echo start >> ${log} && until [ -f ${gate} ]; do sleep 0.02; done && echo finish >> ${log}`
370
+ }
371
+ const openGate = (directory: string) =>
372
+ NodeFs.writeFileSync(NodePath.join(directory, "gate"), "")
373
+
374
+ const isAlive = (pid: number) => {
375
+ try {
376
+ process.kill(pid, 0)
377
+ return true
378
+ } catch (error) {
379
+ if ((error as NodeJS.ErrnoException).code === "ESRCH") return false
380
+ throw error
381
+ }
382
+ }
383
+
384
+ // Polls until the gated command's shell has exited. The kill can land after
385
+ // the caller has moved on, as an RPC interrupt does not wait for the server.
386
+ // A command that is never killed waits at its gate, so it fails the deadline.
387
+ const waitForExit = (directory: string) =>
388
+ Effect.gen(function* () {
389
+ const pid = Number(
390
+ NodeFs.readFileSync(NodePath.join(directory, "pid"), "utf8"),
391
+ )
392
+ while (isAlive(pid)) {
393
+ yield* Effect.sleep("20 millis")
394
+ }
395
+ }).pipe(
396
+ Effect.timeoutOrElse({
397
+ duration: "2 seconds",
398
+ orElse: () => Effect.die(new Error("The command was not stopped")),
399
+ }),
400
+ )
401
+
402
+ // Polls the log until `done` holds.
403
+ const waitForLog = (directory: string, done: (log: string) => boolean) =>
404
+ Effect.gen(function* () {
405
+ const path = NodePath.join(directory, "runs.log")
406
+ while (!done(readLog(path))) {
407
+ yield* Effect.sleep("20 millis")
408
+ }
409
+ return readLog(path)
410
+ })
411
+ const started = (log: string) => log !== ""
412
+ const finished = (log: string) => log.includes("finish")
413
+
304
414
  // Puts a `gh` that only sleeps first on PATH, so the test needs neither the
305
415
  // real CLI nor the network.
306
416
  const withSlowGh = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
@@ -447,23 +557,171 @@ await sleep(60000)`,
447
557
  })
448
558
 
449
559
  describe(`${mode} executor limits`, () => {
450
- it.live("stops a bash command at the caller's command timeout", () =>
560
+ it.live("runs a bash command in the background", () =>
451
561
  Effect.gen(function* () {
562
+ const executor = yield* AgentExecutor.AgentExecutor
563
+ const { environment } = yield* executor.capabilities
564
+ const output = yield* runScript(`
565
+ const result = await bash({
566
+ command: ${JSON.stringify(gatedCommand(environment.cwd))},
567
+ background: true,
568
+ })
569
+ console.log("RETURNED:", result)`)
570
+ assert.include(output, "RETURNED:")
571
+ assert.match(output, /background/i)
572
+ assert.strictEqual(
573
+ yield* waitForLog(environment.cwd, started),
574
+ "start\n",
575
+ "still running after the script ended",
576
+ )
577
+ openGate(environment.cwd)
578
+ assert.strictEqual(
579
+ yield* waitForLog(environment.cwd, finished),
580
+ "start\nfinish\n",
581
+ )
582
+ }).pipe(Effect.timeout("5 seconds"), Effect.provide(executorLayer({}))),
583
+ )
584
+
585
+ it.live("moves a bash command to the background at its timeout", () =>
586
+ Effect.gen(function* () {
587
+ const executor = yield* AgentExecutor.AgentExecutor
588
+ const { environment } = yield* executor.capabilities
452
589
  const output = yield* runScript(`
453
590
  try {
454
- await bash({ command: 'sleep 10 && echo fini""shed', timeoutMs: 60000 })
591
+ const result = await bash({
592
+ command: ${JSON.stringify(gatedCommand(environment.cwd))},
593
+ timeoutMs: 60000,
594
+ })
595
+ console.log("RETURNED:", result)
455
596
  } catch (error) {
456
597
  console.log("REJECTED:", String(error))
457
598
  }`)
458
- assert.include(output, "REJECTED:")
459
- assert.match(output, /timed out/i)
460
- assert.notInclude(output, "finished")
599
+ assert.include(output, "RETURNED:")
600
+ assert.notInclude(output, "REJECTED:")
601
+ assert.match(output, /background/i)
602
+ assert.strictEqual(
603
+ yield* waitForLog(environment.cwd, started),
604
+ "start\n",
605
+ "still running after the script ended",
606
+ )
607
+ openGate(environment.cwd)
608
+ assert.strictEqual(
609
+ yield* waitForLog(environment.cwd, finished),
610
+ "start\nfinish\n",
611
+ )
461
612
  }).pipe(
462
- Effect.timeout("3 seconds"),
613
+ Effect.timeout("5 seconds"),
463
614
  Effect.provide(executorLayer({ commandTimeout: "300 millis" })),
464
615
  ),
465
616
  )
466
617
 
618
+ it.live("reports background jobs through jobOutput", () =>
619
+ Effect.gen(function* () {
620
+ const executor = yield* AgentExecutor.AgentExecutor
621
+ const { environment } = yield* executor.capabilities
622
+ const output = yield* runScript(`
623
+ const done = async (id) => {
624
+ let job = await jobOutput(id)
625
+ while (job.status === "running") {
626
+ await sleep(20)
627
+ job = await jobOutput(id)
628
+ }
629
+ return job
630
+ }
631
+ await bash({ command: ${JSON.stringify(gatedCommand(environment.cwd))}, background: true })
632
+ await bash({ command: "echo out && exit 3", background: true })
633
+ console.log("RUNNING:", JSON.stringify(await jobOutput("1")))
634
+ await writeFile({ path: "gate", content: "" })
635
+ console.log("COMPLETED:", JSON.stringify(await done("1")))
636
+ console.log("FAILED:", JSON.stringify(await done("2")))`)
637
+ assert.include(output, 'RUNNING: {"id":"1","status":"running"')
638
+ assert.include(
639
+ output,
640
+ 'COMPLETED: {"id":"1","status":"completed","exitCode":0,"output":""}',
641
+ )
642
+ assert.include(
643
+ output,
644
+ 'FAILED: {"id":"2","status":"failed","exitCode":3,"output":"out\\n"}',
645
+ )
646
+ }).pipe(Effect.timeout("5 seconds"), Effect.provide(executorLayer({}))),
647
+ )
648
+
649
+ it.live("stops a background job with stopJob", () =>
650
+ Effect.gen(function* () {
651
+ const executor = yield* AgentExecutor.AgentExecutor
652
+ const { environment } = yield* executor.capabilities
653
+ const output = yield* runScript(`
654
+ await bash({ command: ${JSON.stringify(gatedCommand(environment.cwd))}, background: true })
655
+ console.log("STOPPED:", JSON.stringify(await stopJob("1")))
656
+ try {
657
+ await stopJob("99")
658
+ } catch (error) {
659
+ console.log("REJECTED:", String(error))
660
+ }`)
661
+ assert.include(output, 'STOPPED: {"id":"1","status":"stopped"')
662
+ assert.match(output, /REJECTED:.*No background job with id "99"/)
663
+ openGate(environment.cwd)
664
+ yield* Effect.sleep("500 millis")
665
+ assert.notInclude(
666
+ readLog(NodePath.join(environment.cwd, "runs.log")),
667
+ "finish",
668
+ "killed",
669
+ )
670
+ }).pipe(Effect.timeout("5 seconds"), Effect.provide(executorLayer({}))),
671
+ )
672
+
673
+ // Interrupting the script ends the call before the command timeout, so
674
+ // the command is stopped rather than handed over.
675
+ it.live(
676
+ "stops a foreground bash command when the script is interrupted",
677
+ () =>
678
+ Effect.gen(function* () {
679
+ const executor = yield* AgentExecutor.AgentExecutor
680
+ const { environment } = yield* executor.capabilities
681
+ const fiber = yield* runScript(
682
+ `await bash({ command: ${JSON.stringify(gatedCommand(environment.cwd))} })`,
683
+ ).pipe(Effect.forkScoped)
684
+ yield* waitForLog(environment.cwd, started)
685
+ yield* Fiber.interrupt(fiber)
686
+ yield* waitForExit(environment.cwd)
687
+ assert.strictEqual(
688
+ readLog(NodePath.join(environment.cwd, "runs.log")),
689
+ "start\n",
690
+ "killed",
691
+ )
692
+ }).pipe(
693
+ Effect.scoped,
694
+ Effect.timeout("5 seconds"),
695
+ Effect.provide(executorLayer({})),
696
+ ),
697
+ )
698
+
699
+ // The log sits outside the executor's directory, which is removed with
700
+ // the executor.
701
+ it.live("stops background jobs when the executor shuts down", () =>
702
+ Effect.gen(function* () {
703
+ const fs = yield* FileSystem.FileSystem
704
+ const directory = yield* fs.makeTempDirectoryScoped()
705
+ yield* runScript(
706
+ `await bash({ command: ${JSON.stringify(gatedCommand(directory))}, background: true })`,
707
+ ).pipe(
708
+ Effect.andThen(waitForLog(directory, started)),
709
+ Effect.provide(executorLayer({})),
710
+ )
711
+ openGate(directory)
712
+ yield* Effect.sleep("500 millis")
713
+ assert.strictEqual(
714
+ readLog(NodePath.join(directory, "runs.log")),
715
+ "start\n",
716
+ "killed",
717
+ )
718
+ }).pipe(
719
+ Effect.scoped,
720
+ Effect.timeout("5 seconds"),
721
+ Effect.provide(NodeServices.layer),
722
+ ),
723
+ )
724
+
467
725
  it.live("stops a gh command at the caller's command timeout", () =>
468
726
  Effect.gen(function* () {
469
727
  const output = yield* runScript(`
@@ -57,6 +57,7 @@ import * as Schema from "effect/Schema"
57
57
  import * as SchemaTransformation from "effect/SchemaTransformation"
58
58
  import * as RpcGroup from "effect/rpc/RpcGroup"
59
59
  import * as Rpc from "effect/rpc/Rpc"
60
+ import * as Predicate from "effect/Predicate"
60
61
  import * as Result from "effect/Result"
61
62
  import { SemanticSearch } from "./SemanticSearch/Service.ts"
62
63
  import { preprocessScript } from "./ScriptPreprocessing.ts"
@@ -775,14 +776,14 @@ export const makeRpc = Effect.gen(function* () {
775
776
  client
776
777
  .renderEnvironment({ environment, reset: options?.reset ?? false })
777
778
  .pipe(Effect.orDie),
778
- executeUnsafe({ environment, ...options }) {
779
- return encodeRpcParams(options.tool, options.params).pipe(
780
- Effect.flatMap((params) =>
781
- client.executeUnsafe(
782
- environment === undefined
783
- ? { ...options, params }
784
- : { ...options, params, environment },
785
- ),
779
+ executeUnsafe({ tool, params, environment }) {
780
+ return encodeRpcParams(tool, params).pipe(
781
+ Effect.flatMap((json) =>
782
+ client.executeUnsafe({
783
+ tool,
784
+ ...(json === undefined ? undefined : { params: json }),
785
+ ...(environment === undefined ? undefined : { environment }),
786
+ }),
786
787
  ),
787
788
  Effect.orDie,
788
789
  )
@@ -1103,7 +1104,7 @@ export class Rpcs extends RpcGroup.make(
1103
1104
  Rpc.make("executeUnsafe", {
1104
1105
  payload: Schema.Struct({
1105
1106
  tool: Schema.String,
1106
- params: Schema.Json,
1107
+ params: Schema.optionalKey(Schema.Json),
1107
1108
  environment: Schema.optionalKey(ExecutionEnvironment),
1108
1109
  }),
1109
1110
  success: Schema.Json,
@@ -1114,10 +1115,13 @@ export class Rpcs extends RpcGroup.make(
1114
1115
  // Internal
1115
1116
  // -------------------------------------------
1116
1117
 
1117
- // `executeUnsafe` params cross RPC as JSON. `writeFile` is the only built-in
1118
- // tool whose params JSON can't carry: its content may be bytes. The default
1119
- // JSON form of bytes is a base64 string, which the server couldn't tell apart
1120
- // from string content, so over RPC bytes travel as `{ base64 }` instead.
1118
+ // `executeUnsafe` params cross RPC as JSON. JSON has no `undefined`, so
1119
+ // `undefined` params are omitted from the payload, `undefined` properties are
1120
+ // dropped, and `undefined` array items become `null`, as `JSON.stringify` does.
1121
+ // `writeFile` is the only built-in tool whose params JSON can't carry: its
1122
+ // content may be bytes. The default JSON form of bytes is a base64 string,
1123
+ // which the server couldn't tell apart from string content, so over RPC bytes
1124
+ // travel as `{ base64 }` instead.
1121
1125
  const RpcWriteFileParams = Schema.Struct({
1122
1126
  ...AgentTools.tools.writeFile.parametersSchema.fields,
1123
1127
  content: Schema.Union([
@@ -1134,17 +1138,40 @@ const RpcWriteFileParams = Schema.Struct({
1134
1138
  ]),
1135
1139
  })
1136
1140
 
1141
+ const isPlainObject = (value: unknown): value is Record<string, unknown> => {
1142
+ if (!Predicate.isObject(value)) return false
1143
+ const proto = Object.getPrototypeOf(value)
1144
+ return proto === Object.prototype || proto === null
1145
+ }
1146
+
1147
+ // Only arrays and plain objects are walked, so bytes and other values reach
1148
+ // the schema untouched.
1149
+ const dropUndefined = (value: unknown): unknown => {
1150
+ if (Array.isArray(value)) {
1151
+ return value.map((item) => dropUndefined(item) ?? null)
1152
+ }
1153
+ if (!isPlainObject(value)) return value
1154
+ // `Object.fromEntries` keeps an own `__proto__` key as a data property.
1155
+ return Object.fromEntries(
1156
+ Object.entries(value)
1157
+ .filter(([, field]) => field !== undefined)
1158
+ .map(([key, field]) => [key, dropUndefined(field)]),
1159
+ )
1160
+ }
1161
+
1137
1162
  const encodeRpcParams = (
1138
1163
  tool: string,
1139
1164
  params: unknown,
1140
- ): Effect.Effect<Schema.Json, Schema.SchemaError> =>
1141
- tool === "writeFile"
1142
- ? Schema.encodeUnknownEffect(RpcWriteFileParams)(params)
1143
- : Effect.succeed(params as Schema.Json)
1165
+ ): Effect.Effect<Schema.Json | undefined, Schema.SchemaError> => {
1166
+ const json = dropUndefined(params)
1167
+ return tool === "writeFile"
1168
+ ? Schema.encodeUnknownEffect(RpcWriteFileParams)(json)
1169
+ : Effect.succeed(json as Schema.Json | undefined)
1170
+ }
1144
1171
 
1145
1172
  const decodeRpcParams = (
1146
1173
  tool: string,
1147
- params: Schema.Json,
1174
+ params: Schema.Json | undefined,
1148
1175
  ): Effect.Effect<unknown, Schema.SchemaError> =>
1149
1176
  tool === "writeFile"
1150
1177
  ? Schema.decodeUnknownEffect(RpcWriteFileParams)(params)
@@ -1230,7 +1257,8 @@ const errorMessage = (error: unknown): string =>
1230
1257
  ? error.message
1231
1258
  : String(error)
1232
1259
 
1233
- // Leaving out `delegate` leaves out the tools that address its sub-agents.
1260
+ // Leaving out `delegate` leaves out the tools that address its sub-agents,
1261
+ // and leaving out `bash` leaves out the tools that address its jobs.
1234
1262
  const excludedToolNames = (
1235
1263
  excludeTools: ReadonlyArray<ExcludableTool> | undefined,
1236
1264
  ): ReadonlySet<string> => {
@@ -1245,6 +1273,10 @@ const excludedToolNames = (
1245
1273
  names.add(name)
1246
1274
  }
1247
1275
  }
1276
+ if (names.has("bash")) {
1277
+ names.add("jobOutput")
1278
+ names.add("stopJob")
1279
+ }
1248
1280
  return names
1249
1281
  }
1250
1282