@agentmark-ai/shared-utils 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -468,6 +468,44 @@ declare class MastraTransformer implements ScopeTransformer {
     private extractStreamResult;
 }
 
+/**
+ * Transformer for AgentMark spans emitted via OTEL.
+ * Handles GenAI semantic convention attributes and classifies spans.
+ *
+ * Classification rules (per OTEL GenAI conventions):
+ * - GENERATION: Spans that represent actual LLM API calls (chat, text_completion)
+ * - SPAN: All other spans (tool execution, agent invocation, grouping spans)
+ *
+ * Only spans that send requests to the LLM should be GENERATION type.
+ * Wrapper/grouping spans like conversations are regular SPAN type.
+ */
+declare class AgentMarkTransformer implements ScopeTransformer {
+    /**
+     * Classify the span type based on span name and attributes.
+     *
+     * GENERATION type (actual LLM calls):
+     * - Spans starting with "chat " (OTEL convention)
+     * - gen_ai.llm.turn spans (legacy traced module)
+     * - gen_ai.session spans (legacy hooks) - these wrap LLM calls
+     * - Spans with gen_ai.operation.name = "chat" or "text_completion"
+     *
+     * SPAN type (everything else):
+     * - gen_ai.conversation (grouping span)
+     * - execute_tool / gen_ai.tool.call (tool execution)
+     * - invoke_agent / gen_ai.subagent (agent invocation)
+     */
+    classify(span: OtelSpan, attributes: Record<string, any>): SpanType;
+    /**
+     * Transform the span and extract normalized fields from GenAI attributes.
+     */
+    transform(_span: OtelSpan, attributes: Record<string, any>): Partial<NormalizedSpan>;
+}
+/**
+ * The scope name used by AgentMark's OTEL tracer.
+ * Used by the registry to route spans to this transformer.
+ */
+declare const AGENTMARK_SCOPE_NAME = "agentmark";
+
 declare function normalizeSpan(resource: OtelResource, scope: OtelScope, span: OtelSpan): NormalizedSpan;
 /**
  * Normalize spans from raw OTLP resourceSpans structure
@@ -475,4 +513,4 @@ declare function normalizeSpan(resource: OtelResource, scope: OtelScope, span: O
  */
 declare function normalizeOtlpSpans(resourceSpans: OtlpResourceSpans[]): NormalizedSpan[];
 
-export { type AgentmarkConfig, type AgentmarkModelConfig, type AgentmarkModelSchema, type AgentmarkModelSettingsConfig, type AgentmarkModelSettingsSchema, AiSdkTransformer, type AiSdkVersion, type AttributeExtractor, MastraTransformer, type McpServerConfig, type McpServers, type McpStdioServerConfig, type McpUrlServerConfig, type Message, type ModelSettingsTypeAspectRatio, type ModelSettingsTypeImageSize, type ModelSettingsTypeSelect, type ModelSettingsTypeSlider, type NormalizedSpan, type OtelEvent, type OtelLink, type OtelResource, type OtelScope, type OtelSpan, type OtlpAttribute, type OtlpAttributeValue, type OtlpEvent, type OtlpLink, type OtlpResource, type OtlpResourceSpans, type OtlpScope, type OtlpScopeSpans, type OtlpSpan, type ScopeTransformer, SpanType, type StandardMessageContent, type StandardTextContent, type StandardToolCallContent, type StandardToolResultContent, type ToolCall, TransformerRegistry, TypeClassifier, convertOtlpAttributes, createSignature, detectVersion, extractCustomMetadata, extractReasoningFromProviderMetadata, extractResourceScopeSpan, fetchPromptsFrontmatter, findPromptFiles, generateTypeDefinitions, generateUnique8CharString, normalizeOtlpSpans, normalizeSpan, parseAgentMarkAttributes, parseMetadata, parseTokens, registry, toFrontMatter, typeClassifier, verifySignature };
+export { AGENTMARK_SCOPE_NAME, AgentMarkTransformer, type AgentmarkConfig, type AgentmarkModelConfig, type AgentmarkModelSchema, type AgentmarkModelSettingsConfig, type AgentmarkModelSettingsSchema, AiSdkTransformer, type AiSdkVersion, type AttributeExtractor, AgentMarkTransformer as ClaudeAgentTransformer, MastraTransformer, type McpServerConfig, type McpServers, type McpStdioServerConfig, type McpUrlServerConfig, type Message, type ModelSettingsTypeAspectRatio, type ModelSettingsTypeImageSize, type ModelSettingsTypeSelect, type ModelSettingsTypeSlider, type NormalizedSpan, type OtelEvent, type OtelLink, type OtelResource, type OtelScope, type OtelSpan, type OtlpAttribute, type OtlpAttributeValue, type OtlpEvent, type OtlpLink, type OtlpResource, type OtlpResourceSpans, type OtlpScope, type OtlpScopeSpans, type OtlpSpan, type ScopeTransformer, SpanType, type StandardMessageContent, type StandardTextContent, type StandardToolCallContent, type StandardToolResultContent, type ToolCall, TransformerRegistry, TypeClassifier, convertOtlpAttributes, createSignature, detectVersion, extractCustomMetadata, extractReasoningFromProviderMetadata, extractResourceScopeSpan, fetchPromptsFrontmatter, findPromptFiles, generateTypeDefinitions, generateUnique8CharString, normalizeOtlpSpans, normalizeSpan, parseAgentMarkAttributes, parseMetadata, parseTokens, registry, toFrontMatter, typeClassifier, verifySignature };

