@karmaniverous/jeeves-meta-openclaw 0.16.0 → 0.17.0

package/README.md

@@ -5,8 +5,8 @@ OpenClaw plugin for [jeeves-meta](https://github.com/karmaniverous/jeeves-meta/t
 ## Features
 
 - **Twelve tools** — standard: `meta_status`, `meta_config`, `meta_config_apply`, `meta_service`; custom: `meta_list`, `meta_detail`, `meta_trigger`, `meta_preview`, `meta_seed`, `meta_unlock`, `meta_queue` (list/clear/abort), `meta_update`
-- **MetaServiceClient** — typed HTTP client delegating all operations to the running service
-- **Phase-state awareness** — tools expose per-meta `_phaseState`, `owedPhase`, and phase-state summary from the service's phase-state machine
+- **SDK client** — every tool calls the running service through `@karmaniverous/jeeves-meta-sdk`
+- **Phase-state awareness** — tools expose per-meta `phaseState`, `owedPhase`, and phase-state summary from the service's phase-state machine
 - **Lazy config** — registers with no config; `configRoot` is resolved when a tool needs it
 - **Consumer skill** — `jeeves-meta` skill shipped through the plugin manifest
 

package/dist/index.js

@@ -1,6 +1,8 @@
-import { resolvePluginSetting, resolveOptionalPluginSetting, fail, init, resolveWorkspacePath, getErrorMessage, fetchJson, postJson, ok, connectionFail, createPluginToolset, jeevesComponentDescriptorSchema, getPackageVersion } from '@karmaniverous/jeeves';
-import { getEndpoint, META_COMPONENT } from '@karmaniverous/jeeves-meta-core';
+import { resolvePluginSetting, resolveOptionalPluginSetting, fail, init, resolveWorkspacePath, getErrorMessage, connectionFail, ok, createPluginToolset, jeevesComponentDescriptorSchema, getPackageVersion } from '@karmaniverous/jeeves';
+import { META_CATALOG, META_COMPONENT } from '@karmaniverous/jeeves-meta-core';
 import { z } from 'zod';
+import { isMetaError, errorBodyText, createMetaClient } from '@karmaniverous/jeeves-meta-sdk';
+import { CatalogClientError } from '@karmaniverous/jeeves/catalog';
 
 /**
  * Shared constants for the jeeves-meta OpenClaw plugin.
@@ -109,137 +111,203 @@ function requireConfigRoot(tool, gate, needsConfigRoot = () => true) {
 }
 
 /**
- * Thin HTTP client for the jeeves-meta service.
+ * Tool result for a failed SDK call, worded as the 0.16.0 tools worded it
+ * (spec 4.4.7). A non-2xx response reads as `Error: HTTP {status}: {body}`,
+ * with the body exactly as received (now the standard error body, so the
+ * text carries the code and message); an unreachable service gets the
+ * connection guidance; anything else reads as `Error: {message}`. Pure.
  *
- * Plugin delegates all operations to the running service via HTTP.
- * Shared response types are imported from `@karmaniverous/jeeves-meta-core`.
+ * @module toolError
+ */
+/**
+ * The error a status-0 `MetaError` wraps (the network error), so
+ * connection guidance sees the same cause it saw in 0.16.0.
  *
- * @module serviceClient
+ * @param error - A status-0 MetaError.
+ * @returns The underlying error, or the MetaError itself.
  */
-class MetaServiceClient {
-    baseUrl;
-    constructor(config) {
-        this.baseUrl = config.apiUrl.replace(/\/$/, '');
-    }
-    /** Return the base URL (for error reporting). */
-    getBaseUrl() {
-        return this.baseUrl;
-    }
-    /** GET helper — returns parsed JSON. */
-    async get(path) {
-        return fetchJson(this.baseUrl + path);
-    }
-    /** POST helper — returns parsed JSON. */
-    async post(path, body) {
-        return postJson(this.baseUrl + path, body);
+function underlying(error) {
+    const inner = error.cause instanceof CatalogClientError ? error.cause.cause : error.cause;
+    return inner ?? error;
+}
+/**
+ * Tool result for a failed call.
+ *
+ * @param error - What the SDK call threw.
+ * @param baseUrl - The service URL the call used.
+ * @returns The error result.
+ */
+function toolError(error, baseUrl) {
+    if (!isMetaError(error))
+        return fail(error);
+    if (error.status >= 300) {
+        return fail(new Error(`HTTP ${String(error.status)}: ${errorBodyText(error)}`));
     }
-    /**
-     * Interpolate a parameterized endpoint path.
-     * Replaces `:param` placeholders with URI-encoded values.
-     */
-    endpointPath(name, params) {
-        let p = getEndpoint(name).path;
-        if (params) {
-            for (const [key, value] of Object.entries(params)) {
-                p = p.replace(`:${key}`, encodeURIComponent(value));
+    if (error.issues !== undefined)
+        return fail(error);
+    return connectionFail(underlying(error), baseUrl, PLUGIN_ID);
+}
+
+/**
+ * Shared parts of the custom tools: catalog descriptions, the mapping of
+ * tool parameters to query strings, and the call wrapper that turns a
+ * failure into the 0.16.0-worded tool error. Pure.
+ *
+ * @module toolHelpers
+ */
+/** A catalog entry's description. */
+function entryDescription(name) {
+    const entry = META_CATALOG.entries.find((e) => e.name === name);
+    return entry?.description ?? '';
+}
+/** A number or boolean as a query string; anything else stays absent. */
+const str = (value) => typeof value === 'number' || typeof value === 'boolean'
+    ? String(value)
+    : undefined;
+/** A boolean filter as its query flag; undefined stays absent. */
+const flag = (value) => value === undefined ? undefined : value ? 'true' : 'false';
+/** A field list as the comma-separated query value. */
+const list = (value) => Array.isArray(value) && value.length > 0 ? value.join(',') : undefined;
+/** Run a call: its result, or the 0.16.0-worded error (`toolError`). */
+function wrap(baseUrl, fn) {
+    return fn()
+        .then(ok)
+        .catch((error) => toolError(error, baseUrl));
+}
+
+/**
+ * The custom tools that change state: `meta_trigger`, `meta_seed`,
+ * `meta_unlock` and `meta_update`, each calling its catalog entry
+ * through the SDK.
+ *
+ * @module writeTools
+ */
+function buildMetaTriggerTool(client, baseUrl) {
+    return {
+        name: 'meta_trigger',
+        description: entryDescription('synthesize'),
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Optional: specific .meta/ or owner path to synthesize.',
+                },
+            },
+        },
+        execute: async (_id, params) => wrap(baseUrl, () => client.synthesize(params.path ? { path: params.path } : {})),
+    };
+}
+function buildMetaSeedTool(client, baseUrl) {
+    return {
+        name: 'meta_seed',
+        description: entryDescription('seed'),
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Owner directory path to seed with .meta/ and meta.json.',
+                },
+                crossRefs: {
+                    type: 'string',
+                    description: 'JSON array of cross-ref owner paths (e.g. \'["<drive label>:/path/a","<drive label>:/path/b"]\'). Use server_drives to discover available drive labels.',
+                },
+                steer: {
+                    type: 'string',
+                    description: 'Steering prompt written as _steer in the initial meta.json.',
+                },
+            },
+            required: ['path'],
+        },
+        execute: async (_id, params) => {
+            let crossRefs;
+            if (typeof params.crossRefs === 'string' && params.crossRefs) {
+                try {
+                    crossRefs = JSON.parse(params.crossRefs);
+                }
+                catch (e) {
+                    const message = e instanceof Error ? e.message : String(e);
+                    return ok({
+                        error: 'Invalid JSON in crossRefs parameter.',
+                        details: message,
+                    });
+                }
             }
-        }
-        return p;
-    }
-    /** GET /status — service health + queue state. */
-    async status() {
-        return this.get(this.endpointPath('status'));
-    }
-    /** GET /metas — list all meta entities with summary. */
-    async listMetas(params) {
-        const qs = new URLSearchParams();
-        if (params?.pathPrefix)
-            qs.set('pathPrefix', params.pathPrefix);
-        if (params?.hasError !== undefined)
-            qs.set('hasError', String(params.hasError));
-        if (params?.staleHours !== undefined)
-            qs.set('staleHours', String(params.staleHours));
-        if (params?.neverSynthesized !== undefined)
-            qs.set('neverSynthesized', String(params.neverSynthesized));
-        if (params?.locked !== undefined)
-            qs.set('locked', String(params.locked));
-        if (params?.disabled !== undefined)
-            qs.set('disabled', String(params.disabled));
-        if (params?.fields?.length)
-            qs.set('fields', params.fields.join(','));
-        const query = qs.toString();
-        return this.get(this.endpointPath('listMetas') + (query ? '?' + query : ''));
-    }
-    /** PATCH /metas/:path — update user-settable reserved properties. */
-    async update(metaPath, updates) {
-        return fetchJson(`${this.baseUrl}${this.endpointPath('updateMeta', { path: metaPath })}`, {
-            method: 'PATCH',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(updates),
-        });
-    }
-    /** GET /metas/:path — detail for a single meta. */
-    async detail(metaPath, options) {
-        const qs = new URLSearchParams();
-        if (options?.includeArchive !== undefined)
-            qs.set('includeArchive', String(options.includeArchive));
-        if (options?.fields?.length)
-            qs.set('fields', options.fields.join(','));
-        const query = qs.toString();
-        return this.get(this.endpointPath('metaDetail', { path: metaPath }) +
-            (query ? '?' + query : ''));
-    }
-    /** GET /preview — dry-run next synthesis candidate. */
-    async preview(path) {
-        const qs = path ? '?path=' + encodeURIComponent(path) : '';
-        return this.get(this.endpointPath('preview') + qs);
-    }
-    /** POST /synthesize — enqueue synthesis. */
-    async synthesize(path) {
-        return this.post(this.endpointPath('synthesize'), path ? { path } : {});
-    }
-    /** POST /seed — create .meta/ for a path. */
-    async seed(path, crossRefs, steer) {
-        const body = { path };
-        if (crossRefs !== undefined)
-            body.crossRefs = crossRefs;
-        if (steer !== undefined)
-            body.steer = steer;
-        return this.post(this.endpointPath('seed'), body);
-    }
-    /** POST /unlock — remove .lock from a meta entity. */
-    async unlock(path) {
-        return this.post(this.endpointPath('unlock'), { path });
-    }
-    /** GET /config — query service config with optional JSONPath. */
-    async config(path) {
-        const qs = path ? '?path=' + encodeURIComponent(path) : '';
-        return this.get(this.endpointPath('config') + qs);
-    }
-    /** GET /queue — current queue state. */
-    async queue() {
-        return this.get(this.endpointPath('queue'));
-    }
-    /** POST /queue/clear — remove all pending queue items. */
-    async clearQueue() {
-        return this.post(this.endpointPath('queueClear'), {});
-    }
-    /** POST /synthesize/abort — abort current synthesis. */
-    async abort() {
-        return this.post(this.endpointPath('abort'), {});
-    }
+            const steer = typeof params.steer === 'string' && params.steer
+                ? params.steer
+                : undefined;
+            return wrap(baseUrl, () => client.seed({ path: params.path, crossRefs, steer }));
+        },
+    };
+}
+function buildMetaUnlockTool(client, baseUrl) {
+    return {
+        name: 'meta_unlock',
+        description: entryDescription('unlock'),
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Path to the .meta/ directory or owner directory.',
+                },
+            },
+            required: ['path'],
+        },
+        execute: async (_id, params) => wrap(baseUrl, () => client.unlock({ path: params.path })),
+    };
+}
+function buildMetaUpdateTool(client, baseUrl) {
+    return {
+        name: 'meta_update',
+        description: entryDescription('updateMeta'),
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Path to the .meta/ directory or owner directory.',
+                },
+                updates: {
+                    type: 'object',
+                    description: 'Properties to set. Supported: _steer, _emphasis, _depth, _crossRefs, _disabled. Set to null to remove.',
+                    properties: {
+                        _steer: { type: ['string', 'null'] },
+                        _emphasis: { type: ['number', 'null'] },
+                        _depth: { type: ['number', 'null'] },
+                        _crossRefs: {
+                            oneOf: [
+                                { type: 'array', items: { type: 'string' } },
+                                { type: 'null' },
+                            ],
+                        },
+                        _disabled: { type: ['boolean', 'null'] },
+                    },
+                },
+            },
+            required: ['path', 'updates'],
+        },
+        execute: async (_id, params) => wrap(baseUrl, () => client.updateMeta({
+            ...params.updates,
+            path: params.path,
+        })),
+    };
 }
 
 /**
  * Custom domain-specific tool descriptors for the meta plugin.
  *
  * These tools supplement the standard factory-produced tools
- * (meta_status, meta_config, meta_config_apply, meta_service).
+ * (meta_status, meta_config, meta_config_apply, meta_service). Each calls
+ * its catalog entry through the SDK (Decision 187); descriptions come from
+ * `META_CATALOG`; input schemas stay hand-written (Decision 188).
  *
  * @module customTools
  */
 /** Build the array of custom domain-specific tool descriptors. */
