# Ollie 🐙

Ollie is a distributed, integrating 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 this 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

`session/new` accepts `name`, `remote`, `workflow`, `cwd`, and `yolo=true` key/value fields. Session-level `yolo` is persisted and applies to local or remote toolsrv startup; it disables native Landlock enforcement for explicit development use. Normal tools use the configured native Landlock policy, while approved escape requests go through the bypass broker.

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 native Landlock 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.

### Future work: portable toolsrv hosts

`toolsrv` should be extensible to other host operating systems so Ollie tools remain useful on as many systems as possible. This includes the host-specific execution, filesystem, process, networking, and sandbox integrations required on BSD systems, macOS, and other Unix-like platforms. `olliesrv` may remain Linux-specific; its role is the agent runtime and orchestration service, while `toolsrv` is the platform-dependent execution boundary. WSL2 should work through its Linux kernel and use the existing Linux implementation.

## 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 (toolsrv+session+agents)
- Ollie collects shiny tools in his garden
- Ollie starts with `o` 🧐
- Ollie-ollie-octopus!

<p>
<img src="./doc/img/ollie.svg" alt="Ollie" width="200" height="200">
</p>