@archships/dim-plugin-auto-compact

@archships/dim-plugin-auto-compact

Official supported auto compaction plugin for dim-agent-sdk.

What it does

• listens to context.compact.before
• summarizes older history into one canonical compaction segment
• optionally uses a dedicated summaryModel instead of the session model
• aligns compaction cut points to real user messages so projected history never starts with assistant / tool
• injects the retained summary as a synthetic user message, and injects one lightweight auto-compact context user message ahead of the retained anchor query
• keeps full session.messages intact for UI and restore
• stores provenance in pluginState['auto-compact'], including rolling checkpoint entries (checkpointId, createdAt) plus semantic lastAttempt diagnostics

Requirements

• enable SDK core compaction (compaction: {} or an explicit safetyRatio) on the agent
• publish ModelCapabilities.contextWindow on the model adapter so the gate can derive threshold = contextWindow − plannedOutput − contextWindow × safetyRatio
• configure compaction.compactorPluginId: 'auto-compact'
• grant model permission to the plugin runtime

Usage

import { createAgent, createModel } from '@archships/dim-agent-sdk'
import { createAutoCompactPlugin } from '@archships/dim-plugin-auto-compact'

const agent = createAgent({
  model: createModel(adapter),
  plugins: [
    createAutoCompactPlugin({
      summaryModel: { provider: 'openai', modelId: 'gpt-4.1-mini' },
      retainMessages: 6,
      compaction: {
        auto: true,
        prune: true,
        reserved: 10_000,
      },
    }),
  ],
  compaction: {
    safetyRatio: 0.2,
    compactorPluginId: 'auto-compact',
  },
})

Notes

• summaryModel is optional; the plugin defaults to context.status.model
• maxSummaryTokens is optional; the plugin defaults summary requests to 1024
• automatic compaction starts from threshold compaction pressure; the plugin reacts in context.compact.before after SDK core budget detection fires
• summary failures are fail-open and fall back to context_compaction_required
• summary model calls now opt into the SDK usage ledger with semantic request kinds: threshold-triggered passes record auto_compaction, and session.compact() summary calls record manual_compaction
• the default summary prompt asks the model for plain-text summary body only; runtime normalizes accepted output back into one canonical <continuation_summary>...</continuation_summary> block before replay, including wrapped blocks, merged multi-block outputs, and malformed-tag fragments that still yield a non-empty semantic body
• when normalization yields an empty body, runtime preserves the previous saved continuation summary when one already exists; only empty output without a previous summary fails with invalid_summary_contract
• lastAttempt is updated on every threshold-triggered compaction pass with planned / skipped / compacted / failed, budget metadata, estimator-based estimatedInputTokensAfter / estimatedSavedTokens, reason codes such as missing_summary_model, nothing_to_compact, empty_summary_preserved_previous, summary_generation_failed, or compaction_owner_required, and optional summaryNormalization values (plain_text, wrapped_block, extracted_block) when the summary output was inspected
• persisted plugin state keeps only semantic provenance fields; summary-call counters and per-message id arrays stay out of pluginState
• context.compacted notifications now include compacted / retained message counts plus estimator-based before / after / saved token fields when budgeting is enabled
• retainMessages remains a preferred target, but the planner can keep compacting down to the newest real user boundary when needed
• the runtime now keeps leading system messages first, appends runtime prompt/context next, then uses synthetic user messages for the auto-compact environment note and the compaction summary around the retained anchor query
• run pnpm run demo:auto-compact in the repo for the scripted walkthrough