@kitn.ai/ui 0.22.2 → 0.24.0

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

@@ -10,13 +10,50 @@ const vercelAiSdk: Integration = {
   // 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';
+  webRoute: `import { dynamicTool, jsonSchema, streamText } from 'ai';
+import type {
+  AssistantContent,
+  FilePart,
+  JSONSchema7,
+  ModelMessage,
+  SystemModelMessage,
+  ToolResultPart,
+  ToolSet,
+  UserContent,
+} from 'ai';
 
 // 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.
 
+/**
+ * The model, PINNED — and deliberately NOT read off the request body.
+ *
+ * Change THIS LINE to change the model; it is the only place one is named. The
+ * AI Gateway takes a \`creator/model-name\` string, so any id it routes works
+ * here without touching another import.
+ *
+ * Why it is not forwarded from the client, unlike the openai / openrouter /
+ * anthropic routes:
+ *
+ *   · Those three POST to ONE host with ONE id space, so the scaffold can seed a
+ *     valid default. The Gateway is a router across every vendor's id space at
+ *     once, so there is no default that is right for it — only one vendor's guess
+ *     baked into a provider-agnostic template.
+ *   · A forwarded model id on a \`needs-proxy\` route is a spend lever handed to
+ *     anything that can POST here, and the Gateway bills per token per model.
+ *
+ * WHY THIS ID. It is the one this route has actually been driven against live —
+ * text, a single tool call and a multi-round tool loop, through the Gateway —
+ * and, unlike a frontier default, it ANSWERS ON A FREE GATEWAY ACCOUNT. A paid
+ * id fails a first \`npm run dev\` with
+ * \`Free tier users do not have access to this model\`, which reads as a broken
+ * scaffold rather than as a billing setting. It also supports tools and
+ * reasoning, so the two things this route re-frames are reachable by default,
+ * and it is cheaper than gpt-4o by roughly two orders of magnitude.
+ */
+const MODEL = 'openai/gpt-oss-120b';
+
 /**
  * One attachment to an AI SDK FilePart.
  *
@@ -88,21 +125,211 @@ function toModelMessages(messages: ChatRequestBody['messages']): ModelMessage[]
   });
 }
 
+/** The OpenAI function-calling envelope the front end sends, narrowed from
+ *  \`unknown[]\`. Declared as this integration's \`clientToolFormat\`. */
+type OpenAIFunctionTool = {
+  function?: { name?: string; description?: string; parameters?: unknown };
+};
+
+/**
+ * OpenAI function schemas -> the AI SDK's own ToolSet.
+ *
+ * \`dynamicTool\` is the helper for a schema known only at RUNTIME. The ordinary
+ * \`tool()\` infers its input type from a Zod schema written in the route, which
+ * a list arriving in the request body cannot have.
+ *
+ * NO \`execute\`, deliberately. A tool the SDK can run makes the ROUTE the loop
+ * owner: streamText would call it, feed the result back and answer in a single
+ * response, so the tool call would never reach the browser and \`<kai-tool>\`
+ * would have nothing to render. Without \`execute\` the SDK emits the call and
+ * stops, which is the contract the kit's front end already implements — run the
+ * tool, \`applyToolOutput\`, POST the thread again.
+ */
+function toToolSet(tools: ChatRequestBody['tools']): ToolSet | undefined {
+  if (!tools?.length) return undefined;
+  const out: ToolSet = {};
+  for (const raw of tools) {
+    const fn = (raw as OpenAIFunctionTool).function;
+    if (!fn?.name) continue;
+    out[fn.name] = dynamicTool({
+      description: fn.description ?? '',
+      inputSchema: jsonSchema((fn.parameters as JSONSchema7 | undefined) ?? { type: 'object' }),
+    });
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** AI SDK finish reasons -> OpenAI's spelling. They agree on 'stop', 'length'
+ *  and 'error' and disagree on the other two, and readOpenAIStream's table reads
+ *  OpenAI's — so an unmapped 'tool-calls' normalises to 'other' and the turn
+ *  stops saying why it stopped. */
+const FINISH_REASONS: Record<string, string> = {
+  'tool-calls': 'tool_calls',
+  'content-filter': 'content_filter',
+};
+
 async function chatHandler(request: Request): Promise<Response> {
-  const { messages } = await readChatRequest(request);
+  const { messages, tools } = await readChatRequest(request);
+  const toolSet = toToolSet(tools);
+  const prompt = toModelMessages(messages);
+
+  // THE SYSTEM TURN DOES NOT GO IN \`messages\`, and this is the one that costs a
+  // live run to find. \`SystemModelMessage\` is still part of the \`ModelMessage\`
+  // union, so a system entry in this array TYPECHECKS — and then \`ai\` v7's
+  // \`standardizePrompt\` throws \`InvalidPromptError: System messages are not
+  // allowed in the prompt or messages fields. Use the instructions option
+  // instead.\` The kit's own encoder puts the system prompt at \`messages[0]\`, so
+  // that is every single turn of a scaffolded app, not an edge case.
+  //
+  // Hoisted rather than joined into a string: \`instructions\` takes the message
+  // array, so several system turns keep their order and their count.
+  //
+  // On \`ai\` v5/v6 there is no \`instructions\` option and a system message in
+  // \`messages\` is correct — drop this split and pass \`prompt\` straight through
+  // if you pin an older SDK.
+  const instructions = prompt.filter((m): m is SystemModelMessage => m.role === 'system');
+  const conversation = prompt.filter((m) => m.role !== 'system');
 
+  // \`streamText\` is not awaited: it returns synchronously and does its work as
+  // the stream is iterated. Prompt validation is part of that work, so an
+  // invalid prompt surfaces from \`for await (… of result.fullStream)\` below
+  // rather than from this line — which is why the catch that reports it lives
+  // in the stream and not around this call. Confirmed by observation: a rejected
+  // prompt reached the browser as an in-band error frame, not as a 500.
   const result = streamText({
-    model: 'openai/gpt-4o', // AI Gateway id; needs AI_GATEWAY_API_KEY
-    messages: toModelMessages(messages),
+    model: MODEL, // AI Gateway id; needs AI_GATEWAY_API_KEY
+    ...(instructions.length > 0 ? { instructions } : {}),
+    messages: conversation,
+    ...(toolSet ? { tools: toolSet } : {}),
   });
 
   const encoder = new TextEncoder();
+
+  // OpenAI correlates tool-call fragments by their POSITION in the tool_calls
+  // array; the SDK identifies each call by id and never sends a position. So one
+  // is derived from the other, in first-seen order, and every fragment of a call
+  // carries the same number. Getting this wrong does not throw — the fragments
+  // land on the wrong call and the arguments come out as spliced JSON.
+  const toolIndex = new Map<string, number>();
+  const indexOf = (id: string): number => {
+    const known = toolIndex.get(id);
+    if (known !== undefined) return known;
+    const next = toolIndex.size;
+    toolIndex.set(id, next);
+    return next;
+  };
+  // How many argument characters a call streamed. \`tool-call\` re-sends the whole
+  // input at the end, so emitting it unconditionally would DOUBLE the arguments
+  // of every call that streamed — and skipping it unconditionally would empty
+  // the arguments of any provider that does not stream them. Neither is safe to
+  // assume, so the decision is made per call from what actually arrived.
+  const streamedArgs = new Map<string, number>();
+
   const sse = new ReadableStream({
     async start(controller) {
+      const send = (chunk: unknown): void => {
+        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\`));
+        // fullStream, NOT textStream. textStream is text deltas only: a tool call
+        // or a reasoning block goes past it silently, so a route built on it
+        // emits a plain answer and nothing else however the model replied.
+        for await (const part of result.fullStream) {
+          switch (part.type) {
+            case 'text-delta':
+              send({ choices: [{ delta: { content: part.text } }] });
+              break;
+
+            case 'reasoning-delta':
+              send({ choices: [{ delta: { reasoning: part.text } }] });
+              break;
+
+            // The call is ANNOUNCED here, before its arguments exist, which is
+            // what lets <kai-tool> open a panel with the tool's name in it while
+            // the arguments are still being written.
+            case 'tool-input-start':
+              streamedArgs.set(part.id, 0);
+              send({
+                choices: [{
+                  delta: {
+                    tool_calls: [{
+                      index: indexOf(part.id),
+                      id: part.id,
+                      type: 'function',
+                      function: { name: part.toolName, arguments: '' },
+                    }],
+                  },
+                }],
+              });
+              break;
+
+            case 'tool-input-delta':
+              streamedArgs.set(part.id, (streamedArgs.get(part.id) ?? 0) + part.delta.length);
+              send({
+                choices: [{
+                  delta: { tool_calls: [{ index: indexOf(part.id), function: { arguments: part.delta } }] },
+                }],
+              });
+              break;
+
+            case 'tool-call':
+              // Only when nothing streamed: see \`streamedArgs\`.
+              if ((streamedArgs.get(part.toolCallId) ?? 0) === 0) {
+                send({
+                  choices: [{
+                    delta: {
+                      tool_calls: [{
+                        index: indexOf(part.toolCallId),
+                        id: part.toolCallId,
+                        type: 'function',
+                        function: {
+                          name: part.toolName,
+                          arguments: JSON.stringify(part.input ?? {}),
+                        },
+                      }],
+                    },
+                  }],
+                });
+              }
+              break;
+
+            // One frame carries both, the way chat-completions sends them.
+            // \`reasoning_tokens\` is the number that proves thinking happened even
+            // when the provider streamed no reasoning text.
+            case 'finish':
+              send({
+                choices: [{
+                  delta: {},
+                  finish_reason: FINISH_REASONS[part.finishReason] ?? part.finishReason,
+                }],
+                usage: {
+                  prompt_tokens: part.totalUsage.inputTokens,
+                  completion_tokens: part.totalUsage.outputTokens,
+                  total_tokens: part.totalUsage.totalTokens,
+                  completion_tokens_details: {
+                    reasoning_tokens: part.totalUsage.outputTokenDetails.reasoningTokens,
+                  },
+                },
+              });
+              break;
+
+            // An error the SDK caught mid-stream. The status is long spent, so it
+            // goes IN BAND like the catch below.
+            case 'error':
+              send({
+                error: {
+                  message: part.error instanceof Error ? part.error.message : String(part.error),
+                },
+              });
+              break;
+
+            // Everything else — text-start/end, tool-input-end, sources, files,
+            // step boundaries, raw provider frames — has no OpenAI-wire spelling
+            // and is dropped. \`source\` is the one worth knowing about: map it to
+            // \`delta.annotations[].url_citation\` if your model cites its sources.
+            default:
+              break;
+          }
         }
       } catch (err) {
         // The status is spent by the time the SDK fails — the headers went out
@@ -110,7 +337,7 @@ async function chatHandler(request: Request): Promise<Response> {
         // 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\`));
+        send({ error: { message } });
       }
       controller.enqueue(encoder.encode('data: [DONE]\\n\\n'));
       controller.close();
@@ -127,12 +354,26 @@ async function chatHandler(request: Request): Promise<Response> {
     },
   });
 }`,
-  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).',
+  streamMapping:
+    "The Vercel AI SDK's toUIMessageStreamResponse() and toTextStreamResponse() don't emit OpenAI-format SSE, so the route re-frames the stream itself and readOpenAIStream from @kitn.ai/ui/wire parses it exactly as it does every other integration. Iterate result.fullStream, NOT result.textStream: textStream carries text deltas only, so a route built on it emits a plain answer however the model replied and drops every tool call and every reasoning block silently. fullStream yields typed parts: text-delta.text -> delta.content, reasoning-delta.text -> delta.reasoning, tool-input-start plus its tool-input-delta fragments -> delta.tool_calls, finish -> finish_reason plus a usage frame, error -> an in-band {error:{message}}. Two traps. (1) OpenAI correlates tool-call fragments by their POSITION in the tool_calls array and the SDK only ever gives an id, so the route keeps an id -> index map; passing anything else through as the index splices one call's arguments into another. (2) fullStream sends the complete input AGAIN on the tool-call part after streaming it in fragments, so emitting both doubles the arguments — the route tracks how much each call streamed and emits the tool-call part only for a provider that streamed none. Parts with no OpenAI spelling (text-start/end, tool-input-end, step boundaries, raw) are dropped; source parts have one — delta.annotations[].url_citation — and are left unmapped because the SDK's Source union carries document sources a url_citation cannot express. On the REQUEST side the trap that only a live run finds: ai v7 REFUSES a system message inside `messages` (InvalidPromptError, 'Use the instructions option instead') even though SystemModelMessage is still in the ModelMessage union and therefore typechecks — and the kit's encoder puts the system prompt at messages[0], so that is every turn. Hoist system turns into `instructions` and pass the rest as `messages`. That failure arrives from ITERATING fullStream, not from the streamText() call — streamText returns synchronously and validates as the stream is read — so the in-band catch around the loop is what reports it, and it reaches the browser as an error frame rather than as a 500.",
+  runNote:
+    "Set AI_GATEWAY_API_KEY for the AI Gateway (string model id form: creator/model-name). The route pins `const MODEL = 'openai/gpt-oss-120b'` — one line, at the top, and any id the Gateway routes works in it. That id is pinned because it answers on a FREE Gateway account: most ids (deepseek/*, meta/*, anthropic/*) return `Free tier users do not have access to this model` or a free-tier rate limit until the account has paid credits, which looks like a broken scaffold rather than a billing setting. For direct provider access, import its provider package (e.g. @ai-sdk/openai) and set the corresponding key (e.g. OPENAI_API_KEY). The tools the front end posts become `dynamicTool`s with NO `execute`, which is what keeps the tool loop in the app: the SDK emits the call and stops, the app runs it, renders it in <kai-tool> and posts the thread back. Give a tool an `execute` and the SDK runs the whole loop server-side, so nothing reaches the browser but the final sentence.",
   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: [],
