@karmaniverous/jeeves-meta-openclaw 0.4.0 → 0.5.0

package/dist/rollup.config.d.ts

@@ -2,6 +2,10 @@
  * Rollup configuration for the OpenClaw plugin package.
  * Two entry points: plugin (ESM + declarations) and CLI (ESM executable).
  *
+ * `\@karmaniverous/jeeves` is BUNDLED into the plugin output — the plugin
+ * runs in OpenClaw's extensions directory where node_modules is not
+ * reliably available. All other node: builtins are externalized.
+ *
  * @module rollup.config
  */
 import type { RollupOptions } from 'rollup';

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

@@ -55,6 +55,31 @@ critic) runs in the background.
 - `path` (optional): Specific `.meta/` or owner directory path. If omitted,
   synthesizes the stalest candidate.
 
+### meta_seed
+Create a new `.meta/` directory with a skeleton `meta.json` (containing a
+UUID `_id`). Use this to bootstrap synthesis for a new path before the
+first cycle runs.
+
+**Parameters:**
+- `path` (required): Owner directory path where `.meta/` will be created.
+
+### meta_unlock
+Remove a stale `.lock` file from a meta entity. Locks are created during
+synthesis and normally cleaned up automatically; use this when a synthesis
+crashed and left a lock behind.
+
+**Parameters:**
+- `path` (required): `.meta/` or owner directory path with a stuck lock.
+
+### meta_config
+Query the running service configuration. Supports optional JSONPath
+filtering to extract specific settings. Sensitive fields (e.g.
+`gatewayApiKey`) are redacted.
+
+**Parameters:**
+- `path` (optional): JSONPath expression (e.g. `$.schedule`). If omitted,
+  returns the full sanitized config.
+
 ## When to Use
 
 - **Checking synthesis health:** `meta_list`
@@ -63,6 +88,9 @@ critic) runs in the background.
 - **Getting full details:** `meta_detail` with optional `includeArchive: 5`
 - **Understanding what a cycle will do:** `meta_preview`
 - **Forcing a refresh:** `meta_trigger` with optional path
+- **Seeding a new meta:** `meta_seed` with path
+- **Clearing a stuck lock:** `meta_unlock` with path
+- **Inspecting service config:** `meta_config` with optional JSONPath
 - **Reading synthesis output:** Use `watcher_search` filtered by the properties
   configured in `metaProperty` (e.g. `{ "domains": ["meta"] }` in production).
   The default properties are `{ _meta: "current" }` for live metas and
@@ -77,6 +105,12 @@ critic) runs in the background.
 - **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/`.
+- **Progressive synthesis (`_state`):** The builder can set an opaque `_state`
+  value in its output JSON. This state is persisted in `meta.json` and passed
+  back as context on the next cycle, enabling multi-cycle progressive work
+  (e.g. phased analysis, incremental refinement). On builder timeout, the
+  engine attempts to recover partial output — if `_state` advanced, it saves
+  the new state without overwriting existing content.
 
 ## Configuration
 
@@ -104,7 +138,9 @@ Key settings:
 | `skipUnchanged` | true | Skip candidates with no changes since last synthesis |
 | `thinking` | `low` | Thinking level for spawned LLM sessions |
 | `port` | 1938 | HTTP API listen port |
+| `host` | `127.0.0.1` | Bind address for the HTTP server |
 | `schedule` | `*/30 * * * *` | Cron expression for automatic synthesis scheduling |
+| `serverBaseUrl` | (optional) | Public base URL of the service (e.g. `http://myhost:1938`). When set, progress reports include clickable entity links. |
 | `reportChannel` | (optional) | Gateway channel target for progress messages (e.g. Slack channel ID) |
 | `logging.level` | `info` | Log level (trace/debug/info/warn/error) |
 | `logging.file` | (optional) | Log file path |
@@ -221,8 +257,8 @@ The following fields can be changed without restarting the service:
 - `logging.level` — log verbosity
 
 Edit the config file and save; the service detects changes via `fs.watchFile`.
-All other fields (including `metaProperty`, `port`, timeouts) require a service
-restart.
+All other fields (including `metaProperty`, `host`, `port`, timeouts) require a
+service restart.
 
 ### Progress Reporting
 
