clanka 0.22.2 → 0.22.4

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.
@@ -400,7 +414,6 @@ export const makeWith = Effect.fnUntraced(function* <
400
414
  if (typeof opts.system === "string") {
401
415
  system += `\n${opts.system}\n`
402
416
  }
403
- console.log("system:", system)
404
417
 
405
418
  function maybeSend(options: {
406
419
  readonly agentId: number
@@ -789,9 +802,37 @@ ${prompt}`,
789
802
  })
790
803
  }
791
804
 
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.
805
+ // Closes a compaction's progress event, after committing its rewrite
806
+ // when it has one. The refresh is rendered before the rewrite and both
807
+ // are committed together, so an interrupt leaves the old history and
808
+ // the old environment, which still agree.
809
+ const endCompaction = (
810
+ reason: Compaction.CompactionReason,
811
+ rewrite: Option.Option<{
812
+ readonly prompt: Prompt.Prompt
813
+ readonly refresh: AgentExecutor.EnvironmentUpdate
814
+ }>,
815
+ ) => {
816
+ const tokensBefore = Compaction.estimateTokens(prompt.current)
817
+ let tokensAfter = tokensBefore
818
+ if (Option.isSome(rewrite)) {
819
+ // The refresh sends the kept updates again, so they are dropped
820
+ // here to appear once.
821
+ replaceHistory(
822
+ Prompt.fromMessages(
823
+ rewrite.value.prompt.content.filter(
824
+ (message) => !isEnvironmentUpdate(message),
825
+ ),
826
+ ),
827
+ )
828
+ tokensAfter = Compaction.estimateTokens(rewrite.value.prompt)
829
+ }
830
+ maybeSend({
831
+ agentId,
832
+ part: new CompactionEnded({ reason, tokensBefore, tokensAfter }),
833
+ })
834
+ if (Option.isSome(rewrite)) applyEnvironmentUpdate(rewrite.value.refresh)
835
+ }
795
836
  const compactWithEvents = <E, R>(
796
837
  reason: Compaction.CompactionReason,
797
838
  compaction: Effect.Effect<
@@ -809,44 +850,176 @@ ${prompt}`,
809
850
  onNone: () => Effect.succeedNone,
810
851
  onSome: (result) =>
811
852
  Effect.map(renderEnvironment({ reset: true }), (refresh) =>
812
- Option.some({ ...result, refresh }),
853
+ Option.some({ prompt: result.prompt, refresh }),
813
854
  ),
814
855
  }),
815
856
  ),
816
857
  Effect.onExit((exit) =>
817
858
  Effect.sync(() => {
818
859
  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
- }
860
+ endCompaction(
861
+ reason,
862
+ Exit.isSuccess(exit) ? exit.value : Option.none(),
863
+ )
846
864
  }),
847
865
  ),
848
866
  )
849
867
 
