clanka 0.8.5 → 0.9.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 (92) hide show
  1. package/dist/Acp.d.ts.map +1 -1
  2. package/dist/Acp.js +9 -3
  3. package/dist/Acp.js.map +1 -1
  4. package/dist/Acp.test.js +72 -1
  5. package/dist/Acp.test.js.map +1 -1
  6. package/dist/AcpImage.test.js +1 -0
  7. package/dist/AcpImage.test.js.map +1 -1
  8. package/dist/Agent.d.ts +65 -8
  9. package/dist/Agent.d.ts.map +1 -1
  10. package/dist/Agent.js +481 -113
  11. package/dist/Agent.js.map +1 -1
  12. package/dist/Agent.test.js +77 -4
  13. package/dist/Agent.test.js.map +1 -1
  14. package/dist/AgentCallerConfig.test.d.ts +2 -0
  15. package/dist/AgentCallerConfig.test.d.ts.map +1 -0
  16. package/dist/AgentCallerConfig.test.js +327 -0
  17. package/dist/AgentCallerConfig.test.js.map +1 -0
  18. package/dist/AgentExecutor.d.ts +254 -54
  19. package/dist/AgentExecutor.d.ts.map +1 -1
  20. package/dist/AgentExecutor.js +416 -99
  21. package/dist/AgentExecutor.js.map +1 -1
  22. package/dist/AgentExecutor.test.js +201 -31
  23. package/dist/AgentExecutor.test.js.map +1 -1
  24. package/dist/AgentExecutorImage.test.js +2 -1
  25. package/dist/AgentExecutorImage.test.js.map +1 -1
  26. package/dist/AgentImage.test.js +5 -1
  27. package/dist/AgentImage.test.js.map +1 -1
  28. package/dist/AgentOutput.d.ts +54 -2
  29. package/dist/AgentOutput.d.ts.map +1 -1
  30. package/dist/AgentOutput.js +52 -0
  31. package/dist/AgentOutput.js.map +1 -1
  32. package/dist/AgentSkills.d.ts +22 -0
  33. package/dist/AgentSkills.d.ts.map +1 -1
  34. package/dist/AgentSkills.js +36 -0
  35. package/dist/AgentSkills.js.map +1 -1
  36. package/dist/AgentSkills.test.js +2 -0
  37. package/dist/AgentSkills.test.js.map +1 -1
  38. package/dist/AgentSubagents.test.d.ts +2 -0
  39. package/dist/AgentSubagents.test.d.ts.map +1 -0
  40. package/dist/AgentSubagents.test.js +452 -0
  41. package/dist/AgentSubagents.test.js.map +1 -0
  42. package/dist/AgentTools.d.ts +356 -14
  43. package/dist/AgentTools.d.ts.map +1 -1
  44. package/dist/AgentTools.js +213 -34
  45. package/dist/AgentTools.js.map +1 -1
  46. package/dist/CompactionTransport.test.js +1 -1
  47. package/dist/CompactionTransport.test.js.map +1 -1
  48. package/dist/OutputFormatter.d.ts.map +1 -1
  49. package/dist/OutputFormatter.js +16 -2
  50. package/dist/OutputFormatter.js.map +1 -1
  51. package/dist/ToolkitRenderer.d.ts.map +1 -1
  52. package/dist/ToolkitRenderer.js +6 -1
  53. package/dist/ToolkitRenderer.js.map +1 -1
  54. package/dist/bin/{Effect-BEUn4I5E.mjs → Effect-2jPlJ8eu.mjs} +399 -207
  55. package/dist/bin/Effect-2jPlJ8eu.mjs.map +1 -0
  56. package/dist/bin/{McpClient-C0FVuDj2.mjs → McpClient-1W508adc.mjs} +4 -4
  57. package/dist/bin/{McpClient-C0FVuDj2.mjs.map → McpClient-1W508adc.mjs.map} +1 -1
  58. package/dist/bin/{OutputFormatter-DffD5oxX.mjs → OutputFormatter-DXXKo4E8.mjs} +16 -5
  59. package/dist/bin/{OutputFormatter-DffD5oxX.mjs.map → OutputFormatter-DXXKo4E8.mjs.map} +1 -1
  60. package/dist/bin/{Schema-CjUGw2Xh.mjs → Schema-D-7VuCiC.mjs} +640 -87
  61. package/dist/bin/Schema-D-7VuCiC.mjs.map +1 -0
  62. package/dist/bin/{SemanticSearch-CFB73IPb.mjs → SemanticSearch-Cb8aqvGv.mjs} +89 -56
  63. package/dist/bin/SemanticSearch-Cb8aqvGv.mjs.map +1 -0
  64. package/dist/bin/{Stream-Cu6P7ZHo.mjs → Stream-DEu2tfCV.mjs} +81 -51
  65. package/dist/bin/Stream-DEu2tfCV.mjs.map +1 -0
  66. package/dist/bin/cli.mjs +3632 -5538
  67. package/dist/bin/cli.mjs.map +1 -1
  68. package/dist/bin/{turndown.cjs-usmCKZ4b.mjs → turndown.cjs-DK29wZw3.mjs} +2 -2
  69. package/dist/bin/{turndown.cjs-usmCKZ4b.mjs.map → turndown.cjs-DK29wZw3.mjs.map} +1 -1
  70. package/package.json +7 -7
  71. package/src/Acp.test.ts +121 -2
  72. package/src/Acp.ts +10 -3
  73. package/src/AcpImage.test.ts +1 -0
  74. package/src/Agent.test.ts +100 -3
  75. package/src/Agent.ts +752 -142
  76. package/src/AgentCallerConfig.test.ts +514 -0
  77. package/src/AgentExecutor.test.ts +297 -37
  78. package/src/AgentExecutor.ts +707 -159
  79. package/src/AgentExecutorImage.test.ts +2 -1
  80. package/src/AgentImage.test.ts +11 -2
  81. package/src/AgentOutput.ts +74 -1
  82. package/src/AgentSkills.test.ts +2 -0
  83. package/src/AgentSkills.ts +43 -0
  84. package/src/AgentSubagents.test.ts +758 -0
  85. package/src/AgentTools.ts +376 -52
  86. package/src/CompactionTransport.test.ts +1 -1
  87. package/src/OutputFormatter.ts +16 -2
  88. package/src/ToolkitRenderer.ts +7 -1
  89. package/dist/bin/Effect-BEUn4I5E.mjs.map +0 -1
  90. package/dist/bin/Schema-CjUGw2Xh.mjs.map +0 -1
  91. package/dist/bin/SemanticSearch-CFB73IPb.mjs.map +0 -1
  92. package/dist/bin/Stream-Cu6P7ZHo.mjs.map +0 -1
