clanka 0.8.6 → 0.10.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 (96) hide show
  1. package/dist/Acp.d.ts +6 -1
  2. package/dist/Acp.d.ts.map +1 -1
  3. package/dist/Acp.js +34 -3
  4. package/dist/Acp.js.map +1 -1
  5. package/dist/Acp.test.js +178 -2
  6. package/dist/Acp.test.js.map +1 -1
  7. package/dist/AcpImage.test.js +7 -1
  8. package/dist/AcpImage.test.js.map +1 -1
  9. package/dist/Agent.d.ts +82 -8
  10. package/dist/Agent.d.ts.map +1 -1
  11. package/dist/Agent.js +556 -113
  12. package/dist/Agent.js.map +1 -1
  13. package/dist/Agent.test.js +86 -5
  14. package/dist/Agent.test.js.map +1 -1
  15. package/dist/AgentCallerConfig.test.d.ts +2 -0
  16. package/dist/AgentCallerConfig.test.d.ts.map +1 -0
  17. package/dist/AgentCallerConfig.test.js +335 -0
  18. package/dist/AgentCallerConfig.test.js.map +1 -0
  19. package/dist/AgentEnvironment.d.ts +76 -0
  20. package/dist/AgentEnvironment.d.ts.map +1 -0
  21. package/dist/AgentEnvironment.js +119 -0
  22. package/dist/AgentEnvironment.js.map +1 -0
  23. package/dist/AgentEnvironment.test.d.ts +2 -0
  24. package/dist/AgentEnvironment.test.d.ts.map +1 -0
  25. package/dist/AgentEnvironment.test.js +304 -0
  26. package/dist/AgentEnvironment.test.js.map +1 -0
  27. package/dist/AgentExecutor.d.ts +342 -183
  28. package/dist/AgentExecutor.d.ts.map +1 -1
  29. package/dist/AgentExecutor.js +607 -127
  30. package/dist/AgentExecutor.js.map +1 -1
  31. package/dist/AgentExecutor.test.js +287 -31
  32. package/dist/AgentExecutor.test.js.map +1 -1
  33. package/dist/AgentExecutorImage.test.js +5 -1
  34. package/dist/AgentExecutorImage.test.js.map +1 -1
  35. package/dist/AgentImage.test.js +15 -2
  36. package/dist/AgentImage.test.js.map +1 -1
  37. package/dist/AgentOutput.d.ts +70 -5
  38. package/dist/AgentOutput.d.ts.map +1 -1
  39. package/dist/AgentOutput.js +65 -0
  40. package/dist/AgentOutput.js.map +1 -1
  41. package/dist/AgentSkills.d.ts +37 -0
  42. package/dist/AgentSkills.d.ts.map +1 -1
  43. package/dist/AgentSkills.js +96 -32
  44. package/dist/AgentSkills.js.map +1 -1
  45. package/dist/AgentSkills.test.js +14 -2
  46. package/dist/AgentSkills.test.js.map +1 -1
  47. package/dist/AgentSubagents.test.d.ts +2 -0
  48. package/dist/AgentSubagents.test.d.ts.map +1 -0
  49. package/dist/AgentSubagents.test.js +494 -0
  50. package/dist/AgentSubagents.test.js.map +1 -0
  51. package/dist/AgentTools.d.ts +356 -14
  52. package/dist/AgentTools.d.ts.map +1 -1
  53. package/dist/AgentTools.js +214 -35
  54. package/dist/AgentTools.js.map +1 -1
  55. package/dist/OutputFormatter.d.ts.map +1 -1
  56. package/dist/OutputFormatter.js +19 -2
  57. package/dist/OutputFormatter.js.map +1 -1
  58. package/dist/ToolkitRenderer.d.ts.map +1 -1
  59. package/dist/ToolkitRenderer.js +6 -1
  60. package/dist/ToolkitRenderer.js.map +1 -1
  61. package/dist/bin/{Effect-rADALOOD.mjs → Effect-2jPlJ8eu.mjs} +43 -38
  62. package/dist/bin/Effect-2jPlJ8eu.mjs.map +1 -0
  63. package/dist/bin/{McpClient-NazR2OwL.mjs → McpClient-1W508adc.mjs} +3 -3
  64. package/dist/bin/{McpClient-NazR2OwL.mjs.map → McpClient-1W508adc.mjs.map} +1 -1
  65. package/dist/bin/{OutputFormatter-BVHbgF2b.mjs → OutputFormatter-BFAv48k9.mjs} +17 -5
  66. package/dist/bin/{OutputFormatter-BVHbgF2b.mjs.map → OutputFormatter-BFAv48k9.mjs.map} +1 -1
  67. package/dist/bin/{Schema-C7NXAOWA.mjs → Schema-D-7VuCiC.mjs} +2 -2
  68. package/dist/bin/{Schema-C7NXAOWA.mjs.map → Schema-D-7VuCiC.mjs.map} +1 -1
  69. package/dist/bin/{SemanticSearch-4Jes3jCl.mjs → SemanticSearch-Cb8aqvGv.mjs} +4 -4
  70. package/dist/bin/{SemanticSearch-4Jes3jCl.mjs.map → SemanticSearch-Cb8aqvGv.mjs.map} +1 -1
  71. package/dist/bin/{Stream-CSLA1_GD.mjs → Stream-DEu2tfCV.mjs} +12 -3
  72. package/dist/bin/Stream-DEu2tfCV.mjs.map +1 -0
  73. package/dist/bin/cli.mjs +13333 -12470
  74. package/dist/bin/cli.mjs.map +1 -1
  75. package/package.json +1 -1
  76. package/src/Acp.test.ts +279 -3
  77. package/src/Acp.ts +34 -4
  78. package/src/AcpImage.test.ts +7 -1
  79. package/src/Agent.test.ts +109 -4
  80. package/src/Agent.ts +874 -140
  81. package/src/AgentCallerConfig.test.ts +522 -0
  82. package/src/AgentEnvironment.test.ts +504 -0
  83. package/src/AgentEnvironment.ts +161 -0
  84. package/src/AgentExecutor.test.ts +414 -37
  85. package/src/AgentExecutor.ts +1028 -191
  86. package/src/AgentExecutorImage.test.ts +5 -1
  87. package/src/AgentImage.test.ts +21 -3
  88. package/src/AgentOutput.ts +91 -1
  89. package/src/AgentSkills.test.ts +14 -2
  90. package/src/AgentSkills.ts +117 -34
  91. package/src/AgentSubagents.test.ts +824 -0
  92. package/src/AgentTools.ts +377 -53
  93. package/src/OutputFormatter.ts +19 -2
  94. package/src/ToolkitRenderer.ts +7 -1
  95. package/dist/bin/Effect-rADALOOD.mjs.map +0 -1
  96. package/dist/bin/Stream-CSLA1_GD.mjs.map +0 -1
package/src/Agent.ts CHANGED
@@ -5,6 +5,7 @@ import * as Model from "effect/ai/Model"
5
5
  import type * as Response from "effect/ai/Response"
6
6
  import * as AgentExecutor from "./AgentExecutor.ts"
7
7
  import * as AgentSkills from "./AgentSkills.ts"
8
+ import { ToolkitRenderer } from "./ToolkitRenderer.ts"
8
9
  import { stripWrappingCodeFence } from "./ScriptExtraction.ts"
9
10
  import type * as Path from "effect/Path"
10
11
  import type * as ChildProcessSpawner from "effect/process/ChildProcessSpawner"
@@ -12,9 +13,12 @@ import type * as HttpClient from "effect/http/HttpClient"
12
13
  import type {
13
14
  CurrentDirectory,
14
15
  DirectoryChanger,
16
+ ExcludableTool,
15
17
  ImageAttacher,
16
18
  ImageAttachment,
17
19
  SubagentExecutor,
20
+ SubagentResult,
21
+ SubagentStatus,
18
22
  TaskCompleter,
19
23
  } from "./AgentTools.ts"
20
24
  import * as Image from "./Image.ts"
