docs(agentex-ui): tighten comments to the non-obvious

Trim redundant/verbose comments across the account-picker BFF layer (drop lines that
restate the code or repeat a docstring); no behavior change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: erichwoo-scale

agentex-ui/app/api/_lib/bff.ts

@@ -1,21 +1,14 @@
-/**
- * Server-only platform API upstream, shared by the platform-backed BFF routes
- * (/api/feedback, /api/user-info). SGP_API_URL preferred; falls back to the dashboard
- * app origin's /api.
- */
+/** Server-only platform API base for the BFF routes. Prefers SGP_API_URL, else the app URL. */
 export const SGP_BASE_URL =
   process.env.SGP_API_URL ??
   (process.env.NEXT_PUBLIC_SGP_APP_URL
     ? `${process.env.NEXT_PUBLIC_SGP_APP_URL}/api`
     : undefined);
 
 /**
- * Apply BFF credentials to an outgoing upstream request's `headers`, in place, so no
- * credential reaches client JS. Shared by every /api/* proxy (agentex, platform):
- *   - `x-selected-account-id` from the client (sourced from the account_id query param);
- *     forwarded as-is — the upstream authorizes the principal's access to the account.
- *   - any client-supplied `authorization` is dropped so a client can't inject its own
- *     bearer token; the request cookies are forwarded for the upstream's cookie auth.
+ * Attach credentials to an upstream request's `headers` in place, so none reach client JS:
+ * forward `x-selected-account-id` (the upstream authorizes the account), drop any
+ * client-sent `authorization`, and forward cookies for the upstream's own auth.
  */
 export async function applyBffCredentials(
   req: Request,
@@ -25,7 +18,6 @@ export async function applyBffCredentials(
   if (accountId) headers.set('x-selected-account-id', accountId);
   else headers.delete('x-selected-account-id');
 
-  // Credentials are server-managed: never trust a client-sent Authorization header.
   headers.delete('authorization');
 
   const cookie = req.headers.get('cookie');

agentex-ui/app/api/agentex/[...path]/route.ts

@@ -1,23 +1,17 @@
 import { applyBffCredentials } from '@/app/api/_lib/bff';
 
 /**
- * BFF proxy for the Agentex API. The browser ALWAYS calls this same-origin route, so
- * the backend origin + credentials never touch client JS. Credentials (access token
- * or forwarded cookies, plus x-selected-account-id) are applied server-side by
- * applyBffCredentials — see app/api/_lib/bff.ts.
+ * Same-origin BFF proxy for the Agentex API, so the upstream URL and credentials never
+ * reach client JS. applyBffCredentials attaches credentials server-side.
  */
 export const dynamic = 'force-dynamic';
 
-// Server-only upstream — the client only ever calls /api/agentex, so the backend URL
-// stays out of the browser bundle.
 const UPSTREAM = (
   process.env.AGENTEX_API_URL ?? 'http://localhost:5003'
 ).replace(/\/$/, '');
 
-// Hop-by-hop request headers to drop before forwarding. Credential headers (`cookie`,
-// `authorization`) are intentionally NOT listed here: applyBffCredentials owns them — it
-// deletes any client-supplied values and sets the server-managed ones — so the same
-// stripping applies to every /api/* proxy, not just this route.
+// Hop-by-hop headers to drop. Credential headers (cookie/authorization) are handled by
+// applyBffCredentials, not here.
 const STRIP_REQ = ['host', 'connection', 'content-length'];
 const STRIP_RES = [
   'content-encoding',

agentex-ui/app/api/feedback/route.ts

@@ -78,8 +78,7 @@ export async function POST(request: Request) {
     );
   }
 
-  // Same server-side credentials the agentex proxy forwards (access token or cookies,
-  // plus x-selected-account-id) — the client never sends them.
+  // Credentials attached server-side (see applyBffCredentials).
   const sgpHeaders = new Headers({ 'Content-Type': 'application/json' });
   await applyBffCredentials(request, sgpHeaders);
   const now = new Date().toISOString();

agentex-ui/app/api/user-info/route.ts

@@ -3,10 +3,9 @@ import { NextResponse } from 'next/server';
 import { applyBffCredentials, SGP_BASE_URL } from '@/app/api/_lib/bff';
 
 /**
- * BFF proxy for the one SGP endpoint agentex-ui needs client-side: the caller's
- * accounts (access_profiles), used to bootstrap / switch the selected account. Scoped
- * to just this path — deliberately NOT a catch-all SGP proxy — so the browser can't
- * reach arbitrary SGP endpoints with the server-attached credentials.
+ * Scoped BFF proxy for the caller's accounts (access_profiles), used to bootstrap/switch
+ * the selected account. Only this path is exposed — not a catch-all — so the browser can't
+ * reach arbitrary platform endpoints with the server-attached credentials.
  */
 export const dynamic = 'force-dynamic';
 

agentex-ui/components/account-picker/account-picker.tsx

@@ -37,10 +37,9 @@ export function AccountPicker({
   const profiles = useMemo(() => data?.access_profiles ?? [], [data]);
   const selectedId = selectedAccountId ?? undefined;
 
-  // Reset (not just invalidate) account-scoped data on a switch. invalidate keeps the
-  // previous data cached during the refetch, so the new account would briefly render the
-  // old account's agents (HomeView) before recalibrating; reset clears it so we show a
-  // loading state instead. user-info is preserved — the account list doesn't change.
+  // Reset (not invalidate) account-scoped data on switch: invalidate keeps the old data
+  // cached during refetch, briefly showing the previous account's agents. user-info is
+  // preserved — the account list doesn't change on switch.
   const resetAccountScoped = useCallback(
     () =>
       queryClient.resetQueries({
@@ -73,8 +72,8 @@ export function AccountPicker({
 
   if (!accountsEnabled) return null;
 
-  // A size-9 icon tile — the collapsed-rail footprint. Shared by the loading placeholder
-  // (muted) and the single-account display (solid, with the name as a tooltip).
+  // Size-9 collapsed-rail tile — shared by the loading placeholder (muted) and the
+  // single-account display (solid).
   const iconTile = (opts?: { muted?: boolean; title?: string | undefined }) => (
     <div
       title={opts?.title}
@@ -89,8 +88,7 @@ export function AccountPicker({
     </div>
   );
 
-  // While accounts load, show a disabled, empty picker (icon only) instead of a skeleton
-  // block — keeps the row stable and reads as a loading account selector.
+  // Loading: a disabled, empty picker (icon only) rather than a skeleton — keeps the row stable.
   if (isLoading) {
     return collapsed ? (
       iconTile({ muted: true })
@@ -123,8 +121,7 @@ export function AccountPicker({
   );
 
   if (collapsed) {
-    // Single account → static icon; multiple → an icon-only trigger whose dropdown pops
-    // out beside the collapsed rail (Radix keeps it in view).
+    // Single → static icon; multiple → icon-only trigger (dropdown pops out beside the rail).
     if (single) return iconTile({ title: current?.account.name });
     return (
       <Select value={selectedId ?? ''} onValueChange={onAccountChange}>
@@ -142,8 +139,7 @@ export function AccountPicker({
     );
   }
 
-  // A single account needs no switcher — show it as static context, matching the New Chat
-  // button's size + spacing (size-5 icon, p-2, medium weight).
+  // Single account: no switcher, just static context (matches the New Chat button).
   if (single) {
     return (
       <div

agentex-ui/components/providers/agentex-provider.tsx

@@ -20,21 +20,19 @@ import {
 interface AgentexContextValue {
   agentexClient: AgentexSDK;
   sgpAppURL: string;
-  // Whether the platform API is configured, so the account picker can fetch/switch accounts
+  // Platform API configured → the account picker can fetch/switch accounts.
   accountsEnabled: boolean;
-  // Selected account id (from the `account_id` query param) + a setter that mirrors it
-  // to the URL and updates the header the SDK sends.
+  // Selected account (from the `account_id` param) + a setter that mirrors it to the URL.
   selectedAccountId: string | null;
   setSelectedAccountId: (id: string, replace?: boolean) => void;
 }
 
 const AgentexContext = createContext<AgentexContextValue | null>(null);
 
 /**
- * Main provider. The SDK ALWAYS targets the same-origin BFF proxy (`/api/agentex`), which
- * forwards credentials server-side. The selected account travels as the
- * `x-selected-account-id` header, sourced from the `account_id` query param — no cookie
- * involved.
+ * The SDK always targets the same-origin BFF (`/api/agentex`), which attaches credentials
+ * server-side. The selected account rides as `x-selected-account-id`, from the `account_id`
+ * query param.
  */
 export function AgentexProvider({
   children,
@@ -47,9 +45,8 @@ export function AgentexProvider({
 }) {
   const { sgpAccountID, updateParams } = useSafeSearchParams();
 
-  // Synchronous source for the SDK's per-request header. Seeded from the URL and kept in
-  // sync with it; setSelectedAccountId also sets it synchronously so a switch's refetch doesn't
-  // race the (async) URL navigation.
+  // Synchronous source for the SDK header: setSelectedAccountId sets it before the (async)
+  // URL navigation, so a switch's refetch doesn't race it.
   const selectedAccountIdRef = useRef<string | null>(sgpAccountID);
   useEffect(() => {
     selectedAccountIdRef.current = sgpAccountID;
@@ -61,8 +58,8 @@ export function AgentexProvider({
       updateParams(
         {
           [SearchParamKey.SGP_ACCOUNT_ID]: id,
-          // An explicit switch (not the initial bootstrap, which passes replace) drops the
-          // open task — it's account-scoped and won't resolve under the new account.
+          // An explicit switch (not bootstrap, which passes replace) drops the open task:
+          // it's account-scoped and won't resolve under the new account.
           ...(replace ? {} : { [SearchParamKey.TASK_ID]: null }),
         },
         replace
@@ -72,9 +69,8 @@ export function AgentexProvider({
   );
 
   const agentexClient = useMemo(() => {
-    // The SDK builds request URLs with `new URL()`, so the base must be ABSOLUTE. On the
-    // server `window` is absent, but no request fires during the initial server render
-    // (react-query fetches on the client); the client render recomputes an absolute URL.
+    // The SDK builds URLs with `new URL()`, so the base must be absolute. `window` is absent
+    // on the server, but no request fires during SSR; the client render recomputes it.
     const baseURL =
       typeof window !== 'undefined'
         ? `${window.location.origin}/api/agentex`

agentex-ui/hooks/use-user-info.ts

@@ -16,11 +16,7 @@ type UserInfo = { access_profiles: AccessProfile[] };
 
 export const userInfoKey = ['user-info'] as const;
 
-/**
- * Fetches the caller's accounts (access_profiles) via the scoped `/api/user-info` BFF
- * proxy, to bootstrap / switch the selected account. `enabled` gates the fetch (off when
- * the platform API isn't configured).
- */
+/** Caller's accounts (access_profiles) via /api/user-info; `enabled` off when unconfigured. */
 export function useUserInfo(enabled: boolean) {
   return useQuery({
     queryKey: userInfoKey,
@@ -30,8 +26,8 @@ export function useUserInfo(enabled: boolean) {
       if (!res.ok) throw new Error(`user-info: ${res.status}`);
       return res.json();
     },
-    // The account list is stable for the session — fetch once, don't refetch on remount
-    // (e.g. the account_id navigation) or focus.
+    // The account list is stable for the session — don't refetch on the account_id
+    // navigation or window focus.
     staleTime: Infinity,
     refetchOnWindowFocus: false,
   });