dsh-plugin-verispring
Verispring three-role session architecture plus a bundled local knowledge graph (manon), substantially improving main-session context and reducing premium model API costs.
中文 | English
What it enforces
| # | Gate | Behavior |
|---|
| 1 | Dispatch spec gate | subagent / subagent_fork requires the dispatch spec content to have appeared in the session (a read result containing the spec's first-line marker; state is persisted in the session log and survives restarts) |
| 2 | Resident scout | The first dispatch of a session is pinned to the scout role at runtime (description is a display label only); once resident, repeats are denied with a send_message reuse pointer; escape hatch touch /tmp/dsh-caseos-scout-reset-<pid> (path is in the denial), and the reset is persisted too. Child roles are persisted at spawn (session-state/<child session id>.json) and restored from the record and the session title after reloads, so a resident scout is never silently reclassified as executor |
| 3 | Map first + freshness | Non-scout dispatch requires <session workspace>/.project-map.md (project root = .git/.manon present; otherwise fail-open); it is also denied when main has advanced past the map's registered baseline — the denial points to a scout incremental recheck plus a map rewrite (write to that file registers the current HEAD; fail-open before the first baseline and when CASEOS_SCOUT=0) |
| 4 | Pinned model | Routes are enforced at runtime per role: the first dispatch uses the panel's scout route, later ones the executor route; explicit provider/model on the call is ignored. subagent_fork is always denied |
| 5 | Commit gate | git commit requires a prior read of ~/.dsh/specs/代码写作规范.md; the shape is forced to -F file -- explicit paths, with timeout/env/nice/nohup/stdbuf style wrappers seen through |
| 6 | Leader scope | The leader's tool face shrinks to the review five (bash/edit/write/read/read_image) plus the dispatch face (subagent/send_message/interrupt_agent/list_agents), intersected with the tools that actually exist in the leader's view (desktop serves them from the preset layer, headless from the root layer); dispatch tools are shadowed by slim definitions; subagent-base is unconditionally denied at the root layer (if the routing executor ever breaks, the model has no fallback to sneak through). Scout and executor subagents get the full face of the verispring-subagent preset, and scouts are hard-denied edit/write through the dispatch request. Kill switch CASEOS_SCOUT=0 drops the scout part of the division clause |
| 7 | manon bridge | Resolves the local graph CLI (MANON_KG_BIN > bundled manon/manon-kg > legacy ~/manon/manon-kg) and, when present, injects per role: the scout gets the full surface (commands, sourced invocation rule, ownership discipline), the leader gets one line ("graph facts come from the scout"), the executor gets one line — manon is scout-owned; leader and executors never invoke it directly; semantics in ~/.dsh/specs/Manon调用规则.md. The load-bearing part is the invocation rule: dsh's subprocess service strips KEY/TOKEN-shaped env vars from children (anti-leak), so a bare manon-kg sync always fails with a missing key — the injected form sources ~/.dsh/manon.env inside the bash command first (the scrub only strips the first hop; grandchildren inherit freely). Secret values never pass through or get printed |
| 8 | Secret hygiene | Credential/env files (manon.env, verispring.env, project .env*) cannot be read via read or echoed via cat/sed and friends (matched per command segment, so the sanctioned source prefix and pipes on manon output are not false positives); whole-environment dumps — bare env/printenv, ps eww, /proc/*/environ, docker inspect without --format — are denied |
| 9 | Runtime monitor | Role drift, gate denials, scout resets and subagent start/end (role + route + stop reason) are appended to ~/.dsh/verispring-monitor.jsonl, so audits no longer require decompressing session logs |
Receipts instead of polling
When a subagent finishes, DSH delivers a settlement receipt (including its closing report) into the leader's inbox and wakes the leader's turn; scout reports arrive as messages. The leader system prompt now says: end the turn after dispatching and wait for receipts; sleep loops, placeholder subagents and repeated list_agents polling are forbidden; the final answer comes only after every dispatched work has been receipted and accepted.
The bundle patch also configures the subagent tool: backgroundMode: continuable, maxDepth: 1,
and the executor persona; both presets turn modelSelectionSettings off on tool-subagent
(routes are enforced per role, so model selection has no effect, and when it is on the subagent
tool registers into each session's own layer where the routing wrapper cannot shadow it). The
dispatch entry uses DSH's official activation API and returns a child id immediately; use the
child continuation tools for subsequent messages. In headless/CLI runs the process exits with
the turn, so child work is not retained after the process ends.
Context compaction (per role)
| Role | Mounted on | Trigger → summary cap |
|---|
| Main session (leader) | compaction group of the standard preset | 40% of the context window (~400k on a 1M window) → summary capped at 40k tokens |
| Scout/executor subagents | compaction group of the verispring-subagent preset | 60% of the context window (~600k) → summary capped at 60k tokens |
Both policies prune oversized tool results first (a result over 8192 characters keeps its first
4096 and last 1024), then condense the safely balanced history with DSH's structured template; no
verbatim tail is kept, and context overflow retries automatically. The summary length is chosen
by the model from a fixed template; the cap only bounds it, and real summaries usually run far shorter.
Subagents on verispring-subagent: the harness spawn request has no preset field and a child
inherits its parent's preset by default; dispatch-gate switches the child inside its creation
window (agent/created, before the first prompt) and records an agent-preset/selected event,
so a cold resume recomposes from the session log. The headless one-shot runner
(dsh --profile … "<task>") composes no preset for the main session, so the main session does
not get the standard 400k policy — only a root-level compaction-basic if the profile enables
one; subagents are unaffected.
Install
# Install / update (tracks main; pin a release with a tag like #v1.3.3)
dsh plugin --profile <your-profile> add github:brandonzyy/dsh-plugin-verispring
# Desktop app: Settings → Plugins → install, paste the same spec
The desktop app enables HMR by default (the base bundle turns it on whenever a profile
context exists), so installs initiated through the plugin manager apply immediately —
no restart needed. Already-running sessions keep their current tree; new sessions and new
dispatches pick up the new one. A restart is only required where HMR is explicitly disabled
(headless/SDK/ACP). Updates: uninstall and reinstall the same spec (the platform reserves
the Update button for official on-demand bundles).
manon component (bundled)
manon/ ships the full local code-graph CLI: the manon-kg entry, the
matrixone_graph/codeindex/core sources, and a frozen requirements.txt
(click/httpx/networkx/numpy/rich/PyYAML + the full tree-sitter language family — all
prebuilt wheels). Bridge resolution order: explicit MANON_KG_BIN > bundled component
(version-matched to this package) > legacy ~/manon/manon-kg.
Indexing defaults to every mainstream language (Python/TS/TSX/JS/Java/PHP/Go/Rust/C/C++/C#/Ruby/Lua/Bash, matching the frozen tree-sitter packs) — a bare sync indexes all of them, with no shallow detection gating; missing packs degrade per language without crashing. query -j outputs a slim payload by default (compact fields, ≤40 entities, ≤60 relations, truncated descriptions/snippets); pass --full for the complete payload.
On first run the component bootstraps a Python venv and installs its dependencies (one-time
network, python3 ≥3.11 required), then works offline. The venv lives under
${DSH_HOME:-~/.dsh}/manon-kg-runtime (the installed package directory is read-only; the
runtime never writes into the package). tree-sitter language packs load
dynamically; a missing pack only downgrades that language. Keys come from
~/.dsh/manon.env + ~/.dsh/verispring.env, sourced inside the bash command by the
injected invocation.
Prerequisites (the gates tell you what is missing)
- Profile composition: the agent preset registry and a
preset-standard entry (shipped by the
desktop app and the web bundle). A bare dsh-headless profile has neither, and the plugin patch
fails to load with entry "preset-standard" not found.
- Spec files:
~/.dsh/specs/子代理派遣规范.md and ~/.dsh/specs/代码写作规范.md
(resolved against the home directory). Missing specs mean the corresponding gate keeps
denying with directions — by design: every denial must be satisfiable.
- Model route: the profile needs a
verispring provider with a deepseek-flash
model (via llm-pi-ai or an equivalent adapter). For another gateway, update
agentOptions in cordis.patch.yml and DEFAULT_ROUTES in
gates/dispatch-gate.js, keeping the two in sync (a saved panel wins via ~/.dsh/verispring.json).
- manon (optional): bundled — no local install needed. Keys live in
~/.dsh/manon.env
(MANON_EMBEDDING_API_KEY, sync embeddings) and ~/.dsh/verispring.env
(VERISPRING_API_KEY, deep-query fallback); the injected invocation sources both files
itself, so model/endpoint overrides (MANON_DEEPQUERY_* / MANON_EMBEDDING_*) set there
apply to every session. Without manon, every other gate is unaffected.
Configuration panel (v1.3+)
After install, the bundle detail page displays the configuration directly. The panel uses
the DSH shared form controls and reads the live model catalog, so provider and model choices
stay aligned with the Models configuration. The three agent route slots are editable and apply on save; the main session uses the native DSH model picker.
While the panel has never been saved (everything at defaults), the plugin rewrites no
enforcement surface — verispring.json and manon.env keep your
native values:
| Panel field | Persisted to | Takes effect |
|---|
| Surveying/execution provider / model / effort | ~/.dsh/verispring.json | each route is enforced by the dispatch gate; execution defaults are also written to tool-subagent |
| Manon Deep Query provider / model / effort | MANON_DEEPQUERY_* keys in ~/.dsh/manon.env | flows into manon-kg with the sourced invocation |
| embedding endpoint / model | MANON_EMBEDDING_* keys in ~/.dsh/manon.env | re-run sync after switching models |
Writes are rooted at the Harness home (DSH_HOME), so multi-home/probe environments never
cross-contaminate; manon.env upserts only the panel-owned keys and preserves your
credential lines. The plugin ships the verispring llm-pi-ai route. Surveying and execution
each have independent provider, model, and reasoning-effort selectors. The Verispring key is
stored through DSH credentials; saving it discovers the gateway model list and refreshes the
catalog. The embedding model remains a text field.
Model configuration guide
Three agent route slots are configurable in the plugin panel; the main session uses DSH's native model picker.
| Slot | Where | Recommendation |
|---|
| Surveying / execution agents | independently selected in the plugin panel | DeepSeek Flash for both by default; each route can choose its own provider, model, and effort |
| Manon Deep Query | choose the verispring provider, model, and effort in the panel; key falls back to VERISPRING_API_KEY | DeepSeek Flash + off (shipped as recommended); saving writes ~/.dsh/manon.env and the sourced invocation uses it. |
| embedding | env: MANON_EMBEDDING_URL / MANON_EMBEDDING_MODEL / MANON_EMBEDDING_API_KEY (defaults to SiliconFlow BAAI/bge-m3) | the built-in bge-m3 is the recommendation; switching requires a re-sync to rebuild vectors |
Minimal main-session + gateway config (goes into the profile's cordis.patch.yml; pairs with
the plugin-pinned verispring/deepseek-flash route):
- id: llm-pi-ai
config:
providers:
verispring:
displayName: Verispring
apiKeyEnv: VERISPRING_API_KEY
api: anthropic-messages
baseURL: https://api.verispring.cn
models:
- id: claude-opus-5-5
name: Claude Opus 5.5
contextWindow: 1000000
maxTokens: 128000
compat:
forceAdaptiveThinking: true
reasoningEfforts:
low: low
medium: medium
high: high
xhigh: xhigh
max: max
- id: deepseek-flash
name: DeepSeek Flash
contextWindow: 1000000
maxTokens: 384000
reasoningEfforts:
'off': null
low: low
high: high
max: max
- id: agent-default-model
config:
provider: verispring
model: claude-opus-5-5
Exclusive discounts: contact the package author — 20% off Claude, 50% off DeepSeek Flash; WeChat: jinyong0716.
Compatibility
peerDependencies pins @deepseek-ai/cordis 4.0.4 || ~4.0.5-alpha.1, and engines.dsh
covers dsh 0.2.0-rc.2 through 0.2.1-rc.1. Incompatible installs are rejected up front; the official
exemption flow exists for force-installs.
Upgrade smoke check
Run pnpm smoke after a dsh upgrade for manifest and syntax checks. Set DSH_BIN and
DSH_SMOKE_PROFILE to add an official --dump-config composition check against an isolated
profile; the check must find the dispatch gate, configuration entry and subagent preset.
Dependencies and upgrade surface
- The plugin itself imports
node:fs / node:os / node:path / node:url only — no npm
runtime dependencies. The manon component freezes its Python dependencies in
manon/requirements.txt.
- cordis surface in use:
ctx.tools.guard, ctx.on("tools/result"), ctx.on("agent/created"),
ctx.tools.restrict({allow/deny}), ctx.tools.schemas/get/register, ctx.systemPrompt.section,
ctx.inject, ctx.logger.warn.
- The manon component tracks the upstream manon repository; after upstream changes, re-test
sync/query/deep-query as a set before updating the component here.
Uninstall
dsh plugin --profile <your-profile> remove dsh-plugin-verispring
Desktop: deselect and remove on the plugins page.
License
MIT
