@apiosk/mcp 1.3.1 → 2.0.0

package/src/gateway-v2-card-answer.mjs

@@ -0,0 +1,68 @@
+// Presentation of returned evidence only. This is not an onboarding approval,
+// a compliance certification, or a replacement for the gateway's payment verdict.
+export function ukSupplierSummary(data, results) {
+  const context = data?.context_view || {};
+  const question = context.conversation?.[0]?.question || '';
+  const notices = Array.isArray(context.coverage_notices) ? context.coverage_notices : [];
+  const ukCheck = notices.some(note => typeof note === 'string' && note.includes('complete roster of up to five active directors'))
+    || (/\b(?:UK|British|United Kingdom)\b/i.test(question) && /supplier|onboard/i.test(question) && /VAT/i.test(question) && /director|screening/i.test(question));
+  if (!ukCheck || context.worker_active || context.analyzing || context.result_is_historical || !['succeeded', 'partial'].includes(data.status)) return null;
+  const profiles = results.filter(r => r.source?.provider === 'companies-house' && typeof r.data?.company_number === 'string' && typeof r.data?.company_status === 'string');
+  if (profiles.length !== 1 || !profiles[0].subject?.entity_ref) return null;
+  const profile = profiles[0], company = profile.data;
+  const related = results.filter(r => r.subject?.entity_ref === profile.subject.entity_ref && r.coverage !== 'partial' && !r.error);
+  const completeProfile = related.includes(profile);
+  const psc = related.find(r => r.source?.provider === 'companies-house' && /persons-with-significant-control/.test(r.source.path || ''));
+  const pscCount = Number.isInteger(psc?.data?.total_results) ? psc.data.total_results : null;
+  const accounts = completeProfile ? company.accounts : null;
+  const period = accounts?.last_accounts?.made_up_to;
+  const overdue = accounts?.overdue === true || accounts?.next_accounts?.overdue === true;
+  const vat = related.find(r => r.source?.provider === 'ask-merlin');
+  const vatValue = vat?.data?.data?.valid ?? vat?.data?.valid;
+  const invalidCandidate = vatValue === false;
+  const screening = related.filter(r => r.source?.provider === 'opensanctions');
+  const responses = screening.flatMap(r => Object.values(r.data?.responses || {}));
+  const candidateCount = responses.reduce((count, response) => count + (Array.isArray(response?.results) ? response.results.length : 0), 0);
+  const noCandidates = responses.length > 0 && responses.every(response => Array.isArray(response?.results) && response.results.length === 0 && response.total?.value === 0 && !response.error);
+  const active = completeProfile && company.company_status === 'active';
+  const checks = [
+    {label:'UK entity', status:active?'pass':'review', detail:completeProfile ? company.company_status + ' · ' + company.company_number : 'Registration evidence incomplete'},
+    {label:'Ownership', status:pscCount>0?'info':'unknown', detail:pscCount>0 ? pscCount + ' PSC records · ownership still needs review' : pscCount===0 ? 'Not established · no PSC records returned' : 'Not verified · no complete PSC result'},
+    {label:'Filed accounts', status:overdue?'review':period?'info':'unknown', detail:period ? 'Period ' + period + (overdue?' · overdue':' · filing status only') : 'Not verified · no accounts period returned'},
+    {label:'VAT', status:vat&&!invalidCandidate?'review':'unknown', detail:invalidCandidate ? 'Candidate invalid · supplier VAT unverified' : vatValue===true ? 'Number valid · supplier identity match needs review' : vat ? 'Validation returned · review validity and identity match' : 'Not verified · no validation result'},
+    {label:'Director screening', status:screening.length?'review':'unknown', detail:candidateCount ? candidateCount + ' potential ' + (candidateCount===1?'match':'matches') + ' · manual review' : noCandidates ? 'No candidates returned · review roster coverage' : screening.length ? 'Screening returned · manual review required' : 'Not verified · no screening result'},
+  ];
+  const incomplete = data.status === 'partial' || checks.some(check => check.status === 'unknown');
+  return {subject:company.company_name || profile.subject.label, label:incomplete?'Not fully verified':'Review required', checks,
+    summary:active ? 'The UK entity is active. That does not establish full supplier-onboarding clearance.' : 'The saved checks do not establish an active, fully verified UK supplier.',
+    note:'Missing evidence is not a failed check. A screening candidate is not a confirmed sanctions finding.'};
+}
+
+// The generic answer mirrors the App's Ask task view (GatewayV2Outputs): the
+// full answer text, then blocks (answer_schema_version 2) or the presentation
+// table. Without an analysis there is no answer section: the source result is
+// drawn directly (see gateway-v2-card-research.mjs).
+export const V2_CARD_ANSWER = `
+${ukSupplierSummary.toString()}
+function renderResearchAnswer(data,results){
+ const uk=ukSupplierSummary(data,results),analysis=data.context_view?.analysis;
+ if(!uk&&!analysis)return null;
+ let s;
+ if(uk){
+  s=section(formatDisplayNarrative(uk.subject,data));s.classList.add('answer-section','research-answer');
+  const headline=el('p','answer-verdict',uk.label);headline.setAttribute('role','status');s.append(headline,el('p','answer-summary',uk.summary));
+  const checks=el('dl','answer-checks');
+  for(const check of uk.checks){const row=el('div','answer-check '+check.status);row.append(el('dt','',check.label),el('dd','',formatDisplayNarrative(check.detail,data)));checks.append(row)}
+  s.append(checks,el('p','meta answer-caveat',uk.note));
+ }else{
+  s=el('section','section answer-section research-answer');s.setAttribute('aria-label','Answer');sections.append(s);
+  const question=data.context_view?.conversation?.at(-1)?.question||'',value=answerText(analysis,{results,question});
+  if(data.status==='partial'||analysis.status==='partial')s.append(el('p','meta answer-partial','Some information is missing. Review the available results in Sources and details.'));
+  if(value)s.append(renderAnswerText(value,{results,analysis}));
+  const detail=isBlocksAnswer(analysis)?renderAnswerBlocks(analysis):renderAnswerPresentation(question,results,analysis);
+  if(detail)s.append(detail);
+ }
+ const links=el('div','result-links');s.append(links);
+ return {section:s,links,title:uk?'Supplier verification':'Answer',subtitle:uk?'Based on saved source evidence.':'Based on the saved source results.'};
+}
+`;

