Skip to content

A desktop coding agent with free access to frontier models.

TypeScript

feat: automatic context compaction

ogsamrat542e134a0650
diff --git a/apps/app/src/react-app/shell/app-root.tsx b/apps/app/src/react-app/shell/app-root.tsx
index a55e1758..6253bc75 100644
--- a/apps/app/src/react-app/shell/app-root.tsx
+++ b/apps/app/src/react-app/shell/app-root.tsx
@@ -30,6 +30,7 @@ import { OmniRushWebAccessGate } from "../domains/cloud/omnirush-web-access-gate
import { OrgOnboardingPage } from "../domains/cloud/org-onboarding-page";
import { NewProvidersListener } from "./new-providers-listener";
import { BudgetWrapConsent } from "./budget-wrap-consent";
+import { AutoCompactNotice } from "./auto-compact-notice";
import { useDesktopFontZoomBehavior } from "./font-zoom";
import { LoadingOverlay } from "./loading-overlay";
import { useVisualViewportInset } from "../../hooks/use-visual-viewport-inset";
@@ -396,6 +397,7 @@ export function AppRoot() {
<OmniRushRouteControlActions />
<OmniRushContextPublisher />
<BudgetWrapConsent />
+ <AutoCompactNotice />
<DenAuthControlActions />
<BrandThemeControlActions />
<EnterpriseActivationGate>
diff --git a/apps/app/src/react-app/shell/auto-compact-notice.tsx b/apps/app/src/react-app/shell/auto-compact-notice.tsx
new file mode 100644
index 00000000..a77c2674
--- /dev/null
+++ b/apps/app/src/react-app/shell/auto-compact-notice.tsx
@@ -0,0 +1,29 @@
+import { useMemo } from "react";
+
+import { toast } from "@/components/ui/sonner";
+import { useControlAction, type OmniRushControlAction } from "./control/control-provider";
+
+export const AUTO_COMPACT_NOTICE = "Compacting the conversation to keep it fast…";
+export const AUTO_COMPACT_FAILED_NOTICE = "Could not compact the conversation. Continuing as is.";
+
+/** The local server's automatic compaction (session-archive/auto-compact.ts): a short notice while a chat compacts. */
+export function AutoCompactNotice() {
+ const action = useMemo<OmniRushControlAction>(() => ({
+ id: "auto.compact.notice",
+ label: "Automatic compaction notice",
+ description: "Show that a chat is being compacted before its next prompt.",
+ // The server sends it through the query mailbox: no Control Mode, no visible action animation.
+ kind: "query",
+ sideEffect: "none",
+ requiresArgs: true,
+ execute: (args) => {
+ const stage = args && typeof args === "object" && "stage" in args ? args.stage : undefined;
+ if (stage === "started") toast.info(AUTO_COMPACT_NOTICE);
+ else if (stage === "failed") toast.warning(AUTO_COMPACT_FAILED_NOTICE);
+ else if (stage !== "finished") return { ok: false, error: "Unknown compaction stage" };
+ return { ok: true };
+ },
+ }), []);
+ useControlAction(action);
+ return null;
+}
diff --git a/apps/server/src/auto-compact-engine.ts b/apps/server/src/auto-compact-engine.ts
new file mode 100644
index 00000000..dd27ae64
--- /dev/null
+++ b/apps/server/src/auto-compact-engine.ts
@@ -0,0 +1,64 @@
+// The desktop's side of automatic compaction (session-archive/auto-compact.ts,
+// shared with the CLI): one chat's engine calls through the proxy's engine
+// target, and the server's policy read from /collect/capabilities.
+
+import { autoCompactPolicy, type AutoCompactEngine, type AutoCompactPolicy, type ModelRef } from "./session-archive/auto-compact.js";
+import { buildOpencodeProxyUrl, projectArchiveEngineReads, type EngineTarget } from "./session-upload-observer.js";
+import { loopbackFetch } from "./server-fetch.js";
+import type { TraceCapabilities } from "./session-uploader.js";
+
+/** How long an answer of the server counts for an ordinary prompt; a due compaction asks again. */
+export const POLICY_MAX_AGE_MS = 60_000;
+const FRESH_WAIT_MS = 4_000;
+
+type Fetch = (input: string, init: RequestInit) => Promise<Response>;
+
+/** The v1 engine `target` for `sessionId`. */
+export function desktopAutoCompactEngine(target: EngineTarget, sessionId: string, fetchImpl: Fetch = loopbackFetch): AutoCompactEngine {
+ const reads = projectArchiveEngineReads(target, sessionId);
+ return {
+ messages: () => reads.messages(),
+ session: () => reads.session(),
+ async busy() {
+ const response = await fetchImpl(buildOpencodeProxyUrl(target.baseUrl, "/session/status", target.search), {
+ headers: new Headers(target.headers),
+ signal: AbortSignal.timeout(5_000),
+ });
+ if (!response.ok) { await response.body?.cancel().catch(() => undefined); return null; }
+ const statuses = (await response.json()) as Record<string, { type?: string } | undefined>;
+ const type = statuses?.[sessionId]?.type ?? "idle";
+ return type === "busy" || type === "retry";
+ },
+ async summarize(model: ModelRef, signal: AbortSignal) {
+ const headers = new Headers(target.headers);
+ headers.set("content-type", "application/json");
+ const response = await fetchImpl(buildOpencodeProxyUrl(target.baseUrl, `/session/${encodeURIComponent(sessionId)}/summarize`, target.search), {
+ method: "POST",
+ headers,
+ body: JSON.stringify({ providerID: model.providerID, modelID: model.modelID }),
+ signal,
+ });
+ const text = await response.text().catch(() => "");
+ if (!response.ok) throw new Error(`summarize answered ${response.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
+ },
+ };
+}
+
+/**
+ * The server's policy through the broker's capabilities cache: at most
+ * POLICY_MAX_AGE_MS old for an ordinary prompt, asked again when `fresh`
+ * (bounded). A failed ask keeps the last policy seen; none ever is off.
+ */
+export function brokerAutoCompactPolicy(read: (options: { strict: true; maxAgeMs: number }) => Promise<TraceCapabilities>) {
+ let last: AutoCompactPolicy | null = null;
+ return async ({ fresh }: { fresh: boolean }): Promise<AutoCompactPolicy | null> => {
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const answer = await Promise.race([
+ read({ strict: true, maxAgeMs: fresh ? 0 : POLICY_MAX_AGE_MS }).then((capabilities) => ({ capabilities }), () => null),
+ new Promise<null>((resolve) => { timer = setTimeout(() => resolve(null), FRESH_WAIT_MS); }),
+ ]);
+ clearTimeout(timer);
+ if (answer) last = autoCompactPolicy(answer.capabilities);
+ return last;
+ };
+}
diff --git a/apps/server/src/capture-context.test.ts b/apps/server/src/capture-context.test.ts
index 7aef3e4b..2e7d1a14 100644
--- a/apps/server/src/capture-context.test.ts
+++ b/apps/server/src/capture-context.test.ts
@@ -844,12 +844,12 @@ test("CLI/desktop parity: the context modules match PARITY.sha256 (the same list
for (const name of files) assert.equal(createHash("sha256").update(fs.readFileSync(path.join(contextDir, name))).digest("hex"), listed.get(name), `${name} changed: port it to the CLI and update PARITY.sha256 in both`);
});
-test("CLI/desktop parity: the shared session-archive modules match their PARITY.sha256 (late writes, tool start, turn writers, turn prompts)", async () => {
+test("CLI/desktop parity: the shared session-archive modules match their PARITY.sha256 (auto compact, late writes, tool start, turn writers, turn prompts)", async () => {
const { createHash } = await import("node:crypto");
const dir = path.join(import.meta.dir, "session-archive");
const lines = fs.readFileSync(path.join(dir, "PARITY.sha256"), "utf8").split("\n").filter((line) => line && !line.startsWith("#"));
const listed = new Map(lines.map((line) => { const [hash, name] = line.split(/\s+/); return [name, hash]; }));
- assert.deepEqual([...listed.keys()].sort(), ["late-writes.ts", "tool-start.ts", "turn-overlap.ts", "turn-prompts.ts", "turn-writers.ts"]);
+ assert.deepEqual([...listed.keys()].sort(), ["auto-compact.ts", "late-writes.ts", "tool-start.ts", "turn-overlap.ts", "turn-prompts.ts", "turn-writers.ts"]);
for (const [name, hash] of listed) assert.equal(createHash("sha256").update(fs.readFileSync(path.join(dir, name))).digest("hex"), hash, `${name} changed: port it to the CLI and update PARITY.sha256 in both`);
});
diff --git a/apps/server/src/omnirush-gateway-broker.ts b/apps/server/src/omnirush-gateway-broker.ts
index 2a0dfc32..f1180148 100644
--- a/apps/server/src/omnirush-gateway-broker.ts
+++ b/apps/server/src/omnirush-gateway-broker.ts
@@ -1371,7 +1371,7 @@ export class OmniRushGatewayBroker {
* it reads as the oldest backend. Either way it is asked again after
* TRACE_CAPABILITY_RETRY_MS, not after the full TTL.
*/
- async sessionUploadCapabilities(options: { strict?: boolean } = {}): Promise<TraceCapabilities> {
+ async sessionUploadCapabilities(options: { strict?: boolean; maxAgeMs?: number } = {}): Promise<TraceCapabilities> {
const none: TraceCapabilities = { schema_versions: [1, 2], canonical_trace: false };
if (!this.state) {
if (options.strict) throw new Error("capabilities unavailable: signed out");
@@ -1380,9 +1380,11 @@ export class OmniRushGatewayBroker {
const state = this.state;
const gatewayUrl = state.gatewayUrl;
const key = this.capabilityKey(state);
+ // `maxAgeMs`: an answer older than that is asked again (the automatic compaction's check before it compacts).
if (this.capabilityCache?.gatewayUrl === gatewayUrl
&& this.capabilityCache.accountKey === key
- && this.capabilityCache.expiresAt > Date.now()) {
+ && this.capabilityCache.expiresAt > Date.now()
+ && (options.maxAgeMs === undefined || Date.now() - (this.capabilityCache.expiresAt - TRACE_CAPABILITY_TTL_MS) < options.maxAgeMs)) {
return this.capabilityCache.capabilities;
}
const failed = () => {
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 02c2334c..7f90ea66 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -205,6 +205,8 @@ import { startCaptureService, type CaptureService } from "./capture-client.js";
import type { LateWritesGate } from "./capture-host.js";
import { buildOpencodeProxyUrl, engineTarget, turnsBeforeCapture, type EngineTarget } from "./session-upload-observer.js";
import { claimSteerId, claimedSteerIds, createSteerTracker, steerRecord } from "./turn-steer.js";
+import { AutoCompactor, type AutoCompactOutcome } from "./session-archive/auto-compact.js";
+import { brokerAutoCompactPolicy, desktopAutoCompactEngine } from "./auto-compact-engine.js";
import { OmniRushGatewayBroker } from "./omnirush-gateway-broker.js";
import { awaitOmniRushModelCatalogSettled, startOmniRushModelCatalogSync } from "./omnirush-model-catalog-sync.js";
import { OmniRushVoiceService, voiceProjectContext } from "./omnirush-voice.js";
@@ -234,6 +236,16 @@ const agentDiagnosticsLastRunByServer = new WeakMap<ServerConfig, Map<string, nu
const agentDiagnosticsInFlightByServer = new WeakMap<ServerConfig, Set<string>>();
const commandAdmissionsByServer = new WeakMap<ServerConfig, Map<string, { fingerprint: string; admittedAt: number }>>();
const captureServicesByServer = new WeakMap<ServerConfig, CaptureService>();
+/** Automatic compaction (session-archive/auto-compact.ts), one per server: its counts live as long as the app. */
+const autoCompactorsByServer = new WeakMap<ServerConfig, AutoCompactor>();
+/**
+ * How long a prompt waits for its chat's automatic compaction: the window
+ * aborts a prompt request after 30 s, and the prompt's own capture steps
+ * may take up to about 13 s more. Past it the prompt goes out and the
+ * engine runs it right after the compaction.
+ */
+const AUTO_COMPACT_HOLD_MS = 10_000;
+const AUTO_COMPACT_SEED_WAIT_MS = 5_000;
const turnActivityByServer = new WeakMap<ServerConfig, TurnActivity>();
/** Whether the agent works on this server's engine (turn-activity.ts), for an embedding app that asked (onTurnActivity). */
@@ -1114,6 +1126,17 @@ export async function startServer(config: ServerConfig): Promise<ServeResult> {
});
},
});
+ // Automatic compaction: the server's policy (auto_compact) through the capabilities cache; the
+ // window shows a short notice (the "auto.compact.notice" query) while a chat compacts.
+ if (gatewayBroker.enabled) {
+ autoCompactorsByServer.set(config, new AutoCompactor({
+ policy: brokerAutoCompactPolicy((options) => gatewayBroker.sessionUploadCapabilities(options)),
+ holdMs: AUTO_COMPACT_HOLD_MS,
+ seedWaitMs: AUTO_COMPACT_SEED_WAIT_MS,
+ log: (level, message, attributes) => logger.log(level, message, attributes),
+ notify: (sessionID, stage) => { void uiControl.request("query", { id: "auto.compact.notice", args: { sessionID, stage } }); },
+ }));
+ }
if (gatewayBroker.enabled) sessionIntegrityByServer.set(config, (sessionId, options) => gatewayBroker.sessionIntegrity(sessionId, options));
voiceServicesByServer.set(config, new OmniRushVoiceService(gatewayBroker, {
log: (level, message, attributes) => logger.log(level, message, attributes),
@@ -2228,6 +2251,16 @@ export async function proxyOpencodeRequest(input: {
// and end snapshot behind.
const captured = Boolean(capture?.uploadEnabled && uploadedSessionId && workspace && workspace.workspaceType !== "remote"
&& (capture.hasSession(uploadedSessionId) || await engineHasSession(baseUrl, auth, directory, uploadedSessionId)));
+ // Automatic compaction (session-archive/auto-compact.ts): a chat with the server's number of prompts
+ // since its last compaction is compacted before this prompt (never mid-turn, never a sub-agent's chat).
+ const autoCompactor = workspace && workspace.workspaceType !== "remote" && uploadedSessionId && isUploadPromptDispatch(method, proxyPath)
+ ? autoCompactorsByServer.get(input.config)
+ : undefined;
+ if (autoCompactor && uploadedSessionId) {
+ const outcome = await autoCompactor.beforePrompt(uploadedSessionId, desktopAutoCompactEngine(engineTarget(baseUrl, headers, search), uploadedSessionId), body)
+ .catch((error: unknown): AutoCompactOutcome => ({ action: "failed", reason: error instanceof Error ? error.message : String(error) }));
+ if (outcome.action !== "none") createServerLogger(input.config).log("info", "Automatic compaction.", { "auto_compact.action": outcome.action, "auto_compact.reason": outcome.reason ?? "", "auto_compact.turns": outcome.turns ?? -1 });
+ }
// Steering (turn-steer.ts): a prompt sent while the agent works goes into
// the running turn, which the engine hands to the model at the agent's next
// step. Classified before anything is taken for it, with two small reads at
diff --git a/apps/server/src/session-archive/PARITY.sha256 b/apps/server/src/session-archive/PARITY.sha256
index 5fc34aaa..6572c3c0 100644
--- a/apps/server/src/session-archive/PARITY.sha256
+++ b/apps/server/src/session-archive/PARITY.sha256
@@ -1,7 +1,8 @@
# Session-archive modules that are the same files in omnirush-cli (assets/extensions/omnirush/capture/session-archive/)
# and omnirush-gui (apps/server/src/session-archive/). A change to one must be ported to the other and this list updated in both.
+4291c19235d4027c441b2787dcec31ed01fa3067ea6d33fbdc8177eab279684a auto-compact.ts
8fd84683b5542236f0c88750e3d9bd756e15a304d263141b57998b17c4a1ab9c late-writes.ts
4d9a13a5df136cd6e13d0aeb67983249ca4a6913b66c5a8f768daa63da511dda tool-start.ts
38dc65a461de6905134c22837f5230d03383ec0bdd6df35090dd269160446edf turn-overlap.ts
1906cab8c93370abd1d024d3552fe919a0006af9ebef084ada7b64c290d1bc95 turn-writers.ts
-402d175a7cffb8fdac490a97430b7590d72f4dde637e134e0a8de7c88ba06687 turn-prompts.ts
+55e5e322b2c372b77714eb3677bee6ea0f3e0a11120ba6edc7d202c264a3d7e8 turn-prompts.ts
diff --git a/apps/server/src/session-archive/auto-compact.test.ts b/apps/server/src/session-archive/auto-compact.test.ts
new file mode 100644
index 00000000..e0b7f47e
--- /dev/null
+++ b/apps/server/src/session-archive/auto-compact.test.ts
@@ -0,0 +1,100 @@
+// Automatic compaction (auto-compact.ts, byte-identical in the CLI and listed
+// in PARITY.sha256). The CLI's test/auto-compact.test.js covers the same
+// module; this checks the desktop's glue and the shared decisions.
+import { describe, expect, test } from "bun:test";
+
+import { brokerAutoCompactPolicy, desktopAutoCompactEngine } from "../auto-compact-engine.js";
+import { compactionSummary, workingOn } from "../turn-steer.js";
+import { AutoCompactor, autoCompactPolicy, RETRY_AFTER_TURNS, turnsSinceCompaction, type AutoCompactEngine, type ModelRef } from "./auto-compact.js";
+import { completedTurnCount, steerPrompts } from "./turn-prompts.js";
+
+const MODEL: ModelRef = { providerID: "omnirush", modelID: "astra" };
+const user = (id: string, created: number) => ({ info: { id, role: "user", time: { created }, model: MODEL }, parts: [{ type: "text", text: "do it" }] });
+const done = (id: string, created: number) => ({ info: { id, role: "assistant", time: { created, completed: created + 1 }, finish: "stop" }, parts: [] });
+const compactRequest = (id: string, created: number) => ({ info: { id, role: "user", time: { created }, model: MODEL }, parts: [{ type: "compaction", auto: false }] });
+const summary = (id: string, created: number, completed = created + 1) => ({ info: { id, role: "assistant", summary: true, mode: "compaction", agent: "compaction", time: { created, completed }, finish: "stop" }, parts: [] });
+const chat = (n: number) => Array.from({ length: n }, (_, i) => [user(`u${i}`, i * 100), done(`a${i}`, i * 100 + 10)]).flat();
+
+function engineOf(messages: () => unknown, { busy = false as boolean | null, parent = null as string | null, fail = false } = {}) {
+ const calls = { messages: 0, summarize: [] as ModelRef[] };
+ const engine: AutoCompactEngine = {
+ messages: async () => { calls.messages += 1; return messages(); },
+ session: async () => ({ id: "ses", ...(parent ? { parentID: parent } : {}) }),
+ busy: async () => busy,
+ summarize: async (model) => { calls.summarize.push(model); if (fail) throw new Error("summarize answered 500"); },
+ };
+ return { engine, calls };
+}
+
+describe("auto compaction", () => {
+ test("reads the policy; absent is off", () => {
+ expect(autoCompactPolicy({ auto_compact: { enabled: true, after_turns: 40, min_context_tokens: 0 } })).toEqual({ enabled: true, afterTurns: 40, minContextTokens: 0 });
+ expect(autoCompactPolicy({ schema_versions: [3] })).toBeNull();
+ });
+
+ test("counts prompts since the last compaction; a prompt behind a running compaction opens a turn", () => {
+ expect(turnsSinceCompaction([...chat(5), compactRequest("c", 600), summary("s", 601), user("u9", 700)])).toBe(1);
+ const queued = [user("u1", 0), done("a1", 10), compactRequest("c", 100), summary("s", 101, 900), user("u2", 500), done("a2", 1_000)];
+ expect(steerPrompts(queued).size).toBe(0);
+ expect(completedTurnCount(queued)).toBe(2);
+ expect(compactionSummary({ info: { role: "assistant", summary: true, time: { created: 1 } } })).toBe(true);
+ expect(workingOn({ info: { role: "assistant", mode: "compaction", time: { created: 1 } } })).toBe(false);
+ });
+
+ test("compacts a due chat before the prompt, on the prompt's model", async () => {
+ const compactor = new AutoCompactor({ policy: async () => ({ enabled: true, afterTurns: 3, minContextTokens: 0 }) });
+ const { engine, calls } = engineOf(() => chat(3));
+ const outcome = await compactor.beforePrompt("s", engine, new TextEncoder().encode(JSON.stringify({ parts: [], model: { providerID: "omnirush", modelID: "sol" } })).buffer);
+ expect(outcome.action).toBe("compacted");
+ expect(calls.summarize).toEqual([{ providerID: "omnirush", modelID: "sol" }]);
+ expect(calls.messages).toBe(1);
+ expect(compactor.count("s")).toBe(1);
+ });
+
+ test("off, busy, a sub-agent's chat: nothing; a failure is retried later", async () => {
+ const off = engineOf(() => chat(9));
+ expect((await new AutoCompactor({ policy: async () => ({ enabled: false, afterTurns: 3, minContextTokens: 0 }) }).beforePrompt("s", off.engine)).reason).toBe("off");
+ expect(off.calls.messages).toBe(0);
+ const policy = async () => ({ enabled: true, afterTurns: 3, minContextTokens: 0 });
+ const busy = engineOf(() => chat(9), { busy: true });
+ expect((await new AutoCompactor({ policy }).beforePrompt("s", busy.engine)).reason).toBe("busy");
+ const child = engineOf(() => chat(9), { parent: "root" });
+ expect((await new AutoCompactor({ policy }).beforePrompt("s", child.engine)).reason).toBe("sub_agent");
+ const failing = engineOf(() => chat(9), { fail: true });
+ const retry = new AutoCompactor({ policy });
+ expect((await retry.beforePrompt("s", failing.engine)).action).toBe("failed");
+ expect(retry.count("s")).toBe(Math.max(0, 3 - RETRY_AFTER_TURNS) + 1);
+ expect(busy.calls.summarize.length + child.calls.summarize.length).toBe(0);
+ });
+});
+
+describe("the desktop's glue", () => {
+ test("the broker policy: fresh asks with maxAgeMs 0, a failure keeps the last answer", async () => {
+ const asked: number[] = [];
+ let fail = false;
+ const policy = brokerAutoCompactPolicy(async ({ maxAgeMs }) => {
+ asked.push(maxAgeMs);
+ if (fail) throw new Error("down");
+ return { schema_versions: [3], canonical_trace: true, auto_compact: { enabled: true, after_turns: 40 } };
+ });
+ expect((await policy({ fresh: false }))?.afterTurns).toBe(40);
+ fail = true;
+ expect((await policy({ fresh: true }))?.afterTurns).toBe(40);
+ expect(asked).toEqual([60_000, 0]);
+ });
+
+ test("the engine calls go to the target with its scope and auth", async () => {
+ const seen: { url: string; method: string; auth: string | null; body?: string }[] = [];
+ const fetchImpl = async (url: string, init: RequestInit) => {
+ const headers = new Headers(init.headers);
+ seen.push({ url, method: init.method ?? "GET", auth: headers.get("authorization"), ...(init.body ? { body: String(init.body) } : {}) });
+ if (url.includes("/session/status")) return Response.json({ ses_1: { type: "busy" } });
+ return Response.json(true);
+ };
+ const engine = desktopAutoCompactEngine({ baseUrl: "http://127.0.0.1:4096", headers: [["authorization", "Basic x"]], search: "?directory=%2Fw", engine: "v1" }, "ses_1", fetchImpl);
+ expect(await engine.busy()).toBe(true);
+ await engine.summarize(MODEL, new AbortController().signal);
+ expect(seen[0]).toEqual({ url: "http://127.0.0.1:4096/session/status?directory=%2Fw", method: "GET", auth: "Basic x" });
+ expect(seen[1]).toEqual({ url: "http://127.0.0.1:4096/session/ses_1/summarize?directory=%2Fw", method: "POST", auth: "Basic x", body: JSON.stringify(MODEL) });
+ });
+});
diff --git a/apps/server/src/session-archive/auto-compact.ts b/apps/server/src/session-archive/auto-compact.ts
new file mode 100644
index 00000000..c56e18b9
--- /dev/null
+++ b/apps/server/src/session-archive/auto-compact.ts
@@ -0,0 +1,357 @@
+/**
+ * Automatic compaction: a chat that has had `after_turns` prompts since its
+ * last compaction is compacted by the engine (its own /summarize, the same
+ * compaction a person gets from /compact) before the next prompt goes out.
+ * The same file ships in omnirush-cli and omnirush-gui (PARITY.sha256).
+ *
+ * The server decides: GET /collect/capabilities `auto_compact`
+ * ({enabled, after_turns, min_context_tokens}). No block, or enabled false,
+ * and nothing happens. The policy is read again right before a compaction,
+ * so switching it off on the server stops the next one.
+ *
+ * Counting: per chat, the prompts sent since its last compaction. The first
+ * prompt of a chat in this app run reads the chat once to start the count;
+ * later prompts only add one. The count is an upper bound (a compaction the
+ * person or the engine ran in between resets it only on the next read): a
+ * compaction is decided on the chat's messages read again at that point.
+ *
+ * Never mid-turn: only a chat the engine reports idle is compacted, and the
+ * caller asks only for a prompt that opens a turn (not a steer). Sub-agent
+ * chats are never compacted on their own. A failed compaction is tried
+ * again RETRY_AFTER_TURNS prompts later; the prompt goes out regardless.
+ *
+ * The prompt waits for the compaction at most `holdMs`; past that it goes
+ * out and the engine runs it right after the compaction.
+ */
+import { isPromptMessage, steerPrompts } from "./turn-prompts.js";
+
+export const AUTO_COMPACT_NOTICE = "Compacting the conversation to keep it fast…";
+export const AUTO_COMPACT_FAILED_NOTICE = "Could not compact the conversation. Continuing as is.";
+/** A compaction that failed (or was skipped for a reason that may pass) is tried again this many prompts later. */
+export const RETRY_AFTER_TURNS = 5;
+/** How long the first prompt of a chat waits for the read that starts its count. */
+export const SEED_WAIT_MS = 10_000;
+/** The longest a compaction may run before it counts as failed. */
+export const COMPACTION_TIMEOUT_MS = 10 * 60_000;
+
+export type AutoCompactPolicy = { enabled: boolean; afterTurns: number; minContextTokens: number };
+export type ModelRef = { providerID: string; modelID: string };
+
+/** One chat's engine, as the caller reaches it. Each read resolves null (or throws) when it cannot be read. */
+export type AutoCompactEngine = {
+ /** The chat's messages in the engine's order. */
+ messages(): Promise<unknown>;
+ /** The chat's record (its parentID marks a sub-agent's chat). */
+ session(): Promise<unknown>;
+ /** Whether the engine is running the chat now; null when unknown. */
+ busy(): Promise<boolean | null>;
+ /** Runs the engine's compaction on `model`; resolves once it finished, rejects when it failed. */
+ summarize(model: ModelRef, signal: AbortSignal): Promise<void>;
+};
+
+export type AutoCompactStage = "started" | "finished" | "failed";
+
+export type AutoCompactorOptions = {
+ /** The server's policy (null: none, off). `fresh`: ask the server again rather than a cached answer. */
+ policy(options: { fresh: boolean }): Promise<AutoCompactPolicy | null>;
+ notify?(sessionId: string, stage: AutoCompactStage): void;
+ log?(level: "info" | "warn", message: string, attributes?: Record<string, unknown>): void;
+ /** How long a prompt waits for its chat's compaction before it goes out anyway (Infinity: until it ends). */
+ holdMs?: number;
+ seedWaitMs?: number;
+ timeoutMs?: number;
+};
+
+export type AutoCompactOutcome = {
+ action: "none" | "compacted" | "queued" | "failed" | "skipped";
+ reason?: string;
+ turns?: number;
+};
+
+type Json = Record<string, unknown>;
+
+function isRecord(value: unknown): value is Json {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function infoOf(message: Json): Json {
+ return isRecord(message.info) ? message.info : message;
+}
+
+function finiteInt(value: unknown): number | null {
+ return typeof value === "number" && Number.isInteger(value) ? value : null;
+}
+
+/** The `auto_compact` block of a /collect/capabilities answer; null when absent or unreadable (off). */
+export function autoCompactPolicy(capabilities: unknown): AutoCompactPolicy | null {
+ if (!isRecord(capabilities) || !isRecord(capabilities.auto_compact)) return null;
+ const block = capabilities.auto_compact;
+ const afterTurns = finiteInt(block.after_turns);
+ if (typeof block.enabled !== "boolean" || afterTurns === null || afterTurns < 2) return null;
+ const floor = finiteInt(block.min_context_tokens);
+ return { enabled: block.enabled, afterTurns, minContextTokens: floor !== null && floor > 0 ? floor : 0 };
+}
+
+/** An assistant message that is a compaction's summary (the engine's compaction agent). */
+export function isCompactionSummary(message: unknown): boolean {
+ if (!isRecord(message)) return false;
+ const info = infoOf(message);
+ if (info.role !== "assistant") return false;
+ return info.summary === true || info.mode === "compaction" || info.agent === "compaction";
+}
+
+/**
+ * Turns opened since the chat's last compaction (one that produced its
+ * summary without an error): prompts someone sent, not steers, not the
+ * engine's own messages. Null when the list could not be read.
+ */
+export function turnsSinceCompaction(messages: unknown): number | null {
+ if (!Array.isArray(messages)) return null;
+ const steers = steerPrompts(messages);
+ let turns = 0;
+ messages.forEach((message, index) => {
+ if (!isRecord(message)) return;
+ if (isCompactionSummary(message)) {
+ if (infoOf(message).error == null) turns = 0;
+ return;
+ }
+ if (!isPromptMessage(message)) return;
+ const id = infoOf(message).id;
+ if (!steers.has(typeof id === "string" ? id : index)) turns += 1;
+ });
+ return turns;
+}
+
+/** The context the chat's newest answered step used (input, cache and output tokens); null when none says. */
+export function lastContextTokens(messages: unknown): number | null {
+ if (!Array.isArray(messages)) return null;
+ for (let index = messages.length - 1; index >= 0; index -= 1) {
+ const message = messages[index];
+ if (!isRecord(message) || isCompactionSummary(message)) continue;
+ const info = infoOf(message);
+ if (info.role !== "assistant" || !isRecord(info.tokens)) continue;
+ const tokens = info.tokens;
+ const cache = isRecord(tokens.cache) ? tokens.cache : {};
+ const total = [tokens.input, tokens.output, cache.read, cache.write]
+ .reduce<number>((sum, value) => sum + (typeof value === "number" && Number.isFinite(value) ? value : 0), 0);
+ if (total > 0) return total;
+ }
+ return null;
+}
+
+function modelRef(value: unknown): ModelRef | null {
+ if (!isRecord(value)) return null;
+ const providerID = value.providerID;
+ const modelID = value.modelID ?? value.id;
+ return typeof providerID === "string" && providerID && typeof modelID === "string" && modelID ? { providerID, modelID } : null;
+}
+
+/** The model a prompt body asks for (`model: {providerID, modelID}`), if it names one. */
+export function promptModel(body: unknown): ModelRef | null {
+ if (typeof body === "string" || body instanceof Uint8Array || body instanceof ArrayBuffer) {
+ try {
+ const text = typeof body === "string" ? body : new TextDecoder().decode(body instanceof ArrayBuffer ? new Uint8Array(body) : body);
+ return promptModel(JSON.parse(text));
+ } catch {
+ return null;
+ }
+ }
+ return isRecord(body) ? modelRef(body.model) : null;
+}
+
+/** The model of the chat's newest prompt (the one the engine would go on with). */
+export function lastPromptModel(messages: unknown): ModelRef | null {
+ if (!Array.isArray(messages)) return null;
+ for (let index = messages.length - 1; index >= 0; index -= 1) {
+ const message = messages[index];
+ if (!isRecord(message)) continue;
+ const info = infoOf(message);
+ if (info.role !== "user") continue;
+ const model = modelRef(info.model) ?? (typeof info.providerID === "string" ? modelRef({ providerID: info.providerID, modelID: info.modelID }) : null);
+ if (model) return model;
+ }
+ return null;
+}
+
+function parentOf(session: unknown): string | null | undefined {
+ if (!isRecord(session)) return undefined;
+ const info = isRecord(session.info) ? session.info : session;
+ const parent = info.parentID ?? info.parentId ?? info.parent_id;
+ return typeof parent === "string" && parent ? parent : null;
+}
+
+function within<T>(promise: Promise<T>, ms: number): Promise<T | undefined> {
+ if (!Number.isFinite(ms)) return promise;
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const timeout = new Promise<undefined>((resolve) => {
+ timer = setTimeout(() => resolve(undefined), Math.max(0, ms));
+ (timer as { unref?: () => void }).unref?.();
+ });
+ return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+function errorText(error: unknown): string {
+ return error instanceof Error ? error.message : String(error);
+}
+
+export class AutoCompactor {
+ /** Prompts sent per chat since its last compaction (an upper bound, module docstring). */
+ private readonly counts = new Map<string, number>();
+ private readonly seeding = new Map<string, Promise<unknown>>();
+ private readonly children = new Set<string>();
+ private readonly running = new Map<string, Promise<boolean>>();
+
+ constructor(private readonly options: AutoCompactorOptions) {}
+
+ /** Whether the engine is compacting `sessionId` for this compactor now. */
+ compacting(sessionId: string): boolean {
+ return this.running.has(sessionId);
+ }
+
+ /** The chat was compacted another way (the person, the engine): count from zero. */
+ noteCompacted(sessionId: string): void {
+ if (!this.running.has(sessionId)) this.counts.set(sessionId, 0);
+ }
+
+ forget(sessionId: string): void {
+ this.counts.delete(sessionId);
+ this.children.delete(sessionId);
+ }
+
+ /** Prompts counted for `sessionId` since its last compaction (undefined before its first prompt). */
+ count(sessionId: string): number | undefined {
+ return this.counts.get(sessionId);
+ }
+
+ private log(level: "info" | "warn", message: string, attributes?: Record<string, unknown>): void {
+ try { this.options.log?.(level, message, attributes); } catch { /* logging never fails a prompt */ }
+ }
+
+ private notify(sessionId: string, stage: AutoCompactStage): void {
+ try { this.options.notify?.(sessionId, stage); } catch { /* a notice never fails a prompt */ }
+ }
+
+ private async policy(fresh: boolean): Promise<AutoCompactPolicy | null> {
+ try { return await this.options.policy({ fresh }); } catch { return null; }
+ }
+
+ /** Starts the count of a chat seen for the first time: one read of its messages and record. Resolves the messages read. */
+ private seed(sessionId: string, engine: AutoCompactEngine): Promise<unknown> {
+ const pending = this.seeding.get(sessionId);
+ if (pending) return pending;
+ const run = (async () => {
+ const [session, messages] = await Promise.all([
+ engine.session().catch(() => undefined),
+ engine.messages().catch(() => null),
+ ]);
+ if (parentOf(session)) this.children.add(sessionId);
+ this.counts.set(sessionId, turnsSinceCompaction(messages) ?? 0);
+ return messages;
+ })().finally(() => this.seeding.delete(sessionId));
+ this.seeding.set(sessionId, run);
+ return run;
+ }
+
+ private add(sessionId: string, base?: number): void {
+ this.counts.set(sessionId, (base ?? this.counts.get(sessionId) ?? 0) + 1);
+ }
+
+ /** Try again RETRY_AFTER_TURNS prompts later; this prompt counts. */
+ private later(sessionId: string, policy: AutoCompactPolicy): void {
+ this.counts.set(sessionId, Math.max(0, policy.afterTurns - RETRY_AFTER_TURNS) + 1);
+ }
+
+ /**
+ * Called for a prompt to `sessionId` that is about to go out and opens a
+ * turn. Resolves when the prompt may go out: at once, or after the
+ * chat's compaction (at most `holdMs`). `prompt`: the dispatch body (its
+ * model is the compaction's).
+ */
+ async beforePrompt(sessionId: string, engine: AutoCompactEngine, prompt?: unknown): Promise<AutoCompactOutcome> {
+ const holdMs = this.options.holdMs ?? Infinity;
+ const inFlight = this.running.get(sessionId);
+ if (inFlight) {
+ // A prompt sent while its chat compacts goes out behind the compaction.
+ this.add(sessionId);
+ const done = await within(inFlight, holdMs);
+ return { action: done === undefined ? "queued" : done ? "compacted" : "failed", reason: "already_compacting" };
+ }
+ const policy = await this.policy(false);
+ // The chat's messages, when this call read them already (its first prompt).
+ let read: { messages: unknown } | null = null;
+ if (!this.counts.has(sessionId)) {
+ // Off: no read at all. A chat is counted from its first prompt after the switch is on.
+ if (!policy?.enabled) return { action: "none", reason: "off" };
+ const seeded = await within(this.seed(sessionId, engine).then((messages) => ({ messages })), this.options.seedWaitMs ?? SEED_WAIT_MS);
+ // Not in time: the read goes on in the background and starts the count.
+ if (seeded === undefined) return { action: "none", reason: "seeding" };
+ read = seeded;
+ }
+ if (this.children.has(sessionId)) return { action: "none", reason: "sub_agent" };
+ const counted = this.counts.get(sessionId) ?? 0;
+ if (!policy?.enabled || counted < policy.afterTurns) {
+ this.add(sessionId);
+ return { action: "none", reason: policy?.enabled ? "below" : "off", turns: counted };
+ }
+ // Due by the count: the server's policy now, then the chat itself.
+ const current = await this.policy(true) ?? policy;
+ if (!current.enabled || counted < current.afterTurns) {
+ this.add(sessionId);
+ return { action: "none", reason: current.enabled ? "below" : "off", turns: counted };
+ }
+ const busy = await engine.busy().catch(() => null);
+ if (busy !== false) {
+ // Mid-turn (a steer: no turn of its own) or unknown: never compact then.
+ if (busy === null) this.add(sessionId);
+ return { action: "skipped", reason: busy ? "busy" : "status_unreadable", turns: counted };
+ }
+ const messages = read ? read.messages : await engine.messages().catch(() => null);
+ const turns = turnsSinceCompaction(messages);
+ if (turns === null) {
+ this.later(sessionId, current);
+ return { action: "skipped", reason: "unreadable", turns: counted };
+ }
+ if (turns < current.afterTurns) {
+ this.add(sessionId, turns);
+ return { action: "none", reason: "below", turns };
+ }
+ const context = lastContextTokens(messages);
+ if (current.minContextTokens > 0 && context !== null && context < current.minContextTokens) {
+ this.later(sessionId, current);
+ return { action: "skipped", reason: "small_context", turns };
+ }
+ const model = promptModel(prompt) ?? lastPromptModel(messages);
+ if (!model) {
+ this.later(sessionId, current);
+ return { action: "skipped", reason: "no_model", turns };
+ }
+ // This prompt is the first after the compaction.
+ this.counts.set(sessionId, 1);
+ this.notify(sessionId, "started");
+ this.log("info", "auto compaction started", { sessionId, turns, context_tokens: context, after_turns: current.afterTurns });
+ const started = Date.now();
+ const controller = new AbortController();
+ const timeoutMs = this.options.timeoutMs ?? COMPACTION_TIMEOUT_MS;
+ const timer = setTimeout(() => controller.abort(new Error("compaction timed out")), timeoutMs);
+ (timer as { unref?: () => void }).unref?.();
+ const run: Promise<boolean> = engine.summarize(model, controller.signal).then(
+ () => {
+ this.log("info", "auto compaction finished", { sessionId, elapsed_ms: Date.now() - started });
+ this.notify(sessionId, "finished");
+ return true;
+ },
+ (error: unknown) => {
+ this.log("warn", "auto compaction failed", { sessionId, elapsed_ms: Date.now() - started, error: errorText(error) });
+ this.later(sessionId, current);
+ this.notify(sessionId, "failed");
+ return false;
+ },
+ ).finally(() => {
+ clearTimeout(timer);
+ this.running.delete(sessionId);
+ });
+ this.running.set(sessionId, run);
+ const done = await within(run, holdMs);
+ return { action: done === undefined ? "queued" : done ? "compacted" : "failed", turns };
+ }
+}
diff --git a/apps/server/src/session-archive/turn-prompts.ts b/apps/server/src/session-archive/turn-prompts.ts
index 67e3247e..818c73c6 100644
--- a/apps/server/src/session-archive/turn-prompts.ts
+++ b/apps/server/src/session-archive/turn-prompts.ts
@@ -15,8 +15,8 @@
* running turn, so the turn keeps the workspace its first prompt found and
* the steer is recorded in it (the client's `turn.steer` event).
*
- * A prompt is a steer when an assistant message created before it ended
- * after it was sent (the agent was mid-step: thinking, a tool, a sub-agent),
+ * A prompt is a steer when an assistant message (not a compaction's
+ * summary) created before it ended after it was sent (the agent was mid-step: thinking, a tool, a sub-agent),
* or when the step before it asked for more steps (tool calls) and ended at
* most STEER_GAP_MS before it, without an error (between two steps). An
* assistant message that never ended (a crashed run) proves nothing.
@@ -57,6 +57,16 @@ function roleOf(message: MessageRecord): unknown {
return info.role ?? info.type;
}
+/**
+ * An assistant message that is a compaction's summary: the engine at work
+ * on the chat, not the agent on a turn. A prompt sent while it runs (an
+ * automatic or a /compact compaction) opens a turn of its own.
+ */
+function isCompactionSummary(message: MessageRecord): boolean {
+ const info = infoOf(message);
+ return info.summary === true || info.mode === "compaction" || info.agent === "compaction";
+}
+
/**
* A user message that is a prompt someone sent: not a compaction's request
* (a "compaction" part, or the 2.x adapter's compaction agent) and not
@@ -88,6 +98,7 @@ export function steerPrompts(messages: readonly unknown[]): Set<string | number>
if (!isRecord(message)) return;
const role = roleOf(message);
if (role === "assistant") {
+ if (isCompactionSummary(message)) return;
const info = infoOf(message);
const completed = completedMs(message);
if (completed !== null) busyUntil = Math.max(busyUntil, completed);
@@ -136,7 +147,7 @@ export function completedTurnCount(messages: unknown): number | null {
// The prompt before ended without an answer (stopped right away): it was a turn too.
if (awaitingReply) turns += 1;
awaitingReply = true;
- } else if (roleOf(message) === "assistant" && awaitingReply && isEnded(message)) {
+ } else if (roleOf(message) === "assistant" && awaitingReply && !isCompactionSummary(message) && isEnded(message)) {
turns += 1;
awaitingReply = false;
}
diff --git a/apps/server/src/session-uploader.ts b/apps/server/src/session-uploader.ts
index 477565b9..236101c5 100644
--- a/apps/server/src/session-uploader.ts
+++ b/apps/server/src/session-uploader.ts
@@ -861,6 +861,8 @@ export type TraceCapabilities = {
install_log?: { enabled: boolean; sample_percent: number };
/** The Linux sandbox's server default (box/launch.ts serverDefault): "off" | "offer" | "on", and the backends it allows (serverBackends). */
local_box?: { default: string; max_turn_bytes?: number | null; backends?: string[] | null };
+ /** Automatic compaction (session-archive/auto-compact.ts): absent is off. */
+ auto_compact?: { enabled: boolean; after_turns: number; min_context_tokens?: number };
};
diff --git a/apps/server/src/turn-steer.ts b/apps/server/src/turn-steer.ts
index 3bd1d756..fc88d872 100644
--- a/apps/server/src/turn-steer.ts
+++ b/apps/server/src/turn-steer.ts
@@ -29,7 +29,7 @@ const infoOf = (message: unknown): unknown => (isRecord(message) && isRecord(mes
const toMs = (value: unknown): number | null => (typeof value === "number" && Number.isFinite(value) ? value : null);
/** Why a prompt counted as it did: a steer (`working`, `busy_unread`) or a turn start (the rest). */
-export type SteerReason = "idle" | "working" | "busy_unread" | "not_started" | "ending" | "status_unreadable";
+export type SteerReason = "idle" | "working" | "busy_unread" | "not_started" | "ending" | "compacting" | "status_unreadable";
export type SteerVerdict = { steer: boolean; busy: boolean | null; reason: SteerReason; error?: string };
/** A tool call relative to a steer: `sub_agent` is the task tool's child session. */
@@ -45,11 +45,17 @@ function isPrompt(message: unknown): boolean {
return !(content.length > 0 && content.every((part) => part.type === "text" && part.synthetic === true));
}
+/** A compaction's summary (the engine compacting the chat): no agent step, a prompt sent then opens a turn. */
+export function compactionSummary(message: unknown): boolean {
+ const info = infoOf(message);
+ return isRecord(info) && info.role === "assistant" && (info.summary === true || info.mode === "compaction" || info.agent === "compaction");
+}
+
/** Whether the agent is mid-turn on `newest` (the session's newest message): an assistant step that has not ended normally. */
export function workingOn(newest: unknown): boolean {
const info = infoOf(newest);
if (!isRecord(info) || info.role !== "assistant") return false;
- if (info.error != null) return false;
+ if (info.error != null || compactionSummary(newest)) return false;
const completed = toMs(isRecord(info.time) ? info.time.completed : undefined);
return !(completed !== null && typeof info.finish === "string" && NORMAL_FINISH.has(info.finish));
}
@@ -150,6 +156,7 @@ export function createSteerTracker(target: EngineTarget, { timeoutMs = 1_500, fe
try {
const [last] = (await newest(sessionId, 1)).slice(-1);
if (workingOn(last)) return { steer: true, busy: true, reason: "working" };
+ if (compactionSummary(last)) return { steer: false, busy: true, reason: "compacting" };
const info = infoOf(last);
return { steer: false, busy: true, reason: isRecord(info) && info.role === "user" ? "not_started" : "ending" };
} catch (error) {