clanka 0.8.5 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/dist/Acp.d.ts.map +1 -1
  2. package/dist/Acp.js +9 -3
  3. package/dist/Acp.js.map +1 -1
  4. package/dist/Acp.test.js +72 -1
  5. package/dist/Acp.test.js.map +1 -1
  6. package/dist/AcpImage.test.js +1 -0
  7. package/dist/AcpImage.test.js.map +1 -1
  8. package/dist/Agent.d.ts +65 -8
  9. package/dist/Agent.d.ts.map +1 -1
  10. package/dist/Agent.js +481 -113
  11. package/dist/Agent.js.map +1 -1
  12. package/dist/Agent.test.js +77 -4
  13. package/dist/Agent.test.js.map +1 -1
  14. package/dist/AgentCallerConfig.test.d.ts +2 -0
  15. package/dist/AgentCallerConfig.test.d.ts.map +1 -0
  16. package/dist/AgentCallerConfig.test.js +327 -0
  17. package/dist/AgentCallerConfig.test.js.map +1 -0
  18. package/dist/AgentExecutor.d.ts +254 -54
  19. package/dist/AgentExecutor.d.ts.map +1 -1
  20. package/dist/AgentExecutor.js +416 -99
  21. package/dist/AgentExecutor.js.map +1 -1
  22. package/dist/AgentExecutor.test.js +201 -31
  23. package/dist/AgentExecutor.test.js.map +1 -1
  24. package/dist/AgentExecutorImage.test.js +2 -1
  25. package/dist/AgentExecutorImage.test.js.map +1 -1
  26. package/dist/AgentImage.test.js +5 -1
  27. package/dist/AgentImage.test.js.map +1 -1
  28. package/dist/AgentOutput.d.ts +54 -2
  29. package/dist/AgentOutput.d.ts.map +1 -1
  30. package/dist/AgentOutput.js +52 -0
  31. package/dist/AgentOutput.js.map +1 -1
  32. package/dist/AgentSkills.d.ts +22 -0
  33. package/dist/AgentSkills.d.ts.map +1 -1
  34. package/dist/AgentSkills.js +36 -0
  35. package/dist/AgentSkills.js.map +1 -1
  36. package/dist/AgentSkills.test.js +2 -0
  37. package/dist/AgentSkills.test.js.map +1 -1
  38. package/dist/AgentSubagents.test.d.ts +2 -0
  39. package/dist/AgentSubagents.test.d.ts.map +1 -0
  40. package/dist/AgentSubagents.test.js +452 -0
  41. package/dist/AgentSubagents.test.js.map +1 -0
  42. package/dist/AgentTools.d.ts +356 -14
  43. package/dist/AgentTools.d.ts.map +1 -1
  44. package/dist/AgentTools.js +213 -34
  45. package/dist/AgentTools.js.map +1 -1
  46. package/dist/CompactionTransport.test.js +1 -1
  47. package/dist/CompactionTransport.test.js.map +1 -1
  48. package/dist/OutputFormatter.d.ts.map +1 -1
  49. package/dist/OutputFormatter.js +16 -2
  50. package/dist/OutputFormatter.js.map +1 -1
  51. package/dist/ToolkitRenderer.d.ts.map +1 -1
  52. package/dist/ToolkitRenderer.js +6 -1
  53. package/dist/ToolkitRenderer.js.map +1 -1
  54. package/dist/bin/{Effect-BEUn4I5E.mjs → Effect-2jPlJ8eu.mjs} +399 -207
  55. package/dist/bin/Effect-2jPlJ8eu.mjs.map +1 -0
  56. package/dist/bin/{McpClient-C0FVuDj2.mjs → McpClient-1W508adc.mjs} +4 -4
  57. package/dist/bin/{McpClient-C0FVuDj2.mjs.map → McpClient-1W508adc.mjs.map} +1 -1
  58. package/dist/bin/{OutputFormatter-DffD5oxX.mjs → OutputFormatter-DXXKo4E8.mjs} +16 -5
  59. package/dist/bin/{OutputFormatter-DffD5oxX.mjs.map → OutputFormatter-DXXKo4E8.mjs.map} +1 -1
  60. package/dist/bin/{Schema-CjUGw2Xh.mjs → Schema-D-7VuCiC.mjs} +640 -87
  61. package/dist/bin/Schema-D-7VuCiC.mjs.map +1 -0
  62. package/dist/bin/{SemanticSearch-CFB73IPb.mjs → SemanticSearch-Cb8aqvGv.mjs} +89 -56
  63. package/dist/bin/SemanticSearch-Cb8aqvGv.mjs.map +1 -0
  64. package/dist/bin/{Stream-Cu6P7ZHo.mjs → Stream-DEu2tfCV.mjs} +81 -51
  65. package/dist/bin/Stream-DEu2tfCV.mjs.map +1 -0
  66. package/dist/bin/cli.mjs +3632 -5538
  67. package/dist/bin/cli.mjs.map +1 -1
  68. package/dist/bin/{turndown.cjs-usmCKZ4b.mjs → turndown.cjs-DK29wZw3.mjs} +2 -2
  69. package/dist/bin/{turndown.cjs-usmCKZ4b.mjs.map → turndown.cjs-DK29wZw3.mjs.map} +1 -1
  70. package/package.json +7 -7
  71. package/src/Acp.test.ts +121 -2
  72. package/src/Acp.ts +10 -3
  73. package/src/AcpImage.test.ts +1 -0
  74. package/src/Agent.test.ts +100 -3
  75. package/src/Agent.ts +752 -142
  76. package/src/AgentCallerConfig.test.ts +514 -0
  77. package/src/AgentExecutor.test.ts +297 -37
  78. package/src/AgentExecutor.ts +707 -159
  79. package/src/AgentExecutorImage.test.ts +2 -1
  80. package/src/AgentImage.test.ts +11 -2
  81. package/src/AgentOutput.ts +74 -1
  82. package/src/AgentSkills.test.ts +2 -0
  83. package/src/AgentSkills.ts +43 -0
  84. package/src/AgentSubagents.test.ts +758 -0
  85. package/src/AgentTools.ts +376 -52
  86. package/src/CompactionTransport.test.ts +1 -1
  87. package/src/OutputFormatter.ts +16 -2
  88. package/src/ToolkitRenderer.ts +7 -1
  89. package/dist/bin/Effect-BEUn4I5E.mjs.map +0 -1
  90. package/dist/bin/Schema-CjUGw2Xh.mjs.map +0 -1
  91. package/dist/bin/SemanticSearch-CFB73IPb.mjs.map +0 -1
  92. package/dist/bin/Stream-Cu6P7ZHo.mjs.map +0 -1
