@kitn.ai/ui 0.20.0 → 0.21.0

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

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

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

@@ -43,10 +43,32 @@ async def chat(req: ChatRequest):
     return StreamingResponse(openai_sse(req.messages), media_type='text/event-stream')`,
   },
   streamMapping:
-    "Pydantic AI's agent.run_stream() yields text deltas via result.stream_text(delta=True). Each delta is re-framed as a data: {choices:[{delta:{content}}]} SSE line and the stream closes with data: [DONE]. The kai-chat reader is unchanged — it sees standard OpenAI-format SSE.",
+    "Pydantic AI's agent.run_stream() yields text deltas via result.stream_text(delta=True). Each delta is re-framed as a data: {choices:[{delta:{content}}]} SSE line and the stream closes with data: [DONE]. readOpenAIStream from @kitn.ai/ui/wire parses tool calls and reasoning too, but stream_text() yields text only: iterate the run's events instead and re-frame its tool-call events onto delta.tool_calls to fill kai-tool.",
+  // No install list here: `deps` below is the one, and the scaffolder emits it.
+  // This sentence used to open "Install: pip install pydantic-ai fastapi
+  // uvicorn." — three of the four packages, missing the `pydantic` its own route
+  // imports on the next line.
   runNote:
-    'Install: pip install pydantic-ai fastapi uvicorn. Set OPENAI_API_KEY. Run: uvicorn main:app --reload (default port 8000). Point kai-chat at http://localhost:8000/api/chat.',
+    'Set OPENAI_API_KEY. Run: uvicorn main:app --reload (default port 8000). Point kai-chat at http://localhost:8000/api/chat.',
   docsSlug: 'integrations/pydantic-ai',
+  // Nothing. Agent('openai:gpt-4o') pins the model and the agent registers its
+  // own tools, both server-side.
+  forwardsFromClient: [],
+  // The only python integration, so the only non-empty `pip`. Three of the four
+  // are the route's own imports (`pydantic_ai` is imported under its module
+  // name and installed under its hyphenated one); `uvicorn` is the ASGI server
+  // the run note starts, which nothing imports and without which the app cannot
+  // run. That asymmetry is why the pip guard checks imports ⊆ declared and not
+  // the reverse.
+  deps: { npm: [], pip: ['pydantic-ai', 'fastapi', 'pydantic', 'uvicorn'] },
+  // Agent('openai:gpt-4o') reads OPENAI_API_KEY inside the python process.
+  //
+  // Worth being precise about, because this one looks like an exception: the
+  // FastAPI app sets CORS to allow_origins=['*'] and the browser fetches it
+  // DIRECTLY on :8000, with no JS proxy in front. That still is not
+  // 'frontend-safe' — the flag asks where the SECRET lives, and it lives in the
+  // python process. The FastAPI service IS the server hop.
+  keyExposure: 'needs-proxy',
 };
 
 export default pydanticAi;

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

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

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

@@ -2,16 +2,48 @@
  * manifest.ts — reads dist/custom-elements.json (a Custom Elements Manifest)
  * and exposes helpers for the component_reference tool.
  *
- * Resolution strategy (dual-context):
+ * Resolution strategy (dual-context) — each context is an EXACT location, never a
+ * search. See `resolveManifestPath` for why that distinction is the whole point:
  *  1. Bundled bin: dist/mcp.es.js lives in dist/, so custom-elements.json is
- *     a sibling → try ./custom-elements.json relative to import.meta.url.
- *  2. Vitest (source): manifest.ts lives in src/agent-tooling/mcp/, so we walk
- *     up parent directories looking for <dir>/dist/custom-elements.json.
+ *     a sibling → ./custom-elements.json relative to import.meta.url.
+ *  2. Vitest (source): manifest.ts lives at <package>/src/agent-tooling/mcp/, so
+ *     the manifest is <package>/dist/custom-elements.json and nowhere else.
+ *
+ * It also answers "which of these 80 elements has anything to do with cards", for
+ * the card contract component_reference serves. That question lives HERE rather than
+ * in reference.ts because half of it is a question about the element manifest — the
+ * kit's own `type -> tag` map, crossed against the tag list this module already owns
+ * — and because both halves of the answer must come off one place. See
+ * `cardTagForType` for the rule and for what happens when an eighth card type lands.
  */
 
 import { readFileSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { join, dirname } from 'node:path';
+import { join, dirname, resolve } from 'node:path';
+// The package's own public entry, by the same specifier the scaffolder tells a
+// consumer's route to use. That is now a CHOICE, and this comment used to say the
+// opposite: the barrel re-exports src/schemas/registry.ts, which type-IMPORTED
+// `CardComponentMap` from src/primitives/card-registry.TSX, and pulling a .tsx into
+// this pass would mean giving tsconfig.mcp.json `jsx` + `jsxImportSource` + the DOM
+// lib, dragging the whole Solid component tree into a Node-only project — measured
+// as 0 errors -> 1364. Those two types moved to the DOM-free
+// src/primitives/card-component-types.ts, so a relative import of the barrel would
+// typecheck here today. It stays on the public specifier anyway, because emitting
+// and consuming the same string is the point of this module. The built entry
+// resolves to dist/schemas/index.d.ts, whose own reference to card-registry is a
+// .d.ts that skipLibCheck skips, so the Node/no-DOM guarantee survives intact.
+//
+// `BUILTIN_CARD_TAGS` is the authoritative `CardEnvelope.type -> kai-* tag` map and
+// arrives here as DATA, not a type. It is authored in src/primitives/card-tags.ts,
+// which holds that map ALONE — no Solid below it — so it is readable from source by a
+// Node/no-DOM project rather than only through this built entry. Before that split it
+// shared a module with `BUILTIN_CARD_COMPONENTS` and this module re-derived it by
+// convention instead; see `cardTagForType`.
+//
+// This costs a build before typecheck and before the unit suite. That is not a new
+// dependency: resolveManifestPath() below already requires dist/custom-elements.json,
+// and CI already runs `nx build ui` ahead of both.
+import { BUILTIN_CARD_TAGS, cardSchemaNames } from '@kitn.ai/ui/schemas';
 
 // ── CEM types ────────────────────────────────────────────────────────────────
 
@@ -81,32 +113,95 @@ interface CustomElementsManifest {
 }
 
 // ── Manifest resolution ───────────────────────────────────────────────────────
+//
+// THE MANIFEST IS THIS PACKAGE'S OWN BUILD ARTIFACT, SO IT IS ADDRESSED, NOT SEARCHED
+// FOR. This used to walk up ten parent directories taking the first
+// `<dir>/dist/custom-elements.json` it found, and that is a categorically weaker
+// thing than it looks: "a custom-elements.json exists somewhere above me" and "THIS
+// package's custom-elements.json exists" are different facts, and a walk-up cannot
+// tell them apart. It reports success for both.
+//
+// It was not hypothetical. Measured from an agent git worktree at
+// `<repo>/.claude/worktrees/<agent>/packages/ui/src/agent-tooling/mcp`, the loop
+// climbed past the worktree's own (unbuilt) `packages/ui/dist`, out of the worktree
+// entirely, and bound on iteration 8 to `<repo>/dist/custom-elements.json` — a
+// leftover from the pre-monorepo layout, six weeks stale, 78 tags, and zero elements
+// declaring `cardSchemas`. The consequence is this repo's dominant failure mode in
+// its purest form: on an unbuilt tree the MCP manifest tests did not error, they
+// PASSED, 16 of 17, against an artifact from a tree nobody was working in. Two
+// checkouts could disagree about what they had tested and nothing said so.
+//
+// So the rule here is now: a missing manifest is a HARD FAILURE that names the path
+// it expected. Never a fallback, never a wider search. If this throws, the answer is
+// to build — not to let it find someone else's build.
+
+const PACKAGE_NAME = '@kitn.ai/ui';
+const MANIFEST_FILE = 'custom-elements.json';
+
+/**
+ * `<package>/src/agent-tooling/mcp` -> `<package>`. A fixed, exact hop, and it is
+ * CHECKED below rather than trusted: if this module is ever moved to a different
+ * depth the derived root stops being this package and resolution throws, instead of
+ * silently addressing whatever directory happens to sit three levels up.
+ */
+const SOURCE_TO_PACKAGE_ROOT = ['..', '..', '..'] as const;
+
+/** Is `root` the root of THIS package — not merely *a* directory holding a dist/? */
+function isThisPackage(root: string): boolean {
+  const manifest = join(root, 'package.json');
+  if (!existsSync(manifest)) return false;
+  try {
+    return (JSON.parse(readFileSync(manifest, 'utf-8')) as { name?: string }).name === PACKAGE_NAME;
+  } catch {
+    return false;
+  }
+}
 
-function resolveManifestPath(): string {
-  const thisFile = fileURLToPath(import.meta.url);
-  const thisDir = dirname(thisFile);
+/**
+ * Absolute path to this package's Custom Elements Manifest, or a throw naming what
+ * it looked for.
+ *
+ * `fromDir` exists for the tests and defaults to this module's own directory. It is
+ * the only way to write the check that matters: the guarantee is not "a manifest was
+ * found", it is "THIS package's manifest was found", and the two only come apart
+ * when there is a decoy above the origin. manifest.test.ts builds exactly that tree.
+ */
+export function resolveManifestPath(
+  fromDir: string = dirname(fileURLToPath(import.meta.url)),
+): string {
+  // 1. Bundled bin: dist/mcp.es.js and dist/custom-elements.json are siblings.
+  //    Unambiguous by construction — a sibling cannot be another checkout's artifact.
+  const sibling = join(fromDir, MANIFEST_FILE);
+  if (existsSync(sibling)) return sibling;
+
+  // 2. Source (vitest, tsx): one exact location, derived and then verified.
+  const packageRoot = resolve(fromDir, ...SOURCE_TO_PACKAGE_ROOT);
+  const expected = join(packageRoot, 'dist', MANIFEST_FILE);
 
-  // 1. Bundled bin: sibling in the same directory
-  const sibling = join(thisDir, 'custom-elements.json');
-  if (existsSync(sibling)) {
-    return sibling;
+  if (!isThisPackage(packageRoot)) {
+    throw new Error(
+      `[${PACKAGE_NAME}] Cannot locate the Custom Elements Manifest: ${packageRoot} is not ` +
+        `the ${PACKAGE_NAME} package root, so ${expected} would not be this package's ` +
+        `manifest even if it existed.\n` +
+        `Resolved from: ${fromDir}\n` +
+        `This module must live at <package>/src/agent-tooling/mcp/ (or be bundled beside ` +
+        `${MANIFEST_FILE} in dist/). Resolution deliberately does NOT search parent ` +
+        `directories — finding some other checkout's manifest is worse than failing.`,
+    );
   }
 
