@kitn.ai/ui 0.25.2 → 0.27.0

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,14 +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 { constructTool } from './tools/construct';
 import type { Tool } from './tools/types';
+import { validateToolArgs } from './validate-args';
 
-const tools: Tool[] = [reference, scaffold, theme, debug];
+const tools: Tool[] = [reference, scaffold, theme, debug, constructTool];
+
+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
@@ -24,10 +75,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 +98,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);

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

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+import type { Tool } from './types';
+import { validateConstruct, CONSTRUCT_SCHEMA_URL } from '../../construct/schema';
+
+/**
+ * construct — turn-by-turn authoring of a kitn construct (one JSON file → one
+ * web component). Stateless by design: the HARNESS owns the construct file;
+ * every call carries the full construct for THIS turn — that is what makes
+ * turn 40 safe, there is no server-side draft to corrupt.
+ *
+ * Two entry shapes: `intent` alone returns a STARTER construct plus the
+ * real-choice questions the intent leaves open (menu-honesty: never ask a
+ * question the intent already answers). `construct` (optionally with
+ * `intent`) validates — rejection is a NORMAL, non-error result, not a thrown
+ * error, because an invalid turn does not change the file: the previous good
+ * construct still stands.
+ *
+ * NOTE on the advertised schema: `Tool.inputSchema` is a plain `z.ZodObject`,
+ * and both `server.ts` (`z.toJSONSchema`) and `validate-args.ts`
+ * (`schema.shape`) need that exact shape — a `.superRefine` wrapper is a
+ * `ZodEffects`-like type with no `.shape`, so it can't be `tool.inputSchema`.
+ * The advertised schema therefore stays a plain `.strict()` object; the
+ * "at least one of intent/construct" rule is enforced here in the handler
+ * with the same message the skeleton's superRefine would have produced.
+ */
+
+const inputSchema = z
+  .object({
+    intent: z
+      .string()
+      .min(1)
+      .optional()
+      .describe('What the author wants, in their words. Alone: returns a starter construct.'),
+    construct: z
+      .record(z.string(), z.unknown())
+      .optional()
+      .describe('The FULL construct JSON for this turn. The harness owns the file; send all of it every turn.'),
+  })
+  .strict();
+
+function starterFor(intent: string) {
+  // Derive what the intent already implies; ask only what it leaves open.
+  const impliesWidget = /widget|embed|bubble|corner|launcher/i.test(intent);
+  const name = 'my-chat'; // real-choice: always ask for the tag name (it is theirs)
+  return {
+    construct: {
+      $schema: CONSTRUCT_SCHEMA_URL,
+      name,
+      layout: 'widget',
+      provider: { mode: 'mock' },
+    },
+    stated: impliesWidget ? ['layout: widget (implied by your request)'] : [],
+    questions: [
+      `What should the element tag be? (kebab-case, e.g. "acme-support"; using "${name}" until you say)`,
+      ...(impliesWidget ? [] : ['Layout: widget, fullscreen, aside, split, or custom?']),
+    ],
+  };
+}
+
+export const constructTool: Tool = {
+  name: 'construct',
+  description:
+    'Author a kitn construct (one JSON file → one web component) turn by turn. ' +
+    'Send the full construct each turn; invalid turns come back REJECTED with per-path reasons and the previous good construct stands. ' +
+    `Schema: ${CONSTRUCT_SCHEMA_URL}. Preview with "kai dev <file>".`,
+  inputSchema,
+  handler: async (args) => {
+    const { intent, construct } = args as { intent?: string; construct?: Record<string, unknown> };
+
+    if (!intent && !construct) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: 'construct: pass intent, construct, or both' }],
+      };
+    }
+
+    if (!construct) {
+      const s = starterFor(intent ?? '');
+      return {
+        content: [
+          {
+            type: 'text',
+            text: [
+              'STARTER construct (mock provider — keyless, previews immediately):',
+              '```json',
+              JSON.stringify(s.construct, null, 2),
+              '```',
+              ...s.stated,
+              ...s.questions,
+            ].join('\n'),
+          },
+        ],
+      };
+    }
+
+    const out = validateConstruct(construct);
+    if (!out.ok) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: [
+              'REJECTED — this turn does not change the file; the previous good construct stands.',
+              ...out.problems.map((p) => `  ${p.path || '(root)'}: ${p.message}`),
+            ].join('\n'),
+          },
+        ],
+      };
+    }
+
+    const c = out.construct;
+    return {
+      content: [
+        {
+          type: 'text',
+          text: [
+            `VALID: <${c.name}> (${c.layout}, ${c.provider.mode}).`,
+            '```json',
+            JSON.stringify(c, null, 2),
+            '```',
+            `Preview: kai dev <file>. Compile: kai compile <file>.`,
+            ...(c.provider.mode === 'endpoint'
+              ? ['Backend route: use the scaffold tool — it emits a compiling route for your framework and wire.']
+              : []),
+          ].join('\n'),
+        },
+      ],
+    };
+  },
+};

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