package/src/gateway-v2-card-blocks.mjs

@@ -0,0 +1,166 @@
+// The App's versioned answer blocks (answer_schema_version 2): data tables,
+// bar charts and the generic fallback that renders any other kind as facts
+// (app/src/lib/domain/answer-blocks-view.ts, components/ask/answer-blocks).
+// Every Fact arrives resolved by the gateway; the card only displays, sorts
+// and filters it. Keep in sync with the App.
+export function isBlocksAnswer(analysis) { return !!analysis && (analysis.answer_schema_version ?? 1) >= 2 && Array.isArray(analysis.blocks); }
+export function factOrigin(fact, collection, rowIndex, relativePointer) {
+  if (fact?.result_ref && fact.pointer) return { result_ref: fact.result_ref, pointer: fact.pointer };
+  if (collection && rowIndex != null && relativePointer) return { result_ref: collection.result_ref, pointer: collection.rows_pointer + '/' + rowIndex + relativePointer };
+  return null;
+}
+/** Sorts the complete selected set, nulls last in both directions, before paging. */
+export function sortTableRows(columns, rows, sort) {
+  const index = sort ? columns.findIndex(c => c.id === sort.column_id) : -1;
+  if (index < 0) return rows;
+  const direction = sort.direction === 'asc' ? 1 : -1, key = row => row?.cells?.[index]?.value ?? null;
+  return [...rows].sort((a, b) => {
+    const av = key(a), bv = key(b);
+    if (av == null && bv == null) return 0;
+    if (av == null) return 1;
+    if (bv == null) return -1;
+    return typeof av === 'number' && typeof bv === 'number' ? (av - bv) * direction : String(av).localeCompare(String(bv)) * direction;
+  });
+}
+export function filterTableRows(rows, query) {
+  const q = String(query || '').trim().toLowerCase();
+  return q ? rows.filter(row => (row?.cells || []).some(cell => cell?.value != null && String(cell.value).toLowerCase().includes(q))) : rows;
+}
+/** Fixed over every selected bar, so revealing more never rescales. */
+export function barScale(block) {
+  if (block.scale) return block.scale;
+  const values = (block.bars || []).map(bar => typeof bar.fact?.value === 'number' ? bar.fact.value : null).filter(v => v != null);
+  return { min: Math.min(0, ...values), max: Math.max(0, ...values) };
+}
+export function rankingScopeLabel(scope) {
+  return scope === 'total_available' ? 'ranked across every available result' : scope === 'fetched' ? 'ranked across every fetched result' : 'ranked across the selected results';
+}
+function blockLabelOf(label, fact, id) { return label ? label : fact?.value != null ? String(fact.value) : id; }
+/** Any kind's facts as labelled rows; unknown kinds render through this. */
+export function blockFacts(block) {
+  const list = value => Array.isArray(value) ? value : [];
+  switch (block.kind) {
+    case 'summary': return list(block.conclusion?.facts).map((fact, i) => ({ label: 'Fact ' + (i + 1), fact }));
+    case 'data_table': return list(block.rows).flatMap((row, ri) => list(block.columns).map((column, ci) => ({ label: column.label, fact: row.cells?.[ci], collection: block.collection, rowIndex: row.row_index ?? ri, relativePointer: column.pointer })));
+    case 'comparison': return list(block.rows).flatMap(row => list(row.cells).map((fact, i) => ({ label: row.label + ' — ' + (block.entities?.[i]?.label ?? ''), fact })));
+    case 'kpi': return list(block.cards).flatMap(card => [{ label: card.label, fact: card.fact }, ...(card.change ? [{ label: card.label + ' (baseline)', fact: card.change.baseline }] : [])]);
+    case 'line_chart': return list(block.series).flatMap(series => list(series.points).map((point, pi) => ({ label: series.label + ' — ' + (point.period?.key ?? point.period?.value ?? ''), fact: point.fact ?? null, collection: series.collection, rowIndex: point.row_index ?? pi, relativePointer: series.value_pointer })));
+    case 'bar_chart': return list(block.bars).map((bar, bi) => ({ label: blockLabelOf(bar.label, bar.label_fact, 'Bar ' + (bi + 1)), fact: bar.fact ?? null, collection: block.collection, rowIndex: bar.row_index ?? bi, relativePointer: block.value_pointer }));
+    case 'map': return list(block.features).flatMap(feature => list(feature.facts).map(lf => ({ label: blockLabelOf(feature.label, feature.label_fact, feature.id) + ' — ' + lf.label, fact: lf.fact ?? null, collection: block.collection, rowIndex: feature.row_index })));
+    case 'timeline': return list(block.events).flatMap(event => [
+      { label: blockLabelOf(event.label, event.label_fact, event.id) + ' — date', fact: event.date ?? null, collection: block.collection, rowIndex: event.row_index, relativePointer: block.date_pointer },
+      ...list(event.facts).map(lf => ({ label: blockLabelOf(event.label, event.label_fact, event.id) + ' — ' + lf.label, fact: lf.fact ?? null, collection: block.collection, rowIndex: event.row_index }))]);
+    case 'profile': return [
+      ...(block.name ? [{ label: 'Name', fact: block.name }] : []),
+      ...list(block.identifiers).map(lf => ({ label: lf.label, fact: lf.fact ?? null })),
+      ...(block.status ? [{ label: block.status.label, fact: block.status.fact ?? null }] : []),
+      ...list(block.attributes).map(lf => ({ label: lf.label, fact: lf.fact ?? null }))];
+    case 'relationship': return list(block.edges).flatMap(edge => list(edge.evidence).map((fact, i) => ({ label: edge.label + ' (' + (i + 1) + ')', fact })));
+    default: return [];
+  }
+}
+
+// ---- DOM, run inside the card only --------------------------------------------
+function renderAnswerBlocks(analysis) {
+  const wrap = el('div', 'answer-blocks');wrap.setAttribute('aria-label', 'Answer data');
+  // A narrative block is the observations, already shown as the answer text.
+  for (const block of analysis.blocks) if (block && block.kind !== 'narrative') wrap.append(block.kind === 'data_table' ? dataTableBlock(block, analysis) : block.kind === 'bar_chart' ? barChartBlock(block, analysis) : genericBlock(block, analysis));
+  return wrap.children.length ? wrap : null;
+}
+function blockFactValue(fact) {
+  if (!fact || fact.value == null) return el('span', 'body-muted', 'Unknown');
+  const value = answerValue(fact.value, fact.field ?? '', fact.currency?.value != null ? String(fact.currency.value) : null, 'nl-NL');
+  const labels = { estimated: 'Estimated', provisional: 'Provisional', revised: 'Revised', rounded: 'Rounded', confidential: 'Confidential' };
+  if (!fact.flags?.length) return el('span', 'fact-value', value);
+  const span = el('span', 'fact-value');span.append(el('span', '', value));
+  for (const flag of fact.flags) span.append(el('span', 'fact-flag', labels[flag?.kind] || text(flag?.kind)));
+  return span;
+}
+function blockFactSource(fact, sourceIndex, collection, rowIndex, relativePointer) {
+  const origin = factOrigin(fact, collection, rowIndex, relativePointer);
+  if (!origin) return fact?.derivation_id ? el('span', 'fact-source', 'Calculated') : null;
+  const entry = (sourceIndex || []).find(s => s.result_ref === origin.result_ref);
+  return el('span', 'fact-source', (entry?.name ?? entry?.provider ?? 'Source') + ' · ' + origin.pointer);
+}
+function blockCell(fact, sourceIndex, collection, rowIndex, relativePointer) {
+  const td = el('td'), source = blockFactSource(fact, sourceIndex, collection, rowIndex, relativePointer);
+  td.append(blockFactValue(fact));if (source) td.append(source);
+  return td;
+}
+function blockTable(label, headings, rows) {
+  const region = el('div', 'block-table-wrap'), table = el('table', 'block-table'), head = el('tr'), thead = el('thead'), tbody = el('tbody');
+  region.setAttribute('role', 'region');region.setAttribute('aria-label', label);region.tabIndex = 0;
+  for (const heading of headings) { const th = el('th', '', heading);th.setAttribute('scope', 'col');head.append(th); }
+  thead.append(head);tbody.append(...rows);table.append(thead, tbody);region.append(table);
+  return region;
+}
+function blockMore(label, onClick) { const b = el('button', 'quiet', label);b.type = 'button';b.onclick = () => { onClick();window.apiosk.resize(); };return b; }
+function dataTableBlock(block, analysis) {
+  const s = el('section', 'answer-block'), columns = block.columns || [], all = block.rows || [], sourceIndex = analysis?.source_index || [];
+  const counts = el('p', 'meta'), region = el('div'), more = el('div'), controls = el('div', 'block-controls'), field = el('input', 'block-filter'), toggles = el('fieldset', 'block-columns');
+  const hidden = new Set(columns.filter(c => c.hidden).map(c => c.id)), sorted = sortTableRows(columns, all, block.sort);
+  let shown = 20, query = '';
+  s.setAttribute('aria-label', block.title ?? 'Data table');if (block.title) s.append(el('h3', '', block.title));
+  field.type = 'search';field.placeholder = 'Filter rows';field.setAttribute('aria-label', 'Filter rows');
+  const draw = () => {
+    const filtered = filterTableRows(sorted, query), visible = columns.filter(c => !hidden.has(c.id)), coverage = block.coverage;
+    counts.textContent = (coverage ? coverage.selected + ' selected · ' + coverage.fetched + ' fetched' + (coverage.total_available !== undefined ? ' · ' + coverage.total_available + ' total available' : '') : all.length + ' rows') + (filtered.length !== all.length ? ' · ' + filtered.length + ' match the filter' : '');
+    region.replaceChildren(visible.length ? blockTable((block.title ?? 'Data table') + ' table', visible.map(c => c.label), filtered.slice(0, shown).map((row, ri) => {
+      const tr = el('tr');
+      for (const column of visible) tr.append(blockCell(row.cells?.[columns.indexOf(column)], sourceIndex, block.collection, row.row_index ?? ri, column.pointer));
+      return tr;
+    })) : el('p', 'meta', 'Every column is hidden.'));
+    more.replaceChildren(...(shown < filtered.length ? [blockMore('Show more rows (' + (filtered.length - shown) + ' remaining)', () => { shown += 20;draw(); })] : []));
+  };
+  field.oninput = () => { query = field.value;shown = 20;draw();window.apiosk.resize(); };
+  toggles.append(el('legend', 'sr-only', 'Columns shown'));
+  for (const column of columns) {
+    const option = el('label'), box = el('input');box.type = 'checkbox';box.checked = !hidden.has(column.id);
+    box.onchange = () => { box.checked ? hidden.delete(column.id) : hidden.add(column.id);draw();window.apiosk.resize(); };
+    option.append(box, el('span', '', column.label));toggles.append(option);
+  }
+  controls.append(field, toggles);s.append(counts, controls, region, more);draw();
+  return s;
+}
+function barChartBlock(block, analysis) {
+  const figure = el('figure', 'answer-block bar-chart'), bars = block.bars || [], scale = barScale(block), range = (scale.max - scale.min) || 1, zero = (0 - scale.min) / range * 100;
+  const caption = el('figcaption', '', block.title ?? block.value_label), list = el('div', 'bar-list'), more = el('div');
+  if (block.ranking) caption.append(el('span', 'meta block-note', (block.ranking.direction === 'desc' ? 'Highest first, ' : 'Lowest first, ') + rankingScopeLabel(block.ranking.scope) + '.'));
+  figure.setAttribute('aria-label', block.title ?? block.value_label ?? 'Chart');
+  let shown = 10;
+  const draw = () => {
+    list.replaceChildren(...bars.slice(0, shown).map((bar, i) => {
+      const value = typeof bar.fact?.value === 'number' ? bar.fact.value : null, end = value == null ? zero : (value - scale.min) / range * 100;
+      const name = bar.label ?? (bar.label_fact?.value != null ? String(bar.label_fact.value) : 'Bar ' + (i + 1));
+      const row = el('div', 'bar-row'), line = el('div', 'bar-line'), source = blockFactSource(bar.fact, analysis?.source_index, block.collection, bar.row_index ?? i, block.value_pointer);
+      line.append(el('span', 'bar-label', (bar.rank != null ? '#' + bar.rank + ' ' : '') + name), blockFactValue(bar.fact));
+      row.append(line, answerBar(zero, value == null ? null : end));if (source) row.append(source);
+      return row;
+    }));
+    more.replaceChildren(...(shown < bars.length ? [blockMore('Show more bars (' + (bars.length - shown) + ' remaining)', () => { shown += 10;draw(); })] : []));
+  };
+  figure.append(caption, list, more);draw();
+  return figure;
+}
+function answerBar(zero, end) {
+  const track = el('div', 'bar-track'), axis = el('span', 'bar-zero');
+  track.setAttribute('aria-hidden', 'true');axis.setAttribute('style', 'left:' + zero + '%');track.append(axis);
+  if (end != null) { const fill = el('span', 'bar-fill');fill.setAttribute('style', 'left:' + Math.min(zero, end) + '%;width:' + Math.abs(end - zero) + '%');track.append(fill); }
+  return track;
+}
+function genericBlock(block, analysis) {
+  const rows = blockFacts(block), title = block.title ?? String(block.kind || 'block').replace('_', ' '), s = el('section', 'answer-block');
+  s.setAttribute('aria-label', title);s.append(el('h3', 'block-kind', title));
+  if (!rows.length) { s.append(el('p', 'meta', 'No details to show for this ' + String(block.kind || 'block').replace('_', ' ') + '.'));return s; }
+  s.append(blockTable(title + ' facts', ['Field', 'Value', 'Source'], rows.map(row => {
+    const tr = el('tr'), value = el('td'), source = el('td'), origin = blockFactSource(row.fact, analysis?.source_index, row.collection, row.rowIndex, row.relativePointer);
+    value.append(blockFactValue(row.fact));if (origin) source.append(origin);tr.append(el('td', '', row.label), value, source);
+    return tr;
+  })));
+  return s;
+}
+
+export const V2_CARD_BLOCKS = [
+  isBlocksAnswer, factOrigin, sortTableRows, filterTableRows, barScale, rankingScopeLabel, blockLabelOf, blockFacts,
+  renderAnswerBlocks, blockFactValue, blockFactSource, blockCell, blockTable, blockMore, dataTableBlock, barChartBlock, answerBar, genericBlock,
+].map(fn => fn.toString()).join('\n');

