@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
• normalizes summary output back into one canonical <continuation_summary>...</continuation_summary> block
• includes assistant tool calls and tool result metadata in the summary input; with compaction.prune: true, older tool outputs are omitted with character counts while recent/error outputs render bounded previews
• 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: one summary attempt, 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
• compaction.prune defaults to true; set it to false only when the summary model should receive full tool text and structured content before chunking/truncation
• 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 or last_message_fallback; controller failures use context.compaction.failed.metadata.attemptStage = 'default_summary'
• 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 adjusts to legal message boundaries and can use terminal compaction when the visible history ends with assistant/tool messages
• 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 before retained messages
• run pnpm run demo:auto-compact in the repo for the scripted walkthrough