ollie/doc/architecture.md

Ollie Architecture

Ollie is a small Go runtime whose integration boundary is a 9P filesystem. The current architecture has one control-plane service, olliesrv, and a separate tool-execution service, toolsrv.

Boundaries

flowchart TB
    C[9P clients and frontends] --> S[olliesrv]
    S --> F[fs.Tree and session namespace]
    S --> A[agent loop]
    A --> B[provider backend]
    A --> T[toolsrv]
    T --> R[tool registry]
    T --> X[landrun / Landlock sandbox]
    T --> P[bypass broker]

olliesrv

The daemon constructs an fs.Tree. The tree is the session collection; there is no separate manager abstraction. Session operations are package functions over the tree. A session owns its agents, context, cancellation, and lifecycle. An agent owns history and runs the model/tool loop.

The daemon exposes the 9P namespace directly. Reads and writes are the protocol: writing session/new creates a session, writing an agent's prompt submits work, reading chat observes history, and reading statewait blocks until a state transition.

Agent loop

The loop resolves system and user prompts, renders context, calls the configured backend, parses streamed responses, executes requested tools, appends results to history, and repeats. context.Context cancellation flows from the daemon through the session and agent. Context management handles token statistics, output limits, retries, and compaction.

Toolsrv

toolsrv is a separate process connected through 9P. It owns tool discovery, metadata, lazy registry loading, process lifecycle, output streaming, and sandbox invocation. Tool implementations are installed executables or scripts; they are not compiled into the agent loop. The same service can expose local and remotely deployed tools.

The tool namespace also provides process and sandbox state. Normal execution is restricted by configured Landlock/landrun policy. The bypass broker is a policy-controlled path for explicitly approved operations outside that policy.

Namespace

session/
├── new
├── idx
└── {session}/
    ├── plan
    ├── env
    └── agent/{agent}/
        ├── cfg ctl state statewait
        ├── prompt prompt.prev chat offset
        ├── fifo.in fifo.out
        ├── context systemprompt usage cost ctxsz models
        ├── tools toolsrv.loaded toolsrv.rev
        ├── tail
        └── proc/

The namespace is intentionally composable: Unix programs, editor integrations, shell scripts, and GUI clients can use the same operations without a client-specific RPC API. Authentication and permissions are provided by the 9P transport and the service's filesystem policy.

Configuration and data

Installed runtime data includes backend configuration, agent definitions, prompt templates, skills, and tool executables. The runtime resolves paths under the XDG configuration/data locations. OptMem owns persistent memory storage; the memory tools call it directly instead of maintaining a parallel Ollie store.

Multi-agent operation

subagent_spawn creates child agents with independent runtime state. Cascade-style fan-out and observer/feed agents are orchestration patterns built on the same session and 9P primitives, not a second agent runtime. Parent and child sessions exchange prompts and results through files.

Design constraints

The core deliberately avoids framework-heavy abstractions. Provider selection, tool discovery, sandboxing, and user interfaces are replaceable boundaries; the stable contract is the 9P namespace and its blocking read/write behavior.