Architecture

August 20, 2026 ยท View on GitHub

Decision

V0.1 is technically feasible on DeepSeek Harness 0.1.0-rc.8 using the public tools/post-execute waterfall. It is a host-only Cordis bundle and does not modify Core or register replacement tools.

Pipeline

ToolExecutionResult
  -> call next() (respect downstream tool/result transforms)
  -> accept/content-only guard
  -> plain-text block extraction
  -> inspector (size, estimated tokens, type, tool name)
  -> enabled / excluded / threshold checks
  -> processor router (log | JSON | HTML | text)
  -> evidence and budget guard
  -> retain original with official spillStore
  -> transparent compression notice + locator
  -> accept with replacement content
  -> official spill-policy hard-size fallback
  -> DSH materialization and tools/result

Invariants

  1. Never replace canonical value.
  2. Never mutate exec, result, content blocks, or decisions.
  3. Preserve non-text and mixed content unchanged.
  4. Preserve additionalContexts from downstream decisions.
  5. Return the original if inspection, parsing, compression, retention, or notice assembly throws.
  6. Do not replace content unless the final output is smaller.
  7. Mark all omissions and estimate token counts honestly.
  8. Default to retaining the original through the official spill store.

Processors

  • Log: head + evidence windows + unique stack-trace roots + tail; collapse repeated lines/blocks with exact repeat counts.
  • JSON: structural/key overview, important/error-bearing records, representative samples, and exact per-array omitted counts.
  • HTML: parse rules, remove script/style/svg/noscript/comments, retain semantic text, tables, lists, links, and code. If extraction is unreliable, fall back to conservative text processing or the original.
  • Text: normalize excessive whitespace and collapse exact duplicate lines or paragraphs; use conservative evidence/head/tail selection only when still over budget.

Token estimation and budgets

TokenEstimator is an interface. V0.1 uses a fast character-class estimate, with denser accounting for CJK text. No provider tokenizer is bundled.

minTokens controls activation, targetTokens guides processor budgets, and maxTokens is a final safety ceiling. Configuration validation requires:

0 < minTokens <= maxTokens
0 < targetTokens <= maxTokens

Retention and reversibility

Replacing presentation content also changes the durable tool-result content. The canonical JSON value is still preserved by DSH, but it is not a substitute for the formatted original. Before replacement, V0.1 stores the full formatted text through ctx.spillStore.saveText and includes the returned locator and retrieval hint. With default retainOriginal: true, missing storage causes a fail-open pass-through.

Relationship to native compaction

This plugin reduces new large results. Native spill remains the hard-size and retrieval fallback; native compaction/pruning still manages accumulated history. The systems are complementary. Compression output is append-only, so it does not rewrite earlier messages or invalidate an already reusable KV-cache prefix.

Deferred

  • Web dashboard and /squeeze command
  • command-specific processor catalog
  • provider tokenizers
  • non-text/media processing
  • nested run_code dispatch-log transformation
  • adaptive or LLM-based summarization