@mastra/client-js 1.20.0-alpha.0 → 1.20.0-alpha.10

package/dist/docs/references/docs-agents-signals.md

@@ -1,6 +1,6 @@
 # Signals
 
-> **Experimental:** Agent signals are experimental. Breaking changes may occur without a major version bump until the API is stable.
+> **Experimental:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
 
 Signals are a way to interact with an agent through a thread. Instead of starting every interaction with `agent.stream()`, subscribe to a thread and send signals. Mastra either wakes the agent when the thread is idle or drops the signal into the running agent loop.
 
@@ -86,6 +86,32 @@ agent.sendSignal(
 )
 ```
 
+## Identify users with attributes
+
+Use `attributes` to tag each signal with user identity. The signal type and attributes are rendered as XML so the model can distinguish who said what in a multi-user thread:
+
+```typescript
+agent.sendSignal(
+  {
+    type: 'user',
+    contents: 'Can we simplify the API surface?',
+    attributes: { name: 'Devin', from: 'slack' },
+  },
+  {
+    resourceId: 'user_123',
+    threadId: 'thread_456',
+  },
+)
+```
+
+The model receives:
+
+```xml
+<user name="Devin" from="slack">Can we simplify the API surface?</user>
+```
+
+The UI sees just the message contents but can also read `attributes` and `metadata` off the signal message for custom rendering (e.g. showing user names, avatars, or platform badges).
+
 ## Send external event context
 
 Use custom signal types for system-generated context. Non-user signal types are rendered as XML-style user-role context so they can appear inside conversation history without looking like assistant output.
@@ -96,7 +122,7 @@ agent.sendSignal(
     type: 'system-reminder',
     contents: 'User X has left a new PR comment asking for a smaller API surface.',
     attributes: {
-      type: 'github',
+      source: 'github',
       pr: '123',
     },
   },
@@ -110,7 +136,7 @@ agent.sendSignal(
 The model receives the custom signal as context like this:
 
 ```xml