@@ -450,6 +450,123 @@ const RULES: Rule[] = [
       'A malformed definition (not two candidates, missing/duplicate ids) fires `kai-error` ' +
       'instead. The event is non-bubbling — listen on the element, not on `document`.',
   },
+  {
+    // Rule 13 — kai-composer is the bare editor; attachments + send live on kai-prompt-input
+    // Source: src/elements/composer.tsx (element doc), src/elements/prompt-input.tsx,
+    // apps/docs components/composer.mdx (the taxonomy sentence). Rung-6 F-43.
+    id: 'composer-attachments',
+    test: (t) => {
+      // Attachment / send-button / toolbar questions asked ABOUT the composer.
+      if (!/kai-composer|composer\b/i.test(t)) return false;
+      return /attach|paperclip|file.?upload|upload|send.?button|toolbar|staging|staged/i.test(t);
+    },
+    title: '`<kai-composer>` is the bare editor — attachments and the send button live on `<kai-prompt-input>`',
+    cause:
+      '`<kai-composer>` is deliberately the bare editing surface: rich text, entity pills, ' +
+      'triggers, Enter-to-submit — and nothing else. No send button, no toolbar, no attachment ' +
+      'surface; its `kai-submit` detail is `{ doc, text, entities }` with no `attachments` field. ' +
+      'Nothing is missing — the batteries-included wrapper is a different element.',
+    fix:
+      'Reach for `<kai-prompt-input>`, which is built on the composer and adds the send button, ' +
+      'the toolbar, and attachments: a paperclip that stages files as chips, a ' +
+      '`kai-attachments-change` event, and `attachments` on its `kai-submit` detail.\n\n' +
+      '```html\n' +
+      '<kai-prompt-input placeholder="Send a message..."></kai-prompt-input>\n' +
+      '```\n\n' +
+      '```js\n' +
+      "document.querySelector('kai-prompt-input').addEventListener('kai-submit', (e) => {\n" +
+      '  const { value, attachments } = e.detail; // attachments staged via the paperclip\n' +
+      '});\n' +
+      '```\n\n' +
+      'Keep `<kai-composer>` only when you are composing the input row yourself — then the ' +
+      'picker, staging tray and send control are yours to build, and every staged file’s ' +
+      '`url` must be a `data:` URI, never `URL.createObjectURL` (see the attachment-blob-url rule).',
+  },
+  {
+    // Rule 14 — blob: attachment URLs: the wire refuses them; use a data: URI
+    // Source: src/components/attachment-types.ts (AttachmentData.url doc),
+    // src/elements/default-input.tsx (readAsDataUrl), src/wire/files.ts (the refusal),
+    // apps/docs patterns/attachments-flow.mdx. Rung-6 F-44; the defect PR #186 shipped.
+    id: 'attachment-blob-url',
+    test: (t) => {
+      // The literal defect in a snippet, with attachment/file-staging context.
+      if (/createObjectURL/.test(t) && /attachment|type:\s*'file'|filename|kai|@kitn/i.test(t)) return true;
+      // A wire refusal or preview-works-send-fails symptom naming blob: URLs.
+      if (/blob:/.test(t) && /attachment|toOpenAIMessages|toAnthropicMessages|wire|kai|@kitn/i.test(t)) return true;
+      return false;
+    },
+    title: 'Never `URL.createObjectURL` in `AttachmentData.url` — read the file as a `data:` URI',
+    cause:
+      'An object URL resolves only inside the browser tab that minted it, so `url: ' +
+      'URL.createObjectURL(file)` renders a flawless local preview and is meaningless to any ' +
+      'provider. `toOpenAIMessages` / `toAnthropicMessages` REFUSE a `blob:` URL rather than ' +
+      'send an address the model cannot fetch — before they refused it, an attachment-only ' +
+      'turn reached the model as nothing at all. A mock-only app hides the defect ' +
+      '(`createMockResponder` never encodes the thread back); it surfaces the moment you point ' +
+      'at a real provider.',
+    fix:
+      'Read every staged file as a `data:` URI and put THAT in `url` — it previews identically ' +
+      'and is the one form both provider wires actually take:\n\n' +
+      '```js\n' +
+      'const readAsDataUrl = (file) =>\n' +
+      '  new Promise((resolve, reject) => {\n' +
+      '    const reader = new FileReader();\n' +
+      '    reader.onload = () => resolve(String(reader.result));\n' +
+      '    reader.onerror = () => reject(reader.error);\n' +
+      '    reader.readAsDataURL(file);\n' +
+      '  });\n\n' +
+      "const url = await readAsDataUrl(file); // data: URI — never URL.createObjectURL\n" +
+      "return { id, type: 'file', filename: file.name, mediaType: file.type, url };\n" +
+      '```\n\n' +
+      '`<kai-prompt-input>`’s built-in paperclip already does this for you; the conversion ' +
+      'is only yours when you stage files yourself. With `data:` URIs there is also nothing ' +
+      'to revoke — no object-URL lifecycle to manage.',
+  },
+  {
+    // Rule 15 — mock tool calls: MockTurn.toolCalls scripts them; the HOST resolves them
+    // Source: src/state/mock.ts (MockTurn/MockToolCall), src/wire/chunk.ts (ModelTurn.toolCalls),
+    // src/state/stream.ts (upsertTool). Rung-6 F-46/F-47/F-52.
+    id: 'mock-tool-calls',
+    test: (t) => {
+      const toolContext = /tool.?call|toolCalls|input-available/i.test(t);
+      // The mock responder asked about tool calls…
+      if (/createMockResponder|mock responder|MockTurn/i.test(t) && toolContext) return true;
+      // …or a tool part parked in input-available with kai/mock context.
+      if (toolContext && /\bmock\b/i.test(t) && /kai|@kitn|stream|responder/i.test(t)) return true;
+      return false;
+    },
+    title: 'Scripting mock tool calls — `MockTurn.toolCalls`; the HOST resolves the announced call',
+    cause:
+      'Two separate facts. (1) The default mock replies are text-only, so out of the box ' +
+      '`createMockResponder()` never announces a tool call — scripting one takes a `MockTurn` ' +
+      'reply. (2) A tool call — mock or real provider — is only ever ANNOUNCED by the stream: ' +
+      'the part parks at `state: \'input-available\'` and stays there. The kit parses and ' +
+      'renders the call; EXECUTING it and answering is the host’s job.',
+    fix:
+      'Script the call with a `MockTurn` reply (`{ text?, toolCalls? }`); the mock frames it ' +
+      'announce-then-arguments with `finish_reason: \'tool_calls\'`, exactly as a real ' +
+      'OpenAI-wire turn, so it flows through `readOpenAIStream` unchanged:\n\n' +
+      '```js\n' +
+      "import { createMockResponder } from '@kitn.ai/ui/state';\n\n" +
+      'const mock = createMockResponder({\n' +
+      '  replies: [\n' +
+      "    'Plain text turn.',\n" +
+      "    { text: 'Checking…', toolCalls: [{ name: 'get_weather', arguments: { city: 'Oslo' } }] },\n" +
+      '  ],\n' +
+      '});\n' +
+      '```\n\n' +
+      'Then resolve each announced call yourself after the read settles — walk the returned ' +
+      '`ModelTurn.toolCalls` and patch the part to `output-available`:\n\n' +
+      '```js\n' +
+      'const result = await readOpenAIStream(response, stream);\n' +
+      'for (const call of result.toolCalls) {\n' +
+      '  const output = await runTool(call.name, call.input); // your side of the seam\n' +
+      "  stream.upsertTool(call.id, { state: 'output-available', output });\n" +
+      '}\n' +
+      '```\n\n' +
+      'Skip any call with `providerExecuted: true` — the provider already ran it and its ' +
+      'result arrived in-stream.',
+  },
 ];
 
 function buildText(matched: Rule[]): string {
@@ -458,10 +575,15 @@ function buildText(matched: Rule[]): string {
       'No known failure pattern matched. Suggested next steps:\n\n' +
       '1. Use the `component_reference` tool to look up the real API for the element ' +
       '(prop names, event names, attribute vs. property distinction).\n' +
-      '2. Check the **Streaming recipe** in `llms-full.txt` ' +
-      '(`node_modules/@kitn.ai/ui/llms-full.txt` or https://ui.kitn.ai/llms-full.txt) ' +
-      'for correct streaming wiring.\n' +
-      '3. Paste `https://ui.kitn.ai/llms.txt` into your prompt for a compact orientation.'
+      '2. If the problem is in host code rather than an element — streaming, ' +
+      '`createAssistantStream`, `createMockResponder`, the SSE readers, the encoders — ' +
+      'call `component_reference` with `{ name: "programmatic" }` for the full ' +
+      '`@kitn.ai/ui/state` + `@kitn.ai/ui/wire` API, and `{ name: "composed-thread" }` ' +
+      'for a complete hand-composed surface to compare wiring against.\n' +
+      '3. Check the **Streaming recipe** and the **Programmatic layer** sections in ' +
+      '`llms-full.txt` (`node_modules/@kitn.ai/ui/llms-full.txt` or ' +
+      'https://ui.kitn.ai/llms-full.txt) for correct streaming wiring.\n' +
+      '4. Paste `https://ui.kitn.ai/llms.txt` into your prompt for a compact orientation.'
     );
   }