@devries-cameron20 / t3code Mirror · read-only / commits / 5d3875d703
Fork 0

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;