lkn
/
ollie
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Summarize integration boundaries

This commit is contained in:
Ollie Agent 2026-08-16 20:08:30 +02:00
parent 7b8f6942c6
commit 2e3680e33a
1 changed files with 9 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
doc/architecture.md
View File

@ -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