@karmaniverous/jeeves-watcher-openclaw 0.6.1 → 0.7.0

package/README.md

@@ -53,10 +53,11 @@ On startup, the plugin writes a `## Watcher` section to `TOOLS.md` in the agent'
 | `watcher_status` | Service health, uptime, and collection stats |
 | `watcher_search` | Semantic search across indexed documents |
 | `watcher_enrich` | Enrich document metadata via rules engine |
-| `watcher_query` | Query the merged virtual document via JSONPath |
+| `watcher_config` | Query the effective runtime config via JSONPath |
+| `watcher_walk` | Walk watched filesystem paths with glob intersection |
 | `watcher_validate` | Validate a watcher configuration |
 | `watcher_config_apply` | Apply a new configuration |
-| `watcher_reindex` | Trigger a full reindex |
+| `watcher_reindex` | Trigger a scoped reindex with blast area plan |
 | `watcher_scan` | Filter-only point query with cursor pagination |
 | `watcher_issues` | List indexing issues and errors |
 

package/dist/index.js

@@ -79,24 +79,14 @@ async function generateWatcherMenu(apiUrl) {
     const activeRules = [];
     const watchPaths = [];
     const ignoredPaths = [];
+    const scoreThresholds = { strong: 0.75, relevant: 0.5, noise: 0.25 };
     try {
-        const [statusRes, rulesRes, pathsRes, ignoredRes] = (await Promise.all([
+        const [statusRes, rulesRes, pathsRes, thresholdsRes, ignoredRes] = (await Promise.all([
             fetchJson(`${apiUrl}/status`),
-            fetchJson(`${apiUrl}/config/query`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ path: '$.inferenceRules[*]' }),
-            }),
-            fetchJson(`${apiUrl}/config/query`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ path: '$.watch.paths[*]' }),
-            }),
-            fetchJson(`${apiUrl}/config/query`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ path: '$.watch.ignored[*]' }),
-            }),
+            fetchJson(`${apiUrl}/config?path=${encodeURIComponent('$.inferenceRules[*]')}`),
+            fetchJson(`${apiUrl}/config?path=${encodeURIComponent('$.watch.paths[*]')}`),
+            fetchJson(`${apiUrl}/config?path=${encodeURIComponent('$.search.scoreThresholds')}`),
+            fetchJson(`${apiUrl}/config?path=${encodeURIComponent('$.watch.ignored[*]')}`),
         ]));
         pointCount = statusRes.collection?.pointCount ?? 0;
         if (Array.isArray(rulesRes.result)) {
@@ -119,6 +109,16 @@ async function generateWatcherMenu(apiUrl) {
                     ignoredPaths.push(p);
             }
         }
