handoff-app 2.0.0-8 → 2.0.0

package/src/app/components/ui/confirm-dialog.tsx

@@ -0,0 +1,87 @@
+'use client';
+
+import { Loader2 } from 'lucide-react';
+import * as React from 'react';
+
+import { Button } from './button';
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from './dialog';
+
+export interface ConfirmDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  title: string;
+  description: React.ReactNode;
+  confirmLabel: string;
+  /** Shown on the confirm button while `onConfirm` runs. */
+  pendingLabel?: string;
+  variant?: 'default' | 'destructive';
+  /** The dialog closes when this resolves. When it throws, the dialog stays open and shows the error. */
+  onConfirm: () => void | Promise<void>;
+}
+
+/**
+ * A confirmation step before an action. It behaves as an alert dialog: a click outside does not dismiss
+ * it, and focus starts on Cancel, so pressing Enter does not confirm by accident.
+ */
+export function ConfirmDialog({
+  open,
+  onOpenChange,
+  title,
+  description,
+  confirmLabel,
+  pendingLabel,
+  variant = 'default',
+  onConfirm,
+}: ConfirmDialogProps) {
+  const [isPending, setIsPending] = React.useState(false);
+  const [error, setError] = React.useState<string | null>(null);
+
+  const changeOpen = (next: boolean) => {
+    if (isPending) return;
+    if (!next) setError(null);
+    onOpenChange(next);
+  };
+
+  const confirm = async () => {
+    if (isPending) return;
+    setIsPending(true);
+    setError(null);
+    try {
+      await onConfirm();
+      onOpenChange(false);
+    } catch (reason) {
+      setError(reason instanceof Error ? reason.message : 'Could not complete this action.');
+    } finally {
+      setIsPending(false);
+    }
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={changeOpen}>
+      <DialogContent role="alertdialog" className="sm:max-w-md" onInteractOutside={(event) => event.preventDefault()}>
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+          <DialogDescription>{description}</DialogDescription>
+        </DialogHeader>
+
+        {error ? <p className="text-xs text-destructive">{error}</p> : null}
+
+        <DialogFooter>
+          <Button variant="ghost" size="sm" disabled={isPending} onClick={() => changeOpen(false)}>
+            Cancel
+          </Button>
+          <Button variant={variant} size="sm" disabled={isPending} onClick={() => void confirm()}>
+            {isPending ? (
+              <>
+                <Loader2 className="animate-spin" aria-hidden />
+                {pendingLabel ?? confirmLabel}
+              </>
+            ) : (
+              confirmLabel
+            )}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/app/components/ui/dialog.tsx

@@ -17,7 +17,7 @@ const DialogOverlay = React.forwardRef<
   <DialogPrimitive.Overlay
     ref={ref}
     className={cn(
-      'fixed inset-0 z-50 bg-gray-200/50 backdrop-blur-xs data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
+      'fixed inset-0 z-50 bg-gray-200/50 backdrop-blur-xs dark:bg-gray-950/60 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
       className
     )}
     {...props}
@@ -54,6 +54,11 @@ const DialogHeader = ({ className, ...props }: React.HTMLAttributes<HTMLDivEleme
 );
 DialogHeader.displayName = 'DialogHeader';
 
+const DialogFooter = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
+  <div className={cn('flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2', className)} {...props} />
+);
+DialogFooter.displayName = 'DialogFooter';
+
 const DialogTitle = React.forwardRef<
   React.ElementRef<typeof DialogPrimitive.Title>,
   React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>
@@ -70,4 +75,4 @@ const DialogDescription = React.forwardRef<
 ));
 DialogDescription.displayName = DialogPrimitive.Description.displayName;
 
-export { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogTrigger };
+export { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger };

package/src/app/components/ui/marker.tsx

