clanka 0.22.2 → 0.22.3

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.
package/src/Agent.ts CHANGED
@@ -251,6 +251,13 @@ export const makeWith = Effect.fnUntraced(function* <
251
251
  const history = MutableRef.make(Prompt.empty)
252
252
  const environment = MutableRef.make(capabilities.environment)
253
253
 
254
+ // Threshold compactions run next to the model calls of the history they
255
+ // compact, and can outlive the run that started them.
256
+ const backgroundCompactions = new WeakMap<
257
+ MutableRef.MutableRef<Prompt.Prompt>,
258
+ BackgroundCompaction
259
+ >()
260
+
254
261
  const spawn: (opts: {
255
262
  /** Identifies the agent's output; the root agent is 0. */
256
263
  readonly agentId: number
@@ -292,6 +299,13 @@ export const makeWith = Effect.fnUntraced(function* <
292
299
  const conversationMode = yield* ConversationMode
293
300
  const turnTimeout = yield* TurnTimeout
294
301
  const maxRetries = yield* MaxRetries
302
+ const compactionConfig = yield* Compaction.CompactionConfig
303
+ // A summarizer on its own `SummarizerModel` builds its model per call. On
304
+ // this run's model it must not outlive the run, which may close the
305
+ // model when it ends.
306
+ const ownSummarizer = Option.isSome(
307
+ yield* Effect.serviceOption(Compaction.SummarizerModel),
308
+ )
295
309
  let finalSummary = Option.none<string>()
296
310
  // `inputTokens.total` from the most recent finish part; undefined until
297
311
  // the first response and after every rewrite of the history.
@@ -789,9 +803,37 @@ ${prompt}`,
789
803
  })
790
804
  }
791
805
 
792
- // The refresh is rendered before the rewrite and both are committed
793
- // together, so an interrupt leaves the old history and the old
794
- // environment, which still agree.
806
+ // Closes a compaction's progress event, after committing its rewrite
807
+ // when it has one. The refresh is rendered before the rewrite and both
808
+ // are committed together, so an interrupt leaves the old history and
809
+ // the old environment, which still agree.
810
+ const endCompaction = (
811
+ reason: Compaction.CompactionReason,
812
+ rewrite: Option.Option<{
813
+ readonly prompt: Prompt.Prompt
814
+ readonly refresh: AgentExecutor.EnvironmentUpdate
815
+ }>,
816
+ ) => {
817
+ const tokensBefore = Compaction.estimateTokens(prompt.current)
818
+ let tokensAfter = tokensBefore
819
+ if (Option.isSome(rewrite)) {
820
+ // The refresh sends the kept updates again, so they are dropped
821
+ // here to appear once.
822
+ replaceHistory(
823
+ Prompt.fromMessages(
824
+ rewrite.value.prompt.content.filter(
825
+ (message) => !isEnvironmentUpdate(message),
826
+ ),
827
+ ),
828
+ )
829
+ tokensAfter = Compaction.estimateTokens(rewrite.value.prompt)
830
+ }
831
+ maybeSend({
832
+ agentId,
833
+ part: new CompactionEnded({ reason, tokensBefore, tokensAfter }),
834
+ })
835
+ if (Option.isSome(rewrite)) applyEnvironmentUpdate(rewrite.value.refresh)
836
+ }
795
837
  const compactWithEvents = <E, R>(
796
838
  reason: Compaction.CompactionReason,
797
839
  compaction: Effect.Effect<
@@ -809,44 +851,176 @@ ${prompt}`,
809
851
  onNone: () => Effect.succeedNone,
810
852
  onSome: (result) =>
811
853
  Effect.map(renderEnvironment({ reset: true }), (refresh) =>
812
- Option.some({ ...result, refresh }),
854
+ Option.some({ prompt: result.prompt, refresh }),
813
855
  ),
814
856
  }),
815
857
  ),
816
858
  Effect.onExit((exit) =>
817
859
  Effect.sync(() => {
818
860
  if (!compactionStarted) return
819
- const result = Exit.isSuccess(exit) ? exit.value : Option.none()
820
- let tokensBefore: number
821
- let tokensAfter: number
822
- if (Option.isSome(result)) {
823
- // The refresh sends the kept updates again, so they are
824
- // dropped here to appear once.
825
- replaceHistory(
826
- Prompt.fromMessages(
827
- result.value.prompt.content.filter(
828
- (message) => !isEnvironmentUpdate(message),
829
- ),
830
- ),
831
- )
832
- tokensBefore = result.value.tokensBefore
833
- tokensAfter = result.value.tokensAfter
834
- } else {
835
- tokensBefore = tokensAfter = Compaction.estimateTokens(
836
- prompt.current,
837
- )
838
- }
839
- maybeSend({
840
- agentId,
841
- part: new CompactionEnded({ reason, tokensBefore, tokensAfter }),
842
- })
843
- if (Option.isSome(result)) {
844
- applyEnvironmentUpdate(result.value.refresh)
845
- }
861
+ endCompaction(
862
+ reason,
863
+ Exit.isSuccess(exit) ? exit.value : Option.none(),
864
+ )
846
865
  }),
847
866
  ),
848
867
  )
