@tinyclaw/plugins 2.0.0-dev.a9dfb14 → 2.0.0-dev.b27966d

package/dist/community.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Community Plugin Manager
+ *
+ * Provides helpers for installing, removing, and listing third-party
+ * (community) plugins that live outside the official monorepo.
+ *
+ * Community plugins are stored in the config key `plugins.community: string[]`
+ * — separate from `plugins.enabled` which tracks actively running plugins.
+ *
+ * Installation flow:
+ *   1. Validate the package name (strict npm naming rules)
+ *   2. Run `bun add <package>` to install the dependency
+ *   3. Dynamically import the package and validate the plugin contract
+ *   4. Register it in `plugins.community`
+ *
+ * Security:
+ *   - Package names are validated against strict npm naming rules before any
+ *     shell execution — no metacharacters, no path traversal.
+ *   - Official `@tinyclaw/plugin-*` packages are rejected from this flow
+ *     (they are managed via the monorepo, not community install).
+ *   - The installed module must satisfy the TinyClawPlugin interface before
+ *     it's registered — random npm packages that aren't plugins are rejected.
+ */
+import type { ConfigManagerInterface } from '@tinyclaw/types';
+/**
+ * Validate a package name is safe for shell execution and npm resolution.
+ * Returns the cleaned name (without version suffix) or null if invalid.
+ */
+export declare function validatePackageName(input: string): {
+    name: string;
+    installSpec: string;
+} | null;
+/** Read the community plugin list from config. */
+export declare function getCommunityPlugins(configManager: ConfigManagerInterface): string[];
+export interface InstallResult {
+    success: boolean;
+    message: string;
+    plugin?: {
+        id: string;
+        name: string;
+        type: string;
+        version: string;
+    };
+}
+/**
+ * Install a community plugin from npm.
+ *
+ * 1. Validates the package name
+ * 2. Runs `bun add <package>` to install
+ * 3. Imports the module and validates the plugin contract
+ * 4. Registers in `plugins.community` config
+ *
+ * @returns Result with success status and a human-readable message
+ */
+export declare function installCommunityPlugin(packageInput: string, configManager: ConfigManagerInterface): Promise<InstallResult>;
+/**
+ * Remove a community plugin.
+ *
+ * Removes from `plugins.community` and `plugins.enabled`, then runs `bun remove`.
+ */
+export declare function removeCommunityPlugin(packageName: string, configManager: ConfigManagerInterface): Promise<InstallResult>;
+export interface CommunityPluginInfo {
+    id: string;
+    name: string;
+    type: string;
+    version: string;
+    enabled: boolean;
+    source: 'community';
+}
+/**
+ * List all registered community plugins with their status.
+ * Imports are parallelized to avoid serial delays with many plugins.
+ */
+export declare function listCommunityPlugins(configManager: ConfigManagerInterface): Promise<CommunityPluginInfo[]>;

package/dist/community.js

