@kortyx/hooks 0.21.0 → 0.23.0

package/dist/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   WorkflowCallError: () => WorkflowCallError,
+  completeResponse: () => completeResponse,
   createWorkflowHooks: () => createWorkflowHooks,
   emitWorkflowCall: () => emitWorkflowCall,
   runWithHookContext: () => runWithHookContext,
@@ -35,6 +36,9 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/complete-response.ts
+var import_zod = require("zod");
+
 // src/context.ts
 var import_node_async_hooks = require("async_hooks");
 var storage = new import_node_async_hooks.AsyncLocalStorage();
@@ -125,7 +129,7 @@ var toTokenUsageDelta = (usage) => {
   if (!usage) return void 0;
   const input = usage.input ?? 0;
   const output = usage.output ?? 0;
-  const total = usage.total ?? input + output + (usage.reasoning ?? 0);
+  const total = usage.total ?? input + output + (usage.outputIncludesReasoning ? 0 : usage.reasoning ?? 0);
   if (input === 0 && output === 0 && total === 0) {
     return void 0;
   }
@@ -188,6 +192,30 @@ function getHookContext() {
   }
   return ctx;
 }
+function snapshotHookState() {
+  const ctx = getHookContext();
+  return {
+    ...ctx.state,
+    lastNode: ctx.node.graph.node,
+    runtime: { ...ctx.state.runtime, ...buildRuntimeStateUpdates(ctx) }
+  };
+}
+
+// src/complete-response.ts
+var optionsSchema = import_zod.z.object({
+  message: import_zod.z.string().optional(),
+  data: import_zod.z.json().optional()
+}).strict();
+async function completeResponse(options = {}) {
+  const ctx = getHookContext();
+  const parsed = optionsSchema.parse(options);
+  if (!ctx.node.completeResponse) {
+    throw new Error(
+      "completeResponse requires an agent-managed root workflow."
+    );
+  }
+  await ctx.node.completeResponse(parsed, snapshotHookState());
+}
 
 // src/interrupt.ts
 var import_core = require("@kortyx/core");
