@apiosk/mcp 1.7.0 → 2.0.0

package/src/source-groups.mjs

@@ -0,0 +1,91 @@
+// Source browsing contract: grouped providers and the /v2/sources output schema.
+//
+// A grouped provider is ONE directory source whose listings are its services.
+// The gateway groups by the stored owner handle (gateway/src/sources.rs
+// GROUPED_PROVIDERS); this copy only words the chatbot contract so a host never
+// counts those services as separate sources. Keep the three copies identical:
+// gateway/src/sources.rs, app/src/lib/domain/source-directory.ts and this file.
+export const GROUPED_PROVIDERS = Object.freeze([
+  Object.freeze({ handle: "pulsenetwork", name: "Pulse Network", description: "Data services published by Pulse Network.", category: "intelligence" }),
+  Object.freeze({ handle: "coinbase-bazaar", name: "Coinbase Bazaar", description: "Third-party pay-per-call services listed in the Coinbase x402 Bazaar. Apiosk buys each call for you from your balance.", category: "marketplace" }),
+]);
+
+const groupedNames = (() => {
+  const names = GROUPED_PROVIDERS.map(provider => provider.name);
+  return names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0];
+})();
+
+/** Tool-description sentence: each grouped provider is one source. */
+export const GROUPED_SOURCES_TOOL_TEXT = `${groupedNames} are each one source with nested services; never count or list those services as separate sources in an overview.`;
+/** Notice sentence carried on every browse result. */
+export const GROUPED_SOURCES_NOTICE = `${groupedNames} are each one source; their nested services are not additional sources.`;
+
+const capabilitySource = {
+  type: "object", additionalProperties: false, required: ["slug", "name"],
+  properties: { slug: { type: "string" }, name: { type: "string" } },
+};
+const capabilityGroup = {
+  type: "object", additionalProperties: false,
+  required: ["slug", "name", "primary_sources", "supplementary_sources"],
+  properties: {
+    slug: { type: "string" }, name: { type: "string" },
+    primary_sources: { type: "array", items: capabilitySource },
+    supplementary_sources: { type: "array", items: capabilitySource },
+  },
+};
+const sourceOutput = {
+  type: "object", additionalProperties: false,
+  properties: {
+    slug: { type: "string" }, provider_slug: { type: ["string", "null"] }, logo_url: { type: ["string", "null"] },
+    name: { type: "string" }, description: { type: "string" }, category: { type: "string" },
+    categories: { type: "array", items: { type: "string" } },
+    service_count: { type: "integer", minimum: 1, description: "Services within this one source; do not count them as separate sources." },
+    matching_service_count: { type: "integer", minimum: 1 },
+    services: { type: "array", items: { type: "object", additionalProperties: false, properties: { slug: { type: "string" }, name: { type: "string" }, description: { type: "string" }, category: { type: "string" } } } },
+    readiness: { type: "object", additionalProperties: true },
+    tags: { type: "array", items: { type: "string" } }, sectors: { type: "array", items: { type: "string" } },
+    endpoint_count: { type: "integer", minimum: 0, description: "Published endpoints in this source, not chatbot tools." },
+    capabilities: { type: "array", items: { type: "string" } }, input_types: { type: "array", items: { type: "string" } },
+    executable_capabilities: { type: "array", items: { type: "string" } },
+    capability_roles: { type: "object", additionalProperties: { type: "string", enum: ["primary", "supplementary"] } },
+  },
+};
+
+/** Output schema of apiosk_sources; `errorFields` are the shared failure fields. */
+export function sourcesOutputSchema(errorFields) {
+  return {
+    type: "object", additionalProperties: false,
+    properties: {
+      protocol_version: { type: "string", const: "2" }, sources: { type: "array", items: sourceOutput },
+      total: { type: "integer", minimum: 0 }, offset: { type: "integer", minimum: 0 },
+      next_offset: { type: ["integer", "null"], minimum: 0 }, categories: { type: "array", items: { type: "string" } },
+      tags: { type: "array", items: { type: "string" } }, sectors: { type: "array", items: { type: "string" } },
+      capabilities: { type: "array", items: { type: "string" } }, notice: { type: "string" }, ...errorFields,
+      capability_groups: { type: "array", items: capabilityGroup },
+      selected_capability: { anyOf: [capabilityGroup, { type: "null" }] },
+    },
+    anyOf: [{ required: ["protocol_version", "sources", "total", "offset", "categories", "tags", "sectors", "capabilities", "notice"] }, { required: ["error_code", "message"] }],
+  };
+}
+
+/** A browse result as the chatbot sees it: no internal readiness fields and the public notice. */
+// A grouped provider lists every member's capabilities: Pulse Network alone
+// carries hundreds. Hosts and models need a readable page, not the index.
+const LISTED_CAPABILITIES = 12;
+const FACET_LIMIT = 200;
+const facet = values => Array.isArray(values) ? values.filter(value => !String(value).startsWith("operation.")).slice(0, FACET_LIMIT) : [];
+
+export function presentSources(result) {
+  const { catalog_total: _catalogTotal, ...publicResult } = result;
+  return { ...publicResult, tags: facet(result.tags), capabilities: facet(result.capabilities),
+    sources: result.sources.map(({ available_in_v2: _available, can_answer_questions: _canAnswer, executable_capabilities: _executable, input_types: _inputs, readiness, capabilities, services, tags, categories, ...source }) => ({ ...source,
+      ...(readiness && { readiness: { contracts: readiness.contracts } }),
+      ...(Array.isArray(capabilities) && { capabilities: facet(capabilities).slice(0, LISTED_CAPABILITIES) }),
+      // A grouped provider carries every member's tags: tens of KB per row.
+      ...(Array.isArray(tags) && { tags: tags.slice(0, LISTED_CAPABILITIES) }),
+      ...(Array.isArray(categories) && { categories: categories.slice(0, LISTED_CAPABILITIES) }),
+      ...(Array.isArray(services) && { services: services.map(service => typeof service.description === "string" ? { ...service, description: service.description.slice(0, 120) } : service) }),
+    })),
+    notice: `Browsing is free. Published sources may have execution or coverage restrictions. Capability groups list primary sources; supplementary sources are optional enrichment. Each source is counted once. ${GROUPED_SOURCES_NOTICE} Apiosk checks the exact question and price before any purchase.`,
+  };
+}

