Handle provider errors gracefully in AI service streaming

Author: hotlong

packages/services/service-ai/src/adapters/vercel-adapter.ts

@@ -116,8 +116,17 @@ export class VercelLLMAdapter implements LLMAdapter {
       ...buildVercelOptions(options),
     });
 
-    for await (const part of result.fullStream) {
-      yield part as TextStreamPart<ToolSet>;
+    try {
+      for await (const part of result.fullStream) {
+        yield part as TextStreamPart<ToolSet>;
+      }
+    } catch (err) {
+      // Convert provider errors into a typed `error` part so the encoder can
+      // surface them to the client instead of leaving the SSE stream open.
+      yield {
+        type: 'error',
+        error: err instanceof Error ? err : new Error(String(err)),
+      } as unknown as TextStreamPart<ToolSet>;
     }
   }
 

packages/services/service-ai/src/plugin.ts

@@ -131,11 +131,24 @@ export class AIServicePlugin implements Plugin {
       if (process.env[envKey]) {
         try {
           const mod = await import(/* webpackIgnore: true */ pkg);
-          const createModel = mod[factory] ?? mod.default;
-          if (typeof createModel === 'function') {
+          const provider = mod[factory] ?? mod.default;
+          if (typeof provider === 'function') {
             const modelId = process.env.AI_MODEL ?? defaultModel;
-            const adapter = new VercelLLMAdapter({ model: createModel(modelId) });
-            return { adapter, description: `${displayName} (model: ${modelId})` };
+            // For OpenAI, prefer the Chat Completions API (`openai.chat(...)`)
+            // over the new Responses API. The Responses endpoint
+            // (`/v1/responses`) is not supported by common reverse proxies
+            // such as the Vercel AI Gateway, Cloudflare AI Gateway, or
+            // Azure-style OpenAI deployments — calling it returns 403
+            // Forbidden and the chat completion silently fails. The Chat
+            // Completions endpoint (`/v1/chat/completions`) is the
+            // industry-standard contract every gateway supports.
+            const useChatApi = factory === 'openai' && typeof (provider as any).chat === 'function';
+            const model = useChatApi
+              ? (provider as any).chat(modelId)
+              : provider(modelId);
+            const adapter = new VercelLLMAdapter({ model });
+            const apiSuffix = useChatApi ? ' [chat-completions]' : '';
+            return { adapter, description: `${displayName} (model: ${modelId})${apiSuffix}` };
           }
         } catch (err) {
           ctx.logger.warn(

packages/services/service-ai/src/routes/assistant-routes.ts

@@ -258,7 +258,14 @@ export function buildAssistantRoutes(
             '[AI Route] /assistant/chat error',
             err instanceof Error ? err : undefined,
           );
-          return { status: 500, body: { error: 'Internal AI service error' } };
+          // Surface a brief upstream message so the client UI can render it
+          // instead of an opaque "Internal AI service error". Stack traces
+          // stay in the logger.
+          const upstreamMsg = err instanceof Error ? err.message : String(err);
+          return {
+            status: 500,
+            body: { error: 'Internal AI service error', detail: upstreamMsg },
+          };
         }
       },
     },

packages/services/service-ai/src/stream/vercel-stream-encoder.ts

@@ -118,35 +118,64 @@ export async function* encodeVercelDataStream(
 
   let textOpen = true;
   let finishReason = 'stop';
+  let errorMessage: string | undefined;
+
+  try {
+    for await (const part of events) {
+      // Surface error parts emitted by the underlying provider stream.
+      if ((part as { type: string }).type === 'error') {
+        const errPart = part as unknown as { error?: unknown };
+        const raw = errPart.error;
+        errorMessage =
+          (raw && typeof raw === 'object' && 'message' in raw
+            ? String((raw as { message: unknown }).message)
+            : typeof raw === 'string'
+              ? raw
+              : 'Unknown provider error');
+        finishReason = 'error';
+        break;
+      }
 
-  for await (const part of events) {
-    // Capture finish reason
-    if (part.type === 'finish') {
-      finishReason = part.finishReason ?? 'stop';
-    }
+      // Capture finish reason
+      if (part.type === 'finish') {
+        finishReason = part.finishReason ?? 'stop';
+      }
 
-    // Before finish-step/finish, close the text part first
-    if (part.type === 'finish-step' || part.type === 'finish') {
-      if (textOpen) {
-        yield sse({ type: 'text-end', id: '0' });
-        textOpen = false;
+      // Before finish-step/finish, close the text part first
+      if (part.type === 'finish-step' || part.type === 'finish') {
+        if (textOpen) {
+          yield sse({ type: 'text-end', id: '0' });
+          textOpen = false;
+        }
+        // Don't emit these via encodeStreamPart — we handle them in postamble
+        continue;
       }
-      // Don't emit these via encodeStreamPart — we handle them in postamble
-      continue;
-    }
 
-    const frame = encodeStreamPart(part);
-    if (frame) {
-      yield frame;
+      const frame = encodeStreamPart(part);
+      if (frame) {
+        yield frame;
+      }
     }
+  } catch (err) {
+    // Upstream provider threw (auth failure, network error, etc.). Without
+    // this catch the SSE response would hang half-open and the client would
+    // never leave its "streaming" state.
+    errorMessage = err instanceof Error ? err.message : String(err);
+    finishReason = 'error';
   }
 
   // Close text if still open (safety)
   if (textOpen) {
     yield sse({ type: 'text-end', id: '0' });
   }
 
-  // Postamble
+  // If we recorded an error, emit it as a UI Message Stream `error` part so
+  // the client can display it instead of spinning forever.
+  if (errorMessage) {
+    yield sse({ type: 'error', errorText: errorMessage });
+  }
+
+  // Postamble — always emit so the client transitions out of "streaming".
   yield sse({ type: 'finish-step' });
   yield sse({ type: 'finish', finishReason });
   yield 'data: [DONE]\n\n';