qlogicagent 2.13.4 → 2.13.5

package/dist/skills/plugins/plugin-loader.js

@@ -0,0 +1,254 @@
+// ============================================================
+// Plugin Loader — discover, load, and wire plugins into
+// tool pool + HookRegistry + SkillStore.
+//
+// Scan order (hermes-aligned):
+//   1. ~/.qlogicagent/plugins/   (user-level)
+//   2. .qlogicagent/plugins/     (project-level, injected via config)
+//
+// Each plugin directory must contain an index.js (compiled)
+// or index.ts (dev mode) that exports { register(api) }.
+// ============================================================
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import { addTool, removeTool } from "../tools.js";
+import { PLUGIN_HOOK_MAP, } from "./plugin-api.js";
+// ── Loader ──────────────────────────────────────────────────
+export class PluginLoader {
+    config;
+    loaded = [];
+    pluginSkills = [];
+    activations = new Map();
+    log;
+    constructor(config) {
+        this.config = config;
+        this.log = config.log ?? { info: () => { }, warn: () => { } };
+    }
+    /**
+     * Discover and load all plugins from configured directories.
+     * Returns the list of successfully loaded plugins.
+     */
+    async loadAll() {
+        for (const dir of this.config.pluginDirs) {
+            if (!fs.existsSync(dir))
+                continue;
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                if (entry.name.startsWith(".") || entry.name.startsWith("_"))
+                    continue;
+                const pluginDir = path.join(dir, entry.name);
+                await this.loadPlugin(entry.name, pluginDir);
+            }
+        }
+        this.log.info(`[plugins] loaded ${this.loaded.length} plugin(s): ${this.loaded.map(p => p.name).join(", ") || "(none)"}`);
+        return this.loaded;
+    }
+    /**
+     * Get all skills registered by plugins.
+     */
+    getPluginSkills() {
+        return this.pluginSkills;
+    }
+    /**
+     * Get list of all loaded plugins.
+     */
+    getLoaded() {
+        return this.loaded;
+    }
+    /**
+     * Discover and load NEW plugins that weren't present during initial loadAll().
+     * Call per-turn to pick up newly-created skill directories (铁律 #16).
+     */
+    async discoverNew() {
+        const loadedNames = new Set(this.loaded.map(p => p.name));
+        let newCount = 0;
+        for (const dir of this.config.pluginDirs) {
+            if (!fs.existsSync(dir))
+                continue;
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                if (entry.name.startsWith(".") || entry.name.startsWith("_"))
+                    continue;
+                if (loadedNames.has(entry.name))
+                    continue;
+                const pluginDir = path.join(dir, entry.name);
+                await this.loadPlugin(entry.name, pluginDir);
+                newCount++;
+            }
+        }
+        if (newCount > 0) {
+            this.log.info(`[plugins] discovered ${newCount} new plugin(s)`);
+        }
+        return newCount;
+    }
+    /**
+     * Re-check activation for plugins whose TTL has expired.
+     * Call this before tool resolution or periodically in the agent loop.
+     * Only re-runs check functions when the cache has expired.
+     */
+    async refreshActivations() {
+        const now = Date.now();
+        for (const [name, act] of this.activations) {
+            if (now - act.lastCheckAt < act.ttlMs)
+                continue;
+            let result;
+            try {
+                result = await act.checkFn();
+            }
+            catch (err) {
+                this.log.warn(`[plugins] ${name}: check_fn error: ${err instanceof Error ? err.message : err}`);
+                result = act.lastResult; // Keep last known state on error
+            }
+            act.lastCheckAt = now;
+            if (result === act.lastResult)
+                continue;
+            act.lastResult = result;
+            if (result && !act.active) {
+                // Reactivate: re-register tools
+                for (const tool of act.tools) {
+                    this.addRegisteredTool(tool);
+                }
+                act.active = true;
+                this.log.info(`[plugins] ${name}: reactivated (${act.tools.length} tools)`);
+            }
+            else if (!result && act.active) {
+                // Deactivate: unregister tools
+                for (const tool of act.tools) {
+                    this.removeRegisteredTool(tool.name);
+                }
+                // Unhook all hooks
+                for (const fn of act.hookUnregisterFns) {
+                    fn();
+                }
+                act.active = false;
+                this.log.info(`[plugins] ${name}: deactivated`);
+            }
+        }
+    }
+    // ── Private ──────────────────────────────────────────────
+    async loadPlugin(name, directory) {
+        // Find entry point
+        const candidates = ["index.js", "index.mjs"];
+        let entryPath = null;
+        for (const candidate of candidates) {
+            const p = path.join(directory, candidate);
+            if (fs.existsSync(p)) {
+                entryPath = p;
+                break;
+            }
+        }
+        if (!entryPath) {
+            this.log.warn(`[plugins] ${name}: no index.js found, skipping`);
+            return;
+        }
+        // Tracking counters for this plugin
+        let toolCount = 0;
+        let hookCount = 0;
+        let skillCount = 0;
+        const registeredTools = [];
+        const unregisterFns = [];
+        let activationCheckFn = null;
+        let activationTtlMs = 60_000;
+        // Read plugin config (if exists)
+        let pluginConfig = {};
+        const configPath = path.join(directory, "config.json");
+        if (fs.existsSync(configPath)) {
+            try {
+                pluginConfig = JSON.parse(fs.readFileSync(configPath, "utf8"));
+            }
+            catch {
+                // Ignore malformed config
+            }
+        }
+        // Build PluginApi
+        const api = {
+            pluginName: name,
+            registerTool: (tool) => {
+                this.addRegisteredTool(tool);
+                registeredTools.push(tool);
+                toolCount++;
+            },
+            registerHook: (phase, handler) => {
+                const hookPoint = PLUGIN_HOOK_MAP[phase];
+                if (!hookPoint) {
+                    this.log.warn(`[plugins] ${name}: unknown hook phase "${phase}"`);
+                    return;
+                }
+                const unregister = this.config.hookRegistry.register({
+                    point: hookPoint,
+                    handler,
+                    label: `plugin:${name}:${phase}`,
+                    priority: 200, // Plugin hooks run after built-in hooks
+                });
+                unregisterFns.push(unregister);
+                hookCount++;
+            },
+            registerSkill: (skill) => {
+                this.pluginSkills.push(skill);
+                skillCount++;
+            },
+            getConfig: () => pluginConfig,
+            setActivationCheck: (checkFn, ttlMs) => {
+                activationCheckFn = checkFn;
+                if (ttlMs !== undefined)
+                    activationTtlMs = ttlMs;
+            },
+        };
+        // Dynamic import and call register()
+        try {
+            const moduleUrl = pathToFileURL(entryPath).href;
+            const mod = await import(moduleUrl);
+            if (typeof mod.register !== "function") {
+                this.log.warn(`[plugins] ${name}: no register() export, skipping`);
+                return;
+            }
+            await mod.register(api);
+            // Store activation check if plugin set one
+            if (activationCheckFn) {
+                this.activations.set(name, {
+                    checkFn: activationCheckFn,
+                    ttlMs: activationTtlMs,
+                    lastCheckAt: Date.now(),
+                    lastResult: true, // Assume active after initial register()
+                    directory,
+                    tools: registeredTools,
+                    hookUnregisterFns: unregisterFns,
+                    active: true,
+                });
+            }
+            this.loaded.push({ name, directory, toolCount, hookCount, skillCount });
+            this.log.info(`[plugins] ${name}: ${toolCount} tools, ${hookCount} hooks, ${skillCount} skills`);
+        }
+        catch (err) {
+            this.log.warn(`[plugins] ${name}: load error: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    addRegisteredTool(tool) {
+        if (this.config.toolCatalog) {
+            this.config.toolCatalog.addTool(tool);
+        }
+        else {
+            addTool(tool);
+        }
+    }
+    removeRegisteredTool(name) {
+        return this.config.toolCatalog?.removeTool(name) ?? removeTool(name);
+    }
+}

package/dist/skills/plugins/plugin-marketplace.d.ts

@@ -0,0 +1,61 @@
+export interface MarketplaceSource {
+    /** Source type */
+    type: "npm" | "git" | "url";
+    /** Package name (npm), git URL, or zip URL */
+    specifier: string;
+    /** Optional version constraint (npm only) */
+    version?: string;
+}
+export interface MarketplaceConfig {
+    /** Enabled plugins from marketplace */
+    enabledPlugins: MarketplaceSource[];
+    /**
+     * Enterprise policy: only allow plugins matching these names.
+     * If set, any plugin not in the allowlist is blocked.
+     */
+    allowlist?: string[];
+    /**
+     * Enterprise policy: block these plugin names.
+     */
+    blocklist?: string[];
+}
+export interface MarketplaceCatalogEntry {
+    /** Plugin name */
+    name: string;
+    /** Installed version */
+    version: string;
+    /** Source that provided this plugin */
+    source: MarketplaceSource;
+    /** Local install path */
+    installPath: string;
+    /** Install timestamp */
+    installedAt: string;
+}
+export interface InstalledPluginsManifest {
+    version: 1;
+    plugins: MarketplaceCatalogEntry[];
+}
+export interface MarketplaceLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+}
+/**
+ * Load plugins from cache only (no network). Fast startup path.
+ * CC parity: loadAllPluginsCacheOnly()
+ */
+export declare function loadCachedPlugins(): string[];
+/**
+ * Install/update marketplace plugins and return their local paths.
+ * CC parity: loadAllPluginsWithDynamic()
+ */
+export declare function installMarketplacePlugins(config: MarketplaceConfig, log: MarketplaceLogger): Promise<string[]>;
+/**
+ * Get the marketplace config from user settings.
+ * Reads ~/.qlogicagent/marketplace.json
+ */
+export declare function loadMarketplaceConfig(): MarketplaceConfig | null;
+/**
+ * Combine local plugin dirs + marketplace plugin dirs for PluginLoader.
+ * CC parity: loadAllPlugins() merges session + marketplace + builtin.
+ */
+export declare function resolveAllPluginDirs(localDirs: string[], log: MarketplaceLogger): Promise<string[]>;

package/dist/skills/plugins/plugin-marketplace.js

@@ -0,0 +1,229 @@
+// ============================================================
+// Plugin Marketplace — remote plugin discovery + caching.
+//
+// CC reference: src/utils/plugins/pluginLoader.ts
+//   - loadAllPluginsWithDynamic / loadAllPluginsCacheOnly
+//   - marketplace discovery (npm, git URL, zip)
+//   - enterprise policy (allowlist/blocklist)
+//   - versioned cache (installed_plugins.json)
+//
+// Architecture:
+//   1. MarketplaceConfig defines remote sources
+//   2. discoverRemote() fetches plugin catalog from sources
+//   3. installPlugin() downloads + caches locally
+//   4. loadAllWithMarketplace() combines local + remote
+//
+// Plugin sources:
+//   - npm registry: "name@npm" → npm pack + extract
+//   - git URL: "https://github.com/user/repo" → git clone
+//   - direct URL: "https://example.com/plugin.zip" → download
+//
+// Cache layout:
+//   ~/.qlogicagent/plugin-cache/
+//     installed_plugins.json   ← manifest
+//     <name>@<version>/       ← extracted plugin
+// ============================================================
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getDefaultPathService } from "../../runtime/infra/default-path-service.js";
+// ── Cache directory ─────────────────────────────────────────
+function getCacheDir() {
+    return getDefaultPathService().getUserPluginCacheDir();
+}
+function getManifestPath() {
+    return path.join(getCacheDir(), "installed_plugins.json");
+}
+function readManifest() {
+    const manifestPath = getManifestPath();
+    if (!fs.existsSync(manifestPath)) {
+        return { version: 1, plugins: [] };
+    }
+    try {
+        return JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+    }
+    catch {
+        return { version: 1, plugins: [] };
+    }
+}
+function writeManifest(manifest) {
+    const cacheDir = getCacheDir();
+    if (!fs.existsSync(cacheDir)) {
+        fs.mkdirSync(cacheDir, { recursive: true });
+    }
+    fs.writeFileSync(getManifestPath(), JSON.stringify(manifest, null, 2), "utf-8");
+}
+// ── Enterprise policy ───────────────────────────────────────
+function isPluginAllowed(name, config) {
+    if (config.blocklist?.includes(name))
+        return false;
+    if (config.allowlist && !config.allowlist.includes(name))
+        return false;
+    return true;
+}
+// ── Plugin installation (npm) ───────────────────────────────
+async function installFromNpm(specifier, version, log) {
+    const { execFile } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const execFileAsync = promisify(execFile);
+    const cacheDir = getCacheDir();
+    const packageSpec = version ? `${specifier}@${version}` : specifier;
+    try {
+        // Use npm pack to download without installing
+        const { stdout } = await execFileAsync("npm", ["pack", packageSpec, "--pack-destination", cacheDir], {
+            timeout: 60_000,
+            cwd: cacheDir,
+        });
+        const tgzName = stdout.trim().split("\n").pop()?.trim();
+        if (!tgzName) {
+            log.warn(`[marketplace] npm pack returned no output for ${packageSpec}`);
+            return null;
+        }
+        const tgzPath = path.join(cacheDir, tgzName);
+        // Extract: npm pack creates name-version.tgz
+        // Parse version from tgz filename: specifier-1.0.0.tgz
+        const match = tgzName.match(/^(.+)-(\d+\.\d+\.\d+.*)\.tgz$/);
+        const resolvedVersion = match?.[2] ?? "0.0.0";
+        const installPath = path.join(cacheDir, `${specifier}@${resolvedVersion}`);
+        if (!fs.existsSync(installPath)) {
+            fs.mkdirSync(installPath, { recursive: true });
+        }
+        // Extract tgz
+        await execFileAsync("tar", ["xzf", tgzPath, "-C", installPath, "--strip-components=1"], {
+            timeout: 30_000,
+        });
+        // Cleanup tgz
+        try {
+            fs.unlinkSync(tgzPath);
+        }
+        catch { /* ignore */ }
+        // Install dependencies if package.json exists
+        const pkgJsonPath = path.join(installPath, "package.json");
+        if (fs.existsSync(pkgJsonPath)) {
+            try {
+                await execFileAsync("npm", ["install", "--production", "--no-save"], {
+                    cwd: installPath,
+                    timeout: 120_000,
+                });
+            }
+            catch (err) {
+                log.warn(`[marketplace] npm install for ${specifier} failed: ${err.message}`);
+                // Non-fatal — plugin may work without deps
+            }
+        }
+        log.info(`[marketplace] installed ${specifier}@${resolvedVersion} from npm`);
+        return { name: specifier, version: resolvedVersion, installPath };
+    }
+    catch (err) {
+        log.warn(`[marketplace] failed to install ${packageSpec} from npm: ${err.message}`);
+        return null;
+    }
+}
+// ── Public API ──────────────────────────────────────────────
+/**
+ * Load plugins from cache only (no network). Fast startup path.
+ * CC parity: loadAllPluginsCacheOnly()
+ */
+export function loadCachedPlugins() {
+    const manifest = readManifest();
+    return manifest.plugins
+        .filter(p => fs.existsSync(p.installPath))
+        .map(p => p.installPath);
+}
+/**
+ * Install/update marketplace plugins and return their local paths.
+ * CC parity: loadAllPluginsWithDynamic()
+ */
+export async function installMarketplacePlugins(config, log) {
+    const manifest = readManifest();
+    const results = [];
+    for (const source of config.enabledPlugins) {
+        const pluginName = source.specifier.split("/").pop() ?? source.specifier;
+        // Enterprise policy check
+        if (!isPluginAllowed(pluginName, config)) {
+            log.warn(`[marketplace] plugin "${pluginName}" blocked by enterprise policy`);
+            continue;
+        }
+        // Check if already installed
+        const existing = manifest.plugins.find(p => p.source.specifier === source.specifier && p.source.type === source.type);
+        if (existing && fs.existsSync(existing.installPath)) {
+            // If no specific version requested or version matches, skip reinstall
+            if (!source.version || existing.version === source.version) {
+                results.push(existing.installPath);
+                continue;
+            }
+        }
+        // Install based on source type
+        let installed = null;
+        switch (source.type) {
+            case "npm":
+                installed = await installFromNpm(source.specifier, source.version, log);
+                break;
+            case "git":
+            case "url":
+                // Git and URL install: future extension
+                log.warn(`[marketplace] ${source.type} source not yet implemented for "${source.specifier}"`);
+                break;
+        }
+        if (installed) {
+            // Update manifest
+            const entry = {
+                name: installed.name,
+                version: installed.version,
+                source,
+                installPath: installed.installPath,
+                installedAt: new Date().toISOString(),
+            };
+            // Remove old entry if exists
+            manifest.plugins = manifest.plugins.filter(p => !(p.source.specifier === source.specifier && p.source.type === source.type));
+            manifest.plugins.push(entry);
+            results.push(installed.installPath);
+        }
+    }
+    // Persist updated manifest
+    writeManifest(manifest);
+    return results;
+}
+/**
+ * Get the marketplace config from user settings.
+ * Reads ~/.qlogicagent/marketplace.json
+ */
+export function loadMarketplaceConfig() {
+    const configPath = getDefaultPathService().getUserMarketplaceConfigPath();
+    if (!fs.existsSync(configPath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Combine local plugin dirs + marketplace plugin dirs for PluginLoader.
+ * CC parity: loadAllPlugins() merges session + marketplace + builtin.
+ */
+export async function resolveAllPluginDirs(localDirs, log) {
+    const allDirs = [...localDirs];
+    // Add cached marketplace plugins (fast, no network)
+    const cachedPaths = loadCachedPlugins();
+    allDirs.push(...cachedPaths);
+    // Try to install/update from marketplace config
+    const config = loadMarketplaceConfig();
+    if (config && config.enabledPlugins.length > 0) {
+        try {
+            const marketplacePaths = await installMarketplacePlugins(config, log);
+            // Deduplicate: marketplace paths already include cached ones
+            const existingSet = new Set(allDirs);
+            for (const p of marketplacePaths) {
+                if (!existingSet.has(p)) {
+                    allDirs.push(p);
+                }
+            }
+        }
+        catch (err) {
+            log.warn(`[marketplace] failed to update plugins: ${err.message}`);
+            // Fallback to cached plugins only — already added above
+        }
+    }
+    return allDirs;
+}