diff --git a/9p b/9p index 6c07c30..b82e4d8 160000 --- a/9p +++ b/9p @@ -1 +1 @@ -Subproject commit 6c07c308e118f59e0e8e3caa537cf2e3bdb70608 +Subproject commit b82e4d857ac229e8960620a578a950c2019afa86 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..927805c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,179 @@ +# AGENTS.md + +Project-level context for AI agents working in this repository. + +## Project Overview + +Ollie is an AI agent runtime inspired by Plan 9: agent state and behaviors are exposed as files in a 9P namespace. Orchestration, scheduling, and UIs are external — shell scripts, editors, web apps. The core is minimal; capabilities come from composing scripts. + +## 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 +├── core/ (Go) Core library: agent loop, backends, tools, config +├── 9p/ (Go) 9P filesystem server (olliesrv) +├── dbus/ (Go) D-Bus session manager daemon (ollied) +├── acme/ (Go) Plan 9 acme editor frontend +├── httpgw/ (Go) HTTP-to-9P gateway +├── webui/ (TypeScript) Preact SPA browser frontend +├── kde/ (C++/Qt6) KDE integration: plasmoid, standalone GUI, Kate plugin, KRunner, tray +├── el/ (Elisp) Emacs frontend (ellie.el) +├── agents/ Agent config JSONs (loaded at runtime) +├── prompts/ System prompt templates (markdown) ← NOT used; see note below +├── tools/ Tool scripts (file_read, lsp_*, memory_*, etc.) +├── sandbox/ Landlock sandbox config YAML +├── scripts/ User-facing CLI scripts: +│ ├── s/ Session management (sh, bfg, ls, kill, ...) +│ ├── u/ Utilities (complete, optimize, cascade) +│ └── x/ Internal/plumbing (elevate, prime, bd, task) +├── doc/ Architecture docs, usage guide +├── contrib/ Community scripts +└── experiments/ Trial notes +``` + +### Canonical source for prompts/tools/skills + +Three locations have prompt and tool files. The **source of truth** depends on which component you're editing: + +| Location | Purpose | Deployed by | +|----------|---------|-------------| +| `9p/prompts/`, `9p/tools/` | Canonical source for the 9P server | `make -C 9p` installs to `~/.config/ollie/` | +| `9p/skills/`, `kde/skills/` | Shared `agent-skills` submodule (same repo in both) | `make data` copies to `~/.config/ollie/skills/` | +| `kde/prompts/`, `kde/tools/` | KDE-specific copies (may diverge for KDE-only tools like `gui_*`) | CMake install | +| Root `prompts/`, `tools/` | Top-level copies installed by `make data` from monorepo root | `make data` | + +The root-level `make data` target copies `agents/`, `prompts/`, `tools/`, `sandbox/` (and `skills/` from submodules) into `~/.config/ollie/`. **Do not edit `~/.config/ollie/` directly** — changes are overwritten on next install. + +When adding a new prompt/tool that should be available to all frontends, add it to both `9p/prompts/` (or `9p/tools/`) and the root `prompts/` (or `tools/`) directory. + +## Build System + +```bash +# From monorepo root: +make # build everything + install data/scripts +make core # just core library +make 9p # just 9P server +make dbus # just D-Bus daemon +make httpgw # just HTTP gateway +make webui # just web UI (needs npm) +make data # install agents/prompts/tools/skills to ~/.config/ollie/ +make scripts # install CLI scripts + +# KDE (from kde/): +mkdir build-kf6 && cd build-kf6 && cmake .. && make + +# Individual Go submodules: +cd core && make +cd 9p && make +cd dbus && make +``` + +There's also a Plan 9 `mkfile` at the root and in submodules for `mk` users. + +## Testing + +```bash +# Go tests (from any Go submodule): +go test ./... + +# Core has the most tests: +cd core && go test ./... + +# 9P server tests: +cd 9p && go test ./... + +# KDE has integration test scripts: +cd kde && ./test-e2e.sh +``` + +## Language & Conventions + +- **Go** (core, 9p, dbus, acme, httpgw): Go 1.25+, standard library preferred, minimal dependencies. Modules are `ollie` (core), `olliesrv` (9p), `ollie-dbus`, `ollie-acme`, `ollie-httpgw`. +- **C++20/Qt6/KF6** (kde): CMake build, dual Qt5/Qt6 support where noted. +- **TypeScript** (webui): Vite + Preact. +- **Elisp** (el): single file `ellie.el`. +- **Tool scripts**: Python 3 or Bash. Must be executable. Header comments declare metadata (`# ollie:parallel read`, `# ollie:tier cold`, `# description:`, `# args:`). + +### Code style +- Go: `gofmt`, short variable names, error returns (no panics), table-driven tests. +- 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. **9P namespace**: Everything is a file. Sessions live at `s/{name}/`, memory at `m/`, skills at `sk/`, tools discovered from `OLLIE_TOOLS_PATH`. +2. **Agent loop** (`core/pkg/agent/`): Streaming LLM call → parse tool calls → dispatch → loop until no more tool calls or max steps. +3. **Tool dispatch** (`core/pkg/tools/`): `execute_code` is built-in. All others are external scripts resolved from `OLLIE_TOOLS_PATH`. +4. **Sandbox** (`core/internal/sandbox/`): Landlock-based. Config in `sandbox/*.yaml` defines filesystem access per profile. +5. **Backends** (`core/pkg/backend/`): Ollama, OpenAI-compatible, Anthropic, Copilot, Kiro. Selectable per-session. +6. **Prompts assembled at runtime**: Agent JSON `prompt` array runs shell commands (via `x/prime`) that cat markdown files together. No static prompt file is used directly. +7. **D-Bus** (kde/dbus only): `ollied` exposes `org.ollie.SessionManager` for KDE frontends. It's a separate daemon from `olliesrv`. + +## Key Files + +| What | Where | +|------|-------| +| Agent loop | `core/pkg/agent/loop.go` | +| Tool dispatcher | `core/pkg/tools/execute/` | +| Sandbox enforcement | `core/internal/sandbox/` | +| 9P filesystem | `9p/fs/` | +| Session management | `9p/session/` | +| System prompt template | `9p/prompts/SYSTEM_PROMPT.md` (or `prompts/SYSTEM_PROMPT.md`) | +| Agent configs | `agents/*.json` | +| D-Bus daemon | `dbus/main.go` | +| KDE D-Bus client | `kde/plasmoid/plugin/olliedbusclient.cpp` | +| Standalone GUI | `kde/gui/` | +| Kate plugin | `kde/kate/` | + +## Environment + +Config lives in `~/.config/ollie/env`. Key variables: +- `OLLIE_BACKEND` — default backend (ollama, openai, anthropic, copilot, kiro) +- `OLLIE_MODEL` — default model +- `OLLIE_TOOLS_PATH` — where tool scripts live (default: `~/.config/ollie/tools`) +- `OLLIE_MEMORY_PATH` — persistent memory directory +- `OLLIE_ENABLED_BACKENDS` — backends available for routing +- `OLLIE_TIER_WORKER_*` / `OLLIE_TIER_EXPERT_*` — per-backend model tiers + +## Adding a new tool + +1. Create an executable script in `tools/` (and `9p/tools/`, `kde/tools/` if needed) +2. Add header comments: `# description:`, `# args:`, optionally `# ollie:parallel read` or `# ollie:tier cold` +3. Create a matching `prompts/tools-*.md` documentation file (and in `9p/prompts/`, `kde/prompts/`) +4. Run `make data` to install + +## Adding a new prompt + +1. Write the markdown file in `9p/prompts/` and root `prompts/` +2. If it should be loaded by default, add a `$OLLIE_CFG_PATH/scripts/x/prime ` entry to `agents/default.json` +3. Run `make data` to install + +## Submodule workflow + +```bash +# Update all submodules: +git submodule update --remote --merge + +# Work in a submodule (e.g., core): +cd core +# ... make changes, commit ... +git push +cd .. +git add core +git commit -m "update core submodule" +``` + +Each submodule has its own remote at `ssh://lkn@lneely.de:44220/lkn/ollie-{name}.git`. + +### Nested submodules + +Both `9p/` and `kde/` contain a nested `skills/` submodule pointing to the same repo (`agent-skills.git`). There is no root-level `skills/` directory. + +``` +9p/skills/ → ssh://lkn@lneely.de:44220/lkn/agent-skills.git +kde/skills/ → ssh://lkn@lneely.de:44220/lkn/agent-skills.git (same repo) +``` + +When cloning, use `--recurse-submodules` or run `git submodule update --init --recursive` to get these. diff --git a/kde b/kde index 5eb8f49..4a29efc 160000 --- a/kde +++ b/kde @@ -1 +1 @@ -Subproject commit 5eb8f49d154504c880a9f667058f0c0951bb5d1c +Subproject commit 4a29efc1212164c2c83ec246ba8ba9cbe05c11b1