@karmaniverous/jeeves-server-openclaw 0.1.0-0

package/dist/cli.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+import { existsSync, rmSync, mkdirSync, cpSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * CLI for installing/uninstalling the jeeves-server OpenClaw plugin.
+ *
+ * Usage:
+ *   npx \@karmaniverous/jeeves-server-openclaw install
+ *   npx \@karmaniverous/jeeves-server-openclaw uninstall
+ */
+const PLUGIN_ID = 'jeeves-server-openclaw';
+function resolveOpenClawHome() {
+    if (process.env.OPENCLAW_CONFIG)
+        return dirname(resolve(process.env.OPENCLAW_CONFIG));
+    if (process.env.OPENCLAW_HOME)
+        return resolve(process.env.OPENCLAW_HOME);
+    return join(homedir(), '.openclaw');
+}
+function resolveConfigPath(home) {
+    if (process.env.OPENCLAW_CONFIG)
+        return resolve(process.env.OPENCLAW_CONFIG);
+    return join(home, 'openclaw.json');
+}
+function getPackageRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), '..');
+}
+function readJson(p) {
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeJson(p, data) {
+    writeFileSync(p, JSON.stringify(data, null, 2) + '\n');
+}
+function patchAllowList(parent, key, label, mode) {
+    if (!Array.isArray(parent[key]) || parent[key].length === 0)
+        return undefined;
+    const list = parent[key];
+    if (mode === 'add') {
+        if (!list.includes(PLUGIN_ID)) {
+            list.push(PLUGIN_ID);
+            return 'Added "' + PLUGIN_ID + '" to ' + label;
+        }
+    }
+    else {
+        const filtered = list.filter((id) => id !== PLUGIN_ID);
+        if (filtered.length !== list.length) {
+            parent[key] = filtered;
+            return 'Removed "' + PLUGIN_ID + '" from ' + label;
+        }
+    }
+    return undefined;
+}
+function patchConfig(config, mode) {
+    const messages = [];
+    if (!config.plugins || typeof config.plugins !== 'object')
+        config.plugins = {};
+    const plugins = config.plugins;
+    const pluginAllow = patchAllowList(plugins, 'allow', 'plugins.allow', mode);
+    if (pluginAllow)
+        messages.push(pluginAllow);
+    if (!plugins.entries || typeof plugins.entries !== 'object')
+        plugins.entries = {};
+    const entries = plugins.entries;
+    if (mode === 'add') {
+        if (!entries[PLUGIN_ID]) {
+            entries[PLUGIN_ID] = { enabled: true };
+            messages.push('Added "' + PLUGIN_ID + '" to plugins.entries');
+        }
+    }
+    else if (PLUGIN_ID in entries) {
+        Reflect.deleteProperty(entries, PLUGIN_ID);
+        messages.push('Removed "' + PLUGIN_ID + '" from plugins.entries');
+    }
+    if (!config.tools || typeof config.tools !== 'object')
+        config.tools = {};
+    const tools = config.tools;
+    const toolAllow = patchAllowList(tools, 'allow', 'tools.allow', mode);
+    if (toolAllow)
+        messages.push(toolAllow);
+    return messages;
+}
+function install() {
+    const home = resolveOpenClawHome();
+    const configPath = resolveConfigPath(home);
+    const extDir = join(home, 'extensions', PLUGIN_ID);
+    const pkgRoot = getPackageRoot();
+    console.log('OpenClaw home:  ' + home);
+    console.log('Config:         ' + configPath);
+    console.log('Extensions dir: ' + extDir);
+    console.log('Package root:   ' + pkgRoot);
+    console.log();
+    if (!existsSync(home)) {
+        console.error('Error: OpenClaw home not found at ' + home);
+        process.exit(1);
+    }
+    if (!existsSync(configPath)) {
+        console.error('Error: OpenClaw config not found at ' + configPath);
+        process.exit(1);
+    }
+    console.log('Copying plugin to extensions directory...');
+    if (existsSync(extDir))
+        rmSync(extDir, { recursive: true, force: true });
+    mkdirSync(extDir, { recursive: true });
+    for (const file of ['dist', 'openclaw.plugin.json', 'package.json']) {
+        const src = join(pkgRoot, file);
+        const dest = join(extDir, file);
+        if (existsSync(src)) {
+            cpSync(src, dest, { recursive: true });
+            console.log('  \u2713 ' + file);
+        }
+    }
+    const nodeModulesSrc = join(pkgRoot, 'node_modules');
+    if (existsSync(nodeModulesSrc)) {
+        cpSync(nodeModulesSrc, join(extDir, 'node_modules'), { recursive: true });
+        console.log('  \u2713 node_modules');
+    }
+    console.log();
+    console.log('Patching OpenClaw config...');
+    const config = readJson(configPath);
+    if (!config) {
+        console.error('Error: Could not parse ' + configPath);
+        process.exit(1);
+    }
+    for (const msg of patchConfig(config, 'add'))
+        console.log('  \u2713 ' + msg);
+    writeJson(configPath, config);
+    console.log();
+    console.log('\u2705 Plugin installed successfully.');
+    console.log('   Restart the OpenClaw gateway to load the plugin.');
+}
+function uninstall() {
+    const home = resolveOpenClawHome();
+    const configPath = resolveConfigPath(home);
+    const extDir = join(home, 'extensions', PLUGIN_ID);
+    console.log('OpenClaw home:  ' + home);
+    console.log('Config:         ' + configPath);
+    console.log('Extensions dir: ' + extDir);
+    console.log();
+    if (existsSync(extDir)) {
+        rmSync(extDir, { recursive: true, force: true });
+        console.log('\u2713 Removed ' + extDir);
+    }
+    else
+        console.log('  (extensions directory not found, skipping)');
+    if (existsSync(configPath)) {
+        console.log('Patching OpenClaw config...');
+        const config = readJson(configPath);
+        if (config) {
+            for (const msg of patchConfig(config, 'remove'))
+                console.log('  \u2713 ' + msg);
+            writeJson(configPath, config);
+        }
+    }
+    // Clean up TOOLS.md server section
+    cleanupToolsMd(home, configPath);
+    console.log();
+    console.log('\u2705 Plugin uninstalled successfully.');
+    console.log('   Restart the OpenClaw gateway to complete removal.');
+}
+function resolveWorkspaceDir(home, configPath) {
+    const config = readJson(configPath);
+    if (!config)
+        return null;
+    const agents = config.agents;
+    const defaults = agents?.defaults;
+    const workspace = defaults?.workspace;
+    if (workspace)
+        return resolve(workspace.replace(/^~/, homedir()));
+    return join(home, 'workspace');
+}
+function cleanupToolsMd(home, configPath) {
+    const workspaceDir = resolveWorkspaceDir(home, configPath);
+    if (!workspaceDir)
+        return;
+    const toolsPath = join(workspaceDir, 'TOOLS.md');
+    if (!existsSync(toolsPath))
+        return;
+    let content = readFileSync(toolsPath, 'utf8');
+    const serverRe = /^## Server\n[\s\S]*?(?=\n## |\n# |$(?![\s\S]))/m;
+    if (!serverRe.test(content))
+        return;
+    content = content.replace(serverRe, '').replace(/\n{3,}/g, '\n\n');
+    content = content.trim() + '\n';
+    writeFileSync(toolsPath, content);
+    console.log('\u2713 Cleaned up TOOLS.md (removed Server section)');
+}
+const command = process.argv[2];
+switch (command) {
+    case 'install':
+        install();
+        break;
+    case 'uninstall':
+        uninstall();
+        break;
+    default:
+        console.log('@karmaniverous/jeeves-server-openclaw \u2014 OpenClaw plugin installer');
+        console.log();
+        console.log('Usage:');
+        console.log('  npx @karmaniverous/jeeves-server-openclaw install    Install plugin');
+        console.log('  npx @karmaniverous/jeeves-server-openclaw uninstall  Remove plugin');
+        console.log();
+        console.log('Environment variables:');
+        console.log('  OPENCLAW_CONFIG  Path to openclaw.json (overrides all)');
+        console.log('  OPENCLAW_HOME    Path to .openclaw directory');
+        if (command &&
+            command !== 'help' &&
+            command !== '--help' &&
+            command !== '-h') {
+            console.error('\nUnknown command: ' + command);
+            process.exit(1);
+        }
+        break;
+}
+
+export { patchConfig };

package/dist/index.js

@@ -0,0 +1,416 @@
+import { createHmac } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+/**
+ * Shared types and utility functions for the OpenClaw plugin tool registrations.
+ */
+const DEFAULT_API_URL = 'http://127.0.0.1:1934';
+const PLUGIN_ID = 'jeeves-server-openclaw';
+/** Extract plugin config from the API object */
+function getPluginConfig(api) {
+    return api.config?.plugins?.entries?.[PLUGIN_ID]?.config;
+}
+/** Resolve the server API base URL from plugin config. */
+function getApiUrl(api) {
+    const url = getPluginConfig(api)?.apiUrl;
+    return typeof url === 'string' ? url : DEFAULT_API_URL;
+}
+/** Resolve the plugin key seed from plugin config. */
+function getPluginKey(api) {
+    const key = getPluginConfig(api)?.pluginKey;
+    return typeof key === 'string' ? key : undefined;
+}
+/** Derive HMAC key from seed. */
+function deriveKey(seed) {
+    return createHmac('sha256', seed).update('insider').digest('hex');
+}
+/** Append auth key query param to a URL. */
+function withAuth(url, keySeed) {
+    if (!keySeed)
+        return url;
+    const derived = deriveKey(keySeed);
+    const sep = url.includes('?') ? '&' : '?';
+    return url + sep + 'key=' + derived;
+}
+/** 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,
+    };
+}
+/** Format a connection error with actionable guidance. */
+function connectionFail(error, baseUrl) {
+    const cause = error instanceof Error ? error.cause : undefined;
+    const code = cause && typeof cause === 'object' && 'code' in cause
+        ? String(cause.code)
+        : '';
+    const isConnectionError = code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'ETIMEDOUT';
+    if (isConnectionError) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: [
+                        'Server not reachable at ' + baseUrl + '.',
+                        'Either start the jeeves-server service, or if it runs on a different port,',
+                        'set plugins.entries.jeeves-server-openclaw.config.apiUrl in openclaw.json.',
+                    ].join('\n'),
+                },
+            ],
+            isError: true,
+        };
+    }
+    return fail(error);
+}
+/** Fetch JSON from a URL, throwing on non-OK responses. */
+async function fetchJson(url, init) {
+    const res = await fetch(url, init);
+    if (!res.ok) {
+        throw new Error('HTTP ' + String(res.status) + ': ' + (await res.text()));
+    }
+    return res.json();
+}
+
+/**
+ * Server tool registrations (server_* tools) for the OpenClaw plugin.
+ */
+/** Normalize a browse path param: strip leading slash. */
+function normalizePath(params) {
+    return String(params.path).replace(/^\//, '');
+}
+/** Register a single API tool with standard try/catch + ok/connectionFail. */
+function registerApiTool(api, baseUrl, keySeed, config) {
+    api.registerTool({
+        name: config.name,
+        description: config.description,
+        parameters: config.parameters,
+        execute: async (_id, params) => {
+            try {
+                const [endpoint, method, body] = config.buildRequest(params);
+                const url = withAuth(baseUrl + endpoint, keySeed);
+                const init = {};
+                if (method)
+                    init.method = method;
+                if (body !== undefined) {
+                    init.method = method ?? 'POST';
+                    init.headers = { 'Content-Type': 'application/json' };
+                    init.body = JSON.stringify(body);
+                }
+                const data = await fetchJson(url, Object.keys(init).length > 0 ? init : undefined);
+                return ok(data);
+            }
+            catch (error) {
+                return connectionFail(error, baseUrl);
+            }
+        },
+    }, { optional: true });
+}
+/** Register all server_* tools with the OpenClaw plugin API. */
+function registerServerTools(api, baseUrl) {
+    const keySeed = getPluginKey(api);
+    const tools = [
+        {
+            name: 'server_status',
+            description: 'Get jeeves-server health: version, uptime, port, Chrome availability, export formats, connected services.',
+            parameters: { type: 'object', properties: {} },
+            buildRequest: () => ['/api/status'],
+        },
+        {
+            name: 'server_link_info',
+            description: 'Query available link types for a path (exists, page URL, raw URL, export links for PDF/DOCX/SVG/PNG).',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'Browse path (e.g. "j/domains/projects/readme.md")',
+                    },
+                },
+                required: ['path'],
+            },
+            buildRequest: (params) => {
+                const p = normalizePath(params);
+                return ['/api/link-info/' + p];
+            },
+        },
+        {
+            name: 'server_browse',
+            description: 'Get file or directory metadata. For files: size, mtime, content type, rendered HTML availability. For directories: listing of entries.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'Browse path (e.g. "j/domains/projects")',
+                    },
+                },
+                required: ['path'],
+            },
+            buildRequest: (params) => {
+                const p = normalizePath(params);
+                return ['/api/directory/' + p];
+            },
+        },
+        {
+            name: 'server_share',
+            description: 'Generate a share link for a path. Returns an HMAC-signed URL with optional expiry and directory depth.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'Browse path to share',
+                    },
+                    expiryDays: {
+                        type: 'number',
+                        description: 'Link expiry in days (default: 30)',
+                    },
+                    depth: {
+                        type: 'number',
+                        description: 'Directory depth for deep shares (0 = file only)',
+                    },
+                },
+                required: ['path'],
+            },
+            buildRequest: (params) => {
+                const p = normalizePath(params);
+                const qs = [];
+                if (params.expiryDays !== undefined)
+                    qs.push('exp=' + String(params.expiryDays));
+                if (params.depth !== undefined)
+                    qs.push('d=' + String(params.depth));
+                const query = qs.length > 0 ? '?' + qs.join('&') : '';
+                return ['/api/share/' + p + query];
+            },
+        },
+        {
+            name: 'server_export',
+            description: 'Trigger an export of a file or directory. Returns a download URL. Supported formats depend on file type and server capabilities (Chrome for PDF).',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'Browse path to export',
+                    },
+                    format: {
+                        type: 'string',
+                        description: 'Export format: pdf, docx, svg, png, zip',
+                        enum: ['pdf', 'docx', 'svg', 'png', 'zip'],
+                    },
+                },
+                required: ['path', 'format'],
+            },
+            buildRequest: (params) => {
+                const p = normalizePath(params);
+                const fmt = String(params.format);
+                return ['/export/' + p + '.' + fmt];
+            },
+        },
+        {
+            name: 'server_event_status',
+            description: 'Query event gateway status: active schemas, recent event log entries, and event counts.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    limit: {
+                        type: 'number',
+                        description: 'Maximum number of recent events to return (default: 20)',
+                    },
+                },
+            },
+            buildRequest: (params) => {
+                const limit = params.limit ? String(params.limit) : '20';
+                return ['/api/status?events=' + limit];
+            },
+        },
+    ];
+    for (const tool of tools) {
+        registerApiTool(api, baseUrl, keySeed, tool);
+    }
+}
+
+/**
+ * Generates the Server menu string for TOOLS.md injection.
+ */
+/**
+ * Fetch server status and generate a Markdown menu string.
+ */
+async function generateServerMenu(apiUrl) {
+    let status;
+    try {
+        status = (await fetchJson(apiUrl + '/api/status', {
+            signal: AbortSignal.timeout(5000),
+        }));
+    }
+    catch {
+        return `> **ACTION REQUIRED: jeeves-server is unreachable.**
+> The server API at ${apiUrl} is down or not configured.
+>
+> **Troubleshooting:**
+> - Check if the JeevesServer service is running
+> - Verify the apiUrl in plugins.entries.jeeves-server-openclaw.config
+> - Try: \`jeeves-server service start\``;
+    }
+    const lines = [
+        `jeeves-server v${status.version ?? 'unknown'} running on port ${String(status.port ?? 'unknown')}.`,
+        '',
+    ];
+    // Export formats
+    if (status.exportFormats && status.exportFormats.length > 0) {
+        lines.push('### Export Formats');
+        lines.push('Available: ' + status.exportFormats.join(', '));
+        if (!status.chrome) {
+            lines.push('> **Note:** Chrome not detected — PDF export unavailable.');
+        }
+        lines.push('');
+    }
+    // Diagram support
+    if (status.diagrams && status.diagrams.length > 0) {
+        lines.push('### Diagram Support');
+        lines.push('Supported languages: ' + status.diagrams.join(', '));
+        lines.push('');
+    }
+    // Connected services
+    if (status.services) {
+        lines.push('### Connected Services');
+        for (const [name, svc] of Object.entries(status.services)) {
+            const icon = svc.reachable ? '\u2705' : '\u274c';
+            lines.push(`* ${icon} **${name}**: ${svc.url}`);
+        }
+        lines.push('');
+    }
+    // Event gateway
+    if (status.events && status.events.length > 0) {
+        lines.push('### Event Gateway');
+        lines.push('Active schemas:');
+        for (const evt of status.events) {
+            lines.push('* **' +
+                evt.name +
+                '**' +
+                (evt.pattern ? ' — pattern: `' + evt.pattern + '`' : ''));
+        }
+        lines.push('');
+    }
+    // Insider count
+    if (status.insiderCount !== undefined) {
+        lines.push('### Access');
+        lines.push(String(status.insiderCount) + ' insider(s) configured.');
+        lines.push('');
+    }
+    // Sharing guidance
+    lines.push('### Sharing');
+    lines.push('Use `server_share` to generate links. Insiders authenticate via Google; outsiders use HMAC share links.');
+    lines.push('Use `server_link_info` to check available export formats for a path before exporting.');
+    return lines.join('\n');
+}
+
+/**
+ * Writes the Server menu section directly to TOOLS.md on disk.
+ */
+const REFRESH_INTERVAL_MS = 60_000;
+let intervalHandle = null;
+let lastWrittenMenu = '';
+/**
+ * Resolve the workspace TOOLS.md path.
+ */
+function resolveToolsPath(api) {
+    if (api.resolvePath) {
+        return api.resolvePath('TOOLS.md');
+    }
+    return resolve(process.cwd(), 'TOOLS.md');
+}
+/**
+ * Upsert the server section in TOOLS.md content.
+ */
+function upsertServerContent(existing, serverMenu) {
+    const section = '## Server\n\n' + serverMenu;
+    // Replace existing server section
+    const re = /^## Server\n[\s\S]*?(?=\n## |\n# |$(?![\s\S]))/m;
+    if (re.test(existing)) {
+        return existing.replace(re, section);
+    }
+    // No existing section — insert under platform tools H1
+    const platformH1 = '# Jeeves Platform Tools';
+    if (existing.includes(platformH1)) {
+        // Find end of H1 line, insert after any existing ## sections
+        // Place after ## Watcher if it exists, otherwise after H1
+        const watcherEnd = existing.match(/^## Watcher\n[\s\S]*?(?=\n## |\n# |$(?![\s\S]))/m);
+        if (watcherEnd) {
+            const idx = existing.indexOf(watcherEnd[0]) + watcherEnd[0].length;
+            return existing.slice(0, idx) + '\n\n' + section + existing.slice(idx);
+        }
+        const idx = existing.indexOf(platformH1) + platformH1.length;
+        return existing.slice(0, idx) + '\n\n' + section + existing.slice(idx);
+    }
+    // No platform header — prepend
+    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 server menu and write it to TOOLS.md if changed.
+ */
+async function refreshToolsMd(api) {
+    const apiUrl = getApiUrl(api);
+    const menu = await generateServerMenu(apiUrl);
+    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 = upsertServerContent(current, menu);
+    if (updated !== current) {
+        await writeFile(toolsPath, updated, 'utf8');
+        lastWrittenMenu = menu;
+        return true;
+    }
+    lastWrittenMenu = menu;
+    return false;
+}
+/**
+ * Start the periodic TOOLS.md writer.
+ */
+function startToolsWriter(api) {
+    refreshToolsMd(api).catch((err) => {
+        console.error('[jeeves-server] Failed to write TOOLS.md:', err);
+    });
+    if (intervalHandle)
+        clearInterval(intervalHandle);
+    intervalHandle = setInterval(() => {
+        refreshToolsMd(api).catch((err) => {
+            console.error('[jeeves-server] Failed to refresh TOOLS.md:', err);
+        });
+    }, REFRESH_INTERVAL_MS);
+    if (typeof intervalHandle === 'object' && 'unref' in intervalHandle) {
+        intervalHandle.unref();
+    }
+}
+
+/**
+ * OpenClaw plugin entry point. Registers all jeeves-server tools.
+ */
+/** Register all jeeves-server tools with the OpenClaw plugin API. */
+function register(api) {
+    const baseUrl = getApiUrl(api);
+    registerServerTools(api, baseUrl);
+    startToolsWriter(api);
+}
+
+export { register as default };

package/dist/rollup.config.d.ts

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

package/dist/scripts/build-skills.d.ts

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

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

@@ -0,0 +1,139 @@
+# Jeeves Server Skill
+
+Operate and interact with a jeeves-server deployment. Use for file browsing, document sharing, export, link generation, event gateway queries, and server diagnostics.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `server_status` | Server health: version, uptime, Chrome availability, export formats, connected services |
+| `server_browse` | Get file/directory metadata and listings for a browse path |
+| `server_link_info` | Query available link types for a path (page URL, raw URL, export links) |
+| `server_share` | Generate share links with optional expiry and directory depth |
+| `server_export` | Trigger export (PDF, DOCX, SVG, PNG, ZIP) and get download URL |
+| `server_event_status` | Query event gateway status, active schemas, and recent event log |
+
+## Browse Paths
+
+All paths use the jeeves-server browse path format: `{drive}/{path}` (e.g., `j/domains/projects/readme.md`).
+
+To convert a Windows file path to a browse path:
+- `J:\domains\projects\readme.md` → `j/domains/projects/readme.md`
+- Strip the colon, lowercase the drive letter, use forward slashes
+
+## Sharing
+
+- **Insiders** authenticate via Google OAuth — bare URLs work for them
+- **Outsiders** need HMAC share links — use `server_share` to generate them
+- Share links have configurable expiry (default 30 days)
+- Directory shares support depth control for recursive access
+
+## Export
+
+Available formats depend on file type and server capabilities:
+- **Markdown files:** PDF (requires Chrome), DOCX
+- **Mermaid diagrams:** SVG, PNG, PDF
+- **PlantUML diagrams:** Formats depend on server configuration
+- **Directories:** ZIP (insider-only)
+
+Use `server_link_info` first to check which formats are available for a path.
+
+## Diagnostics
+
+Run `server_status` to check:
+- Server version and uptime
+- Chrome availability (required for PDF export)
+- Connected services (watcher, runner) and their reachability
+- Available export formats and diagram languages
+
+## Bootstrap: Full Stack Setup
+
+### Prerequisites
+
+- **Node.js 20+** and npm
+- **Java 8+** (optional, for local PlantUML rendering)
+- **Chrome/Chromium** (optional, for PDF export)
+- **NSSM** (Windows) or **systemd** (Linux) for service management
+- **Caddy** (recommended) or nginx for reverse proxy with automatic TLS
+
+### 1. Install jeeves-server
+
+```bash
+npm install -g @karmaniverous/jeeves-server
+```
+
+### 2. Create config
+
+Create `jeeves-server.config.json` in the server's working directory:
+
+```json
+{
+  "port": 1934,
+  "roots": {
+    "data": "/path/to/data"
+  },
+  "keys": {
+    "_internal": "random-hex-seed-for-puppeteer",
+    "_plugin": "random-hex-seed-for-openclaw-plugin"
+  },
+  "insiders": [
+    { "email": "you@example.com" }
+  ],
+  "google": {
+    "clientId": "${GOOGLE_CLIENT_ID}",
+    "clientSecret": "${GOOGLE_CLIENT_SECRET}"
+  },
+  "sessionSecret": "${SESSION_SECRET}",
+  "watcherUrl": "http://127.0.0.1:1936"
+}
+```
+
+### 3. Validate config
+
+```bash
+jeeves-server config validate
+jeeves-server config show
+```
+
+### 4. Register as system service
+
+**Windows (NSSM):**
+```bash
+jeeves-server service install
+jeeves-server service start
+```
+
+**Linux (systemd):**
+```bash
+sudo jeeves-server service install
+sudo jeeves-server service start
+```
+
+### 5. Configure Caddy reverse proxy
+
+Add to your Caddyfile:
+
+```
+your-domain.com {
+    reverse_proxy localhost:1934
+}
+```
+
+Caddy handles TLS certificate provisioning automatically. Ensure DNS A/AAAA records point to your server.
+
+### 6. Install OpenClaw plugin
+
+```bash
+npx @karmaniverous/jeeves-server-openclaw install
+```
+
+Configure the plugin in `openclaw.json` with `apiUrl` and `pluginKey` (matching the `_plugin` key seed from server config). Restart the OpenClaw gateway.
+
+## Troubleshooting
+
+If the server is unreachable:
+1. Is the service running? → `jeeves-server service start`
+2. Is the apiUrl correct? → Default: `http://127.0.0.1:1934`
+3. Is the `_plugin` key configured in both server config and plugin config?
+4. Is Caddy proxying to the correct port? → Check `Caddyfile`
+5. Is the firewall allowing traffic on port 1934? → Only needed for local access; Caddy handles external traffic

package/dist/src/cli.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CLI for installing/uninstalling the jeeves-server OpenClaw plugin.
+ *
+ * Usage:
+ *   npx \@karmaniverous/jeeves-server-openclaw install
+ *   npx \@karmaniverous/jeeves-server-openclaw uninstall
+ */
+export declare function patchConfig(config: Record<string, unknown>, mode: 'add' | 'remove'): string[];

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

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

package/dist/src/helpers.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared types and utility functions for the OpenClaw plugin tool registrations.
+ */
+/** Minimal OpenClaw plugin API surface used for tool registration. */
+export interface PluginApi {
+    config?: {
+        plugins?: {
+            entries?: Record<string, {
+                config?: Record<string, unknown>;
+            }>;
+        };
+    };
+    resolvePath?: (input: string) => string;
+    registerTool(tool: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+        execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
+    }, options?: {
+        optional?: boolean;
+    }): void;
+}
+/** Result shape returned by each tool execution. */
+export interface ToolResult {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/** Resolve the server API base URL from plugin config. */
+export declare function getApiUrl(api: PluginApi): string;
+/** Resolve the plugin key seed from plugin config. */
+export declare function getPluginKey(api: PluginApi): string | undefined;
+/** Derive HMAC key from seed. */
+export declare function deriveKey(seed: string): string;
+/** Append auth key query param to a URL. */
+export declare function withAuth(url: string, keySeed: string | undefined): string;
+/** Format a successful tool result. */
+export declare function ok(data: unknown): ToolResult;
+/** Format an error tool result. */
+export declare function fail(error: unknown): ToolResult;
+/** Format a connection error with actionable guidance. */
+export declare function connectionFail(error: unknown, baseUrl: string): ToolResult;
+/** Fetch JSON from a URL, throwing on non-OK responses. */
+export declare function fetchJson(url: string, init?: RequestInit): Promise<unknown>;

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

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

package/dist/src/index.d.ts

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

package/dist/src/promptInjection.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generates the Server menu string for TOOLS.md injection.
+ */
+/**
+ * Fetch server status and generate a Markdown menu string.
+ */
+export declare function generateServerMenu(apiUrl: string): Promise<string>;

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

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

package/dist/src/serverTools.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Server tool registrations (server_* tools) for the OpenClaw plugin.
+ */
+import { type PluginApi } from './helpers.js';
+/** Register all server_* tools with the OpenClaw plugin API. */
+export declare function registerServerTools(api: PluginApi, baseUrl: string): void;

package/dist/src/toolsWriter.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Writes the Server menu section directly to TOOLS.md on disk.
+ */
+import { type PluginApi } from './helpers.js';
+/**
+ * Start the periodic TOOLS.md writer.
+ */
+export declare function startToolsWriter(api: PluginApi): void;

package/openclaw.plugin.json

@@ -0,0 +1,34 @@
+{
+  "id": "jeeves-server-openclaw",
+  "name": "Jeeves Server",
+  "description": "File browsing, document sharing, export, and event gateway tools for jeeves-server.",
+  "version": "0.1.0-0",
+  "skills": [
+    "dist/skills/jeeves-server"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiUrl": {
+        "type": "string",
+        "description": "jeeves-server API base URL",
+        "default": "http://127.0.0.1:1934"
+      },
+      "pluginKey": {
+        "type": "string",
+        "description": "Server _plugin key seed (for authenticated API calls)"
+      }
+    }
+  },
+  "uiHints": {
+    "apiUrl": {
+      "label": "Server API URL",
+      "placeholder": "http://127.0.0.1:1934"
+    },
+    "pluginKey": {
+      "label": "Plugin Key Seed",
+      "placeholder": "hex string from server config keys._plugin"
+    }
+  }
+}

package/package.json

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