132 lines
6.6 KiB
Markdown
132 lines
6.6 KiB
Markdown
# ollie
|
|
|
|
A Go library for building agentic systems. Provides a sandboxed `shell` tool, a common LLM backend interface, and a skill system for domain-specific capabilities.
|
|
|
|
## Primitives
|
|
|
|
**`agent.Core`** — the central interface for a running agent session. Key methods:
|
|
|
|
- `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
|
|
- `IsRunning` — whether a turn is in progress
|
|
- `AgentName`/`BackendName`/`ModelName` — active identifiers
|
|
- `Usage`/`Cost`/`CtxSz` — token counts, cost, context size
|
|
- `ListModels` — available models from the backend
|
|
- `CWD`/`SetCWD` — working directory for tool execution
|
|
- `SetSessionID` — rename the session
|
|
- `SystemPrompt` — fully rendered system prompt
|
|
- `Context` — current message history as sent to the backend
|
|
- `GenerationParams`/`SetGenerationParams` — sampling parameters
|
|
- `CompactionModel`/`SetCompactionModel` — model override for compaction
|
|
- `SetEnv` — inject session-scoped env var into subprocesses
|
|
- `WaitChange` — block until a field changes (state, usage, ctxsz, cwd)
|
|
- `ToolCallCount` — monotonic tool call counter
|
|
- `SaveSession` — persist session state to disk
|
|
- `Detach`/`ListDetached`/`SignalDetached`/`GetDetachedOutput` — background process management
|
|
- `Close` — release resources
|
|
|
|
**`agent.Session`** — the conversation turn accumulator. Tracks message history, token usage, context compaction, and session persistence. Supports `compact` (summarize-and-truncate) and `PreCompactionSnapshot`.
|
|
|
|
**`agent.AgentEnv`** — wires together a backend, tool dispatcher, config, and hooks into the environment passed to `NewAgentCore`. Built via `BuildAgentEnv`.
|
|
|
|
**`agent.Hooks`** — lifecycle callbacks (`agentSpawn`, `preTurn`, `postTurn`, `preCompact`, `postCompact`, `turnError`) executed as shell commands with a JSON payload. Run via `Hooks.Run`.
|
|
|
|
**`backend.Backend`** — the LLM interface: `ChatStream`, `Models`, `ContextLength`, `Name`, `Model`/`SetModel`, `DefaultModel`. Implementations: Ollama, OpenAI-compatible (including OpenRouter), Anthropic, Copilot, Kiro/CodeWhisperer, Gemini.
|
|
|
|
**`tools.Server`** — interface for a tool provider: `ListTools`, `CallTool`, `Close`. The only built-in implementation is `execute.Server`. Custom servers implement this interface directly.
|
|
|
|
**`tools.Dispatcher`** — routes tool calls to the correct server by name. Built via `NewDispatcher` or `NewDispatcherFunc` (from a map of `Decl` factories). Supports `AddServer`, `GetServer`, `ListTools`, `Dispatch`.
|
|
|
|
## Packages
|
|
|
|
```
|
|
pkg/agent/ — Core interface, agent loop, session management
|
|
pkg/backend/ — Backend interface + implementations (Ollama, OpenAI, Anthropic, Copilot, Kiro, Gemini)
|
|
pkg/config/ — Config struct and loader
|
|
pkg/env/ — Environment variable loading (env file + shell)
|
|
pkg/log/ — Structured logging
|
|
pkg/paths/ — Config and data directory resolution
|
|
pkg/skills/ — Skill file discovery and loading
|
|
pkg/tools/ — Server and Dispatcher interfaces; tool definitions
|
|
pkg/tools/execute/ — execute.Server: shell
|
|
```
|
|
|
|
## Install
|
|
|
|
```
|
|
mk
|
|
```
|
|
|
|
No build step — ollie-core is a library.
|
|
|
|
## Configuration
|
|
|
|
### Config file: `~/.config/ollie/config.json`
|
|
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"agentSpawn": [
|
|
"bd prime 2>/dev/null || true"
|
|
],
|
|
"preTurn": [
|
|
"$OLLIE/x/prime tools-file",
|
|
"$OLLIE/x/prime tools-reasoning",
|
|
"$OLLIE/x/prime tools-memory",
|
|
"$OLLIE/x/prime tools-subagent"
|
|
],
|
|
"postTurn": ["true"]
|
|
}
|
|
}
|
|
```
|
|
|
|
Hook values accept a string or an array of strings. Commands run in order; each command's stdout is appended to the system prompt context. Exit code 2 blocks the triggering action; any other non-zero exit is a non-blocking warning.
|
|
|
|
### System prompt
|
|
|
|
The base system prompt is embedded in the ollie binary (`system_prompt.md` in the 9p submodule) and loaded by Go at session creation via `BuildAgentEnv`. Tool-specific prompts are injected via `preTurn` hooks using the `prime` script (`$OLLIE/x/prime <name>`), which reads a file from `p/` and writes it to stdout with environment variable substitution. The fully assembled result is readable at `s/<id>/systemprompt`.
|
|
|
|
### Sandbox config: `~/.config/ollie/sandbox/<name>.yaml`
|
|
|
|
Controls landrun sandboxing for `shell`. Created automatically with defaults on first run. See the file header for documentation.
|
|
|
|
## Tools
|
|
|
|
One built-in tool via `execute.Server`:
|
|
|
|
**`shell`** — run a bash command in a sandbox. Accepts `cmd` (string), `timeout` (default 30s, 0 for no timeout), `sandbox` (profile name), `elevated` (bypass sandbox). Use `elevated: true` to escape the sandbox, or `timeout: 0` to run indefinitely (detachable).
|
|
|
|
Named tool scripts from `OLLIE_TOOLS_PATH` are promoted to native callable functions via the tool registry — no wrapper needed.
|
|
|
|
## Session lifecycle
|
|
|
|
`NewAgentCore` creates `/tmp/ollie/{sessionID}` when a session starts. `Core.Close()` removes it. Callers must call `Close()` when tearing down a session — olliesrv does this in `killSession` and on server shutdown.
|
|
|
|
Additional capabilities (file I/O, memory, reasoning, task management, sub-agents, browser automation) are implemented as tool scripts in `OLLIE_TOOLS_PATH`, promoted to native callable functions via the tool registry. Default tools: `file_read`, `file_write`, `file_edit`, `file_glob`, `file_grep`, `memory_remember`, `memory_recall`, `reasoning_think`, `browser_screencap`, `subagent_spawn`.
|
|
|
|
Each tool server exports a `Decl` function that returns a `func() tools.Server` factory. `execute.Decl(cwd)` accepts a working directory used as `cmd.Dir` for sandboxed commands and for `{CWD}` expansion in the sandbox config; pass `""` to fall back to `os.Getwd()`. Frontends register servers by passing Decl results to `tools.NewDispatcherFunc`. Adding a new tool means implementing `tools.Server`, exporting a `Decl` function, and registering it — no frontend changes required.
|
|
|
|
## Skills
|
|
|
|
Skills are domain-specific knowledge files served from the ollie 9P mount (`sk/` directory).
|
|
|
|
```sh
|
|
# Discover
|
|
ls ${OLLIE:-$HOME/mnt/ollie}/sk/
|
|
grep -li <keyword> ${OLLIE:-$HOME/mnt/ollie}/sk/*.md
|
|
|
|
# Load
|
|
cat ${OLLIE:-$HOME/mnt/ollie}/sk/<name>.md
|
|
```
|
|
|
|
Skills are sourced from `OLLIE_SKILLS_PATH` (default: `~/.config/ollie/skills/`). The `sk/` directory in the mount exposes them as flat `<name>.md` files.
|
|
|
|
## License
|
|
|
|
GPLv3
|