@@ -302,7 +338,7 @@ To uninstall: `npx @karmaniverous/jeeves-meta-openclaw uninstall`
       "jeeves-meta-openclaw": {
         "enabled": true,
         "config": {
-          "serviceUrl": "http://127.0.0.1:1938"
+          "apiUrl": "http://127.0.0.1:1938"
         }
       }
     }
@@ -357,7 +393,7 @@ The service exposes these endpoints (default port 1938):
 | POST | `/synthesize` | Enqueue synthesis (stalest or specific path) |
 | POST | `/seed` | Create `.meta/` directory + meta.json |
 | POST | `/unlock` | Remove `.lock` file from a meta entity |
-| GET | `/config/validate` | Return sanitized active configuration |
+| GET | `/config` | Query sanitized config with optional JSONPath (`?path=$.schedule`) |
 
 All endpoints return JSON. The OpenClaw plugin tools are thin wrappers
 around these endpoints.
@@ -371,7 +407,7 @@ jeeves-meta <command> [options]
 ```
 
 Commands: `start`, `status`, `list`, `detail`, `preview`, `synthesize`,
-`seed`, `unlock`, `validate`, `service install|start|stop|status|remove`.
+`seed`, `unlock`, `config`, `service install|start|stop|status|remove`.
 
 Config resolution: `--config` flag → `JEEVES_META_CONFIG` env var → error.
 All client commands support `-p, --port` to specify the service port (default: 1938).
@@ -397,11 +433,11 @@ stalest entity) in the agent's system prompt automatically.
 ### Service unreachable
 
 **Symptom:** TOOLS.md shows "ACTION REQUIRED: jeeves-meta service is unreachable"
-**Cause:** Meta service not running or wrong `serviceUrl` in plugin config
+**Cause:** Meta service not running or wrong `apiUrl` in plugin config
 **Fix:**
 1. Check if the service is running: `jeeves-meta service status` or `curl http://localhost:1938/status`
 2. If down, start it: `jeeves-meta service start` or `jeeves-meta start --config <path>`
-3. If running on a different port, update `serviceUrl` in plugin config
+3. If running on a different port, update `apiUrl` in plugin config
 
 ### Watcher unreachable
 
@@ -437,13 +473,19 @@ stalest entity) in the agent's system prompt automatically.
 
 ### Executor timeouts
 
-**Symptom:** `meta_trigger` fails with timeout error
+**Symptom:** `meta_detail` shows `_error` with code `TIMEOUT`
 **Cause:** Subprocess took longer than configured timeout
+**Note:** The engine attempts partial recovery on builder timeouts. If the
+builder wrote partial output with an advanced `_state`, the state is saved
+(preserving existing content) and the error is recorded. This means
+progressive work is not lost on timeout — only the content update is skipped.
 **Fix:**
