@cognipeer/agent-sdk 0.9.2 → 0.9.4

package/README.md

@@ -417,6 +417,8 @@ You can disable payload capture with `logData: false` to keep only metrics, or c
 
 Each session/event also carries OTel-compatible correlation identifiers (`traceId`, `rootSpanId`, `spanId`, `parentSpanId`) so you can stitch agent traces into distributed telemetry pipelines.
 
+Pass `tracing: { metadata: { ... } }` to attach arbitrary key-value tags (e.g. `{ complexity: "complex" }`) to every payload sent to the sink. The SDK does not interpret these tags itself — they're forwarded as-is so a downstream consumer (e.g. Console) can use them as reporting/attribution dimensions.
+
 ## Development
 
 Install dependencies and build the package:

package/dist/index.cjs

@@ -294,63 +294,16 @@ var NativeJsonSchemaStrategy = class {
     }
     return resolvedSchema;
   }
-  normalizeOpenAIStrictSchema(schema) {
-    const visit = (node) => {
-      if (!node || typeof node !== "object") return node;
-      if (Array.isArray(node)) {
-        return node.map(visit);
-      }
-      const clone2 = { ...node };
-      if (clone2.properties && typeof clone2.properties === "object") {
-        const normalizedProperties = {};
-        for (const [key, value] of Object.entries(clone2.properties)) {
-          normalizedProperties[key] = visit(value);
-        }
-        clone2.properties = normalizedProperties;
-        clone2.required = Object.keys(normalizedProperties);
-        if (clone2.additionalProperties === void 0) {
-          clone2.additionalProperties = false;
-        }
-      }
-      if (clone2.items) {
-        clone2.items = visit(clone2.items);
-      }
-      if (clone2.definitions && typeof clone2.definitions === "object") {
-        const normalizedDefinitions = {};
-        for (const [key, value] of Object.entries(clone2.definitions)) {
-          normalizedDefinitions[key] = visit(value);
-        }
-        clone2.definitions = normalizedDefinitions;
-      }
-      if (clone2.$defs && typeof clone2.$defs === "object") {
-        const normalizedDefs = {};
-        for (const [key, value] of Object.entries(clone2.$defs)) {
-          normalizedDefs[key] = visit(value);
-        }
-        clone2.$defs = normalizedDefs;
-      }
-      for (const compositeKey of ["anyOf", "oneOf", "allOf"]) {
-        if (Array.isArray(clone2[compositeKey])) {
-          clone2[compositeKey] = clone2[compositeKey].map(visit);
-        }
-      }
-      return clone2;
-    };
-    return visit(schema);
-  }
   /**
    * Convert a Zod schema to the JSON Schema object used in response_format.
    */
   toJsonSchema(schema, name = "structured_response") {
     const result = zodToJsonSchema.zodToJsonSchema(schema, {
       name,
-      openaiStrictMode: true,
-      nameStrategy: "duplicate-ref",
-      $refStrategy: "extract-to-root",
-      nullableStrategy: "property"
+      target: "openAi",
+      $refStrategy: "root"
     });
-    const normalized = this.normalizeOpenAIStrictSchema(result);
-    return this.unwrapRootObjectSchema(normalized);
+    return this.unwrapRootObjectSchema(result);
   }
   /**
    * Build response_format configuration for the model call.
@@ -1209,9 +1162,9 @@ async function postStreamingSessionStart(baseUrl, headers, payload) {
   const url = `${baseUrl.replace(/\/$/, "")}/stream/${payload.sessionId}/start`;
   await postJsonReliable(url, headers, payload, { retry: true });
 }
-async function postStreamingEvent(baseUrl, headers, sessionId, event) {
+async function postStreamingEvent(baseUrl, headers, sessionId, event, metadata) {
   const url = `${baseUrl.replace(/\/$/, "")}/stream/${sessionId}/events`;
-  await postJsonReliable(url, headers, { event }, { retry: false });
+  await postJsonReliable(url, headers, { event, metadata }, { retry: false });
 }
 async function postStreamingSessionEnd(baseUrl, headers, payload) {
   const url = `${baseUrl.replace(/\/$/, "")}/stream/${payload.sessionId}/end`;
@@ -1261,6 +1214,8 @@ function eventToOtlpSpan(event) {
     stringAttr("cognipeer.actor.name", event.actor?.name),
     stringAttr("cognipeer.actor.role", event.actor?.role),
     stringAttr("cognipeer.model", event.model),
+    intAttr("cognipeer.tokens.reasoning", event.reasoningTokens),
+    stringAttr("cognipeer.finish_reason", event.finishReason),
     stringAttr("cognipeer.provider", event.provider),
     stringAttr("cognipeer.tool.details", event.toolDetails ? JSON.stringify(event.toolDetails) : void 0),
     intAttr("cognipeer.tokens.input", event.inputTokens),
@@ -1316,7 +1271,8 @@ function traceSessionToOtlp(session) {
     stringAttr("cognipeer.session.id", session.sessionId),
     stringAttr("cognipeer.thread.id", session.threadId),
     stringAttr("cognipeer.agent.model", session.agent?.model),
-    stringAttr("cognipeer.agent.provider", session.agent?.provider)
+    stringAttr("cognipeer.agent.provider", session.agent?.provider),
+    ...Object.entries(session.metadata || {}).map(([key, value]) => stringAttr(`cognipeer.metadata.${key}`, value))
   ].filter(Boolean);
   const rootAttrs = [
     stringAttr("cognipeer.session.status", session.status),
@@ -1488,6 +1444,8 @@ function defaultSectionLabel(kind) {
       return "Details";
     case "tool_definitions":
       return "Tool Definitions";
+    case "response_format":
+      return "Response Format";
     default:
       return "Section";
   }
@@ -1545,6 +1503,42 @@ function buildToolDefinitionsSection(toolDefinitions) {
   }
   return section;
 }
+var RESPONSE_FORMAT_MAX_SECTION_BYTES = 64 * 1024;
+var RESPONSE_FORMAT_MAX_NAME_CHARS = 200;
+function buildResponseFormatSection(responseFormat, strategy) {
+  if (!responseFormat || typeof responseFormat !== "object" || Array.isArray(responseFormat)) return void 0;
+  const raw = responseFormat.response_format ?? responseFormat.responseFormat ?? responseFormat;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const type = typeof raw.type === "string" && raw.type.trim().length > 0 ? raw.type.trim() : void 0;
+  const jsonSchema = raw.json_schema ?? raw.jsonSchema;
+  const schemaSource = jsonSchema && typeof jsonSchema === "object" ? jsonSchema : raw;
+  const schema = schemaSource.schema && typeof schemaSource.schema === "object" && !Array.isArray(schemaSource.schema) ? schemaSource.schema : void 0;
+  if (!type && !schema) return void 0;
+  const section = {
+    kind: "response_format",
+    label: "Response Format",
+    type: type ?? (schema ? "json_schema" : "unknown"),
+    ...strategy ? { strategy } : {},
+    ...typeof schemaSource.name === "string" && schemaSource.name.length > 0 ? { schemaName: schemaSource.name.slice(0, RESPONSE_FORMAT_MAX_NAME_CHARS) } : {},
+    ...typeof schemaSource.strict === "boolean" ? { strict: schemaSource.strict } : {}
+  };
+  if (schema) {
+    try {
+      section.schema = JSON.parse(JSON.stringify(schema));
+    } catch {
+    }
+  }
+  try {
+    if (section.schema && buffer.Buffer.byteLength(JSON.stringify(section), "utf8") > RESPONSE_FORMAT_MAX_SECTION_BYTES) {
+      delete section.schema;
+      section.truncated = true;
+    }
+  } catch {
+    delete section.schema;
+    section.truncated = true;
+  }
+  return section;
+}
 function buildMessageLabel(role, index) {
   const normalized = role?.trim().length ? role.trim() : "message";
   const base = `${normalized.charAt(0).toUpperCase()}${normalized.slice(1)} Message`;
@@ -1653,6 +1647,7 @@ function createTraceSession(opts) {
     rootSpanId,
     threadId: opts.tracing?.threadId,
     configAgentName: opts.tracing?.agentName?.trim() || void 0,
+    configMetadata: opts.tracing?.metadata && Object.keys(opts.tracing.metadata).length > 0 ? opts.tracing.metadata : void 0,
     startedAt: Date.now(),
     resolvedConfig: cfg,
     events: [],
@@ -1691,6 +1686,7 @@ async function startStreamingSession(session, agentRuntime) {
     threadId: session.threadId,
     startedAt: startedAtIso,
     agent: agentInfo,
+    metadata: session.configMetadata,
     config: configSnapshot
   };
   if (sink.type === "cognipeer" || sink.type === "http") {
@@ -1740,6 +1736,7 @@ function recordTraceEvent(session, event) {
   if (!Number.isNaN(cachedInputTokens ?? NaN) && cachedInputTokens !== void 0) {
     session.summary.totalCachedInputTokens += cachedInputTokens;
   }
+  const reasoningTokens = event.reasoningTokens !== void 0 ? Number(event.reasoningTokens) : void 0;
   const totalTokens = event.totalTokens !== void 0 ? Number(event.totalTokens) : void 0;
   const requestBytes = event.requestBytes !== void 0 ? Number(event.requestBytes) : void 0;
   if (!Number.isNaN(requestBytes ?? NaN) && requestBytes !== void 0) {
@@ -1765,6 +1762,13 @@ function recordTraceEvent(session, event) {
         if (menuSection) sections = ensureUniqueSections(id, [...sections ?? [], menuSection]);
       }
     }
+    if (event.responseFormat) {
+      const existing = (sections ?? []).some((section) => section.kind === "response_format");
+      if (!existing) {
+        const formatSection = buildResponseFormatSection(event.responseFormat, event.responseFormatStrategy);
+        if (formatSection) sections = ensureUniqueSections(id, [...sections ?? [], formatSection]);
+      }
+    }
   }
   const resolvedModel = event.model ?? inferModelFromMessages(event.messageList);
   const resolvedProvider = event.provider ?? inferProviderFromMessages(event.messageList);
@@ -1795,6 +1799,11 @@ function recordTraceEvent(session, event) {
       ...totalTokens !== void 0 && { totalTokens },
       ...cachedInputTokens !== void 0 && { cachedInputTokens }
     },
+    // Absent, never zeroed for ai_call the way the four above are: a model
+    // that does no reasoning and one whose provider reports nothing are
+    // different facts, and a zero would erase the difference.
+    ...reasoningTokens !== void 0 && !Number.isNaN(reasoningTokens) ? { reasoningTokens } : {},
+    ...event.finishReason ? { finishReason: event.finishReason } : {},
     requestBytes,
     responseBytes,
     model: resolvedModel,
@@ -1838,7 +1847,7 @@ function recordTraceEvent(session, event) {
   if (session.resolvedConfig.mode === "streaming" && session.sessionStarted) {
     if (sink.type === "cognipeer" || sink.type === "http") {
       const headers = sink.type === "cognipeer" ? { Authorization: `Bearer ${sink.apiKey}` } : sink.headers;
-      postStreamingEvent(sink.url, headers, session.sessionId, record).catch((err) => {
+      postStreamingEvent(sink.url, headers, session.sessionId, record, session.configMetadata).catch((err) => {
         const errMsg = err instanceof Error ? err.message : String(err);
         if (typeof console !== "undefined" && typeof console.warn === "function") {
           console.warn("[Tracing] Failed to send streaming event:", errMsg);
@@ -1890,6 +1899,7 @@ async function finalizeTraceSession(session, params = {}) {
     endedAt: endedAtIso,
     durationMs,
     agent: agentInfo || session.agentInfo,
+    metadata: session.configMetadata,
     config: configSnapshot,
     summary: session.summary,
     events: session.events,
@@ -1924,7 +1934,8 @@ async function finalizeTraceSession(session, params = {}) {
           durationMs,
           status: initialStatus,
           summary: session.summary,
-          errors: session.errors
+          errors: session.errors,
+          metadata: session.configMetadata
         });
       } else {
         await postTraceSession(sink.url, headers, payloadForSink);
@@ -3892,6 +3903,18 @@ function createAgentCoreNode(opts) {
       }
     }
     const responseFormat = runtime.responseFormat;
+    let traceResponseFormat = responseFormat;
+    let traceResponseFormatStrategy = responseFormat ? "native" : void 0;
+    if (!traceResponseFormat && runtime.outputSchema) {
+      const responseTool = traceToolDefinitions?.find((tool) => tool.name === "response");
+      if (responseTool?.parameters) {
+        traceResponseFormat = {
+          type: "json_schema",
+          json_schema: { name: "response", strict: false, schema: responseTool.parameters }
+        };
+        traceResponseFormatStrategy = "tool_based";
+      }
+    }
     const reasoningForCall = state.ctx?.__reasoning;
     const reasoningInvokeOpts = reasoningForCall ? { reasoning: reasoningForCall } : void 0;
     const extractText2 = (chunk) => {
@@ -3951,7 +3974,9 @@ function createAgentCoreNode(opts) {
         provider: getProviderName(runtime.model || opts.model),
         error: { message: err?.message || String(err), stack: err?.stack },
         messageList: state.messages,
-        toolDefinitions: traceToolDefinitions
+        toolDefinitions: traceToolDefinitions,
+        responseFormat: traceResponseFormat,
+        responseFormatStrategy: traceResponseFormatStrategy
       });
       throw err;
     }
@@ -3966,6 +3991,7 @@ function createAgentCoreNode(opts) {
     const shouldLogResponse = !!traceSession && traceSession.resolvedConfig.logData;
     const responsePayload = shouldLogResponse ? sanitizeTracePayload(response) : void 0;
     const responseBytes = responsePayload !== void 0 ? estimatePayloadBytes(responsePayload) : void 0;
+    const finishReason = response?.response_metadata?.finish_reason ?? response?.response_metadata?.finishReason ?? response?.finishReason;
     recordTraceEvent(traceSession, {
       type: "ai_call",
       label: "Assistant Response",
@@ -3975,12 +4001,18 @@ function createAgentCoreNode(opts) {
       outputTokens: normalized?.completion_tokens,
       totalTokens: normalized?.total_tokens,
       cachedInputTokens: normalized?.prompt_tokens_details?.cached_tokens,
+      // A subset of completion_tokens, and on a reasoning model routinely most
+      // of the output bill while being invisible in the response text.
+      reasoningTokens: normalized?.completion_tokens_details?.reasoning_tokens,
+      finishReason: typeof finishReason === "string" ? finishReason : void 0,
       requestBytes: promptBytes,
       responseBytes,
       model: modelName,
       provider: getProviderName(runtime.model || opts.model),
       messageList: messagesWithResponse,
-      toolDefinitions: traceToolDefinitions
+      toolDefinitions: traceToolDefinitions,
+      responseFormat: traceResponseFormat,
+      responseFormatStrategy: traceResponseFormatStrategy
     });
     if (normalized) {
       recordUsage(state, modelName, normalized);
@@ -11793,6 +11825,7 @@ exports.ToolBasedStrategy = ToolBasedStrategy;
 exports.VertexProvider = VertexProvider;
 exports.agentVerdictRule = agentVerdictRule;
 exports.appendBoundTools = appendBoundTools;
+exports.buildResponseFormatSection = buildResponseFormatSection;
 exports.buildSkillHeaderBlock = buildSkillHeaderBlock;
 exports.buildSubagentCatalogBlock = buildSubagentCatalogBlock;
 exports.buildSystemPrompt = buildSystemPrompt;