fix(ui): load all agents so the picker and deep-links work past the first page (#347)

### What
- Page through the **full** agent list in `useAgents` instead of
fetching only the default first page.
- Add `useAgentByName` to validate a deep-linked `agent_name` directly,
so a valid agent opens even if it's outside the loaded list.
- Only clear `agent_name` when it's present *and* invalid; accept an
agent found in the list **or** by name.
- Cap the picker's chip grid height and let it scroll, so a long agent
list doesn't push the title/prompt input off-screen.
- Distinguish a real 404 (agent doesn't exist) from transient errors in
the by-name lookup, and validate only against freshly-fetched data, so a
blip or a mid-refetch never bounces a valid deep link.

### Why
The picker fetched agents with an unpaginated `list()` call, so on
accounts with more than one page of agents only the first ~50 showed.
Those agents were invisible in the picker and because the same list
backed deep-link validation, deep-linking to one bounced back to the
home grid. Loading the full list then surfaced a layout issue where a
tall picker overflowed a vertically-centered container with no way to
scroll.

### Testing
- Unit tests for the pagination loop (multi-page, short-page, empty,
exact-boundary, safety-bound, mid-loop error) and the by-name lookup.
- `npm run typecheck` + `npm run lint` clean.
- Manually verified in a dev environment against an account with 100+
agents: all agents appear, the picker scrolls with the title/input
fixed, and deep-linking a valid agent opens its chat.

Before:


https://github.com/user-attachments/assets/46f78616-f525-499f-8047-e7fbffd54910

After:


https://github.com/user-attachments/assets/9a3b27ed-ba88-4d93-ae1f-0b2c7372f973

<!-- greptile_comment -->

<h3>Greptile Summary</h3>

This PR fixes the agent picker and deep-link routing by paginating
through the full agent list (instead of stopping after the default first
page), adding a `useAgentByName` hook for direct deep-link validation,
and capping the picker's chip grid height to prevent layout overflow on
large accounts.

- **`useAgents`** now loops through all pages up to a `MAX_AGENT_PAGES`
safety bound (100 × 100 = 10 000 agents max), warns loudly if truncated,
and exports its constants so tests can import them rather than
duplicating hardcoded values.
- **`useAgentByName`** validates a deep-linked agent name directly
against the backend: 404 resolves to `null`, any other error is
re-thrown so React Query surfaces it as `isError`, and the effect in
`agentex-ui-root.tsx` respects `couldNotDetermine` to avoid clearing a
valid deep link on a transient failure.
- **`AgentsList`** gains `max-h-[60vh] overflow-y-auto` so a long agent
list scrolls within the centered container rather than pushing the title
and input off-screen.

<details><summary><h3>Confidence Score: 5/5</h3></summary>

Safe to merge — all changed paths are well-tested, the catch narrowing
and couldNotDetermine guard are correctly implemented, and the
pagination loop has a clear termination condition.

The pagination loop terminates reliably on a short page or at the safety
bound, both hooks narrow their error handling correctly (404 → null,
everything else re-thrown), and the validation effect is gated on both
isFetching signals so it never acts on stale data. Unit tests cover all
meaningful boundary cases. The previous review thread's concerns have
been fully addressed.

No files require special attention.
</details>

<details><summary><h3>Important Files Changed</h3></summary>

| Filename | Overview |
|----------|----------|
| agentex-ui/hooks/use-agents.ts | Replaces single unpaginated list()
call with an async loop that accumulates pages until a short page
signals the end; exports PAGE_SIZE and MAX_AGENT_PAGES for test imports;
adds safety-bound warning when truncation occurs. |
| agentex-ui/hooks/use-agent-by-name.ts | New hook that validates a
deep-linked agent name directly against the backend; narrows 404 to null
(success) and re-throws all other errors so transient failures surface
via isError rather than silently clearing the URL. |
| agentex-ui/components/agentex-ui-root.tsx | Integrates useAgentByName
alongside useAgents; gates validation on both isFetching signals;
couldNotDetermine guard prevents clearing a valid deep link on transient
API errors. |
| agentex-ui/components/agents-list/agents-list.tsx | Single-line change
adds max-h-[60vh] and overflow-y-auto to the chip grid container so a
long agent list scrolls instead of overflowing the vertically-centered
layout. |
| agentex-ui/hooks/use-agents.test.tsx | New unit tests covering
multi-page, short-page, empty-list, exact-multiple, safety-bound, and
mid-loop error scenarios; imports PAGE_SIZE and MAX_AGENT_PAGES directly
from source after previous review feedback. |
| agentex-ui/hooks/use-agent-by-name.test.tsx | New unit tests covering
disabled-when-no-name, successful lookup, 404→null, and non-404 error
surfacing, using NotFoundError and APIError from the agentex SDK. |

</details>

<details><summary><h3>Flowchart</h3></summary>

<a href="#gh-light-mode-only">

```mermaid
%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Page loads with agent_name in URL] --> B{isAgentsFetching\nOR isAgentByNameFetching?}
    B -- Yes --> C[Return early — wait for both queries to settle]
    B -- No --> D{agentName present\nin URL?}

    D -- No --> E{localAgentName\nin localStorage?}
    E -- Yes --> F[Restore: updateParams agent_name = localAgentName]
    E -- No --> G[No-op]

    D -- Yes --> H{Agent found\nin paginated list?}
    H -- Yes --> I[agentInList = agent]
    H -- No --> J{useAgentByName\nresult?}

    J -- Agent returned --> K[agentByName = Agent]
    J -- 404 → null --> L[agentByName = null]
    J -- Non-404 error --> M[isAgentByNameError = true\ncouldNotDetermine = true]

    I --> N{status === Ready?}
    K --> N
    L --> O[isAgentValid = false\ncouldNotDetermine = false]
    M --> P[Leave URL alone\npreserve deep link]

    N -- Yes --> Q[isAgentValid = true\nLeave URL alone — agent opens]
    N -- No --> O

    O --> R[Clear agent_name from URL\nsetLocalAgentName undefined]
```

</a>
<a href="#gh-dark-mode-only">

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Page loads with agent_name in URL] --> B{isAgentsFetching\nOR isAgentByNameFetching?}
    B -- Yes --> C[Return early — wait for both queries to settle]
    B -- No --> D{agentName present\nin URL?}

    D -- No --> E{localAgentName\nin localStorage?}
    E -- Yes --> F[Restore: updateParams agent_name = localAgentName]
    E -- No --> G[No-op]

    D -- Yes --> H{Agent found\nin paginated list?}
    H -- Yes --> I[agentInList = agent]
    H -- No --> J{useAgentByName\nresult?}

    J -- Agent returned --> K[agentByName = Agent]
    J -- 404 → null --> L[agentByName = null]
    J -- Non-404 error --> M[isAgentByNameError = true\ncouldNotDetermine = true]

    I --> N{status === Ready?}
    K --> N
    L --> O[isAgentValid = false\ncouldNotDetermine = false]
    M --> P[Leave URL alone\npreserve deep link]

    N -- Yes --> Q[isAgentValid = true\nLeave URL alone — agent opens]
    N -- No --> O

    O --> R[Clear agent_name from URL\nsetLocalAgentName undefined]
```

</a>
</details>

<sub>Reviews (3): Last reviewed commit: ["Merge origin/main into
vineetvora/agx1-3..."](433e6a2)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=42404585)</sub>

<!-- /greptile_comment -->

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: vineetvora-scale

agentex-ui/components/agentex-ui-root.tsx

@@ -8,6 +8,7 @@ import { PrimaryContent } from '@/components/primary-content/primary-content';
 import { useAgentexClient } from '@/components/providers';
 import { TaskSidebar } from '@/components/task-sidebar/task-sidebar';
 import { TracesSidebar } from '@/components/traces-sidebar/traces-sidebar';
+import { useAgentByName } from '@/hooks/use-agent-by-name';
 import { useAgents } from '@/hooks/use-agents';
 import { useLocalStorageState } from '@/hooks/use-local-storage-state';
 import {
@@ -19,18 +20,39 @@ export function AgentexUIRoot() {
   const { agentName, taskID, updateParams } = useSafeSearchParams();
   const [isTracesSidebarOpen, setIsTracesSidebarOpen] = useState(false);
   const { agentexClient } = useAgentexClient();
-  const { data: agents = [], isLoading } = useAgents(agentexClient);
+  const { data: agents = [], isFetching: isAgentsFetching } =
+    useAgents(agentexClient);
+  // Validate the deep-linked agent directly against the backend so a valid agent opens
+  // even if it sits outside the loaded list (e.g. on accounts with many agents).
+  const {
+    data: agentByName,
+    isFetching: isAgentByNameFetching,
+    isError: isAgentByNameError,
+  } = useAgentByName(agentexClient, agentName);
   const [localAgentName, setLocalAgentName] = useLocalStorageState<
     string | undefined
   >('lastSelectedAgent', undefined);
 
+  // Wait until neither query is fetching before validating. We gate on `isFetching` (not
+  // `isLoading`, which is false once a query has cached data) so we never validate against
+  // stale data mid-refetch. A disabled by-name query reports `isFetching: false`, so it
+  // doesn't block the localStorage-restore path when there's no agent_name. Deps are
+  // intentionally narrowed so we re-validate on fetch settle / agent_name change.
   useEffect(() => {
-    if (isLoading) return;
+    if (isAgentsFetching || isAgentByNameFetching) return;
 
-    const selectedAgent = agents.find(agent => agent.name === agentName);
+    // Accept an agent found in the (paginated) list OR resolved directly by name, so a valid
+    // deep-linked agent opens even if it falls outside the loaded list.
+    const agentInList = agents.find(agent => agent.name === agentName);
+    const selectedAgent = agentInList ?? agentByName ?? undefined;
     const isAgentValid = selectedAgent && selectedAgent.status === 'Ready';
 
-    if (!isAgentValid) {
+    // If the agent isn't in the loaded list and the by-name lookup errored (a transient
+    // failure, not a 404), we can't tell whether it's valid — leave the URL alone rather
+    // than bouncing a possibly-valid deep link to the home grid.
+    const couldNotDetermine = !agentInList && isAgentByNameError;
+
+    if (agentName && !isAgentValid && !couldNotDetermine) {
       updateParams({ [SearchParamKey.AGENT_NAME]: null });
       setLocalAgentName(undefined);
     }
@@ -39,7 +61,7 @@ export function AgentexUIRoot() {
       updateParams({ [SearchParamKey.AGENT_NAME]: localAgentName });
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [isLoading]);
+  }, [isAgentsFetching, isAgentByNameFetching, isAgentByNameError, agentName]);
 
   const handleSelectTask = useCallback(
     (taskId: string | null) => {

agentex-ui/components/agents-list/agents-list.tsx

@@ -50,7 +50,7 @@ export function AgentsList({ agents, isLoading = false }: AgentsListProps) {
   return (
     <TooltipProvider delayDuration={200}>
       <motion.div
-        className="mb-2 flex max-w-4xl flex-wrap items-center justify-center gap-2"
+        className="mb-2 flex max-h-[60vh] max-w-4xl flex-wrap items-center justify-center gap-2 overflow-y-auto"
         layout={hasMounted.current}
       >
         {displayedAgents.length > 0 ? (

agentex-ui/hooks/use-agent-by-name.test.tsx

@@ -0,0 +1,101 @@
+import type { ReactNode } from 'react';
+
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { renderHook, waitFor } from '@testing-library/react';
+import { APIError, NotFoundError } from 'agentex';
+import { describe, expect, it, vi } from 'vitest';
+
+import { useAgentByName } from './use-agent-by-name';
+
+import type AgentexSDK from 'agentex';
+import type { Agent } from 'agentex/resources';
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    );
+  };
+}
+
+function clientWith(retrieveByName: ReturnType<typeof vi.fn>) {
+  return { agents: { retrieveByName } } as unknown as AgentexSDK;
+}
+
+describe('useAgentByName', () => {
+  it('does not fetch when no agent name is provided', () => {
+    const retrieveByName = vi.fn();
+
+    const { result } = renderHook(
+      () => useAgentByName(clientWith(retrieveByName), null),
+      {
+        wrapper: createWrapper(),
+      }
+    );
+
+    expect(retrieveByName).not.toHaveBeenCalled();
+    expect(result.current.fetchStatus).toBe('idle');
+    expect(result.current.data).toBeUndefined();
+  });
+
+  it('returns the agent when the lookup succeeds', async () => {
+    const agent = {
+      id: 'a1',
+      name: 'interview-agent',
+      status: 'Ready',
+    } as Agent;
+    const retrieveByName = vi.fn().mockResolvedValueOnce(agent);
+
+    const { result } = renderHook(
+      () => useAgentByName(clientWith(retrieveByName), 'interview-agent'),
+      { wrapper: createWrapper() }
+    );
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(result.current.data).toEqual(agent);
+    expect(retrieveByName).toHaveBeenCalledWith('interview-agent');
+  });
+
+  it('resolves to null (not an error) on a 404', async () => {
+    const notFound = new NotFoundError(
+      404,
+      undefined,
+      'Not found',
+      new Headers()
+    );
+    const retrieveByName = vi.fn().mockRejectedValueOnce(notFound);
+
+    const { result } = renderHook(
+      () => useAgentByName(clientWith(retrieveByName), 'missing-agent'),
+      { wrapper: createWrapper() }
+    );
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(result.current.data).toBeNull();
+    expect(result.current.isError).toBe(false);
+  });
+
+  it('surfaces a non-404 error instead of masquerading as not-found', async () => {
+    const serverError = new APIError(
+      500,
+      undefined,
+      'Server error',
+      new Headers()
+    );
+    const retrieveByName = vi.fn().mockRejectedValueOnce(serverError);
+
+    const { result } = renderHook(
+      () => useAgentByName(clientWith(retrieveByName), 'some-agent'),
+      { wrapper: createWrapper() }
+    );
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+
+    expect(result.current.data).toBeUndefined();
+  });
+});

agentex-ui/hooks/use-agent-by-name.ts

@@ -0,0 +1,48 @@
+import { useQuery } from '@tanstack/react-query';
+import { APIError } from 'agentex';
+
+import type AgentexSDK from 'agentex';
+import type { Agent } from 'agentex/resources';
+
+export const agentByNameKeys = {
+  byName: (name: string) => ['agents', 'by-name', name] as const,
+};
+
+/**
+ * Fetches a single agent by its unique name.
+ *
+ * Used to validate a deep-linked `agent_name` directly against the backend so that opening
+ * an agent does not depend on the entire (paginated) agent list having been loaded first.
+ * The query is disabled when no name is provided. A 404 resolves to `null` ("no such agent"
+ * — a normal outcome), while any other failure (network / 5xx / auth) is re-thrown so React
+ * Query surfaces it as an error rather than masquerading as "not found" (which could
+ * otherwise clear a valid deep link).
+ *
+ * @param agentexClient - AgentexSDK - The SDK client used to communicate with the Agentex API
+ * @param agentName - The agent name to look up; query is disabled when absent (null/undefined)
+ * @returns UseQueryResult<Agent | null> - React Query result containing the agent, or null if not found
+ */
+export function useAgentByName(
+  agentexClient: AgentexSDK,
+  agentName: string | null | undefined
+) {
+  return useQuery({
+    queryKey: agentByNameKeys.byName(agentName ?? ''),
+    queryFn: async (): Promise<Agent | null> => {
+      try {
+        return await agentexClient.agents.retrieveByName(agentName as string);
+      } catch (error) {
+        // A 404 means the name isn't a real, reachable agent — a normal "not found"
+        // outcome, so resolve to null. Re-throw anything else (network / 5xx / auth) so a
+        // transient failure surfaces as a query error instead of masquerading as
+        // "not found", which could otherwise clear a valid deep link.
+        if (error instanceof APIError && error.status === 404) {
+          return null;
+        }
+        throw error;
+      }
+    },
+    enabled: !!agentName,
+    refetchOnWindowFocus: false,
+  });
+}

agentex-ui/hooks/use-agents.test.tsx

@@ -0,0 +1,146 @@
+import type { ReactNode } from 'react';
+
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { renderHook, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  AGENTS_PAGE_SIZE as PAGE_SIZE,
+  MAX_AGENT_PAGES,
+  useAgents,
+} from './use-agents';
+
+import type AgentexSDK from 'agentex';
+import type { Agent } from 'agentex/resources';
+
+function makeAgents(count: number, prefix: string): Agent[] {
+  return Array.from(
+    { length: count },
+    (_, i) =>
+      ({
+        id: `${prefix}-${i}`,
+        name: `${prefix}-${i}`,
+        status: 'Ready',
+      }) as Agent
+  );
+}
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    );
+  };
+}
+
+function clientWith(list: ReturnType<typeof vi.fn>) {
+  return { agents: { list } } as unknown as AgentexSDK;
+}
+
+describe('useAgents', () => {
+  it('pages through every agent until a short page is returned', async () => {
+    const list = vi
+      .fn()
+      .mockResolvedValueOnce(makeAgents(PAGE_SIZE, 'p1')) // full page -> keep going
+      .mockResolvedValueOnce(makeAgents(24, 'p2')); // short page -> stop
+
+    const { result } = renderHook(() => useAgents(clientWith(list)), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(result.current.data).toHaveLength(PAGE_SIZE + 24);
+    expect(list).toHaveBeenCalledTimes(2);
+    expect(list).toHaveBeenNthCalledWith(1, {
+      limit: PAGE_SIZE,
+      page_number: 1,
+    });
+    expect(list).toHaveBeenNthCalledWith(2, {
+      limit: PAGE_SIZE,
+      page_number: 2,
+    });
+  });
+
+  it('makes a single request when the first page is not full', async () => {
+    const list = vi.fn().mockResolvedValueOnce(makeAgents(10, 'only'));
+
+    const { result } = renderHook(() => useAgents(clientWith(list)), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(result.current.data).toHaveLength(10);
+    expect(list).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns an empty list without paging when there are no agents', async () => {
+    const list = vi.fn().mockResolvedValueOnce([]);
+
+    const { result } = renderHook(() => useAgents(clientWith(list)), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(result.current.data).toEqual([]);
+    expect(list).toHaveBeenCalledTimes(1);
+  });
+
+  it('stops at the exact-multiple boundary without looping forever', async () => {
+    // Total is an exact multiple of the page size: a full page followed by an empty page.
+    const list = vi
+      .fn()
+      .mockResolvedValueOnce(makeAgents(PAGE_SIZE, 'p1'))
+      .mockResolvedValueOnce([]);
+
+    const { result } = renderHook(() => useAgents(clientWith(list)), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(result.current.data).toHaveLength(PAGE_SIZE);
+    expect(list).toHaveBeenCalledTimes(2);
+  });
+
+  it('stops at the safety bound and warns when every page stays full', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    // Always return a full page so the loop can only stop at MAX_AGENT_PAGES.
+    const list = vi.fn().mockResolvedValue(makeAgents(PAGE_SIZE, 'full'));
+
+    const { result } = renderHook(() => useAgents(clientWith(list)), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(list).toHaveBeenCalledTimes(MAX_AGENT_PAGES);
+    expect(result.current.data).toHaveLength(PAGE_SIZE * MAX_AGENT_PAGES);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('MAX_AGENT_PAGES')
+    );
+
+    warn.mockRestore();
+  });
+
+  it('surfaces an error instead of a partial list when a page fails mid-loop', async () => {
+    const list = vi
+      .fn()
+      .mockResolvedValueOnce(makeAgents(PAGE_SIZE, 'p1'))
+      .mockRejectedValueOnce(new Error('boom'));
+
+    const { result } = renderHook(() => useAgents(clientWith(list)), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+
+    expect(result.current.data).toBeUndefined();
+    expect(list).toHaveBeenCalledTimes(2);
+  });
+});