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
@@ -5,23 +5,37 @@ import * as NodeConsole from "node:console"
5
5
  import * as NodeOs from "node:os"
6
6
  import * as NodeVm from "node:vm"
7
7
  import { Writable } from "node:stream"
8
+ import { Worker } from "node:worker_threads"
9
+ import type * as NodeWorkerThreads from "node:worker_threads"
8
10
  import {
9
11
  AgentToolHandlers,
12
+ type DelegateResult,
13
+ type SubagentInfo,
14
+ type SubagentResult,
10
15
  AgentTools,
11
16
  AgentToolsWithSearch,
17
+ CommandLimits,
12
18
  CurrentDirectory,
19
+ defaultBashTimeout,
13
20
  DirectoryChanger,
21
+ type ExcludableTool,
14
22
  ImageAttacher,
15
23
  type ImageAttachment,
24
+ makeBashTool,
16
25
  SubagentExecutor,
26
+ type Subagents,
27
+ subagentsUnavailable,
17
28
  TaskCompleter,
18
29
  } from "./AgentTools.ts"
19
30
  import * as Image from "./Image.ts"
20
31
  import { ToolkitRenderer } from "./ToolkitRenderer.ts"
32
+ import * as AgentEnvironment from "./AgentEnvironment.ts"
21
33
  import * as AgentSkills from "./AgentSkills.ts"
22
34
  import type * as ChildProcessSpawner from "effect/process/ChildProcessSpawner"
23
35
  import type * as HttpClient from "effect/http/HttpClient"
24
36
  import * as Context from "effect/Context"
37
+ import * as Deferred from "effect/Deferred"
38
+ import * as Duration from "effect/Duration"
25
39
  import * as Effect from "effect/Effect"
26
40
  import * as Option from "effect/Option"
27
41
  import * as Stream from "effect/Stream"
@@ -55,30 +69,168 @@ export class AgentExecutor extends Context.Service<
55
69
  AgentExecutor,
56
70
  {
57
71
  readonly capabilities: Effect.Effect<Capabilities>
58
- execute(options: {
59
- readonly script: string
60
- readonly onTaskComplete: (summary: string) => Effect.Effect<void>
61
- readonly onSubagent: (message: string) => Effect.Effect<string>
62
- /**
63
- * Receives every image `readFile` attached while the script ran.
64
- */
65
- readonly onImage: (image: ImageAttachment) => Effect.Effect<void>
66
- }): Stream.Stream<string>
72
+ execute(options: ExecuteOptions): Stream.Stream<string>
67
73
  executeUnsafe<Tool extends keyof typeof AgentTools.tools>(options: {
68
74
  readonly tool: Tool
69
75
  readonly params: (typeof AgentTools.tools)[Tool]["parametersSchema"]["Encoded"]
76
+ /**
77
+ * The environment the tool runs in. Defaults to the startup
78
+ * environment. Changes made by the tool are not returned.
79
+ */
80
+ readonly environment?: ExecutionEnvironment | undefined
70
81
  }): Effect.Effect<Schema.Json>
82
+ /**
83
+ * Render the AGENTS.md files and skills that apply to the environment's
84
+ * directory and that the model has not seen yet. The agent calls it once
85
+ * after the scripts of a model response, so one update covers all of
86
+ * them; `execute` itself never renders one.
87
+ *
88
+ * With `reset`, everything sent since the system prompt is forgotten and
89
+ * rendered again. Any operation that rewrites the history, such as
90
+ * compaction, must do this, so the environment's record of what the
91
+ * model has seen matches the history.
92
+ *
93
+ * Optional: without it the agent sends no updates.
94
+ */
95
+ readonly renderEnvironment?:
96
+ | ((
97
+ environment: ExecutionEnvironment,
98
+ options?: { readonly reset?: boolean | undefined } | undefined,
99
+ ) => Effect.Effect<EnvironmentUpdate>)
100
+ | undefined
71
101
  }
72
102
  >()("clanka/AgentExecutor") {}
73
103
 
104
+ /**
105
+ * @since 1.0.0
106
+ * @category Models
107
+ */
108
+ export interface ExecuteOptions {
109
+ readonly script: string
110
+ /**
111
+ * The environment the script starts in: the `environment` of the last
112
+ * `onEnvironment` call for this agent, or `Capabilities.environment` for
113
+ * its first script.
114
+ */
115
+ readonly environment: ExecutionEnvironment
116
+ /**
117
+ * Receives the environment the script left behind, once, when the script
118
+ * ends. It is also called when the script fails, times out or is
119
+ * interrupted. Pass it to the next `execute` of the same agent.
120
+ */
121
+ readonly onEnvironment: (
122
+ environment: ExecutionEnvironment,
123
+ ) => Effect.Effect<void>
124
+ /**
125
+ * Fails with a message for the script when the task cannot be completed
126
+ * yet, for example while sub-agents are still running.
127
+ */
128
+ readonly onTaskComplete: (summary: string) => Effect.Effect<void, string>
129
+ /**
130
+ * The sub-agents of the agent running the script.
131
+ */
132
+ readonly subagents: ExecuteSubagents
133
+ /**
134
+ * Receives every image `readFile` attached while the script ran.
135
+ */
136
+ readonly onImage: (image: ImageAttachment) => Effect.Effect<void>
137
+ /**
138
+ * Functions added to the script sandbox whose handlers run on the loop
139
+ * side, next to the Agent.
140
+ */
141
+ readonly loopTools?: LoopToolHandlers | undefined
142
+ }
143
+
144
+ /**
145
+ * The sub-agents of the agent running a script. `delegate` also receives the
146
+ * environment the new agent starts in: the script's directory at the moment
147
+ * `delegate` was called, with an update holding everything that applies to
148
+ * it beyond the system prompt.
149
+ *
150
+ * @since 1.0.0
151
+ * @category Models
152
+ */
153
+ export interface ExecuteSubagents extends Omit<Subagents, "delegate"> {
154
+ readonly delegate: (options: {
155
+ readonly prompt: string
156
+ readonly background: boolean
157
+ readonly environment: EnvironmentUpdate
158
+ }) => Effect.Effect<DelegateResult>
159
+ }
160
+
161
+ /**
162
+ * The state the executor keeps for one agent, such as its working directory.
163
+ * Only the executor reads its fields. The agent stores the value it last
164
+ * received from `onEnvironment` and passes it to its next `execute`, so every
165
+ * agent has its own working directory.
166
+ *
167
+ * @since 1.0.0
168
+ * @category Models
169
+ */
170
+ export class ExecutionEnvironment extends Schema.Class<ExecutionEnvironment>(
171
+ "clanka/AgentExecutor/ExecutionEnvironment",
172
+ )({
173
+ cwd: Schema.String,
174
+ /**
175
+ * Ids of the context items already in the system prompt.
176
+ */
177
+ baseline: Schema.Array(Schema.String),
178
+ /**
179
+ * Ids of the context items sent to the model in the history since.
180
+ */
181
+ seen: Schema.Array(Schema.String),
182
+ }) {}
183
+
184
+ /**
185
+ * @since 1.0.0
186
+ * @category Models
187
+ */
188
+ export class EnvironmentUpdate extends Schema.Class<EnvironmentUpdate>(
189
+ "clanka/AgentExecutor/EnvironmentUpdate",
190
+ )({
191
+ /**
192
+ * The environment once `update` is in the history: what it describes
193
+ * counts as seen. Store it only together with the update.
194
+ */
195
+ environment: ExecutionEnvironment,
196
+ /**
197
+ * AGENTS.md files and skills the model has not seen yet, or `None` when
198
+ * nothing is new. The agent wraps it in an `<environment-update>` message.
199
+ */
200
+ update: Schema.Option(Schema.String),
201
+ }) {}
202
+
203
+ /**
204
+ * Loop-side tool handlers by function name. A handler receives the script's
205
+ * argument undecoded; a failure rejects the script's call with the string as
206
+ * the error message.
207
+ *
208
+ * @since 1.0.0
209
+ * @category Models
210
+ */
211
+ export type LoopToolHandlers = Readonly<
212
+ Record<string, (params: unknown) => Effect.Effect<unknown, string>>
213
+ >
214
+
74
215
  /**
75
216
  * @since 1.0.0
76
217
  * @category Models
77
218
  */
