79 lines
6.8 KiB
Markdown
79 lines
6.8 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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 subscribing to the `event` stream monitors state transitions.
|
|
|
|
### 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`](architecture-tools.md) and [`architecture-toolsrv.md`](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](https://github.com/steveyegge/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`, `event`, 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`](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`](architecture-remote.md).
|
|
- **A competing memory store.** [OptMem](https://github.com/VictorTaelin/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`](architecture-9p.md) — public 9P transport, namespace, clients, permissions, and lifecycle.
|
|
- [`architecture-core.md`](architecture-core.md) — agent loop, sessions, history, backends, hooks, and concurrency.
|
|
- [`architecture-prompting.md`](architecture-prompting.md) — prompt resolution and runtime preamble assembly.
|
|
- [`architecture-tools.md`](architecture-tools.md) — tool metadata and authoring, including metadata-only tools.
|
|
- [`architecture-embedding.md`](architecture-embedding.md) — semantic tool and skill discovery.
|
|
- [`lessons-learned.md`](lessons-learned.md) — durable engineering lessons and design principles.
|
|
- [`architecture-toolsrv.md`](architecture-toolsrv.md) — tool registry, 9P service, process execution, sandbox, and cancellation.
|
|
- [`architecture-remote.md`](architecture-remote.md) — SSH deployment of a remote toolsrv.
|
|
- [`architecture-virtfs.md`](architecture-virtfs.md) — the declaration DSL and in-memory filesystem tree.
|
|
- [`architecture-kde.md`](architecture-kde.md) — KDE/Qt clients and integration.
|
|
- [`architecture-ide.md`](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](https://github.com/VictorTaelin/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 is an orchestration pattern 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. |