@karmaniverous/jeeves-meta-openclaw 0.1.0

package/dist/rollup.config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Rollup configuration for the OpenClaw plugin package.
+ * Two entry points: plugin (ESM + declarations) and CLI (ESM executable).
+ *
+ * @module rollup.config
+ */
+import type { RollupOptions } from 'rollup';
+declare const _default: RollupOptions[];
+export default _default;

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

@@ -0,0 +1,207 @@
+# jeeves-meta — OpenClaw Skill
+
+## Overview
+
+jeeves-meta is the Jeeves platform's knowledge synthesis engine. It discovers
+`.meta/` directories, gathers context from the Qdrant vector index, and uses
+a three-step LLM process (architect, builder, critic) to produce structured
+synthesis artifacts.
+
+## Available Tools
+
+### synth_list
+List all `.meta/` directories with summary stats and per-meta projection.
+Supports filtering by path prefix, error status, staleness, and lock state.
+Use for engine health checks and finding stale knowledge.
+
+**Parameters:**
+- `pathPrefix` (optional): Filter by path prefix (e.g. "github/")
+- `filter` (optional): Structured filter (`{ hasError: true }`, `{ staleHours: 24 }`)
+- `fields` (optional): Property projection array
+
+### synth_detail
+Full detail for a single meta, with optional archive history.
+
+**Parameters:**
+- `path` (required): `.meta/` or owner directory path
+- `fields` (optional): Property projection
+- `includeArchive` (optional): false, true, or number (N most recent)
+
+### synth_preview
+Dry-run for the next synthesis cycle. Shows scope files, delta files,
+architect trigger reasons, steer status, and structure changes — without
+running any LLM calls. Use before `synth_trigger` to understand what
+will happen.
+
+### synth_trigger
+Manually trigger a full synthesis cycle (architect → builder → critic) for
+a specific meta or the next-stalest candidate.
+
+**Parameters:**
+- `path` (optional): Specific `.meta/` or owner directory path. If omitted,
+  synthesizes the stalest candidate.
+
+## When to Use
+
+- **Checking synthesis health:** `synth_list`
+- **Finding stale knowledge:** `synth_list` with `filter: { staleHours: 24 }`
+- **Checking errors:** `synth_list` with `filter: { hasError: true }`
+- **Getting full details:** `synth_detail` with optional `includeArchive: 5`
+- **Understanding what a cycle will do:** `synth_preview`
+- **Forcing a refresh:** `synth_trigger` with optional path
+- **Reading synthesis output:** Use `watcher_search` with domain `synth-meta`
+
+## Key Concepts
+
+- **Steering (`_steer`):** Human-written prompt in `meta.json` that guides
+  synthesis focus. The only field humans typically write.
+- **Staleness:** Time since last synthesis. Deeper metas (leaves) update more
+  often than rollup metas (parents).
+- **Three steps:** Architect crafts the task brief, Builder produces content,
+  Critic evaluates quality. The feedback loop self-improves over cycles.
+- **Archives:** Each cycle creates a timestamped snapshot in `.meta/archive/`.
+
+## Configuration
+
+### Config File
+
+Location determined by `JEEVES_META_CONFIG` env var or plugin `configPath` setting.
+Canonical deployment: `J:\config\jeeves-meta.config.json`.
+
+Key settings:
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `watchPaths` | (required) | Array of paths to scan for `.meta/` directories |
+| `watcherUrl` | (required) | Watcher service URL (e.g. `http://localhost:1936`) |
+| `gatewayUrl` | `http://127.0.0.1:3000` | OpenClaw gateway URL for subprocess spawning |
+| `architectEvery` | 10 | Re-run architect every N cycles even if structure unchanged |
+| `depthWeight` | 0.5 | Exponent for depth-based scheduling (0 = pure staleness) |
+| `maxArchive` | 20 | Max archived snapshots per meta |
+| `maxLines` | 500 | Max lines for builder context |
+| `architectTimeout` | 120s | Architect subprocess timeout |
+| `builderTimeout` | 600s | Builder subprocess timeout |
+| `criticTimeout` | 300s | Critic subprocess timeout |
+
+### Prompt Customization
+
+Default prompts live at `J:\config\jeeves-meta\prompts\{architect,critic}.md`,
+referenced via `@file:` in the config:
+
+```json
+{
+  "defaultArchitect": "@file:jeeves-meta/prompts/architect.md",
+  "defaultCritic": "@file:jeeves-meta/prompts/critic.md"
+}
+```
+
+**Per-meta overrides:** Set `_architect` or `_critic` directly in a `meta.json`
+to override the defaults for that specific entity.
+
+### Adding New Domains
+
+1. Create a `.meta/` directory under the domain path
+2. The engine auto-creates `meta.json` with a UUID on first discovery
+3. Optionally set `_steer`, `_depth`, and `_emphasis` in `meta.json`
+4. The entity appears in `synth_list` on the next cycle
+
+### Tuning Scheduling
+
+- **`_depth`:** Higher = updates more often. Defaults from tree nesting.
+- **`_emphasis`:** Per-meta multiplier (default 1). Set 2 to double depth effect, 0 to ignore depth.
+- **`depthWeight`:** Global exponent. Set 0 for pure staleness rotation.
+
+## Bootstrapping
+
+### Prerequisites
+
+Before the synthesis engine can operate:
+
+1. **jeeves-watcher** must be running and indexing data
+   - Verify: `curl http://localhost:1936/status` should return point count > 0
+   - The watcher provides both semantic search and structured scan
+
+2. **Qdrant** must be running with indexed data
+   - Verify: `curl http://localhost:6333/healthz`
+
+3. **Config file** must exist
+   - Default: path from `JEEVES_META_CONFIG` env var
+   - Must contain valid `watchPaths` and `watcherUrl`
+
+4. **Prompt files** must exist
+   - `J:\config\jeeves-meta\prompts\architect.md`
+   - `J:\config\jeeves-meta\prompts\critic.md`
+
+5. **Watch paths** must be indexed by the watcher
+   - The paths in `watchPaths` must overlap with the watcher's configured paths
+
+### Installation
+
+```bash
+npx @karmaniverous/jeeves-meta-openclaw install
+```
+
+Then restart the OpenClaw gateway to load the plugin.
+
+### First Synthesis
+
+1. Check discovery: `synth_list` — should show your `.meta/` entities
+2. Preview: `synth_preview` — verify scope files and delta detection
+3. Trigger: `synth_trigger` — run the first cycle
+4. Review: `synth_detail <path> --includeArchive 1` — check output quality
+5. Iterate on `_steer` prompts if needed
+
+## Troubleshooting
+
+### Watcher unreachable
+
+**Symptom:** TOOLS.md shows "ACTION REQUIRED: jeeves-watcher is unreachable"
+**Cause:** Watcher service not running or wrong URL in config
+**Fix:**
+1. Check watcher status: `curl http://localhost:1936/status`
+2. If down, start the watcher service
+3. If running on a different port, update `watcherUrl` in config
+
+### No entities discovered
+
+**Symptom:** `synth_list` returns empty, TOOLS.md shows "No synthesis entities found"
+**Cause:** No `.meta/` directories in configured `watchPaths`, or paths not indexed
+**Fix:**
+1. Check `watchPaths` in config matches where `.meta/` dirs exist
+2. Create `.meta/` directories if needed: `mkdir <domain>/.meta`
+3. Verify watcher indexes those paths
+
+### Synthesis stuck (locked entities)
+
+**Symptom:** `synth_list` shows locked entities that never unlock
+**Cause:** Previous synthesis crashed, leaving stale `.lock` file
+**Fix:**
+1. Check lock: `synth_detail <path>` — look for `locked: true`
+2. Locks auto-expire after 30 minutes
+3. For immediate unlock: delete `.meta/.lock` file manually
+
+### Executor timeouts
+
+**Symptom:** `synth_trigger` fails with timeout error
+**Cause:** Subprocess took longer than configured timeout
+**Fix:**
+1. Increase timeout in config (`architectTimeout`, `builderTimeout`, `criticTimeout`)
+2. Check if the LLM provider is slow or rate-limited
+3. Check scope size: large scopes with many files take longer
+
+### LLM errors in synthesis steps
+
+**Symptom:** `synth_detail` shows `_error` field with step/code/message
+**Cause:** Subprocess failed (API error, malformed output, rate limit)
+**Fix:**
+1. Check error details: `synth_detail <path>` — the `_error.step` tells you which step failed
+2. Architect failure with existing `_builder`: engine reuses cached brief (self-healing)
+3. Architect failure without `_builder` (first run): retry with `synth_trigger`
+4. Builder failure: meta stays stale, retried next cycle automatically
+5. Critic failure: content saved without feedback, not critical
+
+## Gotchas
+
+- `synth_trigger` runs a full LLM cycle (3 subprocess calls). It can take
+  several minutes.
+- A locked meta (another synthesis in progress) will be skipped silently.
+- First-run quality is lower — the feedback loop needs 2-3 cycles to calibrate.

