From 2e3680e33a76e484830bc337070f7f16f384dbab Mon Sep 17 00:00:00 2001 From: Ollie Agent Date: Sun, 16 Aug 2026 20:08:30 +0200 Subject: [PATCH] Summarize integration boundaries --- doc/architecture.md | 57 +++++++-------------------------------------- 1 file changed, 9 insertions(+), 48 deletions(-) diff --git a/doc/architecture.md b/doc/architecture.md index 3ec2c77..0114cbb 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -34,56 +34,17 @@ The tool namespace also provides process and sandbox state. Normal execution is ## Deliberately unimplemented agent patterns -Ollie keeps the core small by refusing several common framework boundaries. The filesystem, external tools, and ordinary processes already provide the required primitives. +Ollie deliberately does not build the following into the agent runtime: -### No MCP client layer +- **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. 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`](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. -Ollie does not implement native Model Context Protocol support. MCP adds a JSON-RPC client, transport and initialization handshake, server configuration, connection lifecycle, and another tool adapter. Ollie already has: - -| MCP concern | Ollie primitive | -|---|---| -| Structured tool discovery | `.meta` files and the toolsrv registry | -| Tool invocation | JSON on stdin, stdout, exit status, and toolsrv process files | -| Typed schemas | `.meta` JSON Schema and tool prompt documentation | -| Subprocess lifecycle | toolsrv and its sandbox | -| Server composition | executable or metadata-only tools | - -An MCP server can remain an optional external dependency. A bridge tool can invoke an MCP client CLI when interoperability is required, without making MCP part of the agent runtime. - -### No embedded tool framework - -Capabilities are not compiled into the agent loop as provider-specific or framework-specific tool objects. Tool behavior lives in external executables or metadata-only commands, and toolsrv owns discovery, loading, execution, sandboxing, and process state. See [`architecture-tools.md`](architecture-tools.md) and [`architecture-toolsrv.md`](architecture-toolsrv.md). - -### No built-in plan-and-execute workflow - -Ollie does not implement a planner/executor subsystem, task graph, scheduler, or workflow engine. Planning is agent state; execution is the normal tool loop. Ollie does not own task dependencies, retries, compensation, or durable workflow semantics. - -Those concerns belong at the composition boundary. A system such as [Beads](https://github.com/steveyegge/beads) can expose task creation, dependency queries, updates, and completion through a tool. The external system owns the durable task graph and workflow semantics; toolsrv executes the tool; Ollie supplies the agent, sessions, prompts, and 9P observation/control surface. - -```text -Ollie agent - └─ toolsrv → Beads/task-graph tool → external durable state -``` - -This preserves a clean boundary: Ollie remains useful without Beads, while agents can use Beads or another task system when durable plan-and-execute behavior adds value. - -### No external coordination protocol - -Ollie does not expose a workflow engine, message bus, actor framework, or master coordinator as an external integration boundary. The runtime does contain an internal session event bus for agent and session observers; it is an implementation detail, not a public coordination API. External multi-agent coordination uses sessions, agents, `prompt`, `chat`, `statewait`, `feed`, and `ctl` files. Hub-and-spoke, pipeline, scatter-gather, peer, reactive, and self-directed workflows are scripts or agent conventions over those files. - -### No separate frontend control plane - -UIs, editor integrations, shell clients, and automation are 9P clients. They do not maintain a parallel session store or call a frontend-specific API. The public namespace is documented in [`architecture-9p.md`](architecture-9p.md). - -### No hidden distributed state layer - -Remote execution does not replicate the agent runtime or introduce a second RPC model. The agent loop, prompts, history, and model calls stay local; only toolsrv and tool execution move to the remote host over SSH-forwarded authenticated 9P. See [`architecture-remote.md`](architecture-remote.md). - -### No competing memory store - -Persistent memory is owned by [OptMem](https://github.com/VictorTaelin/OptMem). Ollie exposes memory through tools rather than maintaining a second memory database or synchronization layer. - -These omissions are deliberate composition choices, not missing extension points. New behavior should first be expressed as a tool, a 9P file operation, a session, or a shell workflow before adding a new runtime subsystem. +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