@@ -5,11 +5,14 @@ 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";
11
12
  import * as AgentSkills from "./AgentSkills.js";
12
13
  import * as Context from "effect/Context";
14
+ import * as Deferred from "effect/Deferred";
15
+ import * as Duration from "effect/Duration";
13
16
  import * as Effect from "effect/Effect";
14
17
  import * as Option from "effect/Option";
15
18
  import * as Stream from "effect/Stream";
@@ -47,6 +50,10 @@ export class Capabilities extends Schema.Class("Capabilities")({
47
50
  toolsDts: Schema.String,
48
51
  agentsMd: Schema.Option(Schema.String),
49
52
  supportsSearch: Schema.Boolean,
53
+ /**
54
+ * The names of the script functions the executor offers.
55
+ */
56
+ tools: Schema.Array(Schema.String),
50
57
  /**
51
58
  * Skills available on the executor filesystem.
52
59
  */
@@ -71,20 +78,36 @@ export const makeLocal = Effect.fnUntraced(function* (options) {
71
78
  currentDirectory = target;
72
79
  return target;
73
80
  }, Effect.orDie);
81
+ const commandTimeout = options.limits?.commandTimeout;
82
+ const commandLimits = {
83
+ timeout: commandTimeout === undefined
84
+ ? undefined
85
+ : Duration.fromInputUnsafe(commandTimeout),
86
+ outputChars: options.limits?.commandOutputChars,
87
+ };
88
+ const scriptTimeout = Option.map(Option.fromUndefinedOr(options.limits?.scriptTimeout), Duration.fromInputUnsafe);
89
+ const excluded = excludedToolNames(options.excludeTools);
74
90
  const search = yield* Effect.serviceOption(SemanticSearch);
75
- const hasSearch = Option.isSome(search);
76
- const AllTools = Toolkit.merge(hasSearch ? AgentToolsWithSearch : AgentTools, options.tools ?? Toolkit.empty);
91
+ const BuiltInTools = Toolkit.make(...Object.values(Toolkit.merge(Option.isSome(search) ? AgentToolsWithSearch : AgentTools,
92
+ // Same tool id, so the handler is unchanged. Only the description,
93
+ // which states the timeout, differs.
94
+ Toolkit.make(makeBashTool(commandLimits.timeout ?? defaultBashTimeout))).tools).filter((tool) => !excluded.has(tool.name)));
95
+ const hasSearch = "search" in BuiltInTools.tools;
96
+ const AllTools = Toolkit.merge(BuiltInTools, options.tools ?? Toolkit.empty);
77
97
  const tools = yield* AllTools;
78
98
  const toolsDts = renderer.render(AllTools);
79
99
  const services = yield* Effect.context();
80
- const toolEntries = Object.entries(tools.tools).map(([name, tool]) => {
100
+ const toolEntries = new Map(Object.entries(tools.tools).map(([name, tool]) => {
81
101
  const handler = services.mapUnsafe.get(tool.id);
82
- return {
102
+ return [
83
103
  name,
84
- services: Context.merge(services, handler.context),
85
- handler: handler.handler,
86
- };
87
- });
104
+ {
105
+ services: Context.merge(services, handler.context),
106
+ handler: handler.handler,
107
+ },
108
+ ];
109
+ }));
110
+ const toolNames = Array.from(toolEntries.keys());
88
111
  if (typeof process !== "undefined") {
89
112
  process.on("uncaughtException", () => { });
90
113
  }
@@ -93,64 +116,103 @@ export const makeLocal = Effect.fnUntraced(function* (options) {
93
116
  const console = yield* makeConsole(output);
94
117
  const handlerScope = Scope.makeUnsafe("parallel");
95
118
  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)
119
+ const taskServices = Context.empty().pipe(Context.add(TaskCompleter, opts.onTaskComplete), Context.add(DirectoryChanger, changeDirectory), Context.add(SubagentExecutor, opts.subagents), Context.add(ImageAttacher, opts.onImage), Context.add(CommandLimits, commandLimits), Context.add(Console.Console, console), Context.add(References.CurrentLogAnnotations, {}), Option.isSome(search)
97
120
  ? Context.add(SemanticSearch, search.value)
98
121
  : identity);
122
+ // The script runs in its own worker thread, so a script that is busy in
123
+ // JavaScript can still be stopped. Tool calls are sent back here and run
124
+ // as before.
99
125
  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,
126
+ const source = prepareScript(opts.script);
127
+ const settled = yield* Deferred.make();
128
+ const worker = yield* Effect.acquireRelease(Effect.sync(() => new Worker(workerSource, {
129
+ eval: true,
130
+ workerData: {
131
+ source,
132
+ tools: [...toolNames, ...Object.keys(opts.loopTools ?? {})],
133
+ },
134
+ })), (worker) => Effect.promise(() => worker.terminate()));
135
+ // Every call is answered, interrupted ones included: the worker only
136
+ // reports Done once nothing is outstanding. While the script is being
137
+ // stopped the worker is already gone and the answer is dropped.
138
+ const respond = (id, exit) => {
139
+ const message = Exit.isSuccess(exit)
140
+ ? { id, ok: true, value: exit.value }
141
+ : { id, ok: false, failure: toFailure(Cause.squash(exit.cause)) };
142
+ try {
143
+ // oxlint-disable-next-line unicorn/require-post-message-target-origin
144
+ worker.postMessage(message);
145
+ }
146
+ catch (error) {
147
+ // The value cannot be copied to the worker.
148
+ // oxlint-disable-next-line unicorn/require-post-message-target-origin
149
+ worker.postMessage({ id, ok: false, failure: toFailure(error) });
150
+ }
108
151
  };
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,
152
+ const call = (message) => {
153
+ const entry = toolEntries.get(message.name);
154
+ const runFork = Effect.runForkWith(Context.add(entry ? Context.merge(entry.services, taskServices) : taskServices, CurrentDirectory, currentDirectory));
155
+ const fiber = trackFiber(runFork(entry
156
+ ? entry.handler(message.params, {})
157
+ : // A loop-side tool: its failure is the script's error message.
158
+ opts.loopTools[message.name](message.params).pipe(Effect.catch((message) => Effect.die(new Error(message))))));
159
+ fiber.addObserver((exit) => respond(message.id, exit));
160
+ };
161
+ worker.on("message", (message) => {
162
+ switch (message._tag) {
163
+ case "Output":
164
+ Queue.offerUnsafe(output, message.text);
165
+ break;
166
+ case "Call":
167
+ call(message);
168
+ break;
169
+ case "Done":
170
+ Deferred.doneUnsafe(settled, Effect.void);
171
+ break;
172
+ case "Failed":
173
+ Deferred.doneUnsafe(settled, Effect.die(fromFailure(message.failure)));
174
+ break;
175
+ }
132
176
  });
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);
177
+ // Bridge failures end the script instead of leaving it pending.
178
+ worker.on("error", (error) => {
179
+ Deferred.doneUnsafe(settled, Effect.die(error));
180
+ });
181
+ worker.on("messageerror", (error) => {
182
+ Deferred.doneUnsafe(settled, Effect.die(error));
183
+ });
184
+ worker.on("exit", (code) => {
185
+ Deferred.doneUnsafe(settled, Effect.die(new Error(`The script worker exited with code ${code} early`)));
186
+ });
187
+ yield* Deferred.await(settled);
188
+ }).pipe(
189
+ // Stops the worker on every exit: done, failed, timed out, interrupted.
190
+ Effect.scoped, Option.isSome(scriptTimeout)
191
+ ? Effect.timeoutOrElse({
192
+ duration: scriptTimeout.value,
193
+ 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`),
194
+ })
195
+ : identity,
196
+ // Interrupts the tool calls still running, and the processes they own.
197
+ Effect.ensuring(Scope.close(handlerScope, Exit.void)), Effect.catchCause(Effect.logFatal), Effect.provideService(Console.Console, console), Effect.ensuring(Queue.end(output)), Effect.forkScoped);
140
198
  return Stream.fromQueue(output);
141
199
  }, Stream.unwrap);
142
200
  return AgentExecutor.of({
143
201
  capabilities: Effect.gen(function* () {
144
202
  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));
203
+ // Skills are read with readFile, so there are none without it.
204
+ const skills = "readFile" in tools.tools
205
+ ? yield* AgentSkills.discover({
206
+ directory: options.directory,
207
+ homeDirectory: homeDirectory(),
208
+ hermesHome: Option.fromNullishOr(process.env.HERMES_HOME),
209
+ }).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, pathService))
210
+ : [];
150
211
  return new Capabilities({
151
212
  toolsDts,
152
213
  agentsMd,
153
214
  supportsSearch: hasSearch,
215
+ tools: Object.keys(tools.tools),
154
216
  skills,
155
217
  });
156
218
  }),
@@ -164,9 +226,9 @@ export const makeLocal = Effect.fnUntraced(function* (options) {
164
226
  if (!handler) {
165
227
  return Effect.die(new Error(`Unknown tool: ${opts.tool}`));
166
228
  }
167
- const taskServices = handler.context.pipe(Context.add(TaskCompleter, () => Effect.void), Context.add(CurrentDirectory, currentDirectory), Context.add(DirectoryChanger, changeDirectory), Context.add(SubagentExecutor, () => Effect.succeed("")),
229
+ const taskServices = handler.context.pipe(Context.add(TaskCompleter, () => Effect.void), Context.add(CurrentDirectory, currentDirectory), Context.add(DirectoryChanger, changeDirectory), Context.add(SubagentExecutor, subagentsUnavailable),
168
230
  // Direct tool calls have no model turn to attach images to.
169
- Context.add(ImageAttacher, () => Effect.void), Context.add(References.CurrentLogAnnotations, {}), Option.isSome(search)
231
+ Context.add(ImageAttacher, () => Effect.void), Context.add(CommandLimits, commandLimits), Context.add(References.CurrentLogAnnotations, {}), Option.isSome(search)
170
232
  ? Context.add(SemanticSearch, search.value)
171
233
  : identity);
172
234
  const encodeSuccess = Schema.encodeUnknownEffect(Schema.toCodecJson(tool.successSchema));
@@ -184,17 +246,19 @@ export const makeRpc = Effect.gen(function* () {
184
246
  });
185
247
  return AgentExecutor.of({
186
248
  capabilities: Effect.orDie(client.capabilities()),
187
- execute: (opts) => Scope.Scope.useSync((scope) => client.execute({ script: opts.script }).pipe(Stream.tap((part) => {
249
+ execute: (opts) => Scope.Scope.useSync((scope) => client
250
+ .execute({
251
+ script: opts.script,
252
+ loopTools: Object.keys(opts.loopTools ?? {}),
253
+ })
254
+ .pipe(Stream.tap((part) => {
188
255
  switch (part._tag) {
189
256
  case "Text": {
190
257
  return Effect.void;
191
258
  }
192
- case "TaskComplete": {
193
- return opts.onTaskComplete(part.summary);
194
- }
195
- case "Subagent": {
259
+ case "Request": {
196
260
  const id = part.id;
197
- return pipe(opts.onSubagent(part.prompt), Effect.flatMap((output) => client.subagentOutput({ id, output })), Effect.forkIn(scope));
261
+ return pipe(handleRequest(opts, part.request), Effect.exit, Effect.flatMap((exit) => client.respond({ id, response: exitToResponse(exit) })), Effect.forkIn(scope));
198
262
  }
199
263
  case "Image": {
200
264
  return opts.onImage({
@@ -204,7 +268,9 @@ export const makeRpc = Effect.gen(function* () {
204
268
  });
205
269
  }
206
270
  }
207
- }), Stream.orDie, Stream.filterMap((part) => part._tag === "Text" ? Result.succeed(part.text) : Result.failVoid))).pipe(Stream.unwrap),
271
+ }), Stream.orDie, Stream.filterMap((part) => part._tag === "Text"
272
+ ? Result.succeed(part.text)
273
+ : Result.failVoid))).pipe(Stream.unwrap),
208
274
  executeUnsafe(options) {
209
275
  return client.executeUnsafe(options).pipe(Effect.orDie);
210
276
  },
@@ -214,7 +280,7 @@ export const makeRpc = Effect.gen(function* () {
214
280
  * @since 1.0.0
215
281
  * @category Layers
216
282
  */
217
- export const layerLocal = (options) => Layer.effect(AgentExecutor, makeLocal(options)).pipe(Layer.provide([AgentToolHandlers, ToolkitRenderer.layer]));
283
+ export const layerLocal = (options) => Layer.effect(AgentExecutor, withBuiltInHandlers(makeLocal(options))).pipe(Layer.provide(ToolkitRenderer.layer));
218
284
  /**
219
285
  * Create an AgentExecutor that communicates with a remote RpcServer serving the
220
286
  * AgentExecutor protocol.
@@ -235,42 +301,55 @@ export const layerRpcServer = (options) => RpcServer.layer(Rpcs, {
235
301
  spanPrefix: "AgentExecutorServer",
236
302
  disableFatalDefects: true,
237
303
  }).pipe(Layer.provide(Rpcs.toLayer(Effect.gen(function* () {
238
- const local = yield* makeLocal(options);
239
- const subagentResumes = new Map();
240
- let subagentId = 0;
304
+ const local = yield* withBuiltInHandlers(makeLocal(options));
305
+ const requestResumes = new Map();
306
+ let requestId = 0;
241
307
  return Rpcs.of({
242
308
  capabilities: () => local.capabilities,
243
- subagentOutput: ({ id, output }) => {
244
- const resume = subagentResumes.get(id);
309
+ respond: ({ id, response }) => {
310
+ const resume = requestResumes.get(id);
245
311
  if (resume) {
246
- resume(Effect.succeed(output));
247
- subagentResumes.delete(id);
312
+ requestResumes.delete(id);
313
+ resume(response._tag === "Success"
314
+ ? Effect.succeed(response.value)
315
+ : Effect.fail(response.message));
248
316
  }
249
317
  return Effect.void;
250
318
  },
251
- execute: Effect.fnUntraced(function* ({ script }) {
319
+ execute: Effect.fnUntraced(function* ({ script, loopTools }) {
252
320
  const queue = yield* Queue.unbounded();
321
+ // Sends a request to the client and waits for its response.
322
+ // IDs come from a server-wide counter, so concurrent and nested
323
+ // execute streams never collide.
324
+ // The client answers with the value of the matching callback.
325
+ const request = (request) => Effect.callback((resume) => {
326
+ const id = requestId++;
327
+ requestResumes.set(id, resume);
328
+ Queue.offerUnsafe(queue, { _tag: "Request", id, request });
329
+ return Effect.sync(() => {
330
+ requestResumes.delete(id);
331
+ });
332
+ });
253
333
  yield* pipe(local.execute({
254
334
  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
- });
335
+ onTaskComplete: (summary) => request({ _tag: "TaskComplete", summary }),
336
+ subagents: {
337
+ delegate: (options) => Effect.orDie(request({
338
+ _tag: "Delegate",
339
+ ...options,
340
+ })),
341
+ waitAgents: (ids) => request({
342
+ _tag: "WaitAgents",
343
+ ids,
344
+ }),
345
+ messageAgent: (options) => request({
346
+ _tag: "MessageAgent",
347
+ ...options,
348
+ }),
349
+ stopAgent: (id) => request({ _tag: "StopAgent", id }),
350
+ listAgents: Effect.orDie(request({
351
+ _tag: "ListAgents",
352
+ })),
274
353
  },
275
354
  onImage(image) {
276
355
  return Queue.offer(queue, {
@@ -280,6 +359,14 @@ export const layerRpcServer = (options) => RpcServer.layer(Rpcs, {
280
359
  data: image.data,
281
360
  });
282
361
  },
362
+ loopTools: Object.fromEntries(loopTools.map((name) => [
363
+ name,
364
+ (params) => toJson(name, params).pipe(Effect.flatMap((params) => request({
365
+ _tag: "LoopTool",
366
+ name,
367
+ params,
368
+ }))),
369
+ ])),
283
370
  }), Stream.runForEachArray((parts) => {
284
371
  for (const part of parts) {
285
372
  Queue.offerUnsafe(queue, {
@@ -297,15 +384,38 @@ export const layerRpcServer = (options) => RpcServer.layer(Rpcs, {
297
384
  return local.executeUnsafe(opts);
298
385
  },
299
386
  });
300
- }))), Layer.provide([AgentToolHandlers, ToolkitRenderer.layer]));
387
+ }))), Layer.provide(ToolkitRenderer.layer));
388
+ /**
389
+ * @since 1.0.0
390
+ * @category Rpcs
391
+ */
392
+ export const AgentRequest = Schema.TaggedUnion({
393
+ TaskComplete: { summary: Schema.String },
394
+ Delegate: { prompt: Schema.String, background: Schema.Boolean },
395
+ WaitAgents: { ids: Schema.UndefinedOr(Schema.Array(Schema.String)) },
396
+ MessageAgent: { id: Schema.String, message: Schema.String },
397
+ StopAgent: { id: Schema.String },
398
+ ListAgents: {},
399
+ LoopTool: { name: Schema.String, params: Schema.optional(Schema.Json) },
400
+ });
401
+ /**
402
+ * The client's answer to a `Request`. `Failure` carries a message for the
403
+ * script; a failed foreground `delegate` is raised there as a defect.
404
+ *
405
+ * @since 1.0.0
406
+ * @category Rpcs
407
+ */
408
+ export const AgentResponse = Schema.TaggedUnion({
409
+ Success: { value: Schema.Json },
410
+ Failure: { message: Schema.String },
411
+ });
301
412
  /**
302
413
  * @since 1.0.0
303
414
  * @category Rpcs
304
415
  */
305
416
  export const ExecuteOutput = Schema.TaggedUnion({
306
417
  Text: { text: Schema.String },
307
- TaskComplete: { summary: Schema.String },
308
- Subagent: { id: Schema.Finite, prompt: Schema.String },
418
+ Request: { id: Schema.Finite, request: AgentRequest },
309
419
  Image: {
310
420
  fileName: Schema.String,
311
421
  mediaType: Image.ImageMediaType,
@@ -318,14 +428,18 @@ export const ExecuteOutput = Schema.TaggedUnion({
318
428
  */
319
429
  export class Rpcs extends RpcGroup.make(Rpc.make("capabilities", {
320
430
  success: Capabilities,
321
- }), Rpc.make("subagentOutput", {
431
+ }), Rpc.make("respond", {
322
432
  payload: {
323
433
  id: Schema.Finite,
324
- output: Schema.String,
434
+ response: AgentResponse,
325
435
  },
326
436
  }), Rpc.make("execute", {
327
437
  payload: Schema.Struct({
328
438
  script: Schema.String,
439
+ /**
440
+ * The loop-side tools to add to the script sandbox.
441
+ */
442
+ loopTools: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
329
443
  }),
330
444
  success: ExecuteOutput,
331
445
  stream: true,
@@ -337,12 +451,82 @@ export class Rpcs extends RpcGroup.make(Rpc.make("capabilities", {
337
451
  success: Schema.Json,
338
452
  })) {
339
453
  }
454
+ // ------------------------------------------
455
+ // Internal
456
+ // -------------------------------------------
457
+ const handleRequest = (opts, request) => {
458
+ switch (request._tag) {
459
+ case "TaskComplete":
460
+ return opts.onTaskComplete(request.summary);
461
+ case "Delegate":
462
+ return opts.subagents.delegate(request);
463
+ case "WaitAgents":
464
+ return opts.subagents.waitAgents(request.ids);
465
+ case "MessageAgent":
466
+ return opts.subagents.messageAgent(request);
467
+ case "StopAgent":
468
+ return opts.subagents.stopAgent(request.id);
469
+ case "ListAgents":
470
+ return opts.subagents.listAgents;
471
+ case "LoopTool": {
472
+ const handler = opts.loopTools?.[request.name];
473
+ return handler
474
+ ? handler(request.params)
475
+ : Effect.fail(`Unknown loop-side tool: ${request.name}`);
476
+ }
477
+ }
478
+ };
479
+ // Script arguments cross the RPC boundary as JSON.
480
+ const toJson = (name, params) => Effect.try({
481
+ try: () => {
482
+ const json = JSON.stringify(params);
483
+ return json === undefined ? undefined : JSON.parse(json);
484
+ },
485
+ catch: (error) => `Invalid arguments for ${name}: ${errorMessage(error)}`,
486
+ });
487
+ // The built-in handlers sit underneath the caller's context, so a caller tool
488
+ // named like a built-in keeps its own handler.
489
+ const withBuiltInHandlers = (effect) => Effect.flatMap(Layer.build(AgentToolHandlers), (builtIns) => Effect.updateContext(effect, (context) => Context.merge(builtIns, context)));
490
+ const exitToResponse = (exit) => {
491
+ if (Exit.isSuccess(exit)) {
492
+ return { _tag: "Success", value: (exit.value ?? null) };
493
+ }
494
+ return { _tag: "Failure", message: errorMessage(Cause.squash(exit.cause)) };
495
+ };
496
+ const errorMessage = (error) => typeof error === "string"
497
+ ? error
498
+ : error instanceof Error
499
+ ? error.message
500
+ : String(error);
501
+ // Leaving out `delegate` leaves out the tools that address its sub-agents.
502
+ const excludedToolNames = (excludeTools) => {
503
+ const names = new Set(excludeTools);
504
+ if (names.has("delegate")) {
505
+ for (const name of [
506
+ "waitAgents",
507
+ "messageAgent",
508
+ "stopAgent",
509
+ "listAgents",
510
+ ]) {
511
+ names.add(name);
512
+ }
513
+ }
514
+ return names;
515
+ };
340
516
  const wrapScript = (script) => `async function main() {
341
517
  ${script}
342
518
  }`;
343
- const compileScript = (script) => {
519
+ /**
520
+ * Returns source that compiles, preprocessing the script if it has syntax
521
+ * errors. Throws the original syntax error if neither version compiles.
522
+ */
523
+ const prepareScript = (script) => {
524
+ const source = wrapScript(script);
344
525
  try {
345
- return new NodeVm.Script(wrapScript(script));
526
+ // Compiled only to check the syntax. The worker compiles it again.
527
+ // oxlint-disable-next-line eslint/no-new
528
+ new NodeVm.Script(source);
529
+ return source;
346
530
  }
347
531
  catch (error) {
348
532
  if (!(error instanceof SyntaxError)) {
@@ -352,15 +536,148 @@ const compileScript = (script) => {
352
536
  if (preprocessed === script) {
353
537
  throw error;
354
538
  }
539
+ const preprocessedSource = wrapScript(preprocessed);
355
540
  try {
356
- return new NodeVm.Script(wrapScript(preprocessed));
541
+ // oxlint-disable-next-line eslint/no-new
542
+ new NodeVm.Script(preprocessedSource);
543
+ return preprocessedSource;
357
544
  }
358
545
  catch {
359
546
  throw error;
360
547
  }
361
548
  }
362
549
  };
363
- const defaultMain = () => Promise.resolve();
550
+ // -------------------------------------------
551
+ // Script worker
552
+ //
553
+ // The worker runs from source text (`new Worker(source, { eval: true })`), so
554
+ // it needs no separate file in the package, the CLI bundle or a consumer's
555
+ // bundle. The source is built from the function declarations below with
556
+ // `Function.prototype.toString`, which keeps them type-checked and shared
557
+ // with the parent instead of copied into a string.
558
+ //
559
+ // Constraints, because the text of each function must run on its own:
560
+ // - Each must be a `function` declaration, so its text carries its name.
561
+ // - They may reference only each other, their parameters and globals: no
562
+ // imports, module-level values or closures.
563
+ // - Node modules are loaded with the `load` parameter, which the source text
564
+ // binds to the worker's `require`. Bundlers rewrite a bare `require` (the
565
+ // CLI bundle turns it into `__require`), but leave a parameter alone.
566
+ // - A bundler must keep their bodies whole. Renaming identifiers
567
+ // consistently is fine. Transforms that move code out of a body, such as
568
+ // coverage instrumentation or helper hoisting, are not. Only the
569
+ // library build and the CLI bundle are checked.
570
+ // The executor tests run every script through this worker, so they catch a
571
+ // broken constraint in the source. They run the source, not a bundle, so a
572
+ // bundler's rewrites only show up when the built output is run.
573
+ // -------------------------------------------
574
+ function toFailure(value) {
575
+ if (Object.prototype.toString.call(value) === "[object Error]") {
576
+ const error = value;
577
+ return {
578
+ _tag: "Error",
579
+ name: error.name,
580
+ message: error.message,
581
+ stack: error.stack,
582
+ };
583
+ }
584
+ try {
585
+ return { _tag: "Value", value: structuredClone(value) };
586
+ }
587
+ catch {
588
+ return { _tag: "Value", value: String(value) };
589
+ }
590
+ }
591
+ function fromFailure(failure) {
592
+ if (failure._tag === "Value")
593
+ return failure.value;
594
+ const error = new Error(failure.message);
595
+ error.name = failure.name;
596
+ if (failure.stack !== undefined)
597
+ error.stack = failure.stack;
598
+ return error;
599
+ }
600
+ /**
601
+ * Runs one script inside a vm context with the same globals as before, and
602
+ * forwards console output and tool calls to the parent.
603
+ */
604
+ function runScriptWorker(load) {
605
+ // Type-only references: the casts are erased, so the text stays
606
+ // self-contained.
607
+ const { parentPort, workerData } = load("node:worker_threads");
608
+ const vm = load("node:vm");
609
+ const { Console } = load("node:console");
610
+ const { Writable: WorkerWritable } = load("node:stream");
611
+ const port = parentPort;
612
+ const data = workerData;
613
+ // Like the parent process: a stray rejection must not end the script.
614
+ process.on("uncaughtException", () => { });
615
+ process.on("unhandledRejection", () => { });
616
+ const post = (message) => port.postMessage(message);
617
+ const pending = new Map();
618
+ let nextId = 0;
619
+ let mainSettled = false;
620
+ let done = false;
621
+ // Done once main() has settled and no tool call is outstanding. The check
622
+ // runs after the microtasks a result triggers, so a continuation that
623
+ // calls another tool is waited for too. Done is sent once.
624
+ const maybeDone = () => {
625
+ if (done || !mainSettled || pending.size > 0)
626
+ return;
627
+ setImmediate(() => {
628
+ if (done || pending.size > 0)
629
+ return;
630
+ done = true;
631
+ post({ _tag: "Done" });
632
+ });
633
+ };
634
+ port.on("message", (message) => {
635
+ const call = pending.get(message.id);
636
+ if (call === undefined)
637
+ return;
638
+ pending.delete(message.id);
639
+ if (message.ok)
640
+ call.resolve(message.value);
641
+ else
642
+ call.reject(fromFailure(message.failure));
643
+ maybeDone();
644
+ });
645
+ const stdout = new WorkerWritable({
646
+ write(chunk, _encoding, callback) {
647
+ post({ _tag: "Output", text: String(chunk) });
648
+ callback();
649
+ },
650
+ });
651
+ const sandbox = {
652
+ console: new Console({ stdout, colorMode: false }),
653
+ fetch,
654
+ process: undefined,
655
+ };
656
+ for (const name of data.tools) {
657
+ sandbox[name] = (params) => new Promise((resolve, reject) => {
658
+ const id = nextId++;
659
+ pending.set(id, { resolve, reject });
660
+ try {
661
+ post({ _tag: "Call", id, name, params });
662
+ }
663
+ catch (error) {
664
+ // The params cannot be copied to the parent.
665
+ pending.delete(id);
666
+ reject(error);
667
+ maybeDone();
668
+ }
669
+ });
670
+ }
671
+ new vm.Script(data.source).runInNewContext(sandbox);
672
+ sandbox.main().then(() => {
673
+ mainSettled = true;
674
+ maybeDone();
675
+ }, (error) => post({ _tag: "Failed", failure: toFailure(error) }));
676
+ }
677
+ const workerSource = `${toFailure}
678
+ ${fromFailure}
679
+ (${runScriptWorker})(require)
680
+ `;
364
681
  const homeDirectory = () => {
365
682
  const fromEnv = process.env.HOME;
366
683
  if (fromEnv)