@kitn.ai/ui 0.20.1 → 0.21.0

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

@@ -1,6 +1,16 @@
 import { z } from 'zod';
+import {
+  KAI_TOOL_PREFIX,
+  cardSchemaNames,
+  cardSchemas,
+  cardTools,
+  isCardSchemaName,
+  toolNameForCardType,
+} from '@kitn.ai/ui/schemas';
+import type { CardSchemaName, ToolProvider } from '@kitn.ai/ui/schemas';
 import type { Tool } from './types';
-import { getElement, listElements } from '../manifest';
+import { cardHostTags, cardTagForType, cardTypeForTag, getElement, listElements } from '../manifest';
+import type { CemMember } from '../manifest';
 
 /**
  * component_reference — look up AI/UI (kai-*) web components, their props,
@@ -10,6 +20,10 @@ import { getElement, listElements } from '../manifest';
  * Backed by manifest.ts which resolves the CEM in both the bundled bin
  * (dist/mcp.es.js sibling) and the Vitest source context (walks up to find
  * dist/custom-elements.json in the repo root).
+ *
+ * For a card-backed element it also serves the card's JSON Schema and a tool
+ * definition GENERATED by `cardTools()`. See `renderCardContract` for why not one
+ * byte of that is written here as a literal.
  */
 
 /** Types that warrant the JS-property contract note. */
@@ -19,7 +33,199 @@ function isJsOnlyType(typeText: string | undefined): boolean {
   return typeText ? JS_ONLY_TYPE_PATTERNS.test(typeText) : false;
 }
 
