# 9P Operational Model

Your world model is a 9P filesystem. Your session ID is `${OLLIE_SESSION_ID}`. Use `ollie-9p` for all filesystem operations.

## Root Namespace

| File | Mode | Purpose |
|---|---|---|
| `agents`    | read   | Available agent names, one per line |
| `backends`  | read   | Available backend names, one per line |
| `models`    | read   | Available models (backend\tmodel per line) |
| `help`      | read   | Help text |
| `ctl`       | write  | Server control commands (e.g. `invalidate` to refresh model cache) |
| `session/`  | dir    | Sessions (see below) |
| `complete`  | r/w    | Write: JSON `{"file","prefix","suffix"}`. Read: code completion result. |
| `generate`  | r/w    | Write: JSON `{"prompt"}` or plain text. Read: one-shot LLM generation result. |
| `route`     | r/w    | Write: task description. Read: `backend=X model=Y` recommendation. |

`complete`, `generate`, and `route` are request-response files:

```bash
echo 'implement login page' | ollie-9p rdwr route
echo '{"prompt":"summarize X"}' | ollie-9p rdwr generate
echo '{"file":"main.go","prefix":"func "}' | ollie-9p rdwr complete
```

## Session Management (`session/`)

| File | Mode | Purpose |
|---|---|---|
| `session/new`      | r/w  | Write key=value to create a new session |
| `session/idx`      | read | Session index (id\tstate\tcwd\tbackend\tmodel) |
| `session/ls`       | exec | List sessions |
| `session/kill`     | exec | Kill a session |
| `session/sh`       | exec | Interactive shell |
| `session/b`        | exec | Batch session |
| `session/bfg`      | exec | Foreground query |
| `session/bbg`      | exec | Background query |
| `session/cleanup`  | exec | Kill idle sessions |

## Session Directory (`session/{sid}/`)

| File | Mode | Purpose |
|---|---|---|
| `plan`        | r/w   | Session-scoped markdown checklist; survives compaction |
| `env`         | read  | Session environment variables |
| `agent/`      | dir   | Agents within this session |

## Agent Directory (`session/{sid}/agent/{aid}/`)

Each agent has its own directory. The `{aid}` is the agent's numeric ID (stable, used for permissions).

| File | Mode | Purpose |
|---|---|---|
| `prompt`      | write | Submit a prompt to this agent |
| `prompt.prev` | read  | Previous prompt text |
| `fifo.in`     | write | Queue a prompt (FIFO input) |
| `fifo.out`    | read  | Pop queued prompt (FIFO output) |
| `chat`        | read  | Agent conversation history (tail-able) |
| `offset`      | read  | Byte offset after last user prompt |
| `state`       | read  | Current state: `idle`, `thinking`, or `calling: <tool>` |
| `statewait`   | read  | Blocks until state changes; returns new value |
| `cfg`         | r/w   | Agent config: backend, model, cwd, params (key=value) |
| `ctl`         | write | Control: stop, compact, clear, model, backend, cwd |
| `usage`       | read  | Token usage stats |
| `cost`        | read  | Estimated cost |
| `ctxsz`       | read  | Context size |
| `models`      | read  | Available models for current backend |
| `systemprompt` | read | Fully rendered system prompt |
| `context`     | read  | Rendered context window |
| `tools`       | r/w   | Write tool name to load. Read: list all available tools |
| `tools.loaded`| read  | Currently loaded tools |
| `tools.rev`   | read  | Revision counter — bumps each time a tool is loaded |
| `react`       | write | Send a reaction to the last response |
| `reactions`   | read  | Reaction history |
| `tail`        | exec  | Tail helper |
| `proc/`       | dir   | Detached background processes |

## Operations

```bash
# Discover sessions
ollie-9p read session/idx

# Spawn a session
echo "cwd=$PWD" | ollie-9p write session/new
printf 'name=reviewer\ncwd=%s\n' "$PWD" | ollie-9p write session/new

# Kill a session
ollie-9p rm session/{sid}

# Read session plan
ollie-9p read session/{sid}/plan

# --- Agent operations (from within session/{sid}/agent/{aid}/) ---

# Send a prompt
echo "fix the bug" | ollie-9p write session/{sid}/agent/{aid}/prompt

# Read state
ollie-9p read session/{sid}/agent/{aid}/state

# Read chat
ollie-9p read session/{sid}/agent/{aid}/chat

# Control commands
echo "stop" | ollie-9p write session/{sid}/agent/{aid}/ctl
echo "model gpt-4o" | ollie-9p write session/{sid}/agent/{aid}/ctl
echo "compact" | ollie-9p write session/{sid}/agent/{aid}/ctl

# Read/write config
ollie-9p read session/{sid}/agent/{aid}/cfg
echo "temperature=0.7" | ollie-9p write session/{sid}/agent/{aid}/cfg

# Read latest response
offset=$(ollie-9p read session/{sid}/agent/{aid}/offset)
ollie-9p read session/{sid}/agent/{aid}/chat | tail -c +$((offset + 1))

# Load a tool
echo "file_read" | ollie-9p write session/{sid}/agent/{aid}/tools
```