lkn
/
ollie
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: s/ → session/ namespace rename throughout

This commit is contained in:
Levi Neely 2026-07-29 20:34:51 +02:00
parent 7fc180af80
commit 106dc310e6
5 changed files with 61 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
9p

@ -1 +1 @@
Subproject commit 55fcebd032ad54d3892e639b545440eec9e085ed
Subproject commit 47c4890037c7e3364b3b2e018ae1bde02e2a79e9

22
README.md
View File

@ -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.

34
doc/MULTI_AGENT.md
View File

@ -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 <name>` |
| `/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 <name>` |
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

38
doc/USAGE.md
View File

@ -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/<session-id>/cfg # state, backend, model, agent, cwd, params
cat $OLLIE/s/<session-id>/chat
rm -r $OLLIE/s/<session-id> # 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"}'

26
doc/help.md
View File

@ -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/<id>/prompt # send a prompt
cat ~/mnt/ollie/s/<id>/chat # read the conversation
tail -f ~/mnt/ollie/s/<id>/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/<id>/prompt # send a prompt
cat ~/mnt/ollie/session/<id>/chat # read the conversation
tail -f ~/mnt/ollie/session/<id>/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/<id> ~/mnt/ollie/s/my-name # rename
rm -r ~/mnt/ollie/s/<id> # kill
echo stop > ~/mnt/ollie/s/<id>/ctl # interrupt current turn
echo "cwd=/path backend=ollama model=qwen3:8b" > ~/mnt/ollie/session/new
mv ~/mnt/ollie/session/<id> ~/mnt/ollie/session/my-name # rename
rm -r ~/mnt/ollie/session/<id> # kill
echo stop > ~/mnt/ollie/session/<id>/ctl # interrupt current turn
```
## Switching backend/model/agent
```sh
cat ~/mnt/ollie/backends # list backends
cat ~/mnt/ollie/s/<id>/models # list models for current backend
echo backend=ollama > ~/mnt/ollie/s/<id>/cfg
echo model=qwen3:8b > ~/mnt/ollie/s/<id>/cfg
echo agent=myagent > ~/mnt/ollie/s/<id>/cfg
cat ~/mnt/ollie/session/<id>/models # list models for current backend
echo backend=ollama > ~/mnt/ollie/session/<id>/cfg
echo model=qwen3:8b > ~/mnt/ollie/session/<id>/cfg
echo agent=myagent > ~/mnt/ollie/session/<id>/cfg
```
Writes to cfg are rejected while the agent is running.