package/src/source-value-format.mjs

@@ -0,0 +1,25 @@
+import { formatDisplayText, formatDisplayNarrative, isLiteralField } from './display-text.mjs';
+// Display formatting only. Raw source JSON remains unchanged.
+export function sourceCurrency(value) {
+  const candidate = typeof value === 'string' ? value : value?.currency ?? value?.currencyCode ?? value?.unit;
+  if (typeof candidate !== 'string') return null;
+  const code = candidate.replace(/^iso4217:/i, '').toUpperCase();
+  return /^(EUR|USD|GBP|CHF|JPY|CAD|AUD|SEK|NOK|DKK)$/.test(code) ? code : null;
+}
+export function formatSourceValue(value, key = '', currency = null, nameContext) {
+  const raw = String(value ?? '');
+  if (isLiteralField(key)) return raw;
+  if (typeof value === 'string') value = formatDisplayText(value, key);
+  const label = String(key).replace(/[\s_.-]/g, '');
+  // Identifiers, calendar years and dates are labels, not amounts.
+  if (/year|date|code|identifier|kvk|postcode|postal|phone|iban/i.test(label) || /(?:^id$|Id$|ID$|Number$|Nummer$)/.test(label)) return raw;
+  if (!/^-?(?:0|[1-9]\d*)(?:\.\d+)?$/.test(raw)) return formatDisplayNarrative(String(value ?? ''), nameContext);
+  const negative = raw.startsWith('-'), unsigned = negative ? raw.slice(1) : raw;
+  const [whole, fraction] = unsigned.split('.');
+  const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',') + (fraction == null ? '' : '.' + fraction);
+  const monetary = /^(Assets|Liabilities|Equity|Receivables|Cash|Property|Provisions|Share|RetainedEarnings|FinancialIncome|IncomeTax|Result|Depreciation|EmployeeBenefits|Operating|GrossMargin|Impairment|SumOfExpenses|Revenue|Profit|Turnover|Amount|Balance|Price|Cost|Tax)/i.test(label);
+  const code = monetary ? sourceCurrency(currency) : null;
+  const symbol = code && ({ EUR: '€', USD: '$', GBP: '£' }[code] || code);
+  return (negative ? '-' : '') + (symbol ? symbol + ' ' : '') + grouped;
+}
+export const V2_SOURCE_VALUE_FORMAT = [sourceCurrency, formatSourceValue].map(fn => fn.toString()).join('\n');

