@kitn.ai/ui 0.20.1 → 0.22.0

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

@@ -7,9 +7,10 @@ const langgraph: Integration = {
   language: 'ts',
   streamFormat: 'openai-sse',
   envVars: ['OPENAI_API_KEY'],
-  routeTemplates: {
-    next: `// POST /api/chat — stream a compiled LangGraph agent to the browser
-import { createReactAgent } from '@langchain/langgraph/prebuilt';
+  // 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 { createReactAgent } from '@langchain/langgraph/prebuilt';
 import { ChatOpenAI } from '@langchain/openai';
 import { tool } from '@langchain/core/tools';
 import { z } from 'zod';
@@ -28,10 +29,35 @@ const agent = createReactAgent({
   tools: [getWeather],
 });
 
-export async function POST(req: Request) {
-  const { messages } = await req.json();
+// Stream a compiled LangGraph agent to the browser as OpenAI-format SSE.
+async function chatHandler(request: Request): Promise<Response> {
+  const { messages } = await readChatRequest(request);
 
-  const stream = await agent.stream({ messages }, { streamMode: 'messages' });
+  // agent.stream() coerces plain {role, content} objects into BaseMessage
+  // instances itself, including OpenAI-shaped tool_calls, so the wire messages
+  // can be passed through almost as-is. The one incompatible bit is content:
+  // OpenAI represents a tool-calls-only assistant turn as content: null, and
+  // LangChain's MessageContent type (and runtime coercion) only accepts string.
+  const agentMessages = messages.map((m) => ({ ...m, content: m.content ?? '' }));
+
+  // Let TS infer the stream's element type from this call instead of hand
+  // writing it: the real type is a [BaseMessage, metadata] tuple, keyed off the
+  // streamMode: 'messages' literal, not the plain object shape it looks like.
+  const startStream = () => agent.stream({ messages: agentMessages }, { streamMode: 'messages' });
+
+  let stream: Awaited<ReturnType<typeof startStream>>;
+  try {
+    stream = await startStream();
+  } catch (err) {
+    // A REAL status, before a byte is streamed: a missing OPENAI_API_KEY fails
+    // here. Returning 200 would send this JSON out labelled text/event-stream,
+    // the SSE reader would find no frame, and the turn would resolve empty with
+    // nothing logged and no bubble.
+    return new Response(
+      JSON.stringify({ error: { message: err instanceof Error ? err.message : 'Agent failed to start' } }),
+      { status: 502, headers: { 'Content-Type': 'application/json' } },
+    );
+  }
 
   const encoder = new TextEncoder();
   const body = new ReadableStream({
@@ -39,22 +65,63 @@ export async function POST(req: Request) {
       const send = (obj: unknown) =>
         controller.enqueue(encoder.encode(\`data: \${JSON.stringify(obj)}\\n\\n\`));
 
-      for await (const [chunk] of stream) {
-        if (typeof chunk.content === 'string' && chunk.content) {
-          send({ choices: [{ delta: { content: chunk.content } }] });
+      try {
+        for await (const [chunk] of stream) {
+          if (typeof chunk.content === 'string' && chunk.content) {
+            send({ choices: [{ delta: { content: chunk.content } }] });
+          }
         }
+      } catch (err) {
+        // The status is spent once the stream started, so report IN BAND:
+        // readOpenAIStream lands this on turn.error and keeps what streamed.
+        send({ error: { message: err instanceof Error ? err.message : 'Agent stream failed' } });
       }
       controller.enqueue(encoder.encode('data: [DONE]\\n\\n'));
       controller.close();
     },
   });
 
-  return new Response(body, { headers: { 'Content-Type': 'text/event-stream' } });
+  return new Response(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',
+    },
+  });
 }`,
-  },
-  streamMapping: "Use graph.stream(input, { streamMode: 'messages' }) to get [messageChunk, metadata] tuples. Extract chunk.content (string) and forward as OpenAI-format SSE frames: data: {choices:[{delta:{content}}]}. Close with data: [DONE]. The kai-chat reader handles it.",
-  runNote: 'Set OPENAI_API_KEY (or the key for your chosen model provider). Install @langchain/langgraph, @langchain/openai, @langchain/core.',
+  streamMapping: "Use graph.stream(input, { streamMode: 'messages' }) to get [messageChunk, metadata] tuples. Extract chunk.content (string) and forward as OpenAI-format SSE frames: data: {choices:[{delta:{content}}]}. Close with data: [DONE]. readOpenAIStream from @kitn.ai/ui/wire parses tool calls and reasoning too, but the route template forwards chunk.content only, which is text: the same message chunks carry the tool-call fragments on chunk.tool_call_chunks, so re-frame those 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 end "Install @langchain/langgraph, @langchain/openai,
+  // @langchain/core." — three of the four packages, for as long as nobody was
+  // comparing it to anything.
+  runNote: 'Set OPENAI_API_KEY (or the key for your chosen model provider).',
   docsSlug: 'integrations/langgraph',
+  // Nothing. The agent owns both: ChatOpenAI({ model: 'gpt-4o' }) and the tools
+  // array passed to createReactAgent are server-side.
+  forwardsFromClient: [],
+  // Four, one per import in the route above. `zod` is the one the deleted prose
+  // forgot: the tool's `schema:` is a z.object(), so an app installed from that
+  // sentence alone fails to build. Deriving this from the imports rather than
+  // from a sentence is the point of the field.
+  deps: { npm: ['@langchain/langgraph', '@langchain/openai', '@langchain/core', 'zod'], pip: [] },
+  // No key appears in the route: `new ChatOpenAI(...)` reads OPENAI_API_KEY from
+  // the environment itself. Same invisible-key shape as vercel-ai-sdk.
+  keyExposure: 'needs-proxy',
+  // 'none', and this is the entry most likely to be "corrected" to something
+  // else, so the reason is here rather than assumed. The create-kai spec lists
+  // LangGraph under "Bring a server or runtime". That is WRONG for this route:
+  // the graph is built and compiled IN PROCESS above (`createReactAgent` over a
+  // `new ChatOpenAI(...)`), so there is no LangGraph server, no port and no
+  // second process — the four packages in `deps` are the whole install and
+  // `runNote` asks for a key and nothing else.
+  //
+  // LangGraph Platform / `langgraph dev` IS a server, and an integration that
+  // talked to one over HTTP would be 'local-server'. That is a different route
+  // than the one above, and if it is ever added it must be added as its own
+  // catalog entry rather than by changing this line.
+  outOfBand: 'none',
 };
 
 export default langgraph;

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

