@2en/clawly-plugins 1.28.1 → 1.29.0-beta.1

package/gateway/plugins.ts

@@ -13,6 +13,7 @@ import {$} from 'zx'
 
 import type {PluginApi} from '../types'
 import {LruCache} from '../lib/lruCache'
+import {manualPluginInstall} from '../lib/manualPluginInstall'
 import {captureEvent} from './posthog'
 import {isUpdateAvailable} from '../lib/semver'
 import {stripCliLogs} from '../lib/stripCliLogs'
@@ -61,301 +62,6 @@ async function fetchNpmView(npmPkgName: string): Promise<NpmViewCache | null> {
   }
 }
 
-const BACKUP_DIR_SUFFIX = '.update-backup'
-const LEGACY_BACKUP_ZIP_SUFFIX = '.update-backup.zip'
-const STAGING_DIR_PREFIX = '.staging-'
-
-/**
- * Back up plugin dir before an install/update operation, verify the sentinel
- * file exists after, and rollback from backup on failure.
- *
- * Two modes:
- * - **staging** (default): Install to a staging dir under extensions/, then do
- *   two fast renames to swap dirs. The plugin dir is only missing for
- *   microseconds between renames, not for the entire npm install duration.
- * - **in-place** (`staging: false`): Copy-based backup for in-place operations
- *   like `openclaw plugins update`. The original dir stays live during the
- *   operation; rollback restores from the copy.
- */
-async function withPluginBackup<T>(
-  api: PluginApi,
-  pluginId: string,
-  operation: (ctx: {stagingDir?: string}) => Promise<T>,
-  opts?: {staging?: boolean},
-): Promise<T> {
-  const stateDir = api.runtime.state.resolveStateDir()
-  if (!stateDir) return operation({})
-
-  const extensionsBase = path.join(stateDir, 'extensions')
-  const extensionDir = path.join(extensionsBase, pluginId)
-  const backupDir = `${extensionDir}${BACKUP_DIR_SUFFIX}`
-  const useStaging = opts?.staging !== false
-
-  if (useStaging) {
-    return withStagingInstall(
-      api,
-      {stateDir, extensionsBase, extensionDir, backupDir, pluginId},
-      operation,
-    )
-  }
-  return withInPlaceBackup(api, {extensionDir, backupDir, pluginId}, operation)
-}
-
-async function withStagingInstall<T>(
-  api: PluginApi,
-  dirs: {
-    stateDir: string
-    extensionsBase: string
-    extensionDir: string
-    backupDir: string
-    pluginId: string
-  },
-  operation: (ctx: {stagingDir?: string}) => Promise<T>,
-): Promise<T> {
-  const {extensionsBase, extensionDir, backupDir, pluginId} = dirs
-
-  // Clean any orphaned staging dirs from previous interrupted attempts
-  cleanOrphanedStagingDirs(api, pluginId)
-
-  const suffix = crypto.randomBytes(4).toString('hex')
-  const stagingDir = path.join(extensionsBase, `${STAGING_DIR_PREFIX}${pluginId}-${suffix}`)
-
-  // Create staging dir (same filesystem as extensions/ → renameSync is atomic)
-  fs.mkdirSync(stagingDir, {recursive: true})
-
-  try {
-    const result = await operation({stagingDir})
-
-    // Verify sentinel in staging output
-    const stagedPluginDir = path.join(stagingDir, 'extensions', pluginId)
-    if (!fs.existsSync(path.join(stagedPluginDir, PLUGIN_SENTINEL))) {
-      throw new Error(
-        `plugin files missing after operation (${PLUGIN_SENTINEL} not found in staging)`,
-      )
-    }
-
-    // Atomic swap: rename existing → backup, then staging → final
-    const hasExisting = fs.existsSync(path.join(extensionDir, PLUGIN_SENTINEL))
-    if (hasExisting) {
-      if (fs.existsSync(backupDir)) fs.rmSync(backupDir, {recursive: true, force: true})
-      fs.renameSync(extensionDir, backupDir)
-    } else if (fs.existsSync(extensionDir)) {
-      // Broken dir without sentinel — remove it
-      fs.rmSync(extensionDir, {recursive: true, force: true})
-    }
-
-    fs.renameSync(stagedPluginDir, extensionDir)
-    api.logger.info(`plugins: staged install of ${pluginId} swapped in`)
-
-    // Cleanup staging dir + backup — failure must not trigger rollback
-    try {
-      fs.rmSync(stagingDir, {recursive: true, force: true})
-    } catch {}
-    try {
-      if (fs.existsSync(backupDir)) fs.rmSync(backupDir, {recursive: true, force: true})
-    } catch (cleanupErr) {
-      api.logger.warn(
-        `plugins: failed to clean backup dir — ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`,
-      )
-    }
-
-    return result
-  } catch (err) {
-    // Clean up staging dir on failure — original is untouched
-    try {
-      if (fs.existsSync(stagingDir)) fs.rmSync(stagingDir, {recursive: true, force: true})
-    } catch {}
-
-    // If we already renamed the original away (crash between step 3 and 4),
-    // the backup exists — restore it
-    if (fs.existsSync(backupDir) && !fs.existsSync(path.join(extensionDir, PLUGIN_SENTINEL))) {
-      api.logger.warn(`plugins: rolling back ${pluginId} from backup`)
-      try {
-        if (fs.existsSync(extensionDir)) fs.rmSync(extensionDir, {recursive: true, force: true})
-        fs.renameSync(backupDir, extensionDir)
-        api.logger.info(`plugins: rollback complete`)
-      } catch (rollbackErr) {
-        api.logger.error(
-          `plugins: rollback failed — ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`,
-        )
-      }
-    }
-    throw err
-  }
-}
-
-async function withInPlaceBackup<T>(
-  api: PluginApi,
-  dirs: {extensionDir: string; backupDir: string; pluginId: string},
-  operation: (ctx: {stagingDir?: string}) => Promise<T>,
-): Promise<T> {
-  const {extensionDir, backupDir, pluginId} = dirs
-
-  const hasExisting = fs.existsSync(path.join(extensionDir, PLUGIN_SENTINEL))
-  if (hasExisting) {
-    try {
-      if (fs.existsSync(backupDir)) fs.rmSync(backupDir, {recursive: true, force: true})
-      fs.cpSync(extensionDir, backupDir, {recursive: true})
-      api.logger.info(`plugins: backed up ${pluginId} (in-place)`)
-    } catch (err) {
-      throw new Error(
-        `plugin backup failed, aborting update: ${err instanceof Error ? err.message : String(err)}`,
-      )
-    }
-  }
-
-  try {
-    const result = await operation({})
-
-    if (!fs.existsSync(path.join(extensionDir, PLUGIN_SENTINEL))) {
-      if (!hasExisting && fs.existsSync(extensionDir)) {
-        try {
-          fs.rmSync(extensionDir, {recursive: true, force: true})
-        } catch {}
-      }
-      throw new Error(`plugin files missing after operation (${PLUGIN_SENTINEL} not found)`)
-    }
-
-    // Clean backup on success
-    try {
-      if (fs.existsSync(backupDir)) fs.rmSync(backupDir, {recursive: true, force: true})
-    } catch (cleanupErr) {
-      api.logger.warn(
-        `plugins: failed to clean backup dir — ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`,
-      )
-    }
-
-    return result
-  } catch (err) {
-    // Clean up partial install on first-time failure (no backup to restore)
-    if (!hasExisting && fs.existsSync(extensionDir)) {
-      try {
-        fs.rmSync(extensionDir, {recursive: true, force: true})
-      } catch {}
-    }
-
-    if (fs.existsSync(backupDir)) {
-      api.logger.warn(`plugins: rolling back ${pluginId} from backup`)
-      try {
-        if (fs.existsSync(extensionDir)) fs.rmSync(extensionDir, {recursive: true, force: true})
-        fs.renameSync(backupDir, extensionDir)
-        api.logger.info(`plugins: rollback complete`)
-      } catch (rollbackErr) {
-        api.logger.error(
-          `plugins: rollback failed — ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`,
-        )
-      }
-    } else {
-      const legacyZip = `${extensionDir}${LEGACY_BACKUP_ZIP_SUFFIX}`
-      if (fs.existsSync(legacyZip)) {
-        api.logger.warn(`plugins: rolling back ${pluginId} from legacy zip backup`)
-        try {
-          if (fs.existsSync(extensionDir)) fs.rmSync(extensionDir, {recursive: true, force: true})
-          await $`unzip -qo ${legacyZip} -d ${path.dirname(extensionDir)}`
-          fs.unlinkSync(legacyZip)
-          api.logger.info(`plugins: rollback from legacy zip complete`)
-        } catch (rollbackErr) {
-          api.logger.error(
-            `plugins: legacy zip rollback failed — ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`,
-          )
-        }
-      }
-    }
-    throw err
-  }
-}
-
-/**
- * Clean up orphaned staging dirs left by interrupted installs.
- * Staging dirs are named `.staging-<pluginId>-<hex>` under extensions/.
- */
-function cleanOrphanedStagingDirs(api: PluginApi, pluginId: string): void {
-  const stateDir = api.runtime.state.resolveStateDir()
-  if (!stateDir) return
-
-  const extensionsBase = path.join(stateDir, 'extensions')
-  try {
-    const entries = fs.readdirSync(extensionsBase)
-    const pattern = new RegExp(
-      `^${STAGING_DIR_PREFIX}${pluginId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-[0-9a-f]{8}$`,
-    )
-    for (const entry of entries) {
-      if (pattern.test(entry)) {
-        try {
-          fs.rmSync(path.join(extensionsBase, entry), {recursive: true, force: true})
-          api.logger.info(`plugins: cleaned up orphaned staging dir ${entry}`)
-        } catch {}
-      }
-    }
-  } catch {}
-}
-
-/**
- * Recover from orphaned backups left by interrupted updates.
- * Called during plugin registration (startup).
- */
-async function recoverOrphanedBackup(api: PluginApi, pluginId: string): Promise<void> {
-  const stateDir = api.runtime.state.resolveStateDir()
-  if (!stateDir) return
-
-  // Clean orphaned staging dirs first
-  cleanOrphanedStagingDirs(api, pluginId)
-
-  const extensionDir = path.join(stateDir, 'extensions', pluginId)
-  const backupDir = `${extensionDir}${BACKUP_DIR_SUFFIX}`
-  const legacyZip = `${extensionDir}${LEGACY_BACKUP_ZIP_SUFFIX}`
-  const sentinelExists = fs.existsSync(path.join(extensionDir, PLUGIN_SENTINEL))
-
-  if (sentinelExists) {
-    // Plugin dir is healthy — clean up any stale backups
-    if (fs.existsSync(backupDir)) {
-      try {
-        fs.rmSync(backupDir, {recursive: true, force: true})
-        api.logger.info(`plugins: cleaned up stale backup dir for ${pluginId}`)
-      } catch {}
-    }
-    if (fs.existsSync(legacyZip)) {
-      try {
-        fs.unlinkSync(legacyZip)
-        api.logger.info(`plugins: cleaned up stale legacy backup zip for ${pluginId}`)
-      } catch {}
-    }
-    return
-  }
-
-  // Plugin dir is missing or broken — try to recover from backup
-  if (fs.existsSync(backupDir)) {
-    api.logger.warn(`plugins: recovering ${pluginId} from orphaned backup dir`)
-    try {
-      if (fs.existsSync(extensionDir)) fs.rmSync(extensionDir, {recursive: true, force: true})
-      fs.renameSync(backupDir, extensionDir)
-      if (!fs.existsSync(path.join(extensionDir, PLUGIN_SENTINEL))) {
-        api.logger.warn(
-          `plugins: recovered dir for ${pluginId} is missing sentinel — plugin may still be broken`,
-        )
-      } else {
-        api.logger.info(`plugins: recovery from orphaned backup complete`)
-      }
-    } catch (err) {
-      api.logger.error(
-        `plugins: orphaned backup recovery failed — ${err instanceof Error ? err.message : String(err)}`,
-      )
-    }
-  } else if (fs.existsSync(legacyZip)) {
-    api.logger.warn(`plugins: recovering ${pluginId} from orphaned legacy zip backup`)
-    try {
-      if (fs.existsSync(extensionDir)) fs.rmSync(extensionDir, {recursive: true, force: true})
-      await $`unzip -qo ${legacyZip} -d ${path.join(stateDir, 'extensions')}`
-      fs.unlinkSync(legacyZip)
-      api.logger.info(`plugins: recovery from orphaned legacy zip complete`)
-    } catch (err) {
-      api.logger.error(
-        `plugins: legacy zip recovery failed — ${err instanceof Error ? err.message : String(err)}`,
-      )
-    }
-  }
-}
-
 interface UpdateParams {
   pluginId: string
   npmPkgName: string
@@ -372,24 +78,7 @@ interface UpdateParams {
   skipIfCurrent?: boolean
 }
 
-// Exported for testing
-export {
-  withPluginBackup,
-  recoverOrphanedBackup,
-  cleanOrphanedStagingDirs,
-  BACKUP_DIR_SUFFIX,
-  LEGACY_BACKUP_ZIP_SUFFIX,
-  STAGING_DIR_PREFIX,
-}
-
 export function registerPlugins(api: PluginApi) {
-  // ── Startup recovery for orphaned backups ──────────────────────
-  void recoverOrphanedBackup(api, 'clawly-plugins').catch((err) => {
-    api.logger.error(
-      `plugins: orphaned backup recovery crashed — ${err instanceof Error ? err.message : String(err)}`,
-    )
-  })
-
   // ── clawly.plugins.version ──────────────────────────────────────
 
   api.registerGatewayMethod('clawly.plugins.version', async ({params, respond}) => {
@@ -524,69 +213,23 @@ export function registerPlugins(api: PluginApi) {
     try {
       let output = ''
 
-      if (strategy === 'force') {
-        if (!stateDir) throw new Error('cannot resolve openclaw state dir')
+      if (!stateDir) throw new Error('cannot resolve openclaw state dir')
 
-        const configPath = path.join(stateDir, 'openclaw.json')
-
-        // 1. Save current plugins.entries.<id> config (preserve user settings)
-        let savedEntry: Record<string, unknown> = {enabled: true}
-        try {
-          const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
-          const entry = config?.plugins?.entries?.[pluginId]
-          if (entry && typeof entry === 'object') {
-            savedEntry = entry as Record<string, unknown>
-          }
-        } catch {
-          // config unreadable — use default
-        }
-        api.logger.info(`plugins: force — saved entry config for ${pluginId}`)
-
-        // 2. Install to staging dir (OPENCLAW_STATE_DIR gives clean slate),
-        //    then atomic swap — no config write needed before install.
-        output = await withPluginBackup(api, pluginId, async ({stagingDir}) => {
-          api.logger.info(`plugins: force — installing ${installTarget} to staging dir`)
-          const result = stagingDir
-            ? await $`OPENCLAW_STATE_DIR=${stagingDir} openclaw plugins install ${installTarget}`
-            : await $`openclaw plugins install ${installTarget}`
-          return result.stdout.trim()
-        })
+      const targetDir = path.join(stateDir, 'extensions', pluginId)
+      const stagingDir = path.join(
+        stateDir,
+        'clawly',
+        'staging',
+        `${pluginId}-${crypto.randomBytes(4).toString('hex')}`,
+      )
 
-        // 3. Ensure config entry is present (triggers config watcher → restart)
-        try {
-          const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
-          if (!config.plugins) config.plugins = {}
-          if (!config.plugins.entries) config.plugins.entries = {}
-          config.plugins.entries[pluginId] = {
-            ...config.plugins.entries[pluginId],
-            ...savedEntry,
-          }
-          fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n')
-          api.logger.info(`plugins: force — ensured entry config for ${pluginId}`)
-        } catch (err) {
-          api.logger.warn(
-            `plugins: force — failed to write entry config: ${err instanceof Error ? err.message : String(err)}`,
-          )
-        }
-      } else if (strategy === 'update') {
-        output = await withPluginBackup(
-          api,
-          pluginId,
-          async () => {
-            const result = await $`openclaw plugins update ${pluginId}`
-            return result.stdout.trim()
-          },
-          {staging: false},
-        )
-      } else {
-        // install
-        output = await withPluginBackup(api, pluginId, async ({stagingDir}) => {
-          const result = stagingDir
-            ? await $`OPENCLAW_STATE_DIR=${stagingDir} openclaw plugins install ${installTarget}`
-            : await $`openclaw plugins install ${installTarget}`
-          return result.stdout.trim()
-        })
-      }
+      api.logger.info(`plugins: ${strategy} — installing ${installTarget}`)
+      output = await manualPluginInstall({
+        spec: installTarget,
+        targetDir,
+        stagingDir,
+        logger: api.logger,
+      })
 
       // Invalidate npm cache for this package
       npmCache.delete(npmPkgName)

package/gateway/presence.ts

@@ -13,7 +13,6 @@ import {stripCliLogs} from '../lib/stripCliLogs'
 $.verbose = false
 
 const DEFAULT_HOST = 'openclaw-ios'
-const CLAWLY_MOBILE_PREFIX = 'Clawly Mobile'
 
 interface PresenceEntry {
   host?: string
@@ -39,9 +38,7 @@ export async function isClientOnline(host = DEFAULT_HOST): Promise<boolean> {
     const result = await $`openclaw gateway call system-presence --json`
     const jsonStr = stripCliLogs(result.stdout)
     const entries: PresenceEntry[] = JSON.parse(jsonStr)
-    const entry =
-      entries.find((e) => e.host === host) ||
-      entries.find((e) => e.host?.startsWith(CLAWLY_MOBILE_PREFIX))
+    const entry = entries.find((e) => e.host === host)
     return isOnlineEntry(entry)
   } catch {
     return false

package/gateway/telemetry-config.test.ts

@@ -17,6 +17,7 @@ describe('readTelemetryPluginConfig', () => {
       otelDataset: 'clawly-otel-logs-dev',
       posthogApiKey: 'ph-key',
       posthogHost: 'https://us.i.posthog.com',
+      messageLogEnabled: false,
     })
   })
 
@@ -35,6 +36,7 @@ describe('readTelemetryPluginConfig', () => {
       otelDataset: 'clawly-otel-logs-dev',
       posthogApiKey: 'ph-key',
       posthogHost: 'https://us.i.posthog.com',
+      messageLogEnabled: false,
     })
   })
 
@@ -53,6 +55,7 @@ describe('readTelemetryPluginConfig', () => {
       otelDataset: undefined,
       posthogApiKey: undefined,
       posthogHost: undefined,
+      messageLogEnabled: false,
     })
   })
 })

