handoff-app 2.0.0-8 → 2.0.0

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

@@ -0,0 +1,120 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { dynamicTool, jsonSchema, type ToolSet } from 'ai';
+import { createMcpServer } from '../mcp';
+
+/**
+ * The assistant's tools: the MCP server's own tools, reached in process.
+ *
+ * The chat route connects a client to {@link createMcpServer} over a linked in-memory transport
+ * pair rather than calling `/api/mcp/` over HTTP. In registry mode that endpoint demands a
+ * `registry:read` bearer token while the browser holds a session cookie, so the server would have
+ * to mint a token to call itself, and the HTTP hop is needless inside one function either way.
+ *
+ * A tool added to the MCP server therefore reaches the assistant with no further work here.
+ */
+
+/** A page or component a tool read, surfaced to the reader as a link under the answer. */
+export interface AiSource {
+  url: string;
+  title: string;
+}
+
+export interface AiToolSession {
+  tools: ToolSet;
+  close: () => Promise<void>;
+}
+
+/** Docs route for one component id. Patterns and pages carry their own paths. */
+const componentUrl = (id: string): string => `/system/component/${encodeURIComponent(id)}`;
+
+const asRecord = (value: unknown): Record<string, unknown> | null =>
+  value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+
+const text = (value: unknown): string | undefined => (typeof value === 'string' && value.trim() ? value.trim() : undefined);
+
+/**
+ * The pages and components behind one tool result, so the answer can link to what it was read from.
+ * Only the shapes `./shape` produces are recognized; anything else contributes no source, which
+ * costs a link rather than breaking the answer.
+ */
+const sourcesOf = (toolName: string, payload: unknown): AiSource[] => {
+  const record = asRecord(payload);
+  if (!record) return [];
+
+  if (toolName === 'handoff_get_component' || toolName === 'handoff_get_component_source') {
+    const id = text(record.id);
+    return id ? [{ url: componentUrl(id), title: text(record.title) ?? id }] : [];
+  }
+  // A preview links to the component's docs page, which is where a reader sees it rendered.
+  if (toolName === 'handoff_get_component_preview') {
+    const component = asRecord(record.component);
+    const id = component && text(component.id);
+    return id ? [{ url: componentUrl(id), title: text(component.title) ?? id }] : [];
+  }
+  if (toolName === 'handoff_get_page') {
+    const url = text(record.url);
+    return url ? [{ url, title: text(record.title) ?? url }] : [];
+  }
+  if (toolName === 'handoff_search_pages') {
+    const results = Array.isArray(record.results) ? record.results : [];
+    return results.flatMap((entry) => {
+      const page = asRecord(entry);
+      const url = page && text(page.url);
+      return url ? [{ url, title: text(page.title) ?? url }] : [];
+    });
+  }
+  return [];
+};
+
+/** Parse the single JSON text block an MCP tool returns. */
+const parseToolPayload = (result: CallToolResult): unknown => {
+  const block = result.content?.find((entry) => entry.type === 'text');
+  if (!block || block.type !== 'text') return null;
+  try {
+    return JSON.parse(block.text);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Build the tool set for one request. Tool descriptions and input schemas come from the MCP server
+ * itself, so the agent sees what any other MCP client would.
+ *
+ * @param onSources - Called with the pages and components each tool read, as they are read.
+ */
+export const createAiToolSession = async (onSources: (sources: AiSource[]) => void): Promise<AiToolSession> => {
+  const server = createMcpServer();
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const client = new Client({ name: 'handoff-docs-assistant', version: '1.0.0' });
+  await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+
+  const { tools: definitions } = await client.listTools();
+  const tools: ToolSet = Object.fromEntries(
+    definitions.map((definition) => [
+      definition.name,
+      dynamicTool({
+        description: definition.description,
+        inputSchema: jsonSchema(definition.inputSchema as Parameters<typeof jsonSchema>[0]),
+        execute: async (input) => {
+          const result = (await client.callTool({
+            name: definition.name,
+            arguments: (asRecord(input) ?? {}) as Record<string, unknown>,
+          })) as CallToolResult;
+          if (!result.isError) onSources(sourcesOf(definition.name, parseToolPayload(result)));
+          return result.content;
+        },
+      }),
+    ])
+  );
+
+  return {
+    tools,
+    close: async () => {
+      await client.close();
+      await server.close();
+    },
+  };
+};

package/src/app/lib/api/methods.ts

@@ -0,0 +1,13 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+
+/**
+ * Method guard shared by every API route. It carries no registry dependency, so routes that also
+ * serve workspace mode can use it without pulling the registry auth/database layer into that path.
+ */
+export const allowApiMethods = (req: NextApiRequest, res: NextApiResponse, methods: string[]): string | null => {
+  const method = (req.method ?? 'GET').toUpperCase();
+  if (methods.includes(method)) return method;
+  res.setHeader('Allow', methods.join(', '));
+  res.status(405).json({ error: `Method ${method} is not allowed.` });
+  return null;
+};

package/src/app/lib/asset-storage.ts

@@ -1,21 +1,20 @@
 /**
  * Server-only asset storage runtime. Resolves the active provider from the baked server runtime
- * config and lazily builds/memoizes adapter instances. Writes use the active adapter; reads resolve
- * by each blob's recorded provider id, so DB-backed (`database`, inline bytea) and object-backed
- * blobs coexist and old blobs stay readable after the active provider changes. `database` is the
- * inline default with no adapter (bytes live directly in `asset_blobs.content`).
+ * config and lazily builds and memoizes it. Writes use the active provider. Reads resolve by each
+ * blob's recorded provider, so `database` blobs (inline bytea) stay readable when a `custom` provider
+ * is active. `database` has no module: its bytes live directly in `asset_blobs.content`.
  *
  * Imported exclusively by registry API route handlers and the registry store.
  */
 
-import { createVercelBlobStorage } from '@handoff/registry/asset-storage/adapters/vercel-blob';
 import { resolveAssetStorageSettings, type ResolvedAssetStorage } from '@handoff/registry/asset-storage/resolve';
-import type { AssetStorage, AssetStorageFactory } from '@handoff/registry/asset-storage/types';
+import type { StorageProvider } from '@handoff/registry/asset-storage/types';
 import type { AssetStorageProvider } from '@handoff/registry/db/schema';
 import { getServerRuntimeConfig } from './docs-api/runtime-config';
+import { loadServerModule } from './server-module';
 
 let activeCache: ResolvedAssetStorage | null = null;
-const adapterCache = new Map<string, AssetStorage | null>();
+const providerCache = new Map<string, StorageProvider | null>();
 
 /** The active, fully-resolved asset storage settings for new uploads. */
 export const getActiveAssetStorage = (): ResolvedAssetStorage => {
@@ -25,57 +24,57 @@ export const getActiveAssetStorage = (): ResolvedAssetStorage => {
   return activeCache;
 };
 
-/** Load a custom adapter module and coerce its default export (adapter object or factory) to an adapter. */
-const loadCustomAdapter = async (active: ResolvedAssetStorage): Promise<AssetStorage> => {
+/** A storage configuration error whose message is safe to show to a client. */
+export class AssetStorageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AssetStorageError';
+  }
+}
+
+/** Load a custom provider module and coerce its default export (provider object or factory) to a provider. */
+const loadCustomProvider = async (active: ResolvedAssetStorage): Promise<StorageProvider> => {
   if (!active.module) {
-    throw new Error('A custom asset storage adapter is selected but no module path is configured.');
+    throw new AssetStorageError('A custom asset storage provider is selected but no module path is configured.');
   }
-  // Traced into the registry bundle at build time; resolved by Node at runtime (see build tracing).
-  const mod: any = await import(/* webpackIgnore: true */ active.module);
-  const exported = mod?.default ?? mod;
-  const adapter: unknown = typeof exported === 'function' ? await (exported as AssetStorageFactory)({ options: active.options, env: process.env }) : exported;
-  const candidate = adapter as Partial<AssetStorage> | null;
+  const candidate = (await loadServerModule(active.module, { options: active.options })) as Partial<StorageProvider> | null;
   if (!candidate || typeof candidate.put !== 'function' || typeof candidate.get !== 'function' || typeof candidate.delete !== 'function') {
-    throw new Error(`Custom asset storage module "${active.module}" must default-export a defineAssetStorage adapter.`);
+    throw new AssetStorageError(`Custom asset storage module "${active.module}" must default-export a defineStorageProvider() result.`);
   }
-  return candidate as AssetStorage;
+  return candidate as StorageProvider;
 };
 
 /**
- * Resolve the {@link AssetStorage} adapter for a provider id, or `null` when the provider is the
- * inline `database` default (there is no adapter; content lives in the DB row). Reading a blob whose
+ * Resolve the {@link StorageProvider} for a recorded provider, or `null` when the provider is the
+ * inline `database` default (there is no module; content lives in the DB row). Reading a blob whose
  * provider is no longer configured throws an actionable error rather than silently failing.
  */
-export const getAssetStorageAdapter = async (provider: AssetStorageProvider): Promise<AssetStorage | null> => {
+export const getStorageProvider = async (provider: AssetStorageProvider): Promise<StorageProvider | null> => {
   if (provider === 'database') {
     return null;
   }
-  if (adapterCache.has(provider)) {
-    return adapterCache.get(provider) ?? null;
+  if (providerCache.has(provider)) {
+    return providerCache.get(provider) ?? null;
   }
 
   const active = getActiveAssetStorage();
-  let adapter: AssetStorage;
-  if (provider === 'vercel-blob') {
-    adapter = createVercelBlobStorage({ tokenEnv: active.tokenEnv, options: active.options });
-  } else if (active.adapterKind === 'custom' && active.provider === provider) {
-    adapter = await loadCustomAdapter(active);
-  } else {
-    throw new Error(
-      `No asset storage adapter is configured for provider "${provider}". A blob was stored by that ` +
-        'provider but it is no longer selected. Restore its configuration (or migrate its objects) to read it.'
+  if (active.provider !== provider) {
+    throw new AssetStorageError(
+      `No asset storage module is configured for provider "${provider}". A blob was stored by that ` +
+        'provider but it is no longer selected. Restore its configuration to read it.'
     );
   }
+  const storage = await loadCustomProvider(active);
 
-  adapterCache.set(provider, adapter);
-  return adapter;
+  providerCache.set(provider, storage);
+  return storage;
 };
 
-/** The adapter for the active provider (used for new uploads), or `null` for the inline database default. */
-export const getActiveAssetStorageAdapter = (): Promise<AssetStorage | null> => getAssetStorageAdapter(getActiveAssetStorage().provider);
+/** The active provider (used for new uploads), or `null` for the inline database default. */
+export const getActiveStorageProvider = (): Promise<StorageProvider | null> => getStorageProvider(getActiveAssetStorage().provider);
 
 /** Reset memoized state (test seam only). */
 export const __resetAssetStorageCache = (): void => {
   activeCache = null;
-  adapterCache.clear();
+  providerCache.clear();
 };

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

@@ -3,21 +3,13 @@ import type { RegistryDatabase } from '@handoff/registry/db/client';
 import { getRegistryInstallationState, type RegistryUser } from '@handoff/registry/auth';
 import { getServerRuntimeConfig } from '../docs-api/runtime-config';
 import { getRegistryConnection, RegistryConnectionError } from '../registry-connection';
+import { allowApiMethods } from '../api/methods';
 import { canonicalRegistryUrl, getRegistrySessionUser } from './config';
 
-export const allowApiMethods = (req: NextApiRequest, res: NextApiResponse, methods: string[]): string | null => {
-  const method = (req.method ?? 'GET').toUpperCase();
-  if (methods.includes(method)) return method;
-  res.setHeader('Allow', methods.join(', '));
-  res.status(405).json({ error: `Method ${method} is not allowed.` });
-  return null;
-};
+// Re-exported so the registry routes keep reaching it here, next to the authorization they pair it with.
+export { allowApiMethods };
 
-export const registryPageUrl = (
-  path: string,
-  query?: Record<string, string>,
-  fragment?: Record<string, string>
-): string | null => {
+export const registryPageUrl = (path: string, query?: Record<string, string>, fragment?: Record<string, string>): string | null => {
   const canonical = canonicalRegistryUrl();
   if (!canonical) return null;
   const base = canonical.pathname.replace(/\/+$/, '');

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

@@ -1,34 +1,107 @@
-export const registryEmailIsConfigured = (): boolean => Boolean(process.env.RESEND_API_KEY?.trim() && process.env.AUTH_FROM_EMAIL?.trim());
+import { isEnvReference, resolveEnvReferences } from '@handoff/config/from-env';
+import { createSmtpProvider } from '@handoff/registry/email/providers/smtp';
+import type { EmailProviderKind, EmailSettings } from '@handoff/registry/email/resolve';
+import type { EmailProvider } from '@handoff/registry/email/types';
+import { getServerRuntimeConfig } from '../docs-api/runtime-config';
+import { loadServerModule } from '../server-module';
+
+/** Options a provider needs before email counts as configured. */
+const REQUIRED_OPTIONS: Record<EmailProviderKind, readonly string[]> = { smtp: ['host'], custom: [] };
+
+/**
+ * The settings that still need a value, named as the administrator sets them: the config key, or the
+ * env var that an option references.
+ */
+export const missingRegistryEmailSettings = (): string[] => {
+  const settings = getServerRuntimeConfig().email;
+  const options = resolveEnvReferences(settings.options, process.env);
+  const missing = settings.from ? [] : ['runtime.registry.email.from'];
+  if (!settings.provider) return [...missing, 'runtime.registry.email.provider'];
+  if (settings.provider === 'custom' && !settings.module) missing.push('runtime.registry.email.module');
+  for (const key of REQUIRED_OPTIONS[settings.provider]) {
+    if (options[key] !== undefined) continue;
+    const authored = settings.options[key];
+    missing.push(isEnvReference(authored) ? authored.$env : `runtime.registry.email.options.${key}`);
+  }
+  return missing;
+};
+
+export const registryEmailIsConfigured = (): boolean => missingRegistryEmailSettings().length === 0;
+
+/** The provider name for messages shown to an administrator. */
+export const registryEmailProviderName = (): string => {
+  const { provider } = getServerRuntimeConfig().email;
+  return provider === 'smtp' ? 'SMTP' : 'the custom email provider';
+};
+
+let customProvider: Promise<EmailProvider> | null = null;
+
+/** Load the custom module once and coerce its default export (provider object or factory) to a provider. */
+const loadCustomProvider = async (settings: EmailSettings, options: Record<string, unknown>): Promise<EmailProvider> => {
+  const provider = await loadServerModule(settings.module!, { options });
+  if (typeof (provider as Partial<EmailProvider> | null)?.send !== 'function') {
+    throw new Error(`Custom email provider module "${settings.module}" must default-export a defineEmailProvider() provider.`);
+  }
+  return provider as EmailProvider;
+};
+
+const getEmailProvider = (settings: EmailSettings, options: Record<string, unknown>): Promise<EmailProvider> => {
+  if (settings.provider === 'smtp') return Promise.resolve(createSmtpProvider(options));
+  customProvider ??= loadCustomProvider(settings, options).catch((error) => {
+    customProvider = null;
+    throw error;
+  });
+  return customProvider;
+};
 
 const escapeHtml = (value: string): string =>
   value.replace(/[&<>"']/g, (character) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character]!);
 
-export const sendRegistryAuthEmail = async (input: {
+const FOOTNOTE = 'If you did not expect this email, you can ignore it.';
+
+interface AuthEmail {
   to: string;
   subject: string;
   heading: string;
   message: string;
   actionLabel: string;
   actionUrl: string;
-}): Promise<boolean> => {
-  const apiKey = process.env.RESEND_API_KEY?.trim();
-  const from = process.env.AUTH_FROM_EMAIL?.trim();
-  if (!apiKey || !from) return false;
-
-  const response = await fetch('https://api.resend.com/emails', {
-    method: 'POST',
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({
-      from,
-      to: [input.to],
-      subject: input.subject,
-      html:
-        `<h1>${escapeHtml(input.heading)}</h1><p>${escapeHtml(input.message)}</p>` +
-        `<p><a href="${escapeHtml(input.actionUrl)}">${escapeHtml(input.actionLabel)}</a></p>`,
-    }),
-  });
-  return response.ok;
+}
+
+const renderHtml = ({ heading, message, actionLabel, actionUrl }: AuthEmail): string => {
+  const url = escapeHtml(actionUrl);
+  return `<!DOCTYPE html>
+<html lang="en">
+<body style="margin:0;padding:32px 16px;background:#f4f4f5;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#18181b;">
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0"><tr><td align="center">
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="max-width:480px;background:#ffffff;border-radius:8px;">
+<tr><td style="padding:32px;">
+<h1 style="margin:0 0 16px;font-size:20px;">${escapeHtml(heading)}</h1>
+<p style="margin:0 0 24px;font-size:15px;line-height:1.5;">${escapeHtml(message)}</p>
+<a href="${url}" style="display:inline-block;padding:12px 20px;border-radius:6px;background:#18181b;color:#ffffff;font-size:15px;text-decoration:none;">${escapeHtml(actionLabel)}</a>
+<p style="margin:24px 0 0;font-size:13px;line-height:1.5;color:#71717a;">If the button does not work, open this link:<br><a href="${url}" style="color:#71717a;word-break:break-all;">${url}</a></p>
+<p style="margin:16px 0 0;font-size:13px;color:#71717a;">${FOOTNOTE}</p>
+</td></tr></table>
+</td></tr></table>
+</body>
+</html>`;
+};
+
+const renderText = ({ heading, message, actionLabel, actionUrl }: AuthEmail): string =>
+  `${heading}\n\n${message}\n\n${actionLabel}: ${actionUrl}\n\n${FOOTNOTE}\n`;
+
+/** Send through the configured provider. Returns false, and logs the failure, when email is not configured or delivery fails. */
+export const sendRegistryAuthEmail = async (email: AuthEmail): Promise<boolean> => {
+  if (!registryEmailIsConfigured()) return false;
+  const settings = getServerRuntimeConfig().email;
+  const options = resolveEnvReferences(settings.options, process.env);
+
+  try {
+    const provider = await getEmailProvider(settings, options);
+    await provider.send({ from: settings.from!, to: email.to, subject: email.subject, html: renderHtml(email), text: renderText(email) });
+    return true;
+  } catch (error) {
+    console.error(`Email delivery through ${registryEmailProviderName()} failed.`, error);
+    return false;
+  }
 };

package/src/app/lib/docs-api/page-rendering.ts

@@ -31,7 +31,7 @@ export const documentationMetadata = (source: Record<string, unknown>) => {
   return {
     title,
     description,
-    metaTitle: value('metaTitle') || title,
+    metaTitle: value('metaTitle'),
     metaDescription: value('metaDescription') || description,
   };
 };

package/src/app/lib/docs-api/registry.ts

@@ -21,7 +21,7 @@ import {
 import { defaultPageDetail, type BakedDefaultPage } from './page-rendering';
 import { MAX_SEARCH_BODY_LENGTH, MAX_SEARCH_CANDIDATES, truncateSearchBody, type SearchResponse } from './search';
 import { getRegistryConnection } from '../registry-connection';
-import { getAssetStorageAdapter } from '../asset-storage';
+import { getStorageProvider } from '../asset-storage';
 // A static import includes package defaults in each registry serverless bundle. A deployed function
 // cannot read the build machine's `config/docs` directory.
 import defaultPages from '../../generated/default-pages.json';
@@ -148,8 +148,7 @@ const searchRegistryPages = async (db: RegistryDatabase, request: PageSearchRequ
 export const createRegistryDocsBackend = async (): Promise<DocsBackend> => {
   const connection = await getRegistryConnection();
   const { db } = connection;
-  // Inject the storage-adapter resolver so object-backed asset content resolves by provider id.
-  const store = createRegistryStore({ db, resolveAssetAdapter: getAssetStorageAdapter });
+  const store = createRegistryStore({ db, resolveStorageProvider: getStorageProvider });
 
   return {
     async listComponents() {

package/src/app/lib/docs-api/runtime-config.ts

@@ -1,12 +1,10 @@
 import fs from 'fs-extra';
 import path from 'path';
 import type { RuntimeMode } from '@handoff/types/config';
-import {
-  DEFAULT_DATABASE_URL_ENV,
-  DEFAULT_REGISTRY_DRIVER,
-  type RegistryDatabaseDriver,
-} from '@handoff/registry/db/driver';
-import { DEFAULT_ASSET_STORAGE_ADAPTER, type AssetStorageSettings } from '@handoff/registry/asset-storage/resolve';
+import { DEFAULT_DATABASE_URL_ENV, DEFAULT_REGISTRY_DRIVER, type RegistryDatabaseDriver } from '@handoff/registry/db/driver';
+import { DEFAULT_ASSET_STORAGE_PROVIDER, type AssetStorageSettings } from '@handoff/registry/asset-storage/resolve';
+import { mergeAiConnections, parseAiConnections, type AiSettings } from '@handoff/ai/connections';
+import { parseEmailSettings, type EmailSettings } from '@handoff/registry/email/resolve';
 
 /**
  * Server-side runtime resolution for the docs read API.
@@ -35,12 +33,20 @@ export interface ServerRuntimeConfig {
   mode: RuntimeMode;
   /** Whether this build serves `/api/mcp/`. Config-only, baked at build time. */
   mcp: boolean;
+  /**
+   * The AI assistant: whether this build serves it, and the connections it can reach. `enabled` is
+   * baked; the connection list is resolved per request so a deployment can change it without a
+   * rebuild.
+   */
+  ai: AiSettings;
   registry: ServerRegistryRuntimeConfig;
   /**
-   * Asset storage selection for registry mode (provider + non-secret options + env-var names). Secret
-   * values are resolved from `process.env` at request time, never persisted here.
+   * Asset storage provider, module, and options for registry mode. Options hold `{ $env }` references,
+   * never secret values.
    */
   assetStorage: AssetStorageSettings;
+  /** Registry email provider, sender, and options. Options hold `{ $env }` references, never secret values. */
+  email: EmailSettings;
 }
 
 let cached: ServerRuntimeConfig | null = null;
@@ -49,16 +55,18 @@ let cached: ServerRuntimeConfig | null = null;
 const defaults = (): ServerRuntimeConfig => ({
   mode: 'workspace',
   mcp: true,
+  ai: { enabled: false, connections: [] },
   registry: {
     driver: DEFAULT_REGISTRY_DRIVER,
     databaseUrlEnv: DEFAULT_DATABASE_URL_ENV,
   },
-  assetStorage: { adapter: DEFAULT_ASSET_STORAGE_ADAPTER },
+  assetStorage: { provider: DEFAULT_ASSET_STORAGE_PROVIDER },
+  email: { options: {} },
 });
 
 /** Parse the baked asset-storage selection from env (names/selectors only; JSON options tolerated). */
 const assetStorageFromEnv = (): AssetStorageSettings => {
-  const adapter = process.env.HANDOFF_ASSET_STORAGE_ADAPTER?.trim();
+  const provider = process.env.HANDOFF_ASSET_STORAGE_PROVIDER?.trim();
   let options: Record<string, unknown> | undefined;
   const rawOptions = process.env.HANDOFF_ASSET_STORAGE_OPTIONS?.trim();
   if (rawOptions) {
@@ -71,22 +79,33 @@ const assetStorageFromEnv = (): AssetStorageSettings => {
   }
   const maxInline = Number(process.env.HANDOFF_ASSET_STORAGE_MAX_INLINE_BYTES);
   return {
-    adapter: adapter === 'vercel-blob' || adapter === 'custom' ? adapter : DEFAULT_ASSET_STORAGE_ADAPTER,
+    provider: provider === 'custom' ? provider : DEFAULT_ASSET_STORAGE_PROVIDER,
     module: process.env.HANDOFF_ASSET_STORAGE_MODULE?.trim() || undefined,
-    tokenEnv: process.env.HANDOFF_ASSET_STORAGE_TOKEN_ENV?.trim() || undefined,
     maxInlineBytes: Number.isFinite(maxInline) && maxInline > 0 ? maxInline : undefined,
     options,
   };
 };
 
+/**
+ * Resolve the AI settings from the baked flag and connection list, then merge the
+ * deployment-supplied `HANDOFF_AI_CONNECTIONS` over it by id.
+ *
+ * `HANDOFF_AI_CONNECTIONS` is read dynamically rather than as a literal `process.env` reference: the
+ * baked values in `next.config.mjs` are inlined at build time, so a name in that block can never
+ * carry a deploy-time value. That is why the baked list uses its own `HANDOFF_AI_BAKED_CONNECTIONS`.
+ */
+const aiFromEnv = (): AiSettings => ({
+  enabled: process.env.HANDOFF_AI_ENABLED?.trim() === 'true',
+  connections: mergeAiConnections(
+    parseAiConnections(process.env.HANDOFF_AI_BAKED_CONNECTIONS),
+    parseAiConnections(process.env['HANDOFF_AI_CONNECTIONS'])
+  ),
+  defaultModel: process.env.HANDOFF_AI_DEFAULT_MODEL?.trim() || undefined,
+});
+
 /** Absolute path of the server-only runtime config persisted next to `client.config.json`. */
 const serverRuntimeConfigPath = (): string =>
-  path.resolve(
-    process.env.HANDOFF_MODULE_PATH ?? '',
-    '.handoff',
-    process.env.HANDOFF_PROJECT_ID ?? '',
-    'runtime.server.json'
-  );
+  path.resolve(process.env.HANDOFF_MODULE_PATH ?? '', '.handoff', process.env.HANDOFF_PROJECT_ID ?? '', 'runtime.server.json');
 
 /**
  * Resolve the server-side runtime config from the values baked into the bundle at build time
@@ -107,11 +126,18 @@ const fromEnv = (): ServerRuntimeConfig | null => {
   return {
     mode: mode === 'registry' ? 'registry' : 'workspace',
     mcp: process.env.HANDOFF_MCP_ENABLED?.trim() !== 'false',
+    ai: aiFromEnv(),
     registry: {
       driver: process.env.HANDOFF_REGISTRY_DRIVER?.trim() === 'neon' ? 'neon' : 'pg',
       databaseUrlEnv,
     },
     assetStorage: assetStorageFromEnv(),
+    email: parseEmailSettings({
+      from: process.env.HANDOFF_EMAIL_FROM,
+      provider: process.env.HANDOFF_EMAIL_PROVIDER?.trim(),
+      module: process.env.HANDOFF_EMAIL_MODULE,
+      options: process.env.HANDOFF_EMAIL_OPTIONS,
+    }),
   };
 };
 
@@ -141,17 +167,17 @@ export const getServerRuntimeConfig = (): ServerRuntimeConfig => {
           ? parsed.registry.databaseUrlEnv.trim()
           : DEFAULT_DATABASE_URL_ENV;
       const assetStorage: AssetStorageSettings =
-        parsed?.assetStorage && typeof parsed.assetStorage === 'object'
-          ? parsed.assetStorage
-          : { adapter: DEFAULT_ASSET_STORAGE_ADAPTER };
+        parsed?.assetStorage && typeof parsed.assetStorage === 'object' ? parsed.assetStorage : { provider: DEFAULT_ASSET_STORAGE_PROVIDER };
       cached = {
         mode: parsed?.mode === 'registry' ? 'registry' : 'workspace',
         mcp: parsed?.mcp !== false,
+        ai: aiFromEnv(),
         registry: {
           driver: parsed?.registry?.driver === 'neon' ? 'neon' : 'pg',
           databaseUrlEnv,
         },
         assetStorage,
+        email: parseEmailSettings(parsed?.email ?? {}),
       };
       return cached;
     }