-  // 2. Source/Vitest: walk up parent directories looking for dist/custom-elements.json
-  let dir = thisDir;
-  for (let i = 0; i < 10; i++) {
-    const candidate = join(dir, 'dist', 'custom-elements.json');
-    if (existsSync(candidate)) {
-      return candidate;
-    }
-    const parent = dirname(dir);
-    if (parent === dir) break; // reached filesystem root
-    dir = parent;
+  if (!existsSync(expected)) {
+    throw new Error(
+      `[${PACKAGE_NAME}] Missing build artifact: ${expected}\n` +
+        `Resolved from: ${fromDir}\n` +
+        `The Custom Elements Manifest is generated by the build. Run \`nx build ui\` ` +
+        `(or \`npm run build:api\` in packages/ui) and try again.\n` +
+        `Resolution deliberately does NOT search parent directories: binding to a ` +
+        `neighbouring checkout's manifest would make this succeed against stale data.`,
+    );
   }
 
-  throw new Error(
-    `Could not find custom-elements.json. Searched from: ${thisDir}`,
-  );
+  return expected;
 }
 
 // ── Parsed manifest (module-level cache) ─────────────────────────────────────
@@ -140,3 +235,89 @@ export function listElements(): string[] {
     .map((d) => d.tagName!)
     .sort();
 }