-function buildCustomTools(client, baseUrl) {
+function buildCustomTools(baseUrl) {
+    const client = createMetaClient({ baseUrl });
     return [
         buildMetaListTool(client, baseUrl),
         buildMetaDetailTool(client, baseUrl),
@@ -251,16 +319,10 @@ function buildCustomTools(client, baseUrl) {
         buildMetaUpdateTool(client, baseUrl),
     ];
 }
-/** Wrap tool execution with connection error handling. */
-function wrap(baseUrl, fn) {
-    return fn()
-        .then(ok)
-        .catch((error) => connectionFail(error, baseUrl, PLUGIN_ID));
-}
 function buildMetaListTool(client, baseUrl) {
     return {
         name: 'meta_list',
-        description: getEndpoint('listMetas').description,
+        description: entryDescription('listMetas'),
         parameters: {
             type: 'object',
             properties: {
@@ -289,13 +351,13 @@ function buildMetaListTool(client, baseUrl) {
         execute: async (_id, params) => {
             const filter = params.filter;
             return wrap(baseUrl, () => client.listMetas({
-                pathPrefix: params.pathPrefix,
-                hasError: filter?.hasError,
-                staleHours: filter?.staleHours,
-                neverSynthesized: filter?.neverSynthesized,
-                locked: filter?.locked,
-                disabled: filter?.disabled,
-                fields: params.fields,
+                pathPrefix: params.pathPrefix || undefined,
+                hasError: flag(filter?.hasError),
+                staleHours: str(filter?.staleHours),
+                neverSynthesized: flag(filter?.neverSynthesized),
+                locked: flag(filter?.locked),
+                disabled: flag(filter?.disabled),
+                fields: list(params.fields),
             }));
         },
     };
@@ -303,7 +365,7 @@ function buildMetaListTool(client, baseUrl) {
 function buildMetaDetailTool(client, baseUrl) {
     return {
         name: 'meta_detail',
-        description: getEndpoint('metaDetail').description,
+        description: entryDescription('metaDetail'),
         parameters: {
             type: 'object',
             properties: {
@@ -323,16 +385,17 @@ function buildMetaDetailTool(client, baseUrl) {
             },
             required: ['path'],
         },
-        execute: async (_id, params) => wrap(baseUrl, () => client.detail(params.path, {
-            includeArchive: params.includeArchive,
-            fields: params.fields,
+        execute: async (_id, params) => wrap(baseUrl, () => client.metaDetail({
+            path: params.path,
+            includeArchive: str(params.includeArchive),
+            fields: list(params.fields),
         })),
     };
 }
 function buildMetaPreviewTool(client, baseUrl) {
     return {
         name: 'meta_preview',
-        description: getEndpoint('preview').description,
+        description: entryDescription('preview'),
         parameters: {
             type: 'object',
             properties: {
@@ -342,89 +405,13 @@ function buildMetaPreviewTool(client, baseUrl) {
                 },
             },
         },
-        execute: async (_id, params) => wrap(baseUrl, () => client.preview(params.path)),
-    };
-}
-function buildMetaTriggerTool(client, baseUrl) {
-    return {
-        name: 'meta_trigger',
-        description: getEndpoint('synthesize').description,
-        parameters: {
-            type: 'object',
-            properties: {
-                path: {
-                    type: 'string',
-                    description: 'Optional: specific .meta/ or owner path to synthesize.',
-                },
-            },
-        },
-        execute: async (_id, params) => wrap(baseUrl, () => client.synthesize(params.path)),
-    };
-}
-function buildMetaSeedTool(client, baseUrl) {
-    return {
-        name: 'meta_seed',
-        description: getEndpoint('seed').description,
-        parameters: {
-            type: 'object',
-            properties: {
-                path: {
-                    type: 'string',
-                    description: 'Owner directory path to seed with .meta/ and meta.json.',
-                },
-                crossRefs: {
-                    type: 'string',
-                    description: 'JSON array of cross-ref owner paths (e.g. \'["<drive label>:/path/a","<drive label>:/path/b"]\'). Use server_drives to discover available drive labels.',
-                },
-                steer: {
-                    type: 'string',
-                    description: 'Steering prompt written as _steer in the initial meta.json.',
-                },
-            },
-            required: ['path'],
-        },
-        execute: async (_id, params) => {
-            let crossRefs;
-            if (typeof params.crossRefs === 'string' && params.crossRefs) {
-                try {
-                    crossRefs = JSON.parse(params.crossRefs);
-                }
-                catch (e) {
-                    const message = e instanceof Error ? e.message : String(e);
-                    return ok({
-                        error: 'Invalid JSON in crossRefs parameter.',
-                        details: message,
-                    });
-                }
-            }
-            const steer = typeof params.steer === 'string' && params.steer
-                ? params.steer
-                : undefined;
-            return wrap(baseUrl, () => client.seed(params.path, crossRefs, steer));
-        },
-    };
-}
-function buildMetaUnlockTool(client, baseUrl) {
-    return {
-        name: 'meta_unlock',
-        description: getEndpoint('unlock').description,
-        parameters: {
-            type: 'object',
-            properties: {
-                path: {
-                    type: 'string',
-                    description: 'Path to the .meta/ directory or owner directory.',
-                },
-            },
-            required: ['path'],
-        },
-        execute: async (_id, params) => wrap(baseUrl, () => client.unlock(params.path)),
+        execute: async (_id, params) => wrap(baseUrl, () => client.preview(params.path ? { path: params.path } : {})),
     };
 }
 function buildMetaQueueTool(client, baseUrl) {
     return {
         name: 'meta_queue',
-        description: `Queue management. list: ${getEndpoint('queue').description} clear: ${getEndpoint('queueClear').description} abort: ${getEndpoint('abort').description}`,
+        description: `Queue management. list: ${entryDescription('queue')} clear: ${entryDescription('queueClear')} abort: ${entryDescription('abort')}`,
         parameters: {
             type: 'object',
             properties: {
@@ -442,7 +429,7 @@ function buildMetaQueueTool(client, baseUrl) {
                 case 'list':
                     return wrap(baseUrl, () => client.queue());
                 case 'clear':
-                    return wrap(baseUrl, () => client.clearQueue());
+                    return wrap(baseUrl, () => client.queueClear());
                 case 'abort':
                     return wrap(baseUrl, () => client.abort());
                 default:
@@ -451,39 +438,6 @@ function buildMetaQueueTool(client, baseUrl) {
         },
     };
 }
-function buildMetaUpdateTool(client, baseUrl) {
-    return {
-        name: 'meta_update',
-        description: getEndpoint('updateMeta').description,
-        parameters: {
-            type: 'object',
-            properties: {
-                path: {
-                    type: 'string',
-                    description: 'Path to the .meta/ directory or owner directory.',
-                },
-                updates: {
-                    type: 'object',
-                    description: 'Properties to set. Supported: _steer, _emphasis, _depth, _crossRefs, _disabled. Set to null to remove.',
-                    properties: {
-                        _steer: { type: ['string', 'null'] },
-                        _emphasis: { type: ['number', 'null'] },
-                        _depth: { type: ['number', 'null'] },
-                        _crossRefs: {
-                            oneOf: [
-                                { type: 'array', items: { type: 'string' } },
-                                { type: 'null' },
-                            ],
-                        },
-                        _disabled: { type: ['boolean', 'null'] },
-                    },
-                },
-            },
-            required: ['path', 'updates'],
-        },
-        execute: async (_id, params) => wrap(baseUrl, () => client.update(params.path, params.updates)),
-    };
-}
 
 /**
  * Meta tool registrations for OpenClaw.
@@ -507,8 +461,7 @@ const CONFIG_ROOT_TOOLS = new Map([
     ['meta_service', (params) => params.action === 'install'],
 ]);
 /** Register all meta_* tools (standard + custom). */
-function registerMetaTools(api, client, descriptor, gate) {
-    const baseUrl = client.getBaseUrl();
+function registerMetaTools(api, baseUrl, descriptor, gate) {
     // Standard tools from factory: meta_status, meta_config, meta_config_apply, meta_service.
     // `apiUrl` is resolved on every call with the same resolution as the
     // custom tools, so the standard HTTP tools hit the configured service.
@@ -520,7 +473,7 @@ function registerMetaTools(api, client, descriptor, gate) {
         api.registerTool(needsConfigRoot ? requireConfigRoot(tool, gate, needsConfigRoot) : tool);
     }
     // Custom domain-specific tools
-    for (const tool of buildCustomTools(client, baseUrl)) {
+    for (const tool of buildCustomTools(baseUrl)) {
         api.registerTool(tool);
     }
 }
@@ -587,9 +540,9 @@ function buildDescriptor() {
  * lazily when a tool that needs it runs.
  */
 function register(api) {
-    const client = new MetaServiceClient({ apiUrl: getServiceUrl(api) });
+    const baseUrl = getServiceUrl(api).replace(/\/$/, '');
     warnIfConfigRootMissing(api);
-    registerMetaTools(api, client, buildDescriptor(), createConfigRootGate(api));
+    registerMetaTools(api, baseUrl, buildDescriptor(), createConfigRootGate(api));
 }
 
 export { register as default, pluginConfigSchema };

package/dist/rollup.config.d.ts

@@ -2,8 +2,8 @@
  * Rollup configuration for the OpenClaw plugin package.
  * Single entry point: the plugin (ESM + declarations).
  *
- * Runtime dependencies (`@karmaniverous/jeeves`, `@karmaniverous/jeeves-meta-core`,
- * `zod`) are externalized and resolved from the plugin's installed dependencies.
+ * Every runtime dependency (and its sub-paths) is externalized and resolved
+ * from the plugin's installed dependencies.
  */
 import type { RollupOptions } from 'rollup';
 declare const _default: RollupOptions[];

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

@@ -1,7 +1,7 @@
 ---
 name: jeeves-meta
 description: >
-  Knowledge synthesis with jeeves-meta. Use when checking synthesis status, listing or inspecting .meta/ entities, triggering or seeding synthesis, managing the meta service, or troubleshooting stale, failed, or locked metas.
+  jeeves-meta knowledge synthesis: status, list or inspect .meta/ entities, trigger or seed synthesis, queue, service, stale, failed or locked metas.
 ---
 
 # jeeves-meta — OpenClaw Skill
@@ -30,7 +30,7 @@ List all `.meta/` directories with summary stats and per-meta projection. Suppor
 
 ### meta_detail
 
-Full detail for a single meta, with optional archive history. Includes `_phaseState` showing the per-phase state machine status.
+Full detail for a single meta, with optional archive history. Includes `phaseState` showing the per-phase state machine status.
 
 **Parameters:**
 
@@ -436,10 +436,30 @@ The service exposes these endpoints (default port 1938):
 | POST | `/unlock` | Remove `.lock` file from a meta entity |
 | GET | `/config` | Query sanitized config with optional JSONPath (`?path=$.schedule`) |
 | POST | `/config/apply` | Apply a config patch (merge or replace) |
-| GET | `/queue` | Queue state: current (with phase), overrides, automatic, pending |
+| GET | `/queue` | Queue state: `current` (with phase), `pending` overrides, `automatic` candidates |
 | POST | `/queue/clear` | Remove all override queue entries |
+| GET | `/openapi.json` | OpenAPI 3.1 document of every route |
 
-All endpoints return JSON. The OpenClaw plugin tools are thin wrappers around these endpoints.
+All endpoints return JSON and validate their requests (a malformed request is `HTTP 400` `FST_ERR_VALIDATION`). The OpenClaw plugin tools call these endpoints through `@karmaniverous/jeeves-meta-sdk`.
+
+### Error codes
+
+A failed tool reads `Error: HTTP <status>: <body>`; the body is `{ statusCode, code, error, message }`. Act on the `code`:
+
+| `code` | Status | What it means | What to do |
+| --- | --- | --- | --- |
+| `META_NOT_FOUND` | 404 | No meta at that path | Check the path with `meta_list` (owner path or `.meta/` path); create it with `meta_seed` |
+| `META_ALREADY_EXISTS` | 409 | `meta_seed` on a path that already has `.meta/` | Nothing to create; use `meta_update` to change it |
+| `META_NOT_LOCKED` | 409 | `meta_unlock` on a meta with no lock | Nothing to do; it is already unlocked |
+| `META_WATCHER_UNAVAILABLE` | 503 | The service could not reach jeeves-watcher | Check `watcher_status`; retry once the watcher is up (see Troubleshooting) |
+| `META_NOT_READY` | 503 | The service is starting | Retry in a few seconds; `meta_status` (it reports `serviceState: "starting"`) and `meta_config` work meanwhile |
+| `META_INVALID_JSONPATH` | 400 | `meta_config` with a JSONPath that cannot be evaluated | Fix the expression (e.g. `$.schedule`) |
+| `META_CONFIG_UNAVAILABLE` | 500 | `meta_config_apply` on a service started without a config file | Restart the service with `--config <path>`, or edit the config file directly |
+| `JEEVES_CONFIG_INVALID` | 400 | `meta_config_apply`: the patched config is invalid | Read `message` for the failing field; fix the patch |
+| `FST_ERR_VALIDATION` | 400 | A tool sent a request its route rejects | Read `message`; check the tool's parameters |
+| (no code) | 500 | An unexpected failure | Read the service log (`jeeves-meta service status`); report it |
+
+No error carries `Retry-After`. A connection error (no HTTP status) means the service is unreachable: see Troubleshooting.
 
 ## Service CLI
 
@@ -449,7 +469,7 @@ The service package ships a CLI:
 jeeves-meta <command> [options]
 ```
 
-Commands: `start`, `status`, `list`, `detail`, `preview`, `synthesize`, `seed`, `unlock`, `abort`, `prune`, `config`, `queue list|clear`, `service install|start|stop|status|remove`.
+Commands: `start`, `status`, `list`, `detail`, `preview`, `synthesize`, `seed`, `unlock`, `abort`, `prune` (no API route yet, #69), `config`, `queue list|clear`, `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). The `start` command uses `--config`/`-c` instead (port is read from the config file).
 

package/dist/src/customTools.d.ts

@@ -2,11 +2,12 @@
  * Custom domain-specific tool descriptors for the meta plugin.
  *
  * These tools supplement the standard factory-produced tools
- * (meta_status, meta_config, meta_config_apply, meta_service).
+ * (meta_status, meta_config, meta_config_apply, meta_service). Each calls
+ * its catalog entry through the SDK (Decision 187); descriptions come from
+ * `META_CATALOG`; input schemas stay hand-written (Decision 188).
  *
  * @module customTools
  */
 import { type ToolDescriptor } from '@karmaniverous/jeeves';
-import type { MetaServiceClient } from './serviceClient.js';
 /** Build the array of custom domain-specific tool descriptors. */
-export declare function buildCustomTools(client: MetaServiceClient, baseUrl: string): ToolDescriptor[];
+export declare function buildCustomTools(baseUrl: string): ToolDescriptor[];

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

@@ -0,0 +1,8 @@
+/**
+ * @module customTools.test
+ * What each custom tool sends (spec 4.4.7): tool parameters mapped to the
+ * SDK input as 0.16.0 mapped them to the URL (boolean filters as
+ * `true`/`false`, field lists comma-joined, absent values left out), and
+ * the tools' own parameter errors.
+ */
+export {};

package/dist/src/toolError.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Tool result for a failed SDK call, worded as the 0.16.0 tools worded it
+ * (spec 4.4.7). A non-2xx response reads as `Error: HTTP {status}: {body}`,
+ * with the body exactly as received (now the standard error body, so the
+ * text carries the code and message); an unreachable service gets the
+ * connection guidance; anything else reads as `Error: {message}`. Pure.
+ *
+ * @module toolError
+ */
+import { type ToolResult } from '@karmaniverous/jeeves';
+/**
+ * Tool result for a failed call.
+ *
+ * @param error - What the SDK call threw.
+ * @param baseUrl - The service URL the call used.
+ * @returns The error result.
+ */
+export declare function toolError(error: unknown, baseUrl: string): ToolResult;

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

@@ -0,0 +1,9 @@
+/**
+ * @module toolError.test
+ * Tool results for failed calls (spec 4.4.7), through real tools over a
+ * stubbed `fetch`: a non-2xx reply reads `HTTP {status}: {body}` with the
+ * body as received, an unreachable service gets the connection guidance,
+ * and a timeout, an invalid reply or a non-SDK error reads
+ * `Error: {message}`.
+ */
+export {};

package/dist/src/toolHelpers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared parts of the custom tools: catalog descriptions, the mapping of
+ * tool parameters to query strings, and the call wrapper that turns a
+ * failure into the 0.16.0-worded tool error. Pure.
+ *
+ * @module toolHelpers
+ */
+import { type ToolResult } from '@karmaniverous/jeeves';
+import { type MetaEntryName } from '@karmaniverous/jeeves-meta-core';
+/** A catalog entry's description. */
+export declare function entryDescription(name: MetaEntryName): string;
+/** A number or boolean as a query string; anything else stays absent. */
+export declare const str: (value: unknown) => string | undefined;
+/** A boolean filter as its query flag; undefined stays absent. */
+export declare const flag: (value: unknown) => "true" | "false" | undefined;
+/** A field list as the comma-separated query value. */
+export declare const list: (value: unknown) => string | undefined;
+/** Run a call: its result, or the 0.16.0-worded error (`toolError`). */
+export declare function wrap(baseUrl: string, fn: () => Promise<unknown>): Promise<ToolResult>;

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

@@ -0,0 +1,10 @@
+/**
+ * @module toolSnapshot.test
+ * The registered tools against plugin 0.16.0 (spec 4.4.7): the same tool
+ * names, and each tool's description and input schema unchanged, so agents
+ * see the same tools. `tools-0.16.0.json` was captured from the published
+ * `@karmaniverous/jeeves-meta-openclaw@0.16.0` with the same fake API.
+ * The standard tools come from jeeves' `createPluginToolset`; their input
+ * schemas changed with jeeves 0.11.0 (T2), as listed in `JEEVES_0_11`.
+ */
+export {};

package/dist/src/tools.d.ts

@@ -9,6 +9,5 @@
  */
 import { type JeevesComponentDescriptor, type PluginApi } from '@karmaniverous/jeeves';
 import { type ConfigRootGate } from './configRoot.js';
-import type { MetaServiceClient } from './serviceClient.js';
 /** Register all meta_* tools (standard + custom). */
-export declare function registerMetaTools(api: PluginApi, client: MetaServiceClient, descriptor: JeevesComponentDescriptor, gate: ConfigRootGate): void;
+export declare function registerMetaTools(api: PluginApi, baseUrl: string, descriptor: JeevesComponentDescriptor, gate: ConfigRootGate): void;

package/dist/src/writeTools.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The custom tools that change state: `meta_trigger`, `meta_seed`,
+ * `meta_unlock` and `meta_update`, each calling its catalog entry
+ * through the SDK.
+ *
+ * @module writeTools
+ */
+import { type ToolDescriptor } from '@karmaniverous/jeeves';
+import type { MetaClient } from '@karmaniverous/jeeves-meta-sdk';
+export declare function buildMetaTriggerTool(client: MetaClient, baseUrl: string): ToolDescriptor;
+export declare function buildMetaSeedTool(client: MetaClient, baseUrl: string): ToolDescriptor;
+export declare function buildMetaUnlockTool(client: MetaClient, baseUrl: string): ToolDescriptor;
+export declare function buildMetaUpdateTool(client: MetaClient, baseUrl: string): ToolDescriptor;

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "jeeves-meta-openclaw",
   "name": "Jeeves Meta",
   "description": "Knowledge synthesis tools — trigger synthesis, view status, manage entities.",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "skills": ["dist/skills/jeeves-meta"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -4,24 +4,25 @@
     "url": "https://github.com/karmaniverous/jeeves-meta/issues"
   },
   "dependencies": {
-    "@karmaniverous/jeeves": "0.7.0",
-    "@karmaniverous/jeeves-meta-core": "^0.3.0",
+    "@karmaniverous/jeeves": "0.11.0",
+    "@karmaniverous/jeeves-meta-core": "^0.4.0",
+    "@karmaniverous/jeeves-meta-sdk": "^0.1.0",
     "zod": "^4.6.7"
   },
   "description": "OpenClaw plugin for jeeves-meta — synthesis tools and virtual rule registration",
   "devDependencies": {
-    "@dotenvx/dotenvx": "^2.35.0",
+    "@dotenvx/dotenvx": "^2.38.2",
     "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-node-resolve": "^16.0.3",
-    "@rollup/plugin-typescript": "^12.3.0",
+    "@rollup/plugin-typescript": "^12.3.1",
     "cross-env": "^10.1.0",
-    "release-it": "^21.1.1",
-    "rollup": "^4.64.6",
-    "tslib": "^2.8.1",
-    "vitest": "^5.0.4"
+    "release-it": "^21.1.2",
+    "rollup": "^4.68.3",
+    "tslib": "^2.9.1",
+    "vitest": "^5.1.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24.22.2"
   },
   "exports": {
     ".": {
@@ -114,5 +115,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.16.0"
+  "version": "0.17.0"
 }

package/dist/src/serviceClient.d.ts

@@ -1,101 +0,0 @@
-/**
- * Thin HTTP client for the jeeves-meta service.
- *
- * Plugin delegates all operations to the running service via HTTP.
- * Shared response types are imported from `@karmaniverous/jeeves-meta-core`.
- *
- * @module serviceClient
- */
-import { type GatewayDepHealth, type MetasResponse, type NextPhaseCandidate, type PhaseStateSummary, type ServiceState, type WatcherDepHealth } from '@karmaniverous/jeeves-meta-core';
-export type { GatewayDepHealth, MetasResponse, NextPhaseCandidate, PhaseStateSummary, ServiceState, WatcherDepHealth, };
-/**
- * Service status response from GET /status.
- *
- * The jeeves-core `createStatusHandler` wraps `getHealth()` output under
- * a top-level `health` key. Dependency info lives at `health.dependencies`.
- */
-export interface StatusResponse {
-    /** Service name. */
-    name: string;
-    /** Service uptime in seconds. */
-    uptime: number;
-    /** Overall status (healthy, degraded, unhealthy). */
-    status: string;
-    /** Service version. */
-    version?: string;
-    /** Component-specific health details from getHealth(). */
-    health: {
-        /** Service-specific lifecycle state. */
-        serviceState?: ServiceState;
-        dependencies: {
-            watcher: WatcherDepHealth;
-            gateway: GatewayDepHealth;
-        };
-        /** Per-phase counts of each status, from the scheduler. */
-        phaseStateSummary?: PhaseStateSummary;
-        /** Next phase candidate from the scheduler. */
-        nextPhase?: NextPhaseCandidate | null;
-        [key: string]: unknown;
-    };
-}
-/** Constructor config. */
-interface MetaServiceConfig {
-    /** Base URL of the jeeves-meta service (e.g. http://127.0.0.1:1938). */
-    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. */
-    private post;
-    /**
-     * Interpolate a parameterized endpoint path.
-     * Replaces `:param` placeholders with URI-encoded values.
-     */
-    private endpointPath;
-    /** GET /status — service health + queue state. */
-    status(): Promise<StatusResponse>;
-    /** GET /metas — list all meta entities with summary. */
-    listMetas(params?: {
-        pathPrefix?: string;
-        hasError?: boolean;
-        staleHours?: number;
-        neverSynthesized?: boolean;
-        locked?: boolean;
-        disabled?: boolean;
-        fields?: string[];
-    }): Promise<MetasResponse>;
-    /** PATCH /metas/:path — update user-settable reserved properties. */
-    update(metaPath: string, updates: {
-        _steer?: string | null;
-        _emphasis?: number | null;
-        _depth?: number | null;
-        _crossRefs?: string[] | null;
-        _disabled?: boolean | null;
-    }): Promise<unknown>;
-    /** GET /metas/:path — detail for a single meta. */
-    detail(metaPath: string, options?: {
-        includeArchive?: boolean | number;
-        fields?: string[];
-    }): Promise<unknown>;
-    /** GET /preview — dry-run next synthesis candidate. */
-    preview(path?: string): Promise<unknown>;
-    /** POST /synthesize — enqueue synthesis. */
-    synthesize(path?: string): Promise<unknown>;
-    /** POST /seed — create .meta/ for a path. */
-    seed(path: string, crossRefs?: string[], steer?: string): Promise<unknown>;
-    /** POST /unlock — remove .lock from a meta entity. */
-    unlock(path: string): Promise<unknown>;
-    /** GET /config — query service config with optional JSONPath. */
-    config(path?: string): Promise<unknown>;
-    /** GET /queue — current queue state. */
-    queue(): Promise<unknown>;
-    /** POST /queue/clear — remove all pending queue items. */
-    clearQueue(): Promise<unknown>;
-    /** POST /synthesize/abort — abort current synthesis. */
-    abort(): Promise<unknown>;
-}