opencode-plugin-dsml-fix/docs/STATUS.md

PROJECT STATUS / HANDOFF

Read this first when resuming. It captures the goal, the design, every decision, current test state, and the exact next steps. Companion docs: docs/PATTERNS.md (variant catalogue) and docs/TEST-MATRIX.md (test ↔ behaviour map).

1. Goal

Build an OpenCode V2 plugin that fixes DeepSeek "DSML" tool calls that leak into assistant text instead of being parsed as structured tool calls. Two consumers: fix new streams and repair old stored transcripts.

2. Hard facts established (do not re-investigate)

• OpenCode has no DSML handling anywhere. Upgrading will not fix it. grep -ri dsml over the whole v2 source = 0 hits. Installed binary = 0 hits.
• Installed OpenCode: v2.0.18. Latest stable latest = 2.0.22. Nightly dev tag = 0.0.0-dev-*. We target 2.0.22.
• V2 source repo = anomalyco/opencode, default branch v2 (HEAD 2026-10-04). Worktree: /code/opencode-v2. (The older /code/opencode-src is sst/opencode, branch dev, which is V1 — not what we build against.)
• Failing path in the user's real session: provider opencode-go, model deepseek-v4.1-flash, package @ai-sdk/openai-compatible, baseURL https://opencode.ai/zen/go/v1. The opencode (Zen) provider uses the same shape.
• Trigger (evidence from a real long-context session: an Android speech-to-text project on opencode-go/deepseek-v4.1-flash): all leaks happen late in a huge context (seq 5177+ of ~5700 messages). Degradation: outer <DSML tool_calls> opener missing, invoke opener mangled to a bare parameter name="edit", and only inner params carry the DSML token. finish_reason was stop. Matches vLLM #48931 / #54686.
• Two extra hypotheses confirmed: (a) the provider backend's greedy text→tool-call extractor can turn arbitrary prose containing a tool-call-shaped tag into a real call (we saw this with the user's own messages); (b) the extractor is the same layer that fails to parse legit DSML at long context.

3. Where to insert the middleware (verified against /code/opencode-v2)

Chain for the AI-SDK provider path:

@ai-sdk/openai-compatible SSE
  → LanguageModelV3 doStream()
  → LanguageModelV3StreamPart stream
  → [ctx.aisdk.hook("language") + wrapLanguageModel]   ← OUR MIDDLEWARE
  → streamPartEvents()  packages/core/src/aisdk.ts      ← OpenCode lowering
  → LLMEvent.toolCall / stepFinish
  → runner/step.ts  dispatches tool-call events

• Enter at ctx.aisdk.hook("language", ...) (PluginContext field aisdk, type AISDKDomain with hook: ModelHooks<AISDKHooks>). Replace event.language with wrapLanguageModel({ model: event.language, middleware }).
• We must return AI-SDK LanguageModelV3StreamParts. OpenCode already converts tool-input-start|delta|end and tool-call into LLMEvent.toolCall, then runner/step.ts:117 dispatches it. finish.finishReason.unified must become "tool-calls" (else runner sees stop/unknown).
• Other usable hooks if needed: ctx.session.hook("http.response"|"http.request"| "context"|"retry"|"prompt"), ctx.event.subscribe, ctx.session.synthetic/prompt, ctx.storage. Plugin package @opencode/plugin (v2.0.22), Plugin.define({ id, setup }).

4. Prior art (nothing to duplicate)

• CherryStudio (peer Electron app, NOT OpenCode): deepseekDsmlParserPlugin.ts, PR #14747. Streaming state machine + wrapGenerate. We port its algorithm.
• openclaw (peer agent): packages/ai/src/transports/openai-completions-dsml.ts
  • deepseek-dsml-grammar.ts. Doubled-bar markers, buffer cap, chunk boundary.
• pi-dsml (peer agent, npm pi-dsml@0.0.1, unpacked at /tmp/opencode/package): grammar with mangled calls> variant, ranges model, code-fence guard, string=false JSON rule. We port its parse.ts shape.
• vLLM #54686: leak taxonomy (runaway name / mis-closed param / misspelled opener).
• No OpenCode plugin exists for this. Do not go looking again.

5. Repository layout (/code/opencode-dsml-plugin)

docs/PATTERNS.md      variant catalogue + reject arms + two-consumer model (source of truth)
docs/TEST-MATRIX.md   each behaviour ↔ test id
docs/STATUS.md        this file (handoff — read first after compaction)
src/grammar.ts        all regexes, each linked to a V# in PATTERNS.md
src/parse.ts          parseDsml(text)->{calls,ranges}, stripRanges, orphan rescue
src/middleware.ts     createDsmlStreamMiddleware() AI-SDK LanguageModelV3Middleware
src/index.ts          (TODO) Plugin.define: aisdk.language hook + fallback
src/fallback.ts       (TODO) Strategy A: event subscribe + synthetic resume + storage cap
src/prompt.ts         (TODO) correction directive text (see §8)
test/fixtures.ts      runtime fixture builders (never store a live DSML token)
test/parse.test.ts    28 parser tests — ALL PASS
test/stream.test.ts   11 streaming tests — ALL PASS
test/wrapper.test.ts  generate + wrapper delegation — ALL PASS
test/config.test.ts   config matrix, strict parsing, prompt guards, fallback, system nudge — ALL PASS

Total: 89 tests, 0 fail. tsc --noEmit clean.

