clanka 0.17.3 → 0.18.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 (91) hide show
  1. package/README.md +24 -0
  2. package/dist/Acp.d.ts.map +1 -1
  3. package/dist/Acp.js +5 -0
  4. package/dist/Acp.js.map +1 -1
  5. package/dist/Agent.d.ts +11 -0
  6. package/dist/Agent.d.ts.map +1 -1
  7. package/dist/Agent.js +35 -15
  8. package/dist/Agent.js.map +1 -1
  9. package/dist/Agent.test.js +23 -0
  10. package/dist/Agent.test.js.map +1 -1
  11. package/dist/AgentExecutor.js +15 -2
  12. package/dist/AgentExecutor.js.map +1 -1
  13. package/dist/AgentExecutor.test.js +16 -0
  14. package/dist/AgentExecutor.test.js.map +1 -1
  15. package/dist/AgentOutput.d.ts +23 -4
  16. package/dist/AgentOutput.d.ts.map +1 -1
  17. package/dist/AgentOutput.js +19 -0
  18. package/dist/AgentOutput.js.map +1 -1
  19. package/dist/ClaudeAgent.d.ts.map +1 -1
  20. package/dist/ClaudeAgent.js +37 -4
  21. package/dist/ClaudeAgent.js.map +1 -1
  22. package/dist/ClaudeAgent.test.js +82 -0
  23. package/dist/ClaudeAgent.test.js.map +1 -1
  24. package/dist/Codex.js +9 -5
  25. package/dist/Codex.js.map +1 -1
  26. package/dist/Codex.test.js +26 -7
  27. package/dist/Codex.test.js.map +1 -1
  28. package/dist/Compaction.d.ts +41 -6
  29. package/dist/Compaction.d.ts.map +1 -1
  30. package/dist/Compaction.js +52 -11
  31. package/dist/Compaction.js.map +1 -1
  32. package/dist/Compaction.test.js +5 -4
  33. package/dist/Compaction.test.js.map +1 -1
  34. package/dist/CompactionTransport.test.js +11 -0
  35. package/dist/CompactionTransport.test.js.map +1 -1
  36. package/dist/Copilot.d.ts.map +1 -1
  37. package/dist/Copilot.js +3 -6
  38. package/dist/Copilot.js.map +1 -1
  39. package/dist/ModelLayer.d.ts +35 -6
  40. package/dist/ModelLayer.d.ts.map +1 -1
  41. package/dist/ModelLayer.js +30 -18
  42. package/dist/ModelLayer.js.map +1 -1
  43. package/dist/ModelLayer.test.js +11 -3
  44. package/dist/ModelLayer.test.js.map +1 -1
  45. package/dist/OutputFormatter.d.ts.map +1 -1
  46. package/dist/OutputFormatter.js +3 -0
  47. package/dist/OutputFormatter.js.map +1 -1
  48. package/dist/Xai.d.ts.map +1 -1
  49. package/dist/Xai.js +4 -12
  50. package/dist/Xai.js.map +1 -1
  51. package/dist/bin/{Effect-DNYYQ84C.mjs → Effect-5XYMLOiB.mjs} +31 -30
  52. package/dist/bin/Effect-5XYMLOiB.mjs.map +1 -0
  53. package/dist/bin/{Latch-BSlIwuxI.mjs → Latch-BnrpWMd1.mjs} +2 -2
  54. package/dist/bin/{Latch-BSlIwuxI.mjs.map → Latch-BnrpWMd1.mjs.map} +1 -1
  55. package/dist/bin/{McpClient-C7ctqJWo.mjs → McpClient-DoPNaNzW.mjs} +3 -3
  56. package/dist/bin/{McpClient-C7ctqJWo.mjs.map → McpClient-DoPNaNzW.mjs.map} +1 -1
  57. package/dist/bin/{OutputFormatter-DXej05JW.mjs → OutputFormatter-Dqxyk2qD.mjs} +4 -3
  58. package/dist/bin/{OutputFormatter-DXej05JW.mjs.map → OutputFormatter-Dqxyk2qD.mjs.map} +1 -1
  59. package/dist/bin/{Schema-CSQN_Zso.mjs → Schema-Box_9VZG.mjs} +6 -3
  60. package/dist/bin/{Schema-CSQN_Zso.mjs.map → Schema-Box_9VZG.mjs.map} +1 -1
  61. package/dist/bin/{SemanticSearch-BiwCnpKX.mjs → SemanticSearch-CH125AHH.mjs} +4 -4
  62. package/dist/bin/{SemanticSearch-BiwCnpKX.mjs.map → SemanticSearch-CH125AHH.mjs.map} +1 -1
  63. package/dist/bin/{Stream-Dwvj9X5X.mjs → Stream-C51usiew.mjs} +3 -3
  64. package/dist/bin/{Stream-Dwvj9X5X.mjs.map → Stream-C51usiew.mjs.map} +1 -1
  65. package/dist/bin/cli.mjs +321 -225
  66. package/dist/bin/cli.mjs.map +1 -1
  67. package/dist/bin/{upgrade-BSNjCnra.mjs → upgrade-HMRGSqq8.mjs} +4 -4
  68. package/dist/bin/{upgrade-BSNjCnra.mjs.map → upgrade-HMRGSqq8.mjs.map} +1 -1
  69. package/dist/cli.js +45 -5
  70. package/dist/cli.js.map +1 -1
  71. package/package.json +1 -1
  72. package/src/Acp.ts +7 -0
  73. package/src/Agent.test.ts +27 -0
  74. package/src/Agent.ts +49 -15
  75. package/src/AgentExecutor.test.ts +23 -1
  76. package/src/AgentExecutor.ts +16 -2
  77. package/src/AgentOutput.ts +23 -0
  78. package/src/ClaudeAgent.test.ts +113 -0
  79. package/src/ClaudeAgent.ts +51 -4
  80. package/src/Codex.test.ts +37 -9
  81. package/src/Codex.ts +25 -20
  82. package/src/Compaction.test.ts +18 -15
  83. package/src/Compaction.ts +89 -20
  84. package/src/CompactionTransport.test.ts +36 -0
  85. package/src/Copilot.ts +5 -6
  86. package/src/ModelLayer.test.ts +17 -2
  87. package/src/ModelLayer.ts +68 -22
  88. package/src/OutputFormatter.ts +3 -0
  89. package/src/Xai.ts +8 -12
  90. package/src/cli.ts +97 -5
  91. package/dist/bin/Effect-DNYYQ84C.mjs.map +0 -1
