@mrclrchtr/supi-lsp 7.3.1 → 8.0.0

package/src/provider/refactor-planning.ts

@@ -4,6 +4,8 @@ import type {
   RefactorResult,
   SourceRange,
 } from "@mrclrchtr/supi-code-runtime/api";
+import { CodeActionTriggerKind } from "vscode-languageserver-types";
+import { codeActionKindsForOperation } from "../config/operation-support.ts";
 import type { CodeAction } from "../config/types.ts";
 import type { WorkspaceLspRuntime } from "../session/runtime-registry.ts";
 import {
@@ -25,6 +27,12 @@ export async function runRenameRefactor(options: {
   if (!response) {
     return { kind: "unavailable", reason: "No routed LSP client could plan the rename." };
   }
+  if (!response.value) {
+    return {
+      kind: "unavailable",
+      reason: response.reason ?? "No routed LSP client could plan the rename.",
+    };
+  }
   return normalizeSemanticEdit(
     { kind: "workspace-edit", edit: response.value },
     {
@@ -52,17 +60,25 @@ export async function runFilteredCodeActionRefactor(options: {
   lsp: WorkspaceLspRuntime;
   file: string;
   position: CodePosition;
-  operation: "update_imports" | "delete_dead_code" | "extract_function" | "extract_variable";
+  operation: "update_imports" | "delete_dead_code";
   range?: SourceRange;
   matches: (action: CodeAction) => boolean;
   control?: CodeRequestControl;
 }): Promise<RefactorResult> {
   const { lsp, file, position, operation, matches } = options;
-  const response = options.control
-    ? await lsp.codeActions(file, options.range ?? position, options.control)
-    : await lsp.codeActions(file, options.range ?? position);
-  const actions = response?.value;
-  if (!response || !actions || actions.length === 0) {
+  const response = await lsp.codeActions(file, options.range ?? position, options.control, {
+    only: codeActionKindsForOperation(operation),
+    triggerKind: CodeActionTriggerKind.Invoked,
+  });
+  if (!response || response.reason) {
+    return {
+      kind: "unavailable",
+      reason:
+        response?.reason ?? `No code actions are available for refactor operation "${operation}".`,
+    };
+  }
+  const actions = response.value;
+  if (!actions || actions.length === 0) {
     return {
       kind: "unavailable",
       reason: `No code actions are available for refactor operation "${operation}".`,
@@ -81,63 +97,99 @@ export async function runFilteredCodeActionRefactor(options: {
     getOpenDocumentVersion: (candidate) => lsp.getOpenDocumentVersion(candidate),
     authorizedMutationRoots: response.authorizedMutationRoots,
   };
-  let unavailableReason: string | null = null;
-  for (const action of matching) {
-    const converted = normalizeSemanticEdit({ kind: "code-action", action }, context);
-    if (converted.kind === "precise") return converted;
-    if (converted.kind === "unavailable") unavailableReason ??= converted.reason;
+  const plans = collectPrecisePlans(matching, context);
+  if (plans.precise.length === 1) return plans.precise[0].result;
+  if (plans.precise.length > 1) {
+    return {
+      kind: "ambiguous",
+      candidates: plans.precise.map(({ action, result }, index) =>
+        refactorCandidate(action, result, index, plans.precise),
+      ),
+    };
   }
-
   return {
     kind: "unavailable",
-    reason: unavailableReason
-      ? `Matching code action is unavailable: ${unavailableReason}`
+    reason: plans.unavailableReason
+      ? `Matching code action is unavailable: ${plans.unavailableReason}`
       : `Matching code actions for refactor operation "${operation}" did not produce precise edits.`,
   };
 }
 
 export function isUpdateImportsCodeAction(action: CodeAction): boolean {
-  const kind = action.kind ?? "";
-  const title = action.title.trim().toLowerCase();
-  const kindlessTitleMatch = kind === "" && title === "organize imports";
-  return (
-    kind === "source.organizeImports" ||
-    kind.startsWith("source.organizeImports.") ||
-    kindlessTitleMatch
-  );
+  const kind = typeof action?.kind === "string" ? action.kind : "";
+  return kind === "source.organizeImports" || kind.startsWith("source.organizeImports.");
 }
 
-export function isExtractFunctionCodeAction(action: CodeAction): boolean {
-  const kind = action.kind ?? "";
-  const title = action.title.trim().toLowerCase();
-  return (
-    kind === "refactor.extract.function" ||
-    kind.startsWith("refactor.extract.function.") ||
-    (title.includes("extract") && /\b(function|method)\b/.test(title))
-  );
+export function isDeleteDeadCodeCodeAction(action: CodeAction): boolean {
+  const kind = typeof action?.kind === "string" ? action.kind : "";
+  return kind === "source.removeUnused" || kind.startsWith("source.removeUnused.");
+}
+
+interface PreciseCodeActionPlan {
+  action: CodeAction;
+  result: Extract<RefactorResult, { kind: "precise" }>;
 }
 
-export function isExtractVariableCodeAction(action: CodeAction): boolean {
-  const kind = action.kind ?? "";
-  const title = action.title.trim().toLowerCase();
-  return (
-    kind === "refactor.extract.constant" ||
-    kind.startsWith("refactor.extract.constant.") ||
-    kind === "refactor.extract.variable" ||
-    kind.startsWith("refactor.extract.variable.") ||
-    (title.includes("extract") && /\b(constant|const|variable)\b/.test(title))
+function collectPrecisePlans(
+  actions: readonly CodeAction[],
+  context: SemanticEditNormalizationContext,
+): { precise: PreciseCodeActionPlan[]; unavailableReason: string | null } {
+  const precise: PreciseCodeActionPlan[] = [];
+  const planKeys = new Set<string>();
+  let unavailableReason: string | null = null;
+  for (const action of actions) {
+    const converted = normalizeSemanticEdit({ kind: "code-action", action }, context);
+    if (converted.kind === "precise") {
+      const key = normalizedPlanKey(converted);
+      if (!planKeys.has(key)) {
+        planKeys.add(key);
+        precise.push({ action, result: converted });
+      }
+      continue;
+    }
+    if (converted.kind === "unavailable") unavailableReason ??= converted.reason;
+  }
+  return { precise, unavailableReason };
+}
+
+function normalizedPlanKey(result: Extract<RefactorResult, { kind: "precise" }>): string {
+  const edits = result.edits.edits
+    .map((edit) => ({
+      file: edit.file,
+      start: edit.range.start,
+      end: edit.range.end,
+      newText: edit.newText,
+    }))
+    .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+  const preconditions = [...(result.edits.documentPreconditions ?? [])].sort((left, right) =>
+    JSON.stringify(left).localeCompare(JSON.stringify(right)),
   );
+  return JSON.stringify({ edits, preconditions });
 }
 
-export function isDeleteDeadCodeCodeAction(action: CodeAction): boolean {
-  const kind = action.kind ?? "";
-  const title = action.title.trim().toLowerCase();
-  const kindMatches =
-    kind === "quickfix" ||
-    kind.startsWith("quickfix.") ||
-    kind === "refactor.rewrite" ||
-    kind.startsWith("refactor.rewrite.");
-  const titleMatches =
-    /(unused|dead code|remove unused|remove unreachable|remove declaration)/.test(title);
-  return kindMatches && titleMatches;
+function refactorCandidate(
+  action: CodeAction,
+  result: Extract<RefactorResult, { kind: "precise" }>,
+  index: number,
+  plans: readonly { action: CodeAction }[],
+): {
+  description: string;
+  file?: string;
+  line?: number;
+  character?: number;
+} {
+  const firstEdit = result.edits.edits[0];
+  const sameTitleCount = plans.filter((plan) => plan.action.title === action.title).length;
+  const description =
+    sameTitleCount > 1 ? `${action.title} (alternative ${index + 1})` : action.title;
+  return {
+    description,
+    ...(firstEdit
+      ? {
+          file: firstEdit.file,
+          line: firstEdit.range.start.line + 1,
+          character: firstEdit.range.start.character + 1,
+        }
+      : {}),
+  };
 }

package/src/provider/semantic-edit-normalizer.ts

@@ -36,7 +36,9 @@ function normalizeCodeAction(
   const action = asRecord(value);
   if (
     !action ||
+    !Object.hasOwn(action, "title") ||
     typeof action.title !== "string" ||
+    action.title.trim().length === 0 ||
     !hasOnlyKeys(action, [
       "title",
       "kind",
@@ -46,11 +48,33 @@ function normalizeCodeAction(
       "edit",
       "command",
       "data",
+    ]) ||
+    !hasNoInheritedAllowedKeys(action, [
+      "title",
+      "kind",
+      "diagnostics",
+      "isPreferred",
+      "disabled",
+      "edit",
+      "command",
+      "data",
     ])
   ) {
     return { kind: "unavailable", reason: "LSP server returned a malformed code action." };
   }
   const title = action.title;
+  if (
+    Object.hasOwn(action, "kind") &&
+    (typeof action.kind !== "string" || action.kind.trim().length === 0)
+  ) {
+    return { kind: "unavailable", reason: `Code action "${title}" has a malformed kind.` };
+  }
+  if (Object.hasOwn(action, "diagnostics") && !Array.isArray(action.diagnostics)) {
+    return { kind: "unavailable", reason: `Code action "${title}" has malformed diagnostics.` };
+  }
+  if (Object.hasOwn(action, "isPreferred") && typeof action.isPreferred !== "boolean") {
+    return { kind: "unavailable", reason: `Code action "${title}" has a malformed preference.` };
+  }
   if (Object.hasOwn(action, "disabled")) {
     return { kind: "unavailable", reason: `Code action "${title}" is disabled.` };
   }
@@ -82,7 +106,8 @@ function normalizeWorkspaceEdit(
   const workspaceEdit = asRecord(value);
   if (
     !workspaceEdit ||
-    !hasOnlyKeys(workspaceEdit, ["changes", "documentChanges", "changeAnnotations"])
+    !hasOnlyKeys(workspaceEdit, ["changes", "documentChanges", "changeAnnotations"]) ||
+    !hasNoInheritedAllowedKeys(workspaceEdit, ["changes", "documentChanges", "changeAnnotations"])
   ) {
     return { kind: "unavailable", reason: "LSP server returned a malformed workspace edit." };
   }
@@ -92,7 +117,8 @@ function normalizeWorkspaceEdit(
       reason: "Workspace edit contains unsupported change annotations.",
     };
   }
-  return Object.hasOwn(workspaceEdit, "documentChanges")
+  const hasDocumentChanges = Object.hasOwn(workspaceEdit, "documentChanges");
+  return hasDocumentChanges
     ? normalizeDocumentChanges(workspaceEdit.documentChanges, context)
     : normalizeChanges(workspaceEdit.changes, context);
 }
@@ -165,7 +191,7 @@ function normalizeDocumentChange(
   if (!file) {
     return { kind: "unavailable", reason: "Document change does not contain a valid file URI." };
   }
-  if (!("version" in textDocument)) {
+  if (!Object.hasOwn(textDocument, "version")) {
     return { kind: "unavailable", reason: "Document change does not contain a version." };
   }
   const precondition = establishPrecondition(file, textDocument.version, context);
@@ -185,9 +211,14 @@ function parseTextDocumentEdit(edit: Record<string, unknown> | null): {
   const textDocument = asRecord(edit?.textDocument);
   if (
     !edit ||
+    !Object.hasOwn(edit, "textDocument") ||
+    !Object.hasOwn(edit, "edits") ||
     !hasOnlyKeys(edit, ["textDocument", "edits"]) ||
+    !hasNoInheritedAllowedKeys(edit, ["textDocument", "edits"]) ||
     !textDocument ||
+    !Object.hasOwn(textDocument, "uri") ||
     !hasOnlyKeys(textDocument, ["uri", "version"]) ||
+    !hasNoInheritedAllowedKeys(textDocument, ["uri", "version"]) ||
     !Array.isArray(edit.edits)
   ) {
     return null;
@@ -245,9 +276,15 @@ function normalizeTextEdits(
     const end = asPosition(range?.end);
     if (
       !textEdit ||
+      !Object.hasOwn(textEdit, "range") ||
+      !Object.hasOwn(textEdit, "newText") ||
       !hasOnlyKeys(textEdit, ["range", "newText"]) ||
+      !hasNoInheritedAllowedKeys(textEdit, ["range", "newText", "snippet", "annotationId"]) ||
       !range ||
+      !Object.hasOwn(range, "start") ||
+      !Object.hasOwn(range, "end") ||
       !hasOnlyKeys(range, ["start", "end"]) ||
+      !hasNoInheritedAllowedKeys(range, ["start", "end"]) ||
       !start ||
       !end ||
       isBefore(end, start) ||
@@ -285,6 +322,13 @@ function hasOnlyKeys(value: Record<string, unknown>, allowed: readonly string[])
   return Object.keys(value).every((key) => allowedKeys.has(key));
 }
 
+function hasNoInheritedAllowedKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+): boolean {
+  return allowed.every((key) => !(key in value) || Object.hasOwn(value, key));
+}
+
 function asRecord(value: unknown): Record<string, unknown> | null {
   return typeof value === "object" && value !== null && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -294,6 +338,8 @@ function asRecord(value: unknown): Record<string, unknown> | null {
 function asPosition(value: unknown): { line: number; character: number } | null {
   const position = asRecord(value);
   return position &&
+    Object.hasOwn(position, "line") &&
+    Object.hasOwn(position, "character") &&
     hasOnlyKeys(position, ["line", "character"]) &&
     Number.isInteger(position.line) &&
     (position.line as number) >= 0 &&

package/src/session/runtime-controller.ts

@@ -13,14 +13,13 @@ import {
   recordDebugEvent,
   truncateDebugIdentity as truncateIdentity,
 } from "@mrclrchtr/supi-core/debug";
-import { loadConfig } from "../config/config.ts";
-import { type LspSettings, loadLspSettings } from "../config/lsp-settings.ts";
+import { getExplicitlyDisabledLanguages, loadConfig } from "../config/config.ts";
 import { clearTsconfigCache } from "../config/tsconfig-scope.ts";
 import type { DetectedProjectServer, LspConfig, ProjectServerInfo } from "../config/types.ts";
 import { LspManager, type ManagerLifecycleTransition } from "../manager/manager.ts";
 import {
   type AutomaticLspPathPolicy,
-  createAutomaticLspPathPolicy,
+  createDefaultAutomaticLspPathPolicy,
 } from "../workspace-path-policy.ts";
 import {
   markLspCapabilitiesReady,
@@ -62,7 +61,7 @@ interface LspControllerReady {
   workspaceRuntime: WorkspaceLspRuntime;
   projectServers: ProjectServerInfo[];
   detectedServers: DetectedProjectServer[];
-  settings: LspSettings;
+  config: LspConfig;
   automaticPathPolicy: AutomaticLspPathPolicy;
 }
 
@@ -76,6 +75,16 @@ interface LspControllerUnavailable {
   reason: string;
 }
 
+/** Options for one LSP runtime controller. */
+export interface LspRuntimeControllerOptions {
+  /** Whether project-scoped configuration is trusted. Defaults to true. */
+  readonly projectTrusted?: boolean;
+  /** Global config home, used by managed sessions and tests. */
+  readonly homeDir?: string;
+  /** A policy captured by the owning workspace host. */
+  readonly automaticPathPolicy?: AutomaticLspPathPolicy;
+}
+
 /** Result type from {@link LspRuntimeController.start}. */
 export type LspStartResult =
   | { kind: "ready"; runtime: WorkspaceLspRuntime }
@@ -129,6 +138,7 @@ function supersededStartResult(): LspStartResult {
  */
 export class LspRuntimeController {
   readonly #cwd: string;
+  readonly #options: LspRuntimeControllerOptions;
   #state: LspControllerState;
   #capabilityRuntime: WorkspaceRuntime | null;
   #activeManager: LspManager | null = null;
@@ -139,9 +149,14 @@ export class LspRuntimeController {
   readonly #lifecycleListeners = new Set<LspRuntimeTransitionListener>();
   /** Monotonic ownership token for starts, shutdowns, and manager callbacks. */
   #readinessGeneration = 0;
+  /** Explicit disablement captured with the active server configuration. */
+  #activeExplicitlyDisabledLanguages: readonly string[] = [];
+  /** Validation failure from the configuration snapshot used by automatic work. */
+  #configurationError: string | null = null;
 
-  constructor(cwd: string, runtime?: WorkspaceRuntime) {
+  constructor(cwd: string, runtime?: WorkspaceRuntime, options: LspRuntimeControllerOptions = {}) {
     this.#cwd = cwd;
+    this.#options = options;
     this.#state = { kind: "initial" };
     this.#capabilityRuntime = runtime ?? null;
   }
@@ -173,9 +188,9 @@ export class LspRuntimeController {
     return [];
   }
 
-  /** LSP settings used for this session. */
-  get settings(): LspSettings | null {
-    if (this.#state.kind === "ready") return this.#state.settings;
+  /** Automatic path policy captured for the active runtime. */
+  get automaticPathPolicy(): AutomaticLspPathPolicy | null {
+    if (this.#state.kind === "ready") return this.#state.automaticPathPolicy;
     return null;
   }
 
@@ -208,7 +223,8 @@ export class LspRuntimeController {
   /**
    * Start the LSP session for this controller's cwd.
    *
-   * Loads settings, creates the manager, starts detected servers,
+   * Loads the server configuration and one automatic path snapshot, creates
+   * the manager, starts detected servers,
    * publishes the session service, and registers capabilities.
    *
    * Always attempts detected servers unless they were explicitly disabled
@@ -224,11 +240,37 @@ export class LspRuntimeController {
     await this.cleanupExistingSession();
     if (generation !== this.#readinessGeneration) return supersededStartResult();
 
-    const lspSettings = loadLspSettings(this.#cwd);
-    const config = loadConfig(this.#cwd);
-
+    let automaticPathPolicy: AutomaticLspPathPolicy;
+    let config: LspConfig;
+    let explicitlyDisabledLanguages: string[];
+    try {
+      automaticPathPolicy =
+        this.#options.automaticPathPolicy ??
+        createDefaultAutomaticLspPathPolicy(this.#cwd, {
+          projectTrusted: this.#options.projectTrusted,
+          homeDir: this.#options.homeDir,
+        });
+      config = loadConfig(this.#cwd, {
+        projectTrusted: this.#options.projectTrusted,
+        homeDir: this.#options.homeDir,
+      });
+      explicitlyDisabledLanguages = getExplicitlyDisabledLanguages(this.#cwd, {
+        projectTrusted: this.#options.projectTrusted,
+        homeDir: this.#options.homeDir,
+      });
+    } catch (error: unknown) {
+      this.#configurationError =
+        error instanceof Error && error.message ? error.message : String(error);
+      return this.setUnavailable(error, generation);
+    }
+    this.#configurationError = null;
     try {
-      return await this.initializeLspSession(config, lspSettings, generation);
+      return await this.initializeLspSession(
+        config,
+        automaticPathPolicy,
+        explicitlyDisabledLanguages,
+        generation,
+      );
     } catch (error: unknown) {
       return this.setUnavailable(error, generation);
     }
@@ -266,6 +308,7 @@ export class LspRuntimeController {
     const reason = error instanceof Error ? error.message : String(error);
     this.#activeManager = null;
     this.#latestManagerTransition = null;
+    this.#activeExplicitlyDisabledLanguages = [];
     if (this.#capabilityRuntime) unregisterLspCapabilities(this.#capabilityRuntime, this.#cwd);
     this.#projectedSemanticReady = null;
     this.#state = { kind: "unavailable", reason };
@@ -279,15 +322,16 @@ export class LspRuntimeController {
    */
   private async initializeLspSession(
     config: LspConfig,
-    settings: LspSettings,
+    automaticPathPolicy: AutomaticLspPathPolicy,
+    explicitlyDisabledLanguages: readonly string[],
     generation: number,
   ): Promise<LspStartResult> {
     if (generation !== this.#readinessGeneration) return supersededStartResult();
     clearWorkspaceLspRuntime(this.#cwd);
+    this.#activeExplicitlyDisabledLanguages = [...explicitlyDisabledLanguages];
     if (Object.keys(config.servers).length === 0) return this.setDisabled(generation);
     this.#state = { kind: "pending" };
 
-    const automaticPathPolicy = createAutomaticLspPathPolicy(this.#cwd, settings.exclude);
     let manager: LspManager;
     manager = new LspManager(
       config,
@@ -340,7 +384,7 @@ export class LspRuntimeController {
       workspaceRuntime,
       projectServers,
       detectedServers,
-      settings,
+      config,
       automaticPathPolicy,
     };
 
@@ -438,6 +482,8 @@ export class LspRuntimeController {
     clearTsconfigCache();
     this.#activeManager = null;
     this.#latestManagerTransition = null;
+    this.#activeExplicitlyDisabledLanguages = [];
+    this.#configurationError = null;
 
     if (this.#capabilityRuntime) {
       unregisterLspCapabilities(this.#capabilityRuntime, this.#cwd);
@@ -456,10 +502,24 @@ export class LspRuntimeController {
     this.publishLifecycle("shutdown", false, []);
   }
 
+  /** Explicit language disablement captured by the active LSP session. */
+  getExplicitlyDisabledLanguages(): readonly string[] {
+    return [...this.#activeExplicitlyDisabledLanguages];
+  }
+
+  /** Configuration validation error that prevented automatic LSP startup, if any. */
+  getConfigurationError(): string | null {
+    return this.#configurationError;
+  }
+
   /** Get the missing servers warning (servers whose binary is not on PATH). */
   getMissingServers(): Array<{ name: string; command: string }> {
     if (this.#state.kind !== "ready") return [];
-    const config = loadConfig(this.#cwd);
-    return scanMissingServers(config, this.#cwd, undefined, this.#state.automaticPathPolicy);
+    return scanMissingServers(
+      this.#state.config,
+      this.#cwd,
+      undefined,
+      this.#state.automaticPathPolicy,
+    );
   }
 }

package/src/session/runtime-registry.ts

@@ -15,6 +15,7 @@ import {
 } from "@mrclrchtr/supi-core/debug";
 import { resolveToolPath as resolveSessionPath } from "@mrclrchtr/supi-core/path";
 import { createSessionStateRegistry } from "@mrclrchtr/supi-core/session";
+import { CodeActionTriggerKind } from "vscode-languageserver-types";
 import type {
   CodeAction,
   Diagnostic,
@@ -47,6 +48,7 @@ import type {
   BulkTrackFilesResult,
   RoutedMutationResponse,
   SemanticReadinessResult,
+  WorkspaceCodeActionRequestOptions,
   WorkspaceLspRuntime,
   WorkspaceLspRuntimeState,
 } from "./workspace-lsp-runtime.ts";
@@ -81,12 +83,18 @@ export type {
   BulkTrackFilesResult,
   RoutedMutationResponse,
   SemanticReadinessResult,
+  WorkspaceCodeActionRequestOptions,
   WorkspaceLspRuntime,
   WorkspaceLspRuntimeState,
 } from "./workspace-lsp-runtime.ts";
 
 function isRange(value: Position | Range): value is Range {
-  return "start" in value && "end" in value;
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Object.hasOwn(value, "start") &&
+    Object.hasOwn(value, "end")
+  );
 }
 
 function unavailableFileQuery<T>(operation: string, file: string): CodeQueryResult<T> {
@@ -234,6 +242,18 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
       control,
     });
     if (!client) return null;
+    if (typeof client.renameDetailed === "function") {
+      const result = await client.renameDetailed(resolvedPath, position, newName, control);
+      return {
+        value: result.kind === "completed" ? result.data : null,
+        authorizedMutationRoots: [client.root],
+        ...(result.kind === "unavailable"
+          ? { reason: result.reason }
+          : result.data === null
+            ? { reason: "LSP server returned no workspace edit." }
+            : {}),
+      };
+    }
     return {
       value: await client.rename(resolvedPath, position, newName, control),
       authorizedMutationRoots: [client.root],
@@ -248,6 +268,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     filePath: string,
     positionOrRange: Position | Range,
     control?: CodeRequestControl,
+    options?: WorkspaceCodeActionRequestOptions,
   ): Promise<RoutedMutationResponse<CodeAction[] | null> | null> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
@@ -264,8 +285,25 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
       .filter((diagnostic) => diagnostic.range.end.line >= range.start.line)
       .filter((diagnostic) => diagnostic.range.start.line <= range.end.line);
 
+    const context = {
+      diagnostics,
+      triggerKind: options?.triggerKind ?? CodeActionTriggerKind.Invoked,
+      ...(options?.only ? { only: [...options.only] } : {}),
+    };
+    if (typeof client.codeActionsDetailed === "function") {
+      const result = await client.codeActionsDetailed(resolvedPath, range, context, control);
+      return {
+        value: result.kind === "completed" ? result.data : null,
+        authorizedMutationRoots: [client.root],
+        ...(result.kind === "unavailable"
+          ? { reason: result.reason }
+          : result.data === null
+            ? { reason: "LSP server returned no code actions." }
+            : {}),
+      };
+    }
     return {
-      value: await client.codeActions(resolvedPath, range, { diagnostics }, control),
+      value: await client.codeActions(resolvedPath, range, context, control),
       authorizedMutationRoots: [client.root],
     };
   }
@@ -410,6 +448,12 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     this.manager.noteWorkspaceChanges(changes);
   }
 
+  /** Synchronize tracked files after successful writes and send requested saves. */
+  noteWorkspaceWrites(changes: FileEvent[]): void {
+    this.manager.clearAllPullResultIds();
+    this.manager.noteWorkspaceWrites(changes);
+  }
+
   async #shutdown(): Promise<void> {
     await this.manager.shutdownAll();
   }

package/src/session/workspace-lsp-runtime.ts

@@ -1,6 +1,7 @@
 import type { CodeQueryResult, CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import type {
   CodeAction,
+  CodeActionContext,
   DocumentSymbol,
   FileEvent,
   Hover,
@@ -61,6 +62,16 @@ export interface RoutedMutationResponse<T> {
   readonly value: T;
   /** Roots that the routed client owns for this mutation response. */
   readonly authorizedMutationRoots: readonly string[];
+  /** Honest reason when the routed server could not provide the operation. */
+  readonly reason?: string;
+}
+
+/** Extra protocol context for one explicit code-action request. */
+export interface WorkspaceCodeActionRequestOptions {
+  /** Operation-specific CodeActionKind filters. */
+  readonly only?: readonly string[];
+  /** Explicit requests use Invoked; automatic callers may select another kind. */
+  readonly triggerKind?: CodeActionContext["triggerKind"];
 }
 
 /** Outcome for one path selected by a bounded automatic tracking batch. */
@@ -134,6 +145,7 @@ export interface WorkspaceLspRuntime extends WorkspaceLspDiagnosticSurface {
     filePath: string,
     positionOrRange: Position | Range,
     control?: CodeRequestControl,
+    options?: WorkspaceCodeActionRequestOptions,
   ): Promise<RoutedMutationResponse<CodeAction[] | null> | null>;
   getOpenDocumentVersion(filePath: string): number | null;
   /**
@@ -173,4 +185,6 @@ export interface WorkspaceLspRuntime extends WorkspaceLspDiagnosticSurface {
   closeFile(filePath: string): void;
   pruneMissingFiles(): readonly string[];
   noteWorkspaceChanges(changes: FileEvent[]): void;
+  /** Synchronize tracked files after successful writes and send requested saves. */
+  noteWorkspaceWrites(changes: FileEvent[]): void;
 }