Hyperionjust/dsh-tool-underseal ↗★ 2

dsh-tool-underseal

提供封装了安全适配器的模型端类型化工具 适合需要用哈希绑定的任务文件、调用边界检查和追加式证据记录管理代理委派的用户。

包名
dsh-tool-underseal
兼容性
待验证
Harness 依赖范围
^0.1.0-rc.0
Cordis 依赖范围
^4.0.1
版本
0.1.4
许可证
Apache-2.0
最近更新
2026年8月14日

安装

$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:Hyperionjust/dsh-tool-underseal

dsh-tool-underseal

English | 中文

CI npm license

The one-breath pitch: chat is transport, not authorization. Authority is a hash-sealed assignment file; evidence is append-only and re-derivable by any third party; and every boundary fails closed — sealed tools, a worker check-in lock, and byte-pinned supply-chain sentinels — behind a single dsh plugin add dsh-tool-underseal.

Tested on DSH 0.1.0-rc.5 — runtime mounting smoke test passed: dsh plugin add + dsh --dump-config mounts both layers (underseal and underseal-guard), and the full ceremony chain (doctor → seal → start → event → audit → retire) ran end to end through the vendored adapter in a real Git repository. Two field notes: when dsh plugin add takes a local path containing spaces, wrap it in literal double quotes (dsh plugin --profile p add '"D:\Project Hyperion\A_Deepseek Harness Workspace\underseal-dsh"') — the CLI joins pnpm args through a shell without quoting; and after sealing, commit the lead plane (.underseal/, .underseal-runs/) before the worker starts — the normative scope audit fails closed on uncommitted control-plane files (see the bundled skill).

Model-facing typed tools that wrap the frozen, reviewed underseal adapter for the DeepSeek Harness.

Underseal is a hash-sealed, file-authorization protocol for delegating bounded work between AI agents. Its frozen Python verifier is the only authority; this package is a process shell only — it never reimplements validation. Each tool spawns the vendored adapter through the ctx.subprocess seam, requires the adapter's canonical UNDERSEAL_ADAPTER_* marker, and throws with the adapter's E_* diagnostic on failure.

The package also ships a DSH skill (skills/underseal-delegation/SKILL.md) that documents the delegation workflow in DSH terms (subagent / subagent_fork / workflow / goal), and reference files under skills/underseal-delegation/references/.

Field record: the ceremony's shape in production

A three-day production run of the original underseal workflow (Codex as lead, DeepSeek workers, August 2026) left OpenAI-side metering worth reading as a design signal — with two caveats: it predates this DSH plugin, and it mixes Codex's own context with underseal's, so no clean per-part attribution exists.

Metric (3 days, weighted)Value
Input cache hit rate99.164%
Total input289,510,152 tokens
Total output1,669,568 tokens
Input/output ratio≈ 173:1
Effective input cost at 0.1× cached reads≈ 31.1M tokens (≈ 89% saved)

Two honest readings:

  1. The 99% cache hit rate is a property to keep. Sealed assignments, receipts, dispatch bindings, and ceremony rules are stable, hash-bound text, so long prompt prefixes cache almost perfectly. Protocol stability is cache-friendliness.
  2. The 173:1 ratio is the tax of carrying the ceremony inside the chat. The same roughly 100K-token prefix was re-read thousands of times; caching made it cheap but did not make it light — rate limits, latency, and the exposed prompt surface all paid for it.

This plugin is the correction: authority lives in files, not in the prompt. A steady-state turn carries the 8 tool schemas (~1–2K tokens) plus bounded tool results ({marker, payload, exitCode, stdout, stderr}); the assignment is read exactly once by the worker that must obey it, and evidence never re-enters the context. A normalized per-task benchmark (sealed vs. unsealed, same task) is in BENCHMARK.md — run it and fill in a real Δ.

Measured on DSH 0.1.0-rc.5 with deepseek-v4-flash, the seal overhead is a flat ~10.4K-uncached-token per-task constant — not a percentage tax (plus tens of seconds of wall clock, +10s trivial / +54s real task): on a trivial one-file task it was 42% of total input; on a real coding task (a Python module plus a 16-test suite) it dropped to 14% — and it keeps shrinking as the task grows. Full tables and caveats in BENCHMARK.md.

Benchmark: what sealing actually costs

Measured end-to-end on DSH 0.1.0-rc.5 with deepseek-v4-flash, same task run twice — unsealed (A) vs. the full sealed ceremony (B):

Task (A → B)uncached Δwall-clock Δoverhead as % of total input
Trivial: create one file+10,420 tokens+10.2s41.7%
Real: Python module + 16-test suite+10,282 tokens+54.3s13.8%

The seal is a flat ~10.4K-uncached-token per-task constant — not a percentage tax. The token bill barely moves as the task grows (+10,420 → +10,282), so its share of a task's input falls from 42% on a trivial one-file job to 14% on a real coding task and keeps shrinking. (Wall clock grows a little more, since the ceremony adds model round-trips whose latency scales with reasoning.) Full per-run tables, method, and caveats: BENCHMARK.md.

