Language server protocol

acton ls implements the standard Language Server Protocol and a small set of custom requests. Use standard LSP methods for editor features whenever one exists. For example, formatting uses textDocument/formatting and textDocument/rangeFormatting rather than a custom method.

Positions and ranges use the LSP UTF-16 coordinate system. File locations are absolute file: URIs unless a request says otherwise.

Runtime settings

The language server has one settings object for every supported language. Its generated JSON Schema contains every property, default value, enum value, and description.

Pass the settings object through initializationOptions to configure the server before it opens documents:

{
  "processId": null,
  "rootUri": "file:///workspace",
  "capabilities": {},
  "initializationOptions": {
    "tolk": {
      "diagnostics": {
        "enabled": true,
        "linter": {"enabled": true},
        "compiler": {"enabled": true}
      }
    }
  }
}

Send the same object in workspace/didChangeConfiguration when settings change:

{
  "settings": {
    "tolk": {
      "hints": {"parameters": false},
      "diagnostics": {
        "linter": {"enabled": false}
      }
    }
  }
}

VS Code sends its configuration section inside a ton property. The server accepts this wrapper too:

{
  "settings": {
    "ton": {
      "tolk": {
        "completion": {"addImports": false}
      }
    }
  }
}

Omitted properties use the defaults from the schema. A configuration change replaces the previous settings object. Send every non-default value again with each change.

Changes to diagnostic settings republish diagnostics for every open Tolk document. Changes to inlay hints and semantic highlighting request a client refresh. Other changes apply to the next matching request.

Lint rule levels and contract-specific overrides stay in Acton.toml. Runtime settings only enable or disable the linter as a diagnostic provider.

tolk.getTypeAtPosition

Returns the inferred Tolk type at a source position. This request is available in native and WASM servers.

{
  "textDocument": {"uri": "file:///workspace/main.tolk"},
  "position": {"line": 12, "character": 20}
}

{
  "type": "cell",
  "range": {
    "start": {"line": 12, "character": 16},
    "end": {"line": 12, "character": 23}
  }
}

Both fields are null when the server cannot determine a type.

ton/profile

Returns accumulated language-server performance data. Pass an empty object as the request params. Profiling must be enabled when starting the native server:

acton ls --stdio --profile

{}

{
  "enabled": true,
  "counters": {
    "document.open": 1,
    "document.change": 4
  },
  "spans": {
    "tolk.type_inference": {
      "count": 5,
      "totalMs": 42.75,
      "averageMs": 8.55
    }
  }
}

counters contains operation counts. spans contains timings aggregated by operation name for the current server session. Values are not reset when this request is called. A disabled profiler returns enabled: false with empty data.

ton/disassemble

Disassembles a Bag of Cells into TON assembly. This request is available in the native server. Provide exactly one of uri or data.

Use uri for a binary or text-encoded BoC file:

{
  "uri": "file:///workspace/build/contract.boc"
}

Use data for a hex- or base64-encoded BoC:

{
  "data": "te6ccgEBAQEAAgAAAA=="
}

{
  "assembly": "SETCP 0\n..."
}

The server returns JSON-RPC error -32603 when the URI cannot be read, the input cannot be decoded, or disassembly fails. Passing both inputs or neither input is also an error.

WASM host requests

The browser worker exposes additional methods for embedding the WASM server. They are host controls, not part of the native acton ls contract.

The WASM worker also implements ton/profile and tolk.getTypeAtPosition with the response shapes documented above.