Document or expose a stable workspace-ready signal for AutomaticWorkspaceInit clients

[Neftedollar]

Details

I am building a non-IDE LSP client on top of FsAutoComplete. The client starts FSAC as an LSP subprocess and exposes F# semantic navigation tools to coding agents.

The client currently uses:

{
  "initializationOptions": {
    "AutomaticWorkspaceInit": true
  }
}

and listens to fsharp/notifyWorkspace / fsharp/workspaceLoad notifications to decide when semantic tools such as definition, references, workspace symbols, and diagnostics are safe to use.

The README documents that:

• fsharp/workspaceLoad loads projects in the background
• partial results are notified through fsharp/notifyWorkspace
• AutomaticWorkspaceInit = true starts workspace loading automatically

For a non-IDE client, the missing piece is a stable readiness contract: which notification or request result should be treated as authoritative evidence that the workspace is loaded enough for semantic operations.

Questions this feature should answer

1. Which method name is authoritative for workspace load completion?

   • fsharp/notifyWorkspace
   • fsharp/workspaceLoad
   • another method/notification?

2. What exact payload shape means workspace ready?

   • { "Kind": "workspaceLoad", "Data": { "Status": "finished" } }
   • { "content": "{\"Kind\":\"workspaceLoad\",\"Data\":{\"Status\":\"finished\"}}" }
   • { "status": "finished" }
   • another shape?

3. Does AutomaticWorkspaceInit = true emit the same completion notification as manually calling fsharp/workspaceLoad?

4. What does completion mean?

   • workspace discovery finished
   • projects loaded
   • type checking ready
   • diagnostics published
   • all of the above?

Why this matters

Agent clients do not have a human watching IDE UI state. If the client marks the workspace ready too early, semantic tools can return incomplete or misleading results. If the client waits for the wrong notification, startup hangs or times out.

Possible solutions

Any of these would work from a client perspective.

Option A: document the authoritative notification

Document one canonical ready signal, for example:

{
  "method": "fsharp/notifyWorkspace",
  "params": {
    "Kind": "workspaceLoad",
    "Data": {
      "Status": "finished"
    }
  }
}

and clarify that clients should ignore unrelated status = finished payloads.

Option B: add a structured workspace status request

Expose a request such as:

fsharp/workspaceStatus

returning something like:

{
  "status": "loading | ready | failed",
  "loadedProjects": 12,
  "failedProjects": [],
  "diagnosticsComplete": true
}

Option C: add an explicit notification

Emit a dedicated notification when semantic services are ready:

fsharp/workspaceReady

with a stable payload.

Current workaround

The client currently treats fsharp/notifyWorkspace payloads with:

{
  "Kind": "workspaceLoad",
  "Data": {
    "Status": "finished"
  }
}

as ready, and also tolerates wrapped content payloads. This works in observed testing, but it is based on behavior rather than a clearly documented contract.

Checklist

• I have looked through existing issues to make sure that this feature has not been requested before
• I have provided a descriptive title for this issue
• I am aware that even valid feature requests may be rejected if they do not align with the project's goals
• I or my company would be willing to contribute this feature