package/src/gateway-v2-card-body.mjs

@@ -0,0 +1,259 @@
+// The App's answer reader (app/src/components/discover/answer-view.tsx and
+// app/src/lib/ui/answer.ts), for the card. A source result is drawn as what it
+// is: records as rows, a record's name as its heading, links live, prose as
+// prose. Nothing is summarised or dropped; the readable view contains no JSON.
+// Rules are by key name and shape, never by value. Keep in sync with the App.
+const BODY_NOISE_KEYS = new Set(["id", "uuid", "guid", "objectid", "key", "slug", "hash", "etag", "checksum", "signature", "nonce", "cursor", "pagetoken", "nextpagetoken", "page", "pagenumber", "pagina", "pagesize", "perpage", "resultsperpage", "resultatenperpagina", "offset", "hasmore", "hasnext", "hasnextpage", "nextpage", "prevpage", "previouspage", "contenttype", "mimetype", "charset", "encoding", "statuscode", "httpstatus", "requestid", "traceid", "correlationid", "apiversion", "schemaversion", "typename"]);
+const BODY_LINK_OBJECT_KEYS = new Set(["href", "rel", "type", "title", "name", "method", "templated", "hreflang", "profile", "deprecation"]);
+const BODY_ENVELOPE_KEYS = new Set(["data", "result", "results", "response", "payload", "body", "content", "items", "records", "rows", "list", "output", "value", "values", "fields", "opendatafields"]);
+const BODY_NAME_KEYS = ["sourcename", "name", "title", "headline", "label", "provider", "symbol"];
+const BODY_IMAGE_KEYS = ["sourceimg", "image", "img", "logo", "icon", "avatar", "thumbnail", "picture"];
+const BODY_LINK_KEYS = ["weburl", "url", "link", "href", "website", "site"];
+
+export function bodyIsRecord(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
+export function bodyIsUrl(value) { return /^https?:\/\/\S+$/i.test(String(value).trim()); }
+export function bodyIsImageUrl(value) { return /\.(png|jpe?g|gif|webp|avif|svg)(\?|#|$)/i.test(String(value).trim()); }
+export function bodyAsDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2})?/.test(value)) return null;
+  const at = new Date(value);
+  return Number.isNaN(at.getTime()) ? null : at.toLocaleDateString("en-GB", { day: "numeric", month: "short", year: "numeric" });
+}
+export function bodyLabel(key) {
+  const words = String(key).replace(/^_+/, "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").trim().toLowerCase();
+  return words ? words.charAt(0).toUpperCase() + words.slice(1) : String(key);
+}
+export function bodyHost(url) { try { return new URL(url).host; } catch { return url; } }
+function bodyFlatten(key) { return String(key).replace(/[\s_-]+/g, "").toLowerCase(); }
+export function isNoiseKey(key) {
+  if (BODY_NOISE_KEYS.has(bodyFlatten(key))) return true;
+  const bare = String(key).replace(/^_+/, "");
+  return /[_\-\s](id|ids|uuid|guid|key|hash|token|checksum)$/i.test(bare) || /[a-z0-9](Id|Ids|UUID|Uuid|GUID|Guid|Key|Hash|Token|Checksum)$/.test(bare);
+}
+export function isEmptyValue(value) {
+  if (value === null || value === undefined) return true;
+  if (typeof value === "string") return value.trim() === "";
+  if (Array.isArray(value)) return value.length === 0;
+  if (bodyIsRecord(value)) return Object.keys(value).length === 0;
+  return false;
+}
+function isLinkObject(value) {
+  if (!bodyIsRecord(value)) return false;
+  const keys = Object.keys(value).map(bodyFlatten);
+  return keys.includes("href") && keys.every(key => BODY_LINK_OBJECT_KEYS.has(key));
+}
+export function isLinkPlumbing(value) {
+  if (isLinkObject(value)) return true;
+  if (Array.isArray(value)) return value.length > 0 && value.every(isLinkObject);
+  if (bodyIsRecord(value)) { const values = Object.values(value); return values.length > 0 && values.every(inner => isLinkPlumbing(inner)); }
+  return false;
+}
+/** Plumbing out, but never emptied: a record of only identifiers is drawn whole. */
+export function withoutPlumbing(record) {
+  const kept = Object.entries(record).filter(([key, value]) => !isNoiseKey(key) && !isEmptyValue(value) && !isLinkPlumbing(value));
+  return kept.length ? Object.fromEntries(kept) : record;
+}
+/** Peel `{ data: ... }`-style envelopes while exactly one meaningful key remains. */
+export function unwrapEnvelope(value, limit = 4) {
+  let current = value;
+  for (let i = 0; i < limit; i++) {
+    if (!bodyIsRecord(current)) return current;
+    const entries = Object.entries(current).filter(([key, inner]) => !isNoiseKey(key) && !isEmptyValue(inner) && !isLinkPlumbing(inner));
+    if (entries.length !== 1 || !BODY_ENVELOPE_KEYS.has(bodyFlatten(entries[0][0]))) return current;
+    current = entries[0][1];
+  }
+  return current;
+}
+function readPair(item) {
+  if (!bodyIsRecord(item)) return null;
+  let key = null, value, hasValue = false, children = null;
+  for (const [name, inner] of Object.entries(item)) {
+    const flat = bodyFlatten(name);
+    if (key === null && ["key", "name", "field"].includes(flat) && typeof inner === "string") { key = inner.trim(); continue; }
+    if (!hasValue && ["value", "val"].includes(flat)) { value = inner; hasValue = true; continue; }
+    if (children === null && Array.isArray(inner)) { children = inner; continue; }
+    return null;
+  }
+  if (!key || (!hasValue && children === null)) return null;
+  if (children !== null && children.length > 0) { const nested = pairsToRecord(children); return nested === null ? null : [key, nested]; }
+  return [key, hasValue ? value : null];
+}
+/** A list of `{ key, value }` pairs is one record, e.g. KVK annual accounts. */
+export function pairsToRecord(items) {
+  if (!items.length) return null;
+  const held = new Map();
+  for (const item of items) {
+    const pair = readPair(item);
+    if (!pair) return null;
+    if (held.has(pair[0])) held.get(pair[0]).push(pair[1]); else held.set(pair[0], [pair[1]]);
+  }
+  return Object.fromEntries([...held].map(([key, values]) => [key, values.length === 1 ? values[0] : values]));
+}
+export function isProse(value) {
+  const text = String(value).trim();
+  return !!text && !bodyIsUrl(text) && (text.includes("\n") || text.length > 180);
+}
+/** Headings, paragraphs, bullets and numbered lists; no inline markup. */
+export function readBlocks(text) {
+  const blocks = [];
+  let paragraph = [], items = [], listKind = null;
+  const endParagraph = () => { if (paragraph.length) blocks.push({ kind: "paragraph", text: paragraph.join("\n") }); paragraph = []; };
+  const endList = () => { if (listKind && items.length) blocks.push({ kind: listKind, items }); items = []; listKind = null; };
+  for (const line of String(text).replace(/\r\n?/g, "\n").split("\n")) {
+    if (!line.trim()) { endParagraph(); endList(); continue; }
+    const heading = /^ {0,3}(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+    if (heading) { endParagraph(); endList(); blocks.push({ kind: "heading", text: heading[2], level: Math.min(heading[1].length, 3) }); continue; }
+    const bullet = /^ {0,3}[-*•]\s+(.+)$/.exec(line), numbered = /^ {0,3}\d{1,3}[.)]\s+(.+)$/.exec(line);
+    if (bullet || numbered) {
+      const kind = bullet ? "bullets" : "numbers";
+      endParagraph(); if (listKind !== kind) endList(); listKind = kind; items.push((bullet || numbered)[1].trim()); continue;
+    }
+    endList(); paragraph.push(line.trimEnd());
+  }
+  endParagraph(); endList();
+  return blocks;
+}
+
+// ---- DOM, run inside the card only (uses the card's el/text/window.apiosk) ----
+function answerBody(value) {
+  const body = unwrapEnvelope(displayData(value)), wrap = el("div", "answer-body");
+  if (bodyIsRecord(body) && Array.isArray(body.value) && Object.keys(body).some(key => key.startsWith("@odata."))) {
+    const { value: records, ...metadata } = body, meta = el("details", "body-meta");
+    meta.append(el("summary", "", "Source metadata"), bodyFields(metadata, 0)); meta.ontoggle = () => window.apiosk.resize();
+    wrap.append(bodyNode(records, 0), meta); return wrap;
+  }
+  wrap.append(bodyNode(body, 0)); return wrap;
+}
+function bodyMuted(value) { return el("span", "body-muted", value); }
+function bodyNode(value, depth) {
+  if (value === null || value === undefined) return bodyMuted("null");
+  if (typeof value === "string") return isProse(value) ? bodyProse(value) : bodyScalar(value);
+  if (typeof value === "number" || typeof value === "boolean") return el("span", "body-number", String(value));
+  if (Array.isArray(value)) return bodyList(value, depth);
+  if (bodyIsRecord(value)) return bodyFields(value, depth);
+  return bodyMuted("not shown");
+}
+function bodyTableColumns(items) {
+  if (items.length < 2 || !items.every(bodyIsRecord)) return null;
+  const columns = Object.keys(items[0]);
+  if (!columns.length || columns.length > 10 || columns.some(key => BODY_NAME_KEYS.includes(key.toLowerCase()) || BODY_IMAGE_KEYS.includes(key.toLowerCase()))) return null;
+  return items.every(item => Object.keys(item).length === columns.length && columns.every(key => Object.hasOwn(item, key) && !bodyIsRecord(item[key]) && !Array.isArray(item[key]) && !(typeof item[key] === "string" && isProse(item[key])))) ? columns : null;
+}
+function bodyList(items, depth) {
+  if (!items.length) return bodyMuted("Empty list.");
+  const spelled = pairsToRecord(items);
+  if (spelled) return bodyFields(spelled, depth);
+  const scalars = items.every(item => !bodyIsRecord(item) && !Array.isArray(item));
+  if (scalars && items.some(item => typeof item === "string" && isProse(item))) {
+    const list = el("ul", "body-bullets");
+    for (const item of items) { const li = el("li"); li.append(el("span", "body-dot", "•"), typeof item === "string" ? el("span", "body-prose-item", item) : bodyNode(item, depth + 1)); list.append(li); }
+    return list;
+  }
+  if (scalars) { const list = el("ul", "body-chips"); for (const item of items) { const li = el("li"); li.append(bodyNode(item, depth + 1)); list.append(li); } return list; }
+  const wrap = el("div", "body-list"), columns = bodyTableColumns(items);
+  const draw = all => {
+    const shown = all ? items : items.slice(0, 20), rest = items.length - shown.length, parts = [];
+    if (columns) {
+      const region = el("div", "body-table-wrap"), table = el("table", "body-table"), head = el("tr"), thead = el("thead"), tbody = el("tbody");
+      region.setAttribute("role", "region"); region.setAttribute("aria-label", "Result records"); region.tabIndex = 0;
+      table.append(el("caption", "", items.length + " results"));
+      for (const key of columns) { const th = el("th", "", bodyLabel(key)); th.setAttribute("scope", "col"); head.append(th); }
+      thead.append(head);
+      for (const item of shown) { const tr = el("tr"); for (const key of columns) { const td = el("td"); td.append(bodyNode(item[key], depth + 1)); tr.append(td); } tbody.append(tr); }
+      table.append(thead, tbody); region.append(table); parts.push(region);
+    } else {
+      const list = el("ol", "body-records");
+      for (const item of shown) { const li = el("li"); li.append(bodyIsRecord(item) ? bodyRecord(item, depth + 1) : bodyNode(item, depth + 1)); list.append(li); }
+      parts.push(el("p", "body-count", items.length + (items.length === 1 ? " result" : " results")), list);
+    }
+    if (rest > 0) { const more = el("button", "body-more", "Show " + rest + " more"); more.type = "button"; more.onclick = () => { draw(true); window.apiosk.resize(); }; parts.push(more); }
+    wrap.replaceChildren(...parts);
+  };
+  draw(false);
+  return wrap;
+}
+function bodyRecord(record, depth) {
+  const entries = Object.entries(withoutPlumbing(record)), wrap = el("div", "body-record");
+  const nameKey = entries.find(([key, value]) => typeof value === "string" && BODY_NAME_KEYS.includes(key.toLowerCase()));
+  const imageKey = entries.find(([key, value]) => typeof value === "string" && BODY_IMAGE_KEYS.includes(key.toLowerCase()) && bodyIsUrl(value));
+  const linkKey = entries.find(([key, value]) => typeof value === "string" && BODY_LINK_KEYS.includes(key.toLowerCase()) && bodyIsUrl(value));
+  const rest = entries.filter(([key]) => key !== nameKey?.[0] && key !== imageKey?.[0]);
+  if (nameKey || imageKey) {
+    const head = el("div", "body-record-head"), copy = el("div", "body-record-copy");
+    if (imageKey) head.append(bodyThumb(imageKey[1]));
+    if (nameKey) copy.append(el("p", "body-record-name", nameKey[1]));
+    if (linkKey) copy.append(bodyLink(linkKey[1], bodyHost(linkKey[1])));
+    head.append(copy); wrap.append(head);
+  }
+  if (rest.length) wrap.append(bodyFields(Object.fromEntries(rest), depth));
+  return wrap;
+}
+function bodyFields(record, depth) {
+  const entries = Object.entries(withoutPlumbing(record));
+  if (!entries.length) return bodyMuted("Nothing in it.");
+  const grid = rows => {
+    const dl = el("dl", "body-fields");
+    for (const [key, value] of rows) {
+      const row = el("div", "result-row"), dd = el("dd", "value");
+      dd.append(depth >= 8 && (bodyIsRecord(value) || Array.isArray(value)) ? bodyMuted(bodySummarise(value)) : bodyNode(value, depth >= 8 ? depth : depth + 1));
+      row.append(el("dt", "key", bodyLabel(key)), dd); dl.append(row);
+    }
+    return dl;
+  };
+  if (depth >= 8) return grid(entries);
+  const wrap = el("div", "body-group");
+  const flat = entries.filter(([, value]) => !bodyIsRecord(value) && !Array.isArray(value) && !(typeof value === "string" && isProse(value)));
+  if (flat.length) wrap.append(grid(flat));
+  const prose = entries.filter(([, value]) => typeof value === "string" && isProse(value)), nested = entries.filter(([, value]) => bodyIsRecord(value) || Array.isArray(value));
+  for (const [key, value] of [...prose, ...nested]) {
+    const part = el("section", "body-section");
+    part.append(el("h4", "", bodyLabel(key)), typeof value === "string" ? bodyProse(value) : bodyNode(value, depth + 1));
+    wrap.append(part);
+  }
+  return wrap;
+}
+function bodyProse(value) {
+  const blocks = readBlocks(value), wrap = el("div", "body-prose");
+  if (!blocks.length) return bodyMuted("empty");
+  for (const block of blocks) {
+    if (block.kind === "heading") { wrap.append(el("p", "body-prose-heading", block.text)); continue; }
+    if (block.kind === "paragraph") { wrap.append(el("p", "", block.text)); continue; }
+    const list = el(block.kind === "numbers" ? "ol" : "ul");
+    for (const item of block.items) list.append(el("li", "", item));
+    wrap.append(list);
+  }
+  return wrap;
+}
+function bodyScalar(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return bodyMuted("empty");
+  if (bodyIsUrl(trimmed)) {
+    if (!bodyIsImageUrl(trimmed)) return bodyLink(trimmed, trimmed);
+    const wrap = el("div", "body-image"); wrap.append(bodyThumb(trimmed), bodyLink(trimmed, trimmed)); return wrap;
+  }
+  const when = bodyAsDate(trimmed);
+  if (when) { const span = el("span", "", when); span.title = trimmed; return span; }
+  return el("span", "body-text", trimmed);
+}
+function bodyThumb(src) {
+  const img = el("img", "body-thumb"); img.alt = ""; img.loading = "lazy"; img.decoding = "async"; img.referrerPolicy = "no-referrer";
+  img.onerror = () => img.remove(); img.src = src; return img;
+}
+function bodyLink(href, label) {
+  const a = el("a", "body-link", label); a.href = href; a.target = "_blank"; a.rel = "noopener noreferrer";
+  a.onclick = event => { event?.preventDefault?.(); void window.apiosk.openLink(href); };
+  return a;
+}
+function bodySummarise(value) {
+  if (Array.isArray(value)) return value.length + (value.length === 1 ? " item" : " items");
+  const count = Object.keys(value).length;
+  return count + (count === 1 ? " detail" : " details");
+}
+
+const CONSTANTS = { BODY_NOISE_KEYS, BODY_LINK_OBJECT_KEYS, BODY_ENVELOPE_KEYS };
+export const V2_CARD_BODY = [
+  ...Object.entries(CONSTANTS).map(([name, set]) => `const ${name}=new Set(${JSON.stringify([...set])});`),
+  `const BODY_NAME_KEYS=${JSON.stringify(BODY_NAME_KEYS)},BODY_IMAGE_KEYS=${JSON.stringify(BODY_IMAGE_KEYS)},BODY_LINK_KEYS=${JSON.stringify(BODY_LINK_KEYS)};`,
+  bodyIsRecord, bodyIsUrl, bodyIsImageUrl, bodyAsDate, bodyLabel, bodyHost, bodyFlatten, isNoiseKey, isEmptyValue, isLinkObject, isLinkPlumbing,
+  withoutPlumbing, unwrapEnvelope, readPair, pairsToRecord, isProse, readBlocks,
+  answerBody, bodyMuted, bodyNode, bodyTableColumns, bodyList, bodyRecord, bodyFields, bodyProse, bodyScalar, bodyThumb, bodyLink, bodySummarise,
+].map(value => typeof value === "function" ? value.toString() : value).join("\n");