Status: out-of-tree bundle

This directory is an out-of-tree plugin package that doubles as an installable DSH bundle: package.json declares dsh.bundle = { patch: "./cordis.patch.yml" }, so dsh plugin add activates its layer automatically. It compiles with a plain tsc -p . (see tsconfig.json) and is not yet registered in the monorepo's tsconfig.host.json / knip.json / root workspaces. See Inlining.

Install

Three official forms (publish guide):

# 1. npm (preferred): prebuilt lib/ ships in the published package
dsh plugin --profile  add dsh-tool-underseal

# 2. Git checkout: pnpm runs this package's `prepare` (tsc -p .) after fetch;
#    the first add fails until you allowlist the build in the profile's
#    pnpm-workspace.yaml (copy the exact key pnpm printed):
#      allowBuilds:
#        dsh-tool-underseal: true
#    then re-run, pinning a commit:
dsh plugin --profile  add github:you/dsh-tool-underseal#

# 3. Tarball: no build permission needed at all
pnpm pack
dsh plugin --profile  add ./dsh-tool-underseal-0.1.0.tgz

Verify the layer without booting, then boot:

dsh --profile  --dump-config   # shows a "# == dsh-tool-underseal" layer
dsh --profile 

Uninstall: dsh plugin --profile remove dsh-tool-underseal removes both the dependency and its layer.

Treat allowBuilds as what it is: permission to execute this package's code at install time, outside any agent sandbox. Prefer the npm or tarball forms when you do not want to grant it.

Service API

Two plugins ship in this package:

  • Plugin name: tool-underseal

  • inject: ['tools', 'subprocess'] — the plugin loads only when both the tool registry (ctx.tools) and a subprocess provider (ctx.subprocess) exist.

  • Contribution: registers eight model-facing tools on ctx.tools.

  • Plugin name: underseal-guard (subpath dsh-tool-underseal/guard)

  • inject: ['tools']

  • Contribution: registers one monotonic execution guard on ctx.tools — the worker check-in lock (see Worker check-in lock).

Config

tool-underseal:

FieldTypeDefaultMeaning
adapterPathstringvendored python/underseal_adapter.py (absolute, resolved at load)Adapter script; when pythonPath is empty, an executable name or absolute path instead.
pythonPathstringpython (Windows) / python3 (POSIX)Interpreter prefix for the .py adapter script. Empty string spawns adapterPath directly as an executable.
cwdstringprocess.cwd()Child working directory. The adapter resolves its workspace from --workspace-root, so this only affects PATH-relative tooling.
graceMsnumber30000Grace period (ms) for the subprocess terminate escalation.
outputMaxBytesnumber65536In-memory cap per output stream before tail retention.
spillMaxBytesnumber4194304Whole-stream spill cap per output stream.

underseal-guard:

FieldTypeDefaultMeaning
blockedToolsstring[]['write', 'edit', 'pwsh', 'bash']Tool names whose mutations are denied while READY evidence is missing.
cacheTtlMsnumber2000Verdict cache lifetime (ms) per repository; the small underseal state files are re-read when stale.

Defaults are self-contained: the reviewed adapter is vendored inside the package, so a bare dsh plugin add needs only a Python interpreter on the host. Override pythonPath: '' + adapterPath: underseal-adapter to use a separately provisioned console-script install instead.

Vendored verifier

python/ carries the exact reviewed bytes, not a moving branch:

  • Upstream: https://github.com/Hyperionjust/underseal
  • Reviewed upstream commit: 18f85a6b3bc89a8b3325a9bd665ee51a8ab3d225
  • The underseal.py bytes match python/underseal.pin.json (SHA-256 130c86e0…); python/.gitattributes forces LF so checkout-time CRLF rewriting cannot drift the pinned bytes.
  • Apache-2.0: LICENSE and NOTICE ship alongside.

Treat every vendored-verifier update as a new supply-chain review (skills/underseal-delegation/references/maintenance.md).

Supply-chain sentinels

The plugin runs three byte-level anti-forgery checks inside apply() before registering any tool, so a tampered package cannot activate silently:

  • E1 — vendored verifier bytes. SHA-256 of python/underseal.py must equal the pin in python/underseal.pin.json; python/underseal_adapter.py must exist. On any mismatch the plugin logs error and registers nothing (the whole package goes silent rather than run a drifted verifier).
  • E2 — skill body pin. Every byte of the skills/underseal-delegation/SKILL.md body (the range after the closing frontmatter --- line) is hashed and compared with the metadata.pin value in its frontmatter. Drift logs a warn and still loads the skill — the skill is guidance, not authority, so E2 never blocks tool registration.
  • E3 — bundle patch bytes. SHA-256 of cordis.patch.yml must equal the pin in cordis.pin.json. A mismatch logs error and registers nothing, preventing a supply-chain-rewritten layer from activating.

