runa/AGENTS.md

Project Guidelines

Project overview

Runa (short for Rune Actors) is an experimental Rust project whose long-term goal is a persistent, live programming world built around isolated Rune actors. The current workspace contains Rune 0.14.2 feasibility experiments and a minimal single-worker actor runtime. Verified capabilities and unresolved limitations are in docs/rune-feasibility.md and docs/runtime.md.

The architecture, design goals, constraints, and implementation roadmap are documented in docs/architecture.md. Treat proposed capabilities as plans, not existing behavior.

Agent rules

• Remove placeholders that do not apply. For project details you cannot determine reliably, ask the user rather than guessing; if they are unavailable, leave the placeholders clearly marked.
• Never push changes unless explicitly told to.
• After changing files, run the project's formatter using its configured settings. Do not override project formatting configuration or invoke a formatter directly on individual files unless project guidance says to.
• Use conventional commits with the types used by this project. Use ! and a BREAKING CHANGE: footer for breaking API or behavior changes.
• End commit messages with a co-author trailer appropriate to the agent and product. For example: Co-Authored-By: <AGENT_NAME> <AGENT_EMAIL>.
• Inform the user about commits and other Git changes, including commit messages.
• Commit changes after each step unless the user says not to or a project no-commit marker such as .NOCOMMIT exists in the repository root.
  • Changes affecting compilation or tests may only be committed after the relevant build, lint, and test checks pass.
  • Documentation, CI, editor, and deployment configuration changes may not require code checks; follow the project's validation requirements.
  • Check the current branch before every commit.
• Commit formatting-only changes separately when formatting reformats code unrelated to the functional changes.
• Add user-visible changes to the project's Unreleased changelog section using its established format, creating that section if needed.

Architecture and constraints

• Keep actor identity, mailbox, private state, behavior implementation, and incarnation distinct as runtime work begins.
• Use message passing for normal actor interaction; do not introduce shared mutable actor state.
• Keep behavior implementations immutable and install updates at safe boundaries. Do not mutate active execution frames in place.
• Start with the Rune feasibility work in Phase 0. Verify APIs and capabilities against the actual Rune version before relying on them; do not claim interruption, preemption, durability, or delivery guarantees without tests.
• Build only the smallest workspace structure needed for the current milestone; the crate layout in the spec is proposed, not a requirement to create empty crates.

Repository structure

• Cargo.toml: Rust workspace definition.
• crates/runa/: current executable crate and entry point.
• crates/runa-core/: stable identity types shared across layers.
• crates/runa-rune/: Phase 0 Rune compilation and execution experiments.
• crates/runa-code/: source identities and in-memory Rune compile cache.
• crates/runa-actor/: actor value and lifecycle contracts.
• crates/runa-runtime/: single-worker scheduling and in-memory transitions.
• crates/runa-image-api/: trusted in-process services for operating on an image.
• crates/runa-protocol/: versioned transport-neutral request, response, and event DTOs.
• crates/runa-server/: protocol dispatch, JSON-lines stdio, and loopback WebSockets.
• crates/runa-client/: stdio child-process and runa-debug WebSocket clients.
• runa-std/actors/: default Rune actor scripts loaded by the local CLI.
• docs/architecture.md: architecture, roadmap, risks, and acceptance scenario.
• docs/decisions/: architectural decisions.
• runa-std/: default Rune scripts for an image.
• scripts/: general-purpose development automation.
• tests/: system and end-to-end tests; require an explicit runner rather than assuming Cargo discovers tests at a virtual workspace root.
• examples/: reserved for examples.
• vscode/: TypeScript localhost inspection client and extension tests.
• README.md: project overview and current getting-started instructions.

Commands

Run these from the repository root:

mise run format
mise run lint
mise run test
mise run start
mise run serve
mise run test-extension-host
mise run pre-commit

mise run pre-commit runs format, lint, and test sequentially, stopping on failure. Formatting uses the repository's Tombi, rustfmt, and extension Prettier configurations. Clippy checks all workspace targets and treats warnings as errors. Extension checks use strict TypeScript and Prettier. Node.js 22+ and npm are required; install the locked extension dependencies with npm --prefix vscode ci.

The workspace tests cover execution probes, actor runtime invariants, and the interactive CLI. Extension tests include a real Rust-server WebSocket round trip. mise run start opens the local CLI. The separate mise run test-extension-host task verifies inspector commands in VS Code and requires a display (or xvfb-run -a mise run test-extension-host on headless Linux).

Conventions

• Keep changes focused and follow existing Rust formatting and workspace conventions.
• Prefer verified Rune APIs and explicit runtime guarantees over assumptions.
• Keep the README and architecture spec aligned with implemented behavior; label planned capabilities as planned.
• Do not push changes unless explicitly asked.
• Check the current branch before committing. Use conventional commit messages and include the repository's configured Copilot co-author trailer.
• Add user-visible changes to the project's Unreleased changelog section using its established format before you commit something, creating that section if needed.
• Before every commit, including documentation-only commits, run mise run pre-commit and require a successful exit. Fix all reported formatting, lint, and test problems, then rerun the task until it passes. Do not bypass checks or suppress diagnostics merely to make a commit pass.
• Review and stage formatter changes before committing. If further changes are made after validation, rerun mise run pre-commit before committing.