@@ -0,0 +1,56 @@
+import { Slot } from '@radix-ui/react-slot';
+import { cva, type VariantProps } from 'class-variance-authority';
+import * as React from 'react';
+
+import { cn } from '../../lib/utils';
+
+const markerVariants = cva(
+  "group/marker relative flex min-h-4 w-full items-center gap-2 text-left text-sm text-muted-foreground [&_svg:not([class*='size-'])]:size-4 [a]:underline [a]:underline-offset-3 [a]:hover:text-foreground",
+  {
+    variants: {
+      variant: {
+        default: '',
+        separator:
+          'before:mr-1 before:h-px before:min-w-0 before:flex-1 before:bg-border after:ml-1 after:h-px after:min-w-0 after:flex-1 after:bg-border',
+        border: 'border-b border-border pb-2',
+      },
+    },
+  }
+);
+
+function Marker({
+  className,
+  variant = 'default',
+  asChild = false,
+  ...props
+}: React.ComponentProps<'div'> & VariantProps<typeof markerVariants> & { asChild?: boolean }) {
+  const Comp = asChild ? Slot : 'div';
+
+  return <Comp data-slot="marker" data-variant={variant} className={cn(markerVariants({ variant, className }))} {...props} />;
+}
+
+function MarkerIcon({ className, ...props }: React.ComponentProps<'span'>) {
+  return (
+    <span
+      data-slot="marker-icon"
+      aria-hidden="true"
+      className={cn("size-4 shrink-0 [&_svg:not([class*='size-'])]:size-4", className)}
+      {...props}
+    />
+  );
+}
+
+function MarkerContent({ className, ...props }: React.ComponentProps<'span'>) {
+  return (
+    <span
+      data-slot="marker-content"
+      className={cn(
+        'wrap-break-word min-w-0 group-data-[variant=separator]/marker:flex-none group-data-[variant=separator]/marker:text-center',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Marker, MarkerContent, MarkerIcon, markerVariants };

package/src/app/components/ui/sidebar.tsx

@@ -272,7 +272,9 @@ const SidebarInset = React.forwardRef<HTMLDivElement, React.ComponentProps<'main
     <main
       ref={ref}
       className={cn(
-        'relative flex w-full flex-1 flex-col bg-background',
+        // `min-w-0` lets the column shrink below its widest descendant, so a wide table or code block
+        // scrolls inside itself instead of widening the page.
+        'relative flex w-full min-w-0 flex-1 flex-col bg-background',
         'md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-sm',
         className
       )}

package/src/app/components/util/index.ts

@@ -10,6 +10,7 @@ import { KNOWN_PATHS } from '@handoff/utils/menu-shell';
 import { collectPageSlugSegments } from '@handoff/utils/pages';
 import { getRegistryNavData, getWorkspaceNavData, type NavData, type NavTokenSet, type SectionLink } from '@handoff/nav';
 import { resolveDocsBackend } from '../../lib/docs-api/backend';
+import { documentationMetadata } from '../../lib/docs-api/page-rendering';
 import { tokenFormatStrings } from '../../lib/docs-api/token-detail';
 // Build-time-baked navigation shell. Imported statically (same as `pages/api/docs/nav.json.ts`) so
 // it is bundled into the route chunk and readable at request time in the Vercel registry lambda,
@@ -543,7 +544,8 @@ export const fetchDocPageMetadataAndContent = (localPath: string, slug: string |
     currentContents = fs.readFileSync(contentModuleFilePath, 'utf-8');
   }
 
-  const { data: metadata, content } = parseMarkdown(currentContents);
+  const { data, content } = parseMarkdown(currentContents);
+  const metadata: typeof data = { ...data, ...documentationMetadata(data) };
 
   return { metadata, content, options: {} };
 };
@@ -555,17 +557,6 @@ export const fetchDocPageMetadataAndContent = (localPath: string, slug: string |
  */
 export const filterOutUndefined = <T>(value: T): value is NonNullable<T> => value !== undefined;
 
-/**
- * Create a title string from a prefix
- * @param prefix
- * @returns
- */
-export const titleString = (prefix: string | null): string => {
-  const config = getClientRuntimeConfig();
-  const prepend = prefix ? `${prefix} | ` : '';
-  return `${prepend}${config?.app?.client} Design System`;
-};
-
 /**
  * Get the tokens for a component
  * @param component

package/src/app/css/index.css

@@ -159,6 +159,70 @@
 	}
 }
 
+/*
+  The docked assistant and the column the page leaves for it.
+
+  `--ai-dock-width` is the single source for both, so the panel and the page can never disagree and
+  one transition moves both. It is `0px` with the dock closed, or on a viewport too narrow to carry
+  a column. An inline script in `_document` sets it before the first paint, so a reader who left the
+  dock open does not watch the page reflow after hydration.
+
+  A resize drag writes the variable on every pointer move, so the transition is dropped for the drag
+  or the page eases along behind the pointer.
+*/
+.ai-dock-inset {
+	padding-right: var(--ai-dock-width, 0px);
+}
+
+/* The app header keeps the full width, and the dock starts below it. */
+.ai-dock-bleed {
+	margin-right: calc(-1 * var(--ai-dock-width, 0px));
+}
+
+.ai-dock-inset,
+.ai-dock-bleed,
+.ai-dock {
+	transition:
+		width 0.2s ease-out,
+		padding-right 0.2s ease-out,
+		margin-right 0.2s ease-out;
+}
+
+.ai-assistant-trigger {
+	display: inline-flex;
+	flex-shrink: 0;
+	max-width: 9rem;
+	overflow: hidden;
+	opacity: 1;
+	transition:
+		max-width 0.2s ease-out,
+		margin-right 0.2s ease-out,
+		opacity 0.2s ease-out;
+}
+
+.ai-assistant-trigger[data-open='true'],
+[data-ai-dock-open='true'] .ai-assistant-trigger {
+	pointer-events: none;
+	margin-right: -1rem;
+	max-width: 0;
+	opacity: 0;
+}
+
+[data-ai-dock-resizing] .ai-dock-inset,
+[data-ai-dock-resizing] .ai-dock-bleed,
+[data-ai-dock-resizing] .ai-dock {
+	transition: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.ai-dock-inset,
+	.ai-dock-bleed,
+	.ai-dock,
+	.ai-assistant-trigger {
+		transition: none;
+	}
+}
+
 @layer base {
 	* {
 		@apply border-border;

package/src/app/lib/ai/auth.ts

@@ -0,0 +1,33 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { getServerRuntimeConfig } from '../docs-api/runtime-config';
+
+/**
+ * Authorization for the AI routes.
+ *
+ * The chat route authorizes once, on the session, the way the account routes do. This holds only
+ * while every tool the agent can reach is read-only; a tool that writes must assert its own scope.
+ *
+ * A build with the assistant turned off answers 404 rather than 403, so a feature that is absent
+ * reads as absent instead of as something a credential would unlock. That check runs before any
+ * auth work, exactly as `/api/mcp/` does it.
+ */
+
+/** The reader behind one request: a registry user id, or `null` in a workspace, which has one user. */
+export interface AiReader {
+  userId: string | null;
+}
+
+export const authorizeAiRequest = async (req: NextApiRequest, res: NextApiResponse, mutation = false): Promise<AiReader | null> => {
+  const runtime = getServerRuntimeConfig();
+  if (!runtime.ai.enabled) {
+    res.status(404).end();
+    return null;
+  }
+  if (runtime.mode !== 'registry') {
+    return { userId: null };
+  }
+  // Imported lazily so the registry auth/database dependencies stay out of the workspace path.
+  const { prepareRegistryApi } = await import('../auth/api');
+  const context = await prepareRegistryApi(req, res, { auth: 'user', mutation });
+  return context?.user ? { userId: context.user.id } : null;
+};

package/src/app/lib/ai/context.ts

@@ -0,0 +1,99 @@
+import type { UIMessage } from 'ai';
+
+import type { DocsBackend } from '../docs-api/backend';
+import { pageIdFromUrl } from '../mcp/page-url';
+
+/**
+ * The page a question was asked from.
+ *
+ * The client sends only the route. The server resolves it through the docs backend, so only
+ * backend data reaches the model and the raw route never does.
+ */
+
+export type AiPageKind = 'component' | 'pattern' | 'page';
+
+export interface AiPageRef {
+  kind: AiPageKind;
+  id: string;
+}
+
+/** Token and foundation routes map to token sets, not pages, so they give no context yet. */
+const UNSUPPORTED = /^(system\/tokens|foundations)(\/|$)/;
+
+/** The entity a route shows, or `null` for a route that gives no context. Pure, so the client uses it too. */
+export const pageRefFromPath = (path: string): AiPageRef | null => {
+  const id = pageIdFromUrl(path);
+  if (id === null || UNSUPPORTED.test(id)) return null;
+  const entity = /^system\/(component|pattern)\/([^/]+)$/.exec(id);
+  if (entity) return { kind: entity[1] as AiPageKind, id: decodeURIComponent(entity[2]) };
+  return { kind: 'page', id };
+};
+
+/** One line, bounded, and unable to open or close a tag, so an authored title cannot reshape the prompt. */
+const clean = (text: string, max: number): string => {
+  const line = text
+    .replace(/[\u0000-\u001f\u007f<>]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+};
+
+/**
+ * The fields of a question's `<application_context>` block, or `null` when the route gives no
+ * context. Identity only: the agent reads the detail with its tools. Patterns have no tool, so their
+ * block also carries the description.
+ */
+const describePage = async (backend: DocsBackend, path: string): Promise<string[] | null> => {
+  const ref = pageRefFromPath(path);
+  if (!ref) return null;
+  try {
+    if (ref.kind === 'component') {
+      const component = await backend.getComponentDetail(ref.id);
+      if (!component) return null;
+      return ['page: component', `title: ${clean(component.title || component.id, 50)}`, `id: ${clean(component.id, 50)}`];
+    }
+    if (ref.kind === 'pattern') {
+      const pattern = await backend.getPatternDetail(ref.id);
+      if (!pattern) return null;
+      return [
+        'page: pattern',
+        `title: ${clean(pattern.title || pattern.id, 50)}`,
+        `id: ${clean(pattern.id, 50)}`,
+        ...(pattern.description ? [`description: ${clean(pattern.description, 80)}`] : []),
+      ];
+    }
+    const page = await backend.getPageDetail(ref.id);
+    if (!page) return null;
+    return ['page: docs page', `title: ${clean(page.title || page.id, 50)}`, `url: ${clean(page.path, 50)}`];
+  } catch {
+    return null;
+  }
+};
+
+const CONTEXT_TAG = /<(\/?)application_context/gi;
+
+/**
+ * The conversation as the model reads it: each question starts with an `<application_context>`
+ * block for the page it was asked from, taken from its own `metadata.path`. A question with no
+ * resolvable page gets no block.
+ *
+ * The reader's own text has the tag escaped, so every block the model sees is one the site wrote.
+ */
+export const withPageContext = async (messages: UIMessage[], backend: DocsBackend): Promise<UIMessage[]> => {
+  const pages = new Map<string, Promise<string[] | null>>();
+  return Promise.all(
+    messages.map(async (message) => {
+      if (message.role !== 'user') return message;
+      const parts = message.parts.map((part) =>
+        part.type === 'text' ? { ...part, text: part.text.replace(CONTEXT_TAG, '&lt;$1application_context') } : part
+      );
+      const path = (message.metadata as { path?: unknown } | undefined)?.path;
+      if (typeof path !== 'string') return { ...message, parts };
+      if (!pages.has(path)) pages.set(path, describePage(backend, path));
+      const fields = await pages.get(path);
+      if (!fields) return { ...message, parts };
+      const block = ['<application_context>', ...fields, '</application_context>'].join('\n');
+      return { ...message, parts: [{ type: 'text' as const, text: block }, ...parts] };
+    })
+  );
+};

package/src/app/lib/ai/model.ts

@@ -0,0 +1,79 @@
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { aiCredentialKind, type AiConnectionSettings } from '@handoff/ai/connections';
+
+import type { AiProvider } from '@handoff/ai/types';
+import type { LanguageModel } from 'ai';
+import { getServerRuntimeConfig } from '../docs-api/runtime-config';
+import { loadServerModule } from '../server-module';
+
+/**
+ * Server-only model construction.
+ *
+ * Every built-in connection speaks the OpenAI-compatible `/chat/completions` API. A connection that
+ * fits nothing else names a `defineAiProvider()` module instead of a base URL.
+ *
+ * The base URL always comes from the config, never from the request, so the server can never be
+ * made to call an endpoint a reader chose.
+ */
+
+/** Thrown when a connection cannot be used as configured. The message is safe to show the reader. */
+export class AiConnectionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AiConnectionError';
+  }
+}
+
+/**
+ * The key to send for this connection: the deployment's own for a service connection, this reader's
+ * for a `credential: 'user'` one, and none where the endpoint needs none.
+ *
+ * The registry data layer is imported lazily so its Postgres dependencies stay out of the workspace
+ * path.
+ */
+export const resolveAiKey = async (connection: AiConnectionSettings, userId: string | null): Promise<string | undefined> => {
+  const credential = aiCredentialKind(connection);
+  if (credential === 'none') return undefined;
+  if (credential === 'service') {
+    const key = connection.apiKeyEnv ? process.env[connection.apiKeyEnv]?.trim() : undefined;
+    if (!key) {
+      throw new AiConnectionError(`${connection.label} is not available: its API key environment variable is not set.`);
+    }
+    return key;
+  }
+  if (!userId || getServerRuntimeConfig().mode !== 'registry') {
+    throw new AiConnectionError(`${connection.label} needs your own API key, and this deployment has no place to store one.`);
+  }
+  const [{ getRegistryConnection }, { readRegistryAiKey }] = await Promise.all([
+    import('../registry-connection'),
+    import('@handoff/registry/auth'),
+  ]);
+  const { db } = await getRegistryConnection();
+  const key = await readRegistryAiKey(db, { userId, connectionId: connection.id });
+  if (!key) {
+    throw new AiConnectionError(`Add your ${connection.label} API key on the AI providers page before using this model.`);
+  }
+  return key;
+};
+
+/** Load a custom provider module and coerce its default export (provider object or factory) to a provider. */
+const loadProviderModule = async (connection: AiConnectionSettings, apiKey: string | undefined): Promise<AiProvider> => {
+  const candidate = (await loadServerModule(connection.module!, { options: connection.options, apiKey })) as Partial<AiProvider> | null;
+  if (!candidate || typeof candidate.languageModel !== 'function') {
+    throw new AiConnectionError(`Custom AI provider module "${connection.module}" must default-export a defineAiProvider provider.`);
+  }
+  return candidate as AiProvider;
+};
+
+/** Build the language model for one declared connection and one of its declared models. */
+export const createAiLanguageModel = async (
+  connection: AiConnectionSettings,
+  model: string,
+  userId: string | null
+): Promise<LanguageModel> => {
+  const apiKey = await resolveAiKey(connection, userId);
+  if (connection.module) {
+    return (await loadProviderModule(connection, apiKey)).languageModel(model);
+  }
+  return createOpenAICompatible({ name: connection.id, baseURL: connection.baseUrl!, apiKey }).chatModel(model);
+};

package/src/app/lib/ai/prompt.ts

@@ -0,0 +1,36 @@
+/**
+ * The assistant's system prompt.
+ *
+ * One instruction earns its place: the catalog is finite and checkable, so a confident wrong answer
+ * does real damage and "I don't know" has to read as the correct answer. Nothing here tells the
+ * agent to keep responses small, because no tool returns more than what it is asked for.
+ */
+export const DOCS_ASSISTANT_PROMPT = [
+  'You answer questions about the design system documented by this site.',
+  '',
+  'Ground factual answers in the tools. Search with handoff_search_components or handoff_search_pages,',
+  'then read the relevant record with handoff_get_component or handoff_get_page. For a component preview,',
+  'use its preview id with handoff_get_component_preview. For its implementation, use',
+  'handoff_get_component_source. Use handoff_get_tokens for colors, typography and spacing.',
+  '',
+  'Do not invent components, props, variants, pages or token values. If the tools do not contain',
+  'something, say that it is not in this design system.',
+  '',
+  'Messages may include an <application_context> block written by the site. It describes what the',
+  'reader was viewing when that message was sent. Do not mention the block.',
+  '',
+  'Resolve references using this order:',
+  '1. An explicitly named subject in the current message.',
+  '2. The subject established by the recent conversation.',
+  '3. The application context for that message.',
+  '',
+  'Treat follow-ups such as "it", "that component", "its props" or "what about variants?" as referring',
+  'to the established conversational subject unless the reader clearly changes the subject.',
+  'Treat phrases such as "this component", "this page" or "the current component" as referring to the',
+  'application context when applicable.',
+  '',
+  'When the application context identifies the needed record, read it directly instead of searching.',
+  '',
+  'Answer in short, specific prose. Name components and tokens you read. Use code blocks only for',
+  'code or markup the reader would copy. Do not list source pages; the site shows them separately.',
+].join('\n');

package/src/app/lib/ai/resolve.ts

@@ -0,0 +1,97 @@
+import { aiCredentialKind, parseAiModelId, type AiConnectionSettings } from '@handoff/ai/connections';
+import type { AiCredentialKind } from '@handoff/types/config';
+import { getServerRuntimeConfig } from '../docs-api/runtime-config';
+
+/**
+ * Per-request AI connection resolution.
+ *
+ * Reports what the config declared and whether a usable key exists for the current reader. The key
+ * value itself never leaves the server: the browser only ever learns `configured`.
+ */
+
+/** One connection as the browser sees it. */
+export interface ResolvedAiConnection {
+  id: string;
+  label: string;
+  /** Absent for a connection served by a `defineAiProvider()` module rather than a base URL. */
+  baseUrl?: string;
+  models?: string[];
+  credential: AiCredentialKind;
+  /**
+   * Whether this reader can use the connection right now: the deployment's key is set, the endpoint
+   * needs none, or the reader has saved their own.
+   */
+  configured: boolean;
+}
+
+/** Find a declared connection by id. Ids only ever come from the resolved list, never from a reader. */
+export const findAiConnection = (connectionId: string): AiConnectionSettings | undefined =>
+  getServerRuntimeConfig().ai.connections.find((connection) => connection.id === connectionId);
+
+/**
+ * Read this reader's saved connection ids. Registry mode only — a workspace has one user, whose
+ * config file and `.env` are their user layer, so it has no per-user key store.
+ *
+ * The registry data layer is imported lazily so the Drizzle/Postgres dependencies stay out of the
+ * workspace path, the same way the rest of the registry runtime is reached.
+ */
+const readSavedConnections = async (userId: string | null): Promise<Set<string>> => {
+  if (!userId || getServerRuntimeConfig().mode !== 'registry') return new Set();
+  const [{ getRegistryConnection }, { listRegistryAiKeyConnections }] = await Promise.all([
+    import('../registry-connection'),
+    import('@handoff/registry/auth'),
+  ]);
+  const { db } = await getRegistryConnection();
+  return new Set(await listRegistryAiKeyConnections(db, userId));
+};
+
+/** Whether a connection is usable for a reader, given the keys that reader has saved. */
+const isConfigured = (connection: AiConnectionSettings, saved: ReadonlySet<string>): boolean => {
+  switch (aiCredentialKind(connection)) {
+    case 'service':
+      return Boolean(connection.apiKeyEnv && process.env[connection.apiKeyEnv]?.trim());
+    case 'user':
+      return saved.has(connection.id);
+    default:
+      return true;
+  }
+};
+
+/** Every declared connection, each marked with whether this reader can use it. */
+export const describeAiConnections = async (userId: string | null): Promise<ResolvedAiConnection[]> => {
+  const { ai } = getServerRuntimeConfig();
+  const saved = await readSavedConnections(userId);
+  return ai.connections.map((connection) => ({
+    id: connection.id,
+    label: connection.label,
+    ...(connection.baseUrl ? { baseUrl: connection.baseUrl } : {}),
+    ...(connection.models?.length ? { models: connection.models } : {}),
+    credential: aiCredentialKind(connection),
+    configured: isConfigured(connection, saved),
+  }));
+};
+
+/** The connections a reader may add a key for. Empty when the config declares none. */
+export const describeAiUserConnections = async (userId: string | null): Promise<ResolvedAiConnection[]> =>
+  (await describeAiConnections(userId)).filter((connection) => connection.credential === 'user');
+
+/**
+ * The model to run, given what the reader asked for. A requested model must name a declared
+ * connection and one of that connection's declared models, so a reader can never reach a model the
+ * deployment did not list. Falls back to `defaultModel`, then to the first usable model.
+ */
+export const selectAiModel = (
+  connections: readonly ResolvedAiConnection[],
+  requested: string | undefined
+): { connection: ResolvedAiConnection; model: string } | null => {
+  const usable = connections.filter((connection) => connection.configured && connection.models?.length);
+  const pick = (value: string | undefined) => {
+    const parsed = value ? parseAiModelId(value) : null;
+    if (!parsed) return null;
+    const connection = usable.find((candidate) => candidate.id === parsed.connectionId);
+    return connection?.models?.includes(parsed.model) ? { connection, model: parsed.model } : null;
+  };
+  const { ai } = getServerRuntimeConfig();
+  const first = usable[0];
+  return pick(requested) ?? pick(ai.defaultModel) ?? (first?.models?.[0] ? { connection: first, model: first.models[0] } : null);
+};