package/src/tool-result.mjs

@@ -0,0 +1,20 @@
+// One shape for every tool result.
+//
+// `structuredContent` is what a client can act on; the text block is what a
+// model reads when the client has no structured channel. Both are always
+// present, and they are always the same object, so an agent never has to guess
+// which one is authoritative.
+
+export function content(value) {
+  const result = {
+    content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }],
+  };
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    result.structuredContent = value;
+  }
+  return result;
+}
+
+export function trimString(value) {
+  return String(value ?? "").trim();
+}

package/src/ui-bridge.mjs

@@ -0,0 +1,185 @@
+// One card, two hosts, and the reason this is a string.
+//
+// A widget in this server has to run in two worlds that disagree about
+// everything except the HTML: OpenAI's Apps SDK injects a `window.openai`
+// object, and MCP Apps (SEP-1865) injects nothing at all and expects the iframe
+// to speak JSON-RPC to its parent over postMessage. Written twice, the two
+// paths drift.
+//
+// So the transport is written once, here, as the source text the card embeds.
+// It is a template string rather than a module because a UI resource is ONE
+// self-contained document: the host renders the HTML in a sandboxed iframe, so
+// there is nothing to import from.
+//
+// What a card gets is four calls and no host detection:
+//
+//   apiosk.onData(fn)          fn(structuredContent) now and on every update
+//   apiosk.callTool(name,args) resolves with the tool's structuredContent
+//   apiosk.openLink(url)       opens outside the iframe, or returns false
+//   apiosk.say(text)           puts a message in the conversation as the user
+//
+// `apiosk.can.callTool` and `apiosk.can.say` say whether the host supports
+// them, because a button that silently does nothing is worse than a button that
+// is not there.
+
+/**
+ * The bridge, as browser source.
+ *
+ * MCP Apps handshake, in order: send `ui/initialize`, then the
+ * `ui/notifications/initialized` notification, then wait for
+ * `ui/notifications/tool-result` — the host delivers the tool's output as a
+ * notification rather than as a global, so a card that only reads a global
+ * renders blank there forever.
+ */
+export const APIOSK_UI_BRIDGE = `
+(()=>{
+const listeners=[],inputListeners=[];let data=null,input=null,dataKey=null,localState=null,pending=new Map(),rpcId=0,mcp=false,host={};
+function applyTheme(theme){if(theme!=='light'&&theme!=='dark')return;document.documentElement.dataset.theme=theme;document.documentElement.style.colorScheme=theme}
+applyTheme(window.openai?.theme);
+// Hosts may resend the original tool snapshot when widget state or layout
+// changes. Replaying it would overwrite a newer in-card tool response and
+// cancel the execution timer immediately after approval.
+function emit(v){if(v==null)return;v=restoredView(v);if(localState?.state_ref===v?.state?.state_ref&&Number(v?.state?.revision)<=Number(localState?.revision))return;if(data?.state?.state_ref&&data.state.state_ref===v?.state?.state_ref&&Number(v.state.revision)<Number(data.state.revision))return;let key;try{key=JSON.stringify(v)}catch(e){}if(key!==undefined&&key===dataKey)return;dataKey=key;data=v;for(const fn of listeners){try{fn(v)}catch(e){}}}
+function emitInput(v){if(v==null)return;input=v;for(const fn of inputListeners){try{fn(v)}catch(e){}}}
+function unwrap(r){if(r&&typeof r==='object'){if(r.structuredContent)return r.structuredContent;
+ if(Array.isArray(r.content))for(const block of r.content){if(block?.type==='text'&&typeof block.text==='string'){try{const value=JSON.parse(block.text);if(value&&typeof value==='object')return value}catch(e){}}}}
+ return r}
+// ---- MCP Apps (SEP-1865): JSON-RPC over postMessage to the host frame -------
+function send(msg){try{window.parent.postMessage(msg,'*')}catch(e){}}
+function rpc(method,params){return new Promise((resolve,reject)=>{const id=++rpcId;
+ const timer=setTimeout(()=>{if(pending.has(id)){pending.delete(id);reject(new Error('timeout'))}},180000);
+ pending.set(id,{resolve,reject,timer});send({jsonrpc:'2.0',id,method,params:params||{}})})}
+window.addEventListener('message',event=>{if(event.source!==window.parent)return;const msg=event.data;
+ if(!msg||msg.jsonrpc!=='2.0')return;
+ if(msg.id!=null&&pending.has(msg.id)){const p=pending.get(msg.id);pending.delete(msg.id);
+  clearTimeout(p.timer);
+  msg.error?p.reject(new Error(msg.error.message||'host error')):p.resolve(msg.result);return}
+ if(msg.method==='ui/notifications/host-context-changed'){applyTheme(msg.params?.theme);return}
+ if(msg.method==='ui/notifications/tool-input'){emitInput(msg.params);return}
+ if(msg.method==='ui/notifications/tool-result'){emit(unwrap(msg.params));return}
+ // A host cancelling its local tool wait does not prove that the durable
+ // Gateway task stopped. Keep the latest task snapshot and its recovery
+ // controls; only a Gateway response may set status=cancelled.
+ if(msg.method==='ui/notifications/tool-cancelled'){return}});
+// ---- OpenAI Apps SDK: globals plus an event ---------------------------------
+function restoredView(raw){const o=window.openai,saved=o?.widgetState?.privateContent?.apioskResult??o?.widgetState?.result;
+ // Keep the last server-returned view for this card across remounts. This is
+ // a display cache only: the card still recovers server state and never starts
+ // a paid step from mounting or from persisted widget state.
+ if(saved?.state?.state_ref&&saved.state.state_ref===raw?.state?.state_ref&&Number(saved.state.revision)>=Number(raw.state.revision))return saved;
+ return raw}
+function openaiData(){const o=window.openai;return o?(o.toolOutput??o.structuredContent??null):null}
+window.addEventListener('openai:set_globals',e=>{const g=e.detail?.globals??e.detail;
+ if(g?.theme)applyTheme(g.theme);
+ if(g&&Object.prototype.hasOwnProperty.call(g,'toolInput'))emitInput(g.toolInput);
+ if(g&&Object.prototype.hasOwnProperty.call(g,'toolOutput'))emit(g.toolOutput)});
+// ---- one surface over both ---------------------------------------------------
+const api={
+ get data(){return data},
+ can:{callTool:false,say:false,openLink:false,purchase:false,autoFollowUp:false},
+ onInput(fn){inputListeners.push(fn);if(input!=null){try{fn(input)}catch(e){}}},
+ onData(fn){listeners.push(fn);if(data!=null){try{fn(data)}catch(e){}}},
+ async callTool(name,args){
+  if(window.openai&&window.openai.callTool)return unwrap(await window.openai.callTool(name,args||{}));
+  if(mcp)return unwrap(await rpc('tools/call',{name,arguments:args||{}}));
+  throw new Error('This host cannot run a tool from the card.')},
+ async openLink(url){
+  try{if(new URL(url).protocol!=='https:')return false}catch{return false}
+  if(window.openai&&window.openai.openExternal){window.openai.openExternal({href:url});return true}
+  if(mcp){try{await rpc('ui/open-link',{url});return true}catch(e){return false}}
+  return false},
+ async say(text){
+  if(window.openai&&window.openai.sendFollowUpMessage){
+   await window.openai.sendFollowUpMessage({prompt:text,scrollToBottom:true});return true}
+  if(mcp){try{const result=await rpc('ui/message',{role:'user',content:[{type:'text',text}]});return !result?.isError}catch(e){return false}}
+  return false},
+  async context(value){
+  // In-card tool responses are newer than the original host snapshot, even
+  // when saving consent did not change the task revision. Explicit server
+  // refreshes still render directly; this guard only rejects host replays.
+  if(value?.state){data=value;localState=value.state;try{dataKey=JSON.stringify(value)}catch(e){}}
+  let stored=false;if(window.openai?.setWidgetState){try{window.openai.setWidgetState({...window.openai.widgetState,modelContent:{status:value?.status,state_ref:value?.state?.state_ref,billing:value?.billing},privateContent:{...window.openai.widgetState?.privateContent,apioskResult:value}});stored=true}catch(e){}}
+  if(mcp&&host.updateModelContext){const summary={status:value?.status,state_ref:value?.state?.state_ref,billing:value?.billing,result:value?.result,errors:value?.errors};let contextText=JSON.stringify(summary);if(contextText.length>24000)contextText=JSON.stringify({status:value?.status,state_ref:value?.state?.state_ref,billing:value?.billing,note:'Read the saved task to retrieve its result.'});await rpc('ui/update-model-context',{content:[{type:'text',text:contextText}],structuredContent:value});return true}
+  return stored},
+ // Cards grow when a list renders. A host sizing an iframe once shows the first
+ // two rows of six and no scrollbar.
+ resize(){const width=Math.ceil(document.documentElement.scrollWidth),height=Math.ceil(document.documentElement.scrollHeight);
+  if(window.openai&&window.openai.notifyIntrinsicHeight){try{window.openai.notifyIntrinsicHeight(height)}catch(e){}}
+  if(mcp)send({jsonrpc:'2.0',method:'ui/notifications/size-changed',params:{width,height}})}};
+window.apiosk=api;
+(async()=>{
+ if(window.openai){api.can={callTool:!!window.openai.callTool,say:!!window.openai.sendFollowUpMessage,openLink:!!window.openai.openExternal,purchase:!!window.openai.callTool,autoFollowUp:!!window.openai.sendFollowUpMessage};emitInput(window.openai.toolInput);emit(openaiData())}
+ if(typeof ResizeObserver!=='undefined')new ResizeObserver(()=>api.resize()).observe(document.documentElement);
+ if(typeof requestAnimationFrame==='function')requestAnimationFrame(()=>api.resize());else setTimeout(()=>api.resize(),0);
+ if(window.parent===window)return;
+ try{
+  const result=await rpc('ui/initialize',{appInfo:{name:'Apiosk',version:'2.0.0'},protocolVersion:'2026-01-26',appCapabilities:{}});
+  mcp=true;host=(result&&result.hostCapabilities)||{};applyTheme(result?.hostContext?.theme);
+  api.can={callTool:!!host.serverTools,say:!!host.message,openLink:!!host.openLinks,purchase:!!host.serverTools&&!/claude/i.test(result?.hostInfo?.name||''),autoFollowUp:!!window.openai?.sendFollowUpMessage&&!/claude/i.test(result?.hostInfo?.name||'')};
+  send({jsonrpc:'2.0',method:'ui/notifications/initialized',params:{}});
+ }catch(e){/* not an MCP Apps host: the OpenAI path above, or nothing */}
+})();
+})();
+`;
+
+/**
+ * The metadata every Apiosk UI resource carries.
+ *
+ * BOTH VOCABULARIES, because the two hosts read different keys for the same
+ * three facts and a resource that answers only one of them renders in only one
+ * of them. The CSP is SET AND EMPTY on purpose: these cards fetch nothing —
+ * no script, style, font, image or endpoint — so the policy permits nothing
+ * outward, and paid provider data reaches the card only as tool output that the
+ * server already fetched.
+ *
+ * @param {string} description  what a reviewer and a host see the card do
+ */
+export function uiResourceMeta(description) {
+  return {
+    ui: {
+      prefersBorder: true,
+      domain: "https://mcp.apiosk.com",
+      csp: { connectDomains: [], resourceDomains: [] },
+    },
+    "openai/widgetCSP": { connect_domains: [], resource_domains: [] },
+    "openai/widgetDomain": "https://mcp.apiosk.com",
+    "openai/widgetPrefersBorder": true,
+    "openai/widgetDescription": description,
+  };
+}
+
+// The App's design tokens (app/src/index.css), both themes. Dark follows the
+// host's data-theme, else the system preference, and swaps the whole set.
+const LIGHT_TOKENS = "color-scheme:light;--background:#fafafa;--background-2:oklch(.975 .004 265);--surface:oklch(1 0 0);--surface-muted:oklch(.965 .005 265);--surface-soft:#f4f4f5;--card:oklch(1 0 0);--foreground:#303036;--heading:#232329;--muted:oklch(.52 .02 265);--faint:oklch(.62 .018 265);--border:#e9e9ed;--border-2:#dddde3;--border-3:oklch(.82 .01 265);--accent:#6349db;--accent-fg:#fff;--accent-line:rgb(99 73 219/.4);--accent-wash:rgb(99 73 219/.07);--accent-wash-strong:rgb(99 73 219/.13);--secondary:oklch(.96 .006 265);--secondary-fg:oklch(.26 .02 265);--button-primary-bg-hover:#553cc5;--button-secondary-bg:oklch(1 0 0);--button-secondary-fg:oklch(.26 .02 265);--input-bg:oklch(1 0 0);--hover:oklch(.21 .02 265/.05);--success-bg:#e8faf1;--success-fg:#057857;--success-border:#c9efdc;--warning-bg:#fdf5e6;--warning-fg:#b26a12;--warning-border:#f2e2c4;--danger-bg:#fff2f4;--danger-fg:#b42318;--danger-border:#fecdd3";
+const DARK_TOKENS = "color-scheme:dark;--background:oklch(.148 .014 265);--background-2:oklch(.172 .014 265);--surface:oklch(.185 .015 265);--surface-muted:oklch(.225 .015 265);--surface-soft:oklch(.258 .015 265);--card:oklch(.185 .015 265);--foreground:oklch(.925 .008 265);--heading:oklch(.975 .004 265);--muted:oklch(.715 .018 265);--faint:oklch(.565 .02 265);--border:rgba(255,255,255,.08);--border-2:rgba(255,255,255,.12);--border-3:rgba(255,255,255,.18);--accent:#c3a0ff;--accent-fg:#25153c;--accent-line:rgb(195 160 255/.45);--accent-wash:rgb(195 160 255/.12);--accent-wash-strong:rgb(195 160 255/.2);--secondary:oklch(.265 .018 265);--secondary-fg:oklch(.93 .008 265);--button-primary-bg-hover:#d2b8ff;--button-secondary-bg:oklch(.225 .015 265);--button-secondary-fg:oklch(.925 .008 265);--input-bg:oklch(.172 .014 265);--hover:rgba(255,255,255,.06);--success-bg:rgba(16,185,129,.14);--success-fg:#6ee7b7;--success-border:rgba(16,185,129,.28);--warning-bg:rgba(251,191,36,.14);--warning-fg:#fbbf24;--warning-border:rgba(251,191,36,.28);--danger-bg:rgba(244,63,94,.14);--danger-fg:#fda4af;--danger-border:rgba(244,63,94,.28)";
+const FONT = weight => `@font-face{font-family:Inter;src:url("https://mcp.apiosk.com/brand/inter-latin-${weight}-normal.woff2") format("woff2");font-style:normal;font-weight:${weight};font-display:swap}`;
+
+/**
+ * Embedded cards follow the chat host, falling back to the system theme.
+ *
+ * The App's type rules: Inter 400 body without letter-spacing, 500 for names
+ * and headings, 600 only at 16px and 24px; four sizes (12/14/16/24); no
+ * uppercase micro-caps; no monospace face. Radii: 6px controls, 8px panels,
+ * 12px cards.
+ */
+export const APIOSK_UI_STYLE = `
+${[400, 500, 600].map(FONT).join("\n")}
+:root{font-family:Inter,ui-sans-serif,system-ui,-apple-system,sans-serif;${LIGHT_TOKENS}}
+:root[data-theme=dark]{${DARK_TOKENS}}
+@media(prefers-color-scheme:dark){:root:not([data-theme=light]){${DARK_TOKENS}}}
+*{box-sizing:border-box}body{margin:0;padding:12px;background:transparent;color:var(--foreground);font-size:14px;line-height:20px;font-weight:400;font-feature-settings:normal;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;text-rendering:optimizeLegibility}
+h1,h2,h3,h4{color:var(--heading);font-weight:500;margin:0}
+pre,code{font:inherit}
+::selection{background:var(--accent-wash-strong);color:var(--heading)}
+:focus-visible{outline:2px solid var(--accent);outline-offset:2px;border-radius:4px}
+.card{border:1px solid var(--border-2);border-radius:12px;padding:16px;background:var(--card);color:var(--foreground)}
+h2{font-size:16px;line-height:24px;font-weight:600;letter-spacing:-.011em}
+.meta,.hint,.status{font-size:12px;line-height:16px;color:var(--muted)}
+.status{margin-top:12px;min-height:16px}.status.error{color:var(--danger-fg)}.status.ok{color:var(--success-fg)}
+button{display:inline-flex;align-items:center;justify-content:center;gap:8px;min-height:36px;border:1px solid var(--border-2);border-radius:6px;padding:0 12px;background:var(--button-secondary-bg);color:var(--button-secondary-fg);font:inherit;font-size:14px;line-height:20px;font-weight:500;cursor:pointer;transition:background-color .15s,color .15s}
+button:hover{background:var(--secondary)}
+.primary{border-color:transparent;background:var(--accent);color:var(--accent-fg)}.primary:hover{background:var(--button-primary-bg-hover)}
+button:disabled{opacity:.5;cursor:not-allowed}
+.actions{display:flex;flex-wrap:wrap;gap:8px;margin-top:16px}
+.hidden{display:none}
+`;

