@tanstack/ai-client 0.11.8 → 0.13.0

package/src/connection-adapters.ts

@@ -1,10 +1,49 @@
 import { EventType, uiMessagesToWire } from '@tanstack/ai'
-import type { ModelMessage, StreamChunk, UIMessage } from '@tanstack/ai'
+import type {
+  ModelMessage,
+  RunErrorEvent,
+  RunFinishedEvent,
+  StreamChunk,
+  UIMessage,
+} from '@tanstack/ai'
+import type { ChatFetcher } from './types'
+
+/**
+ * Thrown when an SSE/HTTP stream ends with a non-empty unterminated buffer.
+ * Indicates the connection was cut mid-line (server crash, dropped TCP, proxy
+ * timeout) so the partial content cannot be safely parsed.
+ */
+export class StreamTruncatedError extends Error {
+  constructor() {
+    super(
+      'Stream ended with unterminated trailing data — connection was likely cut short.',
+    )
+    this.name = 'StreamTruncatedError'
+  }
+}
 
 function generateRunId(prefix: string): string {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
 }
 
+/**
+ * Asserts an id is present when synthesizing a terminal event. The chat
+ * client always supplies `runContext.threadId` / `runContext.runId`, so an
+ * absent id at this layer indicates the adapter was wired up by a caller
+ * that bypassed that contract — surface it rather than fabricating one.
+ */
+function requireSyntheticId(
+  value: string | undefined,
+  field: 'threadId' | 'runId',
+): string {
+  if (!value) {
+    throw new Error(
+      `Cannot synthesize terminal event: ${field} not supplied via runContext and not observed in the upstream stream.`,
+    )
+  }
+  return value
+}
+
 /**
  * Merge custom headers into request headers
  */
@@ -52,15 +91,83 @@ async function* readStreamLines(
       }
     }
 
-    // Process any remaining data in the buffer
-    if (buffer.trim()) {
-      yield buffer
+    // A non-empty trailing buffer means the connection was cut mid-line.
+    // Surface this as an error so the chat client transitions to 'error'
+    // state instead of silently presenting a partial stream as success.
+    // Skip when the consumer aborted — a user-initiated stop() interrupting
+    // mid-line is expected, not a truncation bug.
+    if (buffer.trim() && !abortSignal?.aborted) {
+      throw new StreamTruncatedError()
     }
   } finally {
     reader.releaseLock()
   }
 }
 
