editor/protocol.md

# TCP Protocol

Transport: UTF-8 JSON objects separated by `\n`.

File paths in text and intelligence requests are normalized to absolute daemon-side paths before being used as document keys.

## Request

```json
{"id":1,"method":"workspace/open","params":{"root":"/home/me/project"}}
```

## Response

```json
{"id":1,"ok":true,"result":{"root":"/home/me/project","gradle":true,"modules":[],"sourceRoots":[],"tasks":[]}}
```

## Error

```json
{"id":1,"ok":false,"error":{"code":"UNKNOWN_METHOD","message":"No handler for method"}}
```

## Event

```json
{"event":"workspace/indexing","params":{"state":"started"}}
```

Diagnostics are also published asynchronously after `text/open` and `text/change`:

```json
{"event":"diagnostics/publish","params":{"path":"/home/me/project/src/main/kotlin/App.kt","version":7,"diagnostics":[]}}
```

## Current Methods

The `kotlin/*` names are historical protocol names. Diagnostics and heuristic intelligence currently also handle `.java` files where noted.

- `ping`
- `workspace/open`
- `workspace/close`
- `text/open`
- `text/change`
- `text/close`
- `kotlin/diagnostics`
- `kotlin/completion`
- `kotlin/definition`
- `kotlin/references`
- `kotlin/rename`
- `kotlin/hover`
- `gradle/tasks`
- `gradle/run`

## `workspace/open` Result

Module `sourceRoots` and `testSourceRoots` include Gradle IdeaModel roots plus common generated Kotlin/Java source directories under `build/generated/` when those directories already exist.

```json
{
  "root": "/home/me/project",
  "gradle": true,
  "modules": [
    {
      "name": "app",
      "gradlePath": ":app",
      "directory": "/home/me/project/app",
      "sourceRoots": [],
      "testSourceRoots": [],
      "resourceRoots": [],
      "testResourceRoots": []
    }
  ],
  "sourceRoots": [],
  "tasks": []
}
```

## `gradle/run` Request

```json
{"id":2,"method":"gradle/run","params":{"task":":app:test"}}
```

## `kotlin/diagnostics` Request

Supports Kotlin and Java files. Kotlin diagnostics use the embedded Kotlin compiler; Java diagnostics use the JDK compiler. Main files use main source roots, while test files use main plus test source roots. Existing module output directories under `build/classes/` and `build/resources/` are added to the compiler classpath.

```json
{"id":3,"method":"kotlin/diagnostics","params":{"path":"/home/me/project/src/main/kotlin/App.kt"}}
```

## `kotlin/diagnostics` Result

```json
{
  "diagnostics": [
    {
      "severity": "error",
      "message": "Syntax error",
      "path": "/home/me/project/src/main/kotlin/App.kt",
      "line": 1,
      "column": 12
    }
  ]
}
```

## `kotlin/completion` Request

Returns prefix-filtered Kotlin/Java keywords plus heuristic declarations and identifiers from the current buffer and workspace.

```json
{"id":4,"method":"kotlin/completion","params":{"path":"/home/me/project/src/main/kotlin/App.kt","line":10,"column":8}}
```

`line` and `column` are 1-based.

## `kotlin/completion` Result

```json
{
  "items": [
    {"label": "fun", "kind": "keyword"}
  ]
}
```

## `kotlin/hover` Request

Returns keyword or heuristic Kotlin/Java declaration information for the identifier at the requested position.

```json
{"id":5,"method":"kotlin/hover","params":{"path":"/home/me/project/src/main/kotlin/App.kt","line":10,"column":8}}
```

`line` and `column` are 1-based.

## `kotlin/hover` Result

```json
{"contents":"Kotlin keyword `fun`"}
```

`contents` is `null` when no hover information is available.

## `kotlin/definition` Request

Returns heuristic Kotlin/Java declaration locations for the identifier at the requested position.

```json
{"id":6,"method":"kotlin/definition","params":{"path":"/home/me/project/src/main/kotlin/App.kt","line":10,"column":8}}
```

`line` and `column` are 1-based.

## `kotlin/definition` Result

```json
{
  "locations": [
    {"path": "/home/me/project/src/main/kotlin/App.kt", "line": 4, "column": 7}
  ]
}
```

## `kotlin/references` Request

Returns heuristic Kotlin/Java text references for the identifier at the requested position.

```json
{"id":7,"method":"kotlin/references","params":{"path":"/home/me/project/src/main/kotlin/App.kt","line":10,"column":8}}
```

`line` and `column` are 1-based.

## `kotlin/references` Result

```json
{
  "locations": [
    {"path": "/home/me/project/src/main/kotlin/App.kt", "line": 4, "column": 7}
  ]
}
```

## `kotlin/rename` Request

```json
{"id":8,"method":"kotlin/rename","params":{"path":"/home/me/project/src/main/kotlin/App.kt","line":10,"column":8,"newName":"newSymbol"}}
```

This is currently preview-only. It does not modify files.
`newName` must be a valid identifier and must not be a Kotlin or Java keyword.

## `kotlin/rename` Result

```json
{
  "applied": false,
  "oldName": "oldSymbol",
  "newName": "newSymbol",
  "edits": [
    {"path": "/home/me/project/src/main/kotlin/App.kt", "line": 4, "column": 7, "oldText": "oldSymbol", "newText": "newSymbol"}
  ]
}
```