package/dist/Agent.js CHANGED
@@ -4,6 +4,7 @@
4
4
  import * as Model from "effect/ai/Model";
5
5
  import * as AgentExecutor from "./AgentExecutor.js";
6
6
  import * as AgentSkills from "./AgentSkills.js";
7
+ import { ToolkitRenderer } from "./ToolkitRenderer.js";
7
8
  import { stripWrappingCodeFence } from "./ScriptExtraction.js";
8
9
  import * as Image from "./Image.js";
9
10
  import * as Prompt from "effect/ai/Prompt";
@@ -28,8 +29,11 @@ import * as Cause from "effect/Cause";
28
29
  import * as Latch from "effect/Latch";
29
30
  import * as Clock from "effect/Clock";
30
31
  import * as Exit from "effect/Exit";
32
+ import * as Deferred from "effect/Deferred";
33
+ import * as Fiber from "effect/Fiber";
34
+ import * as Scope from "effect/Scope";
31
35
  import * as Compaction from "./Compaction.js";
32
- import { ScriptEnd, ScriptOutput, SubagentComplete, SubagentPart, SubagentStart, AgentFinished, ReasoningStart, ReasoningDelta, ReasoningEnd, Usage, ErrorRetry, ScriptStart, ScriptDelta, AgentStart, ExecuteOutputCapped, CompactionStarted, CompactionEnded, } from "./AgentOutput.js";
36
+ import { ScriptEnd, ScriptOutput, SubagentComplete, SubagentPart, SubagentStart, AgentFinished, ReasoningStart, ReasoningDelta, ReasoningEnd, Usage, ErrorRetry, ScriptStart, ScriptDelta, AgentStart, ExecuteOutputCapped, CompactionStarted, CompactionEnded, HistoryAppended, HistoryReplaced, RetriesExhausted, } from "./AgentOutput.js";
33
37
  /**
34
38
  * @since 1.0.0
35
39
  * @category Models
@@ -44,21 +48,29 @@ export const Agent = Context.Service("clanka/Agent");
44
48
  * @since 1.0.0
45
49
  * @category Constructors
46
50
  */