868
+ // A compaction times out once the summarizer has sent nothing for
869
+ // `turnTimeout`, like a model call, so a long summary that is still
870
+ // streaming can finish.
871
+ const withIdleTimeout = <A, E, R>(
872
+ run: (onActivity: () => void) => Effect.Effect<A, E, R>,
873
+ ) =>
874
+ Effect.suspend(() => {
875
+ let expires = clock.currentTimeMillisUnsafe() + turnTimeoutMs
876
+ const onActivity = () => {
877
+ expires = clock.currentTimeMillisUnsafe() + turnTimeoutMs
878
+ }
879
+ const timeout = Effect.gen(function* () {
880
+ while (true) {
881
+ const remaining = expires - clock.currentTimeMillisUnsafe()
882
+ if (remaining <= 0) {
883
+ return yield* new Cause.TimeoutError(
884
+ `The summarizer sent nothing for ${Duration.format(turnTimeout)}`,
885
+ )
886
+ }
887
+ yield* Effect.sleep(remaining)
888
+ }
889
+ })
890
+ return Effect.raceFirst(run(onActivity), timeout)
891
+ })
892
+
893
+ // Threshold compaction runs in the background, so a model call never
894
+ // waits for it. `startCompaction` forks one when the threshold fires
895
+ // and none is running; `settleCompaction` applies a finished one before
896
+ // the next model call. A failed input is not sent again until a back-off
897
+ // has passed, so a summary that times out is not retried every turn.
898
+ // Only a compaction on a `SummarizerModel` outlives the run; any other is
899
+ // cancelled when the run ends, which does not count as a failure.
900
+ const state: BackgroundCompaction = backgroundCompactions.get(prompt) ?? {
901
+ running: undefined,
902
+ failed: undefined,
903
+ failures: 0,
904
+ calls: 0,
905
+ }
906
+ backgroundCompactions.set(prompt, state)
907
+ const startCompaction = Effect.suspend(() => {
908
+ state.calls++
909
+ if (
910
+ state.running !== undefined ||
911
+ !Compaction.shouldCompact({
912
+ prompt: prompt.current,
913
+ contextTokens: lastContextTokens,
914
+ config: compactionConfig,
915
+ })
916
+ ) {
917
+ return Effect.void
918
+ }
919
+ const snapshot = prompt.current
920
+ const split = Compaction.split(
921
+ snapshot,
922
+ compactionConfig.keepRecentTokens,
923
+ )
924
+ if (Option.isNone(split)) return Effect.void
925
+ const { failed } = state
926
+ if (
927
+ failed !== undefined &&
928
+ state.calls < failed.retryAt &&
929
+ Compaction.sameSummarizerInput(failed.split, split.value)
930
+ ) {
931
+ return Effect.void
932
+ }
933
+ maybeSend({
934
+ agentId,
935
+ part: new CompactionStarted({ reason: "threshold" }),
936
+ })
937
+ return withIdleTimeout((onActivity) =>
938
+ Compaction.compact({
939
+ prompt: snapshot,
940
+ reason: "threshold",
941
+ onActivity,
942
+ }),
943
+ ).pipe(
944
+ Effect.forkIn(ownSummarizer ? agentScope : runScope, {
945
+ startImmediately: true,
946
+ }),
947
+ Effect.map((fiber) => {
948
+ state.running = {
949
+ snapshot,
950
+ split: split.value,
951
+ outlivesRun: ownSummarizer,
952
+ fiber,
953
+ }
954
+ }),
955
+ )
956
+ })
957
+ // Succeeds with what became of a finished compaction: `applied` when
958
+ // the history was compacted, `timed-out` when the summarizer went quiet.
959
+ const settleCompaction = Effect.suspend(
960
+ (): Effect.Effect<"applied" | "timed-out" | "unchanged"> => {
961
+ const running = state.running
962
+ const exit = running?.fiber.pollUnsafe()
963
+ if (running === undefined || exit === undefined) {
964
+ return Effect.succeed("unchanged")
965
+ }
966
+ state.running = undefined
967
+ if (Exit.isFailure(exit)) {
968
+ // Cancelled with the run that started it, not a failure.
969
+ if (Cause.hasInterruptsOnly(exit.cause)) {
970
+ endCompaction("threshold", Option.none())
971
+ return Effect.succeed("unchanged")
972
+ }
973
+ state.failures++
974
+ state.failed = {
975
+ split: running.split,
976
+ retryAt: state.calls + 4 * 2 ** (state.failures - 1),
977
+ }
978
+ endCompaction("threshold", Option.none())
979
+ const error = Cause.squash(exit.cause)
980
+ return Effect.as(
981
+ Effect.logWarning(
982
+ "Compaction failed, continuing with the uncompacted prompt",
983
+ error,
984
+ ),
985
+ Cause.isTimeoutError(error) ? "timed-out" : "unchanged",
986
+ )
987
+ }
988
+ state.failures = 0
989
+ state.failed = undefined
990
+ // The history may have grown since the compaction started. Anything
991
+ // else, such as another rewrite, makes the result stale.
992
+ const next = Option.flatMap(exit.value, (result) =>
993
+ rebaseCompaction(running.snapshot, prompt.current, result.prompt),
994
+ )
995
+ if (Option.isNone(next)) {
996
+ endCompaction("threshold", Option.none())
997
+ return Effect.succeed("unchanged")
998
+ }
999
+ return Effect.map(renderEnvironment({ reset: true }), (refresh) => {
1000
+ endCompaction(
1001
+ "threshold",
1002
+ Option.some({ prompt: next.value, refresh }),
1003
+ )
1004
+ return "applied" as const
1005
+ })
1006
+ },
1007
+ )
1008
+ // Waits for a threshold compaction in flight to finish, then settles it.
1009
+ const awaitCompaction = Effect.suspend(() =>
1010
+ state.running === undefined
1011
+ ? settleCompaction
1012
+ : Effect.andThen(Fiber.await(state.running.fiber), settleCompaction),
1013
+ )
1014
+ // Cancels a compaction that cannot outlive this run, when the run ends.
1015
+ const cancelRunCompaction = Effect.suspend(() => {
1016
+ const running = state.running
1017
+ if (running === undefined || running.outlivesRun) return Effect.void
1018
+ state.running = undefined
1019
+ endCompaction("threshold", Option.none())
1020
+ return Fiber.interrupt(running.fiber)
1021
+ })
1022
+
850
1023
  // Script execution
