@contractspec/lib.ai-agent 2.0.0 → 2.1.1

package/dist/telemetry/index.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);
@@ -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/telemetry/posthog-types.d.ts

@@ -15,12 +15,24 @@ export interface PostHogTracingOptions {
     posthogDistinctId?: string;
     /** Trace ID for grouping related generations */
     posthogTraceId?: string;
+    /** Optional model id override */
+    posthogModelOverride?: string;
+    /** Optional provider override */
+    posthogProviderOverride?: string;
+    /** Optional explicit token pricing override */
+    posthogCostOverride?: PostHogCostOverride;
     /** Custom properties attached to every generation event */
     posthogProperties?: Record<string, unknown>;
     /** When true, input/output content is redacted */
     posthogPrivacyMode?: boolean;
     /** Group analytics (e.g., { company: "companyId" }) */
     posthogGroups?: Record<string, string>;
+    /** Sends events immediately (useful for short-lived/serverless contexts) */
+    posthogCaptureImmediate?: boolean;
+}
+export interface PostHogCostOverride {
+    inputCost: number;
+    outputCost: number;
 }
 /**
  * Minimal interface for posthog-node PostHog client.

package/dist/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.ai-agent",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "AI agent orchestration with MCP and tool support",
   "keywords": [
     "contractspec",
@@ -42,9 +42,9 @@
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@posthog/react": "^1.7.1",
     "@posthog/ai": "latest",
-    "@contractspec/lib.contracts-spec": "2.0.0",
-    "@contractspec/lib.ai-providers": "2.0.0",
-    "@contractspec/lib.knowledge": "2.0.0",
+    "@contractspec/lib.contracts-spec": "2.1.1",
+    "@contractspec/lib.ai-providers": "2.1.0",
+    "@contractspec/lib.knowledge": "2.1.1",
     "compare-versions": "^6.1.1",
     "zod": "^4.3.5"
   },
@@ -68,9 +68,9 @@
     }
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "2.0.0",
+    "@contractspec/tool.typescript": "2.1.0",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "2.0.0"
+    "@contractspec/tool.bun": "2.1.0"
   },
   "exports": {
     ".": {