-<system-reminder type="github" pr="123">User X has left a new PR comment asking for a smaller API surface.</system-reminder>
+<system-reminder source="github" pr="123">User X has left a new PR comment asking for a smaller API surface.</system-reminder>
 ```
 
 Use XML-safe signal type names and attribute names. Signal type names and attribute names can contain letters, numbers, underscores, periods, and hyphens. They must start with a letter or underscore.

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

@@ -201,7 +201,7 @@ await agent.sendSignal({
 
 Returns `{ accepted: true, runId: string }`.
 
-**signal** (`{ type: 'user-message' | string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): \`user-message\` signals are treated as user input. Other signal types are wrapped in XML context (with any \`attributes\`) before the next model call. \`providerOptions\` is attached to the resulting prompt turn and persisted on the stored signal message.
+**signal** (`{ type: 'user-message' | 'system-reminder' | string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): \`user-message\` signals without attributes are treated as plain user input. All other signals — including \`user-message\` with \`attributes\`, \`system-reminder\`, and custom types — are wrapped in an XML element named after the signal type with \`attributes\` rendered as XML attributes (e.g. \`\<user name="Devin" from="slack">message\</user>\`). The model sees the XML; the UI sees the raw contents and can read \`attributes\` for custom rendering. \`providerOptions\` is attached to the resulting prompt turn and persisted on the stored signal message.
 
 **runId** (`string`): Run ID to target directly.
 

package/dist/index.cjs

@@ -449,6 +449,34 @@ var Agent = class extends BaseResource {
   details(requestContext) {
     return this.request(`/agents/${this.agentId}${this.getQueryString(requestContext)}`);
   }
+  /**
+   * Probe the agent's browser session state before opening a screencast WebSocket.
+   *
+   * Returns `{ hasSession, screencastAvailable }`. Use this to avoid opening a WS
+   * that would either fail (screencast packages not installed) or sit idle (no
+   * active browser session yet). See {@link GetAgentBrowserSessionResponse}.
+   *
+   * @param threadId - Optional thread ID for thread-scoped browser sessions
+   */
+  browserSession(threadId) {
+    const query = threadId ? `?threadId=${encodeURIComponent(threadId)}` : "";
+    return this.request(`/agents/${this.agentId}/browser/session${query}`);
+  }
+  /**
+   * Close the agent's browser session.
+   *
+   * For thread-scoped browsers, pass `threadId` to close only that thread's
+   * session. Omit it to close the shared session (or all sessions for the agent
+   * depending on the toolset's scope).
+   *
+   * @param threadId - Optional thread ID for thread-scoped browser sessions
+   */
+  closeBrowser(threadId) {
+    return this.request(`/agents/${this.agentId}/browser/close`, {
+      method: "POST",
+      body: { threadId }
+    });
+  }
   enhanceInstructions(instructions, comment) {
     return this.request(`/agents/${this.agentId}/instructions/enhance`, {
       method: "POST",
@@ -1361,6 +1389,7 @@ var Agent = class extends BaseResource {
                 }
                 const newMessages = lastMessage != null ? [...messages.filter((m) => m.id !== lastMessage.id), lastMessage] : [...messages];
                 const updatedMessages = threadId ? newMessages : [...Array.isArray(processedParams.messages) ? processedParams.messages : [], ...newMessages];
+                const recursionRoute = route === "resume-stream" ? "stream" : route === "resume-stream-until-idle" ? "stream-until-idle" : route;
                 try {
                   await this.processStreamResponse(
                     {
@@ -1368,7 +1397,7 @@ var Agent = class extends BaseResource {
                       messages: updatedMessages
                     },
                     controller,
-                    route
+                    recursionRoute
                   );
                 } catch (error) {
                   console.error("Error processing recursive stream response:", error);
@@ -4045,6 +4074,37 @@ var StoredAgent = class extends BaseResource {
     );
   }
   // ==========================================================================
+  // Favorite Methods (EE feature)
+  // ==========================================================================
+  /**
+   * Favorites this agent for the calling user. Idempotent.
+   * Requires the `agent.favorites` builder feature flag to be enabled on the server.
+   * @param requestContext - Optional request context to pass as query parameter
+   * @returns Promise containing the new favorited state and updated favorite count
+   */
+  favorite(requestContext) {
+    return this.request(
+      `/stored/agents/${encodeURIComponent(this.storedAgentId)}/favorite${requestContextQueryString(requestContext)}`,
+      {
+        method: "PUT"
+      }
+    );
+  }
+  /**
+   * Unfavorites this agent for the calling user. Idempotent.
+   * Requires the `agent.favorites` builder feature flag to be enabled on the server.
+   * @param requestContext - Optional request context to pass as query parameter
+   * @returns Promise containing the new favorited state and updated favorite count
+   */
+  unfavorite(requestContext) {
+    return this.request(
+      `/stored/agents/${encodeURIComponent(this.storedAgentId)}/favorite${requestContextQueryString(requestContext)}`,
+      {
+        method: "DELETE"
+      }
+    );
+  }
+  // ==========================================================================
   // Version Methods
   // ==========================================================================
   /**
@@ -4862,6 +4922,30 @@ var StoredSkill = class extends BaseResource {
       }
     );
   }
+  /**
+   * Favorites this skill for the calling user. Idempotent.
+   * Requires the `skill.favorites` builder feature flag to be enabled on the server.
+   */
+  favorite(requestContext) {
+    return this.request(
+      `/stored/skills/${encodeURIComponent(this.storedSkillId)}/favorite${requestContextQueryString(requestContext)}`,
+      {
+        method: "PUT"
+      }
+    );
+  }
+  /**
+   * Unfavorites this skill for the calling user. Idempotent.
+   * Requires the `skill.favorites` builder feature flag to be enabled on the server.
+   */
+  unfavorite(requestContext) {
+    return this.request(
+      `/stored/skills/${encodeURIComponent(this.storedSkillId)}/favorite${requestContextQueryString(requestContext)}`,
+      {
+        method: "DELETE"
+      }
+    );
+  }
 };
 
 // src/resources/responses.ts
@@ -5867,12 +5951,24 @@ var MastraClient = class extends BaseResource {
         searchParams.set("orderBy[direction]", params.orderBy.direction);
       }
     }
+    if (params?.status) {
+      searchParams.set("status", params.status);
+    }
     if (params?.authorId) {
       searchParams.set("authorId", params.authorId);
     }
+    if (params?.visibility) {
+      searchParams.set("visibility", params.visibility);
+    }
     if (params?.metadata) {
       searchParams.set("metadata", JSON.stringify(params.metadata));
     }
+    if (params?.favoritedOnly) {
+      searchParams.set("favoritedOnly", "true");
+    }
+    if (params?.pinFavoritedFor) {
+      searchParams.set("pinFavoritedFor", params.pinFavoritedFor);
+    }
     const queryString = searchParams.toString();
     return this.request(`/stored/agents${queryString ? `?${queryString}` : ""}`);
   }
@@ -6081,9 +6177,18 @@ var MastraClient = class extends BaseResource {
     if (params?.authorId) {
       searchParams.set("authorId", params.authorId);
     }
+    if (params?.visibility) {
+      searchParams.set("visibility", params.visibility);
+    }
     if (params?.metadata) {
       searchParams.set("metadata", JSON.stringify(params.metadata));
     }
+    if (params?.favoritedOnly) {
+      searchParams.set("favoritedOnly", "true");
+    }
+    if (params?.pinFavoritedFor) {
+      searchParams.set("pinFavoritedFor", params.pinFavoritedFor);
+    }
     const queryString = searchParams.toString();
     return this.request(`/stored/skills${queryString ? `?${queryString}` : ""}`);
   }
@@ -6153,6 +6258,80 @@ var MastraClient = class extends BaseResource {
     return this.request("/system/packages");
   }
   // ============================================================================
+  // Editor / Builder
+  // ============================================================================
+  /**
+   * Retrieves agent builder settings for UI gating.
+   * Returns feature flags and configuration set by admin.
+   * @returns Promise containing builder settings
+   */
+  getBuilderSettings() {
+    return this.request("/editor/builder/settings");
+  }
+  /**
+   * Retrieves Agent Builder infrastructure configuration and resolution status.
+   * Requires `infrastructure:read` permission.
+   * @returns Promise containing infrastructure status
+   */
+  getInfrastructureStatus() {
+    return this.request("/editor/builder/infrastructure");
+  }
+  /**
+   * Lists known skill registries surfaced by the Agent Builder config.
+   * Each entry reports whether the registry is enabled. Disabled or unknown
+   * registries return 404 from registry-scoped routes.
+   * Requires `stored-skills:read` permission.
+   */
+  listBuilderRegistries() {
+    return this.request("/editor/builder/registries");
+  }
+  /**
+   * Search a builder skill registry. The registry must be enabled or the
+   * server returns 404.
+   * Requires `stored-skills:read` permission.
+   */
+  searchBuilderRegistry(registryId, params) {
+    const search = new URLSearchParams({ q: params.q });
+    if (params.limit !== void 0) search.set("limit", String(params.limit));
+    return this.request(`/editor/builder/registries/${encodeURIComponent(registryId)}/search?${search.toString()}`);
+  }
+  /**
+   * Fetch the popular skills feed from a builder skill registry.
+   * Requires `stored-skills:read` permission.
+   */
+  getBuilderRegistryPopular(registryId, params) {
+    const search = new URLSearchParams();
+    if (params?.limit !== void 0) search.set("limit", String(params.limit));
+    if (params?.offset !== void 0) search.set("offset", String(params.offset));
+    const query = search.toString();
+    return this.request(
+      `/editor/builder/registries/${encodeURIComponent(registryId)}/popular${query ? `?${query}` : ""}`
+    );
+  }
+  /**
+   * Fetch the rendered preview content for a single registry skill.
+   * Requires `stored-skills:read` permission.
+   */
+  getBuilderRegistryPreview(registryId, params) {
+    const search = new URLSearchParams({
+      owner: params.owner,
+      repo: params.repo,
+      path: params.path
+    });
+    return this.request(`/editor/builder/registries/${encodeURIComponent(registryId)}/preview?${search.toString()}`);
+  }
+  /**
+   * Install a registry skill into the builder's stored-skills DB.
+   * Returns 409 when a stored skill with the derived id already exists.
+   * Requires `stored-skills:write` permission.
+   */
+  installBuilderRegistrySkill(registryId, body) {
+    return this.request(`/editor/builder/registries/${encodeURIComponent(registryId)}/install`, {
+      method: "POST",
+      body
+    });
+  }
+  // ============================================================================
   // Workspace
   // ============================================================================
   /**
@@ -6171,6 +6350,32 @@ var MastraClient = class extends BaseResource {
     return new Workspace(this.options, workspaceId);
   }
   // ============================================================================
+  // Stored Workspaces
+  // ============================================================================
+  /**
+   * Lists stored workspace configurations from the database
+   * @param params - Optional filter and pagination parameters
+   * @returns Promise containing paginated list of stored workspaces
+   */
+  listStoredWorkspaces(params) {
+    const searchParams = new URLSearchParams();
+    if (params?.page !== void 0) searchParams.set("page", String(params.page));
+    if (params?.perPage !== void 0) searchParams.set("perPage", String(params.perPage));
+    if (params?.authorId) searchParams.set("authorId", params.authorId);
+    if (params?.orderBy?.field) searchParams.set("orderBy[field]", params.orderBy.field);
+    if (params?.orderBy?.direction) searchParams.set("orderBy[direction]", params.orderBy.direction);
+    const qs = searchParams.toString();
+    return this.request(`/stored/workspaces${qs ? `?${qs}` : ""}`);
+  }
+  /**
+   * Gets a specific stored workspace by ID
+   * @param id - The workspace ID
+   * @returns Promise containing the stored workspace
+   */
+  getStoredWorkspace(id) {
+    return this.request(`/stored/workspaces/${encodeURIComponent(id)}`);
+  }
+  // ============================================================================
   // Vectors & Embedders
   // ============================================================================
   /**