@apiosk/mcp 1.3.1 → 2.0.0

package/src/create-server.mjs

@@ -2,36 +2,195 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
-import { createApioskMcpRuntime } from "./runtime.mjs";
+import { createApioskMcpRuntime, resolveGatewayV2Url } from "./runtime.mjs";
+import { V2_INSTRUCTIONS, V2_DESCRIPTION, V2_RESOURCE } from "./gateway-v2.mjs";
+import { APIO_V2_CARD_URI, APIO_V2_CHATGPT_CARD_URI, APIO_V2_CARD_LEGACY_URIS, APIO_V2_MODERN_CARD_URIS, gatewayV2CardHtml, gatewayV2CardMeta } from "./gateway-v2-card.mjs";
+
+/**
+ * One sentence, defined once.
+ *
+ * Registries take a server's description from wherever they can find it: the
+ * server card, `serverInfo`, or by scraping the HTML at the root. So every one
+ * of those surfaces reads this constant, and changing the pitch means changing
+ * it in src/gateway-v2.mjs.
+ */
+export const SERVER_DESCRIPTION = V2_DESCRIPTION;
+
+// Base version, kept in step with the published manifests (package.json etc.).
+export const SERVER_BASE_VERSION = "2.0.0";
+
+// The millisecond timestamp encoded in the first 10 chars of a ULID (Crockford
+// base32). Fly's FLY_MACHINE_VERSION is a ULID that changes on every deploy, and
+// its timestamp is monotonically increasing, which is exactly the "counter"
+// property a version needs. Returns null for anything that is not a ULID.
+function ulidTimestampMs(ulid) {
+  const B32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+  const head = String(ulid || "").toUpperCase().slice(0, 10);
+  if (head.length < 10) return null;
+  let ms = 0;
+  for (const ch of head) {
+    const v = B32.indexOf(ch);
+    if (v < 0) return null;
+    ms = ms * 32 + v;
+  }
+  return ms;
+}
+
+// The version a client reads on `initialize`. It must move on every `fly deploy`
+// so a client that caches tool definitions can tell it is looking at a new build
+// after a redeploy or reconnect. Fly provides no plain release counter, but it
+// does set FLY_MACHINE_VERSION (a ULID) which changes each deploy; its timestamp
+// (in seconds) becomes the patch, so each deploy reads as a strictly newer
+// semver (the patch is respected where build metadata after '+' would be
+// ignored). Falls back to the base version locally; APIOSK_MCP_VERSION pins it.
+export function resolveServerVersion(env = process.env) {
+  const explicit = typeof env.APIOSK_MCP_VERSION === "string" ? env.APIOSK_MCP_VERSION.trim() : "";
+  if (explicit) return explicit;
+  const [major = "2", minor = "0"] = SERVER_BASE_VERSION.split(".");
+  const ms = ulidTimestampMs(env.FLY_MACHINE_VERSION || env.FLY_IMAGE_REF?.split("deployment-")?.[1]);
+  return ms ? `${major}.${minor}.${Math.floor(ms / 1000)}` : SERVER_BASE_VERSION;
+}
+
+/** Transparent brand mark, shared by initialize and the published server card.
+ * SVG follows the host color scheme; PNG fallbacks explicitly name their theme. */
+export const SERVER_ICONS = [
+  {
+    src: "https://mcp.apiosk.com/brand/apiosk-a-20260921.png",
+    mimeType: "image/png",
+    sizes: ["1254x1254"],
+    theme: "light",
+  },
+  {
+    "src": "https://mcp.apiosk.com/brand/mark-20260918.svg",
+    "mimeType": "image/svg+xml",
+    "sizes": [
+      "any"
+    ]
+  },
+  {
+    "src": "https://mcp.apiosk.com/brand/mark-light-20260918.png",
+    "mimeType": "image/png",
+    "sizes": [
+      "512x512"
+    ],
+    "theme": "light"
+  },
+  {
+    "src": "https://mcp.apiosk.com/brand/mark-dark-20260918.png",
+    "mimeType": "image/png",
+    "sizes": [
+      "512x512"
+    ],
+    "theme": "dark"
+  }
+];
 
 export const SERVER_INFO = {
   name: "apiosk-mcp",
-  version: "1.3.1",
+  version: resolveServerVersion(),
+  /**
+   * The word a host puts after "from" on its consent card — "Claude wants to
+   * use Plan a data request from Apiosk". The tool titles carry the verb, so
+   * the server carries only the brand.
+   */
+  title: "Apiosk",
+  description: SERVER_DESCRIPTION,
+  websiteUrl: "https://apiosk.com",
+  icons: SERVER_ICONS,
 };
 