@@ -7,21 +7,170 @@ const mastra: Integration = {
   language: 'ts',
   streamFormat: 'openai-sse',
   envVars: ['MASTRA_URL'],
-  routeTemplates: {
-    express: `// POST /api/chat — your server proxies a Mastra agent to the browser
-import { MastraClient } from '@mastra/client-js';
+  // No per-framework templates. The old `express` entry was a fragment, not a
+  // route: it referenced `messages` and `res` without declaring either, and
+  // every non-express framework inherited it anyway. The handler below is
+  // web-standard, so the scaffolder wraps it per framework.
+  routeTemplates: {},
+  webRoute: `import { MastraClient } from '@mastra/client-js';
 
-const mastra = new MastraClient({ baseUrl: process.env.MASTRA_URL });
-
-const stream = await mastra.getAgent('supportAgent').stream({ messages });
-for await (const delta of stream.textStream) {
-  res.write(\`data: \${JSON.stringify({ choices: [{ delta: { content: delta } }] })}\\n\\n\`);
+// MASTRA_URL is required, not defaulted to localhost: a deployed consumer app
+// that forgets to set it would otherwise construct a client that silently
+// points a production Worker/serverless function at 127.0.0.1, then fail deep
+// inside a fetch call with a confusing connection error. Failing at import
+// time, with a message that names the fix, is louder and cheaper to debug.
+const MASTRA_URL = process.env.MASTRA_URL;
+if (!MASTRA_URL) {
+  throw new Error('MASTRA_URL is not set. Point it at your Mastra server, e.g. http://localhost:4111 for \`mastra dev\`.');
 }
-res.write('data: [DONE]\\n\\n');`,
-  },
-  streamMapping: "Mastra agents speak Vercel AI SDK v5 and expose stream.textStream (async iterable of string deltas). Iterate textStream and emit data: {choices:[{delta:{content}}]} frames; close with data: [DONE]. kai-chat's SSE reader handles it. For tool calls and reasoning, convert the agent to a UI message stream with @mastra/ai-sdk.",
-  runNote: 'Set MASTRA_URL to your Mastra server base URL (mastra dev exposes POST /api/agents/:agentId/stream on port 4111). Install @mastra/client-js.',
+
+const mastra = new MastraClient({ baseUrl: MASTRA_URL });
+
+// Proxy a Mastra agent to the browser as OpenAI-format SSE.
+async function chatHandler(request: Request): Promise<Response> {
+  const { messages } = await readChatRequest(request);
+
+  // MastraClient's Agent.stream() takes AI-SDK CoreMessage[], not the OpenAI
+  // wire format: each message has ONE literal role (not a union) and content
+  // is never null. A 'tool' wire message is OUR client-side tool bookkeeping;
+  // this agent owns its tools server-side (forwardsFromClient is empty), so it
+  // has no schema for that shape and the entry is dropped rather than guessed.
+  //
+  // Only the USER role takes content parts: a system prompt is text by
+  // definition, and an assistant turn here is replayed history, not a new
+  // upload. \`data\` uses the bare base64-or-URL shorthand, which every AI SDK
+  // major Mastra accepts understands.
+  type MastraFilePart = { type: 'file'; data: string | URL; mediaType: string; filename?: string };
+  type MastraUserContent = string | Array<{ type: 'text'; text: string } | MastraFilePart>;
+  type MastraMessage = { role: 'system'; content: string } | { role: 'user'; content: MastraUserContent } | { role: 'assistant'; content: string };
+  const mastraMessages: MastraMessage[] = [];
+  for (const m of messages) {
+    // Each branch constructs a literal with ONE fixed role, not m.role (which is
+    // still typed as the 4-way union): a union-VALUED field on a single object
+    // does not structurally match a union of role-discriminated objects, so
+    // widening back to m.role here would reintroduce the original TS2345.
+    if (m.role === 'system') mastraMessages.push({ role: 'system', content: wireText(m.content) });
+    else if (m.role === 'assistant') mastraMessages.push({ role: 'assistant', content: wireText(m.content) });
+    else if (m.role === 'user') {
+      const parts = wireParts(m.content);
+      // Plain string unless the turn actually carries an attachment.
+      if (parts.every((p) => p.kind === 'text')) {
+        mastraMessages.push({ role: 'user', content: wireText(m.content) });
+      } else {
+        mastraMessages.push({
+          role: 'user',
+          content: parts.map((p) =>
+            p.kind === 'text'
+              ? { type: 'text' as const, text: p.text }
+              : {
+                  type: 'file' as const,
+                  mediaType: p.mediaType,
+                  ...(p.filename === undefined ? {} : { filename: p.filename }),
+                  data: p.source.type === 'data' ? p.source.data : new URL(p.source.url),
+                },
+          ),
+        });
+      }
+    }
+  }
+
+  let agentStream: Awaited<ReturnType<ReturnType<typeof mastra.getAgent>['stream']>>;
+  try {
+    agentStream = await mastra.getAgent('supportAgent').stream(mastraMessages);
+  } catch (err) {
+    // A REAL status, before a byte is streamed: an unreachable MASTRA_URL or an
+    // unknown agent id fails here. Returning 200 would send this JSON out
+    // labelled text/event-stream, the SSE reader would find no frame, and the
+    // turn would resolve empty with nothing logged and no bubble.
+    return new Response(
+      JSON.stringify({ error: { message: err instanceof Error ? err.message : 'Mastra agent failed to start' } }),
+      { status: 502, headers: { 'Content-Type': 'application/json' } },
+    );
+  }
+
+  const encoder = new TextEncoder();
+  const body = new ReadableStream({
+    async start(controller) {
+      try {
+        // The client SDK has no textStream: it hands back a Response wrapped
+        // with processDataStream, which replays the agent's SSE body as typed
+        // chunks. Only text-delta carries browser-facing content; tool-call and
+        // reasoning chunks exist here too but are out of scope for this route
+        // (see streamMapping) and are left unhandled rather than half-wired.
+        await agentStream.processDataStream({
+          onChunk: (chunk) => {
+            if (chunk.type === 'text-delta') {
+              const openaiChunk = { choices: [{ delta: { content: chunk.payload.text } }] };
+              controller.enqueue(encoder.encode(\`data: \${JSON.stringify(openaiChunk)}\\n\\n\`));
+            } else if (chunk.type === 'error') {
+              // Mastra reports some failures IN BAND as an 'error' chunk instead
+              // of rejecting the stream; fold it into the same frame the catch
+              // below emits so readOpenAIStream lands it on turn.error either way.
+              const message = chunk.payload.error instanceof Error ? chunk.payload.error.message : 'Mastra agent reported an error';
+              controller.enqueue(encoder.encode(\`data: \${JSON.stringify({ error: { message } })}\\n\\n\`));
+            }
+          },
+        });
+      } catch (err) {
+        // The status is spent once the stream started, so report IN BAND:
+        // readOpenAIStream lands this on turn.error and keeps what streamed.
+        const message = err instanceof Error ? err.message : 'Mastra 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(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',
+    },
+  });
+}`,
+  streamMapping: "Mastra's client SDK has no textStream: agent.stream() returns a Response wrapped with processDataStream({ onChunk }), which replays the agent's SSE body as typed chunks (text-delta, tool-call, reasoning-delta, error, finish, ...). Filter to type === 'text-delta' and emit data: {choices:[{delta:{content:payload.text}}]} frames; close with data: [DONE]. readOpenAIStream from @kitn.ai/ui/wire parses that, including tool calls and reasoning, but this route only wires text-delta: re-frame tool-call/tool-result and reasoning-delta chunks onto delta.tool_calls and delta.reasoning to get them too.",
+  // No install list here: `deps` below is the one, and the scaffolder emits it.
+  // This sentence used to end "Install @mastra/client-js." — right on the day it
+  // was written, and unchecked against the route's imports ever after.
+  runNote: 'Set MASTRA_URL to your Mastra server base URL (mastra dev exposes POST /api/agents/:agentId/stream on port 4111).',
   docsSlug: 'integrations/harnesses',
+  // Nothing. The Mastra agent owns its model and its tools server-side.
+  forwardsFromClient: [],
+  // The route's one import.
+  deps: { npm: ['@mastra/client-js'], pip: [] },
+  // THE JUDGEMENT CALL IN THIS TABLE, so it is argued rather than asserted.
+  //
+  // MASTRA_URL is not a secret — it is a base URL, and the schema's SECRET_ENV_VAR
+  // net deliberately does not match it. So the automatic check cannot decide this
+  // one, and 'frontend-safe' would parse cleanly.
+  //
+  // It is still 'needs-proxy', on what the route actually is: this integration
+  // ships a server `chatHandler` that reads `process.env` at module scope, and
+  // nothing else. There is no browser-direct path in it. Declaring it
+  // 'frontend-safe' would have the CLI point a public bundle at an unauthenticated
+  // agent endpoint — a decision a scaffolder must not make silently, even though
+  // no key leaks. The conservative direction is the cheap one: a needless server
+  // hop costs a process, the other error costs the endpoint.
+  keyExposure: 'needs-proxy',
+  // THE JUDGEMENT CALL FOR THIS FIELD, exactly as keyExposure above is, and for
+  // a related reason: no automatic check can decide it. MASTRA_URL is a base URL
+  // for a server this integration does not ship and cannot start; the route's
+  // only mention of loopback is inside a `throw new Error(...)` string, which
+  // LOOPBACK_FETCH deliberately does not match (a net that fired on prose would
+  // be right here by accident and wrong elsewhere). So 'none' would parse
+  // cleanly.
+  //
+  // It is 'local-server' on what the integration actually requires: a Mastra
+  // server has to be reachable at MASTRA_URL before the first message works,
+  // `mastra dev` is how a developer gets one (port 4111), and `@mastra/client-js`
+  // is a CLIENT for it, not the server itself. Printing "start your Mastra
+  // server" costs a line; omitting it produces a scaffold that fetches a URL
+  // nothing answers.
+  outOfBand: 'local-server',
 };
 
 export default mastra;

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

@@ -1,16 +1,39 @@
 import type { Integration } from '../types';
 
 /**
- * mock — the zero-config first-win.
+ * mock: the zero-config first-win.
  *
- * Not a real backend: there's no provider, no API key, no `/api` route. The
- * scaffolder special-cases `integration === 'mock'` and emits a front-end whose
- * `onSubmit` SIMULATES a streamed assistant reply CLIENT-SIDE (token-by-token,
- * a new array/object reference per chunk — honouring the messages contract).
+ * No provider, no API key, no `/api` route, no network. The scaffolder
+ * special-cases `integration === 'mock'` and emits a front-end whose `onSubmit`
+ * calls `createMockResponder()` from `@kitn.ai/ui/state` where a real
+ * integration calls `fetch('/api/chat', …)`. That is the ONLY difference between
+ * the two emitted handlers. Everything after that expression is already the real
+ * path: `readOpenAIStream` parses the frames, `createAssistantStream` folds them
+ * onto the message parts, and the try/catch/finally and abort handling are
+ * byte-identical. The zero-config preview therefore exercises the kit's own SSE
+ * reader rather than a hand-rolled fold that merely resembles it.
+ *
+ * WHY OPENAI-SHAPED FRAMES. The mock stands in for the consumer's ROUTE, not for
+ * a provider. Every other integration in this catalog re-frames its provider to
+ * the OpenAI chat-completions shape server-side before the browser sees it
+ * (`anthropic`'s route converts the Messages dialect frame by frame, `pi`'s
+ * bridge converts Pi's stdout JSON, `vercel-ai-sdk` wraps `result.textStream`),
+ * which is why `readOpenAIStream` is the only reader the scaffolder emits.
+ * Matching that shape is what keeps "swap the mock for a real backend" a
+ * one-expression change instead of a rewrite of the submit handler.
+ *
+ * WHY YOU CAN ALWAYS TELL. Sharing a real provider's frame shape means shape
+ * alone no longer marks the reply as fake, so the tells are explicit: the stream
+ * opens with a `: kai-mock` SSE comment, every frame carries a `_kai_mock` field
+ * naming the function that produced it, `model` reports as `kai-mock` (no
+ * provider serves that, so an echoed mock frame is rejected upstream rather than
+ * quietly believed), and usage is all zeros. `src/state/mock.ts` records why each
+ * tell sits at a different altitude; do not remove one without reading it.
  *
  * This lets `scaffold(useCase, integration: 'mock', framework: 'react')` run with
  * zero config so a developer sees a live, streaming chat before wiring a model.
- * Swap `integration` for a real provider (openrouter, ollama, …) when ready.
+ * Swap `integration` for a real provider (openai, anthropic, openrouter, ollama,
+ * …) when ready.
  *
  * It carries an empty `routeTemplates` on purpose: there is no server route to
  * emit. `category: 'mock'` keeps it out of the real provider/gateway/framework/
@@ -25,10 +48,26 @@ const mock: Integration = {
   envVars: [],
   routeTemplates: {},
   streamMapping:
-    'No backend. onSubmit streams a canned assistant reply client-side, one token at a time, reassigning messages (new array/object reference) per chunk so kai-chat re-renders. Swap integration for a real provider when ready.',
+    "No backend and no provider, but a real wire. createMockResponder() from @kitn.ai/ui/state yields canned SSE frames and the scaffold reads them with readOpenAIStream from @kitn.ai/ui/wire, on the same code path a real route's response takes: same reader, same part folding, same abort handling. The frames carry the OpenAI chat-completions shape because the mock stands in for your /api/chat ROUTE, not for a provider (every other integration here re-frames its provider to that shape server-side), so going live replaces ONE expression: mockResponse(value) becomes the awaited response from your own chat route, and nothing else in the handler changes. Nothing here can be mistaken for a real turn: the stream opens with a ': kai-mock' SSE comment, every frame carries a _kai_mock field naming createMockResponder, model reports as 'kai-mock' (no provider serves it), and usage is all zeros.",
   runNote:
-    'No backend or API key needed — replies stream locally for preview. Run the front-end as-is; swap `integration` for a real provider (e.g. openrouter, ollama) when ready.',
+    'No backend or API key needed: the reply is generated in the browser and parsed by the same reader a real route feeds. Run the front-end as-is; swap `integration` for a real provider (openai, anthropic, openrouter, ollama) when ready, and the emitted handler differs by one expression.',
   docsSlug: 'integrations/mock',
+  // Nothing: there is no HTTP request at all. The frames are produced in-process
+  // by createMockResponder(), so there is no body to forward a model or a tools
+  // array on, and no route that would read one.
+  forwardsFromClient: [],
+  // Nothing to install: there is no route to install anything for.
+  deps: { npm: [], pip: [] },
+  // The other 'frontend-safe' entry, and the only one that is true by absence:
+  // no routeTemplates, no webRoute, no envVars. There is no request, no upstream
+  // and no secret, so there is nothing a public bundle could give away. This is
+  // the one place where "declares nothing" genuinely means safe — which is
+  // precisely why it still has to SAY so rather than be left blank.
+  keyExposure: 'frontend-safe',
+  // Nothing at all, and here that is the literal truth rather than a shorthand:
+  // there is no route, no upstream and no process. This is the "No backend"
+  // group of create-kai's gateway prompt all by itself.
+  outOfBand: 'none',
 };
 
 export default mock;

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

@@ -7,41 +7,85 @@ const ollama: Integration = {
   language: 'ts',
   streamFormat: 'openai-sse',
   envVars: [],
-  routeTemplates: {
-    next: `// app/api/chat/route.ts — proxy the browser to local Ollama
-export async function POST(req: Request) {
-  const { messages } = await req.json();
+  // No per-framework templates. The handler below is web-standard, so the
+  // scaffolder wraps it in the target framework's own route declaration.
+  //
+  // There was never an `html` entry and there must not be one: routeTemplates
+  // keyed by 'html' are selected as the BACKEND ROUTE for framework: 'html', and
+  // this integration's used to be a second <kai-chat id="chat"> plus a second
+  // kai-submit listener, so pasting both blocks gave a duplicate id and two
+  // fetches per submit. chooseRoute refuses an 'html' key outright.
+  routeTemplates: {},
+  webRoute: `async function chatHandler(request: Request): Promise<Response> {
+  // The model is pinned here, not sent by the browser. tools IS forwarded:
+  // it is undefined unless the front end declared any, and JSON.stringify
+  // drops it, so the same handler serves a tool archetype and a plain chat.
+  const { messages, tools } = await readChatRequest(request);
 
   const upstream = await fetch('http://localhost:11434/v1/chat/completions', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ model: 'llama3.2', messages, stream: true }),
+    body: JSON.stringify({ model: 'llama3.2', messages, tools, stream: true }),
   });
 
-  // Ollama returns OpenAI-format SSE — stream it straight to the browser.
-  return new Response(upstream.body, { headers: { 'Content-Type': 'text/event-stream' } });
-}`,
-    html: `<kai-chat id="chat"></kai-chat>
-
-<script type="module">
-  import '@kitn.ai/ui/elements';
-  const chat = document.getElementById('chat');
-
-  chat.addEventListener('kai-submit', async (e) => {
-    const history = [...chat.messages, { id: crypto.randomUUID(), role: 'user', content: e.detail.value }];
-    chat.messages = [...history, { id: crypto.randomUUID(), role: 'assistant', content: '' }];
-    await fetch('/api/chat', {
-      method: 'POST',
+  // FORWARD THE STATUS. Returning 200 for a failed upstream is how "ollama is
+  // not running" or "that model was never pulled" turns into silence: the error
+  // 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.
+  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: 'Ollama returned no body to stream.' } }), {
+      status: 502,
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ messages: history }),
     });
-    // stream the reply into the last message — see the Streaming recipe
+  }
+
+  // Ollama returns OpenAI-format SSE. Stream it straight to the browser.
+  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',
+    },
   });
-</script>`,
-  },
-  streamMapping: "Ollama's OpenAI-compatible endpoint (http://localhost:11434/v1/chat/completions) returns OpenAI-format SSE — pipe upstream.body straight to the browser; kai-chat's reader handles it. No API key needed; pass any string if a client requires one (Ollama ignores it).",
+}`,
+  streamMapping:
+    "Ollama's OpenAI-compatible endpoint (http://localhost:11434/v1/chat/completions) returns OpenAI-format SSE. Pipe upstream.body straight to the browser; readOpenAIStream from @kitn.ai/ui/wire parses it, including tool calls and reasoning. No API key needed; pass any string if a client requires one (Ollama ignores it).",
   runNote: 'No API key required. Run: ollama serve (starts on 127.0.0.1:11434), then ollama pull <model>. For browser-direct access, set OLLAMA_ORIGINS to allow the page origin; restart Ollama after any env change.',
   docsSlug: 'integrations/ollama',
+  // No 'model': the route pins llama3.2, so a front-end model const would be an
+  // editable value the route throws away. Change the model in the route. 'tools'
+  // IS forwarded, which is what lets an agentic scaffold fill its kai-tool panel.
+  forwardsFromClient: ['tools'],
+  // Ollama's OpenAI-compatible endpoint, and the handler forwards `tools`
+  // verbatim into that body — so the client sends OpenAI's function envelope.
+  clientToolFormat: 'openai',
+  // Nothing. The route is global `fetch` and imports no module; the `ollama`
+  // npm package is not used, and the server itself is installed out of band.
+  deps: { npm: [], pip: [] },
+  // One of the two 'frontend-safe' entries, and it is read off the route rather
+  // than off "it's local, so it's fine": the fetch to localhost:11434 sends
+  // Content-Type and NOTHING else — no Authorization, no key — and envVars is
+  // empty, so there is no secret for a bundle to leak. runNote already documents
+  // the browser-direct path (set OLLAMA_ORIGINS to allow the page origin), which
+  // is the path this value unlocks.
+  keyExposure: 'frontend-safe',
+  // The route fetches http://localhost:11434, so Ollama must ALREADY be running:
+  // `ollama serve`, then `ollama pull <model>` for the model the route pins.
+  // Nothing in package.json installs or starts it — `deps.npm` is empty because
+  // the route is bare `fetch`, which is exactly why this cannot be inferred from
+  // the dependency list. The schema's LOOPBACK_FETCH net catches this one
+  // independently, so a later edit to 'none' fails at the catalog boundary.
+  outOfBand: 'local-server',
 };
 
 export default ollama;

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

@@ -0,0 +1,89 @@
+import type { Integration } from '../types';
+
+const openai: Integration = {
+  id: 'openai',
+  title: 'OpenAI',
+  category: 'provider',
+  language: 'ts',
+  streamFormat: 'openai-sse',
+  envVars: ['OPENAI_API_KEY'],
+  // No per-framework templates: the handler below is web-standard, so the
+  // scaffolder wraps it in whatever the target framework routes with.
+  routeTemplates: {},
+  webRoute: `async function chatHandler(request: Request): Promise<Response> {
+  // Both model and tools come from the browser. \`tools\` is undefined unless the
+  // front end declared any, and 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://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      Authorization: \`Bearer \${process.env.OPENAI_API_KEY}\`,
+      'Content-Type': 'application/json',
+    },
+    // Model ids here carry NO vendor prefix: 'gpt-4o-mini', never
+    // 'openai/gpt-4o-mini' — the prefixed form is an OpenRouter slug and this
+    // host answers it with a 404. The front end's \`model\` const is the one to
+    // edit; it is seeded from CLIENT_MODEL_IDS.openai.
+    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 OpenAI's own message, which is the most useful thing you can be
+  // handed on a first run.
+  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: 'OpenAI returned no body to stream.' } }), {
+      status: 502,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  // OpenAI IS the format readOpenAIStream parses. Pass it straight through.
+  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',
+    },
+  });
+}`,
+  streamMapping:
+    "OpenAI's /v1/chat/completions is the reference OpenAI-format SSE stream — this is the one integration with no re-framing at all. Pipe upstream.body straight to the browser; readOpenAIStream from @kitn.ai/ui/wire parses it, including tool calls (delta.tool_calls) and reasoning (delta.reasoning on the reasoning models). Set stream_options: { include_usage: true } in the body if you want a final usage frame; readOpenAIStream reads prompt_tokens/completion_tokens off it.",
+  runNote:
+    "Set OPENAI_API_KEY (platform.openai.com). Model ids have NO vendor prefix: 'gpt-4o-mini', not 'openai/gpt-4o-mini' — the prefixed form is an OpenRouter slug and api.openai.com answers it with a 404. Change the pinned model in the route.",
+  docsSlug: 'integrations/connect-any-model',
+  // 'model' was withheld until scaffold.ts could seed it correctly: the shared
+  // fallback is 'openai/gpt-4o-mini', an OpenRouter slug that api.openai.com
+  // 404s, and shipping an editable const with a broken default is the exact
+  // dead-const defect forwardsFromClient exists to prevent. CLIENT_MODEL_IDS now
+  // carries a per-integration entry ('gpt-4o-mini'), so the const is real and the
+  // route reads it. 'tools' is what lets an agentic scaffold fill its kai-tool
+  // panel.
+  forwardsFromClient: ['model', 'tools'],
+  // The handler forwards `tools` unconverted to /v1/chat/completions — this IS
+  // the OpenAI wire, so the client sends OpenAI's own function envelope.
+  clientToolFormat: 'openai',
+  // Nothing to install. The route is global `fetch` and imports no module at all.
+  deps: { npm: [], pip: [] },
+  // The route reads OPENAI_API_KEY and puts it in an `Authorization: Bearer`
+  // header. A static bundle carrying that is a published key.
+  keyExposure: 'needs-proxy',
+  // A remote HTTPS endpoint and a key. Nothing to install, nothing to start.
+  outOfBand: 'none',
+};
+
+export default openai;