@kortyx/agent 0.26.2 → 0.28.0

package/dist/index.js

@@ -61,7 +61,7 @@ var require_internal = __commonJS({
       withSafeTraceSpan: () => withSafeTraceSpan2
     });
     module2.exports = __toCommonJS2(internal_exports);
-    var import_errors6 = require("@kortyx/core/errors");
+    var import_errors8 = require("@kortyx/core/errors");
     var MAX_STACK_LENGTH = 32768;
     var MAX_CAUSE_DEPTH = 4;
     var projectDetails = (value, depth, seen) => {
@@ -71,16 +71,16 @@ var require_internal = __commonJS({
           return { type: "Error", message: "Circular error cause." };
         seen.add(objectValue);
       }
-      const name = (0, import_errors6.errorProperty)(value, "name") ?? (value instanceof Error ? value.name : void 0);
-      const message = (0, import_errors6.errorProperty)(value, "message");
-      const stack = (0, import_errors6.errorProperty)(value, "stack") ?? (value instanceof Error ? (() => {
+      const name = (0, import_errors8.errorProperty)(value, "name") ?? (value instanceof Error ? value.name : void 0);
+      const message = (0, import_errors8.errorProperty)(value, "message");
+      const stack = (0, import_errors8.errorProperty)(value, "stack") ?? (value instanceof Error ? (() => {
         try {
           return value.stack;
         } catch {
           return void 0;
         }
       })() : void 0);
-      const cause = depth < MAX_CAUSE_DEPTH ? (0, import_errors6.errorProperty)(value, "cause") : null;
+      const cause = depth < MAX_CAUSE_DEPTH ? (0, import_errors8.errorProperty)(value, "cause") : null;
       return {
         type: typeof name === "string" ? name.slice(0, 256) : "Error",
         message: (typeof value === "string" ? value : typeof message === "string" ? message : "Execution reported a fault.").slice(0, 8192),
@@ -526,6 +526,7 @@ var require_dist = __commonJS({
       completeResponse: () => completeResponse,
       createWorkflowHooks: () => createWorkflowHooks,
       defineInterruptContract: () => defineInterruptContract,
+      defineOutputContract: () => defineOutputContract,
       emitWorkflowCall: () => emitWorkflowCall2,
       parallel: () => parallel,
       reportError: () => reportError,
@@ -789,14 +790,14 @@ var require_dist = __commonJS({
         workflowState: args.workflowState
       }
     });
-    var import_errors6 = require("@kortyx/core/errors");
+    var import_errors8 = require("@kortyx/core/errors");
     var parseWithSchema = (schema, value, label) => {
       if (!schema) return value;
       const parsed = schema.safeParse(value);
       if (parsed.success) return parsed.data;
       const parsedError = "error" in parsed && parsed.error ? parsed.error : void 0;
       const reason = typeof parsedError?.message === "string" && parsedError.message.length > 0 ? parsedError.message : "invalid payload";
-      throw new import_errors6.ValidationError(
+      throw new import_errors8.ValidationError(
         label === "useReason output" ? "MODEL_OUTPUT_SCHEMA" : "SCHEMA_VALIDATION",
         `${label} validation failed: ${reason}`,
         parsedError
@@ -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) {
@@ -3950,7 +4388,7 @@ ${tryStringify2(args.response)}`
       return [getValue(), setValue];
     }
     var import_core7 = require("@kortyx/core");
-    var import_errors7 = require("@kortyx/core/errors");
+    var import_errors72 = require("@kortyx/core/errors");
     var ParallelChildWaiting = class extends Error {
       name = "ParallelChildWaiting";
     };
@@ -3964,14 +4402,14 @@ ${tryStringify2(args.response)}`
         );
         this.results = results;
         this.name = "ParallelError";
-        this.failure = (0, import_errors7.serializeFailure)({
+        this.failure = (0, import_errors72.serializeFailure)({
           version: 1,
           code: this.code,
           category: "workflow",
           message: this.message,
           retryable: null,
           results: results.map(
-            (result) => result.status === "fulfilled" ? { status: "fulfilled" } : { status: "rejected", failure: (0, import_errors7.serializeFailure)(result.reason) }
+            (result) => result.status === "fulfilled" ? { status: "fulfilled" } : { status: "rejected", failure: (0, import_errors72.serializeFailure)(result.reason) }
           )
         });
       }
@@ -3979,7 +4417,7 @@ ${tryStringify2(args.response)}`
       code = "PARALLEL_FAILED";
       failure;
       toJSON() {
-        return (0, import_errors7.serializeFailure)(this);
+        return (0, import_errors72.serializeFailure)(this);
       }
     };
     function registerWorkflowTask(id) {
@@ -4124,11 +4562,11 @@ ${tryStringify2(args.response)}`
     }
     var import_node_crypto6 = require("crypto");
     var import_core8 = require("@kortyx/core");
-    var import_errors8 = require("@kortyx/core/errors");
-    var WorkflowCallError = class extends import_errors8.KortyxError {
+    var import_errors82 = require("@kortyx/core/errors");
+    var WorkflowCallError = class extends import_errors82.KortyxError {
       constructor(workflow, message, cause, failure) {
-        const detail = (0, import_errors8.serializeFailure)(
-          failure ?? cause ?? new import_errors8.WorkflowContractError(message)
+        const detail = (0, import_errors82.serializeFailure)(
+          failure ?? cause ?? new import_errors82.WorkflowContractError(message)
         );
         super(detail.code, `Workflow '${workflow}': ${message}`, {
           ...detail,
@@ -4149,12 +4587,12 @@ ${tryStringify2(args.response)}`
         if (v === null || typeof v === "string" || typeof v === "boolean") return v;
         if (typeof v === "number" && Number.isFinite(v)) return v;
         if (typeof v !== "object" || !v || seen.has(v)) {
-          throw new import_errors8.WorkflowContractError(
+          throw new import_errors82.WorkflowContractError(
             "Workflow input and output must be JSON serializable."
           );
         }
         if (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype) {
-          throw new import_errors8.WorkflowContractError(
+          throw new import_errors82.WorkflowContractError(
             "Workflow input and output must contain plain JSON objects."
           );
         }
@@ -4175,7 +4613,7 @@ ${tryStringify2(args.response)}`
         useWorkflow: (args) => {
           const workflow = workflows[args.workflow];
           if (!workflow || workflow.id !== args.workflow)
-            throw new import_errors8.WorkflowContractError(
+            throw new import_errors82.WorkflowContractError(
               "Workflow registry keys must match definition ids."
             );
           return useWorkflow({ ...args, workflow });
@@ -4201,23 +4639,23 @@ ${tryStringify2(args.response)}`
       (0, import_core8.throwIfExecutionAborted)(ctx.node.abortSignal);
       const service = ctx.node.callWorkflow;
       if (!service)
-        throw new import_errors8.WorkflowContractError(
+        throw new import_errors82.WorkflowContractError(
           "useWorkflow requires an agent workflow registry."
         );
       if (!args.id.trim())
-        throw new import_errors8.WorkflowContractError(
+        throw new import_errors82.WorkflowContractError(
           "useWorkflow requires a stable, nonempty id."
         );
       if (ctx.workflowCallActive && !task.group)
-        throw new import_errors8.WorkflowContractError(
+        throw new import_errors82.WorkflowContractError(
           "Concurrent workflow calls require parallel([...]); otherwise await each call."
         );
       if (ctx.workflowCallIds.has(args.id))
-        throw new import_errors8.WorkflowContractError(
+        throw new import_errors82.WorkflowContractError(
           `Duplicate workflow call id '${args.id}' in one node activation.`
         );
       if (ctx.workflowCallIds.size >= 64)
-        throw new import_errors8.WorkflowContractError(
+        throw new import_errors82.WorkflowContractError(
           "A node may call at most 64 child workflows per activation."
         );
       ctx.workflowCallIds.add(args.id);
@@ -4298,7 +4736,7 @@ ${tryStringify2(args.response)}`
             workflow,
             record.error ?? "child failed",
             void 0,
-            record.failure ?? (0, import_errors8.serializeFailure)(void 0)
+            record.failure ?? (0, import_errors82.serializeFailure)(void 0)
           );
         if (task.group && record.status === "interrupted" && record.interrupts.at(-1)?.response === void 0)
           throw new ParallelChildWaiting();
@@ -4334,7 +4772,7 @@ ${tryStringify2(args.response)}`
               throw error;
             }
             record.status = "failed";
-            record.failure = (0, import_errors8.serializeFailure)(error);
+            record.failure = (0, import_errors82.serializeFailure)(error);
             record.error = record.failure.message;
             report("failed", { error: "Child workflow failed" });
             throw new WorkflowCallError(
@@ -4395,6 +4833,7 @@ ${tryStringify2(args.response)}`
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ChatLifecycleHookError: () => ChatLifecycleHookError,
   ExecutionRequestError: () => ExecutionRequestError,
   createAgent: () => createAgent,
   createChatRouteHandler: () => createChatRouteHandler,
@@ -4417,198 +4856,44 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/adapters/http.ts
+var import_errors5 = require("@kortyx/core/errors");
+var import_stream2 = require("@kortyx/stream");
+var import_zod2 = require("zod");
+
+// src/chat/lifecycle.ts
 var import_errors = require("@kortyx/core/errors");
-var import_stream = require("@kortyx/stream");
-var import_zod = require("zod");
-var chatMessageSchema = import_zod.z.object({
-  role: import_zod.z.enum(["user", "assistant", "system"]),
-  content: import_zod.z.string(),
-  metadata: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
-  id: import_zod.z.string().optional(),
-  timestamp: import_zod.z.number().refine(Number.isFinite).optional()
-}).strict();
-var chatRequestBodySchema = import_zod.z.looseObject({
-  sessionId: import_zod.z.string().optional(),
-  workflowId: import_zod.z.string().optional(),
-  stream: import_zod.z.boolean().optional(),
-  context: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
-  messages: import_zod.z.array(chatMessageSchema)
-});
-var checkpointRequestBodySchema = import_zod.z.discriminatedUnion("action", [
-  import_zod.z.object({
-    action: import_zod.z.literal("list"),
-    sessionId: import_zod.z.string().min(1)
-  }).strict(),
-  import_zod.z.object({
-    action: import_zod.z.literal("get"),
-    checkpointId: import_zod.z.string().min(1)
-  }).strict(),
-  import_zod.z.object({
-    action: import_zod.z.literal("rollback"),
-    checkpointId: import_zod.z.string().min(1)
-  }).strict(),
-  import_zod.z.object({
-    action: import_zod.z.literal("fork"),
-    checkpointId: import_zod.z.string().min(1),
-    newSessionId: import_zod.z.string().min(1).optional()
-  }).strict()
-]);
-async function readRequestJson(request) {
-  try {
-    const value = await request.json();
-    if (!value || typeof value !== "object" || Array.isArray(value))
-      throw new Error("Expected a JSON object.");
-    return value;
-  } catch (cause) {
-    throw new import_errors.KortyxError(
-      "INVALID_REQUEST",
-      "Request body is not valid JSON.",
+var ChatLifecycleHookError = class extends import_errors.KortyxError {
+  phase;
+  constructor(phase, cause) {
+    super(
+      "CHAT_LIFECYCLE_HOOK_FAILED",
+      `Chat lifecycle hook failed: ${phase}`,
       {
-        category: "request",
-        retryable: false,
-        safeMessage: "The request body must contain a valid JSON object.",
+        category: "persistence",
+        retryable: null,
+        safeMessage: "Chat state could not be saved.",
         cause
       }
     );
+    this.name = "ChatLifecycleHookError";
+    this.phase = phase;
   }
-}
-function createFailureResponse(error, status) {
-  const failure = (0, import_errors.serializeFailure)(error);
-  return Response.json(
-    { error: failure.message, failure },
-    { status: status ?? (0, import_errors.failureHttpStatus)(failure) }
-  );
-}
-function parseChatRequestBody(value) {
-  const parsed = chatRequestBodySchema.safeParse(value);
-  if (!parsed.success) {
-    const [firstIssue] = parsed.error.issues;
-    throw new import_errors.KortyxError("INVALID_REQUEST", firstIssue.message, {
+};
+
+// src/interrupt/resume-handler.ts
+var import_core3 = require("@kortyx/core");
+var import_runtime2 = require("@kortyx/runtime");
+
+// src/execution/types.ts
+var import_errors2 = require("@kortyx/core/errors");
+var ExecutionRequestError = class extends import_errors2.KortyxError {
+  name = "ExecutionRequestError";
+  constructor(code, message, cause) {
+    super(code, message, {
       category: "request",
       retryable: false,
-      safeMessage: "The request body is invalid."
-    });
-  }
-  const sessionId = parsed.data.sessionId?.trim();
-  const workflowId = parsed.data.workflowId?.trim();
-  return {
-    ...sessionId ? { sessionId } : {},
-    ...workflowId ? { workflowId } : {},
-    ...typeof parsed.data.stream === "boolean" ? { stream: parsed.data.stream } : {},
-    ...parsed.data.context ? { context: parsed.data.context } : {},
-    messages: parsed.data.messages
-  };
-}
-function parseCheckpointRequestBody(value) {
-  const parsed = checkpointRequestBodySchema.safeParse(value);
-  if (parsed.success) return parsed.data;
-  const [firstIssue] = parsed.error.issues;
-  throw new import_errors.KortyxError("INVALID_REQUEST", firstIssue.message, {
-    category: "request",
-    retryable: false,
-    safeMessage: "The request body is invalid."
-  });
-}
-async function handleChatRequestBody(args) {
-  const { agent, body } = args;
-  const stream = await agent.streamChat(body.messages, {
-    ...args.onExecution ? { onExecution: args.onExecution } : {},
-    ...args.abortSignal ? { abortSignal: args.abortSignal } : {},
-    sessionId: body.sessionId,
-    workflowId: body.workflowId,
-    context: body.context
-  });
-  if (body.stream === false) {
-    const buffered = await (0, import_stream.collectBufferedStream)(stream);
-    return new Response(JSON.stringify(buffered), {
-      headers: {
-        "content-type": "application/json"
-      }
-    });
-  }
-  return (0, import_stream.toSSE)(stream);
-}
-function createChatRouteHandler(args) {
-  const { agent, errorStatus } = args;
-  return async function POST(request) {
-    try {
-      const body = parseChatRequestBody(await readRequestJson(request));
-      return await handleChatRequestBody({
-        agent,
-        body,
-        abortSignal: request.signal,
-        onExecution: args.onExecution
-      });
-    } catch (error) {
-      return createFailureResponse(error, errorStatus);
-    }
-  };
-}
-async function handleCheckpointRequestBody(args) {
-  const { agent, body } = args;
-  const result = body.action === "list" ? await agent.listCheckpoints(body.sessionId) : body.action === "get" ? await agent.getCheckpoint(body.checkpointId) : body.action === "rollback" ? await agent.rollbackTo(body.checkpointId) : await agent.fork(body.checkpointId, {
-    ...body.newSessionId ? { newSessionId: body.newSessionId } : {}
-  });
-  return new Response(JSON.stringify(result), {
-    headers: {
-      "content-type": "application/json"
-    }
-  });
-}
-function createCheckpointRouteHandler(args) {
-  const { agent, errorStatus } = args;
-  return async function POST(request) {
-    try {
-      const body = parseCheckpointRequestBody(await readRequestJson(request));
-      return await handleCheckpointRequestBody({ agent, body });
-    } catch (error) {
-      return createFailureResponse(error, errorStatus);
-    }
-  };
-}
-
-// src/adapters/http-client.ts
-var import_browser = require("@kortyx/stream/browser");
-async function* streamChatFromRoute(args) {
-  yield* (0, import_browser.streamFromRoute)({
-    endpoint: args.endpoint,
-    ...args.fetchImpl ? { fetchImpl: args.fetchImpl } : {},
-    ...args.headers ? { headers: args.headers } : {},
-    body: {
-      sessionId: args.sessionId,
-      workflowId: args.workflowId,
-      messages: args.messages
-    }
-  });
-}
-
-// src/chat/create-agent.ts
-var import_node_path = require("path");
-var import_core5 = require("@kortyx/core");
-var import_providers = require("@kortyx/providers");
-var import_runtime5 = require("@kortyx/runtime");
-var import_zod5 = require("zod");
-
-// src/execution/execute.ts
-var import_core4 = require("@kortyx/core");
-var import_errors5 = require("@kortyx/core/errors");
-var import_runtime3 = require("@kortyx/runtime");
-var import_zod3 = require("zod");
-
-// src/interrupt/resume-handler.ts
-var import_core3 = require("@kortyx/core");
-var import_runtime2 = require("@kortyx/runtime");
-
-// src/execution/types.ts
-var import_errors2 = require("@kortyx/core/errors");
-var ExecutionRequestError = class extends import_errors2.KortyxError {
-  name = "ExecutionRequestError";
-  constructor(code, message, cause) {
-    super(code, message, {
-      category: "request",
-      retryable: false,
-      safeMessage: "The execution request is invalid. Check the workflow contract and request fields.",
-      cause
+      safeMessage: "The execution request is invalid. Check the workflow contract and request fields.",
+      cause
     });
   }
 };
@@ -4619,11 +4904,12 @@ var import_core2 = require("@kortyx/core");
 var import_errors4 = require("@kortyx/core/errors");
 var import_internal = __toESM(require_internal());
 var import_runtime = require("@kortyx/runtime");
+var import_stream = require("@kortyx/stream");
 var import_langgraph = require("@langchain/langgraph");
 
 // src/execution/contracts.ts
 var import_errors3 = require("@kortyx/core/errors");
-var import_zod2 = require("zod");
+var import_zod = require("zod");
 async function resolveExecutionWorkflow(select, reference) {
   const id = typeof reference === "string" ? reference : reference.id;
   let workflow;
@@ -4655,12 +4941,12 @@ async function resolveExecutionWorkflow(select, reference) {
 }
 function parseExecutionInput(workflow, input) {
   try {
-    import_zod2.z.json().parse(input);
+    import_zod.z.json().parse(input);
     const parsed = workflow.inputSchema ? workflow.inputSchema.parse(input) : input;
-    import_zod2.z.json().parse(parsed);
+    import_zod.z.json().parse(parsed);
     return parsed;
   } catch (error) {
-    if (!(error instanceof import_zod2.z.ZodError)) throw error;
+    if (!(error instanceof import_zod.z.ZodError)) throw error;
     throw new ExecutionRequestError("INVALID_INPUT", error.message, error);
   }
 }
@@ -4678,9 +4964,9 @@ async function validateExecutionOutput(state, select) {
     for (const schema of /* @__PURE__ */ new Set([terminal.outputSchema, root.outputSchema])) {
       if (schema) data = schema.parse(data);
     }
-    if (terminal.outputSchema || root.outputSchema) import_zod2.z.json().parse(data);
+    if (terminal.outputSchema || root.outputSchema) import_zod.z.json().parse(data);
   } catch (error) {
-    if (!(error instanceof import_zod2.z.ZodError)) throw error;
+    if (!(error instanceof import_zod.z.ZodError)) throw error;
     const failure = new import_errors3.ValidationError(
       "INVALID_OUTPUT",
       `Workflow output validation failed: ${error.message}`,
@@ -5091,6 +5377,9 @@ async function orchestrateGraphStream({
   abortSignal: requestSignal,
   executionSignal,
   onExecution,
+  clientTurnId,
+  continueOnDisconnect = false,
+  onResponseFinalized,
   emitOutput = true,
   onOutcome,
   selectWorkflow,
@@ -5099,12 +5388,34 @@ async function orchestrateGraphStream({
   executionLeaseRelease
 }) {
   const out = new import_node_stream.PassThrough({ objectMode: true });
+  const visibleMessage = emitOutput && clientTurnId && onResponseFinalized && initialConfig.responseCompleted !== true ? (0, import_stream.createFinalizedChatMessageAccumulator)(clientTurnId) : void 0;
+  let responseFinalized = false;
+  const finalizeVisibleResponse = async (status) => {
+    if (!visibleMessage || !onResponseFinalized || !clientTurnId || !sessionId || responseFinalized)
+      return;
+    responseFinalized = true;
+    try {
+      await onResponseFinalized({
+        sessionId,
+        runId,
+        clientTurnId,
+        status,
+        message: visibleMessage.message(),
+        ...sessionCheckpointId ? { checkpointId: sessionCheckpointId } : {}
+      });
+    } catch (error) {
+      console.error("[chat:onResponseFinalized]", (0, import_errors4.serializeFailure)(error));
+    }
+  };
   const write = (chunk) => {
     if (isRecord3(chunk) && chunk.type === "done" && isGraphState(chunk.data)) {
       const { __kortyxParallelGraph: _journal, ...runtime } = chunk.data.runtime;
       chunk = { ...chunk, data: { ...chunk.data, runtime } };
     }
-    if (emitOutput && !response.closed && !out.destroyed) out.write(chunk);
+    if (emitOutput && !response.closed) {
+      visibleMessage?.apply(chunk);
+      if (!out.destroyed) out.write(chunk);
+    }
   };
   let outcomeState = state;
   let outcomeError;
@@ -5119,7 +5430,7 @@ async function orchestrateGraphStream({
   const response = createResponseLifecycle({
     enabled: emitOutput,
     restored: initialConfig.responseCompleted === true,
-    requestSignal,
+    requestSignal: continueOnDisconnect ? void 0 : requestSignal,
     executionSignal: executionSignal ? AbortSignal.any([executionSignal, leaseAbort.signal]) : leaseAbort.signal,
     onClosed: () => {
       out.write({ type: "done" });
@@ -5183,11 +5494,12 @@ async function orchestrateGraphStream({
         },
         flush: true
       });
+      await finalizeVisibleResponse("completed");
     }
   });
   const abortSignal = response.signal;
   out.on("close", () => {
-    if (!finished) response.disconnect();
+    if (!finished && !continueOnDisconnect) response.disconnect();
   });
   let structuredSeq = 0;
   const debugEnabled = Boolean(config?.features?.tracing);
@@ -5618,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",
@@ -5940,6 +6259,9 @@ async function orchestrateGraphStream({
             );
           }
         }
+        await finalizeVisibleResponse(
+          outcomeError ? "failed" : shouldKeepFrameworkState ? "interrupted" : "completed"
+        );
         write({ type: "done", data: workflowFinalState });
         out.end();
         return;
@@ -6017,6 +6339,9 @@ async function orchestrateGraphStream({
       });
       finished = true;
       runTraceSpan.end?.(runTraceEndArgs());
+      await finalizeVisibleResponse(
+        outcomeError ? "failed" : pendingRecordToken || naturalFinalState.awaitingHumanInput ? "interrupted" : "completed"
+      );
       write({ type: "done", data: naturalFinalState });
       out.end();
       return;
@@ -6077,6 +6402,7 @@ async function orchestrateGraphStream({
     fallbackRunSpan?.setAttributes?.({ "kortyx.run.cancelled": true });
     fallbackRunSpan?.end?.();
     write({ type: "cancelled", runId, reason: "Execution cancelled." });
+    await finalizeVisibleResponse("cancelled");
     write({ type: "done" });
     finished = true;
     out.end();
@@ -6223,6 +6549,9 @@ async function orchestrateGraphStream({
       console.error("[execution:releaseLease]", (0, import_errors4.serializeFailure)(error));
     }
     response.dispose();
+    await finalizeVisibleResponse(
+      outcomeError ? (0, import_core2.isExecutionCancelled)(outcomeError) ? "cancelled" : "failed" : pendingRecordToken || outcomeState.awaitingHumanInput ? "interrupted" : "completed"
+    );
     onOutcome?.({
       state: outcomeState,
       pending: pendingRecordToken ? activePendingRequests.get(pendingRecordToken) : void 0,
@@ -6272,6 +6601,9 @@ async function tryPrepareResumeStream({
   abortSignal,
   executionSignal,
   onExecution,
+  clientTurnId,
+  continueOnDisconnect,
+  onResponseFinalized,
   lastMessage,
   meta: suppliedMeta,
   emitOutput,
@@ -6490,6 +6822,9 @@ async function tryPrepareResumeStream({
       executionSignal: continuedSignal ? AbortSignal.any([continuedSignal, leaseAbort.signal]) : leaseAbort.signal,
       executionLeaseRelease: releaseLease,
       onExecution,
+      clientTurnId,
+      continueOnDisconnect,
+      onResponseFinalized,
       emitOutput,
       onOutcome,
       sessionId,
@@ -6526,7 +6861,316 @@ async function tryPrepareResumeStream({
   }
 }
 
+// src/adapters/http.ts
+var reportLifecycleError = async (callback, event) => {
+  if (!callback) {
+    console.error("[chat:lifecycle]", event.error);
+    return;
+  }
+  try {
+    await callback(event);
+  } catch (error) {
+    console.error("[chat:onLifecycleError]", (0, import_errors5.serializeFailure)(error));
+  }
+};
+var chatMessageSchema = import_zod2.z.object({
+  role: import_zod2.z.enum(["user", "assistant", "system"]),
+  content: import_zod2.z.string(),
+  metadata: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.unknown()).optional(),
+  id: import_zod2.z.string().optional(),
+  timestamp: import_zod2.z.number().refine(Number.isFinite).optional()
+}).strict();
+var chatRequestBodySchema = import_zod2.z.looseObject({
+  sessionId: import_zod2.z.string().optional(),
+  clientTurnId: import_zod2.z.string().max(128).optional(),
+  workflowId: import_zod2.z.string().optional(),
+  stream: import_zod2.z.boolean().optional(),
+  context: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.unknown()).optional(),
+  messages: import_zod2.z.array(chatMessageSchema)
+});
+var checkpointRequestBodySchema = import_zod2.z.discriminatedUnion("action", [
+  import_zod2.z.object({
+    action: import_zod2.z.literal("list"),
+    sessionId: import_zod2.z.string().min(1)
+  }).strict(),
+  import_zod2.z.object({
+    action: import_zod2.z.literal("get"),
+    checkpointId: import_zod2.z.string().min(1)
+  }).strict(),
+  import_zod2.z.object({
+    action: import_zod2.z.literal("rollback"),
+    checkpointId: import_zod2.z.string().min(1)
+  }).strict(),
+  import_zod2.z.object({
+    action: import_zod2.z.literal("fork"),
+    checkpointId: import_zod2.z.string().min(1),
+    newSessionId: import_zod2.z.string().min(1).optional()
+  }).strict()
+]);
+async function readRequestJson(request) {
+  try {
+    const value = await request.json();
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      throw new Error("Expected a JSON object.");
+    return value;
+  } catch (cause) {
+    throw new import_errors5.KortyxError(
+      "INVALID_REQUEST",
+      "Request body is not valid JSON.",
+      {
+        category: "request",
+        retryable: false,
+        safeMessage: "The request body must contain a valid JSON object.",
+        cause
+      }
+    );
+  }
+}
+function createFailureResponse(error, status) {
+  const failure = (0, import_errors5.serializeFailure)(error);
+  return Response.json(
+    { error: failure.message, failure },
+    { status: status ?? (0, import_errors5.failureHttpStatus)(failure) }
+  );
+}
+function parseChatRequestBody(value) {
+  const parsed = chatRequestBodySchema.safeParse(value);
+  if (!parsed.success) {
+    const [firstIssue] = parsed.error.issues;
+    throw new import_errors5.KortyxError("INVALID_REQUEST", firstIssue.message, {
+      category: "request",
+      retryable: false,
+      safeMessage: "The request body is invalid."
+    });
+  }
+  const sessionId = parsed.data.sessionId?.trim();
+  const workflowId = parsed.data.workflowId?.trim();
+  const clientTurnId = parsed.data.clientTurnId?.trim();
+  return {
+    ...sessionId ? { sessionId } : {},
+    ...workflowId ? { workflowId } : {},
+    ...clientTurnId ? { clientTurnId } : {},
+    ...typeof parsed.data.stream === "boolean" ? { stream: parsed.data.stream } : {},
+    ...parsed.data.context ? { context: parsed.data.context } : {},
+    messages: parsed.data.messages
+  };
+}
+function parseCheckpointRequestBody(value) {
+  const parsed = checkpointRequestBodySchema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  const [firstIssue] = parsed.error.issues;
+  throw new import_errors5.KortyxError("INVALID_REQUEST", firstIssue.message, {
+    category: "request",
+    retryable: false,
+    safeMessage: "The request body is invalid."
+  });
+}
+async function handleChatRequestBody(args) {
+  const { agent, body } = args;
+  if (args.onResponseFinalized && (!body.sessionId || !body.clientTurnId)) {
+    throw new import_errors5.KortyxError(
+      "INVALID_REQUEST",
+      "sessionId and clientTurnId are required with onResponseFinalized.",
+      {
+        category: "request",
+        retryable: false,
+        safeMessage: "This chat request needs a session and turn ID."
+      }
+    );
+  }
+  const stream = await agent.streamChat(body.messages, {
+    ...args.onExecution ? { onExecution: args.onExecution } : {},
+    ...body.clientTurnId ? { clientTurnId: body.clientTurnId } : {},
+    ...args.continueOnDisconnect ? { continueOnDisconnect: true } : {},
+    ...args.onResponseFinalized ? { onResponseFinalized: args.onResponseFinalized } : {},
+    ...args.abortSignal && !args.continueOnDisconnect ? { abortSignal: args.abortSignal } : {},
+    sessionId: body.sessionId,
+    workflowId: body.workflowId,
+    context: body.context
+  });
+  if (body.stream === false) {
+    const buffered = await (0, import_stream2.collectBufferedStream)(stream);
+    return new Response(JSON.stringify(buffered), {
+      headers: {
+        "content-type": "application/json"
+      }
+    });
+  }
+  return (0, import_stream2.toSSE)(stream);
+}
+function createChatRouteHandler(args) {
+  const { agent, errorStatus } = args;
+  if (args.disconnect === "continue" && !args.onExecution) {
+    throw new Error(
+      'disconnect: "continue" requires onExecution to retain host lifetime.'
+    );
+  }
+  return async function POST(request) {
+    try {
+      const body = parseChatRequestBody(await readRequestJson(request));
+      if (args.onTurnAccepted || args.onResponseFinalized) {
+        if (!body.sessionId || !body.clientTurnId) {
+          throw new import_errors5.KortyxError(
+            "INVALID_REQUEST",
+            "sessionId and clientTurnId are required with chat lifecycle hooks.",
+            {
+              category: "request",
+              retryable: false,
+              safeMessage: "This chat request needs a session and turn ID."
+            }
+          );
+        }
+        const userMessage = body.messages.at(-1);
+        if (!userMessage || userMessage.role !== "user") {
+          throw new import_errors5.KortyxError(
+            "INVALID_REQUEST",
+            "The last chat message must be from the user.",
+            {
+              category: "request",
+              retryable: false,
+              safeMessage: "The chat request needs a user message."
+            }
+          );
+        }
+        if (args.onTurnAccepted) {
+          try {
+            await args.onTurnAccepted({
+              request,
+              sessionId: body.sessionId,
+              clientTurnId: body.clientTurnId,
+              userMessage: { ...userMessage, role: "user" },
+              kind: parseResumeMeta(userMessage) ? "interrupt-response" : "prompt"
+            });
+          } catch (cause) {
+            const error = new ChatLifecycleHookError("turn-accepted", cause);
+            await reportLifecycleError(args.onLifecycleError, {
+              phase: "turn-accepted",
+              clientTurnId: body.clientTurnId,
+              error
+            });
+            throw error;
+          }
+        }
+      }
+      return await handleChatRequestBody({
+        agent,
+        body,
+        abortSignal: request.signal,
+        onExecution: args.onExecution,
+        continueOnDisconnect: args.disconnect === "continue",
+        ...args.onResponseFinalized ? {
+          onResponseFinalized: async (event) => {
+            try {
+              await args.onResponseFinalized?.({ ...event, request });
+            } catch (cause) {
+              await reportLifecycleError(args.onLifecycleError, {
+                phase: "response-finalized",
+                clientTurnId: event.clientTurnId,
+                error: new ChatLifecycleHookError(
+                  "response-finalized",
+                  cause
+                )
+              });
+            }
+          }
+        } : {}
+      });
+    } catch (error) {
+      return createFailureResponse(error, errorStatus);
+    }
+  };
+}
+async function handleCheckpointRequestBody(args) {
+  const { agent, body } = args;
+  const result = body.action === "list" ? await agent.listCheckpoints(body.sessionId) : body.action === "get" ? await agent.getCheckpoint(body.checkpointId) : body.action === "rollback" ? await agent.rollbackTo(body.checkpointId) : await agent.fork(body.checkpointId, {
+    ...body.newSessionId ? { newSessionId: body.newSessionId } : {}
+  });
+  if (args.request && body.action === "fork" && args.onForked) {
+    const fork = result;
+    try {
+      await args.onForked({
+        request: args.request,
+        sourceSessionId: fork.parentSessionId,
+        newSessionId: fork.sessionId,
+        sourceCheckpointId: fork.forkedFrom,
+        newCheckpointId: fork.checkpoint.id
+      });
+    } catch (cause) {
+      await reportLifecycleError(args.onLifecycleError, {
+        phase: "forked",
+        error: new ChatLifecycleHookError("forked", cause)
+      });
+    }
+  }
+  if (args.request && body.action === "rollback" && args.onRolledBack) {
+    const rollback = result;
+    try {
+      await args.onRolledBack({
+        request: args.request,
+        sessionId: rollback.sessionId,
+        headCheckpointId: rollback.head,
+        invalidatedStructuredStreamIds: rollback.invalidatedStructuredStreamIds
+      });
+    } catch (cause) {
+      await reportLifecycleError(args.onLifecycleError, {
+        phase: "rolled-back",
+        error: new ChatLifecycleHookError("rolled-back", cause)
+      });
+    }
+  }
+  return new Response(JSON.stringify(result), {
+    headers: {
+      "content-type": "application/json"
+    }
+  });
+}
+function createCheckpointRouteHandler(args) {
+  const { agent, errorStatus } = args;
+  return async function POST(request) {
+    try {
+      const body = parseCheckpointRequestBody(await readRequestJson(request));
+      return await handleCheckpointRequestBody({
+        agent,
+        body,
+        request,
+        onForked: args.onForked,
+        onRolledBack: args.onRolledBack,
+        onLifecycleError: args.onLifecycleError
+      });
+    } catch (error) {
+      return createFailureResponse(error, errorStatus);
+    }
+  };
+}
+
+// src/adapters/http-client.ts
+var import_browser = require("@kortyx/stream/browser");
+async function* streamChatFromRoute(args) {
+  yield* (0, import_browser.streamFromRoute)({
+    endpoint: args.endpoint,
+    ...args.fetchImpl ? { fetchImpl: args.fetchImpl } : {},
+    ...args.headers ? { headers: args.headers } : {},
+    body: {
+      sessionId: args.sessionId,
+      clientTurnId: args.clientTurnId,
+      workflowId: args.workflowId,
+      messages: args.messages
+    }
+  });
+}
+
+// src/chat/create-agent.ts
+var import_node_path = require("path");
+var import_core5 = require("@kortyx/core");
+var import_providers = require("@kortyx/providers");
+var import_runtime5 = require("@kortyx/runtime");
+var import_zod5 = require("zod");
+
 // src/execution/execute.ts
+var import_core4 = require("@kortyx/core");
+var import_errors6 = require("@kortyx/core/errors");
+var import_runtime3 = require("@kortyx/runtime");
+var import_zod3 = require("zod");
 var handleSchema = import_zod3.z.object({
   token: import_zod3.z.string().min(1),
   requestId: import_zod3.z.string().min(1),
@@ -6557,7 +7201,7 @@ function resultFromOutcome(outcome, runId, sessionId) {
     return {
       ...info,
       status: "failed",
-      error: (0, import_errors5.serializeFailure)(error)
+      error: (0, import_errors6.serializeFailure)(error)
     };
   }
   if (outcome.cancelled)
@@ -6738,7 +7382,7 @@ async function resumeWorkflow(services, args) {
         );
     }).catch(
       (error) => reject(
-        error instanceof Error ? error : new import_errors5.KortyxError("RESUME_FAILED", "Resume failed.", {
+        error instanceof Error ? error : new import_errors6.KortyxError("RESUME_FAILED", "Resume failed.", {
           category: "persistence",
           cause: error,
           safeMessage: "The saved execution could not be resumed."
@@ -6941,6 +7585,7 @@ function restoreWorkflowCallBranch(requests, telemetry, sourceRunId) {
 }
 
 // src/chat/process-chat.ts
+var import_errors7 = require("@kortyx/core/errors");
 var import_runtime4 = require("@kortyx/runtime");
 
 // src/utils/extract-latest-message.ts
@@ -6961,6 +7606,9 @@ async function streamChat({
   abortSignal,
   executionSignal,
   onExecution,
+  clientTurnId,
+  continueOnDisconnect,
+  onResponseFinalized,
   options,
   sessionId,
   defaultWorkflowId,
@@ -6972,6 +7620,18 @@ async function streamChat({
   getProvider,
   applyResumeSelection
 }) {
+  const suppliedSessionId = sessionId || options?.sessionId;
+  if (onResponseFinalized && (!suppliedSessionId || !clientTurnId?.trim() || clientTurnId.length > 128)) {
+    throw new import_errors7.KortyxError(
+      "INVALID_REQUEST",
+      "sessionId and clientTurnId are required with onResponseFinalized.",
+      {
+        category: "request",
+        retryable: false,
+        safeMessage: "This chat request needs a session and turn ID."
+      }
+    );
+  }
   const config = await loadRuntimeConfig(options);
   let runtimeConfig2 = {
     ...config,
@@ -7010,6 +7670,9 @@ async function streamChat({
     abortSignal,
     executionSignal,
     onExecution,
+    clientTurnId,
+    continueOnDisconnect,
+    onResponseFinalized,
     lastMessage: last,
     sessionId: resolvedSessionId,
     config: runtimeConfig2,
@@ -7083,6 +7746,9 @@ async function streamChat({
     abortSignal,
     executionSignal,
     onExecution,
+    clientTurnId,
+    continueOnDisconnect,
+    onResponseFinalized,
     sessionId: resolvedSessionId,
     runId,
     graph,
@@ -7101,6 +7767,9 @@ var agentProcessOptionsSchema = import_zod5.z.object({
   onExecution: import_zod5.z.custom(
     (value) => typeof value === "function"
   ).optional(),
+  clientTurnId: import_zod5.z.string().min(1).max(128).optional(),
+  continueOnDisconnect: import_zod5.z.boolean().optional(),
+  onResponseFinalized: import_zod5.z.custom((value) => typeof value === "function").optional(),
   limits: import_core5.ExecutionLimitsSchema.optional(),
   abortSignal: import_zod5.z.custom((value) => value instanceof AbortSignal).optional(),
   sessionId: import_zod5.z.string().optional(),
@@ -7247,6 +7916,9 @@ function createAgent(args) {
       abortSignal: parsedOptions?.abortSignal,
       executionSignal: parsedOptions?.executionSignal,
       onExecution: parsedOptions?.onExecution,
+      clientTurnId: parsedOptions?.clientTurnId,
+      continueOnDisconnect: parsedOptions?.continueOnDisconnect,
+      onResponseFinalized: parsedOptions?.onResponseFinalized,
       options: parsedOptions,
       workflowRegistry: registry,
       ...knownWorkflowIds ? { knownWorkflowIds } : {},
@@ -7403,6 +8075,7 @@ function createAgent(args) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ChatLifecycleHookError,
   ExecutionRequestError,
   createAgent,
   createChatRouteHandler,