hermoso 0.1.531 → 0.1.533

package/README.md

@@ -24,8 +24,12 @@ campaigns behind them, all over [MCP](https://modelcontextprotocol.io) tools, a
 
 ## Set up in Claude, ChatGPT or Cursor
 
-**Claude (claude.ai, Claude Desktop):** Customize → Connectors → Add → *Add custom connector*, paste the URL
-below, choose **Sign in now** under Authentication, then Add and Connect.
+**Claude (claude.ai, Claude Desktop):** one click. **[Add to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Hermoso&connectorUrl=https%3A%2F%2Fapp.hermoso.ai%2Fmcp%3Fsrc%3Dreadme)**
+opens Claude's *Add custom connector* dialog with Hermoso already filled in. Press Continue, choose **Sign in now**
+if Claude asks about Authentication, then sign in with your Hermoso account.
+
+By hand: Customize → Connectors → Add → *Add custom connector*, paste the URL below, choose **Sign in now** under
+Authentication, then Add and Connect. On a Team or Enterprise plan an Owner adds it for the organization first.
 
 ```text
 https://app.hermoso.ai/mcp
@@ -67,7 +71,7 @@ Ask in your own words. The agent picks the tools:
 - "Compare last week's Google Ads and Meta Ads results and tell me what to pause."
 - "Schedule this video to TikTok, Instagram Reels and YouTube Shorts for Tuesday at 9am."
 
-**1198 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
+**1231 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
 catalog with exact per-render credit costs plus the full capability map.
 
 **No markup on models** on Starter, Pro and Studio. Stop overpaying markups on AI models. Plans: [hermoso.ai/pricing](https://hermoso.ai/pricing).
@@ -242,7 +246,10 @@ the routes.
 
 ## Instant: the hosted Claude.ai connector
 
-Paste **`https://app.hermoso.ai/mcp?src=readme`** into Claude → Customize → Connectors → Add → *Add custom connector*,
+**[Add to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Hermoso&connectorUrl=https%3A%2F%2Fapp.hermoso.ai%2Fmcp%3Fsrc%3Dreadme)** opens Claude with the connector already filled in: press Continue, sign in with your
+Hermoso account, and you are done.
+
+By hand: paste **`https://app.hermoso.ai/mcp?src=readme`** into Claude → Customize → Connectors → Add → *Add custom connector*,
 press Continue, choose **Sign in now** under Authentication (Claude's detector pre-selects "No sign-in" because our
 discovery handshake is open, and with that your first request comes back "Authentication required"), press Add and
 Connect, approve with your Hermoso account, and you are done: the full toolset with your saved brand context, billed to your plan.
@@ -304,7 +311,7 @@ block entirely if you signed in above; it is there for CI, where the process can
 
 Then ask your agent: *“Generate an image ad with Hermoso.”*
 
-### What the 1198 tools cover
+### What the 1231 tools cover
 
 **Ad spy / research** — `find_competitors`, `competitor_teardown`, `pull_competitor_ads`, `research_ads`; the
 Meta / Google / LinkedIn ad libraries (`search_meta_ads`, `search_google_ads`, `search_linkedin_ads`); organic

package/mcp/arg-guard.mjs

@@ -71,11 +71,17 @@ export function declaredArgKeys(schema) {
   return null;
 }
 
-/** The keys of `args` the schema does not declare (host `_` metadata excluded). [] when there are none or none can be judged. */
+// META ARGUMENTS (2026-11-11, spend-guard.mjs): accepted on EVERY tool without being in its schema, never "unknown".
+// `context` is the user's goal in one sentence, for analytics only; declared once (on call_tool) instead of on 1,200
+// schemas, so it costs the roster nothing. The guard lifts it onto the parsed arguments under CONTEXT_SYM, because the
+// SDK's own parse strips any key the schema does not declare.
+export const META_ARGS = Object.freeze(['context']);
+export const CONTEXT_SYM = Symbol.for('hermoso.agentContext');
+/** The keys of `args` the schema does not declare (host `_` metadata and META_ARGS excluded). [] when there are none or none can be judged. */
 export function unknownArgs(declared, args) {
   if (!Array.isArray(declared) || !args || typeof args !== 'object' || Array.isArray(args)) return [];
   const known = new Set(declared);
-  return Object.keys(args).filter((k) => !known.has(k) && !k.startsWith('_'));
+  return Object.keys(args).filter((k) => !known.has(k) && !k.startsWith('_') && !META_ARGS.includes(k));
 }
 
 function lev(a, b) {

package/mcp/chatgpt-roster.mjs

@@ -1,7 +1,8 @@
 // GENERATED by tools/chatgpt-roster-rank.mjs. Do not edit by hand: re-run the tool (it ranks by the committed usage in
 // tools/lib/chatgpt-roster-usage.json). The provider families ChatGPT lists, best first; a family is all or nothing.
 // The core (every tool that needs no connection) is always listed and is not in these lists. Cap: CHATGPT_TOOL_CAP
-// (950) in mcp/tools.mjs, under ChatGPT's own 1,000-tool limit.
+// (1000) in mcp/tools.mjs, under ChatGPT's own 1,000-tool limit; the families get that minus the room
+// the ChatGPT extension tools take (CHATGPT_EXT_TOOL_ROOM), because those tools are on the same list.
 export const CHATGPT_ROSTER_FAMILIES = Object.freeze([
   'google_drive', // long tail, pinned (plugin skills)
   'intercom', // long tail, pinned (plugin skills)
@@ -49,4 +50,4 @@ export const CHATGPT_ROSTER_LEFT_OUT = Object.freeze([
   'vercel', // long tail
   'whop', // long tail
 ]);
-export const CHATGPT_ROSTER_META = Object.freeze({ cap: 950, usageCollectedAt: "2026-11-03T20:25:36.816Z" });
+export const CHATGPT_ROSTER_META = Object.freeze({ cap: 1000, usageCollectedAt: "2026-11-03T20:25:36.816Z" });

package/mcp/client.mjs

@@ -124,6 +124,14 @@ function headers(extra = {}) {
   // reliable discriminator here. Forgeable, and harmlessly so: the worst a caller achieves is under-reporting
   // their own activity, which is why this decides bookkeeping and nothing else.
   if (ctx) h['x-hermoso-inproc'] = '1';
+  // WHICH HOST THE PERSON IS IN, FOR A REFUSAL ONLY (2026-11-12, lib/buy-page.mjs). A hosted session remembers its client
+  // (mcp/http.mjs rememberedClient); a ChatGPT one is named here so the server can mail the out-of-credits note in ~10
+  // minutes, since nothing can be bought inside ChatGPT. Forgeable and harmless: the worst a caller does is hurry its own email.
+  if (ctx && /openai|chatgpt/i.test(String(ctx.client || ''))) h['x-hermoso-host'] = 'chatgpt';
+  // A PRICE QUOTE AND THE AGENT'S STATED GOAL (2026-11-11, spend-guard.mjs): get_cost / expected_credits run the tool's own
+  // handler with every request marked as a quote (the server stops each spending point and prices it); `context` rides
+  // as one redacted, percent-encoded sentence the server puts on the ledger row of whatever the call bills.
+  { const st = toolCtx.getStore(); if (st?.quoteOnly) h['x-hermoso-quote'] = '1'; if (st?.contextHeader) h['x-hermoso-context'] = st.contextHeader; }
   if (process.env.EDGE_SECRET) h['x-edge-auth'] = process.env.EDGE_SECRET; // belt: in-process self-calls satisfy the edge shield even if the loopback exemption ever changes
   // THE SAME RULE FOR THE BEARER (2026-09-23). This read `ctx?.token || TOKEN`, so a hosted request whose ctx carried
   // no token would have been sent with the SERVER process's own HERMOSO_TOKEN — an operator credential standing in for
@@ -149,17 +157,29 @@ export function signInMessage(status, body, msg, isSignedOut = signedOut()) {
   return /^sign in to continue\.?$/i.test(String(msg || '').trim()) ? SIGN_IN_HINT : `${msg} ${SIGN_IN_HINT}`;
 }
 
+// A PRICE QUOTE'S STOP (2026-11-11, spend-guard.mjs): the server answers a request made in quote mode, at the point it would
+// have spent, with 409 {code:'quote_only', quote:{legs}}. The legs join the running call's tally and the call stops here;
+// wrap() turns the tally into the price. `_quoteStop` is never reported as an error.
+export const QUOTE_STOP_MESSAGE = 'Price quote only: nothing ran and nothing was charged.';
+export const quoteStopError = () => Object.assign(new Error(QUOTE_STOP_MESSAGE), { _quoteStop: true, status: 409, _viaApi: true });
+function quoteStopFrom(status, body) {
+  if (Number(status) !== 409 || body?.code !== 'quote_only') return;
+  const st = toolCtx.getStore();
+  if (st?.quoteOnly) for (const l of (Array.isArray(body?.quote?.legs) ? body.quote.legs : [])) (st.quoteLegs ||= []).push(l);
+  throw quoteStopError();
+}
 // unwrap the {data}|{error} envelope; throw a clean Error (with .status) on failure
 async function unwrap(res, { read = false } = {}) {
   let body = null;
   try { body = await res.json(); } catch (e) { if (read && isDeadline(e)) throw readDeadlineError(); } // a body cut off by the read deadline is not an empty answer
   if (!res.ok) {
+    quoteStopFrom(res.status, body); // a price quote that stopped at a spending point (throws; never data)
     const msg = signInMessage(res.status, body, (body && (body.error || body.message)) || `HTTP ${res.status}`);
     // `_viaApi` MARKS AN ERROR THAT ALREADY REACHED THE SERVER, so route() has already recorded it in the error
     // ledger with the tool name off x-hermoso-tool. wrap() reports ONLY the errors that lack this marker — a local
     // throw, a schema rejection, a socket reset — which is what stops the twins double-counting every 4xx.
     // `connectUrl` rides a not-connected 401 with the brand already in it, so a hint never rebuilds the link.
-    throw Object.assign(new Error(msg), { status: res.status, _viaApi: true, ...(res.status === 429 ? { retryAfter: Number(body?.retryAfter) || Number(res.headers?.get?.('retry-after')) || 60 } : {}), ...(typeof body?.code === 'string' ? { apiCode: body.code } : {}), ...(body?.connector ? { connector: body.connector } : {}), ...(typeof body?.connectUrl === 'string' ? { connectUrl: body.connectUrl } : {}), ...(body?.meta?.videoChoice && typeof body.meta.videoChoice === 'object' ? { videoChoice: body.meta.videoChoice } : {}), ...(body?.metaAuthHold === true ? { metaAuthHold: true } : {}), ...(body?.meta?.welcomeClaim && typeof body.meta.welcomeClaim === 'object' && body.meta.welcomeClaim.url ? { welcomeClaim: { credits: Number(body.meta.welcomeClaim.credits) || 0, url: String(body.meta.welcomeClaim.url) } } : {}), ...(body?.remedy && typeof body.remedy === 'object' && typeof body.remedy.code === 'string' ? { remedy: body.remedy } : {}) }); // `remedy` (2026-10-25): the server's structured next step (a publish outcome, Meta's security hold), handed on whole to wrap()'s _meta and /v1 // `videoChoice` rides a 402 for a video the caller expects and cannot afford (server videoChoiceFor) — wrap() spells its options out instead of a bare top-up line
+    throw Object.assign(new Error(msg), { status: res.status, _viaApi: true, ...(res.status === 429 ? { retryAfter: Number(body?.retryAfter) || Number(res.headers?.get?.('retry-after')) || 60 } : {}), ...(typeof body?.code === 'string' ? { apiCode: body.code } : {}), ...(body?.connector ? { connector: body.connector } : {}), ...(typeof body?.connectUrl === 'string' ? { connectUrl: body.connectUrl } : {}), ...(body?.meta?.videoChoice && typeof body.meta.videoChoice === 'object' ? { videoChoice: body.meta.videoChoice } : {}), ...(body?.metaAuthHold === true ? { metaAuthHold: true } : {}), ...(body?.meta?.welcomeClaim && typeof body.meta.welcomeClaim === 'object' && body.meta.welcomeClaim.url ? { welcomeClaim: { credits: Number(body.meta.welcomeClaim.credits) || 0, url: String(body.meta.welcomeClaim.url) } } : {}), ...(body?.remedy && typeof body.remedy === 'object' && typeof body.remedy.code === 'string' ? { remedy: body.remedy } : {}), ...(body?.buy && typeof body.buy === 'object' && body.buy.pack ? { buy: body.buy } : {}) }); // `buy` (2026-11-12): the two priced doors a balance refusal carries (server buyDoorsFor): a pack and a plan, each with its price and a checkout link // `remedy` (2026-10-25): the server's structured next step (a publish outcome, Meta's security hold), handed on whole to wrap()'s _meta and /v1 // `videoChoice` rides a 402 for a video the caller expects and cannot afford (server videoChoiceFor) — wrap() spells its options out instead of a bare top-up line
   }
   // WHAT THIS CALL WAS CHARGED (2026-10-19). A paid route answers {data, creditsUsed}, and the unwrap below drops the
   // sibling, so a synchronous paid tool's reply could never say what it cost. It is added to the running tool call's
@@ -522,7 +542,7 @@ export async function apiUploadUrl(p, url, { fileName = '' } = {}) {
 // /api/explore/chat streams Server-Sent-Events; collect to the terminal `done` payload {reply, results, actions}.
 export async function apiSSE(p, body = {}) {
   const res = await fetchWrite(`${API_BASE}${withBrandScope(p)}`, { method: 'POST', headers: headers({ Accept: 'text/event-stream' }), body: JSON.stringify(body) });
-  if (!res.ok) { let e; try { e = (await res.json()).error; } catch {} throw Object.assign(new Error(e || `HTTP ${res.status}`), { status: res.status }); }
+  if (!res.ok) { let e, b = null; try { b = await res.json(); e = b?.error; } catch {} quoteStopFrom(res.status, b); throw Object.assign(new Error(e || `HTTP ${res.status}`), { status: res.status }); }
   // A server that answered with plain JSON (an older revision) is read as JSON, never as an empty stream.
   if (!/text\/event-stream/i.test(res.headers.get('content-type') || '')) { const j = await res.json(); return j && Object.prototype.hasOwnProperty.call(j, 'data') ? j.data : j; }
   const reader = res.body.getReader(); const dec = new TextDecoder();
@@ -549,7 +569,19 @@ export async function apiSSE(p, body = {}) {
 // Submit a render to the job queue and (optionally) poll it to completion. Returns the UNWRAPPED worker result
 // (the {image|video, model} object) on success — the job's `result` is itself a {data} envelope, so we peel it.
 export async function submitJob(type, input, { label = '' } = {}) {
-  return apiPost('/api/jobs', { type, input, label }); // → publicJob {id, status, ...}
+  const st = toolCtx.getStore();
+  // A PRICE QUOTE (get_cost / expected_credits): the same submit as a dry run, priced by the job's own hold, then the call
+  // stops: nothing is queued. The server forces the dry run in quote mode too; this keeps the tally exact.
+  if (st?.quoteOnly) {
+    const d = await apiPost('/api/jobs', { type, input, label, dryRun: true });
+    const q = d?.quote || null;
+    (st.quoteLegs ||= []).push({ credits: q && Number(q.credits) > 0 ? Number(q.credits) : null, ...(q && Number(q.priceCredits) > 0 ? { priceCredits: Number(q.priceCredits) } : {}), basis: q && Number(q.credits) > 0 ? 'hold' : 'actual', label: label || q?.label || type, ...(q && q.refused ? { refused: String(q.refused) } : {}) });
+    throw quoteStopError();
+  }
+  // A TOOL CALL WITH AN idempotency_key: each job it queues carries a key derived from it (one per submit in the call), so a
+  // retry of a lost answer collapses onto the same job, and the claim learns the job id (pendingText names it).
+  const idem = st?.idemKey ? { idempotencyKey: `${st.idemJobKey}.${(st.idemJobs = (st.idemJobs || 0) + 1)}`, toolIdemKey: st.idemKey } : {};
+  return apiPost('/api/jobs', { type, input, label, ...idem }); // → publicJob {id, status, ...}
 }
 export async function getJob(id) { return apiGet(`/api/jobs/${encodeURIComponent(id)}`); } // → publicJob
 // ONE READ THAT A ROLLOVER CANNOT TURN INTO "IT DOES NOT EXIST" (2026-10-19). get_job is a single read, and its 404

package/mcp/http.mjs

@@ -16,8 +16,8 @@ import { randomUUID, createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { registerTools, MCP_INSTRUCTIONS, instructionsFor, parseToolScope, DEFAULT_TOOL_GROUPS, anonDiscoveryGroups } from './tools.mjs';
-import { chatgptExtAsked } from './openai-extensions.mjs';
+import { registerTools, MCP_INSTRUCTIONS, instructionsFor, parseToolScope, DEFAULT_TOOL_GROUPS, anonDiscoveryGroups, widgetHostScope, withFirstRunLine, firstRunOffers } from './tools.mjs';
+import { chatgptExtRequested } from './openai-extensions.mjs';
 import { mcpCtx, connectedProviders } from './client.mjs';
 
 // Mount the remote connector onto the Express app. No-op unless explicitly enabled + auth-backed.
@@ -398,7 +398,9 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
   // `?ext=1` asks for the ChatGPT extensions app (the Library panel + sidebar). Only a REQUEST: registerTools turns it
   // on only for a widget host on a process with HERMOSO_CHATGPT_EXT=1 (chatgptExtOn in openai-extensions.mjs), so on
   // the published URL, or with the flag unset, the roster is exactly what it was. Presentation only, like `?tools=`.
-  const extAsked = (req) => chatgptExtAsked(req.query?.ext);
+  // HERMOSO_CHATGPT_EXT_PUBLISHED=1 stands in for `?ext=1` on an unscoped connection (the published all-in-one plugin's
+  // URL cannot carry it; see chatgptExtRequested). Still only a request: the widget-host and HERMOSO_CHATGPT_EXT keys hold.
+  const extAsked = (req, scope) => chatgptExtRequested({ asked: req.query?.ext, app: scope?.app || null });
   const srcOf = (req) => { const v = String(req.query?.src || '').trim().toLowerCase(); return /^[a-z0-9][a-z0-9_.-]{0,39}$/.test(v) ? v : null; };
   const methodsOf = (body) => (Array.isArray(body) ? body : [body]).map((m) => m && m.method).filter(Boolean);
 
@@ -406,6 +408,7 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
     // A widget host (ChatGPT, whose plugin scanner reads this anonymous roster) gets its own instructions — see
     // MCP_INSTRUCTIONS_WIDGET. The SAME host decision as the roster below, so the two can never disagree.
     const widgetHost = isWidgetHost(clientInfoOf(req.body), req);
+    scope = widgetHostScope(scope, widgetHost); // the URL our app handed ChatGPT users is the plain URL there (LEGACY_WIDGET_CONNECT_GROUPS)
     const server = new McpServer({ name: 'hermoso', version: PKG_VERSION }, { instructions: instructionsFor(scope, { widgetHost }) });
     // `widgetHost` withholds the two commerce tools from ChatGPT (see registerTools). It is passed HERE as well
     // as on the session path because OpenAI's own tool scanner reads this anonymous discovery roster — gating
@@ -423,7 +426,7 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
     // default rather than to the session default; an explicit `?tools=` still wins, exactly as it does below.
     // A widget host in full mode gets every group here too, so the anonymous roster and the signed-in one agree (see
     // chatgptRosterMode in tools.mjs: ChatGPT cannot reach an unlisted tool).
-    registerTools(server, { only: scope?.groups || anonDiscoveryGroups(widgetHost), directory: scope?.directory || false, app: scope?.app || null, widgetHost, hosted: true, ext: extAsked(req) }); // metadata only — tools/list never invokes a handler, and tools/call can't reach here
+    registerTools(server, { only: scope?.groups || anonDiscoveryGroups(widgetHost), directory: scope?.directory || false, app: scope?.app || null, widgetHost, hosted: true, ext: extAsked(req, scope) }); // metadata only — tools/list never invokes a handler, and tools/call can't reach here
     // WHO PROBES US WITHOUT A TOKEN, BY NAME (2026-09-25). A host's add-connector dialog decides "sign-in needed or
     // not" from THIS answer: ChatGPT probes with an empty body and gets the 401; claude.ai's dialog sends a real
     // tokenless initialize (UA python-httpx) and our 200 made it pre-select "No sign-in". The UA alone cannot tell
@@ -455,7 +458,18 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
     // doing anything"). Only a tools/call is somebody doing something, so only a tools/call stamps. Auth itself is
     // unchanged in both branches: this decides bookkeeping, never access.
     const didWork = methodsOf(req.body).includes('tools/call');
-    const user = token ? await verifyBearer(token, { stamp: didWork }).catch(() => null) : null;
+    // A KEY STORE THAT COULD NOT BE READ IS NOT A REJECTED KEY (2026-11-11). During the database restart at 22:41 a
+    // Codex session's valid hmk_ key was answered with the 401 challenge, logged as "bearer token rejected"; a 401 tells
+    // the client to drop its credential and sign in again, for an outage of a few seconds. verifyBearer answers null for
+    // an unknown or revoked key and THROWS when the lookup itself fails, so a throw is a 503 the client retries. Same rule
+    // as the refresh path in mcp/oauth.mjs ("a failed read is not a revocation").
+    let storeDown = false;
+    const user = token ? await verifyBearer(token, { stamp: didWork }).catch(() => { storeDown = true; return null; }) : null;
+    if (storeDown) {
+      connectEvent(req, { step: 'mcp-auth', ok: false, reason: 'key store read failed', detail: `${token.slice(0, 4)}… (${token.length} chars) on ${req.method}` });
+      res.setHeader('Retry-After', '5');
+      return res.status(503).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Hermoso is briefly unavailable. Please retry in a few seconds; your connection is fine.' }, id: null });
+    }
     if (!user && token) connectEvent(req, { step: 'mcp-auth', ok: false, reason: 'bearer token rejected', detail: `${token.slice(0, 4)}… (${token.length} chars) on ${req.method}` });
     if (!user) {
       // No valid bearer: allow ONLY the read-only discovery handshake (POST), fail CLOSED for everything else.
@@ -518,8 +532,12 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
       // Only an `initialize` may mint a session. Anything else naming no session at all is the SDK's own 400 —
       // answered here so we never build a server whose only job would be to reject the request.
       if (!init) return needSession(res);
-      const scope = scopeFor(req, res);
-      if (scope === false) return; // unknown group — already answered 400, and nothing was allocated
+      const scope0 = scopeFor(req, res);
+      if (scope0 === false) return; // unknown group — already answered 400, and nothing was allocated
+      // On ChatGPT the URL our own app handed out (seven named groups, no ads or analytics) is read as the plain URL:
+      // a widget host has no executor, so a group it does not list is a feature it does not have. See
+      // LEGACY_WIDGET_CONNECT_GROUPS in tools.mjs. The same host decision as `widgetHost` below.
+      const scope = widgetHostScope(scope0, isWidgetHost(entry?.client || clientInfoOf(req.body), req));
       sweepSessions(); // make room before allocating, so the cap is a ceiling and not a suggestion
       // ── WHAT THIS CALLER CAN ACTUALLY USE (2026-08-26) ────────────────────────────────────────────────────────
       // One free store read, on the ONE request per session that mints the roster, so the tools we advertise are
@@ -537,8 +555,21 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
       const connectors = await mcpCtx.run({ token, remote: true, client: rememberedClient(req) }, () => connectedProviders());
       // ONE host decision for the instructions and the roster (see MCP_INSTRUCTIONS_WIDGET), so the two cannot disagree.
       const widgetHost = isWidgetHost(entry?.client || clientInfoOf(req.body), req);
-      const server = new McpServer({ name: 'hermoso', version: PKG_VERSION }, { instructions: instructionsFor(scope, { widgetHost }) });
-      registerTools(server, { only: scope.groups, directory: scope.directory || false, app: scope.app || null, connectors, widgetHost, hosted: true, ext: extAsked(req), client: entry?.client || rememberedClient(req), ua: String(req.headers['user-agent'] || '').slice(0, 120) }); // the SAME tools as stdio (minus any the caller scoped out) — and every /api call they make carries this user's token
+      // AN ACCOUNT THAT HAS MADE NOTHING YET, ON EVERY HOST (2026-10-19 for ChatGPT; every host since 2026-11-12). Read once
+      // per session, bounded so a slow read can never hold the connect: null (no guidance) is the answer to every failure.
+      // Read BEFORE the server is built, because it changes what initialize says: a fresh account's `instructions` open with
+      // one line saying how to start (withFirstRunLine in tools.mjs), which a host reads before the user types anything. The
+      // first successful tool reply of the session then carries the same next ask (firstRunNote), for hosts that ignore
+      // instructions. `offer` is what this session's own instructions can name, so a focused app or the directory cage is
+      // never told to offer a tool it does not list.
+      const baseInstructions = instructionsFor(scope, { widgetHost });
+      let firstRun = null;
+      if (typeof firstRunFor === 'function' && user.accountId) {
+        try { firstRun = await Promise.race([Promise.resolve(firstRunFor({ accountId: user.accountId })).catch(() => null), new Promise((r) => { const t = setTimeout(() => r(null), 1500); if (t && typeof t.unref === 'function') t.unref(); })]); } catch { firstRun = null; }
+      }
+      firstRun = firstRun && typeof firstRun === 'object' && firstRun.fresh === true ? { ...firstRun, offer: firstRunOffers(baseInstructions) } : null;
+      const server = new McpServer({ name: 'hermoso', version: PKG_VERSION }, { instructions: withFirstRunLine(baseInstructions, firstRun) });
+      registerTools(server, { only: scope.groups, directory: scope.directory || false, app: scope.app || null, connectors, widgetHost, hosted: true, ext: extAsked(req, scope), client: entry?.client || rememberedClient(req), ua: String(req.headers['user-agent'] || '').slice(0, 120) }); // the SAME tools as stdio (minus any the caller scoped out) — and every /api call they make carries this user's token
       const transport = new StreamableHTTPServerTransport({
         // CSPRNG, per the spec's SHOULD for session ids (Math.random() is not one).
         sessionIdGenerator: () => 'sess_' + randomUUID().replace(/-/g, ''),
@@ -548,15 +579,9 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
       // WHO IS CALLING, captured at the ONE moment it is on the wire. `clientInfo` rides the `initialize`
       // request and nothing afterwards, so it has to be remembered on the session or it is gone by the first
       // tools/call. It is advisory only: it may not change auth, scope or spend — it decides PRESENTATION.
-      // A CHATGPT ACCOUNT THAT HAS MADE NOTHING YET (2026-10-19). Read once per session, ChatGPT hosts only, bounded so a slow
-      // read can never hold the connect: null (no note) is the answer to every failure. The first successful tool reply of
-      // the session then offers one concrete next ask (firstRunNote in tools.mjs). Most ChatGPT signups since the
-      // 10-15 publish had made nothing, and a live "make me a video ad" chat on a connected account never called us.
-      let firstRun = null;
-      if (widgetHost && typeof firstRunFor === 'function' && user.accountId) {
-        try { firstRun = await Promise.race([Promise.resolve(firstRunFor({ accountId: user.accountId })).catch(() => null), new Promise((r) => { const t = setTimeout(() => r(null), 1500); if (t && typeof t.unref === 'function') t.unref(); })]); } catch { firstRun = null; }
-      }
-      entry = { transport, server, user, lastSeen: Date.now(), client: rememberedClient(req), ua: String(req.headers['user-agent'] || '').slice(0, 120), src: srcOf(req), startedAt: Date.now(), listed: false, calls: 0, connectSeen: true, firstRun: firstRun && typeof firstRun === 'object' ? firstRun : null };
+      // The fresh-account read (firstRun) happened above, before the server was built; the session keeps it so the first
+      // successful tool reply can carry the same next ask.
+      entry = { transport, server, user, lastSeen: Date.now(), client: rememberedClient(req), ua: String(req.headers['user-agent'] || '').slice(0, 120), src: srcOf(req), startedAt: Date.now(), listed: false, calls: 0, connectSeen: true, firstRun };
       if (typeof onSessionStart === 'function') { try { onSessionStart({ accountId: user.accountId || null, userId: user.userId || null, client: entry.client, ua: entry.ua, src: entry.src }); } catch {} }
       // LOG THE NAME. `hostRendersWidgets()` matches it with a regex, and a regex over a string no one has
       // ever read is a guess. One line per session (not per call) so a new host identifies itself once and

package/mcp/openai-extensions.mjs

@@ -166,6 +166,16 @@ export const chatgptExtAsked = (v) => /^(1|true|on|yes)$/i.test(String(Array.isA
 // All three keys, in one predicate so the transport and the check cannot disagree about what "on" means.
 export const chatgptExtOn = ({ env = process.env, asked, widgetHost } = {}) =>
   !!widgetHost && String(env?.[CHATGPT_EXT_ENV] ?? '').trim() === '1' && chatgptExtAsked(asked);
+// THE PUBLISHED APP CANNOT ASK (2026-11-11). The all-in-one plugin's mcp.json URL is plain /mcp, and OpenAI does not
+// let an update change a published plugin's MCP URL ("To change an existing MCP server's URL, contact support",
+// developers.openai.com/plugins/deploy/submission.md, read 2026-11-11), so `?ext=1` can never reach it. This second
+// env stands in for the ask on an UNSCOPED connection only (no `?tools=` app scope, so the three focused apps are
+// untouched). It is still only a REQUEST: chatgptExtOn above keeps its other two keys (a widget host and
+// HERMOSO_CHATGPT_EXT=1), so with this env unset the roster is byte-identical. Turning it on adds NEW tools, which
+// OpenAI's continuous review checks before any user sees them; no reviewed tool changes.
+export const CHATGPT_EXT_PUBLISHED_ENV = 'HERMOSO_CHATGPT_EXT_PUBLISHED';
+export const chatgptExtRequested = ({ env = process.env, asked, app } = {}) =>
+  chatgptExtAsked(asked) || (!app && String(env?.[CHATGPT_EXT_PUBLISHED_ENV] ?? '').trim() === '1');
 
 // THE SIDEBAR ICON. The spec asks for a 20x20 monochrome SVG in currentColor. This is the bloom (four petals and a
 // centre, public/brand/bloom-mono-black.svg) redrawn in currentColor at the spec's stroke weight. A data: URI, so it

package/mcp/spend-guard.mjs

@@ -0,0 +1,127 @@
+// ── A PAID TOOL CALL: PRICE IT FIRST, BUY IT ONCE (2026-11-11) ─────────────────────────────────────────────────────
+//
+// Three controls on every tool that spends (owner-approved 2026-11-11, after reading how the best agent surfaces do it):
+//   get_cost: true          the exact price, with nothing run and nothing billed;
+//   expected_credits: N     "run it at the price I was quoted": the server re-prices and REFUSES (unbilled) if it moved;
+//   idempotency_key: "…"    chosen once and repeated unchanged on a retry: the same key never buys the call twice.
+// Plus `context` on every tool: the user's goal in one short sentence, for analytics only.
+//
+// WHICH TOOLS: the ones that spend credits, derived from the same classification find_tools prints (tool-cost.mjs:
+// the `create` and `research` groups run a model or Ad Spy research), minus SPEND_EXEMPT, the few tools filed in those
+// groups that spend nothing. X's per-call tools are left out on purpose: post_to_x already has its own 24h
+// idempotencyKey and a free dryRun that prices the exact post. tools/spend-guard-check.mjs derives the set from the
+// registry and the handlers' own code, and fails on a paying tool that lacks the controls.
+//
+// HOW A PRICE IS MADE: the tool's OWN handler runs with quote mode on (client.mjs sends x-hermoso-quote: 1 on every
+// request; server.js answers each spending point with what it would cost and stops it there). So the price is the run's
+// own pricing, never a second table that could drift. Nothing is queued, held or charged.
+//
+// No `get_cost`, no `expected_credits` and no `idempotency_key` ⇒ the tool runs exactly as it always has.
+//
+// BYTE-TWINNED with cli/mcp/spend-guard.mjs (tools/mcp-parity.mjs sweeps every shared file). PURE apart from the
+// injected `post`, and no lib/ import, because the CLI ships rooted at cli/.
+
+import { createHash } from 'node:crypto';
+import { toolCostClass } from './tool-cost.mjs';
+
+// Filed in `create` / `research` but spend nothing: lookups, saved presets, Library and Gallery bookkeeping.
+export const SPEND_EXEMPT = Object.freeze([
+  'list_video_presets', 'save_video_preset', 'update_video_preset', 'delete_video_preset',
+  'delete_library_item', 'submit_to_gallery', 'list_gallery_submissions', 'withdraw_from_gallery',
+  'list_winning_ads', 'set_product_image', 'collect_post_metrics',
+]);
+export const SPEND_CONTROL_ARGS = Object.freeze(['idempotency_key', 'get_cost', 'expected_credits']);
+
+/** Does this tool spend credits (and so take get_cost / expected_credits / idempotency_key)? */
+export function spendTool(name, group) {
+  const n = String(name || '');
+  if (SPEND_EXEMPT.includes(n)) return false;
+  const c = toolCostClass(n, group, null);
+  return c === 'model' || c === 'research';
+}
+
+// The parameter texts. Short on purpose: they ride every paying tool's schema.
+export const SPEND_ARG_TEXT = Object.freeze({
+  get_cost: 'true: return the price only; nothing runs or bills',
+  expected_credits: 'the get_cost price; refused unbilled if the live price differs',
+  idempotency_key: 'chosen once, resent unchanged on retries: the same key never buys twice',
+});
+export const CONTEXT_ARG_TEXT = "optional: the user's underlying goal in one short sentence, for analytics only (no names, contact details or URLs)";
+
+export const TOOL_IDEM_KEY_MAX = 128;
+export function validKey(k) {
+  if (typeof k !== 'string') return null;
+  const s = k.trim();
+  return s && s.length <= TOOL_IDEM_KEY_MAX && !/[\u0000-\u001f\u007f]/.test(s) ? s : null;
+}
+
+function stableJson(v) {
+  if (Array.isArray(v)) return '[' + v.map(stableJson).join(',') + ']';
+  if (v && typeof v === 'object') return '{' + Object.keys(v).sort().filter((k) => v[k] !== undefined).map((k) => JSON.stringify(k) + ':' + stableJson(v[k])).join(',') + '}';
+  return JSON.stringify(v === undefined ? null : v);
+}
+/** The arguments a key is bound to: everything except the call controls and `context`, order-free. */
+export function argsHash(tool, args) {
+  const a = {};
+  for (const [k, v] of Object.entries(args && typeof args === 'object' ? args : {})) if (!SPEND_CONTROL_ARGS.includes(k) && k !== 'context') a[k] = v;
+  return createHash('sha256').update(String(tool || '') + '\n' + stableJson(a)).digest('hex').slice(0, 40);
+}
+/** The root of the job idempotency keys a keyed call's submits carry (server shape /^[A-Za-z0-9._:-]{8,120}$/; client.mjs appends .1, .2…). */
+export function jobKeyRoot(toolKey, tool = '') {
+  return `ti.${createHash('sha256').update(String(tool) + '\n' + String(toolKey)).digest('hex').slice(0, 24)}`;
+}
+
+/** Pull the call controls off the arguments. `clean` is what the handler sees, so none of them ever reaches a body. */
+export function takeSpendMeta(args) {
+  const a = args && typeof args === 'object' ? { ...args } : {};
+  const getCost = a.get_cost === true;
+  const expected = a.expected_credits == null || a.expected_credits === '' ? null : Number(a.expected_credits);
+  const rawKey = a.idempotency_key;
+  for (const k of SPEND_CONTROL_ARGS) delete a[k];
+  return { clean: a, getCost, expected: Number.isFinite(expected) ? expected : (expected === null ? null : NaN), key: rawKey == null || rawKey === '' ? null : validKey(rawKey), badKey: rawKey != null && rawKey !== '' && !validKey(rawKey) };
+}
+
+// ── the agent's `context`, redacted on THIS side before it leaves (lib/agent-context.mjs is the server's copy) ──
+export const AGENT_CONTEXT_MAX = 200;
+export function redactContext(s) {
+  if (typeof s !== 'string') return '';
+  let t = s.replace(/[\u0000-\u001f\u007f]+/g, ' ');
+  t = t.replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, '[email]');
+  t = t.replace(/\b(?:https?:\/\/|www\.)\S+/gi, '[url]');
+  t = t.replace(/\b[a-z0-9-]+(?:\.[a-z0-9-]+)*\.(?:com|net|org|io|ai|co|app|dev|shop|store|us|uk|ca|de|fr|es|it|nl|au|me|xyz)\b\S*/gi, '[url]');
+  t = t.replace(/(^|\s)@[A-Za-z0-9_.]{2,}/g, '$1[handle]');
+  t = t.replace(/\+?\d[\d\s().-]{6,}\d/g, '[number]');
+  t = t.replace(/\s+/g, ' ').trim();
+  return t.length > AGENT_CONTEXT_MAX ? t.slice(0, AGENT_CONTEXT_MAX - 1).trimEnd() + '…' : t;
+}
+// A header value is Latin-1 at the transport: anything else is percent-encoded (the server reads the decoded text).
+export const contextHeaderValue = (t) => { try { return encodeURIComponent(t).slice(0, 900); } catch { return ''; } };
+
+// ── the price ──
+const round1 = (n) => Math.round(n * 10) / 10;
+/** One price out of the legs a quote run collected. credits is null when any leg is billed at its actual cost. */
+export function quoteFromLegs(legs) {
+  const L = (Array.isArray(legs) ? legs : []).filter(Boolean);
+  const refused = L.find((l) => l.refused);
+  if (refused && !L.some((l) => l.credits > 0)) return { credits: null, legs: L, refused: String(refused.refused) };
+  const unpriced = L.filter((l) => !(Number(l.credits) > 0));
+  const sum = L.reduce((t, l) => t + (Number(l.priceCredits) > 0 ? Number(l.priceCredits) : Number(l.credits) > 0 ? Number(l.credits) : 0), 0);
+  const hold = L.reduce((t, l) => t + (Number(l.credits) > 0 ? Number(l.credits) : 0), 0);
+  if (!L.length) return { credits: 0, legs: L, free: true };
+  return { credits: unpriced.length ? null : round1(sum), ...(hold > sum + 1e-9 && !unpriced.length ? { holdCredits: round1(hold) } : {}), ...(L.some((l) => l.basis === 'estimate') ? { estimate: true } : {}), legs: L, ...(unpriced.length ? { unpriced: unpriced.map((l) => l.label || 'a step') } : {}) };
+}
+const legLine = (l) => `${l.label || 'a step'}: ${Number(l.priceCredits) > 0 ? `${l.priceCredits}` : Number(l.credits) > 0 ? `${l.credits}` : 'its actual cost'}`;
+export function quoteText(tool, q) {
+  if (q.refused) return `NO PRICE (nothing ran, nothing was charged): ${tool} would not start: ${q.refused}`;
+  if (q.free) return `PRICE (nothing ran, nothing was charged): ${tool} with these arguments spends no credits.`;
+  if (q.credits == null) {
+    const known = q.legs.filter((l) => Number(l.credits) > 0);
+    return `NO FIXED PRICE (nothing ran, nothing was charged): ${tool} is billed at the actual cost of ${q.unpriced.join(' and ')}, which is not known before it runs.${known.length ? ` The priced part is ${known.map(legLine).join(', ')} credits.` : ''} expected_credits cannot bind this call; run it without it.`;
+  }
+  return `PRICE (nothing ran, nothing was charged): ${tool} costs ${q.estimate ? 'about ' : ''}${q.credits} credits${q.holdCredits ? ` (it sets aside up to ${q.holdCredits} while it runs; the final charge is its actual cost)` : q.estimate ? ' (its own entry estimate; the final charge is the actual cost of the run)' : ''}.${q.legs.length > 1 ? ` Steps: ${q.legs.map(legLine).join('; ')}.` : ''} To run it at this price, call again without get_cost, with expected_credits: ${q.credits} and an idempotency_key.`;
+}
+export function expectedMismatchText(tool, expected, q) {
+  if (q.credits == null) return `Refused, nothing ran and nothing was charged: expected_credits was ${expected}, but ${tool} has no fixed price here (${q.refused || `billed at the actual cost of ${(q.unpriced || []).join(' and ') || 'its model steps'}`}). Run it without expected_credits, or ask the user first.`;
+  return `Refused, nothing ran and nothing was charged: the live price of ${tool} is ${q.credits} credits, not the ${expected} you expected. Tell the user the new price; if they agree, call again with expected_credits: ${q.credits}.`;
+}
+export const priceMatches = (expected, q) => q && q.credits != null && Math.abs(Number(expected) - Number(q.credits)) < 0.05;

package/mcp/tool-cost.mjs

@@ -46,6 +46,9 @@ export const CREATE_FREE_READS = Object.freeze([
   // The product catalog (2026-10-06): a store read or write, and a product page read with curl and parsed locally (no
   // model; POST /api/products answers creditsUsed: 0). Each says "Free" / "0 credits" in its own description.
   'list_products', 'add_product', 'refresh_products', 'update_product', 'remove_product',
+  // Story films (2026-11-11): the catalog, one card's recipe and starting a run (the outline) are store reads and writes;
+  // each says "Free" in its own description. advance_story_film runs the paid stages and stays a model tool.
+  'list_story_cards', 'get_story_card', 'start_story_film',
 ]);
 // Reads inside `research`. `find_competitors` says "0 credits" in its own description (it is the discovery model,
 // billed to us, not a paid ad-data call); the watch tools only write and read a stored preference — the weekly

package/mcp/tool-hints.mjs

@@ -81,10 +81,29 @@ export function videoChoiceDraftCall(tool, d) {
 // then try to upsell the plans/credits?"). The agent says plainly that the account does not have enough credits and offers
 // credits and plans; the image and the light draft stay listed LAST, for a user who asks for something cheaper themselves,
 // never as the agent's own pick. A video-plus-static ask is priced whole (`needCredits`, `alsoImage`) and neither half is made.
+// ── THE TWO PRICED DOORS, AS AN AGENT RELAYS THEM (2026-11-12) ──────────────────────────────────────────────────────
+// A balance refusal carries `buy` (the server's buyDoorsFor): a monthly plan and a credit pack sized to the ask, each with
+// its price, its credits and a checkout link that needs no sign-in, plus the same offer as ready-made `lines`. The old
+// answer explained how buy_credits works and left the agent to make a second call before the user saw a price. Now the
+// prices and the links are in the refusal itself. Never on a widget host (ChatGPT may not link to a checkout): the
+// callers pass `buy` only when the host is not one. Pure, no imports: the twin rule.
+export function buyDoorsOf(e, widgetHost) {
+  const b = e && e.buy;
+  return !widgetHost && b && typeof b === 'object' && b.pack && Array.isArray(b.lines) && b.lines.length ? b : null;
+}
+export function buyDoorsText(buy, tool) {
+  if (!buy) return '';
+  const lines = buy.lines.map((x) => String(x)).filter(Boolean);
+  const doors = lines.filter((l) => l.startsWith('•'));
+  return [buy.plan ? `Recommend the ${buy.plan.name} plan to the user, with its link; a one-time credit pack is the other option:` : 'Give the user this way to continue, with its link:', ...doors,
+    `Each link opens a secure checkout page for this account, no sign-in needed. Once they have paid, call ${tool || 'the same tool'} again with the same arguments. A card already on file: buy_credits({pack:"${buy.pack.id}"}) quotes it and charges on confirm.`].join('\n');
+}
+export const buyDoorsHints = (buy, tool) => (buy ? [{ do: `${buy.plan ? `recommend the ${buy.plan.name} plan from this message with its price and link, and mention the one-time pack as the other option` : 'show the user the pack from this message with its price and link'}; after they pay, call ${tool || 'the same tool'} again with the same arguments`, why: 'the account cannot cover this call; each link is a checkout for this account that needs no sign-in, and nothing was charged' }] : []);
 export function videoChoiceHints(tool, choice, opts = {}) {
   const c = choice && typeof choice === 'object' ? choice : {}, o = c.options || {};
   const out = opts.widgetHost
     ? [{ do: `tell the user they do not have enough credits: it needs ${c.short ?? '?'} more than the account has; they add credits or pick a plan in their Hermoso account at ${ACCOUNT_INFO_URL}`, why: 'this host does not offer purchases, so nothing is bought from here' }]
+    : opts.buy ? buyDoorsHints(opts.buy, tool)
     : [
       { do: 'buy_credits({})', why: `${c.short ?? '?'} credits short; a pack covers it, then the same call makes it as asked` },
       { do: 'upgrade_plan({})', why: 'a monthly plan (Starter, Pro, Studio) includes monthly credits and no markup on models' },
@@ -108,6 +127,7 @@ export function videoChoiceText(tool, choice, opts = {}) {
     // feature needs more credits and link an informational page, never a checkout. `o.topup.url` is a checkout link.
     ...(opts.widgetHost
       ? [`  1. The user can add credits or pick a plan in their Hermoso account (${ACCOUNT_INFO_URL}); then the same call makes it as asked. Nothing can be bought from here.`]
+      : opts.buy ? [buyDoorsText(opts.buy, tool)]
       : [`  1. Add credits: buy_credits({}) quotes a pack on a saved card or returns a checkout link${o.topup?.url ? ` (or ${o.topup.url})` : ''}; then repeat the same call and it goes ahead as asked.`,
         `  2. Or a monthly plan: upgrade_plan({}) lists them; Starter, Pro and Studio include monthly credits and no markup on models, so credits go further.`]),
   ];
@@ -156,8 +176,28 @@ export function withWidgetResultNote(tool, r, widgetHost) {
 // buy_credits / upgrade_plan (WITHHELD_FROM_WIDGET_HOSTS), so its out-of-credits reply must not name them either, and
 // the server's own sentence ("Upgrade or top up to keep going.") is rewritten to say where the account is managed.
 // The link is the pricing page, which describes the options and starts nothing. Pure, no imports — the twin rule.
-export const ACCOUNT_INFO_URL = 'https://hermoso.ai/pricing';
-export const CREDITS_LOW_NOTE = `The Hermoso account's credit balance is too low for this. Tell the user plainly; they manage their account and credits at ${ACCOUNT_INFO_URL}. Nothing can be bought from here.`;
+// TAGGED src=chatgpt-credits (2026-11-12, lib/buy-page.mjs): the pricing page shows a visitor with this tag one button, "Buy credits
+// or a plan", to the app's buy page. Still the informational page ChatGPT's rules allow, and the only link this host is ever
+// given; the buy page itself is never linked from here. The tag rides only the refusal text, never a tool definition.
+export const ACCOUNT_INFO_URL = 'https://hermoso.ai/pricing?src=chatgpt-credits';
+// …AND THE PLAN TIER THE ACCOUNT IS ON, AND NOTHING ELSE (2026-11-12, owner: "shouldnt we only show plans higher than the plan
+// they are on?"). The pricing page is static and cannot see the account, so the link says which tier it is on (&from=starter)
+// and the page hides the plans at or below it. A tier is not personal data; no id, email or balance ever rides the link. An
+// unknown or free tier is the plain link (every plan is above Free). Pure; tools.mjs reads the tier once per refusal.
+export const PLAN_TIERS = Object.freeze(['free', 'basic', 'starter', 'pro', 'studio']);
+export function accountInfoUrl(tier) {
+  const t = String(tier || '').trim().toLowerCase();
+  return PLAN_TIERS.includes(t) && t !== 'free' ? `${ACCOUNT_INFO_URL}&from=${t}` : ACCOUNT_INFO_URL;
+}
+/** A refusal written for a widget host, with the tier put on its info link (text and hints). The text is otherwise untouched. */
+export function withInfoTier(text, hints, tier) {
+  const u = accountInfoUrl(tier);
+  if (u === ACCOUNT_INFO_URL) return { text, hints };
+  const sw = (x) => String(x).split(ACCOUNT_INFO_URL).join(u);
+  return { text: sw(text), hints: (hints || []).map((h) => (h && typeof h === 'object' ? { ...h, ...(typeof h.do === 'string' ? { do: sw(h.do) } : {}), ...(typeof h.why === 'string' ? { why: sw(h.why) } : {}) } : h)) };
+}
+export const ACCOUNT_CREDITS_LINE = `The user can add credits or pick a plan in their Hermoso account at ${ACCOUNT_INFO_URL}, then ask again.`; // the neutral fact every widget-host refusal carries (owner, 2026-11-12): what to do and where, never a pitch
+export const CREDITS_LOW_NOTE = `The Hermoso account does not have enough credits for this. Tell the user plainly. ${ACCOUNT_CREDITS_LINE} Nothing can be bought from here.`;
 const UPSELL_SENTENCE_RE = /\s*(?:please\s+)?(?:upgrade(?:\s+your\s+plan)?\s+or\s+top\s+up|top\s+up|add\s+credits|buy\s+(?:more\s+)?credits|monthly\s+plans\s+have\s+no\s+markup\s+on\s+models)\b[^.!\n]*[.!]?/gi; // the monthly-plan upsell (2026-10-20) is a promotion too: a widget host (ChatGPT) never hears it
 // ── FREE CREDITS NOT CLAIMED YET (2026-10-25, ChatGPT funnel) ─────────────────────────────────────────────────────
 // An account whose welcome credits were never added (the one-time check that a person is behind it did not pass
@@ -165,8 +205,73 @@ const UPSELL_SENTENCE_RE = /\s*(?:please\s+)?(?:upgrade(?:\s+your\s+plan)?\s+or\
 // said on every host, ChatGPT included. The server marks the refusal (meta.welcomeClaim = {credits, url}).
 export const welcomeClaimSentence = (w) => `This account has not received its ${Number(w?.credits) || 0} free credits yet. The user opens ${w?.url} once in a browser (one click, no sign-in and no card) and they arrive in a few seconds after a quick check that a person is there.`;
 export const welcomeClaimHint = (w) => ({ do: `ask the user to open ${w?.url} once in a browser (one click, no sign-in) to receive the ${Number(w?.credits) || 0} free credits; then run the same call again`, why: 'the account never received its free credits: they wait behind a one-time check that a person is behind the account, which runs in the browser' });
-export function neutralCreditsText(msg) {
-  const base = String(msg ?? '').replace(UPSELL_SENTENCE_RE, '').replace(/[ \t]+$/gm, '').replace(/\s*[—–,:-]\s*$/gm, '.').trim();
-  return `${base}${base ? '\n' : ''}${CREDITS_LOW_NOTE}`;
+export function neutralCreditsText(msg, nums = {}) {
+  const base = stripPlanPromo(String(msg ?? '').replace(UPSELL_SENTENCE_RE, '')).replace(/[ \t]+$/gm, '').replace(/\s*[—–,:-]\s*$/gm, '.').trim();
+  // The numbers, when the server's sentence did not carry them ("You’re out of credits." does not): read from the refusal's
+  // structured block (e.buy.need / .balance), never parsed from prose. A count, not a price.
+  const need = Math.round(Number(nums?.need) || 0), bal = Number(nums?.balance);
+  const numLine = need > 0 && !/\bneeds?\b[^.\n]*\d/i.test(base) ? `This needs about ${need} credits${Number.isFinite(bal) && nums?.balance != null ? ` and the account has ${Math.max(0, Math.floor(bal))}` : ''}.` : '';
+  return [base, numLine, CREDITS_LOW_NOTE].filter(Boolean).join('\n');
+}
+// ── NO PLAN PITCH ON A WIDGET HOST, WHEREVER IT CAME FROM (2026-11-12) ────────────────────────────────────────────
+// Measured on production: a ChatGPT out-of-credits refusal carried no price and no checkout link and STILL ended
+// "Starter, Pro and Studio have no markup on models, so your credits go twice as far." — the server's withPlanUpsell
+// sentence (server.js PLAN_UPSELL_LINE, or its "on one of those plans this needs about N" form), which UPSELL_SENTENCE_RE
+// above did not know. OpenAI's app guidelines: apps "may not … promote upgrades". So the rule is a SENTENCE filter, not a
+// list of known sentences: on a widget host any sentence (or list item) that pitches a plan, names a purchase tool, a
+// price, a checkout or a top-up is dropped, and the neutral line (ACCOUNT_CREDITS_LINE) says what to do and where.
+// Two strengths. PLAN_PROMO_RE is for text that is ABOUT credits or the account (a credits refusal, the capability map),
+// where "$" or "upgrade" can only be selling. PLAN_PITCH_RE is narrow enough for any reply on a widget host (a budget
+// error says "$5", ad copy says "go further"): only our own pitch phrases and the purchase tools' names.
+export const PLAN_PROMO_RE = /\b(?:buy_credits|upgrade_plan|set_auto_reload|billing_status)\b|\bupgrad(?:e|es|ed|ing)\b|no markup|twice as far|\bgo(?:es)? further\b|checkout|\btop[- ]?ups?\b|\$\s?\d|WHY HERMOSO|\bcredit packs?\b|\bper month\b|\/mo\b/i;
+export const PLAN_PITCH_RE = /no markup on (?:image, video and voice )?models|credits? go(?:es)? (?:twice as far|further)|\bStarter, Pro and Studio\b|\b(?:buy_credits|upgrade_plan|set_auto_reload|billing_status)\b/i;
+// Split `s` at every `sep` that sits outside parentheses/brackets, so "(a, b; c)" is never cut in half.
+function splitTop(s, sep) {
+  const out = []; let depth = 0, from = 0;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (ch === '(' || ch === '[' || ch === '{') depth++;
+    else if ((ch === ')' || ch === ']' || ch === '}') && depth > 0) depth--;
+    else if (depth === 0) {
+      if (sep === 'sentence') { if (/[.!?]/.test(ch) && /\s/.test(s[i + 1] || '')) { out.push(s.slice(from, i + 1)); from = i + 1; } }
+      else if (s.startsWith(sep, i)) { out.push(s.slice(from, i)); from = i + sep.length; i += sep.length - 1; }
+    }
+  }
+  out.push(s.slice(from));
+  return out;
+}
+const PROMO_LEVELS = [['sentence', ' '], ['; ', '; '], [' · ', ' · ']];
+export function stripPlanPromo(text, re = PLAN_PROMO_RE) {
+  const prune = (s, levels) => {
+    if (!re.test(s)) return s;
+    for (let k = 0; k < levels.length; k++) {
+      const [sep, join] = levels[k];
+      const parts = splitTop(s, sep);
+      if (parts.length < 2) continue;
+      return parts.map((p) => prune(sep === 'sentence' ? p.trim() : p, levels.slice(k + 1))).filter((p) => p.trim()).join(join);
+    }
+    return '';
+  };
+  const src = String(text ?? '');
+  if (!re.test(src)) return src;
+  return src.split('\n').map((line) => (re.test(line) ? { line: prune(line, PROMO_LEVELS), cut: true } : { line, cut: false }))
+    .filter((x) => !(x.cut && !x.line.trim())).map((x) => x.line).join('\n');
+}
+// A reply on a widget host, with every pitch sentence out of its text blocks (a JSON block is data and left whole) and
+// out of its hints. The result object is copied, never edited in place.
+export function withoutPlanPitch(r, re = PLAN_PITCH_RE) {
+  if (!r || typeof r !== 'object') return r;
+  let out = r;
+  if (Array.isArray(r.content) && r.content.some((b) => b && b.type === 'text' && typeof b.text === 'string' && re.test(b.text) && !/^\s*[[{]/.test(b.text))) {
+    out = { ...out, content: r.content.map((b) => (b && b.type === 'text' && typeof b.text === 'string' && !/^\s*[[{]/.test(b.text) ? { ...b, text: stripPlanPromo(b.text, re) } : b)) };
+  }
+  const h = out._meta && Array.isArray(out._meta[HINTS_KEY]) ? out._meta[HINTS_KEY] : null;
+  if (h && h.some((x) => PLAN_PROMO_RE.test(`${x.do} ${x.why}`))) {
+    const kept = h.filter((x) => !PLAN_PROMO_RE.test(`${x.do} ${x.why}`));
+    const meta = { ...out._meta };
+    if (kept.length) meta[HINTS_KEY] = kept; else delete meta[HINTS_KEY];
+    out = { ...out, _meta: meta };
+  }
+  return out;
 }
-export const creditsLowHints = () => [{ do: `tell the user the balance is too low for this; they manage credits at ${ACCOUNT_INFO_URL}`, why: 'this host does not offer purchases, so nothing is bought from here' }];
+export const creditsLowHints = () => [{ do: `tell the user the account does not have enough credits for this; they can add credits or pick a plan in their Hermoso account at ${ACCOUNT_INFO_URL}, then ask again`, why: 'this host does not offer purchases, so nothing is bought from here' }];