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.

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.

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

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.