+        if (Array.isArray(thresholdsRes.result) &&
+            thresholdsRes.result.length > 0) {
+            const t = thresholdsRes.result[0];
+            if (typeof t.strong === 'number')
+                scoreThresholds.strong = t.strong;
+            if (typeof t.relevant === 'number')
+                scoreThresholds.relevant = t.relevant;
+            if (typeof t.noise === 'number')
+                scoreThresholds.noise = t.noise;
+        }
     }
     catch {
         let qdrantStatus = '*Unknown*';
@@ -153,10 +153,10 @@ async function generateWatcherMenu(apiUrl) {
         '**Scan-first rule:** When a task involves structural queries (file enumeration, staleness checks, domain listing, counts), use `watcher_scan` instead of `watcher_search`. Scan does NOT use embeddings and does NOT accept a query string.',
         '**Search-first rule:** When a task involves finding, reading, or modifying files in indexed paths, run `watcher_search` FIRST — even if you already know the file path. Search surfaces related files you may not have considered and catches stale artifacts. Direct filesystem access is for acting on search results, not bypassing them.',
         '',
-        '### Score Interpretation:',
-        '* **Strong:** >= 0.75',
-        '* **Relevant:** >= 0.50',
-        '* **Noise:** < 0.25',
+        '### Score Interpretation (see skill for detail):',
+        `* **Strong:** >= ${String(scoreThresholds.strong)} — High confidence. Use directly.`,
+        `* **Relevant:** >= ${String(scoreThresholds.relevant)} — Likely useful. Verify context before relying on it.`,
+        `* **Noise:** < ${String(scoreThresholds.noise)} — Discard. If all results are noise, broaden your query or try different terms.`,
         '',
         "### What's on the menu:",
     ];
@@ -379,23 +379,23 @@ function registerWatcherTools(api, baseUrl) {
             ],
         },
         {
-            name: 'watcher_query',
-            description: 'Query the merged virtual document via JSONPath.',
+            name: 'watcher_config',
+            description: 'Query the effective runtime config via JSONPath. Returns the full resolved merged document when no path is provided.',
             parameters: {
                 type: 'object',
-                required: ['path'],
                 properties: {
-                    path: { type: 'string', description: 'JSONPath expression.' },
-                    resolve: {
-                        type: 'array',
-                        items: { type: 'string', enum: ['files', 'globals'] },
-                        description: 'Resolution scopes to include (e.g., ["files"], ["globals"], or both).',
+                    path: {
+                        type: 'string',
+                        description: 'JSONPath expression (optional).',
                     },
                 },
             },
             buildRequest: (params) => {
-                const body = pickDefined(params, ['path', 'resolve']);
-                return ['/config/query', body];
+                const path = params.path;
+                if (path) {
+                    return [`/config?path=${encodeURIComponent(path)}`];
+                }
+                return ['/config'];
             },
         },
         {
@@ -443,14 +443,29 @@ function registerWatcherTools(api, baseUrl) {
                 properties: {
                     scope: {
                         type: 'string',
-                        enum: ['rules', 'full'],
-                        description: 'Reindex scope: "rules" (default) re-applies inference rules; "full" re-embeds everything.',
+                        enum: ['rules', 'full', 'issues', 'path', 'prune'],
+                        description: 'Reindex scope: "rules" (default) re-applies inference rules; "full" re-embeds everything; "issues" re-processes files with errors; "path" reindexes a specific file or directory (requires path parameter); "prune" deletes points for files no longer in watch scope.',
+                    },
+                    path: {
+                        oneOf: [
+                            { type: 'string' },
+                            { type: 'array', items: { type: 'string' } },
+                        ],
+                        description: 'Target file or directory path (required when scope is "path"). Accepts a single path or array of paths.',
+                    },
+                    dryRun: {
+                        type: 'boolean',
+                        description: 'When true, compute and return the blast area plan without executing. Returns counts by root showing impact.',
                     },
                 },
             },
             buildRequest: (params) => [
-                '/config-reindex',
-                { scope: params.scope ?? 'rules' },
+                '/reindex',
+                {
+                    scope: params.scope ?? 'rules',
+                    ...(params.path ? { path: params.path } : {}),
+                    ...(params.dryRun ? { dryRun: true } : {}),
+                },
             ],
         },
         {
@@ -500,6 +515,22 @@ function registerWatcherTools(api, baseUrl) {
             parameters: { type: 'object', properties: {} },
             buildRequest: () => ['/issues'],
         },
+        {
+            name: 'watcher_walk',
+            description: 'Walk watched filesystem paths with glob intersection. Returns matching file paths from all configured watch roots, applying watch.ignored and gitignore filtering.',
+            parameters: {
+                type: 'object',
+                required: ['globs'],
+                properties: {
+                    globs: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Glob patterns to intersect with watch paths (e.g., ["**/.meta/meta.json"]).',
+                    },
+                },
+            },
+            buildRequest: (params) => ['/walk', { globs: params.globs }],
+        },
     ];
     for (const tool of tools) {
         registerApiTool(api, baseUrl, tool);

package/dist/skills/jeeves-watcher/SKILL.md

@@ -30,9 +30,7 @@ curl -X POST http://127.0.0.1:<PORT>/search \
   -d '{"query": "search text", "limit": 5}'
 
 # Query config
-curl -X POST http://127.0.0.1:<PORT>/config/query \
-  -H "Content-Type: application/json" \
-  -d '{"path": "$.inferenceRules[*].name"}'
+curl http://127.0.0.1:<PORT>/config
 ```
 
 **Key endpoints:**
@@ -40,14 +38,15 @@ curl -X POST http://127.0.0.1:<PORT>/config/query \
 |----------|--------|---------|
 | `/status` | GET | Health check, uptime, collection stats |
 | `/search` | POST | Semantic search (main query interface) |
-| `/config/query` | POST | JSONPath query over merged virtual document |
+| `/config` | GET | Full resolved config; optional `?path=<jsonpath>` filter |
 | `/config/validate` | POST | Validate candidate config |
 | `/config/apply` | POST | Apply config changes |
-| `/config-reindex` | POST | Trigger reindex |
+| `/reindex` | POST | Trigger reindex |
 | `/metadata` | POST | Enrich document metadata |
 | `/scan` | POST | Filter-only point query (no embeddings) |
+| `/walk` | POST | Filesystem walk with glob intersection |
 | `/issues` | GET | Runtime embedding failures |
-| `/rules/register` | POST | Register virtual inference rules |
+| `/rules/register` | POST | Register virtual inference rules (auto-triggers rules reindex) |
 | `/rules/unregister` | DELETE | Remove virtual rules by source |
 | `/points/delete` | POST | Delete points matching a Qdrant filter |
 
@@ -350,12 +349,17 @@ Set or update metadata on a document.
 - `metadata` (object, required) — key-value metadata to merge
 
 ### `watcher_status`
-Service health check. Returns uptime, collection stats, reindex status.
+Service health check. Returns uptime, version, collection stats, reindex status, and initial scan progress.
+
+After a service restart, the `initialScan` field shows scan progress:
+- `active: true` — filesystem walk in progress; `filesMatched` and `filesEnqueued` grow until chokidar completes
+- `active: false` with `completedAt`/`durationMs` — scan finished
+
+Use this to determine if the service is still initializing after a restart.
 
-### `watcher_query`
-Query the merged virtual document via JSONPath.
-- `path` (string, required) — JSONPath expression
-- `resolve` (string[], optional) — `["files"]`, `["globals"]`, or `["files","globals"]`
+### `watcher_config`
+Query the effective runtime config via JSONPath. Returns the full resolved merged document when no path is provided.
+- `path` (string, optional) — JSONPath expression
 
 ### `watcher_validate`
 Validate config and optionally test file paths.
@@ -371,10 +375,38 @@ Apply config changes atomically.
 Validates, writes to disk, and triggers configured reindex behavior. Returns validation errors if invalid.
 
 ### `watcher_reindex`
-Trigger a reindex.
-- `scope` (string, optional) — `"rules"` (default) or `"full"`
+Trigger a reindex operation. All scopes return a `plan` object showing blast area before execution begins.
+
+**Parameters:**
+- `scope` (string, optional) — Reindex scope. Default: `"rules"`. One of:
+  - `"rules"` — Re-apply inference rules to all watched files. No re-embedding. Lightweight.
+  - `"full"` — Re-extract text, re-embed, and re-apply rules for all watched files. Expensive.
+  - `"issues"` — Re-process only files that previously failed embedding (from `watcher_issues`).
+  - `"path"` — Re-embed a specific file or all files under a directory. Requires `path` parameter.
+  - `"prune"` — Delete Qdrant points for files no longer in watch scope (removed paths, gitignored files, stale data). No re-embedding. Pure cleanup.
+- `path` (string, required when scope is `"path"`) — Target file or directory path.
+- `dryRun` (boolean, optional) — When `true`, compute and return the blast area plan without executing. Returns synchronously.
+
+**Response (normal):**
+```json
+{ "status": "started", "scope": "rules", "plan": { "total": 148000, "toProcess": 148000, "toDelete": 0, "byRoot": { "j:/domains": 95000, "j:/config": 3000 } } }
+```
+
+**Response (dryRun):**
+```json
+{ "status": "dry_run", "scope": "prune", "plan": { "total": 562000, "toProcess": 0, "toDelete": 2300, "byRoot": { "j:/jeeves/node_modules": 1800, "j:/jeeves/.bridge": 500 } } }
+```
 
-Rules scope re-applies inference rules without re-embedding (lightweight). Full scope re-processes all files.
+**Plan fields:**
+- `total` — Total points (prune) or files (other scopes) examined.
+- `toProcess` — Items to embed/re-apply rules (0 for prune).
+- `toDelete` — Points to delete (prune only, 0 for others).
+- `byRoot` — Counts grouped by watch root prefix. Shows where the impact concentrates.
+
+**Guidance:**
+- Use `dryRun: true` before any large-blast operation to preview impact.
+- `prune` is safe — it only deletes orphaned points, never re-embeds. Use after changing watch paths, fixing gitignore, or cleaning up stale data.
+- `prune` is NOT triggered by config-watch auto-reindex (too dangerous for auto-trigger).
 
 
 ### `watcher_scan`
@@ -417,6 +449,30 @@ do {
 ### `watcher_issues`
 Get runtime embedding failures. Returns `{ filePath: IssueRecord }` showing files that failed and why.
 
+### `watcher_walk`
+Walk watched filesystem paths with glob intersection. Returns matching file paths from all configured watch roots.
+- `globs` (string[], required) — glob patterns to intersect with watch paths
+
+**Response:**
+```json
+{
+  "paths": ["j:/domains/foo/.meta/meta.json", "j:/domains/bar/.meta/meta.json"],
+  "matchedCount": 2,
+  "scannedRoots": ["j:/domains", "j:/config"]
+}
+```
+
+**Use cases:**
+- Discover files matching a pattern across all watched directories (e.g., `["**/.meta/meta.json"]`)
+- Enumerate files before rule registration to understand scope
+- Find files that aren't yet indexed (no Qdrant dependency — works even before first embedding)
+
+**Key differences from `watcher_scan`:**
+- Walks the actual filesystem, not the Qdrant index
+- No embedding or indexing required — works immediately after service start
+- Returns file paths only (no metadata, no vectors)
+- Applies `watch.ignored` and gitignore filtering automatically
+
 ## Query Planning: Scan vs Search
 
 **Decision rule:** If the query has no semantic/natural-language dimension, use `watcher_scan`. If you need meaning-based similarity, use `watcher_search`.
@@ -523,7 +579,7 @@ Each result from `watcher_search` contains:
 | `payload.content_hash` | string | Hash of the full document content |
 | `payload.matched_rules` | string[] | Names of inference rules that matched |
 
-Additional metadata fields depend on the deployment's inference rules (e.g., `domain`, `status`, `author`). Use `watcher_query` to discover available fields.
+Additional metadata fields depend on the deployment's inference rules (e.g., `domain`, `status`, `author`). Use `watcher_config` to discover available fields.
 
 ## Query Planning (Per Search Task)
 
@@ -531,7 +587,7 @@ Identify relevant rule(s) from the orientation model, then retrieve their schema
 
 **Retrieve complete schema for a rule:**
 ```
-watcher_query: path="$.inferenceRules[?(@.name=='jira-issue')].schema"
+watcher_config: path="$.inferenceRules[?(@.name=='jira-issue')].schema"
               resolve=["files","globals"]
 ```
 
@@ -539,7 +595,7 @@ Returns the fully merged schema with properties, types, `set` provenance, `uiHin
 
 **For select/multiselect fields without `enum` in schema:**
 ```
-watcher_query: path="$.inferenceRules[?(@.name=='jira-issue')].values.status"
+watcher_config: path="$.inferenceRules[?(@.name=='jira-issue')].values.status"
 ```
 
 Retrieves valid filter values from the runtime values index (distinct values accumulated during embedding).
@@ -613,9 +669,9 @@ A consuming UI will necessarily compose simple single-field filters. The assista
 
 ### Score Interpretation
 Use `scoreThresholds` from config (queried during orientation). Values are deployment-specific, constrained to [-1, 1]:
-- `strong` — minimum score for a strong match
-- `relevant` — minimum score for relevance
-- `noise` — maximum score below which results are noise
+- `strong` — minimum score for a strong match. **Action:** High confidence. Use these results directly.
+- `relevant` — minimum score for relevance. **Action:** Likely useful but verify context before relying on them.
+- `noise` — maximum score below which results are noise. **Action:** Discard. If all results fall below this threshold, broaden your query or try different terms.
 
 ### Chunk Grouping
 Multiple results with the same `file_path` are chunks of one document. Read the full file for complete context.
@@ -623,7 +679,7 @@ Multiple results with the same `file_path` are chunks of one document. Read the
 ### Schema Lookup
 Use `matched_rules` on results to look up applicable schemas for metadata interpretation:
 ```
-watcher_query: path="$.inferenceRules[?(@.name=='jira-issue')].schema"
+watcher_config: path="$.inferenceRules[?(@.name=='jira-issue')].schema"
               resolve=["files","globals"]
 ```
 
@@ -636,7 +692,7 @@ Search gives you chunks; use `read` with `file_path` for the complete document.
 
 When uncertain whether a file is indexed, use the path test endpoint:
 ```
-watcher_query: path="$.inferenceRules[?(@.name=='<rule>')].match"
+watcher_config: path="$.inferenceRules[?(@.name=='<rule>')].match"
 ```
 
 Or check if a specific path would match:
@@ -672,15 +728,18 @@ Progress is reported via `watcher_status` (`reindex.filesProcessed` / `reindex.t
 ### When to Reindex
 - **Rules scope** (`"rules"`): Changed rule matching patterns, set expressions, schema mappings. No re-embedding needed.
 - **Full scope** (`"full"`): Changed embedding config, added watch paths, broad schema restructuring. Re-embeds everything.
+- **Issues scope** (`"issues"`): After fixing the root cause of embedding failures (permissions, encoding, file format). Re-processes only failed files.
+- **Path scope** (`"path"`): Edited files in a specific directory and want to force re-embedding without a full reindex. Or a single file's embedding looks wrong.
+- **Prune scope** (`"prune"`): After changing `watch.paths`, adding gitignore rules, or discovering stale/orphaned points (e.g., indexed `node_modules`). Deletes points for out-of-scope files. Always `dryRun: true` first to preview.
 
 ---
 
 ## Diagnostics
 
 ### Escalation Path
-1. `watcher_status` — is the service healthy? Is a reindex running?
+1. `watcher_status` — is the service healthy? Is a reindex running? Is the initial scan still active?
 2. `watcher_issues` — what files are failing and why?
-3. `watcher_query` with `$.issues` — same data via JSONPath
+3. `watcher_config` with `$.issues` — same data via JSONPath
 4. Check logs at the configured log path
 
 ### Error Categories

package/dist/src/helpers.d.ts

@@ -39,12 +39,8 @@ export interface ToolResult {
 }
 /** Resolve the watcher API base URL from plugin config. */
 export declare function getApiUrl(api: PluginApi): string;
-/** Resolve the cache TTL for plugin hooks from config. */
-export declare function getCacheTtlMs(api: PluginApi): number;
 /** Format a successful tool result. */
 export declare function ok(data: unknown): ToolResult;
-/** Format an error tool result. */
-export declare function fail(error: unknown): ToolResult;
 /** Format a connection error with actionable guidance. */
 export declare function connectionFail(error: unknown, baseUrl: string): ToolResult;
 /** Fetch JSON from a URL, throwing on non-OK responses. */

package/dist/src/promptInjection.d.ts

@@ -1,11 +1,5 @@
-import { type PluginApi } from './helpers.js';
 /**
  * Fetches data from the watcher API and generates a Markdown menu string.
  * The string is platform-agnostic and safe to inject into TOOLS.md.
  */
 export declare function generateWatcherMenu(apiUrl: string): Promise<string>;
-/**
- * Hook handler for agent:bootstrap.
- * Injects/updates the Watcher Menu into the TOOLS.md payload.
- */
-export declare function handleAgentBootstrap(event: unknown, api: PluginApi): Promise<void>;

package/dist/src/toolsWriter.d.ts

@@ -10,11 +10,3 @@ import { type PluginApi } from './helpers.js';
  * Writes immediately on startup, then refreshes every REFRESH_INTERVAL_MS.
  */
 export declare function startToolsWriter(api: PluginApi): void;
-/**
- * Force an immediate refresh (e.g., after watcher_config_apply).
- */
-export declare function forceRefreshToolsMd(api: PluginApi): Promise<void>;
-/**
- * Stop the periodic writer (for cleanup).
- */
-export declare function stopToolsWriter(): 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.6.1",
+  "version": "0.7.0",
   "skills": [
     "dist/skills/jeeves-watcher"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-watcher-openclaw",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "author": "Jason Williscroft",
   "description": "OpenClaw plugin for jeeves-watcher — semantic search and metadata enrichment tools",
   "license": "BSD-3-Clause",