# 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