The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 22, 22:00 UTC
feat(server): compact idle Claude threads before the prompt cache expires (beta) (#21682)
Co-authored-by: maria-rcks <maria@kuuro.net> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Theo Browne committed
Oct 19, 2026 at 22:35 UTC
5d3875d703392751600970831e6779b4f357a7ba
14 files changed
+566
-7
apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts
+15
@@ -1011,6 +1011,21 @@ describe("ClaudeAdapterV2 context usage", () => {
1011
undefined,
1012
);
1013
});
1014
+
1015
+ it("dates cache expiry from the request start, not the response end", () => {
1016
+ const usage = ClaudeAdapterV2.claudeProviderTurnTokenUsage(
1017
+ {
1018
+ input_tokens: 1,
1019
+ output_tokens: 1,
1020
+ cache_creation: { ephemeral_1h_input_tokens: 0, ephemeral_5m_input_tokens: 300 },
1021
+ },
1022
+ CLAUDE_TEST_MODEL_SELECTION,
1023
+ "2026-08-29T00:03:00.000Z",
1024
+ "",
1025
+ DateTime.makeUnsafe("2026-08-29T00:00:00.000Z"),
1026
+ );
1027
+ assert.strictEqual(usage.promptCacheExpiresAt, "2026-08-29T00:05:00.000Z");
1028
+ });
1029
});
1030
1031
describe("ClaudeAdapterV2 session permissions", () => {
apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
+19
-2
@@ -242,11 +242,17 @@ export function claudeProviderTurnTokenUsage(
242
modelSelection: ModelSelection,
243
updatedAt: string,
244
autoCompactWindow = "",
245
+ requestedAt?: DateTime.Utc,
246
) {
247
const inputTokens = claudeMessageInputTokens(usage);
248
const outputTokens = usage.output_tokens;
249
const promptCacheTtlMs = claudePromptCacheTtlMs(usage.cache_creation);
250
const maxTokens = claudeContextWindow(modelSelection);
251
+ // The cache lifetime starts with the request, not when its response ends.
252
+ const promptCacheExpiresAt =
253
+ promptCacheTtlMs === undefined || requestedAt === undefined
254
+ ? undefined
255
+ : DateTime.formatIso(DateTime.add(requestedAt, { milliseconds: promptCacheTtlMs }));
256
return {
257
usedTokens: inputTokens + outputTokens,
258
maxTokens,
@@ -256,6 +262,7 @@ export function claudeProviderTurnTokenUsage(
262
reasoningOutputTokens: 0,
263
...(promptCacheTtlMs === undefined ? {} : { promptCacheTtlMs }),
264
...claudeAutoCompactThreshold(autoCompactWindow, maxTokens),
265
+ ...(promptCacheExpiresAt === undefined ? {} : { promptCacheExpiresAt }),
266
updatedAt,
267
};
268
}
@@ -3254,7 +3261,12 @@ interface ActiveClaudeTurnContext {
3261
// assistant snapshots repeat message_start usage, which some proxies send
3262
// as zeros, so they only fill in input the stream has not reported. A
3263
// compaction makes the usage stale (null) without forgetting the request.
3257
- streamUsage: { readonly messageId: string; usage: ClaudeMessageUsage | null } | null;
3264
+ // `requestedAt` is when a streamed request started; its prompt cache lifetime starts then.
3265
+ streamUsage: {
3266
+ readonly messageId: string;
3267
+ requestedAt?: DateTime.Utc;
3268
+ usage: ClaudeMessageUsage | null;
3269
+ } | null;
3270
readonly toolCalls: Map<string, ActiveClaudeToolCall>;
3271
// A successful status can precede the boundary that supplies its token counts.
3272
compaction: Extract<OrchestrationV2TurnItem, { type: "compaction" }> | null;
@@ -4121,13 +4133,18 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
4133
const emitContextUsage = Effect.fnUntraced(function* (
4134
context: ActiveClaudeTurnContext,
4135
usage: ClaudeMessageUsage,
4136
+ requestStarted = false,
4137
) {
4138
const now = yield* DateTime.now;
4139
+ // Only message_start marks the request start; an assistant snapshot
4140
+ // arrives after generation, so it leaves the cache expiry unknown.
4141
+ if (requestStarted && context.streamUsage !== null) context.streamUsage.requestedAt = now;
4142
const tokenUsage = claudeProviderTurnTokenUsage(
4143
usage,
4144
context.input.modelSelection,
4145
DateTime.formatIso(now),
4146
adapterOptions.settings.autoCompactWindow,
4147
+ context.streamUsage?.requestedAt,
4148
);
4149
if (tokenUsage.inputTokens <= 0) return;
4150
yield* emitProviderEvent({
@@ -7388,7 +7405,7 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
7405
const usage: ClaudeMessageUsage | undefined = event.message.usage;
7406
context.streamUsage =
7407
usage === undefined ? null : { messageId: event.message.id, usage };
7391
- if (usage !== undefined) yield* emitContextUsage(context, usage);
7408
+ if (usage !== undefined) yield* emitContextUsage(context, usage, true);
7409
} else if (event.type === "message_delta") {
7410
const usage: typeof event.usage | undefined = event.usage;
7411
const stream = context.streamUsage;
apps/server/src/orchestration-v2/IdleCompaction.test.ts
new
+269
@@ -0,0 +1,269 @@
1
+import { describe, expect, it } from "@effect/vitest";
2
+import {
3
+ DEFAULT_SERVER_SETTINGS,
4
+ EventId,
5
+ MessageId,
6
+ NodeId,
7
+ ProjectId,
8
+ ProviderDriverKind,
9
+ ProviderInstanceId,
10
+ ProviderThreadId,
11
+ ProviderTurnId,
12
+ RunId,
13
+ ThreadId,
14
+ type OrchestrationV2DomainEvent,
15
+ type OrchestrationV2ServerCommand,
16
+} from "@t3tools/contracts";
17
+import * as DateTime from "effect/DateTime";
18
+import * as Effect from "effect/Effect";
19
+import * as Layer from "effect/Layer";
20
+import * as Queue from "effect/Queue";
21
+import * as Stream from "effect/Stream";
22
+import { TestClock } from "effect/testing";
23
+
24
+import * as SqlitePersistence from "../persistence/Sqlite.ts";
25
+import * as ServerSettings from "../serverSettings.ts";
26
+import { idleCompactionWindow, type IdleCompactionRecords } from "./IdleCompaction.ts";
27
+import * as IdleCompactionService from "./IdleCompactionService.ts";
28
+import * as Orchestrator from "./Orchestrator.ts";
29
+import * as ProjectionStore from "./ProjectionStore.ts";
30
+
31
+const NOW_MS = Date.parse("2026-10-19T12:00:00.000Z");
32
+const MINUTE_MS = 60_000;
33
+const at = (offset = 0) => DateTime.makeUnsafe(NOW_MS + offset);
34
+const threadId = ThreadId.make("idle-thread");
35
+const runId = RunId.make("run-1");
36
+const instanceId = ProviderInstanceId.make("claudeAgent");
37
+const providerThreadId = ProviderThreadId.make("provider-thread");
38
+const modelSelection = { instanceId, model: "claude-opus-5-5" };
39
+
40
+function records(
41
+ usage: { readonly usedTokens?: number; readonly cacheExpiresInMs?: number } = {},
42
+): { -readonly [Key in keyof IdleCompactionRecords]: IdleCompactionRecords[Key] } {
43
+ const messageId = MessageId.make("message-1");
44
+ const nodeId = NodeId.make("root-node");
45
+ return {
46
+ thread: {
47
+ id: threadId,
48
+ projectId: ProjectId.make("project"),
49
+ title: "Idle thread",
50
+ createdBy: "user",
51
+ creationSource: "web",
52
+ providerInstanceId: instanceId,
53
+ modelSelection,
54
+ runtimeMode: "full-access",
55
+ interactionMode: "default",
56
+ branch: null,
57
+ worktreePath: null,
58
+ activeProviderThreadId: providerThreadId,
59
+ lineage: { rootThreadId: threadId, parentThreadId: null, relationshipToParent: null },
60
+ forkedFrom: null,
61
+ createdAt: at(-MINUTE_MS),
62
+ updatedAt: at(),
63
+ archivedAt: null,
64
+ settledOverride: null,
65
+ settledAt: null,
66
+ lastVisitedAt: at(),
67
+ deletedAt: null,
68
+ },
69
+ runs: [
70
+ {
71
+ id: runId,
72
+ threadId,
73
+ ordinal: 1,
74
+ providerInstanceId: instanceId,
75
+ modelSelection,
76
+ providerThreadId,
77
+ userMessageId: messageId,
78
+ rootNodeId: nodeId,
79
+ activeAttemptId: null,
80
+ status: "completed",
81
+ requestedAt: at(-MINUTE_MS),
82
+ startedAt: at(-MINUTE_MS),
83
+ completedAt: at(),
84
+ checkpointId: null,
85
+ contextHandoffId: null,
86
+ },
87
+ ],
88
+ messages: [
89
+ {
90
+ id: messageId,
91
+ threadId,
92
+ runId,
93
+ nodeId,
94
+ role: "user",
95
+ text: "Explain this code",
96
+ attachments: [],
97
+ streaming: false,
98
+ createdBy: "user",
99
+ creationSource: "web",
100
+ createdAt: at(-MINUTE_MS),
101
+ updatedAt: at(-MINUTE_MS),
102
+ },
103
+ ],
104
+ providerThreads: [
105
+ {
106
+ id: providerThreadId,
107
+ driver: ProviderDriverKind.make("claudeAgent"),
108
+ providerInstanceId: instanceId,
109
+ providerSessionId: null,
110
+ appThreadId: threadId,
111
+ ownerNodeId: nodeId,
112
+ nativeThreadRef: null,
113
+ nativeConversationHeadRef: null,
114
+ status: "idle",
115
+ firstRunOrdinal: 1,
116
+ lastRunOrdinal: 1,
117
+ handoffIds: [],
118
+ forkedFrom: null,
119
+ pendingBackgroundTasks: [],
120
+ createdAt: at(-MINUTE_MS),
121
+ updatedAt: at(),
122
+ },
123
+ ],
124
+ providerTurns: [
125
+ {
126
+ id: ProviderTurnId.make("provider-turn-1"),
127
+ providerThreadId,
128
+ nodeId,
129
+ runAttemptId: null,
130
+ nativeTurnRef: null,
131
+ ordinal: 1,
132
+ status: "completed",
133
+ startedAt: at(-MINUTE_MS),
134
+ completedAt: at(),
135
+ tokenUsage: {
136
+ usedTokens: usage.usedTokens ?? 250_000,
137
+ ...(usage.cacheExpiresInMs === undefined
138
+ ? {}
139
+ : { promptCacheExpiresAt: DateTime.formatIso(at(usage.cacheExpiresInMs)) }),
140
+ updatedAt: DateTime.formatIso(at()),
141
+ },
142
+ },
143
+ ],
144
+ runtimeRequests: [],
145
+ turnItems: [],
146
+ contextTransfers: [],
147
+ };
148
+}
149
+
150
+describe("idleCompactionWindow", () => {
151
+ it("starts two minutes before the cache Claude reported expires", () => {
152
+ expect(idleCompactionWindow(records({ cacheExpiresInMs: 60 * MINUTE_MS }), NOW_MS)).toEqual({
153
+ runId,
154
+ startMs: NOW_MS + 58 * MINUTE_MS,
155
+ endMs: NOW_MS + 60 * MINUTE_MS,
156
+ });
157
+ // A 5m cache whose last request started 3 minutes before the run ended.
158
+ const late = records({ cacheExpiresInMs: 2 * MINUTE_MS });
159
+ expect(idleCompactionWindow(late, NOW_MS)).toMatchObject({ startMs: NOW_MS });
160
+ expect(idleCompactionWindow(late, NOW_MS + 2 * MINUTE_MS)).toBeNull();
161
+ });
162
+
163
+ it("skips small contexts, unknown expiry, other providers, switched threads, and compactions", () => {
164
+ const cache = { cacheExpiresInMs: 60 * MINUTE_MS };
165
+ expect(idleCompactionWindow(records({ ...cache, usedTokens: 199_999 }), NOW_MS)).toBeNull();
166
+ expect(idleCompactionWindow(records(), NOW_MS)).toBeNull();
167
+ const codex = records(cache);
168
+ codex.providerThreads = [
169
+ { ...codex.providerThreads[0]!, driver: ProviderDriverKind.make("codex") },
170
+ ];
171
+ expect(idleCompactionWindow(codex, NOW_MS)).toBeNull();
172
+ const switched = records(cache);
173
+ switched.thread = { ...switched.thread, providerInstanceId: ProviderInstanceId.make("codex") };
174
+ expect(idleCompactionWindow(switched, NOW_MS)).toBeNull();
175
+ const compacted = records(cache);
176
+ compacted.messages = [{ ...compacted.messages[0]!, text: "/compact" }];
177
+ expect(idleCompactionWindow(compacted, NOW_MS)).toBeNull();
178
+ const archived = records(cache);
179
+ archived.thread = { ...archived.thread, archivedAt: at() };
180
+ expect(idleCompactionWindow(archived, NOW_MS)).toBeNull();
181
+ });
182
+});
183
+
184
+const seed = Effect.fn("seedIdleThread")(function* (value: IdleCompactionRecords) {
185
+ const store = yield* ProjectionStore.ProjectionStoreV2;
186
+ const event = { threadId, occurredAt: at() };
187
+ yield* store.apply({
188
+ ...event,
189
+ id: EventId.make("e1"),
190
+ type: "thread.created",
191
+ payload: value.thread,
192
+ });
193
+ yield* store.apply({
194
+ ...event,
195
+ id: EventId.make("e2"),
196
+ type: "run.created",
197
+ payload: value.runs[0]!,
198
+ });
199
+ yield* store.apply({
200
+ ...event,
201
+ id: EventId.make("e3"),
202
+ type: "message.updated",
203
+ payload: value.messages[0]!,
204
+ });
205
+ yield* store.apply({
206
+ ...event,
207
+ id: EventId.make("e4"),
208
+ type: "provider-thread.updated",
209
+ payload: value.providerThreads[0]!,
210
+ });
211
+ yield* store.apply({
212
+ ...event,
213
+ id: EventId.make("e5"),
214
+ type: "provider-turn.updated",
215
+ payload: value.providerTurns[0]!,
216
+ });
217
+});
218
+
219
+it.effect("sends /compact as T3 Code once the cache is about to expire", () =>
220
+ Effect.gen(function* () {
221
+ yield* TestClock.setTime(NOW_MS);
222
+ const value = records({ cacheExpiresInMs: 5 * MINUTE_MS });
223
+ yield* seed(value);
224
+ const events = yield* Queue.unbounded<OrchestrationV2DomainEvent>();
225
+ const commands = yield* Queue.unbounded<OrchestrationV2ServerCommand>();
226
+ const reads = yield* Queue.unbounded<void>();
227
+ const store = yield* ProjectionStore.ProjectionStoreV2;
228
+ const dependencies = Layer.mergeAll(
229
+ Layer.succeed(ProjectionStore.ProjectionStoreV2, {
230
+ ...store,
231
+ getThreadRecords: (...args) =>
232
+ store.getThreadRecords(...args).pipe(Effect.tap(() => Queue.offer(reads, undefined))),
233
+ }),
234
+ Layer.mock(ServerSettings.ServerSettingsService)({
235
+ getSettings: Effect.succeed({ ...DEFAULT_SERVER_SETTINGS, compactIdleThreads: true }),
236
+ }),
237
+ Layer.mock(Orchestrator.OrchestratorV2)({
238
+ streamDomainEvents: Stream.fromQueue(events),
239
+ dispatch: (command) =>
240
+ Queue.offer(commands, command).pipe(Effect.as({ sequence: 1, storedEvents: [] })),
241
+ }),
242
+ );
243
+ yield* Effect.gen(function* () {
244
+ const service = yield* IdleCompactionService.make;
245
+ yield* service.start();
246
+ yield* Queue.offer(events, {
247
+ id: EventId.make("completed"),
248
+ type: "run.updated",
249
+ threadId,
250
+ occurredAt: at(),
251
+ payload: value.runs[0]!,
252
+ });
253
+ yield* Queue.take(reads);
254
+ yield* TestClock.adjust("2 minutes");
255
+ expect(yield* Queue.size(commands)).toBe(0);
256
+ yield* TestClock.adjust("1 minute");
257
+ expect(yield* Queue.take(commands)).toMatchObject({
258
+ type: "message.dispatch",
259
+ threadId,
260
+ text: "/compact",
261
+ createdBy: "agent",
262
+ creationSource: "server",
263
+ });
264
+ }).pipe(Effect.provide(dependencies));
265
+ }).pipe(
266
+ Effect.provide(ProjectionStore.layer.pipe(Layer.provide(SqlitePersistence.layerMemory))),
267
+ Effect.scoped,
268
+ ),
269
+);
apps/server/src/orchestration-v2/IdleCompaction.ts
new
+103
@@ -0,0 +1,103 @@
1
+import type { OrchestrationV2ThreadProjection } from "@t3tools/contracts";
2
+import { COMPACTION_SUGGESTION_MIN_TOKENS } from "@t3tools/shared/claudeCompaction";
3
+import { derivePendingBackgroundWork } from "@t3tools/shared/orchestrationV2PendingBackgroundWork";
4
+import * as DateTime from "effect/DateTime";
5
+
6
+// Claude Code's idleCompaction defaults to 200K and won't go below 100K. Below
7
+// that a cold re-read is cheap, so compacting mostly loses context for little
8
+// saving.
9
+const MIN_CONTEXT_TOKENS = COMPACTION_SUGGESTION_MIN_TOKENS;
10
+// Start this long before the cache expires: enough for the session to resume
11
+// and send the compaction while the cache is still warm.
12
+const LEAD_MS = 2 * 60_000;
13
+
14
+export type IdleCompactionRecords = Pick<
15
+ OrchestrationV2ThreadProjection,
16
+ | "thread"
17
+ | "runs"
18
+ | "messages"
19
+ | "providerThreads"
20
+ | "providerTurns"
21
+ | "runtimeRequests"
22
+ | "turnItems"
23
+ | "contextTransfers"
24
+>;
25
+
26
+/**
27
+ * When an idle Claude thread should compact, or null when it should not. The
28
+ * window ends when the prompt cache of Claude's last request expires (1h on
29
+ * subscriptions, 5m on API keys); compacting after that pays a full uncached
30
+ * read.
31
+ */
32
+export function idleCompactionWindow(
33
+ {
34
+ thread,
35
+ runs,
36
+ messages,
37
+ providerThreads,
38
+ providerTurns,
39
+ runtimeRequests,
40
+ turnItems,
41
+ contextTransfers,
42
+ }: IdleCompactionRecords,
43
+ nowMs: number,
44
+): {
45
+ readonly runId: (typeof runs)[number]["id"];
46
+ readonly startMs: number;
47
+ readonly endMs: number;
48
+} | null {
49
+ if (thread.deletedAt !== null || thread.archivedAt !== null) return null;
50
+ if (thread.settledAt !== null || thread.settledOverride === "settled") return null;
51
+ if (thread.snoozedUntil != null && DateTime.toEpochMillis(thread.snoozedUntil) > nowMs)
52
+ return null;
53
+ if (thread.lineage.relationshipToParent === "subagent") return null;
54
+ const latestRun = runs.reduce<(typeof runs)[number] | null>(
55
+ (latest, run) => (latest === null || run.ordinal > latest.ordinal ? run : latest),
56
+ null,
57
+ );
58
+ if (latestRun?.status !== "completed" || latestRun.completedAt === null) return null;
59
+ const message = messages.find((candidate) => candidate.id === latestRun.userMessageId);
60
+ // Never compact a compaction, so one idle spell compacts at most once.
61
+ if (message === undefined || message.text.trim().toLowerCase() === "/compact") return null;
62
+ if (
63
+ runtimeRequests.some((request) => request.status === "pending") ||
64
+ // A pending merge-back belongs to the user's next message.
65
+ contextTransfers.some(
66
+ (transfer) =>
67
+ transfer.type === "merge_back" &&
68
+ transfer.targetThreadId === thread.id &&
69
+ transfer.status === "pending",
70
+ ) ||
71
+ // Background work reports into the next turn; compaction would swallow it.
72
+ derivePendingBackgroundWork({
73
+ latestRun,
74
+ runs,
75
+ providerThreads,
76
+ turnItems,
77
+ activeProviderThreadId: thread.activeProviderThreadId,
78
+ }).length > 0
79
+ )
80
+ return null;
81
+ const providerThread = providerThreads.find(
82
+ (candidate) => candidate.id === thread.activeProviderThreadId,
83
+ );
84
+ // The thread's current selection receives the /compact, so it must still be this Claude session.
85
+ if (
86
+ providerThread?.driver !== "claudeAgent" ||
87
+ providerThread.id !== latestRun.providerThreadId ||
88
+ providerThread.providerInstanceId !== thread.providerInstanceId ||
89
+ latestRun.providerInstanceId !== thread.providerInstanceId
90
+ )
91
+ return null;
92
+ const usages = providerTurns
93
+ .filter((turn) => turn.providerThreadId === providerThread.id && turn.tokenUsage !== undefined)
94
+ .map((turn) => turn.tokenUsage!)
95
+ .toSorted((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt));
96
+ if ((usages[0]?.usedTokens ?? 0) < MIN_CONTEXT_TOKENS) return null;
97
+ // A request served fully from cache creates no cache entry and reports no
98
+ // TTL, but it still refreshes the cache. Treat it as unknown and skip.
99
+ const expiresAt = usages[0]?.promptCacheExpiresAt;
100
+ const endMs = expiresAt === undefined ? Number.NaN : Date.parse(expiresAt);
101
+ if (!Number.isFinite(endMs) || nowMs >= endMs) return null;
102
+ return { runId: latestRun.id, startMs: endMs - LEAD_MS, endMs };
103
+}
apps/server/src/orchestration-v2/IdleCompactionService.ts
new
+97
@@ -0,0 +1,97 @@
1
+import {
2
+ CommandId,
3
+ MessageId,
4
+ resolveProjectProviderInstanceEnabled,
5
+ type RunId,
6
+ type ThreadId,
7
+} from "@t3tools/contracts";
8
+import * as DateTime from "effect/DateTime";
9
+import * as Duration from "effect/Duration";
10
+import * as Effect from "effect/Effect";
11
+import * as FiberMap from "effect/FiberMap";
12
+import * as Stream from "effect/Stream";
13
+
14
+import { forkParked } from "../serverActivation.ts";
15
+import * as ServerSettings from "../serverSettings.ts";
16
+import { idleCompactionWindow } from "./IdleCompaction.ts";
17
+import * as Orchestrator from "./Orchestrator.ts";
18
+import * as ProjectionStore from "./ProjectionStore.ts";
19
+
20
+/**
21
+ * Beta: when a Claude run completes, waits until shortly before its prompt
22
+ * cache expires and sends `/compact` as a visible T3 Code turn. Timers live in
23
+ * memory, so a server restart skips compactions that were still waiting.
24
+ */
25
+export const make = Effect.gen(function* () {
26
+ const orchestrator = yield* Orchestrator.OrchestratorV2;
27
+ const projections = yield* ProjectionStore.ProjectionStoreV2;
28
+ const settings = yield* ServerSettings.ServerSettingsService;
29
+
30
+ const compactWhenDue = Effect.fn("IdleCompactionService.compactWhenDue")(
31
+ function* (threadId: ThreadId, runId: RunId) {
32
+ // Loops once after the wait: the thread may have moved on.
33
+ while (true) {
34
+ const current = yield* settings.getSettings;
35
+ if (!current.compactIdleThreads) return;
36
+ const records = yield* projections.getThreadRecords(
37
+ threadId,
38
+ [
39
+ "runs",
40
+ "messages",
41
+ "providerThreads",
42
+ "providerTurns",
43
+ "runtimeRequests",
44
+ "turnItems",
45
+ "contextTransfers",
46
+ ],
47
+ { messageRunIds: [runId], turnItemStatuses: ["pending", "running", "waiting"] },
48
+ );
49
+ if (
50
+ !resolveProjectProviderInstanceEnabled(
51
+ current,
52
+ records.thread.projectId,
53
+ records.thread.providerInstanceId,
54
+ )
55
+ )
56
+ return;
57
+ const nowMs = DateTime.toEpochMillis(yield* DateTime.now);
58
+ const window = idleCompactionWindow(records, nowMs);
59
+ if (window?.runId !== runId) return;
60
+ if (nowMs < window.startMs) {
61
+ yield* Effect.sleep(Duration.millis(window.startMs - nowMs));
62
+ continue;
63
+ }
64
+ yield* orchestrator.dispatch({
65
+ type: "message.dispatch",
66
+ // One compaction per completed run, even across duplicate events.
67
+ commandId: CommandId.make(`server:idle-compact:${threadId}:${runId}`),
68
+ messageId: MessageId.make(`idle-compact:${threadId}:${runId}`),
69
+ threadId,
70
+ text: "/compact",
71
+ attachments: [],
72
+ createdBy: "agent",
73
+ creationSource: "server",
74
+ dispatchMode: { type: "start_immediately" },
75
+ });
76
+ return;
77
+ }
78
+ },
79
+ (effect, threadId) =>
80
+ effect.pipe(
81
+ Effect.catch((cause) => Effect.logWarning("idle compaction skipped", { threadId, cause })),
82
+ ),
83
+ );
84
+
85
+ const start = Effect.fn("IdleCompactionService.start")(function* () {
86
+ // Keyed by thread: a newer completed run replaces the waiting timer.
87
+ const timers = yield* FiberMap.make<ThreadId>();
88
+ yield* forkParked(
89
+ Stream.runForEach(orchestrator.streamDomainEvents, (event) =>
90
+ event.type === "run.updated" && event.payload.status === "completed"
91
+ ? FiberMap.run(timers, event.threadId, compactWhenDue(event.threadId, event.payload.id))
92
+ : Effect.void,
93
+ ),
94
+ );
95
+ });
96
+ return { start };
97
+});
apps/server/src/server.ts
+6
@@ -175,6 +175,7 @@ import * as RuntimeLayer from "./orchestration-v2/runtimeLayer.ts";
175
import * as ProjectStore from "./orchestration-v2/ProjectStore.ts";
176
import * as ThreadSearch from "./orchestration-v2/ThreadSearch.ts";
177
import * as ThreadSettlementService from "./orchestration-v2/ThreadSettlementService.ts";
178
+import * as IdleCompactionService from "./orchestration-v2/IdleCompactionService.ts";
179
import * as ThreadPullRequestService from "./orchestration-v2/ThreadPullRequestService.ts";
180
import * as RunFinalizationService from "./orchestration-v2/RunFinalizationService.ts";
181
import * as EventStoreV2 from "./orchestration-v2/EventStore.ts";
@@ -516,6 +517,10 @@ const layerThreadSettlementWorker = Layer.effectDiscard(
517
ThreadSettlementService.make.pipe(Effect.flatMap((service) => service.start())),
518
).pipe(Layer.provide(layerPullRequestService), Layer.provide(ProjectionStoreV2.layer));
519
520
+const layerIdleCompactionWorker = Layer.effectDiscard(
521
+ IdleCompactionService.make.pipe(Effect.flatMap((service) => service.start())),
522
+).pipe(Layer.provide(ProjectionStoreV2.layer));
523
+
524
const layerThreadPullRequestWorker = Layer.effectDiscard(
525
ThreadPullRequestService.make.pipe(Effect.flatMap((service) => service.start())),
526
).pipe(Layer.provide(layerPullRequestService));
@@ -556,6 +561,7 @@ const layerRuntimeCoreDependenciesBase = Layer.mergeAll(
561
AgentAwarenessRelay.layer,
562
HeldHooksWaker.layer,
563
layerThreadSettlementWorker,
564
+ layerIdleCompactionWorker,
565
StorageCleanup.layer.pipe(Layer.provide(ProjectionStoreV2.layer)),
566
DatabaseStorage.layer.pipe(
567
Layer.provide(ProjectionMaintenance.layer),
apps/web/src/components/chat/ContextWindowMeter.logic.test.ts
+3
-3
@@ -143,11 +143,11 @@ describe("formatContextWindowCompactionMessage", () => {
143
describe("shouldOfferResumeCompaction", () => {
144
const now = "2026-08-24T12:00:00.000Z";
145
146
- it("matches Claude's old-session age and context thresholds", () => {
146
+ it("offers compaction for old sessions from 200k tokens", () => {
147
expect(
148
shouldOfferResumeCompaction({
149
provider: "claudeAgent",
150
- usedTokens: 100_000,
150
+ usedTokens: 200_000,
151
updatedAt: "2026-08-24T10:50:00.000Z",
152
now,
153
}),
@@ -158,7 +158,7 @@ describe("shouldOfferResumeCompaction", () => {
158
expect(
159
shouldOfferResumeCompaction({
160
provider: "claudeAgent",
161
- usedTokens: 99_999,
161
+ usedTokens: 199_999,
162
updatedAt: "2026-08-24T10:00:00.000Z",
163
now,
164
}),
apps/web/src/components/chat/ContextWindowMeter.logic.ts
+2
-2
@@ -1,6 +1,7 @@
1
import type { ModelSelection, ProviderDriverKind, ProviderInstanceId } from "@t3tools/contracts";
2
import {
3
CLAUDE_RESUME_COMPACTION_NEVER_ANSWER,
4
+ COMPACTION_SUGGESTION_MIN_TOKENS,
5
isClaudeResumeCompactionQuestion,
6
} from "@t3tools/shared/claudeCompaction";
7
import {
@@ -11,7 +12,6 @@ import { getTriggerDisplayModelName, type ModelEsque } from "./providerIconUtils
12
13
// Used when the provider did not report its cache TTL: Claude's 1h cache plus slack.
14
const CLAUDE_RESUME_COMPACTION_FALLBACK_MS = 70 * 60_000;
14
-const CLAUDE_RESUME_COMPACTION_TOKENS = 100_000;
15
16
export function providerSupportsManualCompaction(
17
provider: ProviderInstanceEntry | null | undefined,
@@ -70,7 +70,7 @@ export function shouldOfferResumeCompaction(input: {
70
}): boolean {
71
if (
72
input.provider !== "claudeAgent" ||
73
- (input.usedTokens ?? 0) < CLAUDE_RESUME_COMPACTION_TOKENS
73
+ (input.usedTokens ?? 0) < COMPACTION_SUGGESTION_MIN_TOKENS
74
) {
75
return false;
76
}
apps/web/src/components/settings/SettingsPanels.tsx
+29
@@ -2303,6 +2303,35 @@ export function GeneralSettingsPanel() {
2303
}
2304
/>
2305
2306
+ <SettingsRow
2307
+ serverScoped
2308
+ settingKeys={["compactIdleThreads"]}
2309
+ {...searchableSetting("compact-idle-threads")}
2310
+ description="Compact long idle Claude threads just before their prompt cache expires, so coming back costs less."
2311
+ resetAction={
2312
+ settings.compactIdleThreads !== DEFAULT_UNIFIED_SETTINGS.compactIdleThreads ? (
2313
+ <SettingResetButton
2314
+ label="compact idle Claude threads"
2315
+ onClick={() =>
2316
+ updateSettings({
2317
+ compactIdleThreads: DEFAULT_UNIFIED_SETTINGS.compactIdleThreads,
2318
+ })
2319
+ }
2320
+ />
2321
+ ) : null
2322
+ }
2323
+ control={
2324
+ <ScopedSwitch
2325
+ settingKeys={["compactIdleThreads"]}
2326
+ checked={settings.compactIdleThreads}
2327
+ onCheckedChange={(checked) =>
2328
+ updateSettings({ compactIdleThreads: Boolean(checked) })
2329
+ }
2330
+ aria-label="Compact idle Claude threads (beta)"
2331
+ />
2332
+ }
2333
+ />
2334
+
2335
{supportsAutoSettlement ? (
2336
<>
2337
<SettingsRow
apps/web/src/components/settings/settingsSearch.ts
+7
@@ -336,6 +336,13 @@ export const SETTINGS_SEARCH_ITEMS = [
336
requiresThreadAutoSettlement: true,
337
scope: "project-defaults",
338
},
339
+ {
340
+ id: "compact-idle-threads",
341
+ title: "Compact idle Claude threads (beta)",
342
+ to: "/settings/general",
343
+ scope: "environment-defaults",
344
+ searchTerms: ["context compaction idle cache tokens usage summary beta experimental"],
345
+ },
346
{
347
id: "auto-settle-merged-threads",
348
title: "Auto-settle merged threads",
docs/user/composer.md
+6
@@ -239,6 +239,12 @@ Provider commands must start the message to run. T3 Code commands such as
239
Send `/compact` in an existing conversation to reduce context usage when the
240
provider supports it. Web and desktop also offer compaction from the context meter.
241
242
+Enable **Compact idle Claude threads (beta)** in **Settings > General** to compact
243
+an idle Claude thread with at least 200,000 tokens of context shortly before its
244
+prompt cache expires, so coming back does not reprocess the whole conversation.
245
+The cache lasts 1 hour on Claude subscriptions and 5 minutes with an API key. The
246
+compaction appears in the thread as a `/compact` turn sent by T3 Code.
247
+
248
## Goals
249
250
With Codex and Claude, send `/goal` followed by what "done" means, for example
packages/contracts/src/orchestrationV2.ts
+1
@@ -172,6 +172,7 @@ export const OrchestrationV2ProviderTurnTokenUsage = Schema.Struct({
172
reasoningOutputTokens: Schema.optional(NonNegativeInt),
173
promptCacheTtlMs: Schema.optional(PositiveInt),
174
autoCompactThreshold: Schema.optional(PositiveInt),
175
+ promptCacheExpiresAt: Schema.optional(Schema.String),
176
updatedAt: Schema.String,
177
});
178
export type OrchestrationV2ProviderTurnTokenUsage =
packages/contracts/src/settings.ts
+2
@@ -1158,6 +1158,7 @@ export const ServerSettings = Schema.Struct({
1158
sidebarAutoSettleAfterDays: Schema.NullOr(SidebarAutoSettleAfterDays).pipe(
1159
Schema.withDecodingDefault(Effect.succeed(DEFAULT_SIDEBAR_AUTO_SETTLE_AFTER_DAYS)),
1160
),
1161
+ compactIdleThreads: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
1162
snoozeLimitedThreads: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
1163
autoResumeLimitedThreads: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
1164
sidebarAutoSettleKeepPullRequests: Schema.Boolean.pipe(
@@ -1471,6 +1472,7 @@ export const ServerSettingsPatch = Schema.Struct({
1472
deviceOnboardingCompleted: Schema.optionalKey(Schema.Boolean),
1473
deviceHosts: Schema.optionalKey(SshDeviceHostConfigs),
1474
sidebarAutoSettleAfterDays: Schema.optionalKey(Schema.NullOr(SidebarAutoSettleAfterDays)),
1475
+ compactIdleThreads: Schema.optionalKey(Schema.Boolean),
1476
sidebarAutoSettleKeepPullRequests: Schema.optionalKey(Schema.Boolean),
1477
sidebarAutoSettleOnMerge: Schema.optionalKey(Schema.Boolean),
1478
autoResumeLimitedThreads: Schema.optionalKey(Schema.Boolean),
packages/shared/src/claudeCompaction.ts
+7
@@ -24,3 +24,10 @@ const CLAUDE_RESUME_COMPACTION_QUESTION_PATTERN =
24
export function isClaudeResumeCompactionQuestion(question: string): boolean {
25
return CLAUDE_RESUME_COMPACTION_QUESTION_PATTERN.test(question);
26
}
27
+
28
+/**
29
+ * Context size below which T3 does not suggest or run a Claude compaction:
30
+ * the stale-thread Compact chip and idle compaction. Matches Claude Code's
31
+ * idleCompaction default of 200K.
32
+ */
33
+export const COMPACTION_SUGGESTION_MIN_TOKENS = 200_000;