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

npm --prefix vscode ci
mise run serve-network

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 start) 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:

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:

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.