doc: rename tool-overlays to tool-definitions
This commit is contained in:
Levi Neely
parent
7d44e9ac1f
commit
df7eefaf71
|
|
@ -62,7 +62,7 @@ Everything lives under `$XDG_CONFIG_HOME/ollie/` (default: `~/.config/ollie/`)
|
|||
| **Parallel execution** | Non-conflicting tool calls within a turn run in parallel (scope-based conflict scheduling) |
|
||||
| **Agents** | Write a JSON config in `~/.config/ollie/agents/` with agent prompt in `~/.config/ollie/prompts/` |
|
||||
| **Tools** | Drop an executable + `.meta` in `~/.config/ollie/tools/` — load at runtime via `tool_load` |
|
||||
| **Tool overlays** | Integrate external CLIs (or MCP servers via CLI bridges) with `.meta` files only — no wrapper code ([doc](doc/tool-overlays.md)) |
|
||||
| **Tool definitions** | Define tools with `.meta` files only — no wrapper script needed ([doc](doc/tool-definitions.md)) |
|
||||
| **Domain skills** | Load markdown skill modules at runtime |
|
||||
|
||||
## Repository layout
|
||||
|
|
|
|||
|
|
@ -1,21 +1,24 @@
|
|||
# Tool Overlays
|
||||
# Tool Definitions
|
||||
|
||||
A tool overlay is a set of `.meta` files that expose external CLIs to ollie
|
||||
without wrapper scripts. The `.meta` file declares the schema and specifies
|
||||
the shell command to run — no executable needed.
|
||||
A `.meta` file can define a tool without any companion executable. The `cmd`
|
||||
field specifies a shell command to run — the registry executes it via shell,
|
||||
passing the tool's JSON arguments on stdin.
|
||||
|
||||
## Resolution order
|
||||
This is the same `.meta` schema used in `writing-tools.md`, but without the
|
||||
sidecar executable. No script, no binary — just the definition.
|
||||
|
||||
## Resolution
|
||||
|
||||
When the registry resolves a tool, it checks:
|
||||
|
||||
1. `~/.config/ollie/tools/<name>` — local script or binary
|
||||
2. `.meta` `cmd` field — shell command string, executed directly
|
||||
2. `.meta` `cmd` field — shell command, executed directly
|
||||
3. `exec.LookPath(<name>)` — PATH lookup
|
||||
|
||||
If a `.meta` file has a `cmd` field, the registry executes it via shell. The
|
||||
tool's JSON arguments are passed on stdin.
|
||||
If a `.meta` file has a `cmd` field and no co-located executable exists, the
|
||||
registry runs the command via shell.
|
||||
|
||||
## Meta-only tool structure
|
||||
## Structure
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -33,7 +36,8 @@ tool's JSON arguments are passed on stdin.
|
|||
}
|
||||
```
|
||||
|
||||
No script, no binary — just the `.meta` file.
|
||||
The `cmd` field is the only addition to the standard `.meta` schema. All other
|
||||
fields work the same as documented in `writing-tools.md`.
|
||||
|
||||
## Parsing arguments
|
||||
|
||||
|
|
@ -64,9 +68,7 @@ For subcommand-style CLIs with variable arguments:
|
|||
This extracts a `command` field, builds `--key=value` flags from remaining
|
||||
fields, and calls `my-cli <command> --key=value ...`.
|
||||
|
||||
## Example: wrapping ripgrep
|
||||
|
||||
Expose `rg` as a tool with curated arguments:
|
||||
## Example: ripgrep
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -87,12 +89,7 @@ Expose `rg` as a tool with curated arguments:
|
|||
}
|
||||
```
|
||||
|
||||
The model calls `rg_search(pattern="error", glob="*.log")`. The cmd pipeline
|
||||
extracts fields, builds flags conditionally, and runs `rg -g "*.log" "error" "."`.
|
||||
|
||||
## Example: wrapping kubectl
|
||||
|
||||
Expose common kubectl operations:
|
||||
## Example: kubectl
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -111,13 +108,10 @@ Expose common kubectl operations:
|
|||
}
|
||||
```
|
||||
|
||||
Complex routing logic lives entirely in the `cmd` field. No wrapper script.
|
||||
## Example: MCP bridge
|
||||
|
||||
## Example: wrapping an MCP server
|
||||
|
||||
MCP servers expose tools over JSON-RPC. CLI bridges like `mcp-client-cli` or
|
||||
`npx @anthropic/mcp-client` let you call them from the command line. Wrap the
|
||||
bridge in a `.meta`:
|
||||
MCP servers expose tools over JSON-RPC. CLI bridges like `mcp-client-cli` let
|
||||
you call them from the command line:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -136,63 +130,21 @@ bridge in a `.meta`:
|
|||
}
|
||||
```
|
||||
|
||||
The `cmd` extracts the tool name, passes remaining args as JSON to the MCP
|
||||
bridge. No MCP protocol implementation needed — the bridge handles it.
|
||||
This works for any MCP server with a CLI bridge. See `doc/resources/no-mcp.md`
|
||||
for why ollie uses this pattern instead of implementing MCP natively.
|
||||
|
||||
This pattern works for any MCP server with a CLI bridge: filesystem, database,
|
||||
Slack, linear, etc.
|
||||
## Installation
|
||||
|
||||
## Overlay structure
|
||||
|
||||
An overlay is a directory (usually a git repo) with `.meta` files, agent
|
||||
configs, and prompts:
|
||||
Copy the `.meta` file to `~/.config/ollie/tools/`. The tool is live immediately
|
||||
— no restart needed.
|
||||
|
||||
```sh
|
||||
cp my_tool.meta ~/.config/ollie/tools/
|
||||
```
|
||||
my-overlay/
|
||||
├── tools/
|
||||
│ ├── tool_a.meta
|
||||
│ └── tool_b.meta
|
||||
├── agents/
|
||||
│ └── my-agent.json
|
||||
├── prompts/
|
||||
│ └── agent-my-agent.md
|
||||
└── justfile
|
||||
```
|
||||
|
||||
The justfile installs to `~/.config/ollie/`:
|
||||
|
||||
```just
|
||||
home := env_var('HOME')
|
||||
cfg := home / ".config/ollie"
|
||||
|
||||
default: install
|
||||
|
||||
install: tools agents prompts
|
||||
|
||||
tools:
|
||||
install -m644 tools/tool_a.meta {{cfg}}/tools/tool_a.meta
|
||||
install -m644 tools/tool_b.meta {{cfg}}/tools/tool_b.meta
|
||||
|
||||
agents:
|
||||
mkdir -p {{cfg}}/agents
|
||||
install -m644 agents/my-agent.json {{cfg}}/agents/my-agent.json
|
||||
|
||||
prompts:
|
||||
mkdir -p {{cfg}}/prompts
|
||||
install -m644 prompts/agent-my-agent.md {{cfg}}/prompts/agent-my-agent.md
|
||||
|
||||
uninstall:
|
||||
rm -f {{cfg}}/tools/tool_a.meta {{cfg}}/tools/tool_b.meta
|
||||
rm -f {{cfg}}/agents/my-agent.json
|
||||
rm -f {{cfg}}/prompts/agent-my-agent.md
|
||||
```
|
||||
|
||||
Run `just install`. Tools are live immediately — no restart needed.
|
||||
|
||||
## Notes
|
||||
|
||||
- `additionalProperties: true` allows pass-through arguments the schema doesn't enumerate.
|
||||
- Prefix tool names to avoid collisions (`acme_deploy`, not `deploy`).
|
||||
- Test cmd pipelines: `echo '{"pattern":"TODO"}' | bash -c 'YOUR_CMD'`
|
||||
- Agent configs can auto-load overlay tools via `autoLoad`.
|
||||
- Overlays compose: multiple overlays install to the same tools directory.
|
||||
- Agent configs can auto-load tools via `autoLoad`.
|
||||
Loading…
Reference in New Issue