@radaros/admin 0.3.20 → 0.3.22

package/dist/index.cjs

@@ -0,0 +1,1030 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConfigStore: () => ConfigStore,
+  EntityFactory: () => EntityFactory,
+  ToolkitManager: () => ToolkitManager,
+  createAdminGateway: () => createAdminGateway,
+  createAdminRouter: () => createAdminRouter
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/admin-gateway.ts
+var import_core3 = require("@radaros/core");
+
+// src/config-store.ts
+var NS_AGENTS = "radaros:admin:agents";
+var NS_TEAMS = "radaros:admin:teams";
+var NS_WORKFLOWS = "radaros:admin:workflows";
+var ConfigStore = class {
+  constructor(storage) {
+    this.storage = storage;
+  }
+  async initialize() {
+    await this.storage.initialize?.();
+  }
+  // ── Agents ────────────────────────────────────────────────────────────
+  async saveAgent(blueprint) {
+    await this.storage.set(NS_AGENTS, blueprint.name, blueprint);
+  }
+  async loadAgent(name) {
+    return this.storage.get(NS_AGENTS, name);
+  }
+  async deleteAgent(name) {
+    await this.storage.delete(NS_AGENTS, name);
+  }
+  async listAgents() {
+    const entries = await this.storage.list(NS_AGENTS);
+    return entries.map((e) => e.value);
+  }
+  // ── Teams ─────────────────────────────────────────────────────────────
+  async saveTeam(blueprint) {
+    await this.storage.set(NS_TEAMS, blueprint.name, blueprint);
+  }
+  async loadTeam(name) {
+    return this.storage.get(NS_TEAMS, name);
+  }
+  async deleteTeam(name) {
+    await this.storage.delete(NS_TEAMS, name);
+  }
+  async listTeams() {
+    const entries = await this.storage.list(NS_TEAMS);
+    return entries.map((e) => e.value);
+  }
+  // ── Workflows ─────────────────────────────────────────────────────────
+  async saveWorkflow(blueprint) {
+    await this.storage.set(NS_WORKFLOWS, blueprint.name, blueprint);
+  }
+  async loadWorkflow(name) {
+    return this.storage.get(NS_WORKFLOWS, name);
+  }
+  async deleteWorkflow(name) {
+    await this.storage.delete(NS_WORKFLOWS, name);
+  }
+  async listWorkflows() {
+    const entries = await this.storage.list(NS_WORKFLOWS);
+    return entries.map((e) => e.value);
+  }
+};
+
+// src/entity-factory.ts
+var import_core = require("@radaros/core");
+var EntityFactory = class {
+  toolSource;
+  constructor(toolSource = {}) {
+    this.toolSource = toolSource;
+  }
+  get toolLibrary() {
+    return typeof this.toolSource === "function" ? this.toolSource() : this.toolSource;
+  }
+  createAgent(blueprint) {
+    this.validateProvider(blueprint.provider);
+    const tools = this.resolveTools(blueprint.tools ?? []);
+    const model = import_core.modelRegistry.resolve(blueprint.provider, blueprint.model, blueprint.providerConfig);
+    return new import_core.Agent({
+      name: blueprint.name,
+      model,
+      instructions: blueprint.instructions,
+      tools: tools.length > 0 ? tools : void 0,
+      temperature: blueprint.temperature
+    });
+  }
+  createTeam(blueprint) {
+    this.validateProvider(blueprint.provider);
+    const members = this.resolveMembers(blueprint.members);
+    const mode = this.resolveTeamMode(blueprint.mode);
+    const model = import_core.modelRegistry.resolve(blueprint.provider, blueprint.model, blueprint.providerConfig);
+    return new import_core.Team({
+      name: blueprint.name,
+      mode,
+      model,
+      members,
+      instructions: blueprint.instructions
+    });
+  }
+  /**
+   * Destroy a live entity by removing it from the global registry.
+   * Returns true if found and removed.
+   */
+  destroyAgent(name) {
+    const agent = import_core.registry.getAgent(name);
+    if (!agent) return false;
+    return import_core.registry.remove(agent);
+  }
+  destroyTeam(name) {
+    const team = import_core.registry.getTeam(name);
+    if (!team) return false;
+    return import_core.registry.remove(team);
+  }
+  destroyWorkflow(name) {
+    const workflow = import_core.registry.getWorkflow(name);
+    if (!workflow) return false;
+    return import_core.registry.remove(workflow);
+  }
+  validateProvider(provider) {
+    if (!import_core.modelRegistry.has(provider)) {
+      throw new Error(
+        `Unknown model provider "${provider}". Registered providers can be checked via modelRegistry.has().`
+      );
+    }
+  }
+  resolveTools(toolNames) {
+    const resolved = [];
+    for (const name of toolNames) {
+      const tool = this.toolLibrary[name];
+      if (!tool) {
+        const available = Object.keys(this.toolLibrary).join(", ") || "(none)";
+        throw new Error(`Tool "${name}" not found in toolLibrary. Available: ${available}`);
+      }
+      resolved.push(tool);
+    }
+    return resolved;
+  }
+  resolveMembers(memberNames) {
+    const members = [];
+    for (const name of memberNames) {
+      const agent = import_core.registry.getAgent(name);
+      if (!agent) {
+        const available = import_core.registry.list().agents.join(", ") || "(none)";
+        throw new Error(`Agent "${name}" not found in registry. Available agents: ${available}`);
+      }
+      members.push(agent);
+    }
+    return members;
+  }
+  resolveTeamMode(mode) {
+    const normalized = mode.toLowerCase();
+    const modeMap = {
+      coordinate: import_core.TeamMode.Coordinate,
+      route: import_core.TeamMode.Route,
+      broadcast: import_core.TeamMode.Broadcast,
+      collaborate: import_core.TeamMode.Collaborate,
+      handoff: import_core.TeamMode.Handoff
+    };
+    const resolved = modeMap[normalized];
+    if (!resolved) {
+      throw new Error(`Unknown team mode "${mode}". Expected: ${Object.keys(modeMap).join(", ")}`);
+    }
+    return resolved;
+  }
+};
+
+// src/toolkit-manager.ts
+var import_core2 = require("@radaros/core");
+var NS_TOOLKIT_CONFIGS = "radaros:admin:toolkit-configs";
+function getSecretFields(toolkitId) {
+  const meta = import_core2.toolkitCatalog.get(toolkitId);
+  if (!meta) return /* @__PURE__ */ new Set();
+  const fields = /* @__PURE__ */ new Set();
+  for (const field of meta.configFields) {
+    if (field.secret) fields.add(field.name);
+  }
+  return fields;
+}
+function maskSecrets(cfg) {
+  const secretFields = getSecretFields(cfg.toolkitId);
+  const masked = {};
+  for (const [key, value] of Object.entries(cfg.config)) {
+    if (secretFields.has(key) && typeof value === "string" && value.length > 0) {
+      masked[key] = value.length > 8 ? `${value.slice(0, 4)}${"*".repeat(Math.min(value.length - 4, 20))}` : "********";
+    } else {
+      masked[key] = value;
+    }
+  }
+  return { ...cfg, config: masked };
+}
+var ToolkitManager = class {
+  storage;
+  liveToolkits = /* @__PURE__ */ new Map();
+  mergedToolLibrary = {};
+  constructor(storage) {
+    this.storage = storage;
+  }
+  /* ── Catalog ──────────────────────────────────────────────────── */
+  /** List all available toolkit types from the catalog. */
+  listCatalog() {
+    return import_core2.toolkitCatalog.list();
+  }
+  /** Get a single catalog entry. */
+  getCatalogEntry(id) {
+    return import_core2.toolkitCatalog.get(id);
+  }
+  /* ── Config CRUD ──────────────────────────────────────────────── */
+  /** Save a toolkit config and optionally instantiate it. */
+  async saveConfig(cfg) {
+    if (!import_core2.toolkitCatalog.has(cfg.toolkitId)) {
+      throw new Error(`Unknown toolkit type "${cfg.toolkitId}"`);
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const toSave = {
+      ...cfg,
+      createdAt: cfg.createdAt ?? now,
+      updatedAt: now
+    };
+    await this.storage.set(NS_TOOLKIT_CONFIGS, toSave.instanceName, toSave);
+    if (toSave.enabled) {
+      this.instantiate(toSave);
+    } else {
+      this.deactivate(toSave.instanceName);
+    }
+    return maskSecrets(toSave);
+  }
+  /** Load a toolkit config (masked). */
+  async loadConfig(instanceName) {
+    const raw = await this.storage.get(NS_TOOLKIT_CONFIGS, instanceName);
+    if (!raw) return null;
+    return maskSecrets(raw);
+  }
+  /** Load a toolkit config with raw (unmasked) values — internal use only. */
+  async loadConfigRaw(instanceName) {
+    return this.storage.get(NS_TOOLKIT_CONFIGS, instanceName);
+  }
+  /** List all saved toolkit configs (masked). */
+  async listConfigs() {
+    const entries = await this.storage.list(NS_TOOLKIT_CONFIGS);
+    return entries.map((e) => maskSecrets(e.value));
+  }
+  /** Update a toolkit config (partial). Secret fields are merged, not replaced when omitted. */
+  async updateConfig(instanceName, updates) {
+    const existing = await this.loadConfigRaw(instanceName);
+    if (!existing) {
+      throw new Error(`Toolkit config "${instanceName}" not found`);
+    }
+    const secretFields = getSecretFields(existing.toolkitId);
+    const mergedConfig = { ...existing.config };
+    if (updates.config) {
+      for (const [key, value] of Object.entries(updates.config)) {
+        if (secretFields.has(key) && typeof value === "string" && value.includes("*")) {
+          continue;
+        }
+        mergedConfig[key] = value;
+      }
+    }
+    const updated = {
+      ...existing,
+      config: mergedConfig,
+      enabled: updates.enabled ?? existing.enabled,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    return this.saveConfig(updated);
+  }
+  /** Delete a toolkit config and remove its tools. */
+  async deleteConfig(instanceName) {
+    const existing = await this.loadConfigRaw(instanceName);
+    if (!existing) return false;
+    this.deactivate(instanceName);
+    await this.storage.delete(NS_TOOLKIT_CONFIGS, instanceName);
+    return true;
+  }
+  /* ── Instantiation ────────────────────────────────────────────── */
+  /** Create a live toolkit instance from a config and add its tools. */
+  instantiate(cfg) {
+    try {
+      const tk = import_core2.toolkitCatalog.create(cfg.toolkitId, cfg.config);
+      this.liveToolkits.set(cfg.instanceName, tk);
+      this.rebuildToolLibrary();
+    } catch (error) {
+      throw new Error(`Failed to instantiate toolkit "${cfg.instanceName}": ${error.message}`);
+    }
+  }
+  /** Remove a live toolkit and its tools. */
+  deactivate(instanceName) {
+    if (this.liveToolkits.delete(instanceName)) {
+      this.rebuildToolLibrary();
+    }
+  }
+  /** Rebuild the merged tool library from all active toolkits. */
+  rebuildToolLibrary() {
+    this.mergedToolLibrary = (0, import_core2.collectToolkitTools)(Array.from(this.liveToolkits.values()));
+  }
+  /** Get the current tool library (all tools from active toolkits). */
+  getToolLibrary() {
+    return this.mergedToolLibrary;
+  }
+  /** Get all live toolkit instances. */
+  getLiveToolkits() {
+    return Array.from(this.liveToolkits.values());
+  }
+  /* ── Hydration ────────────────────────────────────────────────── */
+  /**
+   * Load all saved configs from storage and instantiate enabled ones.
+   * Call once at startup.
+   */
+  async hydrate() {
+    const entries = await this.storage.list(NS_TOOLKIT_CONFIGS);
+    let active = 0;
+    const failed = [];
+    for (const entry of entries) {
+      if (entry.value.enabled) {
+        try {
+          this.instantiate(entry.value);
+          active++;
+        } catch {
+          failed.push(entry.value.instanceName);
+        }
+      }
+    }
+    return { total: entries.length, active, failed };
+  }
+};
+
+// src/admin-gateway.ts
+function buildStaticToolLibrary(opts) {
+  const fromToolkits = opts.toolkits ? (0, import_core3.collectToolkitTools)(opts.toolkits) : {};
+  return { ...fromToolkits, ...opts.toolLibrary ?? {} };
+}
+function createAdminGateway(opts) {
+  const staticToolLibrary = buildStaticToolLibrary(opts);
+  const store = new ConfigStore(opts.storage);
+  const tkManager = new ToolkitManager(opts.storage);
+  const getToolLibrary = () => ({
+    ...tkManager.getToolLibrary(),
+    ...staticToolLibrary
+  });
+  const factory = new EntityFactory(getToolLibrary);
+  const ns = opts.io.of(opts.namespace ?? "/radaros-admin");
+  if (opts.authMiddleware) {
+    ns.use(opts.authMiddleware);
+  }
+  ns.on("connection", (socket) => {
+    socket.on("admin.agent.create", async (data, ack) => {
+      try {
+        if (!data.name || !data.provider || !data.model) {
+          return ack?.({ ok: false, error: "name, provider, and model are required" });
+        }
+        const existing = await store.loadAgent(data.name);
+        if (existing) {
+          return ack?.({ ok: false, error: `Agent "${data.name}" already exists` });
+        }
+        const blueprint = {
+          name: data.name,
+          provider: data.provider,
+          model: data.model,
+          instructions: data.instructions,
+          tools: data.tools,
+          temperature: data.temperature,
+          providerConfig: data.providerConfig,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        factory.createAgent(blueprint);
+        await store.saveAgent(blueprint);
+        ns.emit("admin.agent.created", blueprint);
+        ack?.({ ok: true, data: blueprint });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.agent.list", async (_data, ack) => {
+      try {
+        const agents = await store.listAgents();
+        ack?.({ ok: true, data: agents });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.agent.get", async (data, ack) => {
+      try {
+        const blueprint = await store.loadAgent(data.name);
+        if (!blueprint) return ack?.({ ok: false, error: `Agent "${data.name}" not found` });
+        ack?.({ ok: true, data: blueprint });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.agent.update", async (data, ack) => {
+      try {
+        const existing = await store.loadAgent(data.name);
+        if (!existing) return ack?.({ ok: false, error: `Agent "${data.name}" not found` });
+        const updated = {
+          ...existing,
+          ...data,
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        factory.destroyAgent(data.name);
+        factory.createAgent(updated);
+        await store.saveAgent(updated);
+        ns.emit("admin.agent.updated", updated);
+        ack?.({ ok: true, data: updated });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.agent.delete", async (data, ack) => {
+      try {
+        const existing = await store.loadAgent(data.name);
+        if (!existing) return ack?.({ ok: false, error: `Agent "${data.name}" not found` });
+        factory.destroyAgent(data.name);
+        await store.deleteAgent(data.name);
+        ns.emit("admin.agent.deleted", { name: data.name });
+        ack?.({ ok: true, data: { deleted: data.name } });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.team.create", async (data, ack) => {
+      try {
+        if (!data.name || !data.mode || !data.provider || !data.model || !data.members?.length) {
+          return ack?.({ ok: false, error: "name, mode, provider, model, and members[] are required" });
+        }
+        const existing = await store.loadTeam(data.name);
+        if (existing) {
+          return ack?.({ ok: false, error: `Team "${data.name}" already exists` });
+        }
+        const blueprint = {
+          name: data.name,
+          mode: data.mode,
+          provider: data.provider,
+          model: data.model,
+          members: data.members,
+          instructions: data.instructions,
+          providerConfig: data.providerConfig,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        factory.createTeam(blueprint);
+        await store.saveTeam(blueprint);
+        ns.emit("admin.team.created", blueprint);
+        ack?.({ ok: true, data: blueprint });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.team.list", async (_data, ack) => {
+      try {
+        const teams = await store.listTeams();
+        ack?.({ ok: true, data: teams });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.team.get", async (data, ack) => {
+      try {
+        const blueprint = await store.loadTeam(data.name);
+        if (!blueprint) return ack?.({ ok: false, error: `Team "${data.name}" not found` });
+        ack?.({ ok: true, data: blueprint });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.team.update", async (data, ack) => {
+      try {
+        const existing = await store.loadTeam(data.name);
+        if (!existing) return ack?.({ ok: false, error: `Team "${data.name}" not found` });
+        const updated = {
+          ...existing,
+          ...data,
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        factory.destroyTeam(data.name);
+        factory.createTeam(updated);
+        await store.saveTeam(updated);
+        ns.emit("admin.team.updated", updated);
+        ack?.({ ok: true, data: updated });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.team.delete", async (data, ack) => {
+      try {
+        const existing = await store.loadTeam(data.name);
+        if (!existing) return ack?.({ ok: false, error: `Team "${data.name}" not found` });
+        factory.destroyTeam(data.name);
+        await store.deleteTeam(data.name);
+        ns.emit("admin.team.deleted", { name: data.name });
+        ack?.({ ok: true, data: { deleted: data.name } });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.workflow.create", async (data, ack) => {
+      try {
+        if (!data.name) return ack?.({ ok: false, error: "name is required" });
+        const existing = await store.loadWorkflow(data.name);
+        if (existing) return ack?.({ ok: false, error: `Workflow "${data.name}" already exists` });
+        const blueprint = {
+          name: data.name,
+          description: data.description,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        await store.saveWorkflow(blueprint);
+        ns.emit("admin.workflow.created", blueprint);
+        ack?.({ ok: true, data: blueprint });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.workflow.list", async (_data, ack) => {
+      try {
+        const workflows = await store.listWorkflows();
+        ack?.({ ok: true, data: workflows });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.workflow.delete", async (data, ack) => {
+      try {
+        const existing = await store.loadWorkflow(data.name);
+        if (!existing) return ack?.({ ok: false, error: `Workflow "${data.name}" not found` });
+        factory.destroyWorkflow(data.name);
+        await store.deleteWorkflow(data.name);
+        ns.emit("admin.workflow.deleted", { name: data.name });
+        ack?.({ ok: true, data: { deleted: data.name } });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.registry.list", async (_data, ack) => {
+      ack?.({ ok: true, data: import_core3.registry.list() });
+    });
+    socket.on("admin.tools.list", async (_data, ack) => {
+      ack?.({ ok: true, data: (0, import_core3.describeToolLibrary)(getToolLibrary()) });
+    });
+    socket.on("admin.tools.get", async (data, ack) => {
+      const lib = getToolLibrary();
+      const tool = lib[data.name];
+      if (!tool) return ack?.({ ok: false, error: `Tool "${data.name}" not found` });
+      ack?.({
+        ok: true,
+        data: {
+          name: tool.name,
+          description: tool.description,
+          parameters: Object.keys(tool.parameters.shape ?? {})
+        }
+      });
+    });
+    socket.on("admin.toolkit-catalog.list", async (_data, ack) => {
+      ack?.({ ok: true, data: tkManager.listCatalog() });
+    });
+    socket.on("admin.toolkit-catalog.get", async (data, ack) => {
+      const entry = tkManager.getCatalogEntry(data.id);
+      if (!entry) return ack?.({ ok: false, error: `Toolkit type "${data.id}" not found` });
+      ack?.({ ok: true, data: entry });
+    });
+    socket.on("admin.toolkit-config.create", async (data, ack) => {
+      try {
+        if (!data.toolkitId || !data.instanceName) {
+          return ack?.({ ok: false, error: "toolkitId and instanceName are required" });
+        }
+        const existing = await tkManager.loadConfig(data.instanceName);
+        if (existing) {
+          return ack?.({ ok: false, error: `Toolkit config "${data.instanceName}" already exists` });
+        }
+        const config = {
+          toolkitId: data.toolkitId,
+          instanceName: data.instanceName,
+          config: data.config ?? {},
+          enabled: data.enabled !== false
+        };
+        const masked = await tkManager.saveConfig(config);
+        ns.emit("admin.toolkit-config.created", masked);
+        ack?.({ ok: true, data: masked });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.toolkit-config.list", async (_data, ack) => {
+      try {
+        const configs = await tkManager.listConfigs();
+        ack?.({ ok: true, data: configs });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on("admin.toolkit-config.get", async (data, ack) => {
+      try {
+        const cfg = await tkManager.loadConfig(data.instanceName);
+        if (!cfg) return ack?.({ ok: false, error: `Toolkit config "${data.instanceName}" not found` });
+        ack?.({ ok: true, data: cfg });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+    socket.on(
+      "admin.toolkit-config.update",
+      async (data, ack) => {
+        try {
+          const masked = await tkManager.updateConfig(data.instanceName, {
+            config: data.config,
+            enabled: data.enabled
+          });
+          ns.emit("admin.toolkit-config.updated", masked);
+          ack?.({ ok: true, data: masked });
+        } catch (error) {
+          ack?.({ ok: false, error: error.message });
+        }
+      }
+    );
+    socket.on("admin.toolkit-config.delete", async (data, ack) => {
+      try {
+        const deleted = await tkManager.deleteConfig(data.instanceName);
+        if (!deleted) return ack?.({ ok: false, error: `Toolkit config "${data.instanceName}" not found` });
+        ns.emit("admin.toolkit-config.deleted", { instanceName: data.instanceName });
+        ack?.({ ok: true, data: { deleted: data.instanceName } });
+      } catch (error) {
+        ack?.({ ok: false, error: error.message });
+      }
+    });
+  });
+  async function hydrate() {
+    await store.initialize();
+    const tkResult = await tkManager.hydrate();
+    const agentBlueprints = await store.listAgents();
+    for (const bp of agentBlueprints) {
+      if (!import_core3.registry.getAgent(bp.name)) {
+        factory.createAgent(bp);
+      }
+    }
+    const teamBlueprints = await store.listTeams();
+    for (const bp of teamBlueprints) {
+      if (!import_core3.registry.getTeam(bp.name)) {
+        factory.createTeam(bp);
+      }
+    }
+    return {
+      agents: agentBlueprints.length,
+      teams: teamBlueprints.length,
+      workflows: (await store.listWorkflows()).length,
+      toolkits: tkResult
+    };
+  }
+  return { hydrate };
+}
+
+// src/admin-router.ts
+var import_core4 = require("@radaros/core");
+var import_express = require("express");
+function buildStaticToolLibrary2(opts) {
+  const fromToolkits = opts.toolkits ? (0, import_core4.collectToolkitTools)(opts.toolkits) : {};
+  return { ...fromToolkits, ...opts.toolLibrary ?? {} };
+}
+function createAdminRouter(opts) {
+  const staticToolLibrary = buildStaticToolLibrary2(opts);
+  const store = new ConfigStore(opts.storage);
+  const tkManager = new ToolkitManager(opts.storage);
+  const getToolLibrary = () => ({
+    ...tkManager.getToolLibrary(),
+    ...staticToolLibrary
+  });
+  const factory = new EntityFactory(getToolLibrary);
+  const router = (0, import_express.Router)();
+  if (opts.middleware) {
+    for (const mw of opts.middleware) {
+      router.use(mw);
+    }
+  }
+  router.post("/agents", async (req, res) => {
+    try {
+      const body = req.body;
+      if (!body.name || !body.provider || !body.model) {
+        return res.status(400).json({ error: "name, provider, and model are required" });
+      }
+      const existing = await store.loadAgent(body.name);
+      if (existing) {
+        return res.status(409).json({ error: `Agent "${body.name}" already exists` });
+      }
+      const blueprint = {
+        name: body.name,
+        provider: body.provider,
+        model: body.model,
+        instructions: body.instructions,
+        tools: body.tools,
+        temperature: body.temperature,
+        providerConfig: body.providerConfig,
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      factory.createAgent(blueprint);
+      await store.saveAgent(blueprint);
+      res.status(201).json(blueprint);
+    } catch (error) {
+      res.status(422).json({ error: error.message });
+    }
+  });
+  router.get("/agents", async (_req, res) => {
+    try {
+      const agents = await store.listAgents();
+      res.json(agents);
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.get("/agents/:name", async (req, res) => {
+    try {
+      const blueprint = await store.loadAgent(req.params.name);
+      if (!blueprint) {
+        return res.status(404).json({ error: `Agent "${req.params.name}" not found` });
+      }
+      res.json(blueprint);
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.put("/agents/:name", async (req, res) => {
+    try {
+      const name = req.params.name;
+      const existing = await store.loadAgent(name);
+      if (!existing) {
+        return res.status(404).json({ error: `Agent "${name}" not found` });
+      }
+      const body = req.body;
+      const updated = {
+        ...existing,
+        ...body,
+        name,
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      factory.destroyAgent(name);
+      factory.createAgent(updated);
+      await store.saveAgent(updated);
+      res.json(updated);
+    } catch (error) {
+      res.status(422).json({ error: error.message });
+    }
+  });
+  router.delete("/agents/:name", async (req, res) => {
+    try {
+      const name = req.params.name;
+      const existing = await store.loadAgent(name);
+      if (!existing) {
+        return res.status(404).json({ error: `Agent "${name}" not found` });
+      }
+      factory.destroyAgent(name);
+      await store.deleteAgent(name);
+      res.json({ deleted: name });
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.post("/teams", async (req, res) => {
+    try {
+      const body = req.body;
+      if (!body.name || !body.mode || !body.provider || !body.model || !body.members?.length) {
+        return res.status(400).json({ error: "name, mode, provider, model, and members[] are required" });
+      }
+      const existing = await store.loadTeam(body.name);
+      if (existing) {
+        return res.status(409).json({ error: `Team "${body.name}" already exists` });
+      }
+      const blueprint = {
+        name: body.name,
+        mode: body.mode,
+        provider: body.provider,
+        model: body.model,
+        members: body.members,
+        instructions: body.instructions,
+        providerConfig: body.providerConfig,
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      factory.createTeam(blueprint);
+      await store.saveTeam(blueprint);
+      res.status(201).json(blueprint);
+    } catch (error) {
+      res.status(422).json({ error: error.message });
+    }
+  });
+  router.get("/teams", async (_req, res) => {
+    try {
+      const teams = await store.listTeams();
+      res.json(teams);
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.get("/teams/:name", async (req, res) => {
+    try {
+      const blueprint = await store.loadTeam(req.params.name);
+      if (!blueprint) {
+        return res.status(404).json({ error: `Team "${req.params.name}" not found` });
+      }
+      res.json(blueprint);
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.put("/teams/:name", async (req, res) => {
+    try {
+      const name = req.params.name;
+      const existing = await store.loadTeam(name);
+      if (!existing) {
+        return res.status(404).json({ error: `Team "${name}" not found` });
+      }
+      const body = req.body;
+      const updated = {
+        ...existing,
+        ...body,
+        name,
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      factory.destroyTeam(name);
+      factory.createTeam(updated);
+      await store.saveTeam(updated);
+      res.json(updated);
+    } catch (error) {
+      res.status(422).json({ error: error.message });
+    }
+  });
+  router.delete("/teams/:name", async (req, res) => {
+    try {
+      const name = req.params.name;
+      const existing = await store.loadTeam(name);
+      if (!existing) {
+        return res.status(404).json({ error: `Team "${name}" not found` });
+      }
+      factory.destroyTeam(name);
+      await store.deleteTeam(name);
+      res.json({ deleted: name });
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.post("/workflows", async (req, res) => {
+    try {
+      const body = req.body;
+      if (!body.name) {
+        return res.status(400).json({ error: "name is required" });
+      }
+      const existing = await store.loadWorkflow(body.name);
+      if (existing) {
+        return res.status(409).json({ error: `Workflow "${body.name}" already exists` });
+      }
+      const blueprint = {
+        name: body.name,
+        description: body.description,
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await store.saveWorkflow(blueprint);
+      res.status(201).json(blueprint);
+    } catch (error) {
+      res.status(422).json({ error: error.message });
+    }
+  });
+  router.get("/workflows", async (_req, res) => {
+    try {
+      const workflows = await store.listWorkflows();
+      res.json(workflows);
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.get("/workflows/:name", async (req, res) => {
+    try {
+      const blueprint = await store.loadWorkflow(req.params.name);
+      if (!blueprint) {
+        return res.status(404).json({ error: `Workflow "${req.params.name}" not found` });
+      }
+      res.json(blueprint);
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.delete("/workflows/:name", async (req, res) => {
+    try {
+      const name = req.params.name;
+      const existing = await store.loadWorkflow(name);
+      if (!existing) {
+        return res.status(404).json({ error: `Workflow "${name}" not found` });
+      }
+      factory.destroyWorkflow(name);
+      await store.deleteWorkflow(name);
+      res.json({ deleted: name });
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.get("/tools", (_req, res) => {
+    res.json((0, import_core4.describeToolLibrary)(getToolLibrary()));
+  });
+  router.get("/tools/:name", (req, res) => {
+    const lib = getToolLibrary();
+    const tool = lib[req.params.name];
+    if (!tool) return res.status(404).json({ error: `Tool "${req.params.name}" not found` });
+    res.json({
+      name: tool.name,
+      description: tool.description,
+      parameters: Object.keys(tool.parameters.shape ?? {})
+    });
+  });
+  router.get("/toolkit-catalog", (_req, res) => {
+    res.json(tkManager.listCatalog());
+  });
+  router.get("/toolkit-catalog/:id", (req, res) => {
+    const entry = tkManager.getCatalogEntry(req.params.id);
+    if (!entry) return res.status(404).json({ error: `Toolkit type "${req.params.id}" not found` });
+    res.json(entry);
+  });
+  router.post("/toolkit-configs", async (req, res) => {
+    try {
+      const body = req.body;
+      if (!body.toolkitId || !body.instanceName) {
+        return res.status(400).json({ error: "toolkitId and instanceName are required" });
+      }
+      const existing = await tkManager.loadConfig(body.instanceName);
+      if (existing) {
+        return res.status(409).json({ error: `Toolkit config "${body.instanceName}" already exists` });
+      }
+      const config = {
+        toolkitId: body.toolkitId,
+        instanceName: body.instanceName,
+        config: body.config ?? {},
+        enabled: body.enabled !== false
+      };
+      const masked = await tkManager.saveConfig(config);
+      res.status(201).json(masked);
+    } catch (error) {
+      res.status(422).json({ error: error.message });
+    }
+  });
+  router.get("/toolkit-configs", async (_req, res) => {
+    try {
+      const configs = await tkManager.listConfigs();
+      res.json(configs);
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.get("/toolkit-configs/:name", async (req, res) => {
+    try {
+      const cfg = await tkManager.loadConfig(req.params.name);
+      if (!cfg) return res.status(404).json({ error: `Toolkit config "${req.params.name}" not found` });
+      res.json(cfg);
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.put("/toolkit-configs/:name", async (req, res) => {
+    try {
+      const body = req.body;
+      const masked = await tkManager.updateConfig(req.params.name, body);
+      res.json(masked);
+    } catch (error) {
+      if (error.message?.includes("not found")) {
+        res.status(404).json({ error: error.message });
+      } else {
+        res.status(422).json({ error: error.message });
+      }
+    }
+  });
+  router.delete("/toolkit-configs/:name", async (req, res) => {
+    try {
+      const deleted = await tkManager.deleteConfig(req.params.name);
+      if (!deleted) return res.status(404).json({ error: `Toolkit config "${req.params.name}" not found` });
+      res.json({ deleted: req.params.name });
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+  async function hydrate() {
+    await store.initialize();
+    const tkResult = await tkManager.hydrate();
+    const agentBlueprints = await store.listAgents();
+    for (const bp of agentBlueprints) {
+      if (!import_core4.registry.getAgent(bp.name)) {
+        factory.createAgent(bp);
+      }
+    }
+    const teamBlueprints = await store.listTeams();
+    for (const bp of teamBlueprints) {
+      if (!import_core4.registry.getTeam(bp.name)) {
+        factory.createTeam(bp);
+      }
+    }
+    return {
+      agents: agentBlueprints.length,
+      teams: teamBlueprints.length,
+      workflows: (await store.listWorkflows()).length,
+      toolkits: tkResult
+    };
+  }
+  return { router, toolLibrary: staticToolLibrary, toolkitManager: tkManager, hydrate };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConfigStore,
+  EntityFactory,
+  ToolkitManager,
+  createAdminGateway,
+  createAdminRouter
+});

package/dist/index.d.cts

@@ -0,0 +1,227 @@
+import { StorageDriver, ToolDef, Toolkit, ToolkitMeta, Agent, Team } from '@radaros/core';
+import { Router } from 'express';
+
+/**
+ * Serializable agent configuration — no class instances or functions.
+ * Persisted to storage and resolved into a live Agent via EntityFactory.
+ */
+interface AgentBlueprint {
+    name: string;
+    /** Model provider id, e.g. "openai", "anthropic", "google", "ollama" */
+    provider: string;
+    /** Model id, e.g. "gpt-4o", "claude-sonnet-4-20250514" */
+    model: string;
+    instructions?: string;
+    /** Tool names resolved from the toolLibrary at creation time. */
+    tools?: string[];
+    temperature?: number;
+    /** Provider-specific config (apiKey, baseURL, etc.) — passed to modelRegistry.resolve(). */
+    providerConfig?: Record<string, unknown>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * Serializable team configuration.
+ * Members are agent names resolved from the registry at creation time.
+ */
+interface TeamBlueprint {
+    name: string;
+    /** One of: "coordinate", "route", "broadcast", "collaborate", "handoff" */
+    mode: string;
+    provider: string;
+    model: string;
+    /** Agent names — must already exist in the registry. */
+    members: string[];
+    instructions?: string;
+    providerConfig?: Record<string, unknown>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * Serializable workflow configuration.
+ * Workflows with typed state and function steps cannot be fully serialized,
+ * so this is a lightweight placeholder for name-based registration.
+ */
+interface WorkflowBlueprint {
+    name: string;
+    description?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface AdminOptions {
+    /** Storage driver for persisting blueprints across restarts. */
+    storage: StorageDriver;
+    /** Named tools available for agent creation. Users reference tools by key. */
+    toolLibrary?: Record<string, ToolDef>;
+    /**
+     * Toolkit instances whose tools are automatically added to the tool library.
+     * Tools from toolkits are merged with `toolLibrary` (explicit entries take precedence).
+     */
+    toolkits?: Toolkit[];
+    /** Express middleware applied to all admin routes (e.g., auth). */
+    middleware?: any[];
+}
+
+interface AdminGatewayOptions extends AdminOptions {
+    /** Socket.IO server instance. */
+    io: any;
+    /** Socket.IO namespace for admin events. Default: "/radaros-admin" */
+    namespace?: string;
+    /** Socket.IO middleware for authentication. */
+    authMiddleware?: (socket: any, next: (err?: Error) => void) => void;
+}
+/**
+ * Attaches admin CRUD event handlers to a Socket.IO server.
+ */
+declare function createAdminGateway(opts: AdminGatewayOptions): {
+    hydrate: () => Promise<{
+        agents: number;
+        teams: number;
+        workflows: number;
+        toolkits: {
+            total: number;
+            active: number;
+            failed: string[];
+        };
+    }>;
+};
+
+/** Persisted toolkit configuration. */
+interface ToolkitConfig {
+    /** Toolkit id from the catalog (e.g. "github", "slack"). */
+    toolkitId: string;
+    /** User-chosen instance name — allows multiple configs of same type. */
+    instanceName: string;
+    /** Config values (API keys, connection strings, etc.). */
+    config: Record<string, unknown>;
+    /** Whether this toolkit is active (instantiated). */
+    enabled: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** Toolkit config with secret fields masked for API responses. */
+type MaskedToolkitConfig = Omit<ToolkitConfig, "config"> & {
+    config: Record<string, unknown>;
+};
+/**
+ * Manages toolkit configurations: persists credentials, instantiates
+ * toolkits, and maintains a live tool library that agents can use.
+ *
+ * Secret fields (API keys, tokens) are stored as-is in the storage driver
+ * but are always masked in API responses.
+ */
+declare class ToolkitManager {
+    private readonly storage;
+    private readonly liveToolkits;
+    private mergedToolLibrary;
+    constructor(storage: StorageDriver);
+    /** List all available toolkit types from the catalog. */
+    listCatalog(): Omit<ToolkitMeta, "factory">[];
+    /** Get a single catalog entry. */
+    getCatalogEntry(id: string): Omit<ToolkitMeta, "factory"> | undefined;
+    /** Save a toolkit config and optionally instantiate it. */
+    saveConfig(cfg: ToolkitConfig): Promise<MaskedToolkitConfig>;
+    /** Load a toolkit config (masked). */
+    loadConfig(instanceName: string): Promise<MaskedToolkitConfig | null>;
+    /** Load a toolkit config with raw (unmasked) values — internal use only. */
+    private loadConfigRaw;
+    /** List all saved toolkit configs (masked). */
+    listConfigs(): Promise<MaskedToolkitConfig[]>;
+    /** Update a toolkit config (partial). Secret fields are merged, not replaced when omitted. */
+    updateConfig(instanceName: string, updates: Partial<Pick<ToolkitConfig, "config" | "enabled">>): Promise<MaskedToolkitConfig>;
+    /** Delete a toolkit config and remove its tools. */
+    deleteConfig(instanceName: string): Promise<boolean>;
+    /** Create a live toolkit instance from a config and add its tools. */
+    private instantiate;
+    /** Remove a live toolkit and its tools. */
+    private deactivate;
+    /** Rebuild the merged tool library from all active toolkits. */
+    private rebuildToolLibrary;
+    /** Get the current tool library (all tools from active toolkits). */
+    getToolLibrary(): Record<string, ToolDef>;
+    /** Get all live toolkit instances. */
+    getLiveToolkits(): Toolkit[];
+    /**
+     * Load all saved configs from storage and instantiate enabled ones.
+     * Call once at startup.
+     */
+    hydrate(): Promise<{
+        total: number;
+        active: number;
+        failed: string[];
+    }>;
+}
+
+interface AdminRouterResult {
+    /** Express router — mount at your chosen path (e.g., `app.use("/admin", router)`) */
+    router: Router;
+    /** The merged tool library (toolkit tools + explicit toolLibrary + dynamic toolkit configs). */
+    toolLibrary: Record<string, ToolDef>;
+    /** Toolkit manager for programmatic access. */
+    toolkitManager: ToolkitManager;
+    /**
+     * Re-create all persisted entities and toolkit configs into the live registry.
+     * Call once at startup before accepting requests.
+     */
+    hydrate: () => Promise<{
+        agents: number;
+        teams: number;
+        workflows: number;
+        toolkits: {
+            total: number;
+            active: number;
+            failed: string[];
+        };
+    }>;
+}
+declare function createAdminRouter(opts: AdminOptions): AdminRouterResult;
+
+/**
+ * Persists serializable blueprints to a StorageDriver.
+ * All values are plain JSON — no class instances.
+ */
+declare class ConfigStore {
+    private readonly storage;
+    constructor(storage: StorageDriver);
+    initialize(): Promise<void>;
+    saveAgent(blueprint: AgentBlueprint): Promise<void>;
+    loadAgent(name: string): Promise<AgentBlueprint | null>;
+    deleteAgent(name: string): Promise<void>;
+    listAgents(): Promise<AgentBlueprint[]>;
+    saveTeam(blueprint: TeamBlueprint): Promise<void>;
+    loadTeam(name: string): Promise<TeamBlueprint | null>;
+    deleteTeam(name: string): Promise<void>;
+    listTeams(): Promise<TeamBlueprint[]>;
+    saveWorkflow(blueprint: WorkflowBlueprint): Promise<void>;
+    loadWorkflow(name: string): Promise<WorkflowBlueprint | null>;
+    deleteWorkflow(name: string): Promise<void>;
+    listWorkflows(): Promise<WorkflowBlueprint[]>;
+}
+
+/**
+ * Resolves serializable blueprints into live Agent/Team instances
+ * that auto-register into the global registry.
+ *
+ * The `toolSource` can be a static record or a function that returns one,
+ * enabling dynamic tool libraries that grow as toolkit configs are added.
+ */
+declare class EntityFactory {
+    private readonly toolSource;
+    constructor(toolSource?: (() => Record<string, ToolDef>) | Record<string, ToolDef>);
+    private get toolLibrary();
+    createAgent(blueprint: AgentBlueprint): Agent;
+    createTeam(blueprint: TeamBlueprint): Team;
+    /**
+     * Destroy a live entity by removing it from the global registry.
+     * Returns true if found and removed.
+     */
+    destroyAgent(name: string): boolean;
+    destroyTeam(name: string): boolean;
+    destroyWorkflow(name: string): boolean;
+    private validateProvider;
+    private resolveTools;
+    private resolveMembers;
+    private resolveTeamMode;
+}
+
+export { type AdminGatewayOptions, type AdminOptions, type AdminRouterResult, type AgentBlueprint, ConfigStore, EntityFactory, type MaskedToolkitConfig, type TeamBlueprint, type ToolkitConfig, ToolkitManager, type WorkflowBlueprint, createAdminGateway, createAdminRouter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radaros/admin",
-  "version": "0.3.20",
+  "version": "0.3.22",
   "description": "Admin CRUD API for dynamically creating, updating, and deleting RadarOS agents, teams, and workflows at runtime",
   "license": "MIT",
   "repository": {
@@ -17,20 +17,23 @@
     "radaros"
   ],
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
     }
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
@@ -39,7 +42,7 @@
     "typescript": "^5.6.0"
   },
   "peerDependencies": {
-    "@radaros/core": "^0.3.20",
+    "@radaros/core": "^0.3.22",
     "@types/express": "^4.0.0 || ^5.0.0",
     "express": "^4.0.0 || ^5.0.0",
     "socket.io": "^4.0.0"