lean-beam: Instructions file for Codex

AGENTS.md

Purpose

This repository hosts the pre-stable Beam Lean plugin, wrapper, and local broker tooling.

Treat the repo as public but still experimental: prefer conservative, well-tested changes over feature sprawl.

Current public status and limitations live in docs/STATUS.md. Compatibility policy lives in docs/COMPATIBILITY.md. User setup lives in docs/SETUP.md. Exact MCP behavior lives in docs/MCP.md, and exact sync/save/diagnostic behavior lives in docs/SYNC_AND_DIAGNOSTICS.md.

Product Priorities

In order:

1. dead-simple public API
2. rock-solid stability
3. type-safe boundaries
4. isolation of each request
5. performance

Performance matters, but not at the cost of correctness or stability.

Public API Guardrails

The core public request should remain conceptually:

• runAt(pos, "lean text")

Rules:

• no required public mode flag for command vs tactic execution
• backend selection is internal
• keep request and response structures small and typed
• use transport errors for invalid params, stale state, cancellation, and internal faults
• avoid exposing internal execution details unless a concrete client need forces it

Follow-up handle APIs exist, but they are pre-stable extensions around the basic request, not the main story of the project.

Execution Model

Each request should behave like an isolated sandbox:

• never mutate the document's real elaboration state
• never depend on side effects from a previous request
• never leak internal mutable state through the base API
• discard derived execution state unless the request explicitly stores a follow-up handle

Cancellation Policy

Request cancellation is currently soft (cooperative) across Beam. Observe it at safe boundaries; do not promise immediate interruption, rollback, or a universal completion deadline. An active effect may need to settle before the request releases its resources or reports cancellation.