78
219
  export class Capabilities extends Schema.Class<Capabilities>("Capabilities")({
79
220
  toolsDts: Schema.String,
80
- agentsMd: Schema.Option(Schema.String),
221
+ /**
222
+ * The startup AGENTS.md as rendered for the system prompt, with its path.
223
+ */
224
+ instructions: Schema.Option(Schema.String),
81
225
  supportsSearch: Schema.Boolean,
226
+ /**
227
+ * The environment of an agent's first script.
228
+ */
229
+ environment: ExecutionEnvironment,
230
+ /**
231
+ * The names of the script functions the executor offers.
232
+ */
233
+ tools: Schema.Array(Schema.String),
82
234
  /**
83
235
  * Skills available on the executor filesystem.
84
236
  */
@@ -89,17 +241,58 @@ export class Capabilities extends Schema.Class<Capabilities>("Capabilities")({
89
241
  }) {}
90
242
 
91
243
  /**
244
+ * Limits applied by the executor that runs the tools. With `layerRpcServer`
245
+ * they are set on the server, next to the commands they bound.
246
+ *
92
247
  * @since 1.0.0
93
- * @category Constructors
248
+ * @category Models
94
249
  */
95
- export const makeLocal = Effect.fnUntraced(function* <
96
- Toolkit extends Toolkit.Any = never,
97
- >(options: {
250
+ export interface Limits {
251
+ /**
252
+ * The longest a single `bash` or `gh` command may run. For `bash` it is
253
+ * also the default when the model passes no `timeoutMs`, and the `bash`
254
+ * description states it.
255
+ *
256
+ * Defaults to 10 minutes for `bash` and no limit for `gh`, as before.
257
+ */
258
+ readonly commandTimeout?: Duration.Input | undefined
259
+ /**
260
+ * The longest a single `execute` script may run, including the tool calls
261
+ * it awaits. A script that runs out of time is interrupted, and its output
262
+ * so far ends with a line saying it timed out.
263
+ *
264
+ * Defaults to no limit.
265
+ */
266
+ readonly scriptTimeout?: Duration.Input | undefined
267
+ /**
268
+ * The most characters of `bash` and `gh` output held in memory per command.
269
+ * Longer output keeps its start and end, with a marker in place of the
270
+ * middle.
271
+ *
272
+ * Defaults to no limit.
273
+ */
274
+ readonly commandOutputChars?: number | undefined
275
+ }
276
+
277
+ /**
278
+ * Options for an executor that runs scripts in this process.
279
+ *
280
+ * @since 1.0.0
281
+ * @category Models
282
+ */
283
+ export interface LocalOptions<Toolkit extends Toolkit.Any = never> {
98
284
  readonly directory: string
99
285
  readonly tools?: Toolkit | undefined
100
- }): Effect.fn.Return<
101
- AgentExecutor["Service"],
102
- never,
286
+ readonly limits?: Limits | undefined
287
+ /**
288
+ * Built-in tools to leave out of the sandbox and the type declarations.
289
+ * Leaving out `delegate` also leaves out the tools that address its
290
+ * sub-agents.
291
+ */
292
+ readonly excludeTools?: ReadonlyArray<ExcludableTool> | undefined
293
+ }
294
+
295
+ type LocalServices<Toolkit> =
103
296
  | ToolkitRenderer
104
297
  | FileSystem.FileSystem
105
298
  | Path.Path
@@ -114,24 +307,87 @@ export const makeLocal = Effect.fnUntraced(function* <
114
307
  | TaskCompleter
115
308
  | ImageAttacher
116
309
  >
310
+
311
+ /**
312
+ * @since 1.0.0
313
+ * @category Constructors
314
+ */
315
+ export const makeLocal = <Toolkit extends Toolkit.Any = never>(
316
+ options: LocalOptions<Toolkit>,
317
+ ): Effect.Effect<AgentExecutor["Service"], never, LocalServices<Toolkit>> =>
318
+ Effect.map(makeLocalWith(options), (local) => local.executor)
319
+
320
+ /**
321
+ * A local executor, plus an `execute` that also reports every change to the
322
+ * environment while the script runs. `layerRpcServer` sends those changes to
323
+ * its client, so the client has the latest environment when it stops reading.
324
+ */
325
+ const makeLocalWith = Effect.fnUntraced(function* <
326
+ Toolkit extends Toolkit.Any = never,
327
+ >(
328
+ options: LocalOptions<Toolkit>,
329
+ ): Effect.fn.Return<
330
+ {
331
+ readonly executor: AgentExecutor["Service"]
332
+ readonly execute: (
333
+ options: ExecuteOptions,
334
+ onChange: (environment: ExecutionEnvironment) => Effect.Effect<void>,
335
+ ) => Stream.Stream<string>
336
+ readonly renderEnvironment: (
337
+ environment: ExecutionEnvironment,
338
+ options?: { readonly reset?: boolean | undefined } | undefined,
339
+ ) => Effect.Effect<EnvironmentUpdate>
340
+ },
341
+ never,
342
+ LocalServices<Toolkit>
117
343
  > {
118
344
  const fs = yield* FileSystem.FileSystem
119
345
  const pathService = yield* Path.Path
120
346
  const renderer = yield* ToolkitRenderer
121
- let currentDirectory = pathService.resolve(options.directory)
122
- const changeDirectory = Effect.fnUntraced(function* (directory: string) {
123
- const target = pathService.resolve(currentDirectory, directory)
347
+ const startupDirectory = pathService.resolve(options.directory)
348
+ const startupEnvironment = new ExecutionEnvironment({
349
+ cwd: startupDirectory,
350
+ baseline: [],
351
+ seen: [],
352
+ })
353
+ const resolveDirectory = Effect.fnUntraced(function* (
354
+ from: string,
355
+ directory: string,
356
+ ) {
357
+ const target = pathService.resolve(from, directory)
124
358
  const info = yield* fs.stat(target)
125
359
  if (info.type !== "Directory") {
126
360
  return yield* Effect.die(new Error(`Not a directory: ${target}`))
127
361
  }
128
- currentDirectory = target
129
362
  return target
130
363
  }, Effect.orDie)
364
+ const commandTimeout = options.limits?.commandTimeout
365
+ const commandLimits: typeof CommandLimits.Service = {
366
+ timeout:
367
+ commandTimeout === undefined
368
+ ? undefined
369
+ : Duration.fromInputUnsafe(commandTimeout),
370
+ outputChars: options.limits?.commandOutputChars,
371
+ }
372
+ const scriptTimeout = Option.map(
373
+ Option.fromUndefinedOr(options.limits?.scriptTimeout),
374
+ Duration.fromInputUnsafe,
375
+ )
376
+ const excluded = excludedToolNames(options.excludeTools)
131
377
  const search = yield* Effect.serviceOption(SemanticSearch)
132
- const hasSearch = Option.isSome(search)
378
+ const BuiltInTools = Toolkit.make(
379
+ ...Object.values(
380
+ Toolkit.merge(
381
+ Option.isSome(search) ? AgentToolsWithSearch : AgentTools,
382
+ // Same tool id, so the handler is unchanged. Only the description,
383
+ // which states the timeout, differs.
384
+ Toolkit.make(makeBashTool(commandLimits.timeout ?? defaultBashTimeout)),
385
+ ).tools as Record<string, Tool.Any>,
386
+ ).filter((tool) => !excluded.has(tool.name)),
387
+ ) as unknown as typeof AgentToolsWithSearch
388
+ const hasSearch = "search" in BuiltInTools.tools
133
389
  const AllTools = Toolkit.merge(
134
- hasSearch ? AgentToolsWithSearch : AgentTools,
390
+ BuiltInTools,
135
391
  (options.tools as unknown as Toolkit.Toolkit<{}>) ?? Toolkit.empty,
136
392
  )
137
393
  const tools = yield* AllTools
@@ -139,35 +395,110 @@ export const makeLocal = Effect.fnUntraced(function* <
139
395
 
140
396
  const services = yield* Effect.context()
141
397
 
142
- const toolEntries = Object.entries(tools.tools).map(([name, tool]) => {
143
- const handler = services.mapUnsafe.get(tool.id) as Tool.Handler<string>
144
- return {
145
- name,
146
- services: Context.merge(services, handler.context),
147
- handler: handler.handler,
148
- }
398
+ const toolEntries = new Map(
399
+ Object.entries(tools.tools).map(([name, tool]) => {
400
+ const handler = services.mapUnsafe.get(tool.id) as Tool.Handler<string>
401
+ return [
402
+ name,
403
+ {
404
+ services: Context.merge(services, handler.context),
405
+ handler: handler.handler,
406
+ },
407
+ ] as const
408
+ }),
409
+ )
410
+ const toolNames = Array.from(toolEntries.keys())
411
+
412
+ // Skills are read with readFile, so there are none without it.
413
+ const offersSkills = "readFile" in tools.tools
414
+ const home = homeDirectory()
415
+ const discoverAt = (cwd: string) =>
416
+ AgentEnvironment.discover({ cwd, startup: startupDirectory, home }).pipe(
417
+ Effect.map((discovered) =>
418
+ offersSkills ? discovered : { ...discovered, skills: [] },
419
+ ),
420
+ Effect.provideService(FileSystem.FileSystem, fs),
421
+ Effect.provideService(Path.Path, pathService),
422
+ )
423
+ // What applies to the environment's directory and is neither in the
424
+ // system prompt nor seen yet.
425
+ const renderEnvironment = Effect.fnUntraced(function* (
426
+ environment: ExecutionEnvironment,
427
+ options?: { readonly reset?: boolean | undefined } | undefined,
428
+ ) {
429
+ const seen = options?.reset ? [] : environment.seen
430
+ const known = new Set([...environment.baseline, ...seen])
431
+ const discovered = yield* discoverAt(environment.cwd)
432
+ const instructions = discovered.instructions.filter(
433
+ (item) => !known.has(item.id),
434
+ )
435
+ const skills = discovered.skills.filter(
436
+ (skill) => !known.has(AgentEnvironment.skillId(skill)),
437
+ )
438
+ const nothingNew = instructions.length === 0 && skills.length === 0
439
+ return new EnvironmentUpdate({
440
+ environment: new ExecutionEnvironment({
441
+ cwd: environment.cwd,
442
+ baseline: environment.baseline,
443
+ seen: [
444
+ ...seen,
445
+ ...instructions.map((item) => item.id),
446
+ ...skills.map(AgentEnvironment.skillId),
447
+ ],
448
+ }),
449
+ update: nothingNew
450
+ ? Option.none()
451
+ : Option.some(AgentEnvironment.renderUpdate({ instructions, skills })),
452
+ })
149
453
  })
150
454
 
151
455
  if (typeof process !== "undefined") {
152
456
  process.on("uncaughtException", () => {})
153
457
  }
154
458
 
155
- const execute = Effect.fnUntraced(function* (opts: {
156
- readonly script: string
157
- readonly onTaskComplete: (summary: string) => Effect.Effect<void>
158
- readonly onSubagent: (message: string) => Effect.Effect<string>
159
- readonly onImage: (image: ImageAttachment) => Effect.Effect<void>
160
- }) {
459
+ const execute = Effect.fnUntraced(function* (
460
+ opts: ExecuteOptions,
461
+ onChange?: (environment: ExecutionEnvironment) => Effect.Effect<void>,
462
+ ) {
161
463
  const output = yield* Queue.unbounded<string, Cause.Done>()
162
464
  const console = yield* makeConsole(output)
163
465
  const handlerScope = Scope.makeUnsafe("parallel")
164
466
  const trackFiber = Fiber.runIn(handlerScope)
165
467
 
468
+ // Owned by this script, so concurrent scripts never see each other's
469
+ // directory.
470
+ let currentDirectory = opts.environment.cwd
471
+ const currentEnvironment = () =>
472
+ new ExecutionEnvironment({
473
+ cwd: currentDirectory,
474
+ baseline: opts.environment.baseline,
475
+ seen: opts.environment.seen,
476
+ })
477
+ // The script continues only once the change has been reported.
478
+ const changeDirectory = (directory: string) =>
479
+ resolveDirectory(currentDirectory, directory).pipe(
480
+ Effect.tap((target) => {
481
+ currentDirectory = target
482
+ return onChange ? onChange(currentEnvironment()) : Effect.void
483
+ }),
484
+ )
485
+
166
486
  const taskServices = Context.empty().pipe(
167
487
  Context.add(TaskCompleter, opts.onTaskComplete),
168
488
  Context.add(DirectoryChanger, changeDirectory),
169
- Context.add(SubagentExecutor, opts.onSubagent),
489
+ Context.add(SubagentExecutor, {
490
+ ...opts.subagents,
491
+ // A new agent has only the system prompt, so it gets everything that
492
+ // applies to the directory.
493
+ delegate: (options) =>
494
+ renderEnvironment(currentEnvironment(), { reset: true }).pipe(
495
+ Effect.flatMap((environment) =>
496
+ opts.subagents.delegate({ ...options, environment }),
497
+ ),
498
+ ),
499
+ }),
170
500
  Context.add(ImageAttacher, opts.onImage),
501
+ Context.add(CommandLimits, commandLimits),
171
502
  Context.add(Console.Console, console),
172
503
  Context.add(References.CurrentLogAnnotations, {}),
173
504
  Option.isSome(search)
@@ -175,54 +506,122 @@ export const makeLocal = Effect.fnUntraced(function* <
175
506
  : identity,
176
507
  )
177
508
 
509
+ // The script runs in its own worker thread, so a script that is busy in
510
+ // JavaScript can still be stopped. Tool calls are sent back here and run
511
+ // as before.
178
512
  yield* Effect.gen(function* () {
179
- const console = yield* Console.Console
180
- let running = 0
181
-
182
- const vmScript = compileScript(opts.script)
183
- const sandbox: ScriptSandbox = {
184
- main: defaultMain,
185
- console,
186
- fetch,
187
- process: undefined,
188
- }
189
-
190
- for (let i = 0; i < toolEntries.length; i++) {
191
- const { name, handler, services } = toolEntries[i]!
192
- const toolServices = Context.merge(services, taskServices)
513
+ const source = prepareScript(opts.script)
514
+ const settled = yield* Deferred.make<void>()
515
+ const worker = yield* Effect.acquireRelease(
516
+ Effect.sync(
517
+ () =>
518
+ new Worker(workerSource, {
519
+ eval: true,
520
+ workerData: {
521
+ source,
522
+ tools: [...toolNames, ...Object.keys(opts.loopTools ?? {})],
523
+ } satisfies WorkerData,
524
+ }),
525
+ ),
526
+ (worker) => Effect.promise(() => worker.terminate()),
527
+ )
193
528
 
194
- // oxlint-disable-next-line typescript/no-explicit-any
195
- sandbox[name] = function (params: any) {
196
- const runFork = Effect.runForkWith(
197
- Context.add(toolServices, CurrentDirectory, currentDirectory),
198
- )
199
- running++
200
- const fiber = trackFiber(runFork(handler(params, {})))
201
- return new Promise((resolve, reject) => {
202
- fiber.addObserver((exit) => {
203
- running--
204
- if (exit._tag === "Success") {
205
- return resolve(exit.value)
206
- }
207
- if (Cause.hasInterruptsOnly(exit.cause)) return
208
- reject(Cause.squash(exit.cause))
209
- })
210
- })
529
+ // Every call is answered, interrupted ones included: the worker only
530
+ // reports Done once nothing is outstanding. While the script is being
531
+ // stopped the worker is already gone and the answer is dropped.
532
+ const respond = (id: number, exit: Exit.Exit<unknown, unknown>) => {
533
+ const message: ToWorker = Exit.isSuccess(exit)
534
+ ? { id, ok: true, value: exit.value }
535
+ : { id, ok: false, failure: toFailure(Cause.squash(exit.cause)) }
536
+ try {
537
+ // oxlint-disable-next-line unicorn/require-post-message-target-origin
538
+ worker.postMessage(message)
539
+ } catch (error) {
540
+ // The value cannot be copied to the worker.
541
+ // oxlint-disable-next-line unicorn/require-post-message-target-origin
542
+ worker.postMessage({ id, ok: false, failure: toFailure(error) })
211
543
  }
212
544
  }
213
545
 
214
- vmScript.runInNewContext(sandbox, {
215
- timeout: 1000,
216
- })
217
- yield* Effect.promise(sandbox.main)
218
- while (true) {
219
- yield* Effect.yieldNow
220
- if (running === 0) break
546
+ const call = (message: Extract<FromWorker, { _tag: "Call" }>) => {
547
+ const entry = toolEntries.get(message.name)
548
+ const runFork = Effect.runForkWith(
549
+ Context.add(
550
+ entry ? Context.merge(entry.services, taskServices) : taskServices,
551
+ CurrentDirectory,
552
+ currentDirectory,
553
+ ),
554
+ )
555
+ const fiber = trackFiber(
556
+ runFork(
557
+ entry
558
+ ? entry.handler(message.params, {})
559
+ : // A loop-side tool: its failure is the script's error message.
560
+ opts.loopTools![message.name]!(message.params).pipe(
561
+ Effect.catch((message) => Effect.die(new Error(message))),
562
+ ),
563
+ ),
564
+ )
565
+ fiber.addObserver((exit) => respond(message.id, exit))
221
566
  }
567
+
568
+ worker.on("message", (message: FromWorker) => {
569
+ switch (message._tag) {
570
+ case "Output":
571
+ Queue.offerUnsafe(output, message.text)
572
+ break
573
+ case "Call":
574
+ call(message)
575
+ break
576
+ case "Done":
577
+ Deferred.doneUnsafe(settled, Effect.void)
578
+ break
579
+ case "Failed":
580
+ Deferred.doneUnsafe(
581
+ settled,
582
+ Effect.die(fromFailure(message.failure)),
583
+ )
584
+ break
585
+ }
586
+ })
587
+ // Bridge failures end the script instead of leaving it pending.
588
+ worker.on("error", (error) => {
589
+ Deferred.doneUnsafe(settled, Effect.die(error))
590
+ })
591
+ worker.on("messageerror", (error) => {
592
+ Deferred.doneUnsafe(settled, Effect.die(error))
593
+ })
594
+ worker.on("exit", (code) => {
595
+ Deferred.doneUnsafe(
596
+ settled,
597
+ Effect.die(
598
+ new Error(`The script worker exited with code ${code} early`),
599
+ ),
600
+ )
601
+ })
602
+
603
+ yield* Deferred.await(settled)
222
604
  }).pipe(
605
+ // Stops the worker on every exit: done, failed, timed out, interrupted.
606
+ Effect.scoped,
607
+ Option.isSome(scriptTimeout)
608
+ ? Effect.timeoutOrElse({
609
+ duration: scriptTimeout.value,
610
+ orElse: () =>
611
+ Queue.offer(
612
+ output,
613
+ `\nScript timed out: it reached its ${Duration.toMillis(scriptTimeout.value)}ms limit and was stopped. Pending tool calls were cancelled.\n`,
614
+ ),
615
+ })
616
+ : identity,
617
+ // Interrupts the tool calls still running, and the processes they own.
223
618
  Effect.ensuring(Scope.close(handlerScope, Exit.void)),
224
619
  Effect.catchCause(Effect.logFatal),
225
620
  Effect.provideService(Console.Console, console),
621
+ // Before the output ends, so the caller has it once the stream is done.
622
+ Effect.ensuring(
623
+ Effect.suspend(() => opts.onEnvironment(currentEnvironment())),
624
+ ),
226
625
  Effect.ensuring(Queue.end(output)),
227
626
  Effect.forkScoped,
228
627
  )
@@ -230,27 +629,40 @@ export const makeLocal = Effect.fnUntraced(function* <
230
629
  return Stream.fromQueue(output)
231
630
  }, Stream.unwrap)
232
631
 
233
- return AgentExecutor.of({
632
+ const executor = AgentExecutor.of({
234
633
  capabilities: Effect.gen(function* () {
235
- const agentsMd = yield* Effect.option(
236
- fs.readFileString(pathService.join(options.directory, "AGENTS.md")),
237
- )
238
- const skills = yield* AgentSkills.discover({
239
- directory: options.directory,
240
- homeDirectory: homeDirectory(),
241
- hermesHome: Option.fromNullishOr(process.env.HERMES_HOME),
242
- }).pipe(
243
- Effect.provideService(FileSystem.FileSystem, fs),
244
- Effect.provideService(Path.Path, pathService),
245
- )
634
+ const startup = yield* discoverAt(startupDirectory)
635
+ const skills = offersSkills
636
+ ? yield* AgentSkills.discover({
637
+ directory: options.directory,
638
+ homeDirectory: home,
639
+ hermesHome: Option.fromNullishOr(process.env.HERMES_HOME),
640
+ }).pipe(
641
+ Effect.provideService(FileSystem.FileSystem, fs),
642
+ Effect.provideService(Path.Path, pathService),
643
+ )
644
+ : []
246
645
  return new Capabilities({
247
646
  toolsDts,
248
- agentsMd,
647
+ instructions: Option.map(
648
+ Option.fromNullishOr(startup.instructions.at(-1)),
649
+ AgentEnvironment.renderInstructions,
650
+ ),
249
651
  supportsSearch: hasSearch,
652
+ environment: new ExecutionEnvironment({
653
+ cwd: startupDirectory,
654
+ baseline: [
655
+ ...startup.instructions.map((item) => item.id),
656
+ ...skills.map(AgentEnvironment.skillId),
657
+ ],
658
+ seen: [],
659
+ }),
660
+ tools: Object.keys(tools.tools),
250
661
  skills,
251
662
  })
252
663
  }),
253
- execute,
664
+ execute: (opts) => execute(opts),
665
+ renderEnvironment,
254
666
  executeUnsafe: (opts) =>
255
667
  Effect.suspend(() => {
256
668
  const tool = tools.tools[opts.tool as keyof typeof tools.tools]
@@ -262,13 +674,17 @@ export const makeLocal = Effect.fnUntraced(function* <
262
674
  return Effect.die(new Error(`Unknown tool: ${opts.tool}`))
263
675
  }
264
676
 
677
+ const cwd = (opts.environment ?? startupEnvironment).cwd
265
678
  const taskServices = handler.context.pipe(
266
679
  Context.add(TaskCompleter, () => Effect.void),
267
- Context.add(CurrentDirectory, currentDirectory),
268
- Context.add(DirectoryChanger, changeDirectory),
269
- Context.add(SubagentExecutor, () => Effect.succeed("")),
680
+ Context.add(CurrentDirectory, cwd),
681
+ Context.add(DirectoryChanger, (directory) =>
682
+ resolveDirectory(cwd, directory),
683
+ ),
684
+ Context.add(SubagentExecutor, subagentsUnavailable),
270
685
  // Direct tool calls have no model turn to attach images to.
271
686
  Context.add(ImageAttacher, () => Effect.void),
687
+ Context.add(CommandLimits, commandLimits),
272
688
  Context.add(References.CurrentLogAnnotations, {}),
273
689
  Option.isSome(search)
274
690
  ? Context.add(SemanticSearch, search.value)
@@ -286,6 +702,8 @@ export const makeLocal = Effect.fnUntraced(function* <
286
702
  ) as Effect.Effect<Schema.Json>
287
703
  }),
288
704
  })
705
+
706
+ return { executor, execute, renderEnvironment }
289
707
  })
290
708
 
291
709
  /**
@@ -300,43 +718,68 @@ export const makeRpc = Effect.gen(function* () {
300
718
  return AgentExecutor.of({
301
719
  capabilities: Effect.orDie(client.capabilities()),
302
720
  execute: (opts) =>
303
- Scope.Scope.useSync((scope) =>
304
- client.execute({ script: opts.script }).pipe(
305
- Stream.tap((part) => {
306
- switch (part._tag) {
307
- case "Text": {
308
- return Effect.void
309
- }
310
- case "TaskComplete": {
311
- return opts.onTaskComplete(part.summary)
312
- }
313
- case "Subagent": {
314
- const id = part.id
315
- return pipe(
316
- opts.onSubagent(part.prompt),
317
- Effect.flatMap((output) =>
318
- client.subagentOutput({ id, output }),
319
- ),
320
- Effect.forkIn(scope),
321
- )
322
- }
323
- case "Image": {
324
- return opts.onImage({
325
- fileName: part.fileName,
326
- mediaType: part.mediaType,
327
- data: part.data,
328
- })
721
+ Scope.Scope.useSync((scope) => {
722
+ // Every change is recorded here before the server is told it arrived,
723
+ // so this is current even when the stream is interrupted early.
724
+ let latest = opts.environment
725
+ return client
726
+ .execute({
727
+ script: opts.script,
728
+ environment: opts.environment,
729
+ loopTools: Object.keys(opts.loopTools ?? {}),
730
+ })
731
+ .pipe(
732
+ Stream.tap((part) => {
733
+ switch (part._tag) {
734
+ case "Text": {
735
+ return Effect.void
736
+ }
737
+ case "Request": {
738
+ const id = part.id
739
+ if (part.request._tag === "EnvironmentChanged") {
740
+ latest = part.request.environment
741
+ }
742
+ return pipe(
743
+ handleRequest(opts, part.request),
744
+ Effect.exit,
745
+ Effect.flatMap((exit) =>
746
+ client.respond({ id, response: exitToResponse(exit) }),
747
+ ),
748
+ Effect.forkIn(scope),
749
+ )
750
+ }
751
+ case "Image": {
752
+ return opts.onImage({
753
+ fileName: part.fileName,
754
+ mediaType: part.mediaType,
755
+ data: part.data,
756
+ })
757
+ }
758
+ case "Environment": {
759
+ latest = part.environment
760
+ return Effect.void
761
+ }
329
762
  }
330
- }
331
- }),
332
- Stream.orDie,
333
- Stream.filterMap((part) =>
334
- part._tag === "Text" ? Result.succeed(part.text) : Result.failVoid,
335
- ),
336
- ),
337
- ).pipe(Stream.unwrap),
338
- executeUnsafe(options) {
339
- return client.executeUnsafe(options).pipe(Effect.orDie)
763
+ }),
764
+ Stream.orDie,
765
+ Stream.filterMap((part) =>
766
+ part._tag === "Text"
767
+ ? Result.succeed(part.text)
768
+ : Result.failVoid,
769
+ ),
770
+ Stream.ensuring(Effect.suspend(() => opts.onEnvironment(latest))),
771
+ )
772
+ }).pipe(Stream.unwrap),
773
+ renderEnvironment: (environment, options) =>
774
+ client
775
+ .renderEnvironment({ environment, reset: options?.reset ?? false })
776
+ .pipe(Effect.orDie),
777
+ executeUnsafe({ environment, ...options }) {
778
+ return client
779
+ .executeUnsafe(
780
+ environment === undefined ? options : { ...options, environment },
781
+ )
782
+ .pipe(Effect.orDie)
340
783
  },
341
784
  })
342
785
  })
@@ -345,10 +788,9 @@ export const makeRpc = Effect.gen(function* () {
345
788
  * @since 1.0.0
346
789
  * @category Layers
347
790
  */
348
- export const layerLocal = <Toolkit extends Toolkit.Any = never>(options: {
349
- readonly directory: string
350
- readonly tools?: Toolkit | undefined
351
- }): Layer.Layer<
791
+ export const layerLocal = <Toolkit extends Toolkit.Any = never>(
792
+ options: LocalOptions<Toolkit>,
793
+ ): Layer.Layer<
352
794
  AgentExecutor,
353
795
  never,
354
796
  | FileSystem.FileSystem
@@ -366,8 +808,8 @@ export const layerLocal = <Toolkit extends Toolkit.Any = never>(options: {
366
808
  | ImageAttacher
367
809
  >
368
810
  > =>
369
- Layer.effect(AgentExecutor, makeLocal(options)).pipe(
370
- Layer.provide([AgentToolHandlers, ToolkitRenderer.layer]),
811
+ Layer.effect(AgentExecutor, withBuiltInHandlers(makeLocal(options))).pipe(
812
+ Layer.provide(ToolkitRenderer.layer),
371
813
  )
372
814
 
373
815
  /**
@@ -388,10 +830,9 @@ export const layerRpc: Layer.Layer<AgentExecutor, never, RpcClient.Protocol> =
388
830
  * @since 1.0.0
389
831
  * @category Layers
390
832
  */
391
- export const layerRpcServer = <Toolkit extends Toolkit.Any = never>(options: {
392
- readonly directory: string
393
- readonly tools?: Toolkit | undefined
394
- }): Layer.Layer<
833
+ export const layerRpcServer = <Toolkit extends Toolkit.Any = never>(
834
+ options: LocalOptions<Toolkit>,
835
+ ): Layer.Layer<
395
836
  never,
396
837
  never,
397
838
  | RpcServer.Protocol
@@ -417,60 +858,123 @@ export const layerRpcServer = <Toolkit extends Toolkit.Any = never>(options: {
417
858
  Layer.provide(
418
859
  Rpcs.toLayer(
419
860
  Effect.gen(function* () {
420
- const local = yield* makeLocal(options)
421
- const subagentResumes = new Map<
861
+ const local = yield* withBuiltInHandlers(makeLocalWith(options))
862
+ const requestResumes = new Map<
422
863
  number,
423
- (effect: Effect.Effect<string>) => void
864
+ (effect: Effect.Effect<unknown, string>) => void
424
865
  >()
425
- let subagentId = 0
866
+ let requestId = 0
426
867
 
427
868
  return Rpcs.of({
428
- capabilities: () => local.capabilities,
429
- subagentOutput: ({ id, output }) => {
430
- const resume = subagentResumes.get(id)
869
+ capabilities: () => local.executor.capabilities,
870
+ renderEnvironment: ({ environment, reset }) =>
871
+ local.renderEnvironment(environment, { reset }),
872
+ respond: ({ id, response }) => {
873
+ const resume = requestResumes.get(id)
431
874
  if (resume) {
432
- resume(Effect.succeed(output))
433
- subagentResumes.delete(id)
875
+ requestResumes.delete(id)
876
+ resume(
877
+ response._tag === "Success"
878
+ ? Effect.succeed(response.value)
879
+ : Effect.fail(response.message),
880
+ )
434
881
  }
435
882
  return Effect.void
436
883
  },
437
- execute: Effect.fnUntraced(function* ({ script }) {
884
+ execute: Effect.fnUntraced(function* ({
885
+ script,
886
+ environment,
887
+ loopTools,
888
+ }) {
438
889
  const queue = yield* Queue.unbounded<
439
890
  typeof ExecuteOutput.Type,
440
891
  Cause.Done
441
892
  >()
893
+ // Sends a request to the client and waits for its response.
894
+ // IDs come from a server-wide counter, so concurrent and nested
895
+ // execute streams never collide.
896
+ // The client answers with the value of the matching callback.
897
+ const request = <A>(request: typeof AgentRequest.Type) =>
898
+ Effect.callback<A, string>((resume) => {
899
+ const id = requestId++
900
+ requestResumes.set(
901
+ id,
902
+ resume as (effect: Effect.Effect<unknown, string>) => void,
903
+ )
904
+ Queue.offerUnsafe(queue, { _tag: "Request", id, request })
905
+ return Effect.sync(() => {
906
+ requestResumes.delete(id)
907
+ })
908
+ })
442
909
  yield* pipe(
443
- local.execute({
444
- script,
445
- onTaskComplete(summary) {
446
- return Queue.offer(queue, {
447
- _tag: "TaskComplete",
448
- summary,
449
- })
450
- },
451
- onSubagent(prompt) {
452
- const id = subagentId++
453
- return Effect.callback((resume) => {
454
- subagentResumes.set(id, resume)
455
- Queue.offerUnsafe(queue, {
456
- _tag: "Subagent",
457
- id,
458
- prompt,
910
+ local.execute(
911
+ {
912
+ script,
913
+ environment,
914
+ onEnvironment: (environment) =>
915
+ Queue.offer(queue, { _tag: "Environment", environment }),
916
+ onTaskComplete: (summary) =>
917
+ request<void>({ _tag: "TaskComplete", summary }),
918
+ subagents: {
919
+ delegate: (options) =>
920
+ Effect.orDie(
921
+ request<DelegateResult>({
922
+ _tag: "Delegate",
923
+ ...options,
924
+ }),
925
+ ),
926
+ waitAgents: (ids) =>
927
+ request<ReadonlyArray<SubagentResult>>({
928
+ _tag: "WaitAgents",
929
+ ids,
930
+ }),
931
+ messageAgent: (options) =>
932
+ request<SubagentResult>({
933
+ _tag: "MessageAgent",
934
+ ...options,
935
+ }),
936
+ stopAgent: (id) =>
937
+ request<SubagentResult>({ _tag: "StopAgent", id }),
938
+ listAgents: Effect.orDie(
939
+ request<ReadonlyArray<SubagentInfo>>({
940
+ _tag: "ListAgents",
941
+ }),
942
+ ),
943
+ },
944
+ onImage(image) {
945
+ return Queue.offer(queue, {
946
+ _tag: "Image",
947
+ fileName: image.fileName,
948
+ mediaType: image.mediaType,
949
+ data: image.data,
459
950
  })
460
- return Effect.sync(() => {
461
- subagentResumes.delete(id)
462
- })
463
- })
951
+ },
952
+ loopTools: Object.fromEntries(
953
+ loopTools.map((name) => [
954
+ name,
955
+ (params: unknown) =>
956
+ toJson(name, params).pipe(
957
+ Effect.flatMap((params) =>
958
+ request<unknown>({
959
+ _tag: "LoopTool",
960
+ name,
961
+ params,
962
+ }),
963
+ ),
964
+ ),
965
+ ]),
966
+ ),
464
967
  },
465
- onImage(image) {
466
- return Queue.offer(queue, {
467
- _tag: "Image",
468
- fileName: image.fileName,
469
- mediaType: image.mediaType,
470
- data: image.data,
471
- })
472
- },
473
- }),
968
+ // Waits for the client to record the change, so a script
969
+ // that got past `changeDirectory` never leaves it behind.
970
+ (environment) =>
971
+ Effect.orDie(
972
+ request<void>({
973
+ _tag: "EnvironmentChanged",
974
+ environment,
975
+ }),
976
+ ),
977
+ ),
474
978
  Stream.runForEachArray((parts) => {
475
979
  for (const part of parts) {
476
980
  Queue.offerUnsafe(queue, {
@@ -491,28 +995,67 @@ export const layerRpcServer = <Toolkit extends Toolkit.Any = never>(options: {
491
995
  return queue
492
996
  }),
493
997
  executeUnsafe(opts) {
494
- return local.executeUnsafe(opts as any)
998
+ return local.executor.executeUnsafe(opts as any)
495
999
  },
496
1000
  })
497
1001
  }),
498
1002
  ),
499
1003
  ),
500
- Layer.provide([AgentToolHandlers, ToolkitRenderer.layer]),
1004
+ Layer.provide(ToolkitRenderer.layer),
501
1005
  )
502
1006
 
1007
+ /**
1008
+ * @since 1.0.0
1009
+ * @category Rpcs
1010
+ */
1011
+ export const AgentRequest = Schema.TaggedUnion({
1012
+ TaskComplete: { summary: Schema.String },
1013
+ Delegate: {
1014
+ prompt: Schema.String,
1015
+ background: Schema.Boolean,
1016
+ environment: EnvironmentUpdate,
1017
+ },
1018
+ WaitAgents: { ids: Schema.UndefinedOr(Schema.Array(Schema.String)) },
1019
+ MessageAgent: { id: Schema.String, message: Schema.String },
1020
+ StopAgent: { id: Schema.String },
1021
+ ListAgents: {},
1022
+ LoopTool: { name: Schema.String, params: Schema.optional(Schema.Json) },
1023
+ /**
1024
+ * The script changed its environment. The client records it before it
1025
+ * responds.
1026
+ */
1027
+ EnvironmentChanged: { environment: ExecutionEnvironment },
1028
+ })
1029
+
1030
+ /**
1031
+ * The client's answer to a `Request`. `Failure` carries a message for the
1032
+ * script; a failed foreground `delegate` is raised there as a defect.
1033
+ *
1034
+ * @since 1.0.0
1035
+ * @category Rpcs
1036
+ */
1037
+ export const AgentResponse = Schema.TaggedUnion({
1038
+ Success: { value: Schema.Json },
1039
+ Failure: { message: Schema.String },
1040
+ })
1041
+
503
1042
  /**
504
1043
  * @since 1.0.0
505
1044
  * @category Rpcs
506
1045
  */
507
1046
  export const ExecuteOutput = Schema.TaggedUnion({
508
1047
  Text: { text: Schema.String },
509
- TaskComplete: { summary: Schema.String },
510
- Subagent: { id: Schema.Finite, prompt: Schema.String },
1048
+ Request: { id: Schema.Finite, request: AgentRequest },
511
1049
  Image: {
512
1050
  fileName: Schema.String,
513
1051
  mediaType: Image.ImageMediaType,
514
1052
  data: Schema.Uint8Array,
515
1053
  },
1054
+ /**
1055
+ * Sent once, when the script ends. Changes before then are sent as
1056
+ * `EnvironmentChanged` requests.
1057
+ */
1058
+ Environment: { environment: ExecutionEnvironment },
516
1059
  })
517
1060
 
518
1061
  /**
@@ -523,23 +1066,35 @@ export class Rpcs extends RpcGroup.make(
523
1066
  Rpc.make("capabilities", {
524
1067
  success: Capabilities,
525
1068
  }),
526
- Rpc.make("subagentOutput", {
1069
+ Rpc.make("respond", {
527
1070
  payload: {
528
1071
  id: Schema.Finite,
529
- output: Schema.String,
1072
+ response: AgentResponse,
530
1073
  },
531
1074
  }),
532
1075
  Rpc.make("execute", {
533
1076
  payload: Schema.Struct({
534
1077
  script: Schema.String,
1078
+ environment: ExecutionEnvironment,
1079
+ /**
1080
+ * The loop-side tools to add to the script sandbox.
1081
+ */
1082
+ loopTools: Schema.Array(Schema.String).pipe(
1083
+ Schema.withDecodingDefaultKey(Effect.succeed([])),
1084
+ ),
535
1085
  }),
536
1086
  success: ExecuteOutput,
537
1087
  stream: true,
538
1088
  }),
1089
+ Rpc.make("renderEnvironment", {
1090
+ payload: { environment: ExecutionEnvironment, reset: Schema.Boolean },
1091
+ success: EnvironmentUpdate,
1092
+ }),
539
1093
  Rpc.make("executeUnsafe", {
540
1094
  payload: Schema.Struct({
541
1095
  tool: Schema.String,
542
1096
  params: Schema.Json,
1097
+ environment: Schema.optionalKey(ExecutionEnvironment),
543
1098
  }),
544
1099
  success: Schema.Json,
545
1100
  }),
@@ -549,19 +1104,119 @@ export class Rpcs extends RpcGroup.make(
549
1104
  // Internal
550
1105
  // -------------------------------------------
551
1106
 
552
- interface ScriptSandbox {
553
- main: () => Promise<void>
554
- console: Console.Console
555
- [toolName: string]: unknown
1107
+ const handleRequest = (
1108
+ opts: ExecuteOptions,
1109
+ request: typeof AgentRequest.Type,
1110
+ ): Effect.Effect<unknown, string> => {
1111
+ switch (request._tag) {
1112
+ case "TaskComplete":
1113
+ return opts.onTaskComplete(request.summary)
1114
+ case "Delegate":
1115
+ return opts.subagents.delegate(request)
1116
+ case "WaitAgents":
1117
+ return opts.subagents.waitAgents(request.ids)
1118
+ case "MessageAgent":
1119
+ return opts.subagents.messageAgent(request)
1120
+ case "StopAgent":
1121
+ return opts.subagents.stopAgent(request.id)
1122
+ case "ListAgents":
1123
+ return opts.subagents.listAgents
1124
+ case "EnvironmentChanged":
1125
+ // Recorded by the client before it responds.
1126
+ return Effect.void
1127
+ case "LoopTool": {
1128
+ const handler = opts.loopTools?.[request.name]
1129
+ return handler
1130
+ ? handler(request.params)
1131
+ : Effect.fail(`Unknown loop-side tool: ${request.name}`)
1132
+ }
1133
+ }
1134
+ }
1135
+
1136
+ // Script arguments cross the RPC boundary as JSON.
1137
+ const toJson = (
1138
+ name: string,
1139
+ params: unknown,
1140
+ ): Effect.Effect<Schema.Json | undefined, string> =>
1141
+ Effect.try({
1142
+ try: () => {
1143
+ const json = JSON.stringify(params)
1144
+ return json === undefined ? undefined : (JSON.parse(json) as Schema.Json)
1145
+ },
1146
+ catch: (error) => `Invalid arguments for ${name}: ${errorMessage(error)}`,
1147
+ })
1148
+
1149
+ // The built-in handlers sit underneath the caller's context, so a caller tool
1150
+ // named like a built-in keeps its own handler.
1151
+ const withBuiltInHandlers = <A, E, R>(
1152
+ effect: Effect.Effect<A, E, R>,
1153
+ ): Effect.Effect<
1154
+ A,
1155
+ E,
1156
+ | Exclude<R, Tool.HandlersFor<typeof AgentToolsWithSearch.tools>>
1157
+ | Scope.Scope
1158
+ | FileSystem.FileSystem
1159
+ | Path.Path
1160
+ | ChildProcessSpawner.ChildProcessSpawner
1161
+ | HttpClient.HttpClient
1162
+ > =>
1163
+ Effect.flatMap(Layer.build(AgentToolHandlers), (builtIns) =>
1164
+ Effect.updateContext(
1165
+ effect,
1166
+ (context: Context.Context<never>) =>
1167
+ Context.merge(builtIns, context) as Context.Context<R>,
1168
+ ),
1169
+ ) as any
1170
+
1171
+ const exitToResponse = (
1172
+ exit: Exit.Exit<unknown, string>,
1173
+ ): typeof AgentResponse.Type => {
1174
+ if (Exit.isSuccess(exit)) {
1175
+ return { _tag: "Success", value: (exit.value ?? null) as Schema.Json }
1176
+ }
1177
+ return { _tag: "Failure", message: errorMessage(Cause.squash(exit.cause)) }
1178
+ }
1179
+
1180
+ const errorMessage = (error: unknown): string =>
1181
+ typeof error === "string"
1182
+ ? error
1183
+ : error instanceof Error
1184
+ ? error.message
1185
+ : String(error)
1186
+
1187
+ // Leaving out `delegate` leaves out the tools that address its sub-agents.
1188
+ const excludedToolNames = (
1189
+ excludeTools: ReadonlyArray<ExcludableTool> | undefined,
1190
+ ): ReadonlySet<string> => {
1191
+ const names = new Set<string>(excludeTools)
1192
+ if (names.has("delegate")) {
1193
+ for (const name of [
1194
+ "waitAgents",
1195
+ "messageAgent",
1196
+ "stopAgent",
1197
+ "listAgents",
1198
+ ]) {
1199
+ names.add(name)
1200
+ }
1201
+ }
1202
+ return names
556
1203
  }
557
1204
 
558
1205
  const wrapScript = (script: string): string => `async function main() {
559
1206
  ${script}
560
1207
  }`
561
1208
 
562
- const compileScript = (script: string): NodeVm.Script => {
1209
+ /**
1210
+ * Returns source that compiles, preprocessing the script if it has syntax
1211
+ * errors. Throws the original syntax error if neither version compiles.
1212
+ */
1213
+ const prepareScript = (script: string): string => {
1214
+ const source = wrapScript(script)
563
1215
  try {
564
- return new NodeVm.Script(wrapScript(script))
1216
+ // Compiled only to check the syntax. The worker compiles it again.
1217
+ // oxlint-disable-next-line eslint/no-new
1218
+ new NodeVm.Script(source)
1219
+ return source
565
1220
  } catch (error) {
566
1221
  if (!(error instanceof SyntaxError)) {
567
1222
  throw error
@@ -572,15 +1227,197 @@ const compileScript = (script: string): NodeVm.Script => {
572
1227
  throw error
573
1228
  }
574
1229
 
1230
+ const preprocessedSource = wrapScript(preprocessed)
575
1231
  try {
576
- return new NodeVm.Script(wrapScript(preprocessed))
1232
+ // oxlint-disable-next-line eslint/no-new
1233
+ new NodeVm.Script(preprocessedSource)
1234
+ return preprocessedSource
577
1235
  } catch {
578
1236
  throw error
579
1237
  }
580
1238
  }
581
1239
  }
582
1240
 
583
- const defaultMain = () => Promise.resolve()
1241
+ interface WorkerData {
1242
+ readonly source: string
1243
+ readonly tools: ReadonlyArray<string>
1244
+ }
1245
+
1246
+ /**
1247
+ * A rejection crossing the worker boundary. Errors keep their name, message
1248
+ * and stack. Other values are copied, or turned into a string when they
1249
+ * cannot be.
1250
+ */
1251
+ type Failure =
1252
+ | {
1253
+ readonly _tag: "Error"
1254
+ readonly name: string
1255
+ readonly message: string
1256
+ readonly stack: string | undefined
1257
+ }
1258
+ | { readonly _tag: "Value"; readonly value: unknown }
1259
+
1260
+ type FromWorker =
1261
+ | { readonly _tag: "Output"; readonly text: string }
1262
+ | {
1263
+ readonly _tag: "Call"
1264
+ readonly id: number
1265
+ readonly name: string
1266
+ readonly params: unknown
1267
+ }
1268
+ | { readonly _tag: "Done" }
1269
+ | { readonly _tag: "Failed"; readonly failure: Failure }
1270
+
1271
+ type ToWorker =
1272
+ | { readonly id: number; readonly ok: true; readonly value: unknown }
1273
+ | { readonly id: number; readonly ok: false; readonly failure: Failure }
1274
+
1275
+ // -------------------------------------------
1276
+ // Script worker
1277
+ //
1278
+ // The worker runs from source text (`new Worker(source, { eval: true })`), so
1279
+ // it needs no separate file in the package, the CLI bundle or a consumer's
1280
+ // bundle. The source is built from the function declarations below with
1281
+ // `Function.prototype.toString`, which keeps them type-checked and shared
1282
+ // with the parent instead of copied into a string.
1283
+ //
1284
+ // Constraints, because the text of each function must run on its own:
1285
+ // - Each must be a `function` declaration, so its text carries its name.
1286
+ // - They may reference only each other, their parameters and globals: no
1287
+ // imports, module-level values or closures.
1288
+ // - Node modules are loaded with the `load` parameter, which the source text
1289
+ // binds to the worker's `require`. Bundlers rewrite a bare `require` (the
1290
+ // CLI bundle turns it into `__require`), but leave a parameter alone.
1291
+ // - A bundler must keep their bodies whole. Renaming identifiers
1292
+ // consistently is fine. Transforms that move code out of a body, such as
1293
+ // coverage instrumentation or helper hoisting, are not. Only the
1294
+ // library build and the CLI bundle are checked.
1295
+ // The executor tests run every script through this worker, so they catch a
1296
+ // broken constraint in the source. They run the source, not a bundle, so a
1297
+ // bundler's rewrites only show up when the built output is run.
1298
+ // -------------------------------------------
1299
+
1300
+ function toFailure(value: unknown): Failure {
1301
+ if (Object.prototype.toString.call(value) === "[object Error]") {
1302
+ const error = value as Error
1303
+ return {
1304
+ _tag: "Error",
1305
+ name: error.name,
1306
+ message: error.message,
1307
+ stack: error.stack,
1308
+ }
1309
+ }
1310
+ try {
1311
+ return { _tag: "Value", value: structuredClone(value) }
1312
+ } catch {
1313
+ return { _tag: "Value", value: String(value) }
1314
+ }
1315
+ }
1316
+
1317
+ function fromFailure(failure: Failure): unknown {
1318
+ if (failure._tag === "Value") return failure.value
1319
+ const error = new Error(failure.message)
1320
+ error.name = failure.name
1321
+ if (failure.stack !== undefined) error.stack = failure.stack
1322
+ return error
1323
+ }
1324
+
1325
+ /**
1326
+ * Runs one script inside a vm context with the same globals as before, and
1327
+ * forwards console output and tool calls to the parent.
1328
+ */
1329
+ function runScriptWorker(load: (id: string) => unknown): void {
1330
+ // Type-only references: the casts are erased, so the text stays
1331
+ // self-contained.
1332
+ const { parentPort, workerData } = load(
1333
+ "node:worker_threads",
1334
+ ) as typeof NodeWorkerThreads
1335
+ const vm = load("node:vm") as typeof NodeVm
1336
+ const { Console } = load("node:console") as typeof NodeConsole
1337
+ const { Writable: WorkerWritable } = load("node:stream") as {
1338
+ readonly Writable: typeof Writable
1339
+ }
1340
+ const port = parentPort!
1341
+ const data = workerData as WorkerData
1342
+
1343
+ // Like the parent process: a stray rejection must not end the script.
1344
+ process.on("uncaughtException", () => {})
1345
+ process.on("unhandledRejection", () => {})
1346
+
1347
+ const post = (message: FromWorker) => port.postMessage(message)
1348
+
1349
+ const pending = new Map<
1350
+ number,
1351
+ {
1352
+ readonly resolve: (value: unknown) => void
1353
+ readonly reject: (error: unknown) => void
1354
+ }
1355
+ >()
1356
+ let nextId = 0
1357
+ let mainSettled = false
1358
+ let done = false
1359
+ // Done once main() has settled and no tool call is outstanding. The check
1360
+ // runs after the microtasks a result triggers, so a continuation that
1361
+ // calls another tool is waited for too. Done is sent once.
1362
+ const maybeDone = () => {
1363
+ if (done || !mainSettled || pending.size > 0) return
1364
+ setImmediate(() => {
1365
+ if (done || pending.size > 0) return
1366
+ done = true
1367
+ post({ _tag: "Done" })
1368
+ })
1369
+ }
1370
+ port.on("message", (message: ToWorker) => {
1371
+ const call = pending.get(message.id)
1372
+ if (call === undefined) return
1373
+ pending.delete(message.id)
1374
+ if (message.ok) call.resolve(message.value)
1375
+ else call.reject(fromFailure(message.failure))
1376
+ maybeDone()
1377
+ })
1378
+
1379
+ const stdout = new WorkerWritable({
1380
+ write(chunk, _encoding, callback) {
1381
+ post({ _tag: "Output", text: String(chunk) })
1382
+ callback()
1383
+ },
1384
+ })
1385
+
1386
+ const sandbox: Record<string, unknown> = {
1387
+ console: new Console({ stdout, colorMode: false }),
1388
+ fetch,
1389
+ process: undefined,
1390
+ }
1391
+ for (const name of data.tools) {
1392
+ sandbox[name] = (params: unknown) =>
1393
+ new Promise((resolve, reject) => {
1394
+ const id = nextId++
1395
+ pending.set(id, { resolve, reject })
1396
+ try {
1397
+ post({ _tag: "Call", id, name, params })
1398
+ } catch (error) {
1399
+ // The params cannot be copied to the parent.
1400
+ pending.delete(id)
1401
+ reject(error)
1402
+ maybeDone()
1403
+ }
1404
+ })
1405
+ }
1406
+
1407
+ new vm.Script(data.source).runInNewContext(sandbox)
1408
+ ;(sandbox.main as () => Promise<void>)().then(
1409
+ () => {
1410
+ mainSettled = true
1411
+ maybeDone()
1412
+ },
1413
+ (error) => post({ _tag: "Failed", failure: toFailure(error) }),
1414
+ )
1415
+ }
1416
+
1417
+ const workerSource = `${toFailure}
1418
+ ${fromFailure}
1419
+ (${runScriptWorker})(require)
1420
+ `
584
1421
 
585
1422
  const homeDirectory = (): Option.Option<string> => {
586
1423
  const fromEnv = process.env.HOME