+
+// ── Which elements have anything to do with cards ────────────────────────────
+//
+// Two different populations, and conflating them would be the "attaches card
+// material to everything" failure:
+//
+//   CARD-BACKED   kai-confirm, kai-choice, …  — one element per CardEnvelope.type.
+//                 These get a schema and a generated tool definition.
+//   CARD HOST     kai-chat, kai-message, …    — the elements that RENDER a thread of
+//                 cards and therefore carry the `cardTypes` / `cardSchemas` props.
+//                 These get the wiring note, not a schema.
+//
+// Neither list is written down here. The host list is derived from the manifest; the
+// card-backed one is the kit's own map, read rather than guessed at. Either way an
+// eighth card type is covered the day it lands rather than the day someone remembers
+// this file.
+
+/** Cached derivations. Same lifetime as the parsed manifest above. */
+let _cardTags: Map<string, string> | undefined;
+let _cardHosts: string[] | undefined;
+
+/**
+ * `CardEnvelope.type` -> the `kai-*` element that renders it.
+ *
+ * THE MAP IS IMPORTED, NOT INFERRED. `BUILTIN_CARD_TAGS` is the same object
+ * `<kai-cards>` dispatches on in the browser, reached here through
+ * `@kitn.ai/ui/schemas`. This function used to RE-DERIVE it by convention — the tag
+ * is `kai-<t>` when that element exists, else the single element whose tag starts
+ * `kai-<t>-` — which was correct against all 80 tags on this tree, `link` ->
+ * `kai-link-preview` included, and was still a second copy of a fact the repo already
+ * held. The eighth card type is the one that would have broken it: any type whose tag
+ * is neither `kai-<t>` nor the sole `kai-<t>-*` had to be noticed by a human, and a
+ * future `kai-form-field` would have made `form` ambiguous on its own. A lookup has
+ * neither failure mode.
+ *
+ * WHY IT IS STILL CROSSED AGAINST THE MANIFEST. The map is authoritative for the
+ * ASSOCIATION; only the manifest knows what actually got registered. A tag in the map
+ * with no element behind it (a rename that missed this file) would otherwise have
+ * `component_reference` send a harness to an element that does not exist. Entries with
+ * no registered element are dropped, so the answer is a real tag or nothing.
+ *
+ * WHEN IT BREAKS, IT BREAKS LOUDLY. reference.test.ts asserts every member of
+ * `cardSchemaNames` resolves AND that what it resolves to is in `listElements()`, so a
+ * card type missing from the map, or pointed at a tag nobody registered, fails a test
+ * instead of silently losing its schema in the reference.
+ */
+export function cardTagForType(type: string): string | undefined {
+  if (!_cardTags) {
+    const present = new Set(listElements());
+    _cardTags = new Map(Object.entries(BUILTIN_CARD_TAGS).filter(([, tag]) => present.has(tag)));
+  }
+  return _cardTags.get(type);
+}
+
+/** The inverse: which card type does this element render, if any. */
+export function cardTypeForTag(tag: string): string | undefined {
+  for (const name of cardSchemaNames) {
+    if (cardTagForType(name) === tag) return name;
+  }
+  return undefined;
+}
+
+/**
+ * The elements that host a thread of cards, derived from the manifest: an element is
+ * a card host exactly when it declares the `cardSchemas` prop.
+ *
+ * That prop is the one that carries a developer's own card schemas into the browser
+ * validator, so "declares it" and "hosts cards" are the same fact rather than two
+ * facts that can disagree. Today it selects kai-chat / kai-message / kai-thread /
+ * kai-workspace; an element that grows the prop tomorrow joins without an edit here.
+ */
+export function cardHostTags(): string[] {
+  if (!_cardHosts) {
+    _cardHosts = getDeclarations()
+      .filter(
+        (d) =>
+          d.tagName !== undefined &&
+          (d.members ?? []).some(
+            (m) => m.kind === 'field' && m.privacy === 'public' && m.name === 'cardSchemas',
+          ),
+      )
+      .map((d) => d.tagName!)
+      .sort();
+  }
+  return _cardHosts;
+}

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

