hermoso 0.1.310 → 0.1.330

package/README.md

@@ -5,7 +5,7 @@ scripts. Research the ads already winning in a market, generate finished image &
 composited in, copy + CTA included), publish them to your own social channels, and build & manage the ad
 campaigns behind them, all over [MCP](https://modelcontextprotocol.io) tools, a CLI, or installable Claude skills.
 
-**863 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
+**864 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.
 
 **Most of it costs nothing.** Publishing and scheduling posts, building and managing paid campaigns, analytics
@@ -175,7 +175,7 @@ claude plugin marketplace add hermoso-ai/hermoso && claude plugin install hermos
    Codex, Gemini CLI and the rest are in [Install in one command](#install-in-one-command).
 3. **Sign in once.** `npx -y hermoso auth login` opens your browser; your agent also runs it by itself the first
    time it needs Hermoso. On a machine with no browser, use `npx -y hermoso auth login --token hmk_…` with a key
-   from the **MCP & CLI** tab, under **Terminal & API keys**.
+   from the **MCP & CLI** tab, under **Terminal & API keys** (Settings → API keys, or https://app.hermoso.ai/?tab=api-keys, go straight there).
 4. **Ask for what you want**, in your normal prompts. Claude Code picks the Hermoso skill for the job and runs the
    commands. You type none of them.
 
@@ -217,7 +217,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 863 tools cover
+### What the 864 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/bin/hermoso.mjs

@@ -77,7 +77,7 @@ async function main() {
     if (isLocal) { await saveConfig({ apiBase, token: '', profile }); return console.log(`✓ Local dev — no auth required. API: ${apiBase}`); }
     if (sub === 'login') { // browser sign-in: spin a loopback server, open the app's /?cliauth page, receive a minted key
       const key = await browserLogin(apiBase);
-      if (!key) return die(`Sign-in didn’t complete. Re-run "hermoso auth login", or paste a key: hermoso auth login --token <key>  (create one in the app on the MCP & CLI tab, under Terminal & API keys).`);
+      if (!key) return die(`Sign-in didn’t complete. Re-run "hermoso auth login", or paste a key: hermoso auth login --token <key>  (create one at https://app.hermoso.ai/?tab=api-keys, the MCP & CLI tab under Terminal & API keys).`);
       await saveConfig({ apiBase, token: key, profile });
       return console.log(`✓ Signed in — key stored (~/.hermoso/config.json). API: ${apiBase}`);
     }

package/mcp/client.mjs

@@ -330,7 +330,9 @@ export async function connectedProviders() {
     // connectLink: the app deep link for THIS brand with a {provider} slot, so a tool held back for a missing
     // connection can hand the user the one-click link instead of only naming the Connectors page.
     const connectLink = typeof r?.connectLink === 'string' && r.connectLink.includes('{provider}') ? r.connectLink : '';
-    return { connected: new Set(list.filter((p) => typeof p === 'string' && p)), readOk: true, offered, gated, connectLink };
+    // withheld: tools the server does not offer right now (roster-scope.mjs toolWithheldByServer). Absent = none.
+    const withheld = new Set((Array.isArray(r?.withheld) ? r.withheld : []).filter((n) => typeof n === 'string' && n));
+    return { connected: new Set(list.filter((p) => typeof p === 'string' && p)), readOk: true, offered, gated, connectLink, withheld };
   } catch { return { connected: new Set(), readOk: false }; }
 }
 // Upload raw file BYTES to /api/upload (150MB, persists → returns {url,kind,bytes}). Overrides the JSON content-type so
@@ -429,10 +431,38 @@ export function jobWaitMs(requested, cap) {
   return Math.min(cap, Math.floor(n));
 }
 
-export async function pollJob(id, { intervalMs = 3000, timeoutMs = 10 * 60 * 1000, onTick } = {}) {
-  const deadline = Date.now() + timeoutMs;
+// A 404 IN THE SECONDS AFTER A SUBMIT IS NOT "NO SUCH JOB" (journey QA 2026-09-25). edit_video queued a render on the
+// revision a deploy was retiring; the poll 3s later reached the new revision, which had never heard of it, and the tool
+// answered "Error: No such job" about a real render that held credits. The server now reads through to the durable job
+// mirror before a 404 (lib/job-readthrough.mjs), and this is the client half: inside a short grace from the submit a
+// 404 (and a 502/503/504, which is what a rollover looks like from outside) is retried; past it a 404 is final and is
+// said in words, never as the bare route error. PURE, so tools/job-readthrough-check.mjs runs it.
+export const JOB_MISS_GRACE_MS = 30_000;
+export function pollMissVerdict(status, { startedAt, now = Date.now(), deadline = Infinity, graceMs = JOB_MISS_GRACE_MS } = {}) {
+  const st = Number(status);
+  if (st === 404) return (now - startedAt < graceMs && now < deadline) ? 'retry' : 'final';
+  if ((st === 502 || st === 503 || st === 504) && now < deadline) return 'retry';
+  return 'throw';
+}
+export function jobMissMessage(id) {
+  return `Hermoso has no record of job ${id} on this workspace, after checking the live queue and the durable job store for ${Math.round(JOB_MISS_GRACE_MS / 1000)}s. `
+    + 'If it was just submitted, the server that took it was replaced before it wrote the job down, so it cannot be followed from here. A render lost that way is not charged: the credits held for it are released automatically. '
+    + 'Call list_jobs to see this workspace\'s recent jobs. Do not re-run the render on the strength of this message alone.';
+}
+export async function pollJob(id, { intervalMs = 3000, timeoutMs = 10 * 60 * 1000, onTick, getJobFn = getJob } = {}) {
+  const startedAt = Date.now();
+  const deadline = startedAt + timeoutMs;
   for (;;) {
-    const job = await getJob(id);
+    let job;
+    try { job = await getJobFn(id); }
+    catch (e) {
+      const v = pollMissVerdict(e?.status, { startedAt, now: Date.now(), deadline });
+      if (v === 'final') throw Object.assign(new Error(jobMissMessage(id)), { status: 404, _viaApi: true, _jobMissing: true });
+      if (v === 'throw') throw e;
+      await new Promise(r => setTimeout(r, Math.min(intervalMs, Math.max(50, deadline - Date.now()))));
+      if (Date.now() > deadline) throw Object.assign(new Error('Render timed out — check `hermoso jobs get ' + id + '`'), { jobId: id });
+      continue;
+    }
     onTick?.(job);
     if (job.status === 'done') return { job, result: jobResult(job) };
     // A FAILED JOB HAS ALREADY BEEN RECORDED BY THE SERVER (2026-09-21). The job runner files the worker's real error in

package/mcp/http.mjs

@@ -16,7 +16,7 @@ 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, parseToolScope, DEFAULT_TOOL_GROUPS } from './tools.mjs';
+import { registerTools, MCP_INSTRUCTIONS, instructionsFor, parseToolScope, DEFAULT_TOOL_GROUPS } from './tools.mjs';
 import { mcpCtx, connectedProviders } from './client.mjs';
 
 // Mount the remote connector onto the Express app. No-op unless explicitly enabled + auth-backed.
@@ -310,9 +310,37 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
   // Directories that list tools with a sign-in (Smithery, Glama's inspector, OpenAI's and Anthropic's reviews) use
   // OAuth already. SIGNIN_UPFRONT_CLIENTS still wins over a bot-looking UA.
   const ANON_PREVIEW_UA_RE = /\+https?:\/\/|\b(bot|crawler|spider|probe|scanner|health-?check|uptime|monitor|liveness|registry|collector|audit|checkup|validator|indexer|tripwire|research|catalog-health|signals)\b|mcpbeat|sentineloracle|mcp-watch|mcpwatch|verifymcp|mcp\.market|proofbench|factanker/i;
+  // ── A DIRECTORY HEALTH CHECK THAT DOES NOT SAY WHAT IT IS IN ITS UA, RECOGNISED BY NAME + UA TOGETHER (2026-09-25) ──
+  // Glama's connector health check (glama.ai/mcp/connectors/io.github.hermoso-ai/hermoso) sends UA "node" — bare,
+  // exactly what Gemini CLI sends — so the UA rule above cannot see it, and since the inversion it has been 401 every
+  // ~20 min and the listing reads "Status: Unhealthy". Matched on the evidence, not a guess: its "Last Tested" stamp
+  // moved 01:05 → 01:24 UTC on 2026-09-26 in step with our tokenless `node` POSTs at 01:05:36 and 01:24:22, and the
+  // one pre-inversion [mcp-anon] line on that cadence names clientInfo "mcpdd" (2026-09-25T13:34:47). It keeps the
+  // preview only when BOTH match, so neither Gemini CLI ("node" + "mcp-test-client") nor any other host naming
+  // itself differently changes state. Glama's user connections are configured as OAuth on their side (the listing's
+  // inspector links carry authType "oauth"), so they never decide sign-in from this answer.
+  // NOT here, deliberately: python-httpx2 (sends a foreign bearer "ligh…" on retry, unidentified — it is not the
+  // Glama check, whatever an earlier note said), docker-mcp-gateway and Go-http-client (a gateway carrying real
+  // users), and mcp.so's "Fetch tools" (UA node, name unknown; it already falls through to our OAuth). The refused
+  // line below logs the clientInfo of every challenged tokenless initialize, so the next entry comes from evidence.
+  const DIRECTORY_PROBES = [{ client: 'mcpdd', ua: /^node$/i }]; // Glama connector health check
+  const directoryProbe = (req) => {
+    const name = clientInfoOf(req.body); const ua = String(req.headers['user-agent'] || '');
+    return !!name && DIRECTORY_PROBES.some((p) => p.client === name && p.ua.test(ua));
+  };
+  // THE PREVIEW HAS TO OUTLAST THE INITIALIZE. Only the initialize carries clientInfo; the tools/list that follows is
+  // a bare tokenless POST from UA "node", indistinguishable from anyone. So a preview granted by NAME answers the
+  // initialize with an Mcp-Session-Id marked as a preview, the SDK client echoes it, and a tokenless follow-up that
+  // carries it keeps the preview. It unlocks nothing `?auth=none` does not already give anyone (the public tool list;
+  // tools/call is refused on this path whatever the header says), and no host that connects users ever holds one,
+  // because we only ever issue it to a name on the list above. The anonymous transport is stateless, so the SDK
+  // ignores the id rather than validating it.
+  const ANON_PREVIEW_SID_PREFIX = 'anonpreview_';
+  const heldPreviewSession = (req) => String(req.headers['mcp-session-id'] || '').startsWith(ANON_PREVIEW_SID_PREFIX);
   const anonPreviewAllowed = (req) => {
     if (String(req.query?.auth || '').toLowerCase() === 'none') return true;
     if (signinUpfront(req)) return false;
+    if (directoryProbe(req) || heldPreviewSession(req)) return true;
     return ANON_PREVIEW_UA_RE.test(String(req.headers['user-agent'] || ''));
   };
   const isAllPreauth = (body) => {
@@ -347,7 +375,7 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
   const methodsOf = (body) => (Array.isArray(body) ? body : [body]).map((m) => m && m.method).filter(Boolean);
 
   async function serveAnonDiscovery(req, res, scope) {
-    const server = new McpServer({ name: 'hermoso', version: PKG_VERSION }, { instructions: MCP_INSTRUCTIONS });
+    const server = new McpServer({ name: 'hermoso', version: PKG_VERSION }, { instructions: instructionsFor(scope) });
     // `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
     // only the authenticated path would leave both tools listed in the submission.
@@ -372,6 +400,9 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
       try { const m = (Array.isArray(req.body) ? req.body : [req.body]).find((x) => x && x.method === 'initialize'); const ci = m?.params?.clientInfo || {}; console.error(`[mcp-anon] initialize client=${JSON.stringify(String(ci.name || '').slice(0, 64))} v=${JSON.stringify(String(ci.version || '').slice(0, 24))} proto=${String(m?.params?.protocolVersion || '').slice(0, 16)} ua=${JSON.stringify(String(req.headers['user-agent'] || '').slice(0, 80))} src=${srcOf(req) || '-'}`); } catch {}
     }
     if (typeof onAnonDiscovery === 'function' && methodsOf(req.body).includes('tools/list')) { try { onAnonDiscovery({ client: clientInfoOf(req.body), ua: String(req.headers['user-agent'] || '').slice(0, 120), src: srcOf(req) }); } catch {} }
+    // A preview granted by name carries its marker into the follow-ups (see ANON_PREVIEW_SID_PREFIX); set before the
+    // transport writes, and Node merges it into the SDK's own headers.
+    if (methodsOf(req.body).includes('initialize') && directoryProbe(req)) res.setHeader('mcp-session-id', ANON_PREVIEW_SID_PREFIX + randomUUID().replace(/-/g, ''));
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
     res.on('close', () => { try { transport.close(); server.close(); } catch {} });
     await server.connect(transport);
@@ -400,6 +431,11 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
         if (scope === false) return; // unknown group — already answered 400
         return serveAnonDiscovery(req, res, scope).catch(() => { try { challenge(res); } catch {} });
       }
+      // The refused half of the [mcp-anon] line: the clientInfo a challenged tokenless initialize named, so a
+      // directory check that starts failing can be identified from the log instead of guessed from its UA.
+      if (!token && req.method === 'POST' && methodsOf(req.body).includes('initialize')) {
+        try { console.error(`[mcp-anon] refused initialize client=${JSON.stringify(clientInfoOf(req.body))} ua=${JSON.stringify(String(req.headers['user-agent'] || '').slice(0, 80))} src=${srcOf(req) || '-'}`); } catch {}
+      }
       return challenge(res);
     }
 
@@ -460,7 +496,7 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
       // OPEN with the full roster, so the whole change would be silently inert. Never throws; see
       // connectedProviders() ([[failed-read-is-not-empty]]).
       const connectors = await mcpCtx.run({ token, remote: true, client: rememberedClient(req) }, () => connectedProviders());
-      const server = new McpServer({ name: 'hermoso', version: PKG_VERSION }, { instructions: MCP_INSTRUCTIONS });
+      const server = new McpServer({ name: 'hermoso', version: PKG_VERSION }, { instructions: instructionsFor(scope) });
       registerTools(server, { only: scope.groups, directory: scope.directory || false, connectors, widgetHost: isWidgetHost(entry?.client || clientInfoOf(req.body), req) , hosted: true, 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).

package/mcp/roster-scope.mjs

@@ -156,7 +156,15 @@ export const metaAlternativeNote = (name) => INSTAGRAM_LOGIN_TOOLS.has(String(na
   : isWhatsAppTool(name)
     ? ' A WhatsApp Business Account the business already manages is ticked on the "meta" connection\'s assets step; the "whatsapp" connection sets up a number the business does not have yet. Either one is enough for this tool.'
     : '';
+// ── A TOOL THE SERVER WITHHOLDS FROM EVERY ROSTER (2026-09-27, owner: "why do we even allow access to creator
+// marketplace if we can't even access it ourselves?"). `withheld` rides the same /api/connectors/providers read as the
+// connected set: the server names the tools whose capability it does not offer right now (today: the Instagram
+// creator marketplace trio while META_CREATOR_MARKETPLACE_SCOPE is off). ONE server flag decides it, so flipping the
+// env var lights every surface back up with no code change. Absent or unreadable = nothing withheld (fail open, like
+// every other read of this set); a withheld tool is held like a connector-gated one and answered as 'unavailable'.
+export function toolWithheldByServer(name, conn) { return !!(conn && conn.withheld instanceof Set && conn.withheld.has(String(name || ''))); }
 export function toolHeldBackByConnectors(name, conn) {
+  if (toolWithheldByServer(name, conn)) return true;              // the server says this capability is not offered now
   if (!conn || !conn.readOk) return false;                       // property 1 — fail OPEN on an unreadable store
   const p = toolProvider(name);
   if (p === null) return false;                                  // property 2 — unmapped is never held back