+  // `tools` only. `model` is deliberately NOT forwarded — the route pins it in
+  // one named const, and see that const's comment for why the Gateway is the one
+  // host where a client-supplied id has no correct default. The catalog check
+  // agrees from the other direction: `every integration that forwards a model
+  // emits one valid for the host it POSTs to` reads the host off the route's own
+  // fetch(), and this route makes no fetch call at all — the SDK owns the
+  // transport — so a forwarded model here could not be validated against
+  // anything.
+  forwardsFromClient: ['tools'],
+  // 'openai': the ROUTE's request contract, not the SDK's own. `toToolSet` reads
+  // `raw.function.name` / `.function.parameters` off each entry — the OpenAI
+  // function-calling envelope — and rebuilds it as a `dynamicTool` with a
+  // `jsonSchema()` input. Sending the SDK's own tool shape from the client would
+  // leave `.function` undefined and every tool would arrive nameless.
+  clientToolFormat: 'openai',
   // `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.

package/src/agent-tooling/mcp/tools/scaffold.ts

@@ -8,6 +8,13 @@ import {
   listArchetypes,
   listIntegrations,
 } from '../../registry';
+// The route-emission facts, read rather than restated — and deliberately living
+// OUTSIDE this file. This module builds its zod input schema at module scope, so
+// a bundler asked for one of these three has to keep all 5,300 lines of it and
+// all of zod with them; `create-kai`'s CLI bundle went 203 kB -> 904 kB when they
+// were exported from here. See the header of `route-emit.ts`. Import FROM there,
+// never re-export through here.
+import { chatRoutePreamble, defaultModelFor } from '../../route-emit';
 // The kit's media-type declaration, read rather than restated. This is the one
 // import in agent-tooling that reaches outside itself, and the module it reaches
 // for is the reason: `wire/media-types.ts` is pure (no I/O, no DOM, no solid-js),