+/**
+ * Yield StreamChunks parsed from an SSE Response body.
+ *
+ * Accepts either `data: {...}` lines or bare JSON lines. Skips comments
+ * starting with `:` (proxies and CDNs inject these as keepalives) and the
+ * `event:` / `id:` / `retry:` SSE control fields. A `[DONE]` sentinel is
+ * treated as a terminal event: a synthesized RUN_FINISHED is yielded using
+ * the most recent upstream `threadId` / `runId`, ensuring the consumer sees
+ * a clean terminal event with real correlation ids.
+ *
+ * A JSON parse failure throws — the consumer surfaces it as an error.
+ */
+async function* responseToSSEChunks(
+  response: Response,
+  abortSignal?: AbortSignal,
+): AsyncGenerator<StreamChunk> {
+  if (!response.ok) {
+    throw new Error(
+      `HTTP error! status: ${response.status} ${response.statusText}`,
+    )
+  }
+  const reader = response.body?.getReader()
+  if (!reader) {
+    throw new Error('Response body is not readable')
+  }
+  let lastThreadId: string | undefined
+  let lastRunId: string | undefined
+  let lastModel: string | undefined
+  for await (const line of readStreamLines(reader, abortSignal)) {
+    if (
+      line.startsWith(':') ||
+      line.startsWith('event:') ||
+      line.startsWith('id:') ||
+      line.startsWith('retry:')
+    ) {
+      continue
+    }
+    const data = line.startsWith('data: ') ? line.slice(6) : line
+    if (data === '[DONE]') {
+      const synthetic: RunFinishedEvent = {
+        type: EventType.RUN_FINISHED,
+        threadId: lastThreadId ?? '',
+        runId: lastRunId ?? '',
+        model: lastModel ?? '',
+        timestamp: Date.now(),
+        finishReason: 'stop',
+      }
+      yield synthetic
+      return
+    }
+    const chunk = JSON.parse(data) as StreamChunk
+    if ('threadId' in chunk && typeof chunk.threadId === 'string') {
+      lastThreadId = chunk.threadId
+    }
+    if ('runId' in chunk && typeof chunk.runId === 'string') {
+      lastRunId = chunk.runId
+    }
+    if ('model' in chunk && typeof chunk.model === 'string') {
+      lastModel = chunk.model
+    }
+    yield chunk
+  }
+}
+
 /**
  * Per-send context provided by the chat client to the connection adapter.
  * The adapter combines this with serialized messages to build a full
@@ -196,6 +303,8 @@ export function normalizeConnectionAdapter(
     },
     async send(messages, data, abortSignal, runContext) {
       let hasTerminalEvent = false
+      let upstreamThreadId: string | undefined
+      let upstreamRunId: string | undefined
       try {
         const stream = connection.connect(
           messages,
@@ -204,6 +313,12 @@ export function normalizeConnectionAdapter(
           runContext,
         )
         for await (const chunk of stream) {
+          if ('threadId' in chunk && typeof chunk.threadId === 'string') {
+            upstreamThreadId = chunk.threadId
+          }
+          if ('runId' in chunk && typeof chunk.runId === 'string') {
+            upstreamRunId = chunk.runId
+          }
           if (chunk.type === 'RUN_FINISHED' || chunk.type === 'RUN_ERROR') {
             hasTerminalEvent = true
           }
@@ -214,31 +329,40 @@ export function normalizeConnectionAdapter(
         // synthesize RUN_FINISHED so request-scoped consumers can complete.
         // Reuse the caller's threadId/runId so client-side activeRunIds tracking matches.
         if (!abortSignal?.aborted && !hasTerminalEvent) {
-          push({
+          const synthetic: RunFinishedEvent = {
             type: EventType.RUN_FINISHED,
-            threadId: runContext?.threadId ?? `thread-${Date.now()}`,
-            runId: runContext?.runId ?? `run-${Date.now()}`,
+            threadId: requireSyntheticId(
+              upstreamThreadId ?? runContext?.threadId,
+              'threadId',
+            ),
+            runId: requireSyntheticId(
+              upstreamRunId ?? runContext?.runId,
+              'runId',
+            ),
             model: 'connect-wrapper',
             timestamp: Date.now(),
             finishReason: 'stop',
-          })
+          }
+          push(synthetic)
         }
       } catch (err) {
         if (!abortSignal?.aborted && !hasTerminalEvent) {
-          push({
+          const message =
+            err instanceof Error ? err.message : 'Unknown error in connect()'
+          const synthetic: RunErrorEvent = {
             type: EventType.RUN_ERROR,
-            threadId: runContext?.threadId ?? `thread-${Date.now()}`,
-            runId: runContext?.runId ?? `run-${Date.now()}`,
+            threadId: requireSyntheticId(
+              upstreamThreadId ?? runContext?.threadId,
+              'threadId',
+            ),
+            runId: requireSyntheticId(
+              upstreamRunId ?? runContext?.runId,
+              'runId',
+            ),
             timestamp: Date.now(),
-            message:
-              err instanceof Error ? err.message : 'Unknown error in connect()',
-            error: {
-              message:
-                err instanceof Error
-                  ? err.message
-                  : 'Unknown error in connect()',
-            },
-          })
+            message,
+          }
+          push(synthetic)
         }
         throw err
       }
@@ -358,37 +482,7 @@ export function fetchServerSentEvents(
         ...(signal ? { signal } : {}),
       })
 
-      if (!response.ok) {
-        throw new Error(
-          `HTTP error! status: ${response.status} ${response.statusText}`,
-        )
-      }
-
-      // Parse Server-Sent Events format
-      const reader = response.body?.getReader()
-      if (!reader) {
-        throw new Error('Response body is not readable')
-      }
-
-      for await (const line of readStreamLines(reader, abortSignal)) {
-        // Handle Server-Sent Events format
-        const data = line.startsWith('data: ') ? line.slice(6) : line
-
-        if (data === '[DONE]') {
-          console.warn(
-            '[@tanstack/ai-client] Received [DONE] sentinel. This is deprecated — upgrade your @tanstack/ai server package. RUN_FINISHED is the stream terminator.',
-          )
-          continue
-        }
-
-        try {
-          const parsed: StreamChunk = JSON.parse(data)
-          yield parsed
-        } catch (parseError) {
-          // Skip non-JSON lines or malformed chunks
-          console.warn('Failed to parse SSE chunk:', data)
-        }
-      }
+      yield* responseToSSEChunks(response, abortSignal)
     },
   }
 }
@@ -507,12 +601,7 @@ export function fetchHttpStream(
       }
 
       for await (const line of readStreamLines(reader, abortSignal)) {
-        try {
-          const parsed: StreamChunk = JSON.parse(line)
-          yield parsed
-        } catch (parseError) {
-          console.warn('Failed to parse HTTP stream chunk:', line)
-        }
+        yield JSON.parse(line) as StreamChunk
       }
     },
   }
@@ -536,17 +625,92 @@ export function stream(
   streamFactory: (
     messages: Array<UIMessage> | Array<ModelMessage>,
     data?: Record<string, any>,
+    abortSignal?: AbortSignal,
   ) => AsyncIterable<StreamChunk>,
 ): ConnectConnectionAdapter {
   return {
-    async *connect(messages, data, _abortSignal, _runContext) {
+    async *connect(messages, data, abortSignal) {
       // Pass messages as-is (UIMessages with parts preserved)
       // Server-side chat() handles conversion to ModelMessages
-      yield* streamFactory(messages, data)
+      yield* streamFactory(messages, data, abortSignal)
+    },
+  }
+}
+
+/**
+ * Wrap a `ChatFetcher` as a `ConnectConnectionAdapter` so the chat client can
+ * consume it through the same `subscribe`/`send` plumbing used for SSE /
+ * HTTP-stream / RPC connections. May return either a `Response` (parsed as
+ * SSE) or an `AsyncIterable<StreamChunk>` (yielded directly).
+ *
+ * @internal
+ */
+export function fetcherToConnectionAdapter(
+  fetcher: ChatFetcher,
+): ConnectConnectionAdapter {
+  return {
+    async *connect(messages, data, abortSignal, runContext) {
+      if (!abortSignal) {
+        throw new Error(
+          'fetcherToConnectionAdapter requires an AbortSignal — the chat client always supplies one.',
+        )
+      }
+      if (!runContext) {
+        throw new Error(
+          'fetcherToConnectionAdapter requires a RunAgentInputContext — the chat client always supplies one.',
+        )
+      }
+      const uiMessages = messages as Array<UIMessage>
+      const result = await fetcher(
+        {
+          messages: uiMessages,
+          data,
+          threadId: runContext.threadId,
+          runId: runContext.runId,
+        },
+        { signal: abortSignal },
+      )
+      if (result instanceof Response) {
+        yield* responseToSSEChunks(result, abortSignal)
+      } else {
+        yield* abortableIterable(result, abortSignal)
+      }
     },
   }
 }
 
