156 lines
5.8 KiB
Markdown
156 lines
5.8 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
|
|
# 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 remove 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 remove session/{id}/peer/{peerid}
|
|
```
|