@kitn.ai/ui 0.27.0 → 0.29.0

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

@@ -1,133 +0,0 @@
-import type { Integration } from '../types';
-
-const langgraph: Integration = {
-  id: 'langgraph',
-  title: 'LangGraph',
-  category: 'framework',
-  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 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';
-
-const getWeather = tool(
-  async ({ city }) => \`It's 18°C and clear in \${city}.\`,
-  {
-    name: 'get_weather',
-    description: 'Get the current weather for a city.',
-    schema: z.object({ city: z.string() }),
-  },
-);
-
-const agent = createReactAgent({
-  llm: new ChatOpenAI({ model: 'gpt-4o' }),
-  tools: [getWeather],
-});
-
-// Stream a compiled LangGraph agent to the browser as OpenAI-format SSE.
-async function chatHandler(request: Request): Promise<Response> {
-  let chatBody: ChatRequestBody;
-  try {
-    chatBody = await readChatRequest(request);
-  } catch (error) {
-    return toChatErrorResponse(error);
-  }
-  const { messages } = chatBody;
-
-  // 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({
-    async start(controller) {
-      const send = (obj: unknown) =>
-        controller.enqueue(encoder.encode(\`data: \${JSON.stringify(obj)}\\n\\n\`));
-
-      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, {
-    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]. 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

@@ -1,182 +0,0 @@
-import type { Integration } from '../types';
-
-const mastra: Integration = {
-  id: 'mastra',
-  title: 'Mastra',
-  category: 'harness',
-  language: 'ts',
-  streamFormat: 'openai-sse',
-  envVars: ['MASTRA_URL'],
-  // 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';
-
-// 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\`.');
-}
-
-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> {
-  let chatBody: ChatRequestBody;
-  try {
-    chatBody = await readChatRequest(request);
-  } catch (error) {
-    return toChatErrorResponse(error);
-  }
-  const { messages } = chatBody;
-
-  // 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,148 +0,0 @@
-import type { Integration } from '../types';
-
-/**
- * mock: the zero-config first-win.
- *
- * 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 (openai, anthropic, openrouter, ollama,
- * …) when ready.
- *
- * THE ROUTE IS OPTIONAL, AND IT EXISTS ANYWAY (rung-2 finding G-04, recurring
- * since rung 1). Two clean-room builders in a row were told "replies come from a
- * local dev endpoint that streams a mocked response" and had to hand-invent the
- * server side, because this was the one integration whose block (2) held prose
- * where every other integration ships code. So `webRoute` below is the mock's
- * server half: the SAME `createMockResponder()` frames, written to the wire by a
- * portable `chatHandler(Request) => Response` that the scaffolder wraps with the
- * identical per-framework adapters a real integration gets (Vite dev middleware
- * for the SPA frameworks, POST exports for next/svelte/tanstack, the
- * Express/Worker/Angular hosts). Nothing about the emitted app REQUIRES it — the
- * front end streams locally and never fetches — which the emitted block states,
- * along with the one-expression swap that points onSubmit at it.
- *
- * `routeTemplates` stays empty: the handler is web-standard, so there is no
- * framework whose declaration it cannot be wrapped in. `category: 'mock'` keeps
- * it out of the real provider/gateway/framework/harness catalogs.
- */
-const mock: Integration = {
-  id: 'mock',
-  title: 'Mock (local preview)',
-  category: 'mock',
-  language: 'ts',
-  streamFormat: 'native',
-  envVars: [],
-  routeTemplates: {},
-  webRoute: `import { createMockResponder } from '@kitn.ai/ui/state';
-
-// The kit's own mock responder — no provider, no key, no upstream. MODULE
-// scope, not per-request: the responder owns the cursor into its canned
-// replies, so rebuilding it per turn would answer with the first one forever.
-const mockResponse = createMockResponder();
-
-async function chatHandler(request: Request): Promise<Response> {
-  // The responder cycles its replies whatever you send, so the prompt is a
-  // courtesy — but the body is still read exactly the way a real route reads
-  // it, so swapping this handler for a provider's changes nothing upstream of
-  // this file.
-  let chatBody: ChatRequestBody;
-  try {
-    chatBody = await readChatRequest(request);
-  } catch (error) {
-    return toChatErrorResponse(error);
-  }
-  const { messages } = chatBody;
-  const last = [...messages].reverse().find((m) => m.role === 'user');
-  const prompt = last && typeof last.content === 'string' ? last.content : '';
-
-  // createMockResponder() yields COMPLETE OpenAI chat-completions SSE frames —
-  // the same strings the front end's local preview streams — so this route only
-  // writes them out verbatim. No framing is built here; the browser parses them
-  // with readOpenAIStream from @kitn.ai/ui/wire, exactly as it would a real
-  // route's response. Every frame is marked as a mock (a ': kai-mock' banner, a
-  // _kai_mock field, model 'kai-mock', zero usage).
-  const encoder = new TextEncoder();
-  let open = true;
-  const body = new ReadableStream<Uint8Array>({
-    async start(controller) {
-      for await (const frame of mockResponse(prompt)) {
-        // The browser hangs up when the user asks a new question mid-answer;
-        // stop producing frames rather than writing into a cancelled stream.
-        if (!open) return;
-        controller.enqueue(encoder.encode(frame));
-      }
-      controller.close();
-    },
-    cancel() {
-      open = false;
-    },
-  });
-
-  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',
-      // A proxy in front of a preview build would otherwise buffer the whole
-      // stream and the reply would land all at once instead of streaming.
-      'X-Accel-Buffering': 'no',
-    },
-  });
-}`,
-  streamMapping:
-    "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. Block (2) serves the same frames over HTTP as an OPTIONAL route, so the /api/chat seam can be stood up before any provider exists.",
-  runNote:
-    '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. Block (2) is the OPTIONAL server half: the same mock frames served over HTTP, for standing up the /api/chat seam before any provider exists.',
-  docsSlug: 'integrations/mock',
-  // Nothing: the front end makes no HTTP request at all, and the optional route
-  // reads only `messages` — and only as a courtesy prompt the responder is free
-  // to ignore. There is no model to pick and no tools array anything would run.
-  forwardsFromClient: [],
-  // Nothing to install: the route's one import is the kit itself, which every
-  // scaffold already depends on (registry.test.ts pins deps.npm to the route's
-  // imports minus @kitn.ai/ui).
-  deps: { npm: [], pip: [] },
-  // The other 'frontend-safe' entry. The route now exists (G-04) but changes
-  // nothing here: it holds no credential, sends no auth header and reaches no
-  // upstream, so there is still nothing a public bundle could give away. The
-  // schema's own refinement re-checks that claim against the route source.
-  keyExposure: 'frontend-safe',
-  // Nothing to supply out of band: no upstream, no process, no runtime. The
-  // route is optional — the emitted app streams locally without it — which is
-  // what keeps mock in the "No backend" group of create-kai's gateway prompt
-  // (listGatewayGroups derives that from frontend-safe + outOfBand 'none', not
-  // from the absence of a route, precisely because this route is one nobody
-  // NEEDS).
-  outOfBand: 'none',
-};
-
-export default mock;

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

@@ -1,97 +0,0 @@
-import type { Integration } from '../types';
-
-const ollama: Integration = {
-  id: 'ollama',
-  title: 'Ollama',
-  category: 'provider',
-  language: 'ts',
-  streamFormat: 'openai-sse',
-  envVars: [],
-  // 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.
-  let chatBody: ChatRequestBody;
-  try {
-    chatBody = await readChatRequest(request);
-  } catch (error) {
-    return toChatErrorResponse(error);
-  }
-  const { messages, tools } = chatBody;
-
-  const upstream = await fetch('http://localhost:11434/v1/chat/completions', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ model: 'llama3.2', messages, tools, stream: true }),
-  });
-
-  // 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' },
-    });
-  }
-
-  // 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',
-    },
-  });
-}`,
-  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

@@ -1,95 +0,0 @@
-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.
-  let chatBody: ChatRequestBody;
-  try {
-    chatBody = await readChatRequest(request);
-  } catch (error) {
-    return toChatErrorResponse(error);
-  }
-  const { model, messages, tools } = chatBody;
-
-  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;