Native Compaction and Snapcompact Fallbacks

Relevant source files

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

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

Native Compaction and Snapcompact Fallbacks represent the integration logic between the oh-my-pi (omp) host and the Morph Compact API. This system ensures that while Morph handles advanced history summarization and focused digests by default, the host maintains its "native floor"—allowing it to revert to local summarization strategies or specialized image-archiving (Snapcompact) when Morph is unavailable, disabled, or not the optimal tool for the specific task.

The system hooks into the omp session_before_compact event, acting as a bridge that either processes the transcript through Morph or yields control back to the host. This dual-path architecture ensures session continuity regardless of remote API availability or configuration settings like /compact soft.

Sources: README.md:91-103, AGENTS.md:27-38, src/compaction.ts:133-145

Compaction Routing Logic

The plugin follows a strict routing policy to determine when Morph should take control of compaction versus when it should yield to native host strategies. By default, Morph drives all automatic and manual /compact operations if MORPH_API_KEY is configured and MORPH_COMPACT is enabled.

Yield Conditions

The bridge returns undefined to the host, triggering a fallback to the native strategy, under the following conditions:

• Missing Configuration: MORPH_API_KEY is absent or the Morph client is not initialized.
• Local-Only Path: The user executes /compact soft or remoteEnabled is set to false. This prevents transcript egress.
• Snapcompact Strategy: Morph yields to the host's snapcompact strategy (image-archive) specifically when no focus text is provided.
• Empty Context: If there are no messages to summarize or the serialized input for Morph is empty.
• API Errors: If the Morph API call fails or returns an empty summary.

Sources: AGENTS.md:27-46, README.md:104-108, CHANGELOG.md:14-22, src/compaction.ts:145-156

Flow of Compaction Selection

The following diagram illustrates the decision matrix used by the beforeCompact handler to determine the compaction path.

Snapcompact Integration

Snapcompact is a specialized host strategy designed for image-archive compaction. The Morph plugin respects this strategy while offering "Focused Compaction" enhancements.

• Unfocused Snapcompact: If the active strategy is snapcompact and the user provides no specific focus text, the plugin yields. This preserves the host's ability to archive images or perform non-LLM based history reduction.
• Focused Snapcompact: If the user provides focus text (e.g., /compact <focus>), Morph overrides the snapcompact strategy. The focus text is forwarded to the Morph API as a compaction query to produce a directed summary.

Sources: AGENTS.md:34-38, README.md:94-96, CHANGELOG.md:23-25

Data Preservation and Serialization

To maintain iterative history, the Morph compaction bridge must fold specific host-owned data into the remote request. This ensures that history managed by the host's native summarizer is not lost during a Morph-driven compaction.

Serialized Inputs

Input Type	Description	Source
previousSummary	The previous compaction's summary is added as a synthetic leading message.	src/compaction.ts:162-164
turnPrefixMessages	On split turns, these messages are included to prevent history gaps.	src/compaction.ts:168-170
messagesToSummarize	The standard range of messages targeted for compaction.	src/compaction.ts:167
query	The focus text (if any) provided by the user.	src/compaction.ts:178

Content Constraints

During serialization, the bridge applies budget limits to prevent unbounded payload egress:

• Tool Results: Capped at 2,000 characters per message.
• Tool Call Arguments: Capped at 500 characters.
• Images/Thinking: These parts are explicitly omitted from the text-based compaction request.

Sources: src/compaction.ts:114-118, src/compaction.ts:98-110, test/morph.test.ts:314-325

Sequence of a Compaction Request

The following sequence diagram shows the interaction between the coding agent, the Morph plugin, and the remote Morph API.

Technical Implementation Details

The core of the compaction logic resides in src/compaction.ts, specifically the makeBeforeCompact factory function.

// src/compaction.ts:133-145
export function makeBeforeCompact(pi: ExtensionAPI) {
  return async function beforeCompact(
    event: SessionBeforeCompactEvent,
    ctx: ExtensionContext,
  ): Promise<SessionBeforeCompactResult | undefined> {
    if (!morphReady() || !compactClient) return undefined;

    const prep = event.preparation;

    if (prep.settings.remoteEnabled === false) return undefined;

    const focus = event.customInstructions?.trim() || undefined;
    // ...

Abort Handling

Compaction logic includes a "race" against an abort signal. If a compaction is cancelled by the user or the host (e.g., during a manual interruption), the in-flight Morph request is raced against the signal. A cancelled compaction rejects promptly rather than blocking on the remote API response.

Sources: CHANGELOG.md:26-28, src/compaction.ts:173-182, test/morph.test.ts:430-445

Conclusion

The Native Compaction and Snapcompact Fallback system provides a robust failsafe for session management. By strictly defining yield conditions—such as local-only requests, missing API keys, or specific image-archiving strategies—the plugin ensures that Morph's advanced LLM summarization enhances the user experience without sacrificing the reliability of the host's native local operations.