mastra 1.23.0 → 1.23.1-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # mastra
 
+## 1.23.1-alpha.0
+
+### Patch Changes
+
+- **Added file-based schedules for agents** ([#20711](https://github.com/mastra-ai/mastra/pull/20711))
+
+  File-based agents can now declare recurring tasks in a `schedules/` directory next to their tools and skills. Mastra registers them into schedule storage at startup, so a scheduled agent no longer needs any runtime registration code.
+
+  Each file is one schedule: a cron expression plus exactly one execution mode. Prompt mode runs the owning agent with a fixed message.
+
+  ```typescript
+  // src/mastra/agents/support/schedules/heartbeat.ts
+  import { defineSchedule } from '@mastra/core/agent';
+
+  export default defineSchedule({
+    cron: '*/5 * * * *',
+    prompt: 'Check system health and report any failures.',
+  });
+  ```
+
+  Handler mode computes the fire when it triggers, and returning `null` skips it.
+
+  ```typescript
+  // src/mastra/agents/support/schedules/billing/sweep.ts
+  import { defineSchedule } from '@mastra/core/agent';
+
+  export default defineSchedule({
+    cron: '0 3 * * *',
+    handler: async () => {
+      const overdue = await findOverdueInvoices();
+      if (overdue.length === 0) return null;
+      return { prompt: `Chase ${overdue.length} overdue invoices.` };
+    },
+  });
+  ```
+
+  A schedule's id is its path under `schedules/` with the extension stripped, so `billing/sweep.ts` becomes `billing/sweep` and stays stable across builds. Editing a cron patches the stored schedule and recomputes its next fire time, deleting the file deletes the schedule, and pausing a schedule through the API survives a redeploy. Schedules created with `mastra.schedules.create(...)` are in a separate namespace and are never touched by this sync.
+
+  A schedule can also be a Markdown file, using cron frontmatter with the document body as the prompt.
+
+  ```text
+  // src/mastra/agents/support/schedules/cleanup.md
+  ---
+  cron: "0 3 * * *"
+  ---
+
+  Review tickets untouched for 30 days and close the ones that are resolved.
+  ```
+
+  Declaring a schedule is enough to start the scheduler. Schedules are supported on root agents only; a `schedules/` directory under `subagents/` fails the build, because the scheduler cannot resolve a subagent as a run target.
+
+  `defineSchedule` is exported from both `@mastra/core/agent` and `@mastra/core/schedules`, so authoring a file-based agent needs a single import path.
+
+  Build and dev support the same convention: schedules are discovered at build time, Markdown schedules fail the build with a message naming the file when the cron is missing, the body is empty, the frontmatter has an unknown field, or the YAML is unparseable. That last case has its own message because a leading `*` is a YAML alias, so `cron: */5 * * * *` needs quoting. The dev server rebuilds when a Markdown schedule changes.
+
+- Updated dependencies [[`45a9147`](https://github.com/mastra-ai/mastra/commit/45a914741f578754d79d8b7de7b4e4f304d8e14a), [`990611b`](https://github.com/mastra-ai/mastra/commit/990611ba76eb876d86c9c594371ae5f02f94b432), [`ed5d606`](https://github.com/mastra-ai/mastra/commit/ed5d606739c5e3fbdfa9f272df7809aa5ab43b1d)]:
+  - @mastra/core@1.58.0-alpha.0
+  - @mastra/deployer@1.58.0-alpha.0
+
 ## 1.23.0
 
 ### Patch Changes

package/dist/commands/dev/DevBundler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DevBundler.d.ts","sourceRoot":"","sources":["../../../src/commands/dev/DevBundler.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,aAAa,EAKd,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAqB,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAC5F,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAOnD,UAAU,qBAAqB;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,0BAA0B,CAAC;CAC3C;AASD,qBAAa,UAAW,SAAQ,OAAO;IACrC,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,OAAO,CAAU;gBAEb,aAAa,CAAC,EAAE,MAAM,EAAE,OAAO,UAAQ;IAQnD,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAuB1B,OAAO,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+B/C,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,EACjC,qBAAqB,CAAC,EAAE,qBAAqB,GAC5C,UAAU,CAAC,OAAO,aAAa,CAAC;IAsI7B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAG9B"}
+{"version":3,"file":"DevBundler.d.ts","sourceRoot":"","sources":["../../../src/commands/dev/DevBundler.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,aAAa,EAKd,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAqB,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAC5F,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAOnD,UAAU,qBAAqB;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,0BAA0B,CAAC;CAC3C;AAeD,qBAAa,UAAW,SAAQ,OAAO;IACrC,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,OAAO,CAAU;gBAEb,aAAa,CAAC,EAAE,MAAM,EAAE,OAAO,UAAQ;IAQnD,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAuB1B,OAAO,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+B/C,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,EACjC,qBAAqB,CAAC,EAAE,qBAAqB,GAC5C,UAAU,CAAC,OAAO,aAAa,CAAC;IAsI7B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAG9B"}

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra
 description: Documentation for mastra. Use when working with mastra APIs, configuration, or implementation.
 metadata:
   package: "mastra"
-  version: "1.23.0"
+  version: "1.23.1-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.23.0",
+  "version": "1.23.1-alpha.0",
   "package": "mastra",
   "exports": {},
   "modules": {}

package/dist/index.js

@@ -41,7 +41,7 @@ import handler from "serve-handler";
 //#region package.json
 var package_default = {
 	name: "mastra",
-	version: "1.23.0",
+	version: "1.23.1-alpha.0",
 	license: "Apache-2.0",
 	description: "cli for mastra",
 	type: "module",
@@ -3296,8 +3296,17 @@ function releaseDevLock(dotMastraPath) {
 }
 //#endregion
 //#region src/commands/dev/DevBundler.ts
-function collectInstructionPaths(agents) {
-	return agents.flatMap((agent) => [...agent.instructionsPath ? [agent.instructionsPath] : [], ...collectInstructionPaths(agent.subagents)]);
+/**
+* Files whose contents are inlined into the generated fs-agents module rather
+* than imported by it. Rollup can't see them through the module graph, so the
+* dev watcher has to register them explicitly or edits won't trigger a rebuild.
+*/
+function collectInlinedPaths(agents) {
+	return agents.flatMap((agent) => [
+		...agent.instructionsPath ? [agent.instructionsPath] : [],
+		...(agent.schedules ?? []).flatMap((schedule) => schedule.kind === "markdown" ? [schedule.path] : []),
+		...collectInlinedPaths(agent.subagents)
+	]);
 }
 var DevBundler = class extends Bundler {
 	customEnvFile;
@@ -3376,7 +3385,7 @@ var DevBundler = class extends Bundler {
 					async buildStart() {
 						if (!fsRoutingWatchOptions?.preparedEntry.moduleSource) return;
 						const agents = await discoverFsAgents(fsRoutingWatchOptions.mastraDir);
-						for (const instructionsPath of collectInstructionPaths(agents)) this.addWatchFile(resolve(instructionsPath));
+						for (const inlinedPath of collectInlinedPaths(agents)) this.addWatchFile(resolve(inlinedPath));
 						const nextEntry = await prepareFsAgentsEntry(fsRoutingWatchOptions.mastraDir, fsRoutingWatchOptions.userEntryFile, fsRoutingWatchOptions.outputDirectory);
 						if (nextEntry.moduleSource !== lastFsAgentsModuleSource) {
 							await writeFsAgentsEntry(nextEntry);