+// Shown to every connecting MCP client/agent as server-level guidance: the
+// Gateway v2 host contract, synced from gateway/contracts/host-instructions.md.
+export const SERVER_INSTRUCTIONS = V2_INSTRUCTIONS;
+
 function resolveRuntime(options = {}) {
   return options.runtime || createApioskMcpRuntime(options);
 }
 
 export async function listApioskTools(options = {}) {
-  return resolveRuntime(options).listTools(options.authInfo);
+  return resolveRuntime(options).listTools();
+}
+
+export function resolveServerPresentation(env = process.env) {
+  return {
+    info: { ...SERVER_INFO, version: resolveServerVersion(env) },
+    description: SERVER_DESCRIPTION,
+    instructions: SERVER_INSTRUCTIONS,
+  };
 }
 
 export function createApioskMcpServer(options = {}) {
   const runtime = resolveRuntime(options);
+  const env = options.env || process.env;
+  const gatewayUrl = resolveGatewayV2Url(env);
+  const cardHtml = gatewayV2CardHtml(gatewayUrl);
+  const cardMeta = gatewayV2CardMeta(gatewayUrl);
   const server = new Server(
-    SERVER_INFO,
-    { capabilities: { tools: {} } }
+    resolveServerPresentation(env).info,
+    // `prompts` is declared because it is implemented, as an empty list.
+    // Leaving it out made prompts/list answer -32601 Method not found, which a
+    // scanner reads as a broken server rather than a server without prompts.
+    {
+      capabilities: { tools: {}, resources: {}, prompts: {} },
+      instructions: SERVER_INSTRUCTIONS,
+    }
   );
 
-  server.setRequestHandler(ListToolsRequestSchema, async (_request, extra) => ({
-    tools: await runtime.listTools(extra.authInfo),
+  /**
+   * The card, and the one MIME question.
+   *
+   * MCP Apps (SEP-1865) reads `text/html;profile=mcp-app` and OpenAI's Apps SDK
+   * reads `text/html+skybridge`. The current card has a separate, stable URI
+   * for each. Only previously issued compatible URIs keep the old
+   * host-dependent label: modern ChatGPT also sends an OpenAI user agent, so
+   * the user agent is not a MIME signal for the new URIs.
+   */
+  const legacyMime = () => (options.legacyUiMime ? "text/html+skybridge" : "text/html;profile=mcp-app");
+  const cardMime = (uri) => uri.endsWith("-chatgpt.html")
+    ? "text/html+skybridge"
+    : APIO_V2_MODERN_CARD_URIS.includes(uri) ? "text/html;profile=mcp-app" : legacyMime();
+
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: [
+      V2_RESOURCE,
+      { uri: APIO_V2_CARD_URI, name: "Apiosk Gateway v2 interactive card", mimeType: "text/html;profile=mcp-app", _meta: cardMeta },
+      { uri: APIO_V2_CHATGPT_CARD_URI, name: "Apiosk card for ChatGPT", mimeType: "text/html+skybridge", _meta: cardMeta },
+      ...APIO_V2_CARD_LEGACY_URIS.map((uri) => ({
+        uri,
+        name: "Apiosk Gateway v2 interactive card (compatible)",
+        mimeType: cardMime(uri),
+        _meta: cardMeta,
+      })),
+    ],
   }));
 
-  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-    return runtime.callTool(request.params.name, request.params.arguments || {}, extra.authInfo);
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+    if (uri === V2_RESOURCE.uri) return { contents: [{ uri, mimeType: V2_RESOURCE.mimeType, text: V2_INSTRUCTIONS }] };
+    if (uri === APIO_V2_CHATGPT_CARD_URI || APIO_V2_MODERN_CARD_URIS.includes(uri) || APIO_V2_CARD_LEGACY_URIS.includes(uri)) {
+      return { contents: [{ uri, mimeType: cardMime(uri), text: cardHtml, _meta: cardMeta }] };
+    }
+    throw new Error("Unknown Apiosk resource");
+  });
+
+  server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [] }));
+
+  server.setRequestHandler(GetPromptRequestSchema, async () => {
+    throw new Error("Use apiosk_discover with your question");
   });
 
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: await runtime.listTools(),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) =>
+    runtime.callTool(request.params.name, request.params.arguments || {}, extra.authInfo)
+  );
+
   return server;
 }

package/src/display-money.mjs

@@ -0,0 +1,20 @@
+// Self-contained: this exact function is also embedded in the chat card.
+// Conversion affects display only, never the amount submitted for approval.
+export function formatDisplayMoney(atomic, currency = 'USD', display = null, ceiling = false) {
+  if (atomic == null || !/^-?\d+$/.test(String(atomic))) return null;
+  currency = !currency || currency === 'USDC' ? 'USD' : currency;
+  let value = BigInt(atomic);
+  if (currency === 'USD' && display?.base_currency === 'USD' && /^[A-Z]{3}$/.test(display.currency || '') && /^\d{1,18}(\.\d{1,18})?$/.test(display.rate || '')) {
+    const [whole, fraction = ''] = display.rate.split('.');
+    const numerator = BigInt(whole + fraction), denominator = 10n ** BigInt(fraction.length);
+    if (numerator > 0n) {
+      const product = value * numerator;
+      const negative = product < 0n, magnitude = negative ? -product : product;
+      const rounding = ceiling && !negative ? denominator - 1n : denominator / 2n;
+      value = (negative ? -1n : 1n) * ((magnitude + rounding) / denominator);
+      currency = display.currency;
+    }
+  }
+  const negative = value < 0n, magnitude = negative ? -value : value;
+  return `${negative ? '-' : ''}${magnitude / 1000000n}.${(magnitude % 1000000n).toString().padStart(6, '0').replace(/0+$/, '').padEnd(2, '0')} ${currency}`;
+}

