fix(lsp): align operations and harden lifecycle

2026-07-21 13:29:40 +08:00
parent 2a55f6b684
commit 2fd995bf3c
46 changed files with 680 additions and 366 deletions
--- a/packages/lsp/tool-lsp/README.md
+++ b/packages/lsp/tool-lsp/README.md
@@ -6,7 +6,7 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export). In

 ## The tool

-`lsp` accepts `operation` (`definition` | `references` | `implementation` | `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. `references` 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.
+`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. Locations render as stable, file-grouped `path:line:character` entries relativized against the result's `resolvedWorkspaceRoot` (the provider's canonical root), not the session cwd — so a symlinked cwd still renders in-workspace results as workspace-relative paths; a `file:` URI becomes a workspace-relative path (inside) or absolute path (outside), and any other URI stays verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.

@@ -15,7 +15,7 @@ The tool requires the workspace root from the session `header.cwd`, with no fall
 | Key | Default | Meaning |
 |---|---|---|
 | `maxLocations` | `100` | Largest number of rendered locations before an omission marker. |
-| `maxHoverChars` | `16000` | Largest hover length in characters, applied after normalization. |
+| `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
@@ -29,7 +29,7 @@ One system-prompt section (order 112) positions LSP as a precision aid with the
 ##### 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. references always includes the declaration.
+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
@@ -58,11 +58,11 @@ Prefix-stable while the visible tool definition and order are unchanged; registr

 #### What the model sees

-File-grouped `path:line:character` location lines or normalized hover text, capped by `maxLocations` / `maxHoverChars` with an omission marker when truncated, and distinct `No results.` / `No hover information.` lines for empty results.
+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. Empty results use distinct `No results.` / `No hover information.` lines.

 #### Token effect

-Capped per tool result by the two limits above.
+Capped per tool result by `maxResultChars`, with `maxLocations` additionally bounding navigation item count.

 #### KV Cache effect

--- a/packages/lsp/tool-lsp/package.json
+++ b/packages/lsp/tool-lsp/package.json
@@ -1,6 +1,6 @@
 {
  "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 definition/references/implementation/hover operations, one-based UTF-16 cursor coordinates, workspace-grouped location rendering, and hover normalization",
+  "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",
  "private": true,
  "type": "module",
@@ -25,6 +25,7 @@
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-lsp": "^0.0.1",
    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
  },
@@ -38,6 +39,7 @@
    "@deepseek-ai/dsh-lsp-local": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
    "@deepseek-ai/dsh-timeout-policy": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
    "cordis": "^4.0.0-rc.7"
--- a/packages/lsp/tool-lsp/src/index.ts
+++ b/packages/lsp/tool-lsp/src/index.ts
@@ -1,9 +1,10 @@
 /**
 * Model-facing `lsp` tool over `ctx.lsp`. One read-only tool with four operations
- * (`definition`/`references`/`implementation`/`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.
+ * (`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
@@ -12,13 +13,14 @@
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { assertNever, type ContentBlock } from '@deepseek-ai/dsh-llm'
 import { LspError } from '@deepseek-ai/dsh-lsp'
 import type {} from '@deepseek-ai/dsh-lsp'
 import type {} from '@deepseek-ai/dsh-system-prompt'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import {
-  DEFAULT_MAX_HOVER_CHARS,
  DEFAULT_MAX_LOCATIONS,
+  DEFAULT_MAX_RESULT_CHARS,
  formatHover,
  formatLocations,
  LSP_OPERATIONS,
@@ -28,8 +30,8 @@ import {
 import { sessionCwd } from './session-cwd.ts'

 export {
-  DEFAULT_MAX_HOVER_CHARS,
  DEFAULT_MAX_LOCATIONS,
+  DEFAULT_MAX_RESULT_CHARS,
  formatHover,
  formatLocations,
  LSP_OPERATIONS,
@@ -50,22 +52,22 @@ export const DEFAULT_LSP_TOOL_TIMEOUT_MS = 60_000

 /** The stable system-prompt guidance positioning LSP as a precision aid. */
 export 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. references always includes the declaration.'
+  '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 hover length in characters after normalization (default 16000). */
-  maxHoverChars?: 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 const Config: z<Config> = z.object({
  maxLocations: z.number().default(DEFAULT_MAX_LOCATIONS),
-  maxHoverChars: z.number().default(DEFAULT_MAX_HOVER_CHARS),
-  timeoutMs: z.number().default(DEFAULT_LSP_TOOL_TIMEOUT_MS),
+  maxResultChars: z.number().default(DEFAULT_MAX_RESULT_CHARS),
+  timeoutMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_LSP_TOOL_TIMEOUT_MS),
 })

 type ResolvedConfig = Required<Config>
@@ -78,21 +80,21 @@ type ResolvedConfig = Required<Config>
 export function apply(ctx: Context, config: Config): void {
  const resolved = config as ResolvedConfig
  assertPositiveInteger('maxLocations', resolved.maxLocations)
-  assertPositiveInteger('maxHoverChars', resolved.maxHoverChars)
-  assertPositiveInteger('timeoutMs', resolved.timeoutMs)
+  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 definition, references, implementation, hover. line and character are one-based UTF-16 cursor coordinates. references includes the declaration.',
+      '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: 'definition, references, implementation, or hover.',
+        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.' },
@@ -116,9 +118,12 @@ export function apply(ctx: Context, config: Config): void {
          // Relativize against the provider's canonical workspace root (which its file: URIs are
          // relative to), not the session cwd: a symlinked cwd would otherwise misclassify every
          // in-workspace location as external and render it as an absolute path.
-          return [{ type: 'text', text: formatLocations(result.locations, result.resolvedWorkspaceRoot, resolved.maxLocations) }]
+          return [{ type: 'text', text: formatLocations(result.locations, result.resolvedWorkspaceRoot, resolved.maxLocations, resolved.maxResultChars) }]
        case 'hover':
-          return [{ type: 'text', text: formatHover(result.hover, resolved.maxHoverChars) }]
+          return [{ type: 'text', text: formatHover(result.hover, resolved.maxResultChars) }]
+        /* v8 ignore next -- exhaustive over the closed LspQueryResult union; unreachable. */
+        default:
+          return assertNever(result, 'tool-lsp result')
      }
    },
    presentCall: presentLspCall,
@@ -131,3 +136,10 @@ function assertPositiveInteger(name: string, value: number): void {
    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: string, value: number): void {
+  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}`)
+  }
+}
--- a/packages/lsp/tool-lsp/src/render.ts
+++ b/packages/lsp/tool-lsp/src/render.ts
@@ -1,8 +1,8 @@
 /**
 * 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.
+ * conversion, workspace-grouped location rendering with `file:`-URI resolution, complete-result
+ * 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
 */

