@kortyx/agent 0.27.0 → 0.28.0

package/dist/index.js

@@ -526,6 +526,7 @@ var require_dist = __commonJS({
       completeResponse: () => completeResponse,
       createWorkflowHooks: () => createWorkflowHooks,
       defineInterruptContract: () => defineInterruptContract,
+      defineOutputContract: () => defineOutputContract,
       emitWorkflowCall: () => emitWorkflowCall2,
       parallel: () => parallel,
       reportError: () => reportError,
@@ -926,6 +927,112 @@ var require_dist = __commonJS({
       return normalized;
     };
     var isLegacyInterruptContracts = (config) => Boolean(config && legacyConfigs.has(config));
+    var import_zod22 = require("zod");
+    var parseStructuredPath = (path, source) => {
+      if (path.length === 0) {
+        throw new Error(`${source} path must be a non-empty dot-separated string.`);
+      }
+      const parts = path.split(".");
+      if (parts.some((part) => part.length === 0)) {
+        throw new Error(
+          `${source} path "${path}" must not contain empty segments.`
+        );
+      }
+      return parts;
+    };
+    var assertStructuredPath = (path, source) => {
+      parseStructuredPath(path, source);
+    };
+    var EMIT_PREFIX = "kortyx_emit__";
+    var RETURN_PREFIX = "kortyx_return__";
+    var STREAM_EMIT_PREFIX = "kortyx_stream_emit__";
+    var STREAM_RETURN_PREFIX = "kortyx_stream_return__";
+    var legacyOutputWarningEmitted = false;
+    var warnLegacyReasonOutput = () => {
+      if (legacyOutputWarningEmitted) return;
+      legacyOutputWarningEmitted = true;
+      process.emitWarning(
+        "useReason({ outputSchema, structured }) and result.output are deprecated and will be removed in the next major release. Define reusable contracts with defineOutputContract() and pass them through useReason({ outputs }). See docs/internal/next-major-removals.md.",
+        { code: "KORTYX_USE_REASON_OUTPUT_DEPRECATED", type: "DeprecationWarning" }
+      );
+    };
+    var defineOutputContract = (contract) => {
+      if (!contract || typeof contract !== "object")
+        throw new Error("defineOutputContract requires a contract object.");
+      for (const [field, value] of [
+        ["description", contract.description],
+        ["schemaId", contract.schemaId],
+        ["schemaVersion", contract.schemaVersion]
+      ])
+        if (typeof value !== "string" || value.trim().length === 0)
+          throw new Error(`Output contract ${field} must be a non-empty string.`);
+      if (typeof contract.schema?.safeParse !== "function")
+        throw new Error("Output contract schema must provide safeParse(value).");
+      if (contract.stream) {
+        if (!contract.stream.fields || Object.keys(contract.stream.fields).length === 0)
+          throw new Error("Output contract stream.fields must not be empty.");
+        for (const [path, mode] of Object.entries(contract.stream.fields)) {
+          assertStructuredPath(path, "Output contract stream.fields");
+          if (!["set", "append", "text-delta"].includes(mode))
+            throw new Error(`Invalid output contract stream mode for "${path}".`);
+        }
+      }
+      return contract;
+    };
+    var outputControlToolName = (kind, name) => `${kind === "emit" ? EMIT_PREFIX : kind === "return" ? RETURN_PREFIX : kind === "stream-emit" ? STREAM_EMIT_PREFIX : STREAM_RETURN_PREFIX}${name}`;
+    var isOutputControlToolName = (name) => name.startsWith(EMIT_PREFIX) || name.startsWith(RETURN_PREFIX) || name.startsWith(STREAM_EMIT_PREFIX) || name.startsWith(STREAM_RETURN_PREFIX);
+    var normalizeReasonOutputs = (config, hasLegacyOutput) => {
+      if (!config) return void 0;
+      if (hasLegacyOutput)
+        throw new Error(
+          "useReason cannot combine `outputs` with deprecated `outputSchema` or `structured`."
+        );
+      const entries = [
+        ...Object.entries(config.emit ?? {}).map(([name, contract]) => ({
+          name,
+          contract,
+          kind: "emit"
+        })),
+        ...Object.entries(config.return ?? {}).map(([name, contract]) => ({
+          name,
+          contract,
+          kind: "return"
+        }))
+      ];
+      if (entries.length === 0)
+        throw new Error(
+          "useReason outputs must include at least one emit or return contract."
+        );
+      for (const { name, contract, kind } of entries) {
+        if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name) || outputControlToolName(kind, name).length > 64)
+          throw new Error(`Invalid useReason output contract name "${name}".`);
+        defineOutputContract(contract);
+        if (contract.schema["~kortyx"]?.nativeOutput === true)
+          throw new Error(
+            `useReason output contract "${name}" uses a provider-native output schema that cannot be selected through tools. Continue using outputSchema for this provider until a non-tool contract path is available.`
+          );
+        if (contract.stream && outputControlToolName(
+          kind === "emit" ? "stream-emit" : "stream-return",
+          name
+        ).length > 64)
+          throw new Error(
+            `Invalid useReason output contract name "${name}" for streaming tools.`
+          );
+        try {
+          const json = (0, import_zod22.toJSONSchema)(contract.schema);
+          if (json.type !== "object")
+            throw new Error("The tool input schema must have an object root.");
+        } catch (error) {
+          throw new Error(
+            `useReason output contract "${name}" schema must support JSON Schema conversion.`,
+            { cause: error }
+          );
+        }
+      }
+      if (config.maxEmissions !== void 0 && (!Number.isInteger(config.maxEmissions) || config.maxEmissions < 1))
+        throw new Error("useReason outputs.maxEmissions must be at least 1.");
+      return config;
+    };
     var import_core62 = require("@kortyx/core");
     function safeSpan(span) {
       const guard = (fn) => (...args) => {
@@ -1006,21 +1113,6 @@ var require_dist = __commonJS({
       return execution ?? invoke(safeSpan(void 0));
     }
     var import_node_crypto4 = require("crypto");
-    var parseStructuredPath = (path, source) => {
-      if (path.length === 0) {
-        throw new Error(`${source} path must be a non-empty dot-separated string.`);
-      }
-      const parts = path.split(".");
-      if (parts.some((part) => part.length === 0)) {
-        throw new Error(
-          `${source} path "${path}" must not contain empty segments.`
-        );
-      }
-      return parts;
-    };
-    var assertStructuredPath = (path, source) => {
-      parseStructuredPath(path, source);
-    };
     var createStructuredStreamId = () => {
       try {
         return (0, import_node_crypto4.randomUUID)();
@@ -1816,12 +1908,12 @@ var require_dist = __commonJS({
         throw error;
       }
     }
-    var import_zod22 = require("zod");
+    var import_zod32 = require("zod");
     function inferOutputFormat(schema, explicit) {
       if (explicit) return { responseFormat: explicit };
       if (!schema) return {};
       try {
-        const json = (0, import_zod22.toJSONSchema)(schema);
+        const json = (0, import_zod32.toJSONSchema)(schema);
         const clean = (value) => {
           if (Array.isArray(value)) return value.map(clean);
           if (!value || typeof value !== "object") return value;
@@ -2570,7 +2662,7 @@ var require_dist = __commonJS({
     );
     var createInvalidStructuredOutputError = (label, cause) => new import_errors52.ValidationError(
       "INVALID_MODEL_JSON",
-      `${label} did not produce valid structured output. The model returned text instead of the expected JSON payload. Check outputSchema and provider structured-output settings.`,
+      `${label} did not produce valid structured output. The model returned text instead of the expected JSON payload. Check the output contract or outputSchema and provider structured-output settings.`,
       cause
     );
     var parseReasonOutputWithSchema = (args) => {
@@ -2693,7 +2785,7 @@ var require_dist = __commonJS({
         throw error;
       }
     };
-    var import_zod32 = require("zod");
+    var import_zod42 = require("zod");
     var tryStringify2 = (value) => {
       if (typeof value === "string") return value;
       try {
@@ -2704,7 +2796,7 @@ var require_dist = __commonJS({
     };
     var tryGetSchemaHint = (schema) => {
       try {
-        const hint = (0, import_zod32.toJSONSchema)(schema);
+        const hint = (0, import_zod42.toJSONSchema)(schema);
         return JSON.stringify(hint, null, 2);
       } catch {
         return void 0;
@@ -2902,7 +2994,7 @@ ${tryStringify2(args.response)}`
     };
     var import_core52 = require("@kortyx/core");
     var import_errors62 = require("@kortyx/core/errors");
-    var import_zod42 = require("zod");
+    var import_zod52 = require("zod");
     var toToolDefinitions = (tools2) => tools2.map((tool) => ({
       name: tool.name,
       ...tool.title ? { title: tool.title } : {},
@@ -2938,10 +3030,14 @@ ${tryStringify2(args.response)}`
       };
     };
     var createInitialMessages = (args) => [
-      ...typeof args.system === "string" || args.interruptInstructions ? [
+      ...typeof args.system === "string" || args.interruptInstructions || args.outputInstructions ? [
         {
           role: "system",
-          content: [args.system, args.interruptInstructions].filter((value) => Boolean(value)).join("\n\n")
+          content: [
+            args.system,
+            args.interruptInstructions,
+            args.outputInstructions
+          ].filter((value) => Boolean(value)).join("\n\n")
         }
       ] : [],
       { role: "user", content: String(args.input ?? "") }
@@ -2963,12 +3059,13 @@ ${tryStringify2(args.response)}`
         interrupts: useReasonArgs.interrupts
       });
       const interruptByToolName = /* @__PURE__ */ new Map();
+      const outputByToolName = /* @__PURE__ */ new Map();
       const toolByName = /* @__PURE__ */ new Map();
       let separateOutput = false;
       for (const tool of tools2) {
-        if (isInterruptControlToolName(tool.name))
+        if (isInterruptControlToolName(tool.name) || isOutputControlToolName(tool.name))
           throw new Error(
-            `useReason tool name "${tool.name}" uses the reserved interrupt control-tool namespace.`
+            `useReason tool name "${tool.name}" uses a reserved control-tool namespace.`
           );
         if (toolByName.has(tool.name)) {
           throw new Error(`useReason received duplicate tool name "${tool.name}".`);
@@ -2997,7 +3094,7 @@ ${tryStringify2(args.response)}`
           );
         let inputSchema;
         try {
-          inputSchema = (0, import_zod42.toJSONSchema)(contract.requestSchema);
+          inputSchema = (0, import_zod52.toJSONSchema)(contract.requestSchema);
         } catch (error) {
           throw new Error(
             `useReason interrupt contract "${name}" requestSchema must support JSON Schema conversion.`,
@@ -3021,9 +3118,66 @@ ${tryStringify2(args.response)}`
           }
         });
       }
+      const outputDefinitions = [];
+      for (const kind of ["emit", "return"]) {
+        for (const [name, contract] of Object.entries(
+          useReasonArgs.outputs?.[kind] ?? {}
+        )) {
+          if (contract.stream) {
+            const streamName = outputControlToolName(
+              kind === "emit" ? "stream-emit" : "stream-return",
+              name
+            );
+            outputByToolName.set(streamName, {
+              name,
+              kind,
+              contract,
+              stream: true
+            });
+            outputDefinitions.push({
+              name: streamName,
+              title: `Stream structured output: ${name}`,
+              description: `${contract.description} Call this to start realtime generation of this structured value. The value is generated in a separate streamed model pass, validated, and ${kind === "emit" ? "returned as a tool result so you can continue" : "used to finish this operation"}.`,
+              inputSchema: {
+                type: "object",
+                properties: {
+                  instruction: {
+                    type: "string",
+                    description: "What the streamed output should contain."
+                  }
+                },
+                required: ["instruction"],
+                additionalProperties: false
+              },
+              metadata: {
+                kortyxControl: kind === "emit" ? "output.stream.emit" : "output.stream.return",
+                contract: name,
+                schemaId: contract.schemaId,
+                schemaVersion: contract.schemaVersion
+              }
+            });
+          } else {
+            const toolName = outputControlToolName(kind, name);
+            outputByToolName.set(toolName, { name, kind, contract, stream: false });
+            outputDefinitions.push({
+              name: toolName,
+              title: `${kind === "emit" ? "Emit" : "Return"} structured output: ${name}`,
+              description: `${contract.description} ${kind === "emit" ? "Emit this structured value and continue reasoning." : "Return this structured value and finish reasoning."}`,
+              inputSchema: (0, import_zod52.toJSONSchema)(contract.schema),
+              metadata: {
+                kortyxControl: kind === "emit" ? "output.emit" : "output.return",
+                contract: name,
+                schemaId: contract.schemaId,
+                schemaVersion: contract.schemaVersion
+              }
+            });
+          }
+        }
+      }
       const toolDefinitions = [
         ...toToolDefinitions(tools2),
-        ...interruptDefinitions
+        ...interruptDefinitions,
+        ...outputDefinitions
       ];
       let finalizing = checkpoint?.finalizing ?? false;
       let completed = false;
@@ -3038,11 +3192,27 @@ ${tryStringify2(args.response)}`
             "- Call at most one human-input tool in a model turn, and do not combine it with other tool calls in that turn.",
             interruptConfig.mode === "required" ? "- You must call at least one human-input tool before returning the final answer." : "- Human input is optional; call a human-input tool only when the request cannot be completed safely without it."
           ].join("\n")
+        } : {},
+        ...useReasonArgs.outputs ? {
+          outputInstructions: [
+            "Structured output rules:",
+            "- The kortyx_emit__* tools publish validated structured output and return an acknowledgement. You may continue with text or more tools afterward.",
+            "- The kortyx_return__* tools publish a validated result and end this reasoning operation. If return tools are available, call exactly one before finishing.",
+            "- For contracts with realtime streaming, use kortyx_stream_emit__* or kortyx_stream_return__*. These start a separate streamed JSON generation; its fields become visible as tokens arrive.",
+            "- Call a structured output control tool alone in its model turn."
+          ].join("\n")
         } : {}
       });
       const steps = checkpoint?.steps ?? [];
-      const allToolCalls = steps.flatMap((step) => step.toolCalls).filter((call) => !interruptByToolName.has(call.name));
-      const allToolResults = steps.flatMap((step) => step.toolResults).filter((result) => !interruptByToolName.has(result.name));
+      const allToolCalls = steps.flatMap((step) => step.toolCalls).filter(
+        (call) => !interruptByToolName.has(call.name) && !outputByToolName.has(call.name)
+      );
+      const knownToolCallIds = new Set(
+        steps.flatMap((step) => step.toolCalls.map((call) => call.id))
+      );
+      const allToolResults = steps.flatMap((step) => step.toolResults).filter(
+        (result) => !interruptByToolName.has(result.name) && !outputByToolName.has(result.name)
+      );
       let finalText = "";
       let finalRaw;
       let finalOutput;
@@ -3057,8 +3227,11 @@ ${tryStringify2(args.response)}`
         args.initialWarnings
       );
       let pending = checkpoint?.pending;
+      let pendingStepIndex = checkpoint?.pendingStepIndex;
       const approvedCalls = checkpoint?.approvedCalls ?? [];
       const interruptHistory = checkpoint?.interruptHistory ?? [];
+      const emissions = checkpoint?.emissions ?? [];
+      let returned = checkpoint?.returned;
       const save = () => {
         ctx.currentNodeState.byKey[checkpointKey] = {
           status: "tool_loop",
@@ -3067,8 +3240,11 @@ ${tryStringify2(args.response)}`
           steps,
           approvedCalls,
           interruptHistory,
+          emissions,
+          ...returned ? { returned } : {},
           finalizing,
-          ...pending ? { pending } : {}
+          ...pending ? { pending } : {},
+          ...pending && pendingStepIndex !== void 0 ? { pendingStepIndex } : {}
         };
         ctx.stateDirty = true;
       };
@@ -3081,7 +3257,7 @@ ${tryStringify2(args.response)}`
         });
       };
       try {
-        for (let stepIndex = pending ? steps.length - 1 : steps.length; stepIndex < maxSteps; stepIndex += 1) {
+        for (let stepIndex = pending ? pendingStepIndex ?? steps.length - 1 : steps.length; stepIndex < maxSteps; stepIndex += 1) {
           (0, import_core52.throwIfExecutionAborted)(abortSignal);
           traceSpan?.addEvent?.("useReason.tool-step.start", {
             stepIndex,
@@ -3091,6 +3267,7 @@ ${tryStringify2(args.response)}`
           const stream = useReasonArgs.stream ?? useReasonArgs.model.options?.streaming ?? true;
           const emit = useReasonArgs.emit ?? true;
           let textStarted = false;
+          const segmentId = `step-${stepIndex}`;
           const structuredChunk = useReasonArgs.outputSchema && (!separateOutput || finalizing) && stream && emit && shouldStreamStructured(useReasonArgs.structured) ? createStructuredOutputStreamer(useReasonArgs, id, opId) : void 0;
           const step = pending ?? await reasonEngine(
             {
@@ -3104,15 +3281,15 @@ ${tryStringify2(args.response)}`
                 if (structuredChunk) structuredChunk(delta);
                 if (!emit || useReasonArgs.outputSchema || !delta) return;
                 if (!textStarted) {
-                  emitToolEvent("text-start", {});
+                  emitToolEvent("text-start", { segmentId });
                   textStarted = true;
                 }
-                emitToolEvent("text-delta", { delta });
+                emitToolEvent("text-delta", { delta, segmentId });
               }
             },
             { ...id ? { id } : {}, opId }
           );
-          if (textStarted) emitToolEvent("text-end", {});
+          if (textStarted) emitToolEvent("text-end", { segmentId });
           finalText = step.text;
           finalRaw = step.raw;
           if (!reused) {
@@ -3128,7 +3305,7 @@ ${tryStringify2(args.response)}`
           const toolCalls = step.toolCalls ?? [];
           const ids = /* @__PURE__ */ new Set();
           for (const call of toolCalls) {
-            if (!call.id || ids.has(call.id) || !reused && allToolCalls.some((prior) => prior.id === call.id))
+            if (!call.id || ids.has(call.id) || !reused && knownToolCallIds.has(call.id))
               throw new Error("Model returned duplicate or empty tool call IDs.");
             ids.add(call.id);
           }
@@ -3144,7 +3321,12 @@ ${tryStringify2(args.response)}`
               ...step.providerMetadata ? { providerMetadata: step.providerMetadata } : {},
               ...step.warnings ? { warnings: step.warnings } : {}
             });
+          if (!reused) for (const call of toolCalls) knownToolCallIds.add(call.id);
           if (toolCalls.length === 0) {
+            if (Object.keys(useReasonArgs.outputs?.return ?? {}).length > 0 && !returned)
+              throw new Error(
+                "useReason outputs.return requires one terminal output contract call."
+              );
             if (interruptConfig?.mode === "required" && interruptHistory.length === 0)
               throw new Error(
                 "useReason interrupts.mode is required, but the model returned a final answer without requesting human input."
@@ -3182,6 +3364,7 @@ ${tryStringify2(args.response)}`
               });
               finalizing = true;
               pending = void 0;
+              pendingStepIndex = void 0;
               save();
               continue;
             }
@@ -3194,7 +3377,9 @@ ${tryStringify2(args.response)}`
             );
           if (!reused) {
             allToolCalls.push(
-              ...toolCalls.filter((call) => !interruptByToolName.has(call.name))
+              ...toolCalls.filter(
+                (call) => !interruptByToolName.has(call.name) && !outputByToolName.has(call.name)
+              )
             );
             messages.push({
               role: "assistant",
@@ -3204,7 +3389,197 @@ ${tryStringify2(args.response)}`
             });
           }
           pending = step;
+          pendingStepIndex = stepIndex;
           save();
+          const outputCalls = toolCalls.filter(
+            (call) => outputByToolName.has(call.name)
+          );
+          if (outputCalls.length > 0) {
+            if (toolCalls.length !== 1)
+              throw new Error(
+                "A useReason output contract call must be the only tool call in its model turn."
+              );
+            const call = outputCalls[0];
+            if (!call) throw new Error("Missing useReason output control call.");
+            const resolved = outputByToolName.get(call.name);
+            if (!resolved)
+              throw new Error(
+                `Unknown useReason output contract tool "${call.name}".`
+              );
+            if (toolResults.some((result3) => result3.toolCallId === call.id)) {
+              pending = void 0;
+              pendingStepIndex = void 0;
+              save();
+              continue;
+            }
+            if (resolved.kind === "emit" && emissions.length >= (useReasonArgs.outputs?.maxEmissions ?? 16))
+              throw new Error(
+                `useReason reached outputs.maxEmissions (${useReasonArgs.outputs?.maxEmissions ?? 16}).`
+              );
+            let data;
+            if (resolved.stream) {
+              if (!stream)
+                throw new Error(
+                  `useReason streaming output contract "${resolved.name}" requires stream: true.`
+                );
+              if (stepIndex + 1 >= maxSteps)
+                throw new Error(
+                  `useReason output streaming requires another model pass within maxSteps (${maxSteps}).`
+                );
+              const instruction = call.input && typeof call.input === "object" && !Array.isArray(call.input) ? call.input.instruction : void 0;
+              if (typeof instruction !== "string" || instruction.trim().length === 0)
+                throw new Error(
+                  `useReason streaming output contract "${resolved.name}" requires an instruction.`
+                );
+              const streamId = `${opId}:${resolved.kind}:${resolved.name}:${resolved.kind === "emit" ? emissions.length : "return"}`;
+              const structured = {
+                dataType: resolved.contract.schemaId,
+                schemaId: resolved.contract.schemaId,
+                schemaVersion: resolved.contract.schemaVersion,
+                fields: resolved.contract.stream?.fields
+              };
+              const inferred = inferOutputFormat(
+                resolved.contract.schema,
+                void 0
+              );
+              try {
+                const outputStep = await reasonEngine(
+                  {
+                    ...useReasonArgs,
+                    tools: [],
+                    ...inferred.responseFormat ? { responseFormat: inferred.responseFormat } : {},
+                    messages: [
+                      ...messages,
+                      {
+                        role: "tool",
+                        toolCallId: call.id,
+                        name: call.name,
+                        content: "Generating the requested structured output."
+                      },
+                      {
+                        role: "user",
+                        content: withOutputGuardrails(
+                          instruction,
+                          resolved.contract.schema
+                        )
+                      }
+                    ],
+                    emit: false,
+                    stream,
+                    ...emit && stream ? {
+                      onTextChunk: createStructuredOutputStreamer(
+                        { structured },
+                        id,
+                        streamId
+                      )
+                    } : {}
+                  },
+                  { ...id ? { id } : {}, opId }
+                );
+                if (outputStep.toolCalls?.length)
+                  throw new Error(
+                    `Provider requested a tool during streamed output contract "${resolved.name}".`
+                  );
+                aggregatedUsage = mergeUsage(aggregatedUsage, outputStep.usage);
+                accumulateTokenUsage(outputStep.usage);
+                aggregatedWarnings = mergeWarnings(
+                  aggregatedWarnings,
+                  mergeWarnings(inferred.warnings, outputStep.warnings)
+                );
+                aggregatedProviderMetadata = mergeProviderMetadata(
+                  aggregatedProviderMetadata,
+                  outputStep.providerMetadata
+                );
+                finalFinishReason = outputStep.finishReason;
+                finalRaw = outputStep.raw;
+                data = parseReasonOutputWithSchema({
+                  text: outputStep.text,
+                  schema: resolved.contract.schema,
+                  ...outputStep.finishReason ? { finishReason: outputStep.finishReason } : {},
+                  ...aggregatedUsage ? { usage: aggregatedUsage } : {},
+                  label: `useReason output contract "${resolved.name}"`
+                });
+                steps.push({
+                  stepIndex: stepIndex + 1,
+                  kind: "output",
+                  text: outputStep.text,
+                  toolCalls: [],
+                  toolResults: [],
+                  ...outputStep.usage ? { usage: outputStep.usage } : {},
+                  ...outputStep.finishReason ? { finishReason: outputStep.finishReason } : {},
+                  ...outputStep.providerMetadata ? { providerMetadata: outputStep.providerMetadata } : {},
+                  ...outputStep.warnings ? { warnings: outputStep.warnings } : {}
+                });
+                stepIndex += 1;
+              } catch (error) {
+                traceSpan?.addEvent?.("useReason.output.invalidated", {
+                  contract: resolved.name,
+                  kind: resolved.kind,
+                  schemaId: resolved.contract.schemaId,
+                  schemaVersion: resolved.contract.schemaVersion,
+                  streamId
+                });
+                if (emit) {
+                  try {
+                    ctx.node.emit("structured_data_invalidated", {
+                      node: ctx.node.graph.node,
+                      streamId
+                    });
+                  } catch {
+                  }
+                }
+                throw error;
+              }
+            } else {
+              data = parseWithSchema(
+                resolved.contract.schema,
+                call.input,
+                `useReason output contract "${resolved.name}"`
+              );
+            }
+            const entry = { contract: resolved.name, data };
+            const emissionIndex = emissions.length;
+            if (resolved.kind === "emit")
+              emissions.push(entry);
+            else returned = entry;
+            if (emit)
+              emitStructuredData({
+                kind: "final",
+                data,
+                dataType: resolved.contract.schemaId,
+                schemaId: resolved.contract.schemaId,
+                schemaVersion: resolved.contract.schemaVersion,
+                streamId: `${opId}:${resolved.kind}:${resolved.name}:${resolved.kind === "emit" ? emissionIndex : "return"}`,
+                ...id ? { id } : {}
+              });
+            traceSpan?.addEvent?.("useReason.output.emitted", {
+              contract: resolved.name,
+              kind: resolved.kind,
+              schemaId: resolved.contract.schemaId,
+              schemaVersion: resolved.contract.schemaVersion,
+              emissionIndex,
+              data
+            });
+            if (resolved.kind === "return") {
+              pending = void 0;
+              pendingStepIndex = void 0;
+              completed = true;
+              save();
+              break;
+            }
+            const result2 = normalizeToolResult(call, { emitted: true, data });
+            toolResults.push(result2);
+            messages.push({
+              role: "tool",
+              content: result2.content,
+              toolCallId: result2.toolCallId,
+              name: result2.name
+            });
+            pending = void 0;
+            pendingStepIndex = void 0;
+            save();
+            continue;
+          }
           const interruptCalls = toolCalls.filter(
             (call) => interruptByToolName.has(call.name)
           );
@@ -3227,6 +3602,7 @@ ${tryStringify2(args.response)}`
               );
             if (toolResults.some((result3) => result3.toolCallId === interruptCall.id)) {
               pending = void 0;
+              pendingStepIndex = void 0;
               save();
               continue;
             }
@@ -3280,6 +3656,7 @@ ${tryStringify2(args.response)}`
               interruptIndex: interruptHistory.length - 1
             });
             pending = void 0;
+            pendingStepIndex = void 0;
             save();
             continue;
           }
@@ -3455,6 +3832,7 @@ ${tryStringify2(args.response)}`
             save();
           }
           pending = void 0;
+          pendingStepIndex = void 0;
           save();
         }
         if (!completed) {
@@ -3483,7 +3861,7 @@ ${tryStringify2(args.response)}`
         const result = {
           ...id ? { id } : {},
           opId,
-          text: finalText,
+          text: useReasonArgs.outputs ? steps.filter((step) => step.kind !== "output").map((step) => step.text).filter(Boolean).join("\n") : finalText,
           ...finalRaw !== void 0 ? { raw: finalRaw } : {},
           ...aggregatedUsage !== void 0 ? { usage: aggregatedUsage } : {},
           ...finalFinishReason !== void 0 ? { finishReason: finalFinishReason } : {},
@@ -3493,6 +3871,8 @@ ${tryStringify2(args.response)}`
           toolCalls: allToolCalls,
           toolResults: allToolResults,
           steps,
+          ...emissions.length ? { emissions } : {},
+          ...returned ? { returned } : {},
           ...interruptHistory.length > 0 ? { interruptHistory } : {},
           ...isLegacyInterruptContracts(interruptConfig) && interruptHistory.length > 0 ? {
             interruptResponse: interruptHistory.at(-1)?.response
@@ -3508,11 +3888,13 @@ ${tryStringify2(args.response)}`
             toolCallCount: allToolCalls.length,
             toolResultCount: allToolResults.length,
             toolStepCount: steps.length,
-            interruptCount: interruptHistory.length
+            interruptCount: interruptHistory.length,
+            emissionCount: emissions.length,
+            ...returned ? { returnContract: returned.contract } : {}
           },
           telemetry: {
             ...useReasonArgs.telemetry ?? {},
-            output: useReasonArgs.telemetry?.output ?? finalOutput ?? finalText
+            output: useReasonArgs.telemetry?.output ?? returned?.data ?? finalOutput ?? finalText
           }
         });
         ctx.currentNodeState.byKey[checkpointKey] = { status: "completed", result };
@@ -3537,7 +3919,7 @@ ${tryStringify2(args.response)}`
     var resolveEffectiveResponseFormatType = (args) => args.responseFormat?.type ?? args.model.options?.responseFormat?.type;
     var assertReasoningThoughtsCompatibility = (args) => {
       if (!resolveEffectiveReasoningIncludeThoughts(args)) return;
-      const usesStructuredOutput = Boolean(args.outputSchema) || Boolean(args.interrupt) || Boolean(args.interrupts) || Boolean(args.structured) || resolveEffectiveResponseFormatType(args) === "json";
+      const usesStructuredOutput = Boolean(args.outputSchema) || Boolean(args.interrupt) || Boolean(args.interrupts) || Boolean(args.structured) || Boolean(args.outputs) || resolveEffectiveResponseFormatType(args) === "json";
       if (!usesStructuredOutput) return;
       throw new Error(
         "useReason does not support reasoning.includeThoughts with structured output, interrupt mode, or JSON responseFormat. Disable includeThoughts for this call."
@@ -3545,6 +3927,15 @@ ${tryStringify2(args.response)}`
     };
     async function runReason(args) {
       assertReasoningThoughtsCompatibility(args);
+      normalizeReasonOutputs(
+        args.outputs,
+        Boolean(args.outputSchema || args.structured)
+      );
+      if (args.outputSchema || args.structured) warnLegacyReasonOutput();
+      if (args.outputs && resolveEffectiveResponseFormatType(args) === "json")
+        throw new Error(
+          "useReason output contracts use tool calls and cannot be combined with JSON responseFormat."
+        );
       const interruptConfig = normalizeReasonInterrupts({
         interrupt: args.interrupt,
         interrupts: args.interrupts
@@ -3618,7 +4009,7 @@ ${tryStringify2(args.response)}`
           }
         },
         async (traceSpan) => {
-          if ((args.tools?.length || args.interrupts) && !existingCheckpoint) {
+          if ((args.tools?.length || args.interrupts || args.outputs) && !existingCheckpoint) {
             return runReasonToolLoop({
               useReasonArgs: args,
               allowValidatedToolOutput,
@@ -3879,6 +4270,53 @@ ${tryStringify2(args.response)}`
       }
     }
     function useStructuredData(args) {
+      if ("contract" in args) {
+        const contract = defineOutputContract(args.contract);
+        const base = {
+          dataType: contract.schemaId,
+          schemaId: contract.schemaId,
+          schemaVersion: contract.schemaVersion,
+          ...args.id ? { id: args.id } : {},
+          ...args.streamId ? { streamId: args.streamId } : {}
+        };
+        if (args.kind === "set" || args.kind === "append" || args.kind === "text-delta") {
+          if (contract.stream?.fields[args.path] !== args.kind)
+            throw new Error(
+              `Output contract does not allow ${args.kind} at "${args.path}".`
+            );
+          if (args.kind === "set")
+            emitStructuredData({
+              ...base,
+              kind: "set",
+              path: args.path,
+              value: args.value,
+              ...args.valueSchema ? { valueSchema: args.valueSchema } : {}
+            });
+          else if (args.kind === "append")
+            emitStructuredData({
+              ...base,
+              kind: "append",
+              path: args.path,
+              items: args.items,
+              ...args.itemSchema ? { itemSchema: args.itemSchema } : {}
+            });
+          else
+            emitStructuredData({
+              ...base,
+              kind: "text-delta",
+              path: args.path,
+              delta: args.delta
+            });
+          return;
+        }
+        emitStructuredData({
+          ...base,
+          kind: "final",
+          data: args.data,
+          dataSchema: contract.schema
+        });
+        return;
+      }
       emitStructuredData(args);
     }
     function useReason2(args) {
@@ -5492,6 +5930,13 @@ async function orchestrateGraphStream({
       });
       return;
     }
+    if (event === "structured_data_invalidated") {
+      const streamId = payload?.streamId;
+      if (typeof streamId !== "string" || !streamId) return;
+      structuredStreamIds.delete(streamId);
+      write({ type: "structured-data-invalidated", streamId });
+      return;
+    }
     if (event === "transition") {
       write({
         type: "transition",