@@ -399,7 +427,7 @@ var emitNodeEvent = (emitEvent, nodeId, event, payload) => {
   });
 };
 async function runReasonEngine(args) {
-  const stream = args.stream ?? args.model.options?.streaming ?? true;
+  let stream = args.stream ?? args.model.options?.streaming ?? true;
   const emit = args.emit ?? true;
   const temperature = args.temperature ?? args.model.options?.temperature ?? args.defaultTemperature;
   const maxOutputTokens = args.maxOutputTokens ?? args.model.options?.maxOutputTokens;
@@ -407,7 +435,14 @@ async function runReasonEngine(args) {
   const abortSignal = args.abortSignal ?? args.model.options?.abortSignal;
   const reasoning = args.reasoning ?? args.model.options?.reasoning;
   const responseFormat = args.responseFormat ?? args.model.options?.responseFormat;
-  const providerOptions = args.providerOptions ?? args.model.options?.providerOptions;
+  const defaults = args.model.options?.providerOptions;
+  const providerOptions = defaults || args.providerOptions ? { ...defaults, ...args.providerOptions } : void 0;
+  for (const [key, value] of Object.entries(args.providerOptions ?? {})) {
+    const previous = defaults?.[key];
+    if (previous && value && typeof previous === "object" && typeof value === "object" && !Array.isArray(previous) && !Array.isArray(value)) {
+      if (providerOptions) providerOptions[key] = { ...previous, ...value };
+    }
+  }
   const tools = args.tools ?? args.model.options?.tools;
   (0, import_core2.throwIfExecutionAborted)(abortSignal);
   const model = args.model.provider.getModel(args.model.modelId, {
@@ -421,6 +456,7 @@ async function runReasonEngine(args) {
     ...tools !== void 0 ? { tools } : {},
     ...providerOptions !== void 0 ? { providerOptions } : {}
   });
+  if (tools?.length && !model.supportsToolStreaming) stream = false;
   const messages = args.messages !== void 0 ? args.messages : [
     ...typeof args.system === "string" && args.system.length > 0 ? [{ role: "system", content: args.system }] : [],
     { role: "user", content: String(args.input ?? "") }
@@ -448,7 +484,9 @@ async function runReasonEngine(args) {
     },
     telemetry: {
       ...args.telemetry ?? {},
-      input: args.telemetry?.input ?? messages
+      input: args.telemetry?.input ?? messages.map(
+        ({ continuation: _continuation, raw: _raw, ...message }) => message
+      )
     }
   });
   const modelRequestStartedAt = Date.now();
@@ -479,7 +517,11 @@ async function runReasonEngine(args) {
     });
   };
   const failTrace = (span, error) => {
+    const detail = error;
     span?.fail?.(error, {
+      ...detail?.usage ? { usage: detail.usage } : {},
+      ...detail?.finishReason ? { finishReason: detail.finishReason } : {},
+      ...detail?.providerMetadata ? { providerMetadata: detail.providerMetadata } : {},
       attributes: {
         providerId: args.model.provider.id,
         modelId: args.model.modelId
@@ -488,6 +530,7 @@ async function runReasonEngine(args) {
   };
   try {
     if (stream) {
+      let continuation;
       let final = "";
       let raw;
       let usage;
@@ -526,6 +569,7 @@ async function runReasonEngine(args) {
             break;
           }
           case "finish": {
+            continuation = chunk.continuation;
             if (chunk.raw !== void 0) {
               raw = chunk.raw;
             }
@@ -574,6 +618,7 @@ async function runReasonEngine(args) {
       }
       const result2 = {
         text: final,
+        ...continuation ? { continuation } : {},
         ...raw !== void 0 ? { raw } : {},
         ...usage !== void 0 ? { usage } : {},
         ...finishReason !== void 0 ? { finishReason } : {},
@@ -587,6 +632,7 @@ async function runReasonEngine(args) {
     }
     const response = await model.invoke(messages);
     (0, import_core2.throwIfExecutionAborted)(abortSignal);
+    if (response.content) args.onTextChunk?.(response.content);
     if (emit) {
       emitNodeEvent(args.emitEvent, args.nodeId, "text-start", {
         ...commonMeta
@@ -603,6 +649,7 @@ async function runReasonEngine(args) {
     }
     const result = {
       text: response.content,
+      ...response.continuation ? { continuation: response.continuation } : {},
       ...response.raw !== void 0 ? { raw: response.raw } : {},
       ...response.usage !== void 0 ? { usage: response.usage } : {},
       ...response.finishReason !== void 0 ? { finishReason: response.finishReason } : {},
@@ -636,480 +683,188 @@ async function reasonEngine(args, meta, inputOverride) {
   );
   (0, import_core3.throwIfExecutionAborted)(abortSignal);
   ctx.node.consumeExecution?.("maxModelPasses");
-  return runReasonEngine({
-    model: args.model,
-    input: inputOverride ?? args.input,
-    system: args.system,
-    temperature: args.temperature,
-    maxOutputTokens: args.maxOutputTokens,
-    stopSequences: args.stopSequences,
-    abortSignal,
-    reasoning: args.reasoning,
-    responseFormat: args.responseFormat,
-    providerOptions: args.providerOptions,
-    tools: args.tools,
-    messages: args.messages,
-    defaultTemperature: ctx.node.config?.model?.temperature,
-    stream: args.stream,
-    emit: args.emit,
-    onTextChunk: args.onTextChunk,
-    telemetry: args.telemetry,
-    nodeId: ctx.node.graph.node,
-    emitEvent: ctx.node.emit,
-    reasonTrace: ctx.reasonTrace,
-    id: meta.id,
-    opId: meta.opId
-  });
+  try {
+    return await runReasonEngine({
+      model: args.model,
+      input: inputOverride ?? args.input,
+      system: args.system,
+      temperature: args.temperature,
+      maxOutputTokens: args.maxOutputTokens,
+      stopSequences: args.stopSequences,
+      abortSignal,
+      reasoning: args.reasoning,
+      responseFormat: args.responseFormat,
+      providerOptions: args.providerOptions,
+      tools: args.tools,
+      messages: args.messages,
+      defaultTemperature: ctx.node.config?.model?.temperature,
+      stream: args.stream,
+      emit: args.emit,
+      onTextChunk: args.onTextChunk,
+      telemetry: args.telemetry,
+      nodeId: ctx.node.graph.node,
+      emitEvent: ctx.node.emit,
+      reasonTrace: ctx.reasonTrace,
+      id: meta.id,
+      opId: meta.opId
+    });
+  } catch (error) {
+    const usage = error?.usage;
+    if (usage) accumulateTokenUsage(usage);
+    throw error;
+  }
 }
 
-// src/reason/parsing.ts
-var tryJsonParse = (value) => {
+// src/reason/output-format.ts
+var import_zod2 = require("zod");
+function inferOutputFormat(schema, explicit) {
+  if (explicit) return { responseFormat: explicit };
+  if (!schema) return {};
   try {
-    return { ok: true, value: JSON.parse(value) };
-  } catch (error) {
+    const json = (0, import_zod2.toJSONSchema)(schema);
+    const clean = (value) => {
+      if (Array.isArray(value)) return value.map(clean);
+      if (!value || typeof value !== "object") return value;
+      const object = value;
+      if ([
+        "allOf",
+        "not",
+        "dependentRequired",
+        "dependentSchemas",
+        "if",
+        "then",
+        "else",
+        "prefixItems"
+      ].some((key) => key in object))
+        throw new Error(
+          "Schema composition requires an explicit provider schema"
+        );
+      if (object.type === "object") {
+        if (object.additionalProperties !== false)
+          throw new Error(
+            "Dynamic properties require an explicit provider schema"
+          );
+        const properties = object.properties;
+        const required = object.required;
+        if (properties && Object.keys(properties).some((key) => !required?.includes(key))) {
+          throw new Error(
+            "Optional properties require an explicit provider schema"
+          );
+        }
+      }
+      return Object.fromEntries(
+        Object.entries(object).filter(([key]) => key !== "$schema" && key !== "default").map(([key, child]) => {
+          if ((key === "properties" || key === "$defs" || key === "definitions") && child && typeof child === "object")
+            return [
+              key,
+              Object.fromEntries(
+                Object.entries(child).map(([name, definition]) => [
+                  name,
+                  clean(definition)
+                ])
+              )
+            ];
+          return [
+            key,
+            key === "enum" || key === "const" ? child : clean(child)
+          ];
+        })
+      );
+    };
+    if (json.type !== "object")
+      throw new Error("The provider schema must have an object root");
+    return { responseFormat: { type: "json", schema: clean(json) } };
+  } catch {
     return {
-      ok: false,
-      error: error instanceof Error ? error.message : String(error)
+      responseFormat: { type: "json" },
+      warnings: [
+        {
+          type: "compatibility",
+          feature: "outputSchema",
+          details: "This validator cannot be inferred as a strict provider JSON schema. Kortyx still validates the final output locally. Supply responseFormat.schema to enforce a wire schema."
+        }
+      ]
     };
   }
-};
-var extractJsonCodeBlock = (value) => {
-  const match = value.match(/```(?:json)?\s*([\s\S]*?)```/i);
-  if (!match || typeof match[1] !== "string") return null;
-  const inner = match[1].trim();
-  return inner.length > 0 ? inner : null;
-};
-var tryStringify = (value) => {
-  if (typeof value === "string") return value;
-  try {
-    return JSON.stringify(value, null, 2);
-  } catch {
-    return String(value);
+}
+
+// src/reason/structured-stream.ts
+var resolveAppendFieldPaths = (cfg) => {
+  const fields = cfg?.fields;
+  if (!fields) return [];
+  const appendPaths = Object.entries(fields).filter(([, mode]) => mode === "append").map(([path]) => path);
+  for (const path of appendPaths) {
+    assertStructuredPath(path, "useReason structured append");
   }
+  return appendPaths;
 };
-var isRecord2 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
-var resolveOutputCandidate = (text) => {
-  const trimmed = text.trim();
-  if (!trimmed) return text;
-  const direct = tryJsonParse(trimmed);
-  if (direct.ok) return direct.value;
-  const block = extractJsonCodeBlock(trimmed);
-  if (block) {
-    const parsedBlock = tryJsonParse(block);
-    if (parsedBlock.ok) return parsedBlock.value;
+var resolveSetFieldPaths = (cfg) => {
+  const fields = cfg?.fields;
+  if (!fields) return [];
+  const setPaths = Object.entries(fields).filter(([, mode]) => mode === "set").map(([path]) => path);
+  for (const path of setPaths) {
+    assertStructuredPath(path, "useReason structured set");
   }
-  return text;
-};
-var looksLikeStructuredJsonAttempt = (value) => {
-  const trimmed = value.trim();
-  if (!trimmed) return false;
-  return trimmed.startsWith("{") || trimmed.startsWith("[") || /^```(?:json)?/i.test(trimmed);
-};
-var isLikelyTruncatedStructuredOutput = (text) => {
-  const trimmed = text.trim();
-  if (!looksLikeStructuredJsonAttempt(trimmed)) return false;
-  const direct = tryJsonParse(trimmed);
-  if (!direct.ok && direct.error) return true;
-  const block = extractJsonCodeBlock(trimmed);
-  if (!block) return false;
-  const parsedBlock = tryJsonParse(block);
-  return !parsedBlock.ok && Boolean(parsedBlock.error);
+  return setPaths;
 };
-var createTruncatedStructuredOutputError = (label) => new Error(
-  `${label} was truncated before producing valid structured output. The model stopped due to output length. Increase maxOutputTokens or simplify the requested output.`
-);
-var createInvalidStructuredOutputError = (label) => new Error(
-  `${label} did not produce valid structured output. The model returned text instead of the expected JSON payload. This often happens when output is truncated or the provider does not follow JSON mode. Increase maxOutputTokens or simplify the requested output.`
-);
-var parseReasonOutputWithSchema = (args) => {
-  const candidate = resolveOutputCandidate(args.text);
-  try {
-    return parseWithSchema(args.schema, candidate, args.label);
-  } catch (error) {
-    if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
-      throw createTruncatedStructuredOutputError(args.label);
-    }
-    if (typeof candidate === "string" && candidate.trim().length > 0) {
-      throw createInvalidStructuredOutputError(args.label);
-    }
-    throw error;
+var resolveTextDeltaFieldPaths = (cfg) => {
+  const fields = cfg?.fields;
+  if (!fields) return [];
+  const textPaths = Object.entries(fields).filter(([, mode]) => mode === "text-delta").map(([path]) => path);
+  for (const path of textPaths) {
+    assertStructuredPath(path, "useReason structured text-delta");
   }
+  return textPaths;
 };
-var parseInterruptFirstPassResult = (args) => {
-  const candidate = resolveOutputCandidate(args.text);
-  if (!isRecord2(candidate)) {
-    if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
-      throw createTruncatedStructuredOutputError("useReason output");
+var extractCompletedStringValueAt = (args) => {
+  let value = "";
+  for (let i = args.start; i < args.text.length; i += 1) {
+    const ch = args.text[i];
+    if (ch === void 0) break;
+    if (ch === '"') {
+      return {
+        complete: true,
+        value
+      };
     }
-    if (typeof candidate === "string" && candidate.trim().length > 0) {
-      throw createInvalidStructuredOutputError("useReason output");
+    if (ch !== "\\") {
+      value += ch;
+      continue;
     }
-    throw new Error(
-      "useReason first pass with interrupt must return a JSON object."
-    );
-  }
-  const mode = args.mode ?? "required";
-  let interruptRequired = true;
-  if (mode === "optional") {
-    if (candidate.decision !== "continue" && candidate.decision !== "interrupt") {
-      throw new Error(
-        'useReason optional interrupt first pass must include decision "continue" or "interrupt".'
-      );
+    const next = args.text[i + 1];
+    if (!next) {
+      return {
+        complete: false
+      };
     }
-    interruptRequired = candidate.decision === "interrupt";
-    if (!interruptRequired) {
-      const hasUnexpectedRequest = [
-        candidate.interruptRequest,
-        candidate.request,
-        candidate.interrupt
-      ].some((value) => value !== null && value !== void 0);
-      if (hasUnexpectedRequest) {
-        throw new Error(
-          'useReason optional interrupt first pass with decision "continue" must not include an interrupt request.'
-        );
-      }
+    if (next === '"' || next === "\\" || next === "/" || next === "b" || next === "f" || next === "n" || next === "r" || next === "t") {
+      value += next === "b" ? "\b" : next === "f" ? "\f" : next === "n" ? "\n" : next === "r" ? "\r" : next === "t" ? "	" : next;
+      i += 1;
+      continue;
     }
-  }
-  let request;
-  if (interruptRequired) {
-    const requestCandidates = [
-      candidate.interruptRequest,
-      candidate.request,
-      candidate.interrupt,
-      mode === "required" ? candidate : void 0
-    ];
-    const requestPayload = requestCandidates.find(
-      (value) => value !== null && value !== void 0
-    );
-    request = parseWithSchema(
-      args.requestSchema,
-      requestPayload,
-      "useReason interrupt.request"
-    );
-  }
-  let output;
-  if (args.outputSchema) {
-    const outputPayload = Object.hasOwn(candidate, "output") ? candidate.output : candidate;
-    try {
-      output = parseWithSchema(
-        args.outputSchema,
-        outputPayload,
-        "useReason output"
-      );
-    } catch (error) {
-      if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
-        throw createTruncatedStructuredOutputError("useReason output");
-      }
-      if (typeof outputPayload === "string" && outputPayload.trim().length > 0) {
-        throw createInvalidStructuredOutputError("useReason output");
+    if (next === "u") {
+      const hex = args.text.slice(i + 2, i + 6);
+      if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+        return {
+          complete: false
+        };
       }
-      throw error;
+      value += String.fromCharCode(Number.parseInt(hex, 16));
+      i += 5;
+      continue;
     }
-  }
-  const explicitDraft = typeof candidate.draftText === "string" && candidate.draftText.length > 0 ? candidate.draftText : typeof candidate.text === "string" && candidate.text.length > 0 ? candidate.text : void 0;
-  if (!args.outputSchema && !explicitDraft) {
-    throw new Error(
-      "useReason first pass with interrupt requires `draftText` when outputSchema is not provided."
-    );
-  }
-  const draftText = explicitDraft ?? (output !== void 0 ? tryStringify(output) : String(args.text ?? ""));
-  if (!interruptRequired) {
     return {
-      draftText,
-      interruptRequired: false,
-      ...output !== void 0 ? { output } : {}
+      complete: false
     };
   }
   return {
-    draftText,
-    interruptRequired: true,
-    request,
-    ...output !== void 0 ? { output } : {}
+    complete: false
   };
 };
-
-// src/reason/prompting.ts
-var import_zod = require("zod");
-var tryStringify2 = (value) => {
-  if (typeof value === "string") return value;
-  try {
-    return JSON.stringify(value, null, 2);
-  } catch {
-    return String(value);
-  }
-};
-var tryGetSchemaHint = (schema) => {
-  try {
-    const hint = (0, import_zod.toJSONSchema)(schema);
-    return JSON.stringify(hint, null, 2);
-  } catch {
-    return void 0;
-  }
-};
-var withSchemaHint = (input, label, schema) => {
-  const hint = tryGetSchemaHint(schema);
-  if (!hint) return input;
-  return `${input}
-
-${label}:
-${hint}`;
-};
-var defaultInterruptFirstPassInput = (args) => {
-  const mode = args.mode ?? "required";
-  const base = mode === "optional" ? args.outputSchema ? [
-    args.input,
-    "Output rules:",
-    "- Return JSON only. No markdown fences.",
-    "- Return an object with keys: decision, output, interruptRequest, draftText.",
-    '- decision must be either "continue" or "interrupt".',
-    '- Use decision "continue" when you can produce the final output without asking the user.',
-    '- Use decision "interrupt" only when user input is needed before finalizing.',
-    "- output must match the expected output JSON schema.",
-    '- When decision is "interrupt", interruptRequest must match the expected interrupt request JSON schema and must be a non-null object.',
-    '- When decision is "continue", interruptRequest must be null.',
-    "- draftText should be a concise plain-language summary of output."
-  ].join("\n\n") : [
-    args.input,
-    "Output rules:",
-    "- Return JSON only. No markdown fences.",
-    "- Return an object with keys: decision, draftText, interruptRequest.",
-    '- decision must be either "continue" or "interrupt".',
-    '- Use decision "continue" when you can produce the final answer without asking the user.',
-    '- Use decision "interrupt" only when user input is needed before finalizing.',
-    "- draftText should be the current answer text.",
-    '- When decision is "interrupt", interruptRequest must match the expected interrupt request JSON schema and must be a non-null object.',
-    '- When decision is "continue", interruptRequest must be null.'
-  ].join("\n\n") : args.outputSchema ? [
-    args.input,
-    "Output rules:",
-    "- Return JSON only. No markdown fences.",
-    "- Return an object with keys: output, interruptRequest, draftText.",
-    "- output must match the expected output JSON schema.",
-    "- interruptRequest must match the expected interrupt request JSON schema.",
-    "- interruptRequest must be a non-null object.",
-    "- draftText should be a concise plain-language summary of output.",
-    "- If uncertain, still return a valid interruptRequest with safe default options."
-  ].join("\n\n") : [
-    args.input,
-    "Output rules:",
-    "- Return JSON only. No markdown fences.",
-    "- Return an object with keys: draftText, interruptRequest.",
-    "- draftText should be the current draft answer text.",
-    "- interruptRequest must match the expected interrupt request JSON schema.",
-    "- interruptRequest must be a non-null object.",
-    "- If uncertain, still return a valid interruptRequest with safe default options."
-  ].join("\n\n");
-  const withInterruptSchema = withSchemaHint(
-    base,
-    "Expected interrupt request JSON schema (for `interruptRequest`)",
-    args.requestSchema
-  );
-  if (!args.outputSchema) return withInterruptSchema;
-  const withOutputSchema = withSchemaHint(
-    withInterruptSchema,
-    "Expected output JSON schema (for `output`)",
-    args.outputSchema
-  );
-  return [
-    withOutputSchema,
-    "JSON template:",
-    mode === "optional" ? '{ "decision": "continue", "output": { ... }, "interruptRequest": null, "draftText": "..." }' : '{ "output": { ... }, "interruptRequest": { ... }, "draftText": "..." }'
-  ].join("\n\n");
-};
-var defaultContinuationInput = (args) => [
-  "You are continuing a paused reasoning task after user input.",
-  "Update the previous result using the user response and return the final answer only.",
-  "If the previous output was JSON, return JSON in the same schema.",
-  "",
-  `Original request:
-${args.input}`,
-  `Draft answer text:
-${args.draftText}`,
-  `Draft output object:
-${tryStringify2(args.draftOutput ?? args.draftText)}`,
-  `Interrupt request shown to user:
-${tryStringify2(args.request)}`,
-  `User response:
-${tryStringify2(args.response)}`
-].join("\n\n");
-var withOutputGuardrails = (input, schema) => {
-  const base = [
-    input,
-    "Output rules:",
-    "- Return only JSON, no markdown fences.",
-    "- Ensure the response conforms to the expected output schema.",
-    "- Do not include explanatory text outside the JSON object."
-  ].join("\n\n");
-  return withSchemaHint(base, "Expected output JSON schema", schema);
-};
-var withStructuredStreamHints = (input, args) => {
-  const rules = [];
-  for (const path of args.setFieldPaths ?? []) {
-    rules.push(
-      `- For the field path pattern \`${path}\`, write one stable final value and do not rewrite it after it is complete.`
-    );
-  }
-  for (const path of args.appendFieldPaths ?? []) {
-    rules.push(
-      `- For the array field path pattern \`${path}\`, write items in final order and finish each item before starting the next.`
-    );
-    rules.push(
-      `- Once an item in \`${path}\` is complete, do not rewrite or reorder earlier items.`
-    );
-  }
-  for (const path of args.textDeltaFieldPaths ?? []) {
-    rules.push(
-      `- For the string field path pattern \`${path}\`, write the value progressively by appending text to the end.`
-    );
-    rules.push(
-      `- Do not rewrite or replace the earlier prefix of \`${path}\` once emitted.`
-    );
-  }
-  if (rules.length === 0) return input;
-  return [
-    input,
-    "Streaming rules:",
-    ...rules,
-    "- Keep the overall response as valid JSON."
-  ].join("\n\n");
-};
-
-// src/reason/result.ts
-var mergeUsage = (left, right) => {
-  if (!left) return right;
-  if (!right) return left;
-  const sum = (a, b) => a === void 0 && b === void 0 ? void 0 : (a ?? 0) + (b ?? 0);
-  const raw = left.raw || right.raw ? {
-    ...left.raw ?? {},
-    ...right.raw ?? {}
-  } : void 0;
-  const input = sum(left.input, right.input);
-  const output = sum(left.output, right.output);
-  const total = sum(left.total, right.total);
-  const reasoning = sum(left.reasoning, right.reasoning);
-  const cacheRead = sum(left.cacheRead, right.cacheRead);
-  const cacheWrite = sum(left.cacheWrite, right.cacheWrite);
-  const merged = {};
-  if (input !== void 0) merged.input = input;
-  if (output !== void 0) merged.output = output;
-  if (total !== void 0) merged.total = total;
-  if (reasoning !== void 0) merged.reasoning = reasoning;
-  if (cacheRead !== void 0) merged.cacheRead = cacheRead;
-  if (cacheWrite !== void 0) merged.cacheWrite = cacheWrite;
-  if (raw) merged.raw = raw;
-  return merged;
-};
-var mergeWarnings = (left, right) => {
-  if (!left?.length) return right;
-  if (!right?.length) return left;
-  const seen = /* @__PURE__ */ new Set();
-  const merged = [];
-  for (const warning of [...left, ...right]) {
-    const key = JSON.stringify(warning);
-    if (seen.has(key)) continue;
-    seen.add(key);
-    merged.push(warning);
-  }
-  return merged;
-};
-var mergeProviderMetadata = (left, right) => {
-  if (!left) return right;
-  if (!right) return left;
-  return {
-    ...left,
-    ...right
-  };
-};
-var emitReasonStructuredOutput = (args) => {
-  if (!args.emit || !shouldEmitStructured(args.structured)) return;
-  emitStructuredData({
-    dataType: args.structured?.dataType ?? "reason-output",
-    data: args.output,
-    kind: "final",
-    ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
-    ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
-    ...args.id ? { id: args.id } : {},
-    streamId: args.opId
-  });
-};
-
-// src/reason/structured-stream.ts
-var resolveAppendFieldPaths = (cfg) => {
-  const fields = cfg?.fields;
-  if (!fields) return [];
-  const appendPaths = Object.entries(fields).filter(([, mode]) => mode === "append").map(([path]) => path);
-  for (const path of appendPaths) {
-    assertStructuredPath(path, "useReason structured append");
-  }
-  return appendPaths;
-};
-var resolveSetFieldPaths = (cfg) => {
-  const fields = cfg?.fields;
-  if (!fields) return [];
-  const setPaths = Object.entries(fields).filter(([, mode]) => mode === "set").map(([path]) => path);
-  for (const path of setPaths) {
-    assertStructuredPath(path, "useReason structured set");
-  }
-  return setPaths;
-};
-var resolveTextDeltaFieldPaths = (cfg) => {
-  const fields = cfg?.fields;
-  if (!fields) return [];
-  const textPaths = Object.entries(fields).filter(([, mode]) => mode === "text-delta").map(([path]) => path);
-  for (const path of textPaths) {
-    assertStructuredPath(path, "useReason structured text-delta");
-  }
-  return textPaths;
-};
-var extractCompletedStringValueAt = (args) => {
-  let value = "";
-  for (let i = args.start; i < args.text.length; i += 1) {
-    const ch = args.text[i];
-    if (ch === void 0) break;
-    if (ch === '"') {
-      return {
-        complete: true,
-        value
-      };
-    }
-    if (ch !== "\\") {
-      value += ch;
-      continue;
-    }
-    const next = args.text[i + 1];
-    if (!next) {
-      return {
-        complete: false
-      };
-    }
-    if (next === '"' || next === "\\" || next === "/" || next === "b" || next === "f" || next === "n" || next === "r" || next === "t") {
-      value += next === "b" ? "\b" : next === "f" ? "\f" : next === "n" ? "\n" : next === "r" ? "\r" : next === "t" ? "	" : next;
-      i += 1;
-      continue;
-    }
-    if (next === "u") {
-      const hex = args.text.slice(i + 2, i + 6);
-      if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
-        return {
-          complete: false
-        };
-      }
-      value += String.fromCharCode(Number.parseInt(hex, 16));
-      i += 5;
-      continue;
-    }
-    return {
-      complete: false
-    };
-  }
-  return {
-    complete: false
-  };
-};
-var skipWhitespace = (text, start) => {
-  let i = start;
-  while (i < text.length && /\s/.test(text[i] ?? "")) i += 1;
-  return i;
+var skipWhitespace = (text, start) => {
+  let i = start;
+  while (i < text.length && /\s/.test(text[i] ?? "")) i += 1;
+  return i;
 };
 var pathSegmentMatches = (patternPart, actualPart) => patternPart === "*" || patternPart === actualPart;
 var pathMatchesPattern = (actualParts, patternParts) => actualParts.length === patternParts.length && actualParts.every(
@@ -1357,13 +1112,86 @@ var extractCompletedValueAt = (args) => {
       return { complete: false };
     }
   }
-  return { complete: false };
+  return { complete: false };
+};
+var extractCompletedNestedValueAt = (args) => {
+  let inString = false;
+  let isEscaped = false;
+  let nesting = 0;
+  for (let i = args.start; i < args.text.length; i += 1) {
+    const ch = args.text[i];
+    if (ch === void 0) break;
+    if (inString) {
+      if (isEscaped) {
+        isEscaped = false;
+        continue;
+      }
+      if (ch === "\\") {
+        isEscaped = true;
+        continue;
+      }
+      if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+    if (ch === args.opener) {
+      nesting += 1;
+      continue;
+    }
+    if (ch === args.closer) {
+      nesting -= 1;
+      if (nesting === 0) {
+        const raw = args.text.slice(args.start, i + 1);
+        try {
+          return {
+            complete: true,
+            value: JSON.parse(raw)
+          };
+        } catch {
+          return {
+            complete: false
+          };
+        }
+      }
+    }
+  }
+  return {
+    complete: false
+  };
 };
-var extractCompletedNestedValueAt = (args) => {
+var extractCompletedFieldValues = (args) => {
+  const located = locateValueStarts(args);
+  const values = [];
+  for (const match of located) {
+    const parsed = extractCompletedValueAt({
+      text: args.text,
+      start: match.start
+    });
+    if (!parsed.complete) continue;
+    values.push({
+      path: match.path,
+      value: parsed.value
+    });
+  }
+  return values;
+};
+var extractCompletedArrayItems = (args) => {
+  const located = locateValueStart(args);
+  if (!located.found || located.start === void 0) return [];
+  const arrayStart = skipWhitespace(args.text, located.start);
+  if (args.text[arrayStart] !== "[") return [];
+  const start = arrayStart + 1;
+  const items = [];
   let inString = false;
   let isEscaped = false;
   let nesting = 0;
-  for (let i = args.start; i < args.text.length; i += 1) {
+  let itemStart = -1;
+  for (let i = start; i < args.text.length; i += 1) {
     const ch = args.text[i];
     if (ch === void 0) break;
     if (inString) {
@@ -1382,214 +1210,598 @@ var extractCompletedNestedValueAt = (args) => {
     }
     if (ch === '"') {
       inString = true;
+      if (itemStart < 0) itemStart = i;
       continue;
     }
-    if (ch === args.opener) {
+    if (itemStart < 0) {
+      if (/\s/.test(ch) || ch === ",") continue;
+      if (ch === "]") break;
+      itemStart = i;
+      if (ch === "{" || ch === "[") {
+        nesting = 1;
+      } else {
+        nesting = 0;
+      }
+      continue;
+    }
+    if (ch === "{" || ch === "[") {
       nesting += 1;
       continue;
     }
-    if (ch === args.closer) {
-      nesting -= 1;
-      if (nesting === 0) {
-        const raw = args.text.slice(args.start, i + 1);
-        try {
-          return {
-            complete: true,
-            value: JSON.parse(raw)
-          };
-        } catch {
-          return {
-            complete: false
-          };
-        }
-      }
+    if (ch === "}" || ch === "]") {
+      if (nesting > 0) {
+        nesting -= 1;
+        continue;
+      }
+    }
+    if (nesting === 0 && (ch === "," || ch === "]")) {
+      const raw = args.text.slice(itemStart, i).trim();
+      if (raw) {
+        try {
+          items.push(JSON.parse(raw));
+        } catch {
+        }
+      }
+      itemStart = -1;
+      if (ch === "]") break;
+    }
+  }
+  return items;
+};
+var extractCompletedArrayItemGroups = (args) => {
+  return locateValueStarts(args).flatMap((match) => {
+    const items = extractCompletedArrayItems({
+      text: args.text,
+      path: match.path
+    });
+    return items.length > 0 ? [
+      {
+        path: match.path,
+        items
+      }
+    ] : [];
+  });
+};
+var extractStreamingStringValue = (args) => {
+  const located = locateValueStart(args);
+  if (!located.found || located.start === void 0) {
+    return {
+      found: located.found,
+      complete: false,
+      value: ""
+    };
+  }
+  const stringStart = skipWhitespace(args.text, located.start);
+  if (args.text[stringStart] !== '"') {
+    return {
+      found: true,
+      complete: false,
+      value: ""
+    };
+  }
+  let value = "";
+  for (let i = stringStart + 1; i < args.text.length; i += 1) {
+    const ch = args.text[i];
+    if (ch === void 0) break;
+    if (ch === '"') {
+      return {
+        found: true,
+        complete: true,
+        value
+      };
+    }
+    if (ch !== "\\") {
+      value += ch;
+      continue;
+    }
+    const next = args.text[i + 1];
+    if (!next) {
+      return {
+        found: true,
+        complete: false,
+        value
+      };
+    }
+    if (next === '"' || next === "\\" || next === "/" || next === "b" || next === "f" || next === "n" || next === "r" || next === "t") {
+      value += next === "b" ? "\b" : next === "f" ? "\f" : next === "n" ? "\n" : next === "r" ? "\r" : next === "t" ? "	" : next;
+      i += 1;
+      continue;
+    }
+    if (next === "u") {
+      const hex = args.text.slice(i + 2, i + 6);
+      if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+        return {
+          found: true,
+          complete: false,
+          value
+        };
+      }
+      value += String.fromCharCode(Number.parseInt(hex, 16));
+      i += 5;
+      continue;
+    }
+    return {
+      found: true,
+      complete: false,
+      value
+    };
+  }
+  return {
+    found: true,
+    complete: false,
+    value
+  };
+};
+var extractStreamingStringValues = (args) => {
+  return locateValueStarts(args).flatMap((match) => {
+    const current = extractStreamingStringValue({
+      text: args.text,
+      path: match.path
+    });
+    return current.found ? [
+      {
+        path: match.path,
+        complete: current.complete,
+        value: current.value
+      }
+    ] : [];
+  });
+};
+
+// src/reason/output-stream.ts
+function createStructuredOutputStreamer(args, id, opId) {
+  let firstText = "";
+  const setFieldPaths = resolveSetFieldPaths(args.structured);
+  const appendFieldPaths = resolveAppendFieldPaths(args.structured);
+  const textDeltaFieldPaths = resolveTextDeltaFieldPaths(args.structured);
+  const emittedSetValues = /* @__PURE__ */ new Map();
+  const emittedAppendCounts = /* @__PURE__ */ new Map();
+  const emittedTextValues = /* @__PURE__ */ new Map();
+  return (delta) => {
+    firstText += delta;
+    for (const fieldPath of setFieldPaths) {
+      const values = extractCompletedFieldValues({
+        text: firstText,
+        path: fieldPath
+      });
+      for (const { path, value } of values) {
+        const nextSerialized = JSON.stringify(value);
+        if (emittedSetValues.get(path) === nextSerialized) continue;
+        emittedSetValues.set(path, nextSerialized);
+        emitStructuredData({
+          kind: "set",
+          path,
+          value,
+          dataType: args.structured?.dataType ?? "reason-output",
+          ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+          ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+          ...id ? { id } : {},
+          streamId: opId
+        });
+      }
+    }
+    for (const fieldPath of appendFieldPaths) {
+      const groups = extractCompletedArrayItemGroups({
+        text: firstText,
+        path: fieldPath
+      });
+      for (const { path, items } of groups) {
+        const emittedAppendCount = emittedAppendCounts.get(path) ?? 0;
+        if (items.length <= emittedAppendCount) continue;
+        const nextItems = items.slice(emittedAppendCount);
+        emittedAppendCounts.set(path, items.length);
+        emitStructuredData({
+          kind: "append",
+          path,
+          items: nextItems,
+          dataType: args.structured?.dataType ?? "reason-output",
+          ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+          ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+          ...id ? { id } : {},
+          streamId: opId
+        });
+      }
+    }
+    for (const fieldPath of textDeltaFieldPaths) {
+      const values = extractStreamingStringValues({
+        text: firstText,
+        path: fieldPath
+      });
+      for (const { path, value } of values) {
+        const emittedTextValue = emittedTextValues.get(path) ?? "";
+        if (value.length <= emittedTextValue.length || !value.startsWith(emittedTextValue)) {
+          continue;
+        }
+        const nextDelta = value.slice(emittedTextValue.length);
+        emittedTextValues.set(path, value);
+        if (nextDelta.length === 0) continue;
+        emitStructuredData({
+          kind: "text-delta",
+          path,
+          delta: nextDelta,
+          dataType: args.structured?.dataType ?? "reason-output",
+          ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+          ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+          ...id ? { id } : {},
+          streamId: opId
+        });
+      }
+    }
+  };
+}
+
+// src/reason/parsing.ts
+var tryJsonParse = (value) => {
+  try {
+    return { ok: true, value: JSON.parse(value) };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+};
+var extractJsonCodeBlock = (value) => {
+  const match = value.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (!match || typeof match[1] !== "string") return null;
+  const inner = match[1].trim();
+  return inner.length > 0 ? inner : null;
+};
+var tryStringify = (value) => {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+};
+var isRecord2 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var resolveOutputCandidate = (text) => {
+  const trimmed = text.trim();
+  if (!trimmed) return text;
+  const direct = tryJsonParse(trimmed);
+  if (direct.ok) return direct.value;
+  const block = extractJsonCodeBlock(trimmed);
+  if (block) {
+    const parsedBlock = tryJsonParse(block);
+    if (parsedBlock.ok) return parsedBlock.value;
+  }
+  return text;
+};
+var looksLikeStructuredJsonAttempt = (value) => {
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  return trimmed.startsWith("{") || trimmed.startsWith("[") || /^```(?:json)?/i.test(trimmed);
+};
+var isLikelyTruncatedStructuredOutput = (text) => {
+  const trimmed = text.trim();
+  if (!looksLikeStructuredJsonAttempt(trimmed)) return false;
+  const direct = tryJsonParse(trimmed);
+  if (!direct.ok && direct.error) return true;
+  const block = extractJsonCodeBlock(trimmed);
+  if (!block) return false;
+  const parsedBlock = tryJsonParse(block);
+  return !parsedBlock.ok && Boolean(parsedBlock.error);
+};
+var createTruncatedStructuredOutputError = (label) => new Error(
+  `${label} was truncated before producing valid structured output. The model stopped due to output length. Increase maxOutputTokens or simplify the requested output.`
+);
+var createInvalidStructuredOutputError = (label) => new Error(
+  `${label} did not produce valid structured output. The model returned text instead of the expected JSON payload. This often happens when output is truncated or the provider does not follow JSON mode. Increase maxOutputTokens or simplify the requested output.`
+);
+var parseReasonOutputWithSchema = (args) => {
+  const candidate = resolveOutputCandidate(args.text);
+  try {
+    return parseWithSchema(args.schema, candidate, args.label);
+  } catch (error) {
+    if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
+      throw createTruncatedStructuredOutputError(args.label);
+    }
+    if (typeof candidate === "string" && candidate.trim().length > 0) {
+      throw createInvalidStructuredOutputError(args.label);
     }
+    throw error;
   }
-  return {
-    complete: false
-  };
-};
-var extractCompletedFieldValues = (args) => {
-  const located = locateValueStarts(args);
-  const values = [];
-  for (const match of located) {
-    const parsed = extractCompletedValueAt({
-      text: args.text,
-      start: match.start
-    });
-    if (!parsed.complete) continue;
-    values.push({
-      path: match.path,
-      value: parsed.value
-    });
-  }
-  return values;
 };
-var extractCompletedArrayItems = (args) => {
-  const located = locateValueStart(args);
-  if (!located.found || located.start === void 0) return [];
-  const arrayStart = skipWhitespace(args.text, located.start);
-  if (args.text[arrayStart] !== "[") return [];
-  const start = arrayStart + 1;
-  const items = [];
-  let inString = false;
-  let isEscaped = false;
-  let nesting = 0;
-  let itemStart = -1;
-  for (let i = start; i < args.text.length; i += 1) {
-    const ch = args.text[i];
-    if (ch === void 0) break;
-    if (inString) {
-      if (isEscaped) {
-        isEscaped = false;
-        continue;
-      }
-      if (ch === "\\") {
-        isEscaped = true;
-        continue;
-      }
-      if (ch === '"') {
-        inString = false;
-      }
-      continue;
-    }
-    if (ch === '"') {
-      inString = true;
-      if (itemStart < 0) itemStart = i;
-      continue;
+var parseInterruptFirstPassResult = (args) => {
+  const candidate = resolveOutputCandidate(args.text);
+  if (!isRecord2(candidate)) {
+    if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
+      throw createTruncatedStructuredOutputError("useReason output");
     }
-    if (itemStart < 0) {
-      if (/\s/.test(ch) || ch === ",") continue;
-      if (ch === "]") break;
-      itemStart = i;
-      if (ch === "{" || ch === "[") {
-        nesting = 1;
-      } else {
-        nesting = 0;
-      }
-      continue;
+    if (typeof candidate === "string" && candidate.trim().length > 0) {
+      throw createInvalidStructuredOutputError("useReason output");
     }
-    if (ch === "{" || ch === "[") {
-      nesting += 1;
-      continue;
+    throw new Error(
+      "useReason first pass with interrupt must return a JSON object."
+    );
+  }
+  const mode = args.mode ?? "required";
+  let interruptRequired = true;
+  if (mode === "optional") {
+    if (candidate.decision !== "continue" && candidate.decision !== "interrupt") {
+      throw new Error(
+        'useReason optional interrupt first pass must include decision "continue" or "interrupt".'
+      );
     }
-    if (ch === "}" || ch === "]") {
-      if (nesting > 0) {
-        nesting -= 1;
-        continue;
+    interruptRequired = candidate.decision === "interrupt";
+    if (!interruptRequired) {
+      const hasUnexpectedRequest = [
+        candidate.interruptRequest,
+        candidate.request,
+        candidate.interrupt
+      ].some((value) => value !== null && value !== void 0);
+      if (hasUnexpectedRequest) {
+        throw new Error(
+          'useReason optional interrupt first pass with decision "continue" must not include an interrupt request.'
+        );
       }
     }
-    if (nesting === 0 && (ch === "," || ch === "]")) {
-      const raw = args.text.slice(itemStart, i).trim();
-      if (raw) {
-        try {
-          items.push(JSON.parse(raw));
-        } catch {
-        }
+  }
+  let request;
+  if (interruptRequired) {
+    const requestCandidates = [
+      candidate.interruptRequest,
+      candidate.request,
+      candidate.interrupt,
+      mode === "required" ? candidate : void 0
+    ];
+    const requestPayload = requestCandidates.find(
+      (value) => value !== null && value !== void 0
+    );
+    request = parseWithSchema(
+      args.requestSchema,
+      requestPayload,
+      "useReason interrupt.request"
+    );
+  }
+  let output;
+  if (args.outputSchema) {
+    const outputPayload = Object.hasOwn(candidate, "output") ? candidate.output : candidate;
+    try {
+      output = parseWithSchema(
+        args.outputSchema,
+        outputPayload,
+        "useReason output"
+      );
+    } catch (error) {
+      if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
+        throw createTruncatedStructuredOutputError("useReason output");
       }
-      itemStart = -1;
-      if (ch === "]") break;
+      if (typeof outputPayload === "string" && outputPayload.trim().length > 0) {
+        throw createInvalidStructuredOutputError("useReason output");
+      }
+      throw error;
     }
   }
-  return items;
+  const explicitDraft = typeof candidate.draftText === "string" && candidate.draftText.length > 0 ? candidate.draftText : typeof candidate.text === "string" && candidate.text.length > 0 ? candidate.text : void 0;
+  if (!args.outputSchema && !explicitDraft) {
+    throw new Error(
+      "useReason first pass with interrupt requires `draftText` when outputSchema is not provided."
+    );
+  }
+  const draftText = explicitDraft ?? (output !== void 0 ? tryStringify(output) : String(args.text ?? ""));
+  if (!interruptRequired) {
+    return {
+      draftText,
+      interruptRequired: false,
+      ...output !== void 0 ? { output } : {}
+    };
+  }
+  return {
+    draftText,
+    interruptRequired: true,
+    request,
+    ...output !== void 0 ? { output } : {}
+  };
+};
+
+// src/reason/prompting.ts
+var import_zod3 = require("zod");
+var tryStringify2 = (value) => {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+};
+var tryGetSchemaHint = (schema) => {
+  try {
+    const hint = (0, import_zod3.toJSONSchema)(schema);
+    return JSON.stringify(hint, null, 2);
+  } catch {
+    return void 0;
+  }
+};
+var withSchemaHint = (input, label, schema) => {
+  const hint = tryGetSchemaHint(schema);
+  if (!hint) return input;
+  return `${input}
+
+${label}:
+${hint}`;
+};
+var defaultInterruptFirstPassInput = (args) => {
+  const mode = args.mode ?? "required";
+  const base = mode === "optional" ? args.outputSchema ? [
+    args.input,
+    "Output rules:",
+    "- Return JSON only. No markdown fences.",
+    "- Return an object with keys: decision, output, interruptRequest, draftText.",
+    '- decision must be either "continue" or "interrupt".',
+    '- Use decision "continue" when you can produce the final output without asking the user.',
+    '- Use decision "interrupt" only when user input is needed before finalizing.',
+    "- output must match the expected output JSON schema.",
+    '- When decision is "interrupt", interruptRequest must match the expected interrupt request JSON schema and must be a non-null object.',
+    '- When decision is "continue", interruptRequest must be null.',
+    "- draftText should be a concise plain-language summary of output."
+  ].join("\n\n") : [
+    args.input,
+    "Output rules:",
+    "- Return JSON only. No markdown fences.",
+    "- Return an object with keys: decision, draftText, interruptRequest.",
+    '- decision must be either "continue" or "interrupt".',
+    '- Use decision "continue" when you can produce the final answer without asking the user.',
+    '- Use decision "interrupt" only when user input is needed before finalizing.',
+    "- draftText should be the current answer text.",
+    '- When decision is "interrupt", interruptRequest must match the expected interrupt request JSON schema and must be a non-null object.',
+    '- When decision is "continue", interruptRequest must be null.'
+  ].join("\n\n") : args.outputSchema ? [
+    args.input,
+    "Output rules:",
+    "- Return JSON only. No markdown fences.",
+    "- Return an object with keys: output, interruptRequest, draftText.",
+    "- output must match the expected output JSON schema.",
+    "- interruptRequest must match the expected interrupt request JSON schema.",
+    "- interruptRequest must be a non-null object.",
+    "- draftText should be a concise plain-language summary of output.",
+    "- If uncertain, still return a valid interruptRequest with safe default options."
+  ].join("\n\n") : [
+    args.input,
+    "Output rules:",
+    "- Return JSON only. No markdown fences.",
+    "- Return an object with keys: draftText, interruptRequest.",
+    "- draftText should be the current draft answer text.",
+    "- interruptRequest must match the expected interrupt request JSON schema.",
+    "- interruptRequest must be a non-null object.",
+    "- If uncertain, still return a valid interruptRequest with safe default options."
+  ].join("\n\n");
+  const withInterruptSchema = withSchemaHint(
+    base,
+    "Expected interrupt request JSON schema (for `interruptRequest`)",
+    args.requestSchema
+  );
+  if (!args.outputSchema) return withInterruptSchema;
+  const withOutputSchema = withSchemaHint(
+    withInterruptSchema,
+    "Expected output JSON schema (for `output`)",
+    args.outputSchema
+  );
+  return [
+    withOutputSchema,
+    "JSON template:",
+    mode === "optional" ? '{ "decision": "continue", "output": { ... }, "interruptRequest": null, "draftText": "..." }' : '{ "output": { ... }, "interruptRequest": { ... }, "draftText": "..." }'
+  ].join("\n\n");
 };
-var extractCompletedArrayItemGroups = (args) => {
-  return locateValueStarts(args).flatMap((match) => {
-    const items = extractCompletedArrayItems({
-      text: args.text,
-      path: match.path
-    });
-    return items.length > 0 ? [
-      {
-        path: match.path,
-        items
-      }
-    ] : [];
-  });
+var defaultContinuationInput = (args) => [
+  "You are continuing a paused reasoning task after user input.",
+  "Update the previous result using the user response and return the final answer only.",
+  "If the previous output was JSON, return JSON in the same schema.",
+  "",
+  `Original request:
+${args.input}`,
+  `Draft answer text:
+${args.draftText}`,
+  `Draft output object:
+${tryStringify2(args.draftOutput ?? args.draftText)}`,
+  `Interrupt request shown to user:
+${tryStringify2(args.request)}`,
+  `User response:
+${tryStringify2(args.response)}`
+].join("\n\n");
+var withOutputGuardrails = (input, schema) => {
+  const base = [
+    input,
+    "Output rules:",
+    "- Return only JSON, no markdown fences.",
+    "- Ensure the response conforms to the expected output schema.",
+    "- Do not include explanatory text outside the JSON object."
+  ].join("\n\n");
+  return withSchemaHint(base, "Expected output JSON schema", schema);
 };
-var extractStreamingStringValue = (args) => {
-  const located = locateValueStart(args);
-  if (!located.found || located.start === void 0) {
-    return {
-      found: located.found,
-      complete: false,
-      value: ""
-    };
+var withStructuredStreamHints = (input, args) => {
+  const rules = [];
+  for (const path of args.setFieldPaths ?? []) {
+    rules.push(
+      `- For the field path pattern \`${path}\`, write one stable final value and do not rewrite it after it is complete.`
+    );
   }
-  const stringStart = skipWhitespace(args.text, located.start);
-  if (args.text[stringStart] !== '"') {
-    return {
-      found: true,
-      complete: false,
-      value: ""
-    };
+  for (const path of args.appendFieldPaths ?? []) {
+    rules.push(
+      `- For the array field path pattern \`${path}\`, write items in final order and finish each item before starting the next.`
+    );
+    rules.push(
+      `- Once an item in \`${path}\` is complete, do not rewrite or reorder earlier items.`
+    );
   }
-  let value = "";
-  for (let i = stringStart + 1; i < args.text.length; i += 1) {
-    const ch = args.text[i];
-    if (ch === void 0) break;
-    if (ch === '"') {
-      return {
-        found: true,
-        complete: true,
-        value
-      };
-    }
-    if (ch !== "\\") {
-      value += ch;
-      continue;
-    }
-    const next = args.text[i + 1];
-    if (!next) {
-      return {
-        found: true,
-        complete: false,
-        value
-      };
-    }
-    if (next === '"' || next === "\\" || next === "/" || next === "b" || next === "f" || next === "n" || next === "r" || next === "t") {
-      value += next === "b" ? "\b" : next === "f" ? "\f" : next === "n" ? "\n" : next === "r" ? "\r" : next === "t" ? "	" : next;
-      i += 1;
-      continue;
-    }
-    if (next === "u") {
-      const hex = args.text.slice(i + 2, i + 6);
-      if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
-        return {
-          found: true,
-          complete: false,
-          value
-        };
-      }
-      value += String.fromCharCode(Number.parseInt(hex, 16));
-      i += 5;
-      continue;
-    }
-    return {
-      found: true,
-      complete: false,
-      value
-    };
+  for (const path of args.textDeltaFieldPaths ?? []) {
+    rules.push(
+      `- For the string field path pattern \`${path}\`, write the value progressively by appending text to the end.`
+    );
+    rules.push(
+      `- Do not rewrite or replace the earlier prefix of \`${path}\` once emitted.`
+    );
+  }
+  if (rules.length === 0) return input;
+  return [
+    input,
+    "Streaming rules:",
+    ...rules,
+    "- Keep the overall response as valid JSON."
+  ].join("\n\n");
+};
+
+// src/reason/result.ts
+var mergeUsage = (left, right) => {
+  if (!left) return right;
+  if (!right) return left;
+  const sum = (a, b) => a === void 0 && b === void 0 ? void 0 : (a ?? 0) + (b ?? 0);
+  const raw = left.raw || right.raw ? {
+    ...left.raw ?? {},
+    ...right.raw ?? {}
+  } : void 0;
+  const input = sum(left.input, right.input);
+  const output = sum(left.output, right.output);
+  const total = sum(left.total, right.total);
+  const reasoning = sum(left.reasoning, right.reasoning);
+  const cacheRead = sum(left.cacheRead, right.cacheRead);
+  const cacheWrite = sum(left.cacheWrite, right.cacheWrite);
+  const merged = {
+    ...right.outputIncludesReasoning !== void 0 ? { outputIncludesReasoning: right.outputIncludesReasoning } : {},
+    ...right.inputIncludesCacheWrite !== void 0 ? { inputIncludesCacheWrite: right.inputIncludesCacheWrite } : {},
+    ...right.inputIncludesCacheRead !== void 0 ? { inputIncludesCacheRead: right.inputIncludesCacheRead } : {}
+  };
+  if (input !== void 0) merged.input = input;
+  if (output !== void 0) merged.output = output;
+  if (total !== void 0) merged.total = total;
+  if (reasoning !== void 0) merged.reasoning = reasoning;
+  if (cacheRead !== void 0) merged.cacheRead = cacheRead;
+  if (cacheWrite !== void 0) merged.cacheWrite = cacheWrite;
+  if (raw) merged.raw = raw;
+  return merged;
+};
+var mergeWarnings = (left, right) => {
+  if (!left?.length) return right;
+  if (!right?.length) return left;
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const warning of [...left, ...right]) {
+    const key = JSON.stringify(warning);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(warning);
   }
+  return merged;
+};
+var mergeProviderMetadata = (left, right) => {
+  if (!left) return right;
+  if (!right) return left;
   return {
-    found: true,
-    complete: false,
-    value
+    ...left,
+    ...right
   };
 };
-var extractStreamingStringValues = (args) => {
-  return locateValueStarts(args).flatMap((match) => {
-    const current = extractStreamingStringValue({
-      text: args.text,
-      path: match.path
-    });
-    return current.found ? [
-      {
-        path: match.path,
-        complete: current.complete,
-        value: current.value
-      }
-    ] : [];
+var emitReasonStructuredOutput = (args) => {
+  if (!args.emit || !shouldEmitStructured(args.structured)) return;
+  emitStructuredData({
+    dataType: args.structured?.dataType ?? "reason-output",
+    data: args.output,
+    kind: "final",
+    ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+    ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+    ...args.id ? { id: args.id } : {},
+    streamId: args.opId
   });
 };
 
@@ -1646,13 +1858,16 @@ var createInitialMessages = (args) => [
   { role: "user", content: String(args.input ?? "") }
 ];
 var runReasonToolLoop = async (args) => {
-  const { useReasonArgs, id, opId, traceSpan } = args;
+  const { useReasonArgs, id, traceSpan, checkpointKey } = args;
   const ctx = getHookContext();
   const abortSignal = (0, import_core4.combineAbortSignals)(
     ctx.node.abortSignal,
     useReasonArgs.abortSignal,
     useReasonArgs.model.options?.abortSignal
   );
+  const saved = ctx.currentNodeState.byKey[checkpointKey];
+  const checkpoint = saved?.status === "tool_loop" ? saved : void 0;
+  const opId = checkpoint?.opId ?? args.opId;
   const tools = useReasonArgs.tools ?? [];
   const toolByName = /* @__PURE__ */ new Map();
   let validationCompleted = false;
@@ -1678,20 +1893,43 @@ var runReasonToolLoop = async (args) => {
   }
   const toolDefinitions = toToolDefinitions(tools);
   const maxSteps = Math.max(1, useReasonArgs.toolExecution?.maxSteps ?? 3);
-  const messages = createInitialMessages({
+  const messages = checkpoint?.messages ?? createInitialMessages({
     system: useReasonArgs.system,
-    input: useReasonArgs.input
+    input: useReasonArgs.outputSchema ? withOutputGuardrails(useReasonArgs.input, useReasonArgs.outputSchema) : useReasonArgs.input
   });
-  const steps = [];
-  const allToolCalls = [];
-  const allToolResults = [];
+  const steps = checkpoint?.steps ?? [];
+  const allToolCalls = steps.flatMap(
+    (step) => step.toolCalls
+  );
+  const allToolResults = steps.flatMap(
+    (step) => step.toolResults
+  );
   let finalText = "";
   let finalRaw;
   let finalOutput;
-  let aggregatedUsage;
+  let aggregatedUsage = steps.reduce(
+    (usage, step) => mergeUsage(usage, step.usage),
+    void 0
+  );
   let finalFinishReason;
   let aggregatedProviderMetadata;
-  let aggregatedWarnings;
+  let aggregatedWarnings = steps.reduce(
+    (warnings, step) => mergeWarnings(warnings, step.warnings),
+    args.initialWarnings
+  );
+  let pending = checkpoint?.pending;
+  const approvedCalls = checkpoint?.approvedCalls ?? [];
+  const save = () => {
+    ctx.currentNodeState.byKey[checkpointKey] = {
+      status: "tool_loop",
+      opId,
+      messages,
+      steps,
+      approvedCalls,
+      ...pending ? { pending } : {}
+    };
+    ctx.stateDirty = true;
+  };
   const emitToolEvent = (event, payload) => {
     ctx.node.emit(event, {
       ...payload,
@@ -1701,26 +1939,43 @@ var runReasonToolLoop = async (args) => {
     });
   };
   try {
-    for (let stepIndex = 0; stepIndex < maxSteps; stepIndex += 1) {
+    for (let stepIndex = pending ? steps.length - 1 : steps.length; stepIndex < maxSteps; stepIndex += 1) {
       (0, import_core4.throwIfExecutionAborted)(abortSignal);
       traceSpan?.addEvent?.("useReason.tool-step.start", {
         stepIndex,
         toolCount: toolDefinitions.length
       });
-      const step = await reasonEngine(
+      const reused = Boolean(pending);
+      const stream = useReasonArgs.stream ?? useReasonArgs.model.options?.streaming ?? true;
+      const emit = useReasonArgs.emit ?? true;
+      let textStarted = false;
+      const structuredChunk = useReasonArgs.outputSchema && stream && emit && shouldStreamStructured(useReasonArgs.structured) ? createStructuredOutputStreamer(useReasonArgs, id, opId) : void 0;
+      const step = pending ?? await reasonEngine(
         {
           ...useReasonArgs,
           tools: toolDefinitions,
           messages,
           emit: false,
-          stream: false
+          stream,
+          onTextChunk: (delta) => {
+            if (structuredChunk) structuredChunk(delta);
+            if (!emit || useReasonArgs.outputSchema || !delta) return;
+            if (!textStarted) {
+              emitToolEvent("text-start", {});
+              textStarted = true;
+            }
+            emitToolEvent("text-delta", { delta });
+          }
         },
         { ...id ? { id } : {}, opId }
       );
+      if (textStarted) emitToolEvent("text-end", {});
       finalText = step.text;
       finalRaw = step.raw;
-      aggregatedUsage = mergeUsage(aggregatedUsage, step.usage);
-      accumulateTokenUsage(step.usage);
+      if (!reused) {
+        aggregatedUsage = mergeUsage(aggregatedUsage, step.usage);
+        accumulateTokenUsage(step.usage);
+      }
       finalFinishReason = step.finishReason;
       aggregatedProviderMetadata = mergeProviderMetadata(
         aggregatedProviderMetadata,
@@ -1728,32 +1983,35 @@ var runReasonToolLoop = async (args) => {
       );
       aggregatedWarnings = mergeWarnings(aggregatedWarnings, step.warnings);
       const toolCalls = step.toolCalls ?? [];
-      const toolResults = [];
-      steps.push({
-        stepIndex,
-        text: step.text,
-        toolCalls,
-        toolResults,
-        ...step.usage ? { usage: step.usage } : {},
-        ...step.finishReason ? { finishReason: step.finishReason } : {},
-        ...step.providerMetadata ? { providerMetadata: step.providerMetadata } : {},
-        ...step.warnings ? { warnings: step.warnings } : {}
-      });
+      const toolResults = reused ? steps[stepIndex]?.toolResults ?? [] : [];
+      if (!reused)
+        steps.push({
+          stepIndex,
+          text: step.text,
+          toolCalls,
+          toolResults,
+          ...step.usage ? { usage: step.usage } : {},
+          ...step.finishReason ? { finishReason: step.finishReason } : {},
+          ...step.providerMetadata ? { providerMetadata: step.providerMetadata } : {},
+          ...step.warnings ? { warnings: step.warnings } : {}
+        });
       if (toolCalls.length === 0) {
-        if ((useReasonArgs.emit ?? true) && step.text.length > 0) {
-          emitToolEvent("text-start", {});
-          emitToolEvent("text-delta", { delta: step.text });
-          emitToolEvent("text-end", {});
-        }
         break;
       }
-      allToolCalls.push(...toolCalls);
-      messages.push({
-        role: "assistant",
-        content: step.text,
-        toolCalls
-      });
+      if (!reused) {
+        allToolCalls.push(...toolCalls);
+        messages.push({
+          role: "assistant",
+          content: step.text,
+          toolCalls,
+          ...step.continuation ? { continuation: step.continuation } : {}
+        });
+      }
+      pending = step;
+      save();
       for (const toolCall of toolCalls) {
+        if (toolResults.some((result2) => result2.toolCallId === toolCall.id))
+          continue;
         (0, import_core4.throwIfExecutionAborted)(abortSignal);
         const tool = toolByName.get(toolCall.name);
         if (!tool) {
@@ -1783,7 +2041,7 @@ var runReasonToolLoop = async (args) => {
             input: toolCall.input
           });
         }
-        if (shouldApproveTool) {
+        if (shouldApproveTool && !approvedCalls.includes(toolCall.id)) {
           const approval = await awaitInterruptInternal({
             id: `tool:${toolCall.id}`,
             request: {
@@ -1818,8 +2076,18 @@ var runReasonToolLoop = async (args) => {
                 isError: true
               });
             }
+            messages.push({
+              role: "tool",
+              content: denied.content,
+              toolCallId: denied.toolCallId,
+              name: denied.name,
+              isError: true
+            });
+            save();
             continue;
           }
+          approvedCalls.push(toolCall.id);
+          save();
         }
         try {
           (0, import_core4.throwIfExecutionAborted)(abortSignal);
@@ -1873,25 +2141,19 @@ var runReasonToolLoop = async (args) => {
             message: result2.content
           });
         }
+        const completed = toolResults.at(-1);
+        if (completed)
+          messages.push({
+            role: "tool",
+            content: completed.content,
+            toolCallId: completed.toolCallId,
+            name: completed.name,
+            ...completed.isError !== void 0 ? { isError: completed.isError } : {}
+          });
+        save();
       }
-      const currentStep = steps[steps.length - 1];
-      if (currentStep) {
-        steps[steps.length - 1] = {
-          ...currentStep,
-          toolResults
-        };
-      }
-      for (const result2 of toolResults) {
-        messages.push({
-          role: "tool",
-          content: result2.content,
-          toolCallId: result2.toolCallId,
-          name: result2.name,
-          ...result2.structuredContent !== void 0 ? { structuredContent: result2.structuredContent } : {},
-          ...result2.isError !== void 0 ? { isError: result2.isError } : {},
-          ...result2.raw !== void 0 ? { raw: result2.raw } : {}
-        });
-      }
+      pending = void 0;
+      save();
     }
     if (steps.length >= maxSteps && steps.at(-1)?.toolCalls.length) {
       throw new Error(
@@ -1945,6 +2207,8 @@ var runReasonToolLoop = async (args) => {
         output: useReasonArgs.telemetry?.output ?? finalOutput ?? finalText
       }
     });
+    ctx.currentNodeState.byKey[checkpointKey] = { status: "completed", result };
+    ctx.stateDirty = true;
     return result;
   } catch (error) {
     traceSpan?.fail?.(error, {
@@ -1980,7 +2244,15 @@ async function useReason(args) {
     args.model.options?.abortSignal
   );
   (0, import_core5.throwIfExecutionAborted)(abortSignal);
-  args = { ...args, abortSignal };
+  const inferred = inferOutputFormat(
+    args.outputSchema,
+    args.responseFormat ?? args.model.options?.responseFormat
+  );
+  args = {
+    ...args,
+    abortSignal,
+    ...!args.interrupt && inferred.responseFormat ? { responseFormat: inferred.responseFormat } : {}
+  };
   const id = typeof args.id === "string" && args.id.length > 0 ? args.id : void 0;
   const opId = createRuntimeId2();
   const checkpointKey = resolveReasonCheckpointKey({
@@ -2024,6 +2296,8 @@ async function useReason(args) {
   if (args.tools?.length) {
     return runReasonToolLoop({
       useReasonArgs: args,
+      checkpointKey,
+      initialWarnings: inferred.warnings,
       ...id ? { id } : {},
       opId,
       ...traceSpan ? { traceSpan } : {}
@@ -2047,10 +2321,7 @@ async function useReason(args) {
   let aggregatedUsage;
   let finalFinishReason;
   let aggregatedProviderMetadata;
-  let aggregatedWarnings;
-  const emittedSetValues = /* @__PURE__ */ new Map();
-  const emittedAppendCounts = /* @__PURE__ */ new Map();
-  const emittedTextValues = /* @__PURE__ */ new Map();
+  let aggregatedWarnings = inferred.warnings;
   if (existingCheckpoint) {
     firstText = existingCheckpoint.firstText;
     firstRaw = existingCheckpoint.firstRaw;
@@ -2072,78 +2343,7 @@ async function useReason(args) {
         emit: suppressTextStream ? false : args.emit,
         stream: useStructuredIncrementalStreaming ? true : suppressTextStream ? false : args.stream,
         ...useStructuredIncrementalStreaming ? {
-          onTextChunk: (delta) => {
-            firstText += delta;
-            finalText = firstText;
-            for (const fieldPath of setFieldPaths) {
-              const values = extractCompletedFieldValues({
-                text: firstText,
-                path: fieldPath
-              });
-              for (const { path, value } of values) {
-                const nextSerialized = JSON.stringify(value);
-                if (emittedSetValues.get(path) === nextSerialized) continue;
-                emittedSetValues.set(path, nextSerialized);
-                emitStructuredData({
-                  kind: "set",
-                  path,
-                  value,
-                  dataType: args.structured?.dataType ?? "reason-output",
-                  ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
-                  ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
-                  ...id ? { id } : {},
-                  streamId: opId
-                });
-              }
-            }
-            for (const fieldPath of appendFieldPaths) {
-              const groups = extractCompletedArrayItemGroups({
-                text: firstText,
-                path: fieldPath
-              });
-              for (const { path, items } of groups) {
-                const emittedAppendCount = emittedAppendCounts.get(path) ?? 0;
-                if (items.length <= emittedAppendCount) continue;
-                const nextItems = items.slice(emittedAppendCount);
-                emittedAppendCounts.set(path, items.length);
-                emitStructuredData({
-                  kind: "append",
-                  path,
-                  items: nextItems,
-                  dataType: args.structured?.dataType ?? "reason-output",
-                  ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
-                  ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
-                  ...id ? { id } : {},
-                  streamId: opId
-                });
-              }
-            }
-            for (const fieldPath of textDeltaFieldPaths) {
-              const values = extractStreamingStringValues({
-                text: firstText,
-                path: fieldPath
-              });
-              for (const { path, value } of values) {
-                const emittedTextValue = emittedTextValues.get(path) ?? "";
-                if (value.length <= emittedTextValue.length || !value.startsWith(emittedTextValue)) {
-                  continue;
-                }
-                const nextDelta = value.slice(emittedTextValue.length);
-                emittedTextValues.set(path, value);
-                if (nextDelta.length === 0) continue;
-                emitStructuredData({
-                  kind: "text-delta",
-                  path,
-                  delta: nextDelta,
-                  dataType: args.structured?.dataType ?? "reason-output",
-                  ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
-                  ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
-                  ...id ? { id } : {},
-                  streamId: opId
-                });
-              }
-            }
-          }
+          onTextChunk: createStructuredOutputStreamer(args, id, opId)
         } : {}
       },
       reasonMeta,
@@ -2263,6 +2463,7 @@ async function useReason(args) {
     const second = await reasonEngine(
       {
         ...args,
+        ...inferred.responseFormat ? { responseFormat: inferred.responseFormat } : {},
         emit: suppressTextStream ? false : args.emit,
         stream: suppressTextStream ? false : args.stream
       },
@@ -2647,6 +2848,7 @@ async function useWorkflow(args) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   WorkflowCallError,
+  completeResponse,
   createWorkflowHooks,
   emitWorkflowCall,
   runWithHookContext,