Skip to content

Latest commit

 

History

History
184 lines (162 loc) · 11.3 KB

dsh.md

File metadata and controls

184 lines (162 loc) · 11.3 KB

DSH adapter

Status: implemented (73 adapter tests, full suite green); enforcement live-proven on stock headless (guard-deny, lint block, pre-terminal completion block) and on dsh-tui (warn→ask, human /df-goal, review-block dispatch). Instruction pillar (agent/pre-step constitution prepend), all eight df-* commands (host-native, text-returning), and all six dev_framework_* agent tools are wired and live-proven; review children dispatch with the read-only odf-reviewer preset where the registry exists (TUI-proven), preset-less with prompt-level restriction + guards elsewhere. Children may neither touch review.md nor invoke gate tools (deny + redirect, both unit-pinned). Deliberate release still pending.

Agent tools

The same six dev_framework_* agent tools, callable by the model mid-turn: dev_framework_verify (mid-session gate check, reports only), dev_framework_set_profile (applies immediately), dev_framework_status (live state), dev_framework_init (scaffold + report), dev_framework_update (drift brief, mirror included — present each file before editing), dev_framework_runtime (read-only snapshot). The definitions are plain objects in the host's compiled tool shape — no host-internal import, no new dependency.

Same core (src/core/), different wiring: the DSH adapter registers the ODF gates on a DeepSeek Harness Cordis context. Project config is the same .dev-framework.yml (legacy .opencode-dev-framework.yml still read) in the project directory.

Mount

apply(ctx) is the plugin entry (opencode-dev-framework/dsh). One command wires the base install — the package declares a dsh.bundle layer, so no hand-written patch is needed:

dsh plugin --profile <name> add opencode-dev-framework

For the preset seam, layer the installer on top:

df install-dsh --profile <name>   # auto-detects the preset registry

The installer writes a managed odf-gates block into the profile's cordis.patch.yml, auto-detects the agent-preset registry, and leaves everything outside its markers untouched (rerun any time; --force replaces a hand-maintained entry). From source (local development): df install-dsh --profile <name> --dist /path/to/opencode-dev-framework/dist/adapters/dsh/index.js. Or mount by hand with a --patch overlay naming the built file:

- insert:
    - id: odf-gates
      name: /path/to/opencode-dev-framework/dist/adapters/dsh/index.js
- id: odf-gates
  inject:
    - tools
    - goals
    # Ask the human instead of logging: guard `warn` verdicts arrive as
    # `ask` decisions only when this seam is injected. Without it the
    # adapter allows with a warn log (agent-run headless keeps working).
    - approval
    # Reviewer dispatch: the adapter spawns specialist children through
    # this seam on review-blocks. Without it, review stays inline.
    - subagents
    # Read-only reviewer preset: ONLY on profiles whose composition
    # provides the agentPresets registry (dsh-tui does; stock headless
    # does not). Without it the adapter spawns preset-less (prompt
    # restriction + per-exec guards).
    # - agentPresets
dsh --profile headless --patch ./odf-livefire.patch.yml "your task"

Inject rule: name only services the profile provides. A patch inject: entry is a hard activation gate — listing a missing service pends the entire plugin (entry did not activate … pending (waiting for service: …)) with only a stderr warning, silencing every hook. Verify against dsh --profile <name> --dump-config before adding a seam; the adapter itself degrades gracefully, but only for seams that resolve.

The adapter resolves the project directory from ODF_WORKDIR, else the process working directory — run dsh from the project (or export ODF_WORKDIR). A missing or broken config error-logs and registers nothing; it never throws at mount.

Contracts

Mechanism DSH hook Strength
Protected paths + dangerous commands tools/pre-execute deny (+ structured info) Hard block before the tool runs. Shell redirect targets are guard-checked too. Live: .env write → write on protected path ".env" is blocked (matched ".env*") + {"name":"opencode-dev-framework","code":"guard-deny"}; file absent afterwards.
Pre-flight gate tools/pre-execute deny, before guardrails Hard block; advisory warns and continues; the artifact path stays writable (relative or absolute spelling).
Per-edit lint + format tools/post-execute Findings fail the tool call (block with the linter output as model-facing feedback) so the agent fixes its edit in the same turn instead of only learning about a landed edit later. Live: marker edit → [odf post-execute] your edit introduced lint findings; fix them and retry + lint failed for greet.js (exit 1) + {"code":"lint-block"}; the agent retried clean in the same turn. Timeouts, exit-127, and silent nonzero exits stay accept + error-log with the file tracked (infra the model cannot fix). Feedback is capped (4000 chars/body, 5 files + named tail).
Completion gate agent/turn-stopping + steer Blocking, pre-terminal: in standard/strict, a red verdict enqueues the failure as next-step work. The host awaits listeners and cannot end the turn while that queue is non-empty, so this is the behavioral equivalent of a stop-hook decision: block, not optional advice. Pass allows stopping; advisory reports without blocking. Live: after a one-edit task said "Done", the missing review blocked completion and turn 1 continued — the agent ran a style/test/correctness review loop, wrote the review artifact, and only then did the turn end (15 steps, one turn, no new turn). The blocking message is dropped when the turn already aborted. Budget exhaustion stands down loudly.
Warn tier allow + warn log on every hook Ceiling, verified: nothing provides the approval service on headless, so ask would unconditionally deny — advisory never blocks by construction. TUI half live-proven 2026-11-17 (dsh-tui, model muse-spark-1.3-contributor, proj-ask with protect_mode: warn): .env edit surfaced a human approval prompt, approved once, edit landed.
Kill switch profile off skips everything; protect_off stands down guardrails only Pre-flight, lint, and the gate still fire under protect_off.
Specialist dispatch subagents.startActivation at review-blocks + completion-notice fold On review-blocks (green tree, review missing/stale) the adapter spawns one child per reviewer kind (odf-pattern-guardian-N, odf-style-enforcer-N, odf-code-reviewer-N) via the spawn provider with delivery-to-parent; their closing messages fold into the next steer exactly once. Gate-blocks (red tree) dispatch nothing — reviewing broken code wastes runs. No seam, advisory/off, or child session → inline steer, unchanged. Live 2026-11-17 (headless): all three dispatched, notices folded, a real CommonJS-in-ESM finding fixed, gate PASS.

