runa/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

[Unreleased]

Added

• Add an egui/eframe graphical client for browsing and inspecting actors in a running image, with message, lifecycle, breakpoint, stepping, stack, and log views.
• Extend the graphical client with source editing, compilation diagnostics, source commits, and explicit image-event collection.
• Add committed source history browsing, revision preview, and confirmed rollback to the graphical source editor.

Changed

• Pretty-print actor state and mailbox JSON with two-space indentation while preserving exact integers and actor-reference markers.

• Rename the actor's virtual log file to actor.log for automatic VS Code log highlighting and show syslog-style priority, actor, sequence, and severity fields.

• Expand VS Code actors into directories with read-only meta.json/log, live-editable config.json, and guarded natural-JSON state.json/mailbox.json.

• Allow reload/become to repair failed actors' implementations without clearing failure, state, or reserved messages; restart remains explicit.

• Breaking: Successful graceful stop and immediate kill now remove actors, discarding their state, mailbox, and retained logs. Failed actors remain until killed. Restart remains an independent, identity-preserving operation.

• Default the bundled self-incrementing counter's missing/null state to zero when it handles its first message.

• Mark removed actors' open VS Code inspection snapshots read-only with removed: true while removing them from the actor list.

• Breaking: Handler and shutdown-hook unit returns (including omitted returns) now retain the previously committed state instead of replacing it with null. Draft mutations are discarded; valid sends and message acknowledgement still commit.

• Change the bundled counter to an inc operation that logs each increment and continuously queues another increment to itself using ctx.this.

• Breaking: Protocol v5 adds actor log thresholds to snapshots, guarded editing operations, and opt-in log-history/follow operations and notifications.

• Move image sources and actors into a dedicated Runa Activity Bar sidebar, with the source file tree first and both views visible by default.

• Remove the VS Code Add Source Folder to Workspace command; image files are accessed exclusively through the automatic image-source Explorer view.

• Show the image's editable virtual source filesystem automatically in the VS Code Explorer without adding a workspace folder.

• Require an explicit runa-cli subcommand: repl starts the interactive session, and each image operation is also available as a one-shot command.

• Rename the REPL actor listing command from actors to ps, remove its cancel command, and rename mise run cli to mise run repl.

Fixed

• Refresh saved actor inspection JSON through filesystem notifications instead of an unavailable VS Code revert command.
• Always prompt for JSON state when Spawn with State is invoked from a source context menu, including multi-selection menu arguments.
• Close extension connections with a WebSocket handshake on disconnect, reconnect, and deactivation instead of terminating the transport immediately.
• Exit the REPL on Ctrl+C and complete the WebSocket close handshake instead of returning to the prompt.
• Complete the WebSocket close handshake when the CLI exits, preventing normal disconnects from producing a connection-reset protocol error on the server.

Added

• Server startup restoration with --restore <file> / RUNA_RESTORE, reusing snapshot validation and actor scheduling rules without merging bundled sources or falling back to a fresh image on errors.

• Explicit versioned disk image save/restore through the CLI, REPL, protocol and VS Code commands. Preserve source/history, actor identities, committed state, mailbox envelopes and retained logs; reject unfinished handlers, pause runnable actors on save and restore their scheduling eligibility with fresh incarnations. Snapshot files are server-local; replacement requires explicit authorization and is atomic.

• Atomic snapshot replacement with save --overwrite; VS Code prompts before replacing an existing server-local snapshot.

• Native VS Code debugger attachment to failed actors for retained-state, reserved-message and failure inspection, plus DAP exception details for both existing and newly observed failures. Debug controls never retry failed actors; no post-mortem stack is fabricated.

• Read-only snapshot-path watches and Debug Console lookups using actor/<JSON Pointer path>, with Add to Watch paths on actor variables, expandable results, exact integers and explicit rejection of Rune expressions.

• Read-only VS Code debugger actor-snapshot scopes with expandable committed state, mailbox, configuration and identity, exact integer formatting, paged children, and stale-handle invalidation. Invocation drafts and frame locals are not exposed or evaluated.

• Native VS Code Debug Actor attach sessions with exact loaded sources, gutter breakpoint verification, call stacks, pause/continue and bounded toolbar stepping. Sessions terminate on actor removal, implementation/incarnation change or image disconnect; detaching never kills or implicitly resumes the actor.

• Bounded source step-over and step-out through the runtime, image API, protocol, and VS Code actor commands, preserving nested breakpoints and async stop boundaries.

• Actor-local, implementation-bound source breakpoints with explicit line verification and scheduler pauses that retain active drafts and buffered sends.