@@ -22,7 +26,6 @@ import type * as FileSystem from "effect/FileSystem"
22
26
  import * as Prompt from "effect/ai/Prompt"
23
27
  import * as Effect from "effect/Effect"
24
28
  import * as Stream from "effect/Stream"
25
- import type * as Scope from "effect/Scope"
26
29
  import * as LanguageModel from "effect/ai/LanguageModel"
27
30
  import * as AiError from "effect/ai/AiError"
28
31
  import * as Context from "effect/Context"
@@ -42,6 +45,9 @@ import * as Cause from "effect/Cause"
42
45
  import * as Latch from "effect/Latch"
43
46
  import * as Clock from "effect/Clock"
44
47
  import * as Exit from "effect/Exit"
48
+ import * as Deferred from "effect/Deferred"
49
+ import * as Fiber from "effect/Fiber"
50
+ import * as Scope from "effect/Scope"
45
51
  import * as Compaction from "./Compaction.ts"
46
52
  import {
47
53
  ScriptEnd,
@@ -62,6 +68,10 @@ import {
62
68
  ExecuteOutputCapped,
63
69
  CompactionStarted,
64
70
  CompactionEnded,
71
+ EnvironmentUpdated,
72
+ HistoryAppended,
73
+ HistoryReplaced,
74
+ RetriesExhausted,
65
75
  } from "./AgentOutput.ts"
66
76
 
67
77
  /**
@@ -85,6 +95,15 @@ export interface Agent {
85
95
 
86
96
  readonly history: MutableRef.MutableRef<Prompt.Prompt>
87
97
 
98
+ /**
99
+ * The executor environment the next script runs in, such as its working
100
+ * directory and which AGENTS.md files and skills the history already has.
101
+ * Opaque to the agent: it is passed to the executor and replaced with what
102
+ * the executor returns. Store it next to `history` to resume a session
103
+ * where it left off.
104
+ */
105
+ readonly environment: MutableRef.MutableRef<AgentExecutor.ExecutionEnvironment>
106
+
88
107
  /**
89
108
  * Send a prompt to the agent and receive a stream of output.
90
109
  */
@@ -105,13 +124,12 @@ export interface Agent {
105
124
  }) => string)
106
125
  | undefined
107
126
  }): Effect.Effect<
108
- Stream.Stream<Output, AgentFinished | AiError.AiError>,
127
+ Stream.Stream<Output, AgentFinished | AiError.AiError | RetriesExhausted>,
109
128
  never,
110
129
  | Scope.Scope
111
130
  | LanguageModel.LanguageModel
112
131
  | Model.ProviderName
113
132
  | Model.ModelName
114
- | SubagentModel
115
133
  >
116
134
 
117
135
  /**
@@ -131,38 +149,85 @@ export interface Agent {
131
149
  */
132
150
  export const Agent = Context.Service<Agent>("clanka/Agent")
133
151
 
152
+ /**
153
+ * What the Agent offers the model, beyond the executor's built-in tools.
154
+ *
155
+ * @since 1.0.0
156
+ * @category Models
157
+ */
158
+ export interface Options<LoopTools extends Toolkit.Any = never> {
159
+ /**
160
+ * The project instructions for the system prompt. Unset uses the
161
+ * executor's `AGENTS.md`; `Option.none()` leaves them out.
162
+ */
163
+ readonly instructions?: Option.Option<string> | undefined
164
+ /**
165
+ * The skills offered to the model. Unset uses the skills discovered on the
166
+ * executor; a list, possibly empty, replaces them. The model reads a
167
+ * skill's content with `readSkill`, which runs on the loop side.
168
+ */
169
+ readonly skills?: ReadonlyArray<AgentSkills.ProvidedSkill> | undefined
170
+ /**
171
+ * Tools whose handlers run next to the Agent rather than in the executor.
172
+ * Scripts call them like any other function; arguments are decoded with
173
+ * the tool's parameters schema before the handler runs, and a handler
174
+ * failure rejects the script's call with that message.
175
+ */
176
+ readonly loopTools?: LoopTools | undefined
177
+ }
178
+
179
+ /**
180
+ * The services needed by the handlers of a loop-side toolkit.
181
+ *
182
+ * @since 1.0.0
183
+ * @category Models
184
+ */
185
+ export type LoopToolServices<LoopTools> =
186
+ LoopTools extends Toolkit.Toolkit<infer T>
187
+ ? Tool.HandlersFor<T> | Tool.HandlerServices<T[keyof T]>
188
+ : never
189
+
134
190
  /**
135
191
  * @since 1.0.0
136
192
  * @category Constructors
137
193
  */