package/dist/index.d.ts

@@ -468,6 +468,44 @@ declare class MastraTransformer implements ScopeTransformer {
     private extractStreamResult;
 }
 
+/**
+ * Transformer for AgentMark spans emitted via OTEL.
+ * Handles GenAI semantic convention attributes and classifies spans.
+ *
+ * Classification rules (per OTEL GenAI conventions):
+ * - GENERATION: Spans that represent actual LLM API calls (chat, text_completion)
+ * - SPAN: All other spans (tool execution, agent invocation, grouping spans)
+ *
+ * Only spans that send requests to the LLM should be GENERATION type.
+ * Wrapper/grouping spans like conversations are regular SPAN type.
+ */
+declare class AgentMarkTransformer implements ScopeTransformer {
+    /**
+     * Classify the span type based on span name and attributes.
+     *
+     * GENERATION type (actual LLM calls):
+     * - Spans starting with "chat " (OTEL convention)
+     * - gen_ai.llm.turn spans (legacy traced module)
+     * - gen_ai.session spans (legacy hooks) - these wrap LLM calls
+     * - Spans with gen_ai.operation.name = "chat" or "text_completion"
+     *
+     * SPAN type (everything else):
+     * - gen_ai.conversation (grouping span)
+     * - execute_tool / gen_ai.tool.call (tool execution)
+     * - invoke_agent / gen_ai.subagent (agent invocation)
+     */
+    classify(span: OtelSpan, attributes: Record<string, any>): SpanType;
+    /**
+     * Transform the span and extract normalized fields from GenAI attributes.
+     */
+    transform(_span: OtelSpan, attributes: Record<string, any>): Partial<NormalizedSpan>;
+}
+/**
+ * The scope name used by AgentMark's OTEL tracer.
+ * Used by the registry to route spans to this transformer.
+ */
+declare const AGENTMARK_SCOPE_NAME = "agentmark";
+
 declare function normalizeSpan(resource: OtelResource, scope: OtelScope, span: OtelSpan): NormalizedSpan;
 /**
  * Normalize spans from raw OTLP resourceSpans structure
@@ -475,4 +513,4 @@ declare function normalizeSpan(resource: OtelResource, scope: OtelScope, span: O
  */
 declare function normalizeOtlpSpans(resourceSpans: OtlpResourceSpans[]): NormalizedSpan[];
 