package/src/gateway-v2-card-budget.mjs

@@ -0,0 +1,21 @@
+// A budget refusal is not an expired login. Open the existing settings without
+// revoking tokens, pretending to reconnect, or approving/replaying the task.
+export const V2_CARD_BUDGET = `
+function renderApprovalRecovery(response,data){
+ const codes=[response?.error_code,...(response?.errors||[]).map(error=>error.code)];
+ if(!codes.some(code=>['approval_per_request_limit','approval_daily_limit'].includes(code)))return;
+ const actions=byId('feedback-actions');
+ let url=null;try{url=trustedShortcut(new URL('/connections',dataApprovalOrigin()).href,'/connections')}catch{}
+ const button=el('button','primary','Set higher limits');button.type='button';
+ const help=el('p','meta','Choose your connection, change its per-request and daily limits, and save. Then return here and check status before approving.');
+ button.onclick=async()=>{
+  if(output!==data){showFeedback('This request was updated. Check status before continuing.','error');return}
+  if(!url||!await window.apiosk.openLink(url).catch(()=>false)){
+   help.textContent='Open Apiosk > Integrations, choose your connection, set higher spending limits and save. Then return here and check status before approving.';
+   window.apiosk.resize();
+  }
+ };
+ actions.append(button,help,el('p','meta','Or reconnect Apiosk in your chatbot and choose higher limits on the connection screen. After reconnecting, ask the question again using the new connection.'));
+ window.apiosk.resize();
+}
+`;

