@hydraharness/harness-tool-lsp 0.0.0-stage → 0.1.1-rc.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# @hydraharness/harness-tool-lsp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 `@hydraharness/harness-tool-call-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#hydraharness-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/lib/index.js

@@ -0,0 +1,412 @@
+import z from "@hydraharness/schemastery";
+import { defineTool } from "@hydraharness/harness-tools";
+import { assertNever } from "@hydraharness/harness-llm";
+import { LspError } from "@hydraharness/harness-lsp";
+import { MAX_TIMER_DELAY_MS } from "@hydraharness/harness-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 @hydraharness/harness-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 @hydraharness/harness-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
+* `@hydraharness/harness-tool-call-timeout-policy` to enforce. It runtime-injects only `tools`, `lsp`, and `systemPrompt` and
+* imports no provider.
+*
+* Namespace plugin (named exports, no default export).
+* @module @hydraharness/harness-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 `@hydraharness/harness-tool-lsp`.
+* @module @hydraharness/harness-tool-lsp/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-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
+ * `@hydraharness/harness-tool-call-timeout-policy` to enforce. It runtime-injects only `tools`, `lsp`, and `systemPrompt` and
+ * imports no provider.
+ *
+ * Namespace plugin (named exports, no default export).
+ * @module @hydraharness/harness-tool-lsp
+ */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/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 `@hydraharness/harness-tool-lsp`.
+ * @module @hydraharness/harness-tool-lsp/invariant
+ */
+import type { Context } from '@hydraharness/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 @hydraharness/harness-tool-lsp/render
+ */
+import type { GenericCallView } from '@hydraharness/harness-tools';
+import type { LspHover, LspLocation, LspOperation, LspPosition } from '@hydraharness/harness-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 @hydraharness/harness-tool-lsp/session-cwd
+ */
+import type { ToolExecution } from '@hydraharness/harness-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

@@ -1,6 +1,61 @@
 {
   "name": "@hydraharness/harness-tool-lsp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Model-facing lsp tool over the Hydra 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.1.1-rc.7",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-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": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-llm": "^0.1.1-rc.7",
+    "@hydraharness/harness-lsp": "^0.1.1-rc.7",
+    "@hydraharness/harness-system-prompt": "^0.1.1-rc.7",
+    "@hydraharness/harness-tools": "^0.1.1-rc.7",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.7",
+    "@hydraharness/harness-timeout": "^0.1.1-rc.7"
+  },
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-agent": "^0.1.1-rc.7",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.7",
+    "@hydraharness/harness-fs-local": "^0.1.1-rc.7",
+    "@hydraharness/harness-llm": "^0.1.1-rc.7",
+    "@hydraharness/harness-lsp": "^0.1.1-rc.7",
+    "@hydraharness/harness-lsp-stdio": "^0.1.1-rc.7",
+    "@hydraharness/harness-session": "^0.1.1-rc.7",
+    "@hydraharness/harness-subprocess-local": "^0.1.1-rc.7",
+    "@hydraharness/harness-system-prompt": "^0.1.1-rc.7",
+    "@hydraharness/harness-tool-call-timeout-policy": "^0.1.1-rc.7",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-tools": "^0.1.1-rc.7",
+    "@hydraharness/harness-timeout": "^0.1.1-rc.7"
+  }
 }