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

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,67 @@ var BaseResource = class {
 };
 
 // src/resources/agent.ts
+var SIGNAL_RUNTIME_OPTIONS_TTL_MS = 5 * 60 * 1e3;
+var signalRuntimeOptionsByRunId = /* @__PURE__ */ new Map();
+var latestSignalRuntimeOptionsByThread = /* @__PURE__ */ new Map();
+var createSignalRuntimeOptionsEntry = (store, key, streamOptions) => {
+  const timeout = setTimeout(() => store.delete(key), SIGNAL_RUNTIME_OPTIONS_TTL_MS);
+  timeout.unref?.();
+  return { streamOptions, timeout };
+};
+var setSignalRuntimeOptionsEntry = (store, key, streamOptions) => {
+  const existing = store.get(key);
+  if (existing) clearTimeout(existing.timeout);
+  store.set(key, createSignalRuntimeOptionsEntry(store, key, streamOptions));
+};
+var deleteSignalRuntimeOptionsEntry = (store, key) => {
+  const existing = store.get(key);
+  if (existing) clearTimeout(existing.timeout);
+  store.delete(key);
+};
+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 +572,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];
@@ -436,6 +709,52 @@ var Agent = class extends BaseResource {
     const queryString = searchParams.toString();
     return queryString ? `${delimiter}${queryString}` : "";
   }
+  getSignalRuntimeRunKey(runId) {
+    return `${this.options.baseUrl}|${this.apiPrefix}|${this.agentId}|${runId}`;
+  }
+  getSignalRuntimeThreadKey({
+    resourceId,
+    threadId
+  }) {
+    if (!threadId) return void 0;
+    return `${this.options.baseUrl}|${this.apiPrefix}|${this.agentId}|${resourceId ?? ""}|${threadId}`;
+  }
+  setSignalRuntimeOptions({
+    runId,
+    resourceId,
+    threadId,
+    streamOptions
+  }) {
+    const threadKey = this.getSignalRuntimeThreadKey({ resourceId, threadId });
+    if (runId) {
+      setSignalRuntimeOptionsEntry(signalRuntimeOptionsByRunId, this.getSignalRuntimeRunKey(runId), streamOptions);
+      if (threadKey) deleteSignalRuntimeOptionsEntry(latestSignalRuntimeOptionsByThread, threadKey);
+      return;
+    }
+    if (threadKey) {
+      setSignalRuntimeOptionsEntry(latestSignalRuntimeOptionsByThread, threadKey, streamOptions);
+    }
+  }
+  getSignalRuntimeOptions({
+    runId,
+    resourceId,
+    threadId
+  }) {
+    if (runId) {
+      const runOptions = signalRuntimeOptionsByRunId.get(this.getSignalRuntimeRunKey(runId));
+      if (runOptions) return runOptions.streamOptions;
+    }
+    const threadKey = this.getSignalRuntimeThreadKey({ resourceId, threadId });
+    return threadKey ? latestSignalRuntimeOptionsByThread.get(threadKey)?.streamOptions : void 0;
+  }
+  deleteSignalRuntimeOptions(runId) {
+    if (!runId) return;
+    deleteSignalRuntimeOptionsEntry(signalRuntimeOptionsByRunId, this.getSignalRuntimeRunKey(runId));
+  }
+  deleteLatestSignalRuntimeOptions({ resourceId, threadId }) {
+    const threadKey = this.getSignalRuntimeThreadKey({ resourceId, threadId });
+    if (threadKey) deleteSignalRuntimeOptionsEntry(latestSignalRuntimeOptionsByThread, threadKey);
+  }
   /**
    * Retrieves details about the agent
    * @param requestContext - Optional request context to pass as query parameter
@@ -481,32 +800,227 @@ var Agent = class extends BaseResource {
   /**
    * @experimental Agent signals are experimental and may change in a future release.
    */
