Skip to content

Commit d13fc84

Browse files
feat(claude): idle compaction has a global default and per-instance overrides (#23037)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent e749245 commit d13fc84

10 files changed

Lines changed: 154 additions & 23 deletions

File tree

‎apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,7 @@ import {
9797
type ProviderThreadId,
9898
type RunId,
9999
type ThreadId,
100+
resolveIdleCompaction,
100101
} from "@t3tools/contracts";
101102

102103
import * as Cause from "effect/Cause";
@@ -133,6 +134,7 @@ import {
133134
type CompiledClaudeModelSelection,
134135
} from "../../claudeModelOptions.ts";
135136
import * as ServerConfig from "../../config.ts";
137+
import * as ServerSettings from "../../serverSettings.ts";
136138
import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion";
137139
import { spawnAndCollect } from "@t3tools/provider-core/server/snapshotProbe";
138140
import { signalProcessGroup } from "@t3tools/provider-core/server/processGroup";
@@ -3886,6 +3888,7 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
38863888
adapterOptions: ClaudeAdapterV2Options,
38873889
) {
38883890
const mcpSessions = yield* McpProviderSessions.McpProviderSessions;
3891+
const serverSettings = yield* Effect.serviceOption(ServerSettings.ServerSettingsService);
38893892
const { attachmentsDir, fileSystem, path, crypto, idAllocator, queryRunner } = adapterOptions;
38903893
const subagentModelCatalog = scopeClaudeModelCatalog(
38913894
BUNDLED_CLAUDE_MODEL_CATALOG,
@@ -9036,6 +9039,17 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
90369039
if (request.dialogKind !== "resume_return") {
90379040
return { behavior: "cancelled" as const };
90389041
}
9042+
const idleCompaction = Option.isSome(serverSettings)
9043+
? yield* serverSettings.value.getSettings.pipe(
9044+
Effect.map((settings) =>
9045+
resolveIdleCompaction(settings, adapterOptions.instanceId),
9046+
),
9047+
Effect.orElseSucceed(() => adapterOptions.settings.idleCompaction),
9048+
)
9049+
: adapterOptions.settings.idleCompaction;
9050+
if (idleCompaction === "off") {
9051+
return { behavior: "completed" as const, result: "continue" as const };
9052+
}
90399053
const ageMinutes =
90409054
typeof request.payload.sessionAgeMinutes === "number" &&
90419055
Number.isFinite(request.payload.sessionAgeMinutes)

‎apps/server/src/orchestration-v2/IdleCompactionService.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import {
22
CommandId,
33
MessageId,
4+
resolveIdleCompaction,
45
resolveProjectProviderInstanceEnabled,
56
type RunId,
67
type ThreadId,
@@ -18,8 +19,9 @@ import * as Orchestrator from "./Orchestrator.ts";
1819
import * as ProjectionStore from "./ProjectionStore.ts";
1920

2021
/**
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
22+
* Beta: when a run completes on a Claude instance set to compact before the
23+
* cache expires, waits until shortly before its prompt cache expires and sends
24+
* `/compact` as a visible T3 Code turn. Timers live in
2325
* memory, so a server restart skips compactions that were still waiting.
2426
*/
2527
export const make = Effect.gen(function* () {
@@ -32,7 +34,6 @@ export const make = Effect.gen(function* () {
3234
// Loops once after the wait: the thread may have moved on.
3335
while (true) {
3436
const current = yield* settings.getSettings;
35-
if (!current.compactIdleThreads) return;
3637
const records = yield* projections.getThreadRecords(
3738
threadId,
3839
[
@@ -47,6 +48,8 @@ export const make = Effect.gen(function* () {
4748
{ messageRunIds: [runId], turnItemStatuses: ["pending", "running", "waiting"] },
4849
);
4950
if (
51+
resolveIdleCompaction(current, records.thread.providerInstanceId) !==
52+
"beforeCacheExpires" ||
5053
!resolveProjectProviderInstanceEnabled(
5154
current,
5255
records.thread.projectId,

‎apps/server/src/provider/ProviderInstanceRegistry.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,7 @@ const makeClaudeConfig = (overrides: Partial<ClaudeSettings>): ClaudeSettings =>
9797
customModels: [],
9898
launchArgs: "",
9999
autoCompactWindow: "",
100+
idleCompaction: "default",
100101
...overrides,
101102
});
102103

‎apps/web/src/components/ChatView.tsx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ import {
7070
type RunId,
7171
type RunAttemptId,
7272
ProviderInteractionMode,
73+
resolveIdleCompaction,
7374
RuntimeMode,
7475
} from "@t3tools/contracts";
7576
import { deriveThreadTitleSeed } from "@t3tools/client-runtime/operations";
@@ -4011,6 +4012,10 @@ export default function ChatView(props: ChatViewProps) {
40114012
: null;
40124013
const resumeCompactionTokens =
40134014
activeContextWindow &&
4015+
resolveIdleCompaction(
4016+
settings,
4017+
activeProviderInstanceId ?? ProviderInstanceId.make("claudeAgent"),
4018+
) !== "off" &&
40144019
!resumeCompactionPermanentlyDismissed &&
40154020
!nativeResumeCompactionDismissed &&
40164021
!compactDisabled &&

‎apps/web/src/components/settings/SettingsPanels.tsx‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import { Link, useNavigate } from "@tanstack/react-router";
66
import { useEffect, useRef, useState } from "react";
77
import {
88
type DesktopUpdateChannel,
9+
IDLE_COMPACTION_MODES,
910
ProviderDriverKind,
1011
type ProviderInstanceId,
1112
type SidebarProjectGroupingMode,
@@ -997,11 +998,11 @@ export function GeneralSettingsPanel() {
997998
serverScoped
998999
settingKeys={["compactIdleThreads"]}
9991000
{...searchableSetting("compact-idle-threads")}
1000-
description="Compact long idle Claude threads just before their prompt cache expires, so coming back costs less."
1001+
description="When to compact an idle Claude thread over 200,000 tokens: after you return, just before its prompt cache expires, or never. Each Claude provider can override this."
10011002
resetAction={
10021003
settings.compactIdleThreads !== DEFAULT_UNIFIED_SETTINGS.compactIdleThreads ? (
10031004
<SettingResetButton
1004-
label="compact idle Claude threads"
1005+
label="compact idle threads"
10051006
onClick={() =>
10061007
updateSettings({
10071008
compactIdleThreads: DEFAULT_UNIFIED_SETTINGS.compactIdleThreads,
@@ -1011,14 +1012,29 @@ export function GeneralSettingsPanel() {
10111012
) : null
10121013
}
10131014
control={
1014-
<ScopedSwitch
1015-
settingKeys={["compactIdleThreads"]}
1016-
checked={settings.compactIdleThreads}
1017-
onCheckedChange={(checked) =>
1018-
updateSettings({ compactIdleThreads: Boolean(checked) })
1019-
}
1020-
aria-label="Compact idle Claude threads (beta)"
1021-
/>
1015+
<Select
1016+
value={settings.compactIdleThreads}
1017+
onValueChange={(value) => {
1018+
const mode = IDLE_COMPACTION_MODES.find((candidate) => candidate.value === value);
1019+
if (mode) updateSettings({ compactIdleThreads: mode.value });
1020+
}}
1021+
>
1022+
<SelectTrigger size="sm" className="w-full sm:w-56" aria-label="Compact idle threads">
1023+
<SelectValue>
1024+
{
1025+
IDLE_COMPACTION_MODES.find((mode) => mode.value === settings.compactIdleThreads)
1026+
?.label
1027+
}
1028+
</SelectValue>
1029+
</SelectTrigger>
1030+
<SelectPopup align="end" alignItemWithTrigger={false}>
1031+
{IDLE_COMPACTION_MODES.map((mode) => (
1032+
<SelectItem hideIndicator key={mode.value} value={mode.value}>
1033+
{mode.label}
1034+
</SelectItem>
1035+
))}
1036+
</SelectPopup>
1037+
</Select>
10221038
}
10231039
/>
10241040

‎apps/web/src/components/settings/settingsSearch.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -338,10 +338,10 @@ export const SETTINGS_SEARCH_ITEMS = [
338338
},
339339
{
340340
id: "compact-idle-threads",
341-
title: "Compact idle Claude threads (beta)",
341+
title: "Compact idle threads",
342342
to: "/settings/general",
343343
scope: "environment-defaults",
344-
searchTerms: ["context compaction idle cache tokens usage summary beta experimental"],
344+
searchTerms: ["claude context compaction idle cache tokens usage summary resume"],
345345
},
346346
{
347347
id: "auto-settle-merged-threads",

‎docs/user/composer.md‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -239,11 +239,8 @@ Provider commands must start the message to run. T3 Code commands such as
239239
Send `/compact` in an existing conversation to reduce context usage when the
240240
provider supports it. Web and desktop also offer compaction from the context meter.
241241

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.
242+
Claude instances can also compact idle threads for you. See
243+
[compact long conversations](./providers-claude.md#compact-long-conversations).
247244

248245
## Goals
249246

‎docs/user/providers-claude.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,16 @@ history for that message. The cache lasts about an hour on a Claude
5757
subscription and 5 minutes with an API key, Bedrock, or Vertex. See [commands and skills](./composer.md#commands-and-skills) for using
5858
composer commands.
5959

60+
**Compact idle threads** in **Settings > General** controls this for threads
61+
over 200,000 tokens. Each Claude provider's settings can override it:
62+
63+
- **When you return** shows the **Compact** chip described above. This is the default.
64+
- **Before the cache expires (beta)** compacts an idle thread shortly before its
65+
prompt cache expires, so coming back does not reprocess the whole conversation.
66+
The compaction appears in the thread as a `/compact` turn sent by T3 Code.
67+
- **Never** skips idle compaction and Claude's resume prompt. **Auto-compact after**
68+
still applies, and you can still compact by hand.
69+
6070
## Usage limits
6171

6272
If your Claude subscription runs out of usage mid-turn, the thread shows which

‎packages/contracts/src/settings.test.ts‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import {
99
ClaudeSettings,
1010
DEFAULT_SERVER_SETTINGS,
1111
requiredScopesForProjectMutation,
12+
resolveIdleCompaction,
1213
resolveProjectProviderInstanceEnabled,
1314
resolveProviderInstanceEnabled,
1415
ServerSettings,
@@ -134,6 +135,30 @@ describe("custom model settings", () => {
134135
});
135136
});
136137

138+
describe("resolveIdleCompaction", () => {
139+
it("lets a Claude instance override the global default", () => {
140+
const settings = decodeServerSettings({
141+
compactIdleThreads: "off",
142+
providerInstances: {
143+
claude_work: { driver: "claudeAgent", config: { idleCompaction: "onReturn" } },
144+
claude_personal: { driver: "claudeAgent" },
145+
},
146+
});
147+
expect(resolveIdleCompaction(settings, ProviderInstanceId.make("claude_work"))).toBe(
148+
"onReturn",
149+
);
150+
expect(resolveIdleCompaction(settings, ProviderInstanceId.make("claude_personal"))).toBe("off");
151+
expect(resolveIdleCompaction(settings, ProviderInstanceId.make("claudeAgent"))).toBe("off");
152+
});
153+
154+
it("keeps the legacy beta switch's behavior", () => {
155+
expect(decodeServerSettings({ compactIdleThreads: true }).compactIdleThreads).toBe(
156+
"beforeCacheExpires",
157+
);
158+
expect(decodeServerSettings({}).compactIdleThreads).toBe("onReturn");
159+
});
160+
});
161+
137162
describe("ClientSettings notifications", () => {
138163
it("requires opt-in when existing settings omit notification preferences", () => {
139164
expect(decodeClientSettings({}).notificationMode).toBe("off");

‎packages/contracts/src/settings.ts‎

Lines changed: 63 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import {
66
type AuthEnvironmentScope,
77
} from "./auth.ts";
88
import * as Effect from "effect/Effect";
9+
import * as Option from "effect/Option";
910
import * as Duration from "effect/Duration";
1011
import * as Schema from "effect/Schema";
1112
import * as SchemaTransformation from "effect/SchemaTransformation";
@@ -643,6 +644,34 @@ export type CodexSettings = typeof CodexSettings.Type;
643644

644645
const CLAUDE_AUTO_COMPACT_WINDOW_PATTERN = /^(?:|[1-9]\d{5}|1000000)$/;
645646

647+
export const IDLE_COMPACTION_MODES = [
648+
{ value: "onReturn", label: "When you return" },
649+
{ value: "beforeCacheExpires", label: "Before the cache expires (beta)" },
650+
{ value: "off", label: "Never" },
651+
] as const;
652+
export const IdleCompactionMode = Schema.Literals(IDLE_COMPACTION_MODES.map((mode) => mode.value));
653+
export type IdleCompactionMode = typeof IdleCompactionMode.Type;
654+
655+
// `compactIdleThreads` was a beta on/off switch for compacting before the cache expires.
656+
const LegacyCompactIdleThreads = Schema.Boolean.pipe(
657+
Schema.decodeTo(
658+
IdleCompactionMode,
659+
SchemaTransformation.transform({
660+
decode: (enabled): IdleCompactionMode => (enabled ? "beforeCacheExpires" : "onReturn"),
661+
encode: (mode) => mode === "beforeCacheExpires",
662+
}),
663+
),
664+
);
665+
const IdleCompactionModeSetting = Schema.Union([IdleCompactionMode, LegacyCompactIdleThreads]);
666+
667+
const INSTANCE_IDLE_COMPACTION_MODES = [
668+
{ value: "default", label: "Use default" },
669+
...IDLE_COMPACTION_MODES,
670+
] as const;
671+
const InstanceIdleCompaction = Schema.Literals(
672+
INSTANCE_IDLE_COMPACTION_MODES.map((mode) => mode.value),
673+
);
674+
646675
export const ClaudeSettings = makeProviderSettingsSchema(
647676
{
648677
enabled: Schema.Boolean.pipe(
@@ -694,9 +723,22 @@ export const ClaudeSettings = makeProviderSettingsSchema(
694723
},
695724
}),
696725
),
726+
idleCompaction: InstanceIdleCompaction.pipe(
727+
Schema.withDecodingDefault(Effect.succeed("default" as const)),
728+
Schema.annotateKey({
729+
title: "Compact idle threads",
730+
description:
731+
"When to compact an idle thread over 200,000 tokens: after you return, just before its prompt cache expires, or never. Overrides the default in General settings.",
732+
providerSettingsForm: {
733+
control: "select",
734+
options: INSTANCE_IDLE_COMPACTION_MODES,
735+
clearWhenEmpty: "omit",
736+
},
737+
}),
738+
),
697739
},
698740
{
699-
order: ["binaryPath", "homePath", "autoCompactWindow", "launchArgs"],
741+
order: ["binaryPath", "homePath", "autoCompactWindow", "idleCompaction", "launchArgs"],
700742
},
701743
);
702744
export type ClaudeSettings = typeof ClaudeSettings.Type;
@@ -1160,7 +1202,9 @@ export const ServerSettings = Schema.Struct({
11601202
sidebarAutoSettleAfterDays: Schema.NullOr(SidebarAutoSettleAfterDays).pipe(
11611203
Schema.withDecodingDefault(Effect.succeed(DEFAULT_SIDEBAR_AUTO_SETTLE_AFTER_DAYS)),
11621204
),
1163-
compactIdleThreads: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
1205+
compactIdleThreads: IdleCompactionModeSetting.pipe(
1206+
Schema.withDecodingDefault(Effect.succeed("onReturn" as const)),
1207+
),
11641208
snoozeLimitedThreads: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
11651209
autoResumeLimitedThreads: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
11661210
sidebarAutoSettleKeepPullRequests: Schema.Boolean.pipe(
@@ -1334,6 +1378,22 @@ export const resolveProjectProviderInstanceEnabled = (
13341378
: isUnconfiguredDefaultInstanceEnabled(instanceId);
13351379
};
13361380

1381+
const decodeClaudeSettings = Schema.decodeUnknownOption(ClaudeSettings);
1382+
1383+
export const resolveIdleCompaction = (
1384+
settings: Pick<ServerSettings, "providerInstances" | "compactIdleThreads">,
1385+
instanceId: ProviderInstanceId,
1386+
): IdleCompactionMode => {
1387+
const instance = Object.hasOwn(settings.providerInstances, instanceId)
1388+
? settings.providerInstances[instanceId]
1389+
: undefined;
1390+
const override = decodeClaudeSettings(instance?.config ?? {}).pipe(
1391+
Option.map((config) => config.idleCompaction),
1392+
Option.getOrElse(() => "default" as const),
1393+
);
1394+
return override === "default" ? settings.compactIdleThreads : override;
1395+
};
1396+
13371397
export const ServerSettingsOperation = Schema.Literals([
13381398
"normalize",
13391399
"check-exists",
@@ -1475,7 +1535,7 @@ export const ServerSettingsPatch = Schema.Struct({
14751535
deviceHosts: Schema.optionalKey(SshDeviceHostConfigs),
14761536
easDeviceHosts: Schema.optionalKey(EasDeviceHostConfigs),
14771537
sidebarAutoSettleAfterDays: Schema.optionalKey(Schema.NullOr(SidebarAutoSettleAfterDays)),
1478-
compactIdleThreads: Schema.optionalKey(Schema.Boolean),
1538+
compactIdleThreads: Schema.optionalKey(IdleCompactionMode),
14791539
sidebarAutoSettleKeepPullRequests: Schema.optionalKey(Schema.Boolean),
14801540
sidebarAutoSettleOnMerge: Schema.optionalKey(Schema.Boolean),
14811541
autoResumeLimitedThreads: Schema.optionalKey(Schema.Boolean),

0 commit comments

Comments
 (0)