4.7 KiB

Raw Blame History

Tool Registry

toolsrv owns Ollie's tool registry. No tool registry is compiled into olliesrv. The registry is scoped per agent, so each agent can load and unload tools independently while sharing the session's toolsrv process.

Discovery

The registry scans the configured tools directory for *.meta files:

$XDG_CONFIG_HOME/ollie/tools/   # default: ~/.config/ollie/tools/
├── file_read.meta
├── file_read
└── custom_tool.meta

A valid metadata file is enough for a tool to appear in the catalog. The executable is resolved when the tool is invoked. Invalid metadata is skipped. A tool with variants is unavailable when no variant matches the host.

The registry reads metadata, resolves the selected command, and passes tool-call arguments as JSON on standard input.

Agent operations

# List tools currently loaded for an agent
ollie-9p read session/{session}/agent/{agent}/tools

# Load a tool
echo tool_name | ollie-9p write session/{session}/agent/{agent}/tools

# Unload a tool
echo tool_unload tool_name | ollie-9p write session/{session}/agent/{agent}/ctl

# List every discoverable tool
echo tools_all | ollie-9p write session/{session}/agent/{agent}/ctl

tool_load and tool_unload are also callable agent operations. Loading updates the agent's tool preamble and increments its per-agent registry revision. toolsrv.loaded and toolsrv.rev expose the loaded set and revision through 9P.

Agent profiles may specify startup loading with autoLoad. Discovery and loading are separate: a discovered tool is not callable until it is loaded.

Metadata

A .meta file uses this structure:

{
  "description": "Find files by glob pattern.",
  "prompt": "Full usage documentation injected when loaded.",
  "args": {
    "type": "object",
    "required": ["pattern"],
    "properties": {"pattern": {"type": "string"}}
  },
  "tier": "cold",
  "scope": "read",
  "outputFormat": "text",
  "cmd": "file_glob",
  "resetsCounter": false
}

Field	Meaning
`description`	Short catalog description.
`prompt`	Documentation added when the tool is loaded.
`args`	JSON Schema for tool arguments. Defaults to an empty object schema.
`tier`	Context retention tier. Defaults to `hot`.
`scope`	Tool scope metadata.
`outputFormat`	Output format metadata.
`cmd`	Command used to execute the tool.
`resetsCounter`	Marks tools that reset the relevant counter.
`variants`	Host-conditional metadata definitions.

readOnly and bypass are not current metadata fields. Sandbox and privilege behavior is configured by the execution service and its policies.

Command resolution

For a tool named name, toolsrv resolves the command in this order:

$XDG_CONFIG_HOME/ollie/tools/name if the local file exists.
The resolved .meta cmd field, returned as a shell command string.
name found through $PATH.

A .meta file can describe a co-located script, a system executable, or a shell command. Metadata-only tools are valid when their cmd resolves to an executable command.

Variants

The first variant whose conditions all match is merged over the top-level metadata. Variant values override non-empty top-level values. Supported match keys are:

binary: an absolute path or executable available through $PATH.
file: an existing file or directory.
os: the current runtime.GOOS.
arch: the current runtime.GOARCH.
env: a non-empty environment variable.
nenv: an empty or unset environment variable.

A condition value can be a string or an array; arrays use OR semantics. Multiple condition keys use AND semantics. If no variant matches, the tool is hidden.

{
  "description": "Read system logs.",
  "variants": [
    {"match": {"binary": "journalctl"}, "cmd": "system_logs_journald", "scope": "read"},
    {"match": {"file": "/var/log/syslog"}, "cmd": "system_logs_syslog", "scope": "read"}
  ]
}

Remote toolsrv deployments receive the metadata and resolve variants on the remote host. The catalog therefore reflects that host's capabilities.

Execution contract

The selected command receives one JSON object on standard input. A successful tool writes its result to standard output and exits with status 0. A failed tool exits non-zero. Structured content may be returned as JSON when required by the tool's output format.

Normal execution is sandboxed by toolsrv. The --yolo server option disables sandbox enforcement for explicit debugging or development. Bypass behavior is controlled by the separate bypass broker and sandbox policy.

See doc/writing-tools.md for authoring metadata and doc/tool-definitions.md for metadata-only command definitions.

4.7 KiB Raw Blame History