Session Compaction Hook

Relevant source files

The following files were used as context for generating this wiki page:

• src/compaction.ts
• README.md
• AGENTS.md
• src/config.ts
• test/morph.test.ts
• CHANGELOG.md

The Session Compaction Hook is a core feature of the Morph plugin for oh-my-pi (omp) that intercepts the session history management process. It leverages the Morph Compact API to condense conversation history into a shorter, query-focused summary, effectively managing the token window for long-running agentic sessions. By hooking into the session_before_compact event, the plugin provides a high-fidelity alternative to native summarization strategies.

Sources: src/compaction.ts:182-186, README.md:65-67

Architecture and Event Handling

The system operates as a bridge between the oh-my-pi host and the Morph SDK. When a session reaches its token limit or a user manually triggers a /compact command, the host emits the session_before_compact event. The Morph plugin's handler intercepts this event to perform remote summarization.

Workflow Logic

The hook follows a strict set of rules to determine whether it should process the compaction or yield to the native omp strategy:

1. Remote Check: If remoteEnabled is false (e.g., via /compact soft), the hook yields to the native local summarizer to prevent transcript egress.
2. Strategy Check: Morph yields to the host's snapcompact strategy (image-archive) unless a specific focus query is provided.
3. Focus Forwarding: Manual commands like /compact <focus> are forwarded to Morph as a compaction query.
4. Content Accumulation: The hook folds in the previous compaction summary and split-turn prefix messages to ensure iterative history is preserved.

Sources: src/compaction.ts:192-212, AGENTS.md:23-35, CHANGELOG.md:14-16

Data Serialization

Before sending history to the Morph API, the hook must serialize complex agent message shapes into standard role/content pairs. This process includes strict budgeting to prevent oversized requests.

Message Transformation Rules

• Tool Calls: Arguments are capped at 500 characters using a bounded JSON stringifier to avoid materializing large payloads in memory.
• Tool Results: Output content is capped at 2,000 characters. The serializer performs a bounded walk over content parts and halts as soon as the limit is reached.
• Excluded Types: thinking, redactedThinking, and image parts are stripped during serialization for compaction purposes.

Sources: src/compaction.ts:133-176, test/morph.test.ts:241-285

Summarization Inputs Table

Input Element	Description	Source Mapping
previousSummary	Folded in as a synthetic "Summary of earlier history" user message.	src/compaction.ts:213-215
messagesToSummarize	The primary history slice selected by the host for compaction.	src/compaction.ts:217
turnPrefixMessages	Messages from the current split-turn, ensuring no context loss.	src/compaction.ts:218-220
query	The focus text provided by the user in manual compaction calls.	src/compaction.ts:233

Error Handling and Safety

The hook implements several safety mechanisms to ensure session stability:

• Native Fallback: If Morph is unavailable, the API returns an error, or the resulting summary is empty, the handler returns undefined, allowing the host to run its native local strategy.
• Abort Racing: The hook races the Morph API request against the event's AbortSignal. If the compaction is cancelled (e.g., by the user), the hook rejects promptly rather than blocking on the remote network trip.
• UI Integration: If the extension context has a UI enabled, it provides a notification indicating the compression ratio achieved (e.g., "Morph compacted (30% kept)").

Sources: src/compaction.ts:227-248, CHANGELOG.md:21-22, README.md:73-77

Configuration Options

Compaction behavior is primarily controlled via environment variables.

Variable	Default	Description
MORPH_COMPACT	true	Globally enables/disables the session_before_compact hook.
MORPH_COMPACT_RATIO	0.3	The target fraction of content to keep (Valid: 0.05 to 1.0).
MORPH_API_KEY	(Required)	Necessary for remote calls; without it, the hook yields to native.

Sources: src/config.ts:17-43, README.md:33-42

Summary

The Session Compaction Hook provides a robust mechanism for maintaining agent context by delegating history summarization to Morph's specialized LLM. It prioritizes session integrity by folding in iterative summaries and ensuring that any failure or explicit local-only request falls back seamlessly to the oh-my-pi native summarization strategy.

Sources: AGENTS.md:23-40, README.md:65-77