package/src/display-text.mjs

@@ -0,0 +1,67 @@
+// Keep in sync with App src/lib/ui/display-text.ts.
+const displayAbbreviations = new Set([
+    'BV', 'NV', 'VOF', 'CV', 'LLC', 'LLP', 'PLC', 'AG', 'SA', 'SAS', 'SE', 'ASA',
+    'IT', 'ICT', 'AI', 'IBM', 'ING', 'ABN', 'AMRO', 'ASML', 'KPN', 'TNO',
+    'EU', 'UK', 'US', 'USA', 'NL', 'EUR', 'USD', 'GBP', 'VAT', 'KVK', 'API', 'HTTP', 'HTTPS',
+]);
+/** Technical values stay literal regardless of the response's source or shape. */
+export function isLiteralField(key) {
+    const words = key.replace(/([a-z])([A-Z])/g, '$1 $2').split(/[^a-zA-Z]+/).filter(Boolean);
+    return words.some(word => /^(?:id|ids|code|codes|ref|refs|reference|identifier|identifiers|token|key|hash|signature|url|uri|path|pointer|email|domain|postcode|postal|zip|iban|bic|phone|number|nummer|currency|unit|symbol|method)$/i.test(word));
+}
+/** Shared display rule for human-readable labels and values, independent of answer type. */
+export function formatDisplayText(text, key = '') {
+    if (isLiteralField(key) || text.length > 160 || text !== text.toLocaleUpperCase('nl-NL') || !/\p{L}/u.test(text))
+        return text;
+    if (/[@:/_\n]|\p{L}\d|\d\p{L}/u.test(text) || /^\S+\.[A-Z]{2,}$/u.test(text))
+        return text;
+    if (!/\s/u.test(text) && text.length <= 4)
+        return text;
+    return text.replace(/\p{L}[\p{L}\p{M}]*(?:['’][\p{L}\p{M}]+)*/gu, word => {
+        if (displayAbbreviations.has(word))
+            return word;
+        if (word === 'GMBH')
+            return 'GmbH';
+        return word.charAt(0) + word.slice(1).toLocaleLowerCase('nl-NL');
+    });
+}
+/** A display copy for any nested JSON response. Never modifies the source or its keys. */
+export function displayData(value, key = '', depth = 0) {
+    if (depth > 20 || value == null || isLiteralField(key))
+        return value;
+    if (typeof value === 'string')
+        return formatDisplayText(value, key);
+    if (Array.isArray(value))
+        return value.map(child => displayData(child, key, depth + 1));
+    if (typeof value !== 'object')
+        return value;
+    const record = value;
+    const field = record.key ?? record.field ?? record.type ?? record.factType ?? record.pointer;
+    return Object.fromEntries(Object.entries(record).map(([name, child]) => [name,
+        displayData(child, name === 'value' && typeof field === 'string' ? field : name, depth + 1),
+    ]));
+}
+/** Use the same spelling in prose as in the displayed source values. */
+export function formatDisplayNarrative(text, context) {
+    const replacements = new Map();
+    function collect(raw, shown, depth = 0) {
+        if (depth > 20 || raw == null || shown == null)
+            return;
+        if (typeof raw === 'string' && typeof shown === 'string' && raw !== shown)
+            replacements.set(raw, shown);
+        else if (Array.isArray(raw) && Array.isArray(shown))
+            raw.forEach((value, i) => collect(value, shown[i], depth + 1));
+        else if (typeof raw === 'object' && typeof shown === 'object') {
+            for (const [key, value] of Object.entries(raw))
+                collect(value, shown[key], depth + 1);
+        }
+    }
+    collect(context, displayData(context));
+    if (replacements.size) {
+        const pattern = [...replacements.keys()].sort((a, b) => b.length - a.length).map(value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+        text = text.replace(new RegExp(`(?<![\\p{L}\\p{N}_/@.])(?:${pattern})(?![\\p{L}\\p{N}_/@]|\\.[\\p{L}\\p{N}])`, 'gu'), value => replacements.get(value));
+    }
+    return formatDisplayText(text);
+}
+
+export const DISPLAY_TEXT = ['const displayAbbreviations = new Set(' + JSON.stringify([...displayAbbreviations]) + ');', isLiteralField, formatDisplayText, displayData, formatDisplayNarrative].map(value => typeof value === 'function' ? value.toString() : value).join('\n');

package/src/gateway-client.mjs

@@ -0,0 +1,42 @@
+// Where the agent gateway is, and which token speaks for the buyer.
+//
+// Two small answers the rest of the server shares. The Gateway v2 runtime
+// (src/gateway-v2.mjs) sends the token as a Bearer credential; the hosted
+// OAuth flow (src/oauth.mjs) and the served route index
+// (src/well-known-routes.mjs) read the agent gateway's base URL.
+
+/**
+ * The agent gateway: OAuth (/v1/oauth/*), connect and the skill. Data requests
+ * go to Gateway v2 (src/runtime.mjs), never here.
+ */
+export const DEFAULT_GATEWAY_BASE_URL =
+  "https://api.apiosk.com/functions/v1/agent-gateway";
+
+function trimString(value) {
+  return String(value ?? "").trim();
+}
+
+export function resolveGatewayBaseUrl(env = process.env) {
+  const configured =
+    trimString(env.APIOSK_GATEWAY_URL) ||
+    trimString(env.APIOSK_GATEWAY_BASE_URL) ||
+    trimString(env.APIOSK_BASE_URL);
+  return (configured || DEFAULT_GATEWAY_BASE_URL).replace(/\/+$/, "");
+}
+
+/**
+ * The token that names the buyer to the gateway.
+ *
+ * A request-scoped token (minted for this OAuth session, stashed on
+ * `authInfo.extra` by src/oauth.mjs) always beats the per-process env token:
+ * one server serves many buyers, and the caller's own connection is the only
+ * one allowed to spend. For stdio, `APIOSK_CONNECT_TOKEN` holds an Apiosk agent
+ * token (`apk_access_…` or `apk_live_…`).
+ */
+export function resolveConnectToken(authInfo = null, env = process.env) {
+  return (
+    trimString(authInfo?.extra?.apiosk_connect_token) ||
+    trimString(env.APIOSK_CONNECT_TOKEN) ||
+    ""
+  );
+}

package/src/gateway-v2-ask.mjs

@@ -0,0 +1,50 @@
+// The Ask page's own steps for a connected chatbot. The chatbot fills in the
+// capability object the Ask parser would produce (apiosk_search), then prepares
+// one ranked endpoint with the inputs that endpoint declares (apiosk_prepare).
+// The gateway ranks, prices and quotes; this module only shapes the calls and
+// adds no planner, pricing or balance logic of its own.
+import { randomUUID } from "node:crypto";
+import schemas from "./gateway-v2-contracts.json" with { type: "json" };
+
+export const ASK_TOOLS = Object.freeze(["apiosk_search", "apiosk_prepare"]);
+
+const SEARCH_NOTICE = "Searching is free and buys nothing. Only candidates with availability \"supported\" can run: fill each required endpoint.inputs field from the person's words or earlier results, ask for anything missing, then call apiosk_prepare with that candidate's endpoint_id, capability and input.";
+
+export function askDefinitions(errorFields, taskOutput) {
+  const searchOutput = {
+    type: "object", additionalProperties: false,
+    properties: {
+      protocol_version: { type: "string", const: "2" }, view: { type: "string", const: "source_search" },
+      parsed_request: { type: "object" }, matches: { type: "array", items: { type: "object", additionalProperties: true } },
+      apiosk_sources_searched: { type: "integer", minimum: 0 }, catalog_version: { type: "string" }, notice: { type: "string" }, ...errorFields,
+    },
+    anyOf: [{ required: ["protocol_version", "view", "parsed_request", "matches", "notice"] }, { required: ["error_code", "message"] }],
+  };
+  return [
+    { name: "apiosk_search", title: "Search sources for a capability object",
+      description: "Search Apiosk's sources the way the Ask page does, with a capability object you fill in yourself (parsed_request, following the host instructions' parser rules). Slugs are English dot paths of letters and digits, such as location.time.current. Returns, per capability, the Ask page's ranked sources; each runnable candidate carries endpoint.inputs: the exact input keys, whether each is required, and its value schema for apiosk_prepare. Free: creates no task and buys nothing.",
+      inputSchema: schemas.search, outputSchema: searchOutput, annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false } },
+    { name: "apiosk_prepare", title: "Prepare one source",
+      description: "Prepare one runnable apiosk_search candidate: pass its endpoint_id, capability and an input object whose keys are that candidate's endpoint.inputs fields, filled only from the person's words or earlier results, never placeholders. Returns the same task, price ceiling and approval card as apiosk_discover; nothing is bought until the person approves. Continue with apiosk_execute and apiosk_status.",
+      inputSchema: schemas.prepare, outputSchema: taskOutput, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false } },
+  ];
+}
+
+/** The gateway request for an Ask tool: its exact wire body, nothing extra. */
+export function askRequest(name, args) {
+  if (name === "apiosk_search") {
+    // The gateway records who parsed the object; a chatbot parse has no model hash.
+    const meta = { model: "connected-chatbot", parsed_at: new Date().toISOString(), text_sha256: "" };
+    return { path: "/v2/ask-v2/search", body: { parsed_request: { ...args.parsed_request, meta }, origin: "apiosk" } };
+  }
+  return { path: "/v2/ask-v2/prepare", body: { request_id: args.request_id || randomUUID(), endpoint_id: args.endpoint_id,
+    ...(args.capability && { capability: args.capability }), input: args.input } };
+}
+
+/** The card's source search view (`view: "source_search"`). */
+export function presentSearch(result, parsed) {
+  if (!Array.isArray(result?.matches)) throw new Error("Unexpected protocol");
+  return { protocol_version: "2", view: "source_search", parsed_request: parsed, matches: result.matches,
+    ...(Number.isInteger(result.apiosk_sources_searched) && { apiosk_sources_searched: result.apiosk_sources_searched }),
+    ...(typeof result.catalog_version === "string" && { catalog_version: result.catalog_version }), notice: SEARCH_NOTICE };
+}

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

