@karmaniverous/jeeves-watcher-openclaw 0.16.0-3 → 0.16.0-5

package/README.md

@@ -76,6 +76,14 @@ The plugin builds on [`@karmaniverous/jeeves`](https://www.npmjs.com/package/@ka
 | `watcher_vcs_exclude` | Exclude or re-include paths from version tracking |
 | `watcher_vcs_check` | Check whether a path is excluded from version tracking and why |
 
+### Direct tools under OpenClaw Tool Search
+
+OpenClaw 2026.9+ **Tool Search** moves optional plugin tools out of the model-visible tool list into a hidden catalog reachable only through `tool_search`. `watcher_search` and `watcher_scan` are registered with `catalogMode: 'direct-only'`, so they stay directly visible to the model.
+
+**Why:** semantic search only pays off if the model reaches for it _before_ falling back to grep or filesystem walks. Hidden behind a catalog lookup, it is rarely discovered and archive recall silently degrades.
+
+**Trade-off:** these two tools always occupy space in the model's tool list, and they do **not** appear in `tool_search` results. All other `watcher_*` tools remain catalog-eligible. On OpenClaw versions without Tool Search the property is ignored.
+
 ## Documentation
 
 Full docs for the jeeves-watcher service and this plugin:

package/dist/index.js

@@ -29356,6 +29356,10 @@ function warnIfConfigRootUnset(api) {
 /**
  * Wrap a tool so invocations that read `configRoot` (per `readsConfigRoot`)
  * resolve core before executing; all other invocations run unguarded.
+ *
+ * @remarks
+ * Every other descriptor property (e.g. OpenClaw `catalogMode`) is carried
+ * through unchanged; only `execute` is replaced.
  */
 function guardTool(tool, ensureCore, readsConfigRoot = () => true) {
     return {
@@ -29461,29 +29465,29 @@ function createWatcherComponent(pluginVersion) {
 }
 
 /**
- * @module plugin/watcherTools
- * Domain-specific watcher tool registrations (14 tools) for the OpenClaw plugin.
+ * @module plugin/apiTool
+ * Generic HTTP-backed watcher tool registration: config shape, request helpers, and ok/connectionFail wrapping.
  */
 /** Register a single API tool with standard try/catch + ok/connectionFail. */
 function registerApiTool(api, baseUrl, config) {
-    api.registerTool({
+    const tool = {
         name: config.name,
         description: config.description,
         parameters: config.parameters,
+        ...(config.catalogMode ? { catalogMode: config.catalogMode } : {}),
         execute: async (_id, params) => {
             try {
                 const [endpoint, body] = config.buildRequest(params);
                 const url = `${baseUrl}${endpoint}`;
-                const data = body !== undefined
-                    ? await postJson(url, body)
-                    : await fetchJson(url);
+                const data = body !== undefined ? await postJson(url, body) : await fetchJson(url);
                 return ok(data);
             }
             catch (error) {
                 return connectionFail(error, baseUrl, PLUGIN_ID);
             }
         },
-    }, { optional: true });
+    };
+    api.registerTool(tool, { optional: true });
 }
 /** Build a query string from defined params. */
 function buildQuery(params, keys) {
@@ -29506,12 +29510,184 @@ function pickDefined(params, keys) {
     }
     return body;
 }
-/** Register the 14 domain-specific watcher_* tools with the OpenClaw plugin API. */
+
+/**
+ * @module plugin/vcsTools
+ * Version-tracking (watcher_vcs_*) tool configs for the OpenClaw plugin; each maps tool params to a watcher VCS endpoint.
+ */
+/** The 7 watcher_vcs_* tool configs. */
+const vcsToolConfigs = [
+    {
+        name: 'watcher_vcs_status',
+        description: 'Get version tracking health: enabled state, tracked roots, remote status, last activity',
+        parameters: { type: 'object', properties: {} },
+        buildRequest: () => [getEndpoint('vcsStatus').path],
+    },
+    {
+        name: 'watcher_vcs_history',
+        description: 'Query change history by path or glob with optional date range',
+        parameters: {
+            type: 'object',
+            required: ['glob'],
+            properties: {
+                glob: {
+                    type: 'string',
+                    description: 'Path or glob pattern to query history for.',
+                },
+                since: {
+                    type: 'string',
+                    description: 'Start date (ISO 8601 or git date string).',
+                },
+                until: {
+                    type: 'string',
+                    description: 'End date (ISO 8601 or git date string).',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of history entries to return.',
+                },
+            },
+        },
+        buildRequest: (params) => [
+            `${getEndpoint('vcsHistory').path}${buildQuery(params, ['glob', 'since', 'until', 'limit'])}`,
+        ],
+    },
+    {
+        name: 'watcher_vcs_show',
+        description: 'Retrieve file content at a specific version',
+        parameters: {
+            type: 'object',
+            required: ['path', 'commit'],
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'File path to retrieve.',
+                },
+                commit: {
+                    type: 'string',
+                    description: 'Version identifier.',
+                },
+            },
+        },
+        buildRequest: (params) => [
+            `${getEndpoint('vcsShow').path}${buildQuery(params, ['path', 'commit'])}`,
+        ],
+    },
+    {
+        name: 'watcher_vcs_diff',
+        description: 'Show what changed between two versions, or between a version and current',
+        parameters: {
+            type: 'object',
+            required: ['glob', 'commit'],
+            properties: {
+                glob: {
+                    type: 'string',
+                    description: 'Path or glob pattern to diff.',
+                },
+                commit: {
+                    type: 'string',
+                    description: 'Start version identifier.',
+                },
+                commitEnd: {
+                    type: 'string',
+                    description: 'End version identifier (defaults to current if omitted).',
+                },
+            },
+        },
+        buildRequest: (params) => [
+            `${getEndpoint('vcsDiff').path}${buildQuery(params, ['glob', 'commit', 'commitEnd'])}`,
+        ],
+    },
+    {
+        name: 'watcher_vcs_revert',
+        description: 'Undo changes by restoring files to a specific version',
+        parameters: {
+            type: 'object',
+            required: ['glob', 'commit'],
+            properties: {
+                glob: {
+                    type: 'string',
+                    description: 'Path or glob pattern to revert.',
+                },
+                commit: {
+                    type: 'string',
+                    description: 'Version to restore files to.',
+                },
+                existingOnly: {
+                    type: 'boolean',
+                    description: 'When true, only revert files that currently exist (skip deleted files).',
+                },
+            },
+        },
+        buildRequest: (params) => {
+            const body = pickDefined(params, ['glob', 'commit', 'existingOnly']);
+            return [getEndpoint('vcsRevert').path, body];
+        },
+    },
+    {
+        name: 'watcher_vcs_exclude',
+        description: 'Exclude or re-include paths from version tracking',
+        parameters: {
+            type: 'object',
+            required: ['glob'],
+            properties: {
+                glob: {
+                    type: 'string',
+                    description: 'Glob pattern to exclude or re-include.',
+                },
+                root: {
+                    type: 'string',
+                    description: 'Tracked root to target (defaults to auto-detect).',
+                },
+                remove: {
+                    type: 'boolean',
+                    description: 'When true, remove the exclusion rule (re-include the path).',
+                },
+            },
+        },
+        buildRequest: (params) => {
+            const body = pickDefined(params, ['glob', 'root', 'remove']);
+            return [getEndpoint('vcsExclude').path, body];
+        },
+    },
+    {
+        name: 'watcher_vcs_check',
+        description: 'Check whether a path is excluded from version tracking and why',
+        parameters: {
+            type: 'object',
+            required: ['path'],
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'File path to check exclusion status for.',
+                },
+            },
+        },
+        buildRequest: (params) => [
+            `${getEndpoint('vcsCheckExclusion').path}${buildQuery(params, ['path'])}`,
+        ],
+    },
+];
+
+/**
+ * @module plugin/watcherTools
+ * Domain-specific watcher tool registrations (14 tools) for the OpenClaw plugin.
+ */
+/**
+ * Register the 14 domain-specific watcher_* tools with the OpenClaw plugin API.
+ *
+ * @remarks
+ * `watcher_search` and `watcher_scan` are `catalogMode: 'direct-only'` so
+ * OpenClaw Tool Search keeps them model-visible: semantic search must be a
+ * direct tool or the model reaches for grep first. All other tools remain
+ * catalog-eligible.
+ */
 function registerWatcherTools(api, baseUrl) {
     const tools = [
         {
             name: 'watcher_search',
             description: 'Semantic search over indexed documents. Supports Qdrant filters.',
+            catalogMode: 'direct-only',
             parameters: {
                 type: 'object',
                 required: ['query'],
@@ -29615,6 +29791,7 @@ function registerWatcherTools(api, baseUrl) {
         {
             name: 'watcher_scan',
             description: 'Filter-only point query without vector search. Returns metadata for points matching a Qdrant filter. Use for structural queries: file enumeration, staleness checks, delta computation. Use watcher_search for semantic/similarity queries.',
+            catalogMode: 'direct-only',
             parameters: {
                 type: 'object',
                 required: ['filter'],
@@ -29678,157 +29855,7 @@ function registerWatcherTools(api, baseUrl) {
                 { globs: params.globs },
             ],
         },
-        // ── VCS tools ──────────────────────────────────────────────────────
-        {
-            name: 'watcher_vcs_status',
-            description: 'Get version tracking health: enabled state, tracked roots, remote status, last activity',
-            parameters: { type: 'object', properties: {} },
-            buildRequest: () => [getEndpoint('vcsStatus').path],
-        },
-        {
-            name: 'watcher_vcs_history',
-            description: 'Query change history by path or glob with optional date range',
-            parameters: {
-                type: 'object',
-                required: ['glob'],
-                properties: {
-                    glob: {
-                        type: 'string',
-                        description: 'Path or glob pattern to query history for.',
-                    },
-                    since: {
-                        type: 'string',
-                        description: 'Start date (ISO 8601 or git date string).',
-                    },
-                    until: {
-                        type: 'string',
-                        description: 'End date (ISO 8601 or git date string).',
-                    },
-                    limit: {
-                        type: 'number',
-                        description: 'Maximum number of history entries to return.',
-                    },
-                },
-            },
-            buildRequest: (params) => [
-                `${getEndpoint('vcsHistory').path}${buildQuery(params, ['glob', 'since', 'until', 'limit'])}`,
-            ],
-        },
-        {
-            name: 'watcher_vcs_show',
-            description: 'Retrieve file content at a specific version',
-            parameters: {
-                type: 'object',
-                required: ['path', 'commit'],
-                properties: {
-                    path: {
-                        type: 'string',
-                        description: 'File path to retrieve.',
-                    },
-                    commit: {
-                        type: 'string',
-                        description: 'Version identifier.',
-                    },
-                },
-            },
-            buildRequest: (params) => [
-                `${getEndpoint('vcsShow').path}${buildQuery(params, ['path', 'commit'])}`,
-            ],
-        },
-        {
-            name: 'watcher_vcs_diff',
-            description: 'Show what changed between two versions, or between a version and current',
-            parameters: {
-                type: 'object',
-                required: ['glob', 'commit'],
-                properties: {
-                    glob: {
-                        type: 'string',
-                        description: 'Path or glob pattern to diff.',
-                    },
-                    commit: {
-                        type: 'string',
-                        description: 'Start version identifier.',
-                    },
-                    commitEnd: {
-                        type: 'string',
-                        description: 'End version identifier (defaults to current if omitted).',
-                    },
-                },
-            },
-            buildRequest: (params) => [
-                `${getEndpoint('vcsDiff').path}${buildQuery(params, ['glob', 'commit', 'commitEnd'])}`,
-            ],
-        },
-        {
-            name: 'watcher_vcs_revert',
-            description: 'Undo changes by restoring files to a specific version',
-            parameters: {
-                type: 'object',
-                required: ['glob', 'commit'],
-                properties: {
-                    glob: {
-                        type: 'string',
-                        description: 'Path or glob pattern to revert.',
-                    },
-                    commit: {
-                        type: 'string',
-                        description: 'Version to restore files to.',
-                    },
-                    existingOnly: {
-                        type: 'boolean',
-                        description: 'When true, only revert files that currently exist (skip deleted files).',
-                    },
-                },
-            },
-            buildRequest: (params) => {
-                const body = pickDefined(params, ['glob', 'commit', 'existingOnly']);
-                return [getEndpoint('vcsRevert').path, body];
-            },
-        },
-        {
-            name: 'watcher_vcs_exclude',
-            description: 'Exclude or re-include paths from version tracking',
-            parameters: {
-                type: 'object',
-                required: ['glob'],
-                properties: {
-                    glob: {
-                        type: 'string',
-                        description: 'Glob pattern to exclude or re-include.',
-                    },
-                    root: {
-                        type: 'string',
-                        description: 'Tracked root to target (defaults to auto-detect).',
-                    },
-                    remove: {
-                        type: 'boolean',
-                        description: 'When true, remove the exclusion rule (re-include the path).',
-                    },
-                },
-            },
-            buildRequest: (params) => {
-                const body = pickDefined(params, ['glob', 'root', 'remove']);
-                return [getEndpoint('vcsExclude').path, body];
-            },
-        },
-        {
-            name: 'watcher_vcs_check',
-            description: 'Check whether a path is excluded from version tracking and why',
-            parameters: {
-                type: 'object',
-                required: ['path'],
-                properties: {
-                    path: {
-                        type: 'string',
-                        description: 'File path to check exclusion status for.',
-                    },
-                },
-            },
-            buildRequest: (params) => [
-                `${getEndpoint('vcsCheckExclusion').path}${buildQuery(params, ['path'])}`,
-            ],
-        },
+        ...vcsToolConfigs,
     ];
     for (const tool of tools) {
         registerApiTool(api, baseUrl, tool);

package/dist/src/apiTool.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @module plugin/apiTool
+ * Generic HTTP-backed watcher tool registration: config shape, request helpers, and ok/connectionFail wrapping.
+ */
+import { type PluginApi, type ToolDescriptor } from '@karmaniverous/jeeves';
+/**
+ * OpenClaw Tool Search catalog mode.
+ *
+ * @remarks
+ * Mirrors `AnyAgentTool['catalogMode']` in the OpenClaw plugin SDK
+ * (OpenClaw 2026.9+). `'direct-only'` keeps the tool model-visible instead of
+ * moving it into the hidden `tool_search` catalog. Declared locally because
+ * `ToolDescriptor` in `@karmaniverous/jeeves` does not carry it yet and
+ * `openclaw` is not a dependency of this package.
+ */
+export type ToolCatalogMode = 'direct-only';
+/** A tool descriptor carrying the optional OpenClaw catalog mode. */
+export type CatalogToolDescriptor = ToolDescriptor & {
+    /** OpenClaw Tool Search catalog mode (omitted = catalog-eligible). */
+    catalogMode?: ToolCatalogMode;
+};
+/** Config for a watcher API tool. */
+export interface ApiToolConfig {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    /** OpenClaw Tool Search catalog mode; omit to leave the tool catalog-eligible. */
+    catalogMode?: ToolCatalogMode;
+    /** Build the request: return [endpoint, body?]. No body = GET. */
+    buildRequest: (params: Record<string, unknown>) => [string, unknown?];
+}
+/** Register a single API tool with standard try/catch + ok/connectionFail. */
+export declare function registerApiTool(api: PluginApi, baseUrl: string, config: ApiToolConfig): void;
+/** Build a query string from defined params. */
+export declare function buildQuery(params: Record<string, unknown>, keys: string[]): string;
+/** Pick defined keys from params into a body object. */
+export declare function pickDefined(params: Record<string, unknown>, keys: string[]): Record<string, unknown>;

package/dist/src/apiTool.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lazyCore.d.ts

@@ -29,8 +29,12 @@ export declare function warnIfConfigRootUnset(api: PluginApi): boolean;
 /**
  * Wrap a tool so invocations that read `configRoot` (per `readsConfigRoot`)
  * resolve core before executing; all other invocations run unguarded.
+ *
+ * @remarks
+ * Every other descriptor property (e.g. OpenClaw `catalogMode`) is carried
+ * through unchanged; only `execute` is replaced.
  */
-export declare function guardTool(tool: ToolDescriptor, ensureCore: EnsureCore, readsConfigRoot?: ConfigRootPredicate): ToolDescriptor;
+export declare function guardTool<T extends ToolDescriptor>(tool: T, ensureCore: EnsureCore, readsConfigRoot?: ConfigRootPredicate): T;
 /**
  * Derive a plugin API whose `registerTool` guards the tools listed in
  * `readers` with {@link guardTool} (per call, using each tool's predicate);

package/dist/src/toolTestHarness.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module plugin/toolTestHarness
+ * Test-only helpers: a fetch stub and a plugin API that captures registered watcher tools by name. No side effects.
+ */
+import type { ToolRegistrationOptions } from '@karmaniverous/jeeves';
+import { type Mock } from 'vitest';
+import type { CatalogToolDescriptor } from './apiTool.js';
+/** Base URL used by tool tests. */
+export declare const BASE = "http://localhost:1936";
+/** Signature of the `fetch` stub. */
+type FetchStub = (...args: unknown[]) => Promise<unknown>;
+/** A `fetch` stub resolving to an OK JSON response carrying `data`. */
+export declare function mockFetch(data?: unknown): Mock<FetchStub>;
+/** A registered tool plus the options it was registered with. */
+export interface CapturedTool {
+    tool: CatalogToolDescriptor;
+    options?: ToolRegistrationOptions;
+}
+/** Register the watcher tools against a capturing API; returns them by name, in order. */
+export declare function captureTools(baseUrl?: string): Map<string, CapturedTool>;
+/** Invoke a captured tool by name. */
+export declare function run(tools: Map<string, CapturedTool>, name: string, params: Record<string, unknown>): Promise<import("@karmaniverous/jeeves").ToolResult>;
+export {};

package/dist/src/vcsTools.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @module plugin/vcsTools
+ * Version-tracking (watcher_vcs_*) tool configs for the OpenClaw plugin; each maps tool params to a watcher VCS endpoint.
+ */
+import { type ApiToolConfig } from './apiTool.js';
+/** The 7 watcher_vcs_* tool configs. */
+export declare const vcsToolConfigs: ApiToolConfig[];

package/dist/src/vcsTools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/watcherTools.d.ts

@@ -3,5 +3,13 @@
  * Domain-specific watcher tool registrations (14 tools) for the OpenClaw plugin.
  */
 import { type PluginApi } from '@karmaniverous/jeeves';
-/** Register the 14 domain-specific watcher_* tools with the OpenClaw plugin API. */
+/**
+ * Register the 14 domain-specific watcher_* tools with the OpenClaw plugin API.
+ *
+ * @remarks
+ * `watcher_search` and `watcher_scan` are `catalogMode: 'direct-only'` so
+ * OpenClaw Tool Search keeps them model-visible: semantic search must be a
+ * direct tool or the model reaches for grep first. All other tools remain
+ * catalog-eligible.
+ */
 export declare function registerWatcherTools(api: PluginApi, baseUrl: string): void;

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "jeeves-watcher-openclaw",
   "name": "Jeeves Watcher",
   "description": "Semantic search, metadata enrichment, and instance administration for a jeeves-watcher deployment.",
-  "version": "0.16.0-3",
+  "version": "0.16.0-5",
   "skills": ["dist/skills/jeeves-watcher"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -4,8 +4,8 @@
     "url": "https://github.com/karmaniverous/jeeves-watcher/issues"
   },
   "dependencies": {
-    "@karmaniverous/jeeves": "0.6.0-8",
-    "@karmaniverous/jeeves-watcher-core": "^0.2.6-1"
+    "@karmaniverous/jeeves": "0.6.0-9",
+    "@karmaniverous/jeeves-watcher-core": "^0.2.6-2"
   },
   "description": "OpenClaw plugin for jeeves-watcher — semantic search and metadata enrichment tools",
   "devDependencies": {
@@ -115,5 +115,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.16.0-3"
+  "version": "0.16.0-5"
 }