From ecbc93f3b4e36bcff25f6672ef71cdc52c6826f2 Mon Sep 17 00:00:00 2001 From: Ollie Agent Date: Sun, 19 Jul 2026 17:38:19 +0200 Subject: [PATCH] docs: update architecture for current 9P/D-Bus topology - Remove references to non-existent 9P paths (t/idx, sk/idx, m/, etc) - Update system overview diagram to show KDE/Web frontends over D-Bus - Show embedded D-Bus adapter in olliesrv and ollied alternative - Update tool/skill discovery references to use env vars - Update agent config example to current format --- doc/ARCHITECTURE.md | 63 ++++++++++++++++++++++----------------------- doc/MULTI_AGENT.md | 9 +++---- doc/NO_MCP.md | 2 +- doc/OBSERVATIONS.md | 2 +- doc/USAGE.md | 2 +- 5 files changed, 38 insertions(+), 40 deletions(-) diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md index 8949ab1..e67b055 100644 --- a/doc/ARCHITECTURE.md +++ b/doc/ARCHITECTURE.md @@ -34,25 +34,31 @@ ollie/ ## System Overview ``` -┌─────────────────────────────────────────────────────────────────┐ -│ Frontends │ -│ s/sh (terminal) │ acme │ ellie (Emacs) │ Web UI (Preact)│ -└────────┬──────────┴────┬───┴────────┬─────────┴───────┬─────────┘ - │ 9P direct │ 9P direct │ 9P direct │ HTTP - │ │ │ ▼ - │ │ │ ┌─────────────┐ - │ │ │ │ ollie-httpgw│ - │ │ │ └──────┬──────┘ - ▼ ▼ ▼ │ 9P -┌────────────────────────────────────────────────────────▼────────┐ -│ olliesrv (9P server) │ -│ ┌──────────┐ ┌──────────┐ ┌──────┐ ┌────┐ ┌────┐ ┌────┐ │ -│ │ Sessions │ │ Memory │ │Skills│ │Tmp │ │ Tr │ │ ...│ │ -│ │ s/ │ │ m/ │ │ sk/ │ │tmp/│ │tr/ │ │ │ │ -│ └────┬─────┘ └──────────┘ └──────┘ └────┘ └────┘ └────┘ │ -└───────┼─────────────────────────────────────────────────────────┘ +┌───────────────────────────────────────────────────────────────────────────┐ +│ Frontends │ +│ s/sh (terminal) │ acme │ ellie (Emacs) │ KDE GUI/plasmoid │ Web UI │ +└───────┬──────────┴───┬──┴───────┬───────┴────────┬─────────┴──────┬──────┘ + │ 9P │ 9P │ 9P │ D-Bus │ D-Bus + │ │ │ ▼ ▼ + │ │ │ ┌──────────────────────────────────┐ + │ │ │ │ org.ollie.SessionManager (D-Bus)│ + │ │ │ └──────────────┬───────────────────┘ + ▼ ▼ ▼ │ embedded adapter +┌───────────────────────────────────────────────────────▼───────────────────┐ +│ olliesrv (9P server + D-Bus adapter) │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Sessions │ │ backends │ │ models │ │ +│ │ s/ │ │ (file) │ │ (file) │ │ +│ └────┬─────┘ └──────────┘ └──────────┘ │ +└───────┼───────────────────────────────────────────────────────────────────┘ │ per-session ▼ + +Alternative: ollied (pure D-Bus daemon, no 9P — for dbus-only deployments) +┌───────────────────────────────────────────────────────────────────────────┐ +│ ollied (org.ollie.SessionManager) │ +│ Pure D-Bus session manager; same interface, no filesystem. │ +└───────────────────────────────────────────────────────────────────────────┘ ┌────────────────────────────────────────────────────────────────┐ │ agent.Core (per session) │ │ ┌─────────────┐ ┌──────────────┐ ┌────────────────────────┐ │ @@ -208,15 +214,7 @@ Agent configs declare prompts as a JSON array of shell commands. Each command is | `s/{id}/state` | Current state (idle/thinking/calling) | | `s/{id}/statewait` | Blocking read until state changes | | `s/{id}/plan` | Session-scoped markdown checklist | -| `s/{id}/t/` | Tool scripts visible to this session | -| `m/` | Persistent memory files | -| `sk/` | Domain skill files | -| `a/` | Agent definitions (JSON) | -| `p/` | Prompt templates | -| `u/` | Utility scripts | -| `x/` | System plugins and exec helpers | -| `tr/` | Saved transcripts | -| `tmp/` | Temporary storage | + ### Per-Agent 9P Principals @@ -381,15 +379,16 @@ Agent configs are JSON files in `~/.config/ollie/agents/`: ```json { "prompt": [ - "$OLLIE/x/prime SYSTEM_PROMPT", - "$OLLIE/x/prime tools-file", - "$OLLIE/x/prime tools-reasoning" + "$OLLIE_CFG_PATH/scripts/x/prime SYSTEM_PROMPT", + "$OLLIE_CFG_PATH/scripts/x/prime session", + "$OLLIE_CFG_PATH/scripts/x/prime agent-coding", + "$OLLIE_CFG_PATH/scripts/x/prime tools-file", + "$OLLIE_CFG_PATH/scripts/x/prime tools-reasoning" ], "hooks": { - "agentSpawn": ["$OLLIE/x/elevate start"], - "turnError": ["$OLLIE/x/freeloader"] + "agentSpawn": ["$OLLIE_CFG_PATH/scripts/x/elevate-adapter-start"], + "turnError": ["$OLLIE_CFG_PATH/scripts/x/freeloader $OLLIE_SESSION_ID"] }, - "trustedTools": ["escalate"], "maxTokens": 8192, "temperature": 0.7, "maxSteps": 50 diff --git a/doc/MULTI_AGENT.md b/doc/MULTI_AGENT.md index d04fcbd..0745ea6 100644 --- a/doc/MULTI_AGENT.md +++ b/doc/MULTI_AGENT.md @@ -30,11 +30,10 @@ Global namespaces are shared across all sessions: | Path | Purpose | |------|---------| -| `/s/{id}/t/{name}` | Tool scripts (read/write) | -| `/s/{id}/t/idx` | Synthesized tool index (descriptions + args) | -| `/a/{name}.json` | Agent configs (supports `mv`, `cp`, `rm`) | -| `/sk/{name}` | Skill files | -| `/p/{name}` | Prompt templates | +| `/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) | ## Spawning Agents diff --git a/doc/NO_MCP.md b/doc/NO_MCP.md index daf58a0..479bc67 100644 --- a/doc/NO_MCP.md +++ b/doc/NO_MCP.md @@ -20,7 +20,7 @@ The `x/elevate` plugin is a concrete example: it replaced an MCP server that ran | MCP feature | ollie equivalent | |---|---| -| `tools/list` (structured discovery) | `s/{id}/t/idx` (plain text index) + skills | +| `tools/list` (structured discovery) | `ls $OLLIE_TOOLS_PATH/` + `grep` for descriptions | | `tools/call` (invoke a tool) | `execute_code {tool: "name"}` | | JSON-RPC framing | stdin/stdout/exit code | | Subprocess lifecycle management | The sandbox manages process lifecycle | diff --git a/doc/OBSERVATIONS.md b/doc/OBSERVATIONS.md index 60fc449..2ca5992 100644 --- a/doc/OBSERVATIONS.md +++ b/doc/OBSERVATIONS.md @@ -12,7 +12,7 @@ **Radical transparency** — The rendered system prompt for any session is readable at `s/{id}/systemprompt` — the prompt the agent is actually running with, not a reconstruction. The prompt parts that compose it live in `p/`; the agent can read its own instructions but cannot modify them. -**Discoverability** — `ls s/{id}/` shows every control surface. `cat s/{id}/t/idx` and `cat sk/idx` list available tools and skills. `cat help` explains the rest. +**Discoverability** — `ls s/{id}/` shows every control surface. Tools live at `$OLLIE_TOOLS_PATH`, skills at `$OLLIE_SKILLS_PATH`. `cat help` explains the rest. **Composability** — `execute_code` stages chain the same way Unix pipes chain programs. Sessions chain by reading `s/{id}/chat` and writing to another session's `prompt` or `fifo.in`. diff --git a/doc/USAGE.md b/doc/USAGE.md index 79fc14a..1c86a62 100644 --- a/doc/USAGE.md +++ b/doc/USAGE.md @@ -456,7 +456,7 @@ filesystem layout, an agent can decompose the work, create the named sessions, w the coordination script to a temp file, and execute it — all in a single turn. The architecture documents (`ARCHITECTURE.md`, `USAGE.md`) and tool descriptions -(available via `s/{id}/t/idx`) are the agent's reference. No additional scaffolding is needed. +(available via `$OLLIE_TOOLS_PATH`) are the agent's reference. No additional scaffolding is needed. ## Store federation