@appinternalleads/ui 0.2.0

package/tools/ask/mcp.mjs

@@ -0,0 +1,581 @@
+#!/usr/bin/env node
+/**
+ * **`comppack-ask` — an MCP server whose whole job is to put a real control in front of a person.**
+ *
+ * `docs/RFC-MCP.md` §0 found that MCP's own ask-the-user primitive is *deliberately* too weak to
+ * express this library: elicitation's `requestedSchema` is a flat object of primitives, so 7 of
+ * 17 field types survive and **none of the 20 widgets do**. §1 found that the sanctioned place
+ * for real UI — MCP Apps, `ui://`, a sandboxed iframe — is HTML-only and is not rendered by a
+ * terminal client at all.
+ *
+ * So this server does not try to describe the ask to the client. It **renders it itself**, on a
+ * loopback port, in the browser the person already has, and returns the `answer/1` envelope as
+ * `structuredContent`. The client never has to draw anything, which is exactly why it works in a
+ * client that cannot.
+ *
+ * ⚠ **Deliberately no SDK.** The library takes five peers and no more; a server that lives in
+ * `tools/` must not be the reason a sixth arrives. This is stdio JSON-RPC, which is all a stdio
+ * server is.
+ */
+import { createInterface } from 'node:readline';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { askInBrowser } from './serve.mjs';
+/* The blocking policy lives in its own file so a test can check every rule name against the
+   linter's output — a typo here fails silently and makes a rule advisory. */
+import { asLine, split } from './policy.mjs';
+import { speak } from '../speak.mjs';
+
+const PROTOCOL = '2025-06-18';
+
+/**
+ * **The GENERATION profile, not the validator** — `spec/question.generate.json`.
+ *
+ * `spec/question.schema.json` says what is valid and cannot be a tool's `inputSchema`: it is
+ * 22,977 bytes with 26 `if`, ten `#/$defs/` self-references and every numeric bound, and
+ * `RFC-MCP.md` §3 records constrained decoding rejecting exactly those. The profile is flat, has
+ * none of them, and carries the derivation rule in its `description` fields — which is the only
+ * place a model actually reads it. `tests/generate-profile.test.ts` holds the two together.
+ *
+ * Resolved from this file rather than the working directory, so a client may launch the server
+ * from anywhere.
+ */
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG = resolve(HERE, '../..');
+const QUESTION_SCHEMA = JSON.parse(
+  readFileSync(resolve(PKG, 'spec/question.generate.json'), 'utf8'),
+);
+/* `$schema` and `$id` describe the document, not the object it describes. A tool schema has no
+   use for either, and each is one more keyword to be rejected over. */
+delete QUESTION_SCHEMA.$schema;
+delete QUESTION_SCHEMA.$id;
+
+/* ── the wire ─────────────────────────────────────────────────────────────── */
+
+const send = msg => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...msg }) + '\n');
+const ok = (id, result) => send({ id, result });
+const fail = (id, code, message) => send({ id, error: { code, message } });
+
+/**
+ * A tool that *failed* is not a protocol error — `isError` on a successful result is what the
+ * model reads and corrects against. A protocol error, by contrast, is invisible to it.
+ */
+const toolError = (id, text) =>
+  ok(id, { content: [{ type: 'text', text }], isError: true });
+
+/**
+ * **Both halves are precompiled, and both are loaded lazily.**
+ *
+ * `ajv` is a devDependency and `lintQuestion` is TypeScript, so neither can be reached from a
+ * shipped `.mjs`; `ask:build` emits a standalone validator and a bundled linter beside the page.
+ * Lazily because a server that cannot validate should still be able to ask — the failure belongs
+ * in the one tool that needs it, not in `initialize`.
+ */
+let bridge;
+/** Lazily, like the checker — a server that cannot bridge should still be able to ask. */
+async function bridgeFor() {
+  if (bridge !== undefined) return bridge;
+  try {
+    bridge = await import('./dist/elicit.mjs');
+  } catch (e) {
+    bridge = { error: e instanceof Error ? e.message : String(e) };
+  }
+  return bridge;
+}
+
+let checker;
+async function checkerFor() {
+  if (checker !== undefined) return checker;
+  try {
+    const [schema, lint] = await Promise.all([
+      import('./dist/validate-schema.mjs'),
+      import('./dist/lint.mjs'),
+    ]);
+    checker = { validate: schema.default ?? schema.validate, lintQuestion: lint.lintQuestion };
+  } catch (e) {
+    checker = { error: e instanceof Error ? e.message : String(e) };
+  }
+  return checker;
+}
+
+/* ── the tools ────────────────────────────────────────────────────────────── */
+
+const ASK = {
+  name: 'ask_user',
+  title: 'Ask the user, with real controls',
+  description:
+    'Ask the user something with a real control instead of typing the question. Opens a page on '
+    + 'loopback in their browser — a slider, a date picker, a card picker, a counter row, a split '
+    + 'that must sum — waits for them to answer, and returns the answer/1 envelope.\n\n'
+    + 'USE IT when the answer has a shape a sentence loses: a magnitude on a scale, a date or '
+    + 'time, a pick from a ranked set with scores or notes, a split across parts, a band with two '
+    + 'ends, or several fields that should be answered together in one interruption.\n\n'
+    + 'DO NOT USE IT for a yes/no, for an answer that is one short sentence, or for anything you '
+    + 'could infer from what the user already said. Opening a browser tab to ask "shall I '
+    + 'continue?" is worse than typing it. The best question is the one you did not have to ask.\n\n'
+    + 'CHOOSING: two questions decide the type — what IS the answer, and does the asker already '
+    + 'know the possible answers (if yes it is `enum`, whatever the domain). Then the COUNT '
+    + 'decides the control: enum 2-4 short labels `segmented`, 2-8 `radio`, 9+ `select`, from a '
+    + '`source` always `select`; number 1-50 `stepper`, bounded-and-approximate `slider` (which '
+    + 'REQUIRES min and max). Derive from the answer\'s shape, never from the subject.\n\n'
+    + 'The full rule, with every per-type table and what to do before asking anything at all, is '
+    + 'the resource `comppack://asking`. Read it when this summary does not settle a case. '
+    + '`validate_question` checks a block against the schema and 15 lint rules without showing it '
+    + 'to anyone — this tool runs the same checks itself and refuses to open a browser on a block '
+    + 'whose widget cannot function.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      question: QUESTION_SCHEMA,
+      prompt: {
+        type: 'string',
+        description:
+          'The user\'s own message that prompted the ask, shown above the card. From the '
+          + 'transcript, never invented, and never taken from the block.',
+      },
+      options: {
+        type: 'object',
+        description:
+          'Options you resolved for any field with a `source`, keyed by field key. This server '
+          + 'never fetches them — that boundary is the library\'s, not an oversight.',
+      },
+      speak: {
+        type: 'boolean',
+        description:
+          'Read the question aloud as the page opens, and the answer back when it returns. '
+          + 'Silent on a machine with no speech engine — never an error.',
+      },
+      timeoutSeconds: { type: 'number', description: 'Default 600.' },
+    },
+    required: ['question'],
+  },
+};
+
+const VALIDATE = {
+  name: 'validate_question',
+  title: 'Check a question before asking it',
+  description:
+    'Check a question/1 block against the schema and the 15 lint rules, without showing it to '
+    + 'anyone. Returns schema errors first, then findings. Use it when you are unsure of the '
+    + 'shape — ask_user runs the same checks itself, so this is for iterating, not a required '
+    + 'step before every ask.',
+  inputSchema: {
+    type: 'object',
+    properties: { question: QUESTION_SCHEMA },
+    required: ['question'],
+  },
+};
+
+async function validateQuestion(id, args) {
+  const block = args?.question;
+  if (!block || typeof block !== 'object') {
+    return toolError(id, 'validate_question needs a `question` object.');
+  }
+
+  const c = await checkerFor();
+  if (c.error) return toolError(id, `The checker did not load: ${c.error}`);
+
+  const valid = c.validate(block);
+  const errors = valid ? [] : (c.validate.errors ?? []).map(e => ({
+    where: e.instancePath || '/', message: e.message ?? '', keyword: e.keyword,
+  }));
+  /* Lint only what parsed. Linting an invalid block reports on fields that may not be fields, and
+     the schema errors are what the author has to fix first anyway. */
+  const findings = valid ? c.lintQuestion(block) : [];
+  const { blocking, advisory } = split(findings);
+
+  const structured = { valid, errors, findings, blocking: blocking.map(f => f.rule) };
+
+  if (!valid) {
+    return ok(id, {
+      content: [{
+        type: 'text',
+        text: `Not a valid question/1 — ${errors.length} schema `
+          + `${errors.length === 1 ? 'error' : 'errors'}. Fix these and check again:\n`
+          + errors.map(e => `  ${e.where} ${e.message}`).join('\n'),
+      }],
+      structuredContent: structured,
+      isError: true,
+    });
+  }
+
+  /**
+   * ⚠ **Valid-but-poor is a SUCCESS with advice, not an error.**
+   *
+   * `CallToolResult` carries only `content`, `structuredContent` and `isError`; there is no
+   * warnings channel, and `_meta` is host-facing and hidden from the model. The de-facto pattern
+   * — the official ESLint server's — is advisory output in `content` on a successful result,
+   * bracketed by prose saying what to do with it. The bracketing is the part that works.
+   */
+  const lines = [`Valid question/1.`];
+  if (blocking.length) {
+    lines.push('',
+      'These would stop `ask_user` from opening it — the widget cannot function as described:',
+      ...blocking.map(asLine));
+  }
+  if (advisory.length) {
+    lines.push('',
+      'These are advisory. The ask works; it could be better. Act on them if you agree — nothing',
+      'here refuses an ask for being merely poor:',
+      ...advisory.map(asLine));
+  }
+  if (!findings.length) lines.push('No lint findings.');
+
+  return ok(id, {
+    content: [{ type: 'text', text: lines.join('\n') }],
+    structuredContent: structured,
+    /* `isError` only when the block cannot be asked. A poor ask is not a failed tool call. */
+    ...(blocking.length ? { isError: true } : {}),
+  });
+}
+
+const ELICIT = {
+  name: 'to_elicitation',
+  title: 'Flatten an ask for a client with no browser',
+  description:
+    'Turn a question/1 block into a form-mode elicitation, or say why it cannot be one. For a '
+    + 'client that cannot open a browser — anything that can should use `ask_user`, which loses '
+    + 'nothing.\n\n'
+    + 'MCP elicitation is a flat object of primitives by design: no nesting, and return values '
+    + 'limited to string, number, boolean and string[]. Six of the twenty widgets cannot cross at '
+    + 'all and this REFUSES them rather than mangling them — a `share` quietly turned into a '
+    + 'number would be a worse answer than no answer. Ten more cross as values with the widget '
+    + 'lost, and it says which.',
+  inputSchema: {
+    type: 'object',
+    properties: { question: QUESTION_SCHEMA },
+    required: ['question'],
+  },
+};
+
+async function toElicitationTool(id, args) {
+  const block = args?.question;
+  if (!block || typeof block !== 'object') {
+    return toolError(id, 'to_elicitation needs a `question` object.');
+  }
+
+  const b = await bridgeFor();
+  if (b.error) return toolError(id, `The bridge did not load: ${b.error}`);
+
+  const r = b.toElicitation(block);
+
+  if (!r.ok) {
+    return ok(id, {
+      content: [{
+        type: 'text',
+        text: 'This ask cannot become a flat form, and the fields that can would answer a '
+          + 'different question:\n'
+          + r.refusals.map(f => `  ${f.key} (${f.type}) — ${f.because}`).join('\n')
+          + '\n\nUse `ask_user` instead; it loses nothing.',
+      }],
+      structuredContent: { ok: false, refusals: r.refusals },
+      isError: true,
+    });
+  }
+
+  /* Crossing is a success even when a control was lost — the VALUE is intact, and the caller
+     asked for a flat form knowing what one is. The loss is stated, not hidden. */
+  return ok(id, {
+    content: [{
+      type: 'text',
+      text: r.lost.length
+        ? `Crossed. These lost their control and keep their value: ${r.lost.join(', ')}.`
+        : 'Crossed whole — a flat form already has these shapes.',
+    }],
+    structuredContent: { ok: true, elicitation: r.elicitation, lost: r.lost },
+  });
+}
+
+/* ── resources ────────────────────────────────────────────────────────────── */
+
+/**
+ * **The derivation rule as a resource, not as twenty tools.**
+ *
+ * `RFC-MCP.md` §4: the twenty widgets must not become twenty tools — that is twenty descriptions
+ * in every request's context for a choice the model should be deriving. A resource is
+ * URI-addressed and cacheable, and the model reads it when it wants it.
+ *
+ * The compressed form of the same rule is in `ask_user`'s description, because a resource nobody
+ * opens is a resource that does not exist. This is the long form for when the short one is not
+ * enough.
+ */
+const RESOURCES = [
+  {
+    uri: 'comppack://asking',
+    name: 'Choosing a widget',
+    title: 'The derivation rule, in full',
+    description:
+      'How to choose a type and a control for an ask: the rule, the per-type tables, and what to '
+      + 'do before asking anything at all. Written for whoever authors the JSON, agent or person.',
+    mimeType: 'text/markdown',
+    file: 'spec/ASKING.md',
+  },
+  {
+    uri: 'comppack://question-schema',
+    name: 'question/1 — the validator',
+    title: 'What is valid, as opposed to what to generate',
+    description:
+      'The full JSON Schema. `ask_user` does NOT take this as its argument schema — it takes the '
+      + 'generation profile, which is flat. This is what `validate_question` checks against.',
+    mimeType: 'application/json',
+    file: 'spec/question.schema.json',
+  },
+  {
+    uri: 'comppack://answers',
+    name: 'answer/1',
+    title: 'The envelope that comes back',
+    description: 'What an answered, skipped or cancelled ask returns, and what every type answers with.',
+    mimeType: 'text/markdown',
+    file: 'spec/QUESTION-SCHEMA.md',
+  },
+];
+
+/**
+ * **M5.2 · The catalogue, as a templated resource — the only shape in which completion works.**
+ *
+ * `completion/complete` accepts a `ref/resource` and **never** a tool argument, so a templated URI
+ * is the only way a client can offer widget names at all. And a resource rather than twenty tools,
+ * for the reason `RFC-MCP.md` §4 gives: twenty descriptions in every request's context, for a
+ * choice the model should be deriving from the answer's shape.
+ *
+ * The list is `widgetName` from the schema, so it cannot drift from what the renderer accepts.
+ */
+const WIDGETS = (() => {
+  const schema = JSON.parse(readFileSync(resolve(PKG, 'spec/question.schema.json'), 'utf8'));
+  return schema.$defs?.widgetName?.enum ?? [];
+})();
+
+const TEMPLATES = [
+  {
+    uriTemplate: 'comppack://widget/{name}',
+    name: 'One widget',
+    title: 'What a single widget is for, and when to reach for it',
+    description:
+      'The derivation rule for one widget, by name. Completion offers all '
+      + `${WIDGETS.length} of them.`,
+    mimeType: 'text/markdown',
+  },
+];
+
+/**
+ * One widget's entry, pulled from `ASKING.md` rather than written twice.
+ *
+ * ⚠ **A second copy of the guidance is a second thing to keep true.** The document already says
+ * when to reach for each widget; this finds the lines that mention it and hands those back, so a
+ * change to the guidance changes the resource.
+ */
+function widgetEntry(name) {
+  const asking = readFileSync(resolve(PKG, 'spec/ASKING.md'), 'utf8');
+  const lines = asking.split('\n');
+  const hits = lines
+    .map((line, i) => ({ line, i }))
+    .filter(({ line }) => line.includes(name) || line.includes(name.replace(/-/g, ' ')));
+
+  const body = hits.length
+    ? hits.map(({ line, i }) => `${String(i + 1).padStart(4)} | ${line}`).join('\n')
+    : '(ASKING.md does not mention this widget by name — derive from the answer\'s shape.)';
+
+  return `# ${name}\n\nEvery line in spec/ASKING.md that names it:\n\n\`\`\`\n${body}\n\`\`\`\n\n`
+    + 'The rule above these lines: what IS the answer, does the asker already know the possible\n'
+    + 'answers, and then the COUNT decides the control. Never the subject.\n';
+}
+
+function readResource(id, uri) {
+  /* The templated one first: a concrete `comppack://widget/slider` matches no fixed entry. */
+  const widget = /^comppack:\/\/widget\/(.+)$/.exec(uri ?? '');
+  if (widget) {
+    const name = decodeURIComponent(widget[1]);
+    if (!WIDGETS.includes(name)) {
+      return fail(id, -32602,
+        `No such widget: ${name}. The ${WIDGETS.length} are ${WIDGETS.join(', ')}.`);
+    }
+    return ok(id, {
+      contents: [{ uri, mimeType: 'text/markdown', text: widgetEntry(name) }],
+    });
+  }
+
+  const r = RESOURCES.find(x => x.uri === uri);
+  if (!r) return fail(id, -32602, `No such resource: ${uri}`);
+  try {
+    return ok(id, {
+      contents: [{ uri, mimeType: r.mimeType, text: readFileSync(resolve(PKG, r.file), 'utf8') }],
+    });
+  } catch (e) {
+    return fail(id, -32603, `${r.file} is not readable: ${e.message}`);
+  }
+}
+
+/* ── handlers ─────────────────────────────────────────────────────────────── */
+
+async function askUser(id, args) {
+  const block = args?.question;
+  if (!block || typeof block !== 'object') {
+    return toolError(id, 'ask_user needs a `question` object — a question/1 block.');
+  }
+  if (block.schema !== 'question/1') {
+    return toolError(
+      id,
+      `That is not a question/1 block (schema: ${JSON.stringify(block.schema)}). `
+      + 'The renderer checks this rather than assuming it, so a wrong file is this message '
+      + 'instead of a render that goes strange.',
+    );
+  }
+
+  /**
+   * **Checked before a tab opens, because the alternative is a person looking at a broken ask.**
+   *
+   * A block with `slider-without-bounds` renders — as a scrollbar for an unknown range. The user
+   * cannot tell that from a slider, answers it, and the run proceeds on a number that means
+   * nothing. Catching it here costs one function call and turns a bad interaction into a message
+   * the model can act on.
+   *
+   * ⚠ **Advisory findings do NOT stop the ask.** `lintQuestion` never rejects; a menu of three
+   * options is a real criticism of a working ask, and refusing to show it would make this server
+   * an editor of questions rather than a renderer of them.
+   */
+  const c = await checkerFor();
+  if (!c.error) {
+    if (!c.validate(block)) {
+      const errors = (c.validate.errors ?? []).slice(0, 8);
+      return toolError(
+        id,
+        `That block is not valid question/1, so nothing was opened. `
+        + `${errors.length} ${errors.length === 1 ? 'error' : 'errors'}:\n`
+        + errors.map(e => `  ${e.instancePath || '/'} ${e.message}`).join('\n')
+        + '\n\nCall `validate_question` while you iterate.',
+      );
+    }
+    const { blocking, advisory } = split(c.lintQuestion(block));
+    if (blocking.length) {
+      return toolError(
+        id,
+        'That block is valid but the widget cannot function as described, so nothing was '
+        + 'opened:\n' + blocking.map(asLine).join('\n')
+        + '\n\nFix these and call again. Everything else lint finds would have travelled with '
+        + 'the ask rather than stopping it.',
+      );
+    }
+    /* Advisory findings ride along on stderr — the operator's channel. They are not the model's
+       problem at this point: it is about to get an answer, and telling it the ask was mediocre
+       while handing it the result would invite a re-ask the user never agreed to. */
+    if (advisory.length) {
+      console.error(`comppack-ask: ${advisory.length} advisory lint finding(s)`);
+      for (const f of advisory) console.error(asLine(f));
+    }
+  }
+
+  let ask;
+  try {
+    ask = askInBrowser(block, {
+      prompt: args.prompt,
+      options: args.options,
+      timeoutMs: (args.timeoutSeconds ?? 600) * 1000,
+    });
+  } catch (e) {
+    return toolError(id, e.message);
+  }
+
+  const url = await ask.ready;
+
+  /* Lazily, and failure is silent: an ask that renders is not spoiled by a machine that cannot
+     talk, and `speak()` already resolves rather than throwing when no engine exists. */
+  let speech;
+  if (args.speak) {
+    speech = await import('./dist/speakable.mjs').catch(() => undefined);
+    if (speech) await speak({ text: speech.speakableOfBlock(block) }).catch(() => {});
+  }
+
+  /**
+   * **The URL on stderr, because stdout is the protocol.**
+   *
+   * A client shows its own tool-call UI and not this; a person debugging one sees only that a
+   * call is hanging. The URL is the single fact that explains it — the browser did not open, or
+   * opened somewhere they are not looking — and stderr is where a stdio server is allowed to say
+   * so without corrupting a single frame of JSON-RPC.
+   */
+  console.error(`comppack-ask: ${block.question ?? block.slug} — ${url}`);
+
+  const cmd = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'start' : 'xdg-open';
+  spawn(cmd, [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' })
+    .on('error', () => {});
+
+  try {
+    const envelope = await ask.answer;
+    if (speech) {
+      await speak({ text: speech.speakableOfAnswers(block, envelope.answers ?? {}) }).catch(() => {});
+    }
+    ok(id, {
+      /* Both, on purpose: `structuredContent` is the envelope a caller acts on, and the text
+         block is what a model that ignores structured output still reads. */
+      content: [{ type: 'text', text: JSON.stringify(envelope, null, 2) }],
+      structuredContent: envelope,
+    });
+  } catch (e) {
+    ask.close();
+    toolError(id, `${e.message} The page was at ${url}.`);
+  }
+}
+
+const HANDLERS = {
+  initialize: (id) => ok(id, {
+    protocolVersion: PROTOCOL,
+    capabilities: { tools: {}, resources: {}, completions: {} },
+    serverInfo: { name: 'comppack-ask', version: '0.1.2' },
+  }),
+  'notifications/initialized': () => {},
+  ping: id => ok(id, {}),
+  'tools/list': id => ok(id, { tools: [ASK, VALIDATE, ELICIT] }),
+  'tools/call': (id, params) => {
+    const args = params?.arguments ?? {};
+    if (params?.name === 'ask_user') return askUser(id, args);
+    if (params?.name === 'validate_question') return validateQuestion(id, args);
+    if (params?.name === 'to_elicitation') return toElicitationTool(id, args);
+    return fail(id, -32602, `Unknown tool: ${params?.name}`);
+  },
+  /* `file` is where the text lives on disk and is nobody's business over the wire — a resource
+     is addressed by its URI, and leaking a path invites a client to try reading it. */
+  'resources/list': id => ok(id, {
+    resources: RESOURCES.map(r => ({
+      uri: r.uri, name: r.name, title: r.title, description: r.description, mimeType: r.mimeType,
+    })),
+  }),
+  'resources/read': (id, params) => readResource(id, params?.uri),
+  'resources/templates/list': id => ok(id, { resourceTemplates: TEMPLATES }),
+
+  /**
+   * Completion works for `ref/resource` and never for a tool argument, which is why the catalogue
+   * is a template. A prefix match, because a model typing `card` wants `card-picker` and not a
+   * ranked guess.
+   */
+  'completion/complete': (id, params) => {
+    const ref = params?.ref ?? {};
+    if (ref.type !== 'ref/resource' || ref.uri !== 'comppack://widget/{name}') {
+      return ok(id, { completion: { values: [], total: 0, hasMore: false } });
+    }
+    const typed = String(params?.argument?.value ?? '').toLowerCase();
+    const values = WIDGETS.filter(w => w.toLowerCase().startsWith(typed)).slice(0, 100);
+    return ok(id, { completion: { values, total: values.length, hasMore: false } });
+  },
+};
+
+createInterface({ input: process.stdin }).on('line', line => {
+  if (!line.trim()) return;
+  let msg;
+  try { msg = JSON.parse(line); } catch { return; }
+
+  const handler = HANDLERS[msg.method];
+  /* A notification has no id and MUST NOT be answered — replying to one is a stray message the
+     client cannot match to anything. */
+  if (msg.id === undefined) { handler?.(undefined, msg.params); return; }
+  if (!handler) return fail(msg.id, -32601, `Method not found: ${msg.method}`);
+
+  try {
+    const r = handler(msg.id, msg.params);
+    if (r && typeof r.catch === 'function') r.catch(e => fail(msg.id, -32603, String(e)));
+  } catch (e) {
+    fail(msg.id, -32603, String(e));
+  }
+});

package/tools/ask/policy.mjs

@@ -0,0 +1,40 @@
+/**
+ * **Which lint findings stop an ask, and which travel with it.**
+ *
+ * Extracted from `mcp.mjs` so it can be tested: a typo in a rule name here does not fail, it
+ * silently makes that rule advisory, and the ask a person sees is broken in exactly the way the
+ * rule was written to prevent. `tests/ask-policy.test.ts` checks every name against the linter's
+ * own output.
+ *
+ * **`lintQuestion` never rejects** — that is documented and deliberate, and this does not change
+ * it. Blocking is a HOST policy, which is why it lives here and not in `src/`: the library's
+ * `LintLevel` is `warn | info`, which says how loud a finding is, not whether the widget works.
+ */
+
+/**
+ * The bar is deliberately high: **the widget cannot function**, not *the ask could be better*.
+ *
+ * | `slider-without-bounds` | a scrollbar for an unknown range, and the user cannot tell |
+ * | `enum-without-options` | nothing to pick |
+ * | `share-does-not-sum` | the one invariant the widget has, violated |
+ * | `range-default-inverted` | incoherent before anyone touches it |
+ *
+ * Everything else `lintQuestion` finds — a menu of three, a required single-select with no way
+ * out, notes the control cannot show — is a real criticism of a **working** ask. Refusing those
+ * would make this an editor of questions rather than a renderer of them.
+ */
+export const BLOCKING = new Set([
+  'slider-without-bounds',
+  'enum-without-options',
+  'share-does-not-sum',
+  'range-default-inverted',
+]);
+
+/** @param {{rule: string, level: string, where: string, message: string}[]} findings */
+export const split = (findings) => ({
+  blocking: findings.filter(f => BLOCKING.has(f.rule)),
+  advisory: findings.filter(f => !BLOCKING.has(f.rule)),
+});
+
+/** One finding as one line. `!` is a warn, `·` an info — the linter's own levels. */
+export const asLine = f => `  ${f.level === 'warn' ? '!' : '·'} ${f.rule} (${f.where}) — ${f.message}`;