dsh-block-ptc

dsh-block-ptc

English | 中文

Blackboard blocks for PTC mode in DeepSeek Harness.

Version 0.4.0 uses block_compact({ ids, content }). The old block_summary tool and summary/single id arguments are not supported. Restart DSH and start a new Block PTC session after updating.

The block protocol uses the built-in run_code transport. DSH's PTC presentation allows only run_code to be called directly, so the model declares blocks in the tool description:

run_code({ description: "[block: <ids>] <goal>", code })

A *block* is a blackboard region. Every program the model runs is tagged with block ids. When the content is no longer needed, or its results have already been reported and the model is moving to other work, it can submit retained content it writes itself to replace the block's messages. Information still needed for execution, replies or discussion remains available. The original messages stay in the append-only session log, so the human transcript keeps everything and replay stays deterministic.

• DeepSeek Harness 0.2.1-rc.2 or newer; no upper version bound
• Community plugin maintained by mengwEX
• Zero runtime dependencies — the only external import is node:crypto
• License: MIT

Table of contents

• Why
• Context and cache comparison
• How it works
• Install
• Quick start
• Reference
• Design notes
• Verification
• Troubleshooting
• Known limits
• Development
• License

Why

Automatic compaction condenses history when token pressure builds, and it decides what to condense by size. It has no idea that the last forty messages were one finished sub-task and the next ten are a new one.

This plugin lets the model draw that line itself: open a block, work inside it, and close it with a handover summary — so the context it keeps is the one it chose to keep. The model submits the summary inside its program call; the plugin does not run a separate summarizer model.

Context and cache comparison

Mechanism illustration, not an API benchmark. Both panels replay the same synthetic four-task workload with assigned token weights. Full bar = input context; blue = modeled cache hits, orange = modeled cache misses. Cached tokens still occupy the context window.

After a block closes, the next request carries a summary in place of its completed work. Replacing history can also invalidate the cached suffix: smaller context does not guarantee a higher cache-hit rate or a lower bill. The closing assistant/tool pair settles before replacement; original user messages remain. The baseline has not reached its automatic compaction threshold.

See the data, assumptions and reproduction steps. The plugin's tokensFreed is not a provider cache-hit measurement.

How it works

The model's whole surface is the built-in PTC transport plus one program-callable:

run_code({ description: "[block: <ids>] <goal>", code })   the only tool it may call directly
await tools.block_compact({ ids, content })                  callable from inside a program

1. The header in run_code.description names the blocks a program advances.

Its ids apply to the complete assistant message, including preceding thinking/text, and its tool results. Calls in the same assistant message contribute the union of their ids.

1. tools.block_compact({ ids, content }) replaces the complete interval from

the earliest to the latest occurrence of any target id with the retained content.

1. The summary inherits the union of the interval's ids minus the target ids.

It can participate in a later summary. A summary with no remaining ids stays.

1. If a tool pair in the interval is unfinished, the request is queued until

its result lands. A protected system/developer message refuses the entire interval; no prefix is silently replaced.

A A B A C B  -- compact([A]) --> S[B] C B
S[B] C B    -- compact([B]) --> T[C]
T[C]        -- compact([C]) --> U[]
A A B A C B -- compact([A, B]) --> S[C]

What the human sees afterwards: the transcript still shows every original turn (the log is append-only); the model's next request shows the summary instead. In the Web UI the summary renders as a compaction checkpoint node.

Install

Requirements: DeepSeek Harness >=0.2.1-rc.2 and its bundled runtime, with Cordis >=4.0.5. Neither peer range has an upper version bound. The plugin is a profile bundle: installing it adds one row to dsh.profile.bundles and one new agent preset, block-ptc. It does not modify the shipped ptc preset.

The version ranges allow newer hosts to load the plugin; they are not a record of completed compatibility checks. Live host verification for this release used DSH 0.2.1-rc.2. DSH's plugin loader includes prereleases when evaluating its peer ranges. The plugin checks the required tool/prompt methods before mounting and the session methods before summarizing, and reports missing capabilities. Method presence does not verify event semantics, preset configuration or model behaviour; these still need validation when the host changes.

From npm (recommended)

Find dsh-block-ptc in the Harness Plugin Manager and install it, or ask an agent with the Plugin Manager tool enabled to install the bundle:

