@mastra/client-js 1.20.1-alpha.0 → 1.21.0-alpha.1

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './tools.js';
 export type { ChannelPlatformInfo, ChannelInstallationInfo, ChannelConnectOAuth, ChannelConnectDeepLink, ChannelConnectImmediate, ChannelConnectResult, } from './resources/channels.js';
 export type { AgentCardSignatureKeyProviderInput, AgentCardVerificationKey, GetAgentCardOptions, VerifyAgentCardSignatureOptions, } from './resources/a2a.js';
 export { RequestContext } from '@mastra/core/request-context';
+export type { ObservabilityCollector } from './observability/types.js';
 export type { UIMessageWithMetadata } from '@mastra/core/agent';
 export type { Body, Client, ClientMethod, ClientPath, ClientRequest, ClientResponse, ClientResponseKind, ClientRoute, PathParams, QueryParams, RouteKey, RouteRequest, RouteResponse, RouteResponseType, RouteTypes, } from './route-types.generated.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EACnB,+BAA+B,GAChC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EACV,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,UAAU,EACV,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,UAAU,GACX,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EACnB,+BAA+B,GAChC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAG9D,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EACV,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,UAAU,EACV,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,UAAU,GACX,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -10,6 +10,210 @@ import canonicalize from 'canonicalize';
 import { base64url, decodeProtectedHeader, compactVerify, importX509, importSPKI, importJWK } from 'jose';
 
 // src/resources/agent.ts