-function formatReference(tag: string): string {
+// ─────────────────────────────────────────────────────────────────────────────
+// The imperative half of the interaction surface
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A CEM member of `kind: 'method'`.
+ *
+ * `CemMember` in manifest.ts types what EVERY member carries. `parameters` and
+ * `return` exist only on methods, and gen-element-api.mjs writes the AUTHORED
+ * parameter list into a single `parameters[0].name` rather than splitting it, so
+ * the signature is rebuilt from those two fields rather than read off one.
+ */
+interface CemMethodMember extends CemMember {
+  kind: 'method';
+  parameters?: { name: string }[];
+  return?: { type?: { text?: string } };
+}
+
+function isPublicMethod(member: CemMember): member is CemMethodMember {
+  return member.kind === 'method' && member.privacy === 'public';
+}
+
+/** `maximize(index: number): void` — the call as a consumer types it. */
+function methodSignature(method: CemMethodMember): string {
+  return `${method.name}(${method.parameters?.[0]?.name ?? ''}): ${method.return?.type?.text ?? 'void'}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The card contract
+// ─────────────────────────────────────────────────────────────────────────────
+
+const PROVIDERS = ['openai', 'anthropic', 'jsonschema'] as const;
+
+/**
+ * What a caller gets when they do not name a provider.
+ *
+ * NOT a coin-flip between the two wire formats, and deliberately not "serve all
+ * three". The three envelopes are not interchangeable in a way a reader can patch
+ * up: OpenAI nests the schema at `function.parameters`, Anthropic puts it flat at
+ * `input_schema`. Handing over one of those unasked means a harness on the other
+ * provider pastes it in and gets a 400 it will blame on the kit.
+ *
+ * `jsonschema` is the only one of the three that is not a wire envelope at all —
+ * `{ name, description, schema }` cannot be mistaken for either provider's shape, so
+ * a caller who reads it as one is corrected by the field names before they ship it.
+ * It is also directly usable, not a booby prize: `tool({ inputSchema: jsonSchema(
+ * def.schema) })` is exactly what the Vercel AI SDK wants, and of the nine
+ * integrations this MCP scaffolds, exactly one (openrouter) posts a raw OpenAI-wire
+ * tools array; the rest go through an SDK or an agent framework that takes the bare
+ * schema.
+ *
+ * Serving all three was the other candidate and it loses on cost for no gain in
+ * safety: measured on this tree, one card's pretty-printed definition runs
+ * 1.7-5.3 KB, so three of them plus the schema turns a single `kai-artifact` lookup
+ * into roughly 20 KB of context. The response names all three modes and the exact
+ * call that produces each, so a caller who does know their provider is one re-ask
+ * away and still never invents an envelope.
+ */
+const DEFAULT_PROVIDER: ToolProvider = 'jsonschema';
+
+function isProvider(value: string): value is ToolProvider {
+  return (PROVIDERS as readonly string[]).includes(value);
+}
+
+/** Stable fence info strings, so a reader (and reference.test.ts) can lift the blocks back out exactly. */
+const TOOL_FENCE = 'kai-tool-definition';
+const SCHEMA_FENCE = 'kai-card-schema';
+
+function fence(info: string, value: unknown): string[] {
+  return ['```json ' + info, JSON.stringify(value, null, 2), '```'];
+}
+
+/**
+ * Render a card type as it would be written in JS source.
+ *
+ * The seven built-ins are all bare identifiers, but a card type is whatever string a
+ * developer put in `CardEnvelope.type` — `pricing-table` is legal and reaches this
+ * code the day an eighth built-in is hyphenated. Emitting `{ pricing-table: … }` as a
+ * copy-paste sample would be a syntax error, so the quoting is decided, not assumed.
+ */
+const BARE_IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+function asKey(cardType: string): string {
+  return BARE_IDENTIFIER.test(cardType) ? cardType : JSON.stringify(cardType);
+}
+
+function asMember(cardType: string): string {
+  return BARE_IDENTIFIER.test(cardType) ? `.${cardType}` : `[${JSON.stringify(cardType)}]`;
+}
+
+/**
+ * The loop, in the four facts a harness cannot infer from a prop table.
+ *
+ * Shared by the card-backed and the card-host sections because they are the same
+ * contract seen from the two ends, and a second copy would be the drift this whole
+ * task exists to remove, one level up from the tool definition.
+ *
+ * `example` is the card the caller actually asked about, so the illustration is about
+ * their card rather than a fixed one they then have to translate.
+ */
+function loopWiring(example: string): string[] {
+  return [
+    '',
+    '#### Wiring the loop',
+    `- **Tool names are \`${KAI_TOOL_PREFIX}<card type>\`.** \`${toolNameForCardType(example)}\` produces \`{ type: "${example}" }\`. ` +
+      'Use `isCardTool(name)` to split card calls from your own tools; never match the prefix by hand.',
+    '- **`tool_call_id` becomes `CardEnvelope.id`, unchanged.** That is what makes a revision UPSERT: ' +
+      'a model that re-sends the same tool call id replaces the card in place instead of rendering a second copy of it. ' +
+      'Generating your own id breaks that silently.',
+    '- **`cardFromToolCall(name, input, { id: call.id })`** turns the call into a renderable envelope, ' +
+      'or returns `null` when it is one of your own tools so the loop falls through to it. It never throws.',
+    '- **Everything above is one import:** `import { cardTools, cardFromToolCall, isCardTool } from \'@kitn.ai/ui/schemas\'`. ' +
+      `The raw documents also ship as JSON (\`@kitn.ai/ui/schemas/${example}.schema.json\`) for a Python or Go backend.`,
+  ];
+}
+
+/** The card-backed section: schema + a GENERATED tool definition. */
+function renderCardContract(tag: string, cardType: CardSchemaName, provider: ToolProvider): string[] {
+  const schema = cardSchemas[cardType];
+
+  // GENERATED, NEVER RESTATED.
+  //
+  // This calls the same `cardTools` a consumer's route calls, on the same schema, so
+  // the definition served here cannot diverge from the one they ship — not when a
+  // schema gains a field, not when the projection changes what it strips. A literal
+  // typed into this file would read identically today and rot on the first schema
+  // change, which is exactly the hand-copy drift this tool exists to remove.
+  // reference.test.ts asserts byte-equality against BOTH `cardTools({ [type]: schema },
+  // …)` and the matching entry of the whole-registry `cardTools({ provider })`, so a
+  // hand-edit here fails a test rather than shipping.
+  const [def] = cardTools({ [cardType]: schema }, { provider });
+
+  const lines: string[] = [
+    '',
+    '### Card contract',
+    `\`<${tag}>\` renders \`CardEnvelope.type: "${cardType}"\`. A model does not emit an envelope; ` +
+      `it calls the tool \`${toolNameForCardType(cardType)}\`, and the kit turns that call back into one.`,
+  ];
+
+  lines.push(
+    '',
+    `#### Tool definition — provider \`${provider}\``,
+    `Generated by \`cardTools({ ${asKey(cardType)}: cardSchemas${asMember(cardType)} }, { provider: '${provider}' })\`. ` +
+      'Copy it; do not retype it, and do not hand-maintain a second copy — regenerate instead.',
+    `Ask again with \`provider\` set to \`openai\`, \`anthropic\` or \`jsonschema\` for the other envelopes. ` +
+      'They are NOT interchangeable: OpenAI nests the schema at `function.parameters`, Anthropic puts it flat at `input_schema`.',
+    ...fence(TOOL_FENCE, def),
+  );
+
+  lines.push(
+    '',
+    '#### Card data JSON Schema',
+    `\`import { cardSchemas } from '@kitn.ai/ui/schemas'\` → \`cardSchemas${asMember(cardType)}\`. ` +
+      `Raw document: \`@kitn.ai/ui/schemas/${cardType}.schema.json\`.`,
+    'This is the authored contract, and it is what `registry.validate()` checks arriving data against. ' +
+      'The tool definition above carries the same document with `$schema`, `$id` and `x-kai-*` stripped — ' +
+      'that projection is `cardTools`\' job, so do not put a raw schema on the wire yourself.',
+    ...fence(SCHEMA_FENCE, schema),
+  );
+
+  lines.push(...loopWiring(cardType));
+  return lines;
+}
+
+/** The card-host section: no schema of its own, but this is where the props live. */
+function renderCardHost(tag: string): string[] {
+  const rows = cardSchemaNames.map((type) => {
+    const cardTag = cardTagForType(type);
+    return `- \`${type}\` → \`<${cardTag ?? '(no element)'}>\`, tool \`${toolNameForCardType(type)}\``;
+  });
+
+  return [
+    '',
+    '### Card contract',
+    `\`<${tag}>\` renders generative-UI cards inside the thread. It is a HOST: it draws whatever ` +
+      'envelopes arrive, and carries the two props that say what a card may be.',
+    '',
+    '- **`cardTypes`** — `Record<envelope type, custom element tag>`. What DRAWS a card. ' +
+      `Merged over the built-ins, so your entry overrides ours and the other ${cardSchemaNames.length - 1} still render.`,
+    '- **`cardSchemas`** — `Record<envelope type, JSON Schema>`. What a VALID card looks like. ' +
+      `This is the prop that carries YOUR OWN card schemas into the browser validator; the ${cardSchemaNames.length} built-ins are already known. ` +
+      'Both are objects, so both are JS properties (`el.cardSchemas = …`), never HTML attributes.',
+    '',
+    'Write both once with `createCardRegistry({ use, custom })` from `@kitn.ai/ui/schemas` and thread it to both ends: ' +
+      '`el.cardTypes = cards.tags` / `el.cardSchemas = cards.validationSchemas` on the client, `cardTools(cards, { provider })` on the route.',
+    '',
+    'Built-in card types (ask `component_reference` for one of these tags to get its schema and tool definition):',
+    ...rows,
+    ...loopWiring(cardSchemaNames[0]),
+  ];
+}
+
+function formatReference(tag: string, provider: ToolProvider): string {
   const el = getElement(tag);
 
   if (!el) {
@@ -50,6 +256,17 @@ function formatReference(tag: string): string {
       'and read `event.detail` for the payload.',
   );
 
+  // ── Card contract ─────────────────────────────────────────────────────────
+  // Attached to the two populations manifest.ts derives, and to nothing else. A
+  // reference that hangs card material off all 80 elements is worse than one that
+  // hangs it off none: it teaches a harness that every element takes a tool call.
+  const cardType = cardTypeForTag(tag);
+  if (cardType !== undefined && isCardSchemaName(cardType)) {
+    lines.push(...renderCardContract(tag, cardType, provider));
+  } else if (cardHostTags().includes(tag)) {
+    lines.push(...renderCardHost(tag));
+  }
+
   // ── Public JS properties ───────────────────────────────────────────────────
   const publicFields = (el.members ?? []).filter(
     (m) => m.kind === 'field' && m.privacy === 'public',
@@ -93,6 +310,25 @@ function formatReference(tag: string): string {
     }
   }
 
+  // ── Methods ───────────────────────────────────────────────────────────────
+  // The input half of the interaction surface. These were in the manifest and in
+  // the shipped types and rendered in NO reference, so the only way to find one
+  // was to read the kit's source.
+  const methods = (el.members ?? []).filter(isPublicMethod);
+  if (methods.length > 0) {
+    lines.push(
+      '',
+      '### Methods (call these on the element instance)',
+      `Get the element (\`const el = document.querySelector('${tag}')\`), then call it. ` +
+        'Methods drive the element from your code; the events above report back what the ' +
+        'user did. Both are public API.',
+    );
+    for (const method of methods) {
+      const desc = method.description?.trim() ?? '';
+      lines.push(`- **${methodSignature(method)}**${desc ? ` — ${desc}` : ''}`);
+    }
+  }
+
   // ── CSS custom properties ─────────────────────────────────────────────────
   const cssProps = el.cssProperties ?? [];
   if (cssProps.length > 0) {
@@ -142,21 +378,64 @@ function formatReference(tag: string): string {
 export const reference: Tool = {
   name: 'component_reference',
   description:
-    'Look up AI/UI (kai-*) web components: their tags, props, events, and usage examples.',
-  inputSchema: z.object({ name: z.string().optional() }),
+    'Look up AI/UI (kai-*) web components: their tags, props, events, imperative methods, and usage examples. ' +
+    'For a card-backed element it also returns the card\'s JSON Schema and a ready-to-send ' +
+    'tool definition generated from it — pass `provider` to get that provider\'s envelope.',
+  inputSchema: z.object({
+    name: z.string().optional(),
+    provider: z
+      .enum(PROVIDERS)
+      .optional()
+      .describe(
+        'Which tool-definition envelope to project for a card-backed element. ' +
+          `Defaults to "${DEFAULT_PROVIDER}", the provider-neutral { name, description, schema } form.`,
+      ),
+  }),
   handler: async (args: Record<string, unknown>) => {
     const name = typeof args.name === 'string' ? args.name.trim() : undefined;
 
+    // Validated HERE, not left to the zod schema above. server.ts advertises
+    // `inputSchema` over the protocol but hands `request.params.arguments` straight
+    // to this handler without parsing it, so an unrecognised provider would reach
+    // `cardTools`, which treats anything that is not "openai"/"anthropic" as the
+    // jsonschema branch. A caller asking for "gemini" would then get a definition in
+    // a shape they did not ask for, with nothing saying so. Refusing is the only
+    // answer that cannot be mistaken for an answer.
+    const rawProvider = args.provider;
+    if (rawProvider !== undefined && (typeof rawProvider !== 'string' || !isProvider(rawProvider))) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text:
+              `Unknown provider: ${JSON.stringify(rawProvider)}\n\n` +
+              `Valid providers are ${PROVIDERS.map((p) => `"${p}"`).join(', ')}. ` +
+              `Omit it to get "${DEFAULT_PROVIDER}", the provider-neutral { name, description, schema } form ` +
+              'that the Vercel AI SDK and most agent frameworks take directly.\n' +
+              'No tool definition was returned, because guessing which envelope you meant would hand you ' +
+              'a shape your provider rejects with nothing saying why.',
+          },
+        ],
+      };
+    }
+    const provider: ToolProvider = rawProvider ?? DEFAULT_PROVIDER;
+
     let text: string;
 
     if (!name || name === 'list') {
       const tags = listElements();
+      const cardRows = cardSchemaNames
+        .map((t) => cardTagForType(t))
+        .filter((t): t is string => t !== undefined);
       text =
         `AI/UI elements (${tags.length} total):\n\n` +
         tags.map((t) => `  ${t}`).join('\n') +
-        '\n\nCall component_reference with a specific name (e.g. { name: "kai-chat" }) for full API details.';
+        '\n\nCall component_reference with a specific name (e.g. { name: "kai-chat" }) for full API details.' +
+        `\n\nCard-backed elements — ask for one of these to get its JSON Schema and a generated ` +
+        `\`${KAI_TOOL_PREFIX}*\` tool definition:\n  ${cardRows.join(', ')}` +
+        `\nThe elements that HOST them (and carry the \`cardTypes\` / \`cardSchemas\` props): ${cardHostTags().join(', ')}`;
     } else {
-      text = formatReference(name);
+      text = formatReference(name, provider);
     }
 
     return { content: [{ type: 'text' as const, text }] };