@mastra/client-js 1.13.5-alpha.9 → 1.14.0-alpha.10

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @mastra/client-js
 
+## 1.14.0-alpha.10
+
+### Minor Changes
+
+- Added `forEachIndex` option to `run.resume()`, `run.resumeAsync()`, and `run.resumeStream()`. Use it to resume a single iteration of a suspended `.foreach()` step while leaving the other iterations suspended. ([#15563](https://github.com/mastra-ai/mastra/pull/15563))
+
+  ```ts
+  await client
+    .getWorkflow('myWorkflow')
+    .createRun(runId)
+    .resume({
+      step: 'approve',
+      resumeData: { ok: true },
+      forEachIndex: 1, // only resume the second iteration
+    });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`aba393e`](https://github.com/mastra-ai/mastra/commit/aba393e2da7390c69b80e516a4f153cda6f09376), [`0a5fa1d`](https://github.com/mastra-ai/mastra/commit/0a5fa1d3cb0583889d06687155f26fd7d2edc76c), [`ea43e64`](https://github.com/mastra-ai/mastra/commit/ea43e646dd95d507694b6112b0bf1df22ad552b2), [`00d1b16`](https://github.com/mastra-ai/mastra/commit/00d1b16b401199cb294fa23f43336547db4dca9b), [`af8a57e`](https://github.com/mastra-ai/mastra/commit/af8a57ed9ba9685ad8601d5b71ae3706da6222f9)]:
+  - @mastra/core@1.26.0-alpha.10
+
 ## 1.13.5-alpha.9
 
 ### Patch Changes

package/dist/_types/@internal_ai-sdk-v5/dist/index.d.ts

@@ -435,6 +435,8 @@ export declare type AsyncIterableStream<T> = AsyncIterable<T> & ReadableStream<T
  * Attributes is a map from string to attribute values.
  *
  * Note: only the own enumerable keys are counted as valid attribute keys.
+ *
+ * @since 1.3.0
  */
 declare interface Attributes {
     [attributeKey: string]: AttributeValue | undefined;
@@ -444,6 +446,8 @@ declare interface Attributes {
  * Attribute values may be any non-nullish primitive value except an object.
  *
  * null or undefined attribute values are invalid and will result in undefined behavior.
+ *
+ * @since 1.3.0
  */
 declare type AttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
 
@@ -778,6 +782,9 @@ export declare type ContentPart<TOOLS extends ToolSet> = {
     providerMetadata?: ProviderMetadata;
 });
 
+/**
+ * @since 1.0.0
+ */
 declare interface Context {
     /**
      * Get a value from the context.
@@ -1705,6 +1712,8 @@ declare class EventSourceParserStream extends TransformStream<string, EventSourc
  * Defines Exception.
  *
  * string or an object with one of (message or name or code) and optional stack
+ *
+ * @since 1.0.0
  */
 declare type Exception = ExceptionWithCode | ExceptionWithMessage | ExceptionWithName | string;
 
@@ -2973,6 +2982,8 @@ export declare function hasToolCall(toolName: string): StopCondition<any>;
  * The second number is calculated by converting the digits after the decimal point of the subtraction, (1609504210150 / 1000) - HrTime[0], to nanoseconds:
  * HrTime[1] = Number((1609504210.150 - HrTime[0]).toFixed(9)) * 1e9 = 150000000.
  * This is represented in HrTime format as [1609504210, 150000000].
+ *
+ * @since 1.0.0
  */
 declare type HrTime = [number, number];
 
@@ -5546,6 +5557,8 @@ declare function lazyValidator<OBJECT>(createValidator: () => Validator<OBJECT>)
  *    However, it is desirable to associate incoming SpanContext to new trace
  *    initiated on service provider side so two traces (from Client and from
  *    Service Provider) can be correlated.
+ *
+ * @since 1.0.0
  */
 declare interface Link {
     /** The {@link SpanContext} of a linked span. */
@@ -7019,6 +7032,8 @@ export declare type SourceUrlUIPart = {
  * may have children.
  *
  * Spans are created by the {@link Tracer.startSpan} method.
+ *
+ * @since 1.0.0
  */
 declare interface Span {
     /**
@@ -7078,11 +7093,21 @@ declare interface Span {
      */
     addLinks(links: Link[]): this;
     /**
-     * Sets a status to the span. If used, this will override the default Span
-     * status. Default is {@link SpanStatusCode.UNSET}. SetStatus overrides the value
-     * of previous calls to SetStatus on the Span.
+     * Sets the status of the span.
+     *
+     * By default, a span has status {@link SpanStatusCode.UNSET}.
+     * Calling this method overrides that default.
+     *
+     * The status codes have a total order: `OK > ERROR > UNSET`.
+     *
+     * - Once {@link SpanStatusCode.OK} is set, any further attempts to change
+     *   the status are ignored.
+     * - Any attempt to set {@link SpanStatusCode.UNSET} is always ignored.
+     *
+     * The `message` field is only used when {@link SpanStatusCode.ERROR} is set.
+     * For all other status codes, `message` is ignored.
      *
-     * @param status the SpanStatus to set.
+     * @param status The {@link SpanStatus} to set.
      */
     setStatus(status: SpanStatus): this;
     /**
@@ -7127,17 +7152,21 @@ declare interface Span {
 
 /**
  * @deprecated please use {@link Attributes}
+ * @since 1.0.0
  */
 declare type SpanAttributes = Attributes;
 
 /**
  * @deprecated please use {@link AttributeValue}
+ * @since 1.0.0
  */
 declare type SpanAttributeValue = AttributeValue;
 
 /**
  * A SpanContext represents the portion of a {@link Span} which must be
  * serialized and propagated along side of a {@link Baggage}.
+ *
+ * @since 1.0.0
  */
 declare interface SpanContext {
     /**
@@ -7187,6 +7216,9 @@ declare interface SpanContext {
     traceState?: TraceState;
 }
 
+/**
+ * @since 1.0.0
+ */
 declare enum SpanKind {
     /** Default value. Indicates that the span is used internally. */
     INTERNAL = 0,
@@ -7216,6 +7248,8 @@ declare enum SpanKind {
 
 /**
  * Options needed for span creation
+ *
+ * @since 1.0.0
  */
 declare interface SpanOptions {
     /**
@@ -7224,7 +7258,7 @@ declare interface SpanOptions {
      */
     kind?: SpanKind;
     /** A span's attributes */
-    attributes?: SpanAttributes;
+    attributes?: Attributes;
     /** {@link Link}s span to other spans */
     links?: Link[];
     /** A manually specified start time for the created `Span` object. */
@@ -7233,6 +7267,9 @@ declare interface SpanOptions {
     root?: boolean;
 }
 
+/**
+ * @since 1.0.0
+ */
 declare interface SpanStatus {
     /** The status code of this message. */
     code: SpanStatusCode;
@@ -7242,6 +7279,8 @@ declare interface SpanStatus {
 
 /**
  * An enumeration of status codes.
+ *
+ * @since 1.0.0
  */
 declare enum SpanStatusCode {
     /**
@@ -8798,6 +8837,8 @@ export declare type TextUIPart = {
  * Defines TimeInput.
  *
  * hrtime, epoch milliseconds, performance.now() or Date
+ *
+ * @since 1.0.0
  */
 declare type TimeInput = HrTime | number | Date;
 
@@ -9142,6 +9183,8 @@ export declare class TooManyEmbeddingValuesForCallError extends AISDKError {
 
 /**
  * Tracer provides an interface for creating {@link Span}s.
+ *
+ * @since 1.0.0
  */
 declare interface Tracer {
     /**
@@ -9208,6 +9251,9 @@ declare interface Tracer {
     startActiveSpan<F extends (span: Span) => unknown>(name: string, options: SpanOptions, context: Context, fn: F): ReturnType<F>;
 }
 
+/**
+ * @since 1.0.0
+ */
 declare interface TraceState {
     /**
      * Create a new TraceState which inherits from this TraceState and has the

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.13.5-alpha.9"
+  version: "1.14.0-alpha.10"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.13.5-alpha.9",
+  "version": "1.14.0-alpha.10",
   "package": "@mastra/client-js",
   "exports": {
     "RequestContext": {

package/dist/docs/references/docs-editor-overview.md

@@ -214,6 +214,75 @@ curl http://localhost:4111/agents/support-agent?versionId=abc-123
 
 See the [Client SDK agents reference](https://mastra.ai/reference/client-js/agents) for API methods.
 
+### Sub-agent versioning
+
+When a [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) delegates to sub-agents, version overrides determine which stored version of each sub-agent to use instead of the code-defined default. This lets you iterate on sub-agent prompts and tools through the editor without redeploying the supervisor.
+
+Set version overrides at three levels, with later levels taking priority:
+
+1. **Mastra instance config** — global defaults that apply to every `generate()` and `stream()` call.
+2. **Per-invocation options** — overrides passed directly to `generate()` or `stream()`.
+3. **Server request body** — overrides sent in the `versions` field of an API request.
+
+Resolution order: **per-invocation > request body > Mastra instance defaults > code-defined agent**.
+
+#### Mastra instance config
+
+Set global defaults when creating the `Mastra` instance. Every supervisor call inherits these overrides:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+
+export const mastra = new Mastra({
+  agents: { supervisor, researchAgent, writerAgent },
+  editor: new MastraEditor(),
+  versions: {
+    agents: {
+      'research-agent': { status: 'published' },
+      'writer-agent': { versionId: 'abc-123' },
+    },
+  },
+})
+```
+
+#### Per-invocation overrides
+
+Override versions for a single call to `generate()` or `stream()`. These take priority over Mastra instance defaults:
+
+```typescript
+const result = await supervisor.generate('Research and write an article about AI safety', {
+  versions: {
+    agents: {
+      'research-agent': { versionId: 'draft-456' },
+    },
+  },
+})
+```
+
+#### Server request body
+
+When calling agents through the Mastra server, pass version overrides in the request body:
+
+```bash
+curl -X POST http://localhost:4111/agents/supervisor/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [{ "role": "user", "content": "Research AI safety" }],
+    "versions": {
+      "agents": {
+        "research-agent": { "versionId": "draft-456" }
+      }
+    }
+  }'
+```
+
+#### How propagation works
+
+Version overrides propagate automatically through sub-agent delegation via `requestContext`. When a supervisor delegates to a sub-agent, the framework checks if a version override exists for that sub-agent's ID. If one is found, it resolves the stored version from the editor and uses it instead of the code-defined default.
+
+If version resolution fails (for example, when the editor is not configured or the version ID doesn't exist), the framework logs a warning and falls back to the code-defined agent.
+
 ## Next steps
 
 - Set up [prompts](https://mastra.ai/docs/editor/prompts) to build reusable instruction templates.

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

@@ -140,6 +140,18 @@ await run.resume({
 })
 ```
 
+When a [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) step suspends across multiple iterations, pass `forEachIndex` (zero-based; `0` targets the first iteration) to resume one iteration at a time. Iterations you don't target remain suspended.
+
+```typescript
+await run.resume({
+  step: 'approve',
+  resumeData: { ok: true },
+  forEachIndex: 1, // resumes the second iteration
+})
+```
+
+`forEachIndex` is also supported by `resumeAsync()` and `resumeStream()`.
+
 ### `cancel()`
 
 Cancel a running workflow:

package/dist/index.cjs

@@ -2159,6 +2159,7 @@ var Run = class extends BaseResource {
     resumeData,
     tracingOptions,
     perStep,
+    forEachIndex,
     ...rest
   }) {
     const requestContext = parseClientRequestContext(rest.requestContext);
@@ -2169,7 +2170,8 @@ var Run = class extends BaseResource {
         resumeData,
         requestContext,
         tracingOptions,
-        perStep
+        perStep,
+        forEachIndex
       }
     });
   }
@@ -2260,7 +2262,8 @@ var Run = class extends BaseResource {
         resumeData: params.resumeData,
         requestContext,
         tracingOptions: params.tracingOptions,
-        perStep: params.perStep
+        perStep: params.perStep,
+        forEachIndex: params.forEachIndex
       }
     }).then(deserializeWorkflowError);
   }
@@ -2282,7 +2285,8 @@ var Run = class extends BaseResource {
           resumeData: params.resumeData,
           requestContext,
           tracingOptions: params.tracingOptions,
-          perStep: params.perStep
+          perStep: params.perStep,
+          forEachIndex: params.forEachIndex
         },
         stream: true
       }