@tanstack/ai-client 0.29.0 → 0.29.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-client",
-  "version": "0.29.0",
+  "version": "0.29.1",
   "description": "Framework-agnostic headless client for TanStack AI chat, realtime sessions, streaming transports, and media generations.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -53,8 +53,8 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/ai": "^0.50.0",
-    "@tanstack/ai-event-client": "^0.11.0",
+    "@tanstack/ai": "^0.51.0",
+    "@tanstack/ai-event-client": "^0.11.1",
     "@tanstack/ai-utils": "^0.4.0"
   },
   "devDependencies": {

package/src/chat-client.ts

@@ -164,6 +164,20 @@ function resolveTransport(transport: {
   throw new Error('ChatClient: either `connection` or `fetcher` is required.')
 }
 
+function connectionDrainsOnSend(connection: ConnectionAdapter): boolean {
+  return 'connect' in connection
+}
+
+function isIntermediateToolTurn(chunk: StreamChunk): boolean {
+  if (chunk.type !== 'RUN_FINISHED') return false
+  if (chunk.outcome?.type === 'interrupt') return false
+  const extra = chunk as StreamChunk & { finishReason?: unknown }
+  if (extra.finishReason !== undefined) {
+    return extra.finishReason === 'tool_calls'
+  }
+  return tanstackMetadata(chunk)?.finishReason === 'tool_calls'
+}
+
 export interface NormalizedQueueConfig {
   whenBusy: WhenBusy
   drain: 'fifo' | 'batch'
@@ -416,6 +430,12 @@ export class ChatClient<
   private continuationPending = false
   private subscriptionAbortController: AbortController | null = null
   private processingResolve: (() => void) | null = null
+  /**
+   * `connect()` adapters push the full HTTP body into the subscribe queue, then
+   * wait until that queue is idle. After `send()` returns, every chunk from this
+   * request has been processed. Subscribe/send sockets do not drain that way.
+   */
+  private connectionDrainsOnSend = false
   private errorReportedGeneration: number | null = null
   private streamGeneration = 0
   private continuationGeneration = 0
@@ -518,7 +538,9 @@ export class ChatClient<
     this.byokProvider = options.byokProvider
     this.context = options.context
     this.queueConfig = normalizeQueueOption(options.queue)
-    this.connection = normalizeConnectionAdapter(resolveTransport(options))
+    const transport = resolveTransport(options)
+    this.connectionDrainsOnSend = connectionDrainsOnSend(transport)
+    this.connection = normalizeConnectionAdapter(transport)
 
     // Build client tools map
     this.clientToolsRef = { current: new Map() }
@@ -829,6 +851,9 @@ export class ChatClient<
           if (eventType === 'memory:state') {
             this.devtoolsBridge.recordMemoryState(data)
           }
+          if (eventType === 'skills:state') {
+            this.devtoolsBridge.recordSkillsState(data)
+          }
           this.callbacksRef.current.onCustomEvent(eventType, data, context)
         },
       },
@@ -1140,7 +1165,9 @@ export class ChatClient<
       this.clearedStreamTracker.onSessionRunError()
     }
     this.setSessionGenerating(this.activeRunIds.size > 0)
-    if (options?.resolveProcessing !== false) {
+    const skipProcessingResolve =
+      chunk.type === 'RUN_FINISHED' && isIntermediateToolTurn(chunk)
+    if (options?.resolveProcessing !== false && !skipProcessingResolve) {
       this.resolveProcessing()
     }
   }
@@ -2344,6 +2371,14 @@ export class ChatClient<
         return false
       }
 
+      // connect() send() already waited until the subscribe queue was idle.
+      // Kick the processing wait so a stream that ends on tool_calls (no
+      // interrupt / stop) cannot hang. Subscribe/send sockets still wait for
+      // a request-ending terminal below.
+      if (this.connectionDrainsOnSend) {
+        this.resolveProcessing()
+      }
+
       // Wait for subscription loop to finish processing all chunks
       await processingComplete
 
@@ -3045,12 +3080,12 @@ export class ChatClient<
       this.resetSessionGenerating()
       this.setIsSubscribed(false)
       this.setConnectionStatus('disconnected')
-      this.connection = normalizeConnectionAdapter(
-        resolveTransport({
-          connection: options.connection,
-          fetcher: options.fetcher,
-        }),
-      )
+      const transport = resolveTransport({
+        connection: options.connection,
+        fetcher: options.fetcher,
+      })
+      this.connectionDrainsOnSend = connectionDrainsOnSend(transport)
+      this.connection = normalizeConnectionAdapter(transport)
 
       if (wasSubscribed) {
         this.subscribe()

package/src/connection-adapters.ts

@@ -1055,6 +1055,28 @@ export function normalizeConnectionAdapter(
     }
   }
 