package/gateway/telemetry-config.ts

@@ -4,6 +4,7 @@ export interface TelemetryPluginConfig {
   otelDataset?: string
   posthogApiKey?: string
   posthogHost?: string
+  messageLogEnabled?: boolean
 }
 
 function readString(value: unknown): string | undefined {
@@ -23,5 +24,6 @@ export function readTelemetryPluginConfig(
     otelDataset: readString(cfg.otelDataset),
     posthogApiKey: readString(cfg.posthogApiKey),
     posthogHost: readString(cfg.posthogHost),
+    messageLogEnabled: cfg.messageLogEnabled === true || cfg.messageLogEnabled === 'true',
   }
 }

package/index.ts

@@ -34,6 +34,9 @@
  * - agent_end             — sends push notification when client is offline; injects cron results into main session
  * - after_tool_call       — cron telemetry: captures cron job creation/deletion
  * - agent_end (pri 100)   — cron telemetry: captures cron execution outcomes with delivery/push flags
+ * - llm_input             — message-log (dev-only): logs model, provider, history size, images count (no content)
+ * - llm_output            — message-log (dev-only): logs model, provider, content length (no content)
+ * - message_sent          — message-log (dev-only): logs channel delivery outcome (no content)
  * - gateway_start         — auto-approves device pairing for Clawly mobile clients (clientId: openclaw-ios)
  * - gateway_start         — registers auto-update cron job (0 3 * * *) for clawly-plugins
  */

