handoff-app 2.0.0-9 → 2.0.0

package/src/app/pages/account/tokens.tsx

@@ -1,9 +1,13 @@
+import type { ClientConfig } from '@handoff/types/config';
+import type { GetStaticProps } from 'next';
+import { getClientRuntimeConfig } from '../../components/util';
 import { AccountLayout } from '../../components/Auth/AccountLayout';
 import { authApiUrl, readApiError } from '../../components/Auth/api';
 import { Alert, AlertDescription, AlertTitle } from '../../components/ui/alert';
 import { Badge } from '../../components/ui/badge';
 import { Button } from '../../components/ui/button';
 import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '../../components/ui/card';
+import { ConfirmDialog } from '../../components/ui/confirm-dialog';
 import { Input } from '../../components/ui/input';
 import { Label } from '../../components/ui/label';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../../components/ui/select';
@@ -29,15 +33,17 @@ const formatDate = (value?: string | null) => {
   return Number.isNaN(date.valueOf()) ? value : date.toLocaleDateString();
 };
 
-export default function TokensPage() {
+export const getStaticProps: GetStaticProps = async () => ({ props: { config: getClientRuntimeConfig() } });
+
+export default function TokensPage({ config }: { config: ClientConfig }) {
   if (process.env.HANDOFF_RUNTIME_MODE !== 'registry') {
-    return <AccountLayout title="Access tokens">{null}</AccountLayout>;
+    return <AccountLayout config={config} title="Access tokens">{null}</AccountLayout>;
   }
 
-  return <RegistryTokensPage />;
+  return <RegistryTokensPage config={config} />;
 }
 
-function RegistryTokensPage() {
+function RegistryTokensPage({ config }: { config: ClientConfig }) {
   const { data: session } = useSession();
   const role = (session?.user as { role?: string } | undefined)?.role;
   const [tokens, setTokens] = useState<AccessToken[]>([]);
@@ -46,6 +52,7 @@ function RegistryTokensPage() {
   const [copied, setCopied] = useState(false);
   const [pending, setPending] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [tokenToRevoke, setTokenToRevoke] = useState<AccessToken | null>(null);
 
   const load = useCallback(async () => {
     const response = await fetch(authApiUrl('/api/account/tokens'), { credentials: 'include', cache: 'no-store' });
@@ -89,7 +96,6 @@ function RegistryTokensPage() {
   };
 
   const revoke = async (token: AccessToken) => {
-    if (!window.confirm(`Revoke “${token.name}”? Applications using it will immediately lose access.`)) return;
     setPending(true);
     setError(null);
     try {
@@ -115,7 +121,11 @@ function RegistryTokensPage() {
   };
 
   return (
-    <AccountLayout title="Access tokens">
+    <AccountLayout
+      config={config}
+      title="Access tokens"
+      description="Create and revoke credentials for the CLI, CI jobs, and integrations."
+    >
       <div className="space-y-6">
         <Card>
           <CardHeader>
@@ -209,7 +219,12 @@ function RegistryTokensPage() {
                       <TableCell>{formatDate(token.lastUsedAt)}</TableCell>
                       <TableCell>{formatDate(token.expiresAt)}</TableCell>
                       <TableCell className="text-right">
-                        <Button size="sm" variant="ghost" disabled={pending || Boolean(token.revokedAt)} onClick={() => void revoke(token)}>
+                        <Button
+                          size="sm"
+                          variant="ghost"
+                          disabled={pending || Boolean(token.revokedAt)}
+                          onClick={() => setTokenToRevoke(token)}
+                        >
                           <Trash2 /> Revoke
                         </Button>
                       </TableCell>
@@ -227,6 +242,21 @@ function RegistryTokensPage() {
           </CardContent>
         </Card>
       </div>
+
+      {tokenToRevoke ? (
+        <ConfirmDialog
+          open
+          onOpenChange={(open) => {
+            if (!open) setTokenToRevoke(null);
+          }}
+          title={`Revoke “${tokenToRevoke.name}”?`}
+          description="Applications that use this token lose access immediately."
+          confirmLabel="Revoke"
+          pendingLabel="Revoking…"
+          variant="destructive"
+          onConfirm={() => revoke(tokenToRevoke)}
+        />
+      ) : null}
     </AccountLayout>
   );
 }

package/src/app/pages/account/users.tsx

@@ -1,14 +1,18 @@
+import type { ClientConfig } from '@handoff/types/config';
+import type { GetStaticProps } from 'next';
+import { getClientRuntimeConfig } from '../../components/util';
 import { AccountLayout } from '../../components/Auth/AccountLayout';
 import { authApiUrl, readApiError } from '../../components/Auth/api';
 import { Alert, AlertDescription, AlertTitle } from '../../components/ui/alert';
 import { Badge } from '../../components/ui/badge';
 import { Button } from '../../components/ui/button';
 import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '../../components/ui/card';
+import { ConfirmDialog, type ConfirmDialogProps } from '../../components/ui/confirm-dialog';
 import { Input } from '../../components/ui/input';
 import { Label } from '../../components/ui/label';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../../components/ui/select';
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../../components/ui/table';
-import { Check, Copy, MailPlus, RefreshCw } from 'lucide-react';
+import { Check, Copy, KeyRound, MailPlus, RefreshCw } from 'lucide-react';
 import { useSession } from 'next-auth/react';
 import { useRouter } from 'next/router';
 import { FormEvent, useCallback, useEffect, useState } from 'react';
@@ -29,15 +33,17 @@ interface MutationResult {
   message?: string;
 }
 
-export default function UsersPage() {
+export const getStaticProps: GetStaticProps = async () => ({ props: { config: getClientRuntimeConfig() } });
+
+export default function UsersPage({ config }: { config: ClientConfig }) {
   if (process.env.HANDOFF_RUNTIME_MODE !== 'registry') {
-    return <AccountLayout title="Users">{null}</AccountLayout>;
+    return <AccountLayout config={config} title="Users">{null}</AccountLayout>;
   }
 
-  return <RegistryUsersPage />;
+  return <RegistryUsersPage config={config} />;
 }
 
-function RegistryUsersPage() {
+function RegistryUsersPage({ config }: { config: ClientConfig }) {
   const router = useRouter();
   const { data: session, status: sessionStatus } = useSession();
   const currentUser = session?.user as (typeof session.user & { id?: string; role?: string }) | undefined;
@@ -48,6 +54,8 @@ function RegistryUsersPage() {
   const [success, setSuccess] = useState<string | null>(null);
   const [manualLink, setManualLink] = useState<string | null>(null);
   const [copied, setCopied] = useState(false);
+  const [emailConfigured, setEmailConfigured] = useState<boolean | null>(null);
+  const [confirmation, setConfirmation] = useState<Omit<ConfirmDialogProps, 'open' | 'onOpenChange'> | null>(null);
 
   useEffect(() => {
     if (sessionStatus === 'authenticated' && currentUser?.role !== 'admin') void router.replace('/account');
@@ -56,8 +64,9 @@ function RegistryUsersPage() {
   const load = useCallback(async () => {
     const response = await fetch(authApiUrl('/api/admin/users'), { credentials: 'include', cache: 'no-store' });
     if (!response.ok) throw new Error(await readApiError(response, 'Could not load users.'));
-    const body = (await response.json()) as RegistryUser[] | { users: RegistryUser[] };
+    const body = (await response.json()) as RegistryUser[] | { users: RegistryUser[]; emailConfigured?: boolean };
     const rows = Array.isArray(body) ? body : body.users;
+    if (!Array.isArray(body)) setEmailConfigured(body.emailConfigured ?? null);
     setUsers(
       rows.map((user) => ({
         ...user,
@@ -112,7 +121,12 @@ function RegistryUsersPage() {
     }
   };
 
-  const mutate = async (user: RegistryUser, action: 'resend' | 'role' | 'status', body: Record<string, string>, successMessage: string) => {
+  const mutate = async (
+    user: RegistryUser,
+    action: 'resend' | 'reset' | 'role' | 'status',
+    body: Record<string, string>,
+    successMessage: string
+  ) => {
     setPending(true);
     setError(null);
     setSuccess(null);
@@ -146,13 +160,17 @@ function RegistryUsersPage() {
   };
 
   return (
-    <AccountLayout title="Users">
+    <AccountLayout config={config} title="Users" description="Invite people and manage their access to this registry.">
       <div className="space-y-6">
         <Card>
           <CardHeader>
             <CardTitle>Invite a user</CardTitle>
             <CardDescription>
-              Email delivery is used when configured. Otherwise, the activation link appears once for manual delivery.
+              {emailConfigured === false
+                ? 'Email delivery is off. Activation and reset links appear once here for you to deliver.'
+                : emailConfigured
+                  ? 'Invitations and reset links are sent by email.'
+                  : null}
             </CardDescription>
           </CardHeader>
           <form onSubmit={invite}>
@@ -170,12 +188,12 @@ function RegistryUsersPage() {
               {manualLink ? (
                 <Alert variant="warning">
                   <MailPlus />
-                  <AlertTitle>Deliver this activation link securely</AlertTitle>
+                  <AlertTitle>Deliver this link securely</AlertTitle>
                   <AlertDescription>
                     <p className="mb-3">It is shown only in this response.</p>
                     <div className="flex gap-2">
                       <Input value={manualLink} readOnly className="text-xs" />
-                      <Button type="button" size="icon" variant="outline" onClick={() => void copyLink()} aria-label="Copy activation link">
+                      <Button type="button" size="icon" variant="outline" onClick={() => void copyLink()} aria-label="Copy link">
                         {copied ? <Check /> : <Copy />}
                       </Button>
                     </div>
@@ -272,6 +290,24 @@ function RegistryUsersPage() {
                             <RefreshCw /> Resend
                           </Button>
                         ) : null}
+                        {user.status === 'active' ? (
+                          <Button
+                            size="sm"
+                            variant="ghost"
+                            disabled={pending}
+                            onClick={() =>
+                              setConfirmation({
+                                title: `Create a password reset link for ${user.email}?`,
+                                description: 'They can use the link to set a new password.',
+                                confirmLabel: 'Create link',
+                                pendingLabel: 'Creating…',
+                                onConfirm: () => mutate(user, 'reset', {}, `Password reset link created for ${user.email}.`),
+                              })
+                            }
+                          >
+                            <KeyRound /> Reset password
+                          </Button>
+                        ) : null}
                         {user.status !== 'invited' ? (
                           <Button
                             size="sm"
@@ -279,11 +315,25 @@ function RegistryUsersPage() {
                             disabled={pending || (user.id === currentUser?.id && user.status === 'active')}
                             onClick={() => {
                               const nextStatus = user.status === 'active' ? 'deactivated' : 'active';
-                              const message =
+                              const onConfirm = () => mutate(user, 'status', { status: nextStatus }, `Updated ${user.email}.`);
+                              setConfirmation(
                                 nextStatus === 'active'
-                                  ? `Reactivate ${user.email}?`
-                                  : `Deactivate ${user.email} and revoke their credentials?`;
-                              if (window.confirm(message)) void mutate(user, 'status', { status: nextStatus }, `Updated ${user.email}.`);
+                                  ? {
+                                      title: `Reactivate ${user.email}?`,
+                                      description: 'They can sign in again. Access tokens revoked at deactivation stay revoked.',
+                                      confirmLabel: 'Reactivate',
+                                      pendingLabel: 'Reactivating…',
+                                      onConfirm,
+                                    }
+                                  : {
+                                      title: `Deactivate ${user.email}?`,
+                                      description: 'They can no longer sign in, and all their access tokens are revoked.',
+                                      confirmLabel: 'Deactivate',
+                                      pendingLabel: 'Deactivating…',
+                                      variant: 'destructive',
+                                      onConfirm,
+                                    }
+                              );
                             }}
                           >
                             {user.status === 'active' ? 'Deactivate' : 'Reactivate'}
@@ -305,6 +355,16 @@ function RegistryUsersPage() {
           </CardContent>
         </Card>
       </div>
+
+      {confirmation ? (
+        <ConfirmDialog
+          {...confirmation}
+          open
+          onOpenChange={(open) => {
+            if (!open) setConfirmation(null);
+          }}
+        />
+      ) : null}
     </AccountLayout>
   );
 }

package/src/app/pages/api/account/ai/keys/[connectionId].ts

@@ -0,0 +1,60 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { MissingEncryptionSecretError, deleteRegistryAiKey, saveRegistryAiKey } from '@handoff/registry/auth';
+import { aiCredentialKind } from '@handoff/ai/connections';
+import { allowApiMethods, prepareRegistryApi } from '@/lib/auth/api';
+import { findAiConnection } from '@/lib/ai/resolve';
+import { getServerRuntimeConfig } from '@/lib/docs-api/runtime-config';
+
+/**
+ * `/api/account/ai/keys/[connectionId]`: save or remove this reader's key for one declared
+ * connection. A connection id the config does not declare with `credential: 'user'` is rejected, so
+ * a reader can never introduce an endpoint of their own.
+ */
+
+/** Longest key worth accepting. Provider keys are short; anything longer is a mistake or an attack. */
+const MAX_KEY_LENGTH = 512;
+
+export default async function accountAiKeyHandler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  const method = allowApiMethods(req, res, ['PUT', 'DELETE']);
+  if (!method) return;
+  if (!getServerRuntimeConfig().ai.enabled) {
+    res.status(404).end();
+    return;
+  }
+  const context = await prepareRegistryApi(req, res, { auth: 'user', mutation: true });
+  if (!context?.user) return;
+
+  const connectionId = typeof req.query.connectionId === 'string' ? req.query.connectionId : '';
+  const connection = findAiConnection(connectionId);
+  if (!connection || aiCredentialKind(connection) !== 'user') {
+    res.status(404).json({ error: 'That AI connection does not take a personal API key.' });
+    return;
+  }
+
+  if (method === 'DELETE') {
+    const removed = await deleteRegistryAiKey(context.db, { userId: context.user.id, connectionId });
+    if (!removed) {
+      res.status(404).json({ error: 'No API key is saved for that connection.' });
+      return;
+    }
+    res.status(200).json({ ok: true });
+    return;
+  }
+
+  const key = typeof (req.body as { key?: unknown })?.key === 'string' ? (req.body as { key: string }).key.trim() : '';
+  if (!key || key.length > MAX_KEY_LENGTH) {
+    res.status(400).json({ error: 'Enter the API key for this provider.' });
+    return;
+  }
+
+  try {
+    await saveRegistryAiKey(context.db, { userId: context.user.id, connectionId, key });
+  } catch (error) {
+    if (error instanceof MissingEncryptionSecretError) {
+      res.status(503).json({ error: error.message, code: 'encryption_secret_missing' });
+      return;
+    }
+    throw error;
+  }
+  res.status(200).json({ ok: true });
+}

package/src/app/pages/api/account/ai/keys/index.ts

@@ -0,0 +1,20 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { allowApiMethods, prepareRegistryApi } from '@/lib/auth/api';
+import { describeAiUserConnections } from '@/lib/ai/resolve';
+import { getServerRuntimeConfig } from '@/lib/docs-api/runtime-config';
+
+/**
+ * `/api/account/ai/keys`: the connections this reader may add a key for, each with whether they
+ * already have. The key value is write-only across this boundary and is never returned.
+ */
+export default async function accountAiKeysHandler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  if (!allowApiMethods(req, res, ['GET'])) return;
+  if (!getServerRuntimeConfig().ai.enabled) {
+    res.status(404).end();
+    return;
+  }
+  const context = await prepareRegistryApi(req, res, { auth: 'user' });
+  if (!context?.user) return;
+
+  res.status(200).json({ connections: await describeAiUserConnections(context.user.id) });
+}

package/src/app/pages/api/admin/users/[id]/[action].ts

@@ -1,5 +1,13 @@
 import type { NextApiRequest, NextApiResponse } from 'next';
-import { resendUserInvitation, setRegistryUserStatus, updateRegistryUserRole, type RegistryUserRole } from '@handoff/registry/auth';
+import {
+  createPasswordReset,
+  getRegistryUserById,
+  resendUserInvitation,
+  setRegistryUserStatus,
+  updateRegistryUserRole,
+  type RegistryUser,
+  type RegistryUserRole,
+} from '@handoff/registry/auth';
 import { allowApiMethods, prepareRegistryApi, registryPageUrl } from '../../../../../lib/auth/api';
 import { registryEmailIsConfigured, sendRegistryAuthEmail } from '../../../../../lib/auth/email';
 
@@ -10,6 +18,32 @@ const mutationError = (reason: string): { status: number; error: string } => {
   return { status: 400, error: 'The requested user change is not valid.' };
 };
 
+/** Email the link when email is configured; otherwise return it once for the administrator to deliver. */
+const deliverLink = async (
+  res: NextApiResponse,
+  user: RegistryUser,
+  link: { url: string; subject: string; heading: string; message: string; actionLabel: string },
+  messages: { sent: string; failed: string; manual: string }
+) => {
+  if (!registryEmailIsConfigured()) {
+    res.status(200).json({ user, message: messages.manual, activationUrl: link.url });
+    return;
+  }
+  const delivered = await sendRegistryAuthEmail({
+    to: user.email,
+    subject: link.subject,
+    heading: link.heading,
+    message: link.message,
+    actionLabel: link.actionLabel,
+    actionUrl: link.url,
+  });
+  if (!delivered) {
+    res.status(502).json({ error: messages.failed });
+    return;
+  }
+  res.status(200).json({ user, message: messages.sent });
+};
+
 export default async function userActionHandler(req: NextApiRequest, res: NextApiResponse) {
   const method = allowApiMethods(req, res, ['POST']);
   if (!method) return;
@@ -65,23 +99,58 @@ export default async function userActionHandler(req: NextApiRequest, res: NextAp
       res.status(500).json({ error: 'AUTH_URL is not configured.' });
       return;
     }
-    if (registryEmailIsConfigured()) {
-      const delivered = await sendRegistryAuthEmail({
-        to: result.user.email,
+    await deliverLink(
+      res,
+      result.user,
+      {
+        url: activationUrl,
         subject: 'Your Handoff Registry invitation',
         heading: 'You are invited',
         message: 'Set a password to activate your Handoff Registry account.',
         actionLabel: 'Accept invitation',
-        actionUrl: activationUrl,
-      });
-      if (!delivered) {
-        res.status(502).json({ error: 'The invitation was renewed, but email delivery failed.' });
-        return;
+      },
+      {
+        sent: 'Invitation resent.',
+        failed: 'The invitation was renewed, but email delivery failed.',
+        manual: 'Invitation renewed for manual delivery.',
       }
-      res.status(200).json({ user: result.user, message: 'Invitation resent.' });
+    );
+    return;
+  }
+
+  if (action === 'reset') {
+    const user = await getRegistryUserById(context.db, userId);
+    if (!user) {
+      res.status(404).json({ error: 'User not found.' });
+      return;
+    }
+    const result = await createPasswordReset(context.db, user.email);
+    if (!result.token || !result.user) {
+      res.status(409).json({ error: 'Only active users can reset their password.' });
       return;
     }
-    res.status(200).json({ user: result.user, message: 'Invitation renewed for manual delivery.', activationUrl });
+    const resetUrl = registryPageUrl('/reset-password', undefined, { token: result.token });
+    if (!resetUrl) {
+      res.status(500).json({ error: 'AUTH_URL is not configured.' });
+      return;
+    }
+    await deliverLink(
+      res,
+      result.user,
+      {
+        url: resetUrl,
+        subject: 'Reset your Handoff Registry password',
+        heading: 'Reset your password',
+        message:
+          'An administrator started a password reset for your account. Use this single-use link to choose a new password. It expires in one hour.',
+        actionLabel: 'Reset password',
+      },
+      {
+        sent: 'Password reset link sent.',
+        failed: 'The reset link was created, but email delivery failed.',
+        manual: 'Password reset link created for manual delivery. It expires in one hour.',
+      }
+    );
     return;
   }
 

package/src/app/pages/api/admin/users/index.ts

@@ -10,7 +10,7 @@ export default async function usersHandler(req: NextApiRequest, res: NextApiResp
   if (!context?.user) return;
 
   if (method === 'GET') {
-    res.status(200).json({ users: await listRegistryUsers(context.db) });
+    res.status(200).json({ users: await listRegistryUsers(context.db), emailConfigured: registryEmailIsConfigured() });
     return;
   }
 
@@ -43,7 +43,7 @@ export default async function usersHandler(req: NextApiRequest, res: NextApiResp
       actionUrl: activationUrl,
     });
     if (!delivered) {
-      res.status(502).json({ error: 'The invitation was created, but email delivery failed. Fix Resend configuration and resend it.' });
+      res.status(502).json({ error: 'The invitation was created, but email delivery failed. Fix the email configuration and resend it.' });
       return;
     }
     res.status(201).json({ user: result.user, message: 'Invitation sent.' });

package/src/app/pages/api/ai/chat.ts

@@ -0,0 +1,115 @@
+import {
+  convertToModelMessages,
+  createUIMessageStream,
+  pipeUIMessageStreamToResponse,
+  stepCountIs,
+  streamText,
+  toUIMessageStream,
+  type UIMessage,
+} from 'ai';
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { allowApiMethods } from '@/lib/api/methods';
+import { authorizeAiRequest } from '@/lib/ai/auth';
+import { withPageContext } from '@/lib/ai/context';
+import { AiConnectionError, createAiLanguageModel } from '@/lib/ai/model';
+import { DOCS_ASSISTANT_PROMPT } from '@/lib/ai/prompt';
+import { describeAiConnections, findAiConnection, selectAiModel } from '@/lib/ai/resolve';
+import { createAiToolSession, type AiSource } from '@/lib/ai/tools';
+import { resolveDocsBackend } from '@/lib/docs-api';
+
+/**
+ * `/api/ai/chat`: the docs assistant's agent loop, streamed to the browser.
+ *
+ * The agent reads through the MCP tools in process (see `lib/ai/tools`), so it answers from the same
+ * records `/api/mcp/` returns and a tool added there needs no work here.
+ */
+
+/**
+ * How many model turns one question may take. A constant rather than config: a loop with no stop
+ * condition can call tools without end, so this is a liveness control, not a spend control. Spend
+ * belongs to the gateway, which enforces budgets and rate limits per key.
+ */
+const MAX_AGENT_STEPS = 12;
+
+const readMessages = (body: unknown): UIMessage[] => {
+  const messages = (body as { messages?: unknown })?.messages;
+  return Array.isArray(messages) ? (messages as UIMessage[]) : [];
+};
+
+export default async function aiChatHandler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  if (!allowApiMethods(req, res, ['POST'])) return;
+  const reader = await authorizeAiRequest(req, res, true);
+  if (!reader) return;
+
+  const messages = readMessages(req.body);
+  if (messages.length === 0) {
+    res.status(400).json({ error: 'Ask a question to start.' });
+    return;
+  }
+
+  const requested = typeof (req.body as { model?: unknown })?.model === 'string' ? (req.body as { model: string }).model : undefined;
+  const selection = selectAiModel(await describeAiConnections(reader.userId), requested);
+  if (!selection) {
+    res.status(409).json({ error: 'No AI provider is available for this account.', code: 'no_usable_connection' });
+    return;
+  }
+
+  const connection = findAiConnection(selection.connection.id);
+  if (!connection) {
+    res.status(409).json({ error: 'No AI provider is available for this account.', code: 'no_usable_connection' });
+    return;
+  }
+
+  let model;
+  try {
+    model = await createAiLanguageModel(connection, selection.model, reader.userId);
+  } catch (error) {
+    if (error instanceof AiConnectionError) {
+      res.status(409).json({ error: error.message, code: 'connection_unavailable' });
+      return;
+    }
+    console.error('AI model could not be built.', error);
+    res.status(500).json({ error: 'The AI provider could not be reached.' });
+    return;
+  }
+
+  const stream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      // Sources are written as the tools return them, so a link appears as soon as the agent has
+      // read the page it came from. Deduplicated because one question often reads a page twice.
+      const seen = new Set<string>();
+      const writeSources = (sources: AiSource[]) => {
+        for (const source of sources) {
+          if (seen.has(source.url)) continue;
+          seen.add(source.url);
+          writer.write({ type: 'source-url', sourceId: source.url, url: source.url, title: source.title });
+        }
+      };
+
+      const session = await createAiToolSession(writeSources);
+      // Torn down with the response, the way `/api/mcp/` does it: the merged stream outlives this
+      // function, and a reader who closes the modal mid-answer must not leave the session open.
+      res.on('close', () => void session.close());
+
+      // A question never fails for want of context.
+      const labeled = await resolveDocsBackend()
+        .then((backend) => withPageContext(messages, backend))
+        .catch(() => messages);
+
+      const result = streamText({
+        model,
+        system: DOCS_ASSISTANT_PROMPT,
+        messages: await convertToModelMessages(labeled),
+        tools: session.tools,
+        stopWhen: stepCountIs(MAX_AGENT_STEPS),
+      });
+      writer.merge(toUIMessageStream({ stream: result.fullStream, tools: session.tools }));
+    },
+    onError: (error) => {
+      console.error('AI chat request failed.', error);
+      return 'The AI provider could not complete this answer.';
+    },
+  });
+
+  await pipeUIMessageStreamToResponse({ response: res, stream });
+}

package/src/app/pages/api/ai/connections.ts

@@ -0,0 +1,23 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { authorizeAiRequest } from '@/lib/ai/auth';
+import { describeAiConnections } from '@/lib/ai/resolve';
+import { getServerRuntimeConfig } from '@/lib/docs-api/runtime-config';
+import { allowApiMethods } from '@/lib/api/methods';
+
+/**
+ * `/api/ai/connections`: the models this reader can actually run right now, for the assistant's
+ * model picker. Never carries a key, only whether one is in place.
+ */
+export default async function aiConnectionsHandler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  if (!allowApiMethods(req, res, ['GET'])) return;
+  const reader = await authorizeAiRequest(req, res);
+  if (!reader) return;
+
+  const connections = await describeAiConnections(reader.userId);
+  res.status(200).json({
+    connections,
+    defaultModel: getServerRuntimeConfig().ai.defaultModel ?? null,
+    /** Whether this deployment has a page where a reader can add their own key. */
+    canAddKeys: getServerRuntimeConfig().mode === 'registry' && connections.some((connection) => connection.credential === 'user'),
+  });
+}