@opperai/agents 0.1.1 → 0.1.3

package/dist/index.cjs

@@ -2,6 +2,7 @@
 
 var crypto = require('crypto');
 var zod = require('zod');
+var fs = require('fs');
 var opperai = require('opperai');
 var zodToJsonSchema = require('zod-to-json-schema');
 var index_js = require('@modelcontextprotocol/sdk/client/index.js');
@@ -467,6 +468,229 @@ var createHookManager = (logger) => new HookManager(logger);
 
 // src/base/agent.ts
 init_tool();
+function sanitizeId(name) {
+  return name.replace(/\s/g, "_").replace(/-/g, "_").replace(/\./g, "_").replace(/[()]/g, "");
+}
+function sanitizeLabel(text) {
+  let cleaned = text.replace(/"/g, "'").replace(/\n/g, " ").replace(/`/g, "");
+  cleaned = cleaned.split(".")[0]?.trim() || cleaned.trim();
+  if (cleaned.length > 45) {
+    cleaned = cleaned.substring(0, 42) + "...";
+  }
+  return cleaned;
+}
+function getSchemaName(schema) {
+  if (!schema) {
+    return "N/A";
+  }
+  try {
+    const schemaAny = schema;
+    if (schemaAny.description) {
+      return schemaAny.description;
+    }
+    if (schemaAny._def?.description) {
+      return schemaAny._def.description;
+    }
+    const typeName = schemaAny._def?.typeName;
+    if (typeName === "ZodObject" && schemaAny._def) {
+      const shape = schemaAny._def.shape?.();
+      if (shape && typeof shape === "object") {
+        const keys = Object.keys(shape);
+        if (keys.length > 0) {
+          const keyStr = keys.length > 3 ? `{${keys.slice(0, 3).join(", ")}...}` : `{${keys.join(", ")}}`;
+          return keyStr;
+        }
+      }
+      return "Object";
+    }
+    if (typeName) {
+      return typeName.replace("Zod", "").replace("Type", "");
+    }
+    return "Any";
+  } catch {
+    return "Any";
+  }
+}
+function extractParameters(schema) {
+  if (!schema) {
+    return null;
+  }
+  try {
+    const schemaAny = schema;
+    if (schemaAny._def?.typeName === "ZodObject") {
+      const shape = schemaAny._def.shape?.();
+      if (shape && typeof shape === "object") {
+        const params = [];
+        for (const [key, value] of Object.entries(shape)) {
+          const fieldType = value?._def?.typeName;
+          if (fieldType) {
+            const cleanType = fieldType.replace("Zod", "").toLowerCase();
+            params.push(`${key}: ${cleanType}`);
+          } else {
+            params.push(key);
+          }
+        }
+        return params.length > 0 ? params : null;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function getRegisteredHooks(hooks) {
+  const events = [];
+  const allEvents = Object.values(HookEvents);
+  for (const event of allEvents) {
+    if (hooks.listenerCount(event) > 0) {
+      events.push(event);
+    }
+  }
+  return events;
+}
+function getWrappedAgent(tool2) {
+  const wrapped = tool2.metadata?.["wrappedAgent"];
+  if (wrapped && typeof wrapped === "object" && "name" in wrapped) {
+    return wrapped;
+  }
+  return null;
+}
+function isMcpTool(tool2) {
+  return tool2.metadata?.["provider"] === "mcp";
+}
+async function generateAgentFlowDiagram(agent, options = {}) {
+  const visited = options._visited ?? /* @__PURE__ */ new Set();
+  const isRoot = visited.size === 0;
+  const lines = [];
+  if (isRoot) {
+    lines.push("```mermaid");
+    lines.push("graph TB");
+  }
+  const agentId = sanitizeId(agent.name);
+  if (visited.has(agentId)) {
+    return "";
+  }
+  visited.add(agentId);
+  let agentLabel = `\u{1F916} ${agent.name}`;
+  if (agent.description && agent.description !== `Agent: ${agent.name}` && agent.description !== agent.name) {
+    const desc = sanitizeLabel(agent.description);
+    agentLabel += `<br/><i>${desc}</i>`;
+  }
+  const inputSchemaName = getSchemaName(agent.inputSchema);
+  const outputSchemaName = getSchemaName(agent.outputSchema);
+  agentLabel += `<br/>In: ${inputSchemaName} | Out: ${outputSchemaName}`;
+  lines.push(`    ${agentId}["${agentLabel}"]:::agent`);
+  const agentWithHooks = agent;
+  const registeredHooks = getRegisteredHooks(agentWithHooks.hooks);
+  if (registeredHooks.length > 0) {
+    const hookId = `${agentId}_hooks`;
+    const hookNames = registeredHooks.slice(0, 3).join(", ");
+    const hookLabel = registeredHooks.length > 3 ? `${hookNames} +${registeredHooks.length - 3}` : hookNames;
+    lines.push(`    ${hookId}["\u{1FA9D} ${hookLabel}"]:::hook`);
+    lines.push(`    ${agentId} -.-> ${hookId}`);
+  }
+  const tools = agent.getTools();
+  const regularTools = [];
+  const mcpToolsByServer = /* @__PURE__ */ new Map();
+  const agentTools = [];
+  for (const tool2 of tools) {
+    const wrappedAgent = getWrappedAgent(tool2);
+    if (wrappedAgent) {
+      agentTools.push(tool2);
+    } else if (isMcpTool(tool2)) {
+      const serverName = tool2.metadata?.["server"] ?? "unknown";
+      const serverTools = mcpToolsByServer.get(serverName) ?? [];
+      serverTools.push(tool2);
+      mcpToolsByServer.set(serverName, serverTools);
+    } else {
+      regularTools.push(tool2);
+    }
+  }
+  for (const tool2 of regularTools) {
+    const toolId = sanitizeId(`${agentId}_${tool2.name}`);
+    let toolLabel = `\u2699\uFE0F ${sanitizeLabel(tool2.name)}`;
+    if (tool2.description) {
+      const desc = sanitizeLabel(tool2.description);
+      toolLabel += `<br/><i>${desc}</i>`;
+    }
+    const params = extractParameters(tool2.schema);
+    if (params && params.length > 0) {
+      const paramsStr = params.length > 3 ? `${params.slice(0, 3).join(", ")}...` : params.join(", ");
+      toolLabel += `<br/>(${paramsStr})`;
+    }
+    lines.push(`    ${toolId}["${toolLabel}"]:::tool`);
+    lines.push(`    ${agentId} --> ${toolId}`);
+  }
+  if (mcpToolsByServer.size > 0) {
+    for (const [serverName, serverTools] of mcpToolsByServer.entries()) {
+      if (options.includeMcpTools) {
+        for (const tool2 of serverTools) {
+          const toolId = sanitizeId(`${agentId}_${tool2.name}`);
+          let toolLabel = `\u2699\uFE0F ${sanitizeLabel(tool2.name)}`;
+          if (tool2.description) {
+            const desc = sanitizeLabel(tool2.description);
+            toolLabel += `<br/><i>${desc}</i>`;
+          }
+          toolLabel += `<br/>(MCP: ${sanitizeLabel(serverName)})`;
+          lines.push(`    ${toolId}["${toolLabel}"]:::tool`);
+          lines.push(`    ${agentId} --> ${toolId}`);
+        }
+      } else {
+        const providerId = sanitizeId(`${agentId}_provider_${serverName}`);
+        lines.push(`    ${providerId}["\u{1F50C} ${serverName}"]:::provider`);
+        lines.push(`    ${agentId} --> ${providerId}`);
+      }
+    }
+  }
+  for (const tool2 of agentTools) {
+    const wrappedAgent = getWrappedAgent(tool2);
+    if (wrappedAgent) {
+      const subAgentId = sanitizeId(wrappedAgent.name);
+      lines.push(`    ${agentId} --> ${subAgentId}`);
+      const subDiagram = await generateAgentFlowDiagram(wrappedAgent, {
+        ...options,
+        _visited: visited
+      });
+      const subLines = subDiagram.split("\n").filter(
+        (line) => line && !line.includes("```mermaid") && !line.includes("```") && !line.includes("%% Styling") && !line.includes("classDef")
+      );
+      lines.push(...subLines);
+    }
+  }
+  if (isRoot) {
+    lines.push("");
+    lines.push("    %% Styling - Opper Brand Colors");
+    lines.push(
+      "    classDef agent fill:#8CF0DC,stroke:#1B2E40,stroke-width:3px,color:#1B2E40"
+    );
+    lines.push(
+      "    classDef tool fill:#FFD7D7,stroke:#3C3CAF,stroke-width:2px,color:#1B2E40"
+    );
+    lines.push(
+      "    classDef schema fill:#F8F8F8,stroke:#3C3CAF,stroke-width:2px,color:#1B2E40"
+    );
+    lines.push(
+      "    classDef hook fill:#FFB186,stroke:#3C3CAF,stroke-width:2px,color:#1B2E40"
+    );
+    lines.push(
+      "    classDef provider fill:#8CECF2,stroke:#1B2E40,stroke-width:2px,color:#1B2E40"
+    );
+    lines.push("```");
+  }
+  const diagram = lines.join("\n");
+  if (options.outputPath && isRoot) {
+    let filePath = options.outputPath;
+    if (!filePath.endsWith(".md")) {
+      filePath += ".md";
+    }
+    const fileContent = `# Agent Flow: ${agent.name}
+
+${diagram}`;
+    await fs.promises.writeFile(filePath, fileContent, "utf-8");
+    return filePath;
+  }
+  return diagram;
+}
 var MemoryEntryMetadataSchema = zod.z.object({
   createdAt: zod.z.number(),
   updatedAt: zod.z.number(),
@@ -800,7 +1024,9 @@ var BaseAgent = class {
       ...this.inputSchema && { schema: this.inputSchema },
       metadata: {
         isAgent: true,
-        agentName: this.name
+        agentName: this.name,
+        wrappedAgent: this
+        // Store reference to this agent for visualization
       },
       execute: async (input, executionContext) => {
         try {
@@ -998,6 +1224,30 @@ var BaseAgent = class {
     });
     await Promise.allSettled(teardownPromises);
   }
+  /**
+   * Generate a Mermaid flowchart diagram visualizing the agent's structure and flow.
+   * Shows tools, hooks, schemas, providers, and nested agents.
+   *
+   * @param options - Visualization options
+   * @returns Mermaid markdown string, or file path if outputPath was provided
+   *
+   * @example
+   * ```typescript
+   * // Generate diagram string
+   * const diagram = await agent.visualizeFlow();
+   * console.log(diagram);
+   *
+   * // Save to file
+   * const path = await agent.visualizeFlow({ outputPath: "agent_flow.md" });
+   * console.log(`Saved to ${path}`);
+   *
+   * // Include MCP tools details
+   * const diagram = await agent.visualizeFlow({ includeMcpTools: true });
+   * ```
+   */
+  async visualizeFlow(options) {
+    return generateAgentFlowDiagram(this, options);
+  }
 };
 
 // src/index.ts
@@ -1090,7 +1340,7 @@ var ToolExecutionSummarySchema = zod.z.object({
 
 // package.json
 var package_default = {
-  version: "0.1.1"};
+  version: "0.1.3"};
 
 // src/utils/version.ts
 var SDK_NAME = "@opperai/agents";
@@ -2658,6 +2908,7 @@ exports.createInMemoryStore = createInMemoryStore;
 exports.createMCPServerConfig = createMCPServerConfig;
 exports.createOpperClient = createOpperClient;
 exports.extractTools = extractTools;
+exports.generateAgentFlowDiagram = generateAgentFlowDiagram;
 exports.getDefaultLogger = getDefaultLogger;
 exports.getSchemaDefault = getSchemaDefault;
 exports.isSchemaValid = isSchemaValid;