@mastra/client-js 1.31.0-alpha.4 → 1.31.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @mastra/client-js
 
+## 1.31.0
+
+### Minor Changes
+
+- **Added unified schedule methods and deprecated heartbeat methods.** The client now manages agent schedules (previously heartbeats) and workflow schedules through one set of methods backed by `/api/schedules`. ([#18874](https://github.com/mastra-ai/mastra/pull/18874))
+
+  Added `createSchedule()`, `updateSchedule()`, `deleteSchedule()`, and `runSchedule()`, alongside the existing `listSchedules()`, `getSchedule()`, `pauseSchedule()`, `resumeSchedule()`, and `listScheduleTriggers()`. `ScheduleResponse.target` is now a discriminated union of agent and workflow targets.
+
+  ```ts
+  // Schedule an agent (was createHeartbeat)
+  const schedule = await client.createSchedule({
+    agentId: 'chef',
+    cron: '0 9 * * *',
+    prompt: 'Suggest a dish of the day',
+  });
+
+  // Schedule a workflow with the same method
+  await client.createSchedule({
+    workflowId: 'daily-report',
+    cron: '0 6 * * *',
+  });
+  ```
+
+  Deprecated `listHeartbeats()`, `getHeartbeat()`, `createHeartbeat()`, `updateHeartbeat()`, `deleteHeartbeat()`, `pauseHeartbeat()`, `resumeHeartbeat()`, and `runHeartbeat()`. They now delegate to the schedule methods and will be removed in a future release.
+
+### Patch Changes
+
+- Added workspace-level provider registry to MastraEditor. You can now register WorkspaceProvider factories that build complete Workspace instances as a single unit, instead of composing from separate filesystem and sandbox providers. Stored agents can reference a workspace provider via `{ type: 'provider', provider: 'my-cloud', config: { ... } }` and the editor will call the registered factory during agent hydration. ([#18781](https://github.com/mastra-ai/mastra/pull/18781))
+
+  ```ts
+  import { MastraEditor } from '@mastra/editor';
+  import { Workspace } from '@mastra/core/workspace';
+
+  const editor = new MastraEditor({
+    workspaces: {
+      'my-cloud': {
+        id: 'my-cloud',
+        name: 'My Cloud Workspace',
+        createWorkspace: config =>
+          new Workspace({
+            id: 'cloud-ws',
+            name: 'Cloud WS',
+            filesystem: new MyCloudFilesystem(config),
+            sandbox: new MyCloudSandbox(config),
+          }),
+      },
+    },
+  });
+
+  // Stored agent workspace reference using the provider:
+  // { type: 'provider', provider: 'my-cloud', config: { region: 'us-east-1' } }
+  ```
+
+- Updated dependencies [[`b291760`](https://github.com/mastra-ai/mastra/commit/b291760df9d6c7e4fc72606c8f0a4af2cf6e946c), [`3ffb8b7`](https://github.com/mastra-ai/mastra/commit/3ffb8b720e90f5e6977129ec1f6707d43c2bebe0), [`6ef59fe`](https://github.com/mastra-ai/mastra/commit/6ef59fef1da52ed8da5fbb2a892c71cf4fb6c739), [`4039488`](https://github.com/mastra-ai/mastra/commit/403948898af7293198d9e8b3e7fb47f623c78b94), [`29b7ea6`](https://github.com/mastra-ai/mastra/commit/29b7ea64e72b5523d5bdcbd34ee03d2b854d54e1), [`b2c9d70`](https://github.com/mastra-ai/mastra/commit/b2c9d70757207fb01a9069549e69b6f0d73a6636), [`a51c63d`](https://github.com/mastra-ai/mastra/commit/a51c63d8ee639e4daeba2a0be093efa6a1b5e52f), [`252f63d`](https://github.com/mastra-ai/mastra/commit/252f63d8fec723955adb2202be2f01a75ad0e69c), [`5ea76a7`](https://github.com/mastra-ai/mastra/commit/5ea76a723d966c72da9aa3ab30ae20276e049765), [`6445560`](https://github.com/mastra-ai/mastra/commit/6445560327045d20b239585fc63fed72e9ce36ec), [`e2b9f33`](https://github.com/mastra-ai/mastra/commit/e2b9f33456fd638eca555f9466c6519d8d049666), [`10959d5`](https://github.com/mastra-ai/mastra/commit/10959d509d824f682d40ff96e05ee044aec3b0e5), [`c547a77`](https://github.com/mastra-ai/mastra/commit/c547a7729bdf64dfc2df29c965046c0712a18f10), [`a0085fa`](https://github.com/mastra-ai/mastra/commit/a0085fa0934e52c37c8c8b3d75a6bb5cd199af36), [`a2ba369`](https://github.com/mastra-ai/mastra/commit/a2ba369e796dfab610f41c6875965b488272fa55), [`ffc3c17`](https://github.com/mastra-ai/mastra/commit/ffc3c17274ea17c11aa6f73d3140649cd7fc8abc), [`81542c1`](https://github.com/mastra-ai/mastra/commit/81542c1835c35bc32f2ce4fa9136ee11993cd299), [`3908e53`](https://github.com/mastra-ai/mastra/commit/3908e53ce04bbea04f5e0c097d7aa298c35fabee), [`cb24ce7`](https://github.com/mastra-ai/mastra/commit/cb24ce76bd16ca88eb6a963f6277f8780e703029), [`02705fd`](https://github.com/mastra-ai/mastra/commit/02705fd2f5a9062210d64ea061adeeb10dc9452e), [`ae51e81`](https://github.com/mastra-ai/mastra/commit/ae51e818825582d42500338dfc1929a082eff0ba), [`6f304ef`](https://github.com/mastra-ai/mastra/commit/6f304ef319e99725e884bdb8d3193c001b6e5964), [`5f9858f`](https://github.com/mastra-ai/mastra/commit/5f9858f791f1137ca7d52d23559fb4568f7a9026)]:
+  - @mastra/core@1.50.0
+
+## 1.31.0-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`a0085fa`](https://github.com/mastra-ai/mastra/commit/a0085fa0934e52c37c8c8b3d75a6bb5cd199af36)]:
+  - @mastra/core@1.50.0-alpha.5
+
 ## 1.31.0-alpha.4
 
 ### 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.31.0-alpha.4"
+  version: "1.31.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.31.0-alpha.4",
+  "version": "1.31.0",
   "package": "@mastra/client-js",
   "exports": {
     "RequestContext": {

package/dist/docs/references/docs-long-running-agents-schedules.md

@@ -6,13 +6,11 @@
 
 > **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
 
-A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/long-running-agents/signals) into a thread or as a threadless `agent.generate()` run. Use schedules for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
+A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/long-running-agents/signals) into a thread or as a threadless [`agent.generate()`](https://mastra.ai/reference/agents/generate) run. Use schedules for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
 
-Schedules are persisted, so they survive restarts and redeploys. Manage them at runtime through `mastra.schedules`, the canonical create, read, update, and delete (CRUD) surface. The same surface also manages [workflow schedules](https://mastra.ai/docs/workflows/scheduled-workflows) — pass `workflowId` instead of `agentId` to schedule a workflow.
+Schedules are persisted, so they survive restarts and redeploys. Manage them at runtime through [`mastra.schedules`](https://mastra.ai/reference/schedules/overview), the canonical create, read, update, and delete (CRUD) surface. The same surface also manages [workflow schedules](https://mastra.ai/docs/workflows/scheduled-workflows) (pass `workflowId` instead of `agentId` to schedule a workflow).
 
-## Prerequisites
-
-Schedules require a [storage](https://mastra.ai/docs/memory/storage) adapter that implements the schedules domain, for example `@mastra/libsql`. Without one, `mastra.schedules.create()` throws.
+> **Note:** Schedules require a [storage](https://mastra.ai/docs/memory/storage) adapter that implements the schedules domain. See the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview) for supported adapters and API behavior.
 
 ## Quickstart
 
@@ -48,7 +46,7 @@ Mastra starts the scheduler the first time a schedule is created, then fires the
 
 Schedules fire on a cron expression. The `cron` field accepts a standard 5-, 6-, or 7-part cron expression, and it's validated when you create or update the schedule.
 
-Croner nicknames also work, for example `@hourly`, `@daily`, `@weekly`, `@monthly`, and `@midnight`. For day-and-time combinations, write the cron field directly:
+`croner` nicknames also work, for example `@hourly`, `@daily`, `@weekly`, `@monthly`, and `@midnight`. For day-and-time combinations, write the cron field directly:
 
 ```typescript
 // Every weekday at 9am
@@ -85,15 +83,9 @@ await mastra.schedules.create({
 })
 ```
 
-Threaded schedules accept extra fields that control how the signal behaves. They mirror the options [`agent.sendSignal`](https://mastra.ai/docs/long-running-agents/signals) accepts and stay JSON-serializable so they persist with the schedule.
-
-- `signalType`: the [signal type](https://mastra.ai/docs/long-running-agents/signals) to send, for example `notification` or `system-reminder`. Defaults to `notification`.
-- `tagName`: the XML tag the signal renders as. Defaults to `schedule`, so a fire surfaces to the agent as `<schedule>…</schedule>`.
-- `attributes`: values rendered onto the signal's XML tag.
-- `ifActive`: behavior when the thread is already streaming, as `{ behavior, attributes }`. `behavior` is one of `deliver`, `persist`, or `discard`.
-- `ifIdle`: behavior when the thread is idle, as `{ behavior, attributes, streamOptions }`. `behavior` is one of `wake`, `persist`, or `discard`. `streamOptions.requestContext` is applied to the woken run.
+Threaded schedules accept extra fields that control how the signal behaves, including the signal type, XML tag, tag attributes, and active-or-idle delivery behavior. They mirror the options [`agent.sendSignal()`](https://mastra.ai/docs/long-running-agents/signals) accepts and stay JSON-serializable so they persist with the schedule.
 
-These fields require a `threadId`. Passing them on a threadless schedule throws.
+These fields require a `threadId`. For the full threaded input shape, see the [agent schedule input reference](https://mastra.ai/reference/schedules/overview).
 
 ```typescript
 await mastra.schedules.create({
@@ -116,39 +108,21 @@ await mastra.schedules.create({
 
 ## Managing schedules
 
-Use `mastra.schedules` for all schedule operations. To scope to a single agent, pass `agentId` to `create` or `list`.
+Use `mastra.schedules` for all schedule operations. The service can create, read, update, pause, resume, manually run, and delete schedules.
 
 ```typescript
-// Create
 const schedule = await mastra.schedules.create({
   agentId: 'pinger',
   cron: '0 * * * *',
   prompt: 'Status check.',
 })
 
-// Read
-await mastra.schedules.get(schedule.id)
-await mastra.schedules.list({ agentId: 'pinger' })
-
-// Update — changing cron or timezone recomputes the next fire time
-await mastra.schedules.update(schedule.id, { cron: '*/30 * * * *' })
-
-// Pause and resume
 await mastra.schedules.pause(schedule.id)
 await mastra.schedules.resume(schedule.id)
-
-// Fire once now, off-schedule
-await mastra.schedules.run(schedule.id)
-
-// Delete
-await mastra.schedules.delete(schedule.id)
+await mastra.schedules.run(schedule.id) // Fire once now, off-schedule
 ```
 
-A few rules worth knowing:
-
-- `pause` and `resume` are durable and idempotent. A paused schedule survives restarts, and `resume` recomputes the next fire time from now rather than firing backlogged runs.
-- `run` fires the schedule once immediately without affecting its cadence.
-- `list` filters by `agentId`, `workflowId`, `threadId`, `resourceId`, `name`, and `status`. Without a filter it returns every schedule, agent and workflow alike.
+`pause` and `resume` are durable. `run` fires the schedule once immediately without affecting its cadence. For the complete method list, filters, and patch fields, see the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview).
 
 ### Workflow schedules
 
@@ -166,7 +140,7 @@ Workflow schedules created this way are independent of the declarative `schedule
 
 ### Custom IDs
 
-By default `create` generates a random `agent_<uuid>` id. Pass `id` to choose a stable one, for example when you want a predictable handle to look up, update, or delete later:
+Pass `id` when you need a predictable handle to look up, update, or delete later.
 
 ```typescript
 await mastra.schedules.create({
@@ -175,14 +149,13 @@ await mastra.schedules.create({
   cron: '0 9 * * *',
   prompt: 'Summarize anything new since yesterday.',
 })
-// stored as `agent_nightly-summary`
 ```
 
-The id is normalized to `agent_<slug>`: the `agent_` prefix is added if missing and the rest is slugified. Workflow schedules normalize to `schedule_<slug>` instead. Creating a schedule with an id that already exists throws, so use `update` to change an existing one.
+See the [`create(input)` reference](https://mastra.ai/reference/schedules/overview) for ID normalization rules and duplicate ID behavior.
 
 ### From the client
 
-The same operations are available from `@mastra/client-js` over the `/api/schedules` routes (`client.createSchedule`, `client.listSchedules`, `client.runSchedule`, and so on), so you can manage schedules from a separate process or a UI.
+The same operations are available from `@mastra/client-js` over the `/api/schedules` routes, so you can manage schedules from a separate process or a UI. See the [client-js agent schedules reference](https://mastra.ai/reference/client-js/agents) for the client method list.
 
 ## Lifecycle hooks
 
@@ -223,5 +196,6 @@ Hook exceptions are caught and logged. They never re-route the worker or trigger
 
 ## Related
 
+- [`mastra.schedules`](https://mastra.ai/reference/schedules/overview): API reference for creating and managing schedules.
 - [Signals](https://mastra.ai/docs/long-running-agents/signals): the delivery mechanism behind threaded schedules.
 - [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows): declare a cron schedule on a workflow definition.

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

@@ -494,6 +494,94 @@ if (output.finishReason === 'suspended') {
 }
 ```
 
+## Agent schedules
+
+Use the client SDK schedule methods to manage persisted agent schedules over the `/api/schedules` routes. For concepts and server-side examples, see [Schedules](https://mastra.ai/docs/long-running-agents/schedules) and the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview).
+
+### `createSchedule()`
+
+Create an agent schedule by passing `agentId`.
+
+```typescript
+const schedule = await mastraClient.createSchedule({
+  agentId: 'pinger',
+  cron: '0 * * * *',
+  prompt: 'Give me a status update.',
+})
+```
+
+### `listSchedules()`
+
+List agent schedules. Filter by fields such as `agentId`, `threadId`, `resourceId`, `name`, or `status`.
+
+```typescript
+const schedules = await mastraClient.listSchedules({
+  agentId: 'pinger',
+  status: 'active',
+})
+```
+
+### `getSchedule()`
+
+Fetch a single agent schedule by ID.
+
+```typescript
+const schedule = await mastraClient.getSchedule('agent_pinger')
+```
+
+### `updateSchedule()`
+
+Update an agent schedule. Agent schedules can update fields such as `cron`, `timezone`, `prompt`, `name`, signal delivery options, metadata, and `status`.
+
+```typescript
+const updated = await mastraClient.updateSchedule('agent_pinger', {
+  cron: '*/30 * * * *',
+  prompt: 'Give me a status update every 30 minutes.',
+})
+```
+
+### `deleteSchedule()`
+
+Delete an agent schedule.
+
+```typescript
+await mastraClient.deleteSchedule('agent_pinger')
+```
+
+### `runSchedule()`
+
+Fire an agent schedule once immediately without changing its cron cadence.
+
+```typescript
+const run = await mastraClient.runSchedule('agent_pinger')
+```
+
+### `pauseSchedule()`
+
+Pause an agent schedule so the scheduler stops firing it. Returns the updated schedule.
+
+```typescript
+await mastraClient.pauseSchedule('agent_pinger')
+```
+
+### `resumeSchedule()`
+
+Resume a paused agent schedule. The next fire time is recomputed from now, so a long-paused schedule doesn't fire a backlog. Returns the updated schedule.
+
+```typescript
+await mastraClient.resumeSchedule('agent_pinger')
+```
+
+### `listScheduleTriggers()`
+
+List the trigger history for an agent schedule, including the joined run summary for each fire.
+
+```typescript
+const { triggers } = await mastraClient.listScheduleTriggers('agent_pinger', {
+  limit: 50,
+})
+```
+
 ## Client tools
 
 Client-side tools allow you to execute custom functions on the client side when the agent requests them.

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

@@ -214,11 +214,23 @@ A workflow run result yields the following:
 
 ## Schedules
 
-Schedules are declared in code via the `schedule` field on `createWorkflow`. The client SDK exposes read and operational methods for managing them at runtime. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows).
+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).
+
+### `createSchedule()`
+
+Create a workflow schedule by passing `workflowId`.
+
+```typescript
+const schedule = await mastraClient.createSchedule({
+  workflowId: 'daily-report',
+  cron: '0 9 * * *',
+  inputData: { reportType: 'summary' },
+})
+```
 
 ### `listSchedules()`
 
-List all schedules, optionally filtered by workflow id or status.
+List workflow schedules, optionally filtered by workflow ID or status.
 
 ```typescript
 const schedules = await mastraClient.listSchedules({
@@ -229,15 +241,42 @@ const schedules = await mastraClient.listSchedules({
 
 ### `getSchedule()`
 
-Fetch a single schedule by id.
+Fetch a single workflow schedule by ID.
 
 ```typescript
 const schedule = await mastraClient.getSchedule('daily-report')
 ```
 
+### `updateSchedule()`
+
+Update a workflow schedule.
+
+```typescript
+const updated = await mastraClient.updateSchedule('daily-report', {
+  cron: '0 10 * * *',
+  inputData: { reportType: 'summary' },
+})
+```
+
+### `deleteSchedule()`
+
+Delete a workflow schedule.
+
+```typescript
+await mastraClient.deleteSchedule('daily-report')
+```
+
+### `runSchedule()`
+
+Fire a workflow schedule once immediately without changing its cron cadence.
+
+```typescript
+const run = await mastraClient.runSchedule('daily-report')
+```
+
 ### `pauseSchedule()`
 
-Pause a schedule so the scheduler stops firing it. Returns the updated schedule. Idempotent.
+Pause a schedule so the scheduler stops firing it. Returns the updated schedule.
 
 ```typescript
 await mastraClient.pauseSchedule('daily-report')
@@ -245,7 +284,7 @@ await mastraClient.pauseSchedule('daily-report')
 
 ### `resumeSchedule()`
 
-Resume a paused schedule. The next fire time is recomputed from now, so a long-paused schedule doesn't fire a backlog. Returns the updated schedule. Idempotent.
+Resume a paused schedule. The next fire time is recomputed from now, so a long-paused schedule doesn't fire a backlog. Returns the updated schedule.
 
 ```typescript
 await mastraClient.resumeSchedule('daily-report')
@@ -253,7 +292,7 @@ await mastraClient.resumeSchedule('daily-report')
 
 ### `listScheduleTriggers()`
 
-List the trigger history for a schedule, including the joined run summary for each fire.
+List the trigger history for a workflow schedule, including the joined run summary for each fire.
 
 ```typescript
 const { triggers } = await mastraClient.listScheduleTriggers('daily-report', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/client-js",
-  "version": "1.31.0-alpha.4",
+  "version": "1.31.0",
   "description": "The official TypeScript library for the Mastra Client API",
   "author": "",
   "type": "module",
@@ -39,7 +39,7 @@
     "canonicalize": "^1.0.8",
     "jose": "^6.2.1",
     "json-schema": "^0.4.0",
-    "@mastra/core": "1.50.0-alpha.4",
+    "@mastra/core": "1.50.0",
     "@mastra/schema-compat": "1.3.3"
   },
   "peerDependencies": {
@@ -56,10 +56,10 @@
     "typescript": "^6.0.3",
     "vitest": "4.1.8",
     "zod": "^4.4.3",
-    "@internal/ai-sdk-v5": "0.0.58",
-    "@internal/lint": "0.0.111",
-    "@internal/ai-sdk-v4": "0.0.58",
-    "@internal/types-builder": "0.0.86"
+    "@internal/ai-sdk-v4": "0.0.59",
+    "@internal/ai-sdk-v5": "0.0.59",
+    "@internal/lint": "0.0.112",
+    "@internal/types-builder": "0.0.87"
   },
   "engines": {
     "node": ">=22.13.0"