@karmaniverous/jeeves 0.4.6 → 0.4.7

package/dist/cli/jeeves/index.js

@@ -261,14 +261,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.4.5` placeholder is replaced by
+ * The `0.4.6` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.4.5';
+const CORE_VERSION = '0.4.6';
 
 /**
  * Dynamic discovery of installed Jeeves component CLIs.

package/dist/cli/plugin/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { writeFileSync, renameSync, unlinkSync, existsSync, readFileSync, rmSync, mkdirSync, readdirSync, copyFileSync } from 'node:fs';
+import { writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync, readFileSync, readdirSync, copyFileSync, rmSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import * as commander from 'commander';
+import { packageDirectorySync } from 'package-directory';
 import { lock } from 'proper-lockfile';
 import 'semver';
 import { homedir } from 'node:os';
@@ -119,14 +120,14 @@ const COMPONENT_VERSIONS_FILE = 'component-versions.json';
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.4.5` placeholder is replaced by
+ * The `0.4.6` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.4.5';
+const CORE_VERSION = '0.4.6';
 
 /**
  * Shared file I/O helpers for managed section operations.
@@ -224,6 +225,30 @@ function readComponentVersions(coreConfigDir) {
         return {};
     }
 }
+/**
+ * Write a component's version entry to the shared state file.
+ *
+ * @remarks
+ * Reads the existing file, merges the new entry, and writes atomically.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @param options - Component version data to write.
+ */
+function writeComponentVersion(coreConfigDir, options) {
+    const existing = readComponentVersions(coreConfigDir);
+    existing[options.componentName] = {
+        pluginVersion: options.pluginVersion,
+        servicePackage: options.servicePackage,
+        pluginPackage: options.pluginPackage,
+        updatedAt: new Date().toISOString(),
+    };
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    atomicWrite(filePath, JSON.stringify(existing, null, 2) + '\n');
+}
 /**
  * Remove a component's version entry from the shared state file.
  *
@@ -802,13 +827,9 @@ function patchConfig(config, pluginId, mode) {
 }
 
 /**
- * Factory for the standard `-openclaw` plugin installer CLI.
+ * Internal helpers for the plugin installer CLI.
  *
- * @remarks
- * Produces a Commander program with `install` and `uninstall` commands
- * that handle the full plugin lifecycle: copy dist to extensions,
- * patch OpenClaw config, manage HEARTBEAT entries, and clean up
- * managed sections on uninstall.
+ * @module
  */
 /**
  * Derive a component name from a plugin ID.
@@ -823,7 +844,7 @@ function deriveComponentName(pluginId) {
     return pluginId.replace(/^jeeves-/, '').replace(/-openclaw$/, '');
 }
 /**
- * Copy all files from source directory to destination.
+ * Copy all files from source directory to destination, recursively.
  *
  * @param srcDir - Source directory.
  * @param destDir - Destination directory.
@@ -857,6 +878,12 @@ function readJsonFile(filePath) {
         return {};
     }
 }
+
+/**
+ * Factory for the standard `-openclaw` plugin installer CLI.
+ *
+ * @module
+ */
 /**
  * Create a standard plugin installer CLI program.
  *
@@ -882,6 +909,16 @@ function createPluginCli(options) {
         const extensionsDir = join(openClawHome, 'extensions', pluginId);
         console.log(`Copying dist to ${extensionsDir}...`);
         copyDistFiles(distDir, extensionsDir);
+        // Copy package.json and openclaw.plugin.json from package root
+        const pkgRoot = packageDirectorySync({ cwd: distDir });
+        if (pkgRoot) {
+            for (const file of ['package.json', 'openclaw.plugin.json']) {
+                const src = join(pkgRoot, file);
+                if (existsSync(src)) {
+                    copyFileSync(src, join(extensionsDir, file));
+                }
+            }
+        }
         console.log('  ✓ Dist files copied');
         // 2. Patch openclaw.json
         console.log('Patching OpenClaw config...');
@@ -925,7 +962,6 @@ function createPluginCli(options) {
                         : '';
                     const parsed = parseHeartbeat(existing);
                     const fullName = `jeeves-${componentName}`;
-                    // Only add if not already present
                     const hasEntry = parsed.entries.some((e) => e.name === fullName);
                     if (!hasEntry) {
                         parsed.entries.push({
@@ -946,6 +982,25 @@ function createPluginCli(options) {
         catch {
             // HEARTBEAT is best-effort during install
         }
+        // 5. Write component version
+        try {
+            init({
+                workspacePath: opts.workspace ?? '.',
+                configRoot: opts.configRoot,
+            });
+            const pkgJsonPath = join(extensionsDir, 'package.json');
+            const pkgJson = readJsonFile(pkgJsonPath);
+            const pluginVersion = typeof pkgJson.version === 'string' ? pkgJson.version : undefined;
+            writeComponentVersion(getCoreConfigDir(), {
+                componentName,
+                pluginPackage,
+                pluginVersion,
+            });
+            console.log('  ✓ Component version written');
+        }
+        catch {
+            console.log('  ⚠ Could not write component version');
+        }
         console.log();
         console.log(`✅ ${pluginPackage} installed.`);
     });
@@ -974,10 +1029,9 @@ function createPluginCli(options) {
         }
         // 3. Remove TOOLS.md section
         try {
-            const cfgRoot = opts.configRoot;
             const ws = opts.workspace;
             if (ws) {
-                init({ workspacePath: ws, configRoot: cfgRoot });
+                init({ workspacePath: ws, configRoot: opts.configRoot });
                 const sectionId = componentName.charAt(0).toUpperCase() + componentName.slice(1);
                 const toolsPath = join(ws, WORKSPACE_FILES.tools);
                 if (existsSync(toolsPath)) {
@@ -994,10 +1048,9 @@ function createPluginCli(options) {
         }
         // 4. Remove component-versions.json entry
         try {
-            const cfgRoot = opts.configRoot;
             init({
                 workspacePath: opts.workspace ?? '.',
-                configRoot: cfgRoot,
+                configRoot: opts.configRoot,
             });
             removeComponentVersion(getCoreConfigDir(), componentName);
             console.log('  ✓ Component version entry removed');

package/dist/index.d.ts

@@ -267,11 +267,7 @@ declare function createStatusHandler(options: CreateStatusHandlerOptions): Statu
 /**
  * Factory for the standard `-openclaw` plugin installer CLI.
  *
- * @remarks
- * Produces a Commander program with `install` and `uninstall` commands
- * that handle the full plugin lifecycle: copy dist to extensions,
- * patch OpenClaw config, manage HEARTBEAT entries, and clean up
- * managed sections on uninstall.
+ * @module
  */
 
 /** Options for creating a plugin installer CLI. */
