engine: sanitize OpenAPI summaries/descriptions to plain text

Generated MCP tool + Agent Skill descriptions carried the source spec's raw HTML
(Stripe et al. ship <p>…</p>/<a> in operation descriptions), so a forged tool read
"Stripe Get   Charges — <p>Use the <a href=…". Add plain(): strip tags, unescape
common entities, collapse whitespace (also fixes "Get   Charges" double-spacing),
trim — applied at the parse point so all downstream tool/skill/param descriptions
are clean text.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kinlane

src/engine.ts

@@ -72,13 +72,13 @@ export function operations(doc: any): Operation[] {
       const responses = op.responses || {};
       const okCode = Object.keys(responses).find((c) => /^2/.test(c));
       if (okCode) { const r = deref(doc, responses[okCode]); if (r?.content) { const ct = pickJson(r.content); if (ct) responseSchema = ct.schema; } }
-      out.push({ key: `${m} ${path}`, method: m, path, operationId: opId, summary: op.summary || '', description: op.description || '', tags: op.tags || [], params, requestSchema, responseSchema });
+      out.push({ key: `${m} ${path}`, method: m, path, operationId: opId, summary: plain(op.summary || ''), description: plain(op.description || ''), tags: op.tags || [], params, requestSchema, responseSchema });
     }
   }
   return out;
 }
 const pickJson = (content: any) => content['application/json'] || content[Object.keys(content)[0]];
-function normParam(doc: any, p: any): OpParam { p = deref(doc, p); return { name: p.name, in: p.in, required: !!p.required, schema: p.schema, description: p.description }; }
+function normParam(doc: any, p: any): OpParam { p = deref(doc, p); return { name: p.name, in: p.in, required: !!p.required, schema: p.schema, description: p.description ? plain(p.description) : undefined }; }
 
 // ---- extension access (design lives on the doc) ------------------------------
 function opNode(doc: any, op: Operation): any { return doc.paths?.[op.path]?.[op.method]; }
@@ -107,6 +107,17 @@ export function setRootSkills(doc: any, s: SkillDesign[]) {
 export const kebab = (s: string) => String(s || '').replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').replace(/-{2,}/g, '-');
 export const snake = (s: string) => kebab(s).replace(/-/g, '_');
 
+// OpenAPI summaries/descriptions are often HTML (Stripe et al. ship <p>…</p>, <a>, code blocks).
+// A generated MCP tool/skill description must be PLAIN TEXT — an agent reading "<p>Use the <a…"
+// is worse off than one reading a clean sentence. Strip tags, unescape the common entities,
+// collapse whitespace (kills the "Get   Charges" double-spacing too), and trim.
+export const plain = (s: string) => String(s || '')
+  .replace(/<\/(p|div|li|h[1-6]|br)>/gi, ' ')
+  .replace(/<[^>]+>/g, '')
+  .replace(/&(nbsp|amp|lt|gt|quot|#39|apos);/g, (_m, e) => ({ nbsp: ' ', amp: '&', lt: '<', gt: '>', quot: '"', '#39': "'", apos: "'" } as Record<string, string>)[e] || ' ')
+  .replace(/\s+/g, ' ')
+  .trim();
+
 export function draftServer(doc: any): ServerDesign {
   const title = doc.info?.title || 'My API';
   const server = doc.servers?.[0]?.url || 'https://api.example.com';