+/**
+ * Wrap an AsyncIterable so iteration aborts when `signal` fires. Without
+ * this, a fetcher that returns a generator ignoring its signal would leave
+ * the for-await loop hanging until the iterable naturally ends.
+ */
+async function* abortableIterable<T>(
+  iterable: AsyncIterable<T>,
+  signal: AbortSignal,
+): AsyncGenerator<T> {
+  if (signal.aborted) return
+  const iterator = iterable[Symbol.asyncIterator]()
+  const abortPromise = new Promise<{ done: true; value: undefined }>(
+    (resolve) => {
+      signal.addEventListener(
+        'abort',
+        () => resolve({ done: true, value: undefined }),
+        { once: true },
+      )
+    },
+  )
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+      const result = await Promise.race([iterator.next(), abortPromise])
+      if (result.done) return
+      yield result.value
+    }
+  } finally {
+    await iterator.return?.()
+  }
+}
+
 /**
  * Create an RPC stream connection adapter (for RPC-based streaming like Cap'n Web RPC)
  *
@@ -567,13 +731,14 @@ export function rpcStream(
   rpcCall: (
     messages: Array<UIMessage> | Array<ModelMessage>,
     data?: Record<string, any>,
+    abortSignal?: AbortSignal,
   ) => AsyncIterable<StreamChunk>,
 ): ConnectConnectionAdapter {
   return {
-    async *connect(messages, data, _abortSignal, _runContext) {
+    async *connect(messages, data, abortSignal) {
       // Pass messages as-is (UIMessages with parts preserved)
       // Server-side chat() handles conversion to ModelMessages
-      yield* rpcCall(messages, data)
+      yield* rpcCall(messages, data, abortSignal)
     },
   }
 }

package/src/devtools-noop.ts

@@ -0,0 +1,205 @@
+// No-op devtools bridge implementations + factories. The chat / generation /
+// video clients import the real bridge classes as types only and accept a
+// factory in options; when no factory is supplied they fall back to the
+// no-op factories here, which never touch `aiEventClient` or any of the
+// heavy preview/fixture machinery in `./devtools`. This keeps `./devtools`
+// outside the main-entry import graph — consumers opt into functional
+// devtools via `@tanstack/ai-client/devtools` (see `package.json#exports`).
+import { ChatClientEventEmitter } from './events'
+import type {
+  AIDevtoolsToolFixture,
+  ChatDevtoolsBridge,
+  ChatDevtoolsBridgeOptions,
+  GenerationDevtoolsBridge,
+  GenerationDevtoolsBridgeOptions,
+  VideoDevtoolsBridge,
+  VideoDevtoolsBridgeOptions,
+} from './devtools'
+import type { StreamChunk } from '@tanstack/ai'
+import type {
+  ChatClientEventContext,
+  ChatClientRunEventContext,
+} from './events'
+
+export type ChatDevtoolsBridgeFactory = (
+  options: ChatDevtoolsBridgeOptions,
+) => ChatDevtoolsBridge
+
+export type GenerationDevtoolsBridgeFactory = <TOutput>(
+  options: GenerationDevtoolsBridgeOptions<TOutput>,
+) => GenerationDevtoolsBridge<TOutput>
+
+export type VideoDevtoolsBridgeFactory = <TOutput>(
+  options: VideoDevtoolsBridgeOptions<TOutput>,
+) => VideoDevtoolsBridge<TOutput>
+
+// ===========================================================================
+// No-op event emitter — extends the abstract base so it satisfies the type
+// without dragging in any of the event-bus runtime cost.
+// ===========================================================================
+
+class NoOpChatClientEventEmitter extends ChatClientEventEmitter {
+  protected emitEvent(): void {
+    // intentionally empty
+  }
+}
+
+// ===========================================================================
+// No-op bridges. Methods exist to satisfy the structural shape of the real
+// classes; every emit/record call short-circuits.
+// ===========================================================================
+
+export class NoOpChatDevtoolsBridge {
+  readonly events: ChatClientEventEmitter
+
+  constructor(options: ChatDevtoolsBridgeOptions) {
+    this.events = new NoOpChatClientEventEmitter(options.clientId)
+  }
+
+  // base bridge surface
+  emitRegistered(): void {}
+  emitUpdated(): void {}
+  emitSnapshot(): void {}
+  emitToolsRegistered(): void {}
+  emitRunLifecycle(
+    _eventType: unknown,
+    _runId: string,
+    _status: unknown,
+    _options?: { error?: string },
+  ): void {}
+  deactivate(): void {}
+  supersede(): void {}
+  dispose(): void {}
+
+  // chat-specific surface
+  setCurrentStreamId(_streamId: string | null): void {}
+  getCurrentStreamId(): string | null {
+    return null
+  }
+  getLastStreamId(): string | null {
+    return null
+  }
+  resolveStreamId(): string {
+    return ''
+  }
+  observeChunk(_chunk: StreamChunk): void {}
+  beginRun(_runId: string, _threadId: string): void {}
+  getCurrentRunEventContext(): ChatClientRunEventContext | undefined {
+    return undefined
+  }
+  getCurrentOrLastRunEventContext(): ChatClientRunEventContext | undefined {
+    return undefined
+  }
+  findToolCallContext(toolCallId: string): ChatClientEventContext {
+    return { toolCallId }
+  }
+  async applyFixture(_fixture: AIDevtoolsToolFixture): Promise<void> {
+    // intentionally empty
+  }
+}
+
+export class NoOpGenerationDevtoolsBridge<TOutput> {
+  constructor(_options: GenerationDevtoolsBridgeOptions<TOutput>) {}
+
+  // base bridge surface
+  emitRegistered(): void {}
+  emitUpdated(): void {}
+  emitSnapshot(): void {}
+  emitToolsRegistered(): void {}
+  emitRunLifecycle(): void {}
+  deactivate(): void {}
+  supersede(): void {}
+  dispose(): void {}
+
+  // generation-specific surface
+  beginRun(_input: unknown): string {
+    // Real factories supply a stable id; the no-op still returns a
+    // unique value because the generation client passes this run id to
+    // the adapter's RunAgentInputContext.
+    return `noop-run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  }
+  ensureRunStarted(_runId: string): void {}
+  finishRun(
+    _runId: string,
+    _eventType: 'run:completed' | 'run:errored' | 'run:cancelled',
+    _status: 'completed' | 'errored' | 'cancelled',
+    _error?: string,
+  ): void {}
+  getActiveRunId(): string | null {
+    return null
+  }
+  resetRuns(): void {}
+  recordResultChange(): void {}
+  recordLoadingChange(): void {}
+  recordErrorChange(_error: Error | undefined): void {}
+  recordStatusChange(): void {}
+  recordProgressChange(): void {}
+  emitState(): void {}
+}
+
+export class NoOpVideoDevtoolsBridge<
+  TOutput,
+> extends NoOpGenerationDevtoolsBridge<TOutput> {
+  constructor(options: VideoDevtoolsBridgeOptions<TOutput>) {
+    super(options)
+  }
+
+  recordJobIdChange(): void {}
+  recordVideoStatusChange(): void {}
+}
+
+// Compile-time parity checks. If a public method is added to the real
+// bridge class without a matching stub on the no-op, the corresponding
+// `Exclude<...>` will resolve to a non-`never` union and the `as never`
+// assignment below will fail to typecheck — surfacing the drift at build
+// time instead of as a runtime TypeError later.
+type _ChatBridgeMissing = Exclude<
+  keyof ChatDevtoolsBridge,
+  keyof NoOpChatDevtoolsBridge
+>
+type _GenerationBridgeMissing = Exclude<
+  keyof GenerationDevtoolsBridge<unknown>,
+  keyof NoOpGenerationDevtoolsBridge<unknown>
+>
+type _VideoBridgeMissing = Exclude<
+  keyof VideoDevtoolsBridge<unknown>,
+  keyof NoOpVideoDevtoolsBridge<unknown>
+>
+const _chatBridgeParity: _ChatBridgeMissing = undefined as never
+const _generationBridgeParity: _GenerationBridgeMissing = undefined as never
+const _videoBridgeParity: _VideoBridgeMissing = undefined as never
+void _chatBridgeParity
+void _generationBridgeParity
+void _videoBridgeParity
+
+// ===========================================================================
+// Factories — these are what the clients call when no real factory was
+// supplied in options.
+// ===========================================================================
+
+// Casts use `unknown` because the no-op classes don't `extend` the real bridge
+// (that would pull the real implementation into the main-entry import graph).
+// Structural parity is enforced by the `_*BridgeMissing` checks above.
+
+export const createNoOpChatDevtoolsBridge: ChatDevtoolsBridgeFactory = (
+  options,
+) =>
+  // eslint-disable-next-line no-restricted-syntax -- see comment above
+  new NoOpChatDevtoolsBridge(options) as unknown as ChatDevtoolsBridge
+
+export const createNoOpGenerationDevtoolsBridge: GenerationDevtoolsBridgeFactory =
+  <TOutput>(options: GenerationDevtoolsBridgeOptions<TOutput>) =>
+    // eslint-disable-next-line no-restricted-syntax -- see comment above
+    new NoOpGenerationDevtoolsBridge<TOutput>(
+      options,
+    ) as unknown as GenerationDevtoolsBridge<TOutput>
+
+export const createNoOpVideoDevtoolsBridge: VideoDevtoolsBridgeFactory = <
+  TOutput,
+>(
+  options: VideoDevtoolsBridgeOptions<TOutput>,
+) =>
+  // eslint-disable-next-line no-restricted-syntax -- see comment above
+  new NoOpVideoDevtoolsBridge<TOutput>(
+    options,
+  ) as unknown as VideoDevtoolsBridge<TOutput>