# LLM Room Protocol

Rooms are the bounded live-execution primitive in Abbotik.

They are tenant-scoped, authenticated, and exposed as part of the `/llm/*`
execution namespace. The API still owns the public root, docs, and `llms.txt`
entrypoints; room execution is an LLM protocol layered on top of tenant data.

## Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/llm/room` | List visible rooms |
| POST | `/llm/room` | Rent a new room |
| GET | `/llm/room/:id` | Fetch one room |
| PATCH | `/llm/room/:id` | Update mutable room configuration |
| POST | `/llm/room/:id/messages` | Inject one semantic room message |
| POST | `/llm/room/:id/wake` | Wake a room explicitly |
| GET | `/llm/room/:id/events` | Replay or follow room events as SSE |
| GET | `/llm/room/:id/history` | Read durable room history |
| POST | `/llm/room/:id/interrupt` | Interrupt an in-flight turn |
| POST | `/llm/room/:id/release` | Release a room explicitly |

## Model

A room is a rentable, tenant-scoped, bounded execution context for live LLM
work.

Current responsibilities:

- room identity and tenancy
- actor roster
- room-local tool, wake, and done policy
- bounded worker lifecycle
- message history
- event history
- explicit wake, interrupt, and release verbs

Current practical limits:

- one worker per active room
- one queued message at a time per room
- deterministic event ordering within a room
- one bounded actor turn per queued message

Observed room lifecycle states:

- `rented`
- `active`
- `idle`
- `sleeping`
- `releasing`
- `released`
- `failed`

Important runtime guards:

- released rooms reject new messages and wake requests
- interrupt only succeeds while a turn is actively running
- executor failures persist `room.last_error` and emit durable `error` events
- `GET /llm/room/:id/events` replays durable history first and only tails live
  events while the in-memory worker is still attached

## Storage

In the API service, room state is stored durably in tenant-local `rooms`,
`room_messages`, and `room_events` models through direct `Database.*` calls
inside the same process.

There is no loopback HTTP bridge between the LLM runtime and the data layer.

## Factory Boundary

Rooms are the execution primitive.

Factory orchestration is now the sibling `/llm/factory` route family in this
service. Use rooms for bounded live turns, and use factory when the work needs
durable planning, issue tracking, verification, and review state across a run.