From 5c27a948bded6ef3691fa07226fc202a78875f8b Mon Sep 17 00:00:00 2001 From: Ollie Agent Date: Fri, 31 Jul 2026 07:31:58 +0200 Subject: [PATCH] docs: remove stale s/ u/ x/ script namespace references --- README.md | 2 +- doc/USAGE.md | 88 +++++++++++++++++----------------------------------- 2 files changed, 30 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index e7d0df1..24fb89c 100644 --- a/README.md +++ b/README.md @@ -342,7 +342,7 @@ full variant specification. | **Run an agent** | `olliesrv` → any frontend (ellie, KDE, acme) | | **Remote execution** | Set `remote=user@host` in session config | | **Multi-agent** | `subagent_spawn` from within a session, or shell scripts | -| **Code completion** | `u/complete` from acme, or read/write `/complete` | +| **Code completion** | Read/write `/complete` for fill-in-the-middle | | **One-shot LLM** | Write to `/generate`, read back the response | | **Task routing** | Write to `/route`, read back `backend=X model=Y` | | **Background jobs** | Detach via `shell({"elevated":true, "detach":true})` | diff --git a/doc/USAGE.md b/doc/USAGE.md index c33490b..cd2233e 100644 --- a/doc/USAGE.md +++ b/doc/USAGE.md @@ -34,13 +34,13 @@ OLLIE_LOG=debug olliesrv Valid levels: `debug`, `info`, `warn`, `error`. Per-subsystem overrides follow the pattern `OLLIE__LOG=debug` where `` matches the logger's tag (e.g. `OLLIE_SESSION_LOG`). -The rendered context window for any session is readable at `s/{id}/context` — the exact message array sent to the backend on the last turn. Combined with `s/{id}/systemprompt`, this gives full visibility into what the model sees. +The rendered context window for any session is readable at `session/{id}/agent/{aid}/context` — the exact message array sent to the backend on the last turn. Combined with `session/{id}/agent/{aid}/systemprompt`, this gives full visibility into what the model sees. --- Examples below assume `$OLLIE` is set to the ollie mount point (default: `$HOME/mnt/ollie`). -Scripts under `s/` and `u/` are available directly via the mounted filesystem -after running `just`. +The 9P filesystem is the primary interface; all session operations go through +`session/{id}/agent/{aid}/` paths. ## One-shot generation @@ -74,12 +74,12 @@ echo 'implement login page' | ollie-9p rdwr route Use this to dispatch work to the appropriate tier without hardcoding model names. -### s/cleanup +### Session cleanup Remove all idle sessions: ```sh -$OLLIE/session/cleanup +ollie-9p exec session/cleanup ``` Schedule regular cleanup with a cron job: @@ -88,14 +88,14 @@ Schedule regular cleanup with a cron job: */15 * * * * /path/to/mnt/ollie/session/cleanup ``` -### Raw s/ access +### Raw session access ```sh 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 +cat $OLLIE/session//cfg # state, backend, model, agent, cwd, params +cat $OLLIE/session//agent/0/chat +rm -r $OLLIE/session/ # cancel and remove ``` Valid spec keys: `name` (auto-generated if omitted), `cwd` (required), `agent`, @@ -104,7 +104,7 @@ Valid spec keys: `name` (auto-generated if omitted), `cwd` (required), `agent`, ### Generation parameters Parameters are set in the agent config JSON and can be overridden at runtime by -writing `key=value` lines to `s/{id}/cfg`. Runtime writes take precedence over +writing `key=value` lines to `session/{id}/cfg`. Runtime writes take precedence over the agent config. All are optional; omitted values use the backend's default. | Key | Type | Description | @@ -141,8 +141,8 @@ Example agent config: Example runtime override: ```sh -echo "temperature=0.3" > $OLLIE/s/mysession/cfg -echo "topP=0.9" > $OLLIE/s/mysession/cfg +echo "temperature=0.3" > $OLLIE/session/mysession/agent/0/cfg +echo "topP=0.9" > $OLLIE/session/mysession/agent/0/cfg ``` ### Sandbox @@ -164,39 +164,9 @@ Chain multiple generation steps: echo "list 5 blog post ideas" | ollie-9p rdwr generate | head -3 | ollie-9p rdwr generate ``` -## Code completion (acme) +## Code completion -`u/complete` provides AI ghost-text code completion for [acme](http://acme.cat-v.org) -windows. It reads the text before and after the cursor (dot), sends it to a lightweight -model, and opens the suggested insertion in a new window. - -### Setup - -Two environment variables are required (set them in `~/.config/ollie/env` or export -them in your shell): - -``` -OLLIE_COMPLETE_BACKEND=ollama -OLLIE_COMPLETE_MODEL=qwen3:4b -``` - -### Usage - -From an acme window, middle-click `u/complete` in the tag (or add it to the global -tag). The script: - -1. Reads up to 4000 characters before the cursor and 1000 after. -2. Finds or creates a persistent copilot session for the current working directory. -3. Submits a fill-in-the-middle prompt to the configured model. -4. Opens the completion in a new `ollie/complete` window. - -Override model or backend per invocation with flags: - -```sh -u/complete -model phi-4-mini -backend ollama -``` - -### Session reuse +The `complete` file provides fill-in-the-middle code completion: One copilot session is maintained per working directory. The session ID is derived deterministically from the cwd, so concurrent completions in the same directory share @@ -282,13 +252,13 @@ printf 'name=reviewer\ncwd=%s\n' "$PWD" > $OLLIE/session/new ```sh # Queue a prompt on a named session -printf '%s\n' "Draft a design doc for the new cache layer." > $OLLIE/s/writer/prompt +printf '%s\n' "Draft a design doc for the new cache layer." > $OLLIE/session/writer/agent/0/prompt # Wait for the turn to finish (statewait blocks until state changes) -until [ "$(cat $OLLIE/s/writer/statewait)" = "idle" ]; do :; done +until [ "$(cat $OLLIE/session/writer/agent/0/statewait)" = "idle" ]; do :; done # Read only the new output (offset marks the byte position after the user prompt) -tail -c +$(($(cat $OLLIE/s/writer/offset) + 1)) $OLLIE/s/writer/chat +tail -c +$(($(cat $OLLIE/session/writer/agent/0/offset) + 1)) $OLLIE/session/writer/agent/0/chat ``` **Key files per session:** @@ -323,9 +293,9 @@ revises until the reviewer approves, then the tester validates: cwd=${1:?usage: $0 } cd $OLLIE -printf 'name=developer\nagent=developer\ncwd=%s\n' "$cwd" > s/new -printf 'name=reviewer\nagent=reviewer\ncwd=%s\n' "$cwd" > s/new -printf 'name=tester\nagent=tester\ncwd=%s\n' "$cwd" > s/new +printf 'name=developer\nagent=developer\ncwd=%s\n' "$cwd" > session/new +printf 'name=reviewer\nagent=reviewer\ncwd=%s\n' "$cwd" > session/new +printf 'name=tester\nagent=tester\ncwd=%s\n' "$cwd" > session/new # Send a prompt to a named session and return the model's response. # Opens statewait before writing the prompt so the idle baseline is captured @@ -333,16 +303,16 @@ printf 'name=tester\nagent=tester\ncwd=%s\n' "$cwd" > s/new # user prompt in chat; everything from that position to EOF is the model response. send() { sid=$1; shift - exec 3< s/$sid/statewait - printf '%s' "$*" > s/$sid/prompt + exec 3< session/$sid/agent/0/statewait + printf '%s' "$*" > session/$sid/agent/0/prompt while true; do read -r _ <&3 && { exec 3<&-; break; } exec 3<&- - [ "$(awk -F= '/^state=/{print $2}' s/$sid/cfg)" != "idle" ] && break - exec 3< s/$sid/statewait + [ "$(cat session/$sid/agent/0/state)" != "idle" ] && break + exec 3< session/$sid/agent/0/statewait done - until [ "$(awk -F= '/^state=/{print $2}' s/$sid/cfg)" = "idle" ]; do sleep 0.5; done - tail -c +$(($(cat s/$sid/offset) + 1)) s/$sid/chat + until [ "$(cat session/$sid/agent/0/state)" = "idle" ]; do sleep 0.5; done + tail -c +$(($(cat session/$sid/agent/0/offset) + 1)) session/$sid/agent/0/chat } reply=$(send developer "Implement a function that parses a JSON config file.") @@ -373,13 +343,13 @@ $reply") $result") done -rm -r s/developer s/reviewer s/tester +rm -r session/developer session/reviewer session/tester ``` The agents have no knowledge of each other — the script holds all the routing logic. A human can intervene at any time by writing directly to any session's `prompt`. Each agent can use a different `agent=`, `backend=`, or `model=` — set them in the -`s/new` spec lines. +`session/new` spec lines. ### Self-generating workflows @@ -431,7 +401,7 @@ OLLIE_TRANSCRIPT_PATH=~/mnt/archive/tr ``` - Markdown rendering of assistant responses -- 9P filesystem browser (navigate `s/`, `a/`, `m/`, `sk/`) +- 9P filesystem browser (navigate sessions, agents, tools, skills) - Two built-in themes: `midnight` (dark) and `acme` (Plan 9-inspired light); choice persisted to `localStorage`