docs: replace all session/{id} and {sid} with {sname}
This commit is contained in:
Ollie Agent
parent
3a8e3f3c63
commit
1a2ad14f6b
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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 <path> — change the working directory
|
||||
# model <name> — switch model
|
||||
# backend <name> — 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}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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):
|
||||
|
|
|
|||
Loading…
Reference in New Issue