47
- export const make = Effect.gen(function* () {
51
+ export const makeWith = Effect.fnUntraced(function* (options) {
48
52
  const executor = yield* AgentExecutor.AgentExecutor;
49
53
  const singleTool = yield* SingleTools.pipe(Effect.provide(SingleToolHandlers));
50
54
  const capabilities = yield* executor.capabilities;
51
- const pendingMessages = new Set();
52
- const agentsMd = Option.map(capabilities.agentsMd, (content) => `# AGENTS.md
53
-
54
- The following instructions are from ./AGENTS.md in the current directory.
55
- You do not need to read this file again.
56
-
57
- **ALWAYS follow these instructions when completing tasks**:
58
-
59
- <!-- AGENTS.md start -->
60
- ${content}
61
- <!-- AGENTS.md end -->`);
55
+ const loopTools = yield* makeLoopTools({
56
+ loopTools: options.loopTools,
57
+ skills: options.skills,
58
+ executorTools: capabilities.tools,
59
+ });
60
+ const promptTools = {
61
+ toolsDts: loopTools.dts === ""
62
+ ? capabilities.toolsDts
63
+ : `${capabilities.toolsDts}\n\n${loopTools.dts}`,
64
+ offers: (name) => capabilities.tools.includes(name),
65
+ skillsCatalog: options.skills === undefined
66
+ ? AgentSkills.renderCatalog(capabilities.skills)
67
+ : AgentSkills.renderProvidedCatalog(options.skills),
68
+ };
69
+ // Steering messages for the root agent. Sub-agents get their own mailbox.
70
+ const rootMailbox = makeMailbox();
71
+ const agentsMd = options.instructions === undefined
72
+ ? Option.map(capabilities.agentsMd, renderAgentsMd)
73
+ : Option.map(options.instructions, renderInstructions);
62
74
  let agentCounter = 0;
63
75
  const outputBuffer = new Map();
64
76
  let currentOutputAgent = null;
@@ -66,10 +78,12 @@ ${content}
66
78
  const spawn = Effect.fnUntraced(function* (opts) {
67
79
  const agentId = opts.agentId;
68
80
  const ai = yield* LanguageModel.LanguageModel;
69
- const subagentModel = yield* SubagentModel;
81
+ // Without a SubagentModel, sub-agents run on this agent's model.
82
+ const subagentModel = yield* Effect.serviceOption(SubagentModel);
70
83
  const modelConfig = yield* AgentModelConfig;
71
84
  const conversationMode = yield* ConversationMode;
72
85
  const turnTimeout = yield* TurnTimeout;
86
+ const maxRetries = yield* MaxRetries;
73
87
  let finalSummary = Option.none();
74
88
  // `inputTokens.total` from the most recent finish part; undefined until
75
89
  // the first response and after every compaction.
@@ -86,10 +100,31 @@ ${content}
86
100
  let outputTokens = 0;
87
101
  let cacheRead = 0;
88
102
  let cacheWrite = 0;
89
- const prompt = opts.disableHistory ? MutableRef.make(Prompt.empty) : history;
103
+ const prompt = opts.history;
104
+ const mailbox = opts.mailbox;
105
+ // Every change to `prompt` after the system message is set goes through
106
+ // these two, so the history events always add up to the history.
107
+ const appendHistory = (input) => {
108
+ MutableRef.update(prompt, Prompt.concat(input));
109
+ if (!opts.historyEvents)
110
+ return;
111
+ const messages = input.content.filter((message) => message.role !== "system");
112
+ if (messages.length > 0) {
113
+ Queue.offerUnsafe(output, new HistoryAppended({ messages }));
114
+ }
115
+ };
116
+ const replaceHistory = (next) => {
117
+ MutableRef.set(prompt, next);
118
+ if (!opts.historyEvents)
119
+ return;
120
+ Queue.offerUnsafe(output, new HistoryReplaced({
121
+ messages: next.content.filter((message) => message.role !== "system"),
122
+ }));
123
+ };
124
+ // Committed now, emitted after AgentStart below.
90
125
  MutableRef.update(prompt, Prompt.concat(opts.prompt));
91
126
  const generateSystem = typeof opts.system === "function" ? opts.system : defaultSystem;
92
- const toolInstructions = generateSystemTools(capabilities, conversationMode);
127
+ const toolInstructions = generateSystemTools(promptTools, conversationMode);
93
128
  let system = generateSystem({
94
129
  toolInstructions,
95
130
  agentsMd: Option.getOrElse(agentsMd, () => ""),
@@ -98,6 +133,10 @@ ${content}
98
133
  system += `\n${opts.system}\n`;
99
134
  }
100
135
  function maybeSend(options) {
136
+ if (!opts.display) {
137
+ Queue.offerUnsafe(output, options.part);
138
+ return;
139
+ }
101
140
  if (currentOutputAgent === null || currentOutputAgent === opts.agentId) {
102
141
  Queue.offerUnsafe(output, options.part);
103
142
  if (options.acquire) {
@@ -126,42 +165,212 @@ ${content}
126
165
  state.push(options.part);
127
166
  return;
128
167
  }
129
- const spawnSubagent = Effect.fnUntraced(function* (prompt) {
130
- let id = agentCounter++;
168
+ // Sub-agents. Every agent tracks only the children it spawned. They are
169
+ // forked into a scope owned by this run, so none of them outlive it.
170
+ const runScope = yield* Scope.make();
171
+ const runContext = yield* Effect.context();
172
+ const provideSubagentModel = (effect) => Option.match(subagentModel, {
173
+ onNone: () => effect,
174
+ onSome: (model) => effect.pipe(Effect.provide(model), Effect.provideService(SubagentModel, model)),
175
+ });
176
+ const children = new Map();
177
+ // Finished turns waiting to be pushed to the model.
178
+ const completions = [];
179
+ let wakeUp;
180
+ const notify = () => {
181
+ const resume = wakeUp;
182
+ wakeUp = undefined;
183
+ resume?.();
184
+ };
185
+ mailbox.notify = notify;
186
+ const runningChildren = () => Array.Array.from(children.values()).filter((child) => child.turn.status === "running");
187
+ const hasUndelivered = () => completions.some((turn) => !turn.delivered);
188
+ const finishTurn = (turn, exit) => Effect.sync(() => {
189
+ if (Exit.isSuccess(exit)) {
190
+ turn.status = "completed";
191
+ turn.output = exit.value;
192
+ }
193
+ else if (Cause.hasInterruptsOnly(exit.cause)) {
194
+ turn.status = "cancelled";
195
+ }
196
+ else {
197
+ turn.status = "failed";
198
+ turn.output = causeMessage(exit.cause);
199
+ }
200
+ Queue.offerUnsafe(output, new SubagentComplete({
201
+ id: turn.agentId,
202
+ summary: turn.output ?? "",
203
+ status: turn.status,
204
+ }));
205
+ if (!turn.delivered) {
206
+ completions.push(turn);
207
+ }
208
+ Deferred.doneUnsafe(turn.done, Effect.void);
209
+ notify();
210
+ });
211
+ // Runs the child's current turn in its own fiber, with this run's
212
+ // services and the sub-agent model.
213
+ const startTurn = Effect.fnUntraced(function* (options) {
214
+ const { child } = options;
215
+ const turn = child.turn;
216
+ const display = opts.display && !options.background;
131
217
  const stream = spawn({
132
- agentId: id,
133
- prompt: Prompt.make(prompt),
218
+ agentId: child.id,
219
+ prompt: Prompt.make(options.prompt),
134
220
  system: opts.system,
135
- disableHistory: true,
136
- });
137
- const provider = yield* Model.ProviderName;
138
- const model = yield* Model.ModelName;
139
- maybeSend({
140
- agentId: opts.agentId,
141
- part: new SubagentStart({ id, prompt, model, provider }),
142
- release: true,
221
+ history: child.history,
222
+ mailbox: child.mailbox,
223
+ display,
224
+ historyEvents: false,
143
225
  });
144
- return yield* stream.pipe(Stream.runForEachArray((parts) => {
145
- for (const part of parts) {
146
- switch (part._tag) {
147
- case "AgentStart":
148
- break;
149
- case "SubagentStart":
150
- case "SubagentComplete":
151
- case "SubagentPart":
152
- Queue.offerUnsafe(output, part);
153
- break;
154
- default:
155
- Queue.offerUnsafe(output, new SubagentPart({ id, part }));
156
- break;
226
+ turn.fiber = yield* Effect.gen(function* () {
227
+ maybeSend({
228
+ agentId: opts.agentId,
229
+ part: new SubagentStart({
230
+ id: child.id,
231
+ prompt: options.label,
232
+ model: yield* Model.ModelName,
233
+ provider: yield* Model.ProviderName,
234
+ background: options.background,
235
+ }),
236
+ release: true,
237
+ });
238
+ return yield* stream.pipe(Stream.runForEachArray((parts) => {
239
+ for (const part of parts) {
240
+ switch (part._tag) {
241
+ case "AgentStart":
242
+ case "HistoryAppended":
243
+ case "HistoryReplaced":
244
+ break;
245
+ case "SubagentStart":
246
+ case "SubagentComplete":
247
+ Queue.offerUnsafe(output, part);
248
+ break;
249
+ default:
250
+ // Background agents only report start and completion.
251
+ if (!display)
252
+ break;
253
+ Queue.offerUnsafe(output, part._tag === "SubagentPart"
254
+ ? part
255
+ : new SubagentPart({ id: child.id, part }));
256
+ }
157
257
  }
258
+ return Effect.void;
259
+ }), Effect.as(""), Effect.catchTag("AgentFinished", (finished) => Effect.succeed(finished.summary)));
260
+ }).pipe(Effect.onExit((exit) => finishTurn(turn, exit)), provideSubagentModel, Effect.provideContext(runContext), Effect.forkIn(runScope, { startImmediately: true }));
261
+ });
262
+ // Leaves `output` out when unset, so the result stays JSON for RPC.
263
+ const childResult = ({ id, turn }) => turn.output === undefined
264
+ ? { id: String(id), status: turn.status }
265
+ : { id: String(id), status: turn.status, output: turn.output };
266
+ const lookupChild = (id) => Effect.suspend(() => {
267
+ const child = children.get(id);
268
+ return child
269
+ ? Effect.succeed(child)
270
+ : Effect.fail(`Unknown agent id ${JSON.stringify(id)}. You can only address agents you started; call listAgents() to see them.`);
271
+ });
272
+ const subagents = {
273
+ delegate: Effect.fnUntraced(function* ({ prompt, background }) {
274
+ const agentId = agentCounter++;
275
+ const child = {
276
+ id: agentId,
277
+ prompt,
278
+ history: MutableRef.make(Prompt.empty),
279
+ mailbox: makeMailbox(),
280
+ turn: makeTurn(agentId, background),
281
+ };
282
+ const id = String(child.id);
283
+ children.set(id, child);
284
+ const turn = child.turn;
285
+ yield* startTurn({
286
+ child,
287
+ label: prompt,
288
+ prompt: `You have been asked using the "delegate" function to complete the following task. Try to avoid using the "delegate" function yourself unless strictly necessary:
289
+
290
+ ${prompt}`,
291
+ background,
292
+ });
293
+ if (background) {
294
+ return { id, status: "running" };
158
295
  }
159
- return Effect.void;
160
- }), Effect.as(""), Effect.catchTag("AgentFinished", (finished) => {
161
- Queue.offerUnsafe(output, new SubagentComplete({ id, summary: finished.summary }));
162
- return Effect.succeed(finished.summary);
163
- }), Effect.orDie);
164
- }, Effect.provide(subagentModel), Effect.provideService(SubagentModel, subagentModel));
296
+ // Foreground: a failure crashes the script, as before. Interrupting
297
+ // the script stops the agent.
298
+ yield* Deferred.await(turn.done).pipe(Effect.onInterrupt(() => Fiber.interrupt(turn.fiber)));
299
+ if (turn.status !== "completed") {
300
+ return yield* Effect.die(new Error(`Sub-agent ${child.id} ${turn.status}${turn.output ? `: ${turn.output}` : ""}`));
301
+ }
302
+ return { id, status: "completed", output: turn.output ?? "" };
303
+ }),
304
+ waitAgents: Effect.fnUntraced(function* (ids) {
305
+ const targets = ids === undefined
306
+ ? Array.Array.from(children.values())
307
+ : yield* Effect.forEach(ids, lookupChild);
308
+ // A turn started by messageAgent while waiting is waited for too.
309
+ while (true) {
310
+ const running = targets.find((child) => child.turn.status === "running");
311
+ if (!running)
312
+ break;
313
+ yield* Deferred.await(running.turn.done);
314
+ }
315
+ return targets.map((child) => {
316
+ child.turn.delivered = true;
317
+ return childResult(child);
318
+ });
319
+ }),
320
+ messageAgent: Effect.fnUntraced(function* ({ id, message }) {
321
+ const child = yield* lookupChild(id);
322
+ if (child.turn.status === "running") {
323
+ child.mailbox.messages.add({ message, resume: () => { } });
324
+ child.mailbox.notify();
325
+ return childResult(child);
326
+ }
327
+ child.turn = makeTurn(child.id, true);
328
+ yield* startTurn({
329
+ child,
330
+ prompt: message,
331
+ label: message,
332
+ background: true,
333
+ });
334
+ return childResult(child);
335
+ }),
336
+ stopAgent: Effect.fnUntraced(function* (id) {
337
+ const child = yield* lookupChild(id);
338
+ const turn = child.turn;
339
+ turn.delivered = true;
340
+ if (turn.status === "running") {
341
+ yield* Fiber.interrupt(turn.fiber);
342
+ }
343
+ return childResult(child);
344
+ }),
345
+ listAgents: Effect.sync(() => Array.Array.from(children.values(), (child) => ({
346
+ id: String(child.id),
347
+ status: child.turn.status,
348
+ prompt: child.prompt,
349
+ }))),
350
+ };
351
+ const onTaskComplete = (summary) => Effect.suspend(() => {
352
+ const running = runningChildren();
353
+ if (running.length > 0) {
354
+ const ids = running.map((child) => JSON.stringify(String(child.id)));
355
+ return Effect.fail(`taskComplete was rejected: sub-agents ${ids.join(", ")} are still running. Call waitAgents() to wait for them, or stopAgent(id) to stop them, before calling taskComplete.`);
356
+ }
357
+ finalSummary = Option.some(summary);
358
+ return Effect.void;
359
+ });
360
+ // Blocks an idle conversation turn until a child finishes or a message
361
+ // arrives.
362
+ const waitForActivity = Effect.callback((resume) => {
363
+ if (mailbox.messages.size > 0 ||
364
+ hasUndelivered() ||
365
+ runningChildren().length === 0) {
366
+ resume(Effect.void);
367
+ return;
368
+ }
369
+ wakeUp = () => resume(Effect.void);
370
+ return Effect.sync(() => {
371
+ wakeUp = undefined;
372
+ });
373
+ });
165
374
  // Turn timeout
166
375
  const clock = yield* Clock.Clock;
167
376
  const turnTimeoutMs = Duration.toMillis(turnTimeout);
@@ -204,7 +413,7 @@ ${content}
204
413
  let tokensBefore;
205
414
  let tokensAfter;
206
415
  if (Option.isSome(result)) {
207
- MutableRef.set(prompt, result.value.prompt);
416
+ replaceHistory(result.value.prompt);
208
417
  lastContextTokens = undefined;
209
418
  tokensBefore = result.value.tokensBefore;
210
419
  tokensAfter = result.value.tokensAfter;
@@ -224,13 +433,12 @@ ${content}
224
433
  const normalizedScript = stripWrappingCodeFence(script);
225
434
  const output = yield* pipe(executor.execute({
226
435
  script: normalizedScript,
227
- onSubagent: spawnSubagent,
228
- onTaskComplete: (summary) => Effect.sync(() => {
229
- finalSummary = Option.some(summary);
230
- }),
436
+ subagents,
437
+ onTaskComplete,
231
438
  onImage: (image) => Effect.sync(() => {
232
439
  pendingImages.push(image);
233
440
  }),
441
+ loopTools: loopTools.handlers,
234
442
  }), Stream.mkString);
235
443
  // Always-on cap on what enters the Prompt. The ScriptOutput event keeps
236
444
  // the full output for display; the formatter applies its own truncation.
@@ -250,21 +458,51 @@ ${content}
250
458
  if (!modelConfig.systemPromptTransform) {
251
459
  MutableRef.update(prompt, Prompt.setSystem(system));
252
460
  }
461
+ yield* Queue.offer(output, new AgentStart({
462
+ id: opts.agentId,
463
+ prompt: opts.prompt,
464
+ provider: yield* Model.ProviderName,
465
+ model: yield* Model.ModelName,
466
+ }));
467
+ if (opts.historyEvents) {
468
+ const messages = opts.prompt.content.filter((message) => message.role !== "system");
469
+ if (messages.length > 0) {
470
+ yield* Queue.offer(output, new HistoryAppended({ messages }));
471
+ }
472
+ }
253
473
  yield* Effect.gen(function* () {
254
474
  while (true) {
255
475
  if (Option.isSome(finalSummary)) {
256
476
  yield* Queue.fail(output, new AgentFinished({ summary: finalSummary.value }));
257
477
  return;
258
478
  }
259
- if (pendingMessages.size > 0) {
260
- MutableRef.update(prompt, Prompt.concat(Array.Array.from(pendingMessages, ({ message, resume }) => {
479
+ if (mailbox.messages.size > 0) {
480
+ appendHistory(Prompt.make(Array.Array.from(mailbox.messages, ({ message, resume }) => {
261
481
  resume(Effect.void);
262
482
  return {
263
483
  role: "user",
264
484
  content: message,
265
485
  };
266
486
  })));
267
- pendingMessages.clear();
487
+ mailbox.messages.clear();
488
+ }
489
+ // Completion pushes from background sub-agents. These have their own
490
+ // queue: the steering path above cuts the model stream short.
491
+ if (completions.length > 0) {
492
+ const pushes = completions.splice(0).filter((turn) => {
493
+ if (turn.delivered)
494
+ return false;
495
+ turn.delivered = true;
496
+ return true;
497
+ });
498
+ if (pushes.length > 0) {
499
+ appendHistory(Prompt.make(pushes.map((turn) => ({
500
+ role: "user",
501
+ content: `<subagent id="${turn.agentId}" status="${turn.status}">
502
+ ${Compaction.capOutput(turn.output ?? "").output}
503
+ </subagent>`,
504
+ }))));
505
+ }
268
506
  }
269
507
  // Threshold compaction before the next model call
270
508
  yield* compactWithEvents("threshold", Compaction.compactIfNeeded({
@@ -281,6 +519,19 @@ ${content}
281
519
  let reasoningStarted = false;
282
520
  let hadReasoningDelta = false;
283
521
  let hadToolCall = false;
522
+ // Retries of this model call so far, and the error that used up the
523
+ // last one.
524
+ let retries = 0;
525
+ let exhaustedBy;
526
+ const retryOrExhaust = (error) => {
527
+ if (retries >= maxRetries) {
528
+ exhaustedBy = error;
529
+ return false;
530
+ }
531
+ retries++;
532
+ maybeSend({ agentId, part: new ErrorRetry({ error }) });
533
+ return true;
534
+ };
284
535
  const runModel = pipe(Stream.suspend(() => ai.streamText({
285
536
  prompt: sendImages
286
537
  ? prompt.current
@@ -288,7 +539,7 @@ ${content}
288
539
  toolkit: singleTool,
289
540
  })), Stream.takeUntil((part) => {
290
541
  if ((part.type === "text-end" || part.type === "reasoning-end") &&
291
- pendingMessages.size > 0) {
542
+ mailbox.messages.size > 0) {
292
543
  return true;
293
544
  }
294
545
  return false;
@@ -367,32 +618,23 @@ ${content}
367
618
  const attempt = pipe(runModel, Effect.raceFirst(turnTimeoutEffect), Effect.retry({
368
619
  while(err) {
369
620
  if (err._tag === "TimeoutError") {
370
- maybeSend({
371
- agentId,
372
- part: new ErrorRetry({
373
- error: AiError.make({
374
- module: "clanka/Agent",
375
- method: "send",
376
- reason: new AiError.UnknownError({
377
- description: "TurnTimeout was reached",
378
- }),
379
- }),
380
- }),
381
- });
382
621
  discardAttempt();
383
- return true;
622
+ return retryOrExhaust(turnTimeoutError);
384
623
  }
385
624
  // Never retry a context-length error as is: the overflow
386
625
  // handler below compacts first.
387
626
  if (Compaction.isContextLengthError(err))
388
627
  return false;
389
628
  if (err.isRetryable) {
390
- maybeSend({ agentId, part: new ErrorRetry({ error: err }) });
629
+ if (!retryOrExhaust(err)) {
630
+ discardAttempt();
631
+ return false;
632
+ }
391
633
  switch (err.reason._tag) {
392
634
  case "ToolNotFoundError":
393
635
  case "InvalidOutputError": {
394
636
  const toAppend = Prompt.fromResponseParts(response).pipe(Prompt.concat(`There was an error, please try again using the "execute" tool:\n\n${Cause.pretty(Cause.fail(err))}`));
395
- MutableRef.update(prompt, Prompt.concat(toAppend));
637
+ appendHistory(toAppend);
396
638
  }
397
639
  }
398
640
  }
@@ -400,10 +642,11 @@ ${content}
400
642
  return err.isRetryable;
401
643
  },
402
644
  schedule: retryPolicy,
403
- }), Effect.catchTag("TimeoutError", Effect.die));
645
+ }), Effect.catchIf(() => exhaustedBy !== undefined, () => Effect.fail(new RetriesExhausted({ retries, error: exhaustedBy }))), Effect.catchTag("TimeoutError", Effect.die));
404
646
  // Unsupported images: drop them from the request and retry once.
405
647
  // The images stay in the Prompt with an omitted note in their place.
406
- const attemptWithImageFallback = attempt.pipe(Effect.catchIf((err) => sendImages &&
648
+ const attemptWithImageFallback = attempt.pipe(Effect.catchIf((err) => err._tag === "AiError" &&
649
+ sendImages &&
407
650
  Image.hasImages(prompt.current) &&
408
651
  Image.isUnsupportedImageError(err), (err) => {
409
652
  sendImages = false;
@@ -412,7 +655,7 @@ ${content}
412
655
  return attempt;
413
656
  }));
414
657
  // Overflow: compact once, retry the attempt once, then fail.
415
- yield* attemptWithImageFallback.pipe(Effect.catchIf((err) => Compaction.isContextLengthError(err), (err) => Effect.gen(function* () {
658
+ yield* attemptWithImageFallback.pipe(Effect.catchIf((err) => err._tag === "AiError" && Compaction.isContextLengthError(err), (err) => Effect.gen(function* () {
416
659
  discardAttempt();
417
660
  const compacted = yield* compactWithEvents("overflow", Compaction.compact({
418
661
  prompt: prompt.current,
@@ -426,13 +669,19 @@ ${content}
426
669
  ? yield* attemptWithImageFallback
427
670
  : yield* err;
428
671
  })));
429
- MutableRef.update(prompt, Prompt.concat(Prompt.fromResponseParts(response)));
672
+ appendHistory(Prompt.fromResponseParts(response));
430
673
  if (pendingImages.length > 0) {
431
674
  // After the tool result, so call / result pairing stays intact.
432
- MutableRef.update(prompt, Prompt.concat(Prompt.fromMessages([Image.userMessage(pendingImages)])));
675
+ appendHistory(Prompt.fromMessages([Image.userMessage(pendingImages)]));
433
676
  pendingImages.length = 0;
434
677
  }
435
- if (conversationMode && !hadToolCall && pendingMessages.size === 0) {
678
+ if (conversationMode && !hadToolCall && mailbox.messages.size === 0) {
679
+ // The run is not over while children are running or their results
680
+ // have not been seen yet.
681
+ if (runningChildren().length > 0 || hasUndelivered()) {
682
+ yield* waitForActivity;
683
+ continue;
684
+ }
436
685
  finalSummary = Option.some(responseToSummary(response));
437
686
  }
438
687
  }
@@ -440,13 +689,7 @@ ${content}
440
689
  maybeSend({ agentId, part: new ScriptStart() });
441
690
  maybeSend({ agentId, part: new ScriptDelta({ delta: script }) });
442
691
  return executeScript(script);
443
- }), Effect.catchCause((cause) => Queue.failCause(output, cause)), Effect.forkScoped);
444
- yield* Queue.offer(output, new AgentStart({
445
- id: opts.agentId,
446
- prompt: opts.prompt,
447
- provider: yield* Model.ProviderName,
448
- model: yield* Model.ModelName,
449
- }));
692
+ }), Effect.ensuring(Scope.close(runScope, Exit.void)), Effect.catchCause((cause) => Queue.failCause(output, cause)), Effect.forkScoped);
450
693
  return Stream.fromQueue(output);
451
694
  }, Stream.unwrap);
452
695
  const sendLock = Semaphore.makeUnsafe(1);
@@ -457,40 +700,105 @@ ${content}
457
700
  agentId: agentCounter++,
458
701
  prompt: Prompt.make(options.prompt),
459
702
  system: options.system,
703
+ history,
704
+ mailbox: rootMailbox,
705
+ display: true,
706
+ historyEvents: true,
460
707
  }).pipe(Stream.broadcast({ capacity: "unbounded", replay: 1 }), sendLock.withPermit),
461
708
  steer: (message) => Effect.callback((resume) => {
462
709
  const entry = { message, resume };
463
- pendingMessages.add(entry);
464
- return Effect.sync(() => pendingMessages.delete(entry));
710
+ rootMailbox.messages.add(entry);
711
+ rootMailbox.notify();
712
+ return Effect.sync(() => rootMailbox.messages.delete(entry));
465
713
  }),
466
714
  });
467
715
  });
716
+ /**
717
+ * Create an Agent with every executor tool, the executor's `AGENTS.md` and
718
+ * skills, and no loop-side tools.
719
+ *
720
+ * @since 1.0.0
721
+ * @category Constructors
722
+ */
723
+ export const make = makeWith({});
724
+ const makeMailbox = () => ({
725
+ messages: new Set(),
726
+ notify: () => { },
727
+ });
728
+ const makeTurn = (agentId, background) => ({
729
+ agentId,
730
+ status: "running",
731
+ output: undefined,
732
+ // Foreground results go straight back to the script.
733
+ delivered: !background,
734
+ done: Deferred.makeUnsafe(),
735
+ fiber: undefined,
736
+ });
737
+ const causeMessage = (cause) => errorMessage(Cause.squash(cause));
738
+ const turnTimeoutError = AiError.make({
739
+ module: "clanka/Agent",
740
+ method: "send",
741
+ reason: new AiError.UnknownError({
742
+ description: "TurnTimeout was reached",
743
+ }),
744
+ });
468
745
  const retryPolicy = Schedule.min([
469
746
  Schedule.exponential(100, 1.5),
470
747
  Schedule.spaced(5000),
471
748
  ]).pipe(Schedule.jittered);
749
+ const renderAgentsMd = (content) => `# AGENTS.md
750
+
751
+ The following instructions are from ./AGENTS.md in the current directory.
752
+ You do not need to read this file again.
753
+
754
+ **ALWAYS follow these instructions when completing tasks**:
755
+
756
+ <!-- AGENTS.md start -->
757
+ ${content}
758
+ <!-- AGENTS.md end -->`;
759
+ const renderInstructions = (content) => `# Project instructions
760
+
761
+ **ALWAYS follow these instructions when completing tasks**:
762
+
763
+ <!-- instructions start -->
764
+ ${content}
765
+ <!-- instructions end -->`;
472
766
  const defaultSystem = (options) => `You are a world-class software engineer: precise and efficient.
473
767
 
474
768
  ${options.toolInstructions}
475
769
 
476
770
  ${options.agentsMd}
477
771
  `;
478
- const generateSystemTools = (capabilities, conversationMode) => `YOU ONLY HAVE ONE TOOL AVAILABLE: "execute", to run javascript code to do your work.
772
+ const when = (condition, text) => (condition ? text : "");
773
+ const generateSystemTools = (tools, conversationMode) => `YOU ONLY HAVE ONE TOOL AVAILABLE: "execute", to run javascript code to do your work.
479
774
 
480
775
  - Use \`console.log\` to print any output you need.
481
- - Use top level await.${capabilities.supportsSearch
482
- ? `
483
- - Prefer using the "search" function over "rg", unless you are targeting specific files or patterns.`
484
- : ""}
485
- - You can add / update / remove multiple files in one go with "applyPatch".
486
- - Avoid passing scripts into the "bash" function, and instead write javascript.
776
+ - Use top level await.${when(tools.offers("search") && tools.offers("rg"), `
777
+ - Prefer using the "search" function over "rg", unless you are targeting specific files or patterns.`)}${when(tools.offers("applyPatch"), `
778
+ - You can add / update / remove multiple files in one go with "applyPatch".${when(tools.offers("writeFile"), ` Prefer it over "writeFile" to update existing files.`)}`)}${when(tools.offers("bash"), `
779
+ - Avoid passing scripts into the "bash" function, and instead write javascript.`)}
487
780
  - Variables are not shared between executions.
488
- - Do not use \`require\`, \`import\`, \`process\`, or any other Node.js apis.${conversationMode
489
- ? ""
490
- : `
781
+ - Do not use \`require\`, \`import\`, \`process\`, or any other Node.js apis.${when(tools.offers("delegate"), `
782
+ - "delegate" runs a sub-agent and waits for it. Pass \`background: true\` to keep working while it runs: its result is sent to you later as a \`<subagent id="..." status="...">\` message.${when(tools.offers("waitAgents"), ` Use "waitAgents" to wait for the returned id.`)}${when(tools.offers("messageAgent"), ` Use "messageAgent" to send a message to the returned id.`)}${when(tools.offers("stopAgent"), ` Use "stopAgent" to stop the returned id.`)}${when(tools.offers("listAgents"), ` "listAgents" shows the agents you started.`)}`)}${when(!conversationMode, `
491
783
 
492
784
  When you have fully completed your task, call the "taskComplete" function with the final output.
493
- Make sure every detail of the task is done before calling "taskComplete".`}
785
+ Make sure every detail of the task is done before calling "taskComplete".${when(tools.offers("delegate"), `
786
+ Any sub-agents you started must finish first: "taskComplete" fails while they are running.`)}`)}${when(tools.offers("readFile") && tools.offers("ls"), example)}
787
+
788
+ These are the functions available to you:
789
+
790
+ \`\`\`ts
791
+ ${tools.toolsDts}
792
+
793
+ /** The global Fetch API available for making HTTP requests. */
794
+ declare const fetch: typeof globalThis.fetch
795
+ \`\`\`${Option.match(tools.skillsCatalog, {
796
+ onNone: () => "",
797
+ onSome: (catalog) => `
798
+
799
+ ${catalog}`,
800
+ })}`;
801
+ const example = `
494
802
 
495
803
  Here is how you would read a file and list a directory:
496
804
 
@@ -517,21 +825,63 @@ package.json: {
517
825
  "name": "my-project",
518
826
  "version": "1.0.0"
519
827
  }
520
- \`\`\`
521
-
522
- These are the functions available to you:
523
-
524
- \`\`\`ts
525
- ${capabilities.toolsDts}
526
-
527
- /** The global Fetch API available for making HTTP requests. */
528
- declare const fetch: typeof globalThis.fetch
529
- \`\`\`${Option.match(AgentSkills.renderCatalog(capabilities.skills), {
530
- onNone: () => "",
531
- onSome: (catalog) => `
532
-
533
- ${catalog}`,
534
- })}`;
828
+ \`\`\``;
829
+ const ReadSkillTools = Toolkit.make(Tool.make("readSkill", {
830
+ description: "Read the instructions of a skill listed under Skills, by its name.",
831
+ parameters: Schema.String.annotate({ identifier: "name" }),
832
+ success: Schema.String,
833
+ failure: Schema.String,
834
+ }));
835
+ /**
836
+ * Builds the loop-side handlers the executor puts in the sandbox, and their
837
+ * type declarations. Every call is decoded by `Toolkit.handle` before the
838
+ * handler runs; results are encoded to JSON.
839
+ */
840
+ const makeLoopTools = Effect.fnUntraced(function* (options) {
841
+ const skills = options.skills ?? [];
842
+ const callerTools = Object.keys(options.loopTools?.tools ?? {});
843
+ const names = skills.length > 0 ? [...callerTools, "readSkill"] : callerTools;
844
+ for (const name of names) {
845
+ if (options.executorTools.includes(name) ||
846
+ names.indexOf(name) !== names.lastIndexOf(name)) {
847
+ return yield* Effect.die(new Error(`Loop-side tool "${name}" clashes with another tool`));
848
+ }
849
+ }
850
+ const toolkit = Toolkit.merge(options.loopTools ?? Toolkit.empty, skills.length > 0 ? ReadSkillTools : Toolkit.empty);
851
+ const withHandlers = toolkit;
852
+ // Only provided with the tool itself, so it never replaces a caller's
853
+ // `readSkill` handler.
854
+ const handled = yield* skills.length > 0
855
+ ? withHandlers.pipe(Effect.provide(ReadSkillTools.toLayer({
856
+ readSkill: (name) => {
857
+ const skill = skills.find((skill) => skill.name === name);
858
+ return skill
859
+ ? Effect.succeed(skill.content)
860
+ : Effect.fail(`Unknown skill ${JSON.stringify(name)}. Available skills: ${skills.map((skill) => skill.name).join(", ")}`);
861
+ },
862
+ })))
863
+ : withHandlers;
864
+ // Provides the services the caller's handlers depend on.
865
+ const context = yield* Effect.context();
866
+ const handlers = {};
867
+ for (const [name, tool] of Object.entries(handled.tools)) {
868
+ const encodeSuccess = Schema.encodeUnknownEffect(Schema.toCodecJson(tool.successSchema));
869
+ handlers[name] = (params) => handled.handle(name, params).pipe(Effect.flatMap(Stream.runLast), Effect.flatMap((last) => {
870
+ if (Option.isNone(last))
871
+ return Effect.void;
872
+ return last.value.isFailure
873
+ ? Effect.fail(last.value.result)
874
+ : encodeSuccess(last.value.result);
875
+ }), Effect.mapError(errorMessage), Effect.provideContext(context));
876
+ }
877
+ const renderer = yield* Effect.service(ToolkitRenderer).pipe(Effect.provide(ToolkitRenderer.layer));
878
+ return { handlers, dts: renderer.render(toolkit) };
879
+ });
880
+ const errorMessage = (error) => typeof error === "string"
881
+ ? error
882
+ : error instanceof Error
883
+ ? error.message
884
+ : (JSON.stringify(error) ?? String(error));
535
885
  class ScriptExecutor extends Context.Service()("clanka/Agent/ScriptExecutor") {
536
886
  }
537
887
  const SingleTools = Toolkit.make(Tool.make("execute", {
@@ -553,13 +903,18 @@ const SingleToolHandlers = SingleTools.toLayer({
553
903
  * @category Layers
554
904
  */
555
905
  export const layer = Layer.effect(Agent, make);
906
+ /**
907
+ * @since 1.0.0
908
+ * @category Layers
909
+ */
910
+ export const layerWith = (options) => Layer.effect(Agent, makeWith(options));
556
911
  /**
557
912
  * Create an Agent layer that uses a local AgentExecutor.
558
913
  *
559
914
  * @since 1.0.0
560
915
  * @category Layers
561
916
  */
562
- export const layerLocal = (options) => layer.pipe(Layer.provide(AgentExecutor.layerLocal(options)));
917
+ export const layerLocal = (options) => layerWith(options).pipe(Layer.provide(AgentExecutor.layerLocal(options)));
563
918
  /**
564
919
  * @since 1.0.0
565
920
  * @category Subagent model
@@ -594,6 +949,19 @@ export class TurnTimeout extends Context.Reference("clanka/Agent/TurnTimeout", {
594
949
  }) {
595
950
  static layer = (timeout) => Layer.succeed(TurnTimeout, Duration.fromInputUnsafe(timeout));
596
951
  }
952
+ /**
953
+ * The number of times in a row a model call is retried, after a retryable
954
+ * error or after reaching `TurnTimeout`, before `send` fails with
955
+ * `RetriesExhausted`. The count resets after a model call succeeds.
956
+ *
957
+ * @since 1.0.0
958
+ * @category Retries
959
+ */
960
+ export class MaxRetries extends Context.Reference("clanka/Agent/MaxRetries", {
961
+ defaultValue: () => 20,
962
+ }) {
963
+ static layer = (retries) => Layer.succeed(MaxRetries, retries);
964
+ }
597
965
  /**
598
966
  * @since 1.0.0
599
967
  * @category System prompts