-export { type AgentmarkConfig, type AgentmarkModelConfig, type AgentmarkModelSchema, type AgentmarkModelSettingsConfig, type AgentmarkModelSettingsSchema, AiSdkTransformer, type AiSdkVersion, type AttributeExtractor, MastraTransformer, type McpServerConfig, type McpServers, type McpStdioServerConfig, type McpUrlServerConfig, type Message, type ModelSettingsTypeAspectRatio, type ModelSettingsTypeImageSize, type ModelSettingsTypeSelect, type ModelSettingsTypeSlider, type NormalizedSpan, type OtelEvent, type OtelLink, type OtelResource, type OtelScope, type OtelSpan, type OtlpAttribute, type OtlpAttributeValue, type OtlpEvent, type OtlpLink, type OtlpResource, type OtlpResourceSpans, type OtlpScope, type OtlpScopeSpans, type OtlpSpan, type ScopeTransformer, SpanType, type StandardMessageContent, type StandardTextContent, type StandardToolCallContent, type StandardToolResultContent, type ToolCall, TransformerRegistry, TypeClassifier, convertOtlpAttributes, createSignature, detectVersion, extractCustomMetadata, extractReasoningFromProviderMetadata, extractResourceScopeSpan, fetchPromptsFrontmatter, findPromptFiles, generateTypeDefinitions, generateUnique8CharString, normalizeOtlpSpans, normalizeSpan, parseAgentMarkAttributes, parseMetadata, parseTokens, registry, toFrontMatter, typeClassifier, verifySignature };
+export { AGENTMARK_SCOPE_NAME, AgentMarkTransformer, type AgentmarkConfig, type AgentmarkModelConfig, type AgentmarkModelSchema, type AgentmarkModelSettingsConfig, type AgentmarkModelSettingsSchema, AiSdkTransformer, type AiSdkVersion, type AttributeExtractor, AgentMarkTransformer as ClaudeAgentTransformer, MastraTransformer, type McpServerConfig, type McpServers, type McpStdioServerConfig, type McpUrlServerConfig, type Message, type ModelSettingsTypeAspectRatio, type ModelSettingsTypeImageSize, type ModelSettingsTypeSelect, type ModelSettingsTypeSlider, type NormalizedSpan, type OtelEvent, type OtelLink, type OtelResource, type OtelScope, type OtelSpan, type OtlpAttribute, type OtlpAttributeValue, type OtlpEvent, type OtlpLink, type OtlpResource, type OtlpResourceSpans, type OtlpScope, type OtlpScopeSpans, type OtlpSpan, type ScopeTransformer, SpanType, type StandardMessageContent, type StandardTextContent, type StandardToolCallContent, type StandardToolResultContent, type ToolCall, TransformerRegistry, TypeClassifier, convertOtlpAttributes, createSignature, detectVersion, extractCustomMetadata, extractReasoningFromProviderMetadata, extractResourceScopeSpan, fetchPromptsFrontmatter, findPromptFiles, generateTypeDefinitions, generateUnique8CharString, normalizeOtlpSpans, normalizeSpan, parseAgentMarkAttributes, parseMetadata, parseTokens, registry, toFrontMatter, typeClassifier, verifySignature };

package/dist/index.js

@@ -30,7 +30,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AGENTMARK_SCOPE_NAME: () => AGENTMARK_SCOPE_NAME,
+  AgentMarkTransformer: () => AgentMarkTransformer,
   AiSdkTransformer: () => AiSdkTransformer,
+  ClaudeAgentTransformer: () => AgentMarkTransformer,
   MastraTransformer: () => MastraTransformer,
   SpanType: () => SpanType,
   TransformerRegistry: () => TransformerRegistry,
@@ -1333,6 +1336,218 @@ var MastraTransformer = class {
   }
 };
 
