@karmaniverous/jeeves-watcher-openclaw 0.4.1 → 0.5.0

package/dist/index.js

@@ -3,11 +3,21 @@
  * Shared types and utility functions for the OpenClaw plugin tool registrations.
  */
 const DEFAULT_API_URL = 'http://127.0.0.1:1936';
+const DEFAULT_CACHE_TTL_MS = 30000;
+/** Extract plugin config from the API object */
+function getPluginConfig(api) {
+    return api.config?.plugins?.entries?.['jeeves-watcher-openclaw']?.config;
+}
 /** Resolve the watcher API base URL from plugin config. */
 function getApiUrl(api) {
-    const url = api.config?.plugins?.entries?.['jeeves-watcher-openclaw']?.config?.apiUrl;
+    const url = getPluginConfig(api)?.apiUrl;
     return typeof url === 'string' ? url : DEFAULT_API_URL;
 }
+/** Resolve the cache TTL for plugin hooks from config. */
+function getCacheTtlMs(api) {
+    const ttl = getPluginConfig(api)?.cacheTtlMs;
+    return typeof ttl === 'number' ? ttl : DEFAULT_CACHE_TTL_MS;
+}
 /** Format a successful tool result. */
 function ok(data) {
     return {
@@ -18,7 +28,7 @@ function ok(data) {
 function fail(error) {
     const message = error instanceof Error ? error.message : String(error);
     return {
-        content: [{ type: 'text', text: `Error: ${message}` }],
+        content: [{ type: 'text', text: 'Error: ' + message }],
         isError: true,
     };
 }
@@ -35,7 +45,7 @@ function connectionFail(error, baseUrl) {
                 {
                     type: 'text',
                     text: [
-                        `Watcher service not reachable at ${baseUrl}.`,
+                        'Watcher service not reachable at ' + baseUrl + '.',
                         'Either start the watcher service, or if it runs on a different port,',
                         'set plugins.entries.jeeves-watcher-openclaw.config.apiUrl in openclaw.json.',
                     ].join('\n'),
@@ -47,22 +57,162 @@ function connectionFail(error, baseUrl) {
     return fail(error);
 }
 /** Fetch JSON from a URL, throwing on non-OK responses. */
-async function fetchJson(url, init) {
+async function fetchJson$1(url, init) {
     const res = await fetch(url, init);
     if (!res.ok) {
-        throw new Error(`HTTP ${String(res.status)}: ${await res.text()}`);
+        throw new Error('HTTP ' + String(res.status) + ': ' + (await res.text()));
     }
     return res.json();
 }
 /** POST JSON to a URL and return parsed response. */
 async function postJson(url, body) {
-    return fetchJson(url, {
+    return fetchJson$1(url, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(body),
     });
 }
 
+let menuCache = null;
+function isAgentBootstrapEventContext(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const v = value;
+    return Array.isArray(v.bootstrapFiles);
+}
+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.
+ */
+async function generateWatcherMenu(apiUrl) {
+    let pointCount = 0;
+    const activeRules = [];
+    const watchPaths = [];
+    try {
+        const [statusRes, rulesRes, pathsRes] = 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[*]' }),
+            }),
+        ]);
+        pointCount = statusRes.collection?.pointCount ?? 0;
+        if (Array.isArray(rulesRes.result)) {
+            for (const rule of rulesRes.result) {
+                if (rule.name && rule.description) {
+                    activeRules.push({ name: rule.name, description: rule.description });
+                }
+            }
+        }
+        if (Array.isArray(pathsRes.result)) {
+            for (const p of pathsRes.result) {
+                if (typeof p === 'string') {
+                    watchPaths.push(p);
+                }
+            }
+        }
+    }
+    catch {
+        return '*Watcher service is currently unreachable.*';
+    }
+    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.',
+        '',
+        '### Score Interpretation:',
+        '* **Strong:** >= 0.75',
+        '* **Relevant:** >= 0.50',
+        '* **Noise:** < 0.25',
+        '',
+        "### What's on the menu:",
+    ];
+    if (activeRules.length) {
+        for (const rule of activeRules) {
+            lines.push(`* **${rule.name}**: ${rule.description}`);
+        }
+    }
+    else {
+        lines.push('* (No inference rules configured)');
+    }
+    lines.push('', '### Indexed paths:');
+    if (watchPaths.length) {
+        for (const p of watchPaths) {
+            lines.push(`* \`${p}\``);
+        }
+    }
+    else {
+        lines.push('* (No watch paths configured)');
+    }
+    return lines.join('\n');
+}
+async function getCachedWatcherMenu(apiUrl, ttlMs) {
+    const now = Date.now();
+    if (menuCache && menuCache.expiresAt > now) {
+        return menuCache.value;
+    }
+    const menu = await generateWatcherMenu(apiUrl);
+    menuCache = { value: menu, expiresAt: now + ttlMs };
+    return menu;
+}
+function ensurePlatformToolsSection(toolsMd) {
+    if (toolsMd.includes('# Jeeves Platform Tools')) {
+        return toolsMd;
+    }
+    return `# Jeeves Platform Tools\n\n${toolsMd}`;
+}
+function upsertWatcherSection(toolsMd, watcherMenu) {
+    const section = `## Watcher\n\n${watcherMenu}\n`;
+    // If we already injected a Watcher section, replace it.
+    const re = /^## Watcher\n[\s\S]*?(?=^##\s|$)/m;
+    if (re.test(toolsMd)) {
+        return toolsMd.replace(re, section);
+    }
+    // Otherwise insert immediately after the H1 if present, else append.
+    const h1 = '# Jeeves Platform Tools';
+    const idx = toolsMd.indexOf(h1);
+    if (idx !== -1) {
+        const afterH1 = idx + h1.length;
+        return (toolsMd.slice(0, afterH1) + `\n\n${section}` + toolsMd.slice(afterH1));
+    }
+    return `${toolsMd}\n\n${section}`;
+}
+/**
+ * Hook handler for agent:bootstrap.
+ * Injects/updates the Watcher Menu into the TOOLS.md payload.
+ */
+async function handleAgentBootstrap(event, api) {
+    const context = event?.context;
+    if (!isAgentBootstrapEventContext(context)) {
+        return;
+    }
+    const apiUrl = getApiUrl(api);
+    const cacheTtlMs = getCacheTtlMs(api);
+    const watcherMenu = await getCachedWatcherMenu(apiUrl, cacheTtlMs);
+    let toolsFile = context.bootstrapFiles.find((f) => f.name === 'TOOLS.md');
+    if (!toolsFile) {
+        toolsFile = { name: 'TOOLS.md', content: '', missing: false };
+        context.bootstrapFiles.push(toolsFile);
+    }
+    const current = toolsFile.content ?? '';
+    const withH1 = ensurePlatformToolsSection(current);
+    const updated = upsertWatcherSection(withH1, watcherMenu);
+    toolsFile.content = updated;
+}
+
 /**
  * @module plugin/watcherTools
  * Watcher tool registrations (watcher_* tools) for the OpenClaw plugin.
@@ -79,7 +229,7 @@ function registerApiTool(api, baseUrl, config) {
                 const url = `${baseUrl}${endpoint}`;
                 const data = body !== undefined
                     ? await postJson(url, body)
-                    : await fetchJson(url);
+                    : await fetchJson$1(url);
                 return ok(data);
             }
             catch (error) {
@@ -249,6 +399,13 @@ function registerWatcherTools(api, baseUrl) {
 function register(api) {
     const baseUrl = getApiUrl(api);
     registerWatcherTools(api, baseUrl);
+    // Register the agent:bootstrap hook if the host OpenClaw version supports it
+    const registerHook = api.registerInternalHook;
+    if (typeof registerHook === 'function') {
+        registerHook('agent:bootstrap', async (event) => {
+            await handleAgentBootstrap(event, api);
+        });
+    }
 }
 
 export { register as default };

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

@@ -56,8 +56,6 @@ curl -X POST http://127.0.0.1:<PORT>/config/query \
 
 You have access to a **semantic archive** of your human's working world. Documents, messages, tickets, notes, code, and other artifacts are indexed, chunked, embedded, and searchable. This is your long-term recall for anything beyond the current conversation.
 
-**Every deployment is different.** The archive's structure, domains, metadata fields, and record types are all defined by the deployment's configuration. Do not assume any particular domains exist (e.g., "email", "slack", "jira"). Always discover what's available using the Orientation Pattern below. Examples in this skill use common domain names for illustration only.
-
 **When to reach for the watcher:**
 
 - **Someone asks about something that happened.** A meeting, a decision, a conversation, a ticket, a message. You weren't there, but the archive was. Search it.
@@ -72,52 +70,8 @@ You have access to a **semantic archive** of your human's working world. Documen
 - The question is about general knowledge, not the human's specific context
 - The watcher is unreachable (fall back to filesystem browsing)
 
-## Memory → Archive Escalation
-
-You have two complementary tools with different scopes:
-
-- **memory-core** (`memory_search` / `memory_get`) — OpenClaw's built-in memory provider. Manages curated notes in MEMORY.md and memory/*.md. High signal, small scope. This is your long-term memory: decisions, rules, people, project context. Always check here first.
-- **watcher** (`watcher_search`) — the full indexed archive across all configured domains. Broad scope, raw record.
-
-**The escalation rule:** When `memory_search` returns thin, zero, or low-confidence results for something your human clearly expects you to know about — a person, a project, an event, a thing — don't stop there. Follow up with `watcher_search` across the full index.
-
-**Triggers for escalation:**
-- Memory returns 0 results for a named entity (person, project, tool, pet)
-- Memory returns results but they lack the detail the question needs
-- The question is about something that *happened* (a conversation, a meeting, a decision) rather than something you *noted*
-- The human seems surprised you don't know something
-
-**Don't escalate when:**
-- Memory gave you a clear, sufficient answer
-- The question is about your own operational rules or preferences (that's purely memory)
-- You've already searched the archive this turn
-
-**Example:** "Tell me about Project X" → memory says "started in January" → that's thin → escalate to `watcher_search("Project X")` → tickets, messages, and docs reveal the full history. Report the full picture.
-
 **The principle:** Memory-core is your curated highlights. The watcher archive is your perfect recall. Use memory first for speed and signal, but never let its narrow scope be the ceiling of what you can remember.
 
-## Embedding Alignment
-
-Memory-core and the watcher both use embeddings, but may use different models by default. For best cross-tool consistency, offer to configure memory-core to use `gemini-embedding-001` (the same model the watcher uses) via the gateway config:
-
-1. **Verify Google API key** — check that the gateway has a Google API key configured (needed for Gemini embeddings).
-2. **Apply config** — use `gateway config.patch` to set the memory-core embedding provider:
-   ```json
-   {
-     "agents": {
-       "defaults": {
-         "memorySearch": {
-           "provider": "gemini",
-           "model": "gemini-embedding-001"
-         }
-       }
-     }
-   }
-   ```
-3. **Restart gateway** to pick up the new embedding provider. Memory-core will re-embed all memory files on next sync (dimension change triggers automatic vector table recreation).
-
-This gives memory-core the same 3072-dimensional Gemini embeddings the watcher uses, ensuring semantic similarity scores are comparable across memory and archive searches.
-
 ## Plugin Installation
 
 ```
@@ -135,9 +89,8 @@ npx @karmaniverous/jeeves-watcher-openclaw uninstall
 
 If the watcher service is already running and healthy:
 
-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
+1. **Search** — use `watcher_search` with a natural language query and optional metadata filters
+2. **Read source** — use `read` (standard file read) with `file_path` from search results for full document content
 
 ## Bootstrap (First-Time Setup)
 
@@ -165,14 +118,27 @@ If not running, install it. **Prefer native installation** (especially on cloud
 
 **Linux (recommended for servers):**
 ```bash
-# Download latest release
-curl -L https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-unknown-linux-musl.tar.gz -o qdrant.tar.gz
-tar xzf qdrant.tar.gz
-
-# Run (foreground for testing)
-./qdrant
+# Download and install binary
+curl -L https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-unknown-linux-musl.tar.gz -o /tmp/qdrant.tar.gz
+sudo tar xzf /tmp/qdrant.tar.gz -C /usr/local/bin/
+
+# Create qdrant user and directories
+sudo useradd -r -s /bin/false qdrant
+sudo mkdir -p /var/lib/qdrant/storage /var/lib/qdrant/snapshots /etc/qdrant
+sudo chown -R qdrant:qdrant /var/lib/qdrant
+
+# Create config
+sudo tee /etc/qdrant/config.yaml > /dev/null <<EOF
+storage:
+  storage_path: /var/lib/qdrant/storage
+  snapshots_path: /var/lib/qdrant/snapshots
+service:
+  host: 0.0.0.0
+  http_port: 6333
+  grpc_port: 6334
+EOF
 
-# For production: create a systemd service
+# Create systemd service
 sudo tee /etc/systemd/system/qdrant.service > /dev/null <<EOF
 [Unit]
 Description=Qdrant Vector Database
@@ -181,12 +147,14 @@ After=network.target
 [Service]
 Type=simple
 ExecStart=/usr/local/bin/qdrant --config-path /etc/qdrant/config.yaml
+WorkingDirectory=/var/lib/qdrant
 Restart=always
 User=qdrant
 
 [Install]
 WantedBy=multi-user.target
 EOF
+sudo systemctl daemon-reload
 sudo systemctl enable --now qdrant
 ```
 
@@ -310,6 +278,7 @@ After=network.target qdrant.service
 [Service]
 Type=simple
 ExecStart=$(which jeeves-watcher) start -c <config-path>
+WorkingDirectory=%h
 Restart=always
 Environment=GOOGLE_API_KEY=<key>
 User=$USER
@@ -351,10 +320,6 @@ Once health is confirmed and initial indexing has started:
 2. Query `$.inferenceRules[*].['name','description']` for available record types.
 3. Report to the user: how many points indexed so far, which domains are available, estimated time to complete initial indexing (based on file count and embedding rate).
 
-### Step 9: Align Memory-Core Embeddings
-
-After the watcher is healthy, offer to align OpenClaw's memory-core with the same embedding model for consistent vector quality across both systems. See the **Embedding Alignment** section above for the procedure.
-
 ### On Subsequent Sessions
 
 On sessions after bootstrap is complete:
@@ -413,8 +378,6 @@ Get runtime embedding failures. Returns `{ filePath: IssueRecord }` showing file
 
 Filters use Qdrant's native JSON filter format, passed as the `filter` parameter to `watcher_search`.
 
-> **Note:** The field names and values used in these examples (e.g., `domain`, `status`, `assignee`) are illustrative. Actual fields depend on the deployment's inference rules. Use the Orientation Pattern and Query Planning sections to discover what's available before constructing filters.
-
 ### Basic Patterns
 
 **Match exact value:**
@@ -483,94 +446,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.
 
-## 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.
-
-**Efficient pattern (two calls):**
-
-1. **Top-level context:**
-   ```
-   watcher_query: path="$.['description','search']"
-   ```
-   Returns:
-   - `description` — organizational strategy (e.g., how domains are structured, what partitioning means)
-   - `search.scoreThresholds` — score interpretation boundaries (strong, relevant, noise)
-
-2. **Available record types:**
-   ```
-   watcher_query: path="$.inferenceRules[*].['name','description']"
-   ```
-   Returns list of inference rules with their names and descriptions.
-
-**Example result:**
-```json
-[
-  { "name": "email-archive", "description": "Email archive messages" },
-  { "name": "slack-message", "description": "Slack channel messages with channel and author metadata" },
-  { "name": "jira-issue", "description": "Jira issue metadata extracted from issue JSON exports" }
-]
-```
-
-The top-level `description` explains this deployment's organizational strategy. Each rule's `description` explains what that specific record type represents. Both levels are useful: one orients, the other enumerates.
-
----
-
-## `resolve` Usage Guidance
-
-The `resolve` parameter controls which reference layers are expanded in `watcher_query`:
-
-- **No `resolve` (default):** Raw config structure with references intact (lightweight)
-- **`resolve: ["files"]`:** Resolve file path references to their contents (e.g., `"schemas/base.json"` → the JSON Schema object)
-- **`resolve: ["globals"]`:** Resolve named schema references (e.g., `"base"` in a rule's schema array → the global schema object)
-- **`resolve: ["files","globals"]`:** Fully inlined, everything expanded
-
-**When to use:**
-- **Orientation:** No resolve (just names and descriptions, lightweight)
-- **Query planning:** `resolve: ["files","globals"]` (need complete merged schemas for filter construction)
-- **Browsing global schemas:** `resolve: ["files"]` (see schema contents but keep named references visible for DRY structure understanding)
-
----
-
-## 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:
@@ -603,7 +478,7 @@ Use `uiHint` to determine filter construction strategy. **This table is explicit
 | `text` | `{ "key": "<field>", "match": { "text": "<value>" } }` | Substring/keyword match |
 | `select` | `{ "key": "<field>", "match": { "value": "<enum_value>" } }` | Exact match; use `enum` values from schema or runtime values index |
 | `multiselect` | `{ "key": "<field>", "match": { "value": "<enum_value>" } }` | Any-element match on array field; use `enum` or runtime values index |
-| `date` | `{ "key": "<field>", "range": { "gte": <unix_ts>, "lt": <unix_ts> } }` | Either bound optional for open-ended ranges (e.g., "after January" → `gte` only) |
+| `date` | `{ "key": "<field>", "range": { "gte": <unix_ts>, "lt": <unix_ts> } }` | Range filter against integer fields holding Unix timestamps (seconds). Source dates should be normalized in config via `{{toUnix ...}}` in `set` expressions. | for open-ended ranges (e.g., "after January" → `gte` only) |
 | `number` | `{ "key": "<field>", "range": { "gte": <n>, "lte": <n> } }` | Either bound optional for open-ended ranges |
 | `check` | `{ "key": "<field>", "match": { "value": true } }` | Boolean match |
 | *(absent)* | Do not use in filters | Internal bookkeeping field, not intended for search |
@@ -790,3 +665,7 @@ If tools are unavailable (plugin not loaded in this session):
 
 - [JSONPath Plus documentation](https://www.npmjs.com/package/jsonpath-plus) for JSONPath syntax
 - [Qdrant filtering documentation](https://qdrant.tech/documentation/concepts/filtering/) for advanced query patterns and search response format
+
+
+
+

package/dist/src/helpers.d.ts

@@ -19,6 +19,11 @@ export interface PluginApi {
     }, options?: {
         optional?: boolean;
     }): void;
+    /**
+     * Optional internal hook registration (available on newer OpenClaw builds).
+     * We keep this optional to preserve compatibility.
+     */
+    registerInternalHook?: (event: string, handler: (event: unknown) => Promise<void> | void) => void;
 }
 /** Result shape returned by each tool execution. */
 export interface ToolResult {
@@ -30,6 +35,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. */

package/dist/src/promptInjection.d.ts

@@ -0,0 +1,6 @@
+import { type PluginApi } from './helpers.js';
+/**
+ * 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/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.4.1",
+  "version": "0.5.0",
   "skills": [
     "dist/skills/jeeves-watcher"
   ],

package/package.json

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