@@ -0,0 +1,23 @@
+export const V2_ACCOUNT_MARKUP = `<nav class="account-links hidden" id="account-shortcuts" aria-label="Apiosk account shortcuts"><button type="button" id="balance-shortcut">Balance</button><button type="button" id="history-shortcut">History</button></nav>`;
+
+// Workspace scoping and destinations remain Gateway output, never client input.
+// Identity is deliberately not repeated in the embedded request header.
+// Links are limited to the App origin that owns the plan approval and to the
+// two exact read/manage destinations rendered by this card.
+export const V2_CARD_ACCOUNT = `
+function dataApprovalOrigin(){try{return new URL(output?.proposal?.approval_url||'https://app.apiosk.com').origin}catch{return 'https://app.apiosk.com'}}
+function trustedShortcut(value,path){try{const url=new URL(value),approval=dataApprovalOrigin();return url.protocol==='https:'&&url.pathname===path&&!url.username&&!url.password&&(!approval||url.origin===approval)?url.href:null}catch{return null}}
+function renderAccount(data){
+ const bar=byId('account-shortcuts'),workspace=data.context_view?.workspace||data.billing?.workspace;
+ if(!workspace?.workspace_id||workspace.kind==='personal'){
+  for(const id of ['balance-shortcut','history-shortcut']){const button=byId(id);button.classList.add('hidden');button.onclick=null}
+  bar.classList.add('hidden');return
+ }
+ const links=data.context_view?.navigation||{},balance=trustedShortcut(links.balance_url,'/settings/billing'),history=trustedShortcut(links.history_url,'/usage/history');
+ for(const [id,url] of [['balance-shortcut',balance],['history-shortcut',history]]){
+  const button=byId(id);button.classList.toggle('hidden',!url);
+  button.onclick=url?async()=>{if(!await window.apiosk.openLink(url))showFeedback('Open Apiosk to view this account.','error')}:null
+ }
+ bar.classList.toggle('hidden',!balance&&!history)
+}
+`;

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

