@mastra/temporal 0.0.0 → 0.1.0-alpha.0

package/CHANGELOG.md

@@ -1 +1,34 @@
 # @mastra/temporal
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- Added the new `@mastra/temporal` package for running Mastra workflows on Temporal. ([#15789](https://github.com/mastra-ai/mastra/pull/15789))
+
+  **What changed**
+  - Added `init()` to create Temporal-backed Mastra workflows and steps.
+  - Added `MastraPlugin` to bundle workflow code for Temporal workers and load generated activities.
+  - Added `debug: true` support to write transformed workflow modules and emitted bundles to `.mastra/temporal`.
+
+  **Example**
+
+  ```ts
+  import { init } from '@mastra/temporal';
+  import { MastraPlugin } from '@mastra/temporal/worker';
+  import { Client, Connection } from '@temporalio/client';
+  import { Worker } from '@temporalio/worker';
+
+  const connection = await Connection.connect();
+  const client = new Client({ connection });
+  const { createWorkflow, createStep } = init({ client, taskQueue: 'mastra' });
+
+  const step = createStep({ id: 'hello', execute: async () => 'world' });
+  export const helloWorkflow = createWorkflow({ id: 'hello-workflow' }).then(step);
+
+  await Worker.create({
+    connection,
+    taskQueue: 'mastra',
+    plugins: [new MastraPlugin({ src: import.meta.resolve('./mastra/index.ts') })],
+  });
+  ```

package/LICENSE.md

@@ -0,0 +1,30 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,5 +1,107 @@
 # @mastra/temporal
 
-Mastra workflow engine integration with [Temporal](https://temporal.io/) for durable execution.
+Run Mastra workflows on [Temporal](https://temporal.io/) with a workflow authoring API that stays close to standard Mastra workflows.
 
-> **Work in progress** – this package is under active development and not yet ready for production use.
+> **Experimental:** `@mastra/temporal` is under active development and is not ready for production use yet.
+
+## Installation
+
+```bash
+npm install @mastra/temporal @temporalio/client @temporalio/worker @temporalio/envconfig
+```
+
+## Define a Temporal-backed workflow
+
+The following example demonstrates the same pattern used in the `temporal-snapshot` app: create a Temporal client, call `init()`, and define workflows with `createWorkflow()` and `createStep()`.
+
+```ts
+import { z } from 'zod';
+import { init } from '@mastra/temporal';
+import { loadClientConnectConfig } from '@temporalio/envconfig';
+import { Client, Connection } from '@temporalio/client';
+
+const config = loadClientConnectConfig();
+const connection = await Connection.connect(config.connectionOptions);
+const client = new Client({ connection });
+
+const { createWorkflow, createStep } = init({
+  client,
+  taskQueue: 'mastra',
+});
+
+const fetchWeather = createStep({
+  id: 'fetch-weather',
+  inputSchema: z.object({ city: z.string() }),
+  outputSchema: z.object({ forecast: z.string() }),
+  execute: async ({ inputData }) => {
+    return {
+      forecast: `Sunny in ${inputData.city}`,
+    };
+  },
+});
+
+export const weatherWorkflow = createWorkflow({
+  id: 'weather-workflow',
+  inputSchema: z.object({ city: z.string() }),
+  outputSchema: z.object({ forecast: z.string() }),
+}).then(fetchWeather);
+```
+
+## Register the workflow in your Mastra entry file
+
+`MastraPlugin` precompiles your Mastra entry file into dedicated workflow and activity modules before Temporal starts. Point the plugin at the file where your `Mastra` instance registers workflows.
+
+```ts
+import { Mastra } from '@mastra/core/mastra';
+import { weatherWorkflow } from './workflows/weather-workflow';
+
+export const mastra = new Mastra({
+  workflows: { weatherWorkflow },
+});
+```
+
+## Start a Temporal worker
+
+Create a worker, install `MastraPlugin`, and call `await plugin.init()` before `Worker.create()`. Use the Mastra entry file as `src`.
+
+```ts
+import { NativeConnection, Worker } from '@temporalio/worker';
+import { MastraPlugin } from '@mastra/temporal/worker';
+
+const connection = await NativeConnection.connect({
+  address: 'localhost:7233',
+});
+
+const plugin = new MastraPlugin({
+  src: import.meta.resolve('./mastra/index.ts'),
+});
+
+await plugin.init();
+
+const worker = await Worker.create({
+  connection,
+  namespace: 'default',
+  taskQueue: 'mastra',
+  plugins: [plugin],
+});
+
+await worker.run();
+```
+
+## How it works
+
+- `init({ client, taskQueue })`: Returns `createWorkflow()` and `createStep()` helpers for Temporal-backed Mastra workflows.
+- `MastraPlugin({ src })`: Point it at the Mastra entry file that registers workflows.
+- `await plugin.init()`: Precompiles the Mastra app into `node_modules/.mastra/output/index.mjs`, then generates `node_modules/.mastra/workflow.mjs` for workflow bundling and `node_modules/.mastra/activities.mjs` for activity execution before the Temporal worker starts.
+- Generated activities: The plugin extracts `createStep()` handlers into `node_modules/.mastra/activities.mjs` and wires them into the worker automatically.
+- `debug: true`: Writes emitted workflow bundles to `node_modules/.mastra` for inspection.
+
+## Notes
+
+- Workflow ids must be statically defined so the transformer can derive Temporal export names.
+- The plugin expects `src` to point to the Mastra entry file that registers workflows in `new Mastra({ workflows: ... })`.
+- Call `await plugin.init()` before `Worker.create()` so the compiled workflow entry is ready when Temporal configures the worker and bundler.
+
+## License
+
+Apache-2.0

package/dist/chunk-BF6TR7JX.js

@@ -0,0 +1,9 @@
+// src/utils.ts
+function toWorkflowType(id) {
+  const camelCased = id.replace(/[-_]+([a-zA-Z0-9])/g, (_, char) => char.toUpperCase());
+  return camelCased.endsWith("Workflow") ? camelCased : `${camelCased}Workflow`;
+}
+
+export { toWorkflowType };
+//# sourceMappingURL=chunk-BF6TR7JX.js.map
+//# sourceMappingURL=chunk-BF6TR7JX.js.map

package/dist/chunk-BF6TR7JX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils.ts"],"names":[],"mappings":";AAAO,SAAS,eAAe,EAAA,EAAY;AACzC,EAAA,MAAM,UAAA,GAAa,GAAG,OAAA,CAAQ,qBAAA,EAAuB,CAAC,CAAA,EAAG,IAAA,KAAiB,IAAA,CAAK,WAAA,EAAa,CAAA;AAC5F,EAAA,OAAO,WAAW,QAAA,CAAS,UAAU,CAAA,GAAI,UAAA,GAAa,GAAG,UAAU,CAAA,QAAA,CAAA;AACrE","file":"chunk-BF6TR7JX.js","sourcesContent":["export function toWorkflowType(id: string) {\n  const camelCased = id.replace(/[-_]+([a-zA-Z0-9])/g, (_, char: string) => char.toUpperCase());\n  return camelCased.endsWith('Workflow') ? camelCased : `${camelCased}Workflow`;\n}\n"]}

package/dist/chunk-DYBSPLCJ.cjs

@@ -0,0 +1,11 @@
+'use strict';
+
+// src/utils.ts
+function toWorkflowType(id) {
+  const camelCased = id.replace(/[-_]+([a-zA-Z0-9])/g, (_, char) => char.toUpperCase());
+  return camelCased.endsWith("Workflow") ? camelCased : `${camelCased}Workflow`;
+}
+
+exports.toWorkflowType = toWorkflowType;
+//# sourceMappingURL=chunk-DYBSPLCJ.cjs.map
+//# sourceMappingURL=chunk-DYBSPLCJ.cjs.map

package/dist/chunk-DYBSPLCJ.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils.ts"],"names":[],"mappings":";;;AAAO,SAAS,eAAe,EAAA,EAAY;AACzC,EAAA,MAAM,UAAA,GAAa,GAAG,OAAA,CAAQ,qBAAA,EAAuB,CAAC,CAAA,EAAG,IAAA,KAAiB,IAAA,CAAK,WAAA,EAAa,CAAA;AAC5F,EAAA,OAAO,WAAW,QAAA,CAAS,UAAU,CAAA,GAAI,UAAA,GAAa,GAAG,UAAU,CAAA,QAAA,CAAA;AACrE","file":"chunk-DYBSPLCJ.cjs","sourcesContent":["export function toWorkflowType(id: string) {\n  const camelCased = id.replace(/[-_]+([a-zA-Z0-9])/g, (_, char: string) => char.toUpperCase());\n  return camelCased.endsWith('Workflow') ? camelCased : `${camelCased}Workflow`;\n}\n"]}