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

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @mastra/client-js
 
+## 1.21.0-alpha.1
+
+### Minor Changes
+
+- Client-side tool tracing is now built in. When server-side observability is configured, the SDK automatically measures execution duration and ships it back to the server. To add child spans and structured logs from inside your tool's `execute(input, context)` function, use the `observe` helper on the execution context: ([#16425](https://github.com/mastra-ai/mastra/pull/16425))
+
+  ```ts
+  execute: async ({ userId }, { observe }) => {
+    observe.log('info', 'fetching user', { userId });
+    return observe.span('fetch user', () => fetch(`/api/users/${userId}`));
+  };
+  ```
+
+  The `createTool()` helper now calls `execute(input, context)` so client tools receive the same execution context shape as core tools.
+
+### Patch Changes
+
+- Updated dependencies [[`2f5f58a`](https://github.com/mastra-ai/mastra/commit/2f5f58a9a8bb13bcdc6789db221eef7c9bf1ff02)]:
+  - @mastra/core@1.37.0-alpha.1
+
 ## 1.20.1-alpha.0
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-client-js
 description: Documentation for @mastra/client-js. Use when working with @mastra/client-js APIs, configuration, or implementation.
 metadata:
   package: "@mastra/client-js"
-  version: "1.20.1-alpha.0"
+  version: "1.21.0-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.20.1-alpha.0",
+  "version": "1.21.0-alpha.1",
   "package": "@mastra/client-js",
   "exports": {
     "RequestContext": {

package/dist/docs/references/reference-client-js-agents.md

@@ -464,6 +464,37 @@ response.processDataStream({
 })
 ```
 
+### Tracing client tools
+
+When `@mastra/observability` is installed and configured on the server, a client-side tool records a `CLIENT_TOOL_CALL` span as a child of the current `AGENT_RUN` span. The server creates that span when the model emits the client tool call, injects a W3C trace carrier into the outgoing tool-call chunk, and ends the span once the tool arguments are available. Without server-side observability configured, client tool tracing is a no-op.
+
+The client SDK also measures the wall-clock duration of each client tool's `execute` function and ships it back to the server, where it's emitted as a `mastra_tool_duration_ms` metric with `toolType: "client"`.
+
+For richer telemetry from inside your tool's `execute` function, use the `observe` helper on the execution context to add child spans and structured logs:
+
+```typescript
+import { createTool } from '@mastra/client-js'
+import { z } from 'zod'
+
+const fetchUserTool = createTool({
+  id: 'fetchUser',
+  description: 'Fetches the current user profile',
+  inputSchema: z.object({ userId: z.string() }),
+  execute: async ({ userId }, { observe }) => {
+    observe.log('info', 'fetching user', { userId })
+    const user = await observe.span('http GET /users', async () => {
+      const res = await fetch(`/api/users/${userId}`)
+      return res.json()
+    })
+    return user
+  },
+})
+```
+
+`observe` is always available — when no tracing context is active (e.g. running outside a traced agent), `span` runs the function directly and `log` is a no-op. No null-checking needed.
+
+The SDK serializes everything the collector buffered as OTLP/JSON and ships it back in the next request body. The server's `@mastra/observability` package validates that the spans belong to the correct trace (preventing cross-trace injection) and forwards each span/log into the same observability bus that server-side telemetry uses. Your existing exporters pick them up automatically after observability is configured.
+
 ## Stored agents
 
 Stored agents are agent configurations stored in a database that can be created, updated, and deleted at runtime. They reference primitives (tools, workflows, other agents, scorers) by key, which are resolved from the Mastra registry when the agent is instantiated. Memory is configured inline as a `SerializedMemoryConfig` object with options such as `lastMessages` and `semanticRecall`.

package/dist/index.cjs

@@ -15,6 +15,210 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 var canonicalize__default = /*#__PURE__*/_interopDefault(canonicalize);
 
 // 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("#")) {
@@ -295,6 +499,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,
@@ -312,31 +559,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];
@@ -659,17 +914,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 = [
@@ -681,7 +942,8 @@ var Agent = class extends BaseResource {
                   type: "tool-result",
                   toolCallId: toolCall.toolCallId,
                   toolName: toolCall.toolName,
-                  result
+                  result,
+                  ...observability ? { __mastraObservability: observability } : {}
                 }
               ]
             }
@@ -881,14 +1143,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);
@@ -903,7 +1168,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);
@@ -1205,14 +1471,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);
@@ -1228,7 +1497,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);
@@ -1347,25 +1617,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];
@@ -1377,7 +1659,8 @@ var Agent = class extends BaseResource {
                   toolInvocationPart.toolInvocation = {
                     ...toolInvocationPart.toolInvocation,
                     state: "result",
-                    result
+                    result,
+                    ...observability ? { __mastraObservability: observability } : {}
                   };
                 }
                 const toolInvocation = lastMessage?.toolInvocations?.find(
@@ -1386,6 +1669,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];
@@ -1820,23 +2106,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]));
@@ -1847,7 +2145,8 @@ var Agent = class extends BaseResource {
                   toolInvocationPart.toolInvocation = {
                     ...toolInvocationPart.toolInvocation,
                     state: "result",
-                    result
+                    result,
+                    ...observability ? { __mastraObservability: observability } : {}
                   };
                 }
                 const toolInvocation = lastMessage?.toolInvocations?.find(
@@ -1856,6 +2155,9 @@ var Agent = class extends BaseResource {
                 if (toolInvocation) {
                   toolInvocation.state = "result";
                   toolInvocation.result = result;
+                  if (observability) {
+                    toolInvocation.__mastraObservability = observability;
+                  }
                 }
                 const writer = writable.getWriter();
                 try {