@karmaniverous/jeeves-watcher-openclaw 0.1.2 → 0.2.0

package/dist/index.js

@@ -22,6 +22,30 @@ function fail(error) {
         isError: true,
     };
 }
+/** Format a connection error with actionable guidance. */
+function connectionFail(error, baseUrl) {
+    const cause = error instanceof Error ? error.cause : undefined;
+    const code = cause && typeof cause === 'object' && 'code' in cause
+        ? String(cause.code)
+        : '';
+    const isConnectionError = code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'ETIMEDOUT';
+    if (isConnectionError) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: [
+                        `Watcher service not reachable at ${baseUrl}.`,
+                        'Either start the watcher service, or if it runs on a different port,',
+                        'set plugins.entries.jeeves-watcher.config.apiUrl in openclaw.json.',
+                    ].join('\n'),
+                },
+            ],
+            isError: true,
+        };
+    }
+    return fail(error);
+}
 /** Fetch JSON from a URL, throwing on non-OK responses. */
 async function fetchJson(url, init) {
     const res = await fetch(url, init);
@@ -47,7 +71,7 @@ function register(api) {
                 return ok(await fetchJson(`${baseUrl}/status`));
             }
             catch (error) {
-                return fail(error);
+                return connectionFail(error, baseUrl);
             }
         },
     }, { optional: true });
@@ -89,7 +113,7 @@ function register(api) {
                 }));
             }
             catch (error) {
-                return fail(error);
+                return connectionFail(error, baseUrl);
             }
         },
     }, { optional: true });
@@ -122,7 +146,7 @@ function register(api) {
                 }));
             }
             catch (error) {
-                return fail(error);
+                return connectionFail(error, baseUrl);
             }
         },
     }, { optional: true });
@@ -156,7 +180,7 @@ function register(api) {
                 }));
             }
             catch (error) {
-                return fail(error);
+                return connectionFail(error, baseUrl);
             }
         },
     }, { optional: true });
@@ -191,7 +215,7 @@ function register(api) {
                 }));
             }
             catch (error) {
-                return fail(error);
+                return connectionFail(error, baseUrl);
             }
         },
     }, { optional: true });
@@ -217,7 +241,7 @@ function register(api) {
                 }));
             }
             catch (error) {
-                return fail(error);
+                return connectionFail(error, baseUrl);
             }
         },
     }, { optional: true });
@@ -245,7 +269,7 @@ function register(api) {
                 }));
             }
             catch (error) {
-                return fail(error);
+                return connectionFail(error, baseUrl);
             }
         },
     }, { optional: true });
@@ -258,7 +282,7 @@ function register(api) {
                 return ok(await fetchJson(`${baseUrl}/issues`));
             }
             catch (error) {
-                return fail(error);
+                return connectionFail(error, baseUrl);
             }
         },
     }, { optional: true });

package/dist/scripts/build-skills.d.ts

@@ -1,5 +1,5 @@
 /**
  * @module scripts/build-skills
- * Compiles SKILL.src.md files with Handlebars partials into dist/skills/.
+ * Copies skill files to dist/skills/ for plugin packaging.
  */
 export {};

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

@@ -3,11 +3,51 @@ name: jeeves-watcher
 description: >
   Semantic search across a structured document archive. Use when you need to
   recall prior context, find documents, answer questions that require searching
-  across domains (email, Slack, Jira, codebase, meetings, projects), or enrich
-  document metadata.
+  across domains (email, Slack, Jira, codebase, meetings, projects), enrich
+  document metadata, manage watcher config, or diagnose indexing issues.
 ---
 
