runa/vscode/README.md

# Runa VS Code client

This is the first, read-only client for a trusted localhost Runa image. It uses
the [version 3 protocol](../docs/protocol.md) over WebSockets with the `runa-debug`
subprotocol, not Rust APIs, and never
hosts actors or starts its own image.

## Run from source

Requirements: VS Code 1.96+, Node.js 22+, npm, and the repository's Rust toolchain.

From the repository root:

```sh
npm --prefix vscode ci
mise run start
```

Open the repository in VS Code. In Run and Debug, select **Run Runa Extension**
and press F5. The launch task compiles TypeScript before opening an Extension
Development Host.

In that host:

1. Run **Runa: Connect to Local Image**. The default is `127.0.0.1:3737`;
   `runa.address` changes the suggested endpoint.
2. Expand **Runa Actors** in Explorer. Use the REPL (`mise run cli`) to
   spawn actors in the same server. The tree updates automatically.
3. Click an actor or run **Runa: Inspect Actor** to open its JSON snapshot.
4. Run **Runa: Disconnect** to close only this client connection.

Connection prompts accept numeric IPv4 loopback addresses (`127.x.x.x`) or
`[::1]:port`. DNS names, wildcard addresses, remote addresses, and IPv4-mapped
IPv6 addresses are rejected. There is no authentication: connect only to a
trusted local server. In a remote VS Code window, localhost refers to the
machine running the extension host, not necessarily the desktop.

## Snapshot semantics

- The tree shows actor references, lifecycle status, and queued/reserved counts.
  Tooltips include implementation ID, incarnation, and failure text.
- Inspect fetches a fresh snapshot through `inspect_actor`. Documents show
  committed state, FIFO queued messages, the reserved message, status, and
  active-execution telemetry. Tagged values distinguish actor references from
  strings and preserve signed 64-bit integers exactly.
- Documents are read-only snapshots, not editable actor state or live VM frames.
  The timestamp records when this client received the data, not a runtime clock.
  Server `image_changed` notifications automatically update the tree and open
  documents. Bursts are coalesced, and changes arriving during a fetch trigger
  a follow-up fetch. **Refresh Actors** is also available on demand.
- Open documents are retained and marked `connected: false` on disconnect.
  Each connection gets distinct document URIs; reconnecting never replaces
  snapshots from an earlier connection or another image. Closing a document
  releases its cache; snapshots are not persisted across VS Code restarts.
- There is no auto-connect, polling, automatic reconnect, or request retry.
  Timeout, peer disconnect, malformed data, and version/correlation failures
  invalidate the connection and are surfaced in a notification and the **Runa**
  output channel. Server-reported operation errors leave the connection usable.
- The client does not tick the scheduler, drain `get_events`, spawn/send, or
  change actor lifecycle/behavior. Use the REPL for those operations.
  Notifications are non-destructive invalidations, not a replayable runtime
  event stream; reconnect fetches the current image rather than replaying history.

For automation, the `runa.connect` command also accepts an explicit endpoint
string, and `runa.inspect` accepts an object with an `actor_ref` field.

## Development and validation

From the repository root:

```sh
mise run format
mise run lint
mise run test
mise run test-extension-host
```

The normal test task covers portable-value validation, framing and UTF-8
fragmentation, subprotocol negotiation, interleaved notifications, refresh
coalescing, timeout/disconnect behavior, exact 64-bit integer display, and
interoperation with the real Rust server on an ephemeral loopback port.

The separate host test downloads VS Code 1.96.4 to the ignored `.vscode-test/`
cache and runs connection, inspection, disconnect, and reconnect commands
against a test-owned Rust server. It verifies automatic document updates after
another client sends messages, pauses, and advances an actor into failure, as
well as session isolation. On headless Linux:

```sh
xvfb-run -a mise run test-extension-host
```

Behavior/source browsing and editing, spawn/send and lifecycle controls,
compilation diagnostics, detailed runtime event subscriptions, packaging for
distribution, and debugging remain future work.