Feature request: on-demand context compaction API

[jiridanek]

Environment

• google-antigravity SDK v0.1.3
• Python 3.14
• macOS

Problem

The SDK supports automatic context compaction via CapabilitiesConfig.compaction_threshold, but there is no way to trigger compaction on-demand from Python code. The Go harness handles all compaction internally — the Python SDK only receives an OnCompactionHook notification after it happens.

For interactive IDE integrations (ACP agents), users expect a /compact command (like Claude Code's) to proactively compress context before hitting limits. Currently we can only tell users "compaction is automatic."

Current state

What works:

• CapabilitiesConfig(compaction_threshold=50000) — sets when automatic compaction fires
• OnCompactionHook — observability hook dispatched after compaction occurs
• conversation.compaction_indices — tracks where compaction happened in history
• Full history preserved in Python SDK for transcript purposes

What's missing:

1. No API to trigger compaction on-demand — e.g., conversation.request_compaction() or agent.compact()
2. ActionCompaction proto is empty — no metadata about what was compacted (token count before/after, which turns were summarized)
3. No way to control compaction strategy — can't choose summarize vs. prune, or specify which turns to retain

Use case

Building an ACP agent adapter for JetBrains IDEs. Users expect:

• /compact command to proactively compress context when they notice the conversation getting long
• Visibility into what was compacted (token savings)
• Control over when compaction happens (not just when threshold is hit)

The Gemini CLI has compressionThreshold in settings.json. Claude Code has /compact which summarizes earlier messages. The SDK's compaction_threshold is the config equivalent, but lacks the interactive trigger.

Proposed API

# Option 1: Method on Agent
await agent.compact()  # triggers immediate context compaction

# Option 2: Method on Conversation
conversation.request_compaction()

# Option 3: Config-level (less useful for on-demand)
CapabilitiesConfig(compaction_threshold=0)  # compact on next turn

Enriched OnCompactionHook data would also help:

class CompactionData:
    tokens_before: int
    tokens_after: int
    turns_compacted: int

Workaround

Currently the only option is to rebuild the agent (losing conversation context entirely), or to set a very low compaction_threshold so compaction fires frequently. Neither provides the user-controlled "compact now" experience.

References

• Gemini CLI: compressionThreshold setting
• Claude Code: /compact command
• SDK: CapabilitiesConfig.compaction_threshold (types.py line 372)
• SDK: OnCompactionHook (hooks.py line 230)
• SDK: ActionCompaction proto (empty message, no metadata)
• Related: Feature request: cost and safety controls (max turns, token budget, tool call limits) #48 (cost and safety controls)