@vellumai/assistant 0.12.2 → 0.12.3-staging.2

package/src/runtime/routes/migration-routes.ts

@@ -20,11 +20,13 @@ import { createReadStream } from "node:fs";
 import { hostname } from "node:os";
 import { PassThrough, Readable } from "node:stream";
 
+import { GatewayDebugExportIpcResponseSchema } from "@vellumai/gateway-client/gateway-ipc-contracts";
 import { z } from "zod";
 
 import { invalidateConfigCache } from "../../config/loader.js";
 import { resolvePlatformAssistantId } from "../../config/platform-identity.js";
 import { getAssistantName } from "../../daemon/identity-helpers.js";
+import { ipcCallPersistent } from "../../ipc/gateway-client.js";
 import { runAsyncSqlite } from "../../persistence/db-async-query.js";
 import {
   getDb,
@@ -470,8 +472,40 @@ const EXPORT_TO_GCS_PUT_TIMEOUT_MS = 60 * 60 * 1000;
 const MigrationExportToGcsBody = z.object({
   upload_url: z.string().url(),
   description: z.string().optional(),
+  /**
+   * `debug`: a bundle for Vellum staff to inspect. Adds the gateway's
+   * database and recent logs under `gateway/`. `migration` is the default.
+   */
+  profile: z.enum(["migration", "debug"]).default("migration"),
 });
 
+/** Archive path of the gateway's contribution to a debug bundle. */
+export const GATEWAY_DEBUG_EXPORT_PATH = "gateway/export.tar.gz";
+
+/**
+ * Ask the gateway for its debug archive over the local socket. The daemon
+ * cannot read the gateway's files itself: in local mode they sit in the
+ * protected directory beside the encryption keys, and in Docker on a volume
+ * the daemon does not mount.
+ */
+async function collectGatewayDebugExport(): Promise<{
+  archivePath: string;
+  data: Uint8Array;
+}> {
+  const raw = await ipcCallPersistent(
+    "gateway_debug_export",
+    {},
+    GATEWAY_DEBUG_EXPORT_TIMEOUT_MS,
+  );
+  const parsed = GatewayDebugExportIpcResponseSchema.parse(raw);
+  return {
+    archivePath: GATEWAY_DEBUG_EXPORT_PATH,
+    data: new Uint8Array(Buffer.from(parsed.archive_base64, "base64")),
+  };
+}
+
+const GATEWAY_DEBUG_EXPORT_TIMEOUT_MS = 120_000;
+
 /**
  * Collected credentials plus warning markers if the credential store was
  * unreachable. The caller surfaces the warning in logs; production callers
@@ -559,9 +593,10 @@ export async function handleMigrationExportToGcs({ body }: RouteHandlerArgs) {
   const parsed = MigrationExportToGcsBody.safeParse(body);
   if (!parsed.success) {
     throw new BadRequestError(
-      "Request body must be { upload_url: string, description?: string } with a valid URL",
+      "Request body must be { upload_url: string, description?: string, profile?: 'migration' | 'debug' } with a valid URL",
     );
   }
+  const isDebugProfile = parsed.data.profile === "debug";
 
   // ── 2. Validate the upload URL. Never log `parsed.data.upload_url`.
   const validated = validateGcsSignedUrl(
@@ -608,8 +643,11 @@ export async function handleMigrationExportToGcs({ body }: RouteHandlerArgs) {
   // "managed"), and teleport clients re-provision platform identity after
   // a platform→local import — so redact instead of emitting a bundle the
   // importer is guaranteed to reject.
+  //
+  // A debug bundle goes to Vellum staff, so it never carries credentials
+  // either, whatever the deployment mode.
   let collected: CollectedCredentials;
-  if (manifestInputs.origin.mode === "managed") {
+  if (manifestInputs.origin.mode === "managed" || isDebugProfile) {
     collected = {
       credentials: [],
       unreachable: false,
@@ -632,17 +670,44 @@ export async function handleMigrationExportToGcs({ body }: RouteHandlerArgs) {
     collected.perAccountUnreachable,
   );
 
+  if (isDebugProfile) {
+    manifestInputs = {
+      ...manifestInputs,
+      exportOptions: { ...manifestInputs.exportOptions, include_gateway: true },
+    };
+  }
+
   // ── 4. Enqueue the job. The runner captures the collected credentials.
   let job;
   try {
     job = migrationJobs.startJob("export", async () => {
       let cleanup: (() => Promise<void>) | undefined;
       try {
+        // The gateway snapshot can take a while on a large database, so it
+        // runs inside the job (after the export slot is held) rather than
+        // before the 202. A debug bundle without the gateway's data is not
+        // what staff asked for, so a failure fails the job and nothing is
+        // uploaded.
+        let extraFiles: Array<{ archivePath: string; data: Uint8Array }> = [];
+        if (isDebugProfile) {
+          try {
+            extraFiles = [await collectGatewayDebugExport()];
+          } catch (err) {
+            log.error({ err }, "Failed to collect the gateway's debug export");
+            const wrapped = new Error(
+              "The gateway did not provide its debug export; the bundle was not sent.",
+            );
+            (wrapped as { code?: string }).code = "gateway_debug_export_failed";
+            throw wrapped;
+          }
+        }
+
         const result = await streamExportVBundle({
           workspaceDir: getWorkspaceDir(),
           ...manifestInputs,
           secretsRedacted,
           credentials: collected.credentials,
+          extraFiles,
           checkpoint: checkpointDbsForExport,
         });
 
@@ -2402,6 +2467,12 @@ export const ROUTES: RouteDefinition[] = [
         .string()
         .optional()
         .describe("Human-readable export description."),
+      profile: z
+        .enum(["migration", "debug"])
+        .optional()
+        .describe(
+          "Export profile. 'migration' (default) builds a teleport bundle. 'debug' builds a bundle for Vellum staff to open on a debug clone: no credentials, plus the gateway's database and logs under gateway/.",
+        ),
     }),
     responseStatus: "202",
     responseBody: z.object({

package/src/runtime/routes/notification-routes.ts

@@ -14,6 +14,10 @@ import {
   NotificationSourceChannelSchema,
   RoutingIntentSchema,
 } from "../../notifications/signal.js";
+import {
+  NotificationDeliveryResultSchema,
+  NotificationReceiptClassSchema,
+} from "../../notifications/types.js";
 import { UrgencySchema } from "../../notifications/urgency.js";
 import { getDb } from "../../persistence/db-connection.js";
 import { notificationDeliveries } from "../../persistence/schema/index.js";
@@ -78,6 +82,9 @@ const EmitSignalResponse = z.object({
   dispatched: z.boolean(),
   deduplicated: z.boolean(),
   reason: z.string(),
+  selectedChannels: z.array(z.string()),
+  deliveryResults: z.array(NotificationDeliveryResultSchema),
+  receiptClass: NotificationReceiptClassSchema,
 });
 
 async function handleEmitSignal({ body = {} }: RouteHandlerArgs) {
@@ -94,6 +101,9 @@ async function handleEmitSignal({ body = {} }: RouteHandlerArgs) {
     dispatched: result.dispatched,
     deduplicated: result.deduplicated,
     reason: result.reason,
+    selectedChannels: result.selectedChannels,
+    deliveryResults: result.deliveryResults,
+    receiptClass: result.receiptClass,
   };
 }
 

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

@@ -6,6 +6,7 @@
  * the standard runtime auth middleware.
  */
 
+import { INTEGRATION_CATEGORIES } from "@vellumai/service-contracts/integration-categories";
 import { z } from "zod";
 
 import { loadConfig } from "../../config/loader.js";
@@ -176,6 +177,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 +314,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 +402,12 @@ export const oauthProviderSummarySchema = z.object({
   supports_managed_mode: z.boolean(),
   managed_service_is_paid: z.boolean(),
   feature_flag: z.string().nullable(),
+  category: z
+    .enum(INTEGRATION_CATEGORIES)
+    .nullable()
+    .describe(
+      "Where the integrations catalog files the provider; null for a provider without a seed entry.",
+    ),
   tenant_host: z
     .object({
       pattern: z.string(),

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'.",
+    );
+  });
+});