@archships/dim-plugin-auto-compact

@archships/dim-plugin-auto-compact

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

What it does

• exposes SessionCompactorController.compact(...)
• summarizes older history into one canonical compaction segment
• optionally uses a dedicated summaryModel instead of the session model
• accepts an SDK-owned CompactionExecutionRequest, including summaryInputMode: 'default' | 'exclude_tool_messages'
• normalizes summary output back into one canonical <continuation_summary>...</continuation_summary> block
• prunes older tool outputs inside the plugin summary input when configured
• keeps full session.messages intact for UI and restore
• stores plugin-owned provenance in pluginState['auto-compact'], including semantic lastResult diagnostics for the controller call only

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 − max(effectiveO, contextWindow × safetyRatio) (where effectiveO caps plannedOutput at max(DEFAULT_OUTPUT_CAP_TOKENS, contextWindow × safetyRatio) and falls back to the safety floor when plannedOutput / contextWindow > 0.6)
• 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
• SDK core owns planning, cursor movement, checkpoints, typed notifications, and threshold fallback orchestration
• threshold fallback order is fixed in SDK core: default summary, one exclude_tool_messages retry, then SDK-owned last-message fallback
• the plugin only returns typed controller results; SDK-owned last-message fallback does not write into plugin state
• 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
• lastResult is updated on every controller call with compacted / skipped / failed, plus summary normalization and summary-call diagnostics when available
• runtime notifications expose typed fallback metadata: context.compacted.metadata.resolution can be summary, summary_without_tools, or last_message_fallback; context.compaction.failed.metadata.attemptStage distinguishes default_summary from summary_without_tools
• 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 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