@mastra/claude 0.1.0 → 0.2.0-alpha.1

package/dist/index.js

@@ -6,6 +6,7 @@ import { RequestContext } from '@mastra/core/request-context';
 import { ChunkFrom, MastraModelOutput } from '@mastra/core/stream';
 import { MessageList } from '@mastra/core/agent/message-list';
 import { getOrCreateSpan, EntityType, SpanType, executeWithContext } from '@mastra/core/observability';
+import { toStandardSchema, standardSchemaToJSONSchema } from '@mastra/core/schema';
 
 // src/index.ts
 function createNoopModel({ modelId, provider }) {
@@ -33,7 +34,8 @@ function createCompletedMastraStream({
   modelId,
   usage,
   providerMetadata,
-  costContext
+  costContext,
+  object
 }) {
   return new ReadableStream({
     start(controller) {
@@ -58,7 +60,8 @@ function createCompletedMastraStream({
         modelId,
         usage,
         providerMetadata,
-        costContext
+        costContext,
+        object
       });
       controller.close();
     }
@@ -70,11 +73,12 @@ function createMastraOutput({
   modelId,
   provider,
   stream,
+  responseText = "",
   options
 }) {
   const messageList = new MessageList();
   messageList.add(messages, "input");
-  messageList.add([{ role: "assistant", content: "" }], "response");
+  messageList.add([{ role: "assistant", content: responseText }], "response");
   return new MastraModelOutput({
     model: {
       modelId,
@@ -106,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,
@@ -114,6 +119,7 @@ function toFullOutput({
     modelId: result.response.modelId,
     provider,
     stream,
+    responseText: text,
     options
   }).getFullOutput();
 }
@@ -484,7 +490,8 @@ function enqueueFinishChunks(controller, {
   modelId,
   usage,
   providerMetadata,
-  costContext
+  costContext,
+  object
 }) {
   const timestamp = /* @__PURE__ */ new Date();
   const response = {
@@ -508,6 +515,14 @@ function enqueueFinishChunks(controller, {
       providerMetadata
     }
   });
+  if (object !== void 0) {
+    controller.enqueue({
+      type: "object-result",
+      runId,
+      from: ChunkFrom.AGENT,
+      object
+    });
+  }
   controller.enqueue({
     type: "step-finish",
     runId,
@@ -612,6 +627,48 @@ function promptToText(prompt) {
   }
   return "";
 }
+function getStructuredOutputSchema(structuredOutput) {
+  if (!structuredOutput?.schema) {
+    return void 0;
+  }
+  return standardSchemaToJSONSchema(toStandardSchema(structuredOutput.schema));
+}
+async function getStructuredOutputFromValue(value, structuredOutput) {
+  if (!structuredOutput?.schema) {
+    return void 0;
+  }
+  let parsed;
+  if (typeof value === "string") {
+    try {
+      parsed = JSON.parse(value);
+    } catch (error) {
+      return handleStructuredOutputError(
+        new Error("Structured output must be valid JSON.", { cause: error }),
+        structuredOutput
+      );
+    }
+  } else {
+    parsed = value;
+  }
+  const schema = toStandardSchema(structuredOutput.schema);
+  const result = await schema["~standard"].validate(parsed);
+  if (!result.issues) {
+    return result.value;
+  }
+  const message = result.issues.map((issue) => `- ${issue.path?.join(".") || "root"}: ${issue.message}`).join("\n");
+  return handleStructuredOutputError(new Error(`Structured output validation failed:
+${message}`), structuredOutput);
+}
+function handleStructuredOutputError(error, structuredOutput) {
+  if (structuredOutput.errorStrategy === "fallback") {
+    return structuredOutput.fallbackValue;
+  }
+  if (structuredOutput.errorStrategy === "warn") {
+    structuredOutput.logger?.warn(error.message);
+    return void 0;
+  }
+  throw error;
+}
 function sumDefined(...values) {
   const defined = values.filter((value) => typeof value === "number");
   if (defined.length === 0) {
@@ -672,9 +729,7 @@ var ClaudeSDKAgent = class extends Agent {
     });
     let result;
     try {
-      result = await telemetry.execute(
-        () => runClaudeGenerate(prompt, this.options, telemetry, options?.abortSignal ?? options?.signal)
-      );
+      result = await telemetry.execute(() => runClaudeGenerate(prompt, this.options, telemetry, options));
       telemetry.endGenerate(result);
     } catch (error) {
       telemetry.fail(error);
@@ -685,7 +740,7 @@ var ClaudeSDKAgent = class extends Agent {
       runId,
       provider: PROVIDER,
       result,
-      options: telemetry.outputOptions()
+      options: { ...telemetry.outputOptions(), structuredOutput: options?.structuredOutput }
     });
   }
   async stream(messages, options) {
@@ -718,26 +773,82 @@ var ClaudeSDKAgent = class extends Agent {
       runId,
       modelId,
       provider: PROVIDER,
-      stream: telemetry.wrapStream(
-        runClaudeAsMastraStream(prompt, this.options, runId, telemetry, options?.abortSignal ?? options?.signal)
-      ),
-      options: telemetry.outputOptions()
+      stream: telemetry.wrapStream(runClaudeAsMastraStream(prompt, this.options, runId, telemetry, options)),
+      options: { ...telemetry.outputOptions(), structuredOutput: options?.structuredOutput }
     });
   }
+  async resumeGenerate(resumeData, options) {
+    const data = validateClaudeResumeData(resumeData);
+    return this.generate(data.message, createClaudeResumeRunOptions(data, options));
+  }
+  async resumeStream(resumeData, options) {
+    const data = validateClaudeResumeData(resumeData);
+    return this.stream(data.message, createClaudeResumeRunOptions(data, options));
+  }
 };
-async function runClaudeGenerate(prompt, options, telemetry, signal) {
+function validateClaudeResumeData(resumeData) {
+  if (!isRecord(resumeData) || !("message" in resumeData)) {
+    throw new Error("ClaudeSDKAgent resumeData must include a message.");
+  }
+  const hasSessionId = "sessionId" in resumeData;
+  const hasContinue = "continue" in resumeData;
+  if (hasSessionId && hasContinue) {
+    throw new Error("ClaudeSDKAgent resumeData must include either sessionId or continue: true, not both.");
+  }
+  if (hasSessionId) {
+    if (typeof resumeData.sessionId !== "string") {
+      throw new Error("ClaudeSDKAgent resumeData.sessionId must be a string.");
+    }
+    return resumeData;
+  }
+  if (hasContinue) {
+    if (resumeData.continue !== true) {
+      throw new Error("ClaudeSDKAgent resumeData.continue must be true when provided.");
+    }
+    return resumeData;
+  }
+  throw new Error("ClaudeSDKAgent resumeData must include sessionId or continue: true.");
+}
+function createClaudeResumeRunOptions(resumeData, options) {
+  const sdkOptions = { ...options?.sdkOptions };
+  if ("sessionId" in resumeData && typeof resumeData.sessionId === "string") {
+    sdkOptions.resume = resumeData.sessionId;
+    if (resumeData.forkSession !== void 0) {
+      sdkOptions.forkSession = resumeData.forkSession;
+    }
+    if (resumeData.resumeSessionAt !== void 0) {
+      sdkOptions.resumeSessionAt = resumeData.resumeSessionAt;
+    }
+  } else {
+    sdkOptions.continue = true;
+  }
+  return {
+    ...options,
+    sdkOptions
+  };
+}
+async function runClaudeGenerate(prompt, options, telemetry, runOptions) {
   let text = "";
+  let structuredOutputValue;
   const usage = createClaudeUsageCollector();
-  for await (const message of observeClaudeMessages(runClaude(prompt, options, signal), telemetry)) {
+  for await (const message of observeClaudeMessages(
+    runClaude(prompt, options, runOptions?.abortSignal ?? runOptions?.signal, runOptions),
+    telemetry
+  )) {
     usage.record(message);
     if (message.type === "result") {
       if (message.subtype !== "success") {
         throw new Error(message.errors.join("\n") || `Claude Agent SDK failed with ${message.subtype}`);
       }
       text = message.result;
+      structuredOutputValue = getClaudeStructuredOutput(message);
     }
   }
   const totals = usage.totals();
+  const object = await getStructuredOutputFromValue(
+    structuredOutputValue === void 0 ? text : structuredOutputValue,
+    runOptions?.structuredOutput
+  );
   return {
     content: [{ type: "text", text }],
     finishReason: { unified: "stop", raw: "stop" },
@@ -748,10 +859,11 @@ async function runClaudeGenerate(prompt, options, telemetry, signal) {
       timestamp: /* @__PURE__ */ new Date()
     },
     providerMetadata: getClaudeProviderMetadata(options, totals),
-    costContext: getClaudeCostContext(options, totals)
+    costContext: getClaudeCostContext(options, totals),
+    object
   };
 }
-function runClaudeAsMastraStream(prompt, options, runId, telemetry, signal) {
+function runClaudeAsMastraStream(prompt, options, runId, telemetry, runOptions) {
   return new ReadableStream({
     start: async (controller) => {
       const textId = randomUUID();
@@ -759,6 +871,7 @@ function runClaudeAsMastraStream(prompt, options, runId, telemetry, signal) {
       const modelId = getModelId(options);
       const usage = createClaudeUsageCollector();
       let text = "";
+      let structuredOutputValue;
       let sawDelta = false;
       try {
         enqueueStartChunks(controller, {
@@ -769,7 +882,10 @@ function runClaudeAsMastraStream(prompt, options, runId, telemetry, signal) {
           modelId,
           providerMetadata: getClaudeProviderMetadata(options, usage.totals())
         });
-        for await (const message of observeClaudeMessages(runClaude(prompt, options, signal), telemetry)) {
+        for await (const message of observeClaudeMessages(
+          runClaude(prompt, options, runOptions?.abortSignal ?? runOptions?.signal, runOptions),
+          telemetry
+        )) {
           usage.record(message);
           const delta = getTextDelta(message);
           if (delta) {
@@ -785,6 +901,7 @@ function runClaudeAsMastraStream(prompt, options, runId, telemetry, signal) {
               text += message.result;
               enqueueTextDelta(controller, runId, textId, message.result);
             }
+            structuredOutputValue = getClaudeStructuredOutput(message);
           }
         }
         const totals = usage.totals();
@@ -798,7 +915,11 @@ function runClaudeAsMastraStream(prompt, options, runId, telemetry, signal) {
           modelId,
           usage: usage.toLanguageModelUsage(),
           providerMetadata,
-          costContext: getClaudeCostContext(options, totals)
+          costContext: getClaudeCostContext(options, totals),
+          object: await getStructuredOutputFromValue(
+            structuredOutputValue === void 0 ? text : structuredOutputValue,
+            runOptions?.structuredOutput
+          )
         });
         controller.close();
       } catch (error) {
@@ -813,11 +934,19 @@ function runClaudeAsMastraStream(prompt, options, runId, telemetry, signal) {
     }
   });
 }
-function runClaude(prompt, options, signal) {
+function runClaude(prompt, options, signal, runOptions) {
   const abortController = createAbortController(signal);
   const queryOptions = {
-    ...options.sdkOptions
+    ...options.sdkOptions,
+    ...runOptions?.sdkOptions
   };
+  const outputSchema = getStructuredOutputSchema(runOptions?.structuredOutput);
+  if (outputSchema) {
+    queryOptions.outputFormat = {
+      type: "json_schema",
+      schema: outputSchema
+    };
+  }
   if (abortController) {
     queryOptions.abortController = abortController;
   }
@@ -826,6 +955,12 @@ function runClaude(prompt, options, signal) {
     options: queryOptions
   });
 }
+function getClaudeStructuredOutput(message) {
+  if (message.type !== "result") {
+    return void 0;
+  }
+  return message.structured_output;
+}
 async function* observeClaudeMessages(messages, telemetry) {
   for await (const message of messages) {
     recordClaudeToolTelemetry(message, telemetry);