From d33549eca186ed978426717c0433a560873fcf85 Mon Sep 17 00:00:00 2001 From: Ollie Agent Date: Thu, 20 Aug 2026 18:31:31 +0200 Subject: [PATCH] Document one-tool capability bootstrap --- doc/architecture-9p.md | 5 +++++ doc/architecture-core.md | 13 ++++++++++-- doc/architecture-embedding.md | 9 ++++---- doc/architecture-prompting.md | 5 ++++- doc/architecture-tools.md | 12 ++++++++++- doc/architecture-toolsrv.md | 7 ++++++- doc/evolution.md | 39 +++++++++++++++++++++++++++++++++++ 7 files changed, 81 insertions(+), 9 deletions(-) diff --git a/doc/architecture-9p.md b/doc/architecture-9p.md index 026f3d4..11806ca 100644 --- a/doc/architecture-9p.md +++ b/doc/architecture-9p.md @@ -20,6 +20,11 @@ The Ollie namespace is declared in `cmd/olliesrv/internal/fs/spec.go`, materiali `olliesrv` listens on the Unix socket selected by `$NAMESPACE`. It can also expose the same server on an optional TCP address. The TCP listener speaks the same 9P protocol and namespace; it does not add an HTTP or JSON API. +Agents use the same namespace to bootstrap capabilities. A minimal profile can +start with only `client_9p`; it loads another tool by writing +`tool_load ` to its own `agent/{name}/ctl` file. The tool becomes callable +after the runtime refreshes its toolsrv registry revision. + Use `ollie-9p` for direct operations: ```sh diff --git a/doc/architecture-core.md b/doc/architecture-core.md index d2426f5..c21223c 100644 --- a/doc/architecture-core.md +++ b/doc/architecture-core.md @@ -122,6 +122,7 @@ type Runtime struct { Preamble *Preamble Tools []backend.Tool ToolMeta map[string]protocol.ToolInfo + ToolRevision uint64 Exec toolExecutor GenParams backend.GenerationParams MaxSteps int @@ -135,7 +136,7 @@ type Runtime struct { `BuildRuntime(cfg, runner, cwd, env)` wires everything together: -1. Lists all tools from the runner +1. Lists the agent’s currently loaded tools from the runner and records the agent-scoped registry revision 2. Resolves the system prompt by executing the config's `prompt` commands 3. Extracts generation parameters from the config 4. Builds the tool executor closure (routes calls through the runner) @@ -188,7 +189,15 @@ On the first error, the `turnError` hook fires. If it exits 0 (handled), the loo ### Tool Execution -Tool calls are dispatched with parallelism awareness: +Tool calls are dispatched with parallelism awareness. Tool schemas are +loaded progressively: the default profile starts with `client_9p`, and semantic +tool hints tell the agent to issue `tool_load ` through its agent `ctl` +file. + +After a tool round, the agent compares the toolsrv agent-scoped registry +revision with `Runtime.ToolRevision`. If the revision changed, it lists the +loaded tools, rebuilds backend schemas and metadata, and updates the rendered +tool preamble before the next model request. 1. Classify each call from the tool metadata and dispatch flags. 2. Batch read-safe calls when the metadata permits parallel execution. diff --git a/doc/architecture-embedding.md b/doc/architecture-embedding.md index 871c3f3..38887c3 100644 --- a/doc/architecture-embedding.md +++ b/doc/architecture-embedding.md @@ -89,10 +89,11 @@ each turn ``` Relevant skills are injected as a `` block containing complete skill -content. Relevant tools are injected as a `` block containing -callable names and descriptions. The normal tool registry still controls -whether a tool is loaded and executable; semantic matching only improves what -the model sees first. +content. Relevant tools are injected as a `` block containing names and +descriptions plus the `client_9p` operation needed to load them. Semantic +matching does not grant capability: the normal per-agent registry still +controls whether a tool is loaded and executable. The model must load a hinted +tool through the agent `ctl` file before calling it. The bounded result limits prevent discovery from becoming a prompt-size or context-budget problem. This progressive disclosure is especially useful for diff --git a/doc/architecture-prompting.md b/doc/architecture-prompting.md index b8dd065..2a1abb3 100644 --- a/doc/architecture-prompting.md +++ b/doc/architecture-prompting.md @@ -46,7 +46,10 @@ The default configuration uses installed prompt files under `$XDG_CONFIG_HOME/ol ## Tool rendering -When tools are enabled, `BuildRuntime` calls the configured `ToolsrvConn` once to obtain tool metadata. The metadata becomes both: +When tools are enabled, `BuildRuntime` calls the configured `ToolsrvConn` to obtain the +agent’s currently loaded tool metadata and its registry revision. The default +profile starts with only `client_9p`; additional tools are loaded through the +agent `ctl` file and become available after the runtime refreshes its schemas. The metadata becomes both: - the backend function/tool definitions, with dispatch flags added to each schema; and - the rendered `# Tools` preamble section. diff --git a/doc/architecture-tools.md b/doc/architecture-tools.md index 741d52a..5ef9fa9 100644 --- a/doc/architecture-tools.md +++ b/doc/architecture-tools.md @@ -179,7 +179,17 @@ A metadata-only tool needs only the first command. Test its command contract wit echo '{"pattern":"TODO"}' | bash -c 'YOUR_CMD' ``` -Agent profiles can load tools at startup with `autoLoad`. See [`architecture-toolsrv.md`](architecture-toolsrv.md) for discovery, loading, registry, and execution architecture. +Agent profiles may load tools at startup with `autoLoad`, but the default profile +uses an empty list and starts with only `client_9p`. Semantic tool hints tell the +agent to load additional tools through its own `ctl` file: + +```text +client_9p(op="rdwr", path="session/$OLLIE_SESSION_ID/agent/$OLLIE_UNAME/ctl", data="tool_load ") +``` + +After loading, the agent refreshes its model-facing schemas when the toolsrv +registry revision changes. See [`architecture-toolsrv.md`](architecture-toolsrv.md) +for discovery, loading, registry, and execution architecture. ## Repository examples diff --git a/doc/architecture-toolsrv.md b/doc/architecture-toolsrv.md index f56151a..339081b 100644 --- a/doc/architecture-toolsrv.md +++ b/doc/architecture-toolsrv.md @@ -80,6 +80,7 @@ The Ollie client generates a secret for the first connection, saves it for recon ├── tools ├── all ├── info +├── tools_rev ├── bypass/ │ ├── pending │ └── resolve @@ -102,6 +103,7 @@ The Ollie client generates a secret for the first connection, saves it for recon | `tools` | read/write | write an agent ID, then read its loaded tool list as JSON | | `all` | read | list all host-available tools and descriptions | | `info` | read | return `platform` and `arch` | +| `tools_rev` | read/write | write an agent ID, then read that agent’s loaded-tool registry revision | `tools` reads the registry for the supplied agent ID. `all` calls metadata discovery directly and is not the per-agent loaded set. @@ -145,7 +147,10 @@ type Registry struct { The registry is deliberately separate from discovery. Discovery describes every tool available on the host. Loading makes a tool callable for one agent. `Load` resolves current metadata and increments that agent's revision. `Unload` removes the tool and increments the revision. `Loaded` returns tools sorted by name. `Lookup` resolves one loaded tool. -The agent client polls or reads the tool listing after loading changes. The registry does not inspect executable contents. +The agent client reads `tools_rev` after tool rounds and refreshes its loaded-tool +schemas only when the agent-scoped revision changes. A zero revision means the +revision endpoint is unavailable, so the client falls back to refreshing. The +registry does not inspect executable contents. ## Request payloads and results diff --git a/doc/evolution.md b/doc/evolution.md index b290af2..bb3b1d0 100644 --- a/doc/evolution.md +++ b/doc/evolution.md @@ -97,6 +97,7 @@ gantt Split session/agent indexes :done, 2026-08-17, 1d Agent peers + consensus :done, 2026-08-19, 1d Embedding-guided discovery :done, 2026-08-20, 1d + One-tool bootstrap discovery :done, 2026-08-21, 1d ``` ## Phase 1: Monorepo Bootstrap (Apr 11) Started as independent git repos unified under a monorepo with submodules. @@ -1956,3 +1957,41 @@ disclosure keeps the prompt bounded. The embedding model is local and separate from the conversational backend, so provider choice does not affect discovery. --- + +## Phase 36: One-Tool Bootstrap and Progressive Capability Loading (Aug 21) + +The default agent profile now starts with exactly one callable tool: `client_9p`. +The previous static `autoLoad` list was removed. This makes the runtime +capability surface explicit: the agent can begin with the namespace client and +load everything else through its own agent `ctl` file. + +Semantic matching remains a hint, not an implicit capability grant. When a +request matches a tool description, the agent receives the tool name and the +9P operation required to load it. The model calls `client_9p` with: + +```text +rdwr session/$OLLIE_SESSION_ID/agent/$OLLIE_UNAME/ctl +tool_load +``` + +The agent runtime refreshes its model-facing schemas after a load or unload. +`toolsrv` exposes an agent-scoped `tools_rev` request/response file so the +client can detect registry changes without rebuilding tool state on every tool +round. A revision of zero is treated as unavailable and preserves the safe +refresh behavior. + +This completes the progressive-disclosure path: + +```text +client_9p → agent ctl → toolsrv registry → loaded tool schema → tool call +``` + +The important boundary is unchanged. `olliesrv` still owns prompting and the +agent loop; `toolsrv` remains authoritative for discovery, loading, execution, +sandboxing, and process state. The change removes ambient startup capability +without adding a new orchestration subsystem. + +The `client_9p` script also expands `$OLLIE_SESSION_ID` and `$OLLIE_UNAME` in +virtual namespace paths. This is required because JSON argument parsing does not +perform shell expansion, and keeps the documented namespace examples directly +callable by the model.