@mastra/client-js 1.32.1-alpha.2 → 1.33.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @mastra/client-js
 
+## 1.33.0-alpha.3
+
+### Minor Changes
+
+- Added a `requestContext` option to agent controller session methods in @mastra/client-js. You can now pass custom request context to `sendMessage`, `steer`, `followUp`, `approveTool`, and `respondToToolSuspension`, matching what `agent.generate()` already supports. The context is merged into the run's request context on the server, so it reaches dynamic instructions and tools. ([#19531](https://github.com/mastra-ai/mastra/pull/19531))
+
+  ```ts
+  const session = client.getAgentController('code').session('user-1');
+  await session.sendMessage('hello', { requestContext: { userId: 'user-1', tier: 'pro' } });
+  ```
+
+- Added reconnect support to `AgentControllerSession.subscribe()` so SSE subscriptions recover after proxy timeouts or transport errors. Fixes #19202. ([#19560](https://github.com/mastra-ai/mastra/pull/19560))
+
+  ```ts
+  await session.subscribe({
+    onEvent: event => {
+      /* handle event */
+    },
+    reconnect: true,
+  });
+  ```
+
+### Patch Changes
+
+- Fixed AgentController live events and thread history returning serialized message timestamps instead of Date values. ([#18783](https://github.com/mastra-ai/mastra/pull/18783))
+
+- Fixed AgentControllerSession.subscribe() so it resolves only after the stream is established and rejects when it cannot connect (leaving no background retry loop). Reconnect now applies only after an established stream drops, backs off exponentially, and fires a new onReconnect callback on each re-established stream so consumers can re-sync missed events: ([#19580](https://github.com/mastra-ai/mastra/pull/19580))
+
+  ```ts
+  const subscription = await session.subscribe({
+    onEvent: event => applyEvent(event),
+    onError: error => showDisconnected(error),
+    reconnect: { maxRetries: 5, delayMs: 1000, maxDelayMs: 30_000 },
+    onReconnect: async () => {
+      // Events emitted while disconnected are not replayed — re-sync state.
+      applyState(await session.state());
+    },
+  });
+  ```
+
+- Added stable metrics and logs capability reporting for observability storage. The system packages response now includes `observabilityStorageCapabilities` with `metrics` and `logs` flags, enabling capability-based detection that is resilient to bundler-generated constructor name changes. ([#19305](https://github.com/mastra-ai/mastra/pull/19305))
+
+  ```typescript
+  const packages = await client.getSystemPackages();
+  console.log(packages.observabilityStorageCapabilities?.metrics); // true
+  console.log(packages.observabilityStorageCapabilities?.logs); // true
+  ```
+
+  Studio now uses the capability response instead of relying on constructor names, with a fallback for older servers.
+
+- Updated dependencies [[`1426af2`](https://github.com/mastra-ai/mastra/commit/1426af24975879c000d13ac75673f630fcc970c1), [`975295d`](https://github.com/mastra-ai/mastra/commit/975295d418552f0d46a59edfef4c3ee555f9930a), [`85e4fb5`](https://github.com/mastra-ai/mastra/commit/85e4fb50087a81c74df3a762f53b56373db0b912), [`ef03c0c`](https://github.com/mastra-ai/mastra/commit/ef03c0cfc62367a458e4cc56462e2148b35681c5), [`4fb4d88`](https://github.com/mastra-ai/mastra/commit/4fb4d881bc107acee13890ad4d78661016c510ed), [`4eba27a`](https://github.com/mastra-ai/mastra/commit/4eba27adcf60f991df0e62f94b3e75b4e67f3b4b), [`c701be3`](https://github.com/mastra-ai/mastra/commit/c701be32d7d9aa94a66da8c6cc38dcac6856f464)]:
+  - @mastra/core@1.52.0-alpha.3
+
 ## 1.32.1-alpha.2
 
 ### 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.32.1-alpha.2"
+  version: "1.33.0-alpha.3"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.32.1-alpha.2",
+  "version": "1.33.0-alpha.3",
   "package": "@mastra/client-js",
   "exports": {
     "RequestContext": {

package/dist/index.cjs

@@ -6144,6 +6144,19 @@ var Channels = class extends BaseResource {
 };
 
 // src/resources/agent-controller.ts
+function hydrateMessage(message) {
+  return {
+    ...message,
+    createdAt: message.createdAt instanceof Date ? message.createdAt : new Date(message.createdAt)
+  };
+}
+function hydrateEventMessage(event) {
+  if (event.type !== "message_start" && event.type !== "message_update" && event.type !== "message_end") return event;
+  return {
+    ...event,
+    message: hydrateMessage(event.message)
+  };
+}
 var AgentControllerSession = class extends BaseResource {
   constructor(options, controllerId, resourceId, scope) {
     super(options);
@@ -6179,46 +6192,158 @@ var AgentControllerSession = class extends BaseResource {
   /**
    * Subscribe to this session's event stream (SSE). The assistant's reply to a
    * message arrives here as `message_*` events, not on the sendMessage call.
+   *
+   * The returned promise resolves once the stream is actually established and
+   * rejects when it cannot be. A rejected subscribe leaves nothing running —
+   * `reconnect` governs only re-establishment after an established stream
+   * drops, so callers that want connect-time retry can loop around
+   * `subscribe()` themselves and keep cancellation control.
    */
   async subscribe(options) {
-    const response = await this.request(this.url(`${this.base()}/stream`), { stream: true });
-    if (!response.body) {
-      throw new Error("No response body for agent controller session stream");
-    }
-    const reader = response.body.getReader();
-    const decoder = new TextDecoder();
+    const finiteOr = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+    const retriesOr = (value, fallback) => value === Infinity || typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+    const reconnectOptions = options.reconnect === true ? { maxRetries: Infinity, delayMs: 1e3, maxDelayMs: 3e4 } : options.reconnect ? {
+      maxRetries: retriesOr(options.reconnect.maxRetries, Infinity),
+      delayMs: finiteOr(options.reconnect.delayMs, 1e3),
+      maxDelayMs: finiteOr(options.reconnect.maxDelayMs, 3e4)
+    } : null;
+    const backoffDelay = (attempt) => reconnectOptions ? Math.min(reconnectOptions.delayMs * 2 ** (attempt - 1), reconnectOptions.maxDelayMs) : 0;
     let cancelled = false;
-    let buffer = "";
-    const pump = async () => {
+    let currentReader = null;
+    let reconnectTimer;
+    let delayResolve;
+    const settleDelay = () => {
+      if (reconnectTimer) {
+        clearTimeout(reconnectTimer);
+        reconnectTimer = void 0;
+      }
+      const resolve = delayResolve;
+      delayResolve = void 0;
+      resolve?.();
+    };
+    const delay = (ms) => new Promise((resolve) => {
+      delayResolve = resolve;
+      reconnectTimer = setTimeout(settleDelay, ms);
+    });
+    const requestStream = async () => {
+      const response = await this.request(this.url(`${this.base()}/stream`), { stream: true });
+      if (!response.body) {
+        throw new Error("No response body for agent controller session stream");
+      }
+      return response;
+    };
+    const streamEndedError = () => new Error("Agent controller session stream ended unexpectedly");
+    const findFrameSeparator = (text) => {
+      const candidates = [
+        { index: text.indexOf("\r\n\r\n"), length: 4 },
+        { index: text.indexOf("\n\n"), length: 2 },
+        { index: text.indexOf("\r\r"), length: 2 }
+      ].filter((candidate) => candidate.index !== -1);
+      if (candidates.length === 0) return null;
+      return candidates.reduce((earliest, candidate) => candidate.index < earliest.index ? candidate : earliest);
+    };
+    const pump = async (response) => {
+      const reader = response.body.getReader();
+      currentReader = reader;
+      const decoder = new TextDecoder();
+      let buffer = "";
       try {
         while (!cancelled) {
           const { done, value } = await reader.read();
-          if (done) break;
+          if (done) return cancelled ? { kind: "cancelled" } : { kind: "done" };
           buffer += decoder.decode(value, { stream: true });
-          let sep;
-          while ((sep = buffer.indexOf("\n\n")) !== -1) {
-            const frame = buffer.slice(0, sep);
-            buffer = buffer.slice(sep + 2);
-            for (const line of frame.split("\n")) {
+          let separator;
+          while ((separator = findFrameSeparator(buffer)) !== null) {
+            const frame = buffer.slice(0, separator.index);
+            buffer = buffer.slice(separator.index + separator.length);
+            for (const line of frame.split(/\r\n|\n|\r/)) {
               if (!line.startsWith("data:")) continue;
               const data = line.slice(5).trim();
               if (!data) continue;
+              let event;
               try {
-                options.onEvent(JSON.parse(data));
+                event = hydrateEventMessage(JSON.parse(data));
               } catch {
+                continue;
+              }
+              try {
+                options.onEvent(event);
+              } catch (cause) {
+                if (!cancelled) safeOnError(cause);
+                return { kind: "consumer_error" };
               }
             }
           }
         }
+        return { kind: "cancelled" };
+      } catch (error) {
+        return cancelled ? { kind: "cancelled" } : { kind: "transport_error", error };
+      } finally {
+        if (currentReader === reader) currentReader = null;
+        void reader.cancel().catch(() => {
+        });
+      }
+    };
+    const safeOnError = (error) => {
+      try {
+        options.onError?.(error);
+      } catch {
+      }
+    };
+    const reportTerminalError = (result) => {
+      safeOnError(result.kind === "transport_error" ? result.error : streamEndedError());
+    };
+    const pumpSafe = async (response) => {
+      try {
+        return await pump(response);
       } catch (error) {
-        if (!cancelled) options.onError?.(error);
+        return cancelled ? { kind: "cancelled" } : { kind: "transport_error", error };
+      }
+    };
+    const firstResponse = await requestStream();
+    const run = async (initial) => {
+      let response = initial;
+      while (!cancelled) {
+        let result = await pumpSafe(response);
+        if (cancelled || result.kind === "cancelled" || result.kind === "consumer_error") return;
+        if (!reconnectOptions) {
+          reportTerminalError(result);
+          return;
+        }
+        let attempts = 0;
+        let reconnectedResponse;
+        while (!reconnectedResponse) {
+          if (attempts >= reconnectOptions.maxRetries) {
+            reportTerminalError(result);
+            return;
+          }
+          attempts++;
+          await delay(backoffDelay(attempts));
+          if (cancelled) return;
+          try {
+            reconnectedResponse = await requestStream();
+          } catch (error) {
+            result = { kind: "transport_error", error };
+          }
+        }
+        if (cancelled) {
+          void reconnectedResponse.body?.cancel().catch(() => {
+          });
+          return;
+        }
+        response = reconnectedResponse;
+        try {
+          options.onReconnect?.();
+        } catch {
+        }
       }
     };
-    void pump();
+    void run(firstResponse);
     return {
       unsubscribe: () => {
         cancelled = true;
-        void reader.cancel().catch(() => {
+        settleDelay();
+        void currentReader?.cancel().catch(() => {
         });
       }
     };
@@ -6227,12 +6352,18 @@ var AgentControllerSession = class extends BaseResource {
    * Send a user message. The reply streams over `subscribe()`.
    * Pass a structured message to attach files (e.g. pasted images) as base64-encoded data:
    * `sendMessage({ content: 'What is in this image?', files })`.
+   * Pass `options.requestContext` to merge custom context into the run's request context.
    */
-  async sendMessage(message) {
+  async sendMessage(message, options) {
     const { content, files } = typeof message === "string" ? { content: message, files: void 0 } : message;
+    const requestContext = parseClientRequestContext(options?.requestContext);
     await this.request(this.url(`${this.base()}/messages`), {
       method: "POST",
-      body: { message: content, ...files?.length ? { files } : {} }
+      body: {
+        message: content,
+        ...files?.length ? { files } : {},
+        ...requestContext ? { requestContext } : {}
+      }
     });
   }
   /** Abort the in-flight run for this session. */
@@ -6240,10 +6371,11 @@ var AgentControllerSession = class extends BaseResource {
     await this.request(this.url(`${this.base()}/abort`), { method: "POST" });
   }
   /** Approve or decline a pending tool call (`tool_approval_required`). */
-  async approveTool(toolCallId, approved) {
+  async approveTool(toolCallId, approved, options) {
+    const requestContext = parseClientRequestContext(options?.requestContext);
     await this.request(this.url(`${this.base()}/tool-approval`), {
       method: "POST",
-      body: { toolCallId, approved }
+      body: { toolCallId, approved, ...requestContext ? { requestContext } : {} }
     });
   }
   /**
@@ -6251,15 +6383,20 @@ var AgentControllerSession = class extends BaseResource {
    * depends on the tool: a string (or string[]) for `ask_user`, "Yes"/"No" for
    * `request_access`, and a {@link PlanResume} for `submit_plan`.
    */
-  async respondToToolSuspension(toolCallId, resumeData) {
+  async respondToToolSuspension(toolCallId, resumeData, options) {
+    const requestContext = parseClientRequestContext(options?.requestContext);
     await this.request(this.url(`${this.base()}/tool-suspension`), {
       method: "POST",
-      body: { toolCallId, resumeData }
+      body: { toolCallId, resumeData, ...requestContext ? { requestContext } : {} }
     });
   }
   /** Inject a message into the in-flight run without starting a new turn. */
-  async steer(message) {
-    await this.request(this.url(`${this.base()}/steer`), { method: "POST", body: { message } });
+  async steer(message, options) {
+    const requestContext = parseClientRequestContext(options?.requestContext);
+    await this.request(this.url(`${this.base()}/steer`), {
+      method: "POST",
+      body: { message, ...requestContext ? { requestContext } : {} }
+    });
   }
   /** Get the current mode, model, and thread (for initial UI hydration). */
   state() {
@@ -6335,14 +6472,18 @@ var AgentControllerSession = class extends BaseResource {
     const body = await this.request(
       this.url(`${this.base()}/threads/${encodeURIComponent(threadId)}/messages${params}`)
     );
-    return body.messages;
+    return body.messages.map(hydrateMessage);
   }
   /**
    * Queue a follow-up message. If the session is idle it sends immediately;
    * if a run is active it queues for after completion.
    */
-  async followUp(message) {
-    await this.request(this.url(`${this.base()}/follow-up`), { method: "POST", body: { message } });
+  async followUp(message, options) {
+    const requestContext = parseClientRequestContext(options?.requestContext);
+    await this.request(this.url(`${this.base()}/follow-up`), {
+      method: "POST",
+      body: { message, ...requestContext ? { requestContext } : {} }
+    });
   }
   /** Get the observational memory record for this session's thread. */
   async getOMRecord() {
@@ -6452,7 +6593,7 @@ var AgentController = class extends BaseResource {
   }
 };
 function agentControllerMessageText(message) {
-  return message.content.filter((c) => c.type === "text" && typeof c.text === "string").map((c) => c.text).join("");
+  return message.content.parts.filter((p) => p.type === "text" && typeof p.text === "string").map((p) => p.text).join("");
 }
 
 // src/client.ts