clanka 0.9.0 → 0.10.1

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 (81) hide show
  1. package/dist/Acp.d.ts +6 -1
  2. package/dist/Acp.d.ts.map +1 -1
  3. package/dist/Acp.js +25 -0
  4. package/dist/Acp.js.map +1 -1
  5. package/dist/Acp.test.js +109 -4
  6. package/dist/Acp.test.js.map +1 -1
  7. package/dist/AcpImage.test.js +6 -1
  8. package/dist/AcpImage.test.js.map +1 -1
  9. package/dist/Agent.d.ts +17 -0
  10. package/dist/Agent.d.ts.map +1 -1
  11. package/dist/Agent.js +91 -15
  12. package/dist/Agent.js.map +1 -1
  13. package/dist/Agent.test.js +9 -1
  14. package/dist/Agent.test.js.map +1 -1
  15. package/dist/AgentCallerConfig.test.js +9 -1
  16. package/dist/AgentCallerConfig.test.js.map +1 -1
  17. package/dist/AgentEnvironment.d.ts +76 -0
  18. package/dist/AgentEnvironment.d.ts.map +1 -0
  19. package/dist/AgentEnvironment.js +119 -0
  20. package/dist/AgentEnvironment.js.map +1 -0
  21. package/dist/AgentEnvironment.test.d.ts +2 -0
  22. package/dist/AgentEnvironment.test.d.ts.map +1 -0
  23. package/dist/AgentEnvironment.test.js +304 -0
  24. package/dist/AgentEnvironment.test.js.map +1 -0
  25. package/dist/AgentExecutor.d.ts +146 -187
  26. package/dist/AgentExecutor.d.ts.map +1 -1
  27. package/dist/AgentExecutor.js +212 -49
  28. package/dist/AgentExecutor.js.map +1 -1
  29. package/dist/AgentExecutor.test.js +94 -8
  30. package/dist/AgentExecutor.test.js.map +1 -1
  31. package/dist/AgentExecutorImage.test.js +3 -0
  32. package/dist/AgentExecutorImage.test.js.map +1 -1
  33. package/dist/AgentImage.test.js +11 -2
  34. package/dist/AgentImage.test.js.map +1 -1
  35. package/dist/AgentOutput.d.ts +17 -4
  36. package/dist/AgentOutput.d.ts.map +1 -1
  37. package/dist/AgentOutput.js +13 -0
  38. package/dist/AgentOutput.js.map +1 -1
  39. package/dist/AgentSkills.d.ts +15 -0
  40. package/dist/AgentSkills.d.ts.map +1 -1
  41. package/dist/AgentSkills.js +60 -32
  42. package/dist/AgentSkills.js.map +1 -1
  43. package/dist/AgentSkills.test.js +12 -2
  44. package/dist/AgentSkills.test.js.map +1 -1
  45. package/dist/AgentSubagents.test.js +42 -0
  46. package/dist/AgentSubagents.test.js.map +1 -1
  47. package/dist/AgentTools.d.ts +4 -0
  48. package/dist/AgentTools.d.ts.map +1 -1
  49. package/dist/AgentTools.js +7 -2
  50. package/dist/AgentTools.js.map +1 -1
  51. package/dist/AgentToolsReadFile.test.d.ts +2 -0
  52. package/dist/AgentToolsReadFile.test.d.ts.map +1 -0
  53. package/dist/AgentToolsReadFile.test.js +49 -0
  54. package/dist/AgentToolsReadFile.test.js.map +1 -0
  55. package/dist/OutputFormatter.d.ts.map +1 -1
  56. package/dist/OutputFormatter.js +3 -0
  57. package/dist/OutputFormatter.js.map +1 -1
  58. package/dist/bin/{OutputFormatter-DXXKo4E8.mjs → OutputFormatter-BFAv48k9.mjs} +2 -1
  59. package/dist/bin/{OutputFormatter-DXXKo4E8.mjs.map → OutputFormatter-BFAv48k9.mjs.map} +1 -1
  60. package/dist/bin/cli.mjs +13318 -13094
  61. package/dist/bin/cli.mjs.map +1 -1
  62. package/package.json +1 -1
  63. package/src/Acp.test.ts +162 -5
  64. package/src/Acp.ts +24 -1
  65. package/src/AcpImage.test.ts +6 -1
  66. package/src/Agent.test.ts +9 -1
  67. package/src/Agent.ts +137 -12
  68. package/src/AgentCallerConfig.test.ts +9 -1
  69. package/src/AgentEnvironment.test.ts +504 -0
  70. package/src/AgentEnvironment.ts +161 -0
  71. package/src/AgentExecutor.test.ts +121 -4
  72. package/src/AgentExecutor.ts +388 -99
  73. package/src/AgentExecutorImage.test.ts +3 -0
  74. package/src/AgentImage.test.ts +11 -2
  75. package/src/AgentOutput.ts +17 -0
  76. package/src/AgentSkills.test.ts +12 -2
  77. package/src/AgentSkills.ts +74 -34
  78. package/src/AgentSubagents.test.ts +66 -0
  79. package/src/AgentTools.ts +13 -1
  80. package/src/AgentToolsReadFile.test.ts +61 -0
  81. package/src/OutputFormatter.ts +3 -0
