docs: document sudo and tool variants
This commit is contained in:
Ollie Agent
parent
3ea6bc3865
commit
93225704f8
52
README.md
52
README.md
|
|
@ -283,6 +283,58 @@ The `.meta` file (`file_glob.meta`):
|
|||
Everything is sandboxed by default via Landlock. Tools that need to escape
|
||||
request elevation explicitly (`"elevated": true`).
|
||||
|
||||
### Privileged tools: `sudo`
|
||||
|
||||
Tools that need root privileges declare `"sudo": true` in their `.meta`. The
|
||||
dispatch chain becomes a two-gate sequence: elevation approval (escape sandbox)
|
||||
→ credential prompt → `sudo -S` execution. The tool itself has no knowledge of
|
||||
sudo — the privilege wrapping is entirely in the dispatch layer.
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "Read system logs (dmesg).",
|
||||
"sudo": true,
|
||||
"cmd": "system_logs_dmesg",
|
||||
"args": {"type":"object","properties":{"lines":{"type":"string"}}},
|
||||
"readOnly": true
|
||||
}
|
||||
```
|
||||
|
||||
Credentials are prompted via `kdialog`/`zenity` on desktop, or forwarded over
|
||||
SSH for remote execution. See [doc/WRITING_TOOLS.md](doc/WRITING_TOOLS.md) for
|
||||
details.
|
||||
|
||||
### 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.
|
||||
|
||||
## What you can do
|
||||
|
||||
| Capability | How |
|
||||
|
|
|
|||
51
doc/USAGE.md
51
doc/USAGE.md
|
|
@ -486,6 +486,9 @@ Each tool has a `.meta` JSON sidecar file alongside the executable:
|
|||
| `args` | JSON Schema for tool input parameters |
|
||||
| `tier` | Result cacheability: `cold`, `warm`, or `hot` (default: hot) |
|
||||
| `readOnly` | Safe for parallel execution with other read tools |
|
||||
| `cmd` | Executable path or name; overrides co-located binary (see WRITING_TOOLS.md) |
|
||||
| `sudo` | Requires root privileges; implies elevation |
|
||||
| `variants` | Array of conditional definitions for heterogeneous hosts (see WRITING_TOOLS.md) |
|
||||
|
||||
### Runtime access
|
||||
|
||||
|
|
@ -503,6 +506,54 @@ Agents query `/tools` when they need detailed usage for a specific tool.
|
|||
Drop an executable and its `.meta` file in `$OLLIE_TOOLS_PATH`.
|
||||
The next session created will pick it up automatically. No restart required.
|
||||
|
||||
### Host-conditional variants
|
||||
|
||||
Tools can declare multiple **variants** gated by match conditions. The first
|
||||
variant where all conditions pass determines the tool's schema, documentation,
|
||||
and executable. If no variant matches, the tool is hidden from the registry.
|
||||
|
||||
```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"}}}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Supported match keys: `binary`, `file`, `os`, `arch`, `env`, `nenv`. All
|
||||
conditions in a match must be true (AND). Values can be a string or array
|
||||
(OR). See [WRITING_TOOLS.md](WRITING_TOOLS.md) for the full specification.
|
||||
|
||||
### Privileged tools: `sudo`
|
||||
|
||||
Tools that need root privileges declare `"sudo": true` in their `.meta`. The
|
||||
dispatch chain becomes a two-gate sequence: elevation approval (escape sandbox)
|
||||
→ credential prompt → `sudo -S` execution. The tool itself has no knowledge of
|
||||
sudo — the privilege wrapping is entirely in the dispatch layer.
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "Read system logs (dmesg).",
|
||||
"sudo": true,
|
||||
"cmd": "system_logs_dmesg",
|
||||
"args": {"type":"object","properties":{"lines":{"type":"string"}}},
|
||||
"readOnly": true
|
||||
}
|
||||
```
|
||||
|
||||
Credentials are prompted via `kdialog`/`zenity` on desktop, or forwarded over
|
||||
SSH for remote execution. See [WRITING_TOOLS.md](WRITING_TOOLS.md) for details.
|
||||
|
||||
## Alternative front-ends
|
||||
|
||||
The 9P filesystem is the lowest level interface to ollie. All interfaces are wrappers around filesystem operations. Front-ends:
|
||||
|
|
|
|||
Loading…
Reference in New Issue