@@ -214,6 +214,27 @@ export class CompactionEnded extends Schema.TaggedClass<CompactionEnded>()(
214
214
  },
215
215
  ) {}
216
216
 
217
+ /**
218
+ * Emitted when the provider could not continue its live session and was sent
219
+ * the whole history again, so the provider cache missed on it.
220
+ *
221
+ * `reason` is reported by the provider: `history-changed` (an earlier message
222
+ * was rewritten, e.g. by compaction), `step-abandoned` (the last
223
+ * step did not finish: a retry, timeout or interrupt) or `tools-changed`.
224
+ * `contextTokens` and `cacheWrite` are the usage of the resent request.
225
+ *
226
+ * @since 1.0.0
227
+ * @category Output
228
+ */
229
+ export class SessionRestarted extends Schema.TaggedClass<SessionRestarted>()(
230
+ "SessionRestarted",
231
+ {
232
+ reason: Schema.String,
233
+ contextTokens: Schema.Number,
234
+ cacheWrite: Schema.Number,
235
+ },
236
+ ) {}
237
+
217
238
  /**
218
239
  * Emitted when AGENTS.md files or skills the model has not seen yet are
219
240
  * added to the history, after a directory change or a compaction. `update`
@@ -242,6 +263,7 @@ export type ContentPart =
242
263
  | ExecuteOutputCapped
243
264
  | CompactionStarted
244
265
  | CompactionEnded
266
+ | SessionRestarted
245
267
  | EnvironmentUpdated
246
268
 
247
269
  export const ContentPart = Schema.Union([
@@ -257,6 +279,7 @@ export const ContentPart = Schema.Union([
257
279
  ExecuteOutputCapped,
258
280
  CompactionStarted,
259
281
  CompactionEnded,
282
+ SessionRestarted,
260
283
  EnvironmentUpdated,
261
284
  ])
262
285
 
@@ -12,14 +12,18 @@ import * as Effect from "effect/Effect"
12
12
  import * as Exit from "effect/Exit"
13
13
  import * as Fiber from "effect/Fiber"
14
14
  import * as Layer from "effect/Layer"
15
+ import * as Option from "effect/Option"
15
16
  import * as Base64 from "effect/encoding/Base64"
16
17
  import * as Schema from "effect/Schema"
17
18
  import * as Scope from "effect/Scope"
18
19
  import * as Stream from "effect/Stream"
19
20
  import * as LanguageModel from "effect/ai/LanguageModel"
20
21
  import * as Prompt from "effect/ai/Prompt"
22
+ import type * as Response from "effect/ai/Response"
21
23
  import * as Tool from "effect/ai/Tool"
22
24
  import * as Toolkit from "effect/ai/Toolkit"
25
+ import * as Agent from "./Agent.ts"
26
+ import * as AgentExecutor from "./AgentExecutor.ts"
23
27
  import * as ClaudeAgent from "./ClaudeAgent.ts"
24
28
  import { tinyPng } from "./fixtures/TestImages.ts"
25
29
 
@@ -492,6 +496,11 @@ const runSteps = Effect.fnUntraced(function* (
492
496
  }).pipe(Effect.provide(modelWith(fake)))
493
497
  })
494
498
 
499
+ // How a step's finish part says Claude Code re-read the history.
500
+ const historyResent = (parts: ReadonlyArray<Response.StreamPart<any>>) =>
501
+ (parts.find((part) => part.type === "finish")?.metadata.clanka as any)
502
+ ?.historyResent
503
+
495
504
  describe("ClaudeAgent.model", () => {
496
505
  it.effect("hands each parked call the result of its own tool use", () =>
497
506
  Effect.gen(function* () {
@@ -683,6 +692,110 @@ describe("ClaudeAgent.model", () => {
683
692
  }),
684
693
  )
685
694
 
695
+ it.effect("tells the caller why it started the session over", () =>
696
+ Effect.gen(function* () {
697
+ const fake = fakeClaude(async function* (session) {
698
+ await session.input.next()
699
+ yield* finalStep
700
+ })
701
+ const first = Prompt.fromMessages([system, user("go")])
702
+ yield* Effect.gen(function* () {
703
+ const ai = yield* LanguageModel.LanguageModel
704
+ const step = (prompt: Prompt.Prompt) =>
705
+ ai.streamText({ prompt, toolkit: Execute }).pipe(Stream.runCollect)
706
+ assert.isUndefined(historyResent(yield* step(first)))
707
+ const edited = Prompt.fromMessages([
708
+ ...first.content,
709
+ Prompt.makeMessage("assistant", {
710
+ content: [Prompt.makePart("text", { text: "Edited." })],
711
+ }),
712
+ user("Repeat your answer"),
713
+ ])
714
+ assert.deepStrictEqual(historyResent(yield* step(edited)), {
715
+ reason: "history-changed",
716
+ })
717
+ }).pipe(Effect.provide(modelWith(fake)))
718
+ assert.lengthOf(fake.sessions, 2)
719
+ }),
720
+ )
721
+
722
+ it.effect("keeps the session when the agent is steered mid-step", () =>
723
+ Effect.gen(function* () {
724
+ const steered = Promise.withResolvers<void>()
725
+ let steering = ""
726
+ const fake = fakeClaude(async function* (session) {
727
+ await session.input.next()
728
+ // A restarted session answers straight away.
729
+ if (session !== fake.sessions[0]) return yield* finalStep
730
+ yield* replying
731
+ await steered.promise
732
+ yield event({ type: "content_block_stop", index: 0 })
733
+ yield assistant({ type: "text", text: "Working" })
734
+ yield* executeStep([["toolu_a", "a"]]).slice(1)
735
+ await callExecute(session, [["toolu_a", "a"]])
736
+ steering = JSON.stringify((await session.input.next()).value)
737
+ yield* finalStep
738
+ })
739
+ const executor = AgentExecutor.AgentExecutor.of({
740
+ capabilities: Effect.succeed(
741
+ new AgentExecutor.Capabilities({
742
+ toolsDts: "",
743
+ environment: new AgentExecutor.ExecutionEnvironment({
744
+ cwd: "/",
745
+ baseline: [],
746
+ seen: [],
747
+ }),
748
+ instructions: Option.none(),
749
+ supportsSearch: false,
750
+ tools: [],
751
+ skills: [],
752
+ }),
753
+ ),
754
+ execute: () => Stream.succeed("ran a"),
755
+ executeUnsafe: () => Effect.die("executeUnsafe not implemented"),
756
+ })
757
+ const summary = yield* Effect.gen(function* () {
758
+ const agent = yield* Agent.make
759
+ let sentSteering = false
760
+ return yield* agent.send({ prompt: "go" }).pipe(
761
+ Effect.flatMap((stream) =>
762
+ stream.pipe(
763
+ Stream.runForEach((output) =>
764
+ Effect.gen(function* () {
765
+ if (output._tag !== "ReasoningDelta" || sentSteering) return
766
+ sentSteering = true
767
+ yield* Effect.forkChild(agent.steer("Also check the docs"), {
768
+ startImmediately: true,
769
+ })
770
+ steered.resolve()
771
+ }),
772
+ ),
773
+ Effect.as(""),
774
+ Effect.catchTag("AgentFinished", (finished) =>
775
+ Effect.succeed(finished.summary),
776
+ ),
777
+ ),
778
+ ),
779
+ )
780
+ }).pipe(
781
+ Effect.provideService(AgentExecutor.AgentExecutor, executor),
782
+ Effect.provide(
783
+ Layer.merge(
784
+ ClaudeAgent.model("claude-opus-5-5", {
785
+ executable: "/fake/claude",
786
+ query: fake.query,
787
+ }),
788
+ Agent.ConversationMode.layer(true),
789
+ ),
790
+ ),
791
+ Effect.scoped,
792
+ )
793
+ assert.strictEqual(summary, "Done.")
794
+ assert.lengthOf(fake.sessions, 1)
795
+ assert.include(steering, "Also check the docs")
796
+ }),
797
+ )
798
+
686
799
  it.effect("closes Claude Code when a step is cut short", () =>
687
800
  Effect.gen(function* () {
688
801
  const fake = fakeClaude(async function* (session) {
@@ -696,6 +696,11 @@ interface Session {
696
696
  outcome: Outcome | undefined
697
697
  }
698
698
 
699
+ // The tools a session was started with; a step with other tools cannot
700
+ // continue it.
701
+ const toolNames = (provider: LanguageModel.ProviderOptions) =>
702
+ provider.tools.map((tool) => tool.name).join(",")
703
+
699
704
  // Ends `messages` before closing the scope, which interrupts the fiber that
700
705
  // would end it, so a step still reading the session fails instead of waiting.
701
706
  const closeSession = (session: Session) =>
@@ -759,7 +764,7 @@ const startSession = Effect.fnUntraced(function* (
759
764
  bridge,
760
765
  messages,
761
766
  scope,
762
- toolNames: provider.tools.map((tool) => tool.name).join(","),
767
+ toolNames: toolNames(provider),
763
768
  seen: provider.prompt.content,
764
769
  outcome: undefined,
765
770
  }
@@ -824,7 +829,7 @@ const continuation = (
824
829
  const response = messages[seen.length]
825
830
  if (
826
831
  outcome === undefined ||
827
- session.toolNames !== provider.tools.map((tool) => tool.name).join(",") ||
832
+ session.toolNames !== toolNames(provider) ||
828
833
  response?.role !== "assistant" ||
829
834
  !seen.every((message, i) => messages[i] === message) ||
830
835
  !isDeepStrictEqual(appended(response), emitted(outcome))
@@ -854,6 +859,36 @@ const continuation = (
854
859
  return { ids, results, users }
855
860
  }
856
861
 
862
+ // Why a step could not continue the live session. A step that did not
863
+ // finish closes its session, so no session also means an abandoned step.
864
+ const restartReason = (
865
+ session: Session | undefined,
866
+ provider: LanguageModel.ProviderOptions,
867
+ ) =>
868
+ session === undefined || session.outcome === undefined
869
+ ? "step-abandoned"
870
+ : session.toolNames !== toolNames(provider)
871
+ ? "tools-changed"
872
+ : "history-changed"
873
+
874
+ // Marks the finish part of the first step of a restarted session, so the
875
+ // Agent can report what the restart cost.
876
+ const reportRestart = (
877
+ step: Stream.Stream<Response.StreamPartEncoded, AiError.AiError>,
878
+ reason: string,
879
+ ) =>
880
+ Stream.map(step, (part) =>
881
+ part.type === "finish"
882
+ ? {
883
+ ...part,
884
+ metadata: {
885
+ ...part.metadata,
886
+ clanka: { historyResent: { reason } },
887
+ },
888
+ }
889
+ : part,
890
+ )
891
+
857
892
  const continueSession = (
858
893
  session: Session,
859
894
  plan: NonNullable<ReturnType<typeof continuation>>,
@@ -1090,6 +1125,8 @@ const layerLanguageModel = (
1090
1125
  // Set while a step is read. Another step would close the session under
1091
1126
  // it, so it fails instead.
1092
1127
  let reading = false
1128
+ // Whether a session has run, so a new one is a restart.
1129
+ let started = false
1093
1130
 
1094
1131
  const step = (provider: LanguageModel.ProviderOptions) =>
1095
1132
  Stream.suspend(() => {
@@ -1113,9 +1150,14 @@ const layerLanguageModel = (
1113
1150
  current.outcome = undefined
1114
1151
  return readStep(current, closeCurrent)
1115
1152
  }
1153
+ const reason = started
1154
+ ? restartReason(current, provider)
1155
+ : undefined
1116
1156
  yield* closeCurrent
1117
1157
  current = yield* startSession(model, options, provider, true)
1118
- return readStep(current, closeCurrent)
1158
+ started = true
1159
+ const read = readStep(current, closeCurrent)
1160
+ return reason === undefined ? read : reportRestart(read, reason)
1119
1161
  }),
1120
1162
  ).pipe(
1121
1163
  Stream.ensuring(
@@ -1196,6 +1238,11 @@ export const model = (
1196
1238
  // The system prompt stays in the Prompt, where `queryOptions` reads
1197
1239
  // it. No Compaction.SummarizerTransform: Claude Code takes no
1198
1240
  // per-request output cap.
1199
- AgentModelConfig.layer({ supportsImages: options?.supportsImages }),
1241
+ // A step cut short closes the session, so steering waits for the step
1242
+ // to end and the session continues.
1243
+ AgentModelConfig.layer({
1244
+ supportsImages: options?.supportsImages,
1245
+ cutStreamOnSteering: false,
1246
+ }),
1200
1247
  ),
1201
1248
  )
package/src/Codex.test.ts CHANGED
@@ -9,8 +9,9 @@ import type * as HttpClientRequest from "effect/http/HttpClientRequest"
9
9
  import * as HttpClientResponse from "effect/http/HttpClientResponse"
10
10
  import * as Codex from "./Codex.ts"
11
11
 
12
- const requestBody = Effect.fnUntraced(function* (
12
+ const requestBodies = Effect.fnUntraced(function* (
13
13
  options: Codex.ModelOptions | undefined,
14
+ calls = 1,
14
15
  ) {
15
16
  const requests: Array<HttpClientRequest.HttpClientRequest> = []
16
17
  const client = HttpClient.make((request) =>
@@ -24,7 +25,11 @@ const requestBody = Effect.fnUntraced(function* (
24
25
  )
25
26
  yield* Effect.gen(function* () {
26
27
  const ai = yield* LanguageModel.LanguageModel
27
- yield* ai.streamText({ prompt: "hello" }).pipe(Stream.runDrain, Effect.exit)
28
+ for (let i = 0; i < calls; i++) {
29
+ yield* ai
30
+ .streamText({ prompt: "hello" })
31
+ .pipe(Stream.runDrain, Effect.exit)
32
+ }
28
33
  }).pipe(
29
34
  Effect.provide(
30
35
  Codex.model("gpt-6-astra", options).pipe(
@@ -33,15 +38,20 @@ const requestBody = Effect.fnUntraced(function* (
33
38
  ),
34
39
  ),
35
40
  )
36
- assert.lengthOf(requests, 1)
37
- const body = requests[0]!.body
38
- if (body._tag !== "Uint8Array") throw new Error("Expected JSON body")
39
- return JSON.parse(new TextDecoder().decode(body.body)) as Record<
40
- string,
41
- unknown
42
- >
41
+ assert.lengthOf(requests, calls)
42
+ return requests.map((request) => {
43
+ const body = request.body
44
+ if (body._tag !== "Uint8Array") throw new Error("Expected JSON body")
45
+ return JSON.parse(new TextDecoder().decode(body.body)) as Record<
46
+ string,
47
+ unknown
48
+ >
49
+ })
43
50
  })
44
51
 
52
+ const requestBody = (options: Codex.ModelOptions | undefined) =>
53
+ Effect.map(requestBodies(options), (bodies) => bodies[0]!)
54
+
45
55
  describe("Codex.model", () => {
46
56
  it.effect("sends medium reasoning with auto summaries by default", () =>
47
57
  Effect.gen(function* () {
@@ -57,4 +67,22 @@ describe("Codex.model", () => {
57
67
  assert.isFalse("reasoning" in (yield* requestBody({ reasoning: null })))
58
68
  }),
59
69
  )
70
+
71
+ it.effect("sends one prompt cache key for every request of a model", () =>
72
+ Effect.gen(function* () {
73
+ const [first, second] = yield* requestBodies(undefined, 2)
74
+ assert.isString(first!.prompt_cache_key)
75
+ assert.isNotEmpty(first!.prompt_cache_key)
76
+ assert.strictEqual(second!.prompt_cache_key, first!.prompt_cache_key)
77
+ const [other] = yield* requestBodies(undefined)
78
+ assert.notStrictEqual(other!.prompt_cache_key, first!.prompt_cache_key)
79
+ }),
80
+ )
81
+
82
+ it.effect("keeps a prompt cache key the caller sets", () =>
83
+ Effect.gen(function* () {
84
+ const body = yield* requestBody({ prompt_cache_key: "session-1" })
85
+ assert.strictEqual(body.prompt_cache_key, "session-1")
86
+ }),
87
+ )
60
88
  })
package/src/Codex.ts CHANGED
@@ -73,32 +73,37 @@ const layerModel = (
73
73
  model: (string & {}) | OpenAiLanguageModel.Model,
74
74
  options?: ModelOptions | undefined,
75
75
  ) =>
76
- OpenAiLanguageModel.layer({
77
- model,
78
- config: {
79
- ...Struct.omit(options ?? {}, [
80
- "reasoning",
81
- "systemPromptTransform",
82
- "supportsImages",
83
- ]),
84
- store: false,
85
- reasoning:
86
- options?.reasoning === null
87
- ? undefined
88
- : {
89
- effort: "medium",
90
- summary: "auto",
91
- ...(options?.reasoning as any),
92
- },
93
- },
94
- }).pipe(
76
+ // One prompt cache key per model layer, so the requests of a session, and
77
+ // of the sub-agents sharing its system prompt, are routed to the same
78
+ // cache. A key in `options` wins.
79
+ Layer.suspend(() =>
80
+ OpenAiLanguageModel.layer({
81
+ model,
82
+ config: {
83
+ ...Struct.omit(options ?? {}, [
84
+ "reasoning",
85
+ ...AgentModelConfig.optionKeys,
86
+ ]),
87
+ prompt_cache_key: options?.prompt_cache_key ?? crypto.randomUUID(),
88
+ store: false,
89
+ reasoning:
90
+ options?.reasoning === null
91
+ ? undefined
92
+ : {
93
+ effort: "medium",
94
+ summary: "auto",
95
+ ...(options?.reasoning as any),
96
+ },
97
+ },
98
+ }),
99
+ ).pipe(
95
100
  Layer.merge(
96
101
  AgentModelConfig.layer({
102
+ ...Struct.pick(options ?? {}, AgentModelConfig.optionKeys),
97
103
  systemPromptTransform: (system, effect) =>
98
104
  OpenAiLanguageModel.withConfigOverride(effect, {
99
105
  instructions: system,
100
106
  }),
101
- supportsImages: options?.supportsImages,
102
107
  }),
103
108
  // No Compaction.SummarizerTransform: Codex rejects max_output_tokens,
104
109
  // so compaction summaries have no configured output-token cap.
@@ -184,17 +184,20 @@ describe("Compaction.estimateTokens", () => {
184
184
  })
185
185
 
186
186
  describe("Compaction.CompactionConfig", () => {
187
- it.effect("defaults to a 236k window with a 16k reserve", () =>
188
- Effect.gen(function* () {
189
- const config = yield* Compaction.CompactionConfig
190
- assert.deepStrictEqual(Compaction.defaultConfig, {
191
- enabled: true,
192
- contextWindow: 236_000,
193
- reserveTokens: 16_000,
194
- keepRecentTokens: 20_000,
195
- })
196
- assert.deepStrictEqual(config, Compaction.defaultConfig)
197
- }),
187
+ it.effect(
188
+ "defaults to a 236k window, a 16k reserve and a 160k threshold",
189
+ () =>
190
+ Effect.gen(function* () {
191
+ const config = yield* Compaction.CompactionConfig
192
+ assert.deepStrictEqual(Compaction.defaultConfig, {
193
+ enabled: true,
194
+ contextWindow: 236_000,
195
+ reserveTokens: 16_000,
196
+ thresholdTokens: 160_000,
197
+ keepRecentTokens: 20_000,
198
+ })
199
+ assert.deepStrictEqual(config, Compaction.defaultConfig)
200
+ }),
198
201
  )
199
202
  })
200
203
 
@@ -207,9 +210,9 @@ describe("Compaction.shouldCompact", () => {
207
210
  const small = Prompt.fromMessages([user("hi")])
208
211
 
209
212
  for (const [tokens, expected] of [
210
- [219_999, false],
211
- [220_000, false],
212
- [220_001, true],
213
+ [159_999, false],
214
+ [160_000, false],
215
+ [160_001, true],
213
216
  ] as const) {
214
217
  it(`returns ${expected} with default config and ${tokens} reported tokens`, () => {
215
218
  assert.strictEqual(
@@ -823,4 +826,4 @@ describe("Compaction.rewrite", () => {
823
826
  )
824
827
  }),
825
828
  )
826
- })
829
+ })
package/src/Compaction.ts CHANGED
@@ -7,8 +7,8 @@
7
7
  * (`capOutput`). It runs on every surface and is not affected by the
8
8
  * compaction kill switch.
9
9
  * 2. Auto-compaction of the live Prompt (`compactIfNeeded` before a model
10
- * call, `compactAfterOverflow` after a context-length error). Both rewrite
11
- * the Prompt to `system + <compaction-summary> user message + kept tail`.
10
+ * call, `compact` after a context-length error). Both rewrite the Prompt
11
+ * to `system + <compaction-summary> user message + kept tail`.
12
12
  *
13
13
  * @since 1.0.0
14
14
  */
