lkn
/
ollie-core
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update README for new package layout

This commit is contained in:
Levi Neely 2026-07-29 18:12:01 +02:00
parent 2ea13cd611
commit bf137f0265
1 changed files with 56 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

136
README.md
View File

@ -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: <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`.
**`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/<name>.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 <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`.
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`. 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 <keyword> ${OLLIE:-$HOME/mnt/ollie}/sk/*.md
## Session lifecycle
# 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.
`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