@karmaniverous/jeeves 0.5.4 → 0.5.6

package/dist/cli/jeeves/index.js

@@ -269,14 +269,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.3` placeholder is replaced by
+ * The `0.5.5` 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.5.3';
+const CORE_VERSION = '0.5.5';
 
 /**
  * Runtime Node.js version floor check.
@@ -868,7 +868,7 @@ const STALE_LOCK_MS = 120_000;
 /** Default core version when none provided. */
 const DEFAULT_CORE_VERSION = CORE_VERSION;
 /** Lock retry options. */
-const LOCK_RETRIES = { retries: 5, minTimeout: 100, maxTimeout: 1000 };
+const LOCK_RETRIES = { retries: 0 };
 /** Maximum rename retry attempts on EPERM. */
 const ATOMIC_WRITE_MAX_RETRIES = 3;
 /** Delay between EPERM retries in milliseconds. */
@@ -911,26 +911,15 @@ function atomicWrite(filePath, content) {
         }
     }
 }
-/**
- * Execute a callback while holding a file lock.
- *
- * @remarks
- * Acquires a lock on the file, executes the callback, and releases
- * the lock in a finally block. The lock uses a 2-minute stale threshold
- * and retries up to 5 times.
- *
- * @param filePath - Absolute path to the file to lock.
- * @param fn - Async callback to execute while holding the lock.
- */
-async function withFileLock(filePath, fn) {
+async function withLock(targetPath, fn, options, onLockError) {
     let release;
     try {
-        release = await lock(filePath, {
-            stale: STALE_LOCK_MS,
-            retries: LOCK_RETRIES,
-        });
+        release = await lock(targetPath, options);
         await fn();
     }
+    catch (error) {
+        throw error;
+    }
     finally {
         if (release) {
             try {
@@ -942,6 +931,23 @@ async function withFileLock(filePath, fn) {
         }
     }
 }
+/**
+ * Execute a callback while holding a file lock.
+ *
+ * @remarks
+ * Acquires a lock on the file, executes the callback, and releases
+ * the lock in a finally block. The lock uses a 2-minute stale threshold
+ * and retries up to 5 times.
+ *
+ * @param filePath - Absolute path to the file to lock.
+ * @param fn - Async callback to execute while holding the lock.
+ */
+async function withFileLock(filePath, fn) {
+    await withLock(filePath, fn, {
+        stale: STALE_LOCK_MS,
+        retries: LOCK_RETRIES,
+    });
+}
 
 /**
  * Shared component version state file management.
@@ -1099,7 +1105,7 @@ function buildHeartbeatSection(entries) {
  *
  * @remarks
  * Replaces everything from `# Jeeves Platform Status` to EOF.
- * Preserves user content above the heading. Uses file-level locking.
+ * Preserves user content above the heading.
  *
  * @param filePath - Absolute path to HEARTBEAT.md.
  * @param entries - Component entries to write.
@@ -1755,7 +1761,7 @@ function shouldWrite(myVersion, existing, stalenessThresholdMs = STALENESS_THRES
  * - `block`: Replaces the entire managed block (SOUL.md, AGENTS.md).
  * - `section`: Upserts a named H2 section within the managed block (TOOLS.md).
  *
- * Provides file-level locking, version-stamp convergence, and atomic writes.
+ * Provides version-stamp convergence and atomic writes.
  */
 /**
  * Update a managed section in a file.

package/dist/cli/plugin/index.js

@@ -130,14 +130,14 @@ const COMPONENT_VERSIONS_FILE = 'component-versions.json';
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.3` placeholder is replaced by
+ * The `0.5.5` 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.5.3';
+const CORE_VERSION = '0.5.5';
 
 /**
  * Shared file I/O helpers for managed section operations.
@@ -152,7 +152,7 @@ const STALE_LOCK_MS = 120_000;
 /** Default core version when none provided. */
 const DEFAULT_CORE_VERSION = CORE_VERSION;
 /** Lock retry options. */
-const LOCK_RETRIES = { retries: 5, minTimeout: 100, maxTimeout: 1000 };
+const LOCK_RETRIES = { retries: 0 };
 /** Maximum rename retry attempts on EPERM. */
 const ATOMIC_WRITE_MAX_RETRIES = 3;
 /** Delay between EPERM retries in milliseconds. */
@@ -195,26 +195,15 @@ function atomicWrite(filePath, content) {
         }
     }
 }