@@ -21,6 +21,7 @@ import * as Predicate from "effect/Predicate"
21
21
  import * as Stream from "effect/Stream"
22
22
  import * as AiError from "effect/ai/AiError"
23
23
  import * as LanguageModel from "effect/ai/LanguageModel"
24
+ import type * as Model from "effect/ai/Model"
24
25
  import * as Prompt from "effect/ai/Prompt"
25
26
  import type * as AgentOutput from "./AgentOutput.ts"
26
27
  import * as Image from "./Image.ts"
@@ -35,9 +36,11 @@ import * as Image from "./Image.ts"
35
36
  * - `enabled`: kill switch for both compact paths. Does **not** disable the
36
37
  * `execute` output cap.
37
38
  * - `contextWindow`: assumed model context window in tokens.
38
- * - `reserveTokens`: headroom kept free below `contextWindow`. Compaction
39
- * triggers once the last reported `contextTokens` (or the estimate) exceeds
40
- * `contextWindow - reserveTokens`.
39
+ * - `reserveTokens`: headroom kept free below `contextWindow`.
40
+ * - `thresholdTokens`: compaction triggers once the last reported
41
+ * `contextTokens` (or the estimate) exceeds this many tokens, or
42
+ * `contextWindow - reserveTokens` when that is lower. Compacting well below
43
+ * the context window keeps every turn's input smaller.
41
44
  * - `keepRecentTokens`: size of the recent tail preserved verbatim after a
