ionide / ionide/FsAutoComplete

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

Open
#1,532 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
F#
Stars
486
Forks
169
Avg merge
2d 8h
Merged PRs (30d)
5

Description

## 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:

```json
{
"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:

```json
{
"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:

```text
fsharp/workspaceStatus
```

returning something like:

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

#### Option C: add an explicit notification

Emit a dedicated notification when semantic services are ready:

```text
fsharp/workspaceReady
```

with a stable payload.

### Current workaround

The client currently treats `fsharp/notifyWorkspace` payloads with:

```json
{
"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

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.