session.compact()

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

const unsubscribe = session.subscribe((mutation) => {
  apply_mutation_to_ui(mutation);
});

await session.compact();
await session.prompt({ query: "Continue from the compacted history" });

The method is available on both AgentSession and RemoteAgentSession.

Queue semantics

await session.compact() means that the command passed validation and entered the Session's ordered input queue. It does not wait for summary generation or history rewriting.

• 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.

Observing completion

Compaction publishes action messages through the normal Session timeline:

• running while the summary and archive are being prepared
• completed after the canonical history has been replaced
• failed when the model, composer, or storage operation fails

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

Use subscribe() to observe these messages. The compact() return value only reports queue acceptance.

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.