138
- export const make = Effect.gen(function* (): Effect.fn.Return<
194
+ export const makeWith = Effect.fnUntraced(function* <
195
+ LoopTools extends Toolkit.Any = never,
196
+ >(
197
+ options: Options<LoopTools>,
198
+ ): Effect.fn.Return<
139
199
  Agent,
140
200
  never,
141
- Scope.Scope | AgentExecutor.AgentExecutor
201
+ Scope.Scope | AgentExecutor.AgentExecutor | LoopToolServices<LoopTools>
142
202
  > {
143
203
  const executor = yield* AgentExecutor.AgentExecutor
144
204
 
145
205
  const singleTool = yield* SingleTools.pipe(Effect.provide(SingleToolHandlers))
146
206
  const capabilities = yield* executor.capabilities
207
+ const loopTools = yield* makeLoopTools({
208
+ loopTools: options.loopTools,
209
+ skills: options.skills,
210
+ executorTools: capabilities.tools,
211
+ })
212
+ const promptTools: PromptTools = {
213
+ toolsDts:
214
+ loopTools.dts === ""
215
+ ? capabilities.toolsDts
216
+ : `${capabilities.toolsDts}\n\n${loopTools.dts}`,
217
+ offers: (name) => capabilities.tools.includes(name),
218
+ skillsCatalog:
219
+ options.skills === undefined
220
+ ? AgentSkills.renderCatalog(capabilities.skills)
221
+ : AgentSkills.renderProvidedCatalog(options.skills),
222
+ }
147
223
 
148
- const pendingMessages = new Set<{
149
- readonly message: string
150
- readonly resume: (effect: Effect.Effect<void>) => void
151
- }>()
152
-
153
- const agentsMd = Option.map(
154
- capabilities.agentsMd,
155
- (content) => `# AGENTS.md
156
-
157
- The following instructions are from ./AGENTS.md in the current directory.
158
- You do not need to read this file again.
159
-
160
- **ALWAYS follow these instructions when completing tasks**:
224
+ // Steering messages for the root agent. Sub-agents get their own mailbox.
225
+ const rootMailbox = makeMailbox()
161
226
 
162
- <!-- AGENTS.md start -->
163
- ${content}
164
- <!-- AGENTS.md end -->`,
165
- )
227
+ const agentsMd =
228
+ options.instructions === undefined
229
+ ? capabilities.instructions
230
+ : Option.map(options.instructions, renderInstructions)
166
231
 
167
232
  let agentCounter = 0
168
233
 
@@ -170,10 +235,13 @@ ${content}
170
235
  let currentOutputAgent: number | null = null
171
236
 
172
237
  const history = MutableRef.make(Prompt.empty)
238
+ const environment = MutableRef.make(capabilities.environment)
173
239
 
174
240
  const spawn: (opts: {
175
241
  readonly agentId: number
176
242
  readonly prompt: Prompt.Prompt
243
+ /** AGENTS.md files and skills added after the prompt. */
244
+ readonly environmentUpdate?: string | undefined
177
245
  readonly system?:
178
246
  | string
179
247
  | ((options: {
@@ -181,21 +249,32 @@ ${content}
181
249
  readonly agentsMd: string
182
250
  }) => string)
183
251
  | undefined
184
- readonly disableHistory?: boolean | undefined
252
+ readonly history: MutableRef.MutableRef<Prompt.Prompt>
253
+ readonly environment: MutableRef.MutableRef<AgentExecutor.ExecutionEnvironment>
254
+ readonly mailbox: Mailbox
255
+ /**
256
+ * Whether this agent's output is streamed for display. Background agents
257
+ * and everything under them are not, so they never hold the output lock.
258
+ */
259
+ readonly display: boolean
260
+ /**
261
+ * Whether commits to `history` are emitted as `HistoryAppended` and
262
+ * `HistoryReplaced` events. Only the root agent's history is public.
263
+ */
264
+ readonly historyEvents: boolean
185
265
  }) => Stream.Stream<
186
266
  Output,
187
- AgentFinished | AiError.AiError,
188
- | LanguageModel.LanguageModel
189
- | Model.ProviderName
190
- | Model.ModelName
191
- | SubagentModel
267
+ AgentFinished | AiError.AiError | RetriesExhausted,
268
+ LanguageModel.LanguageModel | Model.ProviderName | Model.ModelName
192
269
  > = Effect.fnUntraced(function* (opts) {
193
270
  const agentId = opts.agentId
194
271
  const ai = yield* LanguageModel.LanguageModel
195
- const subagentModel = yield* SubagentModel
272
+ // Without a SubagentModel, sub-agents run on this agent's model.
273
+ const subagentModel = yield* Effect.serviceOption(SubagentModel)
196
274
  const modelConfig = yield* AgentModelConfig
197
275
  const conversationMode = yield* ConversationMode
198
276
  const turnTimeout = yield* TurnTimeout
277
+ const maxRetries = yield* MaxRetries
199
278
  let finalSummary = Option.none<string>()
200
279
  // `inputTokens.total` from the most recent finish part; undefined until
201
280
  // the first response and after every compaction.
@@ -207,20 +286,57 @@ ${content}
207
286
  // Images attached by `readFile` during the current script, spliced onto
208
287
  // the Prompt as a user message once the tool result has been recorded.
209
288
  const pendingImages: Array<ImageAttachment> = []
289
+ // Whether a script ran in the current response. Their environment
290
+ // update is rendered once, after all of their tool results.
291
+ let scriptsRan = false
210
292
 
211
- const output = yield* Queue.make<Output, AgentFinished | AiError.AiError>()
293
+ const output = yield* Queue.make<
294
+ Output,
295
+ AgentFinished | AiError.AiError | RetriesExhausted
296
+ >()
212
297
  let inputTokens = 0
213
298
  let outputTokens = 0
214
299
  let cacheRead = 0
215
300
  let cacheWrite = 0
216
- const prompt = opts.disableHistory ? MutableRef.make(Prompt.empty) : history
301
+ const prompt = opts.history
302
+ const mailbox = opts.mailbox
217
303
 
304
+ // Every change to `prompt` after the system message is set goes through
305
+ // these two, so the history events always add up to the history.
306
+ const appendHistory = (input: Prompt.Prompt) => {
307
+ MutableRef.update(prompt, Prompt.concat(input))
308
+ if (!opts.historyEvents) return
309
+ const messages = input.content.filter(
310
+ (message) => message.role !== "system",
311
+ )
312
+ if (messages.length > 0) {
313
+ Queue.offerUnsafe(output, new HistoryAppended({ messages }))
314
+ }
315
+ }
316
+ const replaceHistory = (next: Prompt.Prompt) => {
317
+ MutableRef.set(prompt, next)
318
+ if (!opts.historyEvents) return
319
+ Queue.offerUnsafe(
320
+ output,
321
+ new HistoryReplaced({
322
+ messages: next.content.filter((message) => message.role !== "system"),
323
+ }),
324
+ )
325
+ }
326
+
327
+ // Committed now, emitted after AgentStart below.
218
328
  MutableRef.update(prompt, Prompt.concat(opts.prompt))
329
+ if (opts.environmentUpdate !== undefined) {
330
+ MutableRef.update(
331
+ prompt,
332
+ Prompt.concat(environmentUpdateMessage(opts.environmentUpdate)),
333
+ )
334
+ }
219
335
 
220
336
  const generateSystem =
221
337
  typeof opts.system === "function" ? opts.system : defaultSystem
222
338
 
223
- const toolInstructions = generateSystemTools(capabilities, conversationMode)
339
+ const toolInstructions = generateSystemTools(promptTools, conversationMode)
224
340
  let system = generateSystem({
225
341
  toolInstructions,
226
342
  agentsMd: Option.getOrElse(agentsMd, () => ""),
@@ -235,6 +351,10 @@ ${content}
235
351
  readonly acquire?: boolean
236
352
  readonly release?: boolean
237
353
  }) {
354
+ if (!opts.display) {
355
+ Queue.offerUnsafe(output, options.part)
356
+ return
357
+ }
238
358
  if (currentOutputAgent === null || currentOutputAgent === opts.agentId) {
239
359
  Queue.offerUnsafe(output, options.part)
240
360
  if (options.acquire) {
@@ -266,20 +386,99 @@ ${content}
266
386
  return
267
387
  }
268
388
 
269
- const spawnSubagent = Effect.fnUntraced(
270
- function* (prompt: string) {
271
- let id = agentCounter++
272
- const stream = spawn({
273
- agentId: id,
274
- prompt: Prompt.make(prompt),
275
- system: opts.system,
276
- disableHistory: true,
277
- })
278
- const provider = yield* Model.ProviderName
279
- const model = yield* Model.ModelName
389
+ // Sub-agents. Every agent tracks only the children it spawned. They are
390
+ // forked into a scope owned by this run, so none of them outlive it.
391
+ const runScope = yield* Scope.make()
392
+ const runContext = yield* Effect.context<
393
+ LanguageModel.LanguageModel | Model.ProviderName | Model.ModelName
394
+ >()
395
+ const provideSubagentModel = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
396
+ Option.match(subagentModel, {
397
+ onNone: () => effect,
398
+ onSome: (model) =>
399
+ effect.pipe(
400
+ Effect.provide(model),
401
+ Effect.provideService(SubagentModel, model),
402
+ ),
403
+ })
404
+ const children = new Map<string, Child>()
405
+ // Finished turns waiting to be pushed to the model.
406
+ const completions: Array<Turn> = []
407
+ let wakeUp: (() => void) | undefined
408
+ const notify = () => {
409
+ const resume = wakeUp
410
+ wakeUp = undefined
411
+ resume?.()
412
+ }
413
+ mailbox.notify = notify
414
+
415
+ const runningChildren = () =>
416
+ Array.Array.from(children.values()).filter(
417
+ (child) => child.turn.status === "running",
418
+ )
419
+ const hasUndelivered = () => completions.some((turn) => !turn.delivered)
420
+
421
+ const finishTurn = (turn: Turn, exit: Exit.Exit<string, unknown>) =>
422
+ Effect.sync(() => {
423
+ if (Exit.isSuccess(exit)) {
424
+ turn.status = "completed"
425
+ turn.output = exit.value
426
+ } else if (Cause.hasInterruptsOnly(exit.cause)) {
427
+ turn.status = "cancelled"
428
+ } else {
429
+ turn.status = "failed"
430
+ turn.output = causeMessage(exit.cause)
431
+ }
432
+ Queue.offerUnsafe(
433
+ output,
434
+ new SubagentComplete({
435
+ id: turn.agentId,
436
+ summary: turn.output ?? "",
437
+ status: turn.status,
438
+ }),
439
+ )
440
+ if (!turn.delivered) {
441
+ completions.push(turn)
442
+ }
443
+ Deferred.doneUnsafe(turn.done, Effect.void)
444
+ notify()
445
+ })
446
+
447
+ // Runs the child's current turn in its own fiber, with this run's
448
+ // services and the sub-agent model.
449
+ const startTurn = Effect.fnUntraced(function* (options: {
450
+ readonly child: Child
451
+ readonly prompt: string
452
+ /** AGENTS.md files and skills for the child's directory. */
453
+ readonly environmentUpdate?: string | undefined
454
+ /** Shown in the start event: the task, or the follow-up message. */
455
+ readonly label: string
456
+ readonly background: boolean
457
+ }) {
458
+ const { child } = options
459
+ const turn = child.turn
460
+ const display = opts.display && !options.background
461
+ const stream = spawn({
462
+ agentId: child.id,
463
+ prompt: Prompt.make(options.prompt),
464
+ environmentUpdate: options.environmentUpdate,
465
+ system: opts.system,
466
+ history: child.history,
467
+ environment: child.environment,
468
+ mailbox: child.mailbox,
469
+ display,
470
+ historyEvents: false,
471
+ })
472
+ turn.fiber = yield* Effect.gen(function* () {
280
473
  maybeSend({
281
474
  agentId: opts.agentId,
282
- part: new SubagentStart({ id, prompt, model, provider }),
475
+ part: new SubagentStart({
476
+ id: child.id,
477
+ prompt: options.label,
478
+ model: yield* Model.ModelName,
479
+ provider: yield* Model.ProviderName,
480
+ background: options.background,
481
+ }),
283
482
  release: true,
284
483
  })
285
484
  return yield* stream.pipe(
@@ -287,34 +486,181 @@ ${content}
287
486
  for (const part of parts) {
288
487
  switch (part._tag) {
289
488
  case "AgentStart":
489
+ case "HistoryAppended":
490
+ case "HistoryReplaced":
290
491
  break
291
492
  case "SubagentStart":
292
493
  case "SubagentComplete":
293
- case "SubagentPart":
294
494
  Queue.offerUnsafe(output, part)
295
495
  break
296
-
297
496
  default:
298
- Queue.offerUnsafe(output, new SubagentPart({ id, part }))
299
- break
497
+ // Background agents only report start and completion.
498
+ if (!display) break
499
+ Queue.offerUnsafe(
500
+ output,
501
+ part._tag === "SubagentPart"
502
+ ? part
503
+ : new SubagentPart({ id: child.id, part }),
504
+ )
300
505
  }
301
506
  }
302
507
  return Effect.void
303
508
  }),
304
509
  Effect.as(""),
305
- Effect.catchTag("AgentFinished", (finished) => {
306
- Queue.offerUnsafe(
307
- output,
308
- new SubagentComplete({ id, summary: finished.summary }),
510
+ Effect.catchTag("AgentFinished", (finished) =>
511
+ Effect.succeed(finished.summary),
512
+ ),
513
+ )
514
+ }).pipe(
515
+ Effect.onExit((exit) => finishTurn(turn, exit)),
516
+ provideSubagentModel,
517
+ Effect.provideContext(runContext),
518
+ Effect.forkIn(runScope, { startImmediately: true }),
519
+ )
520
+ })
521
+
522
+ // Leaves `output` out when unset, so the result stays JSON for RPC.
523
+ const childResult = ({ id, turn }: Child): SubagentResult =>
524
+ turn.output === undefined
525
+ ? { id: String(id), status: turn.status }
526
+ : { id: String(id), status: turn.status, output: turn.output }
527
+
528
+ const lookupChild = (id: string) =>
529
+ Effect.suspend(() => {
530
+ const child = children.get(id)
531
+ return child
532
+ ? Effect.succeed(child)
533
+ : Effect.fail(
534
+ `Unknown agent id ${JSON.stringify(id)}. You can only address agents you started; call listAgents() to see them.`,
309
535
  )
310
- return Effect.succeed(finished.summary)
311
- }),
312
- Effect.orDie,
536
+ })
537
+
538
+ const subagents: AgentExecutor.ExecuteSubagents = {
539
+ delegate: Effect.fnUntraced(function* ({
540
+ prompt,
541
+ background,
542
+ environment,
543
+ }) {
544
+ const agentId = agentCounter++
545
+ const child: Child = {
546
+ id: agentId,
547
+ prompt,
548
+ history: MutableRef.make(Prompt.empty),
549
+ environment: MutableRef.make(environment.environment),
550
+ mailbox: makeMailbox(),
551
+ turn: makeTurn(agentId, background),
552
+ }
553
+ const id = String(child.id)
554
+ children.set(id, child)
555
+ const turn = child.turn
556
+ yield* startTurn({
557
+ child,
558
+ label: prompt,
559
+ 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:
560
+
561
+ ${prompt}`,
562
+ // The update goes into the child's first prompt.
563
+ environmentUpdate: Option.getOrUndefined(environment.update),
564
+ background,
565
+ })
566
+ if (background) {
567
+ return { id, status: "running" }
568
+ }
569
+ // Foreground: a failure crashes the script, as before. Interrupting
570
+ // the script stops the agent.
571
+ yield* Deferred.await(turn.done).pipe(
572
+ Effect.onInterrupt(() => Fiber.interrupt(turn.fiber!)),
313
573
  )
314
- },
315
- Effect.provide(subagentModel),
316
- Effect.provideService(SubagentModel, subagentModel),
317
- )
574
+ if (turn.status !== "completed") {
575
+ return yield* Effect.die(
576
+ new Error(
577
+ `Sub-agent ${child.id} ${turn.status}${turn.output ? `: ${turn.output}` : ""}`,
578
+ ),
579
+ )
580
+ }
581
+ return { id, status: "completed", output: turn.output ?? "" }
582
+ }),
583
+ waitAgents: Effect.fnUntraced(function* (ids) {
584
+ const targets =
585
+ ids === undefined
586
+ ? Array.Array.from(children.values())
587
+ : yield* Effect.forEach(ids, lookupChild)
588
+ // A turn started by messageAgent while waiting is waited for too.
589
+ while (true) {
590
+ const running = targets.find(
591
+ (child) => child.turn.status === "running",
592
+ )
593
+ if (!running) break
594
+ yield* Deferred.await(running.turn.done)
595
+ }
596
+ return targets.map((child) => {
597
+ child.turn.delivered = true
598
+ return childResult(child)
599
+ })
600
+ }),
601
+ messageAgent: Effect.fnUntraced(function* ({ id, message }) {
602
+ const child = yield* lookupChild(id)
603
+ if (child.turn.status === "running") {
604
+ child.mailbox.messages.add({ message, resume: () => {} })
605
+ child.mailbox.notify()
606
+ return childResult(child)
607
+ }
608
+ child.turn = makeTurn(child.id, true)
609
+ yield* startTurn({
610
+ child,
611
+ prompt: message,
612
+ label: message,
613
+ background: true,
614
+ })
615
+ return childResult(child)
616
+ }),
617
+ stopAgent: Effect.fnUntraced(function* (id) {
618
+ const child = yield* lookupChild(id)
619
+ const turn = child.turn
620
+ turn.delivered = true
621
+ if (turn.status === "running") {
622
+ yield* Fiber.interrupt(turn.fiber!)
623
+ }
624
+ return childResult(child)
625
+ }),
626
+ listAgents: Effect.sync(() =>
627
+ Array.Array.from(children.values(), (child) => ({
628
+ id: String(child.id),
629
+ status: child.turn.status,
630
+ prompt: child.prompt,
631
+ })),
632
+ ),
633
+ }
634
+
635
+ const onTaskComplete = (summary: string) =>
636
+ Effect.suspend(() => {
637
+ const running = runningChildren()
638
+ if (running.length > 0) {
639
+ const ids = running.map((child) => JSON.stringify(String(child.id)))
640
+ return Effect.fail(
641
+ `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.`,
642
+ )
643
+ }
644
+ finalSummary = Option.some(summary)
645
+ return Effect.void
646
+ })
647
+
648
+ // Blocks an idle conversation turn until a child finishes or a message
649
+ // arrives.
650
+ const waitForActivity = Effect.callback<void>((resume) => {
651
+ if (
652
+ mailbox.messages.size > 0 ||
653
+ hasUndelivered() ||
654
+ runningChildren().length === 0
655
+ ) {
656
+ resume(Effect.void)
657
+ return
658
+ }
659
+ wakeUp = () => resume(Effect.void)
660
+ return Effect.sync(() => {
661
+ wakeUp = undefined
662
+ })
663
+ })
318
664
 
319
665
  // Turn timeout
320
666
  const clock = yield* Clock.Clock
@@ -349,6 +695,36 @@ ${content}
349
695
  compactionStarted = true
350
696
  maybeSend({ agentId, part: new CompactionStarted({ reason }) })
351
697
  })
698
+ // The AGENTS.md files and skills for the current directory that the
699
+ // history does not have yet. Rendered once per response, after all of
700
+ // its scripts; nothing counts as seen until `applyEnvironmentUpdate` has
701
+ // put it in the history, so an interrupted response is covered by the
702
+ // next one. With `reset`, everything is rendered again: any operation
703
+ // that rewrites the history must do this, because the rewrite drops the
704
+ // earlier updates.
705
+ const renderEnvironment = (options?: { readonly reset?: boolean }) =>
706
+ executor.renderEnvironment?.(opts.environment.current, options) ??
707
+ Effect.succeed(
708
+ new AgentExecutor.EnvironmentUpdate({
709
+ environment: opts.environment.current,
710
+ update: Option.none(),
711
+ }),
712
+ )
713
+ const applyEnvironmentUpdate = (
714
+ update: AgentExecutor.EnvironmentUpdate,
715
+ ) => {
716
+ MutableRef.set(opts.environment, update.environment)
717
+ if (Option.isNone(update.update)) return
718
+ appendHistory(environmentUpdateMessage(update.update.value))
719
+ maybeSend({
720
+ agentId,
721
+ part: new EnvironmentUpdated({ update: update.update.value }),
722
+ })
723
+ }
724
+
725
+ // The refresh is rendered before the rewrite and both are committed
726
+ // together, so an interrupt leaves the old history and the old
727
+ // environment, which still agree.
352
728
  const compactWithEvents = <E, R>(
353
729
  reason: Compaction.CompactionReason,
354
730
  compaction: Effect.Effect<
@@ -361,6 +737,15 @@ ${content}
361
737
  compactionStarted = false
362
738
  return compaction
363
739
  }).pipe(
740
+ Effect.flatMap(
741
+ Option.match({
742
+ onNone: () => Effect.succeedNone,
743
+ onSome: (result) =>
744
+ Effect.map(renderEnvironment({ reset: true }), (refresh) =>
745
+ Option.some({ ...result, refresh }),
746
+ ),
747
+ }),
748
+ ),
364
749
  Effect.onExit((exit) =>
365
750
  Effect.sync(() => {
366
751
  if (!compactionStarted) return
@@ -368,7 +753,15 @@ ${content}
368
753
  let tokensBefore: number
369
754
  let tokensAfter: number
370
755
  if (Option.isSome(result)) {
371
- MutableRef.set(prompt, result.value.prompt)
756
+ // The refresh sends the kept updates again, so they are
757
+ // dropped here to appear once.
758
+ replaceHistory(
759
+ Prompt.fromMessages(
760
+ result.value.prompt.content.filter(
761
+ (message) => !isEnvironmentUpdate(message),
762
+ ),
763
+ ),
764
+ )
372
765
  lastContextTokens = undefined
373
766
  tokensBefore = result.value.tokensBefore
374
767
  tokensAfter = result.value.tokensAfter
@@ -381,6 +774,9 @@ ${content}
381
774
  agentId,
382
775
  part: new CompactionEnded({ reason, tokensBefore, tokensAfter }),
383
776
  })
777
+ if (Option.isSome(result)) {
778
+ applyEnvironmentUpdate(result.value.refresh)
779
+ }
384
780
  }),
385
781
  ),
386
782
  )
@@ -390,18 +786,22 @@ ${content}
390
786
  yield* toolLatchAcquire
391
787
  maybeSend({ agentId, part: new ScriptEnd(), release: true })
392
788
  const normalizedScript = stripWrappingCodeFence(script)
789
+ scriptsRan = true
393
790
  const output = yield* pipe(
394
791
  executor.execute({
395
792
  script: normalizedScript,
396
- onSubagent: spawnSubagent,
397
- onTaskComplete: (summary) =>
793
+ environment: opts.environment.current,
794
+ onEnvironment: (environment) =>
398
795
  Effect.sync(() => {
399
- finalSummary = Option.some(summary)
796
+ MutableRef.set(opts.environment, environment)
400
797
  }),
798
+ subagents,
799
+ onTaskComplete,
401
800
  onImage: (image) =>
402
801
  Effect.sync(() => {
403
802
  pendingImages.push(image)
404
803
  }),
804
+ loopTools: loopTools.handlers,
405
805
  }),
406
806
  Stream.mkString,
407
807
  )
@@ -425,6 +825,30 @@ ${content}
425
825
  MutableRef.update(prompt, Prompt.setSystem(system))
426
826
  }
427
827
 
828
+ yield* Queue.offer(
829
+ output,
830
+ new AgentStart({
831
+ id: opts.agentId,
832
+ prompt: opts.prompt,
833
+ provider: yield* Model.ProviderName,
834
+ model: yield* Model.ModelName,
835
+ }),
836
+ )
837
+ if (opts.environmentUpdate !== undefined) {
838
+ maybeSend({
839
+ agentId,
840
+ part: new EnvironmentUpdated({ update: opts.environmentUpdate }),
841
+ })
842
+ }
843
+ if (opts.historyEvents) {
844
+ const messages = opts.prompt.content.filter(
845
+ (message) => message.role !== "system",
846
+ )
847
+ if (messages.length > 0) {
848
+ yield* Queue.offer(output, new HistoryAppended({ messages }))
849
+ }
850
+ }
851
+
428
852
  yield* Effect.gen(function* () {
429
853
  while (true) {
430
854
  if (Option.isSome(finalSummary)) {
@@ -435,11 +859,10 @@ ${content}
435
859
  return
436
860
  }
437
861
 
438
- if (pendingMessages.size > 0) {
439
- MutableRef.update(
440
- prompt,
441
- Prompt.concat(
442
- Array.Array.from(pendingMessages, ({ message, resume }) => {
862
+ if (mailbox.messages.size > 0) {
863
+ appendHistory(
864
+ Prompt.make(
865
+ Array.Array.from(mailbox.messages, ({ message, resume }) => {
443
866
  resume(Effect.void)
444
867
  return {
445
868
  role: "user",
@@ -448,7 +871,29 @@ ${content}
448
871
  }),
449
872
  ),
450
873
  )
451
- pendingMessages.clear()
874
+ mailbox.messages.clear()
875
+ }
876
+
877
+ // Completion pushes from background sub-agents. These have their own
878
+ // queue: the steering path above cuts the model stream short.
879
+ if (completions.length > 0) {
880
+ const pushes = completions.splice(0).filter((turn) => {
881
+ if (turn.delivered) return false
882
+ turn.delivered = true
883
+ return true
884
+ })
885
+ if (pushes.length > 0) {
886
+ appendHistory(
887
+ Prompt.make(
888
+ pushes.map((turn) => ({
889
+ role: "user" as const,
890
+ content: `<subagent id="${turn.agentId}" status="${turn.status}">
891
+ ${Compaction.capOutput(turn.output ?? "").output}
892
+ </subagent>`,
893
+ })),
894
+ ),
895
+ )
896
+ }
452
897
  }
453
898
 
454
899
  // Threshold compaction before the next model call
@@ -477,6 +922,19 @@ ${content}
477
922
  let reasoningStarted = false
478
923
  let hadReasoningDelta = false
479
924
  let hadToolCall = false
925
+ // Retries of this model call so far, and the error that used up the
926
+ // last one.
927
+ let retries = 0
928
+ let exhaustedBy: AiError.AiError | undefined
929
+ const retryOrExhaust = (error: AiError.AiError) => {
930
+ if (retries >= maxRetries) {
931
+ exhaustedBy = error
932
+ return false
933
+ }
934
+ retries++
935
+ maybeSend({ agentId, part: new ErrorRetry({ error }) })
936
+ return true
937
+ }
480
938
  const runModel = pipe(
481
939
  Stream.suspend(() =>
482
940
  ai.streamText({
@@ -489,7 +947,7 @@ ${content}
489
947
  Stream.takeUntil((part) => {
490
948
  if (
491
949
  (part.type === "text-end" || part.type === "reasoning-end") &&
492
- pendingMessages.size > 0
950
+ mailbox.messages.size > 0
493
951
  ) {
494
952
  return true
495
953
  }
@@ -576,26 +1034,17 @@ ${content}
576
1034
  Effect.retry({
577
1035
  while(err) {
578
1036
  if (err._tag === "TimeoutError") {
579
- maybeSend({
580
- agentId,
581
- part: new ErrorRetry({
582
- error: AiError.make({
583
- module: "clanka/Agent",
584
- method: "send",
585
- reason: new AiError.UnknownError({
586
- description: "TurnTimeout was reached",
587
- }),
588
- }),
589
- }),
590
- })
591
1037
  discardAttempt()
592
- return true
1038
+ return retryOrExhaust(turnTimeoutError)
593
1039
  }
594
1040
  // Never retry a context-length error as is: the overflow
595
1041
  // handler below compacts first.
596
1042
  if (Compaction.isContextLengthError(err)) return false
597
1043
  if (err.isRetryable) {
598
- maybeSend({ agentId, part: new ErrorRetry({ error: err }) })
1044
+ if (!retryOrExhaust(err)) {
1045
+ discardAttempt()
1046
+ return false
1047
+ }
599
1048
  switch (err.reason._tag) {
600
1049
  case "ToolNotFoundError":
601
1050
  case "InvalidOutputError": {
@@ -604,7 +1053,7 @@ ${content}
604
1053
  `There was an error, please try again using the "execute" tool:\n\n${Cause.pretty(Cause.fail(err))}`,
605
1054
  ),
606
1055
  )
607
- MutableRef.update(prompt, Prompt.concat(toAppend))
1056
+ appendHistory(toAppend)
608
1057
  }
609
1058
  }
610
1059
  }
@@ -613,6 +1062,13 @@ ${content}
613
1062
  },
614
1063
  schedule: retryPolicy,
615
1064
  }),
1065
+ Effect.catchIf(
1066
+ () => exhaustedBy !== undefined,
1067
+ () =>
1068
+ Effect.fail(
1069
+ new RetriesExhausted({ retries, error: exhaustedBy! }),
1070
+ ),
1071
+ ),
616
1072
  Effect.catchTag("TimeoutError", Effect.die),
617
1073
  )
618
1074
  // Unsupported images: drop them from the request and retry once.
@@ -620,6 +1076,7 @@ ${content}
620
1076
  const attemptWithImageFallback = attempt.pipe(
621
1077
  Effect.catchIf(
622
1078
  (err): err is AiError.AiError =>
1079
+ err._tag === "AiError" &&
623
1080
  sendImages &&
624
1081
  Image.hasImages(prompt.current) &&
625
1082
  Image.isUnsupportedImageError(err),
@@ -635,7 +1092,7 @@ ${content}
635
1092
  yield* attemptWithImageFallback.pipe(
636
1093
  Effect.catchIf(
637
1094
  (err): err is AiError.AiError =>
638
- Compaction.isContextLengthError(err),
1095
+ err._tag === "AiError" && Compaction.isContextLengthError(err),
639
1096
  (err) =>
640
1097
  Effect.gen(function* () {
641
1098
  discardAttempt()
@@ -660,21 +1117,24 @@ ${content}
660
1117
  }),
661
1118
  ),
662
1119
  )
663
- MutableRef.update(
664
- prompt,
665
- Prompt.concat(Prompt.fromResponseParts(response)),
666
- )
1120
+ appendHistory(Prompt.fromResponseParts(response))
667
1121
  if (pendingImages.length > 0) {
668
1122
  // After the tool result, so call / result pairing stays intact.
669
- MutableRef.update(
670
- prompt,
671
- Prompt.concat(
672
- Prompt.fromMessages([Image.userMessage(pendingImages)]),
673
- ),
674
- )
1123
+ appendHistory(Prompt.fromMessages([Image.userMessage(pendingImages)]))
675
1124
  pendingImages.length = 0
676
1125
  }
677
- if (conversationMode && !hadToolCall && pendingMessages.size === 0) {
1126
+ // After the tool results too, and before any steering messages.
1127
+ if (scriptsRan) {
1128
+ scriptsRan = false
1129
+ applyEnvironmentUpdate(yield* renderEnvironment())
1130
+ }
1131
+ if (conversationMode && !hadToolCall && mailbox.messages.size === 0) {
1132
+ // The run is not over while children are running or their results
1133
+ // have not been seen yet.
1134
+ if (runningChildren().length > 0 || hasUndelivered()) {
1135
+ yield* waitForActivity
1136
+ continue
1137
+ }
678
1138
  finalSummary = Option.some(responseToSummary(response))
679
1139
  }
680
1140
  }
@@ -684,20 +1144,11 @@ ${content}
684
1144
  maybeSend({ agentId, part: new ScriptDelta({ delta: script }) })
685
1145
  return executeScript(script)
686
1146
  }),
1147
+ Effect.ensuring(Scope.close(runScope, Exit.void)),
687
1148
  Effect.catchCause((cause) => Queue.failCause(output, cause)),
688
1149
  Effect.forkScoped,
689
1150
  )
690
1151
 
691
- yield* Queue.offer(
692
- output,
693
- new AgentStart({
694
- id: opts.agentId,
695
- prompt: opts.prompt,
696
- provider: yield* Model.ProviderName,
697
- model: yield* Model.ModelName,
698
- }),
699
- )
700
-
701
1152
  return Stream.fromQueue(output)
702
1153
  }, Stream.unwrap)
703
1154
 
@@ -706,11 +1157,17 @@ ${content}
706
1157
  return Agent.of({
707
1158
  [TypeId]: TypeId,
708
1159
  history,
1160
+ environment,
709
1161
  send: (options) =>
710
1162
  spawn({
711
1163
  agentId: agentCounter++,
712
1164
  prompt: Prompt.make(options.prompt),
713
1165
  system: options.system,
1166
+ history,
1167
+ environment,
1168
+ mailbox: rootMailbox,
1169
+ display: true,
1170
+ historyEvents: true,
714
1171
  }).pipe(
715
1172
  Stream.broadcast({ capacity: "unbounded", replay: 1 }),
716
1173
  sendLock.withPermit,
@@ -718,17 +1175,127 @@ ${content}
718
1175
  steer: (message) =>
719
1176
  Effect.callback((resume) => {
720
1177
  const entry = { message, resume }
721
- pendingMessages.add(entry)
722
- return Effect.sync(() => pendingMessages.delete(entry))
1178
+ rootMailbox.messages.add(entry)
1179
+ rootMailbox.notify()
1180
+ return Effect.sync(() => rootMailbox.messages.delete(entry))
723
1181
  }),
724
1182
  })
725
1183
  })
726
1184
 
1185
+ /**
1186
+ * Create an Agent with every executor tool, the executor's `AGENTS.md` and
1187
+ * skills, and no loop-side tools.
1188
+ *
1189
+ * @since 1.0.0
1190
+ * @category Constructors
1191
+ */
1192
+ export const make: Effect.Effect<
1193
+ Agent,
1194
+ never,
1195
+ Scope.Scope | AgentExecutor.AgentExecutor
1196
+ > = makeWith({})
1197
+
1198
+ interface Mailbox {
1199
+ readonly messages: Set<{
1200
+ readonly message: string
1201
+ readonly resume: (effect: Effect.Effect<void>) => void
1202
+ }>
1203
+ /** Wakes the agent's run if it is waiting for activity. */
1204
+ notify: () => void
1205
+ }
1206
+
1207
+ const makeMailbox = (): Mailbox => ({
1208
+ messages: new Set(),
1209
+ notify: () => {},
1210
+ })
1211
+
1212
+ interface Child {
1213
+ readonly id: number
1214
+ readonly prompt: string
1215
+ /** Kept for the whole run so `messageAgent` can resume the agent. */
1216
+ readonly history: MutableRef.MutableRef<Prompt.Prompt>
1217
+ /** Starts as a copy of the parent's at the moment it was delegated. */
1218
+ readonly environment: MutableRef.MutableRef<AgentExecutor.ExecutionEnvironment>
1219
+ readonly mailbox: Mailbox
1220
+ /** The latest turn. Replaced when `messageAgent` resumes the agent. */
1221
+ turn: Turn
1222
+ }
1223
+
1224
+ interface Turn {
1225
+ readonly agentId: number
1226
+ status: SubagentStatus
1227
+ output: string | undefined
1228
+ /** Whether the model has seen this result. Undelivered results are pushed. */
1229
+ delivered: boolean
1230
+ readonly done: Deferred.Deferred<void>
1231
+ fiber: Fiber.Fiber<string, AiError.AiError | RetriesExhausted> | undefined
1232
+ }
1233
+
1234
+ const makeTurn = (agentId: number, background: boolean): Turn => ({
1235
+ agentId,
1236
+ status: "running",
1237
+ output: undefined,
1238
+ // Foreground results go straight back to the script.
1239
+ delivered: !background,
1240
+ done: Deferred.makeUnsafe(),
1241
+ fiber: undefined,
1242
+ })
1243
+
1244
+ const causeMessage = (cause: Cause.Cause<unknown>): string =>
1245
+ errorMessage(Cause.squash(cause))
1246
+
1247
+ const turnTimeoutError = AiError.make({
1248
+ module: "clanka/Agent",
1249
+ method: "send",
1250
+ reason: new AiError.UnknownError({
1251
+ description: "TurnTimeout was reached",
1252
+ }),
1253
+ })
1254
+
727
1255
  const retryPolicy = Schedule.min([
728
1256
  Schedule.exponential(100, 1.5),
729
1257
  Schedule.spaced(5000),
730
1258
  ]).pipe(Schedule.jittered)
731
1259
 
1260
+ const environmentUpdateOpen = "<environment-update>"
1261
+
1262
+ const environmentUpdateMessage = (text: string) =>
1263
+ Prompt.make([
1264
+ {
1265
+ role: "user",
1266
+ content: `${environmentUpdateOpen}\n${text}\n</environment-update>`,
1267
+ },
1268
+ ])
1269
+
1270
+ // A user message that is one text part starting with `prefix`.
1271
+ const startsWith = (message: Prompt.Message, prefix: string): boolean =>
1272
+ message.role === "user" &&
1273
+ message.content.length === 1 &&
1274
+ message.content[0]!.type === "text" &&
1275
+ message.content[0]!.text.trimStart().startsWith(prefix)
1276
+
1277
+ const isEnvironmentUpdate = (message: Prompt.Message): boolean =>
1278
+ startsWith(message, environmentUpdateOpen)
1279
+
1280
+ /**
1281
+ * Whether a user message was added by the agent rather than typed: an
1282
+ * `<environment-update>` or a `<subagent>` result. Surfaces that replay
1283
+ * history (ACP) skip them.
1284
+ *
1285
+ * @since 1.0.0
1286
+ * @category Models
1287
+ */
1288
+ export const isInjectedMessage = (message: Prompt.Message): boolean =>
1289
+ isEnvironmentUpdate(message) || startsWith(message, "<subagent ")
1290
+
1291
+ const renderInstructions = (content: string) => `# Project instructions
1292
+
1293
+ **ALWAYS follow these instructions when completing tasks**:
1294
+
1295
+ <!-- instructions start -->
1296
+ ${content}
1297
+ <!-- instructions end -->`
1298
+
732
1299
  const defaultSystem = (options: {
733
1300
  readonly toolInstructions: string
734
1301
  readonly agentsMd: string | null
@@ -739,29 +1306,80 @@ ${options.toolInstructions}
739
1306
  ${options.agentsMd}
740
1307
  `
741
1308
 
1309
+ interface PromptTools {
1310
+ readonly toolsDts: string
1311
+ readonly offers: (name: ExcludableTool) => boolean
1312
+ readonly skillsCatalog: Option.Option<string>
1313
+ }
1314
+
1315
+ const when = (condition: boolean, text: string) => (condition ? text : "")
1316
+
742
1317
  const generateSystemTools = (
743
- capabilities: AgentExecutor.Capabilities,
1318
+ tools: PromptTools,
744
1319
  conversationMode: boolean,
745
1320
  ) => `YOU ONLY HAVE ONE TOOL AVAILABLE: "execute", to run javascript code to do your work.
746
1321
 
747
1322
  - Use \`console.log\` to print any output you need.
748
- - Use top level await.${
749
- capabilities.supportsSearch
750
- ? `
751
- - Prefer using the "search" function over "rg", unless you are targeting specific files or patterns.`
752
- : ""
753
- }
754
- - You can add / update / remove multiple files in one go with "applyPatch".
755
- - Avoid passing scripts into the "bash" function, and instead write javascript.
1323
+ - Use top level await.${when(
1324
+ tools.offers("search") && tools.offers("rg"),
1325
+ `
1326
+ - Prefer using the "search" function over "rg", unless you are targeting specific files or patterns.`,
1327
+ )}${when(
1328
+ tools.offers("applyPatch"),
1329
+ `
1330
+ - You can add / update / remove multiple files in one go with "applyPatch".${when(
1331
+ tools.offers("writeFile"),
1332
+ ` Prefer it over "writeFile" to update existing files.`,
1333
+ )}`,
1334
+ )}${when(
1335
+ tools.offers("bash"),
1336
+ `
1337
+ - Avoid passing scripts into the "bash" function, and instead write javascript.`,
1338
+ )}
756
1339
  - Variables are not shared between executions.
757
- - Do not use \`require\`, \`import\`, \`process\`, or any other Node.js apis.${
758
- conversationMode
759
- ? ""
760
- : `
1340
+ - Do not use \`require\`, \`import\`, \`process\`, or any other Node.js apis.${when(
1341
+ tools.offers("delegate"),
1342
+ `
1343
+ - "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(
1344
+ tools.offers("waitAgents"),
1345
+ ` Use "waitAgents" to wait for the returned id.`,
1346
+ )}${when(
1347
+ tools.offers("messageAgent"),
1348
+ ` Use "messageAgent" to send a message to the returned id.`,
1349
+ )}${when(
1350
+ tools.offers("stopAgent"),
1351
+ ` Use "stopAgent" to stop the returned id.`,
1352
+ )}${when(
1353
+ tools.offers("listAgents"),
1354
+ ` "listAgents" shows the agents you started.`,
1355
+ )}`,
1356
+ )}${when(
1357
+ !conversationMode,
1358
+ `
761
1359
 
762
1360
  When you have fully completed your task, call the "taskComplete" function with the final output.
763
- Make sure every detail of the task is done before calling "taskComplete".`
764
- }
1361
+ Make sure every detail of the task is done before calling "taskComplete".${when(
1362
+ tools.offers("delegate"),
1363
+ `
1364
+ Any sub-agents you started must finish first: "taskComplete" fails while they are running.`,
1365
+ )}`,
1366
+ )}${when(tools.offers("readFile") && tools.offers("ls"), example)}
1367
+
1368
+ These are the functions available to you:
1369
+
1370
+ \`\`\`ts
1371
+ ${tools.toolsDts}
1372
+
1373
+ /** The global Fetch API available for making HTTP requests. */
1374
+ declare const fetch: typeof globalThis.fetch
1375
+ \`\`\`${Option.match(tools.skillsCatalog, {
1376
+ onNone: () => "",
1377
+ onSome: (catalog) => `
1378
+
1379
+ ${catalog}`,
1380
+ })}`
1381
+
1382
+ const example = `
765
1383
 
766
1384
  Here is how you would read a file and list a directory:
767
1385
 
@@ -788,21 +1406,104 @@ package.json: {
788
1406
  "name": "my-project",
789
1407
  "version": "1.0.0"
790
1408
  }
791
- \`\`\`
1409
+ \`\`\``
792
1410
 
793
- These are the functions available to you:
1411
+ const ReadSkillTools = Toolkit.make(
1412
+ Tool.make("readSkill", {
1413
+ description:
1414
+ "Read the instructions of a skill listed under Skills, by its name.",
1415
+ parameters: Schema.String.annotate({ identifier: "name" }),
1416
+ success: Schema.String,
1417
+ failure: Schema.String,
1418
+ }),
1419
+ )
794
1420
 
795
- \`\`\`ts
796
- ${capabilities.toolsDts}
1421
+ /**
1422
+ * Builds the loop-side handlers the executor puts in the sandbox, and their
1423
+ * type declarations. Every call is decoded by `Toolkit.handle` before the
1424
+ * handler runs; results are encoded to JSON.
1425
+ */
1426
+ const makeLoopTools = Effect.fnUntraced(function* (options: {
1427
+ readonly loopTools: Toolkit.Any | undefined
1428
+ readonly skills: ReadonlyArray<AgentSkills.ProvidedSkill> | undefined
1429
+ readonly executorTools: ReadonlyArray<string>
1430
+ }) {
1431
+ const skills = options.skills ?? []
1432
+ const callerTools = Object.keys(options.loopTools?.tools ?? {})
1433
+ const names = skills.length > 0 ? [...callerTools, "readSkill"] : callerTools
1434
+ for (const name of names) {
1435
+ if (
1436
+ options.executorTools.includes(name) ||
1437
+ names.indexOf(name) !== names.lastIndexOf(name)
1438
+ ) {
1439
+ return yield* Effect.die(
1440
+ new Error(`Loop-side tool "${name}" clashes with another tool`),
1441
+ )
1442
+ }
1443
+ }
797
1444
 
798
- /** The global Fetch API available for making HTTP requests. */
799
- declare const fetch: typeof globalThis.fetch
800
- \`\`\`${Option.match(AgentSkills.renderCatalog(capabilities.skills), {
801
- onNone: () => "",
802
- onSome: (catalog) => `
1445
+ const toolkit = Toolkit.merge(
1446
+ options.loopTools ?? Toolkit.empty,
1447
+ skills.length > 0 ? ReadSkillTools : Toolkit.empty,
1448
+ ) as unknown as Toolkit.Toolkit<Record<string, Tool.Any>>
1449
+ const withHandlers = toolkit as unknown as Effect.Effect<
1450
+ Toolkit.WithHandler<Record<string, Tool.Any>>
1451
+ >
1452
+ // Only provided with the tool itself, so it never replaces a caller's
1453
+ // `readSkill` handler.
1454
+ const handled = yield* skills.length > 0
1455
+ ? withHandlers.pipe(
1456
+ Effect.provide(
1457
+ ReadSkillTools.toLayer({
1458
+ readSkill: (name) => {
1459
+ const skill = skills.find((skill) => skill.name === name)
1460
+ return skill
1461
+ ? Effect.succeed(skill.content)
1462
+ : Effect.fail(
1463
+ `Unknown skill ${JSON.stringify(name)}. Available skills: ${skills.map((skill) => skill.name).join(", ")}`,
1464
+ )
1465
+ },
1466
+ }),
1467
+ ),
1468
+ )
1469
+ : withHandlers
1470
+ // Provides the services the caller's handlers depend on.
1471
+ const context = yield* Effect.context<never>()
803
1472
 
804
- ${catalog}`,
805
- })}`
1473
+ const handlers: Record<
1474
+ string,
1475
+ (params: unknown) => Effect.Effect<unknown, string>
1476
+ > = {}
1477
+ for (const [name, tool] of Object.entries(handled.tools)) {
1478
+ const encodeSuccess = Schema.encodeUnknownEffect(
1479
+ Schema.toCodecJson(tool.successSchema as Schema.Codec<unknown>),
1480
+ )
1481
+ handlers[name] = (params) =>
1482
+ handled.handle(name, params as never).pipe(
1483
+ Effect.flatMap(Stream.runLast),
1484
+ Effect.flatMap((last): Effect.Effect<unknown, unknown> => {
1485
+ if (Option.isNone(last)) return Effect.void
1486
+ return last.value.isFailure
1487
+ ? Effect.fail(last.value.result)
1488
+ : encodeSuccess(last.value.result)
1489
+ }),
1490
+ Effect.mapError(errorMessage),
1491
+ Effect.provideContext(context),
1492
+ ) as Effect.Effect<unknown, string>
1493
+ }
1494
+
1495
+ const renderer = yield* Effect.service(ToolkitRenderer).pipe(
1496
+ Effect.provide(ToolkitRenderer.layer),
1497
+ )
1498
+ return { handlers, dts: renderer.render(toolkit) }
1499
+ })
1500
+
1501
+ const errorMessage = (error: unknown): string =>
1502
+ typeof error === "string"
1503
+ ? error
1504
+ : error instanceof Error
1505
+ ? error.message
1506
+ : (JSON.stringify(error) ?? String(error))
806
1507
 
807
1508
  class ScriptExecutor extends Context.Service<
808
1509
  ScriptExecutor,
@@ -833,18 +1534,33 @@ const SingleToolHandlers = SingleTools.toLayer({
833
1534
  export const layer: Layer.Layer<Agent, never, AgentExecutor.AgentExecutor> =
834
1535
  Layer.effect(Agent, make)
835
1536
 
1537
+ /**
1538
+ * @since 1.0.0
1539
+ * @category Layers
1540
+ */
1541
+ export const layerWith = <LoopTools extends Toolkit.Any = never>(
1542
+ options: Options<LoopTools>,
1543
+ ): Layer.Layer<
1544
+ Agent,
1545
+ never,
1546
+ AgentExecutor.AgentExecutor | LoopToolServices<LoopTools>
1547
+ > => Layer.effect(Agent, makeWith(options))
1548
+
836
1549
  /**
837
1550
  * Create an Agent layer that uses a local AgentExecutor.
838
1551
  *
839
1552
  * @since 1.0.0
840
1553
  * @category Layers
841
1554
  */
842
- export const layerLocal = <Toolkit extends Toolkit.Any = never>(options: {
843
- readonly directory: string
844
- readonly tools?: Toolkit | undefined
845
- }): Layer.Layer<
1555
+ export const layerLocal = <
1556
+ Toolkit extends Toolkit.Any = never,
1557
+ LoopTools extends Toolkit.Any = never,
1558
+ >(
1559
+ options: AgentExecutor.LocalOptions<Toolkit> & Options<LoopTools>,
1560
+ ): Layer.Layer<
846
1561
  Agent,
847
1562
  never,
1563
+ | LoopToolServices<LoopTools>
848
1564
  | FileSystem.FileSystem
849
1565
  | Path.Path
850
1566
  | ChildProcessSpawner.ChildProcessSpawner
@@ -859,7 +1575,7 @@ export const layerLocal = <Toolkit extends Toolkit.Any = never>(options: {
859
1575
  | TaskCompleter
860
1576
  | ImageAttacher
861
1577
  >
862
- > => layer.pipe(Layer.provide(AgentExecutor.layerLocal(options)))
1578
+ > => layerWith(options).pipe(Layer.provide(AgentExecutor.layerLocal(options)))
863
1579
 
864
1580
  /**
865
1581
  * @since 1.0.0
@@ -923,6 +1639,24 @@ export class TurnTimeout extends Context.Reference<Duration.Duration>(
923
1639
  Layer.succeed(TurnTimeout, Duration.fromInputUnsafe(timeout))
924
1640
  }
925
1641
 
1642
+ /**
1643
+ * The number of times in a row a model call is retried, after a retryable
1644
+ * error or after reaching `TurnTimeout`, before `send` fails with
1645
+ * `RetriesExhausted`. The count resets after a model call succeeds.
1646
+ *
1647
+ * @since 1.0.0
1648
+ * @category Retries
1649
+ */
1650
+ export class MaxRetries extends Context.Reference<number>(
1651
+ "clanka/Agent/MaxRetries",
1652
+ {
1653
+ defaultValue: () => 20,
1654
+ },
1655
+ ) {
1656
+ static readonly layer = (retries: number) =>
1657
+ Layer.succeed(MaxRetries, retries)
1658
+ }
1659
+
926
1660
  /**
927
1661
  * @since 1.0.0
928
1662
  * @category System prompts