-# jeeves-watcher — Search & Discovery
+# jeeves-watcher — Search, Discovery & Administration
+
+## Service Architecture
+
+The watcher is an HTTP API running as a background service (typically NSSM on Windows, systemd on Linux).
+
+**Default port:** 3458 (configurable via `api.port` in watcher config)
+**Non-default port:** If the watcher runs on a different port, the user must set `plugins.entries.jeeves-watcher.config.apiUrl` in `openclaw.json`. The plugin cannot auto-discover a non-default port.
+
+**Health check:** `GET /status` returns uptime, point count, collection dimensions, and reindex status.
+
+**Mental model:** The `watcher_*` tools are thin HTTP wrappers. Each tool call translates to an HTTP request to the watcher API. When tools are available, use them. When they're not (e.g., different session, plugin not loaded), you can hit the API directly. Replace `<PORT>` below with the configured port (default 3458; check `plugins.entries.jeeves-watcher.config.apiUrl` in `openclaw.json` if overridden):
+
+```
+# Health check
+curl http://127.0.0.1:<PORT>/status
+
+# Search
+curl -X POST http://127.0.0.1:<PORT>/search \
+  -H "Content-Type: application/json" \
+  -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"}'
+```
+
+**Key endpoints:**
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/status` | GET | Health check, uptime, collection stats |
+| `/search` | POST | Semantic search (main query interface) |
+| `/config/query` | POST | JSONPath query over merged virtual document |
+| `/config/validate` | POST | Validate candidate config |
+| `/config/apply` | POST | Apply config changes |
+| `/config-reindex` | POST | Trigger reindex |
+| `/metadata` | POST | Enrich document metadata |
+| `/issues` | GET | Runtime embedding failures |
+
+**If the watcher is unreachable:** Check the service status (`nssm status jeeves-watcher` on Windows), check the configured port in the watcher config file, and check logs for startup errors.
 
 ## Theory of Operation
 
@@ -37,9 +77,9 @@ You don't need to know the rules in advance. The config is introspectable at run
 
 ## Quick Start
 
-1. **Orient yourself** (once per session) — learn the deployment's organizational strategy and available record types
-2. **Search** — semantic search with optional metadata filters
-3. **Read source** — retrieve full file content for complete context
+1. **Orient yourself** (once per session) — use `watcher_query` to learn the deployment's organizational strategy and available record types (see Orientation Pattern below)
+2. **Search** — use `watcher_search` with a natural language query and optional metadata filters
+3. **Read source** — use `read` (standard file read) with `file_path` from search results for full document content
 
 ## Tools
 
@@ -63,6 +103,28 @@ Query the merged virtual document via JSONPath.
 - `path` (string, required) — JSONPath expression
 - `resolve` (string[], optional) — `["files"]`, `["globals"]`, or `["files","globals"]`
 
+### `watcher_validate`
+Validate config and optionally test file paths.
+- `config` (object, optional) — candidate config (partial or full). Omit to validate current config.
+- `testPaths` (string[], optional) — file paths to test against the config
+
+Partial configs merge with current config by rule name. If `config` is omitted, tests against the running config.
+
+### `watcher_config_apply`
+Apply config changes atomically.
+- `config` (object, required) — full or partial config to apply
+
+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"`
+
+Rules scope re-applies inference rules without re-embedding (lightweight). Full scope re-processes all files.
+
+### `watcher_issues`
+Get runtime embedding failures. Returns `{ filePath: IssueRecord }` showing files that failed and why.
+
 ## Qdrant Filter Syntax
 
 Filters use Qdrant's native JSON filter format, passed as the `filter` parameter to `watcher_search`.
@@ -135,45 +197,6 @@ Each result from `watcher_search` contains:
 
 Additional metadata fields depend on the deployment's inference rules (e.g., `domain`, `status`, `author`). Use `watcher_query` to discover available fields.
 
-## JSONPath Patterns for Schema Discovery
-
-Use `watcher_query` to explore the merged virtual document. Common patterns:
-
-### Orientation
-```
-$.inferenceRules[*].['name','description']    — List all rules with descriptions
-$.search.scoreThresholds                       — Score interpretation thresholds
-$.slots                                        — Named filter patterns (e.g., memory)
-```
-
-### Schema Discovery
-```
-$.inferenceRules[?(@.name=='jira-issue')]               — Full rule details
-$.inferenceRules[?(@.name=='jira-issue')].values        — Distinct values for a rule
-$.inferenceRules[?(@.name=='jira-issue')].values.status — Values for a specific field
-```
-
-### Helper Enumeration
-```
-$.mapHelpers                        — All JsonMap helper namespaces
-$.mapHelpers.slack.exports          — Exports from the 'slack' helper
-$.templateHelpers                   — All Handlebars helper namespaces
-```
-
-### Issues
-```
-$.issues                            — All runtime embedding failures
-```
-
-### Full Config Introspection
-```
-$.schemas                           — Global named schemas
-$.maps                              — Named JsonMap transforms
-$.templates                         — Named Handlebars templates
-```
-
----
-
 ## Orientation Pattern (Once Per Session)
 
 Query the deployment's organizational context and available record types. This information is stable within a session; query once and rely on results for the remainder.