Pin file locations: python/underseal.pin.json (E1), the metadata.pin frontmatter line of skills/underseal-delegation/SKILL.md (E2), and cordis.pin.json (E3). The expected hash always comes from the pin document itself, so a missing, corrupt, or malformed pin is itself a fail-closed condition.

Re-pinning is a new review action. After a reviewed change to the verifier, the skill body, or the bundle patch, recompute the pins with:

powershell -ExecutionPolicy Bypass -File scripts\repin.ps1

The script prints the three new SHA-256 values, rewrites the two pin JSON files, and updates the SKILL.md frontmatter metadata.pin line (body bytes are never touched). It is idempotent: re-running it with nothing changed leaves every file byte-identical. Inspect the printed values and commit the changed pin files as a new supply-chain review.

Tools

Every tool returns the same canonical value on success (output.schema, additionalProperties: false):

{ marker: string, payload: JsonValue, exitCode: 0, stdout: string, stderr: string }

marker is the adapter's exact success token; payload is the parsed JSON the adapter emitted after it. On any failure (non-zero exit, or missing the expected marker) the tool throws with the adapter's E_* code and stderr — there is no success value with a failure marker. No tool runs acceptance commands, performs Git commits, or performs network operations; each mirrors exactly one adapter subcommand.

ToolAdapter subcommandRequired markerArgsLead / Worker
underseal_doctordoctorUNDERSEAL_ADAPTER_OKworkspaceRootread-only, either
underseal_pinpinUNDERSEAL_ADAPTER_PIN_OKworkspaceRoot, replace?lead
underseal_sealsealUNDERSEAL_ADAPTER_SEALEDworkspaceRoot, taskName, expectedMode (owner|mechanical), expectedRole, dispatchId?lead
underseal_startstartUNDERSEAL_ADAPTER_READYworkspaceRoot, taskName, expectedMode, expectedRole, summary?worker
underseal_eventeventUNDERSEAL_ADAPTER_EVENT_OKworkspaceRoot, taskName, expectedMode, expectedRole, state, summaryworker
underseal_resumeresumeUNDERSEAL_ADAPTER_RESUMEDworkspaceRoot, expectedRole, hostSameAgentConfirmedlead
underseal_auditauditUNDERSEAL_ADAPTER_AUDIT_OKworkspaceRoot, taskName, expectedMode, expectedRolelead
underseal_retireretireUNDERSEAL_ADAPTER_RETIREDworkspaceRoot, expectedRolelead

Notes that are load-bearing for the protocol:

  • expectedRole is a free string, validated against the Underseal role grammar [a-z][a-z0-9_]{0,63} (the adapter's --expected-role is type=_role_name, not a fixed enum). deepseek_owner / deepseek_coder are this skill's convention, not the adapter's closed set.
  • underseal_event.state is the adapter's PROGRESS_STATES minus READY. The CLI accepts READY as a legal choice, but READY is the activation boundary that underseal_start owns; the enum excludes it so workers cannot emit a second activation event through the generic event path.
  • underseal_resume.hostSameAgentConfirmed is a required boolean; the tool refuses false without invoking the adapter, and only passes --host-same-agent-confirmed when true.
  • underseal_seal.dispatchId is required for a full-ceremony assignment and must be omitted for lite (the adapter enforces both directions).

Skill

The bundled skill documents the whole ceremony in DSH terms. DSH's filesystem skill provider does not scan npm package directories, so link it into a scanned root once per machine or project:

# project-scoped (committed to the repo):
mkdir -p .dsh/skills
cp -r node_modules/dsh-tool-underseal/skills/underseal-delegation .dsh/skills/

# or user-scoped:
cp -r node_modules/dsh-tool-underseal/skills/underseal-delegation ~/.agents/skills/

The session skill catalog then lists underseal-delegation; loading it (the skill tool or a /underseal-delegation gesture) injects the workflow whose steps name these tools.

Worker check-in lock (guard)

The second plugin (dsh-tool-underseal/guard, plugin name underseal-guard) turns "call underseal_start before touching project files" from skill guidance into a machine rule in the tool pipeline.

Enforcement seam

The guard registers through ctx.tools.guard(), not the reorderable tools/pre-execute waterfall. The contract (packages/core/tools README, "Public API") makes the difference explicit:

ctx.tools.guard(guard: ToolGuard): () => void — Register a monotonic synchronous execution guard after tools/pre-execute: returning a reason denies the call, while undefined leaves it unchanged. A plain-context guard applies globally … Later waterfall listeners cannot turn a guard denial back into permission.

and ToolGuard is (execution) => string | undefined, evaluated "after the reorderable pre-execute waterfall and before dispatch". A machine rule must not be reversible by reordering a waterfall, so the monotonic guard API is the enforcement point. The guard receives the full identity-protected Readonly (name, arguments, agent), which supplies the caller agent's session.header.cwd for the repository lo