@@ -68,11 +75,11 @@ interface PlacementStyle {
   altNote?: string[];
 }
 
-// The chat element must fill its container. In a `display: flex; flex-direction:
-// column` shell it's a flex child (`flex: 1; min-height: 0`); in a plain block
-// container it fills via `height: 100%`.
+// The chat element must fill its container. Every placement below is a
+// `display: flex; flex-direction: column` shell, so the element is always a flex
+// child and this is the only fill there is. A `height: 100%` variant for a plain
+// block container used to sit here beside it; nothing ever selected it.
 const FLEX_FILL = 'flex: 1; min-height: 0;';
-const BLOCK_FILL = 'height: 100%; width: 100%;';
 
 /**
  * full-page, and it has to be true in a STOCK starter — not just in an empty page.
@@ -808,65 +815,6 @@ function realBodyPayload(opts: { defaultModel?: string; tools: boolean }): (thre
   };
 }
 
-// ── SCAF-8: per-integration default model ids ─────────────────────────────────
-
-/**
- * Default model id per integration whose route forwards one.
- *
- * THE ID IS HOST-SPECIFIC, and there is no such thing as a safe generic one.
- * This used to fall through to `'openai/gpt-4o-mini'` for anything unlisted, on
- * the reasoning that "a route that forwards the client's model is by definition
- * pointed at an OpenAI-compatible endpoint". That was false twice over the
- * moment a first-party provider landed: `openai/gpt-4o-mini` is an OPENROUTER
- * slug — api.openai.com 404s the prefixed form, and api.anthropic.com rejects it
- * outright — so a scaffold generated for the provider it names could not run
- * against it.
- *
- * tsc cannot see any of this; every one of those strings compiles. The guard is
- * `scaffold.test.ts` → "the emitted model id is valid for the host its route
- * POSTs to", which reads the id out of the EMITTED scaffold and the host out of
- * the route source, so a new integration cannot reintroduce a wrong one.
- */
-const CLIENT_MODEL_IDS: Record<string, string> = {
-  // Vendor-prefixed `vendor/model`: OpenRouter's own id space, and the ONLY one
-  // of the three where the prefix belongs.
-  openrouter: 'openai/gpt-4o-mini',
-  // No vendor prefix. This is what the route already pinned, so moving the knob
-  // to the client changes the wire not at all.
-  openai: 'gpt-4o-mini',
-  // Anthropic's id space. Matches what the route pinned; 'claude-sonnet-5' and
-  // 'claude-haiku-4-5' are the cheaper swaps (see this integration's runNote).
-  anthropic: 'claude-opus-5',
-};
-
-/**
- * The default model id for an integration whose ROUTE reads the client's `model`
- * field, and undefined for every other one.
- *
- * This used to be a substring test (`routeSrc.includes('model')`), which is true
- * of any template that so much as writes `model: 'llama3.2'`. That emitted an
- * editable `const model` into ollama, langgraph, vercel-ai-sdk and cloudflare
- * scaffolds whose routes pin their own model and never read the field, so
- * changing it did nothing, and cloudflare's default was not even a valid Workers
- * AI id. `forwardsFromClient` states the fact instead of guessing at it.
- */
-function defaultModelFor(integration: Integration): string | undefined {
-  if (!integration.forwardsFromClient.includes('model')) return undefined;
-  const id = CLIENT_MODEL_IDS[integration.id];
-  // No fallback, deliberately — the old `?? 'openai/gpt-4o-mini'` is what let a
-  // first-party provider inherit an OpenRouter slug and emit a scaffold that
-  // 404s on its own host. A model id is a per-host fact; an integration that
-  // forwards one has to say which.
-  if (id === undefined) {
-    throw new Error(
-      `Integration '${integration.id}' forwards the client's 'model' but has no CLIENT_MODEL_IDS entry, so the ` +
-        `scaffold would emit a model id that is not valid for the host its route POSTs to. Add one in ` +
-        `mcp/tools/scaffold.ts.`,
-    );
-  }
-  return id;
-}
-
 /**
  * True when the scaffold should declare tool schemas and put them in the body.
  *
@@ -4488,122 +4436,6 @@ const WEB_ROUTE_ADAPTERS: Record<string, WebRouteAdapter> = {
   },
 };
 
-/**
- * The request body, declared once per route file.
- *
- * `await request.json()` is `unknown` — it is whatever the client sent — so
- * destructuring it directly is TS2339 on EVERY field. That is not pedantry: it
- * is a hard `npm run build` failure the moment a Node-typed project compiles the
- * route, where `Request` comes from undici (`json(): Promise<unknown>`) rather
- * than from the DOM lib (`json(): Promise<any>`). A stock Vite app does exactly
- * that — `tsc -b` walks vite.config.ts → vite-chat-api.ts → src/server/chat.ts
- * with `lib` and no DOM — so the route ran fine and the build did not.
- *
- * `messages` is typed as the kit's OWN encoder output rather than restated
- * structurally, which keeps the two halves of the scaffold pinned to one type:
- * the front end sends `toOpenAIMessages(thread)`, and this is what that returns.
- * The import is type-only and erases at build time, so the route ships no
- * runtime dependency on the kit.
- */
-const CHAT_REQUEST_BODY_IMPORT = `import type { OpenAIWireMessage } from '@kitn.ai/ui/wire';`;
-const CHAT_REQUEST_BODY_DECL = [
-  `/**`,
-  ` * What the front end POSTs. \`request.json()\` is \`unknown\` (it is whatever the`,
-  ` * client sent), so the body is narrowed once here instead of at every use —`,
-  ` * without it this route does not compile under a server tsconfig. Widen it as`,
-  ` * you add fields of your own.`,
-  ` */`,
-  `type ChatRequestBody = {`,
-  `  messages: OpenAIWireMessage[];`,
-  `  model?: string;`,
-  `  tools?: unknown[];`,
-  `};`,
-  ``,
-  `/** Narrow the JSON body once, at the edge. */`,
-  `async function readChatRequest(request: Request): Promise<ChatRequestBody> {`,
-  `  return (await request.json()) as ChatRequestBody;`,
-  `}`,
-];
-
-/**
- * Attachments, on the way IN.
- *
- * A user turn's `content` is a plain string until it carries a file, at which
- * point `toOpenAIMessages` emits the ARRAY form. Every route that re-maps
- * messages into some other SDK's shape has to handle both, and the three that do
- * (anthropic, mastra, vercel-ai-sdk) were each written when only the string form
- * existed — so each one would have quietly dropped the attachment while still
- * compiling, which is the same defect the encoder was just fixed for.
- *
- * These two helpers are the shared half of that: flattening the wire shape is
- * identical everywhere, while the target shape is not, so each route maps
- * `WirePart[]` into its own SDK itself rather than inheriting a lowest common
- * denominator.
- *
- * Only injected into routes that actually call them — the eight pass-through
- * integrations forward `messages` untouched and need none of this, and an unused
- * declaration is a hard error under the gate's `--noUnusedLocals`.
- */
-const CONTENT_PARTS_DECL = [
-  `/** Where an attachment's bytes are: inline base64, or an address the PROVIDER`,
-  ` *  fetches. Never both. */`,
-  `type WireFileSource = { type: 'data'; data: string } | { type: 'url'; url: string };`,
-  ``,
-  `/** One piece of a turn, with the string and array content forms flattened into`,
-  ` *  a single shape. */`,
-  `type WirePart =`,
-  `  | { kind: 'text'; text: string }`,
-  `  | { kind: 'file'; mediaType: string; filename?: string; source: WireFileSource };`,
-  ``,
-  `const DATA_URI = /^data:([^;,]+);base64,([\\s\\S]*)$/;`,
-  ``,
-  `/**`,
-  ` * Flatten a wire message's content into parts.`,
-  ` *`,
-  ` * An image sent by URL has no media type here — \`image_url\` carries only the`,
-  ` * address — so it reports the top-level segment \`'image'\`, which is all a URL`,
-  ` * source needs. Only images can reach that branch: the kit refuses to encode a`,
-  ` * remote PDF rather than guess at one.`,
-  ` */`,
-  `function wireParts(content: OpenAIWireMessage['content']): WirePart[] {`,
-  `  if (content == null) return [];`,
-  `  if (typeof content === 'string') return content === '' ? [] : [{ kind: 'text', text: content }];`,
-  `  return content.map((part): WirePart => {`,
-  `    if (part.type === 'text') return { kind: 'text', text: part.text };`,
-  `    if (part.type === 'image_url') {`,
-  `      const asData = DATA_URI.exec(part.image_url.url);`,
-  `      return asData`,
-  `        ? { kind: 'file', mediaType: asData[1], source: { type: 'data', data: asData[2] } }`,
-  `        : { kind: 'file', mediaType: 'image', source: { type: 'url', url: part.image_url.url } };`,
-  `    }`,
-  `    const asData = DATA_URI.exec(part.file.file_data);`,
-  `    if (!asData) {`,
-  `      // LOUD on purpose. \`file_data\` is a data URI on this wire; anything else`,
-  `      // cannot be turned into bytes without fetching it, and forwarding a turn`,
-  `      // with the attachment quietly missing is the bug this whole path exists`,
-  `      // to prevent.`,
-  `      throw new Error(`,
-  `        'Unsupported file content part: file_data must be a data: URI of the form data:<media type>;base64,<data>.',`,
-  `      );`,
-  `    }`,
-  `    return {`,
-  `      kind: 'file',`,
-  `      mediaType: asData[1],`,
-  `      filename: part.file.filename,`,
-  `      source: { type: 'data', data: asData[2] },`,
-  `    };`,
-  `  });`,
-  `}`,
-  ``,
-  `/** Just the text of a turn. System, assistant and tool messages are text-only`,
-  ` *  on this wire, so this collapses the array form for them. */`,
-  `function wireText(content: OpenAIWireMessage['content']): string {`,
-  `  return wireParts(content)`,
-  `    .map((p) => (p.kind === 'text' ? p.text : ''))`,
-  `    .join('');`,
-  `}`,
-];
-
 /**
  * Slot the body type in just above `chatHandler`.
  *
@@ -4613,12 +4445,7 @@ const CONTENT_PARTS_DECL = [
  * block that documents it — puts the declaration where a person would have
  * written it.
  */
