88 lines
3.1 KiB
Markdown
88 lines
3.1 KiB
Markdown
## Tool registry: zero built-in tools
|
|
|
|
**No tools are compiled into the Go binary.** Every tool — including `shell` and `reasoning_think` — is an external executable loaded dynamically through the 9P filesystem. Tool definitions, schemas, and execution logic live entirely in the filesystem.
|
|
|
|
### Loading tools
|
|
|
|
Tools are loaded by writing their name to `session/{sname}/agent/{aname}/tools`:
|
|
|
|
```bash
|
|
# List currently loaded tools
|
|
ollie-9p read session/{sname}/agent/{aname}/tools
|
|
|
|
# Load a tool — becomes a native callable function
|
|
echo file_glob | ollie-9p write session/{sname}/agent/{aname}/tools
|
|
|
|
# Global catalog: all discoverable tools on disk
|
|
ollie-9p read tools
|
|
```
|
|
|
|
The `tool_load` tool is itself a bash script that does exactly this — it wraps the 9P write in a callable function so the LLM can load tools during a turn.
|
|
|
|
### Agent autoLoad configuration
|
|
|
|
Agent configs declare which tools to load at startup via `autoLoad`:
|
|
|
|
```json
|
|
{
|
|
"autoLoad": ["file_read", "file_edit", "file_glob", "file_grep", "file_write", "tool_load"]
|
|
}
|
|
```
|
|
|
|
Each agent profile (default, copilot, explorer, librarian, navigator, taskmanager, theo) has its own `autoLoad` list. The `allowTools` field provides a secondary security gate.
|
|
|
|
### Declarative registration
|
|
|
|
Tools are executables in `~/.config/ollie/tools/`. Each one has a `.meta` sidecar
|
|
file declaring its JSON schema, documentation, concurrency class, tier, and
|
|
privilege requirements. The registry reads `.meta` files — it never inspects the
|
|
executable itself.
|
|
|
|
This is **declarative tool registration**: write a `.meta` file, drop an
|
|
executable in `$OLLIE_TOOLS_PATH`, and the tool is live. No server restart,
|
|
no config file, no code change.
|
|
|
|
The `.meta` file (`file_glob.meta`):
|
|
|
|
```json
|
|
{
|
|
"description": "Find files by glob pattern, sorted by mtime (newest first).",
|
|
"args": {"type":"object","properties":{"pattern":{"type":"string"}},"required":["pattern"]},
|
|
"tier": "cold",
|
|
"readOnly": true
|
|
}
|
|
```
|
|
|
|
Everything is sandboxed by default via Landlock. Tools that need to escape
|
|
request bypass explicitly (`"bypass": true`).
|
|
|
|
### Host-conditional variants
|
|
|
|
A single `.meta` file can describe a tool that works differently on different
|
|
hosts. Variants are gated by match conditions (`binary`, `file`, `os`, `arch`,
|
|
`env`, `nenv`). The first matching variant determines the tool's schema,
|
|
documentation, and executable. If no variant matches, the tool is hidden from
|
|
the registry — it doesn't exist on this host.
|
|
|
|
```json
|
|
{
|
|
"description": "Read system logs.",
|
|
"variants": [
|
|
{
|
|
"match": {"binary": "journalctl"},
|
|
"cmd": "system_logs_journald",
|
|
"args": {"type":"object","properties":{"unit":{"type":"string"},"since":{"type":"string"}}}
|
|
},
|
|
{
|
|
"match": {"file": "/var/log/syslog"},
|
|
"cmd": "system_logs_syslog",
|
|
"args": {"type":"object","properties":{"lines":{"type":"string"}}}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
On a systemd host the model sees unit filtering and time ranges. On Alpine it
|
|
sees tail + grep. On a host with neither, the tool doesn't appear. One `.meta`
|
|
deploys everywhere. See [`doc/writing-tools.md`](doc/writing-tools.md) for the
|
|
full variant specification. |