@vellumai/assistant 0.12.1-dev.202609162016.c36c1d1 → 0.12.1-dev.202609162115.4edf01d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.1-dev.202609162016.c36c1d1",
+  "version": "0.12.1-dev.202609162115.4edf01d",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/oauth-commands-routes.test.ts

@@ -698,22 +698,18 @@ describe("POST oauth/request", () => {
     expect(result.body).toEqual({ hello: "world" });
   });
 
-  // The recovery hint on a 401/403 follows the credential's kind. A channel
-  // bot's token is stored by the channel's setup, so the OAuth status and
-  // connect commands cannot repair it; the hint must name the channel's own
-  // diagnostics, through whichever door the request came.
-  // A 403 carrying an HTML page is a resource refusing this identity, not the
-  // credential failing: an API refuses with JSON, and the same token serves
-  // it. The hint names the resource's access and never tells the caller to
-  // reconnect; a JSON 403 from any host keeps the credential reading.
-  test("an HTML 403 names the resource's access, not the credential", async () => {
+  // The hint's wording is pinned in oauth-request-hints.test.ts. Here only
+  // the facts the route hands the composer are proved to arrive: the
+  // response headers, the base the request resolved against, and the bot
+  // channel resolved from the provider key.
+  test("hands the composer the response, the resolved base, and the identity", async () => {
     mockProviders.slack_channel = seededProvider("slack_channel");
     mockResolveResponse = {
       status: 403,
       headers: { "content-type": "text/html; charset=utf-8" },
       body: "<html><title>Slack</title></html>",
     };
-    const result = (await getRoute("POST", "oauth/request").handler(
+    const asBot = (await getRoute("POST", "oauth/request").handler(
       makeArgs({
         body: {
           provider: "slack_channel",
@@ -721,99 +717,28 @@ describe("POST oauth/request", () => {
         },
       }),
     )) as { ok: boolean; status: number; hint?: string };
-    expect(result.ok).toBe(false);
-    expect(result.hint).toContain("HTML page from files.slack.com");
-    expect(result.hint).toContain("cannot see this resource");
-    expect(result.hint).not.toContain("was rejected");
-    expect(result.hint).not.toContain("setup skill");
+    expect(asBot.ok).toBe(false);
+    expect(asBot.status).toBe(403);
+    // An absolute URL's own origin is the resolved base.
+    expect(asBot.hint).toContain("from files.slack.com");
+    expect(asBot.hint).toContain("assistant channels get slack");
 
-    // A JSON 403 is an API refusal and keeps the credential reading, on the
-    // API host and on a provider's other API hosts alike.
+    // A relative path resolves against the provider's base.
     mockResolveResponse = {
-      status: 403,
-      headers: { "content-type": "application/json" },
-      body: { ok: false, error: "missing_scope" },
-    };
-    const apiResult = (await getRoute("POST", "oauth/request").handler(
-      makeArgs({
-        body: { provider: "slack_channel", url: "/conversations.history" },
-      }),
-    )) as { hint?: string };
-    expect(apiResult.hint).toContain("slack bot credential was rejected");
-
-    mockProviders.google = {
-      ...baseProvider,
-      injectionTemplates: JSON.stringify([
-        {
-          hostPattern: "gmail.googleapis.com",
-          injectionType: "header",
-          headerName: "Authorization",
-          valuePrefix: "Bearer ",
-        },
-        {
-          hostPattern: "calendar.googleapis.com",
-          injectionType: "header",
-          headerName: "Authorization",
-          valuePrefix: "Bearer ",
-        },
-      ]),
-      baseUrl: "https://gmail.googleapis.com/gmail/v1/users/me",
+      status: 404,
+      headers: { "content-type": "text/html; charset=UTF-8" },
+      body: "<html><title>Error 404 (Not Found)</title></html>",
     };
-    const otherApi = (await getRoute("POST", "oauth/request").handler(
+    const relative = (await getRoute("POST", "oauth/request").handler(
       makeArgs({
         body: {
           provider: "google",
-          url: "https://calendar.googleapis.com/calendar/v3/calendars/primary",
+          url: "/calendar/v3/calendars/primary/events",
         },
       }),
-    )) as { hint?: string };
-    expect(otherApi.hint).toContain(
-      "The OAuth token may be expired or revoked",
-    );
-    expect(otherApi.hint).not.toContain("cannot see this resource");
-  });
-
-  test("401 as a channel bot points at the channel's diagnostics, never the OAuth commands", async () => {
-    mockProviders.slack_channel = {
-      ...baseProvider,
-      provider: "slack_channel",
-      authorizeUrl: "urn:manual-token",
-      managedServiceConfigKey: null,
-      baseUrl: "https://slack.com/api",
-    };
-    mockResolveResponse = {
-      status: 401,
-      headers: { "content-type": "application/json" },
-      body: { ok: false, error: "invalid_auth" },
-    };
-    const result = (await getRoute("POST", "oauth/request").handler(
-      makeArgs({
-        body: { provider: "slack_channel", url: "/conversations.history" },
-      }),
-    )) as { ok: boolean; status: number; hint?: string };
-    expect(result.ok).toBe(false);
-    expect(result.status).toBe(401);
-    expect(result.hint).toContain("slack bot credential");
-    expect(result.hint).toContain("assistant channels get slack");
-    expect(result.hint).not.toContain("oauth status");
-    expect(result.hint).not.toContain("oauth connect");
-  });
-
-  test("403 as a person's OAuth integration keeps the OAuth recovery steps", async () => {
-    mockResolveResponse = {
-      status: 403,
-      headers: { "content-type": "application/json" },
-      body: { error: "forbidden" },
-    };
-    const result = (await getRoute("POST", "oauth/request").handler(
-      makeArgs({
-        body: { provider: "google", url: "https://api.google.com/v1/me" },
-      }),
-    )) as { ok: boolean; status: number; hint?: string };
-    expect(result.status).toBe(403);
-    expect(result.hint).toContain("assistant oauth status google");
-    expect(result.hint).toContain("oauth connect");
-    expect(result.hint).not.toContain("channels get");
+    )) as { ok: boolean; hint?: string };
+    expect(relative.ok).toBe(false);
+    expect(relative.hint).toContain('base URL "https://api.google.com"');
   });
 
   test("passes a pre-parsed string body through to the connection unchanged", async () => {
@@ -1155,84 +1080,6 @@ describe("POST oauth/request", () => {
     ]);
   });
 
-  test("attaches reconnect hint on 401 response", async () => {
-    mockResolveResponse = { status: 401, headers: {}, body: { error: "no" } };
-    const result = (await getRoute("POST", "oauth/request").handler(
-      makeArgs({
-        body: { provider: "google", url: "https://api.google.com/v1/me" },
-      }),
-    )) as { ok: boolean; hint?: string };
-    expect(result.ok).toBe(false);
-    expect(result.hint).toContain("oauth status");
-  });
-
-  test("attaches wrong-host/path hint on HTML 404 for a relative path", async () => {
-    mockResolveResponse = {
-      status: 404,
-      headers: { "content-type": "text/html; charset=UTF-8" },
-      body: "<html><title>Error 404 (Not Found)</title></html>",
-    };
-    const result = (await getRoute("POST", "oauth/request").handler(
-      makeArgs({
-        body: {
-          provider: "google",
-          url: "/calendar/v3/calendars/primary/events",
-        },
-      }),
-    )) as { ok: boolean; status: number; hint?: string };
-    expect(result.ok).toBe(false);
-    expect(result.status).toBe(404);
-    expect(result.hint).toContain("HTML");
-    // Reports the resolved base URL the relative path was joined onto.
-    expect(result.hint).toContain("https://api.google.com");
-    // Steers the caller toward an absolute URL.
-    expect(result.hint).toContain("absolute URL");
-  });
-
-  test("does not attach HTML-404 hint when a 404 body is JSON", async () => {
-    mockResolveResponse = {
-      status: 404,
-      headers: { "content-type": "application/json" },
-      body: { error: "not found" },
-    };
-    const result = (await getRoute("POST", "oauth/request").handler(
-      makeArgs({
-        body: { provider: "google", url: "/v1/missing" },
-      }),
-    )) as { ok: boolean; status: number; hint?: string };
-    expect(result.ok).toBe(false);
-    expect(result.status).toBe(404);
-    expect(result.hint).toBeUndefined();
-  });
-
-  test("HTML-404 hint reports an absolute URL's own host as the resolved base", async () => {
-    mockProviders.google = {
-      ...baseProvider,
-      injectionTemplates: JSON.stringify([
-        {
-          hostPattern: "www.googleapis.com",
-          injectionType: "header",
-          headerName: "Authorization",
-          valuePrefix: "Bearer ",
-        },
-      ]),
-    };
-    mockResolveResponse = {
-      status: 404,
-      headers: { "content-type": "text/html" },
-      body: "<html>nope</html>",
-    };
-    const result = (await getRoute("POST", "oauth/request").handler(
-      makeArgs({
-        body: {
-          provider: "google",
-          url: "https://www.googleapis.com/calendar/v3/nope",
-        },
-      }),
-    )) as { hint?: string };
-    expect(result.hint).toContain("https://www.googleapis.com");
-  });
-
   test("rejects unregistered client_id in BYO mode", async () => {
     // No entry in mockApps for google:client-x
     await expect(

package/src/runtime/AGENTS.md

@@ -301,6 +301,6 @@ The provider-level rate limiter (`providers/ratelimit.ts`) also logs warnings (m
 
 ## HTTP-Only Transport
 
-HTTP is the sole transport for client-daemon communication. The runtime HTTP server (`assistant/src/runtime/http-server.ts`) is the canonical API surface. Clients connect via HTTP for request/response operations and SSE (`GET /v1/events`) for streaming server-to-client events.
+HTTP is the sole transport for browser and desktop clients; the CLI and the gateway reach the daemon over the IPC socket (see `assistant/AGENTS.md`). The runtime HTTP server (`assistant/src/runtime/http-server.ts`) is the canonical API surface. Clients connect via HTTP for request/response operations and SSE (`GET /v1/events`) for streaming server-to-client events.
 
 A skill never calls the runtime HTTP API directly: every request from a skill targets the gateway, and `gateway-only-guard.test.ts` fails CI on a runtime-port URL in a skill. For configuration reads, use the CLI (`assistant config get`); for control-plane writes with no CLI verb, use `$INTERNAL_GATEWAY_BASE_URL`. See "Gateway-Only API Consumption" in `gateway/AGENTS.md` for the rule and its exceptions.

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

@@ -58,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");
@@ -1040,79 +1041,23 @@ export async function handleRequest({ body = {} }: RouteHandlerArgs) {
       `used "${selected}". Pass --account to select a specific one.`;
   }
 
-  const botChannel = channelForBotProvider(b.provider);
-  if (verdict.reportedFailure) {
-    // The body carries the provider's own error code, so the hint says only
-    // why a 2xx is being reported as a failure.
-    result.hint = `${verdict.reportedFailure} in the response body. The body names the error.`;
-  } else if (response.status === 403 && isHtmlResponse(response.headers)) {
-    // 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.
-    const identity = botChannel ? `${botChannel} bot` : "connected account";
-    const requestHost = parseUrl(baseUrl ?? providerRow.baseUrl)?.hostname;
-    result.hint =
-      `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; ` +
-      (botChannel
-        ? `'assistant channels get ${botChannel}' reports the credential itself.`
-        : `'assistant oauth status ${b.provider}' reports the credential itself.`);
-  } else 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.
-    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-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;
+}