• Bounded source step-into through the image API/protocol and VS Code actor actions, with stop reasons, exact loaded-source navigation, and async/lifecycle safety.

• Read-only execution-stack inspection with exact loaded source identities, bounded nested Rune frames, UTF-16 locations, and explicit pending-await status.

• VS Code Inspect Execution Stack... actor action, navigating frames in immutable loaded-source documents even after shared or temporary source edits.

• Structured Rune compilation errors and warnings through a read-only check_source protocol operation and compilation-failure error details.

• Automatic VS Code inline/Problems diagnostics for open image sources and actor-specific behavior documents, including unsaved edits, correct UTF-16 locations, and stale-response/session isolation.

• Source file creation, rename/move with confirmed actor path updates and history preservation, and deletion guarded against running actor users.

• Server-owned actor-specific temporary behaviors, safe-boundary compile-on-save, and VS Code Edit Current Behavior, Go to Behavior, and confirmed Update Behavior actions. Temporary scripts appear as an actor's behavior file and are cleared by reload without implicitly committing shared source.

• Editable VS Code inspection JSON for inactive actors, restoring protected fields with a warning; actor-reference copy actions and a scheduler toolbar button.

• Read-only ctx.this actor reference for transactional self-messaging.

• Guarded actor state and reserved/queued message editing through the CLI, REPL, and VS Code for paused/stopped/failed actors without active execution.

• Immediate actor logs via ctx.log(level, message) and severity helpers, per-actor thresholds, bounded retained history, and server-filtered CLI logs [-f|--follow] [actor...] subscriptions.

• Mutable image-owned source files organized beneath source/, with independent commit history and generated readable revision IDs. Spawn compiles the current working file whether committed or not.

• Internal sender/data envelopes and actor contexts with send and send_from; sends remain transactional and actors cannot construct privileged system commands.

• Graceful stop with optional on_shutdown(state), force kill, restart, pause/resume, and safe-boundary reload/become.

• VS Code image source filesystem, file-context spawn actions, and source commit/history/rollback controls.

• VS Code behavior explorer with revision history, implementation identities, and read-only Rune source documents isolated by connection and revision. Image notifications refresh behavior listings without changing historical source documents.

• VS Code actor spawning with explicit behavior and initial state, structured message sending, pause/resume/stop/restart controls, and explicit scheduler ticks. JSON inputs preserve i64 integers and $actor/$record markers.

• Lossless, size-bounded mutation requests and real-server/extension-host coverage for actor controls.

• Non-destructive image_changed server notifications with coalesced per-connection revisions and automatic VS Code tree/inspector refresh.

• Tests for WebSocket subprotocol negotiation, invalid messages, multi-client notifications, and automatic mailbox/lifecycle/failure inspector updates.

• Initial TypeScript VS Code extension with explicit localhost connection management, an actor explorer, and read-only state/mailbox/execution snapshots.

• Bounded protocol-v3 extension client with lossless 64-bit JSON integers, correlation checks, disconnect handling, and no automatic retries.

• Extension transport tests, real Rust-server interoperability coverage, and a VS Code host test for inspector refresh and reconnect isolation.

• Portable structured actor values: null, booleans, signed 64-bit integers, strings, lists, records, and distinct NanoID actor references.

• JSON state/message literals in the REPL, including named $actor references, $record escaping, and actor-reference completion inside nested values.

• Value conversion limits and tests for nested-state isolation, copied sends, cyclic/unsupported Rune output, and all-or-nothing structured transitions.

• Reusable loopback TCP protocol client with bounded messages, correlation checks, explicit connection failures, and no automatic request retries.

• Multi-client and reconnect tests proving that actors remain in the server-owned image after development clients disconnect.

• Typed, instruction-sliced Rune invocations with preserved async execution, wake-driven resumption, and cancellation tests.

• Minimal single-worker actor runtime with bounded FIFO mailboxes, private integer state, structured messages, immutable implementation IDs, explicit message effects, inspection, lifecycle events, stop, and restart.

• Runnable two-actor counter demonstration and tests for runaway fairness, pending-message isolation, failures, backpressure, and all-or-nothing effects.

• Interactive local CLI for spawning actors, sending messages, advancing ticks, inspecting actors/events, and stopping/restarting actors.

• Versioned BLAKE3 source and implementation identities, original-source retention, a Rune compile-input fingerprint, and an in-memory compiled artifact cache.

• In-memory named behavior revisions with optimistic publish checks, immutable history, rollback revisions, and runtime installation at idle handler boundaries.