@@ -1230,6 +1226,20 @@ declare function seedContent(options: SeedContentOptions): Promise<void>;
  */
 declare function createPluginToolset(descriptor: JeevesComponentDescriptor): ToolDescriptor[];
 
+/**
+ * Resolve the version of a package from its `import.meta.url`.
+ *
+ * @module
+ */
+/**
+ * Get the version string from the nearest `package.json` relative to the
+ * caller's module URL.
+ *
+ * @param importMetaUrl - The `import.meta.url` of the calling module.
+ * @returns The `version` field, or `'unknown'` on any error.
+ */
+declare function getPackageVersion(importMetaUrl: string): string;
+
 /**
  * HTTP helpers for the OpenClaw plugin SDK.
  *
@@ -1394,6 +1404,153 @@ declare function fail(error: unknown): ToolResult;
  */
 declare function connectionFail(error: unknown, baseUrl: string, pluginId: string): ToolResult;
 
+/**
+ * Shared filesystem utilities for runner job scripts.
+ *
+ * @module
+ */
+/** Return current time as ISO 8601 string. */
+declare function nowIso(): string;
+/** Generate a random UUID v4. */
+declare function uuid(): string;
+/** Create a directory and any missing parents. */
+declare function ensureDir(p: string): void;
+/** Read and parse a JSON file, returning `fallback` on any error. */
+declare function readJson<T>(p: string, fallback: T): T;
+/** Atomically write a JSON file (write to .tmp, then rename). */
+declare function writeJsonAtomic(p: string, obj: unknown): void;
+/** Append a single JSON object as a JSONL line. */
+declare function appendJsonl(p: string, obj: unknown): void;
+/** Read a JSONL file into an array of parsed objects. */
+declare function readJsonl<T = unknown>(p: string): T[];
+/** Overwrite a file with an array of objects as JSONL. */
+declare function writeJsonl(p: string, entries: unknown[]): void;
+/** Synchronous sleep using Atomics.wait. */
+declare function sleepMs(ms: number): void;
+/** Async sleep via setTimeout. */
+declare function sleepAsync(ms: number): Promise<void>;
+/** Load a .env-style key=value file into process.env. */
+declare function loadEnvFile(envPath: string): void;
+/** Parse --key=value arguments from argv into a record. */
+declare function parseArgs(argv?: string[]): Record<string, string>;
+/** Get the value following a named flag, or a default. */
+declare function getArg(argv: string[], name: string, defaultValue: string): string;
+
+/**
+ * Google API auth helpers for runner job scripts.
+ * Supports OAuth refresh tokens and service account impersonation.
+ *
+ * @module
+ */
+/** Service account config object specifying a key file path. */
+interface ServiceAccountFileConfig {
+    /** Path to the service account JSON key file. */
+    file: string;
+}
+/** Configuration for a Google account's auth method. */
+interface AccountConfig {
+    /** Google account email address. */
+    email: string;
+    /** Path to refresh token file (relative to credentialsDir). */
+    tokenFile?: string;
+    /** Service account key file path or config object. */
+    serviceAccount?: string | ServiceAccountFileConfig;
+}
+/** Options for the Google auth helper. */
+interface GoogleAuthOptions {
+    /** Path to the OAuth client credentials JSON file. */
+    clientCredentialsPath: string;
+    /** Base directory for credential files. */
+    credentialsDir: string;
+    /** Directory containing service account JSON files. */
+    serviceAccountDir?: string;
+}
+/**
+ * Create a Google auth helper with the given configuration.
+ * Returns a function that resolves an access token for a given account and scopes.
+ */
+declare function createGoogleAuth(options: GoogleAuthOptions): {
+    /** Get an access token for the given account and scopes. */
+    getAccessToken: (account: AccountConfig, scopes: string[]) => Promise<string>;
+};
+
+/**
+ * Shared crash-handler wrapper for runner job scripts.
+ * Catches uncaught errors, logs them, and exits with code 1.
+ *
+ * @module
+ */
+/**
+ * Wrap a script's main function with crash handling.
+ * On uncaught errors, appends to `_crash.log` in `crashDir` and exits.
+ *
+ * @param name - Script identifier for the crash log.
+ * @param fn - Main function to execute (sync or async).
+ * @param crashDir - Directory for crash logs (default: current working directory).
+ */
+declare function runScript(name: string, fn: () => void | Promise<void>, crashDir?: string): void;
+
+/**
+ * Shell execution utilities for runner job scripts.
+ *
+ * @module
+ */
+/** Options for synchronous command execution. */
+interface RunOptions {
+    /** Output encoding (default utf8). */
+    encoding?: BufferEncoding;
+    /** Max stdout/stderr buffer size in bytes. */
+    maxBuffer?: number;
+    /** Execution timeout in milliseconds. */
+    timeout?: number;
+    /** Run command through the shell. */
+    shell?: boolean;
+}
+/**
+ * Run a command synchronously and return trimmed stdout.
+ * Throws on non-zero exit code.
+ */
+declare function run(cmd: string, args: string[], opts?: RunOptions): string;
+/** Options for retry-enabled command execution. */
+interface RetryOptions {
+    /** Number of retries (default 2). */
+    retries?: number;
+    /** Base backoff interval in milliseconds (default 5000). */
+    backoffMs?: number;
+    /** Custom predicate to determine if an error is retryable. */
+    isRetryable?: (error: unknown) => boolean;
+}
+/**
+ * Run a command with automatic retries on transient failures.
+ * Uses exponential backoff between attempts.
+ */
+declare function runWithRetry(cmd: string, args: string[], opts?: RetryOptions & RunOptions): string;
+
+/**
+ * Slack channel → workspace mapping cache.
+ * Resolves which Slack workspace owns a given channel.
+ *
+ * @module
+ */
+/** Options for the Slack workspace resolver. */
+interface SlackWorkspaceOptions {
+    /** Path to the channel→workspace cache JSON file. */
+    cachePath: string;
+    /** Default workspace team ID when resolution fails. */
+    defaultWorkspace: string;
+}
+/** Flush pending cache changes to disk. */
+declare function saveCache(): void;
+/**
+ * Resolve the workspace team ID that owns a Slack channel.
+ * Results are cached to disk.
+ *
+ * @param channelId - Slack channel ID.
+ * @param token - Slack bot token for API calls.
+ * @param options - Cache path and default workspace.
+ */
+declare function getChannelWorkspace(channelId: string, token: string, options: SlackWorkspaceOptions): Promise<string>;
+
 /**
  * Factory for platform-aware service lifecycle management.
  *
@@ -1437,5 +1594,5 @@ interface ServiceManager {
  */
 declare function createServiceManager(descriptor: JeevesComponentDescriptor): ServiceManager;
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, buildHeartbeatSection, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getBindAddress, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, needsCleanup, ok, orchestrateHeartbeat, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion, writeHeartbeatSection };
-export type { AsyncContentCacheOptions, ComponentDependencies, ComponentState, ComponentVersionEntry, ComponentVersionsState, ConfigApplyHandler, ConfigApplyRequest, ConfigApplyResult, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreatePluginCliOptions, CreateStatusHandlerOptions, HeartbeatEntry, InitOptions, JeevesComponentDescriptor, ManagedMarkers, ManagedSection, OrchestrateHeartbeatOptions, ParseManagedResult, ParsedHeartbeat, PlatformComponent, PluginApi, RefreshPlatformContentOptions, RemoveManagedSectionOptions, SectionId, SeedContentOptions, ServiceManager, ServiceManagerOptions, ServiceState, StatusHandler, StatusHandlerResult, StatusResponse, ToolDescriptor, ToolRegistrationOptions, ToolResult, UpdateManagedSectionOptions, VersionStamp, WriteComponentVersionOptions };
+export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, appendJsonl, atomicWrite, buildHeartbeatSection, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, seedContent, shingles, shouldWrite, sleepAsync, sleepMs, updateManagedSection, uuid, withFileLock, writeComponentVersion, writeHeartbeatSection, writeJsonAtomic, writeJsonl };
+export type { AccountConfig, AsyncContentCacheOptions, ComponentDependencies, ComponentState, ComponentVersionEntry, ComponentVersionsState, ConfigApplyHandler, ConfigApplyRequest, ConfigApplyResult, ConfigQueryHandler, ConfigQueryResponse, CoreConfig, CreatePluginCliOptions, CreateStatusHandlerOptions, GoogleAuthOptions, HeartbeatEntry, InitOptions, JeevesComponentDescriptor, ManagedMarkers, ManagedSection, OrchestrateHeartbeatOptions, ParseManagedResult, ParsedHeartbeat, PlatformComponent, PluginApi, RefreshPlatformContentOptions, RemoveManagedSectionOptions, RetryOptions, RunOptions, SectionId, SeedContentOptions, ServiceAccountFileConfig, ServiceManager, ServiceManagerOptions, ServiceState, SlackWorkspaceOptions, StatusHandler, StatusHandlerResult, StatusResponse, ToolDescriptor, ToolRegistrationOptions, ToolResult, UpdateManagedSectionOptions, VersionStamp, WriteComponentVersionOptions };

