AGENTS.md: fix duplicate section, update build targets, add toolsrv architecture
- Removed duplicated Submodule/Environment section - Updated build targets to match actual justfile - Added two-process model explanation (olliesrv + toolsrv) - Clarified that ALL tools go through toolsrv - Fixed data/agents path reference
This commit is contained in:
parent
e58f76c578
commit
d1ef2c946c
48
AGENTS.md
48
AGENTS.md
|
|
@ -55,23 +55,21 @@ Prompt and tool files live in `data/`. The `just install-data` target copies the
|
||||||
| `kde/` | KDE-specific tool scripts (`gui_*`) | `just install-kde` |
|
| `kde/` | KDE-specific tool scripts (`gui_*`) | `just install-kde` |
|
||||||
## Build System
|
## Build System
|
||||||
```bash
|
```bash
|
||||||
# Build everything:
|
# Build and install everything:
|
||||||
just
|
just
|
||||||
# Individual targets:
|
# Individual build targets:
|
||||||
just ninep # olliesrv + ollie-9p
|
just ninep # olliesrv + ollie-9p
|
||||||
just acme # acme frontend
|
just toolsrv # tool server binary
|
||||||
|
just core # core Go packages
|
||||||
just kde # KDE integration (cmake with ~/.local prefix)
|
just kde # KDE integration (cmake with ~/.local prefix)
|
||||||
just ollie-remote # remote execution binary
|
just lsp-tools # LSP tool binaries
|
||||||
# Install targets (run automatically by the top-level paths):
|
# Install targets:
|
||||||
just install-data # agents, prompts, tools, skills → ~/.config/ollie/
|
just install-data # agents, prompts, tools, skills → ~/.config/ollie/
|
||||||
just install-scripts # CLI scripts → ~/.config/ollie/scripts/
|
|
||||||
just install-contrib # contrib scripts → ~/bin/
|
|
||||||
just install-kde # KDE plugins, desktop file, env → ~/.local/
|
|
||||||
just install-el # ellie.el → ~/.config/emacs/ellie/
|
just install-el # ellie.el → ~/.config/emacs/ellie/
|
||||||
# Test:
|
# Test:
|
||||||
just test # run all tests
|
just test # run all tests
|
||||||
just test-core # core tests only
|
just test-core # core Go tests
|
||||||
just test-9p # 9p tests only
|
just test-9p # 9p integration tests
|
||||||
# Lifecycle:
|
# Lifecycle:
|
||||||
just uninstall # remove all installed files
|
just uninstall # remove all installed files
|
||||||
just clean # remove build artifacts
|
just clean # remove build artifacts
|
||||||
|
|
@ -103,12 +101,13 @@ just test-remote
|
||||||
- Prompts: markdown, concise, example-driven. Follow the pattern in existing `tools-*.md` files.
|
- Prompts: markdown, concise, example-driven. Follow the pattern in existing `tools-*.md` files.
|
||||||
## Architecture (key concepts)
|
## Architecture (key concepts)
|
||||||
1. **One integration surface**: 9P filesystem. Sessions at `session/{sname}/agent/{aname}/`. All control via `ctl` (rdwr: write command, read response). Tools, skills, memory on physical filesystem via env vars.
|
1. **One integration surface**: 9P filesystem. Sessions at `session/{sname}/agent/{aname}/`. All control via `ctl` (rdwr: write command, read response). Tools, skills, memory on physical filesystem via env vars.
|
||||||
2. **Agent loop** (`cmd/olliesrv/internal/agent/loop.go`): Streaming LLM call → parse tool calls → dispatch → loop until no more tool calls or max steps.
|
2. **Two-process model**: Each session runs an `olliesrv` (the 9P namespace, agent loop, backends) and a per-session `toolsrv` (sandboxed tool execution). They communicate over a Unix socket using 9P. The toolsrv is spawned by olliesrv at session creation and has its own namespace (`/proc/new`, `/ctl`, `/tools`, etc.).
|
||||||
3. **Tool dispatch** (`cmd/toolsrv/`): All tools execute remotely through a per-session tool server process. Tools are external scripts resolved from `$XDG_CONFIG_HOME/ollie/tools`. Load via `ctl tool_load <name>`.
|
3. **Agent loop** (`cmd/olliesrv/internal/agent/loop.go`): Streaming LLM call → parse tool calls → dispatch to toolsrv → loop until no more tool calls or max steps.
|
||||||
4. **Sandbox** (`cmd/toolsrv/internal/sandbox/`): Landlock-based. Config in `sandbox/*.yaml` defines filesystem access per profile. Escape via bypass broker (`cmd/olliesrv/internal/bypass/`).
|
4. **Tool dispatch**: ALL tools (including `reasoning_think`, `file_read`, `shell`) execute through the per-session toolsrv. The agent holds a `*toolsrv.Conn` (9P client) and calls `CallTool(name, args)` which writes to `proc/new` and reads the result. Tool registry is per-agent, keyed by agent ID in the protocol.
|
||||||
5. **Backends** (`cmd/olliesrv/internal/backend/`): Ollama, OpenAI-compatible, Anthropic, Copilot, Kiro, Gemini. Selectable per-session.
|
5. **Sandbox** (`cmd/toolsrv/internal/sandbox/`): Landlock-based. Config in `sandbox/*.yaml` defines filesystem access per profile. Escape via bypass broker (`cmd/olliesrv/internal/bypass/`).
|
||||||
6. **Prompts assembled at runtime**: Agent JSON `prompt` array specifies which prompt files to concatenate. Static prompt files can be included directly; the base system prompt is embedded in the binary and always prepended.
|
6. **Backends** (`cmd/olliesrv/internal/backend/`): Ollama, OpenAI-compatible, Anthropic, Copilot, Kiro, Gemini. Selectable per-session.
|
||||||
7. **9P namespace declared via virtfs EDSL**: The entire filesystem is a single recursive `FsNodeDecl` tree in `cmd/olliesrv/internal/fs/spec.go`, built by `virtfs.BuildTree()`. Every handler is an inline closure — no indirection.
|
7. **Prompts assembled at runtime**: Agent JSON `prompt` array specifies which prompt files to concatenate. The base system prompt is embedded in the binary and always prepended.
|
||||||
|
8. **9P namespace declared via virtfs EDSL**: The entire filesystem is a single recursive `FsNodeDecl` tree in `cmd/olliesrv/internal/fs/spec.go`, built by `virtfs.BuildTree()`. Every handler is an inline closure — no indirection. Same pattern in `cmd/toolsrv/internal/fs/spec.go`.
|
||||||
## Key Files
|
## Key Files
|
||||||
| What | Where |
|
| What | Where |
|
||||||
|------|-------|
|
|------|-------|
|
||||||
|
|
@ -155,7 +154,7 @@ Both paths produce the same result: an executable + `.meta` in `$XDG_CONFIG_HOME
|
||||||
The registry doesn't distinguish between scripts and binaries.
|
The registry doesn't distinguish between scripts and binaries.
|
||||||
## Adding a new prompt
|
## Adding a new prompt
|
||||||
1. Write the markdown file in `data/prompts/`
|
1. Write the markdown file in `data/prompts/`
|
||||||
2. If it should be loaded by default, reference it in `agents/default.json`
|
2. If it should be loaded by default, reference it in `data/agents/default.json`
|
||||||
3. Run `just install-data` to install
|
3. Run `just install-data` to install
|
||||||
## Submodule workflow
|
## Submodule workflow
|
||||||
The only remaining submodule is `kde/`. For KDE:
|
The only remaining submodule is `kde/`. For KDE:
|
||||||
|
|
@ -172,18 +171,3 @@ git commit -m "update kde submodule"
|
||||||
```
|
```
|
||||||
Each submodule has its own remote at `ssh://lkn@lneely.de:44220/lkn/ollie-{name}.git`.
|
Each submodule has its own remote at `ssh://lkn@lneely.de:44220/lkn/ollie-{name}.git`.
|
||||||
When cloning, use `--recurse-submodules` or run `git submodule update --init --recursive`.
|
When cloning, use `--recurse-submodules` or run `git submodule update --init --recursive`.
|
||||||
## Environment
|
|
||||||
The only remaining submodule is `kde/`. For KDE:
|
|
||||||
```bash
|
|
||||||
# Update KDE submodule:
|
|
||||||
git submodule update --remote --merge kde
|
|
||||||
# Work in the KDE submodule:
|
|
||||||
cd kde
|
|
||||||
# ... make changes, commit ...
|
|
||||||
git push
|
|
||||||
cd ..
|
|
||||||
git add kde
|
|
||||||
git commit -m "update kde submodule"
|
|
||||||
```
|
|
||||||
Each submodule has its own remote at `ssh://lkn@lneely.de:44220/lkn/ollie-{name}.git`.
|
|
||||||
When cloning, use `--recurse-submodules` or run `git submodule update --init --recursive`.
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue