@tanstack/ai 0.50.0 → 0.52.0

package/src/activities/chat/index.ts

@@ -788,6 +788,7 @@ class TextEngine<
   private readonly effectiveSignal?: AbortSignal
 
   private messages: Array<ModelMessage>
+  private providerMessages: Array<ModelMessage>
   private iterationCount = 0
   /** Cumulative tool calls counted in this run (emitted + pending resume). */
   private toolCallCount = 0
@@ -845,6 +846,9 @@ class TextEngine<
   >
   private readonly middlewareCtx: ChatMiddlewareContext<TContext>
   private readonly sandboxFileQueue: Array<StreamChunk> = []
+  private readonly middlewareCustomQueue: Array<StreamChunk> = []
+  private middlewareCustomWaiters: Array<() => void> = []
+  private drainingMiddlewareCustom = false
   private readonly deferredPromises: Array<Promise<unknown>> = []
   private abortReason?: string
   private readonly middlewareAbortController?: AbortController
@@ -935,6 +939,7 @@ class TextEngine<
     // Convert messages to ModelMessage format (handles both UIMessage and ModelMessage input)
     // This ensures consistent internal format regardless of what the client sends
     this.messages = convertMessagesToModelMessages(config.params.messages)
+    this.providerMessages = this.messages
 
     // Initialize lazy tool manager after messages are converted (needs message history for scanning)
     assertUniqueToolNames(config.params.tools || [])
@@ -993,6 +998,14 @@ class TextEngine<
         this.abortReason = reason
         this.middlewareAbortController?.abort(reason)
       },
+      emitCustomEvent: (name, value) => {
+        this.middlewareCustomQueue.push(
+          this.createCustomEventChunk(name, value),
+        )
+        const waiters = this.middlewareCustomWaiters
+        this.middlewareCustomWaiters = []
+        for (const waiter of waiters) waiter()
+      },
       context: config.context as TContext,
       defer: (promise: Promise<unknown>) => {
         this.deferredPromises.push(promise)
@@ -1128,21 +1141,24 @@ class TextEngine<
 
     try {
       // Provision capabilities before any consumer (onConfig onward) can read them
-      await this.middlewareRunner.runSetup(this.middlewareCtx)
+      yield* this.runWhileYielding(
+        this.middlewareRunner.runSetup(this.middlewareCtx),
+      )
 
       // Run initial onConfig (phase = init)
       this.middlewareCtx.phase = 'init'
       const initialConfig = this.buildMiddlewareConfig()
-      const transformedConfig = await this.middlewareRunner.runOnConfig(
-        this.middlewareCtx,
-        initialConfig,
+      const transformedConfig = yield* this.runWhileYielding(
+        this.middlewareRunner.runOnConfig(this.middlewareCtx, initialConfig),
       )
       this.applyMiddlewareConfig(transformedConfig)
       await this.applyEphemeralInterruptResume(transformedConfig)
       await this.applyDurableGenericInterruptResolution()
 
       // Run onStart (devtools middleware emits text:request:started and initial messages here)
-      await this.middlewareRunner.runOnStart(this.middlewareCtx)
+      yield* this.runWhileYielding(
+        this.middlewareRunner.runOnStart(this.middlewareCtx),
+      )
 
       if (this.earlyTermination) {
         yield* this.emitSuccessfulEarlyTermination()
@@ -1189,18 +1205,16 @@ class TextEngine<
             iteration: this.middlewareCtx.iteration,
           })
 
-          await this.beginCycle()
+          yield* this.runWhileYielding(this.beginCycle())
 
           if (this.cyclePhase === 'processText') {
             // Run onConfig before each model call (phase = beforeModel)
             this.middlewareCtx.phase = 'beforeModel'
             this.middlewareCtx.iteration = this.iterationCount
             const iterConfig = this.buildMiddlewareConfig()
-            const iterTransformedConfig =
-              await this.middlewareRunner.runOnConfig(
-                this.middlewareCtx,
-                iterConfig,
-              )
+            const iterTransformedConfig = yield* this.runWhileYielding(
+              this.middlewareRunner.runOnConfig(this.middlewareCtx, iterConfig),
+            )
             this.applyMiddlewareConfig(iterTransformedConfig)
 
             if (
@@ -1239,7 +1253,7 @@ class TextEngine<
           }
 
           this.endCycle()
-        } while (await this.shouldContinue())
+        } while (yield* this.runWhileYielding(this.shouldContinue()))
       }
 
       this.logger.agentLoop('run finished', {
@@ -1497,7 +1511,7 @@ class TextEngine<
 
     for await (const raw of this.adapter.chatStream({
       model: this.params.model,
-      messages: this.messages,
+      messages: this.providerMessages,
       tools: toolsWithJsonSchemas,
       metadata,
       request: this.effectiveRequest,
@@ -1632,6 +1646,7 @@ class TextEngine<
             continue
           }
           if (spec.type === EventType.RUN_STARTED) {
+            if (this.hasPublicRunStarted) continue
             this.hasPublicRunStarted = true
           }
           this.logger.output(`type=${spec.type}`, { chunk: spec })
@@ -1646,6 +1661,7 @@ class TextEngine<
 
       // Drain any sandbox.file events emitted while processing this chunk.
       yield* this.drainSandboxFileQueue()
+      yield* this.drainMiddlewareCustomQueue()
 
       if (this.earlyTermination) {
         break
@@ -1654,6 +1670,7 @@ class TextEngine<
 
     // Drain any remaining sandbox.file events emitted after the stream ended.
     yield* this.drainSandboxFileQueue()
+    yield* this.drainMiddlewareCustomQueue()
   }
 
   private handleStreamChunk(chunk: AdapterYieldChunk): void {
@@ -2047,12 +2064,14 @@ class TextEngine<
     const allResults = [...executionResult.results, ...deferredErrorResults]
 
     // Notify middleware of tool phase completion (devtools emits aggregate events here)
-    await this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
-      toolCalls: pendingToolCalls,
-      results: allResults,
-      needsApproval: executionResult.needsApproval,
-      needsClientExecution: executionResult.needsClientExecution,
-    })
+    yield* this.runWhileYielding(
+      this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
+        toolCalls: pendingToolCalls,
+        results: allResults,
+        needsApproval: executionResult.needsApproval,
+        needsClientExecution: executionResult.needsClientExecution,
+      }),
+    )
 
     if (
       executionResult.needsApproval.length > 0 ||
@@ -2228,23 +2247,26 @@ class TextEngine<
     const allResults = [...executionResult.results, ...deferredErrorResults]
 
     // Notify middleware of tool phase completion (devtools emits aggregate events here)
-    await this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
-      toolCalls,
-      results: allResults,
-      needsApproval: executionResult.needsApproval,
-      needsClientExecution: executionResult.needsClientExecution,
-    })
+    yield* this.runWhileYielding(
+      this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
+        toolCalls,
+        results: allResults,
+        needsApproval: executionResult.needsApproval,
+        needsClientExecution: executionResult.needsClientExecution,
+      }),
+    )
 
     const afterToolBoundaryChunks = this.buildToolResultChunks(
       allResults,
       finishEvent,
     )
