119 lines
4.7 KiB
Markdown
119 lines
4.7 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.
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
B["olliesrv<br/>9P namespace · session lifecycle · agent runtime<br/>prompt + history · backend dispatch"]
|
|
|
|
S1["Session A (toolsrv)<br/>host + cwd"]
|
|
S2["Session B (toolsrv)<br/>host + cwd"]
|
|
S3["Session C (toolsrv)<br/>host + cwd"]
|
|
SX["(...)"]
|
|
|
|
B --- S1
|
|
B --- S2
|
|
B --- S3
|
|
B --- SX
|
|
|
|
A1["Agent 1"]
|
|
A2["Agent 2"]
|
|
A3["Agent 3"]
|
|
A4["Agent 4"]
|
|
A5["Agent 5"]
|
|
A6["Agent 6"]
|
|
AN["Agent N"]
|
|
AX["(...)"]
|
|
|
|
S1 --- A1
|
|
S1 --- A2
|
|
S2 --- A3
|
|
S2 --- A4
|
|
S3 --- A5
|
|
S3 --- A6
|
|
SX --- AN
|
|
SX --- AX
|
|
|
|
classDef brain fill:#d66b3d,stroke:#642b1c,color:#fff,stroke-width:4px;
|
|
classDef session fill:#e7c65c,stroke:#67551b,color:#211b08;
|
|
classDef agent fill:#c7d4eb,stroke:#354a70,color:#172033;
|
|
|
|
class B brain;
|
|
class S1,S2,S3,SX session;
|
|
class A1,A2,A3,A4,A5,A6,AN,AX agent;
|
|
```
|
|
|
|
## 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}/
|
|
├── goal session goal text (triggers workflow on write)
|
|
├── goalstatus goal status (running/complete/blocked)
|
|
├── goalwait blocks until goal status changes
|
|
├── env session environment
|
|
└── agent/
|
|
├── new create agent by writing key=value
|
|
├── idx tab-separated agent index
|
|
└── {agent}/
|
|
├── plan persistent Markdown checklist
|
|
├── 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.
|
|
|
|
## Why an Octopus?
|
|
|
|
- Octopuses are intelligent
|
|
- Ollie has tentacles
|
|
- Ollie starts with "o"
|
|
- Ollie-ollie-octopus!
|
|
|
|
<p>
|
|
<img src="./doc/img/ollie.svg" alt="Ollie" width="200" height="200">
|
|
</p>
|