@tanstack/ai 0.44.1 → 0.45.1

package/src/activities/chat/index.ts

@@ -655,11 +655,12 @@ interface TextEngineConfig<
    * - nativeCombined: when true, the adapter declared
    *   `supportsCombinedToolsAndSchema()` and the engine wires `jsonSchema`
    *   into the regular `chatStream` call instead of running a separate
-   *   finalization round-trip. The agent loop's final-turn text is the
-   *   schema-constrained JSON; the engine parses it from accumulated
-   *   content. The `'structuredOutput'` middleware phase does NOT fire on
-   *   this path — middleware sees the run through `beforeModel` /
-   *   `modelStream` as usual.
+   *   finalization round-trip. The `'structuredOutput'` middleware phase
+   *   does NOT fire on this path — middleware sees the run through
+   *   `beforeModel` / `modelStream` as usual.
+   * - source: how to take the combined object. `'text'` (default) parses
+   *   accumulated assistant text. `'event'` reads an adapter-emitted
+   *   `structured-output.complete` and does not parse prose.
    */
   finalStructuredOutput?: {
     jsonSchema: JSONSchema
@@ -667,6 +668,7 @@ interface TextEngineConfig<
     normalize?: (data: unknown) => unknown
     validate?: (data: unknown) => unknown
     nativeCombined?: boolean
+    source?: 'text' | 'event'
   }
 }
 
@@ -739,6 +741,7 @@ class TextEngine<
   private eventOptions?: Record<string, unknown> | undefined
   private eventToolNames?: Array<string>
   private finishedEvent: RunFinishedEvent | null = null
+  private readonly streamedToolErrorResults = new Map<string, ToolResult>()
   private deferredToolCallRunFinishedChunks: Array<StreamChunk> = []
   private earlyTermination = false
   private toolPhase: ToolPhaseResult = 'continue'
@@ -801,12 +804,14 @@ class TextEngine<
     code?: string
     cause?: unknown
   } | null = null