Differences from the OpenCode adapter

Stronger where the host allows more: pre-terminal completion blocking with same-turn recovery, model-facing post-execute block, structured denial identity, abort-aware steering, redirect-target guard coverage, adapter-dispatched reviewer children on review-blocks. Identical where the hosts agree: pre-execute deny hardness, warn→allow-with-log, pre-flight ordering and semantics, block budgeting, protect_off scope.

Instruction and commands

  • Constitution: agent/pre-step prepends the constitution, the duty roster, and any startup drift mention once per session, so the agent works under the contract from its first step (mirror of the OpenCode context-hook injection; refreshes when the config changes). Advisory-warn on load failure — the gates still enforce.
  • df-goal <objective>: checks native /goal and the profile, wraps the objective with the verification contract exactly once, and creates the host goal — the DSH-native shape of /df-goal. Live-proven 2026-11-17 (dsh-tui, human-typed objective): agent did the work, wrote a fresh review, dev_framework_verify returned DEV_FRAMEWORK_VERDICT: PASS, and only then completed the goal.
  • df-verify: runs the full completion gate on demand and reports PASS/FAIL (side-effect-free: never retries or blocks stopping).
  • df-profile <off|advisory|standard|strict>: switches profile; invalid names are rejected.
  • df-init / df-update: deterministic scaffold/drift-check in code, judgment half handed to the agent via followup. DSH-native: the scaffold also mirrors the shipped skills into .dsh/skills/, the host's scanned project root, and the brief tells the agent to load project-config with the skill tool and ask user-only questions (at most 3) with ask_user_question. Safe to re-run; mirrors never clobber user edits unasked and never read as drift.
  • df-status: live gate status (profile, config, level) plus host seam availability (tools/goals/approval/subagents/presets/sessionQuery) and who runs the formatter — a degraded mount reads as degraded, never as silently whole. It also reports continuity for the invoking session: clean, resumed after interruption, or unknown (see docs/plans/27-dsh-continuity.md). After a restart, prior gate state is unknown by rule — the gate re-verifies from scratch and a cached pass never survives the process.
  • Warn asks the human (TUI): a guard warn arrives as an ask decision when the approval seam is injected, so it prompts instead of scrolling by in the log. Child sessions never ask (they report back; the parent decides). Without the seam, warn allows with a warn log. Live-proven 2026-11-17 (dsh-tui, proj-ask, protect_mode: warn): .env edit prompted, approved once, landed.
  • Child sessions: the turn-stopping gate skips subagents (they owe no review duty — the parent answers for the shared tree), children cannot write review.md (child-artifact-deny; advisory warns), and children cannot invoke any dev_framework_* tool (deny + redirect; unit-pinned). Parentage is read synchronously from the host session header (origin/parentSession), no lookup needed. Live: the subagent attempted the review write, received the denial text, and reported back while the parent wrote the artifact.
  • Reviewer briefs: each dispatched child is prompted with the project brief first from .dev-framework/agents/<kind>.md, then from .opencode/agents/<kind>.md (the single edited source shared with OpenCode), then an embedded fallback — so DSH-only projects never need OpenCode's home directory.

Troubleshooting

  • Gates silent: check the host log for [odf] lines — a config load failure disables everything by design. Run with a valid .dev-framework.yml in the project directory.
  • Lint blocks every edit with the same message: the linter itself is broken (missing binary, bad config) — but a healthy linter prints findings and exits nonzero, while infra stays accept. Check the [odf post-execute] error log, not the model feedback.
  • Turn ends despite a failing gate: profile: off skips the gate, advisory reports without blocking, and budget exhaustion (gate.max_blocks) stands down loudly — all by design. The df-status command shows the live state.