clanka 0.21.0 → 0.22.1

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 (48) hide show
  1. package/dist/Acp.test.js +19 -7
  2. package/dist/Acp.test.js.map +1 -1
  3. package/dist/Agent.d.ts +4 -4
  4. package/dist/Agent.d.ts.map +1 -1
  5. package/dist/Agent.js +140 -99
  6. package/dist/Agent.js.map +1 -1
  7. package/dist/Agent.test.js +5 -4
  8. package/dist/Agent.test.js.map +1 -1
  9. package/dist/AgentBashJobs.test.js +47 -32
  10. package/dist/AgentBashJobs.test.js.map +1 -1
  11. package/dist/AgentCallerConfig.test.js +26 -7
  12. package/dist/AgentCallerConfig.test.js.map +1 -1
  13. package/dist/AgentExecutor.d.ts +71 -41
  14. package/dist/AgentExecutor.d.ts.map +1 -1
  15. package/dist/AgentExecutor.js +86 -79
  16. package/dist/AgentExecutor.js.map +1 -1
  17. package/dist/AgentExecutor.test.js +108 -83
  18. package/dist/AgentExecutor.test.js.map +1 -1
  19. package/dist/AgentExecutorImage.test.js +2 -2
  20. package/dist/AgentExecutorImage.test.js.map +1 -1
  21. package/dist/AgentImage.test.js +3 -2
  22. package/dist/AgentImage.test.js.map +1 -1
  23. package/dist/AgentSubagents.test.js +218 -29
  24. package/dist/AgentSubagents.test.js.map +1 -1
  25. package/dist/AgentTools.d.ts +318 -290
  26. package/dist/AgentTools.d.ts.map +1 -1
  27. package/dist/AgentTools.js +225 -199
  28. package/dist/AgentTools.js.map +1 -1
  29. package/dist/AgentTools.test.js +2 -2
  30. package/dist/AgentTools.test.js.map +1 -1
  31. package/dist/AgentToolsReadFile.test.js +8 -2
  32. package/dist/AgentToolsReadFile.test.js.map +1 -1
  33. package/dist/bin/cli.mjs +309 -289
  34. package/dist/bin/cli.mjs.map +1 -1
  35. package/package.json +1 -1
  36. package/src/Acp.test.ts +31 -10
  37. package/src/Agent.test.ts +5 -4
  38. package/src/Agent.ts +175 -140
  39. package/src/AgentBashJobs.test.ts +70 -38
  40. package/src/AgentCallerConfig.test.ts +39 -7
  41. package/src/AgentExecutor.test.ts +132 -91
  42. package/src/AgentExecutor.ts +120 -105
  43. package/src/AgentExecutorImage.test.ts +2 -2
  44. package/src/AgentImage.test.ts +4 -3
  45. package/src/AgentSubagents.test.ts +825 -562
  46. package/src/AgentTools.test.ts +2 -2
  47. package/src/AgentTools.ts +345 -288
  48. package/src/AgentToolsReadFile.test.ts +14 -3
@@ -20,13 +20,14 @@ import * as Agent from "./Agent.ts"
20
20
  import * as AgentExecutor from "./AgentExecutor.ts"
21
21
 
22
22
  // =============================================================================
23
- // Background bash jobs: completion pushes.
23
+ // Background bash tasks: completion pushes and lifecycle.
24
24
  //
25
- // These drive the real Agent loop and a real executor. When a background job
26
- // exits, the next model call gets a user message
27
- // `<job id="…" status="…" exitCode="…">output</job>`, unless the job was
28
- // already reported by `stopJob` or by a `jobOutput` call that saw its final
29
- // status. Job IDs come from the executor's counter: "1", "2", ...
25
+ // These drive the real Agent loop and a real executor. When a background bash
26
+ // task exits, the next model call gets a user message
27
+ // `<task id="…" kind="bash" status="…" exitCode="…">output</task>`, unless the
28
+ // task was already reported by `stopTask`, `waitTasks` or a `taskOutput` call
29
+ // that saw its final status. Task IDs come from the executor's counter: "1",
30
+ // "2", ...
30
31
  // =============================================================================
31
32
 