@@ -0,0 +1,282 @@
+/**
+ * Community Plugin Manager
+ *
+ * Provides helpers for installing, removing, and listing third-party
+ * (community) plugins that live outside the official monorepo.
+ *
+ * Community plugins are stored in the config key `plugins.community: string[]`
+ * — separate from `plugins.enabled` which tracks actively running plugins.
+ *
+ * Installation flow:
+ *   1. Validate the package name (strict npm naming rules)
+ *   2. Run `bun add <package>` to install the dependency
+ *   3. Dynamically import the package and validate the plugin contract
+ *   4. Register it in `plugins.community`
+ *
+ * Security:
+ *   - Package names are validated against strict npm naming rules before any
+ *     shell execution — no metacharacters, no path traversal.
+ *   - Official `@tinyclaw/plugin-*` packages are rejected from this flow
+ *     (they are managed via the monorepo, not community install).
+ *   - The installed module must satisfy the TinyClawPlugin interface before
+ *     it's registered — random npm packages that aren't plugins are rejected.
+ */
+import { logger } from '@tinyclaw/logger';
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/**
+ * Strict npm package name pattern (lowercase only, no shell metacharacters).
+ *
+ * Allows:
+ *   - Scoped packages: `@scope/name` (lowercase alphanumeric, hyphens, dots)
+ *   - Unscoped packages: `name`
+ *   - Optional version suffix: `@1.2.3`, `@^1.0.0`, `@latest`
+ *
+ * Rejects everything else — no uppercase, no underscores in names, no spaces,
+ * no shell metacharacters, no path separators.
+ */
+const VALID_PACKAGE_RE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(@[a-z0-9.^~>=<|-]+)?$/;
+/**
+ * Validate a package name is safe for shell execution and npm resolution.
+ * Returns the cleaned name (without version suffix) or null if invalid.
+ */
+export function validatePackageName(input) {
+    const trimmed = input.trim();
+    if (!trimmed || trimmed.length > 214)
+        return null;
+    if (!VALID_PACKAGE_RE.test(trimmed))
+        return null;
+    // Split name from version suffix for the name-only checks.
+    // Safe: the regex above guarantees scoped packages contain '/' and
+    // that the only '@' positions are scope-prefix and version-suffix.
+    const atIdx = trimmed.lastIndexOf('@');
+    const hasVersionSuffix = atIdx > 0 && !trimmed.startsWith('@', atIdx - 1);
+    const name = hasVersionSuffix ? trimmed.slice(0, atIdx) : trimmed;
+    // Reject official plugins — they're managed via the monorepo
+    if (name.startsWith('@tinyclaw/plugin-'))
+        return null;
+    return { name, installSpec: trimmed };
+}
+// ---------------------------------------------------------------------------
+// Plugin contract validation
+// ---------------------------------------------------------------------------
+/**
+ * Dynamically import a package and verify it exports a valid TinyClawPlugin.
+ * Returns the plugin on success, null on failure.
+ */
+async function validatePluginModule(packageName) {
+    try {
+        const mod = await import(packageName);
+        const plugin = mod.default;
+        if (!plugin || typeof plugin !== 'object')
+            return null;
+        const hasRequiredFields = 'id' in plugin &&
+            'name' in plugin &&
+            'type' in plugin &&
+            'version' in plugin &&
+            typeof plugin.id === 'string' &&
+            typeof plugin.name === 'string' &&
+            typeof plugin.type === 'string' &&
+            typeof plugin.version === 'string' &&
+            ['channel', 'provider', 'tools'].includes(plugin.type);
+        if (!hasRequiredFields)
+            return null;
+        return plugin;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Config helpers
+// ---------------------------------------------------------------------------
+/** Read the community plugin list from config. */
+export function getCommunityPlugins(configManager) {
+    return configManager.get('plugins.community') ?? [];
+}
+/** Add a plugin to the community list (idempotent). */
+function addToCommunityList(configManager, packageName) {
+    const current = getCommunityPlugins(configManager);
+    if (!current.includes(packageName)) {
+        configManager.set('plugins.community', [...current, packageName]);
+    }
+}
+/** Remove a plugin from the community list. */
+function removeFromCommunityList(configManager, packageName) {
+    const current = getCommunityPlugins(configManager);
+    configManager.set('plugins.community', current.filter((id) => id !== packageName));
+}
+/**
+ * Install a community plugin from npm.
+ *
+ * 1. Validates the package name
+ * 2. Runs `bun add <package>` to install
+ * 3. Imports the module and validates the plugin contract
+ * 4. Registers in `plugins.community` config
+ *
+ * @returns Result with success status and a human-readable message
+ */
+export async function installCommunityPlugin(packageInput, configManager) {
+    // 1. Validate package name
+    const validated = validatePackageName(packageInput);
+    if (!validated) {
+        return {
+            success: false,
+            message: `Invalid package name "${packageInput}". Must be a valid npm package name. Official @tinyclaw/plugin-* packages are managed separately.`,
+        };
+    }
+    const { name, installSpec } = validated;
+    // 2. Check if already registered
+    const community = getCommunityPlugins(configManager);
+    if (community.includes(name)) {
+        return {
+            success: false,
+            message: `Plugin "${name}" is already registered as a community plugin.`,
+        };
+    }
+    // 3. Install via bun
+    logger.info(`Installing community plugin: ${installSpec}`, undefined, { emoji: '📦' });
+    try {
+        const proc = Bun.spawnSync(['bun', 'add', installSpec], {
+            stdout: 'pipe',
+            stderr: 'pipe',
+            timeout: 60_000,
+        });
+        if (proc.exitCode !== 0) {
+            const stderr = proc.stderr.toString().trim();
+            return {
+                success: false,
+                message: `Failed to install "${installSpec}" from npm. ${stderr ? `Error: ${stderr.slice(0, 200)}` : 'The package may not exist or the registry is unreachable.'}`,
+            };
+        }
+    }
+    catch (err) {
+        return {
+            success: false,
+            message: `Installation failed: ${err.message}`,
+        };
+    }
+    // 4. Validate the plugin contract
+    const plugin = await validatePluginModule(name);
+    if (!plugin) {
+        // Installed but not a valid plugin — remove it
+        try {
+            Bun.spawnSync(['bun', 'remove', name], {
+                stdout: 'pipe',
+                stderr: 'pipe',
+                timeout: 30_000,
+            });
+        }
+        catch {
+            // Best-effort cleanup
+        }
+        return {
+            success: false,
+            message: `Package "${name}" was installed but does not export a valid Tiny Claw plugin (must default-export an object with id, name, type, version). Package was removed.`,
+        };
+    }
+    // 5. Register in config
+    addToCommunityList(configManager, name);
+    logger.info(`Community plugin installed: ${plugin.name} (${plugin.id})`, undefined, {
+        emoji: '✅',
+    });
+    return {
+        success: true,
+        message: `Community plugin "${plugin.name}" (${plugin.id} v${plugin.version}) installed successfully. Restart Tiny Claw to activate it.`,
+        plugin: {
+            id: plugin.id,
+            name: plugin.name,
+            type: plugin.type,
+            version: plugin.version,
+        },
+    };
+}
+/**
+ * Remove a community plugin.
+ *
+ * Removes from `plugins.community` and `plugins.enabled`, then runs `bun remove`.
+ */
+export async function removeCommunityPlugin(packageName, configManager) {
+    const validated = validatePackageName(packageName);
+    if (!validated) {
+        return { success: false, message: `Invalid package name "${packageName}".` };
+    }
+    const { name } = validated;
+    const community = getCommunityPlugins(configManager);
+    if (!community.includes(name)) {
+        return {
+            success: false,
+            message: `Plugin "${name}" is not registered as a community plugin.`,
+        };
+    }
+    // Remove from config lists
+    removeFromCommunityList(configManager, name);
+    // Also remove from enabled if present
+    const enabled = configManager.get('plugins.enabled') ?? [];
+    const wasEnabled = enabled.includes(name);
+    if (wasEnabled) {
+        configManager.set('plugins.enabled', enabled.filter((id) => id !== name));
+    }
+    // Uninstall the npm package
+    try {
+        Bun.spawnSync(['bun', 'remove', name], {
+            stdout: 'pipe',
+            stderr: 'pipe',
+            timeout: 30_000,
+        });
+    }
+    catch {
+        // Best-effort — config is already cleaned up
+    }
+    logger.info(`Community plugin removed: ${name}`, undefined, { emoji: '🗑️' });
+    return {
+        success: true,
+        message: wasEnabled
+            ? `Community plugin "${name}" removed and disabled. Restart Tiny Claw to stop the running instance.`
+            : `Community plugin "${name}" removed.`,
+    };
+}
+/**
+ * List all registered community plugins with their status.
+ * Imports are parallelized to avoid serial delays with many plugins.
+ */
+export async function listCommunityPlugins(configManager) {
+    const community = getCommunityPlugins(configManager);
+    const enabled = new Set(configManager.get('plugins.enabled') ?? []);
+    const results = await Promise.all(community.map(async (id) => {
+        try {
+            const mod = await import(id);
+            const plugin = mod.default;
+            if (plugin && typeof plugin === 'object') {
+                return {
+                    id: plugin.id ?? id,
+                    name: plugin.name ?? id,
+                    type: plugin.type ?? 'unknown',
+                    version: plugin.version ?? 'unknown',
+                    enabled: enabled.has(id),
+                    source: 'community',
+                };
+            }
+            return {
+                id,
+                name: id,
+                type: 'unknown',
+                version: 'unknown',
+                enabled: enabled.has(id),
+                source: 'community',
+            };
+        }
+        catch {
+            return {
+                id,
+                name: id,
+                type: 'unknown',
+                version: 'unresolvable',
+                enabled: enabled.has(id),
+                source: 'community',
+            };
+        }
+    }));
+    return results;
+}

package/dist/index.d.ts

@@ -8,8 +8,11 @@
  * Discovery is config-driven (not filesystem-based) so plugins explicitly
  * opt in via their pairing flow. Import failures are non-fatal — logged and
  * skipped so the rest of the system boots normally.
+ *
+ * Pairing-tool discovery scans the monorepo `plugins/` directories at runtime
+ * so new plugins are picked up automatically without code changes.
  */
-import type { ChannelPlugin, ConfigManagerInterface, ProviderPlugin, ToolsPlugin } from '@tinyclaw/types';
+import type { ChannelPlugin, ConfigManagerInterface, ProviderPlugin, SecretsManagerInterface, Tool, ToolsPlugin } from '@tinyclaw/types';
 export interface LoadedPlugins {
     channels: ChannelPlugin[];
     providers: ProviderPlugin[];
@@ -22,3 +25,24 @@ export interface LoadedPlugins {
  * @returns Grouped loaded plugin instances
  */
 export declare function loadPlugins(configManager: ConfigManagerInterface): Promise<LoadedPlugins>;
+/**
+ * Discover pairing tools from all installed plugins — not just enabled ones.
+ *
+ * This solves the chicken-and-egg problem: pairing tools (e.g. `discord_pair`)
+ * must be available to the agent *before* the plugin is enabled, otherwise the
+ * agent has no way to activate plugins conversationally.
+ *
+ * Only pairing tools are extracted here; full plugin lifecycle (start/stop) is
+ * still gated by `plugins.enabled` via `loadPlugins()`.
+ *
+ * @param enabledIds - IDs already in `plugins.enabled` (their tools are loaded
+ *   separately via loadPlugins — we skip them here to avoid duplicates)
+ * @param secrets - SecretsManager for pairing tools that need it
+ * @param configManager - ConfigManager for pairing tools that need it
+ * @returns Array of pairing tools from not-yet-enabled plugins
+ */
+export declare function discoverPairingTools(enabledIds: string[], secrets: SecretsManagerInterface, configManager: ConfigManagerInterface): Promise<Tool[]>;
+export type { CommunityPluginInfo, InstallResult } from './community.js';
+export { getCommunityPlugins, installCommunityPlugin, listCommunityPlugins, removeCommunityPlugin, validatePackageName, } from './community.js';
+export type { PluginUpdateInfo, PluginVersionInfo } from './update-checker.js';
+export { buildPluginUpdateContext, checkPluginUpdates, } from './update-checker.js';

package/dist/index.js

@@ -8,7 +8,13 @@
  * Discovery is config-driven (not filesystem-based) so plugins explicitly
  * opt in via their pairing flow. Import failures are non-fatal — logged and
  * skipped so the rest of the system boots normally.
+ *
+ * Pairing-tool discovery scans the monorepo `plugins/` directories at runtime
+ * so new plugins are picked up automatically without code changes.
  */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { logger } from '@tinyclaw/logger';
 /**
  * Load all enabled plugins.
@@ -59,6 +65,122 @@ export async function loadPlugins(configManager) {
     }
     return result;
 }
+/**
+ * Directories inside the monorepo `plugins/` folder that contain plugin
+ * packages (each sub-folder must have a `package.json` with a `name` field).
+ */
+const PLUGIN_CATEGORY_DIRS = ['channel', 'provider'];
+/**
+ * Scan the workspace `plugins/` directories and return all plugin package IDs.
+ *
+ * Walks `plugins/channel/*` and `plugins/provider/*`, reads each `package.json`,
+ * and collects the `name` field. This way new plugins added to the monorepo
+ * are discovered automatically — no hardcoded list to maintain.
+ *
+ * Works for all deployment types:
+ * - **Source / dev**: scans the `plugins/` directory from the workspace root
+ * - **Docker**: same — `plugins/` is copied into the image
+ * - **npm global install**: `plugins/` won't exist, returns empty array
+ *   (npm-installed plugins are resolved via dynamic `import()` at pairing
+ *   time, once they're added to `plugins.enabled`)
+ */
+function scanInstalledPluginIds() {
+    try {
+        // Resolve monorepo root: this file lives at packages/plugins/src/index.ts
+        // (or packages/plugins/dist/index.js after build), so root is 3 levels up.
+        const thisDir = dirname(fileURLToPath(import.meta.url));
+        const workspaceRoot = join(thisDir, '..', '..', '..');
+        const pluginsRoot = join(workspaceRoot, 'plugins');
+        if (!existsSync(pluginsRoot)) {
+            logger.debug('Plugin scan: plugins/ directory not found — no discoverable plugins');
+            return [];
+        }
+        const ids = [];
+        for (const category of PLUGIN_CATEGORY_DIRS) {
+            const categoryDir = join(pluginsRoot, category);
+            if (!existsSync(categoryDir))
+                continue;
+            const entries = readdirSync(categoryDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const pkgPath = join(categoryDir, entry.name, 'package.json');
+                if (!existsSync(pkgPath))
+                    continue;
+                try {
+                    const raw = readFileSync(pkgPath, 'utf-8');
+                    const pkg = JSON.parse(raw);
+                    if (typeof pkg.name === 'string' && pkg.name.startsWith('@tinyclaw/plugin-')) {
+                        ids.push(pkg.name);
+                    }
+                }
+                catch {
+                    // Malformed package.json — skip silently
+                }
+            }
+        }
+        logger.debug('Plugin scan: discovered plugins', { ids });
+        return ids;
+    }
+    catch {
+        logger.debug('Plugin scan failed — no discoverable plugins');
+        return [];
+    }
+}
+/**
+ * Discover pairing tools from all installed plugins — not just enabled ones.
+ *
+ * This solves the chicken-and-egg problem: pairing tools (e.g. `discord_pair`)
+ * must be available to the agent *before* the plugin is enabled, otherwise the
+ * agent has no way to activate plugins conversationally.
+ *
+ * Only pairing tools are extracted here; full plugin lifecycle (start/stop) is
+ * still gated by `plugins.enabled` via `loadPlugins()`.
+ *
+ * @param enabledIds - IDs already in `plugins.enabled` (their tools are loaded
+ *   separately via loadPlugins — we skip them here to avoid duplicates)
+ * @param secrets - SecretsManager for pairing tools that need it
+ * @param configManager - ConfigManager for pairing tools that need it
+ * @returns Array of pairing tools from not-yet-enabled plugins
+ */
+export async function discoverPairingTools(enabledIds, secrets, configManager) {
+    const tools = [];
+    const enabledSet = new Set(enabledIds);
+    // Collect IDs from both official (monorepo) and community (config) sources
+    const officialIds = scanInstalledPluginIds();
+    const communityIds = configManager.get('plugins.community') ?? [];
+    const allPluginIds = [...new Set([...officialIds, ...communityIds])];
+    for (const id of allPluginIds) {
+        // Skip plugins that are already enabled — their pairing tools are loaded
+        // through the normal loadPlugins → getPairingTools path.
+        if (enabledSet.has(id))
+            continue;
+        try {
+            const mod = await import(id);
+            const plugin = mod.default;
+            if (!plugin || !isValidPlugin(plugin))
+                continue;
+            // Extract pairing tools from channel and provider plugins
+            if ((plugin.type === 'channel' || plugin.type === 'provider') &&
+                'getPairingTools' in plugin &&
+                typeof plugin.getPairingTools === 'function') {
+                const pairingTools = plugin.getPairingTools(secrets, configManager);
+                if (pairingTools.length > 0) {
+                    tools.push(...pairingTools);
+                    const source = communityIds.includes(id) ? 'community' : 'official';
+                    logger.info(`Discovered pairing tools from: ${plugin.name} (${plugin.id}) [${source}]`, {
+                        toolNames: pairingTools.map((t) => t.name),
+                    });
+                }
+            }
+        }
+        catch (err) {
+            // Non-fatal — plugin may not be installed in this environment
+            logger.debug(`Could not discover plugin "${id}": ${err.message}`);
+        }
+    }
+    return tools;
+}
 /** Minimal structural validation for a plugin object. */
 function isValidPlugin(obj) {
     if (!obj || typeof obj !== 'object')
@@ -69,3 +191,7 @@ function isValidPlugin(obj) {
         typeof p.type === 'string' &&
         ['channel', 'provider', 'tools'].includes(p.type));
 }
+// Re-export community plugin management
+export { getCommunityPlugins, installCommunityPlugin, listCommunityPlugins, removeCommunityPlugin, validatePackageName, } from './community.js';
+// Re-export plugin update checker
+export { buildPluginUpdateContext, checkPluginUpdates, } from './update-checker.js';

package/dist/update-checker.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Plugin Update Checker
+ *
+ * Checks the npm registry for newer versions of installed Tiny Claw plugins.
+ * Results are cached locally (24-hour TTL) to avoid repeated network calls.
+ *
+ * The update info is injected into the agent's system prompt context so the
+ * AI can conversationally inform the user about available plugin upgrades.
+ *
+ * Follows the same pattern as the core update checker in @tinyclaw/core.
+ */
+export interface PluginVersionInfo {
+    /** Plugin package name (e.g. "@tinyclaw/plugin-channel-discord"). */
+    id: string;
+    /** Human-readable name (e.g. "Discord"). */
+    name: string;
+    /** Currently installed version. */
+    current: string;
+    /** Latest version published on npm. */
+    latest: string;
+    /** Whether a newer version is available. */
+    updateAvailable: boolean;
+}
+export interface PluginUpdateInfo {
+    /** Plugins with version information. */
+    plugins: PluginVersionInfo[];
+    /** Number of plugins with available updates. */
+    updatableCount: number;
+    /** Detected runtime environment. */
+    runtime: 'npm' | 'docker' | 'source';
+    /** Timestamp (ms) of the last check. */
+    checkedAt: number;
+}
+/**
+ * Check all installed plugins for available updates.
+ *
+ * Scans both official (monorepo) and community (config-registered) plugins.
+ *
+ * - Returns cached result if still fresh (< 24 hours old).
+ * - Otherwise fetches the npm registry for each plugin.
+ * - Never throws — returns null on any failure.
+ *
+ * @param dataDir - The tinyclaw data directory (e.g. `~/.tinyclaw`).
+ * @param communityPluginIds - Optional list of community plugin IDs to also check.
+ */
+export declare function checkPluginUpdates(dataDir: string, communityPluginIds?: string[]): Promise<PluginUpdateInfo | null>;
+/**
+ * Build a system prompt section that informs the agent about available
+ * plugin updates. Returns an empty string if no updates are available.
+ */
+export declare function buildPluginUpdateContext(info: PluginUpdateInfo | null): string;

package/dist/update-checker.js

@@ -0,0 +1,333 @@
+/**
+ * Plugin Update Checker
+ *
+ * Checks the npm registry for newer versions of installed Tiny Claw plugins.
+ * Results are cached locally (24-hour TTL) to avoid repeated network calls.
+ *
+ * The update info is injected into the agent's system prompt context so the
+ * AI can conversationally inform the user about available plugin upgrades.
+ *
+ * Follows the same pattern as the core update checker in @tinyclaw/core.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { logger } from '@tinyclaw/logger';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Time-to-live for the cache file (24 hours). */
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+/** npm registry base URL. */
+const NPM_REGISTRY_BASE = 'https://registry.npmjs.org';
+/** Maximum time to wait for each registry response (ms). */
+const FETCH_TIMEOUT_MS = 5_000;
+/** Cache file name within the data directory. */
+const CACHE_FILENAME = 'plugin-update-check.json';
+/**
+ * Directories inside the monorepo `plugins/` folder that contain plugin
+ * packages.
+ */
+const PLUGIN_CATEGORY_DIRS = ['channel', 'provider'];
+// ---------------------------------------------------------------------------
+// Semver comparison (minimal — same as core update-checker)
+// ---------------------------------------------------------------------------
+function isNewerVersion(current, latest) {
+    const parse = (v) => v
+        .replace(/^v/, '')
+        .replace(/[-+].*$/, '')
+        .split('.')
+        .map((s) => {
+        const n = Number(s);
+        return Number.isNaN(n) ? 0 : n;
+    })
+        .slice(0, 3);
+    const [cMaj = 0, cMin = 0, cPat = 0] = parse(current);
+    const [lMaj = 0, lMin = 0, lPat = 0] = parse(latest);
+    if (lMaj !== cMaj)
+        return lMaj > cMaj;
+    if (lMin !== cMin)
+        return lMin > cMin;
+    return lPat > cPat;
+}
+/** Matches a semver-like version string. */
+const SEMVER_RE = /^v?\d+\.\d+\.\d+/;
+/** Sanitize a version string for safe prompt interpolation. */
+function sanitizeVersion(value) {
+    const trimmed = value.trim();
+    if (!SEMVER_RE.test(trimmed))
+        return 'unknown';
+    return trimmed.replace(/^(v?\d+\.\d+\.\d+)[\s\S]*$/, '$1');
+}
+/** Sanitize a package name for safe prompt interpolation. */
+function sanitizePackageName(value) {
+    // Only allow scoped npm package names: @scope/name with alphanumeric, hyphens, dots
+    return value.replace(/[^a-zA-Z0-9@/_.-]/g, '');
+}
+// ---------------------------------------------------------------------------
+// Runtime detection
+// ---------------------------------------------------------------------------
+function detectRuntime() {
+    const envRuntime = process.env.TINYCLAW_RUNTIME?.toLowerCase();
+    if (envRuntime === 'docker')
+        return 'docker';
+    if (envRuntime === 'source')
+        return 'source';
+    try {
+        if (existsSync('/.dockerenv'))
+            return 'docker';
+    }
+    catch {
+        // Permission errors — assume npm
+    }
+    return 'npm';
+}
+// ---------------------------------------------------------------------------
+// Community plugin scanning
+// ---------------------------------------------------------------------------
+/**
+ * Resolve community (non-monorepo) plugins by dynamically importing them
+ * and reading their package metadata. Imports run in parallel.
+ */
+async function scanCommunityPlugins(communityIds) {
+    const results = await Promise.all(communityIds
+        .filter((id) => !id.startsWith('@tinyclaw/plugin-'))
+        .map(async (id) => {
+        try {
+            const mod = await import(id);
+            const plugin = mod.default;
+            if (plugin && typeof plugin === 'object' && typeof plugin.version === 'string') {
+                return {
+                    id,
+                    name: typeof plugin.name === 'string' ? plugin.name : id,
+                    version: plugin.version,
+                };
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }));
+    return results.filter((p) => p !== null);
+}
+// ---------------------------------------------------------------------------
+// Official plugin scanning
+// ---------------------------------------------------------------------------
+/**
+ * Scan the workspace for installed plugins and their current versions.
+ */
+function scanInstalledPlugins() {
+    try {
+        const thisDir = dirname(fileURLToPath(import.meta.url));
+        const workspaceRoot = join(thisDir, '..', '..', '..');
+        const pluginsRoot = join(workspaceRoot, 'plugins');
+        if (!existsSync(pluginsRoot))
+            return [];
+        const plugins = [];
+        for (const category of PLUGIN_CATEGORY_DIRS) {
+            const categoryDir = join(pluginsRoot, category);
+            if (!existsSync(categoryDir))
+                continue;
+            const entries = readdirSync(categoryDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const pkgPath = join(categoryDir, entry.name, 'package.json');
+                if (!existsSync(pkgPath))
+                    continue;
+                try {
+                    const raw = readFileSync(pkgPath, 'utf-8');
+                    const pkg = JSON.parse(raw);
+                    if (typeof pkg.name === 'string' && pkg.name.startsWith('@tinyclaw/plugin-')) {
+                        plugins.push({
+                            id: pkg.name,
+                            name: pkg.description?.replace(/plugin for Tiny Claw/i, '').trim() || entry.name,
+                            version: pkg.version || '0.0.0',
+                        });
+                    }
+                }
+                catch {
+                    // Malformed package.json — skip
+                }
+            }
+        }
+        return plugins;
+    }
+    catch {
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// Cache I/O
+// ---------------------------------------------------------------------------
+function getCachePath(dataDir) {
+    return join(dataDir, 'data', CACHE_FILENAME);
+}
+function readCache(dataDir) {
+    try {
+        const raw = readFileSync(getCachePath(dataDir), 'utf-8');
+        const cached = JSON.parse(raw);
+        if (cached &&
+            typeof cached.checkedAt === 'number' &&
+            Array.isArray(cached.plugins) &&
+            typeof cached.updatableCount === 'number') {
+            return cached;
+        }
+    }
+    catch {
+        // Missing or corrupt — will re-check
+    }
+    return null;
+}
+function writeCache(dataDir, info) {
+    try {
+        const dir = join(dataDir, 'data');
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(getCachePath(dataDir), JSON.stringify(info, null, 2), 'utf-8');
+    }
+    catch (err) {
+        logger.debug('Failed to write plugin update cache', err);
+    }
+}
+// ---------------------------------------------------------------------------
+// Registry fetch
+// ---------------------------------------------------------------------------
+async function fetchLatestPluginVersion(packageName) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const url = `${NPM_REGISTRY_BASE}/${encodeURIComponent(packageName)}/latest`;
+        const res = await fetch(url, {
+            signal: controller.signal,
+            headers: { Accept: 'application/json' },
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.version ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Check all installed plugins for available updates.
+ *
+ * Scans both official (monorepo) and community (config-registered) plugins.
+ *
+ * - Returns cached result if still fresh (< 24 hours old).
+ * - Otherwise fetches the npm registry for each plugin.
+ * - Never throws — returns null on any failure.
+ *
+ * @param dataDir - The tinyclaw data directory (e.g. `~/.tinyclaw`).
+ * @param communityPluginIds - Optional list of community plugin IDs to also check.
+ */
+export async function checkPluginUpdates(dataDir, communityPluginIds) {
+    try {
+        const officialPlugins = scanInstalledPlugins();
+        const communityPlugins = await scanCommunityPlugins(communityPluginIds ?? []);
+        const installed = [...officialPlugins, ...communityPlugins];
+        if (installed.length === 0)
+            return null;
+        // Return cached result if still fresh AND the plugin set hasn't changed.
+        // Adding or removing a plugin busts the cache so the new plugin is checked.
+        const cached = readCache(dataDir);
+        const cachedIds = new Set(cached?.plugins.map((p) => p.id) ?? []);
+        const installedIds = new Set(installed.map((p) => p.id));
+        const samePluginSet = cachedIds.size === installedIds.size && [...installedIds].every((id) => cachedIds.has(id));
+        if (cached && samePluginSet && Date.now() - cached.checkedAt < CACHE_TTL_MS) {
+            // Re-evaluate against currently installed versions
+            const refreshed = cached.plugins.map((cp) => {
+                const local = installed.find((ip) => ip.id === cp.id);
+                const current = local?.version ?? cp.current;
+                return {
+                    ...cp,
+                    current,
+                    updateAvailable: isNewerVersion(current, cp.latest),
+                };
+            });
+            const updatableCount = refreshed.filter((p) => p.updateAvailable).length;
+            return { ...cached, plugins: refreshed, updatableCount };
+        }
+        // Fetch latest versions from npm (parallel, with individual timeouts)
+        const results = await Promise.all(installed.map(async (plugin) => {
+            const latest = await fetchLatestPluginVersion(plugin.id);
+            return {
+                id: plugin.id,
+                name: plugin.name,
+                current: plugin.version,
+                latest: latest ?? plugin.version,
+                updateAvailable: latest ? isNewerVersion(plugin.version, latest) : false,
+            };
+        }));
+        const runtime = detectRuntime();
+        const info = {
+            plugins: results,
+            updatableCount: results.filter((p) => p.updateAvailable).length,
+            runtime,
+            checkedAt: Date.now(),
+        };
+        writeCache(dataDir, info);
+        if (info.updatableCount > 0) {
+            logger.info('Plugin updates available', {
+                count: info.updatableCount,
+                plugins: results
+                    .filter((p) => p.updateAvailable)
+                    .map((p) => `${p.id}@${p.current} → ${p.latest}`),
+            }, { emoji: '🔌' });
+        }
+        return info;
+    }
+    catch (err) {
+        logger.debug('Plugin update check failed', err);
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// System prompt context builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a system prompt section that informs the agent about available
+ * plugin updates. Returns an empty string if no updates are available.
+ */
+export function buildPluginUpdateContext(info) {
+    if (!info || info.updatableCount === 0)
+        return '';
+    const updatable = info.plugins.filter((p) => p.updateAvailable);
+    const pluginLines = updatable
+        .map((p) => {
+        const safeName = sanitizePackageName(p.id);
+        const safeCurrent = sanitizeVersion(p.current);
+        const safeLatest = sanitizeVersion(p.latest);
+        return `- **${safeName}**: ${safeCurrent} → ${safeLatest}`;
+    })
+        .join('\n');
+    const upgradeInstructions = info.runtime === 'npm'
+        ? `Since you are running as an npm global install, you can upgrade plugins using the shell tool:
+${updatable.map((p) => `\`bun install -g ${sanitizePackageName(p.id)}@latest\``).join('\n')}
+After upgrading, request a restart using the tinyclaw_restart tool.`
+        : info.runtime === 'docker'
+            ? `Since you are running inside a Docker container, plugin updates are included in the new image.
+Instruct the owner to pull the latest image and restart the container.`
+            : `Since you are running from source, instruct the owner to update and rebuild:
+\`git pull && bun install && bun run build:plugins\`
+Then restart using the tinyclaw_restart tool.`;
+    return `
+
+## Plugin Updates Available
+${pluginLines}
+
+${upgradeInstructions}
+
+**Behavior guidelines:**
+- Mention plugin updates naturally when relevant, but do not interrupt ongoing tasks.
+- Do not repeat the plugin update reminder if the owner has already acknowledged or dismissed it.
+- Plugin updates are separate from core Tiny Claw updates — both should be kept current.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinyclaw/plugins",
-  "version": "2.0.0-dev.a9dfb14",
+  "version": "2.0.0-dev.b27966d",
   "description": "Config-driven plugin loader and validator for Tiny Claw",
   "license": "GPL-3.0",
   "author": "Waren Gonzaga",