42
45
  * compaction.
43
46
  *
@@ -48,6 +51,7 @@ export interface CompactionConfigService {
48
51
  readonly enabled: boolean
49
52
  readonly contextWindow: number
50
53
  readonly reserveTokens: number
54
+ readonly thresholdTokens: number
51
55
  readonly keepRecentTokens: number
52
56
  }
53
57
 
@@ -59,6 +63,7 @@ export const defaultConfig: CompactionConfigService = {
59
63
  enabled: true,
60
64
  contextWindow: 236_000,
61
65
  reserveTokens: 16_000,
66
+ thresholdTokens: 160_000,
62
67
  keepRecentTokens: 20_000,
63
68
  }
64
69
 
@@ -89,6 +94,48 @@ export class SummarizerTransform extends Context.Reference<
89
94
  defaultValue: () => identity,
90
95
  }) {}
91
96
 
97
+ /**
98
+ * The model the summarizer runs on. Without it, the summarizer runs on the
99
+ * agent's own model.
100
+ *
101
+ * The layer is built for each summarizer call, so a stateful model such as
102
+ * Claude Agent never shares its session with an agent. It replaces the
103
+ * agent's `SummarizerTransform` with its own, or with the identity when it
104
+ * has none.
105
+ *
106
+ * @since 1.0.0
107
+ * @category Configuration
108
+ */
109
+ export class SummarizerModel extends Context.Service<
110
+ SummarizerModel,
111
+ Layer.Layer<
112
+ LanguageModel.LanguageModel | Model.ProviderName | Model.ModelName
113
+ >
114
+ >()("clanka/Compaction/SummarizerModel") {}
115
+
116
+ /**
117
+ * Run the summarizer on `layer` instead of the agent's model.
118
+ *
119
+ * @since 1.0.0
120
+ * @category Configuration
121
+ */
122
+ export const layerSummarizerModel = <E, R>(
123
+ layer: Layer.Layer<
124
+ LanguageModel.LanguageModel | Model.ProviderName | Model.ModelName,
125
+ E,
126
+ R
127
+ >,
128
+ ): Layer.Layer<SummarizerModel, never, R> =>
129
+ Layer.effect(
130
+ SummarizerModel,
131
+ Effect.gen(function* () {
132
+ const services = yield* Effect.context<R>()
133
+ return Layer.fresh(Layer.orDie(layer)).pipe(
134
+ Layer.provide(Layer.succeedContext(services)),
135
+ )
136
+ }),
137
+ )
138
+
92
139
  // =============================================================================