package/src/well-known-routes.mjs

@@ -0,0 +1,132 @@
+// /.well-known/apiosk-routes.json — a served page, not a tool.
+//
+// This is a crawler-facing surface, and it is how agents that never install an
+// MCP server find out that a route exists at all. It reshapes the gateway's own
+// /.well-known/x402 document, which is the canonical one; nothing here is a
+// second source of truth, and nothing here is a capability an agent can call.
+//
+// It survived the earlier cut-to-five refactor for the same reason
+// src/settlement-disclosure.mjs did: it is a page this server serves, not a
+// choice an agent has to make.
+
+import { resolveGatewayBaseUrl } from "./gateway-client.mjs";
+import { trimString } from "./tool-result.mjs";
+
+const DEFAULT_MCP_PUBLIC_BASE_URL = "https://mcp.apiosk.com";
+const CACHE_TTL_MS = 60_000;
+
+/**
+ * Pages the gateway's discovery document is walked in. The gateway caps
+ * `perPage` at 100; asking for it keeps a full catalogue walk to a dozen or so
+ * requests instead of one per fifteen resources.
+ */
+const PAGE_SIZE = 100;
+
+/**
+ * Safety bound on the walk. At the cap this is 5,000 resources — well past the
+ * live catalogue — and it stops a gateway bug that always advertises a `next`
+ * from turning this endpoint into an infinite loop.
+ */
+const MAX_PAGES = 50;
+
+const CAIP2_NETWORK_NAMES = {
+  "eip155:8453": "base",
+  "eip155:137": "polygon",
+  "eip155:42161": "arbitrum",
+  "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": "solana",
+};
+
+let cache = null;
+
+export function clearWellKnownRoutesCache() {
+  cache = null;
+}
+
+function friendlyNetworkName(network) {
+  const value = trimString(network);
+  if (!value) return "base";
+  if (CAIP2_NETWORK_NAMES[value]) return CAIP2_NETWORK_NAMES[value];
+  if (value.startsWith("solana:")) return "solana";
+  return value;
+}
+
+function resolveMcpPublicBaseUrl(env = process.env) {
+  return (trimString(env.APIOSK_MCP_PUBLIC_BASE_URL) || DEFAULT_MCP_PUBLIC_BASE_URL).replace(/\/+$/, "");
+}
+
+export function reshapeDiscoveryItems(wellKnownDocument) {
+  const items = Array.isArray(wellKnownDocument?.items) ? wellKnownDocument.items : [];
+  return items.map((item) => {
+    const offer = Array.isArray(item.accepts) ? item.accepts[0] : null;
+    const metadata = item.metadata && typeof item.metadata === "object" ? item.metadata : {};
+    // x402 v2 calls the atomic amount `amount`; v1 called it
+    // `maxAmountRequired`. Both are USDC 6-decimal atomic units.
+    const atomic = Number.parseInt(trimString(offer?.amount ?? offer?.maxAmountRequired), 10);
+    return {
+      name: metadata.name || metadata.api || undefined,
+      description: metadata.description || undefined,
+      url: item.resource,
+      method: metadata.method || "GET",
+      price: Number.isFinite(atomic)
+        ? (atomic / 1e6).toFixed(6).replace(/0+$/, "").replace(/\.$/, "")
+        : undefined,
+      currency: "USDC",
+      network: friendlyNetworkName(offer?.network),
+      pay_to: offer?.payTo || undefined,
+      x402_version: item.x402Version ?? wellKnownDocument?.x402Version ?? 1,
+    };
+  });
+}
+
+/**
+ * Every item in the gateway's x402 document, following `links.next` to the end.
+ *
+ * The document is paginated (a single response was 7.3 MB and unreadable), so
+ * an endpoint that promises an index of EVERY paid route has to walk it. A
+ * document without `links.next` is treated as complete, which is also what an
+ * older, unpaginated gateway produces.
+ */
+async function fetchAllItems(gateway, doFetch) {
+  // `include=all`: the gateway document publishes managed listings by default,
+  // and this endpoint promises every paid route, federated ones included.
+  let url = `${gateway}/.well-known/x402?perPage=${PAGE_SIZE}&include=all`;
+  let first = null;
+  const items = [];
+
+  for (let page = 0; page < MAX_PAGES && url; page += 1) {
+    const response = await doFetch(url, { headers: { accept: "application/json" } });
+    if (!response.ok) {
+      throw new Error(`Gateway discovery document unavailable (HTTP ${response.status}).`);
+    }
+    const document = await response.json();
+    first = first || document;
+    if (Array.isArray(document.items)) items.push(...document.items);
+
+    const next = document?.links?.next;
+    url = typeof next === "string" && next ? next : null;
+  }
+
+  return { document: first || {}, items };
+}
+
+export async function buildDiscoveryDocument({ env = process.env, fetchImpl } = {}) {
+  if (cache && cache.expiresAt > Date.now()) return cache.document;
+
+  const gateway = resolveGatewayBaseUrl(env);
+  const doFetch = fetchImpl || globalThis.fetch;
+  const { document: wellKnown, items } = await fetchAllItems(gateway, doFetch);
+
+  const routes = reshapeDiscoveryItems({ ...wellKnown, items });
+  const document = {
+    name: "Apiosk paid API routes",
+    description:
+      "Machine-readable index of paid x402 routes published through Apiosk. Each route returns 402 Payment Required with an x402 offer until paid in USDC.",
+    generated_from: `${gateway}/.well-known/x402`,
+    mcp_endpoint: `${resolveMcpPublicBaseUrl(env)}/mcp`,
+    count: routes.length,
+    routes,
+  };
+
+  cache = { document, expiresAt: Date.now() + CACHE_TTL_MS };
+  return document;
+}