clanka 0.20.0 → 0.22.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 (45) hide show
  1. package/dist/Acp.test.js +20 -8
  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 +51 -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 -78
  16. package/dist/AgentExecutor.js.map +1 -1
  17. package/dist/AgentExecutor.test.js +173 -72
  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 +220 -31
  24. package/dist/AgentSubagents.test.js.map +1 -1
  25. package/dist/AgentTools.d.ts +369 -257
  26. package/dist/AgentTools.d.ts.map +1 -1
  27. package/dist/AgentTools.js +247 -190
  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/bin/cli.mjs +330 -281
  32. package/dist/bin/cli.mjs.map +1 -1
  33. package/package.json +1 -1
  34. package/src/Acp.test.ts +32 -11
  35. package/src/Agent.test.ts +5 -4
  36. package/src/Agent.ts +175 -137
  37. package/src/AgentBashJobs.test.ts +74 -38
  38. package/src/AgentCallerConfig.test.ts +39 -7
  39. package/src/AgentExecutor.test.ts +229 -72
  40. package/src/AgentExecutor.ts +120 -104
  41. package/src/AgentExecutorImage.test.ts +2 -2
  42. package/src/AgentImage.test.ts +4 -3
  43. package/src/AgentSubagents.test.ts +825 -562
  44. package/src/AgentTools.test.ts +2 -2
  45. package/src/AgentTools.ts +370 -278
@@ -5,6 +5,7 @@
5
5
  import { parsePatch, patchChunks } from "./ApplyPatch.js";
6
6
  import * as ExaSearch from "./ExaSearch.js";
7
7
  import * as WebToMarkdown from "./WebToMarkdown.js";
8
+ import * as Clock from "effect/Clock";
8
9
  import * as Context from "effect/Context";
9
10
  import * as Duration from "effect/Duration";
10
11
  import * as Effect from "effect/Effect";