@@ -209,9 +209,12 @@ const execute = (
209
209
  ) =>
210
210
  Effect.gen(function* () {
211
211
  const executor = yield* AgentExecutor.AgentExecutor
212
+ const { environment } = yield* executor.capabilities
212
213
  return yield* executor
213
214
  .execute({
214
215
  script,
216
+ environment,
217
+ onEnvironment: () => Effect.void,
215
218
  onTaskComplete: () => Effect.void,
216
219
  onImage: () => Effect.void,
217
220
  subagents: subagentsUnavailable,
@@ -500,7 +503,12 @@ describe("executor capabilities", () => {
500
503
  const encoded = yield* Schema.encodeEffect(codec)(
501
504
  new AgentExecutor.Capabilities({
502
505
  toolsDts: "",
503
- agentsMd: Option.none(),
506
+ environment: new AgentExecutor.ExecutionEnvironment({
507
+ cwd: "/",
508
+ baseline: [],
509
+ seen: [],
510
+ }),
511
+ instructions: Option.none(),
504
512
  supportsSearch: false,
505
513
  tools: ["readFile"],
506
514
  skills: [],
@@ -0,0 +1,504 @@
1
+ import { assert, describe, it } from "@effect/vitest"
2
+ import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer"
3
+ import * as NodeServices from "@effect/platform-node/NodeServices"
4
+ import * as Deferred from "effect/Deferred"
5
+ import * as Effect from "effect/Effect"
6
+ import * as Exit from "effect/Exit"
7
+ import * as Fiber from "effect/Fiber"
8
+ import * as FileSystem from "effect/FileSystem"
9
+ import * as FetchHttpClient from "effect/http/FetchHttpClient"
10
+ import * as HttpServer from "effect/http/HttpServer"
11
+ import * as Layer from "effect/Layer"
12
+ import * as MutableRef from "effect/MutableRef"
13
+ import * as Option from "effect/Option"
14
+ import * as Schema from "effect/Schema"
15
+ import * as Stream from "effect/Stream"
16
+ import type * as AiError from "effect/ai/AiError"
17
+ import * as LanguageModel from "effect/ai/LanguageModel"
18
+ import * as Model from "effect/ai/Model"
19
+ import * as Prompt from "effect/ai/Prompt"
20
+ import type * as Response from "effect/ai/Response"
21
+ import * as RpcClient from "effect/rpc/RpcClient"
22
+ import * as RpcSerialization from "effect/rpc/RpcSerialization"
23
+ import * as RpcServer from "effect/rpc/RpcServer"
24
+ import * as NodeFs from "node:fs"
25
+ import * as NodePath from "node:path"
26
+ import * as Agent from "./Agent.ts"
27
+ import * as AgentEnvironment from "./AgentEnvironment.ts"
28
+ import * as AgentExecutor from "./AgentExecutor.ts"
29
+ import type * as AgentOutput from "./AgentOutput.ts"
30
+ import * as Compaction from "./Compaction.ts"
31
+
32
+ const skill = (name: string) => `---
33
+ name: ${name}
34
+ description: The ${name} skill.
35
+ ---
36
+
37
+ Instructions for ${name}.
38
+ `
39
+
40
+ const projectFiles: Record<string, string> = {
41
+ "AGENTS.md": "ROOT-RULES",
42
+ ".agents/skills/root-skill/SKILL.md": skill("root-skill"),
43
+ "pkg/AGENTS.md": "PKG-RULES",
44
+ "pkg/.agents/skills/pkg-skill/SKILL.md": skill("pkg-skill"),
45
+ }
46
+
47
+ const makeProject = Effect.gen(function* () {
48
+ const fs = yield* FileSystem.FileSystem
49
+ const directory = yield* fs.makeTempDirectoryScoped()
50
+ for (const [file, content] of Object.entries(projectFiles)) {
51
+ const target = NodePath.join(directory, file)
52
+ yield* fs.makeDirectory(NodePath.dirname(target), { recursive: true })
53
+ yield* fs.writeFileString(target, content)
54
+ }
55
+ return directory
56
+ })
57
+
58
+ const executors = {
59
+ local: Layer.unwrap(
60
+ Effect.map(makeProject, (directory) =>
61
+ AgentExecutor.layerLocal({ directory }),
62
+ ),
63
+ ).pipe(
64
+ Layer.provide(Layer.mergeAll(NodeServices.layer, FetchHttpClient.layer)),
65
+ ),
66
+ rpc: Layer.unwrap(
67
+ Effect.gen(function* () {
68
+ const directory = yield* makeProject
69
+ const { protocol, httpEffect } =
70
+ yield* RpcServer.makeProtocolWithHttpEffect()
71
+ yield* Layer.build(
72
+ AgentExecutor.layerRpcServer({ directory }).pipe(
73
+ Layer.provide(Layer.succeed(RpcServer.Protocol, protocol)),
74
+ ),
75
+ )
76
+ yield* HttpServer.serveEffect(httpEffect)
77
+ return AgentExecutor.layerRpc.pipe(
78
+ Layer.provide(RpcClient.layerProtocolHttp({ url: "" })),
79
+ )
80
+ }),
81
+ ).pipe(
82
+ Layer.provide(
83
+ Layer.mergeAll(
84
+ RpcSerialization.layerNdjson,
85
+ NodeHttpServer.layerTest,
86
+ NodeServices.layer,
87
+ ),
88
+ ),
89
+ ),
90
+ }
91
+
92
+ interface Call {
93
+ readonly prompt: Prompt.Prompt
94
+ readonly isSummarizer: boolean
95
+ }
96
+
97
+ type Respond = (
98
+ call: Call,
99
+ ) => Stream.Stream<Response.StreamPartEncoded, AiError.AiError>
100
+
101
+ // An Agent on the provided executor and a scripted model that records every
102
+ // call and output. The summarizer is the call without tools.
103
+ const makeAgent = (options: {
104
+ readonly respond: Respond
105
+ readonly compaction?: Partial<Compaction.CompactionConfigService> | undefined
106
+ }) =>
107
+ Effect.gen(function* () {
108
+ const calls: Array<Call> = []
109
+ const outputs: Array<AgentOutput.Output> = []
110
+ const record = (prompt: Prompt.Prompt, tools: ReadonlyArray<unknown>) => {
111
+ const call: Call = { prompt, isSummarizer: tools.length === 0 }
112
+ calls.push(call)
113
+ return options.respond(call)
114
+ }
115
+ const languageModel = yield* LanguageModel.make({
116
+ generateText: (providerOptions) =>
117
+ record(providerOptions.prompt, providerOptions.tools).pipe(
118
+ Stream.runCollect,
119
+ Effect.map((parts): Array<Response.PartEncoded> => [
120
+ {
121
+ type: "text",
122
+ text: parts
123
+ .flatMap((part) =>
124
+ part.type === "text-delta" ? [part.delta] : [],
125
+ )
126
+ .join(""),
127
+ },
128
+ ...parts.filter((part) => part.type === "finish"),
129
+ ]),
130
+ ),
131
+ streamText: (providerOptions) =>
132
+ record(providerOptions.prompt, providerOptions.tools),
133
+ })
134
+ const modelLayer = Layer.mergeAll(
135
+ Layer.succeed(LanguageModel.LanguageModel, languageModel),
136
+ Layer.succeed(Model.ProviderName, "test-provider"),
137
+ Layer.succeed(Model.ModelName, "test-model"),
138
+ )
139
+ const agent = yield* Agent.make
140
+ const send = (prompt: string) =>
141
+ agent.send({ prompt }).pipe(
142
+ Effect.flatMap((stream) =>
143
+ stream.pipe(
144
+ Stream.runForEach((output) =>
145
+ Effect.sync(() => {
146
+ outputs.push(output)
147
+ }),
148
+ ),
149
+ Effect.as(""),
150
+ Effect.catchTag("AgentFinished", (finished) =>
151
+ Effect.succeed(finished.summary),
152
+ ),
153
+ ),
154
+ ),
155
+ Effect.provide(
156
+ Layer.mergeAll(
157
+ modelLayer,
158
+ Agent.ConversationMode.layer(true),
159
+ Agent.layerSubagentModel(modelLayer),
160
+ Compaction.CompactionConfig.layer(options.compaction ?? {}),
161
+ ),
162
+ ),
163
+ Effect.scoped,
164
+ Effect.exit,
165
+ )
166
+ return { agent, calls, outputs, send }
167
+ })
168
+
169
+ let callId = 0
170
+ const toolCall = (script: string): Response.StreamPartEncoded => ({
171
+ type: "tool-call",
172
+ id: `call-${callId++}`,
173
+ name: "execute",
174
+ params: { script },
175
+ })
176
+
177
+ const text = (content: string): Array<Response.StreamPartEncoded> => [
178
+ { type: "text-start", id: "t" },
179
+ { type: "text-delta", id: "t", delta: content },
180
+ { type: "text-end", id: "t" },
181
+ ]
182
+
183
+ const finish = (
184
+ contextTokens: number,
185
+ reason: "stop" | "tool-calls" = "tool-calls",
186
+ ): Response.StreamPartEncoded => ({
187
+ type: "finish",
188
+ reason,
189
+ usage: {
190
+ inputTokens: { total: contextTokens },
191
+ outputTokens: { total: 10 },
192
+ },
193
+ })
194
+
195
+ const messageText = (message: Prompt.Message): string =>
196
+ typeof message.content === "string"
197
+ ? message.content
198
+ : message.content
199
+ .map((part) => (part.type === "text" ? part.text : ""))
200
+ .join("")
201
+
202
+ const isChild = (call: Call) =>
203
+ call.prompt.content.some(
204
+ (message) =>
205
+ message.role === "user" && messageText(message).includes("TASK-CHILD"),
206
+ )
207
+
208
+ const environmentUpdates = (prompt: Prompt.Prompt): Array<string> =>
209
+ prompt.content.flatMap((message) => {
210
+ if (message.role !== "user") return []
211
+ const content = messageText(message)
212
+ return content.includes("<environment-update") ? [content] : []
213
+ })
214
+
215
+ const encodePrompt = Schema.encodeSync(Prompt.Prompt)
216
+ const systemJson = (prompt: Prompt.Prompt) =>
217
+ JSON.stringify(
218
+ encodePrompt(prompt).content.filter((message) => message.role === "system"),
219
+ )
220
+ const conversationJson = (prompt: Prompt.Prompt) =>
221
+ JSON.stringify(
222
+ encodePrompt(prompt).content.filter((message) => message.role !== "system"),
223
+ )
224
+
225
+ // Two earlier turns of about 7.5k tokens each, so there is something to
226
+ // summarize.
227
+ const fatHistory = Prompt.fromMessages(
228
+ [1, 2].flatMap((n) => [
229
+ Prompt.makeMessage("user", {
230
+ content: [Prompt.makePart("text", { text: `Read log ${n}` })],
231
+ }),
232
+ Prompt.makeMessage("assistant", {
233
+ content: [
234
+ Prompt.makePart("tool-call", {
235
+ id: `old-${n}`,
236
+ name: "execute",
237
+ params: { script: `await readFile({ path: "${n}.log" })` },
238
+ providerExecuted: false,
239
+ }),
240
+ ],
241
+ }),
242
+ Prompt.makeMessage("tool", {
243
+ content: [
244
+ Prompt.makePart("tool-result", {
245
+ id: `old-${n}`,
246
+ name: "execute",
247
+ isFailure: false,
248
+ result: "log ".repeat(7_500),
249
+ providerExecuted: false,
250
+ }),
251
+ ],
252
+ }),
253
+ ]),
254
+ )
255
+
256
+ for (const [mode, executorLayer] of Object.entries(executors)) {
257
+ describe(`environment updates (${mode} executor)`, () => {
258
+ it.live(
259
+ "a cd sends only the new instructions and skills, once, with the same system prompt",
260
+ () =>
261
+ Effect.gen(function* () {
262
+ let rootCalls = 0
263
+ const { calls, outputs, send } = yield* makeAgent({
264
+ respond: (call) => {
265
+ if (isChild(call)) {
266
+ return Stream.make(toolCall(`await taskComplete("child done")`))
267
+ }
268
+ switch (rootCalls++) {
269
+ case 0:
270
+ return Stream.make(
271
+ toolCall(`await changeDirectory("pkg")`),
272
+ toolCall(`await changeDirectory("pkg")`),
273
+ )
274
+ case 1:
275
+ return Stream.make(toolCall(`await changeDirectory("..")`))
276
+ case 2:
277
+ return Stream.make(toolCall(`await changeDirectory("pkg")`))
278
+ case 3:
279
+ return Stream.make(
280
+ toolCall(`await delegate({ prompt: "TASK-CHILD" })`),
281
+ )
282
+ default:
283
+ return Stream.fromIterable(text("done"))
284
+ }
285
+ },
286
+ })
287
+ const exit = yield* send("hello")
288
+
289
+ assert.deepStrictEqual(exit, Exit.succeed("done"))
290
+ const root = calls.filter((call) => !isChild(call))
291
+ assert.strictEqual(root.length, 5)
292
+ for (const call of root) {
293
+ assert.strictEqual(
294
+ systemJson(call.prompt),
295
+ systemJson(root[0]!.prompt),
296
+ "the system prompt never changes",
297
+ )
298
+ }
299
+
300
+ const afterCd = root[1]!.prompt
301
+ const updates = environmentUpdates(afterCd)
302
+ assert.strictEqual(updates.length, 1)
303
+ assert.include(updates[0], "PKG-RULES")
304
+ assert.include(updates[0], "pkg-skill")
305
+ assert.notInclude(updates[0], "ROOT-RULES")
306
+ assert.notInclude(updates[0], "root-skill")
307
+ const updateIndex = afterCd.content.findIndex(
308
+ (message) =>
309
+ message.role === "user" &&
310
+ messageText(message).includes("<environment-update"),
311
+ )
312
+ assert.isAbove(
313
+ updateIndex,
314
+ afterCd.content.findLastIndex((message) => message.role === "tool"),
315
+ "the update follows the tool result",
316
+ )
317
+
318
+ assert.strictEqual(
319
+ environmentUpdates(root[4]!.prompt).length,
320
+ 1,
321
+ "leaving and entering pkg again sends nothing new",
322
+ )
323
+
324
+ const child = calls.find(isChild)
325
+ assert.isDefined(child)
326
+ assert.include(
327
+ JSON.stringify(encodePrompt(child!.prompt)),
328
+ "PKG-RULES",
329
+ "a delegate started after the cd sees pkg's instructions",
330
+ )
331
+ const childUpdates = outputs.flatMap((output) =>
332
+ output._tag === "SubagentPart" &&
333
+ output.part._tag === "EnvironmentUpdated"
334
+ ? [{ id: output.id, update: output.part.update }]
335
+ : [],
336
+ )
337
+ assert.strictEqual(childUpdates.length, 1)
338
+ assert.strictEqual(childUpdates[0]!.id, 1)
339
+ assert.include(childUpdates[0]!.update, "PKG-RULES")
340
+ }).pipe(
341
+ Effect.scoped,
342
+ Effect.timeout("4 seconds"),
343
+ Effect.provide(executorLayer),
344
+ ),
345
+ )
346
+
347
+ it.live(
348
+ "compaction preserves instructions through cancellation and refreshes them once",
349
+ () =>
350
+ Effect.gen(function* () {
351
+ const executor = yield* AgentExecutor.AgentExecutor
352
+ const refreshing = yield* Deferred.make<void>()
353
+ let refreshes = 0
354
+ // The first refresh hangs, so the turn is cancelled during it.
355
+ const gated = AgentExecutor.AgentExecutor.of({
356
+ ...executor,
357
+ renderEnvironment: (environment, options) =>
358
+ options?.reset && refreshes++ === 0
359
+ ? Deferred.succeed(refreshing, undefined).pipe(
360
+ Effect.andThen(Effect.never),
361
+ )
362
+ : executor.renderEnvironment!(environment, options),
363
+ })
364
+ let rootCalls = 0
365
+ const { agent, calls, send } = yield* makeAgent({
366
+ compaction: {
367
+ contextWindow: 40_000,
368
+ reserveTokens: 4_000,
369
+ keepRecentTokens: 9_000,
370
+ },
371
+ respond: (call) => {
372
+ if (call.isSummarizer) {
373
+ return Stream.fromIterable([
374
+ ...text("EARLIER-WORK-SUMMARY"),
375
+ finish(6_000, "stop"),
376
+ ])
377
+ }
378
+ switch (rootCalls++) {
379
+ case 0:
380
+ // Usage over the threshold compacts before the next call.
381
+ return Stream.make(
382
+ toolCall(`await changeDirectory("pkg")`),
383
+ finish(37_000),
384
+ )
385
+ case 1:
386
+ return Stream.make(
387
+ toolCall(`console.log("next")`),
388
+ finish(37_000),
389
+ )
390
+ default:
391
+ return Stream.fromIterable([
392
+ ...text("done"),
393
+ finish(9_000, "stop"),
394
+ ])
395
+ }
396
+ },
397
+ }).pipe(Effect.provideService(AgentExecutor.AgentExecutor, gated))
398
+ MutableRef.set(agent.history, fatHistory)
399
+
400
+ const first = yield* Effect.forkScoped(send("start"))
401
+ yield* Deferred.await(refreshing)
402
+ yield* Fiber.interrupt(first)
403
+ const exit = yield* send("continue")
404
+
405
+ assert.deepStrictEqual(exit, Exit.succeed("done"))
406
+ assert.strictEqual(
407
+ conversationJson(
408
+ calls.filter((call) => !call.isSummarizer)[1]!.prompt,
409
+ ).split("PKG-RULES").length - 1,
410
+ 1,
411
+ "cancellation preserves the delivered instructions",
412
+ )
413
+ assert.include(
414
+ conversationJson(calls.at(-1)!.prompt),
415
+ "EARLIER-WORK-SUMMARY",
416
+ )
417
+ assert.strictEqual(
418
+ conversationJson(calls.at(-1)!.prompt).split("PKG-RULES").length -
419
+ 1,
420
+ 1,
421
+ "pkg's instructions appear exactly once",
422
+ )
423
+ }).pipe(
424
+ Effect.scoped,
425
+ Effect.timeout("4 seconds"),
426
+ Effect.provide(executorLayer),
427
+ ),
428
+ )
429
+
430
+ // The update for an interrupted script never reaches the history, so its
431
+ // instructions must still be sent with the next script.
432
+ it.live("instructions found by an interrupted script reach the model", () =>
433
+ Effect.gen(function* () {
434
+ const executor = yield* AgentExecutor.AgentExecutor
435
+ const { environment } = yield* executor.capabilities
436
+ const marker = NodePath.join(environment.cwd, "pkg", "changed")
437
+ let rootCalls = 0
438
+ const { calls, send } = yield* makeAgent({
439
+ respond: () => {
440
+ switch (rootCalls++) {
441
+ case 0:
442
+ return Stream.make(
443
+ toolCall(`await changeDirectory("pkg")
444
+ await writeFile({ path: "changed", content: "" })
445
+ await sleep(60000)`),
446
+ )
447
+ case 1:
448
+ return Stream.make(toolCall(`console.log("next")`))
449
+ default:
450
+ return Stream.fromIterable(text("done"))
451
+ }
452
+ },
453
+ })
454
+
455
+ const first = yield* Effect.forkScoped(send("start"))
456
+ while (!NodeFs.existsSync(marker)) {
457
+ yield* Effect.sleep("10 millis")
458
+ }
459
+ yield* Fiber.interrupt(first)
460
+ const exit = yield* send("continue")
461
+
462
+ assert.deepStrictEqual(exit, Exit.succeed("done"))
463
+ assert.strictEqual(calls.length, 3)
464
+ assert.isTrue(
465
+ environmentUpdates(calls[2]!.prompt).some((update) =>
466
+ update.includes("PKG-RULES"),
467
+ ),
468
+ "pkg's instructions are sent after the next script",
469
+ )
470
+ }).pipe(
471
+ Effect.scoped,
472
+ Effect.timeout("4 seconds"),
473
+ Effect.provide(executorLayer),
474
+ ),
475
+ )
476
+ })
477
+ }
478
+
479
+ // A directory named `..pkg` is inside the startup directory, so the walk
480
+ // stops there and leaves out the AGENTS.md above it.
481
+ it.effect("discovery stops at the startup directory", () =>
482
+ Effect.gen(function* () {
483
+ const fs = yield* FileSystem.FileSystem
484
+ const root = yield* makeProject
485
+ const startup = NodePath.join(root, "start")
486
+ const cwd = NodePath.join(startup, "..pkg")
487
+ yield* fs.makeDirectory(cwd, { recursive: true })
488
+ yield* fs.writeFileString(
489
+ NodePath.join(startup, "AGENTS.md"),
490
+ "START-RULES",
491
+ )
492
+
493
+ const discovered = yield* AgentEnvironment.discover({
494
+ cwd,
495
+ startup,
496
+ home: Option.none(),
497
+ })
498
+
499
+ assert.deepStrictEqual(
500
+ discovered.instructions.map((item) => item.content),
501
+ ["START-RULES"],
502
+ )
503
+ }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
504
+ )
@@ -0,0 +1,161 @@
1
+ /**
2
+ * Find the AGENTS.md files and skills that apply to a directory, and render
3
+ * them for the model.
4
+ *
5
+ * @since 1.0.0
6
+ */
7
+ import * as Effect from "effect/Effect"
8
+ import * as FileSystem from "effect/FileSystem"
9
+ import * as Option from "effect/Option"
10
+ import * as Path from "effect/Path"
11
+ import * as AgentSkills from "./AgentSkills.ts"
12
+
13
+ /**
14
+ * The most characters of one AGENTS.md sent to the model.
15
+ *
16
+ * @since 1.0.0
17
+ * @category Constants
18
+ */
19
+ export const maxInstructionsChars = 32_000
20
+
21
+ /**
22
+ * An AGENTS.md file and the directory it applies to.
23
+ *
24
+ * @since 1.0.0
25
+ * @category Models
26
+ */
27
+ export interface Instructions {
28
+ readonly id: string
29
+ readonly path: string
30
+ readonly directory: string
31
+ readonly content: string
32
+ }
33
+
34
+ /**
35
+ * @since 1.0.0
36
+ * @category Models
37
+ */
38
+ export interface Discovered {
39
+ /** Outermost directory first. */
40
+ readonly instructions: ReadonlyArray<Instructions>
41
+ /** Outermost directory first. */
42
+ readonly skills: ReadonlyArray<AgentSkills.Skill>
43
+ }
44
+
45
+ /**
46
+ * The id that records whether a skill has been sent to the model.
47
+ *
48
+ * @since 1.0.0
49
+ * @category Models
50
+ */
51
+ export const skillId = (skill: AgentSkills.Skill): string =>
52
+ `skill:${skill.location}`
53
+
54
+ /**
55
+ * The AGENTS.md files and project skills from `cwd` up to the startup
56
+ * directory when `cwd` is inside it, or else up to the nearest git root. The
57
+ * walk never goes up into `home` or the filesystem root.
58
+ *
59
+ * @since 1.0.0
60
+ * @category Discovery
61
+ */
62
+ export const discover = Effect.fnUntraced(function* (options: {
63
+ readonly cwd: string
64
+ readonly startup: string
65
+ readonly home: Option.Option<string>
66
+ }): Effect.fn.Return<Discovered, never, FileSystem.FileSystem | Path.Path> {
67
+ const fs = yield* FileSystem.FileSystem
68
+ const path = yield* Path.Path
69
+ const relative = path.relative(options.startup, options.cwd)
70
+ // `..pkg` is a child, so compare the first path segment, not a prefix.
71
+ const inside =
72
+ relative !== ".." &&
73
+ !relative.startsWith(`..${path.sep}`) &&
74
+ !path.isAbsolute(relative)
75
+
76
+ const directories: Array<string> = []
77
+ let directory = options.cwd
78
+ while (true) {
79
+ directories.push(directory)
80
+ if (
81
+ inside
82
+ ? directory === options.startup
83
+ : yield* fs
84
+ .exists(path.join(directory, ".git"))
85
+ .pipe(Effect.orElseSucceed(() => false))
86
+ ) {
87
+ break
88
+ }
89
+ const parent = path.dirname(directory)
90
+ if (
91
+ parent === directory ||
92
+ parent === path.parse(parent).root ||
93
+ (Option.isSome(options.home) && parent === options.home.value)
94
+ ) {
95
+ break
96
+ }
97
+ directory = parent
98
+ }
99
+ directories.reverse()
100
+
101
+ const instructions: Array<Instructions> = []
102
+ const skills: Array<AgentSkills.Skill> = []
103
+ for (const directory of directories) {
104
+ const file = path.join(directory, "AGENTS.md")
105
+ const content = yield* Effect.option(fs.readFileString(file))
106
+ if (Option.isSome(content) && content.value.trim() !== "") {
107
+ instructions.push({
108
+ id: `AGENTS.md:${file}`,
109
+ path: file,
110
+ directory,
111
+ content: cap(content.value),
112
+ })
113
+ }
114
+ skills.push(...(yield* AgentSkills.discoverProject(directory)))
115
+ }
116
+ return { instructions, skills }
117
+ })
118
+
119
+ const cap = (content: string) =>
120
+ content.length <= maxInstructionsChars
121
+ ? content
122
+ : `${content.slice(0, maxInstructionsChars)}\n\n[Truncated: the file has ${content.length} characters; read it for the rest.]`
123
+
124
+ /**
125
+ * One AGENTS.md as the model sees it, in the system prompt and in updates.
126
+ *
127
+ * @since 1.0.0
128
+ * @category Rendering
129
+ */
130
+ export const renderInstructions = (instructions: Instructions) => `# AGENTS.md
131
+
132
+ The following instructions are from ${instructions.path}.
133
+ They apply when working under ${instructions.directory}.
134
+ You do not need to read this file again.
135
+
136
+ **ALWAYS follow these instructions when working under ${instructions.directory}**:
137
+
138
+ <!-- AGENTS.md start -->
139
+ ${instructions.content}
140
+ <!-- AGENTS.md end -->`
141
+
142
+ /**
143
+ * The text of an environment update: new AGENTS.md files, outermost first,
144
+ * then new skills.
145
+ *
146
+ * @since 1.0.0
147
+ * @category Rendering
148
+ */
149
+ export const renderUpdate = (discovered: Discovered): string => {
150
+ const sections = discovered.instructions.map(renderInstructions)
151
+ if (discovered.skills.length > 0) {
152
+ sections.push(`# Skills
153
+
154
+ New skills are available, in addition to those listed before. A skill listed
155
+ here takes precedence over an earlier skill with the same name. Read a skill's
156
+ file with "readFile" before a task that matches its description.
157
+
158
+ ${AgentSkills.renderEntries(discovered.skills)}`)
159
+ }
160
+ return sections.join("\n\n")
161
+ }