fix(lsp): surface gopls spawn failure reasons to LLM via tool output

When gopls fails to start (e.g. Go runtime not installed), the error was
silently swallowed, causing the LLM to only see a generic 'No LSP server
available' message with no actionable guidance.

Changes:
- server.ts: Gopls.spawn() now throws descriptive errors instead of
  silently returning undefined when Go is missing or installation fails
- lsp.ts: broken set -> map to store failure reasons; add failureReason()
  method to query stored reasons by file
- tool/lsp.ts: query failureReason() when LSP unavailable, pass specific
  error message to LLM (e.g. 'Go runtime not found. Please install Go
  first')

Author: qiuhuayang

packages/opencode/src/lsp/lsp.ts

@@ -116,14 +116,15 @@ type LocInput = { file: string; line: number; character: number }
 interface State {
   clients: LSPClient.Info[]
   servers: Record<string, LSPServer.Info>
-  broken: Set<string>
+  broken: Map<string, string>
   spawning: Map<string, Promise<LSPClient.Info | undefined>>
 }
 
 export interface Interface {
   readonly init: () => Effect.Effect<void>
   readonly status: () => Effect.Effect<Status[]>
   readonly hasClients: (file: string) => Effect.Effect<boolean>
+  readonly failureReason: (file: string) => Effect.Effect<string | undefined>
   readonly touchFile: (input: string, diagnostics?: "document" | "full") => Effect.Effect<void>
   readonly diagnostics: () => Effect.Effect<Record<string, LSPClient.Diagnostic[]>>
   readonly hover: (input: LocInput) => Effect.Effect<any>
@@ -195,7 +196,7 @@ export const layer = Layer.effect(
         const s: State = {
           clients: [],
           servers,
-          broken: new Set(),
+          broken: new Map(),
           spawning: new Map(),
         }
 
@@ -222,11 +223,11 @@ export const layer = Layer.effect(
           const handle = await server
             .spawn(root, ctx, flags)
             .then((value) => {
-              if (!value) s.broken.add(key)
+              if (!value) s.broken.set(key, `LSP server '${server.id}' is not available`)
               return value
             })
             .catch((err) => {
-              s.broken.add(key)
+              s.broken.set(key, err instanceof Error ? err.message : `Failed to spawn LSP server ${server.id}`)
               log.error(`Failed to spawn LSP server ${server.id}`, { error: err })
               return undefined
             })
@@ -241,7 +242,7 @@ export const layer = Layer.effect(
             directory: ctx.directory,
             instance: ctx,
           }).catch(async (err) => {
-            s.broken.add(key)
+            s.broken.set(key, `Failed to initialize LSP client ${server.id}`)
             await Process.stop(handle.process)
             log.error(`Failed to initialize LSP client ${server.id}`, { error: err })
             return undefined
@@ -349,6 +350,22 @@ export const layer = Layer.effect(
       })
     })
 
+    const failureReason = Effect.fn("LSP.failureReason")(function* (file: string) {
+      const ctx = yield* InstanceState.context
+      const s = yield* InstanceState.get(state)
+      return yield* Effect.promise(async () => {
+        const extension = path.parse(file).ext || file
+        for (const server of Object.values(s.servers)) {
+          if (server.extensions.length && !server.extensions.includes(extension)) continue
+          const root = await server.root(file, ctx)
+          if (!root) continue
+          const reason = s.broken.get(root + server.id)
+          if (reason) return reason
+        }
+        return undefined
+      })
+    })
+
     const touchFile = Effect.fn("LSP.touchFile")(function* (input: string, diagnostics?: "document" | "full") {
       log.info("touching file", { file: input })
       const clients = yield* getClients(input)
@@ -491,6 +508,7 @@ export const layer = Layer.effect(
       init,
       status,
       hasClients,
+      failureReason,
       touchFile,
       diagnostics,
       hover,

packages/opencode/src/lsp/server.ts

@@ -353,7 +353,9 @@ export const Gopls: Info = {
   async spawn(root, _ctx, flags) {
     let bin = which("gopls")
     if (!bin) {
-      if (!which("go")) return
+      if (!which("go")) {
+        throw new Error("Go runtime not found. Please install Go first; gopls will then be installed automatically.")
+      }
       if (flags.disableLspDownload) return
 
       log.info("installing gopls")
@@ -365,8 +367,7 @@ export const Gopls: Info = {
       })
       const exit = await proc.exited
       if (exit !== 0) {
-        log.error("Failed to install gopls")
-        return
+        throw new Error("Failed to install gopls via 'go install'. Please install gopls manually.")
       }
       bin = path.join(Global.Path.bin, "gopls" + (process.platform === "win32" ? ".exe" : ""))
       log.info(`installed gopls`, {

packages/opencode/src/tool/lsp.ts

@@ -75,7 +75,10 @@ export const LspTool = Tool.define(
           if (!exists) throw new Error(`File not found: ${file}`)
 
           const available = yield* lsp.hasClients(file)
-          if (!available) throw new Error("No LSP server available for this file type.")
+          if (!available) {
+            const reason = yield* lsp.failureReason(file)
+            throw new Error(reason ?? "No LSP server available for this file type.")
+          }
 
           yield* lsp.touchFile(file, "document")
 

packages/opencode/test/session/prompt.test.ts

@@ -139,6 +139,7 @@ const lsp = Layer.succeed(
     init: () => Effect.void,
     status: () => Effect.succeed([]),
     hasClients: () => Effect.succeed(false),
+    failureReason: () => Effect.succeed(undefined),
     touchFile: () => Effect.void,
     diagnostics: () => Effect.succeed({}),
     hover: () => Effect.succeed(undefined),

packages/opencode/test/session/snapshot-tool-race.test.ts

@@ -95,6 +95,7 @@ const lsp = Layer.succeed(
     init: () => Effect.void,
     status: () => Effect.succeed([]),
     hasClients: () => Effect.succeed(false),
+    failureReason: () => Effect.succeed(undefined),
     touchFile: () => Effect.void,
     diagnostics: () => Effect.succeed({}),
     hover: () => Effect.succeed(undefined),

packages/opencode/test/tool/lsp.test.ts

@@ -36,6 +36,7 @@ const lsp = Layer.succeed(
     init: () => Effect.void,
     status: () => Effect.succeed([]),
     hasClients: () => Effect.succeed(true),
+    failureReason: () => Effect.succeed(undefined),
     touchFile: () => Effect.void,
     diagnostics: () => Effect.succeed({}),
     hover: () => Effect.succeed([]),