@kortyx/hooks 0.29.0 → 0.30.1

package/dist/index.js

@@ -24,6 +24,7 @@ __export(index_exports, {
   completeResponse: () => completeResponse,
   createWorkflowHooks: () => createWorkflowHooks,
   defineInterruptContract: () => defineInterruptContract,
+  defineOutputContract: () => defineOutputContract,
   emitWorkflowCall: () => emitWorkflowCall,
   parallel: () => parallel,
   reportError: () => reportError,
@@ -441,6 +442,118 @@ var normalizeReasonInterrupts = (args) => {
 };
 var isLegacyInterruptContracts = (config) => Boolean(config && legacyConfigs.has(config));
 
+// src/output-contract.ts
+var import_zod2 = require("zod");
+
+// src/structured-path.ts
+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);
+};
+
+// src/output-contract.ts
+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_zod2.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;
+};
+
 // src/reason/use-reason.ts
 var import_core6 = require("@kortyx/core");
 
@@ -526,25 +639,6 @@ async function withSafeTraceSpan(adapter, args, fn) {
 
 // src/structured.ts
 var import_node_crypto = require("crypto");
-
-// src/structured-path.ts
-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);
-};
-
-// src/structured.ts
 var createStructuredStreamId = () => {
   try {
     return (0, import_node_crypto.randomUUID)();
@@ -1356,12 +1450,12 @@ async function reasonEngine(args, meta, inputOverride) {
 }
 
 // src/reason/output-format.ts
-var import_zod2 = require("zod");
+var import_zod3 = require("zod");
 function inferOutputFormat(schema, explicit) {
   if (explicit) return { responseFormat: explicit };
   if (!schema) return {};
   try {
-    const json = (0, import_zod2.toJSONSchema)(schema);
+    const json = (0, import_zod3.toJSONSchema)(schema);
     const clean = (value) => {
       if (Array.isArray(value)) return value.map(clean);
       if (!value || typeof value !== "object") return value;
@@ -2116,7 +2210,7 @@ var createTruncatedStructuredOutputError = (label, cause) => new import_errors5.
 );
 var createInvalidStructuredOutputError = (label, cause) => new import_errors5.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) => {
@@ -2241,7 +2335,7 @@ var parseInterruptFirstPassResult = (args) => {
 };
 
 // src/reason/prompting.ts
-var import_zod3 = require("zod");
+var import_zod4 = require("zod");
 var tryStringify2 = (value) => {
   if (typeof value === "string") return value;
   try {
@@ -2252,7 +2346,7 @@ var tryStringify2 = (value) => {
 };
 var tryGetSchemaHint = (schema) => {
   try {
-    const hint = (0, import_zod3.toJSONSchema)(schema);
+    const hint = (0, import_zod4.toJSONSchema)(schema);
     return JSON.stringify(hint, null, 2);
   } catch {
     return void 0;
@@ -2454,7 +2548,7 @@ var emitReasonStructuredOutput = (args) => {
 // src/reason/tools.ts
 var import_core5 = require("@kortyx/core");
 var import_errors6 = require("@kortyx/core/errors");
-var import_zod4 = require("zod");
+var import_zod5 = require("zod");
 var toToolDefinitions = (tools2) => tools2.map((tool) => ({
   name: tool.name,
   ...tool.title ? { title: tool.title } : {},
@@ -2490,10 +2584,14 @@ var normalizeToolResult = (toolCall, value) => {
   };
 };
 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 ?? "") }
@@ -2515,12 +2613,13 @@ var runReasonToolLoop = async (args) => {
     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}".`);
@@ -2549,7 +2648,7 @@ var runReasonToolLoop = async (args) => {
       );
     let inputSchema;
     try {
-      inputSchema = (0, import_zod4.toJSONSchema)(contract.requestSchema);
+      inputSchema = (0, import_zod5.toJSONSchema)(contract.requestSchema);
     } catch (error) {
       throw new Error(
         `useReason interrupt contract "${name}" requestSchema must support JSON Schema conversion.`,
@@ -2573,9 +2672,66 @@ var runReasonToolLoop = async (args) => {
       }
     });
   }
+  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_zod5.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;
@@ -2590,11 +2746,27 @@ var runReasonToolLoop = async (args) => {
         "- 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;
@@ -2609,8 +2781,11 @@ var runReasonToolLoop = async (args) => {
     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",
@@ -2619,8 +2794,11 @@ var runReasonToolLoop = async (args) => {
       steps,
       approvedCalls,
       interruptHistory,
+      emissions,
+      ...returned ? { returned } : {},
       finalizing,
-      ...pending ? { pending } : {}
+      ...pending ? { pending } : {},
+      ...pending && pendingStepIndex !== void 0 ? { pendingStepIndex } : {}
     };
     ctx.stateDirty = true;
   };
@@ -2633,7 +2811,7 @@ var runReasonToolLoop = async (args) => {
     });
   };
   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_core5.throwIfExecutionAborted)(abortSignal);
       traceSpan?.addEvent?.("useReason.tool-step.start", {
         stepIndex,
@@ -2643,6 +2821,7 @@ var runReasonToolLoop = async (args) => {
       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(
         {
@@ -2656,15 +2835,15 @@ var runReasonToolLoop = async (args) => {
             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) {
@@ -2680,7 +2859,7 @@ var runReasonToolLoop = async (args) => {
       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);
       }
@@ -2696,7 +2875,12 @@ var runReasonToolLoop = async (args) => {
           ...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."
@@ -2734,6 +2918,7 @@ var runReasonToolLoop = async (args) => {
           });
           finalizing = true;
           pending = void 0;
+          pendingStepIndex = void 0;
           save();
           continue;
         }
@@ -2746,7 +2931,9 @@ var runReasonToolLoop = async (args) => {
         );
       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",
@@ -2756,7 +2943,197 @@ var runReasonToolLoop = async (args) => {
         });
       }
       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)
       );
@@ -2779,6 +3156,7 @@ var runReasonToolLoop = async (args) => {
           );
         if (toolResults.some((result3) => result3.toolCallId === interruptCall.id)) {
           pending = void 0;
+          pendingStepIndex = void 0;
           save();
           continue;
         }
@@ -2832,6 +3210,7 @@ var runReasonToolLoop = async (args) => {
           interruptIndex: interruptHistory.length - 1
         });
         pending = void 0;
+        pendingStepIndex = void 0;
         save();
         continue;
       }
@@ -3007,6 +3386,7 @@ var runReasonToolLoop = async (args) => {
         save();
       }
       pending = void 0;
+      pendingStepIndex = void 0;
       save();
     }
     if (!completed) {
@@ -3035,7 +3415,7 @@ var runReasonToolLoop = async (args) => {
     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 } : {},
@@ -3045,6 +3425,8 @@ var runReasonToolLoop = async (args) => {
       toolCalls: allToolCalls,
       toolResults: allToolResults,
       steps,
+      ...emissions.length ? { emissions } : {},
+      ...returned ? { returned } : {},
       ...interruptHistory.length > 0 ? { interruptHistory } : {},
       ...isLegacyInterruptContracts(interruptConfig) && interruptHistory.length > 0 ? {
         interruptResponse: interruptHistory.at(-1)?.response
@@ -3060,11 +3442,13 @@ var runReasonToolLoop = async (args) => {
         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 };
@@ -3091,7 +3475,7 @@ var resolveEffectiveReasoningIncludeThoughts = (args) => args.reasoning?.include
 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."
@@ -3099,6 +3483,15 @@ var assertReasoningThoughtsCompatibility = (args) => {
 };
 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
@@ -3172,7 +3565,7 @@ async function runReason(args) {
       }
     },
     async (traceSpan) => {
-      if ((args.tools?.length || args.interrupts) && !existingCheckpoint) {
+      if ((args.tools?.length || args.interrupts || args.outputs) && !existingCheckpoint) {
         return runReasonToolLoop({
           useReasonArgs: args,
           allowValidatedToolOutput,
@@ -3435,6 +3828,53 @@ async function useReason(args) {
 
 // src/hooks.ts
 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) {
@@ -3958,6 +4398,7 @@ async function runWorkflowCall(args, task) {
   completeResponse,
   createWorkflowHooks,
   defineInterruptContract,
+  defineOutputContract,
   emitWorkflowCall,
   parallel,
   reportError,