dsh-blackhole

English | 简体中文

A DSH port of k0valik/pi-blackhole's
brief compiler (VCC conversation-compiler), wrapped in a dual-pipeline
compaction engine.

Drop-in replacement for the official @deepseek-ai/dsh-compaction-basic
backend that routes inside the single summarize() hook:

• OpenAI (or any provider with a configured Responses endpoint) — the
  official remote path: summarization is delegated to the model server via
  the Responses API compaction_trigger (the same protocol Codex's remote
  compaction uses), and the opaque replacement history is persisted per
  session;
• remote failure (no endpoint, missing key, timeout, protocol error) —
  by default the region is compiled locally by a deterministic VCC-style
  compiler (zero model calls, near-lossless (seq N) pointers back into
  the durable session log), with the native one-shot LLM summarizer available
  via fallbackMode: "llm";
• every other provider — the local compiler, straight away, no network.

Remote compaction branch ports
algal/pi-openai-server-compaction
(MIT). The local compiler is a port of pi-blackhole's brief.ts compiler
(VCC conversation-compiler, MIT; rule lineage: lllyasviel/VCC →
dsh-compaction-instant) — the differential suite pins content-level
equivalence against the real pi-blackhole sources (see Equivalence
below).

Why

How it works

1. DSH decides to compact (pressure / overflow / /compact) and calls the
   engine's summarize() hook with the replayed conversation region.
2. The routed provider/model is resolved (durable request header first, agent
   options second) and matched against the configured endpoints.
3. Remote branch (matched endpoint): the region is converted into
   Responses input items (text, reasoning, tool calls/results), a
   compaction_trigger is appended, and the compaction response streams from
   {baseUrl}/responses. The assistant-authored summary becomes the readable
   checkpoint; the opaque compaction item plus the retained tail of user
   messages (Codex-style 20K token budget) is persisted per session. A later
   remote compaction for the same provider/model replays that opaque window
   and appends only the new trailing surface.
4. Fallback: any remote failure logs a warning and hands the region to
   the local compiler (instant, default) or the native LLM summarizer
   (llm). instant-then-llm tries the compiler first and only then the LLM.
5. Local compiler branch (no endpoint match, or fallback): a deterministic
   zero-model pass over the region that keeps ONLY original tokens — every
   tool call becomes one line * bash "ls" (seq 2 -> result 3), tool results
   never occupy entries (one recall away via the pointer), reasoning is
   elided, long text truncates with ...(truncated from seq N), noise XML is
   stripped, and a token cap drops the oldest rows first with an explicit
   [N entries elided: seqs a-b] note. The (seq N) pointers resolve against
   the REAL durable session log (each flattened message is matched to its
   stored event by id), so a recall tool mounted next to this engine restores
   the exact original content.

The engine subclasses the official BasicCompactionEngine, so all pressure /
retention / policy knobs, the token-meter pricing, and the context-overflow
recovery behave exactly as upstream.

Install

Requires DSH 0.1.0-rc.6 (web or headless profile).

# into the profile that serves your sessions
dsh plugin --profile web add dsh-blackhole
# or from a local tarball:
npm pack dsh-blackhole && dsh plugin --profile web add ./dsh-blackhole-0.2.0.tgz

The bundle patch:

• disables the official compaction-basic row (already disabled by the
  web-app bundle — idempotent),
• re-enables command-compact (the /compact command, which the web-app
  bundle disables; it is backend-independent),
• inserts this engine under its own row.

Exactly one compaction service ends up mounted; the dual pipeline lives
inside the engine.

Configure

In the profile's settings (or ~/.dsh/settings.yaml under the plugin key):

