dsh-lsp-actions 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to dsh-lsp-actions are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## 0.2.0 — 2026-08-15
+
+### Added
+
+- **`lsp_rename` tool**: a server-verified symbol rename (`textDocument/prepareRename` +
+  `textDocument/rename`) applied workspace-wide through the filesystem write-intent waterfall and
+  the per-call sandbox policy, exactly like `lsp_format`. Edits are pre-flighted before the first
+  write (workspace containment, overlap check, byte-capped read), no-op files are dropped, and the
+  result renders per-file diff cards. Cross-document positions from `utf-8`/`utf-32` servers are
+  decoded per document by reading each edited file; unreadable targets fail as a structured
+  conflict instead of mis-decoding positions. File resource operations in a rename answer are
+  refused as unsupported. New `LSP_ACTION_NO_SYMBOL` error code for a bare cursor.
+- **Four new read-only tools**: `lsp_code_action` (server-verified quickfixes, reported never
+  applied), `lsp_symbols` (workspace-wide name search and per-file symbol outline),
+  `lsp_signature` (signature help at a cursor), and `lsp_inlay_hints` (type/parameter hints).
+- **Operation-specific seam extras**: the seam query forwards `query` (workspace symbol search),
+  `onlyKinds` (code-action filters), and `newName` (rename), so a future seam vintage can serve
+  the extended operations directly.
+- **Structured JSON-RPC errors**: `LspRpcError` carries the server's wire error code, so advisory
+  round-trips (prepareRename) can distinguish error responses from transport failures.
+- **Position encoding negotiation** for `utf-8` and `utf-32` servers: request positions are
+  encoded and server results are decoded through a per-document codec, so non-utf-16 servers no
+  longer fail the handshake.
+- **`workspace/symbol` with an open routing file**: when `lsp_symbols` receives `file_path` with a
+  query, the file stays transiently open for the request, so project-based servers (tsls) that
+  refuse document-free symbol search work.
+- **One fresh-spawn retry** when a server dies during its handshake, matching the official stdio
+  host's single bad-transport retry; mid-action failures never retry.
+- **Idle server eviction** (`idleTimeoutMs` per server entry, default 0 = keep alive).
+- **Push-diagnostic debounce** (`diagnosticsDebounceMs` per server entry, default 250 ms): the
+  latest pushed batch wins inside the settle window instead of the first.
+- **Per-section `workspace/configuration` answers**: a plain-object `configuration` answers each
+  requested section, falling back to the whole value.
+- **CI** (GitHub Actions: Node 22/24 × ubuntu/windows/macos lint+build+test matrix with a separate
+  coverage-gate job) and **coverage gates** (lines/statements/functions ≥ 90%, branches ≥ 85%),
+  plus a tag-triggered **publish workflow** for npm releases.
+- **Real-server e2e for rename and workspace symbols** through typescript-language-server (the
+  suite is self-contained via the `typescript-language-server` devDependency).
+
+### Changed
+
+- **The action surface is eight tools**: the write-path safety contract (`write-intent`, sandbox
+  policy, conflict handling) now covers `lsp_rename` alongside `lsp_format`; the shared sandbox
+  escalation schema names the action (`formatting` / `rename`) in its advertised descriptions.
+- **Tools are always registered.** With an empty `servers` table and no `ctx.lsp` seam, calls fail
+  loudly with `LSP_ACTION_UNAVAILABLE` instead of the plugin contributing nothing.
+- **Seam detection is lazy per call**: a `ctx.lsp` seam mounted after this plugin (or re-added
+  mid-session) is served without a reload.
+- **Completion results now render the insertion text** (`textEdit.newText` / `insertText`) on an
+  indented arrow line, because the model only sees rendered content.
+- **Glob routes prefer the file's own extension mapping** for the language id, falling back to the
+  entry's first mapping only when the extension is not mapped.
+- **Diagnostics, format, and inlay results carry columns** (and the format summary names the line
+  span), improving UI precision and model readback.
+- **The harness packages are peer dependencies** (`>=0.1.0-rc.6`), so a host harness shares one
+  copy and cross-version `instanceof` mismatches cannot silently break error mapping.
+
+### Fixed
+
+- **Server re-spelled file URIs no longer corrupt rename targets.** Servers re-spell the root URI
+  sent at initialize (lowercase drive letter and percent-encoded colon on Windows), and the
+  workspace-relative mapping sliced the raw URI at the raw root's length — mis-cutting every such
+  URI into a garbage path. Containment is now judged on decoded, case-insensitive forms while the
+  relative path is sliced from the decoded URI.
+- Diagnostics on servers whose `textDocumentSync` excludes transient open now fail with
+  `LSP_ACTION_UNSUPPORTED` (previously unchecked for diagnostics).
+- A caller abort racing a seam failure now surfaces the signal's reason instead of the seam's
+  unrelated error.
+- The e2e suite no longer depends on a sibling harness checkout's node_modules.
+
+## 0.1.0 — 2026-08-14
+
+- Initial release: `lsp_diagnostics`, `lsp_format`, and `lsp_completion` tools over the extended
+  `ctx.lsp` seam proposal and the built-in stdio client.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.es.md