-  sendSignal(params) {
-    return this.request(`/agents/${this.agentId}/signals`, {
-      method: "POST",
-      body: params
-    });
+  async sendSignal(params) {
+    const streamOptions = params.ifIdle?.streamOptions;
+    if (streamOptions) {
+      this.setSignalRuntimeOptions({
+        resourceId: params.resourceId,
+        threadId: params.threadId,
+        streamOptions
+      });
+    }
+    const body = params.ifIdle?.streamOptions ? {
+      ...params,
+      ifIdle: {
+        ...params.ifIdle,
+        streamOptions: {
+          ...params.ifIdle.streamOptions,
+          requestContext: parseClientRequestContext(params.ifIdle.streamOptions.requestContext),
+          clientTools: processClientTools(params.ifIdle.streamOptions.clientTools)
+        }
+      }
+    } : params;
+    let response;
+    try {
+      response = await this.request(`/agents/${this.agentId}/signals`, {
+        method: "POST",
+        body
+      });
+    } catch (error) {
+      if (streamOptions) {
+        this.deleteLatestSignalRuntimeOptions({ resourceId: params.resourceId, threadId: params.threadId });
+      }
+      throw error;
+    }
+    if (streamOptions) {
+      this.setSignalRuntimeOptions({
+        runId: response.runId,
+        resourceId: params.resourceId,
+        threadId: params.threadId,
+        streamOptions
+      });
+    }
+    return response;
   }
   /**
    * @experimental Agent signals are experimental and may change in a future release.
    */
   async subscribeToThread(params) {
-    const streamResponse = await this.request(`/agents/${this.agentId}/threads/subscribe`, {
+    const { resourceId, threadId } = params;
+    const requestSubscription = () => this.request(`/agents/${this.agentId}/threads/subscribe`, {
       method: "POST",
-      body: params,
+      body: { resourceId, threadId },
       stream: true
     });
+    const streamResponse = await requestSubscription();
     if (!streamResponse.body) {
       throw new Error("No response body");
     }
-    streamResponse.processDataStream = async ({
-      onChunk
-    }) => {
-      await processMastraStream({
-        stream: streamResponse.body,
-        onChunk,
-        signal: this.options.abortSignal
-      });
+    const agent = this;
+    streamResponse.processDataStream = async ({ onChunk, reconnect }) => {
+      const pendingToolCallsByRunId = /* @__PURE__ */ new Map();
+      const handleSubscribedChunk = async (chunk) => {
+        if (chunk.type === "tool-call") {
+          const payload = chunk.payload;
+          const toolCallId = payload?.toolCallId;
+          const toolName = payload?.toolName;
+          const runId2 = chunk.runId;
+          if (!toolCallId || !toolName || !runId2) return;
+          const pendingToolCalls2 = pendingToolCallsByRunId.get(runId2) ?? [];
+          pendingToolCalls2.push({ toolCallId, toolName, args: payload.args, observability: payload.observability });
+          pendingToolCallsByRunId.set(runId2, pendingToolCalls2);
+          return;
+        }
+        if (chunk.type !== "finish") return;
+        const runId = chunk.runId;
+        const finishPayload = chunk;
+        if (!runId) return;
+        if (finishPayload.payload?.stepResult?.reason !== "tool-calls") {
+          agent.deleteSignalRuntimeOptions(runId);
+          return;
+        }
+        const pendingToolCalls = pendingToolCallsByRunId.get(runId);
+        pendingToolCallsByRunId.delete(runId);
+        if (!pendingToolCalls?.length) {
+          agent.deleteSignalRuntimeOptions(runId);
+          return;
+        }
+        const activeRuntimeOptions = agent.getSignalRuntimeOptions({ runId, resourceId, threadId });
+        const activeClientTools = activeRuntimeOptions?.clientTools;
+        if (!activeClientTools) {
+          agent.deleteSignalRuntimeOptions(runId);
+          return;
+        }
+        const activeRequestContext = activeRuntimeOptions.requestContext;
+        const processedClientTools = processClientTools(activeClientTools);
+        const processedRequestContext = parseClientRequestContext(activeRequestContext);
+        const toolResultMessages = [];
+        for (const toolCall of pendingToolCalls) {
+          const clientTool = activeClientTools[toolCall.toolName];
+          if (!clientTool || typeof clientTool.execute !== "function") continue;
+          let result;
+          let observability;
+          try {
+            const execution = await executeClientToolWithObservability({
+              clientTool,
+              args: toolCall.args,
+              toolName: toolCall.toolName,
+              parentContext: toolCall.observability,
+              executeContext: {
+                requestContext: activeRequestContext,
+                tracingContext: { currentSpan: void 0 },
+                agent: {
+                  agentId: agent.agentId,
+                  messages: finishPayload.payload?.messages?.nonUser ?? [],
+                  toolCallId: toolCall.toolCallId,
+                  suspend: async () => {
+                  },
+                  threadId,
+                  resourceId
+                }
+              }
+            });
+            result = execution.result;
+            observability = execution.observability;
+          } catch (error) {
+            result = { error: String(error) };
+          }
+          const toolResultContent = {
+            type: "tool-result",
+            toolCallId: toolCall.toolCallId,
+            toolName: toolCall.toolName,
+            result
+          };
+          if (observability) {
+            toolResultContent.__mastraObservability = observability;
+          }
+          await onChunk({
+            type: "tool-result",
+            runId,
+            payload: toolResultContent
+          });
+          toolResultMessages.push({
+            role: "tool",
+            content: [toolResultContent]
+          });
+        }
+        if (toolResultMessages.length === 0) {
+          agent.deleteSignalRuntimeOptions(runId);
+          return;
+        }
+        try {
+          const continuation = await agent.streamUntilIdle(
+            [...finishPayload.payload?.messages?.nonUser ?? [], ...toolResultMessages],
+            {
+              ...activeRuntimeOptions,
+              runId: v4(),
+              requestContext: processedRequestContext,
+              memory: threadId ? { thread: threadId, resource: resourceId } : void 0,
+              clientTools: processedClientTools
+            }
+          );
+          try {
+            void continuation.body?.cancel?.();
+          } catch {
+          }
+        } catch (error) {
+          console.error("Error running client-tool continuation:", error);
+        } finally {
+          agent.deleteSignalRuntimeOptions(runId);
+        }
+      };
+      const reconnectOptions = reconnect === true ? { maxRetries: Infinity, delayMs: 1e3 } : reconnect ? { maxRetries: reconnect.maxRetries ?? Infinity, delayMs: reconnect.delayMs ?? 1e3 } : null;
+      let response = streamResponse;
+      let attempts = 0;
+      const onChunkErrorSentinel = /* @__PURE__ */ Symbol("onChunkErrorSentinel");
+      const guardedOnChunk = async (chunk) => {
+        try {
+          await onChunk(chunk);
+          await handleSubscribedChunk(chunk);
+        } catch (cause) {
+          throw { [onChunkErrorSentinel]: true, cause };
+        }
+      };
+      while (true) {
+        if (!response.body) {
+          throw new Error("No response body");
+        }
+        try {
+          await processMastraStream({
+            stream: response.body,
+            onChunk: guardedOnChunk,
+            signal: this.options.abortSignal
+          });
+        } catch (error) {
+          if (typeof error === "object" && error !== null && error[onChunkErrorSentinel]) {
+            throw error.cause;
+          }
+          if (!reconnectOptions || this.options.abortSignal?.aborted || attempts >= reconnectOptions.maxRetries) {
+            throw error;
+          }
+        }
+        if (!reconnectOptions || this.options.abortSignal?.aborted || attempts >= reconnectOptions.maxRetries) {
+          return;
+        }
+        while (attempts < reconnectOptions.maxRetries) {
+          attempts++;
+          if (this.options.abortSignal?.aborted) {
+            return;
+          }
+          await new Promise((resolve) => setTimeout(resolve, reconnectOptions.delayMs));
+          if (this.options.abortSignal?.aborted) {
+            return;
+          }
+          try {
+            response = await requestSubscription();
+            break;
+          } catch (error) {
+            if (this.options.abortSignal?.aborted || attempts >= reconnectOptions.maxRetries) {
+              throw error;
+            }
+          }
+        }
+      }
     };
     return streamResponse;
   }
@@ -654,17 +1168,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 +1196,8 @@ var Agent = class extends BaseResource {
                   type: "tool-result",
                   toolCallId: toolCall.toolCallId,
                   toolName: toolCall.toolName,
-                  result
+                  result,
+                  ...observability ? { __mastraObservability: observability } : {}
                 }
               ]
             }
@@ -876,14 +1397,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 +1422,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);
@@ -1023,6 +1548,7 @@ var Agent = class extends BaseResource {
     update,
     onToolCall,
     onFinish,
+    onStreamChunk,
     getCurrentDate = () => /* @__PURE__ */ new Date(),
     lastMessage
   }) {
@@ -1090,6 +1616,7 @@ var Agent = class extends BaseResource {
       // TODO: casting as any here because the stream types were all typed as any before in core.
       // but this is completely wrong and this fn is probably broken. Remove ":any" and you'll see a bunch of type errors
       onChunk: async (chunk) => {
+        onStreamChunk?.(chunk);
         switch (chunk.type) {
           case "tripwire": {
             message.parts.push({
@@ -1191,6 +1718,7 @@ var Agent = class extends BaseResource {
                 execUpdate();
               }
             }
+            break;
           }
           case "tool-call-input-streaming-start": {
             if (message.toolInvocations == null) {
@@ -1200,14 +1728,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 +1754,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);
@@ -1303,6 +1835,7 @@ var Agent = class extends BaseResource {
     try {
       let toolCalls = [];
       let messages = [];
+      let streamRunId = processedParams.runId;
       const [streamForController, streamForProcessing] = response.body.tee();
       const pipePromise = streamForController.pipeTo(
         new WritableStream({
@@ -1342,27 +1875,90 @@ 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 runId = streamRunId ?? toolCall2.toolCallId;
+                let result;
+                let observability;
+                let synthetic;
+                try {
+                  ({ 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
+                      }
+                    }
+                  }));
+                  synthetic = {
+                    type: "tool-result",
+                    runId,
+                    from: "AGENT",
+                    payload: {
+                      toolCallId: toolCall2.toolCallId,
+                      toolName: toolCall2.toolName,
+                      result,
+                      isError: false,
+                      providerExecuted: false
+                    }
+                  };
+                } catch (error) {
+                  synthetic = {
+                    type: "tool-error",
+                    runId,
+                    from: "AGENT",
+                    payload: {
+                      toolCallId: toolCall2.toolCallId,
+                      toolName: toolCall2.toolName,
+                      error,
+                      args: toolCall2?.args,
+                      providerExecuted: false
+                    }
+                  };
+                  result = { error: error instanceof Error ? error.message : String(error) };
+                }
+                try {
+                  await pipePromise;
+                } catch {
+                }
+                try {
+                  const errorForSerialization = synthetic.type === "tool-error" ? synthetic.payload.error : void 0;
+                  const serializedError = errorForSerialization instanceof Error ? {
+                    name: errorForSerialization.name,
+                    message: errorForSerialization.message,
+                    stack: errorForSerialization.stack
+                  } : errorForSerialization;
+                  const payloadForWire = synthetic.type === "tool-error" ? { ...synthetic, payload: { ...synthetic.payload, error: serializedError } } : synthetic;
+                  const sseLine = `data: ${JSON.stringify(payloadForWire)}
+
+`;
+                  controller.enqueue(new TextEncoder().encode(sseLine));
+                } catch (enqueueErr) {
+                  console.error("Failed to enqueue synthetic tool-result chunk:", enqueueErr);
+                }
                 const lastMessageRaw = messages[messages.length - 1];
                 const lastMessage = lastMessageRaw != null ? JSON.parse(JSON.stringify(lastMessageRaw)) : void 0;
                 const toolInvocationPart = lastMessage?.parts?.find(
@@ -1372,7 +1968,8 @@ var Agent = class extends BaseResource {
                   toolInvocationPart.toolInvocation = {
                     ...toolInvocationPart.toolInvocation,
                     state: "result",
-                    result
+                    result,
+                    ...observability ? { __mastraObservability: observability } : {}
                   };
                 }
                 const toolInvocation = lastMessage?.toolInvocations?.find(
@@ -1381,6 +1978,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];
@@ -1408,6 +2008,11 @@ var Agent = class extends BaseResource {
             controller.close();
           }
         },
+        onStreamChunk: (chunk) => {
+          if (!streamRunId && typeof chunk.runId === "string") {
+            streamRunId = chunk.runId;
+          }
+        },
         lastMessage: void 0
       }).catch(async (error) => {
         console.error("Error processing stream response:", error);
@@ -1815,23 +2420,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 +2459,8 @@ var Agent = class extends BaseResource {
                   toolInvocationPart.toolInvocation = {
                     ...toolInvocationPart.toolInvocation,
                     state: "result",
-                    result
+                    result,
+                    ...observability ? { __mastraObservability: observability } : {}
                   };
                 }
                 const toolInvocation = lastMessage?.toolInvocations?.find(
@@ -1851,6 +2469,9 @@ var Agent = class extends BaseResource {
                 if (toolInvocation) {
                   toolInvocation.state = "result";
                   toolInvocation.result = result;
+                  if (observability) {
+                    toolInvocation.__mastraObservability = observability;
+                  }
                 }
                 const writer = writable.getWriter();
                 try {