@vellumai/assistant 0.12.2 → 0.12.3-staging.1

package/src/runtime/routes/inbound-stages/background-dispatch.ts

@@ -105,8 +105,11 @@ export interface BackgroundProcessingParams {
   chatType?: string;
   /** IANA timezone reported by the active client for the current turn. */
   clientTimezone?: string;
-  /** Slack app_mention/direct bot mention signal from the gateway. */
-  slackBotMentioned?: boolean;
+  /**
+   * The message addresses the assistant by name, as stated by the channel
+   * (`sourceMetadata.botMentioned`). Absent means not established.
+   */
+  botMentioned?: boolean;
   /**
    * Slack-specific inbound metadata extracted at the HTTP boundary. Threaded
    * through to `persistUserMessage` so the row can be tagged with a
@@ -166,7 +169,7 @@ export function processChannelMessageInBackground(
     sourceLanguageCode,
     chatType,
     clientTimezone,
-    slackBotMentioned,
+    botMentioned,
     slackInbound,
     channelInbound,
     slackReactionRowMeta,
@@ -204,7 +207,7 @@ export function processChannelMessageInBackground(
       initiatorUserId: slackInbound?.actorExternalUserId,
       startImmediately: shouldShowActivityImmediately({
         chatType,
-        botMentioned: slackBotMentioned,
+        botMentioned,
       }),
     });
     const stopApprovalWatcher = replyCallbackUrl

package/src/runtime/routes/inference-profile-session-handler.ts

@@ -16,6 +16,10 @@ import { randomUUID } from "node:crypto";
 
 import { getUserSelectableProfilesForProvider } from "../../config/default-profile-catalog.js";
 import { loadConfig } from "../../config/loader.js";
+import {
+  nonTextConversationProfileMessage,
+  profileSupportsTextGeneration,
+} from "../../config/profile-text-generation.js";
 import { findConversation } from "../../daemon/conversation-registry.js";
 import {
   getConversation,
@@ -163,10 +167,16 @@ export async function setInferenceProfileSession({
     );
   }
 
+  const selectable = profiles as Record<string, unknown>;
+  const selected = selectable[profile] as Record<string, unknown>;
+  if (!profileSupportsTextGeneration(selected, selectable)) {
+    throw new BadRequestError(nonTextConversationProfileMessage(profile));
+  }
+
   // Pinning a profile that provably cannot dispatch turns the next turn in
   // this conversation into a hard failure, so refuse the pin the same way the
   // active-profile setter does.
-  const entry = profiles[profile] as Record<string, unknown>;
+  const entry = selected;
   const availability = await computeProfileAvailability(entry);
   if (isUnavailable(availability)) {
     throw new BadRequestError(

package/src/runtime/routes/inference-profiles-routes.ts

@@ -29,6 +29,10 @@ import {
   getConfigReadOnly,
   loadRawConfig,
 } from "../../config/loader.js";
+import {
+  nonTextConversationProfileMessage,
+  profileSupportsTextGeneration,
+} from "../../config/profile-text-generation.js";
 import {
   ProfileEntry,
   routingIdentityModelIssue,
@@ -891,6 +895,11 @@ async function handleSetActiveProfile({ body = {} }: RouteHandlerArgs) {
       `Profile "${name}" is disabled and cannot be set as the active profile. Enable it first, or pick another.`,
     );
   }
+  if (
+    !profileSupportsTextGeneration(entry, effective as Record<string, unknown>)
+  ) {
+    throw new BadRequestError(nonTextConversationProfileMessage(name));
+  }
   // No escape hatch here: an active profile that cannot dispatch locks the
   // user out of chat entirely, and nothing about the write signals that.
   await guardProfileAvailability({

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,
@@ -54,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");
@@ -233,6 +238,27 @@ 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
@@ -689,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 };
   }
 
@@ -697,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'.`;
@@ -978,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,
@@ -1001,60 +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 missingScopes = missingScopesForConnection(providerRow, connection.id);
-  if (missingScopes.length > 0) {
-    const scopeHint =
-      `The ${b.provider} connection is missing required scopes: ${missingScopes.join(", ")}. ` +
-      `It was connected before they were required, so calls that need them fail. ` +
-      `Reconnect it from Integrations, or run 'assistant oauth connect ${b.provider}', to grant them.`;
-    result.hint = result.hint ? `${scopeHint}\n\n${result.hint}` : scopeHint;
+  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)
 // ---------------------------------------------------------------------------

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;
   }

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;
+}