@karmaniverous/jeeves-watcher-openclaw 0.5.7 → 0.6.0

package/README.md

@@ -57,6 +57,7 @@ On startup, the plugin writes a `## Watcher` section to `TOOLS.md` in the agent'
 | `watcher_validate` | Validate a watcher configuration |
 | `watcher_config_apply` | Apply a new configuration |
 | `watcher_reindex` | Trigger a full reindex |
+| `watcher_scan` | Filter-only point query with cursor pagination |
 | `watcher_issues` | List indexing issues and errors |
 
 ## Documentation

package/dist/index.js

@@ -54,7 +54,7 @@ function connectionFail(error, baseUrl) {
     return fail(error);
 }
 /** Fetch JSON from a URL, throwing on non-OK responses. */
-async function fetchJson$1(url, init) {
+async function fetchJson(url, init) {
     const res = await fetch(url, init);
     if (!res.ok) {
         throw new Error('HTTP ' + String(res.status) + ': ' + (await res.text()));
@@ -63,20 +63,13 @@ async function fetchJson$1(url, init) {
 }
 /** POST JSON to a URL and return parsed response. */
 async function postJson(url, body) {
-    return fetchJson$1(url, {
+    return fetchJson(url, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(body),
     });
 }
 
-async function fetchJson(url, init) {
-    const res = await fetch(url, init);
-    if (!res.ok) {
-        throw new Error(`HTTP ${String(res.status)}: ${await res.text()}`);
-    }
-    return res.json();
-}
 /**
  * Fetches data from the watcher API and generates a Markdown menu string.
  * The string is platform-agnostic and safe to inject into TOOLS.md.
@@ -87,7 +80,7 @@ async function generateWatcherMenu(apiUrl) {
     const watchPaths = [];
     const ignoredPaths = [];
     try {
-        const [statusRes, rulesRes, pathsRes, ignoredRes] = await Promise.all([
+        const [statusRes, rulesRes, pathsRes, ignoredRes] = (await Promise.all([
             fetchJson(`${apiUrl}/status`),
             fetchJson(`${apiUrl}/config/query`, {
                 method: 'POST',
@@ -104,7 +97,7 @@ async function generateWatcherMenu(apiUrl) {
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({ path: '$.watch.ignored[*]' }),
             }),
-        ]);
+        ]));
         pointCount = statusRes.collection?.pointCount ?? 0;
         if (Array.isArray(rulesRes.result)) {
             for (const rule of rulesRes.result) {
@@ -128,11 +121,36 @@ async function generateWatcherMenu(apiUrl) {
         }
     }
     catch {
-        return '*Watcher service is currently unreachable.*';
+        let qdrantStatus = '*Unknown*';
+        try {
+            // Assuming Qdrant runs locally on the default port
+            const res = await fetch('http://127.0.0.1:6333/healthz', {
+                signal: AbortSignal.timeout(1000),
+            });
+            qdrantStatus = res.ok ? 'Running' : 'Error';
+        }
+        catch {
+            qdrantStatus = 'Down / Unreachable';
+        }
+        return `> **ACTION REQUIRED: Watcher service is unreachable.**
+> The jeeves-watcher service API at ${apiUrl} is down or not installed.
+> **Diagnostic Info:**
+> - Watcher API (${apiUrl}): Unreachable
+> - Qdrant (http://127.0.0.1:6333): ${qdrantStatus}
+>
+> **DO NOT** ignore this. Read the \`jeeves-watcher\` skill's **Bootstrap** section immediately and walk the user through the setup process. Use the diagnostic info above to determine if Qdrant needs installing/starting, or if only the watcher service needs attention.`;
+    }
+    if (pointCount === 0) {
+        return `> **ACTION REQUIRED: Watcher service is empty.**
+> The jeeves-watcher service is running at ${apiUrl} but has no indexed data.
+> The service has either just been installed (no configuration/data), or indexing hasn't run.
+>
+> **DO NOT** ignore this. Read the \`jeeves-watcher\` skill's **Bootstrap** section immediately and walk the user through the setup process to configure and reindex the workspace.`;
     }
     const lines = [
         `This environment includes a semantic search index (\`watcher_search\`) covering ${pointCount.toLocaleString()} document chunks.`,
         '**Escalation Rule:** Use `memory_search` for personal operational notes, decisions, and rules. Escalate to `watcher_search` when memory is thin, or when searching the broader archive (tickets, docs, code). ALWAYS use `watcher_search` BEFORE filesystem commands (exec, grep) when looking for information that matches the indexed categories below.',
+        '**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:',
@@ -285,7 +303,7 @@ function registerApiTool(api, baseUrl, config) {
                 const url = `${baseUrl}${endpoint}`;
                 const data = body !== undefined
                     ? await postJson(url, body)
-                    : await fetchJson$1(url);
+                    : await fetchJson(url);
                 return ok(data);
             }
             catch (error) {
@@ -303,7 +321,7 @@ function pickDefined(params, keys) {
     }
     return body;
 }
-/** Register all 8 watcher_* tools with the OpenClaw plugin API. */
+/** Register all 9 watcher_* tools with the OpenClaw plugin API. */
 function registerWatcherTools(api, baseUrl) {
     const tools = [
         {
@@ -435,6 +453,47 @@ function registerWatcherTools(api, baseUrl) {
                 { scope: params.scope ?? 'rules' },
             ],
         },
+        {
+            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.',
+            parameters: {
+                type: 'object',
+                required: ['filter'],
+                properties: {
+                    filter: {
+                        type: 'object',
+                        description: 'Qdrant filter object (required).',
+                    },
+                    limit: {
+                        type: 'number',
+                        description: 'Page size (default 100, max 1000).',
+                    },
+                    cursor: {
+                        type: 'string',
+                        description: 'Opaque cursor from previous response for pagination.',
+                    },
+                    fields: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Payload fields to return (projection).',
+                    },
+                    countOnly: {
+                        type: 'boolean',
+                        description: 'If true, return { count } instead of points.',
+                    },
+                },
+            },
+            buildRequest: (params) => {
+                const body = pickDefined(params, [
+                    'filter',
+                    'limit',
+                    'cursor',
+                    'fields',
+                    'countOnly',
+                ]);
+                return ['/scan', body];
+            },
+        },
         {
             name: 'watcher_issues',
             description: 'Get runtime embedding failures. Shows files that failed processing and why.',

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

@@ -45,6 +45,7 @@ curl -X POST http://127.0.0.1:<PORT>/config/query \
 | `/config/apply` | POST | Apply config changes |
 | `/config-reindex` | POST | Trigger reindex |
 | `/metadata` | POST | Enrich document metadata |
+| `/scan` | POST | Filter-only point query (no embeddings) |
 | `/issues` | GET | Runtime embedding failures |
 | `/rules/register` | POST | Register virtual inference rules |
 | `/rules/unregister` | DELETE | Remove virtual rules by source |
@@ -78,7 +79,11 @@ You have access to a **semantic archive** of your human's working world. Documen
 npx @karmaniverous/jeeves-watcher-openclaw install
 ```
 
-This copies the plugin to OpenClaw's extensions directory and patches `openclaw.json` to register it. Restart the gateway to load the plugin.
+This copies the plugin to OpenClaw's extensions directory and patches `openclaw.json` to register it. 
+
+**Important:** Add `"jeeves-watcher-openclaw"` to the `tools.allow` array in `openclaw.json` so the agent can use the plugin's tools.
+
+Restart the gateway to load the plugin.
 
 To remove:
 ```
@@ -371,9 +376,83 @@ Trigger a reindex.
 
 Rules scope re-applies inference rules without re-embedding (lightweight). Full scope re-processes all files.
 
+
+### `watcher_scan`
+Filter-only point query without vector search. Use for structural queries where the question has no semantic dimension.
+- `filter` (object, required) — Qdrant filter object. Required to prevent accidental full-collection scans.
+- `limit` (number, optional) — page size, default 100, max 1000
+- `cursor` (string, optional) — opaque cursor from previous response for pagination
+- `fields` (string[], optional) — payload fields to return (projection)
+- `countOnly` (boolean, optional) — if true, return `{ count }` instead of points
+
+**Response (normal):**
+```json
+{
+  "points": [{ "id": "uuid", "payload": { ... } }],
+  "cursor": "opaque-string-or-null"
+}
+```
+
+**Response (countOnly):**
+```json
+{ "count": 1234 }
+```
+
+**Key differences from `watcher_search`:**
+- No `query` parameter — does NOT use embeddings
+- No `score` field — results are unranked filter matches
+- Cursor-based pagination (not offset-based)
+- Zero cost per call beyond Qdrant's filtered scroll
+
+**Pagination pattern:**
+```
+let cursor = undefined;
+do {
+  const result = await watcher_scan({ filter, limit: 100, cursor });
+  // process result.points
+  cursor = result.cursor;
+} while (cursor);
+```
+
 ### `watcher_issues`
 Get runtime embedding failures. Returns `{ filePath: IssueRecord }` showing files that failed and why.
 
+## 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`.
+
+| Use `watcher_scan` | Use `watcher_search` |
+|---------------------|----------------------|
+| "List all files in domain X" | "Find documents about authentication" |
+| "Files modified after timestamp T" | "What discusses rate limiting?" |
+| "Enumerate paths under prefix P" | "Prior conversations about deployment" |
+| "Count files matching a condition" | "Related tickets to this issue" |
+| "Staleness detection / delta computation" | "What happened in last week's meetings?" |
+
+**Scan-specific filter examples:**
+
+**Domain enumeration:**
+```json
+{ "must": [{ "key": "domains", "match": { "value": "email" } }] }
+```
+
+**Modified after timestamp:**
+```json
+{ "must": [{ "key": "modified_at", "range": { "gte": 1772800000 } }] }
+```
+
+**Path prefix matching:**
+```json
+{ "must": [{ "key": "file_path", "match": { "text": "j:/domains/jira" } }] }
+```
+
+**Count files in a domain (no point data transferred):**
+```
+watcher_scan: filter={"must":[{"key":"domains","match":{"value":"github"}}]}, countOnly=true
+```
+
+---
+
 ## Qdrant Filter Syntax
 
 Filters use Qdrant's native JSON filter format, passed as the `filter` parameter to `watcher_search`.

package/dist/src/watcherTools.d.ts

@@ -3,5 +3,5 @@
  * Watcher tool registrations (watcher_* tools) for the OpenClaw plugin.
  */
 import { type PluginApi } from './helpers.js';
-/** Register all 8 watcher_* tools with the OpenClaw plugin API. */
+/** Register all 9 watcher_* tools with the OpenClaw plugin API. */
 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.5.7",
+  "version": "0.6.0",
   "skills": [
     "dist/skills/jeeves-watcher"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-watcher-openclaw",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "author": "Jason Williscroft",
   "description": "OpenClaw plugin for jeeves-watcher — semantic search and metadata enrichment tools",
   "license": "BSD-3-Clause",
@@ -55,7 +55,7 @@
     "hideCredit": true
   },
   "devDependencies": {
-    "@dotenvx/dotenvx": "^1.52.0",
+    "@dotenvx/dotenvx": "^1.54.1",
     "@rollup/plugin-typescript": "^12.3.0",
     "auto-changelog": "^2.5.0",
     "cross-env": "^10.1.0",