+
+// src/observability/collector.ts
+var TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+var ZERO_TRACE_ID = "00000000000000000000000000000000";
+var ZERO_SPAN_ID = "0000000000000000";
+var LEVEL_TO_SEVERITY_NUMBER = {
+  debug: 5,
+  info: 9,
+  warn: 13,
+  error: 17,
+  fatal: 21
+};
+var LEVEL_TO_SEVERITY_TEXT = {
+  debug: "DEBUG",
+  info: "INFO",
+  warn: "WARN",
+  error: "ERROR",
+  fatal: "FATAL"
+};
+function nowNs() {
+  return BigInt(Date.now()) * 1000000n;
+}
+function isValidTraceparentMatch(parsed) {
+  const version = parsed[1];
+  const traceId = parsed[2];
+  const spanId = parsed[3];
+  return version !== "ff" && traceId !== ZERO_TRACE_ID && spanId !== ZERO_SPAN_ID;
+}
+function randomSpanIdHex() {
+  if (typeof globalThis.crypto !== "undefined" && globalThis.crypto.getRandomValues) {
+    const bytes = new Uint8Array(8);
+    globalThis.crypto.getRandomValues(bytes);
+    let out2 = "";
+    for (const b of bytes) out2 += b.toString(16).padStart(2, "0");
+    return out2;
+  }
+  let out = "";
+  for (let i = 0; i < 16; i++) out += Math.floor(Math.random() * 16).toString(16);
+  return out;
+}
+function attributesToOtlp(attrs) {
+  const out = [];
+  for (const [key, raw] of Object.entries(attrs)) {
+    if (raw === void 0 || raw === null) continue;
+    if (typeof raw === "string") {
+      out.push({ key, value: { stringValue: raw } });
+    } else if (typeof raw === "boolean") {
+      out.push({ key, value: { boolValue: raw } });
+    } else if (typeof raw === "number") {
+      if (Number.isInteger(raw)) {
+        out.push({ key, value: { intValue: raw } });
+      } else {
+        out.push({ key, value: { doubleValue: raw } });
+      }
+    } else {
+      try {
+        out.push({ key, value: { stringValue: JSON.stringify(raw) } });
+      } catch {
+      }
+    }
+  }
+  return out;
+}
+var ObservabilityCollectorImpl = class {
+  parentContext;
+  #traceId;
+  #rootSpanId;
+  #spans = [];
+  #logs = [];
+  #spanStack = [];
+  /** Wall-clock execution timing, captured by withContext. */
+  #executionStartMs;
+  #executionEndMs;
+  #flushed = false;
+  constructor(parentContext) {
+    this.parentContext = parentContext;
+    const parsed = TRACEPARENT_RE.exec(parentContext.traceparent);
+    if (!parsed || !isValidTraceparentMatch(parsed)) {
+      this.#traceId = ZERO_TRACE_ID;
+      this.#rootSpanId = ZERO_SPAN_ID;
+      return;
+    }
+    this.#traceId = parsed[2];
+    this.#rootSpanId = parsed[3];
+  }
+  async withContext(fn) {
+    const executionStartMs = this.#executionStartMs ?? Date.now();
+    this.#executionStartMs = executionStartMs;
+    this.#spanStack.push(this.#rootSpanId);
+    try {
+      return await fn();
+    } finally {
+      this.#spanStack.pop();
+      this.#executionEndMs = Date.now();
+    }
+  }
+  async span(name, fn, attributes) {
+    const spanId = randomSpanIdHex();
+    const spanStack = this.#getSpanStack();
+    const parentSpanId = spanStack[spanStack.length - 1] ?? this.#rootSpanId;
+    const startTimeNs = nowNs();
+    spanStack.push(spanId);
+    let statusCode = 1;
+    let statusMessage;
+    try {
+      return await fn();
+    } catch (err) {
+      statusCode = 2;
+      statusMessage = err instanceof Error ? err.message : String(err);
+      throw err;
+    } finally {
+      spanStack.pop();
+      this.#spans.push({
+        spanId,
+        parentSpanId,
+        traceId: this.#traceId,
+        name,
+        startTimeNs,
+        endTimeNs: nowNs(),
+        attributes: attributes ?? {},
+        statusCode,
+        statusMessage
+      });
+    }
+  }
+  log(level, message, data) {
+    const spanStack = this.#getSpanStack();
+    const spanId = spanStack[spanStack.length - 1] ?? this.#rootSpanId;
+    this.#logs.push({
+      spanId,
+      traceId: this.#traceId,
+      timestampNs: nowNs(),
+      level,
+      message,
+      data
+    });
+  }
+  #getSpanStack() {
+    return this.#spanStack;
+  }
+  flush() {
+    if (this.#flushed) {
+      return {};
+    }
+    this.#flushed = true;
+    const payload = {};
+    if (this.#executionStartMs !== void 0 && this.#executionEndMs !== void 0) {
+      payload.executionDurationMs = this.#executionEndMs - this.#executionStartMs;
+    }
+    if (this.#spans.length > 0) {
+      payload.spans = {
+        resourceSpans: [
+          {
+            scopeSpans: [
+              {
+                scope: { name: "@mastra/client-js/observability", version: "1" },
+                spans: this.#spans.map((s) => ({
+                  traceId: s.traceId,
+                  spanId: s.spanId,
+                  parentSpanId: s.parentSpanId,
+                  name: s.name,
+                  // OTLP/JSON allows nanosecond timestamps as decimal
+                  // strings to avoid JS number precision loss for
+                  // uint64. Use string form.
+                  startTimeUnixNano: s.startTimeNs.toString(),
+                  endTimeUnixNano: s.endTimeNs.toString(),
+                  attributes: attributesToOtlp(s.attributes),
+                  status: { code: s.statusCode, ...s.statusMessage ? { message: s.statusMessage } : {} },
+                  // OTLP requires `kind`; default to INTERNAL = 1.
+                  kind: 1
+                }))
+              }
+            ]
+          }
+        ]
+      };
+    }
+    if (this.#logs.length > 0) {
+      payload.logs = {
+        resourceLogs: [
+          {
+            scopeLogs: [
+              {
+                scope: { name: "@mastra/client-js/observability", version: "1" },
+                logRecords: this.#logs.map((l) => ({
+                  timeUnixNano: l.timestampNs.toString(),
+                  observedTimeUnixNano: l.timestampNs.toString(),
+                  severityNumber: LEVEL_TO_SEVERITY_NUMBER[l.level],
+                  severityText: LEVEL_TO_SEVERITY_TEXT[l.level],
+                  body: { stringValue: l.message },
+                  traceId: l.traceId,
+                  spanId: l.spanId,
+                  attributes: l.data ? attributesToOtlp(l.data) : []
+                }))
+              }
+            ]
+          }
+        ]
+      };
+    }
+    return payload;
+  }
+};
+var createObservabilityCollector = (parentContext) => new ObservabilityCollectorImpl(parentContext);
 function normalizeRoutePath(path) {
   let normalized = path.trim();
   if (normalized.includes("..") || normalized.includes("?") || normalized.includes("#")) {
@@ -290,6 +494,49 @@ var BaseResource = class {
 };
 
 // src/resources/agent.ts
+var noopClientToolObserve = {
+  async span(_name, fn) {
+    return fn();
+  },
+  log() {
+  }
+};
+function getClientToolObservabilityContext(toolCall) {
+  const candidate = toolCall;
+  return candidate?.payload?.observability ?? candidate?.observability;
+}
+async function executeClientToolWithObservability({
+  clientTool,
+  args,
+  toolName,
+  parentContext,
+  executeContext
+}) {
+  const collector = parentContext ? createObservabilityCollector(parentContext) : void 0;
+  const observe = collector ? {
+    span: collector.span.bind(collector),
+    log: collector.log.bind(collector)
+  } : noopClientToolObserve;
+  const runExecute = () => clientTool.execute(args, {
+    ...executeContext,
+    observe
+  });
+  const result = collector ? await collector.withContext(runExecute) : await runExecute();
+  if (!parentContext) {
+    return { result };
+  }
+  const flushed = collector?.flush();
+  if (flushed) {
+    flushed.toolName = toolName;
+  }
+  return {
+    result,
+    observability: {
+      parentContext,
+      ...flushed ? { payload: flushed } : {}
+    }
+  };
+}
 async function executeToolCallAndRespond({
   response,
   params,
@@ -307,31 +554,39 @@ async function executeToolCallAndRespond({
     for (const toolCall of toolCalls) {
       const clientTool = params.clientTools?.[toolCall.payload.toolName];
       if (clientTool && clientTool.execute) {
-        const result = await clientTool.execute(toolCall?.payload.args, {
-          requestContext,
-          tracingContext: { currentSpan: void 0 },
-          agent: {
-            agentId,
-            messages: response.messages,
-            toolCallId: toolCall?.payload.toolCallId,
-            suspend: async () => {
-            },
-            threadId,
-            resourceId
+        const { result, observability } = await executeClientToolWithObservability({
+          clientTool,
+          args: toolCall?.payload.args,
+          toolName: toolCall.payload.toolName,
+          parentContext: getClientToolObservabilityContext(toolCall),
+          executeContext: {
+            requestContext,
+            tracingContext: { currentSpan: void 0 },
+            agent: {
+              agentId,
+              messages: response.messages,
+              toolCallId: toolCall?.payload.toolCallId,
+              suspend: async () => {
+              },
+              threadId,
+              resourceId
+            }
           }
         });
+        const toolResultContent = {
+          type: "tool-result",
+          toolCallId: toolCall.payload.toolCallId,
+          toolName: toolCall.payload.toolName,
+          result
+        };
+        if (observability) {
+          toolResultContent.__mastraObservability = observability;
+        }
         const newMessages = [
           ...response.response.messages || [],
           {
             role: "tool",
-            content: [
-              {
-                type: "tool-result",
-                toolCallId: toolCall.payload.toolCallId,
-                toolName: toolCall.payload.toolName,
-                result
-              }
-            ]
+            content: [toolResultContent]
           }
         ];
         const updatedMessages = threadId ? newMessages : [...Array.isArray(params.messages) ? params.messages : [], ...newMessages];
@@ -654,17 +909,23 @@ var Agent = class extends BaseResource {
       for (const toolCall of toolCalls) {
         const clientTool = params.clientTools?.[toolCall.toolName];
         if (clientTool && clientTool.execute) {
-          const result = await clientTool.execute(toolCall?.args, {
-            requestContext,
-            tracingContext: { currentSpan: void 0 },
-            agent: {
-              agentId: this.agentId,
-              messages: response.messages,
-              toolCallId: toolCall?.toolCallId,
-              suspend: async () => {
-              },
-              threadId,
-              resourceId
+          const { result, observability } = await executeClientToolWithObservability({
+            clientTool,
+            args: toolCall?.args,
+            toolName: toolCall.toolName,
+            parentContext: getClientToolObservabilityContext(toolCall),
+            executeContext: {
+              requestContext,
+              tracingContext: { currentSpan: void 0 },
+              agent: {
+                agentId: this.agentId,
+                messages: response.messages,
+                toolCallId: toolCall?.toolCallId,
+                suspend: async () => {
+                },
+                threadId,
+                resourceId
+              }
             }
           });
           const updatedMessages = [
@@ -676,7 +937,8 @@ var Agent = class extends BaseResource {
                   type: "tool-result",
                   toolCallId: toolCall.toolCallId,
                   toolName: toolCall.toolName,
-                  result
+                  result,
+                  ...observability ? { __mastraObservability: observability } : {}
                 }
               ]
             }
@@ -876,14 +1138,17 @@ var Agent = class extends BaseResource {
           text: "",
           step,
           toolName: value.toolName,
-          index: message.toolInvocations.length
+          index: message.toolInvocations.length,
+          observability: getClientToolObservabilityContext(value)
         };
+        const observability = getClientToolObservabilityContext(value);
         const invocation = {
           state: "partial-call",
           step,
           toolCallId: value.toolCallId,
           toolName: value.toolName,
-          args: void 0
+          args: void 0,
+          ...observability ? { observability } : {}
         };
         message.toolInvocations.push(invocation);
         updateToolInvocationPart(value.toolCallId, invocation);
@@ -898,7 +1163,8 @@ var Agent = class extends BaseResource {
           step: partialToolCall.step,
           toolCallId: value.toolCallId,
           toolName: partialToolCall.toolName,
-          args: partialArgs
+          args: partialArgs,
+          ...partialToolCall.observability ? { observability: partialToolCall.observability } : {}
         };
         message.toolInvocations[partialToolCall.index] = invocation;
         updateToolInvocationPart(value.toolCallId, invocation);
@@ -1200,14 +1466,17 @@ var Agent = class extends BaseResource {
               text: "",
               step,
               toolName: chunk.payload.toolName,
-              index: message.toolInvocations.length
+              index: message.toolInvocations.length,
+              observability: getClientToolObservabilityContext(chunk)
             };
+            const observability = getClientToolObservabilityContext(chunk);
             const invocation = {
               state: "partial-call",
               step,
               toolCallId: chunk.payload.toolCallId,
               toolName: chunk.payload.toolName,
-              args: chunk.payload.args
+              args: chunk.payload.args,
+              ...observability ? { observability } : {}
             };
             message.toolInvocations.push(invocation);
             updateToolInvocationPart(chunk.payload.toolCallId, invocation);
@@ -1223,7 +1492,8 @@ var Agent = class extends BaseResource {
               step: partialToolCall.step,
               toolCallId: chunk.payload.toolCallId,
               toolName: partialToolCall.toolName,
-              args: partialArgs
+              args: partialArgs,
+              ...partialToolCall.observability ? { observability: partialToolCall.observability } : {}
             };
             message.toolInvocations[partialToolCall.index] = invocation;
             updateToolInvocationPart(chunk.payload.toolCallId, invocation);
@@ -1342,25 +1612,37 @@ var Agent = class extends BaseResource {
           if (finishReason === "tool-calls") {
             const toolCall = [...message?.parts ?? []].reverse().find((part) => part.type === "tool-invocation")?.toolInvocation;
             if (toolCall) {
-              toolCalls.push(toolCall);
+              const toolInvocationWithMetadata = message?.toolInvocations?.find(
+                (invocation) => invocation.toolCallId === toolCall.toolCallId
+              );
+              toolCalls.push({
+                ...toolInvocationWithMetadata,
+                ...toolCall,
+                ...!getClientToolObservabilityContext(toolCall) && toolInvocationWithMetadata ? { observability: getClientToolObservabilityContext(toolInvocationWithMetadata) } : {}
+              });
             }
             let shouldExecuteClientTool = false;
             for (const toolCall2 of toolCalls) {
               const clientTool = processedParams.clientTools?.[toolCall2.toolName];
               if (clientTool && clientTool.execute) {
                 shouldExecuteClientTool = true;
-                const result = await clientTool.execute(toolCall2?.args, {
-                  requestContext: processedParams.requestContext,
-                  // TODO: Pass proper tracing context when client-js supports tracing
-                  tracingContext: { currentSpan: void 0 },
-                  agent: {
-                    agentId: this.agentId,
-                    messages: response.messages,
-                    toolCallId: toolCall2?.toolCallId,
-                    suspend: async () => {
-                    },
-                    threadId,
-                    resourceId
+                const { result, observability } = await executeClientToolWithObservability({
+                  clientTool,
+                  args: toolCall2?.args,
+                  toolName: toolCall2.toolName,
+                  parentContext: getClientToolObservabilityContext(toolCall2),
+                  executeContext: {
+                    requestContext: processedParams.requestContext,
+                    tracingContext: { currentSpan: void 0 },
+                    agent: {
+                      agentId: this.agentId,
+                      messages: response.messages,
+                      toolCallId: toolCall2?.toolCallId,
+                      suspend: async () => {
+                      },
+                      threadId,
+                      resourceId
+                    }
                   }
                 });
                 const lastMessageRaw = messages[messages.length - 1];
@@ -1372,7 +1654,8 @@ var Agent = class extends BaseResource {
                   toolInvocationPart.toolInvocation = {
                     ...toolInvocationPart.toolInvocation,
                     state: "result",
-                    result
+                    result,
+                    ...observability ? { __mastraObservability: observability } : {}
                   };
                 }
                 const toolInvocation = lastMessage?.toolInvocations?.find(
@@ -1381,6 +1664,9 @@ var Agent = class extends BaseResource {
                 if (toolInvocation) {
                   toolInvocation.state = "result";
                   toolInvocation.result = result;
+                  if (observability) {
+                    toolInvocation.__mastraObservability = observability;
+                  }
                 }
                 const newMessages = lastMessage != null ? [...messages.filter((m) => m.id !== lastMessage.id), lastMessage] : [...messages];
                 const updatedMessages = threadId ? newMessages : [...Array.isArray(processedParams.messages) ? processedParams.messages : [], ...newMessages];
@@ -1815,23 +2101,35 @@ var Agent = class extends BaseResource {
           if (finishReason === "tool-calls") {
             const toolCall = [...message?.parts ?? []].reverse().find((part) => part.type === "tool-invocation")?.toolInvocation;
             if (toolCall) {
-              toolCalls.push(toolCall);
+              const toolInvocationWithMetadata = message?.toolInvocations?.find(
+                (invocation) => invocation.toolCallId === toolCall.toolCallId
+              );
+              toolCalls.push({
+                ...toolInvocationWithMetadata,
+                ...toolCall,
+                ...!getClientToolObservabilityContext(toolCall) && toolInvocationWithMetadata ? { observability: getClientToolObservabilityContext(toolInvocationWithMetadata) } : {}
+              });
             }
             for (const toolCall2 of toolCalls) {
               const clientTool = processedParams.clientTools?.[toolCall2.toolName];
               if (clientTool && clientTool.execute) {
-                const result = await clientTool.execute(toolCall2?.args, {
-                  requestContext: processedParams.requestContext,
-                  // TODO: Pass proper tracing context when client-js supports tracing
-                  tracingContext: { currentSpan: void 0 },
-                  agent: {
-                    agentId: this.agentId,
-                    messages: response.messages,
-                    toolCallId: toolCall2?.toolCallId,
-                    suspend: async () => {
-                    },
-                    threadId,
-                    resourceId
+                const { result, observability } = await executeClientToolWithObservability({
+                  clientTool,
+                  args: toolCall2?.args,
+                  toolName: toolCall2.toolName,
+                  parentContext: getClientToolObservabilityContext(toolCall2),
+                  executeContext: {
+                    requestContext: processedParams.requestContext,
+                    tracingContext: { currentSpan: void 0 },
+                    agent: {
+                      agentId: this.agentId,
+                      messages: response.messages,
+                      toolCallId: toolCall2?.toolCallId,
+                      suspend: async () => {
+                      },
+                      threadId,
+                      resourceId
+                    }
                   }
                 });
                 const lastMessage = JSON.parse(JSON.stringify(messages[messages.length - 1]));
@@ -1842,7 +2140,8 @@ var Agent = class extends BaseResource {
                   toolInvocationPart.toolInvocation = {
                     ...toolInvocationPart.toolInvocation,
                     state: "result",
-                    result
+                    result,
+                    ...observability ? { __mastraObservability: observability } : {}
                   };
                 }
                 const toolInvocation = lastMessage?.toolInvocations?.find(
@@ -1851,6 +2150,9 @@ var Agent = class extends BaseResource {
                 if (toolInvocation) {
                   toolInvocation.state = "result";
                   toolInvocation.result = result;
+                  if (observability) {
+                    toolInvocation.__mastraObservability = observability;
+                  }
                 }
                 const writer = writable.getWriter();
                 try {