@deepseek-ai/dsh-tool-lsp 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/lsp/tool-lsp/README.md
+README.md: 36fa3026cba3fc692ae5a86c7307acf77563cf53
+README.zh.md: 1b0b1f4847cf711e7939b79ac2f8035f26cb73aa

package/README.md

@@ -0,0 +1,90 @@
+# @deepseek-ai/dsh-tool-lsp
+
+English | [中文](README.zh.md)
+
+The model-facing **`lsp` tool** over `ctx.lsp`: one read-only tool with four operations for precise code navigation. It owns the model schema, prompt guidance, coordinate conversion, result limits and formatting, and UI presentation; it imports no provider.
+
+Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export). Injects `tools`, `lsp`, and `systemPrompt`.
+
+## The tool
+
+`lsp` accepts `operation` (`goToDefinition` | `findReferences` | `goToImplementation` | `hover`), `file_path`, `line`, and `character`. `line` and `character` are positive, one-based UTF-16 cursor coordinates; the tool converts them to the seam's zero-based positions and converts rendered locations back. `findReferences` includes declarations so impact analysis does not omit the defining site. Provider, language id, workspace root, limits, timeout, initialization, and executable stay outside model input.
+
+The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Its canonical result is the complete normalized Service Definition union: `{ kind: "locations", locations, resolvedWorkspaceUri }` or `{ kind: "hover", hover }`; Code Mode can inspect every acquired location and zero-based range directly. Native rendering projects stable, file-grouped `path:line:character` entries against the provider's canonical workspace URI rather than applying host-platform path rules to the session cwd. A `file:` URI becomes a workspace-relative path inside that URI or a URI-derived absolute path outside it; malformed and non-`file:` URIs stay verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `maxLocations` | `100` | Largest number of rendered locations before an omission marker. |
+| `maxResultChars` | `16000` | Largest complete rendered result, including truncation metadata. |
+| `timeoutMs` | `60000` | Tool-call timeout budget, enforced by `dsh-timeout-policy`; covers the complete queued open/query/close lifecycle and is not model-configurable. |
+
+## Model Experience
+
+### System prompt
+
+#### What the model sees
+
+One system-prompt section (order 112) positions LSP as a precision aid with the following text:
+
+##### Verbatim guidance
+
+```markdown
+Use search/read for ordinary navigation. Use lsp when textual matches are ambiguous or before a change requires precise definitions, implementations, or references. Positions are one-based line and character (UTF-16) at the cursor; an off-symbol position may return no results. findReferences always includes the declaration.
+```
+
+#### Token effect
+
+Fixed guidance cost on every request while the plugin is active.
+
+#### KV Cache effect
+
+Prefix-stable while the plugin scope and guidance text are unchanged; activation or disposal may invalidate reuse from this section.
+
+### Tool schema
+
+#### What the model sees
+
+The model sees the generated [`lsp` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-lsp).
+
+#### Token effect
+
+Fixed schema cost on every request while enabled; the `timeoutMs` budget is never sent to the model.
+
+#### KV Cache effect
+
+Prefix-stable while the visible tool definition and order are unchanged; registration lifecycle or scoped restrictions may invalidate reuse from the first changed schema token.
+
+### Results
+
+#### What the model sees
+
+File-grouped `path:line:character` location lines or normalized hover text, capped first by `maxLocations` and then by `maxResultChars`; omission and truncation markers are included inside the complete character cap. These caps affect only Native/model presentation, not the canonical value. Empty results use distinct `No results.` / `No hover information.` lines.
+
+#### Token effect
+
+Capped per tool result by `maxResultChars`, with `maxLocations` additionally bounding navigation item count.
+
+#### KV Cache effect
+
+Tool results append after the cached request prefix and do not directly invalidate it.
+
+### UI presentation
+
+#### What the model sees
+
+Nothing. The client renders a generic search card — `{ card: 'generic', kind: 'search', title, locations: [{ path, line }] }` — whose args-derived title carries the operation and one-based cursor; follow-along focuses the queried line while the title preserves the column.
+
+#### Token effect
+
+Zero direct token effect because rendering is client-side only.
+
+#### KV Cache effect
+
+None; UI presentation is outside the model request.
+
+## Known Limitations and Deferred Work
+
+- **UTF-16 cursor coordinates** — columns are exact for the protocol but hard for a model to count around non-BMP characters; an off-symbol position may return empty results, so the prompt explains the convention without encouraging broad LSP use ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)).
+- **No cross-server completeness promise** — supported servers may return empty or partial results depending on indexing readiness; the tool promises no completeness across languages or servers.