@@ -0,0 +1,177 @@
+<div align="center">
+
+# 🛰️ dsh-lsp-actions
+
+**La superficie de acción LSP para DeepSeek Harness — servidores de lenguaje reales, retroalimentación real.**
+
+Diagnósticos, formateo, completado de código, correcciones rápidas, símbolos, ayuda de firmas y sugerencias insertadas para el bucle del editor de tu agente, impulsados por los mismos servidores de lenguaje que usa tu IDE.
+
+[![Topic: dsh](https://img.shields.io/badge/Topic-dsh-4D6BFE?style=for-the-badge)](https://github.com/topics/dsh)
+[![Topic: dsh-plugin](https://img.shields.io/badge/Topic-dsh--plugin-8257D0?style=for-the-badge)](https://github.com/topics/dsh-plugin)
+[![License](https://img.shields.io/badge/License-Apache%202.0-D22128?style=flat-square)](LICENSE)
+[![Node](https://img.shields.io/badge/Node-%5E22.19%20%7C%7C%20%3E%3D24-43853D?style=flat-square)](package.json)
+
+[English](README.md) · [简体中文](README.zh-CN.md) · [Español](README.es.md) · [हिन्दी](README.hi.md) · [Português](README.pt.md)
+
+</div>
+
+---
+
+## Qué aporta este plugin a tu agente
+
+El seam oficial `ctx.lsp` de DeepSeek Harness cubre la **navegación** (ir a definición, referencias, implementación, hover). `dsh-lsp-actions` completa la **superficie de acción**: el bucle de retroalimentación que un agente necesita mientras escribe y corrige código:
+
+| Herramienta | Qué hace | ¿Escribe? |
+| --- | --- | --- |
+| `lsp_diagnostics <file>` | Errores, advertencias y sugerencias del compilador/analizador con severidad, rango, mensaje y servidor de origen | ❌ solo lectura |
+| `lsp_format <file> [range?]` | Formatea un archivo o selección mediante el servidor de lenguaje y aplica el resultado, devolviendo el diff | ✅ vía `fs/write-intent` + política sandbox |
+| `lsp_completion <file> <line> <character>` | Sugerencias de completado en una posición del cursor, incluido el texto de inserción real | ❌ solo lectura |
+| `lsp_code_action <file> [range?] [only?]` | Correcciones/refactorizaciones verificadas por el servidor (con sus ediciones) para un rango o el primer diagnóstico | ❌ solo referencia |
+| `lsp_symbols <query?> <file_path?>` | Búsqueda de símbolos por nombre en todo el workspace, o el esquema de símbolos de un archivo | ❌ solo lectura |
+| `lsp_signature <file> <line> <character>` | Ayuda de firmas (parámetros y documentación) dentro de una llamada | ❌ solo lectura |
+| `lsp_inlay_hints <file> [range?]` | Anotaciones de tipo y sugerencias de nombres de parámetros del servidor | ❌ solo lectura |
+| `lsp_rename <file> <line> <character> <new_name>` | Renombrado de símbolo verificado por el servidor, aplicado en todo el workspace con diffs por archivo | ✅ vía `fs/write-intent` + política sandbox |
+
+> ✨ Una ejecución real de `typescript-language-server` forma parte de la suite de tests: diagnósticos, formateo, completado, búsqueda de símbolos y renombrado se verifican de extremo a extremo contra un servidor vivo, no solo con mocks. La suite es autocontenida (tsls es una devDependency) y corre en CI con Node 22/24 en Linux, Windows y macOS.
+
+## Inicio rápido
+
+```sh
+dsh plugin --profile <name> add <ruta-o-tarball-de-dsh-lsp-actions>
+```
+
+Configura una entrada por servidor de lenguaje (la forma replica la configuración oficial de `lsp-stdio`):
+
+```yaml
+# en el cordis.patch.yml de tu perfil (o en la fila del bundle)
+- 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
+        maxDiagnostics: 200
+        maxCompletionItems: 20
+        maxCodeActions: 50
+        maxSymbols: 100
+        maxSignatures: 10
+        maxInlayHints: 200
+        maxResultChars: 16000
+        timeoutMs: 60000
+```
+
+Las ocho herramientas se registran siempre. Con una **tabla `servers` vacía y ningún seam `ctx.lsp` montado, las llamadas fallan en voz alta** con `LSP_ACTION_UNAVAILABLE` indicando qué configurar — el plugin nunca arranca servidores que no configuraste. Un seam `ctx.lsp` montado **después** de este plugin se detecta en la siguiente llamada (la detección del seam es por llamada, así que el orden de carga no importa).
+
+## Por qué es seguro por construcción
+
+- **El formateo y el renombrado son mutaciones reales, tratadas como `write`/`edit`.** Cada byte pasa por el waterfall `fs/write-intent` (observación → escritura protegida → observación) y por la política sandbox de cada llamada. `lsp_rename` pre-vuela cada archivo editado (contención en el workspace, comprobación de solapamientos, lectura con tope de bytes) *antes* de la primera escritura, de modo que una respuesta mala del servidor no puede dejar un renombrado a medio aplicar.
+- **Todo lo demás es de solo lectura por diseño.** Las acciones de código, completados, símbolos, firmas y sugerencias se reportan como material de referencia; aplicarlas es decisión propia del modelo con write/edit. Las formas de comando se reportan y **nunca se ejecutan**.
+- **Las sesiones de solo lectura fallan en voz alta, rápido y estructurado** — `LSP_ACTION_READ_ONLY` con el marcador compartido `[sandbox: …]`, lanzado *antes* de cualquier ida y vuelta con el servidor.
+- **La escalada coincide con las herramientas oficiales.** Bajo un sistema de archivos restrictivo, `lsp_format` y `lsp_rename` anuncian el mismo reintento único `sandbox_permissions` / `justification` que `write`/`edit`, resuelto mediante `ctx.approval`.
+- **Los conflictos nunca pisan nada.** Si el archivo cambió en disco después de leerse, la escritura protegida falla con `LSP_ACTION_CONFLICT` y se le dice al modelo que elija: releer y repetir, o aplicar el diff manualmente.
+- **Los timeouts son de la plataforma.** Cada herramienta declara `timeoutMs`; la política oficial `dsh-tool-call-timeout-policy` lo hace cumplir, y cada await respeta `exec.signal`.
+- **No se cachea nada.** Los resultados viven solo en el log de sesión; no hay persistencia entre sesiones.
+- **Los servidores rotos fallan en voz alta.** Un ejecutable inexistente falla al cargar; un servidor que muere al arrancar falla la llamada con `LSP_ACTION_SERVER_FAILED` más la cola de su stderr (tras un reintento con proceso nuevo).
+
+## Arquitectura
+
+Las acciones van **primero por el seam oficial** y caen al cliente stdio mínimo propio del plugin:
+
+```
+lsp_diagnostics / lsp_format / lsp_completion / lsp_code_action /
+lsp_symbols / lsp_signature / lsp_inlay_hints / lsp_rename
+        │
+        ▼
+   ctx.lsp seam (extendido: diagnostics / formatDocument / completion)
+        │  ausente · legado · sin provider para este archivo
+        ▼
+   cliente stdio integrado  ←  tabla servers (ctx.subprocess.spawn + JSON-RPC)
+```
+
+La extensión del seam está propuesta upstream (`upstream/lsp-action-seam.patch`, descripción del PR en `upstream/PR-description.md`). Cuando aterrice, el plugin sigue funcionando sin cambios — el cliente integrado simplemente deja de usarse. El cliente integrado se conserva como respaldo independiente para la tabla `servers`. Notas completas de investigación y diseño: [`docs/seam-extension-notes.md`](docs/seam-extension-notes.md), [`upstream/README.md`](upstream/README.md).
+
+## Referencia de configuración
+
+```ts
+interface Config {
+  /** Servidores de lenguaje nombrados; vacío = el cliente propio no sirve nada. */
+  servers?: Record<string, LspServerEntry>
+  maxDiagnostics?: number        // por defecto 200
+  maxCompletionItems?: number    // por defecto 20
+  maxCodeActions?: number        // por defecto 50
+  maxSymbols?: number            // por defecto 100
+  maxSignatures?: number         // por defecto 10
+  maxInlayHints?: number         // por defecto 200
+  maxResultChars?: number        // por defecto 16000 (tope del resultado renderizado completo)
+  maxDocumentBytes?: number      // por defecto 4000000
+  timeoutMs?: number             // por defecto 60000 (aplicado por la política oficial de timeout)
+}
+
+interface LspServerEntry {
+  command: string                        // ejecutable, resuelto en PATH al cargar
+  extensionToLanguage: Record<string, string>  // ".ts" → "typescript"
+  fileGlobs?: string[]                   // opcional; los globs ganan al mapa de extensiones
+  args?: string[]                        // sin shell
+  env?: Record<string, string>
+  initializationOptions?: unknown
+  configuration?: unknown                // forma de objeto responde workspace/configuration por sección
+  formattingOptions?: unknown            // p. ej. { tabSize: 2, insertSpaces: true }
+  maxMessageBytes?: number               // por defecto 16000000
+  maxStderrBytes?: number                // por defecto 1000000
+  killGraceMs?: number                   // por defecto 2000
+  shutdownTimeoutMs?: number             // por defecto 5000
+  diagnosticsSettleMs?: number           // por defecto 2000 (ventana de diagnósticos solo push)
+  diagnosticsDebounceMs?: number         // por defecto 250 (período de calma tras el último lote empujado)
+  idleTimeoutMs?: number                 // por defecto 0 (0 = mantener vivo el proceso del servidor)
+}
+```
+
+### Códigos de error
+
+Cada fallo lleva un `code` estable en el resultado de error; los modelos y llamadores enrutan por el código, nunca por el texto del mensaje.
+
+| Code | Significado |
+| --- | --- |
+| `LSP_ACTION_UNAVAILABLE` | Ninguna entrada de servidor ni provider del seam maneja este archivo. |
+| `LSP_ACTION_UNSUPPORTED` | El servidor (o el provider del seam) no anuncia la operación. |
+| `LSP_ACTION_SERVER_FAILED` | El servidor falló (con la cola de su stderr); los fallos de arranque reintentan una vez. |
+| `LSP_ACTION_MALFORMED_RESPONSE` | El servidor envió una carga estructuralmente inválida. |
+| `LSP_ACTION_CONFLICT` | El archivo cambió desde que se leyó, o las ediciones del servidor se solapan / salen de límites / salen del workspace. |
+| `LSP_ACTION_READ_ONLY` | El modo sandbox de la sesión prohíbe la escritura del formateo/renombrado. |
+| `LSP_ACTION_WORKSPACE_REQUIRED` | La sesión que llama no tiene un cwd de workspace donde enraizar el servidor. |
+| `LSP_ACTION_NO_SYMBOL` | El servidor no encontró un símbolo renombrable en la posición del cursor. |
+
+### Versión de host soportada
+
+El plugin declara los paquetes de DeepSeek Harness como **peer dependencies** (`@deepseek-ai/dsh-fs`, `dsh-llm`, `dsh-sandbox`, `dsh-subprocess`, `dsh-tools` ≥ `0.1.0-rc.6`), de modo que una sola copia sirve al host y al plugin. Probado contra `0.1.0-rc.6`.
+
+### Limitaciones conocidas
+
+- **Documentos transitorios.** Cada acción abre el archivo, ejecuta una petición y lo cierra de nuevo (igual que el host stdio oficial). Los servidores basados en proyecto que exigen un archivo abierto residente para peticiones sin documento (tsls rechaza `workspace/symbol` sin uno) se sirven pasando `file_path` a `lsp_symbols`, que mantiene el archivo de enrutamiento abierto durante esa petición. tsls también responde `textDocument/signatureHelp` con `null` bajo este ciclo de vida; otros servidores (gopls, pyright, rust-analyzer) lo sirven con normalidad.
+- **El formateo de rango exige el provider de rango del servidor.** Los servidores que solo anuncian formateo de documento completo fallan las peticiones de rango con `LSP_ACTION_UNSUPPORTED`.
+- **El renombrado solo aplica ediciones de texto.** Las operaciones de recursos (crear/borrar/renombrar archivos) en la respuesta de renombrado del servidor se rechazan con `LSP_ACTION_UNSUPPORTED`, y las ediciones fuera del workspace fallan con `LSP_ACTION_CONFLICT` antes de escribir nada. En servidores `utf-8`/`utf-32`, las posiciones de renombrado entre archivos se decodifican leyendo cada archivo editado; un archivo editado ilegible falla la llamada como conflicto en lugar de decodificar mal las posiciones.
+
+## Desarrollo
+
+```sh
+pnpm install
+pnpm run lint        # oxlint sobre src/ y tests/
+pnpm test            # más de 240 tests: unidad + integración con servidor fixture + e2e real con tsls
+pnpm run test:coverage   # puertas: líneas/sentencias/funciones ≥ 90%, ramas ≥ 85%
+pnpm build           # emite lib/
+```
+
+## License
+
+[Apache License 2.0](LICENSE)