AGENTS.md: update for current architecture
Fix all stale references: fsedsl→virtfs, handlers_*.go→inline spec.go, flat package layout→cmd/olliesrv/internal/*, etc.
This commit is contained in:
Ollie Agent
parent
066659b8b6
commit
e58f76c578
86
AGENTS.md
86
AGENTS.md
|
|
@ -11,29 +11,37 @@ Ollie is an AI agent runtime inspired by Plan 9: agent state and behaviors are e
|
|||
## Repository Layout
|
||||
Monorepo with Git submodules. Each submodule has its own Go module (except `el` which is Elisp and `kde` which is C++/Qt).
|
||||
```
|
||||
ollie/ ← you are here
|
||||
├── agent/ (Go) Agent loop, history, hooks, commands
|
||||
├── toolsrv/ (Go) Tool server, registry, sandboxed execution
|
||||
├── session/ (Go) Session lifecycle, config, persistence
|
||||
├── fs/ (Go) 9P filesystem tree (EDSL-declared)
|
||||
│ ├── spec.go Single source of truth — entire namespace declared here
|
||||
│ ├── fsnode.go Core FsNodeDecl type + Dir/Leaf/TemplateDir constructors
|
||||
│ └── handlers_*.go Read/write handlers grouped by scope (session, agent, root)
|
||||
├── fsedsl/ (Go) Filesystem declaration EDSL (generic, reusable)
|
||||
│ └── builder.go BuildTree — walks spec, validates, produces *Tree
|
||||
├── cmd/ (Go) Binaries (olliesrv, ollie-9p, ollie-remote)
|
||||
├── tools/ (Go) Tool implementations:
|
||||
│ └── lsp/ LSP bridge + cmd/ binaries (definition, hover, rename, ...)
|
||||
├── kde/ (C++/Qt6) KDE integration: plasmoid, GUI, Kate plugin, KRunner, tray
|
||||
├── contrib/elisp (Elisp) Emacs frontend (ellie.el)
|
||||
├── data/agents/ Agent config JSONs (loaded at runtime)
|
||||
├── data/prompts/ System prompt templates (markdown)
|
||||
├── data/tools/ Tool executables + .meta sidecar files (installed to $XDG_CONFIG_HOME/ollie/tools)
|
||||
├── data/skills/ Domain knowledge modules (markdown)
|
||||
├── sandbox/ Landlock sandbox config YAML
|
||||
├── doc/ Architecture docs, usage guide
|
||||
├── contrib/ Community scripts
|
||||
└── experiments/ Trial notes
|
||||
ollie/ ← you are here
|
||||
├── virtfs/ (Go module) Virtual filesystem EDSL (FsNodeDecl, BuildTree, Tree)
|
||||
├── toolsrv/ (Go) Tool server client library (Conn, Dial)
|
||||
├── cmd/
|
||||
│ ├── olliesrv/ (Go) 9P server binary
|
||||
│ │ └── internal/
|
||||
│ │ ├── fs/ 9P namespace (everything in spec.go)
|
||||
│ │ │ ├── spec.go Single source of truth — entire namespace + handlers
|
||||
│ │ │ └── support.go Shared utilities (streamChat, stripMarkers, dispatch)
|
||||
│ │ ├── agent/ Agent loop, history, hooks
|
||||
│ │ ├── session/ Session lifecycle, persistence
|
||||
│ │ ├── backend/ LLM backends (ollama, openai, anthropic, etc.)
|
||||
│ │ └── bypass/ Sandbox bypass broker
|
||||
│ ├── toolsrv/ (Go) Tool server binary (sandboxed execution)
|
||||
│ │ └── internal/
|
||||
│ │ ├── fs/ toolsrv 9P namespace (spec.go)
|
||||
│ │ └── sandbox/ Landlock enforcement
|
||||
│ ├── ollie-9p/ (Go) CLI client for the 9P namespace
|
||||
│ └── ollie-remote/ (Go) Remote execution agent
|
||||
├── tools/ (Go) Tool implementations:
|
||||
│ └── lsp/ LSP bridge + cmd/ binaries
|
||||
├── kde/ (C++/Qt6) KDE integration: GUI, Kate plugin, KRunner, tray
|
||||
├── contrib/elisp (Elisp) Emacs frontend (ellie.el)
|
||||
├── data/agents/ Agent config JSONs (loaded at runtime)
|
||||
├── data/prompts/ System prompt templates (markdown)
|
||||
├── data/tools/ Tool executables + .meta sidecar files
|
||||
├── data/skills/ Domain knowledge modules (markdown)
|
||||
├── sandbox/ Landlock sandbox config YAML
|
||||
├── doc/ Architecture docs, usage guide
|
||||
├── contrib/ Community scripts
|
||||
└── experiments/ Trial notes
|
||||
```
|
||||
### Canonical source for prompts/tools/skills
|
||||
|
||||
|
|
@ -95,25 +103,27 @@ just test-remote
|
|||
- 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/{sname}/agent/{aname}/`. All control via `ctl` (rdwr: write command, read response). 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 `$XDG_CONFIG_HOME/ollie/tools`. Load via `ctl tool_load <name>`.
|
||||
4. **Sandbox** (`sandbox/`): Landlock-based. Config in `sandbox/*.yaml` defines filesystem access per profile. Escape via bypass broker (`bypass/`).
|
||||
5. **Backends** (`backend/`): Ollama, OpenAI-compatible, Anthropic, Copilot, Kiro, Gemini, CodeWhisperer. Selectable per-session.
|
||||
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.
|
||||
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>`.
|
||||
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/`).
|
||||
5. **Backends** (`cmd/olliesrv/internal/backend/`): Ollama, OpenAI-compatible, Anthropic, Copilot, Kiro, Gemini. Selectable per-session.
|
||||
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.
|
||||
7. **9P namespace declared via EDSL**: The entire filesystem is a single recursive `FsNodeDecl` tree in `fs/spec.go`, built by `BuildTree()` in `fsedsl/builder.go`. The `fs/` package is flat — handlers in `handlers_*.go`, ctl dispatch in `ctl.go`. See `doc/edsl.md` for the full reference.
|
||||
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.
|
||||
## Key Files
|
||||
| What | Where |
|
||||
|------|-------|
|
||||
| Agent loop | `agent/loop.go` |
|
||||
| Tool server | `toolsrv/server.go` |
|
||||
| Remote execution | `toolsrv/remote.go`, `cmd/ollie-remote/` |
|
||||
| Sandbox enforcement | `sandbox/` |
|
||||
| 9P filesystem (EDSL spec) | `fs/spec.go` |
|
||||
| 9P filesystem (builder) | `fsedsl/builder.go` |
|
||||
| Session management | `session/session.go` |
|
||||
| System prompt template | Embedded in binary |
|
||||
| Agent configs | `agents/*.json` |
|
||||
| Standalone GUI | `kde/gui/` |
|
||||
| 9P namespace (olliesrv) | `cmd/olliesrv/internal/fs/spec.go` |
|
||||
| 9P namespace (toolsrv) | `cmd/toolsrv/internal/fs/spec.go` |
|
||||
| virtfs EDSL | `virtfs/decl.go`, `virtfs/builder.go` |
|
||||
| Agent loop | `cmd/olliesrv/internal/agent/loop.go` |
|
||||
| Tool server binary | `cmd/toolsrv/` |
|
||||
| Tool server client | `toolsrv/client9p.go` |
|
||||
| Remote execution | `cmd/ollie-remote/` |
|
||||
| Sandbox enforcement | `cmd/toolsrv/internal/sandbox/` |
|
||||
| Session management | `cmd/olliesrv/internal/session/` |
|
||||
| System prompt template | Embedded in binary (`cmd/olliesrv/internal/prompts/`) |
|
||||
| Agent configs | `data/agents/*.json` |
|
||||
| KDE GUI | `kde/gui/` |
|
||||
| Kate plugin | `kde/kate/` |
|
||||
## Environment
|
||||
Config lives in `~/.config/ollie/env`. Key variables:
|
||||
|
|
|
|||
Loading…
Reference in New Issue