package/README.zh.md

@@ -0,0 +1,90 @@
+# @deepseek-ai/dsh-tool-lsp
+
+[English](README.md) | 中文
+
+面向模型的 **`lsp` 工具**，基于 `ctx.lsp`：一个只读工具，通过四种操作执行精确代码导航。它拥有模型 schema、提示词指引、坐标转换、结果限制与格式化，以及 UI 呈现；不导入任何提供方。
+
+Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）。注入 `tools`、`lsp` 和 `systemPrompt`。
+
+## 工具
+
+`lsp` 接受 `operation`（`goToDefinition` | `findReferences` | `goToImplementation` | `hover`）、`file_path`、`line` 和 `character`。`line` 与 `character` 是正的、从 1 开始的 UTF-16 光标坐标；工具将其转换为 seam 从零开始的位置，并把渲染位置转换回来。`findReferences` 包含声明，因此影响分析不会遗漏定义位置。提供方、language id、Workspace 根、限制、超时、初始化和可执行文件均不进入模型输入。
+
+该工具要求从会话 `header.cwd` 取得 Workspace 根，没有回退值：缺失时会在查询前以 `LSP_WORKSPACE_REQUIRED` 失败。其规范结果是完整的已规范化 Service Definition 联合：`{ kind: "locations", locations, resolvedWorkspaceUri }` 或 `{ kind: "hover", hover }`；Code Mode 可以直接检查每个已取得的位置和从零开始的范围。原生渲染以提供方的规范工作区 URI 为基准，投影按文件稳定分组的 `path:line:character` 条目，而不对会话 cwd 应用宿主平台路径规则。`file:` URI 落在该工作区 URI 内时成为工作区相对路径，位于其外时成为从 URI 派生的绝对路径；格式错误的 URI 与非 `file:` URI 保持原样。空位置和 `null` hover 都是成功的无结果响应；格式错误的提供方载荷仍是结构化错误。
+
+## 配置
+
+| Key | 默认值 | 含义 |
+|---|---|---|
+| `maxLocations` | `100` | 出现省略标记前可渲染位置的最大数量。 |
+| `maxResultChars` | `16000` | 完整渲染结果的最大长度，包括截断元数据。 |
+| `timeoutMs` | `60000` | 由 `dsh-timeout-policy` 强制执行的工具调用超时预算；覆盖完整的排队打开／查询／关闭生命周期，且模型不可配置。 |
+
+## 模型体验
+
+### 系统提示词
+
+#### 模型看到的内容
+
+一个系统提示词区段（顺序 112）将 LSP 定位为精确辅助工具，文本如下：
+
+##### 逐字指引
+
+```markdown
+Use search/read for ordinary navigation. Use lsp when textual matches are ambiguous or before a change requires precise definitions, implementations, or references. Positions are one-based line and character (UTF-16) at the cursor; an off-symbol position may return no results. findReferences always includes the declaration.
+```
+
+#### Token 影响
+
+插件处于活跃状态时，每次请求承担固定指引成本。
+
+#### KV Cache 影响
+
+只要插件 scope 与指引文本不变，前缀就保持稳定；激活或释放可能使从该区段起的复用失效。
+
+### 工具 schema
+
+#### 模型看到的内容
+
+模型会看到生成的 [`lsp` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-lsp)。
+
+#### Token 影响
+
+启用期间，每次请求承担固定 schema 成本；`timeoutMs` 预算绝不会发给模型。
+
+#### KV Cache 影响
+
+只要可见工具定义与顺序不变，前缀就保持稳定；注册生命周期或 scope 限制可能使从第一个变化的 schema token 起的复用失效。
+
+### 结果
+
+#### 模型看到的内容
+
+按文件分组的 `path:line:character` 位置行或规范化 hover 文本，先由 `maxLocations` 限制，再由 `maxResultChars` 限制；省略与截断标记计入完整字符上限。这些上限只影响原生／模型呈现，不影响规范值。空结果使用不同的 `No results.`／`No hover information.` 行。
+
+#### Token 影响
+
+每项工具结果以 `maxResultChars` 为上限，`maxLocations` 还会限制导航项数量。
+
+#### KV Cache 影响
+
+工具结果追加在已缓存请求前缀之后，不会直接使其失效。
+
+### UI 呈现
+
+#### 模型看到的内容
+
+无。客户端渲染通用搜索卡片：`{ card: 'generic', kind: 'search', title, locations: [{ path, line }] }`；从 args 派生的标题携带操作与从 1 开始的光标，跟随焦点对准查询行，标题则保留列号。
+
+#### Token 影响
+
+直接 token 影响为零，因为渲染只发生在客户端。
+
+#### KV Cache 影响
+
+无；UI 呈现位于模型请求之外。
+
+## 已知限制与暂缓事项
+
+- **UTF-16 光标坐标**：列坐标与协议精确一致，但模型难以在非 BMP 字符周围计数；非 symbol 位置可能返回空结果，因此提示词解释了该约定，但不会鼓励宽泛使用 LSP（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。
+- **不承诺跨服务器完整性**：受支持的服务器仍可能根据索引就绪情况返回空或部分结果；该工具不承诺跨语言或服务器的完整性。

package/lib/index.js

@@ -0,0 +1,412 @@
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { assertNever } from "@deepseek-ai/dsh-llm";
+import { LspError } from "@deepseek-ai/dsh-lsp";
+import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
+import { posix, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region lib/types/render.js
+/**
+* Pure formatting and coordinate conversion for the `lsp` tool: one-based↔zero-based UTF-16 cursor
+* conversion, workspace-grouped location rendering with `file:`-URI resolution, complete-result
+* capping, and UI presentation. No I/O — a UI may call the presenter on live streaming and on
+* replay, so it depends only on the tool arguments.
+* @module @deepseek-ai/dsh-tool-lsp/render
+*/
+/** The four operations the tool exposes, as a runtime tuple for schema enum + validation. */
+const LSP_OPERATIONS = [
+	"goToDefinition",
+	"findReferences",
+	"goToImplementation",
+	"hover"
+];
+/** Default cap on rendered locations before an omission marker is appended. */
+const DEFAULT_MAX_LOCATIONS = 100;
+/** Default cap on the complete rendered tool result, including truncation metadata. */
+const DEFAULT_MAX_RESULT_CHARS = 16e3;
+/**
+* Validate and convert model arguments: `operation` must be one of the four; `line`/`character` are
+* positive one-based integers converted to the seam's zero-based position.
+* @param args - the schema-validated raw arguments.
+* @returns the validated input with a zero-based position.
+* @throws Error when the operation is unknown or a coordinate is not a positive integer.
+*/
+function parseLspArgs(args) {
+	if (!isOperation(args.operation)) throw new Error(`operation must be one of ${LSP_OPERATIONS.join(", ")}`);
+	if (args.file_path.trim().length === 0) throw new Error("file_path must be a non-empty string");
+	const line = oneBased(args.line, "line");
+	const character = oneBased(args.character, "character");
+	return {
+		operation: args.operation,
+		filePath: args.file_path,
+		position: {
+			line: line - 1,
+			character: character - 1
+		}
+	};
+}
+/** Whether a string is one of the four operations. */
+function isOperation(value) {
+	return LSP_OPERATIONS.includes(value);
+}
+/** Validate a one-based coordinate is a positive integer. */
+function oneBased(value, name) {
+	if (!Number.isInteger(value) || value < 1) throw new Error(`${name} must be a positive integer (one-based)`);
+	return value;
+}
+/**
+* Render a locations result grouped by file, converting each zero-based location back to a one-based
+* `path:line:character` entry. A `file:` URI inside the workspace becomes a workspace-relative path;
+* outside it, a URI-derived absolute path; a non-`file:` URI is kept verbatim. Applies `maxLocations` and
+* appends an omission marker when it truncates by count, then applies the complete result cap.
+* @param locations - the seam's locations (possibly empty).
+* @param workspaceUri - the provider's canonical workspace `file:` URI.
+* @param maxLocations - the cap before truncation.
+* @param maxResultChars - the complete rendered-text cap, including truncation metadata.
+* @returns the rendered text; a distinct no-result line when there are none.
+*/
+function formatLocations(locations, workspaceUri, maxLocations, maxResultChars) {
+	if (locations.length === 0) return boundResult("No results.", maxResultChars, "locations");
+	const shown = locations.slice(0, maxLocations);
+	const omitted = locations.length - shown.length;
+	const grouped = /* @__PURE__ */ new Map();
+	for (const location of shown) {
+		const path = renderUri(location.uri, workspaceUri);
+		const line = location.range.start.line + 1;
+		const character = location.range.start.character + 1;
+		const entries = grouped.get(path) ?? [];
+		entries.push(`${path}:${line}:${character}`);
+		grouped.set(path, entries);
+	}
+	const lines = [];
+	for (const entries of grouped.values()) lines.push(...entries);
+	if (omitted > 0) lines.push(`… ${omitted} more location${omitted === 1 ? "" : "s"} omitted (limit ${maxLocations}).`);
+	return boundResult(lines.join("\n"), maxResultChars, "locations");
+}
+/**
+* Render a hover result, applying `maxResultChars` last and keeping its marker within the cap.
+* @param hover - the normalized hover, or `null` for no hover.
+* @param maxResultChars - the complete rendered-text cap, including truncation metadata.
+* @returns the rendered hover text; a distinct no-result line for `null`.
+*/
+function formatHover(hover, maxResultChars) {
+	return boundResult(hover === null ? "No hover information." : hover.contents, maxResultChars, "hover");
+}
+/** Bound a complete rendered result, including the truncation notice itself. */
+function boundResult(text, maxChars, label) {
+	if (text.length <= maxChars) return text;
+	const notice = `\n… ${label} truncated (limit ${maxChars} characters).`;
+	if (notice.length >= maxChars) return notice.slice(0, maxChars);
+	return `${text.slice(0, maxChars - notice.length)}${notice}`;
+}
+/**
+* Resolve a location URI without applying the harness host's path rules. A valid `file:` URI becomes
+* workspace-relative when it is under the provider's canonical workspace URI, or a URI-derived
+* absolute path otherwise; malformed and non-`file:` URIs remain verbatim.
+* @param uri - the target URI from the seam.
+* @param workspaceUri - the provider's canonical workspace `file:` URI.
+* @returns the display path or the verbatim URI.
+*/
+function renderUri(uri, workspaceUri) {
+	if (!uri.startsWith("file:")) return uri;
+	let target;
+	let workspace;
+	try {
+		target = new URL(uri);
+		workspace = new URL(workspaceUri);
+	} catch {
+		return uri;
+	}
+	if (workspace.protocol !== "file:") return uri;
+	const drivePath = /^\/[a-z](?::|%3A)/iu;
+	const windowsWorld = workspace.hostname.length > 0 || drivePath.test(workspace.pathname);
+	const targetWindowsWorld = windowsWorld && (target.hostname.length > 0 || drivePath.test(target.pathname));
+	const workspacePath = filePath(workspace, windowsWorld);
+	const targetPath = filePath(target, targetWindowsWorld);
+	if (workspacePath === void 0 || targetPath === void 0) return uri;
+	if (windowsWorld !== targetWindowsWorld) return targetPath;
+	const path = windowsWorld ? win32 : posix;
+	const relative = path.relative(workspacePath, targetPath);
+	const outside = relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+	const rendered = relative === "" ? "." : outside ? targetPath : relative;
+	return windowsWorld ? rendered.replaceAll("\\", "/") : rendered;
+}
+/** Decode a file URL for its execution world while containing malformed URL failures. */
+function filePath(url, windows) {
+	try {
+		const path = fileURLToPath(url, { windows });
+		return path.includes("\0") ? void 0 : path;
+	} catch {
+		return;
+	}
+}
+/**
+* UI presentation for a pending `lsp` call. Uses a generic search card; the title carries the
+* operation and one-based cursor, and `locations` focuses the queried line. The shared location
+* shape has no character, so the title preserves the column.
+* @param args - the raw tool arguments.
+* @returns the generic call view.
+*/
+function presentLspCall(args) {
+	return {
+		card: "generic",
+		kind: "search",
+		title: `LSP ${args.operation} ${args.file_path}:${args.line}:${args.character}`,
+		locations: [{
+			path: args.file_path,
+			line: args.line
+		}]
+	};
+}
+//#endregion
+//#region lib/types/session-cwd.js
+/**
+* Derive the workspace root an `lsp` call resolves against: the calling agent's per-session
+* workspace (`exec.agent.session.header.cwd`), mirroring how the filesystem tools resolve paths.
+* Unlike those tools, LSP has NO provider fallback — a missing cwd fails the call as
+* `LSP_WORKSPACE_REQUIRED`, because the local provider must canonicalize a real workspace before it
+* can start a server.
+* @module @deepseek-ai/dsh-tool-lsp/session-cwd
+*/
+/**
+* The session workspace cwd for this call, or `undefined` when none applies.
+* @param exec - the tool-execution context; only its optional `agent` is read.
+* @returns the calling agent's session cwd, or undefined for a non-agent caller.
+*/
+function sessionCwd(exec) {
+	return exec.agent?.session.header.cwd;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Model-facing `lsp` tool over `ctx.lsp`. One read-only tool with four operations
+* (`goToDefinition`/`findReferences`/`goToImplementation`/`hover`); it converts one-based UTF-16
+* cursor coordinates to the seam's zero-based positions, requires the session workspace with no
+* fallback, caps and renders results, and attaches a configurable timeout budget for
+* `dsh-timeout-policy` to enforce. It runtime-injects only `tools`, `lsp`, and `systemPrompt` and
+* imports no provider.
+*
+* Namespace plugin (named exports, no default export).
+* @module @deepseek-ai/dsh-tool-lsp
+*/
+/** Cordis plugin name for loader diagnostics. */
+const name = "tool-lsp";
+/** Services required by this plugin. */
+const inject = [
+	"tools",
+	"lsp",
+	"systemPrompt"
+];
+/** Default tool-call timeout budget (ms), covering the queued open/query/close lifecycle. */
+const DEFAULT_LSP_TOOL_TIMEOUT_MS = 6e4;
+/** The stable system-prompt guidance positioning LSP as a precision aid. */
+const LSP_PROMPT_TEXT = "Use search/read for ordinary navigation. Use lsp when textual matches are ambiguous or before a change requires precise definitions, implementations, or references. Positions are one-based line and character (UTF-16) at the cursor; an off-symbol position may return no results. findReferences always includes the declaration.";
+const Config = z.object({
+	maxLocations: z.number().default(100),
+	maxResultChars: z.number().default(DEFAULT_MAX_RESULT_CHARS),
+	timeoutMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_LSP_TOOL_TIMEOUT_MS)
+});
+const LSP_POSITION_OUTPUT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		line: {
+			type: "integer",
+			required: true
+		},
+		character: {
+			type: "integer",
+			required: true
+		}
+	}
+};
+const LSP_RANGE_OUTPUT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		start: {
+			...LSP_POSITION_OUTPUT_SCHEMA,
+			required: true
+		},
+		end: {
+			...LSP_POSITION_OUTPUT_SCHEMA,
+			required: true
+		}
+	}
+};
+/**
+* Register the `lsp` tool and its system-prompt guidance.
+* @param ctx - the plugin context (must inject `tools`, `lsp`, `systemPrompt`).
+* @param config - the resolved plugin configuration.
+*/
+function apply(ctx, config) {
+	const resolved = config;
+	assertPositiveInteger("maxLocations", resolved.maxLocations);
+	assertPositiveInteger("maxResultChars", resolved.maxResultChars);
+	assertTimer("timeoutMs", resolved.timeoutMs);
+	ctx.systemPrompt.section({
+		name: "tool:lsp",
+		order: 112,
+		text: LSP_PROMPT_TEXT
+	});
+	ctx.tools.register(defineTool({
+		name: "lsp",
+		description: "Query a language server for precise code navigation. operation is one of goToDefinition, findReferences, goToImplementation, hover. line and character are one-based UTF-16 cursor coordinates. findReferences includes the declaration.",
+		parameters: {
+			operation: {
+				type: "string",
+				required: true,
+				enum: [...LSP_OPERATIONS],
+				description: "goToDefinition, findReferences, goToImplementation, or hover."
+			},
+			file_path: {
+				type: "string",
+				required: true,
+				description: "The source file to query, relative to the workspace or absolute."
+			},
+			line: {
+				type: "number",
+				required: true,
+				description: "One-based line of the cursor."
+			},
+			character: {
+				type: "number",
+				required: true,
+				description: "One-based UTF-16 column of the cursor."
+			}
+		},
+		output: {
+			schema: { oneOf: [{
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						required: true,
+						const: "locations"
+					},
+					locations: {
+						type: "array",
+						required: true,
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								uri: {
+									type: "string",
+									required: true
+								},
+								range: {
+									...LSP_RANGE_OUTPUT_SCHEMA,
+									required: true
+								}
+							}
+						}
+					},
+					resolvedWorkspaceUri: {
+						type: "string",
+						required: true
+					}
+				}
+			}, {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						required: true,
+						const: "hover"
+					},
+					hover: {
+						required: true,
+						oneOf: [{ type: "null" }, {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								contents: {
+									type: "string",
+									required: true
+								},
+								range: LSP_RANGE_OUTPUT_SCHEMA
+							}
+						}]
+					}
+				}
+			}] },
+			render: (_args, value) => {
+				switch (value.kind) {
+					case "locations": return [{
+						type: "text",
+						text: formatLocations(value.locations, value.resolvedWorkspaceUri, resolved.maxLocations, resolved.maxResultChars)
+					}];
+					case "hover": return [{
+						type: "text",
+						text: formatHover(value.hover, resolved.maxResultChars)
+					}];
+					/* v8 ignore next -- exhaustive over the output schema's closed union; unreachable. */
+					default: return assertNever(value, "tool-lsp output");
+				}
+			}
+		},
+		timeoutMs: resolved.timeoutMs,
+		async execute(args, exec) {
+			const input = parseLspArgs(args);
+			const workspaceRoot = sessionCwd(exec);
+			if (workspaceRoot === void 0) throw new LspError("the lsp tool requires a session workspace cwd", "LSP_WORKSPACE_REQUIRED");
+			const result = await ctx.lsp.query({
+				operation: input.operation,
+				filePath: input.filePath,
+				position: input.position,
+				workspaceRoot
+			}, exec.signal);
+			switch (result.kind) {
+				case "locations": return {
+					kind: "locations",
+					locations: result.locations.map((location) => ({
+						uri: location.uri,
+						range: {
+							start: {
+								line: location.range.start.line,
+								character: location.range.start.character
+							},
+							end: {
+								line: location.range.end.line,
+								character: location.range.end.character
+							}
+						}
+					})),
+					resolvedWorkspaceUri: result.resolvedWorkspaceUri
+				};
+				case "hover": return {
+					kind: "hover",
+					hover: result.hover === null ? null : {
+						contents: result.hover.contents,
+						...result.hover.range === void 0 ? {} : { range: {
+							start: {
+								line: result.hover.range.start.line,
+								character: result.hover.range.start.character
+							},
+							end: {
+								line: result.hover.range.end.line,
+								character: result.hover.range.end.character
+							}
+						} }
+					}
+				};
+				/* v8 ignore next -- exhaustive over the closed LspQueryResult union; unreachable. */
+				default: return assertNever(result, "tool-lsp result");
+			}
+		},
+		presentCall: presentLspCall
+	}));
+}
+/** Reject a non-positive-integer config value at load, so misconfiguration fails loud. */
+function assertPositiveInteger(name, value) {
+	if (!Number.isInteger(value) || value < 1) throw new Error(`tool-lsp: ${name} must be a positive integer`);
+}
+/** Reject a timer value Node would clamp instead of scheduling as configured. */
+function assertTimer(name, value) {
+	if (!Number.isInteger(value) || value < 1 || value > MAX_TIMER_DELAY_MS) throw new Error(`tool-lsp: ${name} must be a positive integer no greater than ${MAX_TIMER_DELAY_MS}`);
+}
+//#endregion
+export { Config, DEFAULT_LSP_TOOL_TIMEOUT_MS, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS, LSP_OPERATIONS, LSP_PROMPT_TEXT, apply, formatHover, formatLocations, inject, name, parseLspArgs, presentLspCall, renderUri, sessionCwd };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-tool-lsp`.
+* @module @deepseek-ai/dsh-tool-lsp/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-tool-lsp";
+/** Cordis companion plugin name. */
+const name = "tool-lsp-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this stateless adapter contributes one tool and prompt section, while query
+* lifecycle and result relations remain owned by the tool and LSP seams it composes.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Model-facing `lsp` tool over `ctx.lsp`. One read-only tool with four operations
+ * (`goToDefinition`/`findReferences`/`goToImplementation`/`hover`); it converts one-based UTF-16
+ * cursor coordinates to the seam's zero-based positions, requires the session workspace with no
+ * fallback, caps and renders results, and attaches a configurable timeout budget for
+ * `dsh-timeout-policy` to enforce. It runtime-injects only `tools`, `lsp`, and `systemPrompt` and
+ * imports no provider.
+ *
+ * Namespace plugin (named exports, no default export).
+ * @module @deepseek-ai/dsh-tool-lsp
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS, formatHover, formatLocations, LSP_OPERATIONS, parseLspArgs, presentLspCall, renderUri, } from './render.ts';
+export { sessionCwd } from './session-cwd.ts';
+/** Cordis plugin name for loader diagnostics. */
+export declare const name = "tool-lsp";
+/** Services required by this plugin. */
+export declare const inject: string[];
+/** Default tool-call timeout budget (ms), covering the queued open/query/close lifecycle. */
+export declare const DEFAULT_LSP_TOOL_TIMEOUT_MS = 60000;
+/** The stable system-prompt guidance positioning LSP as a precision aid. */
+export declare const LSP_PROMPT_TEXT = "Use search/read for ordinary navigation. Use lsp when textual matches are ambiguous or before a change requires precise definitions, implementations, or references. Positions are one-based line and character (UTF-16) at the cursor; an off-symbol position may return no results. findReferences always includes the declaration.";
+/** Plugin configuration: result caps and the timeout budget. */
+export interface Config {
+    /** Largest number of rendered locations before an omission marker (default 100). */
+    maxLocations?: number;
+    /** Largest complete rendered result in characters, including truncation metadata (default 16000). */
+    maxResultChars?: number;
+    /** Tool-call timeout budget in ms (default 60000). */
+    timeoutMs?: number;
+}
+export declare const Config: z<Config>;
+/**
+ * Register the `lsp` tool and its system-prompt guidance.
+ * @param ctx - the plugin context (must inject `tools`, `lsp`, `systemPrompt`).
+ * @param config - the resolved plugin configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-lsp`.
+ * @module @deepseek-ai/dsh-tool-lsp/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-lsp-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/render.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Pure formatting and coordinate conversion for the `lsp` tool: one-based↔zero-based UTF-16 cursor
+ * conversion, workspace-grouped location rendering with `file:`-URI resolution, complete-result
+ * capping, and UI presentation. No I/O — a UI may call the presenter on live streaming and on
+ * replay, so it depends only on the tool arguments.
+ * @module @deepseek-ai/dsh-tool-lsp/render
+ */
+import type { GenericCallView } from '@deepseek-ai/dsh-tools';
+import type { LspHover, LspLocation, LspOperation, LspPosition } from '@deepseek-ai/dsh-lsp';
+/** The four operations the tool exposes, as a runtime tuple for schema enum + validation. */
+export declare const LSP_OPERATIONS: readonly LspOperation[];
+/** Default cap on rendered locations before an omission marker is appended. */
+export declare const DEFAULT_MAX_LOCATIONS = 100;
+/** Default cap on the complete rendered tool result, including truncation metadata. */
+export declare const DEFAULT_MAX_RESULT_CHARS = 16000;
+/** Validated `lsp` arguments after coordinate checks. */
+export interface LspToolInput {
+    readonly operation: LspOperation;
+    readonly filePath: string;
+    /** Zero-based UTF-16 position converted from the one-based model coordinates. */
+    readonly position: LspPosition;
+}
+/** The raw, schema-typed argument shape. */
+export interface LspToolArgs {
+    readonly operation: string;
+    readonly file_path: string;
+    readonly line: number;
+    readonly character: number;
+}
+/**
+ * Validate and convert model arguments: `operation` must be one of the four; `line`/`character` are
+ * positive one-based integers converted to the seam's zero-based position.
+ * @param args - the schema-validated raw arguments.
+ * @returns the validated input with a zero-based position.
+ * @throws Error when the operation is unknown or a coordinate is not a positive integer.
+ */
+export declare function parseLspArgs(args: LspToolArgs): LspToolInput;
+/**
+ * Render a locations result grouped by file, converting each zero-based location back to a one-based
+ * `path:line:character` entry. A `file:` URI inside the workspace becomes a workspace-relative path;
+ * outside it, a URI-derived absolute path; a non-`file:` URI is kept verbatim. Applies `maxLocations` and
+ * appends an omission marker when it truncates by count, then applies the complete result cap.
+ * @param locations - the seam's locations (possibly empty).
+ * @param workspaceUri - the provider's canonical workspace `file:` URI.
+ * @param maxLocations - the cap before truncation.
+ * @param maxResultChars - the complete rendered-text cap, including truncation metadata.
+ * @returns the rendered text; a distinct no-result line when there are none.
+ */
+export declare function formatLocations(locations: readonly LspLocation[], workspaceUri: string, maxLocations: number, maxResultChars: number): string;
+/**
+ * Render a hover result, applying `maxResultChars` last and keeping its marker within the cap.
+ * @param hover - the normalized hover, or `null` for no hover.
+ * @param maxResultChars - the complete rendered-text cap, including truncation metadata.
+ * @returns the rendered hover text; a distinct no-result line for `null`.
+ */
+export declare function formatHover(hover: LspHover | null, maxResultChars: number): string;
+/**
+ * Resolve a location URI without applying the harness host's path rules. A valid `file:` URI becomes
+ * workspace-relative when it is under the provider's canonical workspace URI, or a URI-derived
+ * absolute path otherwise; malformed and non-`file:` URIs remain verbatim.
+ * @param uri - the target URI from the seam.
+ * @param workspaceUri - the provider's canonical workspace `file:` URI.
+ * @returns the display path or the verbatim URI.
+ */
+export declare function renderUri(uri: string, workspaceUri: string): string;
+/**
+ * UI presentation for a pending `lsp` call. Uses a generic search card; the title carries the
+ * operation and one-based cursor, and `locations` focuses the queried line. The shared location
+ * shape has no character, so the title preserves the column.
+ * @param args - the raw tool arguments.
+ * @returns the generic call view.
+ */
+export declare function presentLspCall(args: LspToolArgs): GenericCallView;
+//# sourceMappingURL=render.d.ts.map

