What this plugin gives your agent

The official DeepSeek Harness ctx.lsp seam covers navigation (go-to-definition, references, implementation, hover). dsh-lsp-actions completes the action surface — the feedback loop an agent needs while it writes and fixes code:

✨ A real typescript-language-server run is part of the test suite: diagnostics, formatting, completion, symbol search, and rename are verified end-to-end against a live server, not just mocks. The suite is self-contained (tsls is a devDependency) and runs in CI on Node 22/24 across Linux, Windows, and macOS.

Quick start

dsh plugin --profile <name> add dsh-lsp-actions

Remove it with:

dsh plugin --profile <name> remove dsh-lsp-actions

Configure one entry per language server (the shape mirrors the official lsp-stdio config):

# in your profile's cordis.patch.yml (or the bundle row)
- insert:
    - id: lsp-actions
      name: dsh-lsp-actions
      inject: [tools, fs, subprocess]
      config:
        servers:
          ts:
            command: typescript-language-server
            args: [--stdio]
            extensionToLanguage:
              ".ts": typescript
            formattingOptions: { tabSize: 2, insertSpaces: true }
          py:
            command: pyright-langserver
            args: [--stdio]
            extensionToLanguage:
              ".py": python
        # The IDE integration backend — leave disabled in Web/CLI profiles;
        # enable only in a dedicated headless backend composition (stdout is the wire):
        editor:
          enabled: false
          requestTimeoutMs: 60000
          diagnosticsCacheMaxFiles: 64
        maxDiagnostics: 200
        maxCompletionItems: 20
        maxCodeActions: 50
        maxSymbols: 100
        maxSignatures: 10
        maxInlayHints: 200
        maxResultChars: 16000
        timeoutMs: 60000

The eight tools are always registered. With an empty servers table and no ctx.lsp seam mounted, calls fail loudly with LSP_ACTION_UNAVAILABLE telling the user what to configure — the plugin never starts servers you did not configure. A ctx.lsp seam mounted after this plugin is picked up on the next call (seam detection is per-call, so load order does not matter).

IDE integration backend: the editor action protocol v1

The plugin is also DSH's IDE integration backend. When editor.enabled: true is set in a dedicated headless composition, it serves a stable editor protocol over newline-delimited JSON-RPC 2.0 (the same wire framing as the official SDK/ACP transports):

All write actions (quickfix.apply, format) go through the official permission presets and approval: a read-only session is refused with LSP_ACTION_READ_ONLY before any server round-trip, edits ride the fs/write-intent waterfall, and the sandbox_permissions + justification escalation pair resolves through the official approveEscalation ask (fail-closed when no answerer can decide). Full wire spec, bilingual: docs/editor-protocol.md · docs/editor-protocol.zh-CN.md.

Versioning and the backward-compatibility promise

• The protocol is versioned — lsp.actions.list returns protocol: "lsp-actions/v1", version: 1. v1 is frozen: field names, action ids, event kinds, and error codes stay stable forever.
• Evolution is additive only: new actions, new fields, and new event kinds arrive without a version bump; existing semantics never change in place; a breaking change ships under a new protocol version, which servers may serve side by side.
• Clients must ignore unknown fields, unknown event kinds, and unknown actions, and route on the stable error code, never on message text.

Minimal VS Code extension

examples/vscode/ ships a UI-only extension (sidebar with the DSH sessions, the diagnostics list, one-click quickfix apply, open-at-range, and format) plus the headless backend composition (backend/cordis.yml) it connects to over ACP-style JSON-RPC. The extension implements zero LSP logic — every capability and every byte written belongs to the plugin. Install steps, settings, and the demo-gif recording script are in examples/vscode/README.md.

Why it is safe by construction

