@karmaniverous/jeeves-meta-openclaw 0.13.3 → 0.15.0-0

package/README.md

@@ -1,16 +1,14 @@
 # @karmaniverous/jeeves-meta-openclaw
 
-OpenClaw plugin for [jeeves-meta](../service/). A thin HTTP client that registers interactive tools and uses [`@karmaniverous/jeeves`](https://github.com/karmaniverous/jeeves) core for managed TOOLS.md content writing and platform maintenance.
+OpenClaw plugin for [jeeves-meta](https://github.com/karmaniverous/jeeves-meta/tree/main/packages/service). A standard OpenClaw plugin and thin HTTP client that registers interactive tools on top of the [`@karmaniverous/jeeves`](https://github.com/karmaniverous/jeeves) core SDK. It writes no workspace files: static platform content is rendered by `jeeves install`, and live state is served by the tools.
 
 ## 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
-- **TOOLS.md injection** — periodic refresh of entity stats, phase-state summary, failed-phase alerts, and next-phase indicator via `ComponentWriter` from `@karmaniverous/jeeves` (73-second prime interval)
 - **Phase-state awareness** — tools expose per-meta `_phaseState`, `owedPhase`, and phase-state summary from the service's phase-state machine
-- **Cleanup escalation** — passes `gatewayUrl` into `ComponentWriter` so managed-content cleanup can request a gateway session when needed
-- **Dependency health** — shows warnings when watcher/gateway are degraded
-- **Consumer skill** — `SKILL.md` for agent integration
+- **Lazy config** — registers with no config; `configRoot` is resolved when a tool needs it
+- **Consumer skill** — `jeeves-meta` skill shipped through the plugin manifest
 
 ## Plugin Lifecycle
 
@@ -18,24 +16,28 @@ OpenClaw plugin for [jeeves-meta](../service/). A thin HTTP client that register
 
 ## Install
 
+Install with the Jeeves CLI, which runs the OpenClaw install and writes the plugin config:
+
 ```bash
-npm install @karmaniverous/jeeves-meta-openclaw
+jeeves install meta --config-root j:/config
 ```
 
-Then run the CLI installer to register with the OpenClaw gateway:
+Or install it as a standard OpenClaw plugin and configure it yourself:
 
 ```bash
-npx @karmaniverous/jeeves-meta-openclaw install
+openclaw plugins install npm:@karmaniverous/jeeves-meta-openclaw@<version> --pin --accept-capabilities
 ```
 
+Restart the gateway afterwards. There is no plugin-specific installer (the `npx @karmaniverous/jeeves-meta-openclaw install` CLI was removed in favour of `jeeves install`).
+
 ## Configuration
 
-The plugin resolves settings via a three-step fallback chain: plugin config → environment variable → default.
+The plugin resolves settings via a fallback chain: plugin config → environment variable → default.
 
 | Setting | Plugin Config Key | Env Var | Default |
-|---------|-------------------|---------|---------|
+| --- | --- | --- | --- |
 | Service URL | `apiUrl` | `JEEVES_META_URL` | `http://127.0.0.1:1938` |
-| Config Root | `configRoot` | `JEEVES_CONFIG_ROOT` | `j:/config` |
+| Config Root | `configRoot` | `JEEVES_CONFIG_ROOT` | _none_ |
 
 ```json
 {
@@ -53,14 +55,21 @@ The plugin resolves settings via a three-step fallback chain: plugin config →
 }
 ```
 
-The `configRoot` setting tells `@karmaniverous/jeeves` core where to find the platform config directory. Core derives `{configRoot}/jeeves-meta/` for component-specific configuration.
+The `configRoot` setting tells `@karmaniverous/jeeves` core where to find the platform config directory. Core derives `{configRoot}/jeeves-meta/` for component-specific configuration. It has no default: `jeeves install --config-root <path>` writes it.
+
+`configRoot` is resolved **lazily**. Registration always succeeds without it (with a running gateway, `openclaw plugins install` activates the plugin before `jeeves install` writes its config), logging one warning:
+
+```text
+[jeeves-meta] configRoot not configured yet — meta_service install will be unavailable until it is set in plugin config or JEEVES_CONFIG_ROOT
+```
+
+Only `meta_service` with `action: "install"` reads it (core resolves the service config path from it); invoked without it, that call returns an error naming both ways to set it. Core `init()` runs the first time `configRoot` resolves. The other `meta_service` actions (`status`, `start`, `stop`, `restart`, `uninstall`) address the OS service by name, and every other tool only talks HTTP to the service at `apiUrl`, so all of them work without it.
 
 ## Documentation
 
 - **[Plugin Setup](guides/plugin-setup.md)** — installation, config, lifecycle
 - **[Tools Reference](guides/tools-reference.md)** — 12 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, meta_update)
 - **[Virtual Rules](guides/virtual-rules.md)** — watcher inference rules
-- **[TOOLS.md Injection](guides/tools-injection.md)** — dynamic prompt generation
 
 ## License
 

package/dist/index.js

@@ -1,5 +1,6 @@
-import { resolvePluginSetting, resolveOptionalPluginSetting, fetchJson, postJson, ok, connectionFail, createPluginToolset, resolveWorkspacePath, init, loadWorkspaceConfig, WORKSPACE_CONFIG_DEFAULTS, createAsyncContentCache, jeevesComponentDescriptorSchema, getPackageVersion, createComponentWriter } from '@karmaniverous/jeeves';
-import { phaseStatuses, phaseNames, getEndpoint, META_COMPONENT } from '@karmaniverous/jeeves-meta-core';
+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 { z } from 'zod';
 
 /**
  * Shared constants for the jeeves-meta OpenClaw plugin.
@@ -14,184 +15,97 @@ const PLUGIN_ID = 'jeeves-meta-openclaw';
  *
  * @module helpers
  */
+/** Environment variable consulted when plugin config has no `configRoot`. */
+const CONFIG_ROOT_ENV = 'JEEVES_CONFIG_ROOT';
+/** Error returned by tools that need `configRoot` when it is not set. */
+const CONFIG_ROOT_MISSING_MESSAGE = `configRoot not configured — set it in plugin config (plugins.entries.${PLUGIN_ID}.config.configRoot) or via ${CONFIG_ROOT_ENV}`;
 /** Resolve the meta service URL. */
 function getServiceUrl(api) {
     return resolvePluginSetting(api, PLUGIN_ID, 'apiUrl', 'JEEVES_META_URL', 'http://127.0.0.1:1938');
 }
-/** Resolve the platform config root. */
-function getConfigRoot(api) {
-    const value = resolveOptionalPluginSetting(api, PLUGIN_ID, 'configRoot', 'JEEVES_CONFIG_ROOT');
-    if (!value) {
-        throw new Error('configRoot not configured — set it in plugin config or via JEEVES_CONFIG_ROOT env var');
-    }
-    return value;
-}
-
 /**
- * Generate the Meta menu content for TOOLS.md injection.
+ * Resolve the platform config root without throwing.
  *
- * Queries the jeeves-meta service for entity stats and produces
- * a Markdown section suitable for agent system prompt injection.
+ * Order: the plugin's own config (`api.pluginConfig`), then
+ * `plugins.entries.<id>.config`, then the `JEEVES_CONFIG_ROOT` env var.
  *
- * @module promptInjection
+ * @returns The config root, or `undefined` when none is set.
  */
-/** Phase statuses that require per-phase breakdown (everything except fresh). */
-const nonFreshStatuses = phaseStatuses.filter((s) => s !== 'fresh');
+function resolveConfigRoot(api) {
+    const own = api.pluginConfig?.['configRoot'];
+    if (typeof own === 'string' && own)
+        return own;
+    return (resolveOptionalPluginSetting(api, PLUGIN_ID, 'configRoot', CONFIG_ROOT_ENV) || undefined);
+}
+
 /**
- * Format a duration in seconds as a compound human-readable interval.
+ * Lazy `configRoot` resolution for the jeeves-meta plugin.
  *
- * Produces at most two units: `2d 3h`, `1h 35m`, `45m`, etc.
- * Returns `'never synthesized'` for non-finite input.
+ * With a running gateway, `openclaw plugins install` activates the plugin
+ * before `jeeves install` writes its config, so `register()` must not
+ * depend on `configRoot`. The gate resolves it on first use, initializes
+ * core once it is known, and lets tools that need it fail cleanly.
  *
- * @param seconds - Duration in seconds.
- * @returns Formatted interval string.
+ * @module configRoot
  */
-function formatAge(seconds) {
-    if (!isFinite(seconds))
-        return 'never synthesized';
-    const d = Math.floor(seconds / 86400);
-    const h = Math.floor((seconds % 86400) / 3600);
-    const m = Math.floor((seconds % 3600) / 60);
-    if (d > 0 && h > 0)
-        return `${d.toString()}d ${h.toString()}h`;
-    if (d > 0)
-        return `${d.toString()}d`;
-    if (h > 0 && m > 0)
-        return `${h.toString()}h ${m.toString()}m`;
-    if (h > 0)
-        return `${h.toString()}h`;
-    return `${Math.max(m, 1).toString()}m`;
-}
+/** Warning logged once at registration when `configRoot` is unset. */
+const CONFIG_ROOT_WARNING = `[jeeves-meta] configRoot not configured yet — meta_service install will be unavailable until it is set in plugin config or ${CONFIG_ROOT_ENV}`;
 /**
- * Generate the Meta menu Markdown for TOOLS.md.
+ * Create a gate over the plugin API.
  *
- * @param client - MetaServiceClient instance.
- * @returns Markdown string for the Meta section.
+ * Nothing is resolved or initialized until {@link ConfigRootGate.ensure}
+ * is called, so config written after registration is picked up.
  */
-async function generateMetaMenu(client) {
-    const [status, metas] = await Promise.all([
-        client.status(),
-        client.listMetas(),
-    ]);
-    if (metas.summary.total === 0) {
-        return [
-            '> **ACTION REQUIRED: No synthesis entities found.**',
-            '> The service is running but no `.meta/` directories were discovered.',
-            '>',
-            "> **Read the `jeeves-meta` skill's Bootstrapping section** for guidance",
-            '> on creating `.meta/` directories.',
-        ].join('\n');
-    }
-    const { summary } = metas;
-    // Find stalest age
-    let stalestAge = 0;
-    for (const item of metas.metas) {
-        const s = item.stalenessSeconds !== null ? item.stalenessSeconds : Infinity;
-        if (s > stalestAge)
-            stalestAge = s;
-    }
-    const stalestDisplay = summary.stalestPath
-        ? summary.stalestPath + ' (' + formatAge(stalestAge) + ')'
-        : 'n/a';
-    const lastSynthDisplay = summary.lastSynthesizedAt
-        ? (summary.lastSynthesizedPath ?? '') +
-            ' (' +
-            summary.lastSynthesizedAt +
-            ')'
-        : 'n/a';
-    // Service status + dependency health
-    // The core SDK's createStatusHandler nests getHealth() under `health`.
-    const { dependencies } = status.health;
-    const depLines = [];
-    if (dependencies.watcher.status === 'indexing') {
-        depLines.push('> ⏳ **Watcher indexing**: Initial filesystem scan in progress. Synthesis will resume when complete.');
-    }
-    else if (dependencies.watcher.status !== 'ok' &&
-        dependencies.watcher.status !== 'indexing') {
-        depLines.push('> ⚠️ **Watcher**: ' + dependencies.watcher.status);
-    }
-    if (dependencies.watcher.rulesRegistered === false &&
-        dependencies.watcher.status === 'ok') {
-        depLines.push('> ⚠️ **Watcher rules not registered**: Meta files may not render properly in search/server.');
-    }
-    if (dependencies.gateway.status !== 'ok') {
-        depLines.push('> ⚠️ **Gateway**: ' + dependencies.gateway.status);
-    }
-    // Phase-state summary from /status health
-    const phaseLines = [];
-    const phaseSummary = status.health.phaseStateSummary;
-    if (phaseSummary) {
-        // Fresh counts are aggregated; non-fresh show <count> <state> <phase>
-        let freshTotal = 0;
-        for (const phase of phaseNames) {
-            freshTotal += phaseSummary[phase].fresh;
-        }
-        const parts = [];
-        if (freshTotal > 0)
-            parts.push(freshTotal.toString() + ' fresh');
-        for (const phase of phaseNames) {
-            for (const state of nonFreshStatuses) {
-                const count = phaseSummary[phase][state];
-                if (count > 0)
-                    parts.push(`${count.toString()} ${state} ${phase}`);
+function createConfigRootGate(api) {
+    let resolved;
+    return {
+        ensure: () => {
+            if (resolved)
+                return { ok: true, configRoot: resolved };
+            const configRoot = resolveConfigRoot(api);
+            if (!configRoot)
+                return { ok: false, error: CONFIG_ROOT_MISSING_MESSAGE };
+            try {
+                init({ workspacePath: resolveWorkspacePath(api), configRoot });
             }
-        }
-        if (parts.length > 0) {
-            phaseLines.push('Phases: ' + parts.join(', '));
-        }
-        // Failed-phase alert
-        const failedParts = [];
-        for (const item of metas.metas) {
-            const ps = item.phaseState;
-            if (!ps)
-                continue;
-            for (const phase of phaseNames) {
-                if (ps[phase] === 'failed') {
-                    const p = item.path;
-                    failedParts.push(p + ' (' + phase + ')');
-                }
+            catch (error) {
+                return {
+                    ok: false,
+                    error: `jeeves core init failed: ${getErrorMessage(error)}`,
+                };
             }
-        }
-        if (failedParts.length > 0) {
-            phaseLines.push('⚠ Failed: ' +
-                failedParts.slice(0, 10).join(', ') +
-                (failedParts.length > 10
-                    ? ' (+' + (failedParts.length - 10).toString() + ' more)'
-                    : ''));
-        }
-    }
-    // Next-phase indicator from /status health
-    const nextPhase = status.health.nextPhase;
-    if (nextPhase) {
-        phaseLines.push('Next: ' +
-            nextPhase.path +
-            ' → ' +
-            nextPhase.phase +
-            ' (band ' +
-            nextPhase.band.toString() +
-            ', staleness ' +
-            formatAge(nextPhase.staleness) +
-            ')');
-    }
-    return [
-        'The jeeves-meta synthesis engine manages ' +
-            summary.total.toString() +
-            ' meta entities.',
-        '',
-        '### Entity Summary',
-        '| Metric | Value |',
-        '|--------|-------|',
-        '| Total | ' + summary.total.toString() + ' |',
-        '| Stale | ' + summary.stale.toString() + ' |',
-        '| Errors | ' + summary.errors.toString() + ' |',
-        '| Never synthesized | ' + summary.neverSynthesized.toString() + ' |',
-        '| Stalest | ' + stalestDisplay + ' |',
-        '| Last synthesized | ' + lastSynthDisplay + ' |',
-        ...(phaseLines.length > 0 ? ['', '### Phase State', ...phaseLines] : []),
-        ...(depLines.length > 0 ? ['', '### Dependencies', ...depLines] : []),
-        '',
-        'Read the `jeeves-meta` skill for usage guidance, configuration, and troubleshooting.',
-    ].join('\n');
+            resolved = configRoot;
+            return { ok: true, configRoot };
+        },
+    };
+}
+/** Log {@link CONFIG_ROOT_WARNING} once if `configRoot` cannot be resolved now. */
+function warnIfConfigRootMissing(api) {
+    if (resolveConfigRoot(api))
+        return;
+    const warn = api.logger?.warn ??
+        ((m) => {
+            console.warn(m);
+        });
+    warn(CONFIG_ROOT_WARNING);
+}
+/**
+ * Wrap a tool so calls that read `configRoot` return a clear error until
+ * it resolves. Calls for which `needsConfigRoot` is false pass straight
+ * through without touching the gate.
+ */
+function requireConfigRoot(tool, gate, needsConfigRoot = () => true) {
+    return {
+        ...tool,
+        execute: (id, params) => {
+            if (!needsConfigRoot(params))
+                return tool.execute(id, params);
+            const check = gate.ensure();
+            if (!check.ok)
+                return Promise.resolve(fail(check.error));
+            return tool.execute(id, params);
+        },
+    };
 }
 
 /**
@@ -580,12 +494,30 @@ function buildMetaUpdateTool(client, baseUrl) {
  *
  * @module tools
  */
+/**
+ * Tool calls that read `configRoot`, keyed by tool name.
+ *
+ * Only `meta_service` with `action: 'install'` reads it: core's service
+ * manager resolves the component config path via `getComponentConfigDir()`.
+ * The other `meta_service` actions drive the OS service manager by name,
+ * and every other tool only talks HTTP to the meta service at `apiUrl`,
+ * so none of them are gated.
+ */
+const CONFIG_ROOT_TOOLS = new Map([
+    ['meta_service', (params) => params.action === 'install'],
+]);
 /** Register all meta_* tools (standard + custom). */
-function registerMetaTools(api, client, descriptor) {
+function registerMetaTools(api, client, descriptor, gate) {
     const baseUrl = client.getBaseUrl();
-    // Standard tools from factory: meta_status, meta_config, meta_config_apply, meta_service
-    for (const tool of createPluginToolset(descriptor)) {
-        api.registerTool(tool);
+    // 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.
+    const toolset = createPluginToolset(descriptor, {
+        apiUrl: () => getServiceUrl(api),
+    });
+    for (const tool of toolset) {
+        const needsConfigRoot = CONFIG_ROOT_TOOLS.get(tool.name);
+        api.registerTool(needsConfigRoot ? requireConfigRoot(tool, gate, needsConfigRoot) : tool);
     }
     // Custom domain-specific tools
     for (const tool of buildCustomTools(client, baseUrl)) {
@@ -593,59 +525,46 @@ function registerMetaTools(api, client, descriptor) {
     }
 }
 
+/**
+ * Zod schema for the jeeves-meta OpenClaw plugin configuration.
+ *
+ * This is the source of truth for the plugin configSchema.
+ * The build-time script `scripts/generate-plugin-schema.mjs` derives
+ * the JSON Schema in `openclaw.plugin.json` from this definition.
+ *
+ * @module pluginConfigSchema
+ */
+/** Zod schema for the jeeves-meta OpenClaw plugin configuration. */
+const pluginConfigSchema = z.object({
+    apiUrl: z
+        .string()
+        .default('http://127.0.0.1:1938')
+        .describe('URL of the jeeves-meta HTTP service. Falls back to JEEVES_META_URL env var.'),
+    configRoot: z
+        .string()
+        .optional()
+        .describe('Absolute path to the platform config root (e.g. j:/config). Used by @karmaniverous/jeeves core for config directory resolution.'),
+});
+
 /**
  * OpenClaw plugin for jeeves-meta.
  *
  * Thin HTTP client — all operations delegate to the jeeves-meta service.
- * Uses `@karmaniverous/jeeves` core for TOOLS.md and platform content.
+ * A standard OpenClaw plugin: it writes no workspace files and is installed
+ * by `jeeves install` (or `openclaw plugins install`).
  *
  * @packageDocumentation
  */
-/** Register all jeeves-meta tools with the OpenClaw plugin API. */
-function register(api) {
-    const client = new MetaServiceClient({ apiUrl: getServiceUrl(api) });
-    const workspacePath = resolveWorkspacePath(api);
-    init({
-        workspacePath,
-        configRoot: getConfigRoot(api),
-    });
-    const gatewayUrl = loadWorkspaceConfig(workspacePath)?.core?.gatewayUrl ??
-        WORKSPACE_CONFIG_DEFAULTS.core.gatewayUrl;
-    const placeholder = 'The jeeves-meta synthesis engine is initializing...\n\n' +
-        'Read the `jeeves-meta` skill for usage guidance, configuration, and troubleshooting.';
-    let consecutive503s = 0;
-    const getContent = createAsyncContentCache({
-        fetch: async () => {
-            const content = await generateMetaMenu(client);
-            consecutive503s = 0;
-            return content;
-        },
-        placeholder,
-        onError: (error) => {
-            const msg = error instanceof Error ? error.message : String(error);
-            if (/HTTP 503\b/i.test(msg) || /scan.in.progress/i.test(msg)) {
-                consecutive503s++;
-                if (consecutive503s === 1) {
-                    console.warn('[jeeves-meta] Watcher scan still in progress — will retry on next refresh cycle.');
-                }
-                else {
-                    console.debug(`[jeeves-meta] Watcher scan still in progress (attempt ${String(consecutive503s)}) — suppressing repeated warnings.`);
-                }
-                return;
-            }
-            consecutive503s = 0;
-            console.warn('[jeeves-meta] Content fetch failed:', msg);
-        },
-    });
-    const descriptor = jeevesComponentDescriptorSchema.parse({
+/** Build the plugin-side component descriptor used by the standard toolset. */
+function buildDescriptor() {
+    return jeevesComponentDescriptorSchema.parse({
         name: META_COMPONENT.name,
         version: getPackageVersion(import.meta.url),
         servicePackage: META_COMPONENT.servicePackage,
         pluginPackage: META_COMPONENT.pluginPackage,
         defaultPort: META_COMPONENT.defaultPort,
-        // The runtime Zod custom validator only checks for a .parse() method.
-        // Use unknown cast to bridge the Zod v4 (service) → v3 (core SDK) type gap.
-        configSchema: { parse: (v) => v },
+        // The plugin never validates service config; the service descriptor does.
+        configSchema: z.unknown(),
         configFileName: 'config.json',
         initTemplate: () => ({}),
         startCommand: (configPath) => [
@@ -655,19 +574,22 @@ function register(api) {
             '-c',
             configPath,
         ],
-        // Plugin-side descriptor is only used by ComponentWriter for managed
-        // content. The real run callback lives in the service descriptor.
+        // The real run callback lives in the service descriptor.
         run: () => {
             return Promise.reject(new Error('run() is not available on the plugin-side descriptor'));
         },
-        sectionId: 'Meta',
-        refreshIntervalSeconds: 73,
-        generateToolsContent: getContent,
-        dependencies: { hard: ['watcher'], soft: [] },
     });
-    registerMetaTools(api, client, descriptor);
-    const writer = createComponentWriter(descriptor, { gatewayUrl });
-    writer.start();
+}
+/**
+ * Register all jeeves-meta tools with the OpenClaw plugin API.
+ *
+ * Always succeeds, even with no plugin config: `configRoot` is resolved
+ * lazily when a tool that needs it runs.
+ */
+function register(api) {
+    const client = new MetaServiceClient({ apiUrl: getServiceUrl(api) });
+    warnIfConfigRootMissing(api);
+    registerMetaTools(api, client, buildDescriptor(), createConfigRootGate(api));
 }
 
-export { register as default };
+export { register as default, pluginConfigSchema };

package/dist/rollup.config.d.ts

@@ -1,10 +1,9 @@
 /**
  * Rollup configuration for the OpenClaw plugin package.
- * Two entry points: plugin (ESM + declarations) and CLI (ESM executable).
+ * Single entry point: the plugin (ESM + declarations).
  *
- * Runtime dependencies (`@karmaniverous/jeeves`, `@karmaniverous/jeeves-meta`)
- * are externalized — the OpenClaw host environment provides them.
- * CLI bundles everything for standalone execution.
+ * Runtime dependencies (`@karmaniverous/jeeves`, `@karmaniverous/jeeves-meta-core`,
+ * `zod`) are externalized and resolved from the plugin's installed dependencies.
  */
 import type { RollupOptions } from 'rollup';
 declare const _default: RollupOptions[];