plugin_manager  install_bundle  dsh-block-ptc

The package is published on npm. Restart the application after installation and select the Block PTC preset.

From a local checkout

git clone https://github.com/mengwEX/dsh-block-ptc.git

Install the absolute checkout path through the Plugin Manager:

plugin_manager  install_bundle  /absolute/path/to/dsh-block-ptc

Both methods use pnpm in the target profile. The local form installs a link: dependency for development. Versioned source archives are also available under GitHub Releases.

Manual install (equivalent, if you prefer files)

In ~/.dsh/profiles//package.json:

{
  "dependencies": { "dsh-block-ptc": "link:/absolute/path/to/dsh-block-ptc" },
  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-block-ptc"] } }
}

then run pnpm in that directory.

After installing

1. The preset appears in the session preset picker as Block PTC.
2. Restart the application once. The loader keeps a plugin module per

resolved URL, and installing a bundle changes the composition; a running host keeps the old module generation until it restarts.

1. Start a session with the Block PTC preset.

Uninstall

plugin_manager  remove_bundle  dsh-block-ptc

then restart. plugin_manager set_bundle dsh-block-ptc enabled=false disables it without removing the package.

Quick start

Work and discuss the results first. Compact earlier blocks when moving to other work, once their original content is no longer needed:

Explain how the tokenizer works.

After that discussion: move on to the lexer; organize the earlier block if

its original content is no longer needed.

You should see:

• the model calling run_code with a description such as

[block: tokenizer] Explain the tokenizer for everything it runs;

• a closing call to block_compact whose return value is

{"replaced": 3, "tokensFreed": 346} — how many messages were replaced and the estimated token count of the replaced messages (before counting the new summary);

• a … node sitting where those messages were.

The initial request includes the header requirement in the system prompt, native tool description and parameter schema. The SDK uses the same header format.

If a program call is refused with *"Every run_code call, including the first"*, that is the preset's guard working. Retry the program with the header; the refused call itself is not tagged.

Reference

Organize blocks around relatively independent units of work, reusing the id while continuing the same work. Compact a block when its content is no longer needed, or its results have already been reported to the user and you are moving on to other work. Keep content needed for upcoming execution, replies or discussion. Finishing a work step alone is not a reason to compact.

Header in run_code.description

Part · Type · Required · Meaning [block: ] · header · yes · Comma-separated, non-empty, unique block ids, such as [block: auth] or [block: auth, parser]. Ids must not contain commas, brackets or line breaks. `` · string · yes · The goal of this program, on the same line after the header. It is displayed as the tool row's summary.

run_code itself is DSH's tool; the plugin does not replace it. Its code/timeoutMs parameters, sandbox, parallel scheduling and result rendering use the built-in PTC behavior. The plugin aligns the model-facing header guidance and reads the header to tag surrounding messages.

Callable tools.block_compact

Parameter · Type · Required · Meaning ids · string[] · yes · Block ids to organize and close. content · string · yes · Written by the model. Organize the complete first-to-last interval for these ids. Preserve information still needed for subsequent work in full, with enough detail to continue directly. Briefly summarize information no longer needed; omit irrelevant or duplicate material. Preserve user requirements, corrections and constraints accurately. Record completed work, results, unfinished work and the next step.

The replacement text identifies information you retained from earlier work and is wrapped in …. It includes a Block ids line only when memberships remain. Empty ids stay in internal metadata. This format is separate from DSH automatic compaction; both can coexist.

On immediate completion, returns { replaced, tokensFreed, ids? }; ids, when non-empty, are the memberships inherited by the summary. tokensFreed is the estimated size of the replaced messages, before the new summary's cost.

If tool results or another compaction are still pending, returns { replaced: 0, tokensFreed: 0, pending: true, requestSeq, note }. This acknowledges queuing, not a completed replacement. The logged successful tool outcome lets the plugin resume the request after restart/fork. Deferred failures are logged; target memberships remain until a replacement commits. Missing target ids and protected messages reject the whole request without removing any memberships.

Preset block-ptc

The shipped ptc preset plus:

• the same tool-presentation.mode: ptc as the shipped preset, so the host's

own PTC collapse remains in force: only run_code may be called directly;