lkn
/
ollie
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ollie/doc/architecture.md

5.6 KiB
Raw Blame History

Ollie Architecture

Ollie is a Go runtime built around a 9P filesystem. olliesrv owns the agent runtime and public control namespace. toolsrv is a separate 9P service for tool discovery and execution.

Current system

9P clients
   │
   ▼
olliesrv ── sessions, agents, prompts, history, backends
   │
   └─ authenticated 9P ── toolsrv ── registry, sandbox, processes
                                      └─ executable or metadata-only tools

The filesystem is the integration boundary. Editors, shells, GUIs, scripts, and external automation use the same 9P namespace. They do not require a second API or a parallel session store.

olliesrv

olliesrv constructs the virtfs tree and serves the Ollie namespace. It owns:

  • session and agent lifecycle;
  • agent configuration, prompts, history, and context management;
  • provider backend selection and model calls;
  • the agent turn loop and internal session event bus;
  • persistence and restoration of sessions; and
  • the public 9P control surface.

An agent turn streams a backend response, executes requested tools through toolsrv, appends results to history, and repeats until the turn completes, is interrupted, or reaches a configured limit. History compaction and hot/warm/cold tool-result handling are part of the agent runtime.

toolsrv

toolsrv runs as a separate process. Its authenticated 9P namespace owns:

  • metadata discovery and host-specific variants;
  • per-agent tool loading and registry revisions;
  • executable and metadata-only command resolution;
  • foreground and background process lifecycle;
  • bounded output and result delivery;
  • sandbox and Landlock/landrun policy; and
  • bypass requests and approval state.

The agent-side ToolsrvConn calls toolsrv over authenticated 9P. Tool implementations are not compiled into the agent loop. A session may use a local toolsrv or an SSH-forwarded remote toolsrv; the agent runtime remains local in either case.

9P surface

The Ollie namespace exposes sessions and agents as files:

Path Use
session/new Create a session.
session/{sname}/agent/new Create an agent or child agent.
session/{sname}/agent/{aname}/prompt Submit a prompt.
session/{sname}/agent/{aname}/chat Read rendered chat.
session/{sname}/agent/{aname}/chat.raw Read raw chat events.
session/{sname}/agent/{aname}/statewait Block until agent state changes.
session/{sname}/agent/{aname}/feed Deliver change-detected observer input.
session/{sname}/agent/{aname}/ctl Control the agent.
session/{sname}/agent/{aname}/proc/ Inspect and control processes.
generate Perform one-shot generation with rdwr.

The namespace also exposes root metadata, backend/model listings, help, events, session controls, and agent configuration. See architecture-9p.md for the complete namespace and client patterns.

A typical request is:

client writes agent/.../prompt
  → olliesrv runs the agent turn
  → agent calls toolsrv when needed
  → toolsrv executes the selected tool
  → agent updates history and chat
  → client reads chat or waits on statewait

feed and statewait support observer and companion patterns without a separate observer service. A client can be a shell command, an editor extension, ollie-gui, a terminal, or another 9P client.

Shared filesystem implementation

virtfs provides the declaration API and in-memory tree used to build the 9P namespaces. Ollie declares nodes with closure-based handlers and dynamic bindings, then passes the declaration to virtfs.BuildTree. The transport and namespace declaration remain separate.

Configuration and external integrations

Backend credentials, endpoints, models, and compaction models are configured in backends.conf. Runtime paths follow XDG locations. Persistent memory is provided by OptMem through tools.

Remote execution moves toolsrv and tool execution to another host through SSH-forwarded authenticated 9P. The agent loop, prompts, history, and model calls stay local. See architecture-remote.md.

Editors and other clients integrate by obtaining context, writing an agent prompt, and using any convenient client for observation and control. See architecture-ide.md.

Deliberate boundaries

Ollie does not embed MCP, a tool framework, a planner/executor engine, a task graph, a scheduler, a public coordination bus, a frontend control plane, distributed agent state, or a competing memory store. These are integration concerns. External systems provide their specialized state and semantics through tools, sessions, scripts, and 9P.

Documentation map