@@ -45,98 +46,89 @@ export class DirectoryChanger extends Context.Service()("clanka/AgentTools/Direc
45
46
  export class TaskCompleter extends Context.Service()("clanka/AgentTools/TaskCompleter") {
46
47
  }
47
48
  /**
49
+ * What a task is: a background `bash` command or a sub-agent started with
50
+ * `delegate`.
51
+ *
48
52
  * @since 1.0.0
49
53
  * @category Models
50
54
  */
51
- export const SubagentStatus = Schema.Literals([
52
- "completed",
53
- "running",
54
- "failed",
55
- "cancelled",
56
- ]);
57
- /**
58
- * @since 1.0.0
59
- * @category Models
60
- */
61
- export const SubagentResult = Schema.Struct({
62
- id: Schema.String,
63
- status: SubagentStatus,
64
- output: Schema.optional(Schema.String),
65
- });
55
+ export const TaskKind = Schema.Literals(["bash", "agent"]);
66
56
  /**
67
57
  * @since 1.0.0
68
58
  * @category Models
69
59
  */
70
- export const DelegateResult = Schema.Struct({
71
- ...SubagentResult.fields,
72
- status: Schema.Literals(["completed", "running"]),
73
- });
60
+ export const TaskStatus = Schema.Literals([
61
+ "running",
62
+ "completed",
63
+ "failed",
64
+ "stopped",
65
+ ]);
74
66
  /**
67
+ * A background `bash` command or a sub-agent, as returned by the task
68
+ * functions. Both kinds share one id space per executor.
69
+ *
75
70
  * @since 1.0.0
76
71
  * @category Models
77
72
  */
78
- export const SubagentInfo = Schema.Struct({
79
- id: Schema.String,
80
- status: SubagentStatus,
81
- prompt: Schema.String,
73
+ export const Task = Schema.Struct({
74
+ id: Schema.String.annotate({
75
+ documentation: "The task id, which can be managed with the task tools.",
76
+ }),
77
+ kind: TaskKind,
78
+ status: TaskStatus,
79
+ /** The bash command, or the sub-agent's prompt. */
80
+ description: Schema.String,
81
+ /** Output so far while running; the final output, or the error, once ended. */
82
+ output: Schema.String,
83
+ /** bash only: set when the command exited on its own. */
84
+ exitCode: Schema.optional(Schema.Number),
82
85
  });
83
86
  /**
84
87
  * @since 1.0.0
85
88
  * @category Context
86
89
  */
87
- export class SubagentExecutor extends Context.Service()("clanka/AgentTools/SubagentExecutor") {
90
+ export class AgentTaskExecutor extends Context.Service()("clanka/AgentTools/AgentTaskExecutor") {
88
91
  }
89
92
  /**
90
- * A `Subagents` implementation for contexts that cannot spawn agents.
93
+ * An `AgentTasks` implementation for contexts that cannot spawn agents.
91
94
  *
92
95
  * @since 1.0.0
93
96
  * @category Context
94
97
  */
95
- export const subagentsUnavailable = {
98
+ export const agentTasksUnavailable = {
96
99
  delegate: () => Effect.die(new Error("Sub-agents are not available here")),
97
- waitAgents: () => Effect.fail("Sub-agents are not available here"),
100
+ taskOutput: () => Effect.fail("Sub-agents are not available here"),
101
+ waitTasks: () => Effect.fail("Sub-agents are not available here"),
98
102
  messageAgent: () => Effect.fail("Sub-agents are not available here"),
99
- stopAgent: () => Effect.fail("Sub-agents are not available here"),
100
- listAgents: Effect.succeed([]),
103
+ stopTask: () => Effect.fail("Sub-agents are not available here"),
104
+ listTasks: Effect.succeed([]),
101
105
  };
102
106
  /**
107
+ * The agent running the current script. Tasks are only visible to the agent
108
+ * that started them; scripts without an agent share the `undefined` owner.
109
+ * The executor sets it from `ExecuteOptions.agentId`.
110
+ *
103
111
  * @since 1.0.0
104
112
  * @category Context
105
113
  */
106
- export class ImageAttacher extends Context.Service()("clanka/AgentTools/ImageAttacher") {
114
+ export class TaskOwner extends Context.Reference("clanka/AgentTools/TaskOwner", { defaultValue: () => undefined }) {
107
115
  }
108
116
  /**
109
117
  * @since 1.0.0
110
- * @category Models
111
- */
112
- export const BashJobStatus = Schema.Literals([
113
- "running",
114
- "completed",
115
- "failed",
116
- "stopped",
117
- ]);
118
- /**
119
- * A `bash` command running in the background, as returned by `jobOutput`
120
- * and `stopJob`.
121
- *
122
- * @since 1.0.0
123
- * @category Models
118
+ * @category Context
124
119
  */
125
- export const BashJob = Schema.Struct({
126
- id: Schema.String,
127
- status: BashJobStatus,
128
- exitCode: Schema.optional(Schema.Number),
129
- output: Schema.String,
130
- });
120
+ export class ImageAttacher extends Context.Service()("clanka/AgentTools/ImageAttacher") {
121
+ }
131
122
  /**
132
- * Receives every background `bash` job as it starts: those started with
133
- * `background: true` and those moved to the background at their timeout.
134
- * The executor sets it from `ExecuteOptions.onJob`.
123
+ * Receives every background `bash` task as it starts: those started with
124
+ * `background: true` and those moved to the background at their timeout. A
125
+ * command that `bash` returns finished is never handed over.
126
+ * The executor sets it from `ExecuteOptions.onTask`.
135
127
  *
136
128
  * @since 1.0.0
137
129
  * @category Context
138
130
  */
139
- export class JobWatcher extends Context.Reference("clanka/AgentTools/JobWatcher", {
131
+ export class TaskWatcher extends Context.Reference("clanka/AgentTools/TaskWatcher", {
140
132
  defaultValue: () => () => Effect.void,
141
133
  }) {
142
134
  }
@@ -175,19 +167,19 @@ export class CommandLimits extends Context.Reference("clanka/AgentTools/CommandL
175
167
  * @category Toolkit
176
168
  */
177
169
  export const makeBashTool = (timeout) => Tool.make("bash", {
178
- description: '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".',
170
+ description: "Run a bash command and return a task.",
179
171
  parameters: Schema.Struct({
180
172
  command: Schema.String,
181
173
  timeoutMs: Schema.optional(Schema.Finite).annotate({
182
- documentation: `How long to wait in ms before moving the command to the background (default and max: ${Duration.toMillis(timeout)})`,
174
+ documentation: `How long to wait in ms before moving the task to the background (default and max: ${Duration.toMillis(timeout)})`,
183
175
  }),
184
176
  background: Schema.optional(Schema.Boolean).annotate({
185
- documentation: "Start the command in the background and return its job id without waiting",
177
+ documentation: "Start the command in the background. Defaults to false which always returns 'completed' tasks.",
186
178
  }),
187
179
  }).annotate({
188
180
  identifier: "command",
189
181
  }),
190
- success: Schema.String,
182
+ success: Task,
191
183
  dependencies: [CurrentDirectory],
192
184
  });
193
185
  const globNamesDirectory = (glob) => glob
@@ -198,18 +190,18 @@ const globNamesDirectory = (glob) => glob
198
190
  * @since 1.0.0
199
191
  * @category Context
200
192
  */
201
- export const makeContextNoop = (cwd) => SubagentExecutor.context(subagentsUnavailable).pipe(Context.add(CurrentDirectory, cwd ?? "/"), Context.add(DirectoryChanger, () => Effect.die("Not implemented")), Context.add(TaskCompleter, () => Effect.void), Context.add(ImageAttacher, () => Effect.void));
193
+ export const makeContextNoop = (cwd) => AgentTaskExecutor.context(agentTasksUnavailable).pipe(Context.add(CurrentDirectory, cwd ?? "/"), Context.add(DirectoryChanger, () => Effect.die("Not implemented")), Context.add(TaskCompleter, () => Effect.void), Context.add(ImageAttacher, () => Effect.void));
202
194
  /**
203
195
  * @since 1.0.0
204
196
  * @category Toolkit
205
197
  */
206
198
  export const AgentTools = Toolkit.make(Tool.make("changeDirectory", {
207
- description: "Change the executor's working directory to an existing directory and return its absolute path. Relative paths resolve from the current directory without shell expansion. Await this before dependent tools. The change persists across your scripts. A sub-agent starts in your directory at the time it is created, and its changes do not affect yours. AGENTS.md files and skills that apply to the new directory are sent to you after the script ends. The semantic-search index root stays fixed.",
199
+ description: "Change the executor's working directory to an existing directory and return its absolute path. The change persists across your scripts.",
208
200
  parameters: Schema.String.annotate({ identifier: "directory" }),
209
201
  success: Schema.String,
210
202
  dependencies: [DirectoryChanger],
211
203
  }), Tool.make("readFile", {
212
- description: "Read a file and optionally filter the lines to return. Returns null if the file doesn't exist. For png/jpeg/gif/webp files the image itself is attached to your next turn and a short marker is returned instead of the bytes; line ranges are not allowed on images.",
204
+ description: "Read a file and optionally filter the lines to return. Returns null if the file doesn't exist. For png/jpeg/gif/webp files the image itself is attached to your next turn.",
213
205
  parameters: Schema.Struct({
214
206
  path: Schema.String,
215
207
  startLine: Schema.optional(Schema.Number),
@@ -237,44 +229,22 @@ export const AgentTools = Toolkit.make(Tool.make("changeDirectory", {
237
229
  success: Schema.String,
238
230
  dependencies: [CurrentDirectory],
239
231
  }), Tool.make("delegate", {
240
- description: 'Delegate a task to another software engineer / sub-agent. By default it waits for the sub-agent and returns its output. With `background: true` it returns straight away with status "running"; the sub-agent keeps working while you take more turns, and its result is sent to you as a <subagent> message when it finishes. Keep the returned id to address the agent later.',
232
+ description: "Delegate a task to another software engineer / sub-agent. With `background: true` the sub-agent works in the background, and its result is sent to you when it finishes.",
241
233
  parameters: Schema.Struct({
242
234
  prompt: Schema.String,
243
235
  background: Schema.optional(Schema.Boolean),
244
236
  }),
245
- success: DelegateResult,
237
+ success: Task,
246
238
  failure: Schema.String,
247
- dependencies: [SubagentExecutor],
248
- }), Tool.make("waitAgents", {
249
- description: 'Wait until the given sub-agents have finished, or all of your sub-agents when no ids are passed. A failed agent is returned with status "failed" and its error as the output; it does not throw.',
250
- parameters: Schema.UndefinedOr(Schema.Array(Schema.String)).annotate({
251
- identifier: "ids",
252
- }),
253
- success: Schema.Array(SubagentResult),
254
- failure: Schema.String,
255
- dependencies: [SubagentExecutor],
239
+ dependencies: [AgentTaskExecutor],
256
240
  }), Tool.make("messageAgent", {
257
- description: "Send a message to one of your sub-agents. A running agent receives it as steering; a finished agent starts a new turn on top of its previous conversation. Returns straight away; the result is sent to you as a <subagent> message.",
241
+ description: "Send a message to one of your sub-agents.",
258
242
  parameters: Schema.Struct({
259
243
  id: Schema.String,
260
244
  message: Schema.String,
261
245
  }),
262
- success: SubagentResult,
263
- failure: Schema.String,
264
- dependencies: [SubagentExecutor],
265
- }), Tool.make("stopAgent", {
266
- description: "Stop one of your sub-agents and every agent it started. Returns its final status.",
267
- parameters: Schema.String.annotate({
268
- identifier: "id",
269
- }),
270
- success: SubagentResult,
271
246
  failure: Schema.String,
272
- dependencies: [SubagentExecutor],
273
- }), Tool.make("listAgents", {
274
- description: "List the sub-agents you have started in this run, with their status.",
275
- parameters: Schema.Void,
276
- success: Schema.Array(SubagentInfo),
277
- dependencies: [SubagentExecutor],
247
+ dependencies: [AgentTaskExecutor],
278
248
  }), Tool.make("glob", {
279
249
  description: "Find files matching a glob pattern.",
280
250
  parameters: Schema.String.annotate({
@@ -289,20 +259,38 @@ export const AgentTools = Toolkit.make(Tool.make("changeDirectory", {
289
259
  }),
290
260
  success: Schema.String,
291
261
  dependencies: [CurrentDirectory],
292
- }), makeBashTool(defaultBashTimeout), Tool.make("jobOutput", {
293
- description: "Return the status and output so far of a background bash job.",
262
+ }), makeBashTool(defaultBashTimeout), Tool.make("taskOutput", {
263
+ description: "Return the status and output so far of one of your tasks: a background bash command or a sub-agent.",
294
264
  parameters: Schema.String.annotate({
295
265
  identifier: "id",
296
266
  }),
297
- success: BashJob,
267
+ success: Task,
268
+ failure: Schema.String,
269
+ dependencies: [AgentTaskExecutor],
270
+ }), Tool.make("waitTasks", {
271
+ description: "Wait until the given tasks have ended and return them, in the order given.",
272
+ parameters: Schema.Struct({
273
+ ids: Schema.Array(Schema.String),
274
+ timeoutMs: Schema.optional(Schema.Finite).annotate({
275
+ documentation: "How long to wait in ms (default and max: the bash command timeout)",
276
+ }),
277
+ }),
278
+ success: Schema.Array(Task),
298
279
  failure: Schema.String,
299
- }), Tool.make("stopJob", {
300
- description: "Stop a background bash job and return its final status and output.",
280
+ dependencies: [AgentTaskExecutor],
281
+ }), Tool.make("stopTask", {
282
+ description: "Stop one of your tasks.",
301
283
  parameters: Schema.String.annotate({
302
284
  identifier: "id",
303
285
  }),
304
- success: BashJob,
286
+ success: Task,
305
287
  failure: Schema.String,
288
+ dependencies: [AgentTaskExecutor],
289
+ }), Tool.make("listTasks", {
290
+ description: "List the tasks you have started, with their status.",
291
+ parameters: Schema.Void,
292
+ success: Schema.Array(Task),
293
+ dependencies: [AgentTaskExecutor],
306
294
  }), Tool.make("applyPatch", {
307
295
  description: "Add, update or remove multiple files with a git diff / unified diff / wrapped patch.",
308
296
  parameters: Schema.String.annotate({
@@ -396,55 +384,51 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(Effect.gen(f
396
384
  const fiber = yield* spawner.spawn(command).pipe(Effect.flatMap((handle) => handle.all.pipe(Stream.decodeText, Stream.runForEach((chunk) => Effect.sync(() => output.append(chunk))), Effect.andThen(handle.exitCode))), Effect.scoped, Effect.forkIn(commandScope));
397
385
  return { fiber, output: output.render };
398
386
  });
399
- const jobs = new Map();
400
- let nextJobId = 1;
401
- const addJob = Effect.fnUntraced(function* (command) {
402
- const id = String(nextJobId++);
403
- const running = { ...command, reported: false };
404
- jobs.set(id, running);
405
- const watch = yield* JobWatcher;
387
+ // Every task started on this executor, bash and agent alike, so both
388
+ // kinds share one id space. Each is only visible to the agent that
389
+ // started it.
390
+ const tasks = new Map();
391
+ let nextTaskId = 1;
392
+ const registerAgentTask = Effect.fnUntraced(function* () {
393
+ const id = String(nextTaskId++);
394
+ tasks.set(id, { kind: "agent", id, owner: yield* TaskOwner });
395
+ return id;
396
+ });
397
+ // Every `bash` command is a task, so any of them can be addressed by
398
+ // id. Only the ones still running when `bash` returns go to the
399
+ // `TaskWatcher`.
400
+ const addBashTask = Effect.fnUntraced(function* (description, command) {
401
+ const entry = {
402
+ kind: "bash",
403
+ id: String(nextTaskId++),
404
+ owner: yield* TaskOwner,
405
+ description,
406
+ command: { ...command, reported: false },
407
+ };
408
+ tasks.set(entry.id, entry);
409
+ return entry;
410
+ });
411
+ const watchBashTask = Effect.fnUntraced(function* (entry) {
412
+ const watch = yield* TaskWatcher;
406
413
  yield* watch({
407
- id,
408
- await: Fiber.await(running.fiber).pipe(Effect.map(() => jobInfo(id, running))),
414
+ id: entry.id,
415
+ kind: "bash",
416
+ await: Fiber.await(entry.command.fiber).pipe(Effect.map(() => bashTask(entry))),
409
417
  claim: Effect.sync(() => {
410
- if (running.reported)
418
+ if (entry.command.reported)
411
419
  return false;
412
- running.reported = true;
420
+ entry.command.reported = true;
413
421
  return true;
414
422
  }),
415
423
  });
416
- return id;
417
424
  });
418
- const findJob = (id) => {
419
- const running = jobs.get(id);
420
- return running === undefined
421
- ? Effect.fail(`No background job with id "${id}"`)
422
- : Effect.succeed(running);
423
- };
424
- // A command still running at its timeout is stopped, or with
425
- // `background` handed over as a job. A caller that is interrupted first
426
- // stops it either way.
427
- const runCommand = Effect.fnUntraced(function* (command, timeout, onTimeout) {
428
- const running = yield* startCommand(command);
429
- const awaited = Fiber.await(running.fiber);
430
- const exit = yield* (timeout === undefined
431
- ? Effect.asSome(awaited)
432
- : Effect.timeoutOption(awaited, timeout)).pipe(Effect.onInterrupt(() => Fiber.interrupt(running.fiber)));
433
- if (Option.isNone(exit)) {
434
- const timeoutMs = Duration.toMillis(timeout);
435
- if (onTimeout === "stop") {
436
- yield* Fiber.interrupt(running.fiber);
437
- return yield* Effect.die(new Error(`Command timed out after ${timeoutMs}ms`));
438
- }
439
- const id = yield* addJob(running);
440
- const output = running.output();
441
- return `${output}${output === "" || output.endsWith("\n") ? "" : "\n"}[Still running after ${timeoutMs}ms, so it was moved to the background as job ${id}. ${jobUsage(id)}]`;
425
+ const findTask = Effect.fnUntraced(function* (id) {
426
+ const owner = yield* TaskOwner;
427
+ const entry = tasks.get(id);
428
+ if (entry === undefined || entry.owner !== owner) {
429
+ return yield* Effect.fail(`No task with id ${JSON.stringify(id)}. You can only address tasks you started; call listTasks() to see them.`);
442
430
  }
443
- const exitCode = yield* exit.value;
444
- const output = running.output();
445
- if (exitCode === 0)
446
- return output;
447
- return yield* Effect.die(new Error(`Command failed with exit code ${exitCode}: ${output}`));
431
+ return entry;
448
432
  });
449
433
  /**
450
434
  * Image branch of `readFile`: the bytes go to the `ImageAttacher` for
@@ -583,8 +567,7 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(Effect.gen(f
583
567
  return yield* Effect.promise(() => import("glob").then((Glob) => Glob.glob(pattern, { cwd })));
584
568
  }),
585
569
  bash: Effect.fn("AgentTools.bash")(function* (options) {
586
- const limits = yield* CommandLimits;
587
- const maxMs = Duration.toMillis(limits.timeout ?? defaultBashTimeout);
570
+ const maxMs = bashTimeoutMs(yield* CommandLimits);
588
571
  const timeoutMs = Math.min(options.timeoutMs ?? maxMs, maxMs);
589
572
  yield* Effect.logInfo(`Calling "bash"`).pipe(Effect.annotateLogs({
590
573
  ...options,
@@ -595,28 +578,84 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(Effect.gen(f
595
578
  cwd,
596
579
  stdin: "ignore",
597
580
  });
598
- if (options.background === true) {
599
- const id = yield* addJob(yield* startCommand(cmd));
600
- return `Started background job ${id}. ${jobUsage(id)}`;
581
+ const entry = yield* addBashTask(options.command, yield* startCommand(cmd));
582
+ if (options.background !== true) {
583
+ const exit = yield* awaitCommand(entry.command, Duration.millis(timeoutMs));
584
+ if (Option.isSome(exit)) {
585
+ // A finished command is reported here, so it is never pushed.
586
+ const exitCode = yield* exit.value;
587
+ const task = reportBash(entry);
588
+ if (exitCode === 0)
589
+ return task;
590
+ return yield* Effect.die(new Error(`Command failed with exit code ${exitCode}: ${task.output}`));
591
+ }
601
592
  }
602
- return yield* runCommand(cmd, Duration.millis(timeoutMs), "background");
593
+ // Snapshot the task before yielding to the watcher: the command can
594
+ // finish while it is being handed over, and its final state must
595
+ // reach the model only once. A finished task is never handed over.
596
+ const task = reportBash(entry);
597
+ if (task.status === "running")
598
+ yield* watchBashTask(entry);
599
+ return task;
603
600
  }, Effect.orDie),
604
- jobOutput: Effect.fn("AgentTools.jobOutput")(function* (input) {
605
- const id = yield* decodeJobOutput(input);
606
- yield* Effect.logInfo(`Calling "jobOutput"`).pipe(Effect.annotateLogs({ id }));
607
- const running = yield* findJob(id);
608
- const job = jobInfo(id, running);
609
- if (job.status !== "running")
610
- running.reported = true;
611
- return job;
601
+ taskOutput: Effect.fn("AgentTools.taskOutput")(function* (input) {
602
+ const id = yield* decodeTaskOutput(input);
603
+ yield* Effect.logInfo(`Calling "taskOutput"`).pipe(Effect.annotateLogs({ id }));
604
+ const entry = yield* findTask(id);
605
+ if (entry.kind === "bash")
606
+ return reportBash(entry);
607
+ const agentTasks = yield* AgentTaskExecutor;
608
+ return yield* agentTasks.taskOutput(id);
609
+ }),
610
+ waitTasks: Effect.fn("AgentTools.waitTasks")(function* (input) {
611
+ const { ids, timeoutMs: requestedMs } = yield* decodeWaitTasks(input);
612
+ const maxMs = bashTimeoutMs(yield* CommandLimits);
613
+ const timeoutMs = Math.min(requestedMs ?? maxMs, maxMs);
614
+ yield* Effect.logInfo(`Calling "waitTasks"`).pipe(Effect.annotateLogs({ ids, timeoutMs }));
615
+ const entries = yield* Effect.forEach(ids, findTask);
616
+ const bashEntries = entries.filter((entry) => entry.kind === "bash");
617
+ const agentIds = entries.flatMap((entry) => entry.kind === "agent" ? [entry.id] : []);
618
+ const agentTasks = yield* AgentTaskExecutor;
619
+ // Nothing is reported until the batch is ready to return: a script
620
+ // stopped while it waits never receives it, so the tasks that ended
621
+ // first must still be pushed. The bash tasks are waited for first,
622
+ // without reporting them. Then one `AgentTasks.waitTasks` call waits
623
+ // for the agents with the time left and reports them together, so
624
+ // over RPC only its single response can be cut off. The agents keep
625
+ // running meanwhile. Tasks still running at the deadline are
626
+ // returned as running and keep going.
627
+ const startedAt = yield* Clock.currentTimeMillis;
628
+ yield* Effect.forEach(bashEntries, (entry) => Fiber.await(entry.command.fiber), { concurrency: "unbounded", discard: true }).pipe(Effect.timeoutOption(timeoutMs));
629
+ const agentResults = agentIds.length === 0
630
+ ? []
631
+ : yield* agentTasks.waitTasks(agentIds, {
632
+ timeoutMs: Math.max(0, timeoutMs - ((yield* Clock.currentTimeMillis) - startedAt)),
633
+ });
634
+ const ended = new Map([...bashEntries.map(reportBash), ...agentResults].map((task) => [
635
+ task.id,
636
+ task,
637
+ ]));
638
+ return ids.map((id) => ended.get(id));
612
639
  }),
613
- stopJob: Effect.fn("AgentTools.stopJob")(function* (input) {
614
- const id = yield* decodeStopJob(input);
615
- yield* Effect.logInfo(`Calling "stopJob"`).pipe(Effect.annotateLogs({ id }));
616
- const running = yield* findJob(id);
617
- yield* Fiber.interrupt(running.fiber);
618
- running.reported = true;
619
- return jobInfo(id, running);
640
+ stopTask: Effect.fn("AgentTools.stopTask")(function* (input) {
641
+ const id = yield* decodeStopTask(input);
642
+ yield* Effect.logInfo(`Calling "stopTask"`).pipe(Effect.annotateLogs({ id }));
643
+ const entry = yield* findTask(id);
644
+ if (entry.kind === "agent") {
645
+ const agentTasks = yield* AgentTaskExecutor;
646
+ return yield* agentTasks.stopTask(id);
647
+ }
648
+ yield* Fiber.interrupt(entry.command.fiber);
649
+ return reportBash(entry);
650
+ }),
651
+ listTasks: Effect.fn("AgentTools.listTasks")(function* () {
652
+ yield* Effect.logInfo(`Calling "listTasks"`);
653
+ const owner = yield* TaskOwner;
654
+ const bashTasks = Array.Array.from(tasks.values()).flatMap((entry) => entry.kind === "bash" && entry.owner === owner
655
+ ? [bashTask(entry)]
656
+ : []);
657
+ const agentTasks = yield* AgentTaskExecutor;
658
+ return [...bashTasks, ...(yield* agentTasks.listTasks)].toSorted((a, b) => Number(a.id) - Number(b.id));
620
659
  }),
621
660
  gh: Effect.fn("AgentTools.gh")(function* (args) {
622
661
  yield* Effect.logInfo(`Calling "gh"`).pipe(Effect.annotateLogs({ args }));
@@ -626,7 +665,17 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(Effect.gen(f
626
665
  stdin: "ignore",
627
666
  });
628
667
  const { timeout } = yield* CommandLimits;
629
- return yield* runCommand(cmd, timeout, "stop");
668
+ const running = yield* startCommand(cmd);
669
+ const exit = yield* awaitCommand(running, timeout);
670
+ if (Option.isNone(exit)) {
671
+ yield* Fiber.interrupt(running.fiber);
672
+ return yield* Effect.die(new Error(`Command timed out after ${Duration.toMillis(timeout)}ms`));
673
+ }
674
+ const exitCode = yield* exit.value;
675
+ const output = running.output();
676
+ if (exitCode === 0)
677
+ return output;
678
+ return yield* Effect.die(new Error(`Command failed with exit code ${exitCode}: ${output}`));
630
679
  }, Effect.orDie),
631
680
  webSearch: Effect.fn("AgentTools.webSearch")(function* (options) {
632
681
  yield* Effect.logInfo(`Calling "webSearch"`).pipe(Effect.annotateLogs(options));
@@ -751,31 +800,19 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(Effect.gen(f
751
800
  delegate: Effect.fn("AgentTools.delegate")(function* (options) {
752
801
  const { prompt, background = false } = yield* decodeDelegate(options);
753
802
  yield* Effect.logInfo(`Calling "delegate"`).pipe(Effect.annotateLogs({ background }));
754
- const subagents = yield* SubagentExecutor;
755
- return yield* subagents.delegate({ prompt, background });
756
- }),
757
- waitAgents: Effect.fn("AgentTools.waitAgents")(function* (input) {
758
- const ids = yield* decodeWaitAgents(input);
759
- yield* Effect.logInfo(`Calling "waitAgents"`).pipe(Effect.annotateLogs({ ids }));
760
- const subagents = yield* SubagentExecutor;
761
- return yield* subagents.waitAgents(ids);
803
+ const id = yield* registerAgentTask();
804
+ const agentTasks = yield* AgentTaskExecutor;
805
+ return yield* agentTasks.delegate({ id, prompt, background });
762
806
  }),
763
807
  messageAgent: Effect.fn("AgentTools.messageAgent")(function* (input) {
764
808
  const options = yield* decodeMessageAgent(input);
765
809
  yield* Effect.logInfo(`Calling "messageAgent"`).pipe(Effect.annotateLogs({ id: options.id }));
766
- const subagents = yield* SubagentExecutor;
767
- return yield* subagents.messageAgent(options);
768
- }),
769
- stopAgent: Effect.fn("AgentTools.stopAgent")(function* (input) {
770
- const id = yield* decodeStopAgent(input);
771
- yield* Effect.logInfo(`Calling "stopAgent"`).pipe(Effect.annotateLogs({ id }));
772
- const subagents = yield* SubagentExecutor;
773
- return yield* subagents.stopAgent(id);
774
- }),
775
- listAgents: Effect.fn("AgentTools.listAgents")(function* () {
776
- yield* Effect.logInfo(`Calling "listAgents"`);
777
- const subagents = yield* SubagentExecutor;
778
- return yield* subagents.listAgents;
810
+ const entry = yield* findTask(options.id);
811
+ if (entry.kind === "bash") {
812
+ return yield* Effect.fail(`messageAgent only addresses sub-agents, and task ${JSON.stringify(entry.id)} is a bash task. Use taskOutput or stopTask with it instead.`);
813
+ }
814
+ const agentTasks = yield* AgentTaskExecutor;
815
+ return yield* agentTasks.messageAgent(options);
779
816
  }),
780
817
  taskComplete: Effect.fn("AgentTools.taskComplete")(function* (message) {
781
818
  if (typeof message !== "string") {
@@ -806,31 +843,51 @@ const decodeParams = (schema, usage) => {
806
843
  return (input) => Effect.mapError(decode(input), () => usage);
807
844
  };
808
845
  const decodeDelegate = decodeParams(AgentTools.tools.delegate.parametersSchema, 'delegate requires an options object, for example: delegate({ prompt: "..." }) or delegate({ prompt: "...", background: true }).');
809
- const decodeWaitAgents = decodeParams(AgentTools.tools.waitAgents.parametersSchema, 'waitAgents takes an optional array of agent ids, for example: waitAgents(["3", "4"]).');
810
846
  const decodeMessageAgent = decodeParams(AgentTools.tools.messageAgent.parametersSchema, 'messageAgent requires an options object, for example: messageAgent({ id: "3", message: "..." }).');
811
- const decodeStopAgent = decodeParams(AgentTools.tools.stopAgent.parametersSchema, 'stopAgent requires an agent id, for example: stopAgent("3").');
812
- const decodeJobOutput = decodeParams(AgentTools.tools.jobOutput.parametersSchema, 'jobOutput requires a job id, for example: jobOutput("1").');
813
- const decodeStopJob = decodeParams(AgentTools.tools.stopJob.parametersSchema, 'stopJob requires a job id, for example: stopJob("1").');
814
- const jobUsage = (id) => `Use jobOutput("${id}") for its status and output, or stopJob("${id}") to stop it.`;
815
- const jobInfo = (id, running) => {
816
- const exit = running.fiber.pollUnsafe();
817
- const output = running.output();
818
- if (exit === undefined)
819
- return { id, status: "running", output };
847
+ const decodeTaskOutput = decodeParams(AgentTools.tools.taskOutput.parametersSchema, 'taskOutput requires a task id, for example: taskOutput("1").');
848
+ const decodeWaitTasks = decodeParams(AgentTools.tools.waitTasks.parametersSchema, 'waitTasks requires an options object, for example: waitTasks({ ids: ["3", "4"] }) or waitTasks({ ids: ["3"], timeoutMs: 60000 }).');
849
+ /** The caller's `bash` timeout, which also bounds `waitTasks`. */
850
+ const bashTimeoutMs = (limits) => Duration.toMillis(limits.timeout ?? defaultBashTimeout);
851
+ const decodeStopTask = decodeParams(AgentTools.tools.stopTask.parametersSchema, 'stopTask requires a task id, for example: stopTask("1").');
852
+ // Waits up to `timeout` for a command to exit. A caller that is
853
+ // interrupted first stops the command.
854
+ const awaitCommand = (command, timeout) => {
855
+ const awaited = Fiber.await(command.fiber);
856
+ return (timeout === undefined
857
+ ? Effect.asSome(awaited)
858
+ : Effect.timeoutOption(awaited, timeout)).pipe(Effect.onInterrupt(() => Fiber.interrupt(command.fiber)));
859
+ };
860
+ // A bash task's final state, once returned to the script, is not pushed.
861
+ const reportBash = (entry) => {
862
+ const task = bashTask(entry);
863
+ if (task.status !== "running")
864
+ entry.command.reported = true;
865
+ return task;
866
+ };
867
+ const bashTask = ({ id, description, command }) => {
868
+ const exit = command.fiber.pollUnsafe();
869
+ const output = command.output();
870
+ if (exit === undefined) {
871
+ return { id, kind: "bash", status: "running", description, output };
872
+ }
820
873
  if (Exit.isSuccess(exit)) {
821
874
  return {
822
875
  id,
876
+ kind: "bash",
823
877
  status: exit.value === 0 ? "completed" : "failed",
824
- exitCode: exit.value,
878
+ description,
825
879
  output,
880
+ exitCode: exit.value,
826
881
  };
827
882
  }
828
883
  if (Cause.hasInterruptsOnly(exit.cause)) {
829
- return { id, status: "stopped", output };
884
+ return { id, kind: "bash", status: "stopped", description, output };
830
885
  }
831
886
  return {
832
887
  id,
888
+ kind: "bash",
833
889
  status: "failed",
890
+ description,
834
891
  output: `${output}${output === "" ? "" : "\n"}${Cause.pretty(exit.cause)}`,
835
892
  };
836
893
  };