@mastra/client-js 1.37.1-alpha.1 → 1.38.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @mastra/client-js
 
+## 1.38.0
+
+### Minor Changes
+
+- Added typed client support for transient agent signals. Use `transient: true` with `sendSignal()` to deliver non-state context for the current model call without retaining it. ([#18909](https://github.com/mastra-ai/mastra/pull/18909))
+
+  ```typescript
+  await client.getAgent('myAgent').sendSignal({
+    resourceId: 'user-1',
+    threadId: 'thread-1',
+    signal: {
+      type: 'reactive',
+      contents: 'Stay on the current task.',
+      transient: true,
+    },
+  });
+  ```
+
+- Added `toolResult` as a recognized processor phase across the processor server API and the generated client types. Processors that implement `processToolResult` are now detected and surfaced when listing processors, the phase can be targeted when executing a processor, and it is accepted by the processor provider and stored agent schemas. The `@mastra/client-js` route types now include the new phase. ([#16012](https://github.com/mastra-ai/mastra/pull/16012))
+
+### Patch Changes
+
+- Fixed streamed UTF-8 characters being corrupted when their bytes span network chunks. ([#20224](https://github.com/mastra-ai/mastra/pull/20224))
+
+- Added landmark types for trace signal theme snapshots. Querying the theme-snapshots endpoint with `presentation=landmarks` returns a bounded, time-balanced selection of snapshots instead of every snapshot in range. The response types now cover that mode. ([#20710](https://github.com/mastra-ai/mastra/pull/20710))
+
+  ```ts
+  import type { ThemeSnapshotsResponse } from '@mastra/client-js';
+
+  const response: ThemeSnapshotsResponse = await fetch(
+    '/api/learning/entities/my-agent/theme-snapshots?' +
+      'entityType=agent&signalNames=goal,outcome&presentation=landmarks&limit=24',
+  ).then(res => res.json());
+
+  response.totalSnapshots; // full in-range count, larger than the landmark list
+  for (const snapshot of response.snapshots) {
+    snapshot.cutoffAt; // position ticks proportionally on a time axis
+    snapshot.reason; // 'range_start' | 'range_end' | 'time_sample'
+  }
+  ```
+
+- Updated dependencies [[`8d2399b`](https://github.com/mastra-ai/mastra/commit/8d2399b638f8e0945cf2cda0187dbea8dcf0b784), [`c8002da`](https://github.com/mastra-ai/mastra/commit/c8002da7775c468e2965b6ff5f82045450fa8cb9), [`92be47f`](https://github.com/mastra-ai/mastra/commit/92be47fbd26ffccec0e2131ef7c1d9e70dd5ef4a), [`89200ba`](https://github.com/mastra-ai/mastra/commit/89200bafa05444bb7949b363ce7b743e29867561), [`c950138`](https://github.com/mastra-ai/mastra/commit/c950138e72e4f317a40187e3800588731ab790ce), [`810c7e7`](https://github.com/mastra-ai/mastra/commit/810c7e74929989d8b8b5db52cd3af22cd0998af4), [`063c8b2`](https://github.com/mastra-ai/mastra/commit/063c8b2eb14e4e5ca021779bc33e8c3c031c8604), [`f9f9884`](https://github.com/mastra-ai/mastra/commit/f9f98848ee194dc71a787a709ec430b065cdc41b), [`e0904dc`](https://github.com/mastra-ai/mastra/commit/e0904dc538792e54e1806b70172e5900ac49bff4), [`9672fab`](https://github.com/mastra-ai/mastra/commit/9672fabfbcadb961a35c22a2d6722e077f7b24b9), [`f4e964c`](https://github.com/mastra-ai/mastra/commit/f4e964cad57057301d6bed5c55bcdd730175b941), [`1f7bbd7`](https://github.com/mastra-ai/mastra/commit/1f7bbd7785a8d230aad02454ecabeb4a0b2cc96f), [`e47ff36`](https://github.com/mastra-ai/mastra/commit/e47ff36945720f4ee4caa09f6e83514d7d188608), [`64d6781`](https://github.com/mastra-ai/mastra/commit/64d67814bccddd314f7e09643243821e57cb87b6), [`14562d6`](https://github.com/mastra-ai/mastra/commit/14562d6ea724ed4ccb9fb079d016ec7ab1bd92a4), [`fb9a6ac`](https://github.com/mastra-ai/mastra/commit/fb9a6ac11c9560518742ece60b49d6b062845fd3), [`aa2cec8`](https://github.com/mastra-ai/mastra/commit/aa2cec8501f634d51c2f3ebfb3dd3aa7af8d2ca2), [`c848e65`](https://github.com/mastra-ai/mastra/commit/c848e655a64ff10331a8ceafafe7f18e70a0f092), [`2adf8eb`](https://github.com/mastra-ai/mastra/commit/2adf8eb4a70ed2b6cff2dd39281496ea0e025fac), [`0494489`](https://github.com/mastra-ai/mastra/commit/049448906e4c3d2d615bbe865b073a0d890ddb7c), [`8d1aeb8`](https://github.com/mastra-ai/mastra/commit/8d1aeb8acf7c20c4bb8e4d8e4bdc6569c83ac561), [`8264611`](https://github.com/mastra-ai/mastra/commit/8264611510e421b818bc7395dc2ae4d9c2d518b2), [`d8fa243`](https://github.com/mastra-ai/mastra/commit/d8fa2430d21113e330c4e676ac65e1235cf44f81), [`44fc98b`](https://github.com/mastra-ai/mastra/commit/44fc98b9d1242aa87a3ab44bdce9e9f12c44d8c9), [`f933ba3`](https://github.com/mastra-ai/mastra/commit/f933ba32700e1d0bf143311c1a08f88300b840b6), [`83065bf`](https://github.com/mastra-ai/mastra/commit/83065bfee9e47c3c6f09132a9034501f6cfb69cf), [`0f2ef41`](https://github.com/mastra-ai/mastra/commit/0f2ef4118da022e4f30dac4e9856cc3a8c97671c), [`01b162f`](https://github.com/mastra-ai/mastra/commit/01b162fe435295881aa7ea55f1759407ad5175ad)]:
+  - @mastra/core@1.57.0
+  - @mastra/schema-compat@1.3.5
+
+## 1.37.1-alpha.2
+
+### Patch Changes
+
+- Fixed streamed UTF-8 characters being corrupted when their bytes span network chunks. ([#20224](https://github.com/mastra-ai/mastra/pull/20224))
+
+- Updated dependencies [[`810c7e7`](https://github.com/mastra-ai/mastra/commit/810c7e74929989d8b8b5db52cd3af22cd0998af4), [`f9f9884`](https://github.com/mastra-ai/mastra/commit/f9f98848ee194dc71a787a709ec430b065cdc41b), [`e0904dc`](https://github.com/mastra-ai/mastra/commit/e0904dc538792e54e1806b70172e5900ac49bff4), [`64d6781`](https://github.com/mastra-ai/mastra/commit/64d67814bccddd314f7e09643243821e57cb87b6), [`c848e65`](https://github.com/mastra-ai/mastra/commit/c848e655a64ff10331a8ceafafe7f18e70a0f092), [`0494489`](https://github.com/mastra-ai/mastra/commit/049448906e4c3d2d615bbe865b073a0d890ddb7c), [`8d1aeb8`](https://github.com/mastra-ai/mastra/commit/8d1aeb8acf7c20c4bb8e4d8e4bdc6569c83ac561), [`83065bf`](https://github.com/mastra-ai/mastra/commit/83065bfee9e47c3c6f09132a9034501f6cfb69cf), [`01b162f`](https://github.com/mastra-ai/mastra/commit/01b162fe435295881aa7ea55f1759407ad5175ad)]:
+  - @mastra/core@1.57.0-alpha.2
+
 ## 1.37.1-alpha.1
 
 ### 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.37.1-alpha.1"
+  version: "1.38.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.37.1-alpha.1",
+  "version": "1.38.0",
   "package": "@mastra/client-js",
   "exports": {},
   "modules": {}

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

@@ -212,6 +212,98 @@ A workflow run result yields the following:
 
 **payload** (`object`): Contains currentStep (id, status, output, payload) and workflowState (status, steps record)
 
+## Stored workflows
+
+> **Beta:** Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+
+Stored workflows are workflow definitions expressed as JSON. The server persists each definition and registers it as a runnable workflow. See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows) for the definition format.
+
+### `listStoredWorkflows()`
+
+List stored workflow definitions, optionally filtered by `status` (`'active' | 'archived'`) and `authorId`:
+
+```typescript
+const { definitions, total } = await mastraClient.listStoredWorkflows({
+  status: 'active',
+})
+```
+
+### `upsertStoredWorkflow()`
+
+Create or replace a stored workflow definition. The server validates the definition, persists it, and live-registers it for execution:
+
+```typescript
+const stored = await mastraClient.upsertStoredWorkflow({
+  id: 'greeting-workflow',
+  description: 'Returns a greeting for the supplied name',
+  inputSchema: {
+    type: 'object',
+    properties: { name: { type: 'string' } },
+    required: ['name'],
+  },
+  outputSchema: {
+    type: 'object',
+    properties: { message: { type: 'string' } },
+    required: ['message'],
+  },
+  graph: [
+    {
+      type: 'mapping',
+      id: 'create-greeting',
+      mapConfig: JSON.stringify({
+        message: { template: 'Hello, ${initData.name}!' },
+      }),
+    },
+  ],
+})
+```
+
+When the root definition nests helper workflows that don't exist yet, pass them in the same request through `dependencies`. The server validates and registers the bundle as a unit and echoes the helper ids back as `dependencyIds`:
+
+```typescript
+const stored = await mastraClient.upsertStoredWorkflow({
+  id: 'root-workflow',
+  // ...schemas and graph referencing 'helper-workflow'...
+  dependencies: [helperDefinition],
+})
+
+console.log(stored.dependencyIds) // ['helper-workflow']
+```
+
+### `getStoredWorkflow()`
+
+Get a stored workflow instance for definition management. To execute a stored workflow, use `getWorkflow(id).createRun()` like any other workflow:
+
+```typescript
+const storedWorkflow = mastraClient.getStoredWorkflow('greeting-workflow')
+```
+
+### `storedWorkflow.details()`
+
+Retrieve the persisted definition, including schemas, graph, status, and timestamps:
+
+```typescript
+const definition = await storedWorkflow.details()
+```
+
+### `storedWorkflow.delete()`
+
+Delete the stored definition and unregister the live workflow:
+
+```typescript
+await storedWorkflow.delete()
+```
+
+### Executing a stored workflow
+
+Once registered, a stored workflow runs through the ordinary workflow API:
+
+```typescript
+const workflow = mastraClient.getWorkflow('greeting-workflow')
+const run = await workflow.createRun()
+const result = await run.startAsync({ inputData: { name: 'Ada' } })
+```
+
 ## Schedules
 
 Schedules are declared in code via the `schedule` field on `createWorkflow`. The client SDK exposes read and operational methods for managing workflow schedules at runtime. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows).