122 lines
4.6 KiB
Markdown
122 lines
4.6 KiB
Markdown
# 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
|
|
```
|