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
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "clanka",
3
3
  "type": "module",
4
- "version": "0.9.0",
4
+ "version": "0.10.1",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
package/src/Acp.test.ts CHANGED
@@ -1,9 +1,13 @@
1
1
  import { assert, describe, it } from "@effect/vitest"
2
+ import * as NodeServices from "@effect/platform-node/NodeServices"
3
+ import * as Context from "effect/Context"
2
4
  import * as Effect from "effect/Effect"
5
+ import * as FileSystem from "effect/FileSystem"
3
6
  import * as Fiber from "effect/Fiber"
4
7
  import * as Layer from "effect/Layer"
5
8
  import * as Option from "effect/Option"
6
9
  import * as Stream from "effect/Stream"
10
+ import * as FetchHttpClient from "effect/http/FetchHttpClient"
7
11
  import * as Prompt from "effect/ai/Prompt"
8
12
  import * as KeyValueStore from "effect/persistence/KeyValueStore"
9
13
  import * as LanguageModel from "effect/ai/LanguageModel"
@@ -24,7 +28,12 @@ type Message = {
24
28
 
25
29
  const capabilities = new AgentExecutor.Capabilities({
26
30
  toolsDts: "",
27
- agentsMd: Option.none(),
31
+ environment: new AgentExecutor.ExecutionEnvironment({
32
+ cwd: "/",
33
+ baseline: [],
34
+ seen: [],
35
+ }),
36
+ instructions: Option.none(),
28
37
  supportsSearch: false,
29
38
  tools: [],
30
39
  skills: [],
@@ -36,6 +45,16 @@ const executor = AgentExecutor.AgentExecutor.of({
36
45
  executeUnsafe: () => Effect.die("executeUnsafe not implemented"),
37
46
  })
38
47
 
48
+ // A fresh executor per server, like the CLI builds one per session.
49
+ const localExecutor = (directory: string) =>
50
+ Layer.build(
51
+ AgentExecutor.layerLocal({ directory }).pipe(
52
+ Layer.provide(Layer.mergeAll(NodeServices.layer, FetchHttpClient.layer)),
53
+ ),
54
+ ).pipe(
55
+ Effect.map((context) => Context.get(context, AgentExecutor.AgentExecutor)),
56
+ )
57
+
39
58
  const makeServer = (
40
59
  streamText: Parameters<typeof LanguageModel.make>[0]["streamText"],
41
60
  agentExecutor = executor,
@@ -100,6 +119,25 @@ const assistantSays = (text: string) =>
100
119
  { type: "text-end", id: "1" },
101
120
  )
102
121
 
122
+ // A model that runs `script` once, then answers "done".
123
+ const runsScript = (script: string) => {
124
+ let calls = 0
125
+ return () =>
126
+ calls++ === 0
127
+ ? parts({
128
+ type: "tool-call",
129
+ id: "call-1",
130
+ name: "execute",
131
+ params: { script },
132
+ })
133
+ : assistantSays("done")
134
+ }
135
+
136
+ const message = (role: "user" | "assistant", text: string) =>
137
+ Prompt.makeMessage(role, {
138
+ content: [Prompt.makePart("text", { text })],
139
+ })
140
+
103
141
  const withStore = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
104
142
  effect.pipe(
105
143
  Effect.provide(
@@ -195,6 +233,8 @@ describe("Acp", () => {
195
233
  .find((update) => update.sessionUpdate === "usage_update"),
196
234
  {
197
235
  sessionUpdate: "usage_update",
236
+ used: 120,
237
+ size: 236_000,
198
238
  usage: {
199
239
  inputTokens: 84,
200
240
  outputTokens: 12,
@@ -245,6 +285,8 @@ describe("Acp", () => {
245
285
  .find((update) => update.sessionUpdate === "usage_update"),
246
286
  {
247
287
  sessionUpdate: "usage_update",
288
+ used: 120,
289
+ size: 236_000,
248
290
  usage: {
249
291
  inputTokens: 120,
250
292
  outputTokens: 12,
@@ -426,9 +468,16 @@ describe("Acp", () => {
426
468
  : assistantSays(summary),
427
469
  {
428
470
  ...executor,
429
- execute: ({ subagents }) =>
471
+ execute: ({ subagents, environment }) =>
430
472
  Stream.fromEffect(
431
- subagents.delegate({ prompt, background: false }),
473
+ subagents.delegate({
474
+ prompt,
475
+ background: false,
476
+ environment: new AgentExecutor.EnvironmentUpdate({
477
+ environment,
478
+ update: Option.none(),
479
+ }),
480
+ }),
432
481
  ).pipe(
433
482
  Stream.map((result) => result.output ?? ""),
434
483
  Stream.orDie,
@@ -511,11 +560,18 @@ describe("Acp", () => {
511
560
  ...executor,
512
561
  // The first script starts a background child; the second
513
562
  // resumes it once its first result has been delivered.
514
- execute: ({ subagents }) =>
563
+ execute: ({ subagents, environment }) =>
515
564
  Stream.fromEffect(
516
565
  executions++ === 0
517
566
  ? subagents
518
- .delegate({ prompt: "TASK-CHILD", background: true })
567
+ .delegate({
568
+ prompt: "TASK-CHILD",
569
+ background: true,
570
+ environment: new AgentExecutor.EnvironmentUpdate({
571
+ environment,
572
+ update: Option.none(),
573
+ }),
574
+ })
519
575
  .pipe(
520
576
  Effect.map((result) => {
521
577
  childId = result.id
@@ -740,6 +796,107 @@ describe("Acp", () => {
740
796
  ),
741
797
  )
742
798
 
799
+ it.live("keeps the working directory across a session reload", () =>
800
+ withStore(
801
+ Effect.gen(function* () {
802
+ const fs = yield* FileSystem.FileSystem
803
+ const cwd = yield* fs.makeTempDirectoryScoped()
804
+ const sessionId = yield* Effect.scoped(
805
+ Effect.gen(function* () {
806
+ const server = yield* makeServer(
807
+ runsScript(`await bash({ command: "mkdir sub" })
808
+ await changeDirectory("sub")`),
809
+ yield* localExecutor(cwd),
810
+ )
811
+ const created = yield* server.request(1, "session/new", { cwd })
812
+ const sessionId: string = created.result.sessionId
813
+ yield* server.request(2, "session/prompt", {
814
+ sessionId,
815
+ prompt: [{ type: "text", text: "change directory" }],
816
+ })
817
+ return sessionId
818
+ }),
819
+ )
820
+
821
+ const output = yield* Effect.scoped(
822
+ Effect.gen(function* () {
823
+ const server = yield* makeServer(
824
+ runsScript(
825
+ `console.log("PWD:" + (await bash({ command: "pwd" })).trim())`,
826
+ ),
827
+ yield* localExecutor(cwd),
828
+ )
829
+ yield* server.request(1, "session/load", { sessionId, cwd })
830
+ yield* server.request(2, "session/prompt", {
831
+ sessionId,
832
+ prompt: [{ type: "text", text: "print it" }],
833
+ })
834
+ return server
835
+ .updates(sessionId)
836
+ .filter((u) => u.sessionUpdate === "tool_call_update")
837
+ .map((u) => String(u.rawOutput))
838
+ .join("\n")
839
+ }),
840
+ )
841
+ assert.match(output, /PWD:\S*\/sub$/m)
842
+ }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
843
+ ),
844
+ )
845
+
846
+ it.effect(
847
+ "hides environment updates and sub-agent results during replay",
848
+ () =>
849
+ withStore(
850
+ Effect.scoped(
851
+ Effect.gen(function* () {
852
+ const kvs = yield* KeyValueStore.KeyValueStore
853
+ const store = KeyValueStore.toSchemaStore(
854
+ KeyValueStore.prefix(kvs, "session-"),
855
+ Acp.SessionRecord,
856
+ )
857
+ const sessionId = "injected-session"
858
+ yield* store.set(
859
+ sessionId,
860
+ new Acp.SessionRecord({
861
+ cwd: "/tmp",
862
+ model: "test:model",
863
+ thoughtLevel: "medium",
864
+ history: Prompt.fromMessages([
865
+ message("user", "Typed by the user"),
866
+ message(
867
+ "user",
868
+ "<environment-update>\nPKG-RULES\n</environment-update>",
869
+ ),
870
+ message(
871
+ "user",
872
+ '<subagent id="1" status="completed">\nCHILD-RESULT\n</subagent>',
873
+ ),
874
+ message("assistant", "Reply"),
875
+ ]),
876
+ }),
877
+ )
878
+
879
+ const server = yield* makeServer(() => assistantSays("unused"))
880
+ const loaded = yield* server.request(1, "session/load", {
881
+ sessionId,
882
+ cwd: "/tmp",
883
+ })
884
+ assert.isUndefined(loaded.error)
885
+ assert.deepStrictEqual(server.updates(sessionId), [
886
+ {
887
+ sessionUpdate: "user_message_chunk",
888
+ content: { type: "text", text: "Typed by the user" },
889
+ },
890
+ {
891
+ sessionUpdate: "agent_message_chunk",
892
+ content: { type: "text", text: "Reply" },
893
+ },
894
+ ])
895
+ }),
896
+ ),
897
+ ),
898
+ )
899
+
743
900
  it.effect("rejects unknown models and methods", () =>
744
901
  withStore(
745
902
  Effect.scoped(
package/src/Acp.ts CHANGED
@@ -29,7 +29,8 @@ import type * as Model from "effect/ai/Model"
29
29
  import * as Prompt from "effect/ai/Prompt"
30
30
  import * as HttpClient from "effect/http/HttpClient"
31
31
  import * as KeyValueStore from "effect/persistence/KeyValueStore"
32
- import type * as Agent from "./Agent.ts"
32
+ import * as Agent from "./Agent.ts"
33
+ import * as AgentExecutor from "./AgentExecutor.ts"
33
34
  import type * as AgentOutput from "./AgentOutput.ts"
34
35
  import * as Compaction from "./Compaction.ts"
35
36
  import * as Image from "./Image.ts"
@@ -125,6 +126,10 @@ export class SessionRecord extends Schema.Class<SessionRecord>(
125
126
  model: Schema.String,
126
127
  thoughtLevel: ThoughtLevel,
127
128
  history: Prompt.Prompt,
129
+ /**
130
+ * The agent's executor environment, such as its working directory.
131
+ */
132
+ environment: Schema.optionalKey(AgentExecutor.ExecutionEnvironment),
128
133
  }) {}
129
134
 
130
135
  /**
@@ -273,6 +278,7 @@ const historyUpdates = (history: Prompt.Prompt) => {
273
278
  for (const message of history.content) {
274
279
  if (message.role !== "user" && message.role !== "assistant") continue
275
280
  if (Compaction.isSummaryMessage(message)) continue
281
+ if (Agent.isInjectedMessage(message)) continue
276
282
  const sessionUpdate =
277
283
  message.role === "user" ? "user_message_chunk" : "agent_message_chunk"
278
284
  for (const part of message.content) {
@@ -312,6 +318,10 @@ export const make = Effect.fnUntraced(function* <RAgent, RModel>(
312
318
  KeyValueStore.KeyValueStore | Scope.Scope
313
319
  > {
314
320
  const kvs = yield* KeyValueStore.KeyValueStore
321
+ const { contextWindow } = yield* Compaction.CompactionConfig
322
+ const size = Number.isFinite(contextWindow)
323
+ ? Math.max(0, Math.round(contextWindow))
324
+ : 0
315
325
  // Optional: `https:` images need an HttpClient and `file:` images need a
316
326
  // FileSystem and Path. Inline (base64) images work without either. When a
317
327
  // service is missing the corresponding block is rejected, never fetched.
@@ -373,6 +383,7 @@ export const make = Effect.fnUntraced(function* <RAgent, RModel>(
373
383
  model: session.model,
374
384
  thoughtLevel: session.thoughtLevel,
375
385
  history: session.agent.history.current,
386
+ environment: session.agent.environment.current,
376
387
  }),
377
388
  )
378
389
  .pipe(
@@ -387,6 +398,9 @@ export const make = Effect.fnUntraced(function* <RAgent, RModel>(
387
398
  ) {
388
399
  const agent = yield* Scope.provide(options.makeAgent(record.cwd), scope)
389
400
  MutableRef.set(agent.history, record.history)
401
+ if (record.environment !== undefined) {
402
+ MutableRef.set(agent.environment, record.environment)
403
+ }
390
404
  const session: Session = {
391
405
  id,
392
406
  cwd: record.cwd,
@@ -654,6 +668,10 @@ export const make = Effect.fnUntraced(function* <RAgent, RModel>(
654
668
  case "Usage":
655
669
  return update(session.id, {
656
670
  sessionUpdate: "usage_update",
671
+ used: Number.isFinite(part.contextTokens)
672
+ ? Math.max(0, Math.round(part.contextTokens))
673
+ : 0,
674
+ size,
657
675
  usage: {
658
676
  inputTokens: Math.max(
659
677
  0,
@@ -769,6 +787,11 @@ export const make = Effect.fnUntraced(function* <RAgent, RModel>(
769
787
  model: modelId,
770
788
  thoughtLevel: record.value.thoughtLevel,
771
789
  history: record.value.history,
790
+ // The stored environment belongs to the stored cwd.
791
+ ...(record.value.environment !== undefined &&
792
+ (cwd === undefined || cwd === record.value.cwd)
793
+ ? { environment: record.value.environment }
794
+ : {}),
772
795
  }),
773
796
  )
774
797
  if (replay) {
@@ -40,7 +40,12 @@ type Message = {
40
40
 
41
41
  const capabilities = new AgentExecutor.Capabilities({
42
42
  toolsDts: "",
43
- agentsMd: Option.none(),
43
+ environment: new AgentExecutor.ExecutionEnvironment({
44
+ cwd: "/",
45
+ baseline: [],
46
+ seen: [],
47
+ }),
48
+ instructions: Option.none(),
44
49
  supportsSearch: false,
45
50
  tools: [],
46
51
  skills: [],
package/src/Agent.test.ts CHANGED
@@ -24,7 +24,12 @@ import * as Compaction from "./Compaction.ts"
24
24
 
25
25
  const capabilities = new AgentExecutor.Capabilities({
26
26
  toolsDts: "",
27
- agentsMd: Option.none(),
27
+ environment: new AgentExecutor.ExecutionEnvironment({
28
+ cwd: "/",
29
+ baseline: [],
30
+ seen: [],
31
+ }),
32
+ instructions: Option.none(),
28
33
  supportsSearch: false,
29
34
  tools: [],
30
35
  skills: [],
@@ -476,8 +481,11 @@ it.layer(localExecutorLayer, { excludeTestServices: true })(
476
481
  AgentExecutor.AgentExecutor.use((executor) =>
477
482
  Effect.gen(function* () {
478
483
  const summaries: Array<string> = []
484
+ const { environment } = yield* executor.capabilities
479
485
  const output = yield* executor
480
486
  .execute({
487
+ environment,
488
+ onEnvironment: () => Effect.void,
481
489
  script: `try { await ${invocation}; console.log("ACCEPTED") } catch (error) { console.log("REJECTED:", String(error)) } console.log("SCRIPT_SURVIVED")`,
482
490
  onTaskComplete: (summary) =>
483
491
  Effect.sync(() => {
package/src/Agent.ts CHANGED
@@ -19,7 +19,6 @@ import type {
19
19
  SubagentExecutor,
20
20
  SubagentResult,
21
21
  SubagentStatus,
22
- Subagents,
23
22
  TaskCompleter,
24
23
  } from "./AgentTools.ts"
25
24
  import * as Image from "./Image.ts"
@@ -69,6 +68,7 @@ import {
69
68
  ExecuteOutputCapped,
70
69
  CompactionStarted,
71
70
  CompactionEnded,
71
+ EnvironmentUpdated,
72
72
  HistoryAppended,
73
73
  HistoryReplaced,
74
74
  RetriesExhausted,
@@ -95,6 +95,15 @@ export interface Agent {
95
95
 
96
96
  readonly history: MutableRef.MutableRef<Prompt.Prompt>
97
97
 
98
+ /**
99
+ * The executor environment the next script runs in, such as its working
100
+ * directory and which AGENTS.md files and skills the history already has.
101
+ * Opaque to the agent: it is passed to the executor and replaced with what
102
+ * the executor returns. Store it next to `history` to resume a session
103
+ * where it left off.
104
+ */
105
+ readonly environment: MutableRef.MutableRef<AgentExecutor.ExecutionEnvironment>
106
+
98
107
  /**
99
108
  * Send a prompt to the agent and receive a stream of output.
100
109
  */
@@ -217,7 +226,7 @@ export const makeWith = Effect.fnUntraced(function* <
217
226
 
218
227
  const agentsMd =
219
228
  options.instructions === undefined
220
- ? Option.map(capabilities.agentsMd, renderAgentsMd)
229
+ ? capabilities.instructions
221
230
  : Option.map(options.instructions, renderInstructions)
222
231
 
223
232
  let agentCounter = 0
@@ -226,10 +235,13 @@ export const makeWith = Effect.fnUntraced(function* <
226
235
  let currentOutputAgent: number | null = null
227
236
 
228
237
  const history = MutableRef.make(Prompt.empty)
238
+ const environment = MutableRef.make(capabilities.environment)
229
239
 
230
240
  const spawn: (opts: {
231
241
  readonly agentId: number
232
242
  readonly prompt: Prompt.Prompt
243
+ /** AGENTS.md files and skills added after the prompt. */
244
+ readonly environmentUpdate?: string | undefined
233
245
  readonly system?:
234
246
  | string
235
247
  | ((options: {
@@ -238,6 +250,7 @@ export const makeWith = Effect.fnUntraced(function* <
238
250
  }) => string)
239
251
  | undefined
240
252
  readonly history: MutableRef.MutableRef<Prompt.Prompt>
253
+ readonly environment: MutableRef.MutableRef<AgentExecutor.ExecutionEnvironment>
241
254
  readonly mailbox: Mailbox
242
255
  /**
243
256
  * Whether this agent's output is streamed for display. Background agents
@@ -273,6 +286,9 @@ export const makeWith = Effect.fnUntraced(function* <
273
286
  // Images attached by `readFile` during the current script, spliced onto
274
287
  // the Prompt as a user message once the tool result has been recorded.
275
288
  const pendingImages: Array<ImageAttachment> = []
289
+ // Whether a script ran in the current response. Their environment
290
+ // update is rendered once, after all of their tool results.
291
+ let scriptsRan = false
276
292
 
277
293
  const output = yield* Queue.make<
278
294
  Output,
@@ -310,6 +326,12 @@ export const makeWith = Effect.fnUntraced(function* <
310
326
 
311
327
  // Committed now, emitted after AgentStart below.
312
328
  MutableRef.update(prompt, Prompt.concat(opts.prompt))
329
+ if (opts.environmentUpdate !== undefined) {
330
+ MutableRef.update(
331
+ prompt,
332
+ Prompt.concat(environmentUpdateMessage(opts.environmentUpdate)),
333
+ )
334
+ }
313
335
 
314
336
  const generateSystem =
315
337
  typeof opts.system === "function" ? opts.system : defaultSystem
@@ -427,6 +449,8 @@ export const makeWith = Effect.fnUntraced(function* <
427
449
  const startTurn = Effect.fnUntraced(function* (options: {
428
450
  readonly child: Child
429
451
  readonly prompt: string
452
+ /** AGENTS.md files and skills for the child's directory. */
453
+ readonly environmentUpdate?: string | undefined
430
454
  /** Shown in the start event: the task, or the follow-up message. */
431
455
  readonly label: string
432
456
  readonly background: boolean
@@ -437,8 +461,10 @@ export const makeWith = Effect.fnUntraced(function* <
437
461
  const stream = spawn({
438
462
  agentId: child.id,
439
463
  prompt: Prompt.make(options.prompt),
464
+ environmentUpdate: options.environmentUpdate,
440
465
  system: opts.system,
441
466
  history: child.history,
467
+ environment: child.environment,
442
468
  mailbox: child.mailbox,
443
469
  display,
444
470
  historyEvents: false,
@@ -509,13 +535,18 @@ export const makeWith = Effect.fnUntraced(function* <
509
535
  )
510
536
  })
511
537
 
512
- const subagents: Subagents = {
513
- delegate: Effect.fnUntraced(function* ({ prompt, background }) {
538
+ const subagents: AgentExecutor.ExecuteSubagents = {
539
+ delegate: Effect.fnUntraced(function* ({
540
+ prompt,
541
+ background,
542
+ environment,
543
+ }) {
514
544
  const agentId = agentCounter++
515
545
  const child: Child = {
516
546
  id: agentId,
517
547
  prompt,
518
548
  history: MutableRef.make(Prompt.empty),
549
+ environment: MutableRef.make(environment.environment),
519
550
  mailbox: makeMailbox(),
520
551
  turn: makeTurn(agentId, background),
521
552
  }
@@ -528,6 +559,8 @@ export const makeWith = Effect.fnUntraced(function* <
528
559
  prompt: `You have been asked using the "delegate" function to complete the following task. Try to avoid using the "delegate" function yourself unless strictly necessary:
529
560
 
530
561
  ${prompt}`,
562
+ // The update goes into the child's first prompt.
563
+ environmentUpdate: Option.getOrUndefined(environment.update),
531
564
  background,
532
565
  })
533
566
  if (background) {
@@ -662,6 +695,36 @@ ${prompt}`,
662
695
  compactionStarted = true
663
696
  maybeSend({ agentId, part: new CompactionStarted({ reason }) })
664
697
  })
698
+ // The AGENTS.md files and skills for the current directory that the
699
+ // history does not have yet. Rendered once per response, after all of
700
+ // its scripts; nothing counts as seen until `applyEnvironmentUpdate` has
701
+ // put it in the history, so an interrupted response is covered by the
702
+ // next one. With `reset`, everything is rendered again: any operation
703
+ // that rewrites the history must do this, because the rewrite drops the
704
+ // earlier updates.
705
+ const renderEnvironment = (options?: { readonly reset?: boolean }) =>
706
+ executor.renderEnvironment?.(opts.environment.current, options) ??
707
+ Effect.succeed(
708
+ new AgentExecutor.EnvironmentUpdate({
709
+ environment: opts.environment.current,
710
+ update: Option.none(),
711
+ }),
712
+ )
713
+ const applyEnvironmentUpdate = (
714
+ update: AgentExecutor.EnvironmentUpdate,
715
+ ) => {
716
+ MutableRef.set(opts.environment, update.environment)
717
+ if (Option.isNone(update.update)) return
718
+ appendHistory(environmentUpdateMessage(update.update.value))
719
+ maybeSend({
720
+ agentId,
721
+ part: new EnvironmentUpdated({ update: update.update.value }),
722
+ })
723
+ }
724
+
725
+ // The refresh is rendered before the rewrite and both are committed
726
+ // together, so an interrupt leaves the old history and the old
727
+ // environment, which still agree.
665
728
  const compactWithEvents = <E, R>(
666
729
  reason: Compaction.CompactionReason,
667
730
  compaction: Effect.Effect<
@@ -674,6 +737,15 @@ ${prompt}`,
674
737
  compactionStarted = false
675
738
  return compaction
676
739
  }).pipe(
740
+ Effect.flatMap(
741
+ Option.match({
742
+ onNone: () => Effect.succeedNone,
743
+ onSome: (result) =>
744
+ Effect.map(renderEnvironment({ reset: true }), (refresh) =>
745
+ Option.some({ ...result, refresh }),
746
+ ),
747
+ }),
748
+ ),
677
749
  Effect.onExit((exit) =>
678
750
  Effect.sync(() => {
679
751
  if (!compactionStarted) return
@@ -681,7 +753,15 @@ ${prompt}`,
681
753
  let tokensBefore: number
682
754
  let tokensAfter: number
683
755
  if (Option.isSome(result)) {
684
- replaceHistory(result.value.prompt)
756
+ // The refresh sends the kept updates again, so they are
757
+ // dropped here to appear once.
758
+ replaceHistory(
759
+ Prompt.fromMessages(
760
+ result.value.prompt.content.filter(
761
+ (message) => !isEnvironmentUpdate(message),
762
+ ),
763
+ ),
764
+ )
685
765
  lastContextTokens = undefined
686
766
  tokensBefore = result.value.tokensBefore
687
767
  tokensAfter = result.value.tokensAfter
@@ -694,6 +774,9 @@ ${prompt}`,
694
774
  agentId,
695
775
  part: new CompactionEnded({ reason, tokensBefore, tokensAfter }),
696
776
  })
777
+ if (Option.isSome(result)) {
778
+ applyEnvironmentUpdate(result.value.refresh)
779
+ }
697
780
  }),
698
781
  ),
699
782
  )
@@ -703,9 +786,15 @@ ${prompt}`,
703
786
  yield* toolLatchAcquire
704
787
  maybeSend({ agentId, part: new ScriptEnd(), release: true })
705
788
  const normalizedScript = stripWrappingCodeFence(script)
789
+ scriptsRan = true
706
790
  const output = yield* pipe(
707
791
  executor.execute({
708
792
  script: normalizedScript,
793
+ environment: opts.environment.current,
794
+ onEnvironment: (environment) =>
795
+ Effect.sync(() => {
796
+ MutableRef.set(opts.environment, environment)
797
+ }),
709
798
  subagents,
710
799
  onTaskComplete,
711
800
  onImage: (image) =>
@@ -745,6 +834,12 @@ ${prompt}`,
745
834
  model: yield* Model.ModelName,
746
835
  }),
747
836
  )
837
+ if (opts.environmentUpdate !== undefined) {
838
+ maybeSend({
839
+ agentId,
840
+ part: new EnvironmentUpdated({ update: opts.environmentUpdate }),
841
+ })
842
+ }
748
843
  if (opts.historyEvents) {
749
844
  const messages = opts.prompt.content.filter(
750
845
  (message) => message.role !== "system",
@@ -1028,6 +1123,11 @@ ${Compaction.capOutput(turn.output ?? "").output}
1028
1123
  appendHistory(Prompt.fromMessages([Image.userMessage(pendingImages)]))
1029
1124
  pendingImages.length = 0
1030
1125
  }
1126
+ // After the tool results too, and before any steering messages.
1127
+ if (scriptsRan) {
1128
+ scriptsRan = false
1129
+ applyEnvironmentUpdate(yield* renderEnvironment())
1130
+ }
1031
1131
  if (conversationMode && !hadToolCall && mailbox.messages.size === 0) {
1032
1132
  // The run is not over while children are running or their results
1033
1133
  // have not been seen yet.
@@ -1057,12 +1157,14 @@ ${Compaction.capOutput(turn.output ?? "").output}
1057
1157
  return Agent.of({
1058
1158
  [TypeId]: TypeId,
1059
1159
  history,
1160
+ environment,
1060
1161
  send: (options) =>
1061
1162
  spawn({
1062
1163
  agentId: agentCounter++,
1063
1164
  prompt: Prompt.make(options.prompt),
1064
1165
  system: options.system,
1065
1166
  history,
1167
+ environment,
1066
1168
  mailbox: rootMailbox,
1067
1169
  display: true,
1068
1170
  historyEvents: true,
@@ -1112,6 +1214,8 @@ interface Child {
1112
1214
  readonly prompt: string
1113
1215
  /** Kept for the whole run so `messageAgent` can resume the agent. */
1114
1216
  readonly history: MutableRef.MutableRef<Prompt.Prompt>
1217
+ /** Starts as a copy of the parent's at the moment it was delegated. */
1218
+ readonly environment: MutableRef.MutableRef<AgentExecutor.ExecutionEnvironment>
1115
1219
  readonly mailbox: Mailbox
1116
1220
  /** The latest turn. Replaced when `messageAgent` resumes the agent. */
1117
1221
  turn: Turn
@@ -1153,16 +1257,36 @@ const retryPolicy = Schedule.min([
1153
1257
  Schedule.spaced(5000),
1154
1258
  ]).pipe(Schedule.jittered)
1155
1259
 
1156
- const renderAgentsMd = (content: string) => `# AGENTS.md
1260
+ const environmentUpdateOpen = "<environment-update>"
1157
1261
 
1158
- The following instructions are from ./AGENTS.md in the current directory.
1159
- You do not need to read this file again.
1262
+ const environmentUpdateMessage = (text: string) =>
1263
+ Prompt.make([
1264
+ {
1265
+ role: "user",
1266
+ content: `${environmentUpdateOpen}\n${text}\n</environment-update>`,
1267
+ },
1268
+ ])
1160
1269
 
1161
- **ALWAYS follow these instructions when completing tasks**:
1270
+ // A user message that is one text part starting with `prefix`.
1271
+ const startsWith = (message: Prompt.Message, prefix: string): boolean =>
1272
+ message.role === "user" &&
1273
+ message.content.length === 1 &&
1274
+ message.content[0]!.type === "text" &&
1275
+ message.content[0]!.text.trimStart().startsWith(prefix)
1162
1276
 
1163
- <!-- AGENTS.md start -->
1164
- ${content}
1165
- <!-- AGENTS.md end -->`
1277
+ const isEnvironmentUpdate = (message: Prompt.Message): boolean =>
1278
+ startsWith(message, environmentUpdateOpen)
1279
+
1280
+ /**
1281
+ * Whether a user message was added by the agent rather than typed: an
1282
+ * `<environment-update>` or a `<subagent>` result. Surfaces that replay
1283
+ * history (ACP) skip them.
1284
+ *
1285
+ * @since 1.0.0
1286
+ * @category Models
1287
+ */
1288
+ export const isInjectedMessage = (message: Prompt.Message): boolean =>
1289
+ isEnvironmentUpdate(message) || startsWith(message, "<subagent ")
1166
1290
 
1167
1291
  const renderInstructions = (content: string) => `# Project instructions
1168
1292
 
@@ -1266,6 +1390,7 @@ const [files, content] = await Promise.all([
1266
1390
  path: "package.json",
1267
1391
  startLine: 1,
1268
1392
  endLine: 10,
1393
+ lineNumbers: false,
1269
1394
  })
1270
1395
  ])
1271
1396
  console.log("files:", files)