@contractspec/lib.ai-agent 2.0.0 → 2.1.0

package/dist/node/telemetry/index.js

@@ -14,24 +14,78 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/telemetry/adapter.ts
 function parseAgentId(agentId) {
-  const match = agentId.match(/^(.+)\.v(\s+)$/);
+  const match = agentId.match(/^(.+)\.v(\d+)$/);
   if (match) {
     return { name: match[1], version: match[2] };
   }
   return { name: agentId, version: "1.0.0" };
 }
-async function trackAgentStep(collector, agentId, step, durationMs) {
+function getRecord(value) {
+  return value && typeof value === "object" ? value : undefined;
+}
+function getStepResponse(step) {
+  const response = getRecord(step.response);
+  if (!response)
+    return;
+  return {
+    id: response["id"],
+    modelId: response["modelId"],
+    timestamp: response["timestamp"],
+    headers: response["headers"],
+    body: response["body"],
+    messages: response["messages"]
+  };
+}
+function getRequestBodyValue(request, key) {
+  const body = request?.["body"];
+  if (!body)
+    return;
+  if (typeof body === "string") {
+    try {
+      const parsed = JSON.parse(body);
+      return typeof parsed[key] === "string" ? parsed[key] : undefined;
+    } catch {
+      return;
+    }
+  }
+  const record = getRecord(body);
+  return typeof record?.[key] === "string" ? record[key] : undefined;
+}
+async function trackAgentStep(collector, agentId, step, durationMs, context) {
   const { name, version } = parseAgentId(agentId);
+  const response = getStepResponse(step);
+  const providerMetadata = step.providerMetadata;
+  const warnings = step.warnings;
+  const rawFinishReason = step.rawFinishReason;
+  const request = getRecord(step.request);
+  const traceId = context?.traceId ?? getRequestBodyValue(request, "$ai_trace_id");
+  const sessionId = context?.sessionId ?? getRequestBodyValue(request, "$ai_session_id");
+  const parentSpanId = response?.id;
   for (const toolCall of step.toolCalls ?? []) {
+    const toolResult = step.toolResults?.find((r) => r.toolCallId === toolCall.toolCallId);
+    const toolError = getRecord(toolResult?.output)?.["error"];
     const toolSample = {
       operation: { name: `${name}.${toolCall.toolName}`, version },
       durationMs: durationMs ?? 0,
       success: step.toolResults?.some((r) => r.toolCallId === toolCall.toolCallId && r.output !== undefined) ?? false,
       timestamp: new Date,
       metadata: {
+        telemetryEvent: "span",
+        traceId,
+        sessionId,
+        spanId: toolCall.toolCallId,
+        parentSpanId,
+        spanName: `tool.${toolCall.toolName}`,
         agentId,
+        actorId: context?.actorId,
+        tenantId: context?.tenantId,
+        stepIndex: context?.stepIndex,
         toolName: toolCall.toolName,
-        finishReason: step.finishReason
+        toolCallArgs: toolCall.input,
+        toolResultOutput: toolResult?.output,
+        errorMessage: typeof toolError === "string" ? toolError : typeof toolResult?.output === "string" ? toolResult.output : undefined,
+        finishReason: step.finishReason,
+        rawFinishReason
       }
     };
     await collector.collect(toolSample);
@@ -42,10 +96,36 @@ async function trackAgentStep(collector, agentId, step, durationMs) {
     success: step.finishReason !== "error",
     timestamp: new Date,
     metadata: {
+      telemetryEvent: "generation",
+      traceId,
+      sessionId,
+      spanId: response?.id,
+      spanName: `agent.${name}.step`,
       agentId,
+      actorId: context?.actorId,
+      tenantId: context?.tenantId,
+      stepIndex: context?.stepIndex,
+      stepStartedAt: context?.stepStartedAt,
       finishReason: step.finishReason,
+      rawFinishReason,
       tokenUsage: step.usage,
-      toolCallCount: step.toolCalls?.length ?? 0
+      totalUsage: step.totalUsage,
+      providerMetadata,
+      warnings,
+      stepText: step.text,
+      stepReasoningText: step.reasoningText,
+      responseId: response?.id,
+      responseModelId: response?.modelId,
+      responseTimestamp: response?.timestamp,
+      responseHeaders: response?.headers,
+      responseBody: response?.body,
+      responseMessages: response?.messages,
+      requestBody: request?.["body"],
+      requestHeaders: request?.["headers"],
+      toolCallCount: step.toolCalls?.length ?? 0,
+      toolCalls: step.toolCalls,
+      toolResults: step.toolResults,
+      errorMessage: step.finishReason === "error" ? step.text : undefined
     }
   };
   await collector.collect(stepSample);
@@ -105,23 +185,60 @@ class PostHogTelemetryCollector {
   }
   async collect(sample) {
     const client = await this.getClient();
-    const distinctId = this.config.defaults?.posthogDistinctId ?? sample.metadata?.["actorId"] ?? "system";
+    const metadata = asRecord(sample.metadata);
+    const distinctId = this.config.defaults?.posthogDistinctId ?? asString(metadata["actorId"]) ?? "system";
+    const traceId = asString(metadata["traceId"]) ?? this.config.defaults?.posthogTraceId;
+    const sessionId = asString(metadata["sessionId"]);
+    const telemetryEvent = asString(metadata["telemetryEvent"]);
+    const event = telemetryEvent === "span" ? "$ai_span" : "$ai_generation";
+    const tokenUsage = metadata["tokenUsage"];
+    const totalUsage = metadata["totalUsage"];
+    const errorMessage = asString(metadata["errorMessage"]);
     client.capture({
       distinctId,
-      event: "$ai_generation",
+      event,
       properties: {
-        $ai_model: sample.operation.name,
-        $ai_provider: "contractspec",
+        $ai_model: asString(metadata["responseModelId"]) ?? sample.operation.name,
+        $ai_provider: asString(metadata["provider"]) ?? "contractspec",
         $ai_latency: sample.durationMs / 1000,
         $ai_is_error: !sample.success,
-        $ai_trace_id: this.config.defaults?.posthogTraceId,
-        ...sample.metadata?.["tokenUsage"] ? mapTokenUsage(sample.metadata["tokenUsage"]) : {},
+        $ai_error: !sample.success ? errorMessage : undefined,
+        $ai_trace_id: traceId,
+        $ai_session_id: sessionId,
+        $ai_span_id: asString(metadata["spanId"]),
+        $ai_parent_id: asString(metadata["parentSpanId"]),
+        $ai_span_name: asString(metadata["spanName"]) ?? sample.operation.name,
+        ...tokenUsage ? mapTokenUsage(tokenUsage) : {},
+        ...totalUsage ? mapTotalUsage(totalUsage) : {},
+        $ai_http_status: asNumber(metadata["httpStatus"]),
+        $ai_request_url: asString(metadata["requestUrl"]),
+        $ai_base_url: asString(metadata["baseUrl"]),
         ...this.config.defaults?.posthogProperties,
         contractspec_operation: sample.operation.name,
         contractspec_version: sample.operation.version,
-        contractspec_agent_id: sample.metadata?.["agentId"],
-        contractspec_finish_reason: sample.metadata?.["finishReason"],
-        contractspec_tool_count: sample.metadata?.["toolCallCount"]
+        contractspec_agent_id: asString(metadata["agentId"]),
+        contractspec_tenant_id: asString(metadata["tenantId"]),
+        contractspec_actor_id: asString(metadata["actorId"]),
+        contractspec_step_index: asNumber(metadata["stepIndex"]),
+        contractspec_step_started_at: asDateIso(metadata["stepStartedAt"]),
+        contractspec_finish_reason: asString(metadata["finishReason"]),
+        contractspec_finish_reason_raw: asString(metadata["rawFinishReason"]),
+        contractspec_tool_count: asNumber(metadata["toolCallCount"]),
+        contractspec_tool_name: asString(metadata["toolName"]),
+        contractspec_tool_call_args: metadata["toolCallArgs"],
+        contractspec_tool_result_output: metadata["toolResultOutput"],
+        contractspec_provider_metadata: metadata["providerMetadata"],
+        contractspec_step_warnings: metadata["warnings"],
+        contractspec_response_id: asString(metadata["responseId"]),
+        contractspec_response_model_id: asString(metadata["responseModelId"]),
+        contractspec_response_timestamp: asDateIso(metadata["responseTimestamp"]),
+        contractspec_response_headers: metadata["responseHeaders"],
+        contractspec_response_body: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["responseBody"],
+        contractspec_response_messages: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["responseMessages"],
+        contractspec_request_headers: metadata["requestHeaders"],
+        contractspec_request_body: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["requestBody"],
+        contractspec_step_text: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["stepText"],
+        contractspec_step_reasoning_text: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["stepReasoningText"]
       },
       groups: this.config.defaults?.posthogGroups
     });
@@ -182,11 +299,44 @@ async function resolvePostHogClient(config) {
   }
 }
 function mapTokenUsage(usage) {
+  const usageRecord = asRecord(usage);
+  const inputTokenDetails = asRecord(usageRecord["inputTokenDetails"]);
+  const outputTokenDetails = asRecord(usageRecord["outputTokenDetails"]);
   return {
-    $ai_input_tokens: usage["promptTokens"],
-    $ai_output_tokens: usage["completionTokens"]
+    $ai_input_tokens: asNumber(usageRecord["inputTokens"]) ?? asNumber(usageRecord["promptTokens"]),
+    $ai_output_tokens: asNumber(usageRecord["outputTokens"]) ?? asNumber(usageRecord["completionTokens"]),
+    $ai_reasoning_tokens: asNumber(outputTokenDetails["reasoningTokens"]) ?? asNumber(usageRecord["reasoningTokens"]),
+    $ai_cache_read_input_tokens: asNumber(inputTokenDetails["cacheReadTokens"]) ?? asNumber(usageRecord["cachedInputTokens"]),
+    $ai_cache_creation_input_tokens: asNumber(inputTokenDetails["cacheWriteTokens"]),
+    $ai_usage: maybeRecord(usageRecord["raw"]) ?? usageRecord
   };
 }
+function mapTotalUsage(usage) {
+  const usageRecord = asRecord(usage);
+  return {
+    contractspec_total_input_tokens: asNumber(usageRecord["inputTokens"]),
+    contractspec_total_output_tokens: asNumber(usageRecord["outputTokens"]),
+    contractspec_total_tokens: asNumber(usageRecord["totalTokens"]),
+    contractspec_total_usage_raw: maybeRecord(usageRecord["raw"]) ?? usageRecord
+  };
+}
+function asRecord(value) {
+  return value && typeof value === "object" ? value : {};
+}
+function maybeRecord(value) {
+  return value && typeof value === "object" ? value : undefined;
+}
+function asString(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function asNumber(value) {
+  return typeof value === "number" ? value : undefined;
+}
+function asDateIso(value) {
+  if (value instanceof Date)
+    return value.toISOString();
+  return;
+}
 // src/telemetry/index.ts
 init_adapter();
 export {

package/dist/node/telemetry/posthog.js

@@ -41,23 +41,60 @@ class PostHogTelemetryCollector {
   }
   async collect(sample) {
     const client = await this.getClient();
-    const distinctId = this.config.defaults?.posthogDistinctId ?? sample.metadata?.["actorId"] ?? "system";
+    const metadata = asRecord(sample.metadata);
+    const distinctId = this.config.defaults?.posthogDistinctId ?? asString(metadata["actorId"]) ?? "system";
+    const traceId = asString(metadata["traceId"]) ?? this.config.defaults?.posthogTraceId;
+    const sessionId = asString(metadata["sessionId"]);
+    const telemetryEvent = asString(metadata["telemetryEvent"]);
+    const event = telemetryEvent === "span" ? "$ai_span" : "$ai_generation";
+    const tokenUsage = metadata["tokenUsage"];
+    const totalUsage = metadata["totalUsage"];
+    const errorMessage = asString(metadata["errorMessage"]);
     client.capture({
       distinctId,
-      event: "$ai_generation",
+      event,
       properties: {
-        $ai_model: sample.operation.name,
-        $ai_provider: "contractspec",
+        $ai_model: asString(metadata["responseModelId"]) ?? sample.operation.name,
+        $ai_provider: asString(metadata["provider"]) ?? "contractspec",
         $ai_latency: sample.durationMs / 1000,
         $ai_is_error: !sample.success,
-        $ai_trace_id: this.config.defaults?.posthogTraceId,
-        ...sample.metadata?.["tokenUsage"] ? mapTokenUsage(sample.metadata["tokenUsage"]) : {},
+        $ai_error: !sample.success ? errorMessage : undefined,
+        $ai_trace_id: traceId,
+        $ai_session_id: sessionId,
+        $ai_span_id: asString(metadata["spanId"]),
+        $ai_parent_id: asString(metadata["parentSpanId"]),
+        $ai_span_name: asString(metadata["spanName"]) ?? sample.operation.name,
+        ...tokenUsage ? mapTokenUsage(tokenUsage) : {},
+        ...totalUsage ? mapTotalUsage(totalUsage) : {},
+        $ai_http_status: asNumber(metadata["httpStatus"]),
+        $ai_request_url: asString(metadata["requestUrl"]),
+        $ai_base_url: asString(metadata["baseUrl"]),
         ...this.config.defaults?.posthogProperties,
         contractspec_operation: sample.operation.name,
         contractspec_version: sample.operation.version,
-        contractspec_agent_id: sample.metadata?.["agentId"],
-        contractspec_finish_reason: sample.metadata?.["finishReason"],
-        contractspec_tool_count: sample.metadata?.["toolCallCount"]
+        contractspec_agent_id: asString(metadata["agentId"]),
+        contractspec_tenant_id: asString(metadata["tenantId"]),
+        contractspec_actor_id: asString(metadata["actorId"]),
+        contractspec_step_index: asNumber(metadata["stepIndex"]),
+        contractspec_step_started_at: asDateIso(metadata["stepStartedAt"]),
+        contractspec_finish_reason: asString(metadata["finishReason"]),
+        contractspec_finish_reason_raw: asString(metadata["rawFinishReason"]),
+        contractspec_tool_count: asNumber(metadata["toolCallCount"]),
+        contractspec_tool_name: asString(metadata["toolName"]),
+        contractspec_tool_call_args: metadata["toolCallArgs"],
+        contractspec_tool_result_output: metadata["toolResultOutput"],
+        contractspec_provider_metadata: metadata["providerMetadata"],
+        contractspec_step_warnings: metadata["warnings"],
+        contractspec_response_id: asString(metadata["responseId"]),
+        contractspec_response_model_id: asString(metadata["responseModelId"]),
+        contractspec_response_timestamp: asDateIso(metadata["responseTimestamp"]),
+        contractspec_response_headers: metadata["responseHeaders"],
+        contractspec_response_body: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["responseBody"],
+        contractspec_response_messages: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["responseMessages"],
+        contractspec_request_headers: metadata["requestHeaders"],
+        contractspec_request_body: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["requestBody"],
+        contractspec_step_text: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["stepText"],
+        contractspec_step_reasoning_text: this.config.defaults?.posthogPrivacyMode ? undefined : metadata["stepReasoningText"]
       },
       groups: this.config.defaults?.posthogGroups
     });
@@ -118,11 +155,44 @@ async function resolvePostHogClient(config) {
   }
 }
 function mapTokenUsage(usage) {
+  const usageRecord = asRecord(usage);
+  const inputTokenDetails = asRecord(usageRecord["inputTokenDetails"]);
+  const outputTokenDetails = asRecord(usageRecord["outputTokenDetails"]);
   return {
-    $ai_input_tokens: usage["promptTokens"],
-    $ai_output_tokens: usage["completionTokens"]
+    $ai_input_tokens: asNumber(usageRecord["inputTokens"]) ?? asNumber(usageRecord["promptTokens"]),
+    $ai_output_tokens: asNumber(usageRecord["outputTokens"]) ?? asNumber(usageRecord["completionTokens"]),
+    $ai_reasoning_tokens: asNumber(outputTokenDetails["reasoningTokens"]) ?? asNumber(usageRecord["reasoningTokens"]),
+    $ai_cache_read_input_tokens: asNumber(inputTokenDetails["cacheReadTokens"]) ?? asNumber(usageRecord["cachedInputTokens"]),
+    $ai_cache_creation_input_tokens: asNumber(inputTokenDetails["cacheWriteTokens"]),
+    $ai_usage: maybeRecord(usageRecord["raw"]) ?? usageRecord
   };
 }
+function mapTotalUsage(usage) {
+  const usageRecord = asRecord(usage);
+  return {
+    contractspec_total_input_tokens: asNumber(usageRecord["inputTokens"]),
+    contractspec_total_output_tokens: asNumber(usageRecord["outputTokens"]),
+    contractspec_total_tokens: asNumber(usageRecord["totalTokens"]),
+    contractspec_total_usage_raw: maybeRecord(usageRecord["raw"]) ?? usageRecord
+  };
+}
+function asRecord(value) {
+  return value && typeof value === "object" ? value : {};
+}
+function maybeRecord(value) {
+  return value && typeof value === "object" ? value : undefined;
+}
+function asString(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function asNumber(value) {
+  return typeof value === "number" ? value : undefined;
+}
+function asDateIso(value) {
+  if (value instanceof Date)
+    return value.toISOString();
+  return;
+}
 export {
   createPostHogTracedModel,
   createPostHogTelemetryCollector,

package/dist/telemetry/adapter.d.ts

@@ -26,6 +26,14 @@ export interface TelemetryCollector {
      */
     collect(sample: OperationMetricSample): Promise<void>;
 }
+interface TrackAgentStepContext {
+    sessionId?: string;
+    tenantId?: string;
+    actorId?: string;
+    traceId?: string;
+    stepIndex?: number;
+    stepStartedAt?: Date;
+}
 /**
  * Track an agent step for telemetry.
  *
@@ -37,7 +45,7 @@ export interface TelemetryCollector {
  * @param step - AI SDK step result
  * @param durationMs - Optional step duration in milliseconds
  */
-export declare function trackAgentStep(collector: TelemetryCollector, agentId: string, step: StepResult<ToolSet>, durationMs?: number): Promise<void>;
+export declare function trackAgentStep(collector: TelemetryCollector, agentId: string, step: StepResult<ToolSet>, durationMs?: number, context?: TrackAgentStepContext): Promise<void>;
 /**
  * In-memory telemetry collector for testing.
  */
@@ -65,3 +73,4 @@ export declare function createInMemoryTelemetryCollector(): InMemoryTelemetryCol
  * No-op telemetry collector that discards all metrics.
  */
 export declare const noopTelemetryCollector: TelemetryCollector;
+export {};

package/dist/telemetry/adapter.js

@@ -14,24 +14,78 @@ var __require = import.meta.require;
 
 // src/telemetry/adapter.ts
 function parseAgentId(agentId) {
-  const match = agentId.match(/^(.+)\.v(\s+)$/);
+  const match = agentId.match(/^(.+)\.v(\d+)$/);
   if (match) {
     return { name: match[1], version: match[2] };
   }
   return { name: agentId, version: "1.0.0" };
 }
-async function trackAgentStep(collector, agentId, step, durationMs) {
+function getRecord(value) {
+  return value && typeof value === "object" ? value : undefined;
+}
+function getStepResponse(step) {
+  const response = getRecord(step.response);
+  if (!response)
+    return;
+  return {
+    id: response["id"],
+    modelId: response["modelId"],
+    timestamp: response["timestamp"],
+    headers: response["headers"],
+    body: response["body"],
+    messages: response["messages"]
+  };
+}
+function getRequestBodyValue(request, key) {
+  const body = request?.["body"];
+  if (!body)
+    return;
+  if (typeof body === "string") {
+    try {
+      const parsed = JSON.parse(body);
+      return typeof parsed[key] === "string" ? parsed[key] : undefined;
+    } catch {
+      return;
+    }
+  }
+  const record = getRecord(body);
+  return typeof record?.[key] === "string" ? record[key] : undefined;
+}
+async function trackAgentStep(collector, agentId, step, durationMs, context) {
   const { name, version } = parseAgentId(agentId);
+  const response = getStepResponse(step);
+  const providerMetadata = step.providerMetadata;
+  const warnings = step.warnings;
+  const rawFinishReason = step.rawFinishReason;
+  const request = getRecord(step.request);
+  const traceId = context?.traceId ?? getRequestBodyValue(request, "$ai_trace_id");
+  const sessionId = context?.sessionId ?? getRequestBodyValue(request, "$ai_session_id");
+  const parentSpanId = response?.id;
   for (const toolCall of step.toolCalls ?? []) {
+    const toolResult = step.toolResults?.find((r) => r.toolCallId === toolCall.toolCallId);
+    const toolError = getRecord(toolResult?.output)?.["error"];
     const toolSample = {
       operation: { name: `${name}.${toolCall.toolName}`, version },
       durationMs: durationMs ?? 0,
       success: step.toolResults?.some((r) => r.toolCallId === toolCall.toolCallId && r.output !== undefined) ?? false,
       timestamp: new Date,
       metadata: {
+        telemetryEvent: "span",
+        traceId,
+        sessionId,
+        spanId: toolCall.toolCallId,
+        parentSpanId,
+        spanName: `tool.${toolCall.toolName}`,
         agentId,
+        actorId: context?.actorId,
+        tenantId: context?.tenantId,
+        stepIndex: context?.stepIndex,
         toolName: toolCall.toolName,
-        finishReason: step.finishReason
+        toolCallArgs: toolCall.input,
+        toolResultOutput: toolResult?.output,
+        errorMessage: typeof toolError === "string" ? toolError : typeof toolResult?.output === "string" ? toolResult.output : undefined,
+        finishReason: step.finishReason,
+        rawFinishReason
       }
     };
     await collector.collect(toolSample);
@@ -42,10 +96,36 @@ async function trackAgentStep(collector, agentId, step, durationMs) {
     success: step.finishReason !== "error",
     timestamp: new Date,
     metadata: {
+      telemetryEvent: "generation",
+      traceId,
+      sessionId,
+      spanId: response?.id,
+      spanName: `agent.${name}.step`,
       agentId,
+      actorId: context?.actorId,
+      tenantId: context?.tenantId,
+      stepIndex: context?.stepIndex,
+      stepStartedAt: context?.stepStartedAt,
       finishReason: step.finishReason,
+      rawFinishReason,
       tokenUsage: step.usage,
-      toolCallCount: step.toolCalls?.length ?? 0
+      totalUsage: step.totalUsage,
+      providerMetadata,
+      warnings,
+      stepText: step.text,
+      stepReasoningText: step.reasoningText,
+      responseId: response?.id,
+      responseModelId: response?.modelId,
+      responseTimestamp: response?.timestamp,
+      responseHeaders: response?.headers,
+      responseBody: response?.body,
+      responseMessages: response?.messages,
+      requestBody: request?.["body"],
+      requestHeaders: request?.["headers"],
+      toolCallCount: step.toolCalls?.length ?? 0,
+      toolCalls: step.toolCalls,
+      toolResults: step.toolResults,
+      errorMessage: step.finishReason === "error" ? step.text : undefined
     }
   };
   await collector.collect(stepSample);

package/dist/telemetry/adapter.test.d.ts

@@ -0,0 +1 @@
+export {};