package/src/gateway-v2-card-cbs.mjs

@@ -0,0 +1,56 @@
+// Display only: join the returned CBS codebooks, never substitute missing values.
+export function cbsAnnualView(data, results) {
+  const question = data.context_view?.conversation?.[0]?.question || '';
+  const years = [...new Set(question.match(/\b(?:19|20)\d{2}\b/g) || [])].sort();
+  if (!years.length || years.length > 2) return null;
+  const base = '/odata/v1/CBS/85809NED/';
+  const observations = results.find(r => r.source?.provider === 'cbs-statline' && r.source.path === base + 'Observations');
+  const entity = observations?.subject?.entity_ref;
+  if (!entity) return null;
+  const names = ['Observations', 'MeasureCodes', 'PeriodenCodes', 'BedrijfstakkenBranchesSBI2008Codes', 'BedrijfsgrootteCodes', 'Properties'];
+  const records = names.map(name => results.find(r => r.source?.provider === 'cbs-statline' && r.source.path === base + name && r.subject?.entity_ref === entity));
+  if (records.some(r => !r?.data || r.coverage === 'partial')) return null;
+  const [values, measures, periods, sectors, sizes, properties] = records.map(r => r.data);
+  if (![values, measures, periods, sectors, sizes].every(d => Array.isArray(d.value))) return null;
+  const selected = values.value.filter(r => years.some(year => r.Perioden === year + 'JJ00'));
+  if (!selected.length || years.some(year => !selected.some(r => r.Perioden === year + 'JJ00'))) return null;
+  const rows = [];
+  for (const row of selected) {
+    const measure = measures.value.find(v => v.Identifier === row.Measure);
+    const period = periods.value.find(v => v.Identifier === row.Perioden);
+    const sector = sectors.value.find(v => v.Identifier === row.BedrijfstakkenBranchesSBI2008);
+    const size = sizes.value.find(v => v.Identifier === row.Bedrijfsgrootte);
+    if (!measure?.Title || !measure.Unit || !period?.Title || !sector?.Title || !size?.Title) return null;
+    rows.push({period:period.Title.trim(), measure:measure.Title, unit:measure.Unit,
+      code:row.Measure, value:typeof row.Value === 'number' && Number.isFinite(row.Value) ? row.Value : 'Niet beschikbaar',
+      status:period.Status || 'Niet vermeld', sector:sector.Title, size:size.Title});
+  }
+  rows.sort((a,b) => a.period.localeCompare(b.period) || a.measure.localeCompare(b.measure));
+  const scopes = [...new Set(rows.map(r => r.sector + ' · ' + r.size))];
+  if (scopes.length !== 1) return null;
+  const url = properties.Distributions?.find(d => /^https:\/\/(?:dataportal|opendata)\.cbs\.nl\//.test(d.AccessUrl || ''))?.AccessUrl;
+  return {records, rows, subject:observations.subject.label, scope:scopes[0], title:properties.Title || observations.subject.label,
+    modified:properties.Modified || properties.ModificationDate, retrieved:observations.source.retrieved_at, url};
+}
+
+export const V2_CARD_CBS = `
+${cbsAnnualView.toString()}
+function renderCbsAnnual(view){
+ const s=section(view.subject||view.title);s.classList.add('answer-section');
+ const number=value=>typeof value==='number'?new Intl.NumberFormat('nl-NL',{maximumFractionDigits:6}).format(value):value;
+ const growth=view.rows.filter(r=>r.code==='M004926'&&r.unit==='%'),latest=growth.at(-1);
+ if(latest){s.append(el('p','answer-number',(typeof latest.value==='number'&&latest.value>0?'+':'')+number(latest.value)+(typeof latest.value==='number'?'%':'')));s.append(el('p','answer-caption','Omzet in '+latest.period+' ten opzichte van '+(Number(latest.period)-1)));const previous=growth.at(-2);if(previous)s.append(el('p','meta','In '+previous.period+': '+number(previous.value)+(typeof previous.value==='number'?'%':'')+' ten opzichte van '+(Number(previous.period)-1)))}
+ const states=[...new Set(view.rows.map(r=>r.status))];s.append(el('p','answer-source','CBS StatLine'+(states.length===1?' · '+states[0]:'')));
+ const links=el('div','result-links');if(view.url){const link=el('button','text-action','Bron bekijken');link.onclick=()=>window.apiosk.openLink(view.url);links.append(link)}s.append(links);
+ const full=el('details','compact-details result-details');full.append(el('summary','','Details'));full.ontoggle=()=>window.apiosk.resize();
+ full.append(el('p','meta',view.scope));
+ const wrap=el('div','cbs-table-wrap'),table=el('table','cbs-table'),head=el('tr');for(const label of ['Jaar','Maatstaf','Waarde','Eenheid','Status'])head.append(el('th','',label));const thead=el('thead');thead.append(head);table.append(thead);const body=el('tbody');
+ for(const row of view.rows){const tr=el('tr');for(const value of [row.period,row.measure,number(row.value),row.unit,row.status])tr.append(el('td','',value));body.append(tr)}table.append(body);wrap.append(table);full.append(wrap);
+ if(view.modified)full.append(el('p','meta','CBS bijgewerkt: '+new Date(view.modified).toLocaleDateString('nl-NL')));
+ if(view.retrieved)full.append(el('p','meta','Opgehaald: '+new Date(view.retrieved).toLocaleString('nl-NL')));
+ const raw=el('details','full-result');raw.append(el('summary','','Brongegevens'),el('pre','',JSON.stringify(view.records,null,2)));full.append(raw);s.append(full);
+ if(!latest)full.open=true;
+ return {section:s,details:full,links};
+}
+`;
+

package/src/gateway-v2-card-choices.mjs

@@ -0,0 +1,4 @@
+// Company selection changes only the visible name; entity references stay exact.
+export const V2_CARD_CHOICES = `
+function renderChoices(data){const select=(data.next_actions||[]).find(a=>a.kind==='select_entity'),candidates=data.context_view?.candidates;if(!select||!Array.isArray(candidates)||!candidates.length)return;const s=section('Which company do you mean?');s.classList.add('choice-section');s.setAttribute('role','region');s.setAttribute('aria-label','Choose the right company');s.append(el('p','meta','Choose once to continue within your approved amount.'));const list=el('div','choice-list');for(const c of candidates){const copy=el('span'),name=(c.facts||[]).find(f=>f.type==='company.name');copy.append(el('strong','',formatDisplayText(text(name?.value||c.label))));const identifiers=(c.facts||[]).filter(f=>/kvk|city|country|lei/i.test(f.type)).map(f=>(/kvk/i.test(f.type)?'KVK ':'')+text(f.value));copy.append(el('span','meta',identifiers.join(' · ')));const b=el('button');b.append(copy,el('span','','Select'));b.onclick=()=>callAction(select,{entity_ref:c.entity_ref});list.append(b)}s.append(list)}
+`;

package/src/gateway-v2-card-clarification.mjs

@@ -0,0 +1,25 @@
+export const V2_CARD_CLARIFICATION = `
+function renderInput(data){
+ const action=(data.next_actions||[]).find(a=>a.kind==='supply_input');
+ if(!action){renderClarification(data);return}
+ const schema=action.input_schema?.properties?.value||{},raw=text(action.label).replace(/^Provide\\s+/i,'').trim();
+ const names={'web.query':'Search query','web.source_search_query':'Search query','domain.name':'Website domain','company_registry.kvknummer':'KVK number','company.registration.lei':'LEI code','company.name':'Company name'};
+ const title=schema.title||names[raw]||(raw?pretty(raw):'');
+ if(!title){section('Request details unavailable').append(el('p','notice','The request did not identify the missing detail. Use Check status to reload the saved request.'));return}
+ const s=section(title),form=el('form','field actions'),field=el('input'),b=el('button','quiet','Continue');
+ const message=data.context_view?.clarification?.message||schema.description||(names[raw]==='Search query'?'What should the web search look for?':'Enter the '+title.toLowerCase()+' to continue.');
+ s.append(el('p','meta',message));field.id='requested-input';field.required=true;field.autocomplete='off';field.setAttribute('aria-label',title);
+ field.placeholder=Array.isArray(schema.examples)&&schema.examples.length?'For example: '+text(schema.examples[0]):title;
+ form.append(field,b);form.onsubmit=e=>{e.preventDefault();if(output!==data||busy||!field.value.trim())return;let value=field.value.trim();const type=schema.type;if(type==='integer'||type==='number')value=Number(value);else if(type==='boolean')value=value==='true';return callAction(action,{value})};s.append(form);
+}
+function renderClarification(data){
+ if(data.status!=='needs_input')return;
+ const turn=data.context_view?.conversation?.at(-1),message=data.context_view?.clarification?.message||turn?.reply;
+ const s=section('One detail is needed');s.append(el('p','notice',message||'Add the missing detail in your chat, or check the saved request status.'));
+ if(!message||!turn?.question||!data.state)return;
+ const form=el('form','field actions'),field=el('input'),b=el('button','quiet','Send answer');
+ field.required=true;field.autocomplete='off';field.placeholder='Your answer';field.setAttribute('aria-label','Your answer to the clarification');form.append(field,b);
+ form.onsubmit=async e=>{e.preventDefault();const answer=field.value.trim();if(!answer||busy||output!==data)return;busy=true;b.disabled=true;showFeedback('Updating your request…');try{const next=await window.apiosk.callTool('apiosk_discover',{question:turn.question+'\\n\\nUser clarification: '+answer,state:data.state});acceptResponse(next)}catch(error){showFeedback(error?.message||'Could not send your answer. Check status and try again.','error')}finally{busy=false;b.disabled=false}};
+ s.append(form);
+}
+`;