prompts: rewrite session_9p.md for agent/{aid} sublevel

Documents the new filesystem structure:
- session/{sid}/plan, env (session-level)
- session/{sid}/agent/{aid}/* (agent-level)
- Removed peer operations (deferred for redesign)
- All operations use ollie-9p CLI
This commit is contained in:
Levi Neely 2026-07-29 20:51:16 +02:00
parent 2a3798ae39
commit f7e084106c
1 changed files with 51 additions and 85 deletions

View File

@ -19,42 +19,16 @@ Your world model is a 9P filesystem. Your session ID is `${OLLIE_SESSION_ID}`. U
`complete`, `generate`, and `route` are request-response files: `complete`, `generate`, and `route` are request-response files:
```bash ```bash
# Pick a backend+model for a task
echo 'implement login page' | ollie-9p rdwr route 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 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 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/`) ## Session Management (`session/`)
Sessions live at `session/`. Each session is a directory; all operations go through `ollie-9p`.
### Session Store Files
| File | Mode | Purpose | | File | Mode | Purpose |
|---|---|---| |---|---|---|
| `session/new` | r/w | Read: key=value template. Write: create a new session. | | `session/new` | r/w | Write key=value to create a new session |
| `session/idx` | read | Session index (id\tstate\tcwd\tbackend\tmodel) | | `session/idx` | read | Session index (id\tstate\tcwd\tbackend\tmodel) |
| `session/ls` | exec | List sessions | | `session/ls` | exec | List sessions |
| `session/kill` | exec | Kill a session | | `session/kill` | exec | Kill a session |
@ -64,34 +38,43 @@ Sessions live at `session/`. Each session is a directory; all operations go thro
| `session/bbg` | exec | Background query | | `session/bbg` | exec | Background query |
| `session/cleanup` | exec | Kill idle sessions | | `session/cleanup` | exec | Kill idle sessions |
### Session Directory (`session/{id}/`) ## Session Directory (`session/{sid}/`)
| File | Mode | Purpose | | File | Mode | Purpose |
|---|---|---| |---|---|---|
| `cfg` | r/w | Session config: backend, model, agent, cwd, params (key=value). Write key=value to change. | | `plan` | r/w | Session-scoped markdown checklist; survives compaction |
| `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 | | `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.in` | write | Queue a prompt (FIFO input) |
| `fifo.out` | read | Pop queued prompt (FIFO output) | | `fifo.out` | read | Pop queued prompt (FIFO output) |
| `models` | read | Available models for current backend | | `chat` | read | Agent conversation history (tail-able) |
| `offset` | read | Byte offset after last user prompt | | `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>` | | `state` | read | Current state: `idle`, `thinking`, or `calling: <tool>` |
| `statewait` | read | Blocks until state changes; returns new value | | `statewait` | read | Blocks until state changes; returns new value |
| `systemprompt` | read | Fully rendered system prompt | | `cfg` | r/w | Agent config: backend, model, cwd, params (key=value) |
| `tail` | exec | Tail helper | | `ctl` | write | Control: stop, compact, clear, model, backend, cwd |
| `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 | | `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 ## Operations
@ -99,57 +82,40 @@ Sessions live at `session/`. Each session is a directory; all operations go thro
# Discover sessions # Discover sessions
ollie-9p read session/idx ollie-9p read session/idx
# Discover sessions in same cwd # Spawn a session
ollie-9p read session/idx | grep "$PWD"
# Spawn a session (minimal, generated ID)
echo "cwd=$PWD" | ollie-9p write session/new echo "cwd=$PWD" | ollie-9p write session/new
# Spawn a session (named)
printf 'name=reviewer\ncwd=%s\n' "$PWD" | ollie-9p write session/new printf 'name=reviewer\ncwd=%s\n' "$PWD" | ollie-9p write session/new
# Kill a session # Kill a session
ollie-9p rm session/{id} ollie-9p rm session/{sid}
# Rename a session # Read session plan
echo "rn newname" | ollie-9p write session/{id}/ctl ollie-9p read session/{sid}/plan
# --- Agent operations (from within session/{sid}/agent/{aid}/) ---
# Send a prompt # Send a prompt
echo "your prompt here" | ollie-9p write session/{id}/prompt echo "fix the bug" | ollie-9p write session/{sid}/agent/{aid}/prompt
# Control commands via ctl: # Read state
# stop — interrupt the current agent turn ollie-9p read session/{sid}/agent/{aid}/state
# 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) # Read chat
ollie-9p read session/{id}/cfg ollie-9p read session/{sid}/agent/{aid}/chat
# Write config changes # Control commands
echo "temperature=0.7" | ollie-9p write session/{id}/cfg 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 most recent response # Read/write config
offset=$(ollie-9p read session/{id}/offset) ollie-9p read session/{sid}/agent/{aid}/cfg
ollie-9p read session/{id}/chat | tail -c +$((offset + 1)) echo "temperature=0.7" | ollie-9p write session/{sid}/agent/{aid}/cfg
# Read current state # Read latest response
ollie-9p read session/{id}/state offset=$(ollie-9p read session/{sid}/agent/{aid}/offset)
ollie-9p read session/{sid}/agent/{aid}/chat | tail -c +$((offset + 1))
# Discover available models # Load a tool
ollie-9p read session/{id}/models echo "file_read" | ollie-9p write session/{sid}/agent/{aid}/tools
# 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 rm session/{id}/peer/{peerid}
``` ```