# Lantern Systems — lantern-agent repo contract

`harnessd` — a Rust daemon that drives browsers with an LLM agent loop, for
your LAN (Tailscale or plain). Server-side sessions, strict tool-call JSON,
live event stream, screenshots, traces. Nothing cloud-hosted.

```
Cargo.toml          the workspace contract (deps are versioned; changes are PRs)
src/main.rs         axum routes = the API contract (route names are law)
src/browser.rs      the Browser trait — everything sits behind it
src/mock.rs         scripted mock browser (hermetic tests; QA owns fixtures)
src/agent.rs        LLM loop: prompt → strict tool-call JSON → dispatch → repeat
src/events.rs       session event vocabulary (SSE + JSONL audit log)
src/trace.rs        per-step traces (T6): prompt excerpt, tool call, result
tests/contract.rs   end-to-end contract tests against the mock
judge.sh            build gate: cargo build + cargo test + /healthz smoke
docs/               deployment (Tailscale!), quickstart, API examples
```

## Day-1 state (seed)

Compiles, /healthz answers on 0.0.0.0:7777, mock browser navigates/scripted
fixtures, agent loop is a stub — the backlog is the delta. `judge.sh` maps
FAILs to owner files; the build gate mails them.

## House rules

1. If it doesn't compile `cargo check` clean, it's not committed. `cargo check` runs the instant a commit lands and errors show up in `check_report.md` — fix your own files in the same session, don't wait for the nightly gate.
2. If the full gate (`sh judge.sh`) is red on main, it doesn't exist. Every commit builds.
2. Failures are enum variants; no stringly-typed errors.
3. The route table in src/main.rs is the contract — renaming one without
   a route-table change + test change is an incident.
4. Tests run against the mock. A demo is not evidence.
5. LLM endpoints in configs point at LAN hosts only (team llama.cpp box or
   the sim's own model). Any default that names the cloud is a review bounce.
6. If you can't run it, run `pixi run`? — no: this is Rust. `cargo test`
   is the bar. (Yes we know pixi is for the python company.)

## Boss usage

    cd work/project && cargo run            # serve 0.0.0.0:7777
    curl -s localhost:7777/healthz          # from any LAN/tailnet node
    sh work/project/judge.sh                # or type `judge` in the sim console