# Changelog All notable changes to this project will be documented in this file. ## [Unreleased] ### Added - Add `runa-dap --listen` / `RUNA_DAP_LISTEN` for loopback TCP DAP sessions, retaining stdio as the default transport. - Add `mise run install-extension` to build the debug adapter, package the VS Code extension, and install it locally using `code` (or `VSCODE_CLI`). - Add a standalone Rust `runa-dap` stdio debug adapter for VS Code actor debugging. - Expose `behavior.rn` for every actor in the graphical and VS Code trees, with actor-specific gutter breakpoints and source diagnostics. - 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 a non-destructive, cursor-based event-history view. - Add committed source history browsing, revision preview, and confirmed rollback to the graphical source editor. - Add actor-local temporary behavior editing and guarded shared-source updates to the graphical actor inspector. ### Changed - Replace the graphical client's behavior dropdowns with a left-hand source file tree and a right-hand actor tree with metadata, state, mailbox, log, and behavior entries. - 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 ` / `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/`, 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 ` 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.