package/dist/src/cli.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CLI for installing/uninstalling the jeeves-meta OpenClaw plugin.
+ *
+ * Usage:
+ *   npx \@karmaniverous/jeeves-meta-openclaw install
+ *   npx \@karmaniverous/jeeves-meta-openclaw uninstall
+ *
+ * Bypasses OpenClaw's `plugins install` command, which has a known
+ * spawn EINVAL bug on Windows (https://github.com/openclaw/openclaw/issues/9224).
+ *
+ * Supports non-default installations via:
+ *   - OPENCLAW_CONFIG env var (path to openclaw.json)
+ *   - OPENCLAW_HOME env var (path to .openclaw directory)
+ *   - Default: ~/.openclaw/openclaw.json
+ *
+ * @module cli
+ */
+/** Patch OpenClaw config for install or uninstall. Returns log messages. */
+export declare function patchConfig(config: Record<string, unknown>, mode: 'add' | 'remove'): string[];

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

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

package/dist/src/configLoader.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Config loader — re-exports from the library package.
+ *
+ * @module configLoader
+ */
+export { loadSynthConfig } from '@karmaniverous/jeeves-meta';

package/dist/src/helpers.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared types and utilities for the OpenClaw plugin.
+ *
+ * @module helpers
+ */
+/** Minimal OpenClaw plugin API surface. */
+export interface PluginApi {
+    config?: {
+        plugins?: {
+            entries?: Record<string, {
+                config?: Record<string, unknown>;
+            }>;
+        };
+    };
+    registerTool(tool: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+        execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
+    }, options?: {
+        optional?: boolean;
+    }): void;
+}
+/** Tool result shape. */
+export interface ToolResult {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * Resolve the config file path.
+ *
+ * Resolution order:
+ * 1. Plugin config `configPath` setting
+ * 2. `JEEVES_META_CONFIG` environment variable
+ * 3. Error — no default path
+ */
+export declare function getConfigPath(api: PluginApi): string;
+/** Format a successful tool result. */
+export declare function ok(data: unknown): ToolResult;
+/** Format an error tool result. */
+export declare function fail(error: unknown): ToolResult;

package/dist/src/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * OpenClaw plugin for jeeves-meta.
+ *
+ * Registers synthesis tools, virtual inference rules, and starts
+ * the periodic TOOLS.md writer at gateway startup.
+ *
+ * @packageDocumentation
+ */
+import type { PluginApi } from './helpers.js';
+/** Register all jeeves-meta tools and rules with the OpenClaw plugin API. */
+export default function register(api: PluginApi): void;

package/dist/src/promptInjection.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Generate the Meta menu content for TOOLS.md injection.
+ *
+ * Queries the watcher API for synthesis entity stats and produces
+ * a Markdown section suitable for agent system prompt injection.
+ *
+ * @module promptInjection
+ */
+/**
+ * Generate the Meta menu Markdown for TOOLS.md.
+ *
+ * Three output modes:
+ * 1. Watcher unreachable - ACTION REQUIRED with diagnostic
+ * 2. No entities found - ACTION REQUIRED with setup guidance
+ * 3. Healthy - entity stats + tool listing + skill reference
+ *
+ * @param watcherUrl - Watcher API base URL.
+ * @returns Markdown string for the Meta section.
+ */
+export declare function generateMetaMenu(watcherUrl: string): Promise<string>;

package/dist/src/rules.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Virtual rule definitions and registration for jeeves-meta.
+ *
+ * Registers three inference rules with the watcher at plugin startup:
+ * 1. synth-meta-live — indexes live .meta/meta.json files
+ * 2. synth-meta-archive — indexes archived snapshots
+ * 3. synth-config — indexes the synth config file
+ *
+ * @module rules
+ */
+/**
+ * Register jeeves-meta virtual rules with the watcher.
+ *
+ * Called at plugin startup. Rules are additive — the watcher appends
+ * them after config-file rules (last-match-wins).
+ *
+ * @param watcherUrl - Base URL for the watcher service.
+ */
+export declare function registerSynthRules(watcherUrl: string): Promise<void>;

package/dist/src/tools.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Synth tool registrations for OpenClaw.
+ *
+ * @module tools
+ */
+import { type PluginApi } from './helpers.js';
+/** Register all synth_* tools. */
+export declare function registerSynthTools(api: PluginApi): void;

package/dist/src/toolsWriter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Periodic TOOLS.md disk writer for the Meta section.
+ *
+ * Upserts a `## Meta` section under the shared `# Jeeves Platform Tools`
+ * header. The gateway reads TOOLS.md fresh from disk on each new session.
+ *
+ * @module toolsWriter
+ */
+import type { PluginApi } from './helpers.js';
+/**
+ * Upsert the Meta section in TOOLS.md content.
+ *
+ * Ordering convention: Watcher, Server, Meta.
+ * - If `## Meta` exists, replace in place.
+ * - Otherwise insert after `## Server` if present, after `## Watcher` if
+ *   Server is absent, or after the H1.
+ */
+export declare function upsertMetaSection(existing: string, metaMenu: string): string;
+/**
+ * Start the periodic TOOLS.md writer.
+ * Defers first write by 5s, then refreshes every 60s.
+ *
+ * @param api - Plugin API.
+ * @param watcherUrl - Watcher API base URL.
+ */
+export declare function startToolsWriter(api: PluginApi, watcherUrl: string): void;

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

@@ -0,0 +1,6 @@
+/**
+ * Tests for the TOOLS.md upsert logic.
+ *
+ * @module toolsWriter.test
+ */
+export {};

package/openclaw.plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "jeeves-meta-openclaw",
+  "name": "Jeeves Meta",
+  "description": "Knowledge synthesis tools — trigger synthesis, view status, manage entities.",
+  "version": "0.1.0",
+  "skills": [
+    "dist/skills/jeeves-meta"
+  ],
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "configPath": {
+        "type": "string",
+        "description": "Path to jeeves-meta.config.json. Falls back to JEEVES_META_CONFIG env var."
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@karmaniverous/jeeves-meta-openclaw",
+  "version": "0.1.0",
+  "author": "Jason Williscroft",
+  "description": "OpenClaw plugin for jeeves-meta — synthesis tools and virtual rule registration",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "jeeves-meta-openclaw": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/karmaniverous/jeeves-meta.git",
+    "directory": "packages/openclaw"
+  },
+  "bugs": {
+    "url": "https://github.com/karmaniverous/jeeves-meta/issues"
+  },
+  "homepage": "https://github.com/karmaniverous/jeeves-meta#readme",
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "jeeves-meta",
+    "synthesis"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "auto-changelog": {
+    "output": "CHANGELOG.md",
+    "unreleased": true,
+    "commitLimit": false,
+    "hideCredit": true
+  },
+  "devDependencies": {
+    "@dotenvx/dotenvx": "^1.54.1",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "auto-changelog": "^2.5.0",
+    "cross-env": "^10.1.0",
+    "knip": "^5.85.0",
+    "release-it": "^19.2.4",
+    "rollup": "^4.59.0",
+    "tslib": "^2.8.1",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "npm run build:plugin && npm run build:skills",
+    "changelog": "auto-changelog",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "release": "dotenvx run -f .env.local -- release-it",
+    "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.prerelease --preRelease",
+    "knip": "knip",
+    "test": "vitest run",
+    "typecheck": "tsc",
+    "diagrams": "cd diagrams && plantuml -tpng -o ../assets -r .",
+    "build:plugin": "rimraf dist && cross-env NO_COLOR=1 rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
+    "build:skills": "node scripts/build-skills.mjs"
+  },
+  "release-it": {
+    "git": {
+      "changelog": "npx auto-changelog --unreleased-only --stdout --template https://raw.githubusercontent.com/release-it/release-it/main/templates/changelog-compact.hbs",
+      "commitMessage": "chore: release @karmaniverous/jeeves-meta-openclaw v${version}",
+      "tagName": "openclaw/${version}",
+      "requireBranch": "main"
+    },
+    "github": {
+      "release": true
+    },
+    "hooks": {
+      "after:bump": [
+        "node -e \"const f='openclaw.plugin.json';const j=JSON.parse(require('fs').readFileSync(f,'utf8'));j.version='${version}';require('fs').writeFileSync(f,JSON.stringify(j,null,2)+'\\n')\""
+      ],
+      "after:init": [
+        "npm run lint",
+        "npm run typecheck",
+        "npm run test",
+        "npm run build"
+      ],
+      "before:npm:release": [
+        "npx auto-changelog -p",
+        "git add -A"
+      ],
+      "after:release": [
+        "git switch -c release/openclaw/${version}",
+        "git push -u origin release/openclaw/${version}",
+        "git switch ${branchName}"
+      ]
+    },
+    "npm": {
+      "publish": true
+    }
+  },
+  "dependencies": {
+    "@karmaniverous/jeeves-meta": "*"
+  }
+}