110 lines
4.3 KiB
Markdown
110 lines
4.3 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
|
|
agent --> tools
|
|
agent --> backend
|
|
agent --> log
|
|
agent --> paths
|
|
|
|
execute --> tools
|
|
execute --> skills
|
|
execute --> detach
|
|
execute --> sandbox
|
|
execute --> paths
|
|
|
|
tools --> paths
|
|
elevate -.->|socket| execute
|
|
```
|
|
|
|
## Packages
|
|
|
|
```
|
|
agent/ Core interface, agent loop, compaction, hooks, session persistence, config loading
|
|
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 execution
|
|
detach/ Background process management (ring buffer, signal)
|
|
skills/ Skill metadata parsing and per-session registry
|
|
elevate/ Elevation broker (privilege escalation daemon, policy management)
|
|
sandbox/ Landrun sandbox configuration and command wrapping
|
|
env/ Session environment helpers
|
|
log/ Structured logger
|
|
paths/ XDG path resolution
|
|
```
|
|
|
|
## Primitives
|
|
|
|
**`agent.Core`** — the central interface for a running agent session:
|
|
|
|
- `Submit` — send a prompt, stream events via the bus
|
|
- `Interrupt` — cancel the current turn
|
|
- `Inject` — append a user interruption to the next tool result
|
|
- `Queue`/`PopQueue` — buffered prompt FIFO
|
|
- `Bus` — session event bus (pubsub)
|
|
- `State` — current state: `idle`, `thinking`, or `calling: <tool>`
|
|
- `Reply` — assistant text from the last completed turn
|
|
- `WaitChange` — block until a field changes (state, usage, ctxsz, cwd)
|
|
- `Detach`/`ListDetached`/`SignalDetached`/`GetDetachedOutput` — background process management
|
|
|
|
**`backend.Backend`** — the LLM interface: `ChatStream`, `Models`, `ContextLength`, `Name`, `Model`/`SetModel`, `DefaultModel`.
|
|
|
|
**`tools.Server`** — interface for a tool provider: `ListTools`, `CallTool`. The primary implementation is `execute.Server` (local) with `execute.RemoteServer` for SSH-transparent execution.
|
|
|
|
**`tools.Dispatcher`** — routes tool calls to the correct server by name. Built via `NewDispatcher` or `NewDispatcherFunc`.
|
|
|
|
**`tools.Registry`** — per-session dynamic tool loading. Discovers tool scripts from `OLLIE_TOOLS_PATH`, parses their schemas and metadata, and promotes them 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.
|
|
|
|
`NewAgentCore` handles per-session state: message history, tool call routing, compaction, and hooks. `Core.Close()` tears down resources when a session is killed.
|
|
|
|
## License
|
|
|
|
GPLv3
|