# 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. Peer links (`peer/` directory) provide topology-controlled inter-agent messaging within a session.

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
            ├── state       current state (idle, calling, thinking, paused)
            ├── status      human-readable status
            ├── prompt      submit a prompt
            ├── peer/       write to peer/{name} to message a peer agent
            ├── 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
```

## Architecture completeness

Ollie's core architecture is complete. Every capability — browser automation, audio processing, RAG, scheduled tasks, database access, external service integrations — is achievable by writing a tool. The runtime provides:

- **Multi-modal tool results**: Tools return structured JSON with text and image content blocks
- **Multi-modal message handling**: Backends handle images in both directions
- **Arbitrary tool complexity**: Tools are executables that can spawn browsers, call APIs, run ML models
- **Long-running operations**: Background processes and sub-agents for parallel/delegated work
- **External triggers**: The 9P namespace is writable — cron, systemd, or scripts can prompt agents
- **Local embeddings**: The `embedding.Model` infrastructure exists for semantic operations

There are no architectural gaps. Missing features are missing tools.

## 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. Each agent profile declares its tools via `autoLoad`; the model sees only the capabilities configured for its role.

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.

## Frontends

Shell scripts, KDE components, and other clients create sessions, write prompts, and read files such as `chat`, `state`, and `feed`. They subscribe to state changes via the `event` stream. 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/lessons-learned.md`](doc/lessons-learned.md) for durable engineering lessons. See [`doc/usage.md`](doc/usage.md) for setup.

## Dependencies

Ollie does **not** require [plan9port](https://9fans.github.io/plan9port/), either explicitly or implicitly. This was previously required by the runtime and is no longer true. Ollie includes its own Go 9P protocol implementation, clients, and namespace management. `olliesrv` creates its namespace directory and removes it only when empty.

plan9port provides valuable additional tools and integrations, including Acme and general-purpose 9P utilities, but those are optional. The core Ollie runtime, `ollie-9p`, `toolsrv`, and native clients do not depend on plan9port or `$PLAN9`.

The standard build requires Go 1.25+ and GNU Make. The optional KDE integration additionally requires CMake, Qt, and KDE Frameworks.

## Build

```sh
make
```

The top-level Makefile builds the Go services and tools, then delegates KDE/Qt
compatibility to `kde/CMakeLists.txt`, which builds against KF6/Qt6.

## 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>

## Future work

### Portable olliesrv

`olliesrv` is currently portable apart from a small number of host-specific process and desktop-integration details. Future work may remove those assumptions so the agent runtime can run directly on BSD systems, macOS, and other Unix-like platforms, independently of the platform-specific `toolsrv` implementation.

### 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` and `toolsrv` should be portable independently, with `toolsrv` remaining the platform-dependent execution boundary. WSL2 should work through its Linux kernel and use the existing Linux implementation.