# 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