• Formatting and rename are real mutations, treated like write/edit. Every byte goes through the fs/write-intent waterfall (observation → guarded write → observation) and the per-call sandbox policy. lsp_rename pre-flights every edited file (workspace containment, overlap check, byte-capped read) before the first write, so a bad server response cannot leave a half-applied rename.
• Everything else is read-only by design. Code actions, completions, symbols, signatures, and hints are reported as reference material; applying them is the model's own write/edit decision. Command forms are reported and never executed.
• Read-only sessions fail loud, fast, and structured — LSP_ACTION_READ_ONLY with the shared [sandbox: …] marker, raised before any server round-trip.
• Escalation matches the official tools. Under a confining filesystem, lsp_format and lsp_rename advertise the same sandbox_permissions / justification one-shot retry as write/edit, resolved through ctx.approval.
• Conflicts never clobber. If the file changed on disk after it was read, the guarded write fails with LSP_ACTION_CONFLICT and the model is told to choose: re-read and re-run, or apply the diff manually.
• Timeouts are the platform's. Each tool declares timeoutMs; the official dsh-tool-call-timeout-policy enforces it, and every await honors exec.signal.
• Nothing is cached on the model path. Tool results live only in the session log; there is no cross-session persistence. The editor protocol keeps exactly one bounded cache — the LRU diagnostics snapshot cache (config editor.diagnosticsCacheMaxFiles), freshness-stamped and invalidated by filesystem observations and the plugin's own writes; it never persists across restarts.
• Prompt hygiene. The plugin injects no persona or prompt prose into the session system prompt — its model-facing surface is the eight tool schemas. Should any future prompt segment be added, it must open with one short role sentence and stay brief (aligned with the official Minimal persona style: You are a helpful software engineer assistant.).
• Bad servers fail loudly. A missing executable fails at load; a server that dies at startup fails the call with LSP_ACTION_SERVER_FAILED plus its stderr tail (after one fresh-spawn retry).

Architecture

Actions run official-seam-first and fall back to the plugin's own minimal stdio client:

lsp_diagnostics / lsp_format / lsp_completion / lsp_code_action /
lsp_symbols / lsp_signature / lsp_inlay_hints / lsp_rename
        │
        ▼
   ctx.lsp seam (extended: diagnostics / formatDocument / completion)
        │  absent · legacy · no provider for this file
        ▼
   built-in stdio client  ←  servers table (ctx.subprocess.spawn + JSON-RPC)

The seam extension is proposed upstream (upstream/lsp-action-seam.patch, PR description in upstream/PR-description.md). Once it lands, the plugin keeps working unchanged — the built-in client simply stops being used. The built-in client stays as the standalone fallback for the servers table. Full research and design notes: docs/seam-extension-notes.md.

The editor protocol rides the same runner, the same write path, and the same permission machinery:

                 ┌────────────────────────────────────────────────────┐
                 │ one DSH runtime (headless editor backend)           │
 VS Code (UI) ───┤  editor action protocol — this plugin               │
                 │  lsp.actions.list / run / lsp.events                │
                 │  (editor.enabled: true; same seam-first runner)     │
                 ├────────────────────────────────────────────────────┤
 official ACP ───┤  @deepseek-ai/dsh-acp — agent chat sessions         │
 clients         │  session/new · prompt · session/request_permission  │
                 ├────────────────────────────────────────────────────┤
 Python SDK ─────┤  @deepseek-ai/dsh-sdk-jsonrpc-server               │
 (deepseek-      │  session/prompt · session.event notifications       │
  harness-sdk)   └────────────────────────────────────────────────────┘

• Official ACP server is the agent-conversation transport; its sessions' agents call the lsp_* tools, and an ACP client answers editor write escalations through session/request_permission (see docs/editor-protocol.md).
• Python SDK (pip install deepseek-harness-sdk) drives the same runtime over the official SDK wire; since the editor protocol shares that wire's framing, SDK-grade clients can call lsp.actions.* unchanged.

Configuration reference

interface Config {
  /** Named language servers; empty = the plugin's own client serves nothing. */
  servers?: Record<string, LspServerEntry>
  /** Editor action protocol (the IDE integration backend). */
  editor?: {
    /** Serve lsp.actions.* over JSON-RPC stdio. Default false — enable only in a
     *  dedicated headless backend composition whose stdout nothing else claims. */
    enabled?: boolean             // default false
    /** Per-run timeout budget in ms, enforced inside the plugin. */
    requestTimeoutMs?: number     // default 60000
    /** Bounded LRU diagnostics-cache size in files (least-recently-used eviction). */
    diagnosticsCacheMaxFiles?: number  // default 64
  }
  maxDiagnostics?: number        // default 200
  maxCompletionItems?: number    // default 20
  maxCodeActions?: number        // default 50
  maxSymbols?: number            // default 100
  maxSignatures?: number         // default 10
  maxInlayHints?: number         // default 200
  maxResultChars?: number        // default 16000 (complete rendered result cap)
  maxDocumentBytes?: number      // default 4000000
  timeoutMs?: number             // default 60000 (enforced by the official timeout policy)
}

