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]
    R --> E[embedding index]
    E --> M[local ONNX embedding model]
    T --> X[native Landlock sandbox helper]
    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.

Agent-side semantic discovery uses the shared embedding and skills packages to index tool metadata and skill descriptions. A local all-MiniLM-L6-v2 ONNX model ranks descriptions against the user request with cosine similarity. Only high-scoring, bounded results are injected: up to five tool hints and three skill definitions. This keeps prompts small while making discovery effective when a request does not use the exact tool or skill name. The embedding model is local and independent of the conversational backend.

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

Deliberately unimplemented agent patterns

Ollie deliberately does not build the following into the agent runtime:

• Native MCP client support. Use executable or metadata-only tools. An external bridge can invoke an MCP client when required.
• Embedded tool frameworks. Tools live outside the agent loop; toolsrv owns discovery, loading, execution, sandboxing, and process state. See architecture-tools.md and architecture-toolsrv.md.
• Plan-and-execute workflow engines. Ollie does not own planners, task graphs, schedulers, retries, compensation, or durable workflow state. A system such as Beads can expose those capabilities through a tool.
• External coordination protocols. Ollie does not expose a workflow engine, actor framework, master coordinator, or public message bus. It does have an internal session event bus for observers. Inter-agent communication uses peer links (peer/ directory) for topology-controlled messaging within a session. External coordination uses sessions, agents, prompt, chat, statewait, feed, and ctl.
• Separate frontend control planes. UIs, editor integrations, shell clients, and automation are 9P clients. They do not maintain a parallel session store or frontend-specific API. See architecture-9p.md.
• Distributed agent state. Remote execution moves toolsrv and tool execution, not the agent loop, prompts, history, or model calls. See architecture-remote.md.
• A competing memory store. OptMem owns persistent memory; Ollie exposes it through tools.

All of these are integration concerns, not built-in concerns. External systems own their specialized state and semantics; toolsrv provides execution; Ollie provides the agent, sessions, prompts, and 9P observation/control surface. New behavior should first be expressed as a tool, a 9P file operation, a session, or a shell workflow before adding a runtime subsystem.

Documentation map

The architecture is split by responsibility:

• architecture-9p.md — public 9P transport, namespace, clients, permissions, and lifecycle.
• architecture-core.md — agent loop, sessions, history, backends, hooks, and concurrency.
• architecture-prompting.md — prompt resolution and runtime preamble assembly.
• architecture-tools.md — tool metadata and authoring, including metadata-only tools.
• architecture-embedding.md — semantic tool and skill discovery.
• lessons-learned.md — durable engineering lessons and design principles.
• architecture-toolsrv.md — tool registry, 9P service, process execution, sandbox, and cancellation.
• architecture-remote.md — SSH deployment of a remote toolsrv.
• architecture-virtfs.md — the declaration DSL and in-memory filesystem tree.
• architecture-kde.md — KDE/Qt clients and integration.
• architecture-ide.md — Editor integration.

Configuration and data

Installed runtime data includes backend configuration, agent definitions, prompt templates, skills, and tool executables. Backend credentials, endpoints, models, and compaction models are configured in backends.conf. Runtime paths follow XDG configuration and data locations. OptMem owns persistent memory storage; memory tools call it directly.

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 stable integration boundary is the 9P namespace and its blocking read/write behavior. Provider selection, prompt assembly, tool discovery, sandboxing, remote execution, and user interfaces are replaceable boundaries documented separately.