fix(core): explain ChatGPT token-sharing errors (#52158)

packages/core/src/session/to-session-error.ts

@@ -7,6 +7,22 @@ import { AgentNotFoundError, StepFailedError } from "./error.js"
 import { ModelResolver } from "../model-resolver.js"
 import { SessionRunnerModel } from "./runner/model.js"
 
+const tokenSharingMessages = {
+  subscription_sharing_v2_user_not_eligible:
+    "ChatGPT token sharing isn't available for this account. Connect with an API key or choose another provider.",
+  subscription_sharing_usage_limit_exceeded:
+    "ChatGPT usage limit reached. Try again after your allowance resets; check ChatGPT Settings → Usage for details.",
+  subscription_sharing_usage_unavailable: "ChatGPT usage can't be checked right now. Try again later.",
+  subscription_sharing_unsupported_capability:
+    "This request uses a feature ChatGPT token sharing doesn't support. Remove the unsupported feature and try again.",
+  subscription_sharing_v2_client_not_enabled:
+    "This ChatGPT client isn't enabled for token sharing. Contact the app maintainer or choose another connection.",
+  subscription_sharing_v2_route_not_supported:
+    "ChatGPT token sharing doesn't support this API route. Check the configured endpoint and HTTP method.",
+  subscription_sharing_v2_invalid_user: "This ChatGPT connection is no longer valid. Reconnect to ChatGPT.",
+  subscription_sharing_v2_user_unavailable: "Your ChatGPT account is temporarily unavailable. Try again later.",
+}
+
 export function toSessionError(cause: unknown): SessionError.Error {
   if (cause instanceof AIError) {
     switch (cause.reason._tag) {
@@ -71,7 +87,7 @@ function providerError(type: string, reason: AIError["reason"]): SessionError.Er
   const status = reason.http?.status
   return {
     type,
-    message: reason.message,
+    message: Object.entries(tokenSharingMessages).find(([code]) => reason.body?.includes(code))?.[1] ?? reason.message,
     ...(status === undefined ? {} : { status }),
     ...(reason.body === undefined ? {} : { response: { body: reason.body } }),
   }

packages/core/test/session-error.test.ts

@@ -136,6 +136,29 @@ describe("toSessionError", () => {
     })
   })
 
+  test("maps token-sharing failures while preserving HTTP and stream bodies", () => {
+    const cases = [
+      ["subscription_sharing_v2_user_not_eligible", "token sharing isn't available for this account"],
+      ["subscription_sharing_usage_limit_exceeded", "ChatGPT usage limit reached"],
+      ["subscription_sharing_usage_unavailable", "Try again later"],
+      ["subscription_sharing_unsupported_capability", "Remove the unsupported feature"],
+      ["subscription_sharing_v2_client_not_enabled", "Contact the app maintainer"],
+      ["subscription_sharing_v2_route_not_supported", "Check the configured endpoint"],
+      ["subscription_sharing_v2_invalid_user", "Reconnect to ChatGPT"],
+      ["subscription_sharing_v2_user_unavailable", "Try again later"],
+    ] as const
+    for (const [code, guidance] of cases) {
+      for (const body of [
+        JSON.stringify({ error: { code, message: "Request failed" } }),
+        JSON.stringify({ type: "response.failed", response: { error: { code, message: "Request failed" } } }),
+      ]) {
+        const error = toSessionError(llm(new UnknownProviderError({ message: "Request failed", body })))
+        expect(error.message).toContain(guidance)
+        expect(error.response).toEqual({ body })
+      }
+    }
+  })
+
   test("preserves unresolved provider endpoint errors", () => {
     const error = new ModelResolver.UnresolvedProviderVariablesError({
       providerID: Provider.ID.make("cloudflare-workers-ai"),