-    const afterToolRequests =
-      await this.middlewareRunner.runOnInterruptBoundary(
+    const afterToolRequests = yield* this.runWhileYielding(
+      this.middlewareRunner.runOnInterruptBoundary(
         this.middlewareCtx as ChatMiddlewareContext<TContext> & {
           phase: 'afterTools'
         },
-      )
+      ),
+    )
     if (afterToolRequests.length > 0) {
       for (const chunk of afterToolBoundaryChunks) {
         yield* this.pipeThroughMiddleware(chunk)
@@ -2924,10 +2946,12 @@ class TextEngine<
     this.middlewareCtx.phase = phase
     const boundaryRequests =
       requests ??
-      (await this.middlewareRunner.runOnInterruptBoundary(
-        this.middlewareCtx as ChatMiddlewareContext<TContext> & {
-          phase: typeof phase
-        },
+      (yield* this.runWhileYielding(
+        this.middlewareRunner.runOnInterruptBoundary(
+          this.middlewareCtx as ChatMiddlewareContext<TContext> & {
+            phase: typeof phase
+          },
+        ),
       ))
     if (boundaryRequests.length === 0) return false
     for (const request of boundaryRequests) {
@@ -3445,9 +3469,11 @@ class TextEngine<
     }
 
     // 1) onStructuredOutputConfig — middleware can transform messages, options, outputSchema
-    structuredConfig = await this.middlewareRunner.runOnStructuredOutputConfig(
-      this.middlewareCtx,
-      structuredConfig,
+    structuredConfig = yield* this.runWhileYielding(
+      this.middlewareRunner.runOnStructuredOutputConfig(
+        this.middlewareCtx,
+        structuredConfig,
+      ),
     )
 
     // 2) onConfig — phase-aware general-purpose middleware re-runs at the
@@ -3456,9 +3482,11 @@ class TextEngine<
     // call — same constraint applies — but the view is consistent with the
     // ChatMiddlewareConfig shape).
     const { outputSchema: pinnedSchema, ...chatConfigSlice } = structuredConfig
-    const postOnConfig = await this.middlewareRunner.runOnConfig(
-      this.middlewareCtx,
-      { ...chatConfigSlice, tools: baseConfig.tools },
+    const postOnConfig = yield* this.runWhileYielding(
+      this.middlewareRunner.runOnConfig(this.middlewareCtx, {
+        ...chatConfigSlice,
+        tools: baseConfig.tools,
+      }),
     )
 
     // Apply merged config back to engine state
@@ -3470,7 +3498,7 @@ class TextEngine<
     const structuredCallOptions = {
       chatOptions: {
         model: this.params.model,
-        messages: this.messages,
+        messages: this.providerMessages,
         metadata: postOnConfig.metadata,
         modelOptions: postOnConfig.modelOptions,
         systemPrompts: postOnConfig.systemPrompts,
@@ -3949,6 +3977,7 @@ class TextEngine<
   private buildMiddlewareConfig(): ChatMiddlewareConfig {
     return {
       messages: this.messages,
+      providerMessages: this.messages,
       systemPrompts: [...this.systemPrompts],
       tools: [...this.tools],
       resume: this.params.resume,
@@ -4367,6 +4396,7 @@ class TextEngine<
   private applyMiddlewareConfig(config: ChatMiddlewareConfig): void {
     this.applyResumeToolState(config.resumeToolState)
     this.messages = config.messages
+    this.providerMessages = config.providerMessages ?? config.messages
     this.systemPrompts = config.systemPrompts
     assertUniqueToolNames(config.tools)
     this.tools = config.tools
@@ -4399,6 +4429,7 @@ class TextEngine<
       for (const spec of normalizeStreamChunk(output as AdapterYieldChunk)) {
         restorePublicUsage(spec)
         if (spec.type === EventType.RUN_STARTED) {
+          if (this.hasPublicRunStarted) continue
           this.hasPublicRunStarted = true
         }
         yield spec
@@ -4419,6 +4450,69 @@ class TextEngine<
       chunk,
     )
     yield* this.emitPublicChunks(afterMw)
+    if (!this.drainingMiddlewareCustom) {
+      yield* this.drainMiddlewareCustomQueue()
+    }
+  }
+
+  /**
+   * Drain CUSTOM chunks pushed by `ctx.emitCustomEvent` through middleware
+   * and into the public stream. If the run has not yet sent `RUN_STARTED`,
+   * emit that first so CUSTOM events are not the first wire event.
+   */
+  private async *drainMiddlewareCustomQueue(): AsyncGenerator<StreamChunk> {
+    if (this.drainingMiddlewareCustom) return
+    if (this.middlewareCustomQueue.length === 0) return
+    this.drainingMiddlewareCustom = true
+    try {
+      yield* this.emitSyntheticRunStarted(this.createSyntheticFinishedEvent())
+      while (this.middlewareCustomQueue.length > 0) {
+        const chunk = this.middlewareCustomQueue.shift()
+        if (chunk) yield* this.pipeThroughMiddleware(chunk)
+      }
+    } finally {
+      this.drainingMiddlewareCustom = false
+    }
+  }
+
+  /**
+   * Await `work` while yielding any `emitCustomEvent` chunks as they arrive.
+   */
+  private async *runWhileYielding<T>(
+    work: Promise<T>,
+  ): AsyncGenerator<StreamChunk, T> {
+    let settled = false
+    let result: T | undefined
+    let error: unknown
+    const done = work.then(
+      (value) => {
+        settled = true
+        result = value
+      },
+      (err: unknown) => {
+        settled = true
+        error = err
+      },
+    )
+
+    while (!settled) {
+      yield* this.drainMiddlewareCustomQueue()
+      if (settled) break
+      await Promise.race([
+        done,
+        new Promise<void>((resolve) => {
+          if (this.middlewareCustomQueue.length > 0) {
+            resolve()
+            return
+          }
+          this.middlewareCustomWaiters.push(resolve)
+        }),
+      ])
+    }
+
+    yield* this.drainMiddlewareCustomQueue()
+    if (error !== undefined) throw error
+    return result as T
   }
 
   /**
@@ -4455,17 +4549,18 @@ class TextEngine<
     },
     void
   > {
-    let next = await generator.next()
-    while (!next.done) {
+    let pending = generator.next()
+    while (true) {
+      const next = yield* this.runWhileYielding(pending)
+      if (next.done) return next.value
       yield* this.pipeThroughMiddleware(next.value)
-      next = await generator.next()
+      pending = generator.next()
     }
-    return next.value
   }
 
   private createCustomEventChunk(
     eventName: string,
-    value: Record<string, any>,
+    value: Record<string, unknown>,
   ): CustomEvent {
     return {
       type: EventType.CUSTOM,

package/src/activities/chat/middleware/compose.ts

@@ -166,7 +166,13 @@ export class MiddlewareRunner<
         const result = await mw.onConfig(ctx, current)
         const hasTransform = result !== undefined && result !== null
         if (hasTransform) {
-          current = { ...current, ...result }
+          current = {
+            ...current,
+            ...result,
+            ...('messages' in result && !('providerMessages' in result)
+              ? { providerMessages: result.messages }
+              : {}),
+          }
           if (!skip) {
             this.logger.config(
               `middleware=${mw.name ?? 'unnamed'} keys=${Object.keys(result).join(',')}`,
@@ -221,7 +227,13 @@ export class MiddlewareRunner<
         const result = await mw.onStructuredOutputConfig(ctx, current)
         const hasTransform = result !== undefined && result !== null
         if (hasTransform) {
-          current = { ...current, ...result }
+          current = {
+            ...current,
+            ...result,
+            ...('messages' in result && !('providerMessages' in result)
+              ? { providerMessages: result.messages }
+              : {}),
+          }
           if (!skip) {
             this.logger.config(
               `middleware=${mw.name ?? 'unnamed'} keys=${Object.keys(result).join(',')}`,

package/src/activities/chat/middleware/index.ts

@@ -67,6 +67,9 @@ export {
 } from './locks'
 export type { LockStore } from './locks'
 
+export { MetadataCapability, getMetadata, provideMetadata } from './metadata'
+export type { MetadataStore } from './metadata'
+
 export {
   isRunStatus,
   isTerminalRunStatus,

package/src/activities/chat/middleware/metadata.ts

@@ -0,0 +1,20 @@
+import { createCapability } from './capabilities'
+
+/**
+ * Namespaced key/value store for app and middleware metadata.
+ *
+ * `(namespace, key)` is the composite identity. Keep both values separate;
+ * joining them with a delimiter can create collisions.
+ */
+export interface MetadataStore {
+  /** Return the value for `(namespace, key)`, or `null` when it is absent. */
+  get: (namespace: string, key: string) => Promise<unknown | null>
+  /** Insert or replace the value for `(namespace, key)`. */
+  set: (namespace: string, key: string, value: unknown) => Promise<void>
+  /** Delete `(namespace, key)`. Do nothing when it is absent. */
+  delete: (namespace: string, key: string) => Promise<void>
+}
+
+export const MetadataCapability = createCapability<MetadataStore>()('metadata')
+
+export const [getMetadata, provideMetadata] = MetadataCapability

package/src/activities/chat/middleware/types.ts

@@ -213,6 +213,12 @@ export interface ChatMiddlewareContext<TContext = unknown> {
   signal?: AbortSignal
   /** Abort the chat run with a reason */
   abort: (reason?: string) => void
+  /**
+   * Push a `CUSTOM` chunk onto the chat stream immediately.
+   * The engine yields it as soon as it can (including while `onConfig`
+   * is still awaiting work such as a summarize call).
+   */
+  emitCustomEvent: (name: string, value: Record<string, any>) => void
   /** Runtime context provided by chat() options */
   context: TContext
   /**
@@ -305,7 +311,10 @@ export interface ChatMiddlewareContext<TContext = unknown> {
  * that middleware is allowed to modify.
  */
 export interface ChatMiddlewareConfig {
+  /** Canonical conversation history. Middleware and persistence read this. */
   messages: Array<ModelMessage>
+  /** Provider-only context. Defaults to `messages` when it is not set. */
+  providerMessages?: Array<ModelMessage> | undefined
   systemPrompts: Array<SystemPrompt>
   tools: Array<Tool>
   resume?: Array<RunAgentResumeItem> | undefined

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

@@ -212,6 +212,7 @@ export class StreamProcessor {
   private finishReason: string | null = null
   private hasError = false
   private isDone = false
+  private streamEndEmitted = false
 
   // Recording
   private recording: ChunkRecording | null = null
@@ -729,9 +730,26 @@ export class StreamProcessor {
         return id
       }
     }
+    // finalizeStream() clears activeMessageIds but keeps messageStates.
+    // Leftover reasoning after an early RUN_FINISHED must resume that
+    // assistant. A new user turn calls prepareAssistantMessage(), which
+    // clears messageStates first.
+    for (const [id, state] of [...this.messageStates].reverse()) {
+      if (state.role === 'assistant') {
+        return id
+      }
+    }
     return null
   }
 
+  private resumeAssistantState(id: string, state: MessageStreamState): void {
+    this.activeMessageIds.add(id)
+    if (state.isComplete || this.isDone) {
+      state.isComplete = false
+      this.isDone = false
+    }
+  }
+
   /**
    * Ensure an active assistant message exists, creating one if needed.
    * Used for backward compat when events arrive without prior TEXT_MESSAGE_START.
@@ -748,14 +766,20 @@ export class StreamProcessor {
     // Try to find state by preferred ID
     if (preferredId) {
       const state = this.getMessageState(preferredId)
-      if (state) return { messageId: preferredId, state }
+      if (state) {
+        this.resumeAssistantState(preferredId, state)
+        return { messageId: preferredId, state }
+      }
     }
 
     // Try active assistant message
     const activeId = this.getActiveAssistantMessageId()
     if (activeId) {
       const state = this.getMessageState(activeId)
-      if (state) return { messageId: activeId, state }
+      if (state) {
+        this.resumeAssistantState(activeId, state)
+        return { messageId: activeId, state }
+      }
     }
 
     // Check if a message with preferredId already exists (reconnect/resume case).
@@ -900,9 +924,21 @@ export class StreamProcessor {
       }
 
       // Ensure state exists
-      if (!this.messageStates.has(messageId)) {
-        this.createMessageState(messageId, uiRole)
+      let pendingState = this.messageStates.get(messageId)
+      if (!pendingState) {
+        pendingState = this.createMessageState(messageId, uiRole)
         this.activeMessageIds.add(messageId)
+      } else if (pendingState.hasToolCallsSinceTextStart) {
+        // A tool call (e.g. TOOL_CALL_START with parentMessageId) marked
+        // this message before its "real" TEXT_MESSAGE_START arrived — same
+        // reset Case 2 performs, so the segment accumulator doesn't carry
+        // stale tool-call state into the text that follows.
+        if (pendingState.currentSegmentText !== pendingState.lastEmittedText) {
+          this.emitTextUpdateForMessage(messageId)
+        }
+        pendingState.currentSegmentText = ''
+        pendingState.lastEmittedText = ''
+        pendingState.hasToolCallsSinceTextStart = false
       }
 
       this.mergeMessageMetadata(messageId, chunk.metadata)
@@ -1647,8 +1683,14 @@ export class StreamProcessor {
     }
 
     if (this.activeRuns.size === 0) {
-      this.isDone = true
       this.completeAllToolCalls()
+      const isIntermediateToolTurn =
+        this.finishReason === 'tool_calls' &&
+        chunk.outcome?.type !== 'interrupt'
+      if (isIntermediateToolTurn) {
+        return
+      }
+      this.isDone = true
       this.finalizeStream()
     }
   }
@@ -2344,6 +2386,7 @@ export class StreamProcessor {
    * @see docs/chat-architecture.md#single-shot-text-response — Finalization step
    */
   finalizeStream(): void {
+    this.isDone = true
     let lastAssistantMessage: UIMessage | undefined
 
     // Finalize ALL active messages
@@ -2407,7 +2450,8 @@ export class StreamProcessor {
     }
 
     // Emit stream end for the last assistant message
-    if (lastAssistantMessage) {
+    if (lastAssistantMessage && !this.streamEndEmitted) {
+      this.streamEndEmitted = true
       this.events.onStreamEnd?.(lastAssistantMessage)
     }
   }
@@ -2526,6 +2570,7 @@ export class StreamProcessor {
     this.finishReason = null
     this.hasError = false
     this.isDone = false
+    this.streamEndEmitted = false
     this.chunkStrategy.reset?.()
   }
 

package/src/activities/chat/tools/schema-converter.ts

@@ -99,6 +99,26 @@ function pruneMap(map: NullWideningMap): NullWideningMap | undefined {
   return Object.keys(map).length > 0 ? map : undefined
 }
 
+function coerceArrayItems(items: JSONSchema | Array<JSONSchema>): {
+  schema: JSONSchema | Array<JSONSchema>
+  itemMap: NullWideningMap | Array<NullWideningMap> | undefined
+} {
+  if (Array.isArray(items)) {
+    const nested = items.map((item) =>
+      makeStructuredOutputCompatible(item, item.required || []),
+    )
+    const itemMaps = nested.map((entry) => entry.nullWidening ?? {})
+    return {
+      schema: nested.map((entry) => entry.schema),
+      itemMap: itemMaps.some((entry) => Object.keys(entry).length > 0)
+        ? itemMaps
+        : undefined,
+    }
+  }
+  const nested = makeStructuredOutputCompatible(items, items.required || [])
+  return { schema: nested.schema, itemMap: nested.nullWidening }
+}
+
 /**
  * Transform a JSON schema to be compatible with OpenAI's structured output requirements.
  * OpenAI requires:
@@ -146,18 +166,15 @@ function makeStructuredOutputCompatible(
         widenedHere = wasOptional
         childMap = nested.nullWidening
       } else if (prop.type === 'array' && prop.items) {
-        const items = Array.isArray(prop.items) ? prop.items[0] : prop.items
-        const nestedItems = items
-          ? makeStructuredOutputCompatible(items, items.required || [])
-          : undefined
+        const nestedItems = coerceArrayItems(prop.items)
         properties[propName] = {
           ...prop,
-          items: nestedItems ? nestedItems.schema : prop.items,
+          items: nestedItems.schema,
           ...(wasOptional ? { type: ['array', 'null'] } : {}),
         }
         widenedHere = wasOptional
-        childMap = nestedItems?.nullWidening
-          ? { items: nestedItems.nullWidening }
+        childMap = nestedItems.itemMap
+          ? { items: nestedItems.itemMap }
           : undefined
       } else if (wasOptional) {
         // Make optional fields nullable by adding null to the type. Mark
@@ -188,17 +205,13 @@ function makeStructuredOutputCompatible(
     if (Object.keys(propertyMaps).length > 0) map.properties = propertyMaps
   }
 
-  // Handle array types with object items
+  // Handle array item schemas. A tuple (`items: [a, b, …]`) keeps every
+  // position. A homogeneous schema stays a single items map so
+  // `undoNullWidening` applies it to every element.
   if (result.type === 'array' && result.items) {
-    const items = Array.isArray(result.items) ? result.items[0] : result.items
-    if (items) {
-      const nestedItems = makeStructuredOutputCompatible(
-        items,
-        items.required || [],
-      )
-      result.items = nestedItems.schema
-      if (nestedItems.nullWidening) map.items = nestedItems.nullWidening
-    }
+    const nestedItems = coerceArrayItems(result.items)
+    result.items = nestedItems.schema
+    if (nestedItems.itemMap) map.items = nestedItems.itemMap
   }
 
   return { schema: result, nullWidening: pruneMap(map) }

package/src/index.ts

@@ -104,6 +104,8 @@ export type {
 // MCP error classes (value exports — usable with instanceof)
 export { MCPDuplicateToolNameError } from './activities/chat/mcp/manager'
 export { DuplicateToolNameError } from './activities/chat/tools/unique-tool-names'
+export { SkillLimitError } from './utilities/errors'
+export type { SkillLimitErrorInit } from './utilities/errors'
 
 // Schema conversion (Standard JSON Schema compliant)
 export {
@@ -281,6 +283,9 @@ export {
   createCapability,
   defineChatMiddleware,
   createChatMiddleware,
+  MetadataCapability,
+  getMetadata,
+  provideMetadata,
 } from './activities/chat/middleware/index'
 export type {
   Capability,
@@ -290,6 +295,7 @@ export type {
   CapabilityProvider,
   DefinedChatMiddleware,
   AnyChatMiddleware,
+  MetadataStore,
 } from './activities/chat/middleware/index'
 // Locks are a distributed-mutex primitive — coordination, not chat state — and
 // live behind their own subpath: `@tanstack/ai/locks` (see ./locks.ts).