@karmaniverous/jeeves-meta-openclaw 0.1.0

package/dist/index.js

@@ -0,0 +1,1001 @@
+import { HttpWatcherClient, paginatedScan, isLocked, normalizePath, globMetas, buildOwnershipTree, findNode, ensureMetaJson, actualStaleness, computeEffectiveStaleness, selectCandidate, filterInScope, computeStructureHash, readLatestArchive, hasSteerChanged, isArchitectTriggered, loadSynthConfig } from '@karmaniverous/jeeves-meta';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+/**
+ * Shared types and utilities for the OpenClaw plugin.
+ *
+ * @module helpers
+ */
+const PLUGIN_NAME = 'jeeves-meta-openclaw';
+/** Get plugin config. */
+function getPluginConfig(api) {
+    return api.config?.plugins?.entries?.[PLUGIN_NAME]?.config;
+}
+/**
+ * Resolve the config file path.
+ *
+ * Resolution order:
+ * 1. Plugin config `configPath` setting
+ * 2. `JEEVES_META_CONFIG` environment variable
+ * 3. Error — no default path
+ */
+function getConfigPath(api) {
+    const fromPlugin = getPluginConfig(api)?.configPath;
+    if (typeof fromPlugin === 'string')
+        return fromPlugin;
+    const fromEnv = process.env['JEEVES_META_CONFIG'];
+    if (fromEnv)
+        return fromEnv;
+    throw new Error('jeeves-meta config path not found. Set configPath in plugin config or JEEVES_META_CONFIG env var.');
+}
+/** Format a successful tool result. */
+function ok(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+/** Format an error tool result. */
+function fail(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        content: [{ type: 'text', text: 'Error: ' + message }],
+        isError: true,
+    };
+}
+
+/**
+ * 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
+ */
+const SOURCE = 'jeeves-meta';
+/** Virtual rule definitions per spec Section 15. */
+const SYNTH_RULES = [
+    {
+        name: 'synth-meta-live',
+        description: 'Live jeeves-meta .meta/meta.json files',
+        match: {
+            properties: {
+                file: {
+                    properties: {
+                        path: { type: 'string', glob: '**/.meta/meta.json' },
+                    },
+                },
+            },
+        },
+        schema: [
+            'base',
+            {
+                properties: {
+                    domains: { set: ['synth-meta'] },
+                    synth_id: { type: 'string', set: '{{json._id}}' },
+                    synth_steer: { type: 'string', set: '{{json._steer}}' },
+                    synth_depth: { type: 'number', set: '{{json._depth}}' },
+                    synth_emphasis: { type: 'number', set: '{{json._emphasis}}' },
+                    synth_synthesis_count: {
+                        type: 'integer',
+                        set: '{{json._synthesisCount}}',
+                    },
+                    synth_structure_hash: {
+                        type: 'string',
+                        set: '{{json._structureHash}}',
+                    },
+                    synth_architect_tokens: {
+                        type: 'integer',
+                        set: '{{json._architectTokens}}',
+                    },
+                    synth_builder_tokens: {
+                        type: 'integer',
+                        set: '{{json._builderTokens}}',
+                    },
+                    synth_critic_tokens: {
+                        type: 'integer',
+                        set: '{{json._criticTokens}}',
+                    },
+                    synth_error_step: {
+                        type: 'string',
+                        set: '{{json._error.step}}',
+                    },
+                    generated_at_unix: {
+                        type: 'integer',
+                        set: '{{toUnix json._generatedAt}}',
+                        description: 'Synthesis timestamp as Unix seconds for range queries',
+                    },
+                    has_error: {
+                        type: 'boolean',
+                        set: '{{#if json._error}}true{{else}}false{{/if}}',
+                    },
+                },
+            },
+        ],
+        render: {
+            frontmatter: [
+                'synth_id',
+                'synth_steer',
+                'generated_at_unix',
+                'synth_depth',
+                'synth_emphasis',
+                'synth_architect_tokens',
+                'synth_builder_tokens',
+                'synth_critic_tokens',
+            ],
+            body: [
+                {
+                    path: 'json._content',
+                    heading: 1,
+                    label: 'Synthesis',
+                },
+            ],
+        },
+        renderAs: 'md',
+    },
+    {
+        name: 'synth-meta-archive',
+        description: 'Archived jeeves-meta .meta/archive snapshots',
+        match: {
+            properties: {
+                file: {
+                    properties: {
+                        path: { type: 'string', glob: '**/.meta/archive/*.json' },
+                    },
+                },
+            },
+        },
+        schema: [
+            'base',
+            {
+                properties: {
+                    domains: { set: ['synth-archive'] },
+                    synth_id: { type: 'string', set: '{{json._id}}' },
+                    archived: { type: 'boolean', set: 'true' },
+                    archived_at: { type: 'string', set: '{{json._archivedAt}}' },
+                },
+            },
+        ],
+        render: {
+            frontmatter: ['synth_id', 'archived', 'archived_at'],
+            body: [
+                {
+                    path: 'json._content',
+                    heading: 1,
+                    label: 'Synthesis (archived)',
+                },
+            ],
+        },
+        renderAs: 'md',
+    },
+    {
+        name: 'synth-config',
+        description: 'jeeves-meta configuration file',
+        match: {
+            properties: {
+                file: {
+                    properties: {
+                        path: { type: 'string', glob: '**/jeeves-meta.config.json' },
+                    },
+                },
+            },
+        },
+        schema: [
+            'base',
+            {
+                properties: {
+                    domains: { set: ['synth-config'] },
+                },
+            },
+        ],
+        render: {
+            frontmatter: [
+                'watchPaths',
+                'watcherUrl',
+                'gatewayUrl',
+                'architectEvery',
+                'depthWeight',
+                'maxArchive',
+                'maxLines',
+                'batchSize',
+            ],
+            body: [
+                {
+                    path: 'json.defaultArchitect',
+                    heading: 2,
+                    label: 'Default Architect Prompt',
+                },
+                {
+                    path: 'json.defaultCritic',
+                    heading: 2,
+                    label: 'Default Critic Prompt',
+                },
+            ],
+        },
+        renderAs: 'md',
+    },
+];
+/**
+ * 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.
+ */
+async function registerSynthRules(watcherUrl) {
+    const client = new HttpWatcherClient({ baseUrl: watcherUrl });
+    await client.registerRules(SOURCE, SYNTH_RULES);
+}
+
+/**
+ * Synth tool registrations for OpenClaw.
+ *
+ * @module tools
+ */
+/** Register all synth_* tools. */
+function registerSynthTools(api) {
+    const configPath = getConfigPath(api);
+    // Lazy-load config (resolved once on first use)
+    let _config = null;
+    const getConfig = () => {
+        if (!_config) {
+            _config = loadSynthConfig(configPath);
+        }
+        return _config;
+    };
+    /** Derive watcherUrl from loaded config. */
+    const getWatcherUrl = () => getConfig().watcherUrl;
+    /** Derive watchPaths from loaded config. */
+    const getWatchPaths = () => getConfig().watchPaths;
+    // ─── synth_list ──────────────────────────────────────────────
+    api.registerTool({
+        name: 'synth_list',
+        description: 'List metas with summary stats and per-meta projection. Replaces synth_status + synth_entities.',
+        parameters: {
+            type: 'object',
+            properties: {
+                pathPrefix: {
+                    type: 'string',
+                    description: 'Filter metas by path prefix (e.g. "github/").',
+                },
+                filter: {
+                    type: 'object',
+                    description: 'Structured filter. Supported keys: hasError (boolean), staleHours (number, min hours stale), neverSynthesized (boolean), locked (boolean).',
+                    properties: {
+                        hasError: { type: 'boolean' },
+                        staleHours: { type: 'number' },
+                        neverSynthesized: { type: 'boolean' },
+                        locked: { type: 'boolean' },
+                    },
+                },
+                fields: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Fields to include per meta. Default: path, depth, emphasis, stalenessSeconds, lastSynthesized, hasError, locked, architectTokens, builderTokens, criticTokens.',
+                },
+            },
+        },
+        execute: async (_id, params) => {
+            try {
+                const pathPrefix = params.pathPrefix;
+                const watcher = new HttpWatcherClient({ baseUrl: getWatcherUrl() });
+                // Query watcher for synth-meta domain points
+                const scanFiles = await paginatedScan(watcher, {
+                    ...(pathPrefix ? { pathPrefix } : {}),
+                    filter: {
+                        must: [{ key: 'domains', match: { value: 'synth-meta' } }],
+                    },
+                    fields: [
+                        'file_path',
+                        'synth_depth',
+                        'synth_emphasis',
+                        'synth_architect_tokens',
+                        'synth_builder_tokens',
+                        'synth_critic_tokens',
+                        'has_error',
+                        'generated_at_unix',
+                        'synth_error_step',
+                    ],
+                });
+                const entities = [];
+                let staleCount = 0;
+                let errorCount = 0;
+                let lockedCount = 0;
+                let neverSynthesizedCount = 0;
+                let totalArchTokens = 0;
+                let totalBuilderTokens = 0;
+                let totalCriticTokens = 0;
+                let lastSynthPath = null;
+                let lastSynthAt = null;
+                let stalestPath = null;
+                let stalestEffective = -1;
+                const config = getConfig();
+                for (const sf of scanFiles) {
+                    const filePath = sf.file_path;
+                    const depth = typeof sf['synth_depth'] === 'number' ? sf['synth_depth'] : 0;
+                    const emphasis = typeof sf['synth_emphasis'] === 'number' ? sf['synth_emphasis'] : 1;
+                    const hasError = sf['has_error'] === true || sf['has_error'] === 'true';
+                    const archTokens = typeof sf['synth_architect_tokens'] === 'number'
+                        ? sf['synth_architect_tokens']
+                        : 0;
+                    const buildTokens = typeof sf['synth_builder_tokens'] === 'number'
+                        ? sf['synth_builder_tokens']
+                        : 0;
+                    const critTokens = typeof sf['synth_critic_tokens'] === 'number'
+                        ? sf['synth_critic_tokens']
+                        : 0;
+                    const genAtUnix = typeof sf['generated_at_unix'] === 'number'
+                        ? sf['generated_at_unix']
+                        : 0;
+                    const locked = isLocked(normalizePath(filePath));
+                    const neverSynth = genAtUnix === 0;
+                    // Compute staleness from generated_at_unix
+                    let stalenessSeconds;
+                    if (neverSynth) {
+                        stalenessSeconds = Infinity;
+                    }
+                    else {
+                        stalenessSeconds = Math.floor(Date.now() / 1000) - genAtUnix;
+                        if (stalenessSeconds < 0)
+                            stalenessSeconds = 0;
+                    }
+                    // Apply structured filter
+                    const filter = params.filter;
+                    if (filter) {
+                        if (filter.hasError !== undefined && hasError !== filter.hasError)
+                            continue;
+                        if (filter.neverSynthesized !== undefined &&
+                            neverSynth !== filter.neverSynthesized)
+                            continue;
+                        if (filter.locked !== undefined && locked !== filter.locked)
+                            continue;
+                        if (typeof filter.staleHours === 'number' &&
+                            stalenessSeconds < filter.staleHours * 3600)
+                            continue;
+                    }
+                    if (stalenessSeconds > 0)
+                        staleCount++;
+                    if (hasError)
+                        errorCount++;
+                    if (locked)
+                        lockedCount++;
+                    if (neverSynth)
+                        neverSynthesizedCount++;
+                    if (archTokens > 0)
+                        totalArchTokens += archTokens;
+                    if (buildTokens > 0)
+                        totalBuilderTokens += buildTokens;
+                    if (critTokens > 0)
+                        totalCriticTokens += critTokens;
+                    const genAtIso = genAtUnix > 0 ? new Date(genAtUnix * 1000).toISOString() : null;
+                    if (genAtIso && (!lastSynthAt || genAtIso > lastSynthAt)) {
+                        lastSynthAt = genAtIso;
+                        lastSynthPath = filePath;
+                    }
+                    // Effective staleness for stalest computation
+                    const depthFactor = Math.pow(1 + config.depthWeight, depth);
+                    const effectiveStaleness = (stalenessSeconds === Infinity
+                        ? Number.MAX_SAFE_INTEGER
+                        : stalenessSeconds) *
+                        depthFactor *
+                        emphasis;
+                    if (effectiveStaleness > stalestEffective) {
+                        stalestEffective = effectiveStaleness;
+                        stalestPath = filePath;
+                    }
+                    // Derive meta path from file_path (strip /meta.json)
+                    const metaPath = filePath.replace(/\/meta\.json$/, '');
+                    const fields = params.fields;
+                    const raw = {
+                        path: metaPath,
+                        depth,
+                        emphasis,
+                        stalenessSeconds: stalenessSeconds === Infinity
+                            ? 'never-synthesized'
+                            : Math.round(stalenessSeconds),
+                        lastSynthesized: genAtIso,
+                        hasError,
+                        locked,
+                        architectTokens: archTokens > 0 ? archTokens : null,
+                        builderTokens: buildTokens > 0 ? buildTokens : null,
+                        criticTokens: critTokens > 0 ? critTokens : null,
+                        children: 0,
+                    };
+                    if (fields) {
+                        const projected = {};
+                        for (const f of fields) {
+                            if (f in raw)
+                                projected[f] = raw[f];
+                        }
+                        entities.push(projected);
+                    }
+                    else {
+                        entities.push(raw);
+                    }
+                }
+                return ok({
+                    summary: {
+                        total: entities.length,
+                        stale: staleCount,
+                        errors: errorCount,
+                        locked: lockedCount,
+                        neverSynthesized: neverSynthesizedCount,
+                        tokens: {
+                            architect: totalArchTokens,
+                            builder: totalBuilderTokens,
+                            critic: totalCriticTokens,
+                        },
+                        stalestPath,
+                        lastSynthesizedPath: lastSynthPath,
+                        lastSynthesizedAt: lastSynthAt,
+                    },
+                    items: entities.sort((a, b) => String(a.path ?? '').localeCompare(String(b.path ?? ''))),
+                });
+            }
+            catch (error) {
+                return fail(error);
+            }
+        },
+    });
+    // ─── synth_detail ────────────────────────────────────────────
+    api.registerTool({
+        name: 'synth_detail',
+        description: 'Full detail for a single meta, with optional archive history.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Path to .meta/ directory or owner directory (required).',
+                },
+                fields: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Fields to include. Default: all except _architect, _builder, _critic, _content, _feedback.',
+                },
+                includeArchive: {
+                    oneOf: [{ type: 'boolean' }, { type: 'number' }],
+                    description: 'false (default), true (all snapshots), or number (N most recent).',
+                },
+            },
+            required: ['path'],
+        },
+        execute: async (_id, params) => {
+            try {
+                const targetPath = normalizePath(params.path);
+                const includeArchive = params.includeArchive;
+                const defaultExclude = new Set([
+                    '_architect',
+                    '_builder',
+                    '_critic',
+                    '_content',
+                    '_feedback',
+                ]);
+                const fields = params.fields;
+                const metaPaths = globMetas(getWatchPaths());
+                const tree = buildOwnershipTree(metaPaths);
+                const targetNode = findNode(tree, targetPath);
+                if (!targetNode) {
+                    return fail('Meta path not found: ' + targetPath);
+                }
+                const meta = ensureMetaJson(targetNode.metaPath);
+                // Apply field projection
+                const projectMeta = (m) => {
+                    if (fields) {
+                        const result = {};
+                        for (const f of fields)
+                            result[f] = m[f];
+                        return result;
+                    }
+                    // Default: exclude big text blobs
+                    const result = {};
+                    for (const [k, v] of Object.entries(m)) {
+                        if (!defaultExclude.has(k))
+                            result[k] = v;
+                    }
+                    return result;
+                };
+                const response = {
+                    meta: projectMeta(meta),
+                };
+                // Archive history
+                if (includeArchive) {
+                    const { readFileSync } = await import('node:fs');
+                    const { join } = await import('node:path');
+                    const { listArchiveFiles } = await import('@karmaniverous/jeeves-meta');
+                    const archiveFiles = listArchiveFiles(targetNode.metaPath);
+                    const limit = typeof includeArchive === 'number'
+                        ? includeArchive
+                        : archiveFiles.length;
+                    // Most recent first (files are sorted by timestamp)
+                    const selected = archiveFiles.slice(-limit).reverse();
+                    const archives = selected.map((af) => {
+                        const raw = readFileSync(join(targetNode.metaPath, 'archive', af), 'utf8');
+                        const parsed = JSON.parse(raw);
+                        return projectMeta(parsed);
+                    });
+                    response.archive = archives;
+                }
+                return ok(response);
+            }
+            catch (error) {
+                return fail(error);
+            }
+        },
+    });
+    // ─── synth_preview ────────────────────────────────────────────
+    api.registerTool({
+        name: 'synth_preview',
+        description: 'Dry-run: show what inputs would be gathered for the next synthesis cycle without running LLM.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Optional: specific .meta/ path to preview. If omitted, previews the stalest candidate.',
+                },
+            },
+        },
+        execute: async (_id, params) => {
+            try {
+                const targetPath = params.path;
+                const metaPaths = globMetas(getWatchPaths());
+                const tree = buildOwnershipTree(metaPaths);
+                let targetNode;
+                if (targetPath) {
+                    const normalized = normalizePath(targetPath);
+                    targetNode = findNode(tree, normalized);
+                    if (!targetNode) {
+                        return fail('Meta path not found: ' + targetPath);
+                    }
+                }
+                else {
+                    // Select stalest
+                    const candidates = [];
+                    for (const node of tree.nodes.values()) {
+                        const meta = ensureMetaJson(node.metaPath);
+                        const staleness = actualStaleness(meta);
+                        if (staleness > 0) {
+                            candidates.push({ node, meta, actualStaleness: staleness });
+                        }
+                    }
+                    const weighted = computeEffectiveStaleness(candidates, getConfig().depthWeight);
+                    const winner = selectCandidate(weighted);
+                    if (!winner) {
+                        return ok({
+                            message: 'No stale metas found. Nothing to synthesize.',
+                        });
+                    }
+                    targetNode = winner.node;
+                }
+                const meta = ensureMetaJson(targetNode.metaPath);
+                const watcher = new HttpWatcherClient({ baseUrl: getWatcherUrl() });
+                // Scope files (paginated for completeness)
+                const allScanFiles = await paginatedScan(watcher, {
+                    pathPrefix: targetNode.ownerPath,
+                });
+                const allFiles = allScanFiles.map((f) => f.file_path);
+                const scopeFiles = filterInScope(targetNode, allFiles);
+                // Structure hash on scope-filtered files (matches orchestrator)
+                const structureHash = computeStructureHash(scopeFiles);
+                const structureChanged = structureHash !== meta._structureHash;
+                // Steer change
+                const latestArchive = readLatestArchive(targetNode.metaPath);
+                const steerChanged = hasSteerChanged(meta._steer, latestArchive?._steer, Boolean(latestArchive));
+                // Architect trigger check
+                const architectTriggered = isArchitectTriggered(meta, structureChanged, steerChanged, getConfig().architectEvery);
+                // Delta files
+                let deltaFiles = [];
+                if (meta._generatedAt) {
+                    const modifiedAfter = Math.floor(new Date(meta._generatedAt).getTime() / 1000);
+                    const deltaScanFiles = await paginatedScan(watcher, {
+                        pathPrefix: targetNode.ownerPath,
+                        modifiedAfter,
+                    });
+                    deltaFiles = filterInScope(targetNode, deltaScanFiles.map((f) => f.file_path));
+                }
+                else {
+                    deltaFiles = scopeFiles;
+                }
+                return ok({
+                    target: targetNode.metaPath,
+                    ownerPath: targetNode.ownerPath,
+                    depth: meta._depth ?? targetNode.treeDepth,
+                    staleness: actualStaleness(meta) === Infinity
+                        ? 'never-synthesized'
+                        : Math.round(actualStaleness(meta)).toString() + 's',
+                    scopeFiles: {
+                        count: scopeFiles.length,
+                        sample: scopeFiles.slice(0, 20),
+                    },
+                    deltaFiles: {
+                        count: deltaFiles.length,
+                        sample: deltaFiles.slice(0, 20),
+                    },
+                    structureChanged,
+                    steerChanged,
+                    architectTriggered,
+                    architectTriggerReasons: [
+                        ...(!meta._builder ? ['no cached builder (first run)'] : []),
+                        ...(structureChanged ? ['structure changed'] : []),
+                        ...(steerChanged ? ['steer changed'] : []),
+                        ...((meta._synthesisCount ?? 0) >= getConfig().architectEvery
+                            ? ['periodic refresh (architectEvery)']
+                            : []),
+                    ],
+                    currentSteer: meta._steer ?? null,
+                    hasExistingContent: Boolean(meta._content),
+                    hasExistingFeedback: Boolean(meta._feedback),
+                    children: targetNode.children.map((c) => c.metaPath),
+                });
+            }
+            catch (error) {
+                return fail(error);
+            }
+        },
+    });
+    // ─── synth_trigger ────────────────────────────────────────────
+    api.registerTool({
+        name: 'synth_trigger',
+        description: 'Manually trigger synthesis for a specific meta or the next-stalest candidate. Runs the full 3-step cycle (architect, builder, critic).',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Optional: specific .meta/ or owner path to synthesize. If omitted, synthesizes the stalest candidate.',
+                },
+            },
+        },
+        execute: async (_id, params) => {
+            try {
+                const { orchestrate } = await import('@karmaniverous/jeeves-meta');
+                const { GatewayExecutor } = await import('@karmaniverous/jeeves-meta');
+                // Load config from canonical config file
+                const config = getConfig();
+                const executor = new GatewayExecutor({
+                    gatewayUrl: config.gatewayUrl,
+                    apiKey: config.gatewayApiKey,
+                });
+                const watcher = new HttpWatcherClient({ baseUrl: getWatcherUrl() });
+                // If path specified, temporarily override watchPaths to target it
+                const targetPath = params.path;
+                const effectiveConfig = targetPath
+                    ? {
+                        ...config,
+                        watchPaths: [targetPath.replace(/[/\\]\.meta[/\\]?$/, '')],
+                    }
+                    : config;
+                const results = await orchestrate(effectiveConfig, executor, watcher);
+                const synthesized = results.filter((r) => r.synthesized);
+                if (synthesized.length === 0) {
+                    return ok({
+                        message: 'No synthesis performed — no stale metas found or all locked.',
+                    });
+                }
+                return ok({
+                    synthesizedCount: synthesized.length,
+                    results: synthesized.map((r) => ({
+                        metaPath: r.metaPath,
+                        error: r.error ?? null,
+                    })),
+                    message: synthesized.length.toString() +
+                        ' meta(s) synthesized.' +
+                        (synthesized.some((r) => r.error)
+                            ? ' Some completed with errors.'
+                            : ''),
+                });
+            }
+            catch (error) {
+                return fail(error);
+            }
+        },
+    });
+}
+
+/**
+ * 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.
+ */
+async function generateMetaMenu(watcherUrl) {
+    let entities = [];
+    try {
+        const watcher = new HttpWatcherClient({ baseUrl: watcherUrl });
+        entities = await paginatedScan(watcher, {
+            filter: {
+                must: [
+                    {
+                        key: 'domains',
+                        match: { value: 'synth-meta' },
+                    },
+                ],
+            },
+            fields: [
+                'synth_depth',
+                'synth_emphasis',
+                'synth_synthesis_count',
+                'synth_architect_tokens',
+                'synth_builder_tokens',
+                'synth_critic_tokens',
+                'synth_error_step',
+                'generated_at_unix',
+                'has_error',
+            ],
+        });
+    }
+    catch {
+        return [
+            '> **ACTION REQUIRED: jeeves-watcher is unreachable.**',
+            '> The jeeves-meta synthesis engine requires a running jeeves-watcher service.',
+            `> The watcher API at ${watcherUrl} is down or not configured.`,
+            '>',
+            "> **Read the `jeeves-meta` skill's Bootstrap section immediately**",
+            '> for setup instructions. Do not attempt synthesis until watcher is available.',
+        ].join('\n');
+    }
+    if (entities.length === 0) {
+        return [
+            '> **ACTION REQUIRED: No synthesis entities found.**',
+            '> The watcher is running but no `.meta/` directories were discovered',
+            '> in the configured watch paths.',
+            '>',
+            "> **Read the `jeeves-meta` skill's Bootstrap section** for guidance",
+            '> on creating `.meta/` directories and configuring watch paths.',
+        ].join('\n');
+    }
+    // Compute stats
+    const now = Math.floor(Date.now() / 1000);
+    let staleCount = 0;
+    let errorCount = 0;
+    let neverSynthesized = 0;
+    let totalArchTokens = 0;
+    let totalBuilderTokens = 0;
+    let totalCriticTokens = 0;
+    let stalestPath = '';
+    let stalestAge = 0;
+    let lastSynthPath = '';
+    let lastSynthUnix = 0;
+    for (const e of entities) {
+        const generatedAt = e['generated_at_unix'];
+        const hasError = e['has_error'];
+        const archTokens = e['synth_architect_tokens'];
+        const builderTokens = e['synth_builder_tokens'];
+        const criticTokens = e['synth_critic_tokens'];
+        if (!generatedAt) {
+            neverSynthesized++;
+            staleCount++;
+            if (!isFinite(stalestAge)) ;
+            else {
+                stalestAge = Infinity;
+                stalestPath = e.file_path;
+            }
+        }
+        else {
+            const age = now - generatedAt;
+            if (age > 0)
+                staleCount++;
+            if (age > stalestAge && isFinite(age)) {
+                stalestAge = age;
+                stalestPath = e.file_path;
+            }
+            if (generatedAt > lastSynthUnix) {
+                lastSynthUnix = generatedAt;
+                lastSynthPath = e.file_path;
+            }
+        }
+        if (hasError)
+            errorCount++;
+        if (archTokens)
+            totalArchTokens += archTokens;
+        if (builderTokens)
+            totalBuilderTokens += builderTokens;
+        if (criticTokens)
+            totalCriticTokens += criticTokens;
+    }
+    const formatAge = (seconds) => {
+        if (!isFinite(seconds))
+            return 'never synthesized';
+        if (seconds < 3600)
+            return Math.round(seconds / 60).toString() + 'm';
+        if (seconds < 86400)
+            return Math.round(seconds / 3600).toString() + 'h';
+        return Math.round(seconds / 86400).toString() + 'd';
+    };
+    const lines = [
+        `The jeeves-meta synthesis engine manages ${entities.length.toString()} meta entities.`,
+        '',
+        '### Entity Summary',
+        '| Metric | Value |',
+        '|--------|-------|',
+        `| Total | ${entities.length.toString()} |`,
+        `| Stale | ${staleCount.toString()} |`,
+        `| Errors | ${errorCount.toString()} |`,
+        `| Never synthesized | ${neverSynthesized.toString()} |`,
+        `| Stalest | ${stalestPath ? stalestPath + ' (' + formatAge(stalestAge) + ')' : 'n/a'} |`,
+        `| Last synthesized | ${lastSynthPath ? lastSynthPath + ' (' + new Date(lastSynthUnix * 1000).toISOString() + ')' : 'n/a'} |`,
+        '',
+        '### Token Usage (cumulative)',
+        '| Step | Tokens |',
+        '|------|--------|',
+        `| Architect | ${totalArchTokens.toLocaleString()} |`,
+        `| Builder | ${totalBuilderTokens.toLocaleString()} |`,
+        `| Critic | ${totalCriticTokens.toLocaleString()} |`,
+        '',
+        '### Tools',
+        '| Tool | Description |',
+        '|------|-------------|',
+        '| `synth_list` | List metas with summary stats and per-meta projection |',
+        '| `synth_detail` | Full detail for a single meta with optional archive history |',
+        '| `synth_trigger` | Manually trigger synthesis for a specific meta or next-stalest |',
+        '| `synth_preview` | Dry-run: show what inputs would be gathered without running LLM |',
+        '',
+        'Read the `jeeves-meta` skill for usage guidance, configuration, and troubleshooting.',
+    ];
+    return lines.join('\n');
+}
+
+/**
+ * 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
+ */
+const REFRESH_INTERVAL_MS = 60_000;
+const INITIAL_DELAY_MS = 5_000;
+let intervalHandle = null;
+let lastWrittenMenu = '';
+/**
+ * Resolve the workspace TOOLS.md path.
+ * Uses api.resolvePath if available, otherwise falls back to CWD.
+ */
+function resolveToolsPath(api) {
+    const resolvePath = api
+        .resolvePath;
+    if (typeof resolvePath === 'function') {
+        return resolvePath('TOOLS.md');
+    }
+    return resolve(process.cwd(), 'TOOLS.md');
+}
+/**
+ * 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.
+ */
+function upsertMetaSection(existing, metaMenu) {
+    const section = '## Meta\n\n' + metaMenu;
+    // Replace existing Meta section (match from ## Meta to next ## or # or EOF)
+    const re = /^## Meta\n[\s\S]*?(?=\n## |\n# |$(?![\s\S]))/m;
+    if (re.test(existing)) {
+        return existing.replace(re, section);
+    }
+    // No existing section. Insert in correct order.
+    const platformH1 = '# Jeeves Platform Tools';
+    // After ## Server if present
+    const serverRe = /^## Server\n[\s\S]*?(?=\n## |\n# |$(?![\s\S]))/m;
+    const serverMatch = serverRe.exec(existing);
+    if (serverMatch) {
+        const insertAt = serverMatch.index + serverMatch[0].length;
+        return (existing.slice(0, insertAt) + '\n\n' + section + existing.slice(insertAt));
+    }
+    // After ## Watcher if present
+    const watcherRe = /^## Watcher\n[\s\S]*?(?=\n## |\n# |$(?![\s\S]))/m;
+    const watcherMatch = watcherRe.exec(existing);
+    if (watcherMatch) {
+        const insertAt = watcherMatch.index + watcherMatch[0].length;
+        return (existing.slice(0, insertAt) + '\n\n' + section + existing.slice(insertAt));
+    }
+    // After H1 if present
+    if (existing.includes(platformH1)) {
+        const idx = existing.indexOf(platformH1) + platformH1.length;
+        return (existing.slice(0, idx) + '\n\n' + section + '\n' + existing.slice(idx));
+    }
+    // Prepend platform header + meta section
+    const trimmed = existing.trim();
+    if (trimmed.length === 0) {
+        return platformH1 + '\n\n' + section + '\n';
+    }
+    return platformH1 + '\n\n' + section + '\n\n' + trimmed + '\n';
+}
+/**
+ * Fetch the current meta menu and write it to TOOLS.md if changed.
+ *
+ * @param api - Plugin API.
+ * @param watcherUrl - Watcher API base URL.
+ * @returns True if the file was updated.
+ */
+async function refreshToolsMd(api, watcherUrl) {
+    const menu = await generateMetaMenu(watcherUrl);
+    if (menu === lastWrittenMenu) {
+        return false;
+    }
+    const toolsPath = resolveToolsPath(api);
+    let current = '';
+    try {
+        current = await readFile(toolsPath, 'utf8');
+    }
+    catch {
+        // File doesn't exist yet
+    }
+    const updated = upsertMetaSection(current, menu);
+    if (updated !== current) {
+        await writeFile(toolsPath, updated, 'utf8');
+        lastWrittenMenu = menu;
+        return true;
+    }
+    lastWrittenMenu = menu;
+    return false;
+}
+/**
+ * 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.
+ */
+function startToolsWriter(api, watcherUrl) {
+    // Deferred initial write
+    setTimeout(() => {
+        refreshToolsMd(api, watcherUrl).catch((err) => {
+            console.error('[jeeves-meta] Failed to write TOOLS.md:', err);
+        });
+    }, INITIAL_DELAY_MS);
+    // Periodic refresh
+    if (intervalHandle) {
+        clearInterval(intervalHandle);
+    }
+    intervalHandle = setInterval(() => {
+        refreshToolsMd(api, watcherUrl).catch((err) => {
+            console.error('[jeeves-meta] Failed to refresh TOOLS.md:', err);
+        });
+    }, REFRESH_INTERVAL_MS);
+    if (typeof intervalHandle === 'object' && 'unref' in intervalHandle) {
+        intervalHandle.unref();
+    }
+}
+
+/**
+ * OpenClaw plugin for jeeves-meta.
+ *
+ * Registers synthesis tools, virtual inference rules, and starts
+ * the periodic TOOLS.md writer at gateway startup.
+ *
+ * @packageDocumentation
+ */
+/** Register all jeeves-meta tools and rules with the OpenClaw plugin API. */
+function register(api) {
+    registerSynthTools(api);
+    // Load config for rule registration and tools writer
+    const config = loadSynthConfig(getConfigPath(api));
+    // Register virtual rules with watcher (fire-and-forget at startup)
+    registerSynthRules(config.watcherUrl).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error('[jeeves-meta] Failed to register virtual rules:', message);
+    });
+    // Start periodic TOOLS.md writer
+    startToolsWriter(api, config.watcherUrl);
+}
+
+export { register as default };