package/lib/manualPluginInstall.test.ts

@@ -0,0 +1,121 @@
+import {afterEach, beforeEach, describe, expect, test} from 'bun:test'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import {manualPluginInstall} from './manualPluginInstall'
+
+const PLUGIN_ID = 'test-plugin'
+const SENTINEL = 'openclaw.plugin.json'
+
+function makeTmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'clawly-plugins-test-'))
+}
+
+function setupPluginDir(stateDir: string): string {
+  const extensionDir = path.join(stateDir, 'extensions', PLUGIN_ID)
+  fs.mkdirSync(extensionDir, {recursive: true})
+  fs.writeFileSync(path.join(extensionDir, SENTINEL), '{}')
+  fs.writeFileSync(path.join(extensionDir, 'package.json'), '{"version":"1.0.0"}')
+  return extensionDir
+}
+
+function setupLocalSpec(tmpDir: string, version: string, hasSentinel = true): string {
+  const specDir = path.join(tmpDir, 'local-spec')
+  fs.mkdirSync(specDir, {recursive: true})
+  if (hasSentinel) fs.writeFileSync(path.join(specDir, SENTINEL), '{}')
+  fs.writeFileSync(path.join(specDir, 'package.json'), `{"version":"${version}"}`)
+  return specDir
+}
+
+let tmpDir: string
+
+beforeEach(() => {
+  tmpDir = makeTmpDir()
+})
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true})
+})
+
+describe('manualPluginInstall', () => {
+  test('first install (empty targetDir): installs from local spec', async () => {
+    const targetDir = path.join(tmpDir, 'extensions', PLUGIN_ID)
+    const stagingDir = path.join(tmpDir, 'clawly', 'staging', PLUGIN_ID)
+    const specDir = setupLocalSpec(tmpDir, '1.0.0')
+
+    const result = await manualPluginInstall({
+      spec: specDir,
+      targetDir,
+      stagingDir,
+    })
+
+    expect(result).toContain('Installed')
+    expect(fs.existsSync(path.join(targetDir, SENTINEL))).toBe(true)
+    expect(JSON.parse(fs.readFileSync(path.join(targetDir, 'package.json'), 'utf-8')).version).toBe(
+      '1.0.0',
+    )
+    expect(fs.existsSync(stagingDir)).toBe(false)
+  })
+
+  test('update: syncs new version, removes stale files, cleans staging', async () => {
+    const targetDir = setupPluginDir(tmpDir)
+    fs.writeFileSync(path.join(targetDir, 'feature-v1.js'), 'old')
+    const stagingDir = path.join(tmpDir, 'clawly', 'staging', PLUGIN_ID)
+    const specDir = setupLocalSpec(tmpDir, '2.0.0')
+
+    const result = await manualPluginInstall({
+      spec: specDir,
+      targetDir,
+      stagingDir,
+    })
+
+    expect(result).toContain('Installed')
+    expect(fs.existsSync(path.join(targetDir, 'feature-v1.js'))).toBe(false)
+    expect(fs.existsSync(path.join(targetDir, SENTINEL))).toBe(true)
+    expect(JSON.parse(fs.readFileSync(path.join(targetDir, 'package.json'), 'utf-8')).version).toBe(
+      '2.0.0',
+    )
+    expect(fs.existsSync(stagingDir)).toBe(false)
+  })
+
+  test('rejects when spec lacks sentinel (targetDir unchanged)', async () => {
+    const targetDir = setupPluginDir(tmpDir)
+    const stagingDir = path.join(tmpDir, 'clawly', 'staging', PLUGIN_ID)
+    const specDir = setupLocalSpec(tmpDir, '2.0.0', false)
+
+    await expect(manualPluginInstall({spec: specDir, targetDir, stagingDir})).rejects.toThrow(
+      'plugin source missing openclaw.plugin.json',
+    )
+
+    expect(fs.existsSync(path.join(targetDir, SENTINEL))).toBe(true)
+    expect(JSON.parse(fs.readFileSync(path.join(targetDir, 'package.json'), 'utf-8')).version).toBe(
+      '1.0.0',
+    )
+  })
+
+  test('first install: rejects when spec lacks sentinel (targetDir left empty)', async () => {
+    const targetDir = path.join(tmpDir, 'extensions', PLUGIN_ID)
+    fs.mkdirSync(path.join(tmpDir, 'extensions'), {recursive: true})
+    const stagingDir = path.join(tmpDir, 'clawly', 'staging', PLUGIN_ID)
+    const specDir = setupLocalSpec(tmpDir, '1.0.0', false)
+
+    await expect(manualPluginInstall({spec: specDir, targetDir, stagingDir})).rejects.toThrow(
+      'plugin source missing openclaw.plugin.json',
+    )
+
+    expect(fs.existsSync(targetDir)).toBe(true)
+    expect(fs.readdirSync(targetDir)).toHaveLength(0)
+  })
+
+  test('local spec path must exist', async () => {
+    const targetDir = path.join(tmpDir, 'extensions', PLUGIN_ID)
+    fs.mkdirSync(targetDir, {recursive: true})
+    const stagingDir = path.join(tmpDir, 'clawly', 'staging', PLUGIN_ID)
+    const specDir = path.join(tmpDir, 'nonexistent')
+
+    await expect(manualPluginInstall({spec: specDir, targetDir, stagingDir})).rejects.toThrow(
+      'local spec path does not exist',
+    )
+  })
+})