package/dist/index.js

@@ -1,14 +1,15 @@
-import { writeFileSync, renameSync, unlinkSync, existsSync, readFileSync, mkdirSync, rmSync, readdirSync, copyFileSync, cpSync } from 'node:fs';
-import { join, dirname, resolve } from 'node:path';
+import fs, { writeFileSync, renameSync, unlinkSync, existsSync, readFileSync, mkdirSync, readdirSync, copyFileSync, rmSync, cpSync } from 'node:fs';
+import path, { join, dirname, resolve } from 'node:path';
 import { lock } from 'proper-lockfile';
 import { JSONPath } from 'jsonpath-plus';
 import * as commander from 'commander';
+import { packageDirectorySync } from 'package-directory';
 import { valid, gte, gt } from 'semver';
 import { homedir } from 'node:os';
 import { z } from 'zod';
-import { execSync } from 'node:child_process';
+import cp, { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { packageDirectorySync } from 'package-directory';
+import crypto from 'node:crypto';
 
 /**
  * Comment markers for managed content blocks.
@@ -176,14 +177,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.4.5` placeholder is replaced by
+ * The `0.4.6` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.4.5';
+const CORE_VERSION = '0.4.6';
 
 /**
  * Workspace and config root initialization.
@@ -1239,13 +1240,9 @@ function patchConfig(config, pluginId, mode) {
 }
 
 /**
- * Factory for the standard `-openclaw` plugin installer CLI.
+ * Internal helpers for the plugin installer CLI.
  *
- * @remarks
- * Produces a Commander program with `install` and `uninstall` commands
- * that handle the full plugin lifecycle: copy dist to extensions,
- * patch OpenClaw config, manage HEARTBEAT entries, and clean up
- * managed sections on uninstall.
+ * @module
  */
 /**
  * Derive a component name from a plugin ID.
@@ -1260,7 +1257,7 @@ function deriveComponentName(pluginId) {
     return pluginId.replace(/^jeeves-/, '').replace(/-openclaw$/, '');
 }
 /**
- * Copy all files from source directory to destination.
+ * Copy all files from source directory to destination, recursively.
  *
  * @param srcDir - Source directory.
  * @param destDir - Destination directory.
@@ -1294,6 +1291,12 @@ function readJsonFile(filePath) {
         return {};
     }
 }
+
+/**
+ * Factory for the standard `-openclaw` plugin installer CLI.
+ *
+ * @module
+ */
 /**
  * Create a standard plugin installer CLI program.
  *
@@ -1319,6 +1322,16 @@ function createPluginCli(options) {
         const extensionsDir = join(openClawHome, 'extensions', pluginId);
         console.log(`Copying dist to ${extensionsDir}...`);
         copyDistFiles(distDir, extensionsDir);
+        // Copy package.json and openclaw.plugin.json from package root
+        const pkgRoot = packageDirectorySync({ cwd: distDir });
+        if (pkgRoot) {
+            for (const file of ['package.json', 'openclaw.plugin.json']) {
+                const src = join(pkgRoot, file);
+                if (existsSync(src)) {
+                    copyFileSync(src, join(extensionsDir, file));
+                }
+            }
+        }
         console.log('  ✓ Dist files copied');
         // 2. Patch openclaw.json
         console.log('Patching OpenClaw config...');
@@ -1362,7 +1375,6 @@ function createPluginCli(options) {
                         : '';
                     const parsed = parseHeartbeat(existing);
                     const fullName = `jeeves-${componentName}`;
-                    // Only add if not already present
                     const hasEntry = parsed.entries.some((e) => e.name === fullName);
                     if (!hasEntry) {
                         parsed.entries.push({
@@ -1383,6 +1395,25 @@ function createPluginCli(options) {
         catch {
             // HEARTBEAT is best-effort during install
         }
+        // 5. Write component version
+        try {
+            init({
+                workspacePath: opts.workspace ?? '.',
+                configRoot: opts.configRoot,
+            });
+            const pkgJsonPath = join(extensionsDir, 'package.json');
+            const pkgJson = readJsonFile(pkgJsonPath);
+            const pluginVersion = typeof pkgJson.version === 'string' ? pkgJson.version : undefined;
+            writeComponentVersion(getCoreConfigDir(), {
+                componentName,
+                pluginPackage,
+                pluginVersion,
+            });
+            console.log('  ✓ Component version written');
+        }
+        catch {
+            console.log('  ⚠ Could not write component version');
+        }
         console.log();
         console.log(`✅ ${pluginPackage} installed.`);
     });
@@ -1411,10 +1442,9 @@ function createPluginCli(options) {
         }
         // 3. Remove TOOLS.md section
         try {
-            const cfgRoot = opts.configRoot;
             const ws = opts.workspace;
             if (ws) {
-                init({ workspacePath: ws, configRoot: cfgRoot });
+                init({ workspacePath: ws, configRoot: opts.configRoot });
                 const sectionId = componentName.charAt(0).toUpperCase() + componentName.slice(1);
                 const toolsPath = join(ws, WORKSPACE_FILES.tools);
                 if (existsSync(toolsPath)) {
@@ -1431,10 +1461,9 @@ function createPluginCli(options) {
         }
         // 4. Remove component-versions.json entry
         try {
-            const cfgRoot = opts.configRoot;
             init({
                 workspacePath: opts.workspace ?? '.',
-                configRoot: cfgRoot,
+                configRoot: opts.configRoot,
             });
             removeComponentVersion(getCoreConfigDir(), componentName);
             console.log('  ✓ Component version entry removed');
@@ -1770,7 +1799,7 @@ function isExecError(err) {
  * (Windows), systemd (Linux), or launchd (macOS) based on platform.
  */
 /** Exec helper that returns stdout. */
-function run(cmd) {
+function run$1(cmd) {
     return execSync(cmd, {
         encoding: 'utf-8',
         timeout: 30_000,
@@ -1823,31 +1852,31 @@ function createWindowsManager(descriptor) {
             const cmdArgs = descriptor.startCommand(cfgPath);
             const appPath = cmdArgs[0];
             const appArgs = cmdArgs.slice(1).join(' ');
-            run(`nssm install ${svcName} ${appPath}`);
+            run$1(`nssm install ${svcName} ${appPath}`);
             if (appArgs) {
-                run(`nssm set ${svcName} AppParameters ${appArgs}`);
+                run$1(`nssm set ${svcName} AppParameters ${appArgs}`);
             }
-            run(`nssm set ${svcName} AppStdout ${join(homedir(), `${svcName}.log`)}`);
-            run(`nssm set ${svcName} AppStderr ${join(homedir(), `${svcName}.log`)}`);
-            run(`nssm set ${svcName} AppRotateFiles 1`);
-            run(`nssm set ${svcName} AppRotateBytes 1048576`);
+            run$1(`nssm set ${svcName} AppStdout ${join(homedir(), `${svcName}.log`)}`);
+            run$1(`nssm set ${svcName} AppStderr ${join(homedir(), `${svcName}.log`)}`);
+            run$1(`nssm set ${svcName} AppRotateFiles 1`);
+            run$1(`nssm set ${svcName} AppRotateBytes 1048576`);
         },
         uninstall(options) {
             const svcName = resolveServiceName(descriptor, options);
             runQuiet(`nssm stop ${svcName}`);
-            run(`nssm remove ${svcName} confirm`);
+            run$1(`nssm remove ${svcName} confirm`);
         },
         start(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`nssm start ${svcName}`);
+            run$1(`nssm start ${svcName}`);
         },
         stop(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`nssm stop ${svcName}`);
+            run$1(`nssm stop ${svcName}`);
         },
         restart(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`nssm restart ${svcName}`);
+            run$1(`nssm restart ${svcName}`);
         },
         status(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -1892,8 +1921,8 @@ function createLinuxManager(descriptor) {
             const cmdArgs = descriptor.startCommand(cfgPath);
             mkdirSync(unitDir, { recursive: true });
             writeFileSync(unitPath(svcName), buildSystemdUnit(svcName, cmdArgs));
-            run('systemctl --user daemon-reload');
-            run(`systemctl --user enable ${svcName}.service`);
+            run$1('systemctl --user daemon-reload');
+            run$1(`systemctl --user enable ${svcName}.service`);
         },
         uninstall(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -1906,15 +1935,15 @@ function createLinuxManager(descriptor) {
         },
         start(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`systemctl --user start ${svcName}.service`);
+            run$1(`systemctl --user start ${svcName}.service`);
         },
         stop(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`systemctl --user stop ${svcName}.service`);
+            run$1(`systemctl --user stop ${svcName}.service`);
         },
         restart(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`systemctl --user restart ${svcName}.service`);
+            run$1(`systemctl --user restart ${svcName}.service`);
         },
         status(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -1978,16 +2007,16 @@ function createMacOSManager(descriptor) {
         },
         start(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`launchctl load ${plistPath(svcName)}`);
+            run$1(`launchctl load ${plistPath(svcName)}`);
         },
         stop(options) {
             const svcName = resolveServiceName(descriptor, options);
-            run(`launchctl unload ${plistPath(svcName)}`);
+            run$1(`launchctl unload ${plistPath(svcName)}`);
         },
         restart(options) {
             const svcName = resolveServiceName(descriptor, options);
             runQuiet(`launchctl unload ${plistPath(svcName)}`);
-            run(`launchctl load ${plistPath(svcName)}`);
+            run$1(`launchctl load ${plistPath(svcName)}`);
         },
         status(options) {
             const svcName = resolveServiceName(descriptor, options);
@@ -3967,6 +3996,33 @@ function createPluginToolset(descriptor) {
     return [statusTool, configTool, configApplyTool, serviceTool];
 }
 
+/**
+ * Resolve the version of a package from its `import.meta.url`.
+ *
+ * @module
+ */
+/**
+ * Get the version string from the nearest `package.json` relative to the
+ * caller's module URL.
+ *
+ * @param importMetaUrl - The `import.meta.url` of the calling module.
+ * @returns The `version` field, or `'unknown'` on any error.
+ */
+function getPackageVersion(importMetaUrl) {
+    try {
+        const dir = fileURLToPath(importMetaUrl);
+        const pkgRoot = packageDirectorySync({ cwd: dir });
+        if (!pkgRoot)
+            return 'unknown';
+        const raw = readFileSync(join(pkgRoot, 'package.json'), 'utf-8');
+        const pkg = JSON.parse(raw);
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+
 /**
  * Plugin resolution helpers for the OpenClaw plugin SDK.
  *
@@ -4038,4 +4094,378 @@ function resolveOptionalPluginSetting(api, pluginId, key, envVar) {
     return undefined;
 }
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, buildHeartbeatSection, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getBindAddress, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, needsCleanup, ok, orchestrateHeartbeat, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion, writeHeartbeatSection };
+/**
+ * Shared filesystem utilities for runner job scripts.
+ *
+ * @module
+ */
+// ========== Time & UUID ==========
+/** Return current time as ISO 8601 string. */
+function nowIso() {
+    return new Date().toISOString();
+}
+/** Generate a random UUID v4. */
+function uuid() {
+    return crypto.randomUUID();
+}
+// ========== File System ==========
+/** Create a directory and any missing parents. */
+function ensureDir(p) {
+    fs.mkdirSync(p, { recursive: true });
+}
+/** Read and parse a JSON file, returning `fallback` on any error. */
+function readJson(p, fallback) {
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Atomically write a JSON file (write to .tmp, then rename). */
+function writeJsonAtomic(p, obj) {
+    ensureDir(path.dirname(p));
+    const tmp = p + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n', 'utf8');
+    fs.renameSync(tmp, p);
+}
+/** Append a single JSON object as a JSONL line. */
+function appendJsonl(p, obj) {
+    ensureDir(path.dirname(p));
+    fs.appendFileSync(p, JSON.stringify(obj) + '\n', 'utf8');
+}
+/** Read a JSONL file into an array of parsed objects. */
+function readJsonl(p) {
+    try {
+        const content = fs.readFileSync(p, 'utf8');
+        return content
+            .split('\n')
+            .filter((line) => line.trim())
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+/** Overwrite a file with an array of objects as JSONL. */
+function writeJsonl(p, entries) {
+    ensureDir(path.dirname(p));
+    const content = entries.map((e) => JSON.stringify(e)).join('\n') + '\n';
+    fs.writeFileSync(p, content, 'utf8');
+}
+// ========== Process Control ==========
+/** Synchronous sleep using Atomics.wait. */
+function sleepMs(ms) {
+    const sab = new SharedArrayBuffer(4);
+    const ia = new Int32Array(sab);
+    Atomics.wait(ia, 0, 0, ms);
+}
+/** Async sleep via setTimeout. */
+function sleepAsync(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+// ========== Env File Loader ==========
+/** Load a .env-style key=value file into process.env. */
+function loadEnvFile(envPath) {
+    if (!fs.existsSync(envPath))
+        throw new Error(`Missing secret file: ${envPath}`);
+    for (const line of fs.readFileSync(envPath, 'utf8').split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const idx = trimmed.indexOf('=');
+        if (idx > 0) {
+            process.env[trimmed.slice(0, idx).trim()] = trimmed.slice(idx + 1).trim();
+        }
+    }
+}
+// ========== CLI Arg Parsing ==========
+/** Parse --key=value arguments from argv into a record. */
+function parseArgs(argv = process.argv.slice(2)) {
+    const args = {};
+    for (const arg of argv) {
+        const match = /^--([^=]+)=(.*)$/.exec(arg);
+        if (match) {
+            args[match[1]] = match[2];
+        }
+    }
+    return args;
+}
+/** Get the value following a named flag, or a default. */
+function getArg(argv, name, defaultValue) {
+    const i = argv.indexOf(name);
+    if (i >= 0 && i + 1 < argv.length)
+        return argv[i + 1];
+    return defaultValue;
+}
+
+/**
+ * Google API auth helpers for runner job scripts.
+ * Supports OAuth refresh tokens and service account impersonation.
+ *
+ * @module
+ */
+// ========== JWT / Service Account ==========
+function base64url(buf) {
+    return buf
+        .toString('base64')
+        .replace(/=/g, '')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_');
+}
+function createJwt(serviceAccount, scopes, subject) {
+    const now = Math.floor(Date.now() / 1000);
+    const header = { alg: 'RS256', typ: 'JWT' };
+    const payload = {
+        iss: serviceAccount.client_email,
+        sub: subject,
+        scope: scopes.join(' '),
+        aud: serviceAccount.token_uri,
+        iat: now,
+        exp: now + 3600,
+    };
+    const headerB64 = base64url(Buffer.from(JSON.stringify(header)));
+    const payloadB64 = base64url(Buffer.from(JSON.stringify(payload)));
+    const unsigned = `${headerB64}.${payloadB64}`;
+    const sign = crypto.createSign('RSA-SHA256');
+    sign.update(unsigned);
+    const signature = base64url(sign.sign(serviceAccount.private_key));
+    return `${unsigned}.${signature}`;
+}
+async function getServiceAccountToken(serviceAccount, scopes, subject) {
+    const jwt = createJwt(serviceAccount, scopes, subject);
+    const resp = await fetch(serviceAccount.token_uri, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+            assertion: jwt,
+        }),
+    });
+    if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(`Service account token failed (${String(resp.status)}): ${body}`);
+    }
+    const data = (await resp.json());
+    return data.access_token;
+}
+// ========== OAuth Refresh ==========
+async function getOAuthToken(refreshToken, client) {
+    const resp = await fetch('https://oauth2.googleapis.com/token', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            client_id: client.client_id,
+            client_secret: client.client_secret,
+            refresh_token: refreshToken,
+            grant_type: 'refresh_token',
+        }),
+    });
+    if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(`OAuth token refresh failed (${String(resp.status)}): ${body}`);
+    }
+    const data = (await resp.json());
+    return data.access_token;
+}
+// ========== Unified Auth ==========
+/**
+ * Create a Google auth helper with the given configuration.
+ * Returns a function that resolves an access token for a given account and scopes.
+ */
+function createGoogleAuth(options) {
+    const { clientCredentialsPath, credentialsDir, serviceAccountDir } = options;
+    let _oauthClient = null;
+    function getOAuthClient() {
+        if (!_oauthClient) {
+            _oauthClient = JSON.parse(fs.readFileSync(clientCredentialsPath, 'utf8'));
+        }
+        return _oauthClient;
+    }
+    /**
+     * Get an access token for the given account and scopes.
+     */
+    async function getAccessToken(account, scopes) {
+        if (account.serviceAccount) {
+            const saDir = serviceAccountDir ?? credentialsDir;
+            const saPath = typeof account.serviceAccount === 'string'
+                ? account.serviceAccount
+                : path.join(saDir, account.serviceAccount.file);
+            const sa = JSON.parse(fs.readFileSync(saPath, 'utf8'));
+            return getServiceAccountToken(sa, scopes, account.email);
+        }
+        if (account.tokenFile) {
+            const tokenPath = path.join(credentialsDir, account.tokenFile);
+            const tokenData = JSON.parse(fs.readFileSync(tokenPath, 'utf8'));
+            return getOAuthToken(tokenData.refresh_token, getOAuthClient());
+        }
+        throw new Error(`No auth method configured for ${account.email}`);
+    }
+    return {
+        /** Get an access token for the given account and scopes. */
+        getAccessToken,
+    };
+}
+
+/**
+ * Shared crash-handler wrapper for runner job scripts.
+ * Catches uncaught errors, logs them, and exits with code 1.
+ *
+ * @module
+ */
+/**
+ * Wrap a script's main function with crash handling.
+ * On uncaught errors, appends to `_crash.log` in `crashDir` and exits.
+ *
+ * @param name - Script identifier for the crash log.
+ * @param fn - Main function to execute (sync or async).
+ * @param crashDir - Directory for crash logs (default: current working directory).
+ */
+function runScript(name, fn, crashDir = process.cwd()) {
+    const execute = () => {
+        const result = fn();
+        if (result instanceof Promise) {
+            result.catch((err) => {
+                handleCrash(name, err, crashDir);
+            });
+        }
+    };
+    try {
+        execute();
+    }
+    catch (err) {
+        handleCrash(name, err, crashDir);
+    }
+}
+function handleCrash(name, err, crashDir) {
+    const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
+    const entry = `[${new Date().toISOString()}] CRASH (${name}): ${message}\n`;
+    try {
+        fs.mkdirSync(crashDir, { recursive: true });
+        fs.appendFileSync(path.join(crashDir, '_crash.log'), entry);
+    }
+    catch {
+        // Best effort — don't crash the crash handler.
+    }
+    console.error(entry);
+    process.exit(1);
+}
+
+/**
+ * Shell execution utilities for runner job scripts.
+ *
+ * @module
+ */
+/**
+ * Run a command synchronously and return trimmed stdout.
+ * Throws on non-zero exit code.
+ */
+function run(cmd, args, opts = {}) {
+    const r = cp.spawnSync(cmd, args, {
+        encoding: 'utf8',
+        maxBuffer: 50 * 1024 * 1024,
+        ...opts,
+    });
+    if (r.error)
+        throw r.error;
+    const stdout = r.stdout || '';
+    const stderr = r.stderr || '';
+    if (r.status !== 0) {
+        const msg = (stderr || stdout).trim();
+        throw new Error(`${cmd} ${args.join(' ')} failed (exit ${String(r.status)}): ${msg}`);
+    }
+    return stdout.trim();
+}
+/**
+ * Run a command with automatic retries on transient failures.
+ * Uses exponential backoff between attempts.
+ */
+function runWithRetry(cmd, args, opts = {}) {
+    const { retries = 2, backoffMs = 5000, isRetryable, ...runOpts } = opts;
+    let lastErr;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return run(cmd, args, runOpts);
+        }
+        catch (e) {
+            lastErr = e;
+            const msg = e instanceof Error ? e.message : String(e);
+            const retryable = isRetryable
+                ? isRetryable(e)
+                : /context deadline exceeded|timed out|timeout/i.test(msg);
+            if (!retryable || attempt === retries)
+                throw lastErr;
+            sleepMs(backoffMs * Math.pow(2, attempt));
+        }
+    }
+    throw lastErr;
+}
+
+/**
+ * Slack channel → workspace mapping cache.
+ * Resolves which Slack workspace owns a given channel.
+ *
+ * @module
+ */
+let _cache = null;
+let _dirty = false;
+let _cachePath = '';
+function loadCache(cachePath) {
+    if (!_cache || _cachePath !== cachePath) {
+        _cachePath = cachePath;
+        try {
+            _cache = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+        }
+        catch {
+            _cache = {};
+        }
+    }
+    return _cache;
+}
+/** Flush pending cache changes to disk. */
+function saveCache() {
+    if (_dirty && _cache && _cachePath) {
+        fs.writeFileSync(_cachePath, JSON.stringify(_cache, null, 2) + '\n');
+        _dirty = false;
+    }
+}
+async function queryChannelWorkspace(channelId, token, defaultWorkspace) {
+    const url = `https://slack.com/api/conversations.info?channel=${channelId}`;
+    try {
+        const res = await fetch(url, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok)
+            return defaultWorkspace;
+        const j = (await res.json());
+        if (!j.ok)
+            return defaultWorkspace;
+        const shared = j.channel?.shared_team_ids ?? [];
+        if (shared.length > 0 && !shared.includes(defaultWorkspace)) {
+            return shared[0];
+        }
+        return defaultWorkspace;
+    }
+    catch {
+        return defaultWorkspace;
+    }
+}
+/**
+ * Resolve the workspace team ID that owns a Slack channel.
+ * Results are cached to disk.
+ *
+ * @param channelId - Slack channel ID.
+ * @param token - Slack bot token for API calls.
+ * @param options - Cache path and default workspace.
+ */
+async function getChannelWorkspace(channelId, token, options) {
+    const cache = loadCache(options.cachePath);
+    if (cache[channelId])
+        return cache[channelId];
+    const teamId = await queryChannelWorkspace(channelId, token, options.defaultWorkspace);
+    cache[channelId] = teamId;
+    _dirty = true;
+    return teamId;
+}
+
+export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, appendJsonl, atomicWrite, buildHeartbeatSection, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, seedContent, shingles, shouldWrite, sleepAsync, sleepMs, updateManagedSection, uuid, withFileLock, writeComponentVersion, writeHeartbeatSection, writeJsonAtomic, writeJsonl };

package/package.json

@@ -139,5 +139,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.4.6"
+  "version": "0.4.7"
 }