@@ -223,6 +246,45 @@ The `resolve` parameter controls which reference layers are expanded in `watcher
 
 ---
 
+## JSONPath Patterns for Schema Discovery
+
+Use `watcher_query` to explore the merged virtual document. Common patterns:
+
+### Orientation
+```
+$.inferenceRules[*].['name','description']    — List all rules with descriptions
+$.search.scoreThresholds                       — Score interpretation thresholds
+$.slots                                        — Named filter patterns (e.g., memory)
+```
+
+### Schema Discovery
+```
+$.inferenceRules[?(@.name=='jira-issue')]               — Full rule details
+$.inferenceRules[?(@.name=='jira-issue')].values        — Distinct values for a rule
+$.inferenceRules[?(@.name=='jira-issue')].values.status — Values for a specific field
+```
+
+### Helper Enumeration
+```
+$.mapHelpers                        — All JsonMap helper namespaces
+$.mapHelpers.slack.exports          — Exports from the 'slack' helper
+$.templateHelpers                   — All Handlebars helper namespaces
+```
+
+### Issues
+```
+$.issues                            — All runtime embedding failures
+```
+
+### Full Config Introspection
+```
+$.schemas                           — Global named schemas
+$.maps                              — Named JsonMap transforms
+$.templates                         — Named Handlebars templates
+```
+
+---
+
 ## Query Planning (Per Search Task)
 
 Identify relevant rule(s) from the orientation model, then retrieve their schemas:
@@ -246,7 +308,7 @@ Retrieves valid filter values from the runtime values index (distinct values acc
 
 ---
 
-## uiHint → Qdrant Filter Mapping
+## uiHint → Filter Mapping
 
 Use `uiHint` to determine filter construction strategy. **This table is explicit, not intuited:**
 
@@ -307,38 +369,6 @@ A consuming UI will necessarily compose simple single-field filters. The assista
 
 ---
 
-## Search Result Shape
-
-**Qdrant output (stable across all configs):**
-```json
-{
-  "id": "<point_id>",
-  "score": 0.82,
-  "payload": {
-    "file_path": "j:/domains/jira/VCN/issue/WEB-123.json",
-    "chunk_index": 0,
-    "total_chunks": 1,
-    "chunk_text": "...",
-    "content_hash": "...",
-    "matched_rules": ["jira-issue", "json-subject"],
-    ...config-defined metadata fields...
-  }
-}
-```
-
-**System fields present on every result** (watcher-managed, not config-defined):
-- `file_path` — source file path
-- `chunk_index` / `total_chunks` — chunk position within document
-- `chunk_text` — the embedded text content
-- `content_hash` — content fingerprint for deduplication
-- `matched_rules` — inference rules that produced this point's metadata
-
-**All other payload fields are config-defined** (via inference rule schemas).
-
-Refer to Qdrant documentation for the complete search response envelope.
-
----
-
 ## Post-Processing Guidance
 
 ### Score Interpretation
@@ -376,18 +406,56 @@ Or check if a specific path would match:
 
 ---
 
+## Config Authoring
+
+### Rule Structure
+Each inference rule has:
+- `name` (required) — unique identifier
+- `description` (optional) — human-readable purpose
+- `match` — JSON Schema with picomatch glob for path matching
+- `set` — metadata fields to set on match
+- `map` (optional) — named JsonMap transform
+- `template` (optional) — named Handlebars template
+
+### Config Workflow
+1. Edit config (or build partial config object)
+2. Validate: `watcher_validate` with optional `testPaths` for dry-run preview
+3. Apply: `watcher_config_apply` — validates, writes, triggers reindex
+4. Monitor: `watcher_issues` for runtime embedding failures
+
+### 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.
+
+---
+
 ## Diagnostics
 
-Check the issues endpoint for failed embeddings:
-```
-watcher_query: path="$.issues"
-```
+### Escalation Path
+1. `watcher_status` — is the service healthy? Is a reindex running?
+2. `watcher_issues` — what files are failing and why?
+3. `watcher_query` with `$.issues` — same data via JSONPath
+4. Check logs at the configured log path
+
+### Error Categories
+- `type_collision` — metadata field type mismatch during extraction (includes `property`, `rules[]`, `types[]`)
+- `interpolation` / `interpolation_error` — template/set expression failed to resolve (includes `property`, `rule`)
+- `read_failure` — file couldn't be read (permissions, encoding)
+- `embedding` — embedding API error
 
 **Issues are self-healing:** resolved on successful re-process. The issues file always represents the current set of unresolved problems: a live todo list.
 
-**Issue types:**
-- `type_collision` — multiple rules declare the same property with incompatible types (includes `property`, `rules[]`, `types[]`)
-- `interpolation_error` — `set` template path doesn't resolve (includes `property`, `rule`)
+---
+
+## Helper Management
+
+Helpers use namespace prefixing: config key becomes prefix. A helper named `slack` exports `slack_extractParticipants`.
+
+Enumerate loaded helpers:
+```
+$.mapHelpers              — JsonMap helper namespaces with exports
+$.templateHelpers         — Handlebars helper namespaces with exports
+```
 
 ---
 
@@ -420,6 +488,16 @@ If the watcher is unreachable:
 - Fall back to direct `read` for known file paths
 - Do not retry silently in a loop
 
+If tools are unavailable (plugin not loaded in this session):
+- The watcher API is still accessible via direct HTTP calls
+- Use `exec` to call the endpoints listed in Service Architecture
+- Default: `http://127.0.0.1:3458`
+
+**CLI Fallbacks:**
+- `jeeves-watcher status` — check if the service is running
+- `jeeves-watcher validate` — validate config from CLI
+- Restart via NSSM (Windows) or systemctl (Linux)
+
 ---
 
 ## References