849
868
 
869
+ // A compaction times out once the summarizer has sent nothing for
870
+ // `turnTimeout`, like a model call, so a long summary that is still
871
+ // streaming can finish.
872
+ const withIdleTimeout = <A, E, R>(
873
+ run: (onActivity: () => void) => Effect.Effect<A, E, R>,
874
+ ) =>
875
+ Effect.suspend(() => {
876
+ let expires = clock.currentTimeMillisUnsafe() + turnTimeoutMs
877
+ const onActivity = () => {
878
+ expires = clock.currentTimeMillisUnsafe() + turnTimeoutMs
879
+ }
880
+ const timeout = Effect.gen(function* () {
881
+ while (true) {
882
+ const remaining = expires - clock.currentTimeMillisUnsafe()
883
+ if (remaining <= 0) {
884
+ return yield* new Cause.TimeoutError(
885
+ `The summarizer sent nothing for ${Duration.format(turnTimeout)}`,
886
+ )
887
+ }
888
+ yield* Effect.sleep(remaining)
889
+ }
890
+ })
891
+ return Effect.raceFirst(run(onActivity), timeout)
892
+ })
893
+
894
+ // Threshold compaction runs in the background, so a model call never
895
+ // waits for it. `startCompaction` forks one when the threshold fires
896
+ // and none is running; `settleCompaction` applies a finished one before
897
+ // the next model call. A failed input is not sent again until a back-off
898
+ // has passed, so a summary that times out is not retried every turn.
899
+ // Only a compaction on a `SummarizerModel` outlives the run; any other is
900
+ // cancelled when the run ends, which does not count as a failure.
901
+ const state: BackgroundCompaction = backgroundCompactions.get(prompt) ?? {
902
+ running: undefined,
903
+ failed: undefined,
904
+ failures: 0,
905
+ calls: 0,
906
+ }
907
+ backgroundCompactions.set(prompt, state)
908
+ const startCompaction = Effect.suspend(() => {
909
+ state.calls++
910
+ if (
911
+ state.running !== undefined ||
912
+ !Compaction.shouldCompact({
913
+ prompt: prompt.current,
914
+ contextTokens: lastContextTokens,
915
+ config: compactionConfig,
916
+ })
917
+ ) {
918
+ return Effect.void
919
+ }
920
+ const snapshot = prompt.current
921
+ const split = Compaction.split(
922
+ snapshot,
923
+ compactionConfig.keepRecentTokens,
924
+ )
925
+ if (Option.isNone(split)) return Effect.void
926
+ const { failed } = state
927
+ if (
928
+ failed !== undefined &&
929
+ state.calls < failed.retryAt &&
930
+ Compaction.sameSummarizerInput(failed.split, split.value)
931
+ ) {
932
+ return Effect.void
933
+ }
934
+ maybeSend({
935
+ agentId,
936
+ part: new CompactionStarted({ reason: "threshold" }),
937
+ })
938
+ return withIdleTimeout((onActivity) =>
939
+ Compaction.compact({
940
+ prompt: snapshot,
941
+ reason: "threshold",
942
+ onActivity,
943
+ }),
944
+ ).pipe(
945
+ Effect.forkIn(ownSummarizer ? agentScope : runScope, {
946
+ startImmediately: true,
947
+ }),
948
+ Effect.map((fiber) => {
949
+ state.running = {
950
+ snapshot,
951
+ split: split.value,
952
+ outlivesRun: ownSummarizer,
953
+ fiber,
954
+ }
955
+ }),
956
+ )
957
+ })
958
+ // Succeeds with what became of a finished compaction: `applied` when
959
+ // the history was compacted, `timed-out` when the summarizer went quiet.
960
+ const settleCompaction = Effect.suspend(
961
+ (): Effect.Effect<"applied" | "timed-out" | "unchanged"> => {
962
+ const running = state.running
963
+ const exit = running?.fiber.pollUnsafe()
964
+ if (running === undefined || exit === undefined) {
965
+ return Effect.succeed("unchanged")
966
+ }
967
+ state.running = undefined
968
+ if (Exit.isFailure(exit)) {
969
+ // Cancelled with the run that started it, not a failure.
970
+ if (Cause.hasInterruptsOnly(exit.cause)) {
971
+ endCompaction("threshold", Option.none())
972
+ return Effect.succeed("unchanged")
973
+ }
974
+ state.failures++
975
+ state.failed = {
976
+ split: running.split,
977
+ retryAt: state.calls + 4 * 2 ** (state.failures - 1),
978
+ }
979
+ endCompaction("threshold", Option.none())
980
+ const error = Cause.squash(exit.cause)
981
+ return Effect.as(
982
+ Effect.logWarning(
983
+ "Compaction failed, continuing with the uncompacted prompt",
984
+ error,
985
+ ),
986
+ Cause.isTimeoutError(error) ? "timed-out" : "unchanged",
987
+ )
988
+ }
989
+ state.failures = 0
990
+ state.failed = undefined
991
+ // The history may have grown since the compaction started. Anything
992
+ // else, such as another rewrite, makes the result stale.
993
+ const next = Option.flatMap(exit.value, (result) =>
994
+ rebaseCompaction(running.snapshot, prompt.current, result.prompt),
995
+ )
996
+ if (Option.isNone(next)) {
997
+ endCompaction("threshold", Option.none())
998
+ return Effect.succeed("unchanged")
999
+ }
1000
+ return Effect.map(renderEnvironment({ reset: true }), (refresh) => {
1001
+ endCompaction(
1002
+ "threshold",
1003
+ Option.some({ prompt: next.value, refresh }),
1004
+ )
1005
+ return "applied" as const
1006
+ })
1007
+ },
1008
+ )
1009
+ // Waits for a threshold compaction in flight to finish, then settles it.
1010
+ const awaitCompaction = Effect.suspend(() =>
1011
+ state.running === undefined
1012
+ ? settleCompaction
1013
+ : Effect.andThen(Fiber.await(state.running.fiber), settleCompaction),
1014
+ )
1015
+ // Cancels a compaction that cannot outlive this run, when the run ends.
1016
+ const cancelRunCompaction = Effect.suspend(() => {
1017
+ const running = state.running
1018
+ if (running === undefined || running.outlivesRun) return Effect.void
1019
+ state.running = undefined
1020
+ endCompaction("threshold", Option.none())
1021
+ return Fiber.interrupt(running.fiber)
1022
+ })
1023
+
850
1024
  // Script execution
