# 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
# Pick a backend+model for a task
echo 'implement login page' | ollie-9p rdwr route
# → returns "backend=anthropic model=claude-sonnet-4-20250514"

# Generate text (one-shot, no session)
echo '{"prompt":"summarize X"}' | ollie-9p rdwr generate
# → returns the generated text

# Get a code completion
echo '{"file":"main.go","prefix":"func "}' | ollie-9p rdwr complete
# → returns completion candidates
```

## Peer Agent Discovery

Sessions sharing your `cwd` are your peer agents. Read `session/idx` to discover other sessions available for cooperation:

```
{id}\t{state}\t{cwd}\t{backend}\t{model}
```

**Inter-Agent Communication**: To send a prompt to another session:
```bash
echo "your prompt" | ollie-9p write session/{id}/prompt
```
Always provide a return path (e.g., [message from $OLLIE_SESSION_ID]).

## Session Management (`session/`)

Sessions live at `session/`. Each session is a directory; all operations go through `ollie-9p`.

### Session Store Files

| File | Mode | Purpose |
|---|---|---|
| `session/new`      | r/w  | Read: key=value template. Write: 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/{id}/`)

| File | Mode | Purpose |
|---|---|---|
| `cfg`         | r/w   | Session config: backend, model, agent, cwd, params (key=value). Write key=value to change. |
| `chat`        | read  | Full cumulative chat history (tail-able); write to save transcript |
| `context`     | read  | Rendered context window |
| `cost`        | read  | Estimated cost |
| `ctl`         | write | Control commands (see below) |
| `ctxsz`       | read  | Context size |
| `env`         | read  | Session environment variables |
| `fifo.in`     | write | Queue a prompt (FIFO input) |
| `fifo.out`    | read  | Pop queued prompt (FIFO output) |
| `models`      | read  | Available models for current backend |
| `offset`      | read  | Byte offset after last user prompt |
| `peer/`       | dir   | Peer links. `touch` to add, `rm` to remove (both sides updated). Write to send prompt to peer. |
| `plan`        | r/w   | Session-scoped markdown checklist; survives compaction; visible to peers |
| `proc/`       | dir   | Detached background processes |
| `prompt`      | write | Submit a prompt to the agent |
| `prompt.prev` | read  | Previous prompt text |
| `state`       | read  | Current state: `idle`, `thinking`, or `calling: <tool>` |
| `statewait`   | read  | Blocks until state changes; returns new value |
| `systemprompt` | read | Fully rendered system prompt |
| `tail`        | exec  | Tail helper |
| `tools`       | r/w   | Write tool name to load it (promote to native callable). Read: list all available tools. |
| `tools.loaded`| read  | List currently loaded (promoted) tools for this session |
| `tools.rev`   | read  | Revision counter — bumps each time a tool is loaded |
| `usage`       | read  | Token usage stats |

## Operations

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

# Discover sessions in same cwd
ollie-9p read session/idx | grep "$PWD"

# Spawn a session (minimal, generated ID)
echo "cwd=$PWD" | ollie-9p write session/new

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

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

# Rename a session
echo "rn newname" | ollie-9p write session/{id}/ctl

# Send a prompt
echo "your prompt here" | ollie-9p write session/{id}/prompt

# Control commands via ctl:
#   stop          — interrupt the current agent turn
#   kill          — terminate the session
#   rn <newname>  — rename the session
#   compact       — compact the conversation history
#   clear         — clear the conversation history
#   cwd <path>    — change the working directory
#   model <name>  — switch model
#   backend <name> — switch backend
echo "model gpt-4o" | ollie-9p write session/{id}/ctl

# Read session config (backend, model, agent, cwd, params)
ollie-9p read session/{id}/cfg

# Write config changes
echo "temperature=0.7" | ollie-9p write session/{id}/cfg

# Read most recent response
offset=$(ollie-9p read session/{id}/offset)
ollie-9p read session/{id}/chat | tail -c +$((offset + 1))

# Read current state
ollie-9p read session/{id}/state

# Discover available models
ollie-9p read session/{id}/models

# Add a peer link (bidirectional)
ollie-9p create session/{id}/peer/{peerid}

# Send a prompt to a peer
echo "your message" | ollie-9p write session/{id}/peer/{peerid}

# Remove a peer link (bidirectional)
ollie-9p rm session/{id}/peer/{peerid}
```