-function withChatRequestBody(fragment: string): string {
-  // The content helpers ride along only where the route calls them; see
-  // CONTENT_PARTS_DECL for why an unconditional injection would not compile.
-  const decl = /\bwire(?:Parts|Text)\s*\(/.test(fragment)
-    ? [...CHAT_REQUEST_BODY_DECL, ``, ...CONTENT_PARTS_DECL]
-    : CHAT_REQUEST_BODY_DECL;
+function withChatRequestBody(fragment: string, decl: readonly string[]): string {
   const lines = fragment.split('\n');
   let at = lines.findIndex((l) => /^(?:export\s+)?async function chatHandler\b/.test(l));
   if (at < 0) return [...decl, ``, ...lines].join('\n');
@@ -4635,17 +4462,22 @@ function webRouteFor(integration: Integration, framework: string): RouteChoice |
   // pull in an import to do it (SvelteKit's $env accessor). Both land at the top
   // of the file, beside the adapter's own `before` lines.
   const adapted = adapter.adaptFragment?.(fragment) ?? { fragment, imports: [] };
+  // One preamble for the whole file: its `imports` go at the top beside the
+  // adapter's own, its `decl` immediately above the handler. Both halves come
+  // from `chatRoutePreamble` rather than from a constant here, so this emitter
+  // and `create-kai`'s cannot answer "what does this route need" differently.
+  const preamble = chatRoutePreamble(adapted.fragment);
   return {
     framework,
     runtime: adapter.runtime,
     exact: true,
     template: [
       `// ${adapter.file}`,
-      CHAT_REQUEST_BODY_IMPORT,
+      ...preamble.imports,
       ...(adapter.before ?? []),
       ...adapted.imports,
       ``,
-      withChatRequestBody(adapted.fragment),
+      withChatRequestBody(adapted.fragment, preamble.decl),
       ...adapter.after,
     ].join('\n'),
   };