@vellumai/assistant 0.12.1 → 0.12.2-dev.202609162214.308bda0

package/src/runtime/routes/oauth-commands-routes.ts

@@ -20,7 +20,10 @@ import {
   type Services,
   ServicesSchema,
 } from "../../config/schemas/services.js";
-import type { OAuthConnectionRequest } from "../../oauth/connection.js";
+import type {
+  OAuthConnectionRequest,
+  OAuthConnectionResponse,
+} from "../../oauth/connection.js";
 import {
   isBinaryOAuthBody,
   jsonSafeOAuthBody,
@@ -30,6 +33,7 @@ import {
   type ResolveOAuthConnectionOptions,
   resolveOAuthConnectionWithMeta,
 } from "../../oauth/connection-resolver.js";
+import { providerReportsFailure } from "../../oauth/identity-verifier.js";
 import { syncManualTokenConnection } from "../../oauth/manual-token-connection.js";
 import {
   disconnectOAuthProvider,
@@ -41,9 +45,11 @@ import {
   listConnections,
   type OAuthProviderRow,
 } from "../../oauth/oauth-store.js";
+import { missingScopesForStoredToken } from "../../oauth/scope-utils.js";
 import { VellumPlatformClient } from "../../platform/client.js";
 import { withValidToken } from "../../security/token-manager.js";
 import { matchHostPattern } from "../../tools/credentials/host-pattern-match.js";
+import { parseJsonSafe } from "../../util/json.js";
 import { getLogger } from "../../util/logger.js";
 import {
   findContentTypeHeader,
@@ -52,6 +58,7 @@ import {
 } from "../../util/oauth-request-body.js";
 import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
+import { composeRequestHint } from "./oauth-request-hints.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("oauth-commands-routes");
@@ -64,6 +71,7 @@ interface PlatformConnectionEntry {
   id: string;
   account_label?: string;
   scopes_granted?: string[];
+  provider_params?: Record<string, string> | null;
   status?: string;
 }
 
@@ -230,6 +238,52 @@ function assertOAuthRequestUrlAllowed(
   }
 }
 
+/**
+ * The verdict on a provider exchange: whether the status said success, and
+ * whether the provider's declared ok field (`responseOkField`) then took it
+ * back. The field is read only under a 2xx, so a 429 or 5xx whose body
+ * happens to carry it stays a transport failure rather than a refusal.
+ * `reportedFailure` is the one-line account of a refusal, absent otherwise.
+ */
+function judgeProviderResponse(
+  providerRow: OAuthProviderRow,
+  response: OAuthConnectionResponse,
+): { ok: boolean; reportedFailure?: string } {
+  const httpOk = response.status >= 200 && response.status < 300;
+  if (httpOk && providerReportsFailure(providerRow, response.body)) {
+    return {
+      ok: false,
+      reportedFailure: `${providerRow.provider} answered HTTP ${response.status} but reported ${providerRow.responseOkField}: false`,
+    };
+  }
+  return { ok: httpOk };
+}
+
+/**
+ * Required scopes the resolved connection's stored grant lacks. Credential
+ * health measures the same thing on the heartbeat; measuring it on the
+ * request names the gap at the moment a call may depend on it, since a
+ * connection made before a scope was required keeps working for every call
+ * that does not need it. A managed connection has no local row and reports
+ * nothing.
+ */
+function missingScopesForConnection(
+  providerRow: OAuthProviderRow,
+  connectionId: string,
+): string[] {
+  const row = getConnection(connectionId);
+  if (!row) {
+    return [];
+  }
+  return missingScopesForStoredToken(
+    parseJsonSafe<string[]>(providerRow.defaultScopes ?? "[]") ?? [],
+    parseJsonSafe<Record<string, string>>(providerRow.authorizeParams ?? "") ??
+      undefined,
+    providerRow.scopeSeparator,
+    parseJsonSafe<string[]>(row.grantedScopes ?? "[]") ?? [],
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Disconnect handler
 // ---------------------------------------------------------------------------
@@ -547,6 +601,9 @@ async function handleStatus({ queryParams = {} }: RouteHandlerArgs) {
       account: c.account_label ?? null,
       grantedScopes: c.scopes_granted ?? [],
       status: c.status ?? "ACTIVE",
+      // Values the provider scopes the connection by (QuickBooks' realm id),
+      // so a caller can address resources the proxy's base URL does not.
+      providerParams: c.provider_params ?? {},
     }));
 
     return {
@@ -658,7 +715,8 @@ async function handlePing({ body = {} }: RouteHandlerArgs) {
     ...(pingBody !== undefined ? { body: pingBody } : {}),
   });
 
-  if (response.status >= 200 && response.status < 300) {
+  const verdict = judgeProviderResponse(providerRow, response);
+  if (verdict.ok) {
     return { ok: true, provider: b.provider, status: response.status };
   }
 
@@ -666,10 +724,21 @@ async function handlePing({ body = {} }: RouteHandlerArgs) {
     ok: false,
     provider: b.provider,
     status: response.status,
-    error: `Ping failed with HTTP ${response.status}`,
+    error: verdict.reportedFailure
+      ? `Ping failed: ${verdict.reportedFailure}`
+      : `Ping failed with HTTP ${response.status}`,
   };
+  if (verdict.reportedFailure) {
+    payload.body = response.body;
+  }
 
-  if (response.status === 401 || response.status === 403) {
+  // A provider that refuses the ping inside a 2xx is refusing the credential
+  // the same way a 401 does.
+  if (
+    response.status === 401 ||
+    response.status === 403 ||
+    verdict.reportedFailure
+  ) {
     payload.hint =
       `Run 'assistant oauth status ${b.provider}' to check connection health. ` +
       `To reconnect, run 'assistant oauth connect --help'.`;
@@ -947,8 +1016,10 @@ export async function handleRequest({ body = {} }: RouteHandlerArgs) {
   const response = await connection.request(req);
   const encodedBody = jsonSafeOAuthBody(response.body);
 
+  const verdict = judgeProviderResponse(providerRow, response);
+
   const result: Record<string, unknown> = {
-    ok: response.status >= 200 && response.status < 300,
+    ok: verdict.ok,
     status: response.status,
     headers: response.headers,
     body: encodedBody.body,
@@ -970,51 +1041,23 @@ export async function handleRequest({ body = {} }: RouteHandlerArgs) {
       `used "${selected}". Pass --account to select a specific one.`;
   }
 
-  if (response.status === 401 || response.status === 403) {
-    // The recovery steps follow the credential's kind, not the door the
-    // request came through: a channel bot's token was stored by the channel's
-    // setup, so the OAuth status and connect commands cannot repair it.
-    const botChannel = channelForBotProvider(b.provider);
-    result.hint = botChannel
-      ? `Request returned HTTP ${response.status}. The ${botChannel} bot credential was rejected; it may have been revoked or reinstalled with fewer scopes.\n\n` +
-        `Run 'assistant channels get ${botChannel}' to re-probe the channel and see what it reports.\n` +
-        `To reconnect, run the channel's setup skill again.`
-      : managed
-        ? `Request returned HTTP ${response.status}. The OAuth token may be expired or revoked.\n\n` +
-          `Run 'assistant oauth status ${b.provider}' to check connection health.\n` +
-          `To reconnect, run 'assistant oauth connect --help'.`
-        : `Request returned HTTP ${response.status}. The OAuth token may be expired or revoked.\n\n` +
-          `Run 'assistant oauth status ${b.provider}' to check connection status.\n` +
-          `To reconnect, run 'assistant oauth connect --help'.`;
-  } else if (response.status === 404 && isHtmlResponse(response.headers)) {
-    // An HTML 404 (rather than a JSON API error) is the signature of a request
-    // reaching a valid host but a path that host does not serve — e.g. a
-    // relative path resolved against a base URL that points at the wrong
-    // product. Surface the resolved base so the caller can tell where the path
-    // landed, and steer them to an absolute URL for non-default services.
-    const resolvedBaseUrl =
-      baseUrl ?? providerRow.baseUrl ?? "(none configured)";
-    result.hint =
-      `Request returned HTTP ${response.status} with an HTML body, which usually means ` +
-      `the path does not exist on the base URL it resolved against.\n\n` +
-      `This request used base URL "${resolvedBaseUrl}" (relative paths are joined onto it). ` +
-      `If you meant a different service on this provider, pass an absolute URL ` +
-      `(e.g. https://host/full/path) so the host and full path are set explicitly.`;
+  const hint = composeRequestHint({
+    provider: b.provider,
+    status: response.status,
+    headers: response.headers,
+    reportedFailure: verdict.reportedFailure,
+    botChannel: channelForBotProvider(b.provider),
+    managed,
+    resolvedBaseUrl: baseUrl ?? providerRow.baseUrl ?? undefined,
+    missingScopes: missingScopesForConnection(providerRow, connection.id),
+  });
+  if (hint) {
+    result.hint = hint;
   }
 
   return result;
 }
 
-/** True when the response's Content-Type header indicates an HTML body. */
-function isHtmlResponse(headers: Record<string, string>): boolean {
-  for (const [key, value] of Object.entries(headers)) {
-    if (key.toLowerCase() === "content-type") {
-      return value.toLowerCase().includes("text/html");
-    }
-  }
-  return false;
-}
-
 // ---------------------------------------------------------------------------
 // Connect handler (managed path for platform OAuth)
 // ---------------------------------------------------------------------------
@@ -1024,6 +1067,8 @@ async function handleManagedConnect({ body = {} }: RouteHandlerArgs) {
     provider: string;
     scopes?: string[];
     redirect_after_connect?: string;
+    /** Per-tenant providers (Shopify): the customer's own host. */
+    tenant_host?: string;
   };
 
   if (!b.provider) {
@@ -1040,6 +1085,13 @@ async function handleManagedConnect({ body = {} }: RouteHandlerArgs) {
   }
   reqBody.redirect_after_connect =
     b.redirect_after_connect ?? "/account/oauth/complete";
+  // Only forwarded when present: the platform validates it against the
+  // provider's pattern and rejects per-tenant providers that omit it.
+  const tenantHost =
+    typeof b.tenant_host === "string" ? b.tenant_host.trim() : "";
+  if (tenantHost) {
+    reqBody.tenant_host = tenantHost;
+  }
 
   const response = await client.fetch(startPath, {
     method: "POST",
@@ -1086,6 +1138,7 @@ async function handleManagedConnectPoll({
       id: e.id,
       account_label: e.account_label ?? null,
       scopes_granted: e.scopes_granted ?? [],
+      provider_params: e.provider_params ?? {},
     })),
   };
 }

package/src/runtime/routes/oauth-providers.ts

@@ -176,6 +176,7 @@ function handleRegisterProvider({ body = {} }: RouteHandlerArgs) {
         (b.identity_response_paths as string[]) ?? undefined,
       identityFormat: (b.identity_format as string) ?? undefined,
       identityOkField: (b.identity_ok_field as string) ?? undefined,
+      responseOkField: (b.response_ok_field as string) ?? undefined,
       setupNotes: (b.setup_notes as string[]) ?? undefined,
     });
 
@@ -312,6 +313,9 @@ function handleUpdateProvider({
   if (b.identity_ok_field !== undefined) {
     params.identityOkField = b.identity_ok_field;
   }
+  if (b.response_ok_field !== undefined) {
+    params.responseOkField = b.response_ok_field;
+  }
   if (b.setup_notes !== undefined) {
     params.setupNotes = b.setup_notes;
   }
@@ -397,6 +401,13 @@ export const oauthProviderSummarySchema = z.object({
   supports_managed_mode: z.boolean(),
   managed_service_is_paid: z.boolean(),
   feature_flag: z.string().nullable(),
+  tenant_host: z
+    .object({
+      pattern: z.string(),
+      label: z.string(),
+      placeholder: z.string(),
+    })
+    .nullable(),
   acts_as: z.enum(["user", "assistant"]),
 });
 

package/src/runtime/routes/oauth-request-hints.test.ts

@@ -0,0 +1,246 @@
+/**
+ * The request doors' hint, asserted on the composer directly. Every case
+ * pins the rendered text in full, so a wording change is a visible diff here
+ * and never a silent one behind a route test's substring match.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+  composeRequestHint,
+  REQUEST_HINT_RULES,
+  type RequestHintFacts,
+} from "./oauth-request-hints.js";
+
+const JSON_HEADERS = { "content-type": "application/json" };
+const HTML_HEADERS = { "content-type": "text/html; charset=utf-8" };
+
+function asBot(overrides: Partial<RequestHintFacts> = {}): RequestHintFacts {
+  return {
+    provider: "slack_channel",
+    status: 200,
+    headers: JSON_HEADERS,
+    botChannel: "slack",
+    managed: false,
+    resolvedBaseUrl: "https://slack.com/api",
+    missingScopes: [],
+    ...overrides,
+  };
+}
+
+function asPerson(overrides: Partial<RequestHintFacts> = {}): RequestHintFacts {
+  return {
+    provider: "google",
+    status: 200,
+    headers: JSON_HEADERS,
+    managed: false,
+    resolvedBaseUrl: "https://api.google.com",
+    missingScopes: [],
+    ...overrides,
+  };
+}
+
+describe("composeRequestHint", () => {
+  test("the rules are applied in this precedence order", () => {
+    // The generic 401/403 rule matches every 403, so the HTML 403 rule has
+    // to be judged before it; a provider's own reported failure outranks
+    // every status. The list is the order, and this pins it.
+    expect(REQUEST_HINT_RULES.map((rule) => rule.name)).toEqual([
+      "provider reported failure",
+      "resource not visible",
+      "credential rejected",
+      "path not served",
+    ]);
+  });
+
+  test("a 2xx is silent", () => {
+    expect(composeRequestHint(asBot())).toBeUndefined();
+    expect(composeRequestHint(asPerson())).toBeUndefined();
+  });
+
+  test("a provider's reported failure names only why the 2xx failed", () => {
+    expect(
+      composeRequestHint(
+        asBot({
+          reportedFailure:
+            "slack_channel answered HTTP 200 but reported ok: false",
+        }),
+      ),
+    ).toBe(
+      "slack_channel answered HTTP 200 but reported ok: false in the response body. The body names the error.",
+    );
+  });
+
+  test("a reported failure outranks every status rule", () => {
+    expect(
+      composeRequestHint(
+        asBot({
+          status: 403,
+          headers: HTML_HEADERS,
+          reportedFailure:
+            "slack_channel answered HTTP 403 but reported ok: false",
+        }),
+      ),
+    ).toBe(
+      "slack_channel answered HTTP 403 but reported ok: false in the response body. The body names the error.",
+    );
+  });
+
+  test("an HTML 403 as a bot names the resource's access and the channel's diagnostics", () => {
+    expect(
+      composeRequestHint(
+        asBot({
+          status: 403,
+          headers: HTML_HEADERS,
+          resolvedBaseUrl: "https://files.slack.com",
+        }),
+      ),
+    ).toBe(
+      "Request returned HTTP 403 with an HTML page from files.slack.com, not an API error. " +
+        "That usually means the slack bot cannot see this resource: it is not shared with it, or the scope it needs is missing. " +
+        "Check the resource's access before treating the credential as revoked; " +
+        "'assistant channels get slack' reports the credential itself.",
+    );
+  });
+
+  test("an HTML 403 as a person names the connected account and oauth status", () => {
+    expect(
+      composeRequestHint(asPerson({ status: 403, headers: HTML_HEADERS })),
+    ).toBe(
+      "Request returned HTTP 403 with an HTML page from api.google.com, not an API error. " +
+        "That usually means the connected account cannot see this resource: it is not shared with it, or the scope it needs is missing. " +
+        "Check the resource's access before treating the credential as revoked; " +
+        "'assistant oauth status google' reports the credential itself.",
+    );
+  });
+
+  test("an HTML 403 with no resolved base omits the host", () => {
+    expect(
+      composeRequestHint(
+        asPerson({
+          status: 403,
+          headers: HTML_HEADERS,
+          resolvedBaseUrl: undefined,
+        }),
+      ),
+    ).toBe(
+      "Request returned HTTP 403 with an HTML page, not an API error. " +
+        "That usually means the connected account cannot see this resource: it is not shared with it, or the scope it needs is missing. " +
+        "Check the resource's access before treating the credential as revoked; " +
+        "'assistant oauth status google' reports the credential itself.",
+    );
+  });
+
+  test("a JSON 403 keeps the credential reading on any host", () => {
+    // An API's own refusal, on the base host or on a provider's other API
+    // hosts alike.
+    const onApiHost = composeRequestHint(asBot({ status: 403 }));
+    expect(onApiHost).toContain("slack bot credential was rejected");
+    expect(onApiHost).not.toContain("cannot see this resource");
+
+    const onOtherApiHost = composeRequestHint(
+      asPerson({
+        status: 403,
+        resolvedBaseUrl: "https://calendar.googleapis.com",
+      }),
+    );
+    expect(onOtherApiHost).toContain(
+      "The OAuth token may be expired or revoked",
+    );
+    expect(onOtherApiHost).not.toContain("cannot see this resource");
+  });
+
+  test("a rejected bot credential points at the channel's diagnostics, never the OAuth commands", () => {
+    expect(composeRequestHint(asBot({ status: 401 }))).toBe(
+      "Request returned HTTP 401. The slack bot credential was rejected; it may have been revoked or reinstalled with fewer scopes.\n\n" +
+        "Run 'assistant channels get slack' to re-probe the channel and see what it reports.\n" +
+        "To reconnect, run the channel's setup skill again.",
+    );
+  });
+
+  test("a rejected managed credential points at connection health", () => {
+    expect(composeRequestHint(asPerson({ status: 403, managed: true }))).toBe(
+      "Request returned HTTP 403. The OAuth token may be expired or revoked.\n\n" +
+        "Run 'assistant oauth status google' to check connection health.\n" +
+        "To reconnect, run 'assistant oauth connect --help'.",
+    );
+  });
+
+  test("a rejected your-own credential points at connection status", () => {
+    expect(composeRequestHint(asPerson({ status: 401 }))).toBe(
+      "Request returned HTTP 401. The OAuth token may be expired or revoked.\n\n" +
+        "Run 'assistant oauth status google' to check connection status.\n" +
+        "To reconnect, run 'assistant oauth connect --help'.",
+    );
+  });
+
+  test("an HTML 404 reports the base the path resolved against", () => {
+    expect(
+      composeRequestHint(asPerson({ status: 404, headers: HTML_HEADERS })),
+    ).toBe(
+      "Request returned HTTP 404 with an HTML body, which usually means " +
+        "the path does not exist on the base URL it resolved against.\n\n" +
+        'This request used base URL "https://api.google.com" (relative paths are joined onto it). ' +
+        "If you meant a different service on this provider, pass an absolute URL " +
+        "(e.g. https://host/full/path) so the host and full path are set explicitly.",
+    );
+  });
+
+  test("an HTML 404 with no base says so", () => {
+    expect(
+      composeRequestHint(
+        asPerson({
+          status: 404,
+          headers: HTML_HEADERS,
+          resolvedBaseUrl: undefined,
+        }),
+      ),
+    ).toContain('This request used base URL "(none configured)"');
+  });
+
+  test("a JSON 404 and every other status are silent", () => {
+    expect(composeRequestHint(asPerson({ status: 404 }))).toBeUndefined();
+    expect(composeRequestHint(asPerson({ status: 429 }))).toBeUndefined();
+    expect(composeRequestHint(asPerson({ status: 500 }))).toBeUndefined();
+  });
+
+  test("the Content-Type check is case-insensitive on key and value", () => {
+    expect(
+      composeRequestHint(
+        asPerson({ status: 404, headers: { "Content-Type": "TEXT/HTML" } }),
+      ),
+    ).toContain("with an HTML body");
+  });
+
+  test("a missing-scope hint stands alone on a successful call", () => {
+    expect(
+      composeRequestHint(
+        asPerson({ provider: "slack", missingScopes: ["files:read"] }),
+      ),
+    ).toBe(
+      "The slack connection is missing required scopes: files:read. " +
+        "It was connected before they were required, so calls that need them fail. " +
+        "Reconnect it from Integrations, or run 'assistant oauth connect slack', to grant them.",
+    );
+  });
+
+  test("a missing-scope hint is prepended to the status hint", () => {
+    expect(
+      composeRequestHint(
+        asPerson({
+          provider: "slack",
+          status: 401,
+          missingScopes: ["files:read", "search:read"],
+        }),
+      ),
+    ).toBe(
+      "The slack connection is missing required scopes: files:read, search:read. " +
+        "It was connected before they were required, so calls that need them fail. " +
+        "Reconnect it from Integrations, or run 'assistant oauth connect slack', to grant them." +
+        "\n\n" +
+        "Request returned HTTP 401. The OAuth token may be expired or revoked.\n\n" +
+        "Run 'assistant oauth status slack' to check connection status.\n" +
+        "To reconnect, run 'assistant oauth connect --help'.",
+    );
+  });
+});

package/src/runtime/routes/oauth-request-hints.ts

@@ -0,0 +1,149 @@
+/**
+ * The hint the request doors attach to a provider response, composed from
+ * the response and the connection facts alone. The route gathers the facts;
+ * nothing here reads a store, a config, or a connection, so a hint's wording
+ * is assertable without booting the route.
+ *
+ * The status hints are an ordered list and the first rule that applies wins.
+ * The order is precedence, not coincidence: a provider's own reported failure
+ * outranks every status, and an HTML 403 must be judged before the generic
+ * 401/403 rule or it is never reached. The missing-scope hint is not a rule
+ * in the list; it is prepended to whichever hint applied, or stands alone.
+ */
+
+export interface RequestHintFacts {
+  /** The provider key the request was made under. */
+  provider: string;
+  status: number;
+  headers: Record<string, string>;
+  /**
+   * The provider's own one-line account of a refusal inside a 2xx, from its
+   * declared ok field; absent when the status is the whole verdict.
+   */
+  reportedFailure?: string;
+  /**
+   * The channel whose bot credential served the request. Absent when the
+   * request acted as a person through their OAuth integration.
+   */
+  botChannel?: string;
+  /** The provider runs in platform-managed mode. */
+  managed: boolean;
+  /**
+   * The base URL the request resolved against: an absolute URL's own origin,
+   * otherwise the provider's configured base. Absent when neither is set.
+   */
+  resolvedBaseUrl?: string;
+  /** Required scopes the resolved connection's stored grant lacks. */
+  missingScopes: readonly string[];
+}
+
+interface RequestHintRule {
+  name: string;
+  applies(facts: RequestHintFacts): boolean;
+  render(facts: RequestHintFacts): string;
+}
+
+/** The status hints in precedence order; the first rule that applies wins. */
+export const REQUEST_HINT_RULES: readonly RequestHintRule[] = [
+  {
+    // The body carries the provider's own error code, so the hint says only
+    // why a 2xx is being reported as a failure.
+    name: "provider reported failure",
+    applies: (facts) => facts.reportedFailure !== undefined,
+    render: (facts) =>
+      `${facts.reportedFailure} in the response body. The body names the error.`,
+  },
+  {
+    // An API refuses with JSON. A 403 carrying an HTML page is a resource
+    // host (a file host, a sign-in page) refusing this identity: the same
+    // token is what the API accepts, and the resource is simply not visible
+    // to it. Blaming the credential sends the caller off to reconnect one
+    // that works.
+    name: "resource not visible",
+    applies: (facts) => facts.status === 403 && isHtmlResponse(facts.headers),
+    render: (facts) => {
+      const identity = facts.botChannel
+        ? `${facts.botChannel} bot`
+        : "connected account";
+      const requestHost = hostnameOf(facts.resolvedBaseUrl);
+      return (
+        `Request returned HTTP 403 with an HTML page${requestHost ? ` from ${requestHost}` : ""}, not an API error. ` +
+        `That usually means the ${identity} cannot see this resource: it is not shared with it, or the scope it needs is missing. ` +
+        `Check the resource's access before treating the credential as revoked; ` +
+        (facts.botChannel
+          ? `'assistant channels get ${facts.botChannel}' reports the credential itself.`
+          : `'assistant oauth status ${facts.provider}' reports the credential itself.`)
+      );
+    },
+  },
+  {
+    // The recovery steps follow the credential's kind, not the door the
+    // request came through: a channel bot's token was stored by the channel's
+    // setup, so the OAuth status and connect commands cannot repair it.
+    name: "credential rejected",
+    applies: (facts) => facts.status === 401 || facts.status === 403,
+    render: (facts) =>
+      facts.botChannel
+        ? `Request returned HTTP ${facts.status}. The ${facts.botChannel} bot credential was rejected; it may have been revoked or reinstalled with fewer scopes.\n\n` +
+          `Run 'assistant channels get ${facts.botChannel}' to re-probe the channel and see what it reports.\n` +
+          `To reconnect, run the channel's setup skill again.`
+        : facts.managed
+          ? `Request returned HTTP ${facts.status}. The OAuth token may be expired or revoked.\n\n` +
+            `Run 'assistant oauth status ${facts.provider}' to check connection health.\n` +
+            `To reconnect, run 'assistant oauth connect --help'.`
+          : `Request returned HTTP ${facts.status}. The OAuth token may be expired or revoked.\n\n` +
+            `Run 'assistant oauth status ${facts.provider}' to check connection status.\n` +
+            `To reconnect, run 'assistant oauth connect --help'.`,
+  },
+  {
+    // An HTML 404 (rather than a JSON API error) is the signature of a request
+    // reaching a valid host but a path that host does not serve, such as a
+    // relative path resolved against a base URL that points at the wrong
+    // product. Surface the resolved base so the caller can tell where the path
+    // landed, and steer them to an absolute URL for non-default services.
+    name: "path not served",
+    applies: (facts) => facts.status === 404 && isHtmlResponse(facts.headers),
+    render: (facts) =>
+      `Request returned HTTP ${facts.status} with an HTML body, which usually means ` +
+      `the path does not exist on the base URL it resolved against.\n\n` +
+      `This request used base URL "${facts.resolvedBaseUrl ?? "(none configured)"}" (relative paths are joined onto it). ` +
+      `If you meant a different service on this provider, pass an absolute URL ` +
+      `(e.g. https://host/full/path) so the host and full path are set explicitly.`,
+  },
+];
+
+/**
+ * The hint for one provider response, or undefined when nothing applies.
+ * A missing-scope hint is prepended to the status hint, or stands alone: a
+ * connection made before a scope was required keeps working for every call
+ * that does not need it, so the gap is named on every request.
+ */
+export function composeRequestHint(
+  facts: RequestHintFacts,
+): string | undefined {
+  const hint = REQUEST_HINT_RULES.find((rule) => rule.applies(facts))?.render(
+    facts,
+  );
+  if (facts.missingScopes.length === 0) {
+    return hint;
+  }
+  const scopeHint =
+    `The ${facts.provider} connection is missing required scopes: ${facts.missingScopes.join(", ")}. ` +
+    `It was connected before they were required, so calls that need them fail. ` +
+    `Reconnect it from Integrations, or run 'assistant oauth connect ${facts.provider}', to grant them.`;
+  return hint ? `${scopeHint}\n\n${hint}` : scopeHint;
+}
+
+/** True when the response's Content-Type header indicates an HTML body. */
+function isHtmlResponse(headers: Record<string, string>): boolean {
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === "content-type") {
+      return value.toLowerCase().includes("text/html");
+    }
+  }
+  return false;
+}
+
+function hostnameOf(url: string | undefined): string | undefined {
+  return url && URL.canParse(url) ? new URL(url).hostname : undefined;
+}