• CLI commands for named behavior publishing, history, rollback, and installation, plus mise run run to launch the local executable.

• Cooperative actor pause/resume between scheduler ticks, preserving active invocations and emitting lifecycle events.

• Explicit safe-point state migration during implementation installation, with atomic failure behavior and migration events.

• Explicit invocation cancellation that requeues the reserved message for retry, exposed in the CLI and documented with native side-effect caveats.

• Active actor execution telemetry in snapshots: completed VM steps, instruction pointer, and call-frame depth.

• Trusted in-process runa-image-api service boundary for code and actor operations, now used by the local CLI.

• Versioned, transport-neutral runa-protocol request, response, and event DTOs with serde support and request validation.

• Transport-neutral runa-server dispatcher routing protocol commands through the image API with typed replies and error codes.

• Local JSON-lines stdio transport for the protocol dispatcher, with a 1 MiB request limit and explicit malformed-input failures.

• Reusable local child-process client for issuing correlated protocol requests and shutting down the server process cleanly.

• Loopback-only TCP JSON-lines endpoint for local development clients, sharing the same live image as stdio and limiting concurrent clients.

• Execution-model decision and Phase 1 runtime documentation.

• Lifecycle tests proving failed-message retry from committed state and stop/restart preservation of reserved-first FIFO order.

• NanoID-based public actor references, explicit behavior-and-state spawning, named REPL actor bindings, tab completion, and command history navigation.

• NanoID-based public actor references, explicit behavior-and-state spawning, named REPL actor bindings, tab completion, and command history navigation.

• Runnable Phase 0 experiment pinned to Rune 0.14.2, covering script execution, native calls, async suspension, instruction budgets, frame inspection, stepping, and compiled-code sharing across isolated VMs and threads.

• Tests for feasibility results, invalid source, runtime errors, independent stacks, and cancellation by dropping suspended execution.

• Rune feasibility report with measured timings, shallow object sizes, limitations, and a proposed Phase 1 execution model.

• Initial Rust workspace with the runa binary and a runa-rune library scaffold for Phase 0. Rune integration is not implemented yet.

• Project README and agent guidelines.

• Base directories for architectural decisions, default image scripts, development automation, examples, system tests, and the VS Code extension.

• Mise tasks for formatting, Clippy linting, workspace tests, and sequential pre-commit validation.

• Tombi, rustfmt, and Clippy configurations.

Changed

• Breaking: Protocol v4 spawns by source path (for example actors/counter). Rune handlers are now handle(ctx, state, sender, message) -> state, with sends through the context instead of returned transition tuples.

• Breaking: CLI commit <path> replaces publishing; history and rollback use file paths and generated revision IDs. Source saves, commits, and actor reloads are separate operations.

• Renamed the server executable/crate from runa-server to runa, and the REPL from runa to runa-cli. The server now listens on 127.0.0.1:3737 by default.

• Clap derive/env argument parsing for both executables, including generated help/version, RUNA_LISTEN / RUNA_CONNECT, and flag-over-environment precedence.

• mise run start now starts the server; mise run cli launches the REPL.

• Replaced the plain TCP JSON-lines transport with loopback-only WebSockets using the required runa-debug subprotocol in the server, REPL, and VS Code. Stdio framing and version 3 request/response shapes are unchanged.

• Renamed the local REPL mise task from run to start.

• Protocol v3 and Rune's two-argument handle(state, message) replace the temporary integer-only state and kind/value/target_ref message envelope. Returned sends now contain (actor_reference, message) pairs; migrations, snapshots, and events preserve structured values.

• The REPL now connects to the localhost server rather than embedding its own image. Start the server first; --connect selects a loopback endpoint.

• TCP server startup publishes the bundled counter behavior once; connecting or disconnecting clients does not reset behavior revisions or actor state.

• Interactive CLI commands now use the versioned protocol dispatcher instead of calling the image API directly.

• Protocol version 2 replaces numeric actor IDs with NanoID actor references and adds optional target references for message effects.

• Protocol version 2 replaces numeric actor IDs with NanoID actor references and adds optional target references for message effects.

• Actor implementation IDs now identify compiled source/configuration content rather than using sequential process-local numbers.

• Expanded the architecture specification with crate ownership and dependency boundaries, and moved it to docs/architecture.md.

• Required agents to pass mise run pre-commit before every commit and document user-visible changes in this changelog.

Removed

• Stdio protocol transport and child-process client; external clients now use runa-debug WebSockets exclusively. Removed the serve and serve-network mise tasks.