109 lines
4.2 KiB
Markdown
109 lines
4.2 KiB
Markdown
# ollie
|
|
|
|
A Go library for building agentic systems. Provides sandboxed tool execution, a common LLM backend interface, dynamic tool/skill registries, and a session lifecycle framework.
|
|
|
|
## Architecture
|
|
|
|
```mermaid
|
|
graph TD
|
|
session --> agent
|
|
session --> backend
|
|
session --> toolsrv
|
|
session --> paths
|
|
|
|
agent --> backend
|
|
agent --> toolsrv
|
|
agent --> paths
|
|
|
|
toolsrv --> detach
|
|
toolsrv --> sandbox
|
|
toolsrv --> skills
|
|
toolsrv --> paths
|
|
|
|
tools --> toolsrv
|
|
sandbox --> paths
|
|
env --> paths
|
|
|
|
elevate -.->|unix socket| toolsrv
|
|
```
|
|
|
|
## Packages
|
|
|
|
```
|
|
session/ Session lifecycle: creation, persistence, environment, event bus
|
|
agent/ Agent runtime: turn loop, compaction, hooks, commands, history, cost, FIFO, prompts
|
|
backend/ Backend interface + LLM providers (Anthropic, OpenAI, Ollama, Copilot, Kiro)
|
|
toolsrv/ Tool server: registry, discovery, schema, shell execution, remote SSH, streaming
|
|
tools/ Built-in tool definitions (shell, skill, tool promotion)
|
|
detach/ Background process management (ring buffer, signal)
|
|
skills/ Skill metadata parsing and per-session registry
|
|
elevate/ Elevation broker (privilege escalation daemon, policy)
|
|
sandbox/ Landrun sandbox configuration and command wrapping
|
|
env/ Session environment helpers
|
|
log/ Structured logger
|
|
paths/ XDG path resolution
|
|
```
|
|
|
|
## Core concepts
|
|
|
|
**`session.Session`** — the public interface. A session is the runtime environment that hosts an agent. It provides identity, working directory, event bus, environment, and lifecycle management.
|
|
|
|
**`session.Agent`** — the reasoning entity within a session. Owns the conversation history, LLM backend, tools, hooks, and system prompt. Swappable via `/agent` command.
|
|
|
|
**`session.harness`** (unexported) — implements Session. Wires the agent to the session environment and drives turn execution.
|
|
|
|
**`backend.Backend`** — the LLM interface: `ChatStream`, `Models`, `ContextLength`, `Name`, `Model`/`SetModel`.
|
|
|
|
**`tools.Server`** — interface for a tool provider: `ListTools`, `CallTool`. Implementations: `execute.Server` (local) and `execute.RemoteServer` (SSH).
|
|
|
|
**`tools.Registry`** — per-session dynamic tool loading. Discovers scripts from `$XDG_CONFIG_HOME/ollie/tools`, parses schemas, promotes to native callable functions on demand.
|
|
|
|
## Install
|
|
|
|
No build step — ollie-core is a library.
|
|
|
|
## Configuration
|
|
|
|
### Agent config: `~/.config/ollie/agents/<name>.json`
|
|
|
|
```json
|
|
{
|
|
"prompt": "agent-coding.md",
|
|
"backend": "anthropic",
|
|
"model": "claude-sonnet-4-20250514",
|
|
"hooks": {
|
|
"preTurn": ["$OLLIE/x/prime tools-file"]
|
|
},
|
|
"maxSteps": 50,
|
|
"reasoning": 10000
|
|
}
|
|
```
|
|
|
|
Hook values accept a string or array of strings. Commands run in order; stdout is appended to context. Exit code 2 blocks the action; other non-zero is a warning.
|
|
|
|
### Sandbox config: `~/.config/ollie/sandbox/<name>.yaml`
|
|
|
|
Controls landrun sandboxing for `shell`. See file header for documentation.
|
|
|
|
## Tools
|
|
|
|
One built-in tool via `execute.Server`:
|
|
|
|
**`shell`** — run a bash command in a sandbox. Accepts `cmd`, `timeout` (default 30s, 0 for unlimited), `sandbox` (profile name), `elevated` (bypass sandbox via elevation broker).
|
|
|
|
Named tool scripts from `$XDG_CONFIG_HOME/ollie/tools` are promoted to native callable functions via `tools.Registry`. Each script declares its schema and metadata in header comments (`ollie:prompt`, `args_json:`, `ollie:tier`, `ollie:parallel read`).
|
|
|
|
## Skills
|
|
|
|
Skills are domain-specific knowledge modules in `$XDG_CONFIG_HOME/ollie/skills` (default: `~/.config/ollie/skills/`). Each is a directory containing a `SKILL.md` with YAML front-matter (name, description). Loaded into session context on demand via `skill_load`.
|
|
|
|
## Session lifecycle
|
|
|
|
The 9P server (`olliesrv`) is the session manager. It instantiates the execute server, elevation broker, and tool/skill registries at daemon level. Sessions are created, queried, and controlled via the 9P filesystem — all agent interaction uses the `ollie-9p` client internally.
|
|
|
|
`session.New()` creates a session with its agent. The session drives turn execution, manages compaction, and handles lifecycle events. `Close()` tears down resources when a session is killed.
|
|
|
|
## License
|
|
|
|
GPLv3
|