129 lines
3.6 KiB
Markdown
129 lines
3.6 KiB
Markdown
## 9P Filesystem: Everything is a File
|
|
|
|
The 9P namespace is the lowest-level interface to ollie. Everything — sessions,
|
|
agents, prompts, tools, state — is a file. The `o` CLI wraps these operations,
|
|
but the raw filesystem is the foundation.
|
|
|
|
### Mounting
|
|
|
|
```sh
|
|
ollie-9p mount unix!/tmp/ns.$USER.$DISPLAY/ollie ~/mnt/ollie
|
|
cd ~/mnt/ollie
|
|
ls session/
|
|
```
|
|
|
|
Or connect remotely:
|
|
|
|
```sh
|
|
ollie-9p mount tcp!server:9564 ~/mnt/ollie
|
|
```
|
|
|
|
### Raw session operations
|
|
|
|
```sh
|
|
# Create a session
|
|
echo "name={sname}" > session/new
|
|
|
|
# Submit a prompt
|
|
echo "fix the bug in main.go" > session/{sname}/agent/{aname}/prompt
|
|
|
|
# Stream the response
|
|
cat session/{sname}/agent/{aname}/chat
|
|
|
|
# Check state
|
|
cat session/{sname}/agent/{aname}/state
|
|
|
|
# Block until state changes
|
|
cat session/{sname}/agent/{aname}/statewait
|
|
|
|
# Read offset (byte position after user prompt)
|
|
cat session/{sname}/agent/{aname}/offset
|
|
```
|
|
|
|
### Network transparency
|
|
|
|
9P is a network protocol. Mount the agent namespace from any machine and every
|
|
session, tool, and config value is accessible as if local:
|
|
|
|
```sh
|
|
# From another machine:
|
|
9p -a 'tcp!server:5640' read session/{sname}/agent/{aname}/state
|
|
```
|
|
|
|
No SSH tunneling, no port forwarding, no API gateway.
|
|
|
|
### Shell composability
|
|
|
|
Because operations are file I/O, they compose with the full Unix toolkit:
|
|
|
|
```sh
|
|
# Fan out a prompt to all agents
|
|
for s in session/*/agent/*/prompt; do echo "run tests" > "$s"; done
|
|
|
|
# Wait for all agents to finish
|
|
for s in session/*/agent/*/statewait; do cat "$s" > /dev/null; done
|
|
|
|
# Grep all agent plans
|
|
grep -r "TODO" session/*/plan
|
|
|
|
# Monitor costs
|
|
cat session/*/agent/*/cost
|
|
|
|
# Strip block markup from chat output
|
|
cat session/{sname}/agent/{aname}/chat | grep -vE '^\[\[\[.*'
|
|
```
|
|
|
|
Pipe agents into `awk`. Filter with `grep`. Schedule with `cron`. Orchestrate
|
|
with a 10-line shell script instead of a framework.
|
|
|
|
### Plan 9 patterns
|
|
|
|
- **`/net/dns` pattern** — `/complete`, `/generate`, `/route` are stateless
|
|
per-fid: write a request, read back the result
|
|
- **`ctl` files** — control operations (stop, kill, rename, compact) are writes
|
|
to a control file, not method calls
|
|
- **Blocking reads** — `statewait` blocks until state changes, replacing event
|
|
subscriptions with a simple `cat`
|
|
- **Multiplexing** — multiple clients mount the same server simultaneously,
|
|
each with an independent view through per-fid state
|
|
|
|
### `/generate` — one-shot LLM
|
|
|
|
```sh
|
|
echo 'summarize this repo' | ollie-9p rdwr generate
|
|
cat main.go | ollie-9p rdwr generate
|
|
echo '{"prompt":"explain recursion"}' | ollie-9p rdwr generate
|
|
```
|
|
|
|
### `/complete` — code completion
|
|
|
|
Fill-in-the-middle:
|
|
|
|
```sh
|
|
echo '{"file":"main.go","prefix":"func ","suffix":""}' | ollie-9p rdwr complete
|
|
```
|
|
|
|
### `/route` — task routing
|
|
|
|
```sh
|
|
echo 'implement login page' | ollie-9p rdwr route
|
|
# backend=anthropic model=claude-sonnet-4-20250514
|
|
```
|
|
|
|
### Key files per agent
|
|
|
|
| File | Mode | Description |
|
|
|---|---|---|
|
|
| `prompt` | write | Queue a new turn |
|
|
| `fifo` | r/w | Prompt queue (write=enqueue, read=dequeue) |
|
|
| `statewait` | read (blocking) | Blocks until state changes |
|
|
| `chat` | read (streaming) | Filtered text (no markers/fences) |
|
|
| `chat.raw` | read (streaming) | Full markup with block markers |
|
|
| `log` | read | Last 64KB of conversation (non-blocking) |
|
|
| `plan` | r/w | Scratch space for agent planning |
|
|
| `cfg` | r/w | Agent config (key=value) |
|
|
| `ctl` | rdwr | Control commands (write cmd, read response) |
|
|
| `stats` | read | Token usage, cost, context size (key=value) |
|
|
| `name` | r/w | Mutable agent name |
|
|
| `id` | read | Immutable agent UUID |
|
|
| `proc/{pid}` | read | Detached process output | |