dsh-blackhole:
  # inherited BasicCompactionEngine knobs (all optional, same defaults as
  # @deepseek-ai/dsh-compaction-basic):
  thresholdRatio: 0.75
  retainRatio: 0.25
  auto: true

  # Responses-assisted knobs:
  endpoints:
    # direct OpenAI Responses
    - provider: openai
      baseUrl: https://api.openai.com/v1
      apiKeyEnv: OPENAI_API_KEY
    # any OpenAI-compatible gateway that forwards the Responses API
    - provider: '*'
      baseUrl: https://my-gateway.example.com/v1
      apiKeyEnv: MY_GATEWAY_KEY
    # official Codex backend (needs the beta-feature header)
    - provider: openai-codex
      baseUrl: https://chatgpt.com/backend-api
      apiKeyEnv: CODEX_TOKEN
      headers:
        OpenAI-Beta: responses=experimental
        x-codex-beta-features: remote_compaction_v2
  timeoutMs: 120000      # abort the remote attempt after 2 min
  fallbackMode: instant  # instant | instant-then-llm | llm
  retainedMessageTokenBudget: 20000
  persistRemoteHistory: true
  stateDir: ~/.dsh/plugins/dsh-blackhole/state

  # Local compiler knobs (all optional):
  compileMaxTokens: 8192     # floor; scaled by checkpointScale on big regions
  checkpointScale: 0.1       # cap = max(compileMaxTokens, shadowed x scale)
  checkpointCap: 65536       # hard ceiling
  textTokens: 512            # per assistant text/reasoning block
  userTextTokens: 1024       # per user text block
  toolCallTokens: 128        # per tool one-liner
  includeReasoning: false
  stripNoiseXml: true
  noisePatterns: []          # empty = built-in VCC patterns
  toolArgTools: []           # empty = built-in whitelist
  hideTools: []              # e.g. [TodoWrite, ToolSearch]

Endpoint matching: provider matches the DSH provider route the latest request
ran on (exact, or * for any); model matches exact id or a * glob.
Authorization uses apiKeyEnv (env var name) or apiKey (inline — never
commit a real key).

fallbackMode semantics (applies to remote failures only):

The legacy fallbackToLlm boolean still maps: false forces instant;
true behaves like the default. Targets with no matching endpoint always
take the local compiler (or, in llm mode, the native LLM).

Behavior notes

• Images: DSH stores image bytes in the attachment store, which a remote
  compaction call cannot resolve; image blocks are carried as an explicit
  "image content omitted" text visit instead of being silently dropped. The
  local compiler renders them as [image] (seq N) labels.
• Checkpoint framing: the engine returns plain text; the inherited
  backend wraps it in the standard <compacted-summary> checkpoint framing.
• Deployments with agent presets: presets mount their own compaction realm.
  If a preset also compacts, either disable auto on one side or drop the
  preset's compaction rows — two engines must not compact the same session.
• Normal-turn opaque replay remains adapter-owned: DSH's immutable
  llm/stream request has no message-rewrite hook. This package therefore
  provides the optional responsesCompactionReplay service. A Responses
  adapter should call prepareInput({ sessionId, provider, model, trailingMessages, endpoint }) immediately before building its HTTP payload;
  it returns [owned opaque replacement history, ...trailingMessages], including
  a final incomplete user/tool turn for the request being sent, or a portable
  conversion of the supplied DSH messages when no owned artifact is available.
  replayHistory(...) remains available for the compaction-side variant, which
  deliberately retains only completed trailing turns. Foreign provider/model
  state, legacy artifacts, endpoint mismatches, and fallback compactions are
  rejected or removed rather than replayed. The Responses compaction path uses
  the completed-turn contract automatically on the next compaction.

Adapter wiring contract (responsesCompactionReplay)

The seam is one method call inside the adapter that serializes an ordinary
Responses request. tests/protocol-smoke.mjs pins the whole matrix as
executable assertions; this is the shape an adapter must implement:

// Inside the Responses adapter fiber:
const replay = ctx.get('responsesCompactionReplay') as
  import('dsh-blackhole').ResponsesCompactionReplay | undefined

// Immediately before building the HTTP payload for a NON-compaction turn:
const input = replay === undefined
  ? dshMessagesToResponseItems(trailing)
  : await replay.prepareInput({
      sessionId,            // agent/session id (the opaque window is keyed by it)
      provider,             // durable route: e.g. 'openai'
      model,                // durable model: e.g. 'gpt-5'
      trailingMessages: trailing, // the DSH Messages being sent this turn
      endpoint,             // optional; pass the base URL if known
    })
// builder.send({ model, input, stream: true, store: false, ... })

