@cuylabs/agent-core 0.7.0 → 0.9.0

package/dist/chunk-WGZAPU6N.js

@@ -0,0 +1,929 @@
+// src/plugin/event-bus.ts
+var PluginEventBus = class {
+  channels = /* @__PURE__ */ new Map();
+  emit(channel, data) {
+    const handlers = this.channels.get(channel);
+    if (!handlers) return;
+    for (const fn of handlers) {
+      try {
+        fn(data);
+      } catch {
+      }
+    }
+  }
+  on(channel, handler) {
+    let set = this.channels.get(channel);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.channels.set(channel, set);
+    }
+    set.add(handler);
+    return () => {
+      set.delete(handler);
+      if (set.size === 0) this.channels.delete(channel);
+    };
+  }
+  /** Number of active channels. */
+  get size() {
+    return this.channels.size;
+  }
+  /** Remove all listeners. */
+  clear() {
+    this.channels.clear();
+  }
+};
+
+// src/plugin/settings.ts
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+}
+function cloneSettingsValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => cloneSettingsValue(item));
+  }
+  if (isPlainObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        key,
+        cloneSettingsValue(item)
+      ])
+    );
+  }
+  return value;
+}
+function mergeSettingsValue(base, override) {
+  if (isPlainObject(base) && isPlainObject(override)) {
+    const merged = { ...cloneSettingsValue(base) };
+    for (const [key, value] of Object.entries(override)) {
+      merged[key] = key in merged ? mergeSettingsValue(merged[key], value) : cloneSettingsValue(value);
+    }
+    return merged;
+  }
+  return cloneSettingsValue(override);
+}
+function parseSettingsValue(namespace, value, schema) {
+  const parsed = schema.safeParse(value);
+  if (parsed.success) {
+    return parsed.data;
+  }
+  throw new Error(
+    `Invalid settings for "${namespace}": ${parsed.error.issues.map((issue) => issue.message).join(", ")}`
+  );
+}
+var NullSettings = class {
+  get(_namespace) {
+    return void 0;
+  }
+  parse(_namespace, _schema) {
+    return void 0;
+  }
+  require(namespace, _schema) {
+    throw new Error(`Missing required settings for "${namespace}"`);
+  }
+};
+var StaticSettings = class {
+  constructor(data) {
+    this.data = data;
+  }
+  get(namespace) {
+    const value = this.data[namespace];
+    return value === void 0 ? void 0 : value;
+  }
+  parse(namespace, schema) {
+    const value = this.get(namespace);
+    return value === void 0 ? void 0 : parseSettingsValue(namespace, value, schema);
+  }
+  require(namespace, schema) {
+    const value = this.get(namespace);
+    if (value === void 0) {
+      throw new Error(`Missing required settings for "${namespace}"`);
+    }
+    return parseSettingsValue(namespace, value, schema);
+  }
+};
+var LayeredSettings = class {
+  constructor(layers) {
+    this.layers = layers;
+  }
+  get(namespace) {
+    let resolved;
+    let hasValue = false;
+    for (const layer of this.layers) {
+      const value = layer.get(namespace);
+      if (value !== void 0) {
+        resolved = hasValue ? mergeSettingsValue(resolved, value) : cloneSettingsValue(value);
+        hasValue = true;
+      }
+    }
+    return hasValue ? resolved : void 0;
+  }
+  parse(namespace, schema) {
+    const value = this.get(namespace);
+    return value === void 0 ? void 0 : parseSettingsValue(namespace, value, schema);
+  }
+  require(namespace, schema) {
+    const value = this.get(namespace);
+    if (value === void 0) {
+      throw new Error(`Missing required settings for "${namespace}"`);
+    }
+    return parseSettingsValue(namespace, value, schema);
+  }
+};
+var ValidatedSettings = class {
+  constructor(base, overrides) {
+    this.base = base;
+    this.overrides = overrides;
+  }
+  get(namespace) {
+    if (namespace in this.overrides) {
+      return this.overrides[namespace];
+    }
+    return this.base.get(namespace);
+  }
+  parse(namespace, schema) {
+    if (namespace in this.overrides) {
+      return parseSettingsValue(namespace, this.overrides[namespace], schema);
+    }
+    return this.base.parse(namespace, schema);
+  }
+  require(namespace, schema) {
+    if (namespace in this.overrides) {
+      return parseSettingsValue(namespace, this.overrides[namespace], schema);
+    }
+    return this.base.require(namespace, schema);
+  }
+};
+
+// src/plugin/loader.ts
+import { existsSync } from "fs";
+import fs from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+import { createJiti } from "jiti";
+var DEFAULT_PLUGIN_DIR = ".cuylabs/plugins";
+var LOADABLE_EXTS = /\.(ts|js|mjs|mts)$/;
+var FRAMEWORK_PACKAGES = [
+  "@cuylabs/agent-core",
+  "@cuylabs/agent-code",
+  "@cuylabs/agent-runtime",
+  "@cuylabs/agent-http",
+  "@cuylabs/agent-runtime-dapr"
+];
+var _frameworkAliases;
+function resolveFrameworkAliases() {
+  if (_frameworkAliases) return _frameworkAliases;
+  const aliases = {};
+  for (const specifier of FRAMEWORK_PACKAGES) {
+    const resolved = resolvePackagePath(specifier);
+    if (resolved) {
+      aliases[specifier] = resolved;
+    }
+  }
+  _frameworkAliases = aliases;
+  return aliases;
+}
+function resetFrameworkAliases() {
+  _frameworkAliases = void 0;
+}
+function resolvePackagePath(specifier) {
+  try {
+    const resolved = import.meta.resolve(specifier);
+    if (resolved) {
+      return resolved.startsWith("file://") ? fileURLToPath(resolved) : resolved;
+    }
+  } catch {
+  }
+  try {
+    const thisDir = path.dirname(fileURLToPath(import.meta.url));
+    const packagesRoot = path.resolve(thisDir, "../../../..");
+    const shortName = specifier.replace("@cuylabs/", "");
+    const candidate = path.join(packagesRoot, shortName, "dist", "index.js");
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  } catch {
+  }
+  return void 0;
+}
+var _jiti = /* @__PURE__ */ new Map();
+function getPluginLoader(options = {}) {
+  const key = getPluginLoaderKey(options);
+  const existing = _jiti.get(key);
+  if (existing) {
+    return existing;
+  }
+  const autoAliases = options.autoAlias ?? true ? resolveFrameworkAliases() : {};
+  const mergedAlias = { ...autoAliases, ...options.alias };
+  const loader = createJiti(import.meta.url, {
+    fsCache: true,
+    moduleCache: true,
+    sourceMaps: options.sourceMaps ?? true,
+    interopDefault: true,
+    tryNative: false,
+    debug: options.debug ?? false,
+    alias: mergedAlias,
+    nativeModules: options.nativeModules
+  });
+  _jiti.set(key, loader);
+  return loader;
+}
+function resetPluginLoader() {
+  _jiti.clear();
+}
+async function discoverPlugins(cwd, extraPaths = []) {
+  const results = [];
+  const seen = /* @__PURE__ */ new Set();
+  const pluginDir = path.resolve(cwd, DEFAULT_PLUGIN_DIR);
+  if (existsSync(pluginDir)) {
+    const entries = await fs.readdir(pluginDir, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      if (entry.name.startsWith("_")) continue;
+      if (entry.isFile() && isLoadable(entry.name)) {
+        const absPath = path.join(pluginDir, entry.name);
+        if (!seen.has(absPath)) {
+          seen.add(absPath);
+          results.push({
+            entryPath: absPath,
+            manifest: manifestFromFilename(entry.name)
+          });
+        }
+      } else if (entry.isDirectory()) {
+        const subdir = path.join(pluginDir, entry.name);
+        const nested = await discoverPluginDirectory(subdir, entry.name);
+        for (const plugin of nested) {
+          if (seen.has(plugin.entryPath)) continue;
+          seen.add(plugin.entryPath);
+          results.push(plugin);
+        }
+      }
+    }
+  }
+  for (const p of extraPaths) {
+    const resolved = path.isAbsolute(p) ? p : path.resolve(cwd, p);
+    if (!existsSync(resolved)) {
+      continue;
+    }
+    const stat = await fs.stat(resolved);
+    if (stat.isDirectory()) {
+      const nested = await discoverPluginDirectory(
+        resolved,
+        path.basename(resolved)
+      );
+      for (const plugin of nested) {
+        if (seen.has(plugin.entryPath)) continue;
+        seen.add(plugin.entryPath);
+        results.push(plugin);
+      }
+      continue;
+    }
+    if (!seen.has(resolved)) {
+      seen.add(resolved);
+      results.push({
+        entryPath: resolved,
+        manifest: manifestFromFilename(path.basename(resolved))
+      });
+    }
+  }
+  return results;
+}
+async function loadPluginModule(entryPath, options) {
+  const jiti = getPluginLoader(options);
+  const mod = await jiti.import(entryPath, { default: true });
+  const init = typeof mod === "function" ? mod : mod.default ?? mod;
+  if (typeof init !== "function") {
+    throw new Error(
+      `Plugin at ${entryPath} must default-export a function, got ${typeof init}`
+    );
+  }
+  return init;
+}
+function isLoadable(filename) {
+  return LOADABLE_EXTS.test(filename) && !filename.startsWith("_");
+}
+function getPluginLoaderKey(options) {
+  const alias = options.alias ? Object.fromEntries(
+    Object.entries(options.alias).sort(
+      ([left], [right]) => left.localeCompare(right)
+    )
+  ) : void 0;
+  const nativeModules = options.nativeModules ? [...options.nativeModules].sort() : void 0;
+  return JSON.stringify({
+    alias,
+    nativeModules,
+    sourceMaps: options.sourceMaps ?? true,
+    debug: options.debug ?? false,
+    autoAlias: options.autoAlias ?? true
+  });
+}
+async function discoverPluginDirectory(dir, dirName) {
+  const { manifest, pluginEntries } = await readManifestFromDir(dir, dirName);
+  if (pluginEntries && pluginEntries.length > 0) {
+    return pluginEntries.map((entry, _index, entries) => ({
+      entryPath: path.resolve(dir, entry),
+      manifest: manifestForEntry(manifest, entry, entries.length)
+    }));
+  }
+  const indexPath = await findIndexFile(dir);
+  if (!indexPath) {
+    return [];
+  }
+  return [{ entryPath: indexPath, manifest }];
+}
+async function findIndexFile(dir) {
+  for (const name of ["index.ts", "index.mts", "index.js", "index.mjs"]) {
+    const candidate = path.join(dir, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+function manifestFromFilename(filename) {
+  const stem = filename.replace(/\.[^.]+$/, "");
+  return { id: stem };
+}
+async function readManifestFromDir(dir, dirName) {
+  const pkgPath = path.join(dir, "package.json");
+  if (!existsSync(pkgPath)) {
+    return { manifest: { id: dirName } };
+  }
+  try {
+    const raw = await fs.readFile(pkgPath, "utf-8");
+    const pkg = JSON.parse(raw);
+    const pluginEntries = readPluginEntries(pkg);
+    return {
+      manifest: {
+        id: typeof pkg.name === "string" ? pkg.name : dirName,
+        name: typeof pkg.name === "string" ? pkg.name : void 0,
+        description: typeof pkg.description === "string" ? pkg.description : void 0,
+        version: typeof pkg.version === "string" ? pkg.version : void 0,
+        compatibility: readPluginCompatibility(pkg)
+      },
+      ...pluginEntries ? { pluginEntries } : {}
+    };
+  } catch {
+    return { manifest: { id: dirName } };
+  }
+}
+function readPluginEntries(pkg) {
+  const cuylabs = isRecord(pkg.cuylabs) ? pkg.cuylabs : void 0;
+  const entries = cuylabs?.plugins;
+  if (typeof entries === "string" && entries.length > 0) {
+    return [entries];
+  }
+  if (!Array.isArray(entries)) {
+    return void 0;
+  }
+  const normalized = entries.filter(
+    (entry) => typeof entry === "string" && entry.length > 0
+  );
+  return normalized.length > 0 ? normalized : void 0;
+}
+function readPluginCompatibility(pkg) {
+  const cuylabs = isRecord(pkg.cuylabs) ? pkg.cuylabs : void 0;
+  const rawApiVersion = cuylabs?.apiVersion;
+  const rawEngines = isRecord(pkg.engines) ? pkg.engines : void 0;
+  const rawNode = rawEngines?.node;
+  const compatibility = {
+    ...typeof rawApiVersion === "string" && rawApiVersion.length > 0 ? { apiVersion: rawApiVersion } : {},
+    ...typeof rawNode === "string" && rawNode.length > 0 ? { node: rawNode } : {}
+  };
+  return Object.keys(compatibility).length > 0 ? compatibility : void 0;
+}
+function manifestForEntry(manifest, entry, entryCount) {
+  if (entryCount <= 1) {
+    return manifest;
+  }
+  const suffix = entry.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\.[^.]+$/, "").replace(/\//g, ":");
+  return {
+    ...manifest,
+    id: `${manifest.id}:${suffix || "entry"}`
+  };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// src/plugin/compatibility.ts
+var COMPARATOR_RE = /^(<=|>=|<|>|=)?\s*(\d+(?:\.\d+){0,2})$/;
+function parseVersion(version) {
+  const match = version.trim().match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!match) {
+    return null;
+  }
+  return [
+    Number.parseInt(match[1] ?? "0", 10),
+    Number.parseInt(match[2] ?? "0", 10),
+    Number.parseInt(match[3] ?? "0", 10)
+  ];
+}
+function compareVersions(left, right) {
+  const leftParts = parseVersion(left);
+  const rightParts = parseVersion(right);
+  if (!leftParts || !rightParts) {
+    return null;
+  }
+  for (let i = 0; i < 3; i++) {
+    const delta = leftParts[i] - rightParts[i];
+    if (delta !== 0) {
+      return delta > 0 ? 1 : -1;
+    }
+  }
+  return 0;
+}
+function matchesVersionRequirement(version, requirement) {
+  const clauses = requirement.split(/\s+/).map((part) => part.trim()).filter(Boolean);
+  if (clauses.length === 0) {
+    return true;
+  }
+  return clauses.every((clause) => {
+    const match = clause.match(COMPARATOR_RE);
+    if (!match) {
+      return false;
+    }
+    const [, operator = "=", expected] = match;
+    const comparison = compareVersions(version, expected);
+    if (comparison === null) {
+      return false;
+    }
+    switch (operator) {
+      case ">":
+        return comparison > 0;
+      case ">=":
+        return comparison >= 0;
+      case "<":
+        return comparison < 0;
+      case "<=":
+        return comparison <= 0;
+      case "=":
+        return comparison === 0;
+      default:
+        return false;
+    }
+  });
+}
+function validatePluginCompatibility(options) {
+  const { compatibility, context } = options;
+  if (!compatibility) {
+    return void 0;
+  }
+  if (compatibility.apiVersion !== void 0 && context.apiVersion !== void 0 && compatibility.apiVersion !== context.apiVersion) {
+    return `requires plugin API ${compatibility.apiVersion}, host provides ${context.apiVersion}`;
+  }
+  if (compatibility.node !== void 0 && context.nodeVersion !== void 0 && !matchesVersionRequirement(context.nodeVersion, compatibility.node)) {
+    return `requires Node ${compatibility.node}, current runtime is ${context.nodeVersion}`;
+  }
+  return void 0;
+}
+
+// src/plugin/define.ts
+function definePlugin(def) {
+  const init = (ctx) => {
+    if (def.tools) {
+      for (const tool of def.tools) ctx.addTool(tool);
+    }
+    if (def.middleware) {
+      for (const mw of def.middleware) ctx.addMiddleware(mw);
+    }
+    if (def.commands) {
+      for (const cmd of def.commands) ctx.addCommand(cmd);
+    }
+    if (def.promptSections) {
+      for (const section of def.promptSections) ctx.addPromptSection(section);
+    }
+    if (def.activate) {
+      const activateFn = def.activate;
+      ctx.onActivate(
+        (sessionCtx) => activateFn({
+          ...sessionCtx,
+          events: ctx.events,
+          settings: ctx.settings
+        })
+      );
+    }
+    if (def.deactivate) {
+      ctx.onDeactivate(def.deactivate);
+    }
+    if (def.setup) {
+      return def.setup(ctx);
+    }
+  };
+  init.__definition = def;
+  return init;
+}
+function isDefinedPlugin(init) {
+  return "__definition" in init;
+}
+
+// src/plugin/registry.ts
+var DEFAULT_TIMEOUTS = {
+  load: 3e4,
+  activate: 15e3,
+  deactivate: 1e4
+};
+var PluginRegistry = class {
+  settings;
+  eventBus;
+  loaderOptions;
+  compatibilityContext;
+  timeouts;
+  plugins = [];
+  pluginIds = /* @__PURE__ */ new Set();
+  commandOwners = /* @__PURE__ */ new WeakMap();
+  commandTokens = /* @__PURE__ */ new Map();
+  _contributions = {
+    tools: [],
+    middleware: [],
+    commands: [],
+    promptSections: [],
+    errors: []
+  };
+  activated = false;
+  activeSessionContext;
+  constructor(options = {}) {
+    this.settings = options.settings ?? new NullSettings();
+    this.eventBus = options.events ?? new PluginEventBus();
+    this.loaderOptions = options.loader;
+    this.compatibilityContext = {
+      apiVersion: options.compatibility?.apiVersion ?? "1",
+      nodeVersion: sanitizeNodeVersion(
+        options.compatibility?.nodeVersion ?? process.versions.node
+      ) ?? process.versions.node
+    };
+    this.timeouts = {
+      load: normalizeTimeout(options.timeouts?.load, DEFAULT_TIMEOUTS.load),
+      activate: normalizeTimeout(
+        options.timeouts?.activate,
+        DEFAULT_TIMEOUTS.activate
+      ),
+      deactivate: normalizeTimeout(
+        options.timeouts?.deactivate,
+        DEFAULT_TIMEOUTS.deactivate
+      )
+    };
+  }
+  /** The shared event bus wired to all loaded plugins. */
+  get events() {
+    return this.eventBus;
+  }
+  /** Read-only view of everything plugins have contributed. */
+  get contributions() {
+    return this._contributions;
+  }
+  /** Number of successfully loaded plugins. */
+  get pluginCount() {
+    return this.plugins.length;
+  }
+  /** Get the static definition for a plugin (if it used `definePlugin()`). */
+  getDefinition(pluginId) {
+    return this.plugins.find((p) => p.manifest.id === pluginId)?.definition;
+  }
+  /** Get all static definitions (only for declarative plugins). */
+  get definitions() {
+    return this.plugins.filter((p) => p.definition !== void 0).map((p) => p.definition);
+  }
+  /** Get the plugin ID that contributed a command. */
+  getCommandOwner(command) {
+    return this.commandOwners.get(command);
+  }
+  /** Record a host-level plugin error without throwing. */
+  recordError(pluginId, error) {
+    this._contributions.errors.push({ pluginId, error });
+  }
+  /** Discover, load, and execute all plugins. */
+  async loadAll(cwd, extraPaths) {
+    const discovered = await discoverPlugins(cwd, extraPaths);
+    for (const entry of discovered) {
+      try {
+        const init = await loadPluginModule(
+          entry.entryPath,
+          this.loaderOptions
+        );
+        await this.loadOne(init, entry.manifest, cwd, entry.entryPath);
+      } catch (err) {
+        this.recordError(
+          entry.manifest.id,
+          err instanceof Error ? err.message : String(err)
+        );
+      }
+    }
+  }
+  /** Load a single plugin from its init function (programmatic / tests). */
+  loadOne(init, manifest, cwd, entryPath = "<inline>") {
+    return Promise.resolve(this.executePlugin(init, manifest, entryPath, cwd));
+  }
+  /** Fire `onActivate` hooks sequentially in load order. */
+  async activate(ctx) {
+    if (this.activated) return;
+    this.activated = true;
+    this.activeSessionContext = Object.freeze({ ...ctx });
+    for (const plugin of this.plugins) {
+      await this.runActivateHooks(plugin, this.activeSessionContext);
+    }
+  }
+  /** Fire `onDeactivate` hooks in reverse load order. */
+  async deactivate() {
+    if (!this.activated) return;
+    this.activated = false;
+    this.activeSessionContext = void 0;
+    for (let i = this.plugins.length - 1; i >= 0; i--) {
+      await this.runDeactivateHooks(this.plugins[i]);
+    }
+    this.eventBus.clear();
+  }
+  executePlugin(init, manifest, entryPath, cwd) {
+    const definition = isDefinedPlugin(init) ? init.__definition : void 0;
+    const effectiveManifest = mergePluginManifest(manifest, definition);
+    if (this.pluginIds.has(effectiveManifest.id)) {
+      this.recordError(
+        effectiveManifest.id,
+        `duplicate plugin ID "${effectiveManifest.id}"`
+      );
+      return;
+    }
+    const compatibilityError = validatePluginCompatibility({
+      compatibility: effectiveManifest.compatibility,
+      context: this.compatibilityContext
+    });
+    if (compatibilityError) {
+      this.recordError(
+        effectiveManifest.id,
+        `compatibility check failed: ${compatibilityError}`
+      );
+      return;
+    }
+    const settings = this.resolvePluginSettings(effectiveManifest, definition);
+    if ("error" in settings) {
+      this.recordError(effectiveManifest.id, settings.error);
+      return;
+    }
+    const lifecycle = {
+      activate: [],
+      deactivate: []
+    };
+    const staged = {
+      tools: [],
+      middleware: [],
+      commands: [],
+      promptSections: []
+    };
+    const ctx = {
+      cwd,
+      manifest: Object.freeze({ ...effectiveManifest }),
+      addTool: (tool) => staged.tools.push(tool),
+      addMiddleware: (mw) => staged.middleware.push(mw),
+      addCommand: (cmd) => staged.commands.push(cmd),
+      addPromptSection: (section) => staged.promptSections.push(section),
+      events: this.eventBus,
+      settings: settings.provider,
+      onActivate: (fn) => {
+        lifecycle.activate.push(fn);
+      },
+      onDeactivate: (fn) => {
+        lifecycle.deactivate.push(fn);
+      }
+    };
+    const finalizeLoad = () => {
+      const commandConflict = this.findCommandConflict(
+        effectiveManifest.id,
+        staged.commands
+      );
+      if (commandConflict) {
+        this.recordError(effectiveManifest.id, commandConflict);
+        return;
+      }
+      const loadedPlugin = {
+        manifest: effectiveManifest,
+        entryPath,
+        lifecycle,
+        definition
+      };
+      this.commitPlugin(loadedPlugin, staged);
+      if (this.activated && this.activeSessionContext) {
+        return this.runActivateHooks(loadedPlugin, this.activeSessionContext);
+      }
+    };
+    try {
+      const result = withTimeout(
+        () => init(ctx),
+        this.timeouts.load,
+        `plugin init timed out after ${this.timeouts.load}ms`
+      );
+      if (isPromiseLike(result)) {
+        return result.then(
+          () => finalizeLoad(),
+          (err) => {
+            this.recordError(
+              effectiveManifest.id,
+              err instanceof Error ? err.message : String(err)
+            );
+          }
+        );
+      }
+    } catch (err) {
+      this.recordError(
+        effectiveManifest.id,
+        err instanceof Error ? err.message : String(err)
+      );
+      return;
+    }
+    return finalizeLoad();
+  }
+  resolvePluginSettings(manifest, definition) {
+    const settingsDefinition = definition?.settings;
+    if (!settingsDefinition) {
+      return { provider: this.settings };
+    }
+    const namespace = settingsDefinition.namespace ?? manifest.id;
+    try {
+      const parsed = resolvePluginSettingsValue(
+        this.settings,
+        namespace,
+        settingsDefinition
+      );
+      if (parsed === void 0) {
+        return { provider: this.settings };
+      }
+      return {
+        provider: new ValidatedSettings(this.settings, { [namespace]: parsed })
+      };
+    } catch (err) {
+      return {
+        error: err instanceof Error ? err.message : String(err)
+      };
+    }
+  }
+  findCommandConflict(pluginId, commands) {
+    const seen = /* @__PURE__ */ new Map();
+    for (const command of commands) {
+      const name = normalizeCommandToken(command.name);
+      if (!name) {
+        return `command name cannot be empty`;
+      }
+      const nameConflict = this.checkCommandTokenConflict(
+        pluginId,
+        command.name,
+        name,
+        seen
+      );
+      if (nameConflict) {
+        return nameConflict;
+      }
+      for (const alias of command.alias ?? []) {
+        const normalizedAlias = normalizeCommandToken(alias);
+        if (!normalizedAlias) {
+          return `command alias cannot be empty for "${command.name}"`;
+        }
+        if (normalizedAlias === name) {
+          continue;
+        }
+        const aliasConflict = this.checkCommandTokenConflict(
+          pluginId,
+          alias,
+          normalizedAlias,
+          seen
+        );
+        if (aliasConflict) {
+          return aliasConflict;
+        }
+      }
+    }
+    return void 0;
+  }
+  checkCommandTokenConflict(pluginId, rawToken, normalizedToken, seen) {
+    const existingOwner = this.commandTokens.get(normalizedToken);
+    if (existingOwner) {
+      return `command token "${rawToken}" conflicts with plugin "${existingOwner}"`;
+    }
+    const localOwner = seen.get(normalizedToken);
+    if (localOwner) {
+      return `command token "${rawToken}" is declared multiple times within plugin "${pluginId}"`;
+    }
+    seen.set(normalizedToken, pluginId);
+    return void 0;
+  }
+  commitPlugin(plugin, staged) {
+    this.plugins.push(plugin);
+    this.pluginIds.add(plugin.manifest.id);
+    this._contributions.tools.push(...staged.tools);
+    this._contributions.middleware.push(...staged.middleware);
+    this._contributions.commands.push(...staged.commands);
+    this._contributions.promptSections.push(...staged.promptSections);
+    for (const command of staged.commands) {
+      this.commandOwners.set(command, plugin.manifest.id);
+      this.commandTokens.set(
+        normalizeCommandToken(command.name),
+        plugin.manifest.id
+      );
+      for (const alias of command.alias ?? []) {
+        const normalizedAlias = normalizeCommandToken(alias);
+        if (normalizedAlias) {
+          this.commandTokens.set(normalizedAlias, plugin.manifest.id);
+        }
+      }
+    }
+  }
+  async runActivateHooks(plugin, ctx) {
+    for (const hook of plugin.lifecycle.activate) {
+      try {
+        await withTimeout(
+          () => hook(ctx),
+          this.timeouts.activate,
+          `activate timed out after ${this.timeouts.activate}ms`
+        );
+      } catch (err) {
+        this.recordError(
+          plugin.manifest.id,
+          `activate failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+  async runDeactivateHooks(plugin) {
+    for (let i = plugin.lifecycle.deactivate.length - 1; i >= 0; i--) {
+      try {
+        await withTimeout(
+          () => plugin.lifecycle.deactivate[i](),
+          this.timeouts.deactivate,
+          `deactivate timed out after ${this.timeouts.deactivate}ms`
+        );
+      } catch (err) {
+        this.recordError(
+          plugin.manifest.id,
+          `deactivate failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+};
+function resolvePluginSettingsValue(settings, namespace, definition) {
+  if (definition.optional ?? true) {
+    return settings.parse(namespace, definition.schema);
+  }
+  return settings.require(namespace, definition.schema);
+}
+function mergePluginManifest(manifest, definition) {
+  if (!definition) {
+    return manifest;
+  }
+  return {
+    ...manifest,
+    id: definition.id ?? manifest.id,
+    name: definition.name ?? manifest.name,
+    description: definition.description ?? manifest.description,
+    version: definition.version ?? manifest.version,
+    compatibility: mergeCompatibility(manifest.compatibility, definition.compatibility) ?? manifest.compatibility
+  };
+}
+function mergeCompatibility(manifest, definition) {
+  if (!manifest) return definition;
+  if (!definition) return manifest;
+  return { ...manifest, ...definition };
+}
+function normalizeCommandToken(token) {
+  return token.trim().replace(/^\//, "").toLowerCase();
+}
+function sanitizeNodeVersion(version) {
+  return version?.replace(/^v/, "");
+}
+function normalizeTimeout(timeout, fallback) {
+  if (timeout === false) {
+    return false;
+  }
+  if (typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0) {
+    return timeout;
+  }
+  return fallback;
+}
+function withTimeout(fn, timeoutMs, message) {
+  const result = fn();
+  if (timeoutMs === false) {
+    return result;
+  }
+  if (!isPromiseLike(result)) {
+    return result;
+  }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+    Promise.resolve(result).then(resolve, reject).finally(() => clearTimeout(timer));
+  });
+}
+function isPromiseLike(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+
+export {
+  PluginEventBus,
+  NullSettings,
+  StaticSettings,
+  LayeredSettings,
+  ValidatedSettings,
+  resolveFrameworkAliases,
+  resetFrameworkAliases,
+  getPluginLoader,
+  resetPluginLoader,
+  discoverPlugins,
+  loadPluginModule,
+  definePlugin,
+  isDefinedPlugin,
+  PluginRegistry
+};