add AGENTS.md, update 9p/kde submodules (tools-image prompt)
This commit is contained in:
Ollie Agent
parent
a54f33d0fb
commit
2cb468bd33
2
9p
2
9p
|
|
@ -1 +1 @@
|
|||
Subproject commit 6c07c308e118f59e0e8e3caa537cf2e3bdb70608
|
||||
Subproject commit b82e4d857ac229e8960620a578a950c2019afa86
|
||||
|
|
@ -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 <name>` 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.
|
||||
2
kde
2
kde
|
|
@ -1 +1 @@
|
|||
Subproject commit 5eb8f49d154504c880a9f667058f0c0951bb5d1c
|
||||
Subproject commit 4a29efc1212164c2c83ec246ba8ba9cbe05c11b1
|
||||
Loading…
Reference in New Issue