@@ -12,13 +12,13 @@ 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']
+export const LSP_OPERATIONS: readonly LspOperation[] = ['goToDefinition', 'findReferences', 'goToImplementation', '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
+/** Default cap on the complete rendered tool result, including truncation metadata. */
+export const DEFAULT_MAX_RESULT_CHARS = 16_000

 /** Validated `lsp` arguments after coordinate checks. */
 export interface LspToolInput {
@@ -75,18 +75,20 @@ function oneBased(value: number, name: string): number {
 * 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.
+ * appends an omission marker when it truncates by count, then applies the complete result cap.
 * @param locations - the seam's locations (possibly empty).
 * @param workspaceRoot - the canonical workspace root for relativizing `file:` paths.
 * @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 function formatLocations(
  locations: readonly LspLocation[],
  workspaceRoot: string,
  maxLocations: number,
+  maxResultChars: number,
 ): string {
-  if (locations.length === 0) return 'No results.'
+  if (locations.length === 0) return boundResult('No results.', maxResultChars, 'locations')
  const shown = locations.slice(0, maxLocations)
  const omitted = locations.length - shown.length
  const grouped = new Map<string, string[]>()
@@ -103,20 +105,26 @@ export function formatLocations(
  if (omitted > 0) {
    lines.push(`… ${omitted} more location${omitted === 1 ? '' : 's'} omitted (limit ${maxLocations}).`)
  }
-  return lines.join('\n')
+  return boundResult(lines.join('\n'), maxResultChars, 'locations')
 }

 /**
- * Render a hover result, applying `maxHoverChars` last and marking truncation.
+ * 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 maxHoverChars - the cap applied after normalization.
+ * @param maxResultChars - the complete rendered-text cap, including truncation metadata.
 * @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).`
+export function formatHover(hover: LspHover | null, maxResultChars: number): string {
+  const text = hover === null ? 'No hover information.' : hover.contents
+  return boundResult(text, maxResultChars, 'hover')
+}
+
+/** Bound a complete rendered result, including the truncation notice itself. */
+function boundResult(text: string, maxChars: number, label: string): string {
+  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}`
 }

 /**
--- a/packages/lsp/tool-lsp/tests/integration.spec.ts
+++ b/packages/lsp/tool-lsp/tests/integration.spec.ts
@@ -78,7 +78,7 @@ function call(ctx: Context, args: unknown) {
 describe('tool-lsp integration', () => {
  it('round-trips a definition query through the real provider and renders a location', async () => {
    const ctx = await mount(false)
-    const result = await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 1, character: 7 })
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 7 })
    expect(result.isError).toBe(false)
    expect(result.content[0]).toEqual({ type: 'text', text: 'a.ts:1:1' })
    await ctx.fiber.dispose()
@@ -86,7 +86,7 @@ describe('tool-lsp integration', () => {

  it('enforces the TOOL_TIMEOUT budget when the server hangs', async () => {
    const ctx = await mount(true, 300)
-    const result = await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 1, character: 7 })
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 7 })
    expect(result.isError).toBe(true)
    expect(result.error?.code).toBe('TOOL_TIMEOUT')
    await ctx.fiber.dispose()
--- a/packages/lsp/tool-lsp/tests/render.spec.ts
+++ b/packages/lsp/tool-lsp/tests/render.spec.ts
@@ -2,8 +2,8 @@ import { describe, expect, it } from 'vitest'
 import { pathToFileURL } from 'node:url'
 import { join } from 'node:path'
 import {
-  DEFAULT_MAX_HOVER_CHARS,
  DEFAULT_MAX_LOCATIONS,
+  DEFAULT_MAX_RESULT_CHARS,
  formatHover,
  formatLocations,
  LSP_OPERATIONS,
@@ -79,52 +79,63 @@ describe('renderUri', () => {

 describe('formatLocations', () => {
  it('renders a no-result line for an empty list', () => {
-    expect(formatLocations([], WS, DEFAULT_MAX_LOCATIONS)).toBe('No results.')
+    expect(formatLocations([], WS, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)).toBe('No results.')
  })

  it('renders one-based path:line:character grouped by file', () => {
    const a = pathToFileURL(join(WS, 'a.ts')).href
-    const text = formatLocations([loc(a, 0, 0), loc(a, 4, 2)], WS, DEFAULT_MAX_LOCATIONS)
+    const text = formatLocations([loc(a, 0, 0), loc(a, 4, 2)], WS, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)
    expect(text).toBe('a.ts:1:1\na.ts:5:3')
  })

  it('caps at maxLocations and marks the omission', () => {
    const a = pathToFileURL(join(WS, 'a.ts')).href
    const many = Array.from({ length: 5 }, (_, i) => loc(a, i))
-    const text = formatLocations(many, WS, 2)
+    const text = formatLocations(many, WS, 2, DEFAULT_MAX_RESULT_CHARS)
    expect(text).toContain('a.ts:1:1')
    expect(text).toContain('3 more locations omitted (limit 2).')
  })

  it('uses the singular omission marker for exactly one extra', () => {
    const a = pathToFileURL(join(WS, 'a.ts')).href
-    const text = formatLocations([loc(a, 0), loc(a, 1)], WS, 1)
+    const text = formatLocations([loc(a, 0), loc(a, 1)], WS, 1, DEFAULT_MAX_RESULT_CHARS)
    expect(text).toContain('1 more location omitted (limit 1).')
  })
+
+  it('caps the complete location text even when one URI is enormous', () => {
+    const maxResultChars = 80
+    const text = formatLocations([loc(`custom:${'x'.repeat(1_000_000)}`, 0)], WS, 1, maxResultChars)
+    expect(text).toHaveLength(maxResultChars)
+    expect(text).toContain('locations truncated')
+  })
 })

 describe('formatHover', () => {
  it('renders a no-result line for null', () => {
-    expect(formatHover(null, DEFAULT_MAX_HOVER_CHARS)).toBe('No hover information.')
+    expect(formatHover(null, DEFAULT_MAX_RESULT_CHARS)).toBe('No hover information.')
  })

  it('returns short hover verbatim', () => {
-    expect(formatHover({ contents: '```ts\nx: number\n```' }, DEFAULT_MAX_HOVER_CHARS)).toBe('```ts\nx: number\n```')
+    expect(formatHover({ contents: '```ts\nx: number\n```' }, DEFAULT_MAX_RESULT_CHARS)).toBe('```ts\nx: number\n```')
  })

-  it('caps hover at maxHoverChars and marks truncation', () => {
-    const text = formatHover({ contents: 'a'.repeat(50) }, 10)
-    expect(text.startsWith('aaaaaaaaaa\n')).toBe(true)
-    expect(text).toContain('hover truncated (limit 10 characters).')
+  it('caps the complete hover text including its truncation marker', () => {
+    const text = formatHover({ contents: 'a'.repeat(100) }, 60)
+    expect(text).toHaveLength(60)
+    expect(text).toContain('hover truncated (limit 60 characters).')
+  })
+
+  it('still honors a cap smaller than the truncation marker', () => {
+    expect(formatHover({ contents: 'a'.repeat(100) }, 10)).toHaveLength(10)
  })
 })

 describe('presentLspCall', () => {
  it('is a generic search card with an operation/cursor title and a line location', () => {
-    expect(presentLspCall({ operation: 'references', file_path: 'a.ts', line: 3, character: 7 })).toEqual({
+    expect(presentLspCall({ operation: 'findReferences', file_path: 'a.ts', line: 3, character: 7 })).toEqual({
      card: 'generic',
      kind: 'search',
-      title: 'LSP references a.ts:3:7',
+      title: 'LSP findReferences a.ts:3:7',
      locations: [{ path: 'a.ts', line: 3 }],
    })
  })
--- a/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts
+++ b/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts
@@ -5,6 +5,7 @@ import ToolRegistry from '@deepseek-ai/dsh-tools'
 import Lsp, { LspProviderId, type LspProvider, type LspProviderQuery, type LspQueryResult } from '@deepseek-ai/dsh-lsp'
 import * as ToolLsp from '@deepseek-ai/dsh-tool-lsp'
 import { DEFAULT_LSP_TOOL_TIMEOUT_MS, LSP_PROMPT_TEXT } from '@deepseek-ai/dsh-tool-lsp'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'

 /** A scripted provider recording queries; `respond` yields the result or throws. */
 function stubProvider(
@@ -76,7 +77,7 @@ describe('tool-lsp registration', () => {
  it('exposes exactly the four operations in the schema enum', async () => {
    const { ctx } = await mount(stubProvider(() => okLocations))
    const schema = ctx.tools.get('lsp')?.parameters as { properties: { operation: { enum: string[] } } }
-    expect(schema.properties.operation.enum).toEqual(['definition', 'references', 'implementation', 'hover'])
+    expect(schema.properties.operation.enum).toEqual(['goToDefinition', 'findReferences', 'goToImplementation', 'hover'])
  })

  it('has no default export (namespace plugin shape)', () => {
@@ -86,16 +87,28 @@ describe('tool-lsp registration', () => {
  it('rejects a non-positive config value at load', async () => {
    await expect(mount(stubProvider(() => okLocations), { maxLocations: 0 })).rejects.toThrow(/maxLocations/)
  })
+
+  it('rejects a timeout above Node timer range at load', async () => {
+    await expect(mount(stubProvider(() => okLocations), { timeoutMs: MAX_TIMER_DELAY_MS + 1 }))
+      .rejects.toThrow(/timeoutMs/)
+    expect(() => {
+      ToolLsp.apply(new Context(), {
+        maxLocations: 100,
+        maxResultChars: 16_000,
+        timeoutMs: MAX_TIMER_DELAY_MS + 1,
+      })
+    }).toThrow(/timeoutMs/)
+  })
 })

 describe('tool-lsp execution', () => {
  it('converts one-based coordinates and passes the session cwd as workspaceRoot', async () => {
    const provider = stubProvider(() => okLocations)
    const { ctx } = await mount(provider)
-    const result = await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 3, character: 5 }, '/ws')
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 3, character: 5 }, '/ws')
    expect(result.isError).toBe(false)
    expect(provider.seen[0]).toMatchObject({
-      operation: 'definition',
+      operation: 'goToDefinition',
      filePath: 'a.ts',
      position: { line: 2, character: 4 },
      workspaceRoot: '/ws',
@@ -104,7 +117,7 @@ describe('tool-lsp execution', () => {

  it('renders locations relative to the workspace', async () => {
    const { ctx } = await mount(stubProvider(() => okLocations))
-    const result = await call(ctx, { operation: 'references', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
+    const result = await call(ctx, { operation: 'findReferences', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
    expect(result.content[0]).toEqual({ type: 'text', text: 'a.ts:1:1' })
  })

@@ -118,7 +131,7 @@ describe('tool-lsp execution', () => {
      resolvedWorkspaceRoot: '/real/ws',
    }))
    const { ctx } = await mount(provider)
-    const result = await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 1, character: 1 }, '/alias')
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, '/alias')
    expect(provider.seen[0]).toMatchObject({ workspaceRoot: '/alias' })
    expect(result.content[0]).toEqual({ type: 'text', text: 'a.ts:1:1' })
  })
@@ -131,14 +144,14 @@ describe('tool-lsp execution', () => {

  it('fails LSP_WORKSPACE_REQUIRED without a session cwd', async () => {
    const { ctx } = await mount(stubProvider(() => okLocations))
-    const result = await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 1, character: 1 }, null)
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, null)
    expect(result.isError).toBe(true)
    expect(result.error?.code).toBe('LSP_WORKSPACE_REQUIRED')
  })

  it('surfaces a structured LSP_UNAVAILABLE when no provider handles the file', async () => {
    const { ctx } = await mount(stubProvider(() => okLocations, { '.py': 'python' }))
-    const result = await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
    expect(result.isError).toBe(true)
    expect(result.error?.code).toBe('LSP_UNAVAILABLE')
  })
@@ -161,7 +174,7 @@ describe('tool-lsp execution', () => {
      },
    }
    const { ctx } = await mount(provider)
-    await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
+    await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
    // The timeout policy is not mounted here, so the signal is whatever the registry passes (may be
    // undefined); the point is the tool threads it through without throwing.
    expect(seen).toHaveLength(1)
--- a/packages/lsp/tool-lsp/tsconfig.json
+++ b/packages/lsp/tool-lsp/tsconfig.json
@@ -26,6 +26,9 @@
    {
      "path": "../../core/system-prompt"
    },
+    {
+      "path": "../../util/timeout"
+    },
    {
      "path": "../lsp"
    }