851
1024
  const executeScript = Effect.fnUntraced(function* (script: string) {
852
1025
  yield* toolLatchAcquire
@@ -930,6 +1103,10 @@ ${prompt}`,
930
1103
  yield* Effect.gen(function* () {
931
1104
  while (true) {
932
1105
  if (Option.isSome(finalSummary)) {
1106
+ // Before the output closes, so the progress event is closed too.
1107
+ // A finished summary is applied rather than lost.
1108
+ yield* settleCompaction
1109
+ yield* cancelRunCompaction
933
1110
  mailbox.emit = undefined
934
1111
  yield* Queue.fail(
935
1112
  output,
@@ -982,22 +1159,11 @@ ${prompt}`,
982
1159
  }
983
1160
  }
984
1161
 
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
- )
1162
+ // Threshold compaction, next to the model call. One that finished
1163
+ // straight away is applied before the call too.
1164
+ yield* settleCompaction
1165
+ yield* startCompaction
1166
+ yield* settleCompaction
1001
1167
 
1002
1168
  // Per attempt: the parts received, and what they reported.
1003
1169
  // oxlint-disable-next-line typescript/no-explicit-any
@@ -1227,33 +1393,53 @@ ${prompt}`,
1227
1393
  },
1228
1394
  ),
1229
1395
  )
1230
- // Overflow: compact once, retry the attempt once, then fail.
1396
+ // Overflow: compact the whole history once, retry the attempt once,
1397
+ // then fail. `retryOnTimeout` retries a summary that went quiet.
1398
+ const overflowCompaction = (
1399
+ err: AiError.AiError,
1400
+ retryOnTimeout: boolean,
1401
+ ) =>
1402
+ Effect.gen(function* () {
1403
+ discardAttempt()
1404
+ const compacted = yield* compactWithEvents(
1405
+ "overflow",
1406
+ withIdleTimeout((onActivity) =>
1407
+ Compaction.compact({
1408
+ prompt: prompt.current,
1409
+ reason: "overflow",
1410
+ onStart: onCompactionStart,
1411
+ onActivity,
1412
+ }),
1413
+ ).pipe(
1414
+ Effect.retry({
1415
+ while: (error) => error._tag === "TimeoutError",
1416
+ times: retryOnTimeout ? 1 : 0,
1417
+ }),
1418
+ Effect.catchTag("TimeoutError", Effect.die),
1419
+ ),
1420
+ )
1421
+ return Option.isSome(compacted)
1422
+ ? yield* attemptWithImageFallback
1423
+ : yield* err
1424
+ })
1231
1425
  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
- }),
1426
+ Effect.catchIf(isOverflow, (err) =>
1427
+ Effect.gen(function* () {
1428
+ discardAttempt()
1429
+ // A threshold summary in flight covers the start of this
1430
+ // history, so it is awaited rather than started over. When it
1431
+ // compacted the history, the call is retried on it first.
1432
+ // After a summary that went quiet, one more quiet summary
1433
+ // fails the turn, so the wait stays at two timeouts.
1434
+ const settled = yield* awaitCompaction
1435
+ const compact = (err: AiError.AiError) =>
1436
+ overflowCompaction(err, settled !== "timed-out")
1437
+ return settled === "applied"
1438
+ ? yield* attemptWithImageFallback.pipe(
1439
+ Effect.catchIf(isOverflow, compact),
1440
+ )
1441
+ : yield* compact(err)
1442
+ }),
1257
1443
  ),
1258
1444
  )
1259
1445
  appendHistory(Prompt.fromResponseParts(response))
@@ -1343,6 +1529,60 @@ export const make: Effect.Effect<
1343
1529
  Scope.Scope | AgentExecutor.AgentExecutor
1344
1530
  > = makeWith({})
1345
1531
 
1532
+ /** A context-length error, which the overflow path compacts for. */
1533
+ const isOverflow = (err: unknown): err is AiError.AiError =>
1534
+ AiError.isAiError(err) && Compaction.isContextLengthError(err)
1535
+
1536
+ interface RunningCompaction {
1537
+ /** The history the compaction started from. */
1538
+ readonly snapshot: Prompt.Prompt
1539
+ readonly split: Compaction.Split
1540
+ /** Whether it runs on a `SummarizerModel`, which can outlive the run. */
1541
+ readonly outlivesRun: boolean
1542
+ readonly fiber: Fiber.Fiber<
1543
+ Option.Option<Compaction.CompactionResult>,
1544
+ AiError.AiError | Cause.TimeoutError
1545
+ >
1546
+ }
1547
+
1548
+ interface BackgroundCompaction {
1549
+ running: RunningCompaction | undefined
1550
+ /** The split of the last failure, not sent again before `retryAt`. */
1551
+ failed:
1552
+ { readonly split: Compaction.Split; readonly retryAt: number } | undefined
1553
+ /** Failures in a row, for the back-off. */
1554
+ failures: number
1555
+ /** Model calls on this history so far. */
1556
+ calls: number
1557
+ }
1558
+
1559
+ /**
1560
+ * Apply a compaction of `snapshot` to `current`: the system message of
1561
+ * `current`, the compacted messages, then whatever was appended since the
1562
+ * snapshot. `None` when `current` does not start with the snapshot.
1563
+ */
1564
+ const rebaseCompaction = (
1565
+ snapshot: Prompt.Prompt,
1566
+ current: Prompt.Prompt,
1567
+ compacted: Prompt.Prompt,
1568
+ ): Option.Option<Prompt.Prompt> => {
1569
+ const before = snapshot.content.filter((message) => message.role !== "system")
1570
+ const now = current.content.filter((message) => message.role !== "system")
1571
+ if (
1572
+ now.length < before.length ||
1573
+ before.some((message, i) => message !== now[i])
1574
+ ) {
1575
+ return Option.none()
1576
+ }
1577
+ return Option.some(
1578
+ Prompt.fromMessages([
1579
+ ...current.content.filter((message) => message.role === "system"),
1580
+ ...compacted.content.filter((message) => message.role !== "system"),
1581
+ ...now.slice(before.length),
1582
+ ]),
1583
+ )
1584
+ }
1585
+
1346
1586
  interface Mailbox {
1347
1587
  readonly messages: Set<{
1348
1588
  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