package/lib/types/session-cwd.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Derive the workspace root an `lsp` call resolves against: the calling agent's per-session
+ * workspace (`exec.agent.session.header.cwd`), mirroring how the filesystem tools resolve paths.
+ * Unlike those tools, LSP has NO provider fallback — a missing cwd fails the call as
+ * `LSP_WORKSPACE_REQUIRED`, because the local provider must canonicalize a real workspace before it
+ * can start a server.
+ * @module @deepseek-ai/dsh-tool-lsp/session-cwd
+ */
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+/**
+ * The session workspace cwd for this call, or `undefined` when none applies.
+ * @param exec - the tool-execution context; only its optional `agent` is read.
+ * @returns the calling agent's session cwd, or undefined for a non-agent caller.
+ */
+export declare function sessionCwd(exec: ToolExecution): string | undefined;
+//# sourceMappingURL=session-cwd.d.ts.map

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@deepseek-ai/dsh-tool-lsp",
+  "description": "Model-facing lsp tool over the DeepSeek Harness LSP capability seam (ctx.lsp) — one read-only tool with goToDefinition/findReferences/goToImplementation/hover operations, one-based UTF-16 cursor coordinates, bounded location rendering, and hover normalization",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/lsp/tool-lsp"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-lsp": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-fs-local": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-lsp": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-lsp-local": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout-policy": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess-local": "^0.0.1-rc.1"
+  }
+}