@kitn.ai/ui 0.20.1 → 0.22.0

package/src/agent-tooling/integrations/openrouter.ts

@@ -7,20 +7,70 @@ const openrouter: Integration = {
   language: 'ts',
   streamFormat: 'openai-sse',
   envVars: ['OPENROUTER_API_KEY'],
-  routeTemplates: {
-    next: `export async function POST(req: Request) {
-  const { model, messages } = await req.json();
+  // No per-framework templates: the handler below is web-standard, so the
+  // scaffolder wraps it in whatever the target framework routes with. This used
+  // to be a `next`-only entry that every other framework inherited verbatim.
+  routeTemplates: {},
+  webRoute: `async function chatHandler(request: Request): Promise<Response> {
+  // tools is undefined unless the front end sent one; JSON.stringify drops it,
+  // so the same handler serves a tool archetype and a plain chat.
+  const { model, messages, tools } = await readChatRequest(request);
+
   const upstream = await fetch('https://openrouter.ai/api/v1/chat/completions', {
     method: 'POST',
-    headers: { Authorization: \`Bearer \${process.env.OPENROUTER_API_KEY}\`, 'Content-Type': 'application/json' },
-    body: JSON.stringify({ model, messages, stream: true }),
+    headers: {
+      Authorization: \`Bearer \${process.env.OPENROUTER_API_KEY}\`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ model, messages, tools, stream: true }),
+  });
+
+  // FORWARD THE STATUS. Returning 200 here is how a missing key turns into
+  // silence: the 401 body is JSON, it goes out labelled text/event-stream, the
+  // SSE reader finds no frame, and the turn resolves empty with nothing logged
+  // and no bubble. With the status intact readOpenAIStream throws a WireError
+  // carrying the provider's own message.
+  if (!upstream.ok) {
+    return new Response(await upstream.text(), {
+      status: upstream.status,
+      headers: {
+        'Content-Type': upstream.headers.get('content-type') ?? 'application/json',
+      },
+    });
+  }
+  if (!upstream.body) {
+    return new Response(JSON.stringify({ error: { message: 'The provider returned no body to stream.' } }), {
+      status: 502,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  return new Response(upstream.body, {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      // no-transform stops a proxy buffering the stream into one blob.
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+    },
   });
-  return new Response(upstream.body, { headers: { 'Content-Type': 'text/event-stream' } });
 }`,
-  },
-  streamMapping: 'OpenRouter returns OpenAI-format SSE — pipe upstream.body straight to the browser; the Streaming-recipe reader handles it.',
+  streamMapping:
+    'OpenRouter returns OpenAI-format SSE. Pipe upstream.body straight to the browser; readOpenAIStream from @kitn.ai/ui/wire parses it, including tool calls and reasoning.',
   runNote: 'Set OPENROUTER_API_KEY. Model ids are vendor/model, e.g. openai/gpt-4o.',
   docsSlug: 'integrations/connect-any-model',
+  // The route forwards both, so a scaffold's editable consts reach the gateway.
+  forwardsFromClient: ['model', 'tools'],
+  // The handler puts the client's `tools` straight into an OpenAI-compatible
+  // /chat/completions body, unconverted — so the client must send OpenAI's own
+  // `{ type: 'function', function: { parameters } }` envelope.
+  clientToolFormat: 'openai',
+  // Nothing to install. The route is global `fetch` and imports no module.
+  deps: { npm: [], pip: [] },
+  // The route reads OPENROUTER_API_KEY into an `Authorization: Bearer` header.
+  keyExposure: 'needs-proxy',
+  // A remote HTTPS endpoint and a key. Nothing to install, nothing to start.
+  outOfBand: 'none',
 };
 
 export default openrouter;

package/src/agent-tooling/integrations/pi.ts

@@ -8,33 +8,114 @@ const pi: Integration = {
   streamFormat: 'native',
   envVars: [],
   routeTemplates: {
-    express: `import { spawn } from 'node:child_process';
-
-// POST /api/chat — bridge a Pi RPC session to the browser as SSE
-const pi = spawn('pi', ['--mode', 'rpc', '--no-session']);
-
-// Send the user's turn. Pi commands are { type, message }.
-pi.stdin.write(JSON.stringify({ type: 'prompt', message: prompt }) + '\\n');
-
-let buffer = '';
-pi.stdout.on('data', (chunk) => {
-  buffer += chunk.toString();
-  const lines = buffer.split('\\n');
-  buffer = lines.pop(); // hold the partial line for the next chunk
-  for (const line of lines) {
-    if (!line) continue;
-    const event = JSON.parse(line);
-    const part = event.assistantMessageEvent;
-    if (event.type === 'message_update' && part?.type === 'text_delta') {
-      res.write(\`data: \${JSON.stringify({ choices: [{ delta: { content: part.delta } }] })}\\n\\n\`);
-    }
+    // Express only, and genuinely so: the bridge spawns a local process, which a
+    // Worker or an edge runtime cannot do. Every other framework gets this under
+    // the scaffolder's "cannot host" warning, the same way pydantic-ai emits a
+    // whole FastAPI service.
+    express: `// server.ts
+import express from 'express';
+import { spawn } from 'node:child_process';
+import type { OpenAIWireMessage } from '@kitn.ai/ui/wire';
+
+const app = express();
+app.use(express.json());
+
+// POST /api/chat: bridge a Pi RPC session to the browser as SSE.
+app.post('/api/chat', (req, res) => {
+  const { messages } = req.body as { messages: OpenAIWireMessage[] };
+  const last = messages.at(-1)?.content;
+  // \`content\` is a plain string until the turn carries an attachment, at which
+  // point it is an ARRAY of content parts. Pi's RPC mode takes a TEXT prompt and
+  // has no channel for a file, so an attachment is REFUSED here. Passing the
+  // array straight through would JSON.stringify an object graph into the prompt
+  // — no type error, no crash, just a model reading serialised noise.
+  if (Array.isArray(last) && last.some((part) => part.type !== 'text')) {
+    res.status(400).json({
+      error: {
+        message:
+          'This Pi bridge forwards a text prompt only and has no channel for an attachment. Extract the file content into the message text, or send it through a tool.',
+      },
+    });
+    return;
   }
+  const prompt =
+    typeof last === 'string'
+      ? last
+      : (last ?? []).map((part) => (part.type === 'text' ? part.text : '')).join('');
+
+  // Headers before the first frame: without text/event-stream the browser
+  // buffers the body and readOpenAIStream never sees a frame.
+  res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
+  // no-transform stops a proxy buffering the stream into one blob.
+  res.setHeader('Cache-Control', 'no-cache, no-transform');
+  res.setHeader('Connection', 'keep-alive');
+
+  // ONE PROCESS PER REQUEST. Pi in RPC mode holds conversation state, so a
+  // module-level process would leak one caller's turns into the next caller's
+  // reply and serialise every request behind a single stdin.
+  const pi = spawn('pi', ['--mode', 'rpc', '--no-session']);
+
+  // A spawn failure (pi not on PATH) arrives asynchronously, by which point the
+  // SSE headers are out and the status is spent, so report IN BAND:
+  // readOpenAIStream lands this on turn.error instead of leaving a blank bubble.
+  pi.on('error', (err) => {
+    res.write(\`data: \${JSON.stringify({ error: { message: err.message } })}\\n\\n\`);
+    res.write('data: [DONE]\\n\\n');
+    res.end();
+  });
+
+  // Send the user's turn. Pi commands are { type, message }.
+  pi.stdin.write(JSON.stringify({ type: 'prompt', message: prompt }) + '\\n');
+
+  let buffer = '';
+  pi.stdout.on('data', (chunk: Buffer) => {
+    buffer += chunk.toString();
+    // Split on \\n rather than readline: readline also breaks on the Unicode
+    // separators U+2028/U+2029, which appear inside model output.
+    const lines = buffer.split('\\n');
+    // pop() is \`string | undefined\`, and the buffer has to stay a string.
+    buffer = lines.pop() ?? ''; // hold the partial line for the next chunk
+    for (const line of lines) {
+      if (!line) continue;
+      const event = JSON.parse(line);
+      const part = event.assistantMessageEvent;
+      if (event.type === 'message_update' && part?.type === 'text_delta') {
+        res.write(\`data: \${JSON.stringify({ choices: [{ delta: { content: part.delta } }] })}\\n\\n\`);
+      }
+    }
+  });
+  pi.on('close', () => { res.write('data: [DONE]\\n\\n'); res.end(); });
 });
-pi.on('close', () => { res.write('data: [DONE]\\n\\n'); res.end(); });`,
+
+app.listen(3001, () => console.log('chat api: http://localhost:3001/api/chat'));
+// The front end fetches a RELATIVE /api/chat, so proxy that path to this port
+// from your dev server, or serve both from one origin.`,
   },
-  streamMapping: "Pi runs as a local stdio process in RPC mode (pi --mode rpc --no-session). It emits newline-delimited JSON events on stdout. Map message_update events where assistantMessageEvent.type === 'text_delta' to data: {choices:[{delta:{content:part.delta}}]} SSE frames; send data: [DONE] on close. Split stdout on \\n (not readline, which breaks on Unicode separators U+2028/U+2029). Pi also emits thinking_delta (map to reasoning) and toolcall_* events (map to tool calls).",
-  runNote: "Pi must be installed locally and available on PATH as 'pi'. No API key is required by the bridge itself; Pi uses its own credentials. Pi runs with full user permissions — sandbox before exposing to a public endpoint. See the RPC reference: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/rpc.md",
+  streamMapping: "Pi runs as a local stdio process in RPC mode (pi --mode rpc --no-session). It emits newline-delimited JSON events on stdout. Map message_update events where assistantMessageEvent.type === 'text_delta' to data: {choices:[{delta:{content:part.delta}}]} SSE frames; send data: [DONE] on close. Split stdout on \\n (not readline, which breaks on Unicode separators U+2028/U+2029). Pi also emits thinking_delta and toolcall_* events; re-frame them onto delta.reasoning and delta.tool_calls in the same frames. readOpenAIStream from @kitn.ai/ui/wire parses it, including tool calls and reasoning.",
+  runNote: "Pi must be installed locally and available on PATH as 'pi'. No API key is required by the bridge itself; Pi uses its own credentials. Pi runs with full user permissions, so sandbox it before exposing to a public endpoint. See the RPC reference: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/rpc.md",
   docsSlug: 'integrations/harnesses',
+  // Nothing. Pi runs with its own credentials, model and tools; the bridge
+  // forwards a prompt, not a model id.
+  forwardsFromClient: [],
+  // `express` only. The bridge's other two imports are excluded by the rule:
+  // `node:child_process` is a builtin and '@kitn.ai/ui/wire' is the kit. Pi
+  // itself is NOT an npm dep of the app — runNote requires it on PATH, and the
+  // route reaches it with spawn('pi'), not an import.
+  deps: { npm: ['express'], pip: [] },
+  // No key anywhere: envVars is empty and Pi uses its own credentials on disk.
+  // This is 'needs-proxy' for the OTHER reason the flag covers — a server-only
+  // capability. The bridge calls spawn(), which no browser can do, and runNote
+  // warns that Pi runs with full user permissions and wants sandboxing before it
+  // is exposed. "No key" is not the same fact as "safe in the browser", and
+  // collapsing the two is exactly how this flag would be got wrong.
+  keyExposure: 'needs-proxy',
+  // Not 'local-server': nothing is listening in advance. The bridge spawns
+  // `pi --mode rpc` per request, so what the developer supplies is an EXECUTABLE
+  // on PATH ("Pi must be installed locally and available on PATH as 'pi'"), and
+  // "start the server first" would be the wrong instruction to print. Pi is not
+  // in `deps` for the same reason — the route reaches it with spawn(), not an
+  // import. The schema's SPAWNS_PROCESS net catches this one independently.
+  outOfBand: 'local-binary',
 };
 
 export default pi;

package/src/agent-tooling/integrations/pydantic-ai.ts

@@ -10,7 +10,7 @@ const pydanticAi: Integration = {
   routeTemplates: {
     fastapi: `# main.py
 import json
-from fastapi import FastAPI
+from fastapi import FastAPI, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel
@@ -23,15 +23,41 @@ app.add_middleware(
     CORSMiddleware, allow_origins=['*'], allow_methods=['*'], allow_headers=['*']
 )
 
+class ContentPart(BaseModel):
+    type: str
+    text: str | None = None
+
 class Message(BaseModel):
     role: str
-    content: str
+    # A plain string until the turn carries an attachment, at which point the
+    # wire sends an ARRAY of content parts. Declaring this \`str\` alone made a
+    # message with a file a 422 that named pydantic rather than the cause.
+    content: str | list[ContentPart] | None = None
 
 class ChatRequest(BaseModel):
     messages: list[Message]
 
+def prompt_text(message: Message) -> str:
+    """The text of a turn, refusing what this route cannot carry.
+
+    agent.run_stream() takes a TEXT prompt, so an image or a document has no
+    channel here. Dropping it would send the model a turn that silently lost the
+    user's file; a 400 that names the reason is the honest failure.
+    """
+    if message.content is None:
+        return ''
+    if isinstance(message.content, str):
+        return message.content
+    if any(part.type != 'text' for part in message.content):
+        raise HTTPException(
+            status_code=400,
+            detail='This route forwards a text prompt only and has no channel for an attachment. '
+            'Extract the file content into the message text, or send it through a tool.',
+        )
+    return ''.join(part.text or '' for part in message.content)
+
 async def openai_sse(messages: list[Message]):
-    prompt = messages[-1].content if messages else ''
+    prompt = prompt_text(messages[-1]) if messages else ''
     async with agent.run_stream(prompt) as result:
         async for delta in result.stream_text(delta=True):
             chunk = {'choices': [{'delta': {'content': delta}}]}
@@ -43,10 +69,40 @@ async def chat(req: ChatRequest):
     return StreamingResponse(openai_sse(req.messages), media_type='text/event-stream')`,
   },
   streamMapping:
-    "Pydantic AI's agent.run_stream() yields text deltas via result.stream_text(delta=True). Each delta is re-framed as a data: {choices:[{delta:{content}}]} SSE line and the stream closes with data: [DONE]. The kai-chat reader is unchanged — it sees standard OpenAI-format SSE.",
+    "Pydantic AI's agent.run_stream() yields text deltas via result.stream_text(delta=True). Each delta is re-framed as a data: {choices:[{delta:{content}}]} SSE line and the stream closes with data: [DONE]. readOpenAIStream from @kitn.ai/ui/wire parses tool calls and reasoning too, but stream_text() yields text only: iterate the run's events instead and re-frame its tool-call events onto delta.tool_calls to fill kai-tool.",
+  // No install list here: `deps` below is the one, and the scaffolder emits it.
+  // This sentence used to open "Install: pip install pydantic-ai fastapi
+  // uvicorn." — three of the four packages, missing the `pydantic` its own route
+  // imports on the next line.
   runNote:
-    'Install: pip install pydantic-ai fastapi uvicorn. Set OPENAI_API_KEY. Run: uvicorn main:app --reload (default port 8000). Point kai-chat at http://localhost:8000/api/chat.',
+    'Set OPENAI_API_KEY. Run: uvicorn main:app --reload (default port 8000). Point kai-chat at http://localhost:8000/api/chat.',
   docsSlug: 'integrations/pydantic-ai',
+  // Nothing. Agent('openai:gpt-4o') pins the model and the agent registers its
+  // own tools, both server-side.
+  forwardsFromClient: [],
+  // The only python integration, so the only non-empty `pip`. Three of the four
+  // are the route's own imports (`pydantic_ai` is imported under its module
+  // name and installed under its hyphenated one); `uvicorn` is the ASGI server
+  // the run note starts, which nothing imports and without which the app cannot
+  // run. That asymmetry is why the pip guard checks imports ⊆ declared and not
+  // the reverse.
+  deps: { npm: [], pip: ['pydantic-ai', 'fastapi', 'pydantic', 'uvicorn'] },
+  // Agent('openai:gpt-4o') reads OPENAI_API_KEY inside the python process.
+  //
+  // Worth being precise about, because this one looks like an exception: the
+  // FastAPI app sets CORS to allow_origins=['*'] and the browser fetches it
+  // DIRECTLY on :8000, with no JS proxy in front. That still is not
+  // 'frontend-safe' — the flag asks where the SECRET lives, and it lives in the
+  // python process. The FastAPI service IS the server hop.
+  keyExposure: 'needs-proxy',
+  // The emitted backend is a FastAPI service: a python interpreter, the four
+  // `deps.pip` packages, and `uvicorn main:app` on its own port — none of which a
+  // node toolchain provides or starts. It also needs OPENAI_API_KEY, so this is
+  // the entry that proves the groups are not mutually exclusive: a runtime
+  // prerequisite and a key at once. The prompt should lead with the runtime,
+  // because a key is useless until the service runs. The schema's `language ===
+  // 'python'` net catches this one independently.
+  outOfBand: 'language-runtime',
 };
 
 export default pydanticAi;

package/src/agent-tooling/integrations/vercel-ai-sdk.ts

@@ -7,38 +7,145 @@ const vercelAiSdk: Integration = {
   language: 'ts',
   streamFormat: 'ai-sdk',
   envVars: ['AI_GATEWAY_API_KEY'],
-  routeTemplates: {
-    next: `// app/api/chat/route.ts
-import { streamText } from 'ai';
+  // No per-framework templates: the handler below is web-standard, so the
+  // scaffolder wraps it in the target framework's own route declaration.
+  routeTemplates: {},
+  webRoute: `import { streamText } from 'ai';
+import type { ModelMessage, AssistantContent, UserContent, FilePart, ToolResultPart } from 'ai';
 
-export const maxDuration = 30; // allow long streaming responses
+// Next.js only: add \`export const maxDuration = 30\` to the route file to allow
+// long streaming responses. It is a Next route-segment config, not part of the
+// handler, so it lives in the file rather than in here.
 
-export async function POST(req: Request) {
-  const { messages } = await req.json();
+/**
+ * One attachment to an AI SDK FilePart.
+ *
+ * \`data\` takes the BARE shorthand — a base64 string, or a URL object for a
+ * remote file — rather than the newer tagged \`{ type: 'data' | 'url' }\` form.
+ * Both are accepted by the installed SDK; the shorthand is also what AI SDK v5
+ * and v6 accept, so this route keeps compiling if the app pins an older \`ai\`.
+ *
+ * Images arrive as \`image_url\` and become FileParts too. \`ImagePart\` still
+ * exists but is deprecated in favour of exactly this.
+ */
+function toFilePart(part: Extract<WirePart, { kind: 'file' }>): FilePart {
+  return {
+    type: 'file',
+    mediaType: part.mediaType,
+    ...(part.filename === undefined ? {} : { filename: part.filename }),
+    data: part.source.type === 'data' ? part.source.data : new URL(part.source.url),
+  };
+}
+
+// The kit's wire format is OpenAI-shaped (tool_calls on the assistant message,
+// a flat content string on the tool message). The AI SDK's ModelMessage is not:
+// a tool call is a CONTENT PART on the assistant message, and a tool result is a
+// tagged output union, not a bare string. Converting rather than casting is the
+// point — a cast would compile but hand the SDK the wrong shape at runtime.
+function toModelMessages(messages: ChatRequestBody['messages']): ModelMessage[] {
+  return messages.map((message): ModelMessage => {
+    switch (message.role) {
+      // A system prompt is text-only on every wire, so the array form collapses.
+      case 'system':
+        return { role: 'system', content: wireText(message.content) };
+      case 'user': {
+        const parts = wireParts(message.content);
+        // Plain string for an ordinary turn: identical to what this route sent
+        // before attachments existed, and the shape the SDK docs lead with.
+        if (parts.every((p) => p.kind === 'text')) {
+          return { role: 'user', content: wireText(message.content) };
+        }
+        const content: UserContent = parts.map((p) =>
+          p.kind === 'text' ? { type: 'text' as const, text: p.text } : toFilePart(p),
+        );
+        return { role: 'user', content };
+      }
+      case 'tool': {
+        const result: ToolResultPart = {
+          type: 'tool-result',
+          toolCallId: message.tool_call_id ?? '',
+          toolName: message.name ?? '',
+          output: { type: 'text', value: wireText(message.content) },
+        };
+        return { role: 'tool', content: [result] };
+      }
+      case 'assistant': {
+        const text = wireText(message.content);
+        if (!message.tool_calls?.length) return { role: 'assistant', content: text };
+        const content: AssistantContent = [];
+        if (text) content.push({ type: 'text', text });
+        for (const call of message.tool_calls) {
+          content.push({
+            type: 'tool-call',
+            toolCallId: call.id,
+            toolName: call.function.name,
+            input: JSON.parse(call.function.arguments),
+          });
+        }
+        return { role: 'assistant', content };
+      }
+    }
+  });
+}
+
+async function chatHandler(request: Request): Promise<Response> {
+  const { messages } = await readChatRequest(request);
 
   const result = streamText({
     model: 'openai/gpt-4o', // AI Gateway id; needs AI_GATEWAY_API_KEY
-    messages,
+    messages: toModelMessages(messages),
   });
 
   const encoder = new TextEncoder();
   const sse = new ReadableStream({
     async start(controller) {
-      for await (const delta of result.textStream) {
-        const chunk = { choices: [{ delta: { content: delta } }] };
-        controller.enqueue(encoder.encode(\`data: \${JSON.stringify(chunk)}\\n\\n\`));
+      try {
+        for await (const delta of result.textStream) {
+          const chunk = { choices: [{ delta: { content: delta } }] };
+          controller.enqueue(encoder.encode(\`data: \${JSON.stringify(chunk)}\\n\\n\`));
+        }
+      } catch (err) {
+        // The status is spent by the time the SDK fails — the headers went out
+        // with the first byte — so report it IN BAND. readOpenAIStream lands
+        // this on turn.error and keeps whatever streamed before it. Without it a
+        // failed key is an empty bubble and nothing in the console.
+        const message = err instanceof Error ? err.message : 'Model stream failed';
+        controller.enqueue(encoder.encode(\`data: \${JSON.stringify({ error: { message } })}\\n\\n\`));
       }
       controller.enqueue(encoder.encode('data: [DONE]\\n\\n'));
       controller.close();
     },
   });
 
-  return new Response(sse, { headers: { 'Content-Type': 'text/event-stream' } });
+  return new Response(sse, {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      // no-transform stops a proxy buffering the stream into one blob.
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+    },
+  });
 }`,
-  },
-  streamMapping: "The Vercel AI SDK's toUIMessageStreamResponse() and toTextStreamResponse() don't emit OpenAI-format SSE. Wrap result.textStream manually: iterate text deltas and emit data: {choices:[{delta:{content}}]} frames, closing with data: [DONE]. The kai-chat SSE reader handles it.",
+  streamMapping: "The Vercel AI SDK's toUIMessageStreamResponse() and toTextStreamResponse() don't emit OpenAI-format SSE. Wrap result.textStream manually: iterate text deltas and emit data: {choices:[{delta:{content}}]} frames, closing with data: [DONE]. readOpenAIStream from @kitn.ai/ui/wire parses tool calls and reasoning too, but textStream carries neither: it is text deltas only. Switch to result.fullStream, which yields typed parts, and re-frame its tool-call and reasoning parts onto delta.tool_calls and delta.reasoning to get them.",
   runNote: 'Set AI_GATEWAY_API_KEY for the AI Gateway (string model id form: creator/model-name). For direct provider access, import its provider package (e.g. @ai-sdk/openai) and set the corresponding key (e.g. OPENAI_API_KEY).',
   docsSlug: 'integrations/vercel-ai-sdk',
+  // Nothing. The route pins model: 'openai/gpt-4o' in the streamText() call and
+  // defines any tools there too, so neither belongs in the front end.
+  forwardsFromClient: [],
+  // `ai` only. A direct provider (e.g. @ai-sdk/openai) is the alternative path
+  // described in runNote, not what this route imports, so it is not listed: the
+  // rule is what the emitted code actually imports.
+  deps: { npm: ['ai'], pip: [] },
+  // Grep the route for a key and you find NOTHING — no header, no process.env.
+  // The AI SDK reads AI_GATEWAY_API_KEY out of the environment itself, inside
+  // streamText(). This is the case that makes inference from route source
+  // unsafe and the declaration necessary; `envVars` is what the schema's safety
+  // net can still see.
+  keyExposure: 'needs-proxy',
+  // The AI Gateway is a remote HTTPS endpoint reached through the `ai` package,
+  // which is an ordinary npm dependency (see `deps`). Nothing to start.
+  outOfBand: 'none',
 };
 
 export default vercelAiSdk;