interface LspServerEntry {
  command: string                        // executable, resolved on PATH at load
  extensionToLanguage: Record<string, string>  // ".ts" → "typescript"
  fileGlobs?: string[]                   // optional; glob matches beat the extension map
  args?: string[]                        // no shell
  env?: Record<string, string>
  initializationOptions?: unknown
  configuration?: unknown                // object form answers workspace/configuration per section
  formattingOptions?: unknown            // e.g. { tabSize: 2, insertSpaces: true }
  maxMessageBytes?: number               // default 16000000
  maxStderrBytes?: number                // default 1000000
  killGraceMs?: number                   // default 2000
  shutdownTimeoutMs?: number             // default 5000
  diagnosticsSettleMs?: number           // default 2000 (push-only diagnostics window)
  diagnosticsDebounceMs?: number         // default 250 (quiet period after the last pushed batch)
  idleTimeoutMs?: number                 // default 0 (0 = keep the server process alive)
}

Error codes

Every failure carries a stable code on the error result; models and callers route on the code, never on message text.

Host version support

The plugin declares its DeepSeek Harness packages as peer dependencies (@deepseek-ai/dsh-fs, dsh-llm, dsh-sandbox, dsh-subprocess, dsh-tools ≥ 0.1.0-rc.6), so one copy serves both the host and the plugin. Tested against 0.1.0-rc.6; last verified 2026-08-15.

Known limitations

• Transient documents. Every action opens the file, runs one request, and closes it again (matching the official stdio host). Project-based servers that require a resident open file for document-free requests (tsls refuses workspace/symbol without one) are served by passing file_path to lsp_symbols, which keeps the routing file open for that request. tsls also answers textDocument/signatureHelp with null under this lifecycle; other servers (gopls, pyright, rust-analyzer) serve it normally.
• Range formatting requires the server's range provider. Servers that only advertise whole-document formatting fail range requests with LSP_ACTION_UNSUPPORTED.
• Rename applies text edits only. Resource operations (create/delete/rename files) in a server's rename answer are refused with LSP_ACTION_UNSUPPORTED, and edits outside the workspace fail as LSP_ACTION_CONFLICT before anything is written. On utf-8/utf-32 servers, cross-file rename positions are decoded by reading each edited file; an unreadable edited file fails the call as a conflict instead of mis-decoding positions.

Development

pnpm install
pnpm run lint        # oxlint over src/ and tests/
pnpm test            # 290+ tests: unit + fixture-server integration + editor-protocol e2e + real tsls e2e
pnpm run test:coverage   # gates: lines/statements/functions ≥ 90%, branches ≥ 85%
pnpm build           # emits lib/

The editor protocol has dedicated coverage: tests/editor-cache.spec.ts (bounded LRU), tests/editor-protocol.spec.ts (service semantics, permission gating, timeouts, and the full diagnostics → quickfix → format chain over JSON-RPC frames against the fixture LSP server). The examples/vscode/ backend and extension are standalone npm projects — see examples/vscode/README.md.

Releasing

CI runs the lint/build/test matrix plus the coverage gate on every push and pull request. Pushing a v* tag triggers the publish workflow, which verifies the suite and publishes the package to npm — it needs an NPM_TOKEN Actions secret (a publish-scoped npm access token) set once on the repository. The version is bumped manually in package.json/CHANGELOG.md before tagging.

Contributors

Thanks to everyone who has contributed to this project:

• PerryLink — the plugin itself: the LSP action client and server lifecycle, all eight tools, tests, CI, and documentation.

PerryLink DSH Plugin Family

This project is one of the 15 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:

License

Apache License 2.0