From bf137f0265ca2f88bebb594532e6ecec9c97f468 Mon Sep 17 00:00:00 2001 From: Levi Neely Date: Wed, 29 Jul 2026 18:12:01 +0200 Subject: [PATCH] update README for new package layout --- README.md | 136 ++++++++++++++++++++++-------------------------------- 1 file changed, 56 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index 47f1e5d..2153bcf 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,45 @@ # 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. +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. Key methods: +**`agent.Core`** — the central interface for a running agent session: - `Submit` — send a prompt, stream events via the bus - `Interrupt` — cancel the current turn @@ -13,118 +48,59 @@ A Go library for building agentic systems. Provides a sandboxed `shell` tool, a - `Bus` — session event bus (pubsub) - `State` — current state: `idle`, `thinking`, or `calling: ` - `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`. +**`backend.Backend`** — the LLM interface: `ChatStream`, `Models`, `ContextLength`, `Name`, `Model`/`SetModel`, `DefaultModel`. -**`agent.AgentEnv`** — wires together a backend, tool dispatcher, config, and hooks into the environment passed to `NewAgentCore`. Built via `BuildAgentEnv`. +**`tools.Server`** — interface for a tool provider: `ListTools`, `CallTool`. The primary implementation is `execute.Server` (local) with `execute.RemoteServer` for SSH-transparent execution. -**`agent.Hooks`** — lifecycle callbacks (`agentSpawn`, `preTurn`, `postTurn`, `preCompact`, `postCompact`, `turnError`) executed as shell commands with a JSON payload. Run via `Hooks.Run`. +**`tools.Dispatcher`** — routes tool calls to the correct server by name. Built via `NewDispatcher` or `NewDispatcherFunc`. -**`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 -``` +**`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 -``` -mk -``` - No build step — ollie-core is a library. ## Configuration -### Config file: `~/.config/ollie/config.json` +### Agent config: `~/.config/ollie/agents/.json` ```json { + "prompt": "agent-coding.md", + "backend": "anthropic", + "model": "claude-sonnet-4-20250514", "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"] - } + "preTurn": ["$OLLIE/x/prime tools-file"] + }, + "maxSteps": 50, + "reasoning": 10000 } ``` -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 `), which reads a file from `p/` and writes it to stdout with environment variable substitution. The fully assembled result is readable at `s//systemprompt`. +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/.yaml` -Controls landrun sandboxing for `shell`. Created automatically with defaults on first run. See the file header for documentation. +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` (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). +**`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 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. +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 files served from the ollie 9P mount (`sk/` directory). +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`. -```sh -# Discover -ls ${OLLIE:-$HOME/mnt/ollie}/sk/ -grep -li ${OLLIE:-$HOME/mnt/ollie}/sk/*.md +## Session lifecycle -# Load -cat ${OLLIE:-$HOME/mnt/ollie}/sk/.md -``` - -Skills are sourced from `OLLIE_SKILLS_PATH` (default: `~/.config/ollie/skills/`). The `sk/` directory in the mount exposes them as flat `.md` files. +`NewAgentCore` creates `/tmp/ollie/{sessionID}` at session start. `Core.Close()` removes it. The 9P server instantiates the execute server and elevation broker at the daemon level; sessions share them with per-session state via the tool registry. ## License