+// src/normalizer/extractors/agentmark-parser.ts
+function parseAgentMarkAttributes(attributes, prefix = "agentmark.") {
+  const result = {};
+  const get = (key) => attributes[`${prefix}${key}`];
+  if (get("session_id")) result.sessionId = String(get("session_id"));
+  if (get("session_name")) result.sessionName = String(get("session_name"));
+  if (get("user_id")) result.userId = String(get("user_id"));
+  if (get("trace_name")) result.traceName = String(get("trace_name"));
+  if (get("prompt_name")) result.promptName = String(get("prompt_name"));
+  if (get("props")) result.props = String(get("props"));
+  if (get("dataset_run_id")) result.datasetRunId = String(get("dataset_run_id"));
+  if (get("dataset_run_name")) result.datasetRunName = String(get("dataset_run_name"));
+  if (get("dataset_item_name")) result.datasetItemName = String(get("dataset_item_name"));
+  if (get("dataset_expected_output")) result.datasetExpectedOutput = String(get("dataset_expected_output"));
+  if (get("dataset_path")) result.datasetPath = String(get("dataset_path"));
+  return result;
+}
+
+// src/normalizer/transformers/agentmark/index.ts
+var GenAIAttributes = {
+  SYSTEM: "gen_ai.system",
+  OPERATION_NAME: "gen_ai.operation.name",
+  REQUEST_MODEL: "gen_ai.request.model",
+  REQUEST_MAX_TOKENS: "gen_ai.request.max_tokens",
+  REQUEST_TEMPERATURE: "gen_ai.request.temperature",
+  REQUEST_INPUT: "gen_ai.request.input",
+  RESPONSE_ID: "gen_ai.response.id",
+  RESPONSE_MODEL: "gen_ai.response.model",
+  RESPONSE_OUTPUT: "gen_ai.response.output",
+  RESPONSE_FINISH_REASONS: "gen_ai.response.finish_reasons",
+  USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens",
+  USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens",
+  TOOL_NAME: "gen_ai.tool.name",
+  TOOL_CALL_ID: "gen_ai.tool.call.id",
+  TOOL_INPUT: "gen_ai.tool.input",
+  TOOL_OUTPUT: "gen_ai.tool.output"
+};
+var SpanNames = {
+  // OTEL GenAI standard operation names (these can be followed by model/tool/agent name)
+  CHAT: "chat",
+  EXECUTE_TOOL: "execute_tool",
+  INVOKE_AGENT: "invoke_agent",
+  // Legacy span names (for backwards compatibility)
+  SESSION: "gen_ai.session",
+  TOOL_CALL: "gen_ai.tool.call",
+  SUBAGENT: "gen_ai.subagent",
+  CONVERSATION: "gen_ai.conversation",
+  LLM_TURN: "gen_ai.llm.turn"
+};
+var OperationNames = {
+  CHAT: "chat",
+  EMBEDDINGS: "embeddings",
+  TEXT_COMPLETION: "text_completion",
+  GENERATE_CONTENT: "generate_content",
+  EXECUTE_TOOL: "execute_tool",
+  CREATE_AGENT: "create_agent",
+  INVOKE_AGENT: "invoke_agent"
+};
+var AgentMarkTransformer = class {
+  /**
+   * Classify the span type based on span name and attributes.
+   *
+   * GENERATION type (actual LLM calls):
+   * - Spans starting with "chat " (OTEL convention)
+   * - gen_ai.llm.turn spans (legacy traced module)
+   * - gen_ai.session spans (legacy hooks) - these wrap LLM calls
+   * - Spans with gen_ai.operation.name = "chat" or "text_completion"
+   *
+   * SPAN type (everything else):
+   * - gen_ai.conversation (grouping span)
+   * - execute_tool / gen_ai.tool.call (tool execution)
+   * - invoke_agent / gen_ai.subagent (agent invocation)
+   */
+  classify(span, attributes) {
+    const operationName = attributes[GenAIAttributes.OPERATION_NAME];
+    if (operationName === OperationNames.CHAT || operationName === OperationNames.TEXT_COMPLETION) {
+      return "GENERATION" /* GENERATION */;
+    }
+    if (span.name === SpanNames.CHAT || span.name.startsWith(SpanNames.CHAT + " ")) {
+      return "GENERATION" /* GENERATION */;
+    }
+    if (span.name === SpanNames.LLM_TURN) {
+      return "GENERATION" /* GENERATION */;
+    }
+    if (span.name === SpanNames.SESSION) {
+      return "GENERATION" /* GENERATION */;
+    }
+    if (span.name === SpanNames.EXECUTE_TOOL || span.name.startsWith(SpanNames.EXECUTE_TOOL + " ") || span.name.startsWith(SpanNames.TOOL_CALL)) {
+      return "SPAN" /* SPAN */;
+    }
+    if (span.name === SpanNames.INVOKE_AGENT || span.name.startsWith(SpanNames.INVOKE_AGENT + " ")) {
+      return "SPAN" /* SPAN */;
+    }
+    if (span.name === SpanNames.CONVERSATION || span.name === SpanNames.SUBAGENT) {
+      return "SPAN" /* SPAN */;
+    }
+    if (attributes[GenAIAttributes.SYSTEM] === "anthropic") {
+      if (attributes[GenAIAttributes.USAGE_INPUT_TOKENS] !== void 0 && attributes[GenAIAttributes.RESPONSE_OUTPUT] !== void 0) {
+        return "GENERATION" /* GENERATION */;
+      }
+    }
+    return "SPAN" /* SPAN */;
+  }
+  /**
+   * Transform the span and extract normalized fields from GenAI attributes.
+   */
+  transform(_span, attributes) {
+    const result = {};
+    const responseModel = attributes[GenAIAttributes.RESPONSE_MODEL];
+    const requestModel = attributes[GenAIAttributes.REQUEST_MODEL];
+    if (responseModel) {
+      result.model = String(responseModel);
+    } else if (requestModel) {
+      result.model = String(requestModel);
+    }
+    const inputTokens = attributes[GenAIAttributes.USAGE_INPUT_TOKENS];
+    const outputTokens = attributes[GenAIAttributes.USAGE_OUTPUT_TOKENS];
+    if (typeof inputTokens === "number") {
+      result.inputTokens = inputTokens;
+    }
+    if (typeof outputTokens === "number") {
+      result.outputTokens = outputTokens;
+    }
+    if (result.inputTokens !== void 0 && result.outputTokens !== void 0) {
+      result.totalTokens = result.inputTokens + result.outputTokens;
+    }
+    const finishReasons = attributes[GenAIAttributes.RESPONSE_FINISH_REASONS];
+    if (finishReasons) {
+      try {
+        const reasons = JSON.parse(finishReasons);
+        if (Array.isArray(reasons) && reasons.length > 0) {
+          result.finishReason = String(reasons[0]);
+        }
+      } catch {
+        result.finishReason = String(finishReasons);
+      }
+    }
+    const maxTokens = attributes[GenAIAttributes.REQUEST_MAX_TOKENS];
+    const temperature = attributes[GenAIAttributes.REQUEST_TEMPERATURE];
+    if (maxTokens !== void 0 || temperature !== void 0) {
+      result.settings = {};
+      if (typeof maxTokens === "number") {
+        result.settings.maxTokens = maxTokens;
+      }
+      if (typeof temperature === "number") {
+        result.settings.temperature = temperature;
+      }
+    }
+    const requestInput = attributes[GenAIAttributes.REQUEST_INPUT];
+    if (requestInput && typeof requestInput === "string") {
+      try {
+        const parsed = JSON.parse(requestInput);
+        if (Array.isArray(parsed) && parsed.length > 0) {
+          const isMessagesArray = parsed.every(
+            (item) => item && typeof item === "object" && "role" in item && "content" in item
+          );
+          if (isMessagesArray) {
+            result.input = parsed;
+          } else {
+            result.input = [{ role: "user", content: requestInput }];
+          }
+        } else {
+          result.input = [{ role: "user", content: requestInput }];
+        }
+      } catch {
+        result.input = [{ role: "user", content: requestInput }];
+      }
+    }
+    const responseOutput = attributes[GenAIAttributes.RESPONSE_OUTPUT];
+    if (responseOutput && typeof responseOutput === "string") {
+      result.output = responseOutput;
+    }
+    const toolName = attributes[GenAIAttributes.TOOL_NAME];
+    const toolCallId = attributes[GenAIAttributes.TOOL_CALL_ID];
+    const toolInput = attributes[GenAIAttributes.TOOL_INPUT];
+    const toolOutput = attributes[GenAIAttributes.TOOL_OUTPUT];
+    if (toolName && typeof toolName === "string") {
+      result.name = toolName;
+      const toolCall = {
+        type: "tool-call",
+        toolCallId: typeof toolCallId === "string" ? toolCallId : "",
+        toolName,
+        args: {}
+      };
+      if (toolInput && typeof toolInput === "string") {
+        try {
+          toolCall.args = JSON.parse(toolInput);
+        } catch {
+          toolCall.args = { raw: toolInput };
+        }
+      }
+      if (toolOutput && typeof toolOutput === "string") {
+        toolCall.result = toolOutput;
+      }
+      result.toolCalls = [toolCall];
+    }
+    const agentmarkAttrs = parseAgentMarkAttributes(attributes);
+    const metadataAttrs = parseMetadata(attributes, "agentmark.metadata.");
+    const customMetadata = extractCustomMetadata(attributes, "agentmark.metadata.");
+    return {
+      ...result,
+      ...metadataAttrs,
+      // agentmark.metadata.* values (lower priority)
+      ...agentmarkAttrs,
+      // agentmark.* values (higher priority)
+      // Only include metadata field if there are custom metadata keys
+      ...Object.keys(customMetadata).length > 0 ? { metadata: customMetadata } : {}
+    };
+  }
+};
+var AGENTMARK_SCOPE_NAME = "agentmark";
+
 // src/normalizer/converters/otlp-converter.ts
 function convertOtlpValue(value) {
   var _a;
@@ -1413,21 +1628,6 @@ function extractResourceScopeSpan(resourceSpans) {
   return result;
 }
 
-// src/normalizer/extractors/agentmark-parser.ts
-function parseAgentMarkAttributes(attributes, prefix = "agentmark.") {
-  const result = {};
-  const get = (key) => attributes[`${prefix}${key}`];
-  if (get("session_id")) result.sessionId = String(get("session_id"));
-  if (get("session_name")) result.sessionName = String(get("session_name"));
-  if (get("user_id")) result.userId = String(get("user_id"));
-  if (get("trace_name")) result.traceName = String(get("trace_name"));
-  if (get("dataset_run_id")) result.datasetRunId = String(get("dataset_run_id"));
-  if (get("dataset_run_name")) result.datasetRunName = String(get("dataset_run_name"));
-  if (get("dataset_item_name")) result.datasetItemName = String(get("dataset_item_name"));
-  if (get("dataset_expected_output")) result.datasetExpectedOutput = String(get("dataset_expected_output"));
-  return result;
-}
-
 // src/normalizer/type-classifier.ts
 var TypeClassifier = class {
   classify(span, attributes) {
@@ -1448,6 +1648,7 @@ var typeClassifier = new TypeClassifier();
 // src/normalizer/index.ts
 registry.register("ai", new AiSdkTransformer());
 registry.register("default-tracer", new MastraTransformer());
+registry.register("agentmark", new AgentMarkTransformer());
 registry.setDefault(new AiSdkTransformer());
 function normalizeSpan(resource, scope, span) {
   var _a, _b, _c;
@@ -1518,7 +1719,10 @@ function normalizeOtlpSpans(resourceSpans) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AGENTMARK_SCOPE_NAME,
+  AgentMarkTransformer,
   AiSdkTransformer,
+  ClaudeAgentTransformer,
   MastraTransformer,
   SpanType,
   TransformerRegistry,