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,11 +5,15 @@ 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 { AgentToolHandlers, AgentTools, AgentToolsWithSearch, CurrentDirectory, DirectoryChanger, ImageAttacher, SubagentExecutor, TaskCompleter, } from "./AgentTools.js";
8
+ import { Worker } from "node:worker_threads";
9
+ import { AgentToolHandlers, AgentTools, AgentToolsWithSearch, CommandLimits, CurrentDirectory, defaultBashTimeout, DirectoryChanger, ImageAttacher, makeBashTool, SubagentExecutor, subagentsUnavailable, TaskCompleter, } from "./AgentTools.js";
9
10
  import * as Image from "./Image.js";
10
11
  import { ToolkitRenderer } from "./ToolkitRenderer.js";
12
+ import * as AgentEnvironment from "./AgentEnvironment.js";
11
13
  import * as AgentSkills from "./AgentSkills.js";
12
14
  import * as Context from "effect/Context";
15
+ import * as Deferred from "effect/Deferred";
16
+ import * as Duration from "effect/Duration";
13
17
  import * as Effect from "effect/Effect";
14
18
  import * as Option from "effect/Option";
15
19
  import * as Stream from "effect/Stream";
@@ -39,14 +43,63 @@ import * as References from "effect/References";
39
43
  */
40
44
  export class AgentExecutor extends Context.Service()("clanka/AgentExecutor") {
41
45
  }
46
+ /**
47
+ * The state the executor keeps for one agent, such as its working directory.
48
+ * Only the executor reads its fields. The agent stores the value it last
49
+ * received from `onEnvironment` and passes it to its next `execute`, so every
50
+ * agent has its own working directory.
51
+ *
52
+ * @since 1.0.0
53
+ * @category Models
54
+ */
55
+ export class ExecutionEnvironment extends Schema.Class("clanka/AgentExecutor/ExecutionEnvironment")({
56
+ cwd: Schema.String,
57
+ /**
58
+ * Ids of the context items already in the system prompt.
59
+ */
60
+ baseline: Schema.Array(Schema.String),
61
+ /**
62
+ * Ids of the context items sent to the model in the history since.
63
+ */
64
+ seen: Schema.Array(Schema.String),
65
+ }) {
66
+ }
67
+ /**
68
+ * @since 1.0.0
69
+ * @category Models
70
+ */
71
+ export class EnvironmentUpdate extends Schema.Class("clanka/AgentExecutor/EnvironmentUpdate")({
72
+ /**
73
+ * The environment once `update` is in the history: what it describes
74
+ * counts as seen. Store it only together with the update.
75
+ */
76
+ environment: ExecutionEnvironment,
77
+ /**
78
+ * AGENTS.md files and skills the model has not seen yet, or `None` when
79
+ * nothing is new. The agent wraps it in an `<environment-update>` message.
80
+ */
81
+ update: Schema.Option(Schema.String),
82
+ }) {
83
+ }
42
84
  /**
43
85
  * @since 1.0.0
44
86
  * @category Models
45
87
  */
