161 lines
6.3 KiB
Markdown
161 lines
6.3 KiB
Markdown
# 9P Operational Model
|
|
|
|
Your world model is a 9P filesystem mounted at ${OLLIE}. Your session ID is `${OLLIE_SESSION_ID}`. Always prefer the 9P filesystem over D-Bus.
|
|
|
|
## Root Namespace (`${OLLIE}/`)
|
|
|
|
| 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) |
|
|
| `s/` | 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. Open one r/w, write a query, then read the response from the same fd:
|
|
|
|
```bash
|
|
# Pick a backend+model for a task
|
|
exec 3<>$OLLIE/route; echo 'implement login page' >&3; cat <&3; exec 3>&-
|
|
# → returns "backend=anthropic model=claude-sonnet-4-20250514"
|
|
|
|
# Generate text (one-shot, no session)
|
|
exec 3<>$OLLIE/generate; echo '{"prompt":"summarize X"}' >&3; cat <&3; exec 3>&-
|
|
# → returns the generated text
|
|
|
|
# Get a code completion
|
|
exec 3<>$OLLIE/complete; echo '{"file":"main.go","prefix":"func "}' >&3; cat <&3; exec 3>&-
|
|
# → returns completion candidates
|
|
```
|
|
|
|
## Peer Agent Discovery
|
|
|
|
Sessions sharing your `cwd` are your peer agents. Read `${OLLIE}/s/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: `echo "your prompt" > ${OLLIE}/s/{id}/prompt`. Always provide a return path (e.g., [message from $OLLIE_SESSION_ID]).
|
|
|
|
## Session Management (`${OLLIE}/s/`)
|
|
|
|
Sessions live at `${OLLIE}/s/`. Each session is a directory; all operations are filesystem reads and writes.
|
|
|
|
### Session Store Files
|
|
|
|
| File | Mode | Purpose |
|
|
|---|---|---|
|
|
| `${OLLIE}/s/new` | r/w | Read: key=value template. Write: create a new session. |
|
|
| `${OLLIE}/s/idx` | read | Session index (id\tstate\tcwd\tbackend\tmodel) |
|
|
| `${OLLIE}/s/ls` | exec | List sessions |
|
|
| `${OLLIE}/s/kill` | exec | Kill a session |
|
|
| `${OLLIE}/s/sh` | exec | Interactive shell |
|
|
| `${OLLIE}/s/b` | exec | Batch session |
|
|
| `${OLLIE}/s/bfg` | exec | Foreground query |
|
|
| `${OLLIE}/s/bbg` | exec | Background query |
|
|
| `${OLLIE}/s/cleanup` | exec | Kill idle sessions |
|
|
|
|
## Tool Registry
|
|
|
|
Tools are scripts in `~/.config/ollie/tools/`. All tools are always discoverable; only loaded tools are callable.
|
|
|
|
- **Discover** — `tool_list` lists all available tools with descriptions.
|
|
- **Load** — `tool_load {"name": "toolname"}` promotes it to a native callable function.
|
|
- **Check** — `tool_active` lists tools currently loaded (promoted) in your session.
|
|
|
|
Once loaded, a tool becomes a first-class function. Call it directly by name with JSON arguments matching its schema — no wrapper, no multiplexer.
|
|
|
|
### Session Directory (`${OLLIE}/s/{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
|
|
cat $OLLIE/s/idx
|
|
|
|
# Discover sessions in same cwd
|
|
grep "$PWD" $OLLIE/s/idx
|
|
|
|
# Spawn a session (minimal, generated ID)
|
|
echo "cwd=$PWD" > $OLLIE/s/new
|
|
|
|
# Spawn a session (named)
|
|
printf 'name=reviewer\ncwd=%s\n' "$PWD" > $OLLIE/s/new
|
|
|
|
# Kill a session
|
|
rm -r $OLLIE/s/{id}
|
|
|
|
# Rename a session
|
|
echo "rn newname" > $OLLIE/s/{id}/ctl
|
|
|
|
# Send a prompt
|
|
echo "your prompt here" > $OLLIE/s/{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/s/{id}/ctl
|
|
|
|
# Read session config (backend, model, agent, cwd, params)
|
|
cat $OLLIE/s/{id}/cfg
|
|
|
|
# Write config changes
|
|
echo "temperature=0.7" > $OLLIE/s/{id}/cfg
|
|
|
|
# Read most recent response
|
|
offset=$(cat $OLLIE/s/{id}/offset)
|
|
tail -c +$((offset + 1)) $OLLIE/s/{id}/chat
|
|
|
|
# Read current state
|
|
cat $OLLIE/s/{id}/state
|
|
|
|
# Discover available models
|
|
cat $OLLIE/s/{id}/models
|
|
|
|
# Add a peer link (bidirectional)
|
|
touch $OLLIE/s/{id}/peer/{peerid}
|
|
|
|
# Send a prompt to a peer
|
|
echo "your message" > $OLLIE/s/{id}/peer/{peerid}
|
|
|
|
# Remove a peer link (bidirectional)
|
|
rm $OLLIE/s/{id}/peer/{peerid}
|
|
```
|