80 lines
3.8 KiB
Markdown
80 lines
3.8 KiB
Markdown
# Ollie
|
|
|
|
Ollie is an AI agent runtime built around a 9P virtual filesystem. The runtime service, `olliesrv`, exposes sessions, agents, prompts, state, history, tools, and control operations as files. Frontends remain thin clients of that interface.
|
|
|
|
```text
|
|
frontends (shell, Acme, KDE, scripts)
|
|
│ 9P
|
|
▼
|
|
olliesrv
|
|
┌──────┼──────┐
|
|
sessions agents fs tree
|
|
│
|
|
agent loop
|
|
│
|
|
provider backends
|
|
│
|
|
toolsrv (9P)
|
|
┌────┴────┐
|
|
tools sandbox
|
|
│
|
|
bypass broker
|
|
```
|
|
|
|
## Runtime model
|
|
|
|
- `olliesrv` owns the in-memory 9P tree and session collection.
|
|
- Each session owns one or more agents. Agents maintain configuration, state, prompts, chat history, rendered context, usage, and cost.
|
|
- The agent loop sends context to the configured provider, dispatches tool calls, updates history, and repeats until completion or cancellation.
|
|
- Child agents are ordinary agents created through the session namespace and communicate through prompt/result files.
|
|
|
|
The 9P namespace is the API:
|
|
|
|
```text
|
|
session/
|
|
├── new create a session by writing key=value arguments
|
|
├── idx tab-separated session index
|
|
└── {session}/
|
|
├── plan persistent Markdown checklist
|
|
├── env session environment
|
|
└── agent/{agent}/
|
|
├── cfg configuration
|
|
├── ctl control commands
|
|
├── state current state
|
|
├── statewait block until state changes
|
|
├── prompt submit a prompt
|
|
├── chat conversation history
|
|
├── context rendered model context
|
|
├── systemprompt rendered system prompt
|
|
├── tools tool discovery and loading
|
|
├── usage token statistics
|
|
├── cost cost estimate
|
|
└── proc/ detached process output
|
|
```
|
|
|
|
## Providers, tools, and security
|
|
|
|
Provider backends are the model-facing boundary; the agent loop is independent of vendor APIs. Tools are external executable programs served by the separate `toolsrv` 9P process. Their metadata is discovered and loaded lazily, so the model sees only the capabilities needed for a task.
|
|
|
|
Tool execution uses the configured Landlock/landrun sandbox. Operations requiring an approved escape use the bypass namespace and broker, which applies policy and approval controls rather than providing an unrestricted escape.
|
|
|
|
Persistent memory is provided by [OptMem](https://github.com/VictorTaelin/OptMem) through `memory_recall` and `memory_remember`; Ollie does not maintain a second memory-file format. History management renders context, tracks usage and cost, caps oversized tool output, and compacts older material when necessary.
|
|
|
|
## Frontends
|
|
|
|
Shell scripts, Acme, KDE components, and other clients create sessions, write prompts, and read files such as `chat`, `statewait`, `context`, and `feed`. They do not embed provider, tool, or agent-loop logic.
|
|
|
|
See [`doc/architecture-ide.md`](doc/architecture-ide.md) for integrating Ollie with an editor or IDE.
|
|
|
|
See [`doc/architecture.md`](doc/architecture.md) for component boundaries and [`doc/evolution.md`](doc/evolution.md) for the design history. See [`doc/usage.md`](doc/usage.md) for setup.
|
|
|
|
## Build
|
|
|
|
```sh
|
|
make
|
|
```
|
|
|
|
The top-level Makefile builds the Go services and tools, then delegates KDE/Qt
|
|
compatibility to `kde/CMakeLists.txt`. CMake detects KF6 first and falls back
|
|
to KF5; use `make kde-kf5` to force the KF5/Qt5 build.
|