feat(lsp): LSP capability seam, generic stdio provider, and lsp tool

Implements the LSP capability seam RFC as three packages: dsh-lsp (the ctx.lsp interface — provider registry by branded id + exclusive extension mapping, per-query order-independent selection, closed request/result vocabulary, LspError taxonomy), dsh-lsp-local (a generic stdio language-server provider — Content-Length JSON-RPC framing, per-(provider, workspace) process single-flight, transient didOpen/query/didClose, an abortable per-instance queue, UTF-16 negotiation, host-namespace source reads outside ctx.fs, and bounded shutdown/kill teardown), and dsh-tool-lsp (the model-facing lsp tool — four operations, one-based UTF-16 cursor conversion, workspace-grouped location rendering, hover capping, a required session workspace, and a timeout budget). Why: an agent had text search and file reads but no way to identify a program symbol — follow an alias, connect an interface to implementations, or read an inferred type — before changing code. Splitting model contract, seam, and local subprocess behavior keeps the four semantic queries stable across future remote or sandbox-native providers without leaking a JSON-RPC escape hatch.
2026-07-16 12:05:35 +08:00
parent 66b2cfc609
commit d0029d8d60
56 changed files with 4527 additions and 30 deletions
@@ -0,0 +1,158 @@
+/**
+ * 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, hover capping, and
+ * ACP 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 { fileURLToPath } from 'node:url'
+import { isAbsolute, relative, sep } from 'node:path'
+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 const LSP_OPERATIONS: readonly LspOperation[] = ['definition', 'references', 'implementation', 'hover']
+
+/** Default cap on rendered locations before an omission marker is appended. */
+export const DEFAULT_MAX_LOCATIONS = 100
+
+/** Default cap on hover characters (applied after normalization) before truncation is marked. */
+export const DEFAULT_MAX_HOVER_CHARS = 16_000
+
+/** 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 function parseLspArgs(args: LspToolArgs): LspToolInput {
+  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,
+    // The model counts from 1; the seam (and protocol) count from 0.
+    position: { line: line - 1, character: character - 1 },
+  }
+}
+
+/** Whether a string is one of the four operations. */
+function isOperation(value: string): value is LspOperation {
+  return (LSP_OPERATIONS as readonly string[]).includes(value)
+}
+
+/** Validate a one-based coordinate is a positive integer. */
+function oneBased(value: number, name: string): number {
+  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, an absolute path; a non-`file:` URI is kept verbatim. Applies `maxLocations` and
+ * appends an omission marker when it truncates.
+ * @param locations - the seam's locations (possibly empty).
+ * @param workspaceRoot - the canonical workspace root for relativizing `file:` paths.
+ * @param maxLocations - the cap before truncation.
+ * @returns the rendered text; a distinct no-result line when there are none.
+ */
+export function formatLocations(
+  locations: readonly LspLocation[],
+  workspaceRoot: string,
+  maxLocations: number,
+): string {
+  if (locations.length === 0) return 'No results.'
+  const shown = locations.slice(0, maxLocations)
+  const omitted = locations.length - shown.length
+  const grouped = new Map<string, string[]>()
+  for (const location of shown) {
+    const path = renderUri(location.uri, workspaceRoot)
+    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: string[] = []
+  for (const entries of grouped.values()) lines.push(...entries)
+  if (omitted > 0) {
+    lines.push(`… ${omitted} more location${omitted === 1 ? '' : 's'} omitted (limit ${maxLocations}).`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Render a hover result, applying `maxHoverChars` last and marking truncation.
+ * @param hover - the normalized hover, or `null` for no hover.
+ * @param maxHoverChars - the cap applied after normalization.
+ * @returns the rendered hover text; a distinct no-result line for `null`.
+ */
+export function formatHover(hover: LspHover | null, maxHoverChars: number): string {
+  if (hover === null) return 'No hover information.'
+  const contents = hover.contents
+  if (contents.length <= maxHoverChars) return contents
+  return `${contents.slice(0, maxHoverChars)}\n… hover truncated (limit ${maxHoverChars} characters).`
+}
+
+/**
+ * Resolve a location URI to a display path. A `file:` URI accepted by Node becomes workspace-relative
+ * (inside) or absolute (outside); any other URI is returned verbatim.
+ * @param uri - the target URI from the seam.
+ * @param workspaceRoot - the canonical workspace root.
+ * @returns the display path or the verbatim URI.
+ */
+export function renderUri(uri: string, workspaceRoot: string): string {
+  if (!uri.startsWith('file:')) return uri
+  let absolute: string
+  try {
+    absolute = fileURLToPath(uri)
+  } catch {
+    // A malformed file: URI is not a path we can resolve; show it verbatim.
+    return uri
+  }
+  const rel = relative(workspaceRoot, absolute)
+  if (rel === '') return '.'
+  const outside = rel.startsWith('..') || isAbsolute(rel)
+  return outside ? absolute : rel.split(sep).join('/')
+}
+
+/**
+ * ACP 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 (ACP `FileLocation` has
+ * no character, so the title preserves the column).
+ * @param args - the raw tool arguments.
+ * @returns the generic call view.
+ */
+export function presentLspCall(args: LspToolArgs): GenericCallView {
+  return {
+    card: 'generic',
+    kind: 'search',
+    title: `LSP ${args.operation} ${args.file_path}:${args.line}:${args.character}`,
+    locations: [{ path: args.file_path, line: args.line }],
+  }
+}