+  private combinedCompleteEmitted = false
   private readonly finalStructuredOutput?: {
     jsonSchema: JSONSchema
     yieldChunks: boolean
     normalize?: (data: unknown) => unknown
     validate?: (data: unknown) => unknown
     nativeCombined?: boolean
+    source?: 'text' | 'event'
   }
 
   constructor(
@@ -1110,7 +1115,8 @@ class TextEngine<
         this.finalStructuredOutput &&
         this.toolPhase !== 'wait' &&
         !this.isCancelled() &&
-        !this.finalizationError
+        !this.finalizationError &&
+        !this.earlyTermination
       ) {
         if (this.finalStructuredOutput.nativeCombined === true) {
           yield* this.harvestCombinedStructuredOutput()
@@ -1277,6 +1283,7 @@ class TextEngine<
     this.currentThinkingContent = ''
     this.currentThinkingSignature = ''
     this.finishedEvent = null
+    this.streamedToolErrorResults.clear()
 
     // Update mutable context fields
     this.middlewareCtx.currentMessageId = this.currentMessageId
@@ -1374,9 +1381,46 @@ class TextEngine<
       // text starting — intermediate tool-call iterations don't need it,
       // and emitting at run-start would wrap tool-call commentary into a
       // structured-output part too.
+      if (
+        chunk.type === EventType.CUSTOM &&
+        chunk.name === 'structured-output.start'
+      ) {
+        this.combinedStartEmitted = true
+        const startValue = chunk.value
+        if (
+          startValue &&
+          typeof startValue === 'object' &&
+          'messageId' in startValue &&
+          typeof startValue.messageId === 'string'
+        ) {
+          this.combinedStructuredMessageId = startValue.messageId
+        }
+      }
+
+      let outboundChunk: StreamChunk = chunk
+      if (
+        this.finalStructuredOutput?.source === 'event' &&
+        chunk.type === EventType.CUSTOM &&
+        chunk.name === 'structured-output.complete'
+      ) {
+        const parsed = readStructuredOutputCompleteValue(chunk.value)
+        if (parsed) {
+          const object = this.finalStructuredOutput.normalize
+            ? this.finalStructuredOutput.normalize(parsed.object)
+            : parsed.object
+          this.structuredOutputResult = { data: object, rawText: parsed.raw }
+          this.combinedCompleteEmitted = true
+          const value = chunk.value
+          if (object !== parsed.object && value && typeof value === 'object') {
+            outboundChunk = { ...chunk, value: { ...value, object } }
+          }
+        }
+      }
+
       if (
         this.finalStructuredOutput?.nativeCombined === true &&
         this.finalStructuredOutput.yieldChunks &&
+        this.finalStructuredOutput.source !== 'event' &&
         !this.combinedStartEmitted &&
         chunk.type === EventType.TEXT_MESSAGE_START
       ) {
@@ -1408,7 +1452,7 @@ class TextEngine<
       // Pipe chunk through middleware (devtools middleware observes; strip-to-spec cleans)
       const outputChunks = await this.middlewareRunner.runOnChunk(
         this.middlewareCtx,
-        chunk,
+        outboundChunk,
       )
       // When a streaming structured-output finalization step will run after
       // the agent loop, suppress the agent-loop's RUN_STARTED/RUN_FINISHED
@@ -1546,6 +1590,20 @@ class TextEngine<
 
   private handleToolCallEndEvent(chunk: ToolCallEndEvent): void {
     this.toolCallManager.completeToolCall(chunk)
+    if (chunk.state !== 'output-error' || chunk.result === undefined) return
+
+    const toolCall = this.toolCallManager
+      .getToolCalls()
+      .find((candidate) => candidate.id === chunk.toolCallId)
+    if (!toolCall) return
+
+    this.streamedToolErrorResults.set(chunk.toolCallId, {
+      toolCallId: chunk.toolCallId,
+      toolName: toolCall.function.name,
+      result: chunk.result,
+      ...(chunk.input !== undefined && { input: chunk.input }),
+      state: 'output-error',
+    })
   }
 
   private handleRunFinishedEvent(chunk: RunFinishedEvent): void {
@@ -1554,9 +1612,23 @@ class TextEngine<
   }
 
   private handleRunErrorEvent(
-    _chunk: Extract<StreamChunk, { type: 'RUN_ERROR' }>,
+    chunk: Extract<StreamChunk, { type: 'RUN_ERROR' }>,
   ): void {
     this.earlyTermination = true
+    if (this.finalStructuredOutput && this.finalizationError === null) {
+      const message =
+        chunk.message ||
+        chunk.error?.message ||
+        'Run failed before structured output completed'
+      this.finalizationError = {
+        message,
+        ...(chunk.code !== undefined
+          ? { code: chunk.code }
+          : chunk.error?.code !== undefined
+            ? { code: chunk.error.code }
+            : {}),
+      }
+    }
   }
 
   private finalizeCurrentThinkingStep(): void {
@@ -1787,6 +1859,9 @@ class TextEngine<
     // Handle undiscovered lazy tool calls with self-correcting error messages
     const undiscoveredLazyResults: Array<ToolResult> = []
     const executableToolCalls = toolCalls.filter((tc) => {
+      if (this.streamedToolErrorResults.has(tc.id)) {
+        return false
+      }
       if (this.lazyToolManager.isUndiscoveredLazyTool(tc.function.name)) {
         undiscoveredLazyResults.push({
           toolCallId: tc.id,
@@ -1803,14 +1878,17 @@ class TextEngine<
       return true
     })
 
-    // Non-executed outcomes (undiscovered lazy). Per-turn skips come from
-    // middleware and appear in execution results.
-    const deferredErrorResults = [...undiscoveredLazyResults]
+    // Non-executed outcomes. Per-turn skips come from middleware and appear in
+    // execution results.
+    const deferredErrorResults = [
+      ...this.streamedToolErrorResults.values(),
+      ...undiscoveredLazyResults,
+    ]
 
     if (executableToolCalls.length === 0) {
       yield* this.flushDeferredToolCallRunFinishedChunks()
-      // All tool calls were undiscovered lazy tools — errors emitted, continue
-      // loop (strategy / onShouldContinue may stop).
+      // All tool calls already have error results — emit them, then continue
+      // the loop (strategy / onShouldContinue may stop).
       if (deferredErrorResults.length > 0) {
         for (const chunk of this.buildToolResultChunks(
           deferredErrorResults,
@@ -2177,7 +2255,9 @@ class TextEngine<
               ? undefined
               : JSON.stringify(message.content)
         return {
-          id: `snapshot_${this.runIdOverride ?? this.requestId}_${index}`,
+          id:
+            message.id ||
+            `snapshot_${this.runIdOverride ?? this.requestId}_${index}`,
           role: message.role,
           ...(content !== undefined ? { content } : {}),
           ...('toolCalls' in message && message.toolCalls
@@ -2855,7 +2935,9 @@ class TextEngine<
       return null
     }
 
-    const buildSynthesizedStart = (): StreamChunk => {
+    // The synthetic event is inserted before its trigger, so share that
+    // trigger's timestamp rather than making the earlier event sort later.
+    const buildSynthesizedStart = (timestamp = Date.now()): StreamChunk => {
       const idForStart = structuredMessageId ?? generateMessageId()
       structuredMessageId = idForStart
       return {
@@ -2863,7 +2945,7 @@ class TextEngine<
         name: 'structured-output.start',
         value: { messageId: idForStart },
         model: this.params.model,
-        timestamp: Date.now(),
+        timestamp,
         threadId: this.threadId,
         ...(this.runIdOverride ? { runId: this.runIdOverride } : {}),
       }
@@ -2913,7 +2995,7 @@ class TextEngine<
             chunk.type === EventType.TEXT_MESSAGE_END)
         ) {
           startEmitted = true
-          const synthStart = buildSynthesizedStart()
+          const synthStart = buildSynthesizedStart(chunk.timestamp)
           const synthOutputs = await pipeThroughMiddleware(synthStart)
           for (const outputChunk of synthOutputs) {
             yield outputChunk
@@ -2926,7 +3008,7 @@ class TextEngine<
         // of a silent UI.
         if (!startEmitted && chunk.type === EventType.RUN_ERROR) {
           startEmitted = true
-          const synthStart = buildSynthesizedStart()
+          const synthStart = buildSynthesizedStart(chunk.timestamp)
           const synthOutputs = await pipeThroughMiddleware(synthStart)
           for (const outputChunk of synthOutputs) {
             yield outputChunk
@@ -3139,35 +3221,46 @@ class TextEngine<
     }
 
     const yieldChunks = this.finalStructuredOutput.yieldChunks
-    const rawText = this.accumulatedContent
+    const source = this.finalStructuredOutput.source ?? 'text'
 
-    // Empty final-turn text means the agent loop terminated without the
-    // model emitting any assistant content (e.g. early termination after
-    // tool calls). Mirror the fallback path's "missing structured result"
-    // error rather than silently returning undefined.
-    if (rawText.length === 0) {
-      this.finalizationError = {
-        message: 'missing structured result',
-        code: 'structured-output-missing-result',
+    if (source === 'event') {
+      if (!this.structuredOutputResult) {
+        this.finalizationError = {
+          message: 'missing structured result',
+          code: 'structured-output-missing-result',
+        }
       }
     } else {
-      try {
-        const parsed: unknown = JSON.parse(rawText)
-        // Normalize (un-widen) before storing so the synthesized
-        // structured-output.complete chunk and the Promise<T> result both
-        // carry the cleaned payload. JSON.parse preserves provider nulls, so
-        // this is where native-combined output gets its widening undone.
-        const data = this.finalStructuredOutput.normalize
-          ? this.finalStructuredOutput.normalize(parsed)
-          : parsed
-        this.structuredOutputResult = { data, rawText }
-      } catch (err: unknown) {
-        const detail =
-          rawText.slice(0, 200) + (rawText.length > 200 ? '...' : '')
+      const rawText = this.accumulatedContent
+
+      // Empty final-turn text means the agent loop terminated without the
+      // model emitting any assistant content (e.g. early termination after
+      // tool calls). Mirror the fallback path's "missing structured result"
+      // error rather than silently returning undefined.
+      if (rawText.length === 0) {
         this.finalizationError = {
-          message: `Failed to parse structured output as JSON. Content: ${detail}`,
-          code: 'structured-output-parse-failed',
-          cause: err,
+          message: 'missing structured result',
+          code: 'structured-output-missing-result',
+        }
+      } else {
+        try {
+          const parsed: unknown = JSON.parse(rawText)
+          // Normalize (un-widen) before storing so the synthesized
+          // structured-output.complete chunk and the Promise<T> result both
+          // carry the cleaned payload. JSON.parse preserves provider nulls, so
+          // this is where native-combined output gets its widening undone.
+          const data = this.finalStructuredOutput.normalize
+            ? this.finalStructuredOutput.normalize(parsed)
+            : parsed
+          this.structuredOutputResult = { data, rawText }
+        } catch (err: unknown) {
+          const detail =
+            rawText.slice(0, 200) + (rawText.length > 200 ? '...' : '')
+          this.finalizationError = {
+            message: `Failed to parse structured output as JSON. Content: ${detail}`,
+            code: 'structured-output-parse-failed',
+            cause: err,
+          }
         }
       }
     }
@@ -3237,7 +3330,11 @@ class TextEngine<
     // complete event yields AFTER the loop ends, by which point
     // `getActiveAssistantMessageId()` returns null and would otherwise drop
     // the event silently).
-    if (this.structuredOutputResult && !this.finalizationError) {
+    if (
+      this.structuredOutputResult &&
+      !this.finalizationError &&
+      !this.combinedCompleteEmitted
+    ) {
       const completeChunk: StreamChunk = {
         type: EventType.CUSTOM,
         name: 'structured-output.complete',
@@ -3890,6 +3987,8 @@ async function runAgenticStructuredOutput<
   // agent loop's accumulated final-turn text.
   const nativeCombined =
     adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true
+  const source =
+    adapter.combinedStructuredOutputSource?.(options.modelOptions) ?? 'text'
 
   const mcpManager = MCPManager.from(mcp)
   const mcpTools = await mcpManager.discover()
@@ -3913,6 +4012,7 @@ async function runAgenticStructuredOutput<
         normalize,
         ...(validate ? { validate } : {}),
         ...(nativeCombined ? { nativeCombined: true } : {}),
+        source,
       },
     },
     logger,
@@ -4008,14 +4108,14 @@ async function* fallbackStructuredOutputStream(
     chatOptions.threadId ?? `fallback-${Date.now()}-${fallbackRand}`
   const messageId = `fallback-${Date.now()}-${fallbackRand}`
   const model = chatOptions.model
-  const timestamp = Date.now()
+  const startedAt = Date.now()
 
   yield {
     type: EventType.RUN_STARTED,
     runId,
     threadId,
     model,
-    timestamp,
+    timestamp: startedAt,
   }
 
   let result: StructuredOutputResult<unknown>
@@ -4029,7 +4129,7 @@ async function* fallbackStructuredOutputStream(
       runId,
       threadId,
       model,
-      timestamp,
+      timestamp: Date.now(),
       message,
       error: { message },
     }
@@ -4041,7 +4141,7 @@ async function* fallbackStructuredOutputStream(
     messageId,
     role: 'assistant',
     model,
-    timestamp,
+    timestamp: Date.now(),
   }
 
   yield {
@@ -4049,14 +4149,14 @@ async function* fallbackStructuredOutputStream(
     messageId,
     delta: result.rawText,
     model,
-    timestamp,
+    timestamp: Date.now(),
   }
 
   yield {
     type: EventType.TEXT_MESSAGE_END,
     messageId,
     model,
-    timestamp,
+    timestamp: Date.now(),
   }
 
   yield {
@@ -4064,7 +4164,7 @@ async function* fallbackStructuredOutputStream(
     name: 'structured-output.complete',
     value: { object: result.data, raw: result.rawText },
     model,
-    timestamp,
+    timestamp: Date.now(),
   }
 
   yield {
@@ -4072,7 +4172,7 @@ async function* fallbackStructuredOutputStream(
     runId,
     threadId,
     model,
-    timestamp,
+    timestamp: Date.now(),
     finishReason: 'stop',
     // Forward adapter-reported token usage so consumers reading
     // `RUN_FINISHED.usage` (and the engine's `runOnUsage` middleware hook) see
@@ -4205,6 +4305,8 @@ async function* runStreamingStructuredOutputImpl<
   // does not fire.
   const nativeCombined =
     adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true
+  const source =
+    adapter.combinedStructuredOutputSource?.(options.modelOptions) ?? 'text'
 
   const mcpManager = MCPManager.from(mcp)
   const mcpTools = await mcpManager.discover()
@@ -4229,6 +4331,7 @@ async function* runStreamingStructuredOutputImpl<
         yieldChunks: true,
         normalize,
         ...(nativeCombined ? { nativeCombined: true } : {}),
+        source,
       },
     },
     logger,

package/src/activities/chat/stream/processor.ts

@@ -1854,9 +1854,10 @@ export class StreamProcessor {
 
     if (chunk.name === 'structured-output.start' && chunk.value) {
       const v = chunk.value as { messageId?: string }
-      const targetId = v.messageId ?? messageId
+      const { messageId: targetId } = this.ensureAssistantMessage(
+        v.messageId ?? messageId ?? undefined,
+      )
       if (targetId) {
-        this.ensureAssistantMessage(targetId)
         this.structuredMessageIds.add(targetId)
         this.structuredOutputUpdateBatches.delete(targetId)
         this.events.onStructuredOutputChange?.({
@@ -1876,7 +1877,9 @@ export class StreamProcessor {
         reasoning?: string
         messageId?: string
       }
-      const targetId = v.messageId ?? messageId
+      const { messageId: targetId } = this.ensureAssistantMessage(
+        v.messageId ?? messageId ?? undefined,
+      )
       if (targetId) {
         this.flushStructuredOutputUpdate(targetId)
         this.messages = completeStructuredOutputPart(

package/src/activities/chat/tools/tool-calls.ts

@@ -813,7 +813,7 @@ export async function* executeToolCalls<TContext = unknown>(
       continue
     }
 
-    // Parse arguments, throwing error if invalid JSON
+    // Parse arguments
     let input: unknown = {}
     const argsStr = toolCall.function.arguments.trim() || '{}'
     if (argsStr) {
@@ -821,9 +821,17 @@ export async function* executeToolCalls<TContext = unknown>(
         const parsed = JSON.parse(argsStr)
         // Normalize null/non-object to {} (e.g. Anthropic empty tool_use blocks)
         input = parsed && typeof parsed === 'object' ? parsed : {}
-      } catch (parseError) {
-        // If parsing fails, throw error to fail fast
-        throw new Error(`Failed to parse tool arguments as JSON: ${argsStr}`)
+      } catch {
+        results.push({
+          toolCallId: toolCall.id,
+          toolName,
+          result: {
+            error: `Failed to parse tool arguments as JSON: ${argsStr}`,
+          },
+          input,
+          state: 'output-error',
+        })
+        continue
       }
     }
 

package/src/adapter-internals.ts

@@ -25,3 +25,11 @@ export {
   PendingTurnCapability,
   providePendingTurn,
 } from './activities/chat/middleware/pending-turn'
+export {
+  appendOutputSchemaInstruction,
+  parseJsonFromAssistantText,
+} from './utilities/structured-output-text'
+export {
+  structuredOutputCompleteChunk,
+  structuredOutputStartChunk,
+} from './utilities/structured-output-events'

package/src/types.ts

@@ -958,10 +958,13 @@ export interface TextOptions<
    *    `supportsCombinedToolsAndSchema(modelOptions) === true`. The adapter
    *    should then wire the schema into the upstream request (e.g.
    *    `response_format: { type: 'json_schema', ... }`, `text.format`,
-   *    `output_format`) alongside any `tools`. The model's natural final
-   *    turn carries the schema-constrained JSON text and the engine
-   *    harvests it from the agent loop without a separate finalization
-   *    round-trip.
+   *    `output_format`, `--json-schema`) alongside any `tools`.
+   *
+   *    How the engine then takes the object depends on
+   *    `combinedStructuredOutputSource()`:
+   *    - `'text'` (default): the final-turn assistant text is the JSON.
+   *    - `'event'`: the adapter emits `structured-output.complete` during
+   *      `chatStream`. Accumulated prose is not parsed.
    *
    *    Adapters that did NOT declare the capability never see this field
    *    populated — the engine instead invokes `structuredOutput` /
@@ -1555,20 +1558,25 @@ export interface CodeModeExternalErrorEvent extends CustomEvent {
   name: 'code_mode:external_error'
   value: { function: string; error: string; duration: number }
 }
-export interface CodeModeSkillCallEvent extends CustomEvent {
-  name: 'code_mode:skill_call'
-  value: { skill: string; input: unknown; timestamp: number }
+export interface CodeModeSnippetCallEvent extends CustomEvent {
+  name: 'code_mode:snippet_call'
+  value: { snippet: string; input: unknown; timestamp: number }
 }
-export interface CodeModeSkillResultEvent extends CustomEvent {
-  name: 'code_mode:skill_result'
-  value: { skill: string; result: unknown; duration: number; timestamp: number }
+export interface CodeModeSnippetResultEvent extends CustomEvent {
+  name: 'code_mode:snippet_result'
+  value: {
+    snippet: string
+    result: unknown
+    duration: number
+    timestamp: number
+  }
 }
-export interface CodeModeSkillErrorEvent extends CustomEvent {
-  name: 'code_mode:skill_error'
-  value: { skill: string; error: string; duration: number; timestamp: number }
+export interface CodeModeSnippetErrorEvent extends CustomEvent {
+  name: 'code_mode:snippet_error'
+  value: { snippet: string; error: string; duration: number; timestamp: number }
 }
-export interface SkillRegisteredEvent extends CustomEvent {
-  name: 'skill:registered'
+export interface SnippetRegisteredEvent extends CustomEvent {
+  name: 'snippet:registered'
   value: { id: string; name: string; description: string; timestamp: number }
 }
 
@@ -1587,10 +1595,10 @@ export type KnownCustomEvent =
   | CodeModeExternalCallEvent
   | CodeModeExternalResultEvent
   | CodeModeExternalErrorEvent
-  | CodeModeSkillCallEvent
-  | CodeModeSkillResultEvent
-  | CodeModeSkillErrorEvent
-  | SkillRegisteredEvent
+  | CodeModeSnippetCallEvent
+  | CodeModeSnippetResultEvent
+  | CodeModeSnippetErrorEvent
+  | SnippetRegisteredEvent
   | StructuredOutputStartEvent
   | StructuredOutputCompleteEvent
   | ApprovalRequestedEvent

package/src/utilities/structured-output-events.ts

@@ -0,0 +1,44 @@
+import { EventType } from '../types'
+import type { StreamChunk } from '../types'
+
+export function structuredOutputStartChunk(args: {
+  messageId: string
+  model: string
+  threadId: string
+  runId: string
+  timestamp?: number
+}): StreamChunk {
+  return {
+    type: EventType.CUSTOM,
+    name: 'structured-output.start',
+    value: { messageId: args.messageId },
+    model: args.model,
+    timestamp: args.timestamp ?? Date.now(),
+    threadId: args.threadId,
+    runId: args.runId,
+  }
+}
+
+export function structuredOutputCompleteChunk(args: {
+  messageId: string
+  model: string
+  threadId: string
+  runId: string
+  object: unknown
+  raw: string
+  timestamp?: number
+}): StreamChunk {
+  return {
+    type: EventType.CUSTOM,
+    name: 'structured-output.complete',
+    value: {
+      object: args.object,
+      raw: args.raw,
+      messageId: args.messageId,
+    },
+    model: args.model,
+    timestamp: args.timestamp ?? Date.now(),
+    threadId: args.threadId,
+    runId: args.runId,
+  }
+}

package/src/utilities/structured-output-text.ts

@@ -0,0 +1,63 @@
+/**
+ * Parse JSON from a model/harness assistant string.
+ * Strips a wrapping markdown fence when the whole payload is fenced.
+ * If the model wrote prose first, take the last JSON object or array.
+ */
+export function parseJsonFromAssistantText(raw: string): unknown {
+  const trimmed = raw.trim()
+  if (trimmed === '') {
+    throw new SyntaxError('Assistant text is empty')
+  }
+
+  const candidates: Array<string> = []
+  const wholeFence = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/)
+  if (wholeFence?.[1]) candidates.push(wholeFence[1].trim())
+  candidates.push(trimmed)
+  const lastFence = [
+    ...trimmed.matchAll(/```(?:json)?\s*([\s\S]*?)\s*```/g),
+  ].at(-1)
+  if (lastFence?.[1]) candidates.push(lastFence[1].trim())
+  const extracted = extractLastJsonSlice(trimmed)
+  if (extracted !== undefined) candidates.push(extracted)
+
+  let lastError: unknown
+  for (const candidate of candidates) {
+    try {
+      return JSON.parse(candidate)
+    } catch (error) {
+      lastError = error
+    }
+  }
+  throw lastError instanceof Error
+    ? lastError
+    : new SyntaxError('No JSON object found in assistant text')
+}
+
+function extractLastJsonSlice(text: string): string | undefined {
+  for (let end = text.length - 1; end >= 0; end--) {
+    if (text[end] !== '}' && text[end] !== ']') continue
+    for (let start = end; start >= 0; start--) {
+      const opener = text[start]
+      if (opener !== '{' && opener !== '[') continue
+      const slice = text.slice(start, end + 1)
+      try {
+        JSON.parse(slice)
+        return slice
+      } catch {
+        // Try an earlier opener, then an earlier closer.
+      }
+    }
+  }
+  return undefined
+}
+
+export function appendOutputSchemaInstruction(
+  prompt: string,
+  schema: unknown,
+): string {
+  return `${prompt}
+
+Respond with a single JSON object that matches this JSON Schema. Do not wrap the object in markdown unless you must.
+
+${JSON.stringify(schema)}`
+}