clanka 0.17.2 → 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 +84 -13
  21. package/dist/ClaudeAgent.js.map +1 -1
  22. package/dist/ClaudeAgent.test.js +187 -4
  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 +339 -229
  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 +271 -4
  79. package/src/ClaudeAgent.ts +114 -19
  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
 
@@ -309,17 +313,36 @@ const fakeClaude = (run: (session: FakeSession) => AsyncGenerator<object>) => {
309
313
  // Claude Code calling clanka's `execute` tool over MCP, each call tagged with
310
314
  // its tool use id unless `tagged` is false. Like Claude Code, it runs the calls
311
315
  // together only when `tools/list` marks the tool read-only, and otherwise
312
- // requests each call after the previous one returns.
316
+ // requests each call after the previous one returns. `onRequest` runs once
317
+ // clanka's handler has taken each request.
313
318
  const callExecute = async (
314
319
  session: FakeSession,
315
320
  calls: ReadonlyArray<readonly [id: string, script: string]>,
316
321
  tagged = true,
322
+ onRequest?: () => void,
317
323
  ) => {
318
- const server = session.options.mcpServers?.clanka as {
324
+ const server = session.options.mcpServers?.clanka as unknown as {
319
325
  readonly instance: {
320
326
  connect: (transport: InMemoryTransport) => Promise<void>
327
+ // The MCP SDK's handlers by method. Not public, but the SDK has no
328
+ // other way to see a request reach a handler that never returns.
329
+ readonly _requestHandlers: Map<
330
+ string,
331
+ (request: unknown, extra: unknown) => Promise<unknown>
332
+ >
321
333
  }
322
334
  }
335
+ if (onRequest !== undefined) {
336
+ const handlers = server.instance._requestHandlers
337
+ const handler = handlers.get("tools/call")
338
+ assert.isDefined(handler)
339
+ // The SDK's wrapper calls clanka's handler before its first await.
340
+ handlers.set("tools/call", (request, extra) => {
341
+ const result = handler(request, extra)
342
+ onRequest()
343
+ return result
344
+ })
345
+ }
323
346
  const [clientTransport, serverTransport] =
324
347
  InMemoryTransport.createLinkedPair()
325
348
  await server.instance.connect(serverTransport)
@@ -346,11 +369,14 @@ const callExecute = async (
346
369
  }
347
370
 
348
371
  // One API message calling `execute` once per call.
349
- const executeStep = (calls: ReadonlyArray<readonly [string, string]>) => [
372
+ const executeStep = (
373
+ calls: ReadonlyArray<readonly [string, string]>,
374
+ id = "msg_tools",
375
+ ) => [
350
376
  event({
351
377
  type: "message_start",
352
378
  message: {
353
- id: "msg_tools",
379
+ id,
354
380
  type: "message",
355
381
  role: "assistant",
356
382
  model: "claude-opus-5-5",
@@ -376,6 +402,22 @@ const executeStep = (calls: ReadonlyArray<readonly [string, string]>) => [
376
402
  event({ type: "message_stop" }),
377
403
  ]
378
404
 
405
+ // Claude Code answering a call itself instead of calling clanka, as it does
406
+ // for input it cannot validate or a call it aborts.
407
+ const answeredByClaude = (id: string, content: string) => ({
408
+ ...frame,
409
+ type: "user",
410
+ message: {
411
+ role: "user",
412
+ content: [
413
+ { type: "tool_result", tool_use_id: id, content, is_error: true },
414
+ ],
415
+ },
416
+ })
417
+
418
+ const invalidInput =
419
+ "<tool_use_error>InputValidationError: JSON parse failed</tool_use_error>"
420
+
379
421
  const finalStep = [
380
422
  assistant({ type: "text", text: "Done." }),
381
423
  {
@@ -454,6 +496,11 @@ const runSteps = Effect.fnUntraced(function* (
454
496
  }).pipe(Effect.provide(modelWith(fake)))
455
497
  })
456
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
+
457
504
  describe("ClaudeAgent.model", () => {
458
505
  it.effect("hands each parked call the result of its own tool use", () =>
459
506
  Effect.gen(function* () {
@@ -505,6 +552,122 @@ describe("ClaudeAgent.model", () => {
505
552
  }),
506
553
  )
507
554
 
555
+ it.effect(
556
+ "drops a call Claude Code answered itself and runs the parked one",
557
+ () =>
558
+ Effect.gen(function* () {
559
+ let results: ReadonlyArray<unknown> = []
560
+ const fake = fakeClaude(async function* (session) {
561
+ await session.input.next()
562
+ yield* executeStep([
563
+ ["toolu_a", "a"],
564
+ ["toolu_b", "b"],
565
+ ])
566
+ yield answeredByClaude("toolu_a", invalidInput)
567
+ results = await callExecute(session, [["toolu_b", "b"]])
568
+ yield* finalStep
569
+ })
570
+ yield* runSteps(fake, (first, response) =>
571
+ Prompt.concat(first, response),
572
+ )
573
+ assert.deepStrictEqual(
574
+ results.map((result: any) => result.content),
575
+ [[{ type: "text", text: "ran b" }]],
576
+ )
577
+ assert.deepStrictEqual(executed, ["b"])
578
+ assert.lengthOf(fake.sessions, 1)
579
+ }),
580
+ )
581
+
582
+ it.effect(
583
+ "keeps reading when Claude Code answers the only call and Claude retries",
584
+ () =>
585
+ Effect.gen(function* () {
586
+ let results: ReadonlyArray<unknown> = []
587
+ const fake = fakeClaude(async function* (session) {
588
+ await session.input.next()
589
+ yield* executeStep([["toolu_a", "a"]])
590
+ yield answeredByClaude("toolu_a", invalidInput)
591
+ yield* executeStep([["toolu_b", "b"]], "msg_retry")
592
+ results = await callExecute(session, [["toolu_b", "b"]])
593
+ yield* finalStep
594
+ })
595
+ yield* runSteps(fake, (first, response) =>
596
+ Prompt.concat(first, response),
597
+ )
598
+ assert.deepStrictEqual(
599
+ results.map((result: any) => result.content),
600
+ [[{ type: "text", text: "ran b" }]],
601
+ )
602
+ assert.deepStrictEqual(executed, ["b"])
603
+ assert.lengthOf(fake.sessions, 1)
604
+ }),
605
+ )
606
+
607
+ it.effect(
608
+ "holds a retry's calls until its message stops, even when they park first",
609
+ () =>
610
+ Effect.gen(function* () {
611
+ const retry = [
612
+ ["toolu_b", "b"],
613
+ ["toolu_c", "c"],
614
+ ] as const
615
+ let results: ReadonlyArray<unknown> = []
616
+ const fake = fakeClaude(async function* (session) {
617
+ await session.input.next()
618
+ yield* executeStep([["toolu_a", "a"]])
619
+ yield answeredByClaude("toolu_a", invalidInput)
620
+ const retryStep = executeStep(retry, "msg_retry")
621
+ yield* retryStep.slice(0, 1)
622
+ // Claude Code runs a call as soon as its block streams, so the
623
+ // retry's requests park before its assistant events and its
624
+ // message_stop.
625
+ const parked = Promise.withResolvers<void>()
626
+ let requests = 0
627
+ const parking = callExecute(session, retry, true, () => {
628
+ if (++requests === retry.length) parked.resolve()
629
+ })
630
+ await parked.promise
631
+ yield* retryStep.slice(1)
632
+ results = await parking
633
+ yield* finalStep
634
+ })
635
+ yield* runSteps(fake, (first, response) =>
636
+ Prompt.concat(first, response),
637
+ )
638
+ assert.deepStrictEqual(
639
+ results.map((result: any) => result.content),
640
+ [
641
+ [{ type: "text", text: "ran b" }],
642
+ [{ type: "text", text: "ran c" }],
643
+ ],
644
+ )
645
+ assert.deepStrictEqual(executed.toSorted(), ["b", "c"])
646
+ assert.lengthOf(fake.sessions, 1)
647
+ }),
648
+ )
649
+
650
+ it.effect("fails an aborted call with the result Claude Code gave it", () =>
651
+ Effect.gen(function* () {
652
+ const fake = fakeClaude(async function* (session) {
653
+ await session.input.next()
654
+ yield* executeStep([["toolu_a", "a"]])
655
+ yield answeredByClaude(
656
+ "toolu_a",
657
+ "[Request interrupted by user for tool use]",
658
+ )
659
+ })
660
+ const error = yield* Effect.flip(
661
+ runSteps(fake, (first, response) => Prompt.concat(first, response)),
662
+ )
663
+ assert.include(
664
+ error.message,
665
+ "[Request interrupted by user for tool use]",
666
+ )
667
+ assert.deepStrictEqual(executed, [])
668
+ }),
669
+ )
670
+
508
671
  it.effect(
509
672
  "starts over when the prompt's answer is not the one Claude gave",
510
673
  () =>
@@ -529,6 +692,110 @@ describe("ClaudeAgent.model", () => {
529
692
  }),
530
693
  )
531
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
+
532
799
  it.effect("closes Claude Code when a step is cut short", () =>
533
800
  Effect.gen(function* () {
534
801
  const fake = fakeClaude(async function* (session) {
@@ -372,6 +372,7 @@ const makeConverter = () => {
372
372
  switch (event.type) {
373
373
  case "message_start":
374
374
  messageId = event.message.id
375
+ calledTools = false
375
376
  streamed.add(messageId)
376
377
  usage.update(messageId, event.message.usage)
377
378
  break
@@ -695,6 +696,11 @@ interface Session {
695
696
  outcome: Outcome | undefined
696
697
  }
697
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
+
698
704
  // Ends `messages` before closing the scope, which interrupts the fiber that
699
705
  // would end it, so a step still reading the session fails instead of waiting.
700
706
  const closeSession = (session: Session) =>
@@ -758,7 +764,7 @@ const startSession = Effect.fnUntraced(function* (
758
764
  bridge,
759
765
  messages,
760
766
  scope,
761
- toolNames: provider.tools.map((tool) => tool.name).join(","),
767
+ toolNames: toolNames(provider),
762
768
  seen: provider.prompt.content,
763
769
  outcome: undefined,
764
770
  }
@@ -823,7 +829,7 @@ const continuation = (
823
829
  const response = messages[seen.length]
824
830
  if (
825
831
  outcome === undefined ||
826
- session.toolNames !== provider.tools.map((tool) => tool.name).join(",") ||
832
+ session.toolNames !== toolNames(provider) ||
827
833
  response?.role !== "assistant" ||
828
834
  !seen.every((message, i) => messages[i] === message) ||
829
835
  !isDeepStrictEqual(appended(response), emitted(outcome))
@@ -853,6 +859,36 @@ const continuation = (
853
859
  return { ids, results, users }
854
860
  }
855
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
+
856
892
  const continueSession = (
857
893
  session: Session,
858
894
  plan: NonNullable<ReturnType<typeof continuation>>,
@@ -888,22 +924,51 @@ const continueSession = (
888
924
  plan.ids.forEach((id, i) => session.bridge.resolve(id, results[i]!))
889
925
  }
890
926
 
891
- // The ids of the tool results in an SDK user message.
892
- const toolResultIds = (message: Sdk.SDKUserMessage): Array<string> =>
927
+ // The tool results in an SDK user message, with their text.
928
+ const toolResults = (
929
+ message: Sdk.SDKUserMessage,
930
+ ): Array<{
931
+ readonly id: string
932
+ readonly isError: boolean
933
+ readonly text: string
934
+ }> =>
893
935
  typeof message.message.content === "string"
894
936
  ? []
895
937
  : message.message.content.flatMap((block) =>
896
- block.type === "tool_result" ? [block.tool_use_id] : [],
938
+ block.type === "tool_result"
939
+ ? [
940
+ {
941
+ id: block.tool_use_id,
942
+ isError: block.is_error === true,
943
+ text:
944
+ typeof block.content === "string"
945
+ ? block.content
946
+ : (block.content ?? [])
947
+ .flatMap((part) =>
948
+ part.type === "text" ? [part.text] : [],
949
+ )
950
+ .join("\n"),
951
+ },
952
+ ]
953
+ : [],
897
954
  )
898
955
 
956
+ // Claude Code wraps the errors it hands back to the model, such as invalid
957
+ // input, a streaming fallback or an unknown tool, in this tag, and marks
958
+ // their results `is_error`. Aborts are not wrapped.
959
+ const isToolUseError = (text: string) =>
960
+ text.trimStart().startsWith("<tool_use_error>")
961
+
899
962
  // Reads one step from the session, recording how it ended. A step that does
900
963
  // not finish leaves the session in an unknown state, so it is closed.
901
964
  //
902
965
  // A tool step holds back its tool calls and its finish until Claude Code has
903
966
  // parked an MCP request for every call. Effect runs a call's handler as soon
904
967
  // as more parts follow it, so emitting a call earlier could run a script
905
- // that Claude Code never waits for. An untagged request, or Claude Code
906
- // answering a call itself, fails the step before any script runs.
968
+ // that Claude Code never waits for. When Claude Code answers a held call
969
+ // itself with an error for the model, the call is dropped and the step keeps
970
+ // reading while the model retries. An untagged request, or any other answer
971
+ // from Claude Code, fails the step before any script runs.
907
972
  const readStep = (
908
973
  session: Session,
909
974
  onAbandon: Effect.Effect<void>,
@@ -932,7 +997,11 @@ const readStep = (
932
997
  ),
933
998
  )
934
999
  }
935
- if (!calls.every((call) => parked.has(call.id))) return Effect.succeed([])
1000
+ // With every call dropped, the step waits for the model's retry or
1001
+ // the end of its turn.
1002
+ if (calls.length === 0 || !calls.every((call) => parked.has(call.id))) {
1003
+ return Effect.succeed([])
1004
+ }
936
1005
  session.outcome = { _tag: "Tools", calls, text }
937
1006
  return Effect.succeed([...calls, finish])
938
1007
  }
@@ -952,16 +1021,30 @@ const readStep = (
952
1021
  return release()
953
1022
  }
954
1023
  if (event.type === "user" && event.parent_tool_use_id === null) {
955
- const answered = toolResultIds(event).find(
956
- (id) => !parked.has(id) && calls.some((call) => call.id === id),
957
- )
958
- if (answered !== undefined) {
959
- return Effect.fail(
960
- unknownError(
961
- `Claude Code answered the tool call ${answered} itself instead of calling clanka.`,
962
- ),
963
- )
1024
+ let dropped = false
1025
+ for (const result of toolResults(event)) {
1026
+ const index = calls.findIndex((call) => call.id === result.id)
1027
+ if (index === -1 || parked.has(result.id)) continue
1028
+ if (!result.isError || !isToolUseError(result.text)) {
1029
+ return Effect.fail(
1030
+ unknownError(
1031
+ `Claude Code answered the tool call ${result.id} itself instead of calling clanka: ${result.text}`,
1032
+ ),
1033
+ )
1034
+ }
1035
+ calls.splice(index, 1)
1036
+ dropped = true
964
1037
  }
1038
+ if (dropped) return release()
1039
+ }
1040
+ // A retry after dropped calls is a new API message; the last one's
1041
+ // finish must not release its calls before its own `message_stop`.
1042
+ if (
1043
+ event.type === "stream_event" &&
1044
+ event.parent_tool_use_id === null &&
1045
+ event.event.type === "message_start"
1046
+ ) {
1047
+ finish = undefined
965
1048
  }
966
1049
  return Effect.flatMap(convert(event), (parts) => {
967
1050
  const out: Array<Response.StreamPartEncoded> = []
@@ -1042,6 +1125,8 @@ const layerLanguageModel = (
1042
1125
  // Set while a step is read. Another step would close the session under
1043
1126
  // it, so it fails instead.
1044
1127
  let reading = false
1128
+ // Whether a session has run, so a new one is a restart.
1129
+ let started = false
1045
1130
 
1046
1131
  const step = (provider: LanguageModel.ProviderOptions) =>
1047
1132
  Stream.suspend(() => {
@@ -1065,9 +1150,14 @@ const layerLanguageModel = (
1065
1150
  current.outcome = undefined
1066
1151
  return readStep(current, closeCurrent)
1067
1152
  }
1153
+ const reason = started
1154
+ ? restartReason(current, provider)
1155
+ : undefined
1068
1156
  yield* closeCurrent
1069
1157
  current = yield* startSession(model, options, provider, true)
1070
- return readStep(current, closeCurrent)
1158
+ started = true
1159
+ const read = readStep(current, closeCurrent)
1160
+ return reason === undefined ? read : reportRestart(read, reason)
1071
1161
  }),
1072
1162
  ).pipe(
1073
1163
  Stream.ensuring(
@@ -1148,6 +1238,11 @@ export const model = (
1148
1238
  // The system prompt stays in the Prompt, where `queryOptions` reads
1149
1239
  // it. No Compaction.SummarizerTransform: Claude Code takes no
1150
1240
  // per-request output cap.
1151
- 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
+ }),
1152
1247
  ),
1153
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
  })