93
140
  // Constants
94
141
  // =============================================================================
@@ -253,6 +300,16 @@ export const estimateTokens = (prompt: Prompt.Prompt): number => {
253
300
  export const estimateMessageTokens = (message: Prompt.Message): number =>
254
301
  Math.ceil(estimateMessageChars(message) / 4)
255
302
 
303
+ /**
304
+ * The token count above which the threshold trigger fires: `thresholdTokens`,
305
+ * or `contextWindow - reserveTokens` when that is lower.
306
+ *
307
+ * @since 1.0.0
308
+ * @category Tokens
309
+ */
310
+ export const compactionThreshold = (config: CompactionConfigService): number =>
311
+ Math.min(config.thresholdTokens, config.contextWindow - config.reserveTokens)
312
+
256
313
  /**
257
314
  * Whether the threshold trigger fires for the next model call.
258
315
  *
@@ -272,7 +329,7 @@ export const shouldCompact = (options: {
272
329
  }): boolean => {
273
330
  if (!options.config.enabled) return false
274
331
  const tokens = options.contextTokens ?? estimateTokens(options.prompt)
275
- return tokens > options.config.contextWindow - options.config.reserveTokens
332
+ return tokens > compactionThreshold(options.config)
276
333
  }
277
334
 
278
335
  // =============================================================================
@@ -727,7 +784,8 @@ export interface CompactionResult {
727
784
  * Returns `None` without calling the model when compaction is disabled or
728
785
  * when `split` finds nothing to summarize. Otherwise `onStart` runs, the
729
786
  * summarizer is called with `streamText` (the Codex backend rejects
730
- * non-streaming requests) through `SummarizerTransform`, and the prompt is
787
+ * non-streaming requests) through `SummarizerTransform`, on the
788
+ * `SummarizerModel` when one is provided, and the prompt is
731
789
  * rewritten to `system + summary + trimKept(kept)`.
732
790
  *
733
791
  * Fails with the summarizer's `AiError`. Callers decide whether that is fatal.
@@ -759,21 +817,32 @@ export const compact: (options: {
759
817
  yield* options.onStart(options.reason)
760
818
  }
761
819
 
762
- const ai = yield* LanguageModel.LanguageModel
763
- const transform = yield* SummarizerTransform
764
- const summary = (yield* transform(
765
- ai
766
- .streamText({
767
- prompt: summarizerPrompt({ previousSummary, messages: toSummarize }),
768
- })
769
- .pipe(
770
- Stream.runFold(
771
- () => "",
772
- (text, part) =>
773
- part.type === "text-delta" ? text + part.delta : text,
820
+ const summarize = Effect.gen(function* () {
821
+ const ai = yield* LanguageModel.LanguageModel
822
+ const transform = yield* SummarizerTransform
823
+ return yield* transform(
824
+ ai
825
+ .streamText({
826
+ prompt: summarizerPrompt({ previousSummary, messages: toSummarize }),
827
+ })
828
+ .pipe(
829
+ Stream.runFold(
830
+ () => "",
831
+ (text, part) =>
832
+ part.type === "text-delta" ? text + part.delta : text,
833
+ ),
774
834
  ),
835
+ )
836
+ })
837
+ const summarizerModel = yield* Effect.serviceOption(SummarizerModel)
838
+ const summary = (yield* Option.match(summarizerModel, {
839
+ onNone: () => summarize,
840
+ onSome: (model) =>
841
+ summarize.pipe(
842
+ Effect.provide(model),
843
+ Effect.provideService(SummarizerTransform, identity),
775
844
  ),
776
- )).trim()
845
+ })).trim()
777
846
 
778
847
  if (summary.length === 0) {
779
848
  return yield* AiError.make({