Golden verification against real captured failures (9 wrapped edit/shell leaks from a long-context DeepSeek session, preserved as synthetic byte-faithful fixtures in test/golden/): all 9 failing messages now recover the intended call — 5× edit (newString+oldString+path), 4× shell (command) — with the finish flipping to tool-calls and no text lost. The dominant shape is V26 (wrapped tool); the fix for the earlier 0-for-9 miss was two parser bugs found by the golden test itself: orphan ranges shadowing the wrapped rescue (insideBlock now checks block ranges only), and the markerless outer opener needing candidate-hold in the stream.

6. Current test state

bun test → 39/39 pass (test/parse.test.ts 28/28, test/stream.test.ts 11/11). ./node_modules/.bin/tsc --noEmit → clean.

Fixed during this session: the streaming drain was flushing partial openers (<, <BAR, <BAR BAR DS) as text instead of holding them — fixed with partialOpenerSuffix hold-back (V17). Streaming emitResolved no longer strips when zero calls were recovered — unclosed/unparseable tails emit verbatim.

7. Design decisions (locked)

• Parser is a strict acceptor: on doubt, strip noise or leave text; never execute a guessed tool. v13-undeclared-tool is intentionally kept (runtime answers "tool not found", a better feedback loop).
• v10 orphan parameter → strip only, no call (no tool name). Do not emit unknown.
• v11 mis-closed param → drop the runaway argument, keep the neighbour (vLLM rule).
• v12 runaway invoke name (name="tool {) → no call, strip.
• Code fences are never parsed or stripped.
• Message that already has native tool calls → strip leaked text only, do not re-run.
• Strategy A test-only for now: on idle, if last assistant text ends in DSML, send a synthetic correction nudge, capped via ctx.storage.

8. The correction prompt (user's latest requirement)

When the parser cannot recover a call, and as preventive guidance, inject a directive telling the model to always emit tool calls in the correct format with the outer XML layer. Text to be finalised in src/prompt.ts, shape:

• Preventive: added via ctx.session.hook("context") or a system instruction, telling the model the exact expected envelope (canonical single-bar, complete outer block, one <invoke> per call, <parameter> with string="true" for raw strings).
• Recovery-failure nudge: on a stream where DSML appeared but no call was recovered, or on session idle with leaked markup, send a short synthetic message: "Your last tool call was malformed (missing the outer block). Re-issue it using the correct format, wrapped in the outer <DSML tool_calls> layer, exactly once."

Exact wording + whether preventive injection is always-on or only for the DEESEEK providers is not yet decided — ask the user.

9. Exact next steps

1. Fix the 2 streaming tests — done, 69/69 green.
2. Write src/index.ts, src/prompt.ts, src/fallback.ts — done.
3. System-channel nudge + full strategy config matrix — done (see §11).
4. Live-wire verification: restart the OpenCode service so the plugin entry in the global opencode.jsonc loads, then run a DeepSeek session and confirm [dsml] debug lines + recovery behaviour.
5. Update docs/PATTERNS.md/TEST-MATRIX.md as rows move from FAIL to PASS.

11. Strategy report (final)

Per-request (in context hook, before the model call):

• Preventive directive (strategies.directive, default on): appends a fixed ~130-token instruction to event.system stating the exact required envelope (complete outer block layer, single bars, one invoke per call, parameters inside invokes). Static bytes every request → one-time prefix shift, then cache-stable.
• History sanitization (strategies.sanitize, default on): strips leaked DSML spans from replayed assistant text. Fires only when a leak exists; deterministic given stored messages, so retries converge to identical bytes (cache-friendly). Never synthesizes calls (no double-execution).
• Conditional system nudge (strategies.systemNudge, default on): when the assembled history ends in unrecoverable DSML, pushes the correction as a transient system instruction — never persisted, auto-clears when the condition clears. Capped per message (id, else content hash) via storage.

Per-response (in aisdk.language wrapper, after the provider stream):

• B1 streaming (strategies.stream): buffers text-delta only, holds partial openers, resolves closed blocks immediately, emits tool-input-* + tool-call, flips finish to tool-calls. Zero calls → buffer emitted verbatim, finish untouched. 64 KiB cap → over-cap unclosed tail emitted as text. Zero request impact → zero cache impact.
• B2 generate (strategies.generate): same recovery for non-streaming results.

Idle safety net (strategies.watchdog + resume.channel/maxAttempts):

• On session idle with unrecovered DSML last message: channel:"system" (default) sends a minimal synthetic wake ping ("Resume the interrupted tool call.") and the context hook attaches the full correction in system on the woken turn; channel:"user" restores the legacy full-text synthetic turn.
• Attempts capped per message; counters in plugin storage.

Fixed prompt texts live in src/prompt.ts (preventiveDirective(), recoveryNudge()); tests assert they contain no live marker bytes.

Caching verdict: only stable, deterministic bytes are ever added; nothing in the plugin churns per-request content. The one real invalidation is the one-time shift when the directive/nudge first appears — expected and unavoidable for any fix, and documented as acceptable.

Rejected alternative: session.instructions.entry.put as the nudge channel. It renders into the system baseline (ideal placement), but the Promise plugin runtime allowlists session methods and instructions is not exposed (type and runtime). Revisit only if OpenCode exposes it to plugins.

10. Environment

• Bun 1.4.2. bun test, ./node_modules/.bin/tsc --noEmit (tsgo unavailable here).
• Deps installed: @ai-sdk/provider@3.0.18, @opencode/plugin@2.0.22, typescript.
• Never write a literal DSML token into a source/doc file — the client/provider may parse it as a phantom tool call. Always build it via test/fixtures.ts or use the ‹DSML› placeholder.