Remove '9P: everything is a file' section from README, link to doc/resources/9p.md instead
This commit is contained in:
Ollie Agent
parent
0d8bd9a56c
commit
86e09b1cd2
135
README.md
135
README.md
|
|
@ -115,139 +115,8 @@ graph TB
|
|||
```
|
||||
|
||||
`olliesrv` exposes the agent runtime over a single surface: a 9P2000 filesystem.
|
||||
The KDE GUI, Kate plugin, and KRunner use 9P internally to communicate with the
|
||||
server — there is no D-Bus interface.
|
||||
|
||||
## 9P: everything is a file
|
||||
|
||||
The 9P server exposes the agent runtime as a synthetic filesystem. Every session
|
||||
is a directory; every operation is a read or write. There is no client library,
|
||||
no SDK, no protocol buffer — `ollie-9p` commands are the API.
|
||||
|
||||
```sh
|
||||
# Create a session
|
||||
echo "name=worker" | ollie-9p write session/new
|
||||
|
||||
# Submit a prompt
|
||||
echo "fix the bug in main.go" | ollie-9p write session/{sname}/agent/{aname}/prompt
|
||||
|
||||
# Stream the response
|
||||
ollie-9p read session/{sname}/agent/{aname}/chat
|
||||
|
||||
# Check state
|
||||
ollie-9p read session/{sname}/agent/{aname}/state
|
||||
|
||||
# One-shot generation (no session needed)
|
||||
echo 'explain monads' | ollie-9p rdwr generate
|
||||
|
||||
# Route a task to the best model
|
||||
echo 'redesign the auth system' | ollie-9p rdwr route
|
||||
# → backend=kiro model=claude-sonnet-4-20250514
|
||||
```
|
||||
|
||||
### Network transparency
|
||||
|
||||
9P is a network protocol. Connect to a remote agent:
|
||||
|
||||
```sh
|
||||
ollie-9p -addr tcp!server:5640 read session/idx
|
||||
```
|
||||
|
||||
No SSH tunneling, no port forwarding, no API gateway. One connection and every
|
||||
session, every tool, every config value is accessible as if local.
|
||||
|
||||
### Pipe `o`: a composable CLI
|
||||
|
||||
The `o` script (`data/scripts/o`) wraps the 9P namespace into a composable CLI:
|
||||
|
||||
```sh
|
||||
o read chat # stream chat output
|
||||
o prompt # interactive multi-line REPL
|
||||
o tail # tail chat with block-marker filtering
|
||||
o readloop statewait # block until state changes
|
||||
```
|
||||
|
||||
Context is set once, then every command addresses the right agent:
|
||||
|
||||
```sh
|
||||
eval $(o env mysession myagent)
|
||||
o read state # → session/mysession/agent/myagent/state
|
||||
o prompt # REPL for session/mysession/agent/myagent
|
||||
```
|
||||
|
||||
Paths resolve based on context — agent files (`state`, `chat`, `prompt`, etc.)
|
||||
use `$session` + `$agent`, session files (`env`, `ctl`, `name`) use just
|
||||
`$session`, root paths (`models`, `agents`, `help`) need no context. Full
|
||||
paths starting with `session/` bypass resolution entirely.
|
||||
|
||||
### `o tui`: an agent terminal in 20 lines of tmux
|
||||
|
||||
`o tui` composes `o tail` and `o prompt` into a single tmux layout — no
|
||||
framework, no widgets, no IPC. It's two shell commands in two panes:
|
||||
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│ o tail | grep │ ← chat stream
|
||||
│ │
|
||||
├──────────────────────────────────┤
|
||||
│ o prompt │ ← input REPL
|
||||
└──────────────────────────────────┘
|
||||
Agent state shown in tmux status bar
|
||||
```
|
||||
|
||||
The prompt REPL supports multi-line input (send with `.` on its own line),
|
||||
slash commands (`/stop`, `/model`, `/quit`, etc.), and readline editing.
|
||||
Agent state updates the tmux status bar in real time via `statewait`, with
|
||||
color-coded background — green for idle, orange for calling, blue for thinking.
|
||||
|
||||
This is the entire "frontend": two `o` subcommands, two tmux splits, one
|
||||
background `statewait` reader. No SDK, no widget toolkit, no event loop.
|
||||
It's the Plan 9 principle in miniature — shell composition over framework
|
||||
bloat.
|
||||
|
||||
Because operations are 9P I/O, they compose with scripts:
|
||||
|
||||
```sh
|
||||
# Fan out a prompt to all agents
|
||||
for s in $(ollie-9p read session/idx | cut -f1); do
|
||||
for a in $(ollie-9p ls session/$s/agent | grep -v new); do
|
||||
echo "run tests" | ollie-9p write session/$s/agent/$a/prompt
|
||||
done
|
||||
done
|
||||
|
||||
# Read all agent plans
|
||||
ollie-9p read session/idx | cut -f1 | while read s; do
|
||||
ollie-9p ls session/$s/agent | grep -v new | while read a; do
|
||||
echo "=== $s/$a ==="
|
||||
ollie-9p read session/$s/agent/$a/plan
|
||||
done
|
||||
done
|
||||
|
||||
# Strip block markup from chat output (text-only frontends)
|
||||
ollie-9p read session/{sname}/agent/{aname}/chat | grep -vE '^\[\[\[.*'
|
||||
# → filters [[[type]]]/[[[end]]] block markers, leaving plain text
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
### KDE frontends
|
||||
|
||||
- **Plasmoid** — embed an agent chat widget in the Plasma panel
|
||||
- **Kate plugin** — inline AI assistance in the text editor
|
||||
- **KRunner** — launch prompts from the desktop search bar
|
||||
- **Standalone GUI** — full-featured Qt6 chat application
|
||||
KDE GUI, Kate plugin, and KRunner all use 9P internally. For a deep dive into the
|
||||
filesystem, see [`doc/resources/9p.md`](doc/resources/9p.md).
|
||||
|
||||
## Tool registry: zero built-in tools
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue