@kitn.ai/ui 0.25.2 → 0.26.0

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

@@ -35,9 +35,22 @@ import type { Integration } from '../types';
  * 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/
- * harness catalogs.
+ * 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',
@@ -47,26 +60,88 @@ const mock: Integration = {
   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.",
+    "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.',
+    '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: 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.
+  // 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: there is no route to install anything for.
+  // 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, 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.
+  // 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 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.
+  // 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',
 };
 

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

@@ -20,7 +20,13 @@ const ollama: Integration = {
   // 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);
+  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',

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

@@ -14,7 +14,13 @@ const openai: Integration = {
   // 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);
+  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',

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

@@ -14,7 +14,13 @@ const openrouter: Integration = {
   webRoute: `async function chatHandler(request: Request): Promise<Response> {
   // tools is undefined unless the front end sent one; JSON.stringify drops it,
   // so the same handler serves a tool archetype and a plain chat.
-  const { model, messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { model, messages, tools } = chatBody;
 
   const upstream = await fetch('https://openrouter.ai/api/v1/chat/completions', {
     method: 'POST',

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

@@ -20,9 +20,64 @@ import type { OpenAIWireMessage } from '@kitn.ai/ui/wire';
 const app = express();
 app.use(express.json());
 
+class ChatRequestError extends Error {
+  constructor(readonly status: number, message: string) { super(message); }
+}
+
+/** Narrow the JSON body once, at the edge. A bare GET or a missing messages
+ *  array is a ChatRequestError with a status — NEVER an unhandled throw
+ *  (findings F-10). Malformed JSON is rejected upstream by express.json(),
+ *  which the error handler below turns into a JSON 400. */
+function readChatRequest(req: express.Request): { messages: OpenAIWireMessage[] } {
+  if (req.method !== 'POST') {
+    throw new ChatRequestError(405, \`Method \${req.method} not allowed — POST /api/chat.\`);
+  }
+  const body = (req.body ?? {}) as { messages?: OpenAIWireMessage[] };
+  if (!Array.isArray(body.messages)) {
+    throw new ChatRequestError(400, 'Request body must carry a messages array.');
+  }
+  return body as { messages: OpenAIWireMessage[] };
+}
+
+/** Map a guard rejection to the response its status demands; rethrow anything
+ *  else — an unexpected error should be loud, not laundered into a 400. */
+function toChatErrorResponse(error: unknown, res: express.Response): void {
+  if (error instanceof ChatRequestError) {
+    res.status(error.status).json({ error: { message: error.message } });
+    return;
+  }
+  throw error;
+}
+
+// express.json() rejects a malformed body at the MIDDLEWARE level, before any
+// handler runs — without this it surfaces as Express's default HTML error page.
+app.use(
+  (
+    err: { status?: number; message?: string },
+    _req: express.Request,
+    res: express.Response,
+    _next: express.NextFunction,
+  ) => {
+    res.status(err?.status ?? 500).json({ error: { message: err?.message ?? 'Request failed.' } });
+  },
+);
+
+// A bare GET is a 405 with the method named, not Express's default 404 —
+// the resource exists, the verb is wrong.
+app.get('/api/chat', (_req, res) => {
+  res.status(405).json({ error: { message: 'Method not allowed — POST /api/chat.' } });
+});
+
 // POST /api/chat: bridge a Pi RPC session to the browser as SSE.
 app.post('/api/chat', (req, res) => {
-  const { messages } = req.body as { messages: OpenAIWireMessage[] };
+  let chatBody: { messages: OpenAIWireMessage[] };
+  try {
+    chatBody = readChatRequest(req);
+  } catch (error) {
+    toChatErrorResponse(error, res);
+    return;
+  }
+  const { messages } = chatBody;
   const last = messages.at(-1)?.content;
   // \`content\` is a plain string until the turn carries an attachment, at which
   // point it is an ARRAY of content parts. Pi's RPC mode takes a TEXT prompt and

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

@@ -169,7 +169,13 @@ const FINISH_REASONS: Record<string, string> = {
 };
 
 async function chatHandler(request: Request): Promise<Response> {
-  const { messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages, tools } = chatBody;
   const toolSet = toToolSet(tools);
   const prompt = toModelMessages(messages);
 

package/src/agent-tooling/mcp/css-raw.d.ts

@@ -0,0 +1,12 @@
+// `*.css?raw` — Vite inlines the file's TEXT as a string at build time.
+//
+// tools/theme.ts uses it to read the real `--kai-*` token names out of
+// theme.css instead of restating them. The declaration lives here rather than
+// coming from `vite/client` because tsconfig.mcp.json deliberately runs with
+// `types: ["node"]` and no DOM — this is a Node bundle that emits HTML as
+// strings. One narrow module pattern is cheaper than pulling the whole browser
+// client typing into that pass.
+declare module '*.css?raw' {
+  const content: string;
+  export default content;
+}

package/src/agent-tooling/mcp/manifest.ts

@@ -17,7 +17,7 @@
  * `cardTagForType` for the rule and for what happens when an eighth card type lands.
  */
 
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { join, dirname, resolve } from 'node:path';
 // The package's own public entry, by the same specifier the scaffolder tells a
@@ -236,6 +236,105 @@ export function listElements(): string[] {
     .sort();
 }
 
+// ── Per-element entry map ─────────────────────────────────────────────────────
+//
+// A STATIC import, not an fs read off resolveManifestPath's dual-context pattern:
+// element-manifest.json (unlike custom-elements.json) is never copied into dist/,
+// so an fs read relative to this module's own URL would resolve in the vitest/source
+// context and 404 in the bundled dist/mcp.es.js. A static import sidesteps the gap
+// entirely — Rollup inlines the JSON at build time, so the bundled bin carries the
+// data with no runtime file dependency. NAMED import (not the whole module), matching
+// the same tradeoff element-diagnostics.ts already made for this file: a default
+// import would pull `files` in too for 0 benefit here.
+import { tags as ELEMENT_ENTRY_TAGS } from '../../elements/element-manifest.json';
+
+/**
+ * The per-element entry basename for a tag, e.g. 'kai-chat' -> 'chat'.
+ *
+ * Read from element-manifest.json's `tags` map rather than derived by stripping
+ * the `kai-` prefix: TEN of the eighty elements do not match that derivation
+ * (`kai-conversations` -> `conversation-list`), so a derived path would emit a
+ * broken import for them.
+ */
+export function entryForTag(tag: string): string | undefined {
+  return (ELEMENT_ENTRY_TAGS as Record<string, string>)[tag];
+}
+
+/**
+ * The per-element entry basename for a tag the register-all bundle does NOT
+ * carry, e.g. 'kai-remote' -> 'remote'. `undefined` for every tag `entryForTag`
+ * already answers, and for a tag no built module registers.
+ *
+ * WHY THIS EXISTS. `entryForTag` reads element-manifest.json, which is generated
+ * from the import list in register-impl.ts — so an opt-in element is absent from
+ * it by construction, and the reference had nothing to name. It said "find the
+ * entry point in the package's published exports", which is the one place in the
+ * reference where "how to make this element exist" does not answer itself.
+ *
+ * WHY IT IS READ AND NOT DERIVED. Stripping `kai-` is wrong for ten of the eighty
+ * elements, so guessing here risks exactly the broken import this tool exists to
+ * catch. The fact is stated in vite.config.elements.ts, which adds an explicit
+ * entry for each opt-in element precisely "so `@kitn.ai/ui/elements/remote`
+ * resolves to a real dist file" — but a vite config is not shipped in the
+ * package, so the runtime reads that intent where it LANDS: dist/elements/. A
+ * candidate is a built module that element-manifest.json does not already claim
+ * (plus the two non-element entries the same build emits), and it is matched to a
+ * tag by the tag literal it registers. So the answer is the built artifact's,
+ * confirmed against the tag rather than assumed from a filename.
+ *
+ * dist/elements/ is a sibling of the manifest in both contexts — the bundled bin
+ * (dist/mcp.es.js) and vitest-over-source, which resolveManifestPath already
+ * normalises — so this needs no second resolution strategy. A missing or
+ * unreadable directory yields `undefined` rather than throwing: the caller's
+ * fallback is the honest "this is opt-in" paragraph it already prints.
+ */
+export function optInEntryForTag(tag: string): string | undefined {
+  if (entryForTag(tag)) return undefined;
+  return optInEntries().get(tag);
+}
+
+/** Not element entries: the register-all barrel and the DOM autoloader, both
+ *  emitted into dist/elements/ by the same per-element build. */
+const NON_ELEMENT_ENTRIES = new Set(['index', 'autoloader']);
+
+let _optInEntries: Map<string, string> | undefined;
+
+function optInEntries(): Map<string, string> {
+  if (_optInEntries) return _optInEntries;
+  _optInEntries = new Map();
+
+  const dir = join(dirname(resolveManifestPath()), 'elements');
+  let candidates: string[];
+  try {
+    const registered = new Set(Object.values(ELEMENT_ENTRY_TAGS as Record<string, string>));
+    candidates = readdirSync(dir)
+      .filter((f) => f.endsWith('.js'))
+      .map((f) => f.slice(0, -'.js'.length))
+      .filter((base) => !registered.has(base) && !NON_ELEMENT_ENTRIES.has(base));
+  } catch {
+    return _optInEntries;
+  }
+
+  // Only the tags element-manifest.json does not already answer for. Narrow on
+  // purpose: an element module may mention a tag it merely renders, and matching
+  // against the whole tag list would let that be read as a registration.
+  const unclaimed = listElements().filter((t) => !entryForTag(t));
+
+  for (const base of candidates) {
+    let code: string;
+    try {
+      code = readFileSync(join(dir, `${base}.js`), 'utf-8');
+    } catch {
+      continue;
+    }
+    for (const tag of unclaimed) {
+      if (!_optInEntries.has(tag) && code.includes(`"${tag}"`)) _optInEntries.set(tag, base);
+    }
+  }
+
+  return _optInEntries;
+}
+
 // ── Which elements have anything to do with cards ────────────────────────────
 //
 // Two different populations, and conflating them would be the "attaches card

package/src/agent-tooling/mcp/server.ts

@@ -3,15 +3,65 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
+import { createRequire } from 'node:module';
 import { z } from 'zod';
 import { reference } from './tools/reference';
 import { scaffold } from './tools/scaffold';
 import { theme } from './tools/theme';
 import { debug } from './tools/debug';
 import type { Tool } from './tools/types';
+import { validateToolArgs } from './validate-args';
 
 const tools: Tool[] = [reference, scaffold, theme, debug];
 
+const PACKAGE_NAME = '@kitn.ai/ui';
+
+/**
+ * The `serverInfo` every MCP harness reads back on `initialize`. READ, NOT TYPED.
+ *
+ * This was a hand-typed `{ name: '@kitn.ai/ui', version: '0.15.0' }` and the kit kept
+ * releasing past it, so every harness that connected was told a version ten minors
+ * stale — the same "derive it, don't type it" failure as the CDN pins, minus their
+ * lint. Nothing here is allowed to restate the version: `server.test.ts` reads
+ * package.json off disk itself and compares.
+ *
+ * RESOLVED BY THE PACKAGE'S OWN NAME, not by path arithmetic. This module runs from
+ * two places — `<package>/src/agent-tooling/mcp/server.ts` under vitest, and inlined
+ * into `<package>/dist/mcp.es.js` for the bin — which sit at different depths, so a
+ * relative hop would need one rule per context (what manifest.ts has to do, because
+ * `dist/custom-elements.json` is a build artifact with no name to ask for). A
+ * self-reference has no depth to get wrong: Node resolves `@kitn.ai/ui/package.json`
+ * against the nearest package.json whose `name` matches, which is this package in
+ * both contexts and in an install. It also never escapes into a neighbouring
+ * checkout the way a parent-directory search can.
+ *
+ * WHY IT SURVIVES PUBLISHING. npm always ships package.json, `exports` carries
+ * `"./package.json": "./package.json"` (self-reference is restricted to the exports
+ * map, so that key is load-bearing — drop it and this throws, and the test goes red
+ * with it), and `bin/mcp.js` imports `../dist/mcp.es.js` by its own URL, so the
+ * resolver starts inside the installed package however it was launched (npx, global
+ * install, symlink). Not a JSON import: that inlines the version at BUILD time, which
+ * is a second copy that can disagree with the package.json shipped beside it, and it
+ * would need `resolveJsonModule` on the repo's browser tsc pass as well as this one.
+ *
+ * A broken resolve throws instead of falling back to a placeholder — `bin/mcp.js`
+ * turns that into a named fatal on stderr, which is the loud version. A wrong version
+ * silently announced to every harness is the quiet one.
+ */
+function packageIdentity(): { name: string; version: string } {
+  const specifier = `${PACKAGE_NAME}/package.json`;
+  const require = createRequire(import.meta.url);
+  const pkg = require(specifier) as { name?: string; version?: string };
+  if (pkg.name !== PACKAGE_NAME || typeof pkg.version !== 'string') {
+    throw new Error(
+      `[${PACKAGE_NAME}] Refusing to report a serverInfo that is not this package's: ` +
+        `${specifier} resolved to ${require.resolve(specifier)}, whose name is ` +
+        `${JSON.stringify(pkg.name)} and version ${JSON.stringify(pkg.version)}.`,
+    );
+  }
+  return { name: pkg.name, version: pkg.version };
+}
+
 /**
  * The AI/UI MCP server. A stdio server (see ./stdio.ts) exposing the AI/UI tools
  * to any MCP harness. Registers four tools; Tasks 2–5 fill in each handler.
@@ -24,10 +74,7 @@ export interface AiUiServer extends Server {
 }
 
 export function createServer(): AiUiServer {
-  const server = new Server(
-    { name: '@kitn.ai/ui', version: '0.15.0' },
-    { capabilities: { tools: {} } },
-  ) as AiUiServer;
+  const server = new Server(packageIdentity(), { capabilities: { tools: {} } }) as AiUiServer;
 
   const byName = new Map(tools.map((t) => [t.name, t]));
 
@@ -50,7 +97,16 @@ export function createServer(): AiUiServer {
         content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }],
       };
     }
-    return tool.handler(request.params.arguments ?? {});
+    const args = request.params.arguments ?? {};
+    // Enforce the schema each tool ADVERTISES (additionalProperties: false +
+    // required) — one path for all four tools. Without this, a wrong key was
+    // silently ignored and the handler answered a different question (see
+    // validate-args.ts for the observed failure).
+    const problem = validateToolArgs(tool.name, tool.inputSchema, args);
+    if (problem) {
+      return { isError: true, content: [{ type: 'text', text: problem }] };
+    }
+    return tool.handler(args);
   });
 
   server.__listToolsForTest = () => tools.map((t) => t.name);