+  async function waitUntilSubscriberIdle(
+    abortSignal?: AbortSignal,
+  ): Promise<void> {
+    // Idle means the subscriber is waiting for the next chunk, so the
+    // previous chunk has left processIncomingChunk. Empty waiters with an
+    // empty buffer is in-flight delivery, not idle.
+    const idle = () =>
+      activeBuffer.length === 0 &&
+      (activeWaiters.length > 0 || abortSignal?.aborted)
+    for (let i = 0; i < 16 && !abortSignal?.aborted; i++) {
+      if (idle()) return
+      await Promise.resolve()
+    }
+    let macrotaskWaits = 0
+    while (!abortSignal?.aborted) {
+      if (idle()) return
+      await new Promise<void>((resolve) => setTimeout(resolve, 0))
+      macrotaskWaits++
+      if (activeWaiters.length === 0 && macrotaskWaits >= 32) return
+    }
+  }
+
   return {
     subscribe(abortSignal?: AbortSignal): AsyncIterable<StreamChunk> {
       // Transfer ownership to the latest subscriber so only one active
@@ -1162,6 +1184,7 @@ export function normalizeConnectionAdapter(
         }
         throw err
       }
+      await waitUntilSubscriberIdle(abortSignal)
     },
     // Expose joinRun only when the underlying connection is resumable. Require
     // a real function — `'joinRun' in connection` is true for

package/src/devtools-noop.ts

@@ -87,6 +87,7 @@ export class NoOpChatDevtoolsBridge {
   }
   observeChunk(_chunk: StreamChunk): void {}
   recordMemoryState(_value: unknown): void {}