@@ -0,0 +1,67 @@
+import { approvalFeedback } from './approval-feedback.mjs';
+import { V2_CARD_BUDGET } from './gateway-v2-card-budget.mjs';
+// Runs inside the card: observe consent, then use only gateway-issued actions.
+export const V2_CARD_ACTIONS = `
+let approvalExpiryTimer=null;
+const quoteExpired=data=>Date.parse(data.proposal?.expires_at)<=Date.now();
+${approvalFeedback.toString()}
+const responseMessage=(data,fallback)=>approvalFeedback(data,money,fallback);
+${V2_CARD_BUDGET}
+async function refreshPrice(data,button){
+ if(busy||output!==data)return;
+ busy=true;button.disabled=true;showFeedback('Refreshing the price. No purchase is being made…');
+ try{
+  const fresh=await window.apiosk.callTool('apiosk_status',{task_ref:data.state.state_ref});
+  if(!fresh?.state||fresh.state.state_ref!==data.state.state_ref)throw new Error('Could not recover this request. Check status and try again.');
+  if(!quoteExpired(fresh)||fresh.billing?.authorization_active||(fresh.billing?.executions||[]).length){acceptResponse(fresh);return}
+  const question=fresh.context_view?.conversation?.at(-1)?.question;
+  if(!question)throw new Error('The original question is unavailable. Ask the question again to get a new price.');
+  const next=await window.apiosk.callTool('apiosk_discover',{question,state:fresh.state});
+  acceptResponse(next);
+  if(next?.proposal&&!quoteExpired(next))showFeedback('Price refreshed. Review the plan and click Approve to continue.');
+ }catch(e){showFeedback(e&&e.message||'Could not refresh the price. Check status and try again.','error')}
+ finally{busy=false;button.disabled=false}
+}
+async function refreshTask(publish=true){if(busy||!output?.state?.state_ref)return;const before=output;if(publish)busy=true;try{const next=await window.apiosk.callTool('apiosk_status',{task_ref:before.state.state_ref});if(!next?.state||next.state.state_ref!==before.state.state_ref)throw new Error(next?.message||'Could not recover this request. Use Check status to try again.');if(publish)acceptResponse(next);else if(!busy&&output===before&&next?.state?.state_ref===before.state.state_ref&&Number(next.state.revision)>=Number(before.state.revision)){render(next);void window.apiosk.context(next).catch(()=>{})}return true}catch(e){if(publish)showFeedback(e&&e.message||'Could not refresh this request. Use Check status to try again.','error')}finally{if(publish)busy=false}}
+async function approvePlan(data,button){
+ if(busy)return;
+ if(output!==data){showFeedback('This request was updated. Use the current plan below.','error');return}
+ if(quoteExpired(data)){render(data);showFeedback('This quote expired. Click Get new price, then review and approve the refreshed plan.','error');return}
+ busy=true;button.disabled=true;showFeedback('Saving your approval…');let refusal=null;
+ try{
+  const next=await window.apiosk.callTool('apiosk_approve',{state:data.state,quote_ref:data.proposal.quote_ref,max_total_atomic:data.proposal.max_total_atomic});
+  if(!next?.state||next.state.state_ref!==data.state.state_ref||!next.billing?.authorization_active||next.billing.quote_ref!==data.proposal.quote_ref||next.proposal?.max_total_atomic!==data.proposal.max_total_atomic){refusal=next;throw new Error(responseMessage(next,'Approval was not confirmed. Check status before continuing.'))}
+  watchUntil=Date.now()+300000;acceptResponse(next);
+ }catch(e){
+  watchUntil=0;showFeedback(e&&e.message||'Approval could not be confirmed. Check status before continuing.','error');renderApprovalRecovery(refusal,data);
+ }finally{busy=false;button.disabled=false}
+}
+function renderActions(data){
+ if(approvalExpiryTimer){clearTimeout(approvalExpiryTimer);approvalExpiryTimer=null}
+ const server=data.context_view?.execution_mode==='server';
+ const actions=data.next_actions||[],run=actions.find(a=>a.kind==='execute_quoted_step')||(server&&!data.context_view?.worker_active?actions.find(a=>a.kind==='poll'):null),poll=actions.find(a=>a.kind==='poll'),read=data.result||data.context_view?.results?.length?[]:actions.filter(a=>a.kind==='read_result'),cancel=actions.find(a=>a.kind==='cancel');
+ const approved=data.billing&&data.billing.authorization_active&&data.billing.quote_ref===(data.proposal&&data.proposal.quote_ref),enabled=data.context_view?.execution_enabled!==false;
+ if(run&&planSurface){
+  const wrap=el('div','actions plan-actions');
+  if(!approved&&enabled&&data.proposal?.approval_url){
+   const b=el('button','primary','Approve up to '+money(data.proposal.max_total_atomic,data.proposal.currency,true));
+   if(quoteExpired(data)){b.disabled=true;b.textContent='Quote expired — request a new price';const renew=el('button','primary','Get new price');renew.onclick=()=>refreshPrice(data,renew);wrap.append(renew)}
+   else{const remaining=Date.parse(data.proposal.expires_at)-Date.now();if(Number.isFinite(remaining)&&remaining>=0)approvalExpiryTimer=setTimeout(()=>{approvalExpiryTimer=null;if(output===data&&!busy){render(data);showFeedback('This quote expired. Get a new price to continue.')}},Math.min(remaining+1,2147483647))}
+   b.onclick=data.context_view?.approval_mode==='chatbot'?()=>approvePlan(data,b):async()=>{if(busy)return;watchUntil=Date.now()+300000;const opened=await window.apiosk.openLink(data.proposal.approval_url);showFeedback(opened?'Approve in Apiosk. This card will continue automatically.':'Open Apiosk to approve this request.',opened?'':'error');if(opened)await refreshTask()};wrap.append(b);
+  }else if(approved&&enabled&&server){
+   if(!attempted.has(run.action_id)){attempted.add(run.action_id);pollTimer=setTimeout(()=>{pollTimer=null;callAction(run)},0)}else{wrap.append(actionButton(run,'Resume request',true))}
+  }else if(approved&&enabled&&Date.now()<watchUntil){
+   if(attempted.has(run.action_id)||(data.errors||[]).length)wrap.append(actionButton(run,'Retry approved step',true));else wrap.append(el('span','notice','Approved. Continuing your request…'));
+   if(!attempted.has(run.action_id)&&!(data.errors||[]).length){pollTimer=setTimeout(()=>{pollTimer=null;if(busy)return;attempted.add(run.action_id);callAction(run)},350)}
+  }else if(approved&&enabled){
+   const b=el('button','primary','Continue approved request');b.onclick=()=>{watchUntil=Date.now()+300000;return refreshTask()};wrap.append(b);
+  }
+  if(data.state?.state_ref&&!server){const refresh=el('button','quiet','Check status');refresh.onclick=()=>{watchUntil=Date.now()+300000;return refreshTask()};wrap.append(refresh)}
+  if(wrap.children.length)planSurface.append(wrap);
+  if(!approved&&enabled&&Date.now()<watchUntil&&Date.parse(data.proposal?.expires_at)>Date.now())pollTimer=setTimeout(()=>{pollTimer=null;refreshTask()},2000);
+ }
+ if(poll&&!server){const wait=Math.max(350,Number(data.retry_after_ms)||900);pollTimer=setTimeout(()=>{pollTimer=null;callAction(poll)},wait)}
+ if(!(data.status==='succeeded'&&!data.context_view?.worker_active&&!(data.errors||[]).length)&&(data.state?.state_ref||read.length||poll||(!server&&cancel))){const s=el('section','section controls'),wrap=el('div','actions');sections.append(s);if(data.state?.state_ref){const check=el('button','quiet','Check status');check.onclick=()=>refreshTask();wrap.append(check)}if(read.length){const view=el('button','quiet','View saved result');view.onclick=()=>refreshTask();wrap.append(view)}if(cancel&&(run||poll||data.context_view?.worker_active))wrap.append(actionButton(cancel,'Cancel request'));s.append(wrap)}
+}
+
+`;

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

