Skip to content

Commit 965fa05

Browse files
fuller-stack-devfuller-stack-dev
authored
feat: add tool search directory mode
Add an experimental directory mode that keeps large authorized tool schemas deferred while exposing bounded discovery, exact deferred hydration, and normal OpenClaw policy/hook execution. Client tools remain directly visible; ambiguous hidden names fail closed.
1 parent 9f32bea commit 965fa05

26 files changed

Lines changed: 2284 additions & 96 deletions

‎docs/.generated/config-baseline.sha256‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
37b56008790612b8293930b6a29d74490e98daa90f954fca9d133fcc28645c4c config-baseline.json
2-
75b64c2ea081369ba4306493313a8a4cd48b784145f92fed995e6b77a5df350d config-baseline.core.json
3-
17d64c9799dfa239a49493413f1100bdd9237e9b67aaeae331a4604dbc227023 config-baseline.channel.json
4-
f9d1f50bfa8403891e76cd99dc1357cdece4a71e8ae18a39b190c2a14e6f97b0 config-baseline.plugin.json
1+
b5887d8c887a53a997dc4c5220f6b9d5adffbddb58e4b25ae0d20ca06850d0ca config-baseline.json
2+
72bb80be618406f3337eaa2560d2559a35e49bd29576de8dd4a3aec1a6a94d92 config-baseline.core.json
3+
1218f5555541b61bd5ddcac6441f15061b44789e2471d4ffecbe3059777c55c1 config-baseline.channel.json
4+
b0dec5acfe60557e728e5ad03cc36d19d2432d51f755656c97846afa7fbe374a config-baseline.plugin.json

‎docs/.generated/plugin-sdk-api-baseline.sha256‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
0cca9891634edbdd08dfcebe0f29b36d7cf2729fd0c2ec3dd4615acef209a7eb plugin-sdk-api-baseline.json
2-
2c763baab30411800b8931857e0a61e2710202394c2284f4c98e3e2f4231f88c plugin-sdk-api-baseline.jsonl
1+
ab2a32b037be61953ad32d2498468bc812b0794ba6135530cefd1c8326d69de8 plugin-sdk-api-baseline.json
2+
2c7bca3b46e0edd08ed445a241bb0a80b77635bf82825d5201ce41a8759c0e56 plugin-sdk-api-baseline.jsonl

‎docs/tools/tool-search.md‎

Lines changed: 51 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,9 @@ search or dynamic-tools surface. Codex-native code mode, tool search, deferred
1616
dynamic tools, and nested tool calls are stable Codex harness surfaces and do
1717
not depend on `tools.toolSearch`.
1818

19-
When enabled for OpenClaw runs, the model receives one `tool_search_code` tool by default.
20-
That tool runs a short JavaScript body in an isolated Node subprocess with an
21-
`openclaw.tools` bridge:
19+
When enabled for OpenClaw runs, the model receives one `tool_search_code` tool
20+
by default. That tool runs a short JavaScript body in an isolated Node
21+
subprocess with an `openclaw.tools` bridge:
2222

2323
```js
2424
const hits = await openclaw.tools.search("create a GitHub issue");
@@ -49,8 +49,8 @@ run:
4949
3. List eligible MCP tools through the session MCP runtime.
5050
4. Add eligible client tools supplied for the current run.
5151
5. Index compact descriptors for search.
52-
6. Expose either the OpenClaw code bridge or the structured fallback tools to the
53-
model.
52+
6. Expose the OpenClaw code bridge, the structured fallback tools, or the
53+
compact directory surface to the model.
5454

5555
At execution time every real tool call returns to OpenClaw. The isolated Node
5656
runtime does not hold plugin implementations, MCP client objects, or secrets.
@@ -59,18 +59,26 @@ normal policy, approval, hook, logging, and result handling still apply.
5959

6060
## Modes
6161

62-
`tools.toolSearch` has two model-facing modes:
62+
`tools.toolSearch` has three model-facing modes:
6363

6464
- `code`: exposes `tool_search_code`, the default compact JavaScript bridge.
6565
- `tools`: exposes `tool_search`, `tool_describe`, and `tool_call` as plain
6666
structured tools for providers that should not receive code.
67-
68-
Both modes use the same catalog and execution path. The only difference is the
69-
shape the model sees. If the current runtime cannot launch the isolated Node
70-
code-mode child process, the default `code` mode falls back to `tools` before
71-
catalog compaction.
72-
73-
Both modes are experimental. Prefer direct tool exposure for small OpenClaw tool
67+
- `directory`: exposes `tool_search`, `tool_describe`, and `tool_call` plus a
68+
bounded prompt directory of available tool names and descriptions for
69+
providers that should see tool names without every full schema. OpenClaw can
70+
also expose a small bounded set of likely or required tool schemas directly
71+
for the current turn.
72+
73+
All modes use the same policy-filtered catalog and normal OpenClaw execution
74+
path. If the current runtime cannot launch the isolated Node code-mode child
75+
process, the default `code` mode falls back to `tools` before catalog
76+
compaction. In `directory` mode, client-provided tools stay directly visible
77+
for the current run while OpenClaw tools, plugin tools, and MCP tools can be
78+
compacted behind the directory catalog. A direct call to an exact hidden
79+
directory name is hydrated from that same authorized catalog before execution.
80+
81+
All modes are experimental. Prefer direct tool exposure for small OpenClaw tool
7482
catalogs, and prefer the Codex-native stable surfaces for Codex harness runs.
7583

7684
There is no separate source-selection config. When Tool Search is enabled, the
@@ -90,7 +98,10 @@ Tool Search changes the shape:
9098
contract
9199
- Tool Search tools mode: the model sees three compact structured fallback
92100
tools
93-
- during the turn: the model loads only the tool schemas it actually needs
101+
- Tool Search directory mode: the model sees a bounded directory plus
102+
search/describe/call controls and a small bounded set of likely or required
103+
schemas
104+
- during the turn: the model can load remaining schemas as needed
94105

95106
Direct tool exposure is still the right default for small catalogs. Tool Search
96107
is best when one run can see many tools, especially from MCP servers or
@@ -132,6 +143,20 @@ The structured fallback mode exposes the same operations as tools:
132143
- `tool_describe`
133144
- `tool_call`
134145

146+
Directory mode exposes:
147+
148+
- `tool_search`
149+
- `tool_describe`
150+
- `tool_call`
151+
152+
It also keeps client-provided tools directly visible and may expose a small
153+
bounded set of likely or required catalog tool schemas directly for the current
154+
turn. If the bounded directory omits entries, use `tool_search` to find them. If
155+
the model requests an exact hidden directory tool name directly, OpenClaw
156+
hydrates it from the authorized catalog before normal execution.
157+
Directory-mode client tool names must not collide with OpenClaw, plugin, or MCP
158+
tool names because exact deferred dispatch uses those names.
159+
135160
## Runtime boundary
136161

137162
The code bridge runs in a short-lived Node subprocess. The subprocess starts
@@ -186,6 +211,18 @@ Use the structured fallback tools instead for OpenClaw runs:
186211
}
187212
```
188213

214+
Use the compact directory surface instead for OpenClaw runs:
215+
216+
```json5
217+
{
218+
tools: {
219+
toolSearch: {
220+
mode: "directory",
221+
},
222+
},
223+
}
224+
```
225+
189226
Tune code-mode timeout and search result limits:
190227

191228
```json5

0 commit comments

Comments
 (0)