+  recordSkillsState(_value: unknown): void {}
   beginRun(_runId: string, _threadId: string): void {}
   getCurrentRunEventContext(): ChatClientRunEventContext | undefined {
     return undefined

package/src/devtools.ts

@@ -33,6 +33,11 @@ export interface AIDevtoolsDisplayOptions {
  * payload of the `memory:state` CUSTOM chunk. Kept local so `ai-client` doesn't
  * depend on `ai-memory`; the memory middleware is the producer.
  */
+interface SkillsStateEventValue {
+  catalog?: Array<{ name: string; description: string }>
+  activated?: Array<string>
+}
+
 interface MemoryStateEventValue {
   scope: MemoryScopeLite
   adapter: string
@@ -448,6 +453,49 @@ function getActiveBridgeRegistry(): Map<string, ActiveDevtoolsBridge> {
   return registry
 }
 
+/**
+ * `{...options}` turns `get hookId()` into a data property. Chat/generation
+ * clients mint `threadId` after construct (`ensureThreadId` on mount), so a
+ * spread would freeze `hookId: ''` and DevTools could never select the hook.
+ */
+function withLiveClientIdentity<TSnapshot extends object>(
+  identity: Pick<
+    AIDevtoolsBridgeOptions<TSnapshot>,
+    | 'hookId'
+    | 'clientId'
+    | 'threadId'
+    | 'metadata'
+    | 'getTools'
+    | 'applyToolFixture'
+  >,
+  rest: Pick<AIDevtoolsBridgeOptions<TSnapshot>, 'getSnapshot'> &
+    Partial<
+      Pick<AIDevtoolsBridgeOptions<TSnapshot>, 'getTools' | 'applyToolFixture'>
+    >,
+): AIDevtoolsBridgeOptions<TSnapshot> {
+  return {
+    get hookId() {
+      return identity.hookId
+    },
+    get clientId() {
+      return identity.clientId
+    },
+    get threadId() {
+      return identity.threadId
+    },
+    metadata: identity.metadata,
+    getSnapshot: rest.getSnapshot,
+    ...(rest.getTools || identity.getTools
+      ? { getTools: rest.getTools ?? identity.getTools }
+      : {}),
+    ...(rest.applyToolFixture || identity.applyToolFixture
+      ? {
+          applyToolFixture: rest.applyToolFixture ?? identity.applyToolFixture,
+        }
+      : {}),
+  }
+}
+
 export class ClientDevtoolsBridge<TSnapshot extends object> {
   protected readonly options: AIDevtoolsBridgeOptions<TSnapshot>
   private readonly unsubscribers: Array<Unsubscribe> = []
@@ -712,6 +760,7 @@ export class ClientDevtoolsBridge<TSnapshot extends object> {
       | 'memory:retrieve:started'
       | 'memory:retrieve:completed'
       | 'memory:snapshot'
+      | 'skills:snapshot'
       | AIDevtoolsRunEventType,
     visibility: AIDevtoolsEventVisibility = 'client-state',
     context: { runId?: string } = {},
@@ -770,17 +819,24 @@ export class ChatDevtoolsBridge extends ClientDevtoolsBridge<AIDevtoolsChatSnaps
   private lastRunEventContext: ChatClientRunEventContext | undefined
   /** Last transported `memory:state` value, replayed when a panel opens. */
   private lastMemoryStateValue: unknown = null
+  /** Last transported `skills:state` value, replayed when a panel opens. */
+  private lastSkillsStateValue: unknown = null
 
   constructor(options: ChatDevtoolsBridgeOptions) {
-    super({
-      ...options,
-      // Thunk defers `this.applyFixture` lookup until after `super` returns.
-      applyToolFixture: (fixture) => this.applyFixture(fixture),
-    })
+    super(
+      withLiveClientIdentity(options, {
+        getSnapshot: options.getSnapshot,
+        // Thunk defers `this.applyFixture` lookup until after `super` returns.
+        applyToolFixture: (fixture) => this.applyFixture(fixture),
+      }),
+    )
     this.chatOptions = options
     // Auto-attaches run/thread context and auto-emits a snapshot after each
     // event so callers can keep using `this.events.X(...)` with no context arg.
-    this.events = new ChatDevtoolsAwareEventEmitter(options.clientId, this)
+    this.events = new ChatDevtoolsAwareEventEmitter(
+      () => options.clientId,
+      this,
+    )
   }
 
   // --- Stream / run context API -------------------------------------------
@@ -874,6 +930,11 @@ export class ChatDevtoolsBridge extends ClientDevtoolsBridge<AIDevtoolsChatSnaps
     this.emitMemoryState(rawValue)
   }
 
+  recordSkillsState(rawValue: unknown): void {
+    this.lastSkillsStateValue = rawValue
+    this.emitSkillsState(rawValue)
+  }
+
   /**
    * Re-emit the browser-side `memory:*` events from a transported
    * `memory:state` value. The devtools store consumes these to render the
@@ -926,10 +987,26 @@ export class ChatDevtoolsBridge extends ClientDevtoolsBridge<AIDevtoolsChatSnaps
     }
   }
 
+  private emitSkillsState(rawValue: unknown): void {
+    if (!rawValue || typeof rawValue !== 'object') return
+    const value = rawValue as SkillsStateEventValue
+    const catalog = Array.isArray(value.catalog) ? value.catalog : []
+    const activated = Array.isArray(value.activated) ? value.activated : []
+    const runContext = this.currentRunId ? { runId: this.currentRunId } : {}
+    emitAIDevtoolsEvent('skills:snapshot', {
+      ...this.createEnvelope('skills:snapshot', 'client-state', runContext),
+      catalog,
+      activated,
+    })
+  }
+
   protected override onReplayState(): void {
     if (this.lastMemoryStateValue != null) {
       this.emitMemoryState(this.lastMemoryStateValue)
     }
+    if (this.lastSkillsStateValue != null) {
+      this.emitSkillsState(this.lastSkillsStateValue)
+    }
   }
 
   getCurrentRunEventContext(): ChatClientRunEventContext | undefined {
@@ -1410,10 +1487,11 @@ export class GenerationDevtoolsBridge<TOutput> extends ClientDevtoolsBridge<
   protected readonly getCoreState: () => GenerationDevtoolsCoreState<TOutput>
 
   constructor(options: GenerationDevtoolsBridgeOptions<TOutput>) {
-    super({
-      ...options,
-      getSnapshot: () => this.buildSnapshot(),
-    })
+    super(
+      withLiveClientIdentity(options, {
+        getSnapshot: () => this.buildSnapshot(),
+      }),
+    )
     this.maxRuns = options.maxRuns ?? 20
     this.getCoreState = options.getCoreState
   }
@@ -1759,10 +1837,18 @@ export class VideoDevtoolsBridge<
 // so resolveStreamId() works without the chat client telling it.
 class ChatDevtoolsAwareEventEmitter extends DefaultChatClientEventEmitter {
   constructor(
-    clientId: string,
+    private readonly getClientId: () => string,
     private readonly helper: ChatDevtoolsBridge,
   ) {
-    super(clientId)
+    super(getClientId())
+  }
+
+  protected override emitEvent(
+    eventName: string,
+    data?: Record<string, any>,
+  ): void {
+    this.clientId = this.getClientId()
+    super.emitEvent(eventName, data)
   }
 
   private afterEmit(streamId?: string): void {