From 106dc310e631ec23261091edc93f26125768c51b Mon Sep 17 00:00:00 2001 From: Levi Neely Date: Wed, 29 Jul 2026 20:34:51 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20s/=20=E2=86=92=20session/=20namespace?= =?UTF-8?q?=20rename=20throughout?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 9p | 2 +- README.md | 22 +++++++++++----------- doc/MULTI_AGENT.md | 34 +++++++++++++++++----------------- doc/USAGE.md | 38 +++++++++++++++++++------------------- doc/help.md | 26 +++++++++++++------------- 5 files changed, 61 insertions(+), 61 deletions(-) diff --git a/9p b/9p index 55fcebd..47c4890 160000 --- a/9p +++ b/9p @@ -1 +1 @@ -Subproject commit 55fcebd032ad54d3892e639b545440eec9e085ed +Subproject commit 47c4890037c7e3364b3b2e018ae1bde02e2a79e9 diff --git a/README.md b/README.md index d346e59..8316257 100644 --- a/README.md +++ b/README.md @@ -204,23 +204,23 @@ There is no client library, no SDK, no protocol buffer — `echo`, `cat`, `tail` ```sh # Create a session -echo "name=worker" > /mnt/ollie/s/new +echo "name=worker" > /mnt/ollie/session/new # Submit a prompt -echo "fix the bug in main.go" > /mnt/ollie/s/worker/prompt +echo "fix the bug in main.go" > /mnt/ollie/session/worker/prompt # Stream the response -tail -f /mnt/ollie/s/worker/chat +tail -f /mnt/ollie/session/worker/chat # Check state -cat /mnt/ollie/s/worker/state +cat /mnt/ollie/session/worker/state # Kill a background process -echo "signal 12345 TERM" > /mnt/ollie/s/worker/ctl +echo "signal 12345 TERM" > /mnt/ollie/session/worker/ctl # Get completions -echo '{"language":"go","code":"func he"}' > /mnt/ollie/s/worker/complete -cat /mnt/ollie/s/worker/complete +echo '{"language":"go","code":"func he"}' > /mnt/ollie/session/worker/complete +cat /mnt/ollie/session/worker/complete # One-shot generation (no session needed) exec 3<>/mnt/ollie/generate; echo 'explain monads in one sentence' >&3; cat <&3; exec 3>&- @@ -257,16 +257,16 @@ Because operations are file I/O, they compose with the entire Unix toolkit: ```sh # Fan out a prompt to all sessions -for s in /mnt/ollie/s/*/prompt; do echo "run tests" > "$s"; done +for s in /mnt/ollie/session/*/prompt; do echo "run tests" > "$s"; done # Wait for all agents to finish -for s in /mnt/ollie/s/*/statewait; do cat "$s" > /dev/null; done +for s in /mnt/ollie/session/*/statewait; do cat "$s" > /dev/null; done # Grep all agent plans -grep -r "TODO" /mnt/ollie/s/*/plan +grep -r "TODO" /mnt/ollie/session/*/plan # Monitor costs -paste /mnt/ollie/s/*/cost +paste /mnt/ollie/session/*/cost ``` Pipe agents into `awk`. Filter with `grep`. Schedule with `cron`. Orchestrate with a 10-line shell script instead of a framework. diff --git a/doc/MULTI_AGENT.md b/doc/MULTI_AGENT.md index fbc7ca3..8d20c0e 100644 --- a/doc/MULTI_AGENT.md +++ b/doc/MULTI_AGENT.md @@ -6,34 +6,34 @@ ordinary shell scripting against a mounted filesystem. ## The Namespace -Every session lives under `/s/{id}/`: +Every session lives under `/session/{id}/`: | Path | Purpose | |------|---------| -| `/s/new` | Create a session (write `name`, `backend`, `model`, `agent`, `cwd`) | -| `/s/{id}/prompt` | Submit a prompt (dispatched async on close) | -| `/s/{id}/chat` | Cumulative conversation history (append-only read) | -| `/s/{id}/cfg` | Session config (KV): state, backend, model, agent, cwd, params | -| `/s/{id}/statewait` | **Blocking read** — returns when state changes | -| `/s/{id}/ctl` | Control commands: `stop`, `kill`, `compact`, `rn ` | +| `/session/new` | Create a session (write `name`, `backend`, `model`, `agent`, `cwd`) | +| `/session/{id}/prompt` | Submit a prompt (dispatched async on close) | +| `/session/{id}/chat` | Cumulative conversation history (append-only read) | +| `/session/{id}/cfg` | Session config (KV): state, backend, model, agent, cwd, params | +| `/session/{id}/statewait` | **Blocking read** — returns when state changes | +| `/session/{id}/ctl` | Control commands: `stop`, `kill`, `compact`, `rn ` | -Utility files at the session root (`/s/`) provide higher-level operations: +Utility files at the session root (`/session/`) provide higher-level operations: | File | Purpose | |------|---------| -| `/s/b` | One-shot: create, submit, wait, print result, kill | -| `/s/bfg` | Batch foreground: submit to existing session, wait, print | -| `/s/bbg` | Batch background: submit, return session path immediately | -| `/s/sh` | Interactive shell session | +| `/session/b` | One-shot: create, submit, wait, print result, kill | +| `/session/bfg` | Batch foreground: submit to existing session, wait, print | +| `/session/bbg` | Batch background: submit, return session path immediately | +| `/session/sh` | Interactive shell session | Global namespaces are shared across all sessions: | Path | Purpose | |------|---------| -| `/s/idx` | Session index (id, state, cwd, backend, model) | -| `/s/{id}/prompt` | Submit a prompt to a peer session | -| `/s/{id}/plan` | Shared session-scoped checklist | -| `/s/{id}/chat` | Full chat history (searchable) | +| `/session/idx` | Session index (id, state, cwd, backend, model) | +| `/session/{id}/prompt` | Submit a prompt to a peer session | +| `/session/{id}/plan` | Shared session-scoped checklist | +| `/session/{id}/chat` | Full chat history (searchable) | ## Spawning Agents @@ -52,7 +52,7 @@ so the spawning tree is recoverable from session IDs alone. ### Hub-and-Spoke (Conductor) A root agent reasons about a task and delegates subtasks to workers. Workers -report back via their chat history; the conductor reads `/s/{id}/chat` after +report back via their chat history; the conductor reads `/session/{id}/chat` after `statewait` unblocks. ```sh diff --git a/doc/USAGE.md b/doc/USAGE.md index 389684c..b6cead5 100644 --- a/doc/USAGE.md +++ b/doc/USAGE.md @@ -107,7 +107,7 @@ Submit a background job and return immediately; prints the `s/{id}` path: ```sh $OLLIE/s/bbg "summarize the recent git log" -# /home/lkn/mnt/ollie/s/1744276689123456789-0 +# /home/lkn/mnt/ollie/session/1744276689123456789-0 ``` Poll for completion: @@ -134,20 +134,20 @@ done Remove all idle sessions: ```sh -$OLLIE/s/cleanup +$OLLIE/session/cleanup ``` Schedule regular cleanup with a cron job: ``` -*/15 * * * * /path/to/mnt/ollie/s/cleanup +*/15 * * * * /path/to/mnt/ollie/session/cleanup ``` ### Raw s/ access ```sh -cat $OLLIE/s/new # show the spec template -printf 'cwd=%s\n---\nSummarize this.\n' "$PWD" > $OLLIE/s/new +cat $OLLIE/session/new # show the spec template +printf 'cwd=%s\n---\nSummarize this.\n' "$PWD" > $OLLIE/session/new cat $OLLIE/s//cfg # state, backend, model, agent, cwd, params cat $OLLIE/s//chat rm -r $OLLIE/s/ # cancel and remove @@ -339,8 +339,8 @@ will not drop a message. **Create named sessions:** ```sh -printf 'name=writer\ncwd=%s\n' "$PWD" > $OLLIE/s/new -printf 'name=reviewer\ncwd=%s\n' "$PWD" > $OLLIE/s/new +printf 'name=writer\ncwd=%s\n' "$PWD" > $OLLIE/session/new +printf 'name=reviewer\ncwd=%s\n' "$PWD" > $OLLIE/session/new ``` **Send a prompt and read the response:** @@ -550,10 +550,10 @@ Each HTTP method maps to a 9P operation: | Method | 9P operation | Example | |---|---|---| | `GET` | read file / list dir | `GET /s/idx` | -| `POST` | write to file | `POST /s/new`, `POST /s/{id}/prompt` | -| `DELETE` | remove | `DELETE /s/{id}` | -| `PATCH` | rename (JSON `{"name":"..."}`) | `PATCH /s/{id}` | -| `HEAD` | stat (metadata in `X-9p-*` headers) | `HEAD /s/{id}` | +| `POST` | write to file | `POST /session/new`, `POST /session/{id}/prompt` | +| `DELETE` | remove | `DELETE /session/{id}` | +| `PATCH` | rename (JSON `{"name":"..."}`) | `PATCH /session/{id}` | +| `HEAD` | stat (metadata in `X-9p-*` headers) | `HEAD /session/{id}` | The full API is described in `httpgw/openapi.json` and served live at `GET /openapi.json`. @@ -562,15 +562,15 @@ The full API is described in `httpgw/openapi.json` and served live at ```sh GET /s/idx # list sessions (JSON array) -GET /s/{id}/cfg # session config (key-value JSON) -GET /s/{id}/chat # conversation transcript (plain text) -POST /s/new # create session (JSON: {cwd, backend, model, agent}) -POST /s/{id}/prompt # submit prompt (JSON: {prompt: "..."}) -POST /s/{id}/ctl # send control command (JSON: {ctl: "stop"}) -DEL /s/{id} # kill and remove session +GET /session/{id}/cfg # session config (key-value JSON) +GET /session/{id}/chat # conversation transcript (plain text) +POST /session/new # create session (JSON: {cwd, backend, model, agent}) +POST /session/{id}/prompt # submit prompt (JSON: {prompt: "..."}) +POST /session/{id}/ctl # send control command (JSON: {ctl: "stop"}) +DEL /session/{id} # kill and remove session GET /backends # list available backends GET /a/ # agent configs -GET /s/{id}/t/ # tool scripts +GET /session/{id}/t/ # tool scripts GET /m/ # memory files GET /sk/ # skills ``` @@ -578,7 +578,7 @@ GET /sk/ # skills ```sh # Examples with curl: curl http://localhost:8080/s/idx -curl -X POST http://localhost:8080/s/new \ +curl -X POST http://localhost:8080/session/new \ -d '{"cwd":"/home/user/project","backend":"anthropic"}' curl -X POST http://localhost:8080/s/mysession/prompt \ -d '{"prompt":"summarize the recent commits"}' diff --git a/doc/help.md b/doc/help.md index 5f295ab..6608f00 100644 --- a/doc/help.md +++ b/doc/help.md @@ -6,11 +6,11 @@ An AI agent exposed as a filesystem. Mount it, then use shell tools. ```sh olliesrv # start the 9P server -echo "cwd=$PWD" > ~/mnt/ollie/s/new # create a session -ls ~/mnt/ollie/s/ # find the session ID -echo "hello" > ~/mnt/ollie/s//prompt # send a prompt -cat ~/mnt/ollie/s//chat # read the conversation -tail -f ~/mnt/ollie/s//chat # follow live output +echo "cwd=$PWD" > ~/mnt/ollie/session/new # create a session +ls ~/mnt/ollie/session/ # find the session ID +echo "hello" > ~/mnt/ollie/session//prompt # send a prompt +cat ~/mnt/ollie/session//chat # read the conversation +tail -f ~/mnt/ollie/session//chat # follow live output ``` ## Filesystem @@ -84,20 +84,20 @@ Or with `9p rdwr`: `echo 'file_edit' | 9p rdwr ollie/tools` ## Session management ```sh -echo "cwd=/path backend=ollama model=qwen3:8b" > ~/mnt/ollie/s/new -mv ~/mnt/ollie/s/ ~/mnt/ollie/s/my-name # rename -rm -r ~/mnt/ollie/s/ # kill -echo stop > ~/mnt/ollie/s//ctl # interrupt current turn +echo "cwd=/path backend=ollama model=qwen3:8b" > ~/mnt/ollie/session/new +mv ~/mnt/ollie/session/ ~/mnt/ollie/session/my-name # rename +rm -r ~/mnt/ollie/session/ # kill +echo stop > ~/mnt/ollie/session//ctl # interrupt current turn ``` ## Switching backend/model/agent ```sh cat ~/mnt/ollie/backends # list backends -cat ~/mnt/ollie/s//models # list models for current backend -echo backend=ollama > ~/mnt/ollie/s//cfg -echo model=qwen3:8b > ~/mnt/ollie/s//cfg -echo agent=myagent > ~/mnt/ollie/s//cfg +cat ~/mnt/ollie/session//models # list models for current backend +echo backend=ollama > ~/mnt/ollie/session//cfg +echo model=qwen3:8b > ~/mnt/ollie/session//cfg +echo agent=myagent > ~/mnt/ollie/session//cfg ``` Writes to cfg are rejected while the agent is running.