Contract semantics (all enforced by RemoteCompactionStateStore):

• Owned artifact (same provider/model/endpoint, versioned details):
  returns [opaque replacement items, ...input items fortrailingMessages],
  keeping a final incomplete user/tool turn (includePending) so the request
  being sent is not lost.
• No state / foreign route / legacy artifact / endpoint mismatch: returns
  the plain DSH→Responses conversion (fail closed — never a stale opaque
  window). replayHistory() returns undefined in exactly these cases.
• Compaction turns: do not call prepareInput() with the compaction
  intent — RoutingCompactionEngine already replays the completed-turn
  window internally when it summarizes. The service exists for ordinary
  conversation turns only.
• Fallback compactions invalidate the stored window (state.remove), so
  a later same-route turn starts from DSH messages and cannot skip the new
  local checkpoint.
• Pure-text regions compress less than tool-dense ones (tool results cost
  zero tokens in the compiled view); a region the compiler cannot shrink is
  rejected fail-closed, exactly like the upstream instant engine's shrink
  guarantee.

Development

pnpm install
pnpm run typecheck   # tsc --noEmit against the rc.6 packages
pnpm run build       # esbuild → lib/index.js
node tests/smoke-load.mjs      # loader composition mounts the engine
node tests/protocol-smoke.mjs  # conversion/SSE/round-trip vs a local fake endpoint
node tests/hybrid-smoke.mjs    # compiler unit + routing (remote/instant/llm/compat)
node tests/equivalence/build-algal.mjs && node tests/equivalence/differential.mjs
                               # protocol equivalence vs the REAL upstream bundle
node tests/equivalence/build-blackhole.mjs && node tests/equivalence/differential-brief.mjs
                               # CONTENT-level differential vs the REAL pi-blackhole
                               # brief compiler (BRIEF-DIFF.md: 11/12 vectors aligned)
node tests/instant-blackhole-align.mjs
                               # regression suite pinning the aligned brief rules
node tests/equivalence/differential-real-session.mjs
                               # content differential on a REAL recorded pi session
                               # (live transcript, not synthetic vectors)
node tests/equivalence/entity-fidelity.mjs
                               # entity-level retention audit (paths/symbols/errors)
DSH_EVAL_KEY=... DSH_EVAL_BASE=... node tests/equivalence/eval-fidelity-llm.mjs
                               # LLM A/B: answer accuracy with full vs brief context
                               # (see FIDELITY.md; key/base/model/session via env)

Equivalence to the upstream port

tests/equivalence/ snapshots the upstream source at a pinned commit
(algal/SOURCE.json) and bundles it with pi dependencies stubbed (only the
computation helpers are replaced; the protocol code runs unmodified). The
differential test then feeds identical vectors to both implementations:
request body, replacement history (retention, 20K truncation, image
exemption, empty-message filtering), SSE parsing (success + every error
path), message conversion (pi↔DSH semantic projection), identity headers,
and a full local-endpoint round trip. 15/15 vectors pass.

Differences that remain are platform adaptation, not protocol drift:

• Eligibility detection: upstream auto-detects direct OpenAI / Codex
  models from the pi-ai registry (host must be api.openai.com); this port
  matches a declared endpoints (provider + model glob), so it can also
  target your own gateway. The upstream host gate would reject exactly the
  deployments this plugin is for.
• Checkpoint text source: upstream runs a parallel local summary and
  stores the remote artifact as details.remoteCompaction (pi has that
  slot); DSH's summarize() returns one text, so this port surfaces the
  server-side summary text as the checkpoint and falls back per
  fallbackMode. One LLM call at most — and by default, none.
• Images: pi carries image bytes (→ input_image); DSH only has
  attachment ids, so image visits become explicit placeholder text.
• Exposed knobs: retainedMessageTokenBudget (upstream's fixed 20K),
  timeoutMs, sendIdentityHeaders, installationId are extra options;
  defaults reproduce upstream behavior exactly.

License

MIT. Portions derived from
algal/pi-openai-server-compaction
(MIT) and the compiler rules of
dsh-compaction-instant
(MIT, VCC conversation-compiler port) — see LICENSE.