32
33
  type Respond = (
@@ -103,11 +104,11 @@ const systemPrompt = (prompts: ReadonlyArray<Prompt.Prompt>): string =>
103
104
  messageText(prompts[0]!.content[0]!)
104
105
 
105
106
  /** The user messages in `prompt` that carry a completion push. */
106
- const jobPushes = (prompt: Prompt.Prompt): Array<string> =>
107
+ const taskPushes = (prompt: Prompt.Prompt): Array<string> =>
107
108
  prompt.content.flatMap((message) => {
108
109
  if (message.role !== "user") return []
109
110
  const text = messageText(message)
110
- return text.includes("<job id=") ? [text] : []
111
+ return text.includes("<task id=") ? [text] : []
111
112
  })
112
113
 
113
114
  // --- executors ---------------------------------------------------------------
@@ -157,16 +158,16 @@ const executors = [
157
158
  // --- tests -------------------------------------------------------------------
158
159
 
159
160
  for (const [executorName, executorLayer] of executors) {
160
- // Each test gets its own executor, so job IDs start at "1".
161
- describe(`background bash jobs (${executorName} executor)`, () => {
161
+ // Each test gets its own executor, so task IDs start at "1".
162
+ describe(`background bash tasks (${executorName} executor)`, () => {
162
163
  it.live(
163
- "a finished job is pushed once with its id, status, exit code and output",
164
+ "a finished bash task is pushed once with its id, kind, status, exit code and output",
164
165
  () =>
165
166
  Effect.gen(function* () {
166
167
  const { exit, prompts } = yield* runAgent((index) => {
167
168
  switch (index) {
168
169
  case 0:
169
- // The script outlives the job, so it has exited before the
170
+ // The script outlives the task, so it has exited before the
170
171
  // next model call.
171
172
  return execute(
172
173
  "start",
@@ -182,14 +183,14 @@ await sleep(500)`,
182
183
 
183
184
  assert.deepStrictEqual(exit, Exit.succeed("done"))
184
185
  assert.strictEqual(prompts.length, 3)
185
- const pushes = jobPushes(prompts[1]!)
186
+ const pushes = taskPushes(prompts[1]!)
186
187
  assert.strictEqual(pushes.length, 1, "pushed before the next call")
187
188
  assert.match(
188
189
  pushes[0]!,
189
- /^<job id="1" status="failed" exitCode="3">\s*JOB-OUTPUT\s*<\/job>$/,
190
+ /^<task id="1" kind="bash" status="failed" exitCode="3">\s*JOB-OUTPUT\s*<\/task>$/,
190
191
  )
191
192
  assert.deepStrictEqual(
192
- jobPushes(prompts[2]!),
193
+ taskPushes(prompts[2]!),
193
194
  pushes,
194
195
  "not pushed a second time",
195
196
  )
@@ -197,26 +198,26 @@ await sleep(500)`,
197
198
  )
198
199
 
199
200
  it.live(
200
- "a job whose final state stopJob, jobOutput, waitJob or bash returned is not pushed",
201
+ "a bash task whose final state stopTask, taskOutput, waitTasks or bash returned is not pushed",
201
202
  () =>
202
203
  Effect.gen(function* () {
203
204
  const { exit, prompts } = yield* runAgent((index) => {
204
205
  switch (index) {
205
206
  case 0:
206
- // Job 3 is never read, so it is the only push.
207
+ // Task 3 is never read, so it is the only push.
207
208
  return execute(
208
209
  "start",
209
210
  `await bash({ command: "sleep 30", background: true })
210
211
  await bash({ command: "echo READ", background: true })
211
212
  await bash({ command: "echo UNREAD", background: true })
212
- await stopJob("1")
213
- let job = await jobOutput("2")
214
- while (job.status === "running") {
213
+ await stopTask("1")
214
+ let task = await taskOutput("2")
215
+ while (task.status === "running") {
215
216
  await sleep(20)
216
- job = await jobOutput("2")
217
+ task = await taskOutput("2")
217
218
  }
218
219
  await bash({ command: "echo FOREGROUND" })
219
- await waitJob({ id: (await bash({ command: "echo WAITED", background: true })).id })
220
+ await waitTasks({ ids: [(await bash({ command: "echo WAITED", background: true })).id] })
220
221
  await sleep(500)
221
222
  console.log("SCRIPT" + "-DONE")`,
222
223
  )
@@ -227,23 +228,54 @@ console.log("SCRIPT" + "-DONE")`,
227
228
 
228
229
  assert.deepStrictEqual(exit, Exit.succeed("done"))
229
230
  assert.strictEqual(prompts.length, 2)
230
- const pushes = jobPushes(prompts[1]!)
231
+ const pushes = taskPushes(prompts[1]!)
231
232
  assert.strictEqual(pushes.length, 1)
232
233
  assert.match(
233
234
  pushes[0]!,
234
- /^<job id="3" status="completed" exitCode="0">\s*UNREAD\s*<\/job>$/,
235
+ /^<task id="3" kind="bash" status="completed" exitCode="0">\s*UNREAD\s*<\/task>$/,
235
236
  )
236
237
  assert.include(JSON.stringify(prompts[1]), "SCRIPT-DONE")
237
238
  }).pipe(Effect.provide(executorLayer)),
238
239
  )
240
+
241
+ // Unlike a sub-agent, a running bash task such as a dev server never holds
242
+ // the run open. The run timeout fails a run that waits for it.
243
+ it.live(
244
+ "a running bash task neither keeps an idle turn alive nor blocks taskComplete",
245
+ () =>
246
+ Effect.gen(function* () {
247
+ const idle = yield* runAgent((index) =>
248
+ index === 0
249
+ ? execute(
250
+ "start",
251
+ `await bash({ command: "sleep 30", background: true })`,
252
+ )
253
+ : text("idle"),
254
+ )
255
+ assert.deepStrictEqual(idle.exit, Exit.succeed("idle"))
256
+ assert.strictEqual(idle.prompts.length, 2)
257
+
258
+ const completed = yield* runAgent((index) =>
259
+ index === 0
260
+ ? execute(
261
+ "complete",
262
+ `await bash({ command: "sleep 30", background: true })
263
+ await taskComplete("done")`,
264
+ )
265
+ : text("taskComplete was rejected"),
266
+ )
267
+ assert.deepStrictEqual(completed.exit, Exit.succeed("done"))
268
+ assert.strictEqual(completed.prompts.length, 1)
269
+ }).pipe(Effect.provide(executorLayer)),
270
+ )
239
271
  })
240
272
  }
241
273
 
242
274
  // Clients and executor servers of different versions must keep working
243
275
  // together.
244
- describe("background bash jobs across versions", () => {
276
+ describe("background bash tasks across versions", () => {
245
277
  it.live(
246
- "the prompt promises job pushes only when the executor sends them",
278
+ "the prompt promises task pushes only when the executor sends them",
247
279
  () =>
248
280
  Effect.gen(function* () {
249
281
  const { current, capabilities } = yield* Effect.gen(function* () {
@@ -253,34 +285,34 @@ describe("background bash jobs across versions", () => {
253
285
  capabilities: yield* executor.capabilities,
254
286
  }
255
287
  }).pipe(Effect.provide(localExecutorLayer))
256
- assert.include(systemPrompt(current.prompts), '<job id="..."')
288
+ assert.include(systemPrompt(current.prompts), '<task id="..."')
257
289
 
258
- // The current executor's tool typings without job pushes: what an
290
+ // The current executor's tool typings without task pushes: what an
259
291
  // older client sees from a current server, or what a custom executor
260
- // that does not set `jobPushes` renders.
261
- const withoutJobPushes = AgentExecutor.AgentExecutor.of({
292
+ // that does not set `taskPushes` renders.
293
+ const withoutTaskPushes = AgentExecutor.AgentExecutor.of({
262
294
  capabilities: Effect.succeed(
263
295
  new AgentExecutor.Capabilities({
264
296
  ...capabilities,
265
- jobPushes: false,
297
+ taskPushes: false,
266
298
  }),
267
299
  ),
268
300
  execute: () => Stream.empty,
269
301
  executeUnsafe: () => Effect.die("executeUnsafe not implemented"),
270
302
  })
271
303
  const older = yield* runAgent(() => text("done")).pipe(
272
- Effect.provideService(AgentExecutor.AgentExecutor, withoutJobPushes),
304
+ Effect.provideService(AgentExecutor.AgentExecutor, withoutTaskPushes),
273
305
  )
274
306
  const olderPrompt = systemPrompt(older.prompts)
275
307
  assert.include(olderPrompt, "bash(", "the tool typings are included")
276
- assert.include(olderPrompt, '"jobOutput"')
277
- assert.notInclude(olderPrompt, "<job", "no push is promised")
308
+ assert.include(olderPrompt, '"taskOutput"')
309
+ assert.notInclude(olderPrompt, "<task", "no push is promised")
278
310
  }),
279
311
  )
280
312
 
281
- // A client from before job pushes cannot decode a `Job` part, so one would
282
- // end its script with a defect.
283
- it.live("the server sends no Job parts to a client that did not ask", () =>
313
+ // A client from before task pushes cannot decode a `Task` part, so one
314
+ // would end its script with a defect.
315
+ it.live("the server sends no Task parts to a client that did not ask", () =>
284
316
  Effect.gen(function* () {
285
317
  const client = yield* RpcClient.make(AgentExecutor.Rpcs)
286
318
  const { environment } = yield* client.capabilities()
@@ -293,7 +325,7 @@ describe("background bash jobs across versions", () => {
293
325
  .pipe(Stream.runCollect)
294
326
  const tags = parts.map((part) => part._tag)
295
327
  assert.include(tags, "Environment", "the script ran")
296
- assert.notInclude(tags, "Job")
328
+ assert.notInclude(tags, "Task")
297
329
  }).pipe(Effect.scoped, Effect.provide(rpcProtocolLayer)),
298
330
  )
299
331
  })
@@ -26,7 +26,7 @@ import * as RpcServer from "effect/rpc/RpcServer"
26
26
  import * as Agent from "./Agent.ts"
27
27
  import * as AgentExecutor from "./AgentExecutor.ts"
28
28
  import * as AgentSkills from "./AgentSkills.ts"
29
- import { type ExcludableTool, subagentsUnavailable } from "./AgentTools.ts"
29
+ import { type ExcludableTool, agentTasksUnavailable } from "./AgentTools.ts"
30
30
 
31
31
  // =============================================================================
32
32
  // Caller-selected tools, instructions, skills and loop-side tools.
@@ -218,7 +218,7 @@ const execute = (
218
218
  onEnvironment: () => Effect.void,
219
219
  onTaskComplete: () => Effect.void,
220
220
  onImage: () => Effect.void,
221
- subagents: subagentsUnavailable,
221
+ agentTasks: agentTasksUnavailable,
222
222
  loopTools,
223
223
  })
224
224
  .pipe(Stream.mkString)
@@ -236,7 +236,7 @@ for (const mode of modes) {
236
236
  executor: {
237
237
  excludeTools: ["gh", "webSearch", "fetchMarkdown", "delegate"],
238
238
  },
239
- script: `const missing = [typeof gh, typeof webSearch, typeof fetchMarkdown, typeof delegate, typeof waitAgents].join(",")
239
+ script: `const missing = [typeof gh, typeof webSearch, typeof fetchMarkdown, typeof delegate, typeof messageAgent].join(",")
240
240
  let call
241
241
  try {
242
242
  await gh(["pr", "view"])
@@ -252,12 +252,44 @@ await taskComplete(missing + " " + call)`,
252
252
  )
253
253
  assert.notMatch(
254
254
  system,
255
- /\b(gh|webSearch|fetchMarkdown|delegate|waitAgents|messageAgent|stopAgent|listAgents)\b/,
255
+ /\b(gh|webSearch|fetchMarkdown|delegate|messageAgent)\b/,
256
256
  )
257
257
  assert.include(system, "declare function readFile(")
258
258
  }),
259
259
  )
260
260
 
261
+ // The shared task functions address bash and agent tasks, so they stay
262
+ // while either kind can still be started.
263
+ it.live("the task functions go only when bash and delegate both go", () =>
264
+ Effect.gen(function* () {
265
+ const tasks =
266
+ "[typeof taskOutput, typeof waitTasks, typeof stopTask, typeof listTasks].join()"
267
+ const withBash = yield* runAgent({
268
+ mode,
269
+ executor: { excludeTools: ["delegate"] },
270
+ script: `await taskComplete(${tasks})`,
271
+ })
272
+ assert.strictEqual(
273
+ withBash.summary,
274
+ "function,function,function,function",
275
+ )
276
+ const withNeither = yield* runAgent({
277
+ mode,
278
+ executor: { excludeTools: ["bash", "delegate"] },
279
+ script: `await taskComplete(${tasks})`,
280
+ })
281
+ assert.strictEqual(
282
+ withNeither.summary,
283
+ "undefined,undefined,undefined,undefined",
284
+ )
285
+ assert.notMatch(
286
+ withNeither.system,
287
+ /\b(taskOutput|waitTasks|stopTask|listTasks)\b/,
288
+ )
289
+ assert.notInclude(withNeither.system, "<task")
290
+ }),
291
+ )
292
+
261
293
  it.live("a caller tool replaces a left-out built-in of the same name", () =>
262
294
  Effect.gen(function* () {
263
295
  let calls = 0
@@ -404,12 +436,12 @@ describe("agent", () => {
404
436
  // applyPatch hint and the executor's skills catalog.
405
437
  const { system, summary } = yield* runAgent({
406
438
  mode: "local",
407
- executor: { excludeTools: ["waitAgents", "applyPatch", "readFile"] },
439
+ executor: { excludeTools: ["waitTasks", "applyPatch", "readFile"] },
408
440
  script:
409
- "await taskComplete([typeof waitAgents, typeof applyPatch, typeof readFile].join())",
441
+ "await taskComplete([typeof waitTasks, typeof applyPatch, typeof readFile].join())",
410
442
  })
411
443
  assert.strictEqual(summary, "undefined,undefined,undefined")
412
- assert.notMatch(system, /\b(waitAgents|applyPatch|readFile)\b/)
444
+ assert.notMatch(system, /\b(waitTasks|applyPatch|readFile)\b/)
413
445
  assert.include(system, "declare function delegate(")
414
446
  }),
415
447
  )