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](docs/rune-feasibility.md) and
[docs/runtime.md](docs/runtime.md).

The architecture, design goals, constraints, and implementation roadmap are
documented in [docs/architecture.md](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 and local JSON-lines stdio transport.
- `crates/runa-client/`: local child-process client for the JSON-lines protocol.
- `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:

```sh
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 TCP 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.