102 lines
4.0 KiB
Markdown
102 lines
4.0 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 --> tools
|
|
session --> backend
|
|
session --> log
|
|
session --> paths
|
|
|
|
execute --> tools
|
|
execute --> skills
|
|
execute --> detach
|
|
execute --> sandbox
|
|
execute --> paths
|
|
|
|
tools --> paths
|
|
elevate -.->|socket| execute
|
|
```
|
|
|
|
## Packages
|
|
|
|
```
|
|
session/ Session + Agent: the core runtime (loop, compaction, hooks, commands, persistence)
|
|
backend/ Backend interface + LLM providers (Anthropic, OpenAI, Ollama, Gemini, Copilot, CodeWhisperer)
|
|
tools/ Server/Dispatcher interfaces, tool registry, discovery, schema parsing
|
|
execute/ Sandboxed shell execution, promoted tool dispatch, skill dispatch, remote SSH
|
|
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 `OLLIE_TOOLS_PATH`, 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 `OLLIE_TOOLS_PATH` 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 `OLLIE_SKILLS_PATH` (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
|