851
1025
  const executeScript = Effect.fnUntraced(function* (script: string) {
852
1026
  yield* toolLatchAcquire
@@ -930,6 +1104,10 @@ ${prompt}`,
930
1104
  yield* Effect.gen(function* () {
931
1105
  while (true) {
932
1106
  if (Option.isSome(finalSummary)) {
1107
+ // Before the output closes, so the progress event is closed too.
1108
+ // A finished summary is applied rather than lost.
1109
+ yield* settleCompaction
1110
+ yield* cancelRunCompaction
933
1111
  mailbox.emit = undefined
934
1112
  yield* Queue.fail(
935
1113
  output,
@@ -982,22 +1160,11 @@ ${prompt}`,
982
1160
  }
983
1161
  }
984
1162
 
985
- // Threshold compaction before the next model call
986
- yield* compactWithEvents(
987
- "threshold",
988
- Compaction.compactIfNeeded({
989
- prompt: prompt.current,
990
- contextTokens: lastContextTokens,
991
- onStart: onCompactionStart,
992
- }).pipe(Effect.timeout(turnTimeout)),
993
- ).pipe(
994
- Effect.catchTag("TimeoutError", (error) =>
995
- Effect.logWarning(
996
- "Compaction timed out, continuing with the uncompacted prompt",
997
- error,
998
- ),
999
- ),
1000
- )
1163
+ // Threshold compaction, next to the model call. One that finished
1164
+ // straight away is applied before the call too.
1165
+ yield* settleCompaction
1166
+ yield* startCompaction
1167
+ yield* settleCompaction
1001
1168
 
