@tanstack/ai 0.44.0 → 0.45.0

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'
   }
 }
 
@@ -729,6 +731,8 @@ class TextEngine<
   private streamStartTime = 0
   private totalChunkCount = 0
   private currentMessageId: string | null = null
+  private currentMessageCreatedAt: Date | null = null
+  private streamIdentityCaptured = false
   private accumulatedContent = ''
   private accumulatedThinking: Array<{ content: string; signature?: string }> =
     []
@@ -799,12 +803,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(
@@ -1108,7 +1114,8 @@ class TextEngine<
         this.finalStructuredOutput &&
         this.toolPhase !== 'wait' &&
         !this.isCancelled() &&
-        !this.finalizationError
+        !this.finalizationError &&
+        !this.earlyTermination
       ) {
         if (this.finalStructuredOutput.nativeCombined === true) {
           yield* this.harvestCombinedStructuredOutput()
@@ -1268,6 +1275,8 @@ class TextEngine<
 
   private async beginIteration(): Promise<void> {
     this.currentMessageId = this.createId('msg')
+    this.currentMessageCreatedAt = new Date()
+    this.streamIdentityCaptured = false
     this.accumulatedContent = ''
     this.accumulatedThinking = []
     this.currentThinkingContent = ''
@@ -1370,9 +1379,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
       ) {
@@ -1404,7 +1450,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
@@ -1455,6 +1501,11 @@ class TextEngine<
     // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- AG-UI EventType enum members vs string-literal case labels; default branch handles untraced events.
     switch (chunk.type) {
       // AG-UI Events
+      case 'TEXT_MESSAGE_START':
+        if (typeof chunk.messageId === 'string' && chunk.messageId !== '') {
+          this.captureStreamMessageIdentity(chunk.messageId)
+        }
+        break
       case 'TEXT_MESSAGE_CONTENT':
         this.handleTextMessageContentEvent(chunk)
         break
@@ -1493,8 +1544,7 @@ class TextEngine<
         break
 
       default:
-        // RUN_STARTED, TEXT_MESSAGE_START, TEXT_MESSAGE_END,
-        // STATE_SNAPSHOT, STATE_DELTA, CUSTOM
+        // RUN_STARTED, TEXT_MESSAGE_END, STATE_SNAPSHOT, STATE_DELTA, CUSTOM
         // - no special handling needed in chat activity
         break
     }
@@ -1513,7 +1563,22 @@ class TextEngine<
     this.middlewareCtx.accumulatedContent = this.accumulatedContent
   }
 
+  private captureStreamMessageIdentity(messageId: string): void {
+    this.currentMessageId = messageId
+    this.middlewareCtx.currentMessageId = messageId
+    if (!this.streamIdentityCaptured) {
+      this.currentMessageCreatedAt = new Date()
+      this.streamIdentityCaptured = true
+    }
+  }
+
   private handleToolCallStartEvent(chunk: ToolCallStartEvent): void {
+    if (
+      typeof chunk.parentMessageId === 'string' &&
+      chunk.parentMessageId !== ''
+    ) {
+      this.captureStreamMessageIdentity(chunk.parentMessageId)
+    }
     this.toolCallManager.addToolCallStartEvent(chunk)
   }
 
@@ -1531,9 +1596,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 {
@@ -1954,6 +2033,8 @@ class TextEngine<
         role: 'assistant',
         content: this.accumulatedContent || null,
         toolCalls,
+        id: this.currentMessageId ?? undefined,
+        createdAt: this.currentMessageCreatedAt ?? undefined,
         ...(this.accumulatedThinking.length > 0 && {
           thinking: this.accumulatedThinking,
         }),
@@ -2152,7 +2233,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
@@ -2830,7 +2913,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 {
@@ -2838,7 +2923,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 } : {}),
       }
@@ -2888,7 +2973,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
@@ -2901,7 +2986,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
@@ -3114,35 +3199,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,
+          }
         }
       }
     }
@@ -3212,7 +3308,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',
@@ -3865,6 +3965,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()
@@ -3888,6 +3990,7 @@ async function runAgenticStructuredOutput<
         normalize,
         ...(validate ? { validate } : {}),
         ...(nativeCombined ? { nativeCombined: true } : {}),
+        source,
       },
     },
     logger,
@@ -3983,14 +4086,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>
@@ -4004,7 +4107,7 @@ async function* fallbackStructuredOutputStream(
       runId,
       threadId,
       model,
-      timestamp,
+      timestamp: Date.now(),
       message,
       error: { message },
     }
@@ -4016,7 +4119,7 @@ async function* fallbackStructuredOutputStream(
     messageId,
     role: 'assistant',
     model,
-    timestamp,
+    timestamp: Date.now(),
   }
 
   yield {
@@ -4024,14 +4127,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 {
@@ -4039,7 +4142,7 @@ async function* fallbackStructuredOutputStream(
     name: 'structured-output.complete',
     value: { object: result.data, raw: result.rawText },
     model,
-    timestamp,
+    timestamp: Date.now(),
   }
 
   yield {
@@ -4047,7 +4150,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
@@ -4180,6 +4283,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()
@@ -4204,6 +4309,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)}`
+}