@chrok/dsh-braid
适用于 Braid 的 DeepSeek Harness 插件：后台代理图、有限循环、实时更新和执行进度
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add @chrok/dsh-braid@0.3.6Braid 以 @chrok/dsh-braid 发布，当前版本为 0.3.6。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
@chrok/dsh-braid)A native DeepSeek Harness plugin for background Braid graphs, bounded loops,
isolated Git worktrees, live updates, pause/resume, and completion reminders.
It uses DSH's provider routing and credentials through ctx.llm; it has no Pi
runtime dependency. Tested against DSH 0.2.0-rc.2 and Node.js 22.19+.
DSH is in developer preview, so host peer versions are pinned to this baseline.
DSH support starts with Braid 0.3.1; the npm badge shows availability.
dsh plugin --profile web add @chrok/dsh-braid
For development, install this repository checkout instead:
npm ci
npm run build:dsh
dsh plugin --profile web add ./integrations/dsh
Restart the DSH profile after installation or rebuilding. The package includes
dsh.bundle metadata and cordis.patch.yml, so installation activates the plugin.
It requires the tools, llm, commands, systemPrompt, and jobs services,
which the standard DSH composition provides. Custom profiles must provide them.
Use your own profile name in place of web. Core @chrok/braid is installed
automatically at the matching version. No API keys belong in plugin configuration;
configure models through DSH. A node's model is an exact provider/model-id,
including any additional slashes in the model ID; omitted overrides use the parent
agent's model captured at submission.
| Capability | DSH interface |
|---|---|
| Submit a graph | braid({ goal, nodes, edges, promptTemplates?, loops?, options? }) |
| List this agent's jobs | braid_status({}) |
| Read a job | braid_status({ jobId }) |
| Read a specific invocation | braid_status({ jobId, executionId }) |
| Read a node's latest invocation | braid_status({ jobId, nodeId }) |
| Page earlier activity of an invocation | braid_status({ jobId, executionId, activityBefore }) |
| Atomically edit/resume | braid_update({ jobId, expectedRevision, ...patch }) |
| Resume without edits | braid_resume({ jobId, expectedRevision, executionIds }) |
| Cancel | braid_cancel({ jobId }) or /braid cancel <jobId> |
| Human progress snapshot | /braid [jobId], /braid list |
| Graph, execution details and controls | Braid in the session header or right-sidebar guide |
| Generic job progress and cancellation | DSH's native Jobs panel |
Submission immediately returns a short job-1 handle, a canonical UUID, and
nativeJobId (for DSH's generic job tools/panel). Braid tools accept the short
handle or UUID, exactly. Handles are scoped to the live agent; another agent or
session cannot retrieve them. Native job IDs belong to DSH's separate registry.
Submission receipts give the job IDs and how to wait for the job; they do not
repeat the submitted graph. Update receipts list the resulting graph without
prompts.
Click Braid in a session's header, or choose Braid from the right-sidebar guide. Braid's five tool calls also render as clickable transcript cards:
| Tool card | Recorded summary and navigation |
|---|---|
braid | Submission receipt and node count; opens the submitted graph once the receipt arrives |
braid_status | Recorded status, revision and execution progress; focuses a requested node/execution; list results provide a link for each job |
braid_update | Before/after revision, upserted/removed nodes, edge counts and resumed executions; rejected updates are marked as not applied |
braid_resume | Requested execution IDs and remaining pauses; a single execution links directly to its history |
braid_cancel | Cancellation requested or job already finished; opens the original job |
The main card opens the right-sidebar Braid tab in the call's owning session. Cards retain the result recorded at the time of the call; the sidebar shows the current graph and status. Raw arguments, results and errors remain accessible under Show tool details, along with DSH's inspector when available. Failed submissions and calls still preparing a new graph do not link to an unrelated latest job. Short handles in older receipts are fenced by the call timestamp; a job missing after a Host restart is reported as unavailable.
The panel is a native DSH tab: the sidebar provides docking, splitting, floating and fullscreen. It follows the session that owns the tab.
The Host sends structured snapshots through DSH's authenticated Remote transport, coalesced to at most one update per 150 ms per observer. Prompts, provider messages and node outputs are excluded from that stream; selected outputs and activity history are read separately. Running executions carry a compact activity summary; stream and tool-output activity refreshes it at most once per second. Switching sessions or closing the tab stops observation, while jobs continue. Disconnected controls are disabled; the panel retries the stream, then offers manual reconnect if retries fail.
The package declares dsh.client and exports ./client, a DSH module-loader
factory sharing the shell's React instance. The Web profile must provide
typert, remote, the slot renderer, conversation header, tool views and right sidebar.
Custom headless profiles can omit these services and retain the tools/commands.
Unloading the plugin removes its tab type, slots, styles and Remote methods.
The generic Jobs panel also streams a text flow diagram, node states, elapsed times, context
token estimates/provider reports, context capacity when available, tool counts,
and recent events; its progress line names the first running node's activity
phase, and /braid adds an activity line for each running node. Its own stop
action cancels the Braid run. Closing the panel
leaves it running. /braid returns a snapshot in the command UI; it does not open
Pi's terminal overlay or bind Pi's keyboard shortcuts. Headless profiles can use
the tools and commands without a Web UI.
The five graph tools expose the same execution controls as the Pi integration.
DSH presentation uses a native Web graph panel, jobs and commands; it does not
include Pi's Mermaid terminal renderer. Tool results are plain-text documents
for the model, in native and PTC mode alike. Each result value is { text, ... }:
besides text it carries only identifiers such as jobId, canonicalJobId,
status, revision, and paused IDs, which the Web client reads from the
result's presentation meta.
{
"goal": "Implement a fix, review it, and apply it",
"nodes": [
{ "type": "execute", "id": "implement", "prompt": "Implement and test the fix." },
{ "type": "execute", "id": "review", "prompt": "Review the implementation and report evidence.", "workspace": "read-only", "pauseAfter": true },
{ "type": "integrate", "id": "apply", "requireSuccess": true }
],
"edges": [
{ "from": "implement", "to": "review" },
{ "from": "review", "to": "apply" }
]
}
execute and decision require prompt; only decisions declare nonempty,
distinct choices and call decide. merge and integrate allow an optional
prompt and forbid workspace/choices. All four types accept model,
notifyOnCompletion, pauseAfter, and requireSuccess. Core validates every
submission and update before it takes effect.
Inside Git, each execution gets a fresh snapshot of its predecessor checkpoints;
roots include tracked and non-ignored untracked caller changes. Execute/decision
nodes default to writable worktrees. workspace: "read-only" keeps snapshot
isolation while removing write/edit/shell tools. Outside Git all workers are
read-only. Independent changed snapshots need an explicit merge node before
another ordinary worker can consume their combined code.
merge combines snapshots in an isolated worktree. integrate applies selected
changes to the invoking checkout, preserving user edits. Nothing automatically
integrates at job completion. Both expose constrained Git operations and require
finish_merge dispositions for every source execution ID. Checkpoints and
integration backup refs remain recoverable after worktree cleanup. A failed
integration can leave partial changes or conflicts; core never resets the caller.
Workers receive a fresh DSH context containing the goal, rendered node prompt, direct predecessor outputs, execution identity, and workspace/merge metadata. They do not inherit the parent transcript, skills, extension/MCP tools, or Braid itself. File and shell tools are DSH's own, so their schemas, guidance, and results match what the parent agent sees:
read, glob, and grep (dsh-tool-fs, dsh-tool-fs-search).write, edit, and bash (dsh-tool-fs, dsh-tool-bash) for writable Git
workspaces; also pwsh (dsh-tool-pwsh) on Windows.git when core provides Git access; finish_merge for merge/integrate nodes.decide only for decision nodes, with exactly one declared choice.Each execution runs these tools in its own Cordis context with local
providers rooted at its workspace (dsh-fs-local, dsh-bash-local,
dsh-subprocess-local), so they do not depend on the host's filesystem or shell
composition. DSH's read-before-write observation policy applies. Braid's
filesystem provider rejects writes outside the assigned workspace, to Git
metadata, submodules, symlinks, hard links, and special files. Shell commands use
host permissions and can bypass file guards; worktrees are not an OS sandbox.
Workers are instructed to keep writes local, preserve shared Git state, and avoid
global or externally visible actions unless requested. Commands run in the
foreground with no background jobs or sandbox escalation; timeout and
cancellation stop them, and processes a command leaves behind are stopped when
the execution ends, before its checkpoint. Ignored new dependencies, caches, and
build outputs are not checkpointed and disappear during cleanup. Shared services
and ports require execution-specific resources.
notifyOnCompletion: true sends an intermediate success/failure reminder.
pauseAfter: true additionally holds outgoing scheduling; independent branches
continue. Reminders identify the exact invocation and loop iteration in the job
data. Fetch braid_status, then use its current graph revision and paused
execution IDs:
{
"jobId": "job-1",
"expectedRevision": 0,
"executionIds": ["<paused-execution-id>"]
}
Pass this to braid_resume. braid_update accepts complete upsertNodes,
removeNodeIds, addEdges, removeEdges, promptTemplates, loops, and
resume. Use historical edge.executionId pins only in updates. Include new
nodes and their dependencies in the same update: a disconnected root can start
immediately. Rejected revisions/patches change nothing. Upserts replace whole
node definitions; supplied templates/loops replace their whole map/list.
removeEdges matches every identity field exactly; omitted fields are not
wildcards. Existing invocations retain their captured inputs and policies.
Finalized jobs cannot be reopened.
Bounded loops use a loops entry { id, entry, maxIterations } and one feedback
edge from a decision to that entry carrying choice and feedback: "<loop-id>".
maxIterations includes the first round. Loops cannot overlap or nest. Prompt
templates use {{name}} placeholders and node prompts such as
{ "template": "review", "variables": { "target": "src/runtime.ts" } }.
Variable names must match exactly; values are inserted literally.
See the execution-control guide
for the shared graph semantics.
Completion and pause messages use DSH agent.steer: a running agent consumes
them at the next step, and an idle agent wakes. Acknowledged messages are removed;
discarded messages retry when the agent returns to idle. DSH's generic job
controller may also show its native job completion notice. Tool descriptions, the
system prompt, and the submission receipt tell the agent to continue independent
work, or end its turn if it needs the result, and to retrieve results after the
reminder instead of sleeping or polling. Stopping a foreground response does not cancel
submitted jobs. Plugin or owning-agent disposal aborts workers, awaits cleanup,
and suppresses Braid reminders. Switching the UI to another still-live agent does
not dispose the original owner or redirect its reminders. Jobs are in memory;
they do not survive a DSH restart.
options accepts maxConcurrency (default 4), maxExecutions (default 1000),
maxToolRounds, maxToolCalls, nodeTimeoutMs, and graphTimeoutMs. Tool/time
budgets are unlimited when omitted. Limits count rejected tool calls too. Workers
receive remaining budget/deadline reminders before model requests. Graph deadlines
continue during pauses and do not reset on resume or update.
braid_status.usage aggregates DSH usage, including completed provider rounds
from workers that later fail or time out. Input/cache fields are disjoint;
totalTokens includes input, output, cache reads, and cache writes. Core runner
usage combines input/cache into inputTokens. DSH does not offer Pi's external
tool-cost accounting contract: repeated status reads return the same totals
without adding charges to the foreground agent. No dollar cost is inferred.
Text over 50 KB is truncated: the control fields come first, and the complete
text is saved as a private file in the host's temporary directory whose path
ends the preview (and is the value's fullOutputPath), for running graphs and
focused execution reads alike. Saved files remain available after job cleanup.
Worker git results read like DSH's bash output ([stderr], [exit code: N]),
and decide returns Recorded choice: <choice>.
npm run check:dsh
npm run test:dsh
npm run build:dsh
npm run test:package
Tests use scripted providers without network model calls. They exercise real
Cordis/DSH registration, native job ownership/control, canonical tool outputs,
reminder delivery and cleanup, graph controls, loops, budgets, filesystem guards,
and process cancellation. Web tests cover the native Gateway, the built browser
factory and Remote mounting, slot registration/unload, session switching, safe
text rendering, controls, revision checks, paging and disconnect cleanup. Package
smoke tests install the packed package outside the checkout, load its browser
factory and run a background worker. All dependencies share the root lockfile.
Use npm install --workspace @chrok/dsh-braid <dependency> for dependency updates.
Host contracts: DSH plugin packaging, tool authoring, client modules, right-sidebar extensions, and native jobs.