session.compact()

session.compact() requests an explicit compaction of the current Session history.

const compact = await session.compact();
const result = await compact.finished;

if (!result.success) {
  console.error(result.error);
}
await session.prompt({ query: "Continue from the compacted history" });

The method is available on both AgentSession and RemoteAgentSession.

Queue semantics

await session.compact() returns a Handle after the command passes validation and enters the Session's ordered input queue. handle.result remains null while it is pending; await handle.finished waits until summary generation and canonical history rewriting have actually finished.

• when the Session is idle, the command runs before the next prompt() turn starts
• when a turn is active, it runs at the next Session step checkpoint
• if the active turn ends before another checkpoint, the command remains queued for the next turn
• compact commands, configuration commands, and steer prompts preserve their queue order
• calling compact() alone never creates a turn or starts a provider request

Before compacting during an active turn, the SDK closes the current Assistant draft. After the canonical history is rewritten, the next provider request reloads that history instead of continuing with stale in-memory messages.

Manual and automatic Compact use the same algorithm: select floor(n / 2) of the oldest Active User and Assistant Messages, summarize that prefix with exactly one model call, archive it as a Segment, and leave the newer messages in Active.

Observing completion

After summary generation succeeds, the canonical commit publishes action messages through the normal Session timeline:

• running while the archive is being committed
• completed after the canonical history has been replaced
• failed when the storage operation fails after the commit starts

If there are no active records, the Session emits a completed action explaining that there was nothing to compact.

The stable Handle result includes:

• compact_id: the explicit compaction request ID
• success: whether the request completed successfully; nothing to compact is also successful
• compacted: whether a compaction plan was generated and committed
• reason: compacted | nothing_to_compact | compact_failed
• error: the failure message, when present

If summary generation fails or returns empty text, Compact returns compact_failed directly and leaves Active history unchanged. The SDK never starts the canonical commit, commits a fallback Summary, or reports the operation as successfully compacted.

subscribe() still emits compact lifecycle mutations and timeline actions for UI state. Application logic should normally await handle.finished instead of inferring completion from Action Messages.

Automatic and explicit compaction

Automatic compaction still runs when real Provider usage reaches the configured context threshold. session.compact() uses the same compaction composer, storage transaction, and action messages; it only adds an explicit request to the Session queue.

See Metadata and storage for summaries, active history, and recovery behavior.