-/**
- * Execute a callback while holding a file lock.
- *
- * @remarks
- * Acquires a lock on the file, executes the callback, and releases
- * the lock in a finally block. The lock uses a 2-minute stale threshold
- * and retries up to 5 times.
- *
- * @param filePath - Absolute path to the file to lock.
- * @param fn - Async callback to execute while holding the lock.
- */
-async function withFileLock(filePath, fn) {
+async function withLock(targetPath, fn, options, onLockError) {
     let release;
     try {
-        release = await lock(filePath, {
-            stale: STALE_LOCK_MS,
-            retries: LOCK_RETRIES,
-        });
+        release = await lock(targetPath, options);
         await fn();
     }
+    catch (error) {
+        throw error;
+    }
     finally {
         if (release) {
             try {
@@ -226,6 +215,23 @@ async function withFileLock(filePath, fn) {
         }
     }
 }
+/**
+ * Execute a callback while holding a file lock.
+ *
+ * @remarks
+ * Acquires a lock on the file, executes the callback, and releases
+ * the lock in a finally block. The lock uses a 2-minute stale threshold
+ * and retries up to 5 times.
+ *
+ * @param filePath - Absolute path to the file to lock.
+ * @param fn - Async callback to execute while holding the lock.
+ */
+async function withFileLock(filePath, fn) {
+    await withLock(filePath, fn, {
+        stale: STALE_LOCK_MS,
+        retries: LOCK_RETRIES,
+    });
+}
 
 /**
  * Shared component version state file management.
@@ -1265,7 +1271,7 @@ function createPluginCli(options) {
             throw new Error(`Plugin dist directory not found: ${distDir}. Ensure the plugin is built before installing.`);
         }
         console.log(`Copying dist to ${extensionsDir}...`);
-        copyDistFiles(distDir, extensionsDir);
+        copyDistFiles(distDir, join(extensionsDir, 'dist'));
         // Copy package.json and openclaw.plugin.json from package root
         for (const file of ['package.json', 'openclaw.plugin.json']) {
             const src = join(pkgRoot, file);

package/dist/index.d.ts

@@ -575,6 +575,7 @@ declare class ComponentWriter {
     private readonly configDir;
     private readonly gatewayUrl;
     private readonly pendingCleanups;
+    private cyclePromise;
     /** @internal */
     constructor(component: JeevesComponentDescriptor, options?: ComponentWriterOptions);
     /** The component's config directory path. */
@@ -592,6 +593,7 @@ declare class ComponentWriter {
     start(): void;
     /** Stop the writer timer. */
     stop(): void;
+    private scheduleNextCycle;
     /**
      * Execute a single write cycle.
      *
@@ -602,6 +604,7 @@ declare class ComponentWriter {
      * 4. Run HEARTBEAT health orchestration.
      */
     cycle(): Promise<void>;
+    private runCycle;
 }
 
 /**
@@ -735,7 +738,7 @@ declare function buildHeartbeatSection(entries: HeartbeatEntry[]): string;
  *
  * @remarks
  * Replaces everything from `# Jeeves Platform Status` to EOF.
- * Preserves user content above the heading. Uses file-level locking.
+ * Preserves user content above the heading.
  *
  * @param filePath - Absolute path to HEARTBEAT.md.
  * @param entries - Component entries to write.
@@ -1268,7 +1271,7 @@ declare function removeManagedSection(filePath: string, options?: RemoveManagedS
  * - `block`: Replaces the entire managed block (SOUL.md, AGENTS.md).
  * - `section`: Upserts a named H2 section within the managed block (TOOLS.md).
  *
- * Provides file-level locking, version-stamp convergence, and atomic writes.
+ * Provides version-stamp convergence and atomic writes.
  */
 
 /** Options for updateManagedSection. */

package/dist/index.js

@@ -183,14 +183,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.3` placeholder is replaced by
+ * The `0.5.5` 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.5.3';
+const CORE_VERSION = '0.5.5';
 
 /**
  * Workspace and config root initialization.
@@ -287,7 +287,11 @@ const STALE_LOCK_MS = 120_000;
 /** Default core version when none provided. */
 const DEFAULT_CORE_VERSION = CORE_VERSION;
 /** Lock retry options. */
-const LOCK_RETRIES = { retries: 5, minTimeout: 100, maxTimeout: 1000 };
+const LOCK_RETRIES = { retries: 0 };
+/** Workspace lock retry options. */
+const WORKSPACE_LOCK_RETRIES = { retries: 0 };
+/** Workspace lock file name. */
+const WORKSPACE_LOCK_FILE = 'jeeves.lock';
 /** Maximum rename retry attempts on EPERM. */
 const ATOMIC_WRITE_MAX_RETRIES = 3;
 /** Delay between EPERM retries in milliseconds. */
@@ -330,26 +334,18 @@ function atomicWrite(filePath, content) {
         }
     }
 }
-/**
- * Execute a callback while holding a file lock.
- *
- * @remarks
- * Acquires a lock on the file, executes the callback, and releases
- * the lock in a finally block. The lock uses a 2-minute stale threshold
- * and retries up to 5 times.
- *
- * @param filePath - Absolute path to the file to lock.
- * @param fn - Async callback to execute while holding the lock.
- */
-async function withFileLock(filePath, fn) {
+async function withLock(targetPath, fn, options, onLockError) {
     let release;
     try {
-        release = await lock(filePath, {
-            stale: STALE_LOCK_MS,
-            retries: LOCK_RETRIES,
-        });
+        release = await lock(targetPath, options);
         await fn();
     }
+    catch (error) {
+        if (onLockError?.(error)) {
+            return;
+        }
+        throw error;
+    }
     finally {
         if (release) {
             try {
@@ -361,6 +357,44 @@ async function withFileLock(filePath, fn) {
         }
     }
 }
+/**
+ * Execute a callback while holding a file lock.
+ *
+ * @remarks
+ * Acquires a lock on the file, executes the callback, and releases
+ * the lock in a finally block. The lock uses a 2-minute stale threshold
+ * and retries up to 5 times.
+ *
+ * @param filePath - Absolute path to the file to lock.
+ * @param fn - Async callback to execute while holding the lock.
+ */
+async function withFileLock(filePath, fn) {
+    await withLock(filePath, fn, {
+        stale: STALE_LOCK_MS,
+        retries: LOCK_RETRIES,
+    });
+}
+/**
+ * Execute a callback while holding the workspace cycle lock.
+ *
+ * @remarks
+ * Acquires a lock on `{workspacePath}/jeeves.lock`, executes the callback,
+ * and releases the lock in a finally block. If the lock is already held,
+ * returns silently so the caller can skip this cycle.
+ *
+ * @param workspacePath - Absolute workspace path.
+ * @param fn - Async callback to execute while holding the lock.
+ */
+async function withWorkspaceLock(workspacePath, fn) {
+    const lockPath = join(workspacePath, WORKSPACE_LOCK_FILE);
+    writeFileSync(lockPath, '', { flag: 'a' });
+    await withLock(lockPath, fn, {
+        stale: STALE_LOCK_MS,
+        retries: WORKSPACE_LOCK_RETRIES,
+    }, (error) => error instanceof Error &&
+        'code' in error &&
+        error.code === 'ELOCKED');
+}
 
 /**
  * Shared internal utility functions.
@@ -1094,7 +1128,7 @@ function buildHeartbeatSection(entries) {
  *
  * @remarks
  * Replaces everything from `# Jeeves Platform Status` to EOF.
- * Preserves user content above the heading. Uses file-level locking.
+ * Preserves user content above the heading.
  *
  * @param filePath - Absolute path to HEARTBEAT.md.
  * @param entries - Component entries to write.
@@ -2706,7 +2740,7 @@ function createPluginCli(options) {
             throw new Error(`Plugin dist directory not found: ${distDir}. Ensure the plugin is built before installing.`);
         }
         console.log(`Copying dist to ${extensionsDir}...`);
-        copyDistFiles(distDir, extensionsDir);
+        copyDistFiles(distDir, join(extensionsDir, 'dist'));
         // Copy package.json and openclaw.plugin.json from package root
         for (const file of ['package.json', 'openclaw.plugin.json']) {
             const src = join(pkgRoot, file);
@@ -3236,7 +3270,7 @@ function stripForeignMarkers(content, currentMarkers) {
  * - `block`: Replaces the entire managed block (SOUL.md, AGENTS.md).
  * - `section`: Upserts a named H2 section within the managed block (TOOLS.md).
  *
- * Provides file-level locking, version-stamp convergence, and atomic writes.
+ * Provides version-stamp convergence and atomic writes.
  */
 /**
  * Update a managed section in a file.
@@ -4673,6 +4707,7 @@ class ComponentWriter {
     configDir;
     gatewayUrl;
     pendingCleanups = new Set();
+    cyclePromise;
     /** @internal */
     constructor(component, options) {
         this.component = component;
@@ -4685,7 +4720,9 @@ class ComponentWriter {
     }
     /** Whether the writer timer is currently running or pending its first cycle. */
     get isRunning() {
-        return this.jitterTimeout !== undefined || this.timer !== undefined;
+        return (this.jitterTimeout !== undefined ||
+            this.timer !== undefined ||
+            this.cyclePromise !== undefined);
     }
     /**
      * Start the writer timer.
@@ -4703,8 +4740,7 @@ class ComponentWriter {
         const jitterMs = Math.floor(Math.random() * intervalMs);
         this.jitterTimeout = setTimeout(() => {
             this.jitterTimeout = undefined;
-            void this.cycle();
-            this.timer = setInterval(() => void this.cycle(), intervalMs);
+            this.scheduleNextCycle(0, intervalMs);
         }, jitterMs);
     }
     /** Stop the writer timer. */
@@ -4714,10 +4750,19 @@ class ComponentWriter {
             this.jitterTimeout = undefined;
         }
         if (this.timer) {
-            clearInterval(this.timer);
+            clearTimeout(this.timer);
             this.timer = undefined;
         }
     }
+    scheduleNextCycle(delayMs, intervalMs) {
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.cycle().finally(() => {
+                if (this.isRunning)
+                    this.scheduleNextCycle(intervalMs, intervalMs);
+            });
+        }, delayMs);
+    }
     /**
      * Execute a single write cycle.
      *
@@ -4728,44 +4773,54 @@ class ComponentWriter {
      * 4. Run HEARTBEAT health orchestration.
      */
     async cycle() {
+        if (this.cyclePromise)
+            return this.cyclePromise;
+        this.cyclePromise = this.runCycle().finally(() => {
+            this.cyclePromise = undefined;
+        });
+        return this.cyclePromise;
+    }
+    async runCycle() {
         try {
             const workspacePath = getWorkspacePath();
             const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
-            // 1. Write the component's TOOLS.md section
-            const toolsContent = this.component.generateToolsContent();
-            await updateManagedSection(toolsPath, toolsContent, {
-                mode: 'section',
-                sectionId: this.component.sectionId,
-                markers: TOOLS_MARKERS,
-                coreVersion: CORE_VERSION,
-            });
-            // 2. Platform content maintenance
-            await refreshPlatformContent({
-                coreVersion: CORE_VERSION,
-                componentName: this.component.name,
-                componentVersion: this.component.version,
-                servicePackage: this.component.servicePackage,
-                pluginPackage: this.component.pluginPackage,
-            });
-            // 3. Cleanup escalation
-            if (this.gatewayUrl) {
-                scanAndEscalateCleanup([
-                    { filePath: toolsPath, markerIdentity: 'TOOLS' },
-                    {
-                        filePath: join(workspacePath, WORKSPACE_FILES.soul),
-                        markerIdentity: 'SOUL',
-                    },
-                    {
-                        filePath: join(workspacePath, WORKSPACE_FILES.agents),
-                        markerIdentity: 'AGENTS',
-                    },
-                ], this.gatewayUrl, this.pendingCleanups);
-            }
-            // 4. HEARTBEAT orchestration
-            await runHeartbeatCycle({
-                workspacePath,
-                coreConfigDir: getCoreConfigDir(),
-                configRoot: getConfigRoot(),
+            await withWorkspaceLock(workspacePath, async () => {
+                // 1. Write the component's TOOLS.md section
+                const toolsContent = this.component.generateToolsContent();
+                await updateManagedSection(toolsPath, toolsContent, {
+                    mode: 'section',
+                    sectionId: this.component.sectionId,
+                    markers: TOOLS_MARKERS,
+                    coreVersion: CORE_VERSION,
+                });
+                // 2. Platform content maintenance
+                await refreshPlatformContent({
+                    coreVersion: CORE_VERSION,
+                    componentName: this.component.name,
+                    componentVersion: this.component.version,
+                    servicePackage: this.component.servicePackage,
+                    pluginPackage: this.component.pluginPackage,
+                });
+                // 3. Cleanup escalation
+                if (this.gatewayUrl) {
+                    scanAndEscalateCleanup([
+                        { filePath: toolsPath, markerIdentity: 'TOOLS' },
+                        {
+                            filePath: join(workspacePath, WORKSPACE_FILES.soul),
+                            markerIdentity: 'SOUL',
+                        },
+                        {
+                            filePath: join(workspacePath, WORKSPACE_FILES.agents),
+                            markerIdentity: 'AGENTS',
+                        },
+                    ], this.gatewayUrl, this.pendingCleanups);
+                }
+                // 4. HEARTBEAT orchestration
+                await runHeartbeatCycle({
+                    workspacePath,
+                    coreConfigDir: getCoreConfigDir(),
+                    configRoot: getConfigRoot(),
+                });
             });
         }
         catch (err) {

package/package.json

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