Luxe 0.1.3: your sessions on your phone, joinable sessions, and nested AGENTS.md

- luxe remote puts the sessions on your computer in reach of your own phone or tablet over
  Tailscale: write, steer, answer prompts, send photos, browse files, diffs and GitHub, with a
  paired device and your own Tailscale login.
- luxe join lets another program on the same machine join a running session over the RPC protocol.
- An AGENTS.md in a subfolder reaches the model the first time it works there.
- Long sessions stay fast: no stall before each model call, lighter memory, cheaper drawing.
- A session is open in one Luxe at a time, web_search shares results across its phrasings, and a
  grep glob starting with ! excludes.

The CHANGELOG has the full list.
This commit is contained in:
Evan Whittaker
2026-10-20 02:40:13 -05:00
parent 99e30d6d0f
commit d2129a886f
423 changed files with 31666 additions and 1669 deletions

288
AGENTS.md
View File

@@ -1,27 +1,27 @@
# AGENTS.md — Luxe
# AGENTS.md
Rules for working in this repository. Each line is something a capable engineer would get wrong
without being told; anything the code already shows is left out, because this file rides in every
request. Process, tooling and the long explanations are in [`CONTRIBUTING.md`](CONTRIBUTING.md).
Rules for working on Luxe: only what you'd get wrong without being told. It's sent with every
request, so keep it short; the long version is [`CONTRIBUTING.md`](CONTRIBUTING.md).
## Commands
```bash
cargo check -p <crate> # the inner loop
cargo nextest run --workspace # ~15s once compiled
cargo check -p <crate> # quick loop
cargo nextest run --workspace # ~15s once built
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all --check
cargo deny check
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps # a broken doc link fails CI
cargo test --workspace --examples # nextest does NOT run these
python3 scripts/size-check.py # file-size ratchet (--report lists)
python3 scripts/fn-length-check.py # function-length ratchet
python3 scripts/voice-check.py # reads source comments too
python3 scripts/docs-check.py # the guide's links, frontmatter, voice
cargo test --workspace --examples # nextest skips these
python3 scripts/size-check.py # file size limit
python3 scripts/fn-length-check.py # function length limit
python3 scripts/voice-check.py # banned words, British spelling
python3 scripts/docs-check.py # guide links, frontmatter, words
python3 scripts/version-check.py <base> # a shipped change bumps one step
scripts/guide-bundle.sh # after editing docs/guide
scripts/site-assets.sh --check # generated web assets are current
scripts/site-fonts.sh --check # webfonts cover those assets
(cd web && npm run cross) # the demos boot in every engine
scripts/site-fonts.sh --check # web fonts cover those assets
(cd web && npm run cross) # site demos run in every browser engine
scripts/win-check.sh [--clippy] # the suite for Windows, under wine
scripts/install-dev.sh # rebuild the release binary on PATH
@@ -29,160 +29,144 @@ cargo run -p luxe-cli -- # the TUI
cargo run -p luxe-cli -- --headless -p "..." # one prompt, no UI
```
Run the whole gate before calling work done, and `scripts/win-check.sh` in **both modes** before
calling anything cross-platform done: CI also lints the Windows target, and a `#[cfg(unix)]` helper
left unused there is a `-D warnings` error the default run cannot see. The voice check reads
**source comments**, so one British spelling in a doc comment fails the build (it checks itself;
do not quote the words it bans). A new glyph that reaches a captured surface needs
`scripts/site-fonts.sh` after `site-assets.sh`, or it ships as tofu.
## Before you call it done
- **Never run two builds or test runs at once.** They thrash and both take longer. Wrap unattended
runs in `timeout <secs>`; never poll with `while pgrep cargo`.
- **A slow run is compiling, not hanging.** `.config/nextest.toml` kills any test over ~120s.
- **`luxe` on `PATH` is `target/release/luxe`, and nothing above builds release.** When a reported
defect contradicts the source, check the binary's date against the fix before re-debugging.
- Run the whole list. For anything cross-platform, run `scripts/win-check.sh` with and without
`--clippy`: CI lints Windows, and an unused `#[cfg(unix)]` helper fails there.
- One build or test run at a time. Wrap unattended runs in `timeout <secs>`; never poll with
`while pgrep cargo`. A slow run is compiling, not stuck: nextest kills tests over ~120s.
- `luxe` on `PATH` is `target/release/luxe`, and only `install-dev.sh` rebuilds it. If a bug report
contradicts the source, check the binary's date first.
- The voice check reads code comments too: one British spelling in a doc comment fails CI.
- A new glyph on a captured screen needs `site-assets.sh`, then `site-fonts.sh`, or it shows as a
box.
## Architecture boundaries
## Architecture
- **Dependencies point inward to `luxe-core`.** Allowed: `providers`, `tools`, `lsp`, `dap`, `mcp`
and `tui` → `core`; `cli` → all of them. Forbidden: `core` → anything in-workspace; `tui` →
`providers`/`tools` (go through core traits).
- **`core` is pure logic and traits: no UI, no HTTP.** No `reqwest`, no `ratatui`. Spawning a
process is fine (git, hooks, formatters, the MCP stdio transport); network I/O lives in
`luxe-providers`, `luxe-tools`' web tools and `luxe-cli`, with any policy (`luxe-core::update`)
kept in core.
- **UI talks to core only over channels.** `Action` in, `Event` out. A UI never calls a provider or
a tool directly and never blocks the runtime.
- **Cross-cutting behavior is a `Hook`**, not a special case threaded through the loop.
- Dependencies point in, to `luxe-core`. `providers`, `tools`, `lsp`, `dap`, `mcp`, `remote` and
`tui` may use `core`; `cli` may use all of them. `core` uses no workspace crate, and `tui` never
uses `providers` or `tools` (go through core traits).
- `core` is logic and traits: no UI, no HTTP, no `reqwest` or `ratatui`. Spawning processes is
fine. Network code lives in `luxe-providers`, `luxe-tools`' web tools, `luxe-remote` and
`luxe-cli`; its policy (like `luxe-core::update`) stays in core.
- A UI talks to core over channels only: `Action` in, `Event` out. It never calls a provider or a
tool and never blocks the runtime.
- Behavior that cuts across the loop is a `Hook`, not a special case in the loop.
- One owner per platform question: `user_dirs` (home and Luxe's folders), `program` (finding
programs and shells, detaching, killing a process tree), `paths` (path to string), `fs_atomic`
(safe file replace), `luxe-lsp::uri` (`file://` URLs).
## Rust conventions
## Rust
- **Modules:** `foo.rs` beside `foo/`, never `foo/mod.rs`, except `luxe-core/tests/common/`, since
each top-level file under `tests/` is its own binary.
- **Errors:** `thiserror` enums in libraries, `anyhow` only in `luxe-cli`. No `unwrap()`/`expect()`
on a fallible path; `expect()` is for real invariants and says why. **Branch on the variant,
never on the message**: a `to_string()` match turns rewording an error into a silent behavior
change. Messages are lowercase with no trailing period.
- **Async:** `tokio`; `spawn_blocking` for blocking work. **Turns must be abortable**: cancellation
drops the future, so anything spawned needs `kill_on_drop` or its own process-group guard.
- **Logging:** `tracing`, structured fields over interpolation, secrets through the redaction
layer. `info` is routine behavior worth reading, `debug` detail you go looking for, `warn` an
oddity the run coped with, `error` a real failure. Don't name the module; `target` does.
- **Size:** at most 500 lines of production code per file (split by responsibility) and 80 lines
per function (4 to 20 for new code). A wide `match` with thin arms is fine; a fat arm is not.
`scripts/size-check.py` and `scripts/fn-length-check.py` are ratchets: an allowlisted entry may
shrink, never grow, and a new one needs a reason a reviewer accepts.
- **Visibility:** `pub` means used from another crate; everything else is `pub(crate)` or
narrower. `unreachable_pub` checks items but not fields, so narrow fields by hand.
- **Tests:** unit tests in-module; an inline test module past 150 lines moves to a sibling
`foo/tests.rs`. Integration tests group into one binary per area (`tests/<area>/main.rs` plus
modules). `core` is fully testable headless: mock providers and temp dirs, no UI, no network. A
test in `examples/` runs only if its `[[example]]` declares `test = true`.
- **A test earns its place by being able to fail.** Watch a regression test fail on the unfixed
code. `scripts/mutants.sh -f <file>` finds the tests that cannot fail; use it on anything
security- or format-critical. A round-trip cannot catch a rename, so a persisted shape is pinned
against a literal copied from real output (a `.luxe/sessions/*.jsonl` line, a real `gh` reply).
- **Every public item has a `///` doc.**
- `foo.rs` next to `foo/`, never `foo/mod.rs` (except `luxe-core/tests/common/`).
- Errors: `thiserror` enums in libraries, `anyhow` only in `luxe-cli`. No `unwrap()` or `expect()`
on anything that can fail; `expect()` is for things that can't, and says why. Match on the error
variant, never its message. Messages are lowercase with no trailing period.
- Turns must be cancelable. Cancel drops the future, so anything spawned needs `kill_on_drop` or
its own process-group guard. Blocking work goes in `spawn_blocking`.
- Logging is `tracing`, with fields instead of formatted strings and secrets through the redaction
layer. `info` is routine, `debug` is detail, `warn` is something odd the run handled, `error` is a
real failure. Don't put the module name in the message.
- New functions are 4 to 20 lines (80 max); files are 500 lines of production code max. The size
scripts are ratchets: an allowlisted entry can shrink, never grow, and a new one needs a reason.
- `pub` means another crate uses it; everything else is `pub(crate)` or narrower. The lint skips
fields, so narrow those by hand.
- Every public item gets a `///` doc.
## Tests
- Unit tests live in the module; past 150 lines they move to a sibling `foo/tests.rs`. Integration
tests are one binary per area: `tests/<area>/main.rs` plus modules.
- `core` tests run headless: mock providers, temp dirs, no UI, no network.
- An example's tests only run if its `[[example]]` sets `test = true`.
- A test has to be able to fail. Watch a regression test fail on the old code first.
`scripts/mutants.sh -f <file>` finds tests that can't fail; use it on security and format code.
- Pin anything saved or sent against a literal copied from real output (a `.luxe/sessions/*.jsonl`
line, a real `gh` reply). A round-trip test can't catch a rename.
## Comments and docs
Lean, casual, senior-dev voice. **Less is more.** Comment the *why*: intent, trade-offs, gotchas,
constraints a reader would not guess. Never restate what the code says; a comment that paraphrases
the next line goes. If a block needs a comment to say *what* it does, extract a named function.
- Comment the why: intent, trade-offs, gotchas. Never restate the code. If a block needs a comment
to say what it does, make it a named function.
- `//!` module docs: `Name — short description.`, a blank line, then how it fits.
- `///` item docs: sentences ending in a period (what, why, edge cases). Variants with a payload get
an `Args:` line. Short field and variant docs are fragments with no period.
- `//` inline: short fragments, no period. Reserved prefixes: `LEARN:`, `NOTE:`, `TODO:`.
- Describe the code as it is: no history, ticket numbers or plan references. That's for the commit.
- No docs that echo the name (`/// Session ID` on `session_id`), no banners, no commented-out code.
- Prose people read follows [`docs/brand/voice.md`](docs/brand/voice.md). How the agent talks lives
in `luxe-core::context`'s base harness, never in a mode or tool description.
- **Module docs (`//!`)**: `Name — short description.`, a blank line, then prose framing the
module in the architecture.
- **Item docs (`///`)**: sentences ending in a period: what, then why, then edge cases.
Payload-carrying variants get an `Args:` line. Label-style field and variant docs are fragments
with no period (`/// Configured accounts`).
- **Inline (`//`)**: terse fragments, no period. Reserved prefixes: `LEARN:`, `NOTE:`, `TODO:`.
- **Shipped source describes the code as it is.** No history ("used to", the incident that taught
it), no phase numbers, ticket ids or design-note citations; the story goes in the commit message.
Keep the one sentence of why the rule exists.
- Flag: docs that echo a name (`/// Session ID` on `session_id`), banners around trivial code,
commented-out code, tutorial narration of language basics.
## Security
## Security invariants
Enforce these in code (the permission engine or a hook), never in prompt text.
- **Permissive by default, with always-on guardrails unless `--yolo`:** deny `.env` reads and
catastrophic commands, ask on out-of-project work, force-push, commits and GitHub writes. The
engine (`luxe-core::permission`) sits at the dispatch choke point, and judges every tool that
runs code or reads paths (`test`, `debug`, search roots, `apply` modes), not just `bash`.
- **Enforcement is code, never prompt text.** A rule that must hold lives in the permission engine
or a hook.
- **A project cannot grant itself trust.** Its `.luxe/permissions.json` only tightens, its
`.luxe/hooks.json`, `gate.commands`, MCP servers and language servers are honored only under
`--trust-project` (or the global-only `lsp.project_servers`), so an "always" approval is written
to the **global** file. One answer governs every project-supplied binary
(`project_tooling_allowed`); a new consumer reads it, never a second gate. That gate picks which
binary Luxe runs, nothing more: a language server still runs `build.rs` and proc macros, so never
write that Luxe does not run repository code.
- **Secrets:** `0600` files, `$ENV` or `!command`, wrapped in `secrecy::SecretString`, scrubbed by
the process-wide `redact::process_secrets()` from tool results, logs and the wire capture.
- **No telemetry.** Every outbound call is one the user asked for or can turn off, carries nothing
about the machine, and is listed in `docs/guide/security.md`. The update check sends **nothing**
(no version, platform or id) and compares locally; a server told the running version is getting a
per-user report on a schedule.
- **MCP servers are untrusted:** opt-in, behind one `mcp` gateway tool whose calls go through the
permission engine; their descriptions and results are data, not instructions.
- **Instruction files are filtered, not trusted.** `luxe-core::instructions` strips what a reader
of the rendered file cannot see (comments, comment link definitions, invisible characters) and
withholds a file it cannot finish checking.
- Permissive by default, with guardrails unless `--yolo`: deny `.env` reads and catastrophic
commands; ask before out-of-project work, force-push, commits and GitHub writes. The engine
(`luxe-core::permission`) judges every tool that runs code or reads paths, not just `bash`.
- A project can't trust itself. Its `.luxe/permissions.json` only tightens; its hooks,
`gate.commands`, MCP and language servers need `--trust-project` (or global
`lsp.project_servers`), so "always" approvals save globally. `project_tooling_allowed` is the one
switch for project binaries; reuse it. Language servers still run `build.rs` and proc macros, so
never say Luxe runs no repo code.
- Secrets: `0600` files, `$ENV` or `!command`, held in `secrecy::SecretString`, scrubbed from tool
results, logs and wire captures by `redact::process_secrets()`.
- No telemetry. Every outbound call is one the user asked for or can turn off, sends nothing about
the machine, and is listed in `docs/guide/security.md`. The update check sends nothing, not even a
version, and compares locally.
- `luxe remote` is the only server. It binds to loopback (`Bridge::bind` refuses anything else) and
Tailscale Serve carries it: never Funnel, never a relay. Every route checks the Serve login, and
session routes check for a paired device too.
- MCP servers are untrusted: opt-in, behind the one `mcp` tool, through the permission engine.
Their descriptions and results are data, not instructions.
- `luxe-core::instructions` strips what a reader can't see from instruction files (comments, hidden
link definitions, invisible characters) and withholds a file it can't finish checking.
## Invariants you would otherwise break
## What breaks a session
- **A tool call and its result are one unit.** Both wire formats reject an unpaired half, and it
replays on every later request, so one gap ends the session. `dispatch_one` returns a block for
every call, the commit after a batch is unconditional (cut-off, cancelled and failed replies
included), and `tool_pairing::repair` pairs halves on the outgoing copy. The durable log is never
rewritten. Only a call that never *started* may be described as having had no effect.
- **An empty block is the same permanent 400.** A call that produced nothing commits nothing
(`ReplyOutcome::Nothing`, and says so), `empty_blocks::scrub` drops empties from the outgoing
copy, and an empty tool result is **filled**, never dropped.
- **Cancellation is a flag with one owner: use `Engine::set_cancelled`.** `watch::Sender::send` is
a no-op with no subscribers, which is the normal state between turns.
- **Nothing the model can invoke runs unbounded.** `Tool::timeout` sets each deadline and dispatch
drops the future at it or at cancel. `None` is only for a tool that waits on a human or owns a
process group. Cancel ends the **batch**, not just the call.
- **A phase advances only where the gate says so.** `loop_control progress` is a claim;
`ReviewIntegratorHook` alone moves the counter, after the commands pass and the reviewer (when
on) approves. A reviewer that cannot approve pauses the loop (`GateOutcome::Held`). A refusal
reaches the model as the tool's own result.
- **Context occupancy is a measurement.** Read it from the last `EntryKind::Usage` after the newest
compaction; `estimate_tokens` is the fallback and counts **every** block kind.
- **A request's transcript is an *append* to the last one's.** Providers cache an exact prefix, so
editing history in flight re-bills everything after the edit at the write rate. Pruning is gated
on real window pressure and cuts in whole `prune_min_tokens` steps. Watch the **written** share on
`/cost` and in `luxe wire`, not the hit rate.
- **The system prompt is byte-identical between turns of a session.** No volatile fact enters it;
one-time context is **appended**. Reason about what reaches the model from a capture
(`LUXE_WIRE_LOG` plus `luxe wire`), not from source.
- **`Action` and `Event` are a published protocol.** `luxe --rpc` streams them to clients nobody
here compiles, and an unknown tag degrades to `Other`, so a rename breaks every client and no
compiler notices. Adding is free; removing or retagging moves `PROTOCOL_VERSION`. Pinned literals
in `tests/event_serialization.rs` hold it.
- **`AGENTS.md` is the only project document in the prompt.** Anything else is pointed at.
- **A tool must beat the shell command it replaces** (bounded output, fewer round trips, correct
defaults, or a capability the shell lacks), and its description names the sibling for the
adjacent question.
- **Glyphs are polish, never meaning.** Every icon sits beside the words it labels; prefer block
- **A tool call and its result are a pair.** Providers reject half a pair on every later request,
so one gap ends the session. `dispatch_one` returns a result for every call, a batch always
commits (cut off, cancelled or failed too), and `tool_pairing::repair` fixes the outgoing copy.
Never rewrite the saved log. Only a call that never started had no effect.
- **An empty block is the same permanent 400.** An empty reply commits nothing
(`ReplyOutcome::Nothing`), `empty_blocks::scrub` drops empties from the outgoing copy, and an
empty tool result is filled, never dropped.
- **Cancel with `Engine::set_cancelled`.** `watch::Sender::send` does nothing without subscribers,
which is normal between turns.
- **Nothing the model runs is unbounded.** `Tool::timeout` sets each deadline; dispatch drops the
future at it or on cancel. `None` is only for a tool that waits on a person or owns a process
group. Cancel ends the whole batch.
- **Only the gate moves a phase.** `loop_control progress` is a claim; `ReviewIntegratorHook` moves
the counter once the commands pass and the reviewer (if on) approves, and pauses the loop
(`GateOutcome::Held`) if it can't. A refusal reaches the model as the tool's result.
- **Context use is measured.** Read it from the last `EntryKind::Usage` after the newest
compaction. `estimate_tokens` is the fallback and counts every block kind.
- **Each request appends to the last.** Providers cache an exact prefix, so editing history
re-bills everything after the edit. Pruning waits for real window pressure and cuts in whole
`prune_min_tokens` steps. Watch the written share on `/cost` and in `luxe wire`, not the hit rate.
- **The system prompt never changes mid-session.** Nothing volatile goes in it; one-time context is
appended. Judge what reaches the model from a capture (`LUXE_WIRE_LOG` plus `luxe wire`).
- **`Action` and `Event` are a public protocol.** `luxe --rpc` streams them to clients built
elsewhere, and an unknown tag becomes `Other`, so a rename breaks them silently. Adding is free;
removing or renaming bumps `PROTOCOL_VERSION`. `tests/event_serialization.rs` pins the literals.
## Product rules
- `AGENTS.md` is the only project document in the prompt. Point at anything else.
- A tool must beat the shell command it replaces (bounded output, fewer round trips, better
defaults, or something the shell can't do), and its description names the sibling tool for the
next question.
- Glyphs decorate; they never carry meaning alone. Every icon sits beside its words. Prefer block
elements, which every terminal draws.
- **Platform questions have one owner each:** `user_dirs` (home and Luxe's directories), `program`
(finding programs, shells, detaching, killing a process tree), `paths` (path to string),
`fs_atomic` (durable replace), `luxe-lsp::uri` (`file://` URLs).
- **Generated assets are generated; captures are recorded.** `web/src/assets/generated/` comes from
the Rust source and CI checks it. `web/src/assets/captures/` are real sessions recorded by
`scripts/site-record.sh`, which nothing can verify; change how Luxe looks and you owe both a
`site-assets.sh` and a re-record.
- **The wordmark constants are the art** (`luxe-tui/src/widgets/wordmark/art.rs`): one drawing, no
- `web/src/assets/generated/` comes from Rust and CI checks it; `captures/` are real sessions from
`scripts/site-record.sh`. Change how Luxe looks and you owe a `site-assets.sh` run and a
re-record.
- The wordmark constants in `luxe-tui/src/widgets/wordmark/art.rs` are the logo: one drawing, no
alternatives.
- **Two voices, two homes.** Prose a person reads follows `docs/brand/voice.md`; how the agent
writes lives in `luxe-core::context`'s base harness, never in a mode or a tool description.
## Where things live
- `CONTRIBUTING.md`: process, tooling, publishing. `docs/guide/`: the user guide, also embedded in
the binary for `luxe docs`.
- `.luxe/todos/<session-id>.json`: the `todo` tool's checklist, one file per session.
- A development checkout also has `PROJECT.md` (what must stay true; read it when a design call is
ambiguous), `ROADMAP.md`, `PROGRESS.md`, `PLAN.md` and design notes, all excluded from releases.
- `CONTRIBUTING.md`: process, tooling, publishing. `docs/guide/`: the user guide, also in
`luxe docs`. `.luxe/todos/<session-id>.json`: the `todo` checklist.
- A dev checkout also has `PROJECT.md` (what must stay true; read it when a design call is
unclear), `ROADMAP.md`, `PROGRESS.md`, `PLAN.md` and design notes. None of them ship.