From 1a2ad14f6b690016ae538ad1ef76eafb47b82f6d Mon Sep 17 00:00:00 2001 From: Ollie Agent Date: Tue, 4 Aug 2026 19:30:57 +0200 Subject: [PATCH] docs: replace all session/{id} and {sid} with {sname} --- AGENTS.md | 2 +- data/prompts/session-9p.md | 42 +++++++++++++++++++------------------- doc/evolution.md | 16 +++++++-------- prompts/session_9p.md | 34 +++++++++++++++--------------- prompts/system_prompt.md | 8 ++++---- 5 files changed, 51 insertions(+), 51 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 428fa93..73ceb9b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -92,7 +92,7 @@ just test-remote - Tool scripts: emit structured output (`STATUS=ok`, `STATUS=error`). Image/LSP tools return JSON content blocks. - Prompts: markdown, concise, example-driven. Follow the pattern in existing `tools-*.md` files. ## Architecture (key concepts) -1. **One integration surface: 9P filesystem (sessions at `session/{id}/agent/{aname}/`). Tools, skills, memory on physical filesystem via env vars. +1. **One integration surface: 9P filesystem (sessions at `session/{sname}/agent/{aname}/`). Tools, skills, memory on physical filesystem via env vars. 2. **Agent loop** (`agent/loop.go`): Streaming LLM call → parse tool calls → dispatch → loop until no more tool calls or max steps. 3. **Tool dispatch** (`toolsrv/`): `shell` is built-in. All others are external scripts resolved from `OLLIE_TOOLS_PATH`. 4. **Sandbox** (`sandbox/`): Landlock-based. Config in `sandbox/*.yaml` defines filesystem access per profile. diff --git a/data/prompts/session-9p.md b/data/prompts/session-9p.md index 825f313..c681a8d 100644 --- a/data/prompts/session-9p.md +++ b/data/prompts/session-9p.md @@ -34,12 +34,12 @@ Tools are loaded dynamically per-agent. The system has three levels: | Path | Purpose | |---|---| | `ollie-9p read tools` | **Global catalog** — all available tools on disk | -| `ollie-9p read session/{id}/agent/{aname}/tools` | **Loaded tools** — tools active in this agent | -| `echo "name" \| ollie-9p write session/{id}/agent/{aname}/tools` | **Load a tool** — activate it for this agent | +| `ollie-9p read session/{sname}/agent/{aname}/tools` | **Loaded tools** — tools active in this agent | +| `echo "name" \| ollie-9p write session/{sname}/agent/{aname}/tools` | **Load a tool** — activate it for this agent | - **List available tools** — `ollie-9p read tools` (global catalog with descriptions) -- **See loaded tools** — `ollie-9p read session/{id}/agent/{aname}/tools` -- **Load a tool** — `echo "toolname" | ollie-9p write session/{id}/agent/{aname}/tools` (or use `tool_load`) +- **See loaded tools** — `ollie-9p read session/{sname}/agent/{aname}/tools` +- **Load a tool** — `echo "toolname" | ollie-9p write session/{sname}/agent/{aname}/tools` (or use `tool_load`) Once loaded, a tool becomes a first-class callable function with typed arguments. Load tools as needed — do not load everything upfront. @@ -48,10 +48,10 @@ Once loaded, a tool becomes a first-class callable function with typed arguments 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} +{sname}\t{state}\t{cwd}\t{backend}\t{model} ``` -**Inter-Agent Communication**: To send a prompt to another session: `echo "your prompt" | ollie-9p write session/{id}/prompt`. Always provide a return path (e.g., [message from $OLLIE_SESSION_ID]). +**Inter-Agent Communication**: To send a prompt to another session: `echo "your prompt" | ollie-9p write session/{sname}/prompt`. Always provide a return path (e.g., [message from $OLLIE_SESSION_ID]). ## Session Management (`session/`) @@ -65,7 +65,7 @@ Sessions live at `session/`. Each session is a directory; all operations are 9P | `session/idx` | read | Session index (name\tstate\tcwd\tbackend\tmodel\tagentName\tid) | | `aliases` | read | Table of alias\tpath for all walkable-but-unlisted names | -### Session Directory (`session/{id}/`) +### Session Directory (`session/{sname}/`) | File | Mode | Purpose | |---|---|---| @@ -91,7 +91,7 @@ Sessions live at `session/`. Each session is a directory; all operations are 9P | `tail` | exec | Tail helper | | `usage` | read | Token usage stats | -### Agent Directory (`session/{id}/agent/{aname}/`) +### Agent Directory (`session/{sname}/agent/{aname}/`) Each agent in a session gets its own subdirectory with its own plan, state, and chat log. @@ -113,13 +113,13 @@ echo "cwd=$PWD" | ollie-9p write session/new printf 'name=reviewer\ncwd=%s\n' "$PWD" | ollie-9p write session/new # Kill a session -ollie-9p rm session/{id} +ollie-9p rm session/{sname} # Rename a session -ollie-9p mv session/{id} session/{newname} +ollie-9p mv session/{sname} session/{newname} # Send a prompt -echo "your prompt here" | ollie-9p write session/{id}/prompt +echo "your prompt here" | ollie-9p write session/{sname}/prompt # Control commands via ctl: # stop — interrupt the current agent turn @@ -129,30 +129,30 @@ echo "your prompt here" | ollie-9p write session/{id}/prompt # cwd — change the working directory # model — switch model # backend — switch backend -echo "model gpt-4o" | ollie-9p write session/{id}/ctl +echo "model gpt-4o" | ollie-9p write session/{sname}/ctl # Read session config (backend, model, agent, cwd, params) -ollie-9p read session/{id}/cfg +ollie-9p read session/{sname}/cfg # Write config changes -echo "temperature=0.7" | ollie-9p write session/{id}/cfg +echo "temperature=0.7" | ollie-9p write session/{sname}/cfg # Read most recent response -offset=$(ollie-9p read session/{id}/offset) -ollie-9p read session/{id}/agent/{aname}/log | tail -c +$((offset + 1)) +offset=$(ollie-9p read session/{sname}/offset) +ollie-9p read session/{sname}/agent/{aname}/log | tail -c +$((offset + 1)) # Read current state -ollie-9p read session/{id}/state +ollie-9p read session/{sname}/state # Discover available models -ollie-9p read session/{id}/models +ollie-9p read session/{sname}/models # Add a peer link (bidirectional) -ollie-9p create session/{id}/peer/{peerid} +ollie-9p create session/{sname}/peer/{peerid} # Send a prompt to a peer -echo "your message" | ollie-9p write session/{id}/peer/{peerid} +echo "your message" | ollie-9p write session/{sname}/peer/{peerid} # Remove a peer link (bidirectional) -ollie-9p rm session/{id}/peer/{peerid} +ollie-9p rm session/{sname}/peer/{peerid} ``` diff --git a/doc/evolution.md b/doc/evolution.md index 26ea11f..16c1285 100644 --- a/doc/evolution.md +++ b/doc/evolution.md @@ -50,8 +50,8 @@ Initial components: Build system was `mkfile` (Plan 9 make), later `Makefile`, finally `justfile`. ## Phase 2: The 9P Decision (Apr 14–28) The defining architectural choice: **every agent primitive is a file**. -Sessions are directories. Sending a prompt is writing to `session/{id}/prompt`. -Reading state is `cat session/{id}/state`. This made the control plane +Sessions are directories. Sending a prompt is writing to `session/{sname}/prompt`. +Reading state is `cat session/{sname}/state`. This made the control plane protocol-agnostic — any program that can read/write files can be a frontend. Key files crystallized: `prompt`, `chat`, `state`, `ctl`, `cfg`, `statewait`. The `session/new` file (write key=value pairs, read back session ID) became the @@ -74,7 +74,7 @@ Planning went through the most iterations of any subsystem: 3. **Beads** integration (external issue tracker) — made optional, then dropped 4. `task_add` / `task_check` tools 5. Inline markdown plans forbidden -6. **Final form**: a single `session/{id}/plan` file (markdown checklist), written by +6. **Final form**: a single `session/{sname}/plan` file (markdown checklist), written by the agent, persisted across context compaction The lesson: planning needed to be simple, agent-controlled, and not bureaucratic. ## Phase 5: Multi-Agent Coordination (May 25 – Jun 15) @@ -210,7 +210,7 @@ Eliminated accumulated abstractions that no longer served a purpose. functions in `**fs**/`. The `*fs.Tree` IS the session collection; `rootState` (unexported) lives in `tree.Data`. CRUD via `NewRoot`, `Lookup`, `Create`, `Kill`, `Rename`, `Shutdown`. -- **Fixed infinite recursion** in `session/{sid}/agent/` directory — `pathType()` +- **Fixed infinite recursion** in `session/{sname}/agent/` directory — `pathType()` didn't recognize agent subdirectories, causing walk to succeed at any depth. - **Fixed phantom session descent** — walk into non-existent sessions now fails immediately. @@ -220,7 +220,7 @@ Eliminated accumulated abstractions that no longer served a purpose. of `rootState.sessions`. Broke D-Bus ListSessions and GUI session restore. ### Frontends - **acme**: paths updated `s/` → `session/`, agent files route through - `session/{id}/agent/{aname}/`. + `session/{sname}/agent/{aname}/`. - **ellie.el**: same path migration, added `ellie--agent-dir` for agent ID discovery. - **KDE GUI**: no changes needed (D-Bus operates on Go objects, not paths). @@ -229,7 +229,7 @@ Eliminated accumulated abstractions that no longer served a purpose. session/ ├── new write key=value to create session ├── idx session index (tab-separated) -├── {sid}/ +├── {sname}/ │ ├── plan session-scoped markdown checklist │ ├── env session environment │ └── agent/ @@ -593,7 +593,7 @@ The KDE frontend received extensive updates across both days: ├── route request-response: model routing ├── elevate/ │ ├── policy global elevation policy -│ └── pending/{id} pending elevation requests +│ └── pending/{sname} pending elevation requests └── session/ ├── new write key=value to create session ├── idx session index (one line per agent) @@ -700,7 +700,7 @@ The most radical simplification yet: **zero tools compiled into the Go binary.** **Before**: `tools/builtin/builtins.go` returned four Go-compiled handlers (`shell`, `reasoning_think`, `tool_list`, `tool_load`, `tool_active`). These were hard-linked into every agent's tool definition, consuming LLM context slots even when unused. The tool registry was a two-tier system: built-in handlers (Go code, always available) + script tools (loaded on demand via `tool_load`). -**After**: `tools/builtin/` was removed entirely — `builtins.go` last returned `nil`. All tools are loaded through a single convergent path: writing the tool name to `session/{id}/agent/{aname}/tools`. The `shell` and `reasoning_think` tools are now external scripts (`data/tools/shell`, `data/tools/reasoning_think`) with `.meta` sidecars — identical to `file_read`, `file_grep`, or any other tool. +**After**: `tools/builtin/` was removed entirely — `builtins.go` last returned `nil`. All tools are loaded through a single convergent path: writing the tool name to `session/{sname}/agent/{aname}/tools`. The `shell` and `reasoning_think` tools are now external scripts (`data/tools/shell`, `data/tools/reasoning_think`) with `.meta` sidecars — identical to `file_read`, `file_grep`, or any other tool. ### Unified tool loading diff --git a/prompts/session_9p.md b/prompts/session_9p.md index a984fe2..27c214a 100644 --- a/prompts/session_9p.md +++ b/prompts/session_9p.md @@ -32,7 +32,7 @@ echo '{"file":"main.go","prefix":"func "}' | ollie-9p rdwr complete | `session/idx` | read | Session index (name\tstate\tcwd\tbackend\tmodel\tagentName\tid) | | `aliases` | read | Table of alias\tpath for all walkable-but-unlisted names | -## Session Directory (`session/{sid}/`) +## Session Directory (`session/{sname}/`) | File | Mode | Purpose | |---|---|---| @@ -40,7 +40,7 @@ echo '{"file":"main.go","prefix":"func "}' | ollie-9p rdwr complete | `env` | read | Session environment variables | | `agent/` | dir | Agents within this session | -## Agent Directory (`session/{sid}/agent/{aname}/`) +## Agent Directory (`session/{sname}/agent/{aname}/`) Each agent has its own directory. The `{aname}` is the agent's numeric ID (stable, used for permissions). @@ -81,38 +81,38 @@ echo "cwd=$PWD" | ollie-9p write session/new printf 'name=reviewer\ncwd=%s\n' "$PWD" | ollie-9p write session/new # Kill a session -ollie-9p rm session/{sid} +ollie-9p rm session/{sname} # Rename a session -ollie-9p mv session/{sid} session/{newname} +ollie-9p mv session/{sname} session/{newname} # Read session plan -ollie-9p read session/{sid}/plan +ollie-9p read session/{sname}/plan -# --- Agent operations (from within session/{sid}/agent/{aname}/) --- +# --- Agent operations (from within session/{sname}/agent/{aname}/) --- # Send a prompt -echo "fix the bug" | ollie-9p write session/{sid}/agent/{aname}/prompt +echo "fix the bug" | ollie-9p write session/{sname}/agent/{aname}/prompt # Read state -ollie-9p read session/{sid}/agent/{aname}/state +ollie-9p read session/{sname}/agent/{aname}/state # Read chat -ollie-9p read session/{sid}/agent/{aname}/chat +ollie-9p read session/{sname}/agent/{aname}/chat # Control commands -echo "stop" | ollie-9p write session/{sid}/agent/{aname}/ctl -echo "model gpt-4o" | ollie-9p write session/{sid}/agent/{aname}/ctl -echo "compact" | ollie-9p write session/{sid}/agent/{aname}/ctl +echo "stop" | ollie-9p write session/{sname}/agent/{aname}/ctl +echo "model gpt-4o" | ollie-9p write session/{sname}/agent/{aname}/ctl +echo "compact" | ollie-9p write session/{sname}/agent/{aname}/ctl # Read/write config -ollie-9p read session/{sid}/agent/{aname}/cfg -echo "temperature=0.7" | ollie-9p write session/{sid}/agent/{aname}/cfg +ollie-9p read session/{sname}/agent/{aname}/cfg +echo "temperature=0.7" | ollie-9p write session/{sname}/agent/{aname}/cfg # Read latest response -offset=$(ollie-9p read session/{sid}/agent/{aname}/offset) -ollie-9p read session/{sid}/agent/{aname}/chat | tail -c +$((offset + 1)) +offset=$(ollie-9p read session/{sname}/agent/{aname}/offset) +ollie-9p read session/{sname}/agent/{aname}/chat | tail -c +$((offset + 1)) # Load a tool -echo "file_read" | ollie-9p write session/{sid}/agent/{aname}/tools +echo "file_read" | ollie-9p write session/{sname}/agent/{aname}/tools ``` diff --git a/prompts/system_prompt.md b/prompts/system_prompt.md index a04a594..f4b85f5 100644 --- a/prompts/system_prompt.md +++ b/prompts/system_prompt.md @@ -26,9 +26,9 @@ You have autonomous access to tools and skills. Proactively load what you need Tools are loaded into your session at startup (configured in the agent's `autoLoad` list). Additional tools can be loaded dynamically via the 9P filesystem: -- **List available tools** — write to `session/{id}/agent/{aname}/tools` (empty string lists all) -- **Load a tool** — write the tool name to `session/{id}/agent/{aname}/tools` -- **See loaded tools** — read from `session/{id}/agent/{aname}/tools` +- **List available tools** — write to `session/{sname}/agent/{aname}/tools` (empty string lists all) +- **Load a tool** — write the tool name to `session/{sname}/agent/{aname}/tools` +- **See loaded tools** — read from `session/{sname}/agent/{aname}/tools` Once loaded, a tool becomes a first-class function. Call it directly by name with JSON arguments matching its schema. @@ -53,7 +53,7 @@ Skills are markdown modules that provide specialized domain knowledge, conventio **Procedure** — before reaching for `shell`, follow this sequence: 1. **Is a loaded tool already fit for purpose?** If so, use it directly. -2. **Search available tools** — check `session/{id}/agent/{aname}/tools` (read) to see what's available. Load any missing tool by writing its name there. +2. **Search available tools** — check `session/{sname}/agent/{aname}/tools` (read) to see what's available. Load any missing tool by writing its name there. 3. **Only if no tool exists** for the operation, fall back to `shell`. **Common mappings** (not exhaustive):