@@ -0,0 +1,130 @@
+import { formatDisplayText, formatDisplayNarrative, isLiteralField } from './display-text.mjs';
+import { sourceCurrency } from './source-value-format.mjs';
+import { readBlocks } from './gateway-v2-card-body.mjs';
+// The App's answer text (app/src/lib/domain/gateway-v2-answer.ts and
+// answer-format.ts): every observation, period headings, source notes, every
+// specific limitation and the follow-up question. Display only; the saved
+// analysis and its evidence stay unchanged. Keep in sync with the App.
+const ANSWER_GENERIC_LIMITATIONS = new Set([
+  'Some requested source calls did not return usable data. This analysis is incomplete.',
+  'Some source information is unavailable. The answer uses the available results.',
+  'The returned source response contains no usable records for this question. No finding can be supported from it.',
+]);
+const ANSWER_PERIOD_KEYS = ['fiscal_year', 'financial_year', 'year', 'fiscalYear', 'financialYear', 'period_end', 'periodEnd', 'fiscal_year_end', 'financialYearEnd', 'reporting_year', 'date_fin_exercice'];
+
+function answerRecord(value) { return value && typeof value === 'object' && !Array.isArray(value) ? value : {}; }
+export function answerLocale(question, analysis) {
+  const text = (analysis?.observations || []).map(o => o?.text || '').join(' ') || question || '';
+  const dutch = text.match(/\b(de|het|een|zijn|voor|van|heeft|bedraagt|jaarrekening|omzet|winst|volgens|toont|werden)\b/gi) ?? [];
+  return dutch.length >= 2 ? 'nl-NL' : 'en-US';
+}
+/** The App's formatSourceValue, with its locale: Dutch groups with dots. */
+export function answerValue(value, key = '', currency = null, locale = 'en-US') {
+  const raw = String(value ?? '');
+  if (isLiteralField(key)) return raw;
+  if (typeof value === 'string') value = formatDisplayText(value, key);
+  const label = String(key).split('/').at(-1).replace(/[\s_.-]/g, '');
+  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 ?? ''));
+  const negative = raw.startsWith('-'), unsigned = negative ? raw.slice(1) : raw, [whole, fraction] = unsigned.split('.'), dutch = locale.startsWith('nl');
+  const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, dutch ? '.' : ',') + (fraction == null ? '' : (dutch ? ',' : '.') + fraction);
+  const monetary = /^(?:(?:total|net|gross))?(Assets|Liabilities|Equity|Receivables|Cash|Property|Provisions|Share|RetainedEarnings|FinancialIncome|Income|Result|Depreciation|EmployeeBenefits|Operating|GrossMargin|Impairment|SumOfExpenses|Revenue|Profit|Turnover|Amount|Balance|Price|Cost|Tax|Bedrag|Omzet|Winst|Kosten)/i.test(label) && !/ratio|percent|rate|count|margin|sharesoutstanding|sharesissued/i.test(label);
+  const code = monetary ? sourceCurrency(currency) : null, symbol = code && ({ EUR: '€', USD: '$', GBP: '£' }[code] || code);
+  return (negative ? '-' : '') + (symbol ? symbol + ' ' : '') + grouped;
+}
+/** Units and periods next to the exact cited field, never from another result. */
+export function answerValueContext(evidence, results) {
+  const pointer = String(evidence?.pointer || ''), doc = (results || []).map(answerRecord).find(d => d.result_ref === evidence?.result_ref), parents = [];
+  let node = doc && { ...doc, data: doc.data ?? doc.preview_data };
+  for (const part of pointer.split('/').slice(1)) {
+    if (!Array.isArray(node)) parents.unshift(answerRecord(node));
+    node = node != null && typeof node === 'object' ? node[part.replaceAll('~1', '/').replaceAll('~0', '~')] : undefined;
+  }
+  const currencyOwner = parents.find(p => p.currency != null || p.currencyCode != null || p.unit != null);
+  const period = parents.flatMap(p => ANSWER_PERIOD_KEYS.map(k => p[k])).find(v => /^(?:19|20)\d{2}(?:-\d{2}-\d{2})?$/.test(String(v)));
+  return { currency: sourceCurrency(currencyOwner), period: period == null ? null : String(period), field: String(parents[0]?.key ?? pointer.split('/').at(-1) ?? '') };
+}
+export function formatAnswerObservation(observation, results, locale) {
+  const values = new Map(), evidence = Array.isArray(observation.evidence) ? observation.evidence : [];
+  for (const item of evidence) {
+    const raw = String(item?.value);
+    if (!/^-?(?:0|[1-9]\d*)(?:\.\d+)?$/.test(raw)) continue;
+    const context = answerValueContext(item, results), field = item.field ?? context.field, pointer = String(item.pointer || ''), parent = pointer.slice(0, pointer.lastIndexOf('/'));
+    const currency = context.currency ?? sourceCurrency(evidence.find(e => e?.result_ref === item.result_ref && e.pointer === parent + '/currency')?.value);
+    const display = answerValue(item.value, field, currency, locale), previous = values.get(raw);
+    values.set(raw, values.has(raw) && previous?.display !== display ? null : { display, currency });
+  }
+  const codes = 'EUR|USD|GBP|CHF|JPY|CAD|AUD|SEK|NOK|DKK';
+  const pattern = new RegExp(`(?<![\\p{L}\\p{N}_/@.:$€£+\\-])(?:(${codes}|[$€£])\\s*)?(-?(?:0|[1-9]\\d*)(?:\\.\\d+)?)(?:\\s*(${codes})(?!\\p{L}))?(?![\\p{L}\\p{N}_/@]|[.:,\\-]\\d)`, 'gu');
+  return String(observation.text).replace(pattern, (match, prefix, raw, suffix) => {
+    const value = values.get(raw);
+    if (!value) return match;
+    const explicit = prefix ?? suffix;
+    if (!explicit) return value.display;
+    const code = { '$': 'USD', '€': 'EUR', '£': 'GBP' }[explicit] ?? explicit;
+    return value.currency && value.currency !== code ? match : answerValue(raw, 'Amount', code, locale);
+  });
+}
+/** A heading may name only a period this observation actually cites. */
+export function observationPeriod(observation, results) {
+  const periods = (observation.evidence || []).flatMap(e => {
+    const key = String(e?.field ?? e?.pointer ?? '').split('/').at(-1) ?? '';
+    if (ANSWER_PERIOD_KEYS.some(k => k.toLowerCase() === key.toLowerCase()) && /^(?:19|20)\d{2}(?:-\d{2}-\d{2})?$/.test(String(e.value))) return [String(e.value)];
+    const context = answerValueContext(e, results);
+    return context.period ? [context.period] : [];
+  });
+  const unique = [...new Set(periods)];
+  return unique.length === 1 ? unique[0] : null;
+}
+export function answerText(analysis, context) {
+  if (!analysis) return '';
+  const question = context?.question || '', results = context?.results || [], locale = answerLocale(question, analysis), nl = locale === 'nl-NL';
+  const observations = (analysis.observations || []).filter(o => typeof o?.text === 'string' && o.text.trim());
+  const limitations = (analysis.limitations || []).filter(text => typeof text === 'string' && text.trim() && !ANSWER_GENERIC_LIMITATIONS.has(text));
+  const structured = observations.length > 1 && !/\b(one sentence|single sentence|één zin|een zin)\b/i.test(question);
+  const blocks = [];
+  let previousHeading = null;
+  for (const observation of observations) {
+    if (structured) {
+      const period = observationPeriod(observation, results);
+      const heading = period ? (nl ? 'Verslagperiode ' : 'Reporting period ') + period : nl ? 'Belangrijkste bevindingen' : 'Key findings';
+      if (heading !== previousHeading) blocks.push('## ' + heading);
+      previousHeading = heading;
+    }
+    blocks.push(formatAnswerObservation(observation, results, locale));
+  }
+  if (limitations.length) {
+    if (observations.length) blocks.push('## ' + (nl ? 'Bronnen en beperkingen' : 'Source notes'));
+    blocks.push(...new Set(limitations));
+  }
+  if (analysis.follow_up_question) blocks.push(analysis.follow_up_question);
+  return blocks.length ? blocks.join('\n\n') : [...new Set((analysis.limitations || []).filter(text => typeof text === 'string'))].join('\n\n');
+}
+export function answerDocumentRequested(analysis, question) {
+  return analysis?.presentation?.kind === 'document' || /\b(document|pdf|rapport|report|dossier)\b/i.test(question || '');
+}
+
+// ---- DOM, run inside the card only --------------------------------------------
+function answerInline(node, value) {
+  const parts = String(value).split(/(-?(?:[$€£]|USD|EUR|GBP|CHF|JPY|CAD|AUD|SEK|NOK|DKK)\s-?\d[\d.,]*)/g);
+  if (parts.length === 1) { node.textContent = value; return node; }
+  parts.forEach((part, index) => { if (part) node.append(el(index % 2 ? 'strong' : 'span', index % 2 ? 'answer-amount' : '', part)); });
+  return node;
+}
+/** The App's StreamingReply, settled: headings, paragraphs and lists. */
+function renderAnswerText(value, nameContext) {
+  const wrap = el('div', 'answer-text');
+  for (const block of readBlocks(formatDisplayNarrative(value, nameContext))) {
+    if (block.kind === 'heading') { wrap.append(el('h3', 'answer-heading', block.text)); continue; }
+    if (block.kind === 'paragraph') { wrap.append(answerInline(el('p'), block.text)); continue; }
+    const list = el(block.kind === 'numbers' ? 'ol' : 'ul');
+    for (const item of block.items) list.append(answerInline(el('li'), item));
+    wrap.append(list);
+  }
+  return wrap;
+}
+
+export const V2_CARD_ANSWER_TEXT = [
+  `const ANSWER_GENERIC_LIMITATIONS=new Set(${JSON.stringify([...ANSWER_GENERIC_LIMITATIONS])}),ANSWER_PERIOD_KEYS=${JSON.stringify(ANSWER_PERIOD_KEYS)};`,
+  answerRecord, answerLocale, answerValue, answerValueContext, formatAnswerObservation, observationPeriod, answerText, answerDocumentRequested, answerInline, renderAnswerText,
+].map(value => typeof value === 'function' ? value.toString() : value).join('\n');