-1. Increase timeout in config (`architectTimeout`, `builderTimeout`,
+1. Check if `_state` advanced (partial recovery succeeded) — subsequent
+   cycles can continue from where the builder left off
+2. 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
+3. Check if the LLM provider is slow or rate-limited
+4. Check scope size: large scopes with many files take longer
 
 ### LLM errors in synthesis steps
 

package/dist/src/cli.d.ts

@@ -15,5 +15,4 @@
  *
  * @module cli
  */
-/** Patch OpenClaw config for install or uninstall. Returns log messages. */
-export declare function patchConfig(config: Record<string, unknown>, mode: 'add' | 'remove'): string[];
+export {};

package/dist/src/constants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared constants for the jeeves-meta OpenClaw plugin.
+ *
+ * @module constants
+ */
+/** Plugin identifier used for config resolution and error guidance. */
+export declare const PLUGIN_ID = "jeeves-meta-openclaw";

package/dist/src/helpers.d.ts

@@ -1,50 +1,10 @@
 /**
- * Shared types and utilities for the OpenClaw plugin.
+ * Meta-specific convenience wrappers over `@karmaniverous/jeeves` core SDK.
  *
  * @module helpers
  */
-/** Minimal OpenClaw plugin API surface. */
-export interface PluginApi {
-    config?: {
-        plugins?: {
-            entries?: Record<string, {
-                config?: Record<string, unknown>;
-            }>;
-        };
-    };
-    resolvePath?: (input: string) => string;
-    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 a plugin setting via the standard three-step fallback chain:
- * plugin config → environment variable → default value.
- *
- * @param api - Plugin API.
- * @param configKey - Key in the plugin config object.
- * @param envVar - Environment variable name.
- * @param fallback - Default value if neither source provides one.
- */
-export declare function resolvePluginSetting(api: PluginApi, configKey: string, envVar: string, fallback: string): string;
+import { type PluginApi } from '@karmaniverous/jeeves';
 /** Resolve the meta service URL. */
 export declare function getServiceUrl(api: PluginApi): string;
 /** Resolve the platform config root. */
 export declare function getConfigRoot(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

@@ -6,6 +6,6 @@
  *
  * @packageDocumentation
  */
-import { type PluginApi } from './helpers.js';
+import { type PluginApi } from '@karmaniverous/jeeves';
 /** Register all jeeves-meta tools with the OpenClaw plugin API. */
 export default function register(api: PluginApi): void;

package/dist/src/serviceClient.d.ts

@@ -55,11 +55,13 @@ export interface MetasResponse {
 /** Constructor config. */
 interface MetaServiceConfig {
     /** Base URL of the jeeves-meta service (e.g. http://127.0.0.1:1938). */
-    serviceUrl: string;
+    apiUrl: string;
 }
 export declare class MetaServiceClient {
     private readonly baseUrl;
     constructor(config: MetaServiceConfig);
+    /** Return the base URL (for error reporting). */
+    getBaseUrl(): string;
     /** GET helper — returns parsed JSON. */
     private get;
     /** POST helper — returns parsed JSON. */
@@ -88,7 +90,7 @@ export declare class MetaServiceClient {
     seed(path: string): Promise<unknown>;
     /** POST /unlock — remove .lock from a meta entity. */
     unlock(path: string): Promise<unknown>;
-    /** GET /config/validate — validate current config. */
-    validate(): Promise<unknown>;
+    /** GET /config — query service config with optional JSONPath. */
+    config(path?: string): Promise<unknown>;
 }
 export {};

package/dist/src/tools.d.ts

@@ -6,7 +6,7 @@
  *
  * @module tools
  */
-import { type PluginApi } from './helpers.js';
+import { type PluginApi } from '@karmaniverous/jeeves';
 import type { MetaServiceClient } from './serviceClient.js';
 /** Register all meta_* tools. */
 export declare function registerMetaTools(api: PluginApi, client: MetaServiceClient): void;

package/openclaw.plugin.json

@@ -2,16 +2,17 @@
   "id": "jeeves-meta-openclaw",
   "name": "Jeeves Meta",
   "description": "Knowledge synthesis tools — trigger synthesis, view status, manage entities.",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "skills": [
     "dist/skills/jeeves-meta"
   ],
   "configSchema": {
     "type": "object",
     "properties": {
-      "serviceUrl": {
+      "apiUrl": {
         "type": "string",
-        "description": "URL of the jeeves-meta HTTP service. Defaults to http://127.0.0.1:1938. Falls back to JEEVES_META_URL env var."
+        "description": "URL of the jeeves-meta HTTP service. Falls back to JEEVES_META_URL env var.",
+        "default": "http://127.0.0.1:1938"
       },
       "configRoot": {
         "type": "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-meta-openclaw",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "author": "Jason Williscroft",
   "description": "OpenClaw plugin for jeeves-meta — synthesis tools and virtual rule registration",
   "license": "BSD-3-Clause",
@@ -20,6 +20,7 @@
   },
   "files": [
     "dist",
+    "content",
     "openclaw.plugin.json"
   ],
   "publishConfig": {
@@ -57,6 +58,8 @@
   },
   "devDependencies": {
     "@dotenvx/dotenvx": "^1.55.1",
+    "@rollup/plugin-commonjs": "^29.0.2",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
     "auto-changelog": "^2.5.0",
     "cross-env": "^10.1.0",
@@ -67,7 +70,7 @@
     "vitest": "^4.1.0"
   },
   "scripts": {
-    "build": "npm run build:plugin && npm run build:skills",
+    "build": "npm run build:plugin && npm run build:skills && npm run build:content",
     "changelog": "auto-changelog",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
@@ -78,7 +81,8 @@
     "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"
+    "build:skills": "node scripts/build-skills.mjs",
+    "build:content": "node scripts/copy-content.mjs"
   },
   "release-it": {
     "git": {
@@ -115,6 +119,6 @@
     }
   },
   "dependencies": {
-    "@karmaniverous/jeeves": "^0.1.1"
+    "@karmaniverous/jeeves": "^0.2.0"
   }
 }