1002
1169
  // Per attempt: the parts received, and what they reported.
1003
1170
  // oxlint-disable-next-line typescript/no-explicit-any
@@ -1227,33 +1394,53 @@ ${prompt}`,
1227
1394
  },
1228
1395
  ),
1229
1396
  )
1230
- // Overflow: compact once, retry the attempt once, then fail.
1397
+ // Overflow: compact the whole history once, retry the attempt once,
1398
+ // then fail. `retryOnTimeout` retries a summary that went quiet.
1399
+ const overflowCompaction = (
1400
+ err: AiError.AiError,
1401
+ retryOnTimeout: boolean,
1402
+ ) =>
1403
+ Effect.gen(function* () {
1404
+ discardAttempt()
1405
+ const compacted = yield* compactWithEvents(
1406
+ "overflow",
1407
+ withIdleTimeout((onActivity) =>
1408
+ Compaction.compact({
1409
+ prompt: prompt.current,
1410
+ reason: "overflow",
1411
+ onStart: onCompactionStart,
1412
+ onActivity,
1413
+ }),
1414
+ ).pipe(
1415
+ Effect.retry({
1416
+ while: (error) => error._tag === "TimeoutError",
1417
+ times: retryOnTimeout ? 1 : 0,
1418
+ }),
1419
+ Effect.catchTag("TimeoutError", Effect.die),
1420
+ ),
1421
+ )
1422
+ return Option.isSome(compacted)
1423
+ ? yield* attemptWithImageFallback
1424
+ : yield* err
1425
+ })
1231
1426
  yield* attemptWithImageFallback.pipe(
1232
- Effect.catchIf(
1233
- (err): err is AiError.AiError =>
1234
- err._tag === "AiError" && Compaction.isContextLengthError(err),
1235
- (err) =>
1236
- Effect.gen(function* () {
1237
- discardAttempt()
1238
- const compacted = yield* compactWithEvents(
1239
- "overflow",
1240
- Compaction.compact({
1241
- prompt: prompt.current,
1242
- reason: "overflow",
1243
- onStart: onCompactionStart,
1244
- }).pipe(
1245
- Effect.timeout(turnTimeout),
1246
- Effect.retry({
1247
- while: (error) => error._tag === "TimeoutError",
1248
- times: 1,
1249
- }),
1250
- Effect.catchTag("TimeoutError", Effect.die),
1251
- ),
1252
- )
1253
- return Option.isSome(compacted)
1254
- ? yield* attemptWithImageFallback
1255
- : yield* err
1256
- }),
1427
+ Effect.catchIf(isOverflow, (err) =>
1428
+ Effect.gen(function* () {
1429
+ discardAttempt()
1430
+ // A threshold summary in flight covers the start of this
1431
+ // history, so it is awaited rather than started over. When it
1432
+ // compacted the history, the call is retried on it first.
1433
+ // After a summary that went quiet, one more quiet summary
1434
+ // fails the turn, so the wait stays at two timeouts.
1435
+ const settled = yield* awaitCompaction
1436
+ const compact = (err: AiError.AiError) =>
1437
+ overflowCompaction(err, settled !== "timed-out")
1438
+ return settled === "applied"
1439
+ ? yield* attemptWithImageFallback.pipe(
1440
+ Effect.catchIf(isOverflow, compact),
1441
+ )
1442
+ : yield* compact(err)
1443
+ }),
1257
1444
  ),
1258
1445
  )
1259
1446
  appendHistory(Prompt.fromResponseParts(response))
@@ -1343,6 +1530,60 @@ export const make: Effect.Effect<
1343
1530
  Scope.Scope | AgentExecutor.AgentExecutor
1344
1531
  > = makeWith({})
1345
1532
 
1533
+ /** A context-length error, which the overflow path compacts for. */
1534
+ const isOverflow = (err: unknown): err is AiError.AiError =>
1535
+ AiError.isAiError(err) && Compaction.isContextLengthError(err)
1536
+
1537
+ interface RunningCompaction {
1538
+ /** The history the compaction started from. */
1539
+ readonly snapshot: Prompt.Prompt
1540
+ readonly split: Compaction.Split
1541
+ /** Whether it runs on a `SummarizerModel`, which can outlive the run. */
1542
+ readonly outlivesRun: boolean
1543
+ readonly fiber: Fiber.Fiber<
1544
+ Option.Option<Compaction.CompactionResult>,
1545
+ AiError.AiError | Cause.TimeoutError
1546
+ >
1547
+ }
1548
+
1549
+ interface BackgroundCompaction {
1550
+ running: RunningCompaction | undefined
1551
+ /** The split of the last failure, not sent again before `retryAt`. */
1552
+ failed:
1553
+ { readonly split: Compaction.Split; readonly retryAt: number } | undefined
1554
+ /** Failures in a row, for the back-off. */
1555
+ failures: number
1556
+ /** Model calls on this history so far. */
1557
+ calls: number
1558
+ }
1559
+
1560
+ /**
1561
+ * Apply a compaction of `snapshot` to `current`: the system message of
1562
+ * `current`, the compacted messages, then whatever was appended since the
1563
+ * snapshot. `None` when `current` does not start with the snapshot.
1564
+ */
1565
+ const rebaseCompaction = (
1566
+ snapshot: Prompt.Prompt,
1567
+ current: Prompt.Prompt,
1568
+ compacted: Prompt.Prompt,
1569
+ ): Option.Option<Prompt.Prompt> => {
1570
+ const before = snapshot.content.filter((message) => message.role !== "system")
1571
+ const now = current.content.filter((message) => message.role !== "system")
1572
+ if (
1573
+ now.length < before.length ||
1574
+ before.some((message, i) => message !== now[i])
1575
+ ) {
1576
+ return Option.none()
1577
+ }
1578
+ return Option.some(
1579
+ Prompt.fromMessages([
1580
+ ...current.content.filter((message) => message.role === "system"),
1581
+ ...compacted.content.filter((message) => message.role !== "system"),
1582
+ ...now.slice(before.length),
1583
+ ]),
1584
+ )
1585
+ }
1586
+
1346
1587
  interface Mailbox {
1347
1588
  readonly messages: Set<{
1348
1589
  readonly message: string
package/src/Compaction.ts CHANGED
@@ -6,9 +6,9 @@
6
6
  * 1. An always-on cap on `execute` results before they enter the Prompt
7
7
  * (`capOutput`). It runs on every surface and is not affected by the
8
8
  * compaction kill switch.
9
- * 2. Auto-compaction of the live Prompt (`compactIfNeeded` before a model
10
- * call, `compact` after a context-length error). Both rewrite the Prompt
11
- * to `system + <compaction-summary> user message + kept tail`.
9
+ * 2. Auto-compaction of the live Prompt (`compact` at the threshold, next
10
+ * to the model calls, and after a context-length error). Both rewrite the
11
+ * Prompt to `system + <compaction-summary> user message + kept tail`.
12
12
  *
13
13
  * @since 1.0.0
14
14
  */
@@ -510,6 +510,19 @@ export const split = (
510
510
  })
511
511
  }
512
512
 
513
+ /**
514
+ * Whether two splits send the same input to the summarizer: the same
515
+ * previous summary and the same messages to summarize.
516
+ *
517
+ * @since 1.0.0
518
+ * @category Cut points
519
+ */
520
+ export const sameSummarizerInput = (self: Split, that: Split): boolean =>
521
+ Option.getOrUndefined(self.previousSummary) ===
522
+ Option.getOrUndefined(that.previousSummary) &&
523
+ self.toSummarize.length === that.toSummarize.length &&
524
+ self.toSummarize.every((message, i) => message === that.toSummarize[i])
525
+
513
526
  /**
514
527
  * Find the text of a previous compaction summary in a Prompt, if present.
515
528
  *
@@ -802,6 +815,11 @@ export const compact: (options: {
802
815
  */
803
816
  readonly onStart?:
804
817
  ((reason: CompactionReason) => Effect.Effect<void>) | undefined
818
+ /**
819
+ * Runs for every part the summarizer streams, so a caller can tell a slow
820
+ * summary from a stalled one.
821
+ */
822
+ readonly onActivity?: (() => void) | undefined
805
823
  }) => Effect.Effect<
806
824
  Option.Option<CompactionResult>,
807
825
  AiError.AiError,
@@ -828,8 +846,10 @@ export const compact: (options: {
828
846
  .pipe(
829
847
  Stream.runFold(
830
848
  () => "",
831
- (text, part) =>
832
- part.type === "text-delta" ? text + part.delta : text,
849
+ (text, part) => {
850
+ options.onActivity?.()
851
+ return part.type === "text-delta" ? text + part.delta : text
852
+ },
833
853
  ),
834
854
  ),
835
855
  )
@@ -866,35 +886,3 @@ export const compact: (options: {
866
886
  tokensAfter: estimateTokens(rewritten),
867
887
  })
868
888
  })
869
-
870
- /**
871
- * Compact before the next model call when `shouldCompact` fires.
872
- *
873
- * Returns `None` when compaction is disabled, not needed, or a no-op. A
874
- * failing summarizer is swallowed here: the caller proceeds with the
875
- * uncompacted prompt and relies on the overflow path.
876
- *
877
- * @since 1.0.0
878
- * @category Compaction
879
- */
880
- export const compactIfNeeded: (options: {
881
- readonly prompt: Prompt.Prompt
882
- readonly contextTokens: number | undefined
883
- readonly onStart?:
884
- ((reason: CompactionReason) => Effect.Effect<void>) | undefined
885
- }) => Effect.Effect<
886
- Option.Option<CompactionResult>,
887
- never,
888
- LanguageModel.LanguageModel
889
- > = Effect.fnUntraced(function* (options) {
890
- const config = yield* CompactionConfig
891
- if (!shouldCompact({ ...options, config })) return Option.none()
892
- return yield* compact({ ...options, reason: "threshold" }).pipe(
893
- Effect.catch((error) =>
894
- Effect.logWarning(
895
- "Compaction failed, continuing with the uncompacted prompt",
896
- error,
897
- ).pipe(Effect.as(Option.none<CompactionResult>())),
898
- ),
899
- )
900
- })
package/src/ModelLayer.ts CHANGED
@@ -98,8 +98,9 @@ const languageModel = (
98
98
  * `auxiliary` models.
99
99
  *
100
100
  * Sub-agents run on `auxiliary.subagent`, or on this model when it is not
101
- * set. The compaction summarizer runs on `auxiliary.summarizer`, or on the
102
- * model of the agent that compacts when it is not set.
101
+ * set. The compaction summarizer runs on `auxiliary.summarizer`, or on its
102
+ * own copy of this model when it is not set. Each summary builds its model,
103
+ * so a summary still running when a prompt ends keeps a working client.
103
104
  *
104
105
  * @since 1.0.0
105
106
  * @category Layers
@@ -120,9 +121,11 @@ export const make = (
120
121
  Agent.layerSubagentModel(
121
122
  auxiliary?.subagent === undefined ? main : fromSpec(auxiliary.subagent),
122
123
  ),
123
- auxiliary?.summarizer === undefined
124
- ? Layer.empty
125
- : Compaction.layerSummarizerModel(fromSpec(auxiliary.summarizer)),
124
+ Compaction.layerSummarizerModel(
125
+ auxiliary?.summarizer === undefined
126
+ ? main
127
+ : fromSpec(auxiliary.summarizer),
128
+ ),
126
129
  )
127
130
  }
128
131