@@ -39,7 +39,7 @@ const RULES: Rule[] = [
       '```js\n' +
       "// ✅ Works — set messages in JavaScript as a property\n" +
       "const chat = document.querySelector('kai-chat');\n" +
-      "chat.messages = [{ id: '1', role: 'assistant', content: 'Hello!' }];\n" +
+      "chat.messages = [{ id: '1', role: 'assistant', parts: [{ type: 'text', text: 'Hello!' }] }];\n" +
       '```\n\n' +
       '```html\n' +
       '<!-- ❌ Fails — messages cannot be an HTML attribute -->\n' +
@@ -55,7 +55,7 @@ const RULES: Rule[] = [
     title: 'In-place mutation does not trigger a re-render',
     cause:
       'Mutating an existing message object or array in place (e.g. `chat.messages.push(…)` ' +
-      'or `chat.messages[i].content = …`) does not trigger a re-render. ' +
+      'or `chat.messages[i].parts = […]`) does not trigger a re-render. ' +
       'The element only reacts when it detects a new array/object reference.',
     fix:
       'Assign a NEW array (and a new object) on every change — never mutate in place.\n\n' +
@@ -63,17 +63,23 @@ const RULES: Rule[] = [
       '// ✅ Triggers re-render — new array + new object reference\n' +
       'chat.messages = [\n' +
       '  ...chat.messages,\n' +
-      "  { id: crypto.randomUUID(), role: 'user', content: userText },\n" +
+      "  { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: userText }] },\n" +
       '];\n\n' +
-      '// ✅ During streaming — replace with a new array + new object on every chunk\n' +
+      '// ✅ During streaming: new array + new object per chunk, and FOLD the delta\n' +
+      "//    onto the trailing text part so reasoning/tool/card parts survive.\n" +
+      "import { appendTextPart } from '@kitn.ai/ui/state';\n" +
       'chat.messages = chat.messages.map((m) =>\n' +
-      '  m.id === assistantId ? { ...m, content: accumulated } : m\n' +
+      '  m.id === assistantId ? { ...m, parts: appendTextPart(m.parts, delta) } : m\n' +
       ');\n\n' +
       '// ❌ Does NOT trigger re-render\n' +
       'chat.messages.push(newMsg);\n' +
-      'chat.messages[i].content = accumulated;\n' +
+      'chat.messages[i].parts = appendTextPart(chat.messages[i].parts, delta);\n\n' +
+      '// ❌ Re-renders, but DROPS the reasoning/tool/card parts already on the message\n' +
+      'chat.messages = chat.messages.map((m) =>\n' +
+      "  m.id === assistantId ? { ...m, parts: [{ type: 'text', text: accumulated }] } : m\n" +
+      ');\n' +
       '```\n\n' +
-      'The ergonomic path: helpers in `@kitn.ai/ui/state` (`appendMessage`, `updateMessage`, `appendContent`) ' +
+      'The ergonomic path: helpers in `@kitn.ai/ui/state` (`appendMessage`, `updateMessage`, `appendText`) ' +
       'and `createAssistantStream` handle the new-reference contract for you. ' +
       '`useKaiChat` (React) and `createKaiChat` (Solid) own state entirely so mutation is never an option.\n\n' +
       '// setMessages((m) => appendMessage(m, msg)) // new array, no footgun',