@mastra/cursor 0.1.0 → 0.2.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @mastra/cursor
 
+## 0.2.0-alpha.0
+
+### Minor Changes
+
+- Added structured output support for Claude and OpenAI SDK agents using their provider-native structured output APIs. Cursor SDK agent calls now fail clearly when structuredOutput is requested because the Cursor TypeScript SDK does not expose a schema-constrained output API. SDK agents now implement provider-native resume through Mastra's existing resumeGenerate/resumeStream methods by accepting provider-specific resumeData with a message payload. Cursor SDK agent options now use the same clear source split as OpenAI: pass either a pre-created agent or SDK options for wrapper-created agents. ([#17580](https://github.com/mastra-ai/mastra/pull/17580))
+
+  Example:
+
+  ```ts
+  await claudeAgent.resumeGenerate({
+    message: 'Continue the task.',
+    sessionId: 'claude-session-id',
+  });
+
+  await openAIAgent.resumeStream({
+    message: 'Continue the task.',
+    previousResponseId: 'resp_123',
+  });
+
+  const result = await openAIAgent.generate('Return the answer as JSON.', {
+    structuredOutput: {
+      schema: z.object({ answer: z.string() }),
+    },
+  });
+  // result.object has shape { answer: string }
+  ```
+
+  Claude and OpenAI SDK agents support `structuredOutput` through their native SDK APIs. `CursorSDKAgent` throws a clear error when `structuredOutput` is requested because the Cursor TypeScript SDK does not expose schema-constrained output.
+
+### Patch Changes
+
+- Updated dependencies [[`575f815`](https://github.com/mastra-ai/mastra/commit/575f815c5c3567b71c0b83cbb7fa98c8253a9d9c), [`306909a`](https://github.com/mastra-ai/mastra/commit/306909a693de77d709b38706e2673c9547d24a28), [`5191af8`](https://github.com/mastra-ai/mastra/commit/5191af80c799eea25357c545fc05d91b3883531d), [`43bd3d4`](https://github.com/mastra-ai/mastra/commit/43bd3d421987463fdf35386a45199c49499ed069), [`e6fa79e`](https://github.com/mastra-ai/mastra/commit/e6fa79ec72a2ddffdd25e85270398951e9d552a4), [`904bcdf`](https://github.com/mastra-ai/mastra/commit/904bcdf7b8004aa7be823f9f70ca63580e47e470), [`7f5ee1d`](https://github.com/mastra-ai/mastra/commit/7f5ee1dca46daee8d2817f2ebe49e6335da81956), [`1e9aab5`](https://github.com/mastra-ai/mastra/commit/1e9aab50ff11e6e88fde4d7cbf512c44a9fe8d61), [`bf8eb6d`](https://github.com/mastra-ai/mastra/commit/bf8eb6d0ec213a403eb9265a594ad283c44ab3dc), [`493a328`](https://github.com/mastra-ai/mastra/commit/493a328f4346a1deeb9f1e2e44c8f2a3a4d7591b), [`029a414`](https://github.com/mastra-ai/mastra/commit/029a4141719793bd3e898a39eb5a0466a55f5f3a), [`b147b29`](https://github.com/mastra-ai/mastra/commit/b147b2907f0cd1aa812efe6d6e3f58d22e66fc88), [`d371ac1`](https://github.com/mastra-ai/mastra/commit/d371ac1d9820afaaf7cfdbc380a475946a994d8f), [`cf182b7`](https://github.com/mastra-ai/mastra/commit/cf182b7fb495767946d9840ef29f19cfa906f31f), [`a049c2a`](https://github.com/mastra-ai/mastra/commit/a049c2a9dfb41d0ee2e7a28874a88cd64fd5669f), [`b147b29`](https://github.com/mastra-ai/mastra/commit/b147b2907f0cd1aa812efe6d6e3f58d22e66fc88), [`2a96528`](https://github.com/mastra-ai/mastra/commit/2a9652848dfa3c5a2426f952e9d93554c26fd90f), [`2656d9c`](https://github.com/mastra-ai/mastra/commit/2656d9c2976d4f3354253bfbbbf9b88a1b2bbf34), [`63e3fe1`](https://github.com/mastra-ai/mastra/commit/63e3fe13cc1ea96f91d7c68aea92f400faf9e4da), [`1d4ce8d`](https://github.com/mastra-ai/mastra/commit/1d4ce8daaa54511f325c1b609d31b8e54009d677), [`8c68372`](https://github.com/mastra-ai/mastra/commit/8c68372e85fe0b066ec12c58bd29ffb93e54c552)]:
+  - @mastra/core@1.42.0-alpha.4
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-cursor
 description: Documentation for @mastra/cursor. Use when working with @mastra/cursor APIs, configuration, or implementation.
 metadata:
   package: "@mastra/cursor"
-  version: "0.1.0"
+  version: "0.2.0-alpha.0"
 ---
 
 ## When to use
@@ -16,7 +16,7 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Docs
 
-- [SDK agents](references/docs-agents-sdk-agents.md) - Use Claude Agent SDK and Cursor Agent SDK agents from Mastra.
+- [SDK agents](references/docs-agents-sdk-agents.md) - Use Claude Agent SDK, Cursor Agent SDK, and OpenAI Agents SDK agents from Mastra.
 
 
 Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0",
+  "version": "0.2.0-alpha.0",
   "package": "@mastra/cursor",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-agents-sdk-agents.md

@@ -13,6 +13,7 @@ SDK agents let you use other agent SDK frameworks inside Mastra. Use them to reg
 
 - [Claude Agent SDK](#claude-agent-sdk): Use `@mastra/claude` to register a Claude SDK agent and call it with Mastra `generate()` and `stream()`.
 - [Cursor Agent SDK](#cursor-agent-sdk): Use `@mastra/cursor` to register a Cursor SDK agent and call it with Mastra `generate()` and `stream()`.
+- [OpenAI Agents SDK](#openai-agents-sdk): Use `@mastra/openai` to register an OpenAI SDK agent and call it with Mastra `generate()` and `stream()`.
 
 ## Claude Agent SDK
 
@@ -154,7 +155,7 @@ export const cursorSDKAgent = new CursorSDKAgent({
   sdkOptions: {
     apiKey: process.env.CURSOR_API_KEY,
     model: {
-      id: 'gpt-5.5',
+      id: 'gpt-5',
     },
     local: {
       cwd: process.cwd(),
@@ -176,7 +177,7 @@ import { CursorSDKAgent } from '@mastra/cursor'
 const cursorAgent = CursorAgent.create({
   apiKey: process.env.CURSOR_API_KEY,
   model: {
-    id: 'gpt-5.5',
+    id: 'gpt-5',
   },
   local: {
     cwd: process.cwd(),
@@ -206,7 +207,7 @@ export const cursorSDKAgent = new CursorSDKAgent({
   sdkOptions: {
     apiKey: process.env.CURSOR_API_KEY,
     model: {
-      id: 'gpt-5.5',
+      id: 'gpt-5',
     },
     local: {
       cwd: process.cwd(),
@@ -216,6 +217,117 @@ export const cursorSDKAgent = new CursorSDKAgent({
 })
 ```
 
+## OpenAI Agents SDK
+
+Use `@mastra/openai` to register an OpenAI Agents SDK agent in Mastra while keeping OpenAI-specific agent settings in OpenAI SDK options.
+
+### Install OpenAI packages
+
+Install the Mastra package and the OpenAI Agents SDK peer dependency:
+
+**npm**:
+
+```bash
+npm install @mastra/openai @openai/agents zod
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/openai @openai/agents zod
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/openai @openai/agents zod
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/openai @openai/agents zod
+```
+
+Set the OpenAI SDK credential:
+
+```bash
+export OPENAI_API_KEY="..."
+```
+
+### Create an OpenAI SDK agent
+
+Configure OpenAI Agents SDK through `sdkOptions`. `OpenAISDKAgent` creates the OpenAI SDK agent on first use.
+
+```typescript
+import { OpenAISDKAgent } from '@mastra/openai'
+
+export const openaiSDKAgent = new OpenAISDKAgent({
+  id: 'openai-sdk-agent',
+  name: 'OpenAI SDK Agent',
+  description: 'Use OpenAI Agents SDK through Mastra.',
+  sdkOptions: {
+    name: 'Repository assistant',
+    instructions: 'Answer clearly and cite the relevant files.',
+    model: 'gpt-5',
+  },
+})
+```
+
+### Use an existing OpenAI SDK agent
+
+If your app already creates an OpenAI SDK agent, pass that agent to `OpenAISDKAgent` instead:
+
+```typescript
+import { Agent as OpenAIAgent } from '@openai/agents'
+import { OpenAISDKAgent } from '@mastra/openai'
+
+const sdkAgent = new OpenAIAgent({
+  name: 'Repository assistant',
+  instructions: 'Answer clearly and cite the relevant files.',
+  model: 'gpt-5',
+})
+
+export const openaiSDKAgent = new OpenAISDKAgent({
+  id: 'openai-sdk-agent',
+  name: 'OpenAI SDK Agent',
+  description: 'Use OpenAI Agents SDK through Mastra.',
+  agent: sdkAgent,
+})
+```
+
+### Add OpenAI SDK tools
+
+OpenAI Agents SDK tools are configured with OpenAI SDK options. Create tools with the OpenAI SDK, then pass them through `sdkOptions.tools`.
+
+```typescript
+import { tool } from '@openai/agents'
+import { OpenAISDKAgent } from '@mastra/openai'
+import { z } from 'zod'
+
+const getTemperature = tool({
+  name: 'get_temperature',
+  description: 'Get the current temperature for a city.',
+  parameters: z.object({
+    city: z.string(),
+  }),
+  execute: async ({ city }) => {
+    return `${city}: 27 C`
+  },
+})
+
+export const openaiSDKAgent = new OpenAISDKAgent({
+  id: 'openai-sdk-agent',
+  name: 'OpenAI SDK Agent',
+  description: 'Use OpenAI Agents SDK through Mastra.',
+  sdkOptions: {
+    name: 'Weather assistant',
+    model: 'gpt-5',
+    tools: [getTemperature],
+  },
+})
+```
+
 ## Register SDK agents
 
 Register SDK agents in the Mastra instance like other agents:
@@ -224,11 +336,13 @@ Register SDK agents in the Mastra instance like other agents:
 import { Mastra } from '@mastra/core'
 import { claudeSDKAgent } from './agents/claude-sdk-agent'
 import { cursorSDKAgent } from './agents/cursor-sdk-agent'
+import { openaiSDKAgent } from './agents/openai-sdk-agent'
 
 export const mastra = new Mastra({
   agents: {
     claudeSDKAgent,
     cursorSDKAgent,
+    openaiSDKAgent,
   },
 })
 ```
@@ -246,11 +360,61 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
+## Resume SDK runs
+
+SDK agents support Mastra `resumeGenerate()` and `resumeStream()` with provider-native resume data. Pass the message to continue with and the resume identifier used by the underlying SDK.
+
+Claude SDK agents can resume a known session with `sessionId`:
+
+```typescript
+const result = await claudeSDKAgent.resumeGenerate({
+  message: 'Continue the previous task.',
+  sessionId: 'claude-session-id',
+})
+
+console.log(result.text)
+```
+
+OpenAI SDK agents can resume with a previous response, conversation, or session:
+
+```typescript
+const stream = await openaiSDKAgent.resumeStream({
+  message: 'Continue the previous task.',
+  previousResponseId: 'resp_123',
+})
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+Cursor SDK agents can continue with the wrapped SDK agent. If you need to resume a stored Cursor SDK agent by ID, pass `agentId` in `resumeData`.
+
+## Structured output
+
+Claude and OpenAI SDK agents support Mastra `structuredOutput` through their provider-native structured output APIs. The validated value is available on `result.object`.
+
+```typescript
+import { z } from 'zod'
+
+const result = await openaiSDKAgent.generate<{ summary: string }>('Summarize this project.', {
+  structuredOutput: {
+    schema: z.object({
+      summary: z.string(),
+    }),
+  },
+})
+
+console.log(result.object.summary)
+```
+
+Cursor SDK agents throw a clear error when `structuredOutput` is requested because the Cursor TypeScript SDK doesn't expose a schema-constrained output API.
+
 ## Observability
 
 SDK agents create Mastra agent and model spans for `generate()` and `stream()` calls. Mastra records SDK-provided usage, tool activity, and provider metadata when the vendor SDK exposes those events.
 
-Claude SDK runs can include SDK-estimated cost from the Claude result message. Cursor SDK runs include token usage from Cursor interaction updates.
+Claude SDK runs can include SDK-estimated cost from the Claude result message. Cursor SDK runs include token usage from Cursor interaction updates. OpenAI SDK runs include token usage from OpenAI run state.
 
 For storage and dashboard setup, see [Observability](https://mastra.ai/docs/observability/overview).
 

package/dist/index.cjs

@@ -35,7 +35,8 @@ function createCompletedMastraStream({
   modelId,
   usage,
   providerMetadata,
-  costContext
+  costContext,
+  object
 }) {
   return new web.ReadableStream({
     start(controller) {
@@ -60,7 +61,8 @@ function createCompletedMastraStream({
         modelId,
         usage,
         providerMetadata,
-        costContext
+        costContext,
+        object
       });
       controller.close();
     }
@@ -108,7 +110,8 @@ function toFullOutput({
     modelId: result.response.modelId,
     usage: toLanguageModelUsage(result.usage),
     providerMetadata: result.providerMetadata,
-    costContext: result.costContext
+    costContext: result.costContext,
+    object: result.object
   });
   return createMastraOutput({
     messages,
@@ -486,7 +489,8 @@ function enqueueFinishChunks(controller, {
   modelId,
   usage,
   providerMetadata,
-  costContext
+  costContext,
+  object
 }) {
   const timestamp = /* @__PURE__ */ new Date();
   const response = {
@@ -510,6 +514,14 @@ function enqueueFinishChunks(controller, {
       providerMetadata
     }
   });
+  if (object !== void 0) {
+    controller.enqueue({
+      type: "object-result",
+      runId,
+      from: stream.ChunkFrom.AGENT,
+      object
+    });
+  }
   controller.enqueue({
     type: "step-finish",
     runId,
@@ -650,9 +662,13 @@ var CursorSDKAgent = class extends agent.Agent {
     return false;
   }
   async generate(messages, options) {
+    assertStructuredOutputUnsupported(options);
+    const sdkAgent = await this.resolveCursorAgent();
+    return this.generateWithAgent(messages, sdkAgent, options);
+  }
+  async generateWithAgent(messages, sdkAgent, options) {
     const prompt = promptToText(messages);
     const runId = options?.runId ?? crypto.randomUUID();
-    const sdkAgent = await this.resolveCursorAgent();
     const modelId = getCursorModelId(this.options, sdkAgent);
     const requestContext$1 = options?.requestContext ?? new requestContext.RequestContext();
     const instructions = options?.instructions ? promptToText(options.instructions) : void 0;
@@ -692,9 +708,13 @@ var CursorSDKAgent = class extends agent.Agent {
     });
   }
   async stream(messages, options) {
+    assertStructuredOutputUnsupported(options);
+    const sdkAgent = await this.resolveCursorAgent();
+    return this.streamWithAgent(messages, sdkAgent, options);
+  }
+  async streamWithAgent(messages, sdkAgent, options) {
     const runId = options?.runId ?? crypto.randomUUID();
     const prompt = promptToText(messages);
-    const sdkAgent = await this.resolveCursorAgent();
     const modelId = getCursorModelId(this.options, sdkAgent);
     const requestContext$1 = options?.requestContext ?? new requestContext.RequestContext();
     const instructions = options?.instructions ? promptToText(options.instructions) : void 0;
@@ -726,6 +746,18 @@ var CursorSDKAgent = class extends agent.Agent {
       options: telemetry.outputOptions()
     });
   }
+  async resumeGenerate(resumeData, options) {
+    assertStructuredOutputUnsupported(options);
+    const data = validateCursorResumeData(resumeData);
+    const sdkAgent = await this.resolveResumeCursorAgent(data);
+    return this.generateWithAgent(data.message, sdkAgent, options);
+  }
+  async resumeStream(resumeData, options) {
+    assertStructuredOutputUnsupported(options);
+    const data = validateCursorResumeData(resumeData);
+    const sdkAgent = await this.resolveResumeCursorAgent(data);
+    return this.streamWithAgent(data.message, sdkAgent, options);
+  }
   resolveCursorAgent() {
     this.#createdAgent ??= resolveCursorAgent(this.options.agent, this.options).catch((error) => {
       this.#createdAgent = void 0;
@@ -733,7 +765,33 @@ var CursorSDKAgent = class extends agent.Agent {
     });
     return this.#createdAgent;
   }
+  async resolveResumeCursorAgent(resumeData) {
+    if (!resumeData.agentId) {
+      return this.resolveCursorAgent();
+    }
+    return sdk.Agent.resume(resumeData.agentId, {
+      ...toCursorCreateOptions(this.options),
+      ...resumeData.sdkOptions
+    });
+  }
 };
+function validateCursorResumeData(resumeData) {
+  if (!toRecord(resumeData) || !("message" in resumeData)) {
+    throw new Error("CursorSDKAgent resumeData must include a message.");
+  }
+  if (resumeData.agentId !== void 0 && typeof resumeData.agentId !== "string") {
+    throw new Error("CursorSDKAgent resumeData.agentId must be a string when provided.");
+  }
+  return resumeData;
+}
+function assertStructuredOutputUnsupported(options) {
+  const structuredOutput = toRecord(toRecord(options)?.structuredOutput);
+  if (structuredOutput && "schema" in structuredOutput) {
+    throw new Error(
+      "CursorSDKAgent does not support structuredOutput because the Cursor TypeScript SDK does not expose a schema-constrained output API."
+    );
+  }
+}
 async function runCursorGenerate(prompt, options, agent, telemetry) {
   const usage = createCursorUsageCollector();
   const run = await agent.send(prompt, createCursorSendOptions(options, usage, telemetry));