# 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.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
just
```