package/dist/src/helpers.d.ts

@@ -34,5 +34,7 @@ export declare function getApiUrl(api: PluginApi): string;
 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. */
 export declare function fetchJson(url: string, init?: RequestInit): Promise<unknown>;

package/openclaw.plugin.json

@@ -1,11 +1,10 @@
 {
   "id": "jeeves-watcher-openclaw",
   "name": "Jeeves Watcher",
-  "description": "Semantic search and metadata enrichment via a jeeves-watcher instance.",
-  "version": "0.1.2",
+  "description": "Semantic search, metadata enrichment, and instance administration for a jeeves-watcher deployment.",
+  "version": "0.2.0",
   "skills": [
-    "dist/skills/jeeves-watcher",
-    "dist/skills/jeeves-watcher-admin"
+    "dist/skills/jeeves-watcher"
   ],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-watcher-openclaw",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "author": "Jason Williscroft",
   "description": "OpenClaw plugin for jeeves-watcher — semantic search and metadata enrichment tools",
   "license": "BSD-3-Clause",
@@ -59,7 +59,6 @@
     "@rollup/plugin-typescript": "^12.3.0",
     "auto-changelog": "^2.5.0",
     "cross-env": "^10.1.0",
-    "handlebars": "^4.7.8",
     "release-it": "^19.2.4",
     "rollup": "^4.59.0",
     "tslib": "^2.8.1"

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

@@ -1,200 +0,0 @@
----
-name: jeeves-watcher-admin
-description: >
-  Instance management for a jeeves-watcher deployment. Use when you need to
-  author or validate config, trigger reindexing, diagnose embedding failures,
-  or manage helper registrations.
----
-
-# jeeves-watcher — Instance Administration
-
-## Tools
-
-### `watcher_validate`
-Validate config and optionally test file paths.
-- `config` (object, optional) — candidate config (partial or full). Omit to validate current config.
-- `testPaths` (string[], optional) — file paths to test against the config
-
-Partial configs merge with current config by rule name. If `config` is omitted, tests against the running config.
-
-### `watcher_config_apply`
-Apply config changes atomically.
-- `config` (object, required) — full or partial config to apply
-
-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"`
-
-Rules scope re-applies inference rules without re-embedding (lightweight). Full scope re-processes all files.
-
-### `watcher_issues`
-Get runtime embedding failures. Returns `{ filePath: IssueRecord }` showing files that failed and why.
-
-### `watcher_query`
-Query config and runtime state via JSONPath (same tool as consumer skill).
-
-### `watcher_status`
-Service health check including reindex progress.
-
-## Qdrant Filter Syntax
-
-Filters use Qdrant's native JSON filter format, passed as the `filter` parameter to `watcher_search`.
-
-### Basic Patterns
-
-**Match exact value:**
-```json
-{ "must": [{ "key": "domain", "match": { "value": "email" } }] }
-```
-
-**Match text (full-text search within field):**
-```json
-{ "must": [{ "key": "chunk_text", "match": { "text": "authentication" } }] }
-```
-
-**Combine conditions (AND):**
-```json
-{
-  "must": [
-    { "key": "domain", "match": { "value": "jira" } },
-    { "key": "status", "match": { "value": "In Progress" } }
-  ]
-}
-```
-
-**Exclude (NOT):**
-```json
-{
-  "must_not": [{ "key": "domain", "match": { "value": "repos" } }]
-}
-```
-
-**Any of (OR):**
-```json
-{
-  "should": [
-    { "key": "domain", "match": { "value": "email" } },
-    { "key": "domain", "match": { "value": "slack" } }
-  ]
-}
-```
-
-**Nested (combine AND + NOT):**
-```json
-{
-  "must": [{ "key": "domain", "match": { "value": "jira" } }],
-  "must_not": [{ "key": "status", "match": { "value": "Done" } }]
-}
-```
-
-### Key Differences
-- `match.value` — exact match (case-sensitive, for keyword fields like `domain`, `status`)
-- `match.text` — full-text match (for text fields like `chunk_text`)
-
-## Search Result Shape
-
-Each result from `watcher_search` contains:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | string | Qdrant point ID |
-| `score` | number | Similarity score (0-1, higher = more relevant) |
-| `payload.file_path` | string | Source file path |
-| `payload.chunk_text` | string | The matched text chunk |
-| `payload.chunk_index` | number | Chunk position within the file |
-| `payload.total_chunks` | number | Total chunks for this file |
-| `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.
-
-## JSONPath Patterns for Schema Discovery
-
-Use `watcher_query` to explore the merged virtual document. Common patterns:
-
-### Orientation
-```
-$.inferenceRules[*].['name','description']    — List all rules with descriptions
-$.search.scoreThresholds                       — Score interpretation thresholds
-$.slots                                        — Named filter patterns (e.g., memory)
-```
-
-### Schema Discovery
-```
-$.inferenceRules[?(@.name=='jira-issue')]               — Full rule details
-$.inferenceRules[?(@.name=='jira-issue')].values        — Distinct values for a rule
-$.inferenceRules[?(@.name=='jira-issue')].values.status — Values for a specific field
-```
-
-### Helper Enumeration
-```
-$.mapHelpers                        — All JsonMap helper namespaces
-$.mapHelpers.slack.exports          — Exports from the 'slack' helper
-$.templateHelpers                   — All Handlebars helper namespaces
-```
-
-### Issues
-```
-$.issues                            — All runtime embedding failures
-```
-
-### Full Config Introspection
-```
-$.schemas                           — Global named schemas
-$.maps                              — Named JsonMap transforms
-$.templates                         — Named Handlebars templates
-```
-
-## Config Authoring
-
-### Rule Structure
-Each inference rule has:
-- `name` (required) — unique identifier
-- `description` (optional) — human-readable purpose
-- `match` — JSON Schema with picomatch glob for path matching
-- `set` — metadata fields to set on match
-- `map` (optional) — named JsonMap transform
-- `template` (optional) — named Handlebars template
-
-### Config Workflow
-1. Edit config (or build partial config object)
-2. Validate: `watcher_validate` with optional `testPaths` for dry-run preview
-3. Apply: `watcher_config_apply` — validates, writes, triggers reindex
-4. Monitor: `watcher_issues` for runtime embedding failures
-
-### 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.
-
-## Diagnostics
-
-### Escalation Path
-1. `watcher_status` — is the service healthy? Is a reindex running?
-2. `watcher_issues` — what files are failing and why?
-3. `watcher_query` with `$.issues` — same data via JSONPath
-4. Check logs at the configured log path
-
-### Error Categories
-- `type_collision` — metadata field type mismatch during extraction
-- `interpolation` — template/set expression failed to resolve
-- `read_failure` — file couldn't be read (permissions, encoding)
-- `embedding` — embedding API error
-
-## Helper Management
-
-Helpers use namespace prefixing: config key becomes prefix. A helper named `slack` exports `slack_extractParticipants`.
-
-Enumerate loaded helpers:
-```
-$.mapHelpers              — JsonMap helper namespaces with exports
-$.templateHelpers         — Handlebars helper namespaces with exports
-```
-
-## CLI Fallbacks
-
-If the watcher API is down:
-- `jeeves-watcher status` — check if the service is running
-- `jeeves-watcher validate` — validate config from CLI
-- Restart via NSSM (Windows) or systemctl (Linux)