46
88
  export class Capabilities extends Schema.Class("Capabilities")({
47
89
  toolsDts: Schema.String,
48
- agentsMd: Schema.Option(Schema.String),
90
+ /**
91
+ * The startup AGENTS.md as rendered for the system prompt, with its path.
92
+ */
93
+ instructions: Schema.Option(Schema.String),
49
94
  supportsSearch: Schema.Boolean,
95
+ /**
96
+ * The environment of an agent's first script.
97
+ */
98
+ environment: ExecutionEnvironment,
99
+ /**
100
+ * The names of the script functions the executor offers.
101
+ */
102
+ tools: Schema.Array(Schema.String),
50
103
  /**
51
104
  * Skills available on the executor filesystem.
52
105
  */
@@ -57,104 +110,225 @@ export class Capabilities extends Schema.Class("Capabilities")({
57
110
  * @since 1.0.0
58
111
  * @category Constructors
59
112
  */
60
- export const makeLocal = Effect.fnUntraced(function* (options) {
113
+ export const makeLocal = (options) => Effect.map(makeLocalWith(options), (local) => local.executor);
114
+ /**
115
+ * A local executor, plus an `execute` that also reports every change to the
116
+ * environment while the script runs. `layerRpcServer` sends those changes to
117
+ * its client, so the client has the latest environment when it stops reading.
118
+ */
119
+ const makeLocalWith = Effect.fnUntraced(function* (options) {
61
120
  const fs = yield* FileSystem.FileSystem;
62
121
  const pathService = yield* Path.Path;
63
122
  const renderer = yield* ToolkitRenderer;
64
- let currentDirectory = pathService.resolve(options.directory);
65
- const changeDirectory = Effect.fnUntraced(function* (directory) {
66
- const target = pathService.resolve(currentDirectory, directory);
123
+ const startupDirectory = pathService.resolve(options.directory);
124
+ const startupEnvironment = new ExecutionEnvironment({
125
+ cwd: startupDirectory,
126
+ baseline: [],
127
+ seen: [],
128
+ });
129
+ const resolveDirectory = Effect.fnUntraced(function* (from, directory) {
130
+ const target = pathService.resolve(from, directory);
67
131
  const info = yield* fs.stat(target);
68
132
  if (info.type !== "Directory") {
69
133
  return yield* Effect.die(new Error(`Not a directory: ${target}`));
70
134
  }
71
- currentDirectory = target;
72
135
  return target;
73
136
  }, Effect.orDie);
137
+ const commandTimeout = options.limits?.commandTimeout;
138
+ const commandLimits = {
139
+ timeout: commandTimeout === undefined
140
+ ? undefined
141
+ : Duration.fromInputUnsafe(commandTimeout),
142
+ outputChars: options.limits?.commandOutputChars,
143
+ };
144
+ const scriptTimeout = Option.map(Option.fromUndefinedOr(options.limits?.scriptTimeout), Duration.fromInputUnsafe);
145
+ const excluded = excludedToolNames(options.excludeTools);
74
146
  const search = yield* Effect.serviceOption(SemanticSearch);
75
- const hasSearch = Option.isSome(search);
76
- const AllTools = Toolkit.merge(hasSearch ? AgentToolsWithSearch : AgentTools, options.tools ?? Toolkit.empty);
147
+ const BuiltInTools = Toolkit.make(...Object.values(Toolkit.merge(Option.isSome(search) ? AgentToolsWithSearch : AgentTools,
148
+ // Same tool id, so the handler is unchanged. Only the description,
149
+ // which states the timeout, differs.
150
+ Toolkit.make(makeBashTool(commandLimits.timeout ?? defaultBashTimeout))).tools).filter((tool) => !excluded.has(tool.name)));
151
+ const hasSearch = "search" in BuiltInTools.tools;
152
+ const AllTools = Toolkit.merge(BuiltInTools, options.tools ?? Toolkit.empty);
77
153
  const tools = yield* AllTools;
78
154
  const toolsDts = renderer.render(AllTools);
79
155
  const services = yield* Effect.context();
80
- const toolEntries = Object.entries(tools.tools).map(([name, tool]) => {
156
+ const toolEntries = new Map(Object.entries(tools.tools).map(([name, tool]) => {
81
157
  const handler = services.mapUnsafe.get(tool.id);
82
- return {
158
+ return [
83
159
  name,
84
- services: Context.merge(services, handler.context),
85
- handler: handler.handler,
86
- };
160
+ {
161
+ services: Context.merge(services, handler.context),
162
+ handler: handler.handler,
163
+ },
164
+ ];
165
+ }));
166
+ const toolNames = Array.from(toolEntries.keys());
167
+ // Skills are read with readFile, so there are none without it.
168
+ const offersSkills = "readFile" in tools.tools;
169
+ const home = homeDirectory();
170
+ const discoverAt = (cwd) => AgentEnvironment.discover({ cwd, startup: startupDirectory, home }).pipe(Effect.map((discovered) => offersSkills ? discovered : { ...discovered, skills: [] }), Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, pathService));
171
+ // What applies to the environment's directory and is neither in the
172
+ // system prompt nor seen yet.
173
+ const renderEnvironment = Effect.fnUntraced(function* (environment, options) {
174
+ const seen = options?.reset ? [] : environment.seen;
175
+ const known = new Set([...environment.baseline, ...seen]);
176
+ const discovered = yield* discoverAt(environment.cwd);
177
+ const instructions = discovered.instructions.filter((item) => !known.has(item.id));
178
+ const skills = discovered.skills.filter((skill) => !known.has(AgentEnvironment.skillId(skill)));
179
+ const nothingNew = instructions.length === 0 && skills.length === 0;
180
+ return new EnvironmentUpdate({
181
+ environment: new ExecutionEnvironment({
182
+ cwd: environment.cwd,
183
+ baseline: environment.baseline,
184
+ seen: [
185
+ ...seen,
186
+ ...instructions.map((item) => item.id),
187
+ ...skills.map(AgentEnvironment.skillId),
188
+ ],
189
+ }),
190
+ update: nothingNew
191
+ ? Option.none()
192
+ : Option.some(AgentEnvironment.renderUpdate({ instructions, skills })),
193
+ });
87
194
  });
88
195
  if (typeof process !== "undefined") {
89
196
  process.on("uncaughtException", () => { });
90
197
  }
91
- const execute = Effect.fnUntraced(function* (opts) {
198
+ const execute = Effect.fnUntraced(function* (opts, onChange) {
92
199
  const output = yield* Queue.unbounded();
93
200
  const console = yield* makeConsole(output);
94
201
  const handlerScope = Scope.makeUnsafe("parallel");
95
202
  const trackFiber = Fiber.runIn(handlerScope);
96
- const taskServices = Context.empty().pipe(Context.add(TaskCompleter, opts.onTaskComplete), Context.add(DirectoryChanger, changeDirectory), Context.add(SubagentExecutor, opts.onSubagent), Context.add(ImageAttacher, opts.onImage), Context.add(Console.Console, console), Context.add(References.CurrentLogAnnotations, {}), Option.isSome(search)
203
+ // Owned by this script, so concurrent scripts never see each other's
204
+ // directory.
205
+ let currentDirectory = opts.environment.cwd;
206
+ const currentEnvironment = () => new ExecutionEnvironment({
207
+ cwd: currentDirectory,
208
+ baseline: opts.environment.baseline,
209
+ seen: opts.environment.seen,
210
+ });
211
+ // The script continues only once the change has been reported.
212
+ const changeDirectory = (directory) => resolveDirectory(currentDirectory, directory).pipe(Effect.tap((target) => {
213
+ currentDirectory = target;
214
+ return onChange ? onChange(currentEnvironment()) : Effect.void;
215
+ }));
216
+ const taskServices = Context.empty().pipe(Context.add(TaskCompleter, opts.onTaskComplete), Context.add(DirectoryChanger, changeDirectory), Context.add(SubagentExecutor, {
217
+ ...opts.subagents,
218
+ // A new agent has only the system prompt, so it gets everything that
219
+ // applies to the directory.
220
+ delegate: (options) => renderEnvironment(currentEnvironment(), { reset: true }).pipe(Effect.flatMap((environment) => opts.subagents.delegate({ ...options, environment }))),
221
+ }), Context.add(ImageAttacher, opts.onImage), Context.add(CommandLimits, commandLimits), Context.add(Console.Console, console), Context.add(References.CurrentLogAnnotations, {}), Option.isSome(search)
97
222
  ? Context.add(SemanticSearch, search.value)
98
223
  : identity);
224
+ // The script runs in its own worker thread, so a script that is busy in
225
+ // JavaScript can still be stopped. Tool calls are sent back here and run
226
+ // as before.
99
227
  yield* Effect.gen(function* () {
100
- const console = yield* Console.Console;
101
- let running = 0;
102
- const vmScript = compileScript(opts.script);
103
- const sandbox = {
104
- main: defaultMain,
105
- console,
106
- fetch,
107
- process: undefined,
228
+ const source = prepareScript(opts.script);
229
+ const settled = yield* Deferred.make();
230
+ const worker = yield* Effect.acquireRelease(Effect.sync(() => new Worker(workerSource, {
231
+ eval: true,
232
+ workerData: {
233
+ source,
234
+ tools: [...toolNames, ...Object.keys(opts.loopTools ?? {})],
235
+ },
236
+ })), (worker) => Effect.promise(() => worker.terminate()));
237
+ // Every call is answered, interrupted ones included: the worker only
238
+ // reports Done once nothing is outstanding. While the script is being
239
+ // stopped the worker is already gone and the answer is dropped.
240
+ const respond = (id, exit) => {
241
+ const message = Exit.isSuccess(exit)
242
+ ? { id, ok: true, value: exit.value }
243
+ : { id, ok: false, failure: toFailure(Cause.squash(exit.cause)) };
244
+ try {
245
+ // oxlint-disable-next-line unicorn/require-post-message-target-origin
246
+ worker.postMessage(message);
247
+ }
248
+ catch (error) {
249
+ // The value cannot be copied to the worker.
250
+ // oxlint-disable-next-line unicorn/require-post-message-target-origin
251
+ worker.postMessage({ id, ok: false, failure: toFailure(error) });
252
+ }
108
253
  };
109
- for (let i = 0; i < toolEntries.length; i++) {
110
- const { name, handler, services } = toolEntries[i];
111
- const toolServices = Context.merge(services, taskServices);
112
- // oxlint-disable-next-line typescript/no-explicit-any
113
- sandbox[name] = function (params) {
114
- const runFork = Effect.runForkWith(Context.add(toolServices, CurrentDirectory, currentDirectory));
115
- running++;
116
- const fiber = trackFiber(runFork(handler(params, {})));
117
- return new Promise((resolve, reject) => {
118
- fiber.addObserver((exit) => {
119
- running--;
120
- if (exit._tag === "Success") {
121
- return resolve(exit.value);
122
- }
123
- if (Cause.hasInterruptsOnly(exit.cause))
124
- return;
125
- reject(Cause.squash(exit.cause));
126
- });
127
- });
128
- };
129
- }
130
- vmScript.runInNewContext(sandbox, {
131
- timeout: 1000,
254
+ const call = (message) => {
255
+ const entry = toolEntries.get(message.name);
256
+ const runFork = Effect.runForkWith(Context.add(entry ? Context.merge(entry.services, taskServices) : taskServices, CurrentDirectory, currentDirectory));
257
+ const fiber = trackFiber(runFork(entry
258
+ ? entry.handler(message.params, {})
259
+ : // A loop-side tool: its failure is the script's error message.
260
+ opts.loopTools[message.name](message.params).pipe(Effect.catch((message) => Effect.die(new Error(message))))));
261
+ fiber.addObserver((exit) => respond(message.id, exit));
262
+ };
263
+ worker.on("message", (message) => {
264
+ switch (message._tag) {
265
+ case "Output":
266
+ Queue.offerUnsafe(output, message.text);
267
+ break;
268
+ case "Call":
269
+ call(message);
270
+ break;
271
+ case "Done":
272
+ Deferred.doneUnsafe(settled, Effect.void);
273
+ break;
274
+ case "Failed":
275
+ Deferred.doneUnsafe(settled, Effect.die(fromFailure(message.failure)));
276
+ break;
277
+ }
132
278
  });
133
- yield* Effect.promise(sandbox.main);
134
- while (true) {
135
- yield* Effect.yieldNow;
136
- if (running === 0)
137
- break;
138
- }
139
- }).pipe(Effect.ensuring(Scope.close(handlerScope, Exit.void)), Effect.catchCause(Effect.logFatal), Effect.provideService(Console.Console, console), Effect.ensuring(Queue.end(output)), Effect.forkScoped);
279
+ // Bridge failures end the script instead of leaving it pending.
280
+ worker.on("error", (error) => {
281
+ Deferred.doneUnsafe(settled, Effect.die(error));
282
+ });
283
+ worker.on("messageerror", (error) => {
284
+ Deferred.doneUnsafe(settled, Effect.die(error));
285
+ });
286
+ worker.on("exit", (code) => {
287
+ Deferred.doneUnsafe(settled, Effect.die(new Error(`The script worker exited with code ${code} early`)));
288
+ });
289
+ yield* Deferred.await(settled);
290
+ }).pipe(
291
+ // Stops the worker on every exit: done, failed, timed out, interrupted.
292
+ Effect.scoped, Option.isSome(scriptTimeout)
293
+ ? Effect.timeoutOrElse({
294
+ duration: scriptTimeout.value,
295
+ orElse: () => Queue.offer(output, `\nScript timed out: it reached its ${Duration.toMillis(scriptTimeout.value)}ms limit and was stopped. Pending tool calls were cancelled.\n`),
296
+ })
297
+ : identity,
298
+ // Interrupts the tool calls still running, and the processes they own.
299
+ Effect.ensuring(Scope.close(handlerScope, Exit.void)), Effect.catchCause(Effect.logFatal), Effect.provideService(Console.Console, console),
300
+ // Before the output ends, so the caller has it once the stream is done.
301
+ Effect.ensuring(Effect.suspend(() => opts.onEnvironment(currentEnvironment()))), Effect.ensuring(Queue.end(output)), Effect.forkScoped);
140
302
  return Stream.fromQueue(output);
141
303
  }, Stream.unwrap);
142
- return AgentExecutor.of({
304
+ const executor = AgentExecutor.of({
143
305
  capabilities: Effect.gen(function* () {
144
- const agentsMd = yield* Effect.option(fs.readFileString(pathService.join(options.directory, "AGENTS.md")));
145
- const skills = yield* AgentSkills.discover({
146
- directory: options.directory,
147
- homeDirectory: homeDirectory(),
148
- hermesHome: Option.fromNullishOr(process.env.HERMES_HOME),
149
- }).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, pathService));
306
+ const startup = yield* discoverAt(startupDirectory);
307
+ const skills = offersSkills
308
+ ? yield* AgentSkills.discover({
309
+ directory: options.directory,
310
+ homeDirectory: home,
311
+ hermesHome: Option.fromNullishOr(process.env.HERMES_HOME),
312
+ }).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, pathService))
313
+ : [];
150
314
  return new Capabilities({
151
315
  toolsDts,
152
- agentsMd,
316
+ instructions: Option.map(Option.fromNullishOr(startup.instructions.at(-1)), AgentEnvironment.renderInstructions),
153
317
  supportsSearch: hasSearch,
318
+ environment: new ExecutionEnvironment({
319
+ cwd: startupDirectory,
320
+ baseline: [
321
+ ...startup.instructions.map((item) => item.id),
322
+ ...skills.map(AgentEnvironment.skillId),
323
+ ],
324
+ seen: [],
325
+ }),
326
+ tools: Object.keys(tools.tools),
154
327
  skills,
155
328
  });
156
329
  }),
157
- execute,
330
+ execute: (opts) => execute(opts),
331
+ renderEnvironment,
158
332
  executeUnsafe: (opts) => Effect.suspend(() => {
159
333
  const tool = tools.tools[opts.tool];
160
334
  if (!tool) {
@@ -164,15 +338,17 @@ export const makeLocal = Effect.fnUntraced(function* (options) {
164
338
  if (!handler) {
165
339
  return Effect.die(new Error(`Unknown tool: ${opts.tool}`));
166
340
  }
167
- const taskServices = handler.context.pipe(Context.add(TaskCompleter, () => Effect.void), Context.add(CurrentDirectory, currentDirectory), Context.add(DirectoryChanger, changeDirectory), Context.add(SubagentExecutor, () => Effect.succeed("")),
341
+ const cwd = (opts.environment ?? startupEnvironment).cwd;
342
+ const taskServices = handler.context.pipe(Context.add(TaskCompleter, () => Effect.void), Context.add(CurrentDirectory, cwd), Context.add(DirectoryChanger, (directory) => resolveDirectory(cwd, directory)), Context.add(SubagentExecutor, subagentsUnavailable),
168
343
  // Direct tool calls have no model turn to attach images to.
169
- Context.add(ImageAttacher, () => Effect.void), Context.add(References.CurrentLogAnnotations, {}), Option.isSome(search)
344
+ Context.add(ImageAttacher, () => Effect.void), Context.add(CommandLimits, commandLimits), Context.add(References.CurrentLogAnnotations, {}), Option.isSome(search)
170
345
  ? Context.add(SemanticSearch, search.value)
171
346
  : identity);
172
347
  const encodeSuccess = Schema.encodeUnknownEffect(Schema.toCodecJson(tool.successSchema));
173
348
  return pipe(handler.handler(opts.params, {}), Effect.flatMap(encodeSuccess), Effect.provideContext(taskServices), Effect.orDie);
174
349
  }),
175
350
  });
351
+ return { executor, execute, renderEnvironment };
176
352
  });
177
353
  /**
178
354
  * @since 1.0.0
@@ -184,29 +360,51 @@ export const makeRpc = Effect.gen(function* () {
184
360
  });
185
361
  return AgentExecutor.of({
186
362
  capabilities: Effect.orDie(client.capabilities()),
187
- execute: (opts) => Scope.Scope.useSync((scope) => client.execute({ script: opts.script }).pipe(Stream.tap((part) => {
188
- switch (part._tag) {
189
- case "Text": {
190
- return Effect.void;
191
- }
192
- case "TaskComplete": {
193
- return opts.onTaskComplete(part.summary);
194
- }
195
- case "Subagent": {
196
- const id = part.id;
197
- return pipe(opts.onSubagent(part.prompt), Effect.flatMap((output) => client.subagentOutput({ id, output })), Effect.forkIn(scope));
198
- }
199
- case "Image": {
200
- return opts.onImage({
201
- fileName: part.fileName,
202
- mediaType: part.mediaType,
203
- data: part.data,
204
- });
363
+ execute: (opts) => Scope.Scope.useSync((scope) => {
364
+ // Every change is recorded here before the server is told it arrived,
365
+ // so this is current even when the stream is interrupted early.
366
+ let latest = opts.environment;
367
+ return client
368
+ .execute({
369
+ script: opts.script,
370
+ environment: opts.environment,
371
+ loopTools: Object.keys(opts.loopTools ?? {}),
372
+ })
373
+ .pipe(Stream.tap((part) => {
374
+ switch (part._tag) {
375
+ case "Text": {
376
+ return Effect.void;
377
+ }
378
+ case "Request": {
379
+ const id = part.id;
380
+ if (part.request._tag === "EnvironmentChanged") {
381
+ latest = part.request.environment;
382
+ }
383
+ return pipe(handleRequest(opts, part.request), Effect.exit, Effect.flatMap((exit) => client.respond({ id, response: exitToResponse(exit) })), Effect.forkIn(scope));
384
+ }
385
+ case "Image": {
386
+ return opts.onImage({
387
+ fileName: part.fileName,
388
+ mediaType: part.mediaType,
389
+ data: part.data,
390
+ });
391
+ }
392
+ case "Environment": {
393
+ latest = part.environment;
394
+ return Effect.void;
395
+ }
205
396
  }
206
- }
207
- }), Stream.orDie, Stream.filterMap((part) => part._tag === "Text" ? Result.succeed(part.text) : Result.failVoid))).pipe(Stream.unwrap),
208
- executeUnsafe(options) {
209
- return client.executeUnsafe(options).pipe(Effect.orDie);
397
+ }), Stream.orDie, Stream.filterMap((part) => part._tag === "Text"
398
+ ? Result.succeed(part.text)
399
+ : Result.failVoid), Stream.ensuring(Effect.suspend(() => opts.onEnvironment(latest))));
400
+ }).pipe(Stream.unwrap),
401
+ renderEnvironment: (environment, options) => client
402
+ .renderEnvironment({ environment, reset: options?.reset ?? false })
403
+ .pipe(Effect.orDie),
404
+ executeUnsafe({ environment, ...options }) {
405
+ return client
406
+ .executeUnsafe(environment === undefined ? options : { ...options, environment })
407
+ .pipe(Effect.orDie);
210
408
  },
211
409
  });
212
410
  });
@@ -214,7 +412,7 @@ export const makeRpc = Effect.gen(function* () {
214
412
  * @since 1.0.0
215
413
  * @category Layers
216
414
  */
217
- export const layerLocal = (options) => Layer.effect(AgentExecutor, makeLocal(options)).pipe(Layer.provide([AgentToolHandlers, ToolkitRenderer.layer]));
415
+ export const layerLocal = (options) => Layer.effect(AgentExecutor, withBuiltInHandlers(makeLocal(options))).pipe(Layer.provide(ToolkitRenderer.layer));
218
416
  /**
219
417
  * Create an AgentExecutor that communicates with a remote RpcServer serving the
220
418
  * AgentExecutor protocol.
@@ -235,42 +433,58 @@ export const layerRpcServer = (options) => RpcServer.layer(Rpcs, {
235
433
  spanPrefix: "AgentExecutorServer",
236
434
  disableFatalDefects: true,
237
435
  }).pipe(Layer.provide(Rpcs.toLayer(Effect.gen(function* () {
238
- const local = yield* makeLocal(options);
239
- const subagentResumes = new Map();
240
- let subagentId = 0;
436
+ const local = yield* withBuiltInHandlers(makeLocalWith(options));
437
+ const requestResumes = new Map();
438
+ let requestId = 0;
241
439
  return Rpcs.of({
242
- capabilities: () => local.capabilities,
243
- subagentOutput: ({ id, output }) => {
244
- const resume = subagentResumes.get(id);
440
+ capabilities: () => local.executor.capabilities,
441
+ renderEnvironment: ({ environment, reset }) => local.renderEnvironment(environment, { reset }),
442
+ respond: ({ id, response }) => {
443
+ const resume = requestResumes.get(id);
245
444
  if (resume) {
246
- resume(Effect.succeed(output));
247
- subagentResumes.delete(id);
445
+ requestResumes.delete(id);
446
+ resume(response._tag === "Success"
447
+ ? Effect.succeed(response.value)
448
+ : Effect.fail(response.message));
248
449
  }
249
450
  return Effect.void;
250
451
  },
251
- execute: Effect.fnUntraced(function* ({ script }) {
452
+ execute: Effect.fnUntraced(function* ({ script, environment, loopTools, }) {
252
453
  const queue = yield* Queue.unbounded();
454
+ // Sends a request to the client and waits for its response.
455
+ // IDs come from a server-wide counter, so concurrent and nested
456
+ // execute streams never collide.
457
+ // The client answers with the value of the matching callback.
458
+ const request = (request) => Effect.callback((resume) => {
459
+ const id = requestId++;
460
+ requestResumes.set(id, resume);
461
+ Queue.offerUnsafe(queue, { _tag: "Request", id, request });
462
+ return Effect.sync(() => {
463
+ requestResumes.delete(id);
464
+ });
465
+ });
253
466
  yield* pipe(local.execute({
254
467
  script,
255
- onTaskComplete(summary) {
256
- return Queue.offer(queue, {
257
- _tag: "TaskComplete",
258
- summary,
259
- });
260
- },
261
- onSubagent(prompt) {
262
- const id = subagentId++;
263
- return Effect.callback((resume) => {
264
- subagentResumes.set(id, resume);
265
- Queue.offerUnsafe(queue, {
266
- _tag: "Subagent",
267
- id,
268
- prompt,
269
- });
270
- return Effect.sync(() => {
271
- subagentResumes.delete(id);
272
- });
273
- });
468
+ environment,
469
+ onEnvironment: (environment) => Queue.offer(queue, { _tag: "Environment", environment }),
470
+ onTaskComplete: (summary) => request({ _tag: "TaskComplete", summary }),
471
+ subagents: {
472
+ delegate: (options) => Effect.orDie(request({
473
+ _tag: "Delegate",
474
+ ...options,
475
+ })),
476
+ waitAgents: (ids) => request({
477
+ _tag: "WaitAgents",
478
+ ids,
479
+ }),
480
+ messageAgent: (options) => request({
481
+ _tag: "MessageAgent",
482
+ ...options,
483
+ }),
484
+ stopAgent: (id) => request({ _tag: "StopAgent", id }),
485
+ listAgents: Effect.orDie(request({
486
+ _tag: "ListAgents",
487
+ })),
274
488
  },
275
489
  onImage(image) {
276
490
  return Queue.offer(queue, {
@@ -280,7 +494,21 @@ export const layerRpcServer = (options) => RpcServer.layer(Rpcs, {
280
494
  data: image.data,
281
495
  });
282
496
  },
283
- }), Stream.runForEachArray((parts) => {
497
+ loopTools: Object.fromEntries(loopTools.map((name) => [
498
+ name,
499
+ (params) => toJson(name, params).pipe(Effect.flatMap((params) => request({
500
+ _tag: "LoopTool",
501
+ name,
502
+ params,
503
+ }))),
504
+ ])),
505
+ },
506
+ // Waits for the client to record the change, so a script
507
+ // that got past `changeDirectory` never leaves it behind.
508
+ (environment) => Effect.orDie(request({
509
+ _tag: "EnvironmentChanged",
510
+ environment,
511
+ }))), Stream.runForEachArray((parts) => {
284
512
  for (const part of parts) {
285
513
  Queue.offerUnsafe(queue, {
286
514
  _tag: "Text",
@@ -294,23 +522,60 @@ export const layerRpcServer = (options) => RpcServer.layer(Rpcs, {
294
522
  return queue;
295
523
  }),
296
524
  executeUnsafe(opts) {
297
- return local.executeUnsafe(opts);
525
+ return local.executor.executeUnsafe(opts);
298
526
  },
299
527
  });
300
- }))), Layer.provide([AgentToolHandlers, ToolkitRenderer.layer]));
528
+ }))), Layer.provide(ToolkitRenderer.layer));
529
+ /**
530
+ * @since 1.0.0
531
+ * @category Rpcs
532
+ */
533
+ export const AgentRequest = Schema.TaggedUnion({
534
+ TaskComplete: { summary: Schema.String },
535
+ Delegate: {
536
+ prompt: Schema.String,
537
+ background: Schema.Boolean,
538
+ environment: EnvironmentUpdate,
539
+ },
540
+ WaitAgents: { ids: Schema.UndefinedOr(Schema.Array(Schema.String)) },
541
+ MessageAgent: { id: Schema.String, message: Schema.String },
542
+ StopAgent: { id: Schema.String },
543
+ ListAgents: {},
544
+ LoopTool: { name: Schema.String, params: Schema.optional(Schema.Json) },
545
+ /**
546
+ * The script changed its environment. The client records it before it
547
+ * responds.
548
+ */
549
+ EnvironmentChanged: { environment: ExecutionEnvironment },
550
+ });
551
+ /**
552
+ * The client's answer to a `Request`. `Failure` carries a message for the
553
+ * script; a failed foreground `delegate` is raised there as a defect.
554
+ *
555
+ * @since 1.0.0
556
+ * @category Rpcs
557
+ */
558
+ export const AgentResponse = Schema.TaggedUnion({
559
+ Success: { value: Schema.Json },
560
+ Failure: { message: Schema.String },
561
+ });
301
562
  /**
302
563
  * @since 1.0.0
303
564
  * @category Rpcs
304
565
  */
305
566
  export const ExecuteOutput = Schema.TaggedUnion({
306
567
  Text: { text: Schema.String },
307
- TaskComplete: { summary: Schema.String },
308
- Subagent: { id: Schema.Finite, prompt: Schema.String },
568
+ Request: { id: Schema.Finite, request: AgentRequest },
309
569
  Image: {
310
570
  fileName: Schema.String,
311
571
  mediaType: Image.ImageMediaType,
312
572
  data: Schema.Uint8Array,
313
573
  },
574
+ /**
575
+ * Sent once, when the script ends. Changes before then are sent as
576
+ * `EnvironmentChanged` requests.
577
+ */
578
+ Environment: { environment: ExecutionEnvironment },
314
579
  });
315
580
  /**
316
581
  * @since 1.0.0
@@ -318,31 +583,113 @@ export const ExecuteOutput = Schema.TaggedUnion({
318
583
  */
319
584
  export class Rpcs extends RpcGroup.make(Rpc.make("capabilities", {
320
585
  success: Capabilities,
321
- }), Rpc.make("subagentOutput", {
586
+ }), Rpc.make("respond", {
322
587
  payload: {
323
588
  id: Schema.Finite,
324
- output: Schema.String,
589
+ response: AgentResponse,
325
590
  },
326
591
  }), Rpc.make("execute", {
327
592
  payload: Schema.Struct({
328
593
  script: Schema.String,
594
+ environment: ExecutionEnvironment,
595
+ /**
596
+ * The loop-side tools to add to the script sandbox.
597
+ */
598
+ loopTools: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
329
599
  }),
330
600
  success: ExecuteOutput,
331
601
  stream: true,
602
+ }), Rpc.make("renderEnvironment", {
603
+ payload: { environment: ExecutionEnvironment, reset: Schema.Boolean },
604
+ success: EnvironmentUpdate,
332
605
  }), Rpc.make("executeUnsafe", {
333
606
  payload: Schema.Struct({
334
607
  tool: Schema.String,
335
608
  params: Schema.Json,
609
+ environment: Schema.optionalKey(ExecutionEnvironment),
336
610
  }),
337
611
  success: Schema.Json,
338
612
  })) {
339
613
  }
614
+ // ------------------------------------------
615
+ // Internal
616
+ // -------------------------------------------
617
+ const handleRequest = (opts, request) => {
618
+ switch (request._tag) {
619
+ case "TaskComplete":
620
+ return opts.onTaskComplete(request.summary);
621
+ case "Delegate":
622
+ return opts.subagents.delegate(request);
623
+ case "WaitAgents":
624
+ return opts.subagents.waitAgents(request.ids);
625
+ case "MessageAgent":
626
+ return opts.subagents.messageAgent(request);
627
+ case "StopAgent":
628
+ return opts.subagents.stopAgent(request.id);
629
+ case "ListAgents":
630
+ return opts.subagents.listAgents;
631
+ case "EnvironmentChanged":
632
+ // Recorded by the client before it responds.
633
+ return Effect.void;
634
+ case "LoopTool": {
635
+ const handler = opts.loopTools?.[request.name];
636
+ return handler
637
+ ? handler(request.params)
638
+ : Effect.fail(`Unknown loop-side tool: ${request.name}`);
639
+ }
640
+ }
641
+ };
642
+ // Script arguments cross the RPC boundary as JSON.
643
+ const toJson = (name, params) => Effect.try({
644
+ try: () => {
645
+ const json = JSON.stringify(params);
646
+ return json === undefined ? undefined : JSON.parse(json);
647
+ },
648
+ catch: (error) => `Invalid arguments for ${name}: ${errorMessage(error)}`,
649
+ });
650
+ // The built-in handlers sit underneath the caller's context, so a caller tool
651
+ // named like a built-in keeps its own handler.
652
+ const withBuiltInHandlers = (effect) => Effect.flatMap(Layer.build(AgentToolHandlers), (builtIns) => Effect.updateContext(effect, (context) => Context.merge(builtIns, context)));
653
+ const exitToResponse = (exit) => {
654
+ if (Exit.isSuccess(exit)) {
655
+ return { _tag: "Success", value: (exit.value ?? null) };
656
+ }
657
+ return { _tag: "Failure", message: errorMessage(Cause.squash(exit.cause)) };
658
+ };
659
+ const errorMessage = (error) => typeof error === "string"
660
+ ? error
661
+ : error instanceof Error
662
+ ? error.message
663
+ : String(error);
664
+ // Leaving out `delegate` leaves out the tools that address its sub-agents.
665
+ const excludedToolNames = (excludeTools) => {
666
+ const names = new Set(excludeTools);
667
+ if (names.has("delegate")) {
668
+ for (const name of [
669
+ "waitAgents",
670
+ "messageAgent",
671
+ "stopAgent",
672
+ "listAgents",
673
+ ]) {
674
+ names.add(name);
675
+ }
676
+ }
677
+ return names;
678
+ };
340
679
  const wrapScript = (script) => `async function main() {
341
680
  ${script}
342
681
  }`;
343
- const compileScript = (script) => {
682
+ /**
683
+ * Returns source that compiles, preprocessing the script if it has syntax
684
+ * errors. Throws the original syntax error if neither version compiles.
685
+ */
686
+ const prepareScript = (script) => {
687
+ const source = wrapScript(script);
344
688
  try {
345
- return new NodeVm.Script(wrapScript(script));
689
+ // Compiled only to check the syntax. The worker compiles it again.
690
+ // oxlint-disable-next-line eslint/no-new
691
+ new NodeVm.Script(source);
692
+ return source;
346
693
  }
347
694
  catch (error) {
348
695
  if (!(error instanceof SyntaxError)) {
@@ -352,15 +699,148 @@ const compileScript = (script) => {
352
699
  if (preprocessed === script) {
353
700
  throw error;
354
701
  }
702
+ const preprocessedSource = wrapScript(preprocessed);
355
703
  try {
356
- return new NodeVm.Script(wrapScript(preprocessed));
704
+ // oxlint-disable-next-line eslint/no-new
705
+ new NodeVm.Script(preprocessedSource);
706
+ return preprocessedSource;
357
707
  }
358
708
  catch {
359
709
  throw error;
360
710
  }
361
711
  }
362
712
  };
363
- const defaultMain = () => Promise.resolve();
713
+ // -------------------------------------------
714
+ // Script worker
715
+ //
716
+ // The worker runs from source text (`new Worker(source, { eval: true })`), so
717
+ // it needs no separate file in the package, the CLI bundle or a consumer's
718
+ // bundle. The source is built from the function declarations below with
719
+ // `Function.prototype.toString`, which keeps them type-checked and shared
720
+ // with the parent instead of copied into a string.
721
+ //
722
+ // Constraints, because the text of each function must run on its own:
723
+ // - Each must be a `function` declaration, so its text carries its name.
724
+ // - They may reference only each other, their parameters and globals: no
725
+ // imports, module-level values or closures.
726
+ // - Node modules are loaded with the `load` parameter, which the source text
727
+ // binds to the worker's `require`. Bundlers rewrite a bare `require` (the
728
+ // CLI bundle turns it into `__require`), but leave a parameter alone.
729
+ // - A bundler must keep their bodies whole. Renaming identifiers
730
+ // consistently is fine. Transforms that move code out of a body, such as
731
+ // coverage instrumentation or helper hoisting, are not. Only the
732
+ // library build and the CLI bundle are checked.
733
+ // The executor tests run every script through this worker, so they catch a
734
+ // broken constraint in the source. They run the source, not a bundle, so a
735
+ // bundler's rewrites only show up when the built output is run.
736
+ // -------------------------------------------
737
+ function toFailure(value) {
738
+ if (Object.prototype.toString.call(value) === "[object Error]") {
739
+ const error = value;
740
+ return {
741
+ _tag: "Error",
742
+ name: error.name,
743
+ message: error.message,
744
+ stack: error.stack,
745
+ };
746
+ }
747
+ try {
748
+ return { _tag: "Value", value: structuredClone(value) };
749
+ }
750
+ catch {
751
+ return { _tag: "Value", value: String(value) };
752
+ }
753
+ }
754
+ function fromFailure(failure) {
755
+ if (failure._tag === "Value")
756
+ return failure.value;
757
+ const error = new Error(failure.message);
758
+ error.name = failure.name;
759
+ if (failure.stack !== undefined)
760
+ error.stack = failure.stack;
761
+ return error;
762
+ }
763
+ /**
764
+ * Runs one script inside a vm context with the same globals as before, and
765
+ * forwards console output and tool calls to the parent.
766
+ */
767
+ function runScriptWorker(load) {
768
+ // Type-only references: the casts are erased, so the text stays
769
+ // self-contained.
770
+ const { parentPort, workerData } = load("node:worker_threads");
771
+ const vm = load("node:vm");
772
+ const { Console } = load("node:console");
773
+ const { Writable: WorkerWritable } = load("node:stream");
774
+ const port = parentPort;
775
+ const data = workerData;
776
+ // Like the parent process: a stray rejection must not end the script.
777
+ process.on("uncaughtException", () => { });
778
+ process.on("unhandledRejection", () => { });
779
+ const post = (message) => port.postMessage(message);
780
+ const pending = new Map();
781
+ let nextId = 0;
782
+ let mainSettled = false;
783
+ let done = false;
784
+ // Done once main() has settled and no tool call is outstanding. The check
785
+ // runs after the microtasks a result triggers, so a continuation that
786
+ // calls another tool is waited for too. Done is sent once.
787
+ const maybeDone = () => {
788
+ if (done || !mainSettled || pending.size > 0)
789
+ return;
790
+ setImmediate(() => {
791
+ if (done || pending.size > 0)
792
+ return;
793
+ done = true;
794
+ post({ _tag: "Done" });
795
+ });
796
+ };
797
+ port.on("message", (message) => {
798
+ const call = pending.get(message.id);
799
+ if (call === undefined)
800
+ return;
801
+ pending.delete(message.id);
802
+ if (message.ok)
803
+ call.resolve(message.value);
804
+ else
805
+ call.reject(fromFailure(message.failure));
806
+ maybeDone();
807
+ });
808
+ const stdout = new WorkerWritable({
809
+ write(chunk, _encoding, callback) {
810
+ post({ _tag: "Output", text: String(chunk) });
811
+ callback();
812
+ },
813
+ });
814
+ const sandbox = {
815
+ console: new Console({ stdout, colorMode: false }),
816
+ fetch,
817
+ process: undefined,
818
+ };
819
+ for (const name of data.tools) {
820
+ sandbox[name] = (params) => new Promise((resolve, reject) => {
821
+ const id = nextId++;
822
+ pending.set(id, { resolve, reject });
823
+ try {
824
+ post({ _tag: "Call", id, name, params });
825
+ }
826
+ catch (error) {
827
+ // The params cannot be copied to the parent.
828
+ pending.delete(id);
829
+ reject(error);
830
+ maybeDone();
831
+ }
832
+ });
833
+ }
834
+ new vm.Script(data.source).runInNewContext(sandbox);
835
+ sandbox.main().then(() => {
836
+ mainSettled = true;
837
+ maybeDone();
838
+ }, (error) => post({ _tag: "Failed", failure: toFailure(error) }));
839
+ }
840
+ const workerSource = `${toFailure}
841
+ ${fromFailure}
842
+ (${runScriptWorker})(require)
843
+ `;
364
844
  const homeDirectory = () => {
365
845
  const fromEnv = process.env.HOME;
366
846
  if (fromEnv)