@appinternalleads/ui 0.2.0 → 0.4.0

package/tools/ask/mcp.mjs

@@ -519,6 +519,146 @@ async function askUser(id, args) {
   }
 }
 
+/* ── the components: the agent component contract ─────────────────────── */
+
+/**
+ * **Search, describe, check — three tools, not twelve.** An agent finds a component by what the
+ * person wants (`search_components` → short cards), learns one (`describe_component` → its
+ * capability: purpose, runtime data, copy, behaviour, actions, states, results), builds a
+ * `render/1` request and checks it (`check_render_request`) — every layer the component would
+ * apply, unknown keys included. The capability is the one `src/agent` builds: the package, the
+ * site's `/api/components` and the builder read the same. `list_components` and
+ * `check_component_config` are the older config-level tools, kept for existing callers.
+ * `dist/components.mjs` holds only pure modules, bundled by `ask:build`.
+ */
+let components;
+const componentsModule = async () => (components ??= await import('./dist/components.mjs'));
+
+const SEARCH_COMPONENTS = {
+  name: 'search_components',
+  title: 'Find a component for what the person wants',
+  description:
+    'Search the approved component catalogue by intent — "proof of payment", "compare laptops", '
+    + '"split seats between teams". Returns short cards (component, name, kind, purpose, signals), '
+    + 'best first. Only components in the agent contract are returned. Then call describe_component '
+    + 'on the one that fits.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'What the person wants, in their words.' },
+      limit: { type: 'number', description: 'At most this many cards (default 5).' },
+    },
+    required: ['query'],
+  },
+};
+
+const DESCRIBE_COMPONENT = {
+  name: 'describe_component',
+  title: 'Everything needed to use one component',
+  description:
+    'The component\'s capability: purpose, when to use and avoid it, related components, kind, '
+    + 'states, actions, the result events it reports, and its request sections — `data` (runtime '
+    + 'data: required keys, types, limits, enums, references, where each value must come from), '
+    + '`copy` (every word: defaults, {placeholders} that must stay, length limits), `behavior` and '
+    + '`presentation` (allowed values and who may set them). Also `askFor`: what to ask the person '
+    + 'when required data is missing. Build a render/1 request from it and check it with '
+    + 'check_render_request.',
+  inputSchema: {
+    type: 'object',
+    properties: { component: { type: 'string', description: 'An id from search_components, e.g. receipt-printer.' } },
+    required: ['component'],
+  },
+};
+
+const CHECK_RENDER_REQUEST = {
+  name: 'check_render_request',
+  title: 'Check a render request before sending it',
+  description:
+    'Validate a render/1 request: { schema: "render/1", component, data, copy?, behavior?, '
+    + 'presentation?, actions?, preset? }. Runs every check the component will: unknown keys, kinds, '
+    + 'required runtime data (nothing is filled in from examples), ranges, formats, enums, '
+    + 'references, copy placeholders and lengths, the component\'s own validator, and what its '
+    + 'submit would refuse. Valid → { valid: true, request (with defaults), preview.visibleText }. '
+    + 'Invalid → { valid: false, issues: [{ path, code, layer, section, message, expected }] } — fix '
+    + 'each issue at its path and check again.',
+  inputSchema: {
+    type: 'object',
+    properties: { request: { type: 'object', description: 'The render/1 request.' } },
+    required: ['request'],
+  },
+};
+
+const LIST_COMPONENTS = {
+  name: 'list_components',
+  title: 'List every component (legacy)',
+  description:
+    'Every component in the package with `agentEditable`: only those marked true are in the agent '
+    + 'contract (search_components, describe_component, check_render_request). The others render '
+    + 'but their words and data are not described or checked — do not use them from an agent.',
+  inputSchema: { type: 'object', properties: {} },
+};
+
+const CHECK_COMPONENT_CONFIG = {
+  name: 'check_component_config',
+  title: 'Check a raw component config (legacy)',
+  description:
+    'Config-level inspection for builders: merge a flat config over a case study and run only the '
+    + 'component\'s validator. It does NOT reject unknown keys, check kinds, required runtime data '
+    + 'or what Print would refuse — agents should use check_render_request.',
+  inputSchema: {
+    type: 'object',
+    properties: { component: { type: 'string' }, preset: { type: 'string' }, config: { type: 'object' } },
+    required: ['component', 'config'],
+  },
+};
+
+const COMPONENT_TOOLS = ['search_components', 'describe_component', 'check_render_request', 'list_components', 'check_component_config'];
+
+const answer = (id, structured, text, isError = false) =>
+  ok(id, { content: [{ type: 'text', text }], structuredContent: structured, ...(isError ? { isError: true } : {}) });
+
+async function componentTool(id, name, args) {
+  let m;
+  try { m = await componentsModule(); } catch (e) {
+    return toolError(id, `The component catalogue did not load (run \`npm run ask:build\`): ${e.message}`);
+  }
+  if (name === 'search_components') {
+    if (typeof args?.query !== 'string' || !args.query.trim()) return toolError(id, 'search_components needs `query`, what the person wants.');
+    const cards = m.searchComponents(args.query, typeof args.limit === 'number' ? args.limit : 5);
+    return answer(id, { components: cards }, cards.length
+      ? JSON.stringify(cards, null, 2)
+      : `Nothing in the catalogue matches "${args.query}". The approved components: ${m.AGENT_COMPONENTS.join(', ')}.`);
+  }
+  if (name === 'describe_component') {
+    const cap = m.describeComponent(args?.component);
+    if (!cap) {
+      const a = m.agentAvailability(String(args?.component));
+      return toolError(id, `${JSON.stringify(args?.component)} is not in the agent contract${a.reason ? ` — ${a.reason}` : ''} Approved: ${m.AGENT_COMPONENTS.join(', ')}.`);
+    }
+    return answer(id, cap, JSON.stringify(cap, null, 2));
+  }
+  if (name === 'check_render_request') {
+    const r = m.validateRenderRequest(args?.request);
+    const text = r.valid
+      ? `Valid — ${r.request.component} will render it. The person would see:\n${r.preview.visibleText.map(t => `  ${t}`).join('\n')}`
+      : `Not valid — ${r.issues.length} ${r.issues.length === 1 ? 'issue' : 'issues'}:\n${r.issues.map(i => `  ${i.path} [${i.code}, ${i.layer}]: ${i.message}${i.expected ? ` Expected: ${Array.isArray(i.expected) ? i.expected.join(', ') : i.expected}.` : ''}`).join('\n')}`;
+    return answer(id, r, text, !r.valid);
+  }
+  if (name === 'list_components') {
+    const list = m.listComponents();
+    return answer(id, { components: list }, JSON.stringify(list, null, 2));
+  }
+  /* check_component_config — legacy. */
+  if (!m.isComponent(args?.component)) return toolError(id, `No New component called ${JSON.stringify(args?.component)}.`);
+  const config = args?.config;
+  if (!config || typeof config !== 'object' || Array.isArray(config)) return toolError(id, 'check_component_config needs `config`, an object.');
+  const r = m.checkConfig(args.component, args.preset, config);
+  const text = r.valid
+    ? `The component's validator accepts it (legacy check — unknown keys, kinds and required data are not checked; use check_render_request). Resolved config:\n${JSON.stringify(r.resolved, null, 2)}`
+    : `Not valid — ${r.issues.length} ${r.issues.length === 1 ? 'problem' : 'problems'}:\n${r.issues.map(i => `  ${i.path}: ${i.message}`).join('\n')}`;
+  return answer(id, r, text, !r.valid);
+}
+
 const HANDLERS = {
   initialize: (id) => ok(id, {
     protocolVersion: PROTOCOL,
@@ -527,12 +667,13 @@ const HANDLERS = {
   }),
   'notifications/initialized': () => {},
   ping: id => ok(id, {}),
-  'tools/list': id => ok(id, { tools: [ASK, VALIDATE, ELICIT] }),
+  'tools/list': id => ok(id, { tools: [ASK, VALIDATE, ELICIT, SEARCH_COMPONENTS, DESCRIBE_COMPONENT, CHECK_RENDER_REQUEST, LIST_COMPONENTS, CHECK_COMPONENT_CONFIG] }),
   '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);
+    if (COMPONENT_TOOLS.includes(params?.name)) return componentTool(id, params.name, 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