falling-ts/dsh-force-compact

dsh-force-compact

Aggressive, local-first context compaction for DeepSeek Harness agents.

A DSH Cordis function plugin that keeps the agent's working context lean by design: serve Qwen3.8‑27B on a self-hosted llama.cpp with a modest context, and the plugin shrinks the conversation itself — a large-window feel with no API cost and no data egress.

Why

• Self-hosted inference — the agent talks to a local OpenAI-compatible llama.cpp server

through the standard DeepSeek adapter; no separate adapter needed.

• Low context, high signal — instead of fighting a small cap, the plugin shrinks the

conversation, so the agent reasons over a tight prompt while keeping deep memory in the compressed head.

• Think off for compactions, passthrough everywhere else — disableThinking: true

(default) turns thinking off on *this plugin's own compaction summarization call only*; every other model request rides the machine's configuration unchanged.

• Private & free — no per-token billing, no egress.

What it does

Two compaction engines coexist behind one facade (resolveCompaction), transparent to callers:

Engine · Used when · Notes Official · the compaction service resolves in the agent realm · Preferred; delegates to compaction/basic. Builtin · automatic fallback (typical standard preset isolates the service) · Self-contained persistent transaction on ctx.sessions / ctx.llm.stream / ctx.tokenMeter; reuses the official compaction/* event vocabulary, so it replays safely across builds.

No toggling — official wins when reachable, builtin takes over otherwise.

Trigger points

• Per-request guard (`agent/pre-step`) — reads the session's *projected* context tokens

(the exact number the harness renders bottom-right). At autoThresholdTokens it rejects the outgoing request and compacts the head instead, retaining the latest retainLatestTokens verbatim. Below the threshold the request proceeds.

• Turn end / idle (`agent/status` → `idle`) — when the agent quiesces, optionally

compacts via compactNow (gate: turnEndForceCompactionEnabled).

• Manual `/force-compact` — immediate compactNow when idle; when busy it queues a

process-local flag consumed at the next model step. Loaded lazily — see "Command availability" under Install. In the / picker the row carries the same face as the first-party commands: an icon, a localized name and a localized description (the official presentation table only covers first-party commands, so the client half attaches the face itself — see AGENTS.md, "指令行的官方外观").

• `session/flush` — the awaited durability checkpoint.

Every path funnels into the single *"compaction result landed in the session"* boundary — the same point where the LiveUI signal fires.

Decision key is projectedTokens (provider-anchored, same figure as the UI corner), so the plugin never drifts from what you see; the threshold-aware shrink gate skips summarizer calls that provably cannot pull the session below the threshold (kills the low-threshold dead loop).

The builtin transaction bills shadowedTokenCount from the same tokenMeter.measure per-node prices the official engine uses, so the meter's collapse protocol settles the drop correctly — the bottom-right counter goes *down* after compaction.

Thinking control: scoped to compactions

Since the 2026-08 semantics revision, disableThinking controls one thing: whether this plugin's own summarization call (engine/builtin.js → engine/summarizer.js → ctx.llm.stream) carries reasoningEffort:'off'. Everything else is untouched:

Call site · With disableThinking: true Builtin-engine summarization call · Carries reasoningEffort:'off' Every other model request (business, sub-agents, tools, other plugins) · Machine's LlmCallConfig unchanged Official compaction service calls · Not routed through any plugin seam — unaffected

A route that cannot express `off` degrades instead of failing. Not every catalog model declares an off level — pi-ai's thinkingLevelMap may map it to null, as opencode-go/deepseek-v4.1-flash does (it accepts only low / high / max, while deepseek/deepseek-flash accepts off too). The summarizer probes the route's capability before the call (llm.resolveCallConfig, a detached lookup with no provider I/O) and, when off is unavailable, uses the cheapest level the route does accept; a model with no reasoning support at all gets no effort field. Because a thinking route bills its reasoning trace against the same maxTokens cap, a fixed reasoning allowance is added on top of maxSummaryTokens (documented as the cap on the summary *text*) so the summary still fits. Both are logged once per route:

summarization route opencode-go/deepseek-v4.1-flash does not support reasoning effort 'off'
  — using the cheapest supported level 'low' instead; compaction continues

Before this guard, such a route failed every compaction outright (the harness rejects the unsupported effort before any provider I/O).

When the target is a llama.cpp / OpenAI-compatible endpoint, the thinking: { type: 'disabled' } field the adapter emits is silently ignored there — so the summarizer ALSO stamps the llama.cpp-native top-level reasoning_effort: "none", gated on the exact same condition. One options object carries BOTH fields:

Endpoint family · Reads · Result Real DeepSeek API · reasoningEffort:'off' → thinking:{type:'disabled'} · Thinking off ✅ llama.cpp / OAI-compatible · reasoning_effort:"none" (top-level) · enable_thinking=false ✅

Each family tolerates-and-ignores the foreign key, so emitting both is harmless. The field is stamped in src/engine/summarizer.js (immediately before llm.stream(options)), NOT in the llm/stream waterfall — a prior draft injected there but proved ineffective structurally (middle-layer returns are discarded; in-place seed mutation crashes the host); see the src/hooks/wire-rewrite.js module header for the write-up (that module is now retired and keeps only this historical record).

Need thinking off on business calls too? Set your provider's reasoningEffort at the request-header level — the plugin deliberately stays out of that decision.

Observability: per-attempt audit lines

Every summarization attempt logs two lines (visible at the default debug: true) — the durable proof of the scoping decision and its wire fields, without capturing traffic:

[force-compact] <sessionId>: compaction thinking-policy — settings.disableThinking=true → extra.reasoningEffort='off' (this summarization call carries thinking-OFF)
[force-compact] <sessionId>: summarization wire-fields → <provider>/<model>: reasoningEffort='off' + reasoning_effort="none" (llama.cpp-native wire field)

• Line 1 (engine/builtin.js) records where disableThinking is read and routed into

the call options; with the setting off it records *machine default*.

• Line 2 (engine/summarizer.js) records both wire fields exactly as they leave the

options object, plus resolved provider/model; unstamped fields are labeled (absent…).

Empirically grounded: probed against a local llama.cpp endpoint, a baseline request returned populated reasoning_content (the model thinks by default), while the same request with top-level reasoning_effort:"none" returned none at all — the field genuinely disables thinking there, and business calls (which omit it) keep thinking.

LiveUI status

A tiny host→client messenger (the liveUi settings field mirrored live to the browser) replaces the official running label's leading phrase beside the turn. Only the text changes: the harness's own elapsed-time text, font, and colour are left exactly as shipped.

The status text reports which kind of time-consuming agent action is running, one phase per kind. Three phases, each driven by one agent seam:

Status · Meaning · Insertion point `模型请求中` (Requesting model) · the agent issued a model request and is waiting for the first token · the agent/request waterfall `模型响应中` (Model responding) · the first token arrived; lasts to the end of the response · the first chunk of agent/assistant-stream (index === 0) `工具执行中` (Running tool) · a non-model, agent-internal operation is running · the tools/pre-execute waterfall

responding hangs on the first chunk, not on the attempt's start frame: start is emitted *before* any token arrives (right after the llm.stream(request) call), and that moment still belongs to requesting's span.

A compaction summarization request never publishes any of the three (the user asked to exclude compaction-time requests). That is a structural exclusion, not a filter: the plugin's (and the official engine's) summarizer calls ctx.llm.stream directly, so it traverses no agent/request waterfall, produces no agent/assistant-stream frame, and dispatches no tools.

The compaction banners are kept:

• `[强制压缩中>>>]` — just before a compaction commits;
• `[压缩完成!]` — the instant a compaction lands; the next agent action (normally the continuing

loop's 模型请求中) then overwrites it. There is no 3 s fallback timer any more;

• Restored at conversation end — when the agent goes idle (the turn is fully done), an **empty

text** is pushed: the client puts the official label back and drops its replacement prefix.

Harness 0.2.0 moved that line into its own RunningStatus component — the old button[data-turn-process] > span now renders only settled turns — anchored on the container attribute data-chat-running:

<div data-chat-running>
  <span role="status" aria-live="polite">深度求索中</span>        ← visually-hidden announcement
  <span .runningDivider>
  <span .runningContent>
    <span .runningIcon>…whale animation (APNG mask + SVG fallback)…</span>
    <TextShimmer data-shimmer>深度求索中，用时1分14秒 ···</TextShimmer>
  </span>
</div>

So the client half substitutes just the leading phrase: it uses the announcement node's text as an anchor, splits the text at their common prefix, and keeps the remainder — the harness clock tail, the official trailing ··· included — verbatim. The whale animation icon and the divider are left exactly as they are: no colours, no font changes, no layout. The announcement node is never touched, so screen readers keep the official text.

A MutationObserver, connected only while a phase is active, writes both copies of the sentence: TextShimmer renders it twice (a real text node plus an aria-hidden animated highlight copy whose glyphs come from CSS ::after { content: attr(data-shimmer-text) }), so patching only the text node would let the sweep reveal the official wording. The observer re-applies in the same microtask in which React rewrites the label, so the clock keeps ticking and nothing polls.

Label text follows the app language: the host writes a locale-independent textId (the phase name) plus the canonical Chinese text, and the client half resolves it through its own ctx.locale zh/en/ja/ko dictionaries — an English UI shows Requesting model / Model responding / Running tool, a Chinese UI keeps the originals.

Badge text follows the app language: the host writes a locale-independent textId (phase name or working.N) alongside the canonical text, and the client half maps it to zh/en via its ctx.locale dictionaries — English UI shows English one-liners, Chinese UI shows the original Chinese.

Publishers are fail-safe: a messenger glitch can never disturb the actual compaction.

How it works

agent/request(payload, next)              # every model request
    return await next()                  # pure pass-through (thinking-off scopes
                                          # ONLY to the plugin's own summarizer)

agent/pre-step(payload, next)             # before each model step
    projectedTokens >= autoThresholdTokens?
        no  -> next()                     # let the request proceed
        yes -> compactRegion(head-before-retainLatestTokens, signal)
               return { kind: "reject" }  # no model request this step

agent/status({ agent, status })          # lifecycle transition
    status === "idle" && turnEndForceCompactionEnabled?
        -> compactNow(agent, freshSignal) # turn-end compaction

session/flush(session)                   # durability checkpoint
    select region -> project messages -> preview + shrink gate
    -> compaction.compactRegion(start, end, agent, signal)

Supporting modules:

• src/hooks/guard.js — agent/request pure pass-through + pre-step threshold gate +

process-local force flag (thinkingDisabled survives only as a legacy predicate).

• src/hooks/command.js — the /force-compact command (lazily registered).
• src/hooks/idle.js — turn-end forced compaction.
• src/hooks/wire-rewrite.js — retired; keeps only the historical note on why the

llm/stream seam cannot carry wire fields. No exports.

• src/engine/region.js — head/tail-anchored region selection (with the official pairing ledger).
• src/engine/summarizer.js — the one-shot LLM summarizer, aligned with official

compaction-basic in structure (target resolution, prefix-cache alignment, purpose:'compaction' tag, fail-closed finish classification, usage capture); the summarization instruction text is localized to Chinese (structure identical, copy localized, with both ` tags kept verbatim). The official engine still uses the English instruction — see the "摘要指令中文化" section in AGENTS.md`.

• src/engine/builtin.js — the builtin persistent transaction (official compaction/* vocab).
• src/engine/checkpoint.js — preview + shrink gate + delegation to the compaction service.
• src/core/projected.js — provider-anchored projectedTokens.
• src/core/ui-signal.js — the LiveUI messenger.

Install

As an installable package (recommended):

# from npm (published):
npm install @falling-ts/dsh-force-compact
# from git:
dsh plugin --profile web add github:falling-ts/dsh-force-compact
# from a local checkout:
dsh plugin --profile web add ./dsh-force-compact

Or, from a local checkout, as a --patch overlay without installing:

dsh web --patch dsh-force-compact/cordis.patch.yml

The plugin is loaded iff ~/.dsh/logs/dsh-force-compact.log gains:

[force-compact] debug logging enabled — writing [force-compact] lines to <absolute path>

Command availability — /force-compact loads lazily