hermoso 0.1.372 → 0.1.373

package/README.md

@@ -5,21 +5,22 @@ 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.
 
-**874 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
+**892 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
-and insights, comments and DMs, connectors, brand profiles and team seats are **free on every plan**, with no
+and insights, comments and DMs, connectors, profiles and team seats are **free on every plan**, with no
 per-post or per-channel fee and no seat pricing. Credits are spent only on running an AI model (image, video,
 voice, text, planning, post-production) and on Ad Spy research, and posting an ad you already rendered is never a
 second charge. The one exception is X (Twitter), where posting and reads bill a few credits per call because X
 charges per API request.
 
 **What it connects to.** Ad platforms: Meta, Google Ads, TikTok Ads, LinkedIn Ads, Reddit Ads, X Ads,
-Pinterest Ads, Snapchat Ads, Microsoft Advertising, Apple Search Ads and ChatGPT Ads, plus product feeds in
-Google Merchant Center. Publishing and scheduling — **ten** channels: Facebook, Instagram, Threads, TikTok,
-YouTube, X, LinkedIn, Pinterest, Bluesky and Telegram. Messaging: WhatsApp (you message a person, so it is not an
-eleventh publishing channel). Ad research: the Meta, Google and LinkedIn ad libraries plus organic TikTok,
+Pinterest Ads, Snapchat Ads, Microsoft Advertising, Apple Search Ads, ChatGPT Ads and AppLovin Ads, plus
+product feeds in Google Merchant Center. Publishing and scheduling — **ten** channels: Facebook, Instagram,
+Threads, TikTok, YouTube, X, LinkedIn, Pinterest, Bluesky and Telegram. Messaging: WhatsApp (you message a
+person, so it is not an eleventh publishing channel) and Instagram DM automations (a keyword comment, a DM, a
+story reply or an ig.me link gets an automatic private reply). Ad research: the Meta, Google and LinkedIn ad libraries plus organic TikTok,
 Instagram, YouTube, Threads and Reddit. Analytics: Google Analytics 4, Google Search Console and every
 connected platform's own post and campaign insights. Files: Google Drive, Sheets, Docs and OneDrive.
 
@@ -200,7 +201,7 @@ into your sessions. If you want the connector: `claude mcp add --transport http
 and `claude mcp list` reports `! Needs authentication` until you run `claude mcp login hermoso` once and approve in
 your browser (`--no-browser` prints the link on a headless machine). Measured against Claude Code 2.1.282 on 2026-09-25.
 
-Your agent now has the full studio **with your workspace's context**: the brand profile, products, logos and
+Your agent now has the full studio **with your profile's context**: the brand details, products, logos and
 learned memory you set up in the web app apply automatically (`get_brand` shows what's saved; omit `brand` in
 `plan_ad`/`plan_variations` to use it). Renders bill your Hermoso credits, at the same prices as the Studio. Only AI model runs and Ad Spy research spend credits; publishing, scheduling, ads management and analytics are free on every plan (posting to X and reading X data are the one per-call exception, managing X ads is free).
 
@@ -230,7 +231,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 874 tools cover
+### What the 892 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
@@ -280,10 +281,20 @@ anything pending: **Hermoso does not receive WhatsApp webhooks, so there is no m
 not an inbox surface and `list_inbox` does not cover it — and **outside the 24-hour window that opens when the
 customer messages first, WhatsApp accepts an APPROVED template and nothing else.**
 
+**Automate Instagram DMs** — `save_instagram_dm_automation` sets up a rule that answers people for the brand: a
+comment with a keyword on one post, the next post or any post gets a private reply, and a DM, a story reply or an
+ig.me link gets an answer, with optional link buttons, a public comment reply, a follow gate and a dry run.
+`test_instagram_dm_automation` shows exactly what a sample comment or DM would send without sending it, and
+`list_instagram_dm_automations` / `delete_instagram_dm_automation` read each rule's stats and send log or remove
+it. Each person gets one reply per post, Meta allows a private reply within 7 days of the comment, and no AI runs
+on the send path, so it costs no credits.
+
 **Run the ads** — full campaign trees, built paused and read back before anything is reported, with every spend
-change confirm-gated, on **eleven** platforms: **Meta**, **Google Ads**, **LinkedIn Ads**, **Reddit Ads**,
+change confirm-gated, on **twelve** platforms: **Meta**, **Google Ads**, **LinkedIn Ads**, **Reddit Ads**,
 **Pinterest Ads**, **Microsoft Advertising**, **ChatGPT Ads** (OpenAI's Advertiser API), **X Ads**, **TikTok Ads**,
-**Snapchat Ads** and **Apple Ads** (Apple Search Ads on the App Store). Each has list + report + create + budget/status tools
+**Snapchat Ads**, **Apple Ads** (Apple Search Ads on the App Store) and **AppLovin Ads** (reporting and the website
+pixel on the keys every account has; campaign building once AppLovin enables Campaign Management API access on the
+account, and server-side conversion events with the Conversion API key AppLovin issues on request). Each has list + report + create + budget/status tools
 (e.g. `list_google_ads_campaigns`, `google_ads_report`, `create_google_ads_campaign`, `set_google_ads_budget`,
 `set_google_ads_status`). *Snapchat needs one extra step the others do not: an ad points at a CREATIVE, and every
 Snapchat creative must carry a Public Profile id — build it with `upload_snapchat_ads_creative`.*
@@ -314,8 +325,8 @@ property holds 50 event-scoped ones.*
 `create_drive_folder`), Google Sheets (`create_sheet`, `append_to_sheet`, `read_sheet`), Google Docs
 (`create_doc`, `append_to_doc`), and OneDrive (`save_to_onedrive` + full CRUD).
 
-**Workspace & account** — brand workspaces (`list_brands`, `create_brand`, `use_brand`, `update_brand`,
-`delete_brand` — one account holds many brands, so an agency runs every client through here), memory
+**Workspace & account** — profiles (`list_brands`, `create_brand`, `use_brand`, `update_brand`,
+`delete_brand`; one account holds many profiles, each a brand, a client, a creator or a personal workspace, so an agency runs every client through here), memory
 (`remember`, `forget`, `list_memory`), custom skills (`save_skill`, `get_skill`, `list_skills`,
 `delete_skill` — the one library, which absorbed the old AI-Employee personas), team (`list_team`, `invite_member`, `remove_member`,
 `set_role`), settings (`get_settings`, `update_settings` — including the **language** every ad, script and plan
@@ -324,7 +335,7 @@ is written in), connectors (`list_connectors`, `list_connector_accounts`, `set_c
 `set_auto_reload`), plus `list_jobs` / `get_job` for async renders.
 
 **Connector accounts are picked, not guessed.** One person often administers several Facebook Pages, Google Ads
-customers or LinkedIn company Pages. Only the accounts ticked for a brand are usable — enforced server-side, and
+customers or LinkedIn company Pages. Only the accounts ticked for a profile are usable — enforced server-side, and
 an empty selection shares nothing. Linking a *new* account is the one step that is not headless (it is an OAuth
 consent screen, so the user does it in the app).
 
@@ -400,8 +411,8 @@ The skills pick themselves. These are whole prompts, not commands:
 | --- | --- |
 | `HERMOSO_API_BASE` | The Hermoso API origin (default `https://app.hermoso.ai` — set `http://localhost:3000` if you run the app yourself) |
 | `HERMOSO_TOKEN` | Bearer agent key (`hmk_…`) — required against the hosted app |
-| `HERMOSO_PROFILE` | Brand-workspace id, for accounts with multiple brand profiles |
-| `HERMOSO_OWNER` | Only for a brand **another account shared with you** (a team workspace): the owning account id. Set it together with `HERMOSO_PROFILE`, and set `HERMOSO_PROFILE` to that workspace's **profileUuid** — a brand's short slug is refused. Run `list_brands` (or `hermoso list_brands` from the CLI) to print both values for every workspace you can enter. The server re-authorizes the pair on every request, so a wrong value is refused, never trusted. |
+| `HERMOSO_PROFILE` | Profile id, for accounts with multiple profiles |
+| `HERMOSO_OWNER` | Only for a profile **another account shared with you** (a team workspace): the owning account id. Set it together with `HERMOSO_PROFILE`, and set `HERMOSO_PROFILE` to that workspace's **profileUuid** (a profile's short slug is refused). Run `list_brands` (or `hermoso list_brands` from the CLI) to print both values for every workspace you can enter. The server re-authorizes the pair on every request, so a wrong value is refused, never trusted. |
 
 `mcp/http.mjs` is the hosted remote-connector transport (paste-a-URL into Claude.ai → Connectors). It ships in
 this repo for transparency and refuses to mount without authenticated identity — no anonymous spend, ever.

package/bin/hermoso.mjs

@@ -129,7 +129,7 @@ async function main() {
         // profile" and it died with the `brand draft` usage line instead — the first command a new user copies off
         // the CLI page. It is get_brand, run through the same handler the MCP twins use.
         if (!sub) { const reg = await import('../mcp/registry.mjs'); return await runTool(reg, 'get_brand', flags, []); }
-        if (sub !== 'draft') return die('usage: hermoso brand            the saved brand profile\n       hermoso brand draft (--domain <d> | --description <t> | --social <h> --platform <p>)');
+        if (sub !== 'draft') return die('usage: hermoso brand            the saved profile (a brand, creator or personal workspace)\n       hermoso brand draft (--domain <d> | --description <t> | --social <h> --platform <p>)');
         const body = flags.domain ? { domain: flags.domain } : flags.description ? { description: flags.description } : flags.social ? { socialHandle: flags.social, platform: flags.platform || 'instagram' } : null;
         if (!body) return die('give --domain, --description, or --social');
         const d = await api.apiPost('/api/brand/draft', body); const p = d.profile || d;

package/mcp/client.mjs

@@ -226,7 +226,40 @@ export async function apiGet(p, query) {
 const TRANSPORT_RE = /fetch failed|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|socket hang up|network|terminated/i;
 const isTransport = (e) => !!e && e.name === 'TypeError' && TRANSPORT_RE.test(String(e.message || '') + ' ' + String(e.cause?.code || e.cause?.message || ''));
 
-async function fetchRead(url, init) {
+// ── THE PLATFORM'S OWN 429 NEVER REACHED US, SO IT IS RETRIED HERE (2026-10-04) ───────────────────────────────
+// Polling a job every 10 seconds from the CLI answered HTTP 429, and it was not a limit of ours: the app has no limiter
+// on GET /api/jobs/:id, and /v1 reads allow 300 a minute per key. Every one of those 429s in the Cloud Run request log
+// (36 between 18:35 and 18:39Z, on /api/credits, GET / and webhooks as much as on job polls) is the platform's "The
+// request was aborted because there was no available instance": a plain-text body, latency 0s, refused before the
+// container saw it, while the one instance's CPU sat pegged by local renders at 2-7 concurrent requests. The browser's
+// api() has retried that answer since 2026-09-06; the CLI and the stdio MCP read it as a failed call, so one busy
+// second ended a render wait. A refusal that never reached the app ran nothing, so it is retried for ANY method; the
+// app's own refusals always answer JSON and pass through untouched (their rules are theirs). A read also rides out a
+// plain-text 502/503/504 (a rollover seen from outside); a write does not, because those can come back after the app
+// already had the request. Waits are env-tunable so a check can run the real loop in milliseconds.
+export const FRONT_DOOR_WAITS_MS = [2000, 5000, 10000];
+const frontDoorWaits = () => { const v = String(process.env.HERMOSO_FRONT_DOOR_WAITS_MS || '').split(',').map(Number).filter((n) => Number.isFinite(n) && n >= 0); return v.length ? v : FRONT_DOOR_WAITS_MS; };
+/** Did the PLATFORM refuse this before it reached the app? Pure: our routes always answer JSON. */
+export function isFrontDoorRefusal(status, contentType, { read = false } = {}) {
+  const st = Number(status);
+  if (/json/i.test(String(contentType || ''))) return false;
+  return st === 429 || (read && (st === 502 || st === 503 || st === 504));
+}
+export const FRONT_DOOR_MESSAGE = 'Hermoso\u2019s server was briefly too busy to take the request and turned it away before the app saw it (HTTP 429). It was retried and the server was still busy. Nothing ran and nothing was charged: try again in a minute.';
+async function throughFrontDoor(send, { read }) {
+  let res = await send();
+  for (const ms of frontDoorWaits()) {
+    if (!isFrontDoorRefusal(res.status, res.headers?.get?.('content-type'), { read })) return res;
+    try { await res.arrayBuffer(); } catch { /* drain, so the socket is reused */ }
+    await new Promise((r) => setTimeout(r, ms));
+    res = await send();
+  }
+  if (isFrontDoorRefusal(res.status, res.headers?.get?.('content-type'), { read })) throw Object.assign(new Error(FRONT_DOOR_MESSAGE), { status: res.status, _frontDoor: true });
+  return res;
+}
+
+async function fetchRead(url, init) { return throughFrontDoor(() => fetchReadOnce(url, init), { read: true }); }
+async function fetchReadOnce(url, init) {
   try { return await fetch(url, init); }
   catch (e) {
     if (!isTransport(e)) throw e;
@@ -239,7 +272,8 @@ async function fetchRead(url, init) {
   }
 }
 
-async function fetchWrite(url, init) {
+async function fetchWrite(url, init) { return throughFrontDoor(() => fetchWriteOnce(url, init), { read: false }); }
+async function fetchWriteOnce(url, init) {
   try { return await fetch(url, init); }
   catch (e) {
     if (!isTransport(e)) throw e;
@@ -469,7 +503,8 @@ 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';
+  // a throttle is not news about the render: a poll that was turned away waits and asks again (2026-10-04)
+  if ((st === 429 || st === 502 || st === 503 || st === 504) && now < deadline) return 'retry';
   return 'throw';
 }
 export function jobMissMessage(id) {

package/mcp/http.mjs

@@ -17,6 +17,7 @@ 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 } from './tools.mjs';
+import { chatgptExtAsked } 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.
@@ -380,6 +381,10 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
   // `?src=<surface>` on the published URL (registry / glama / smithery / cursor / readme …) — attribution only. It may
   // not change auth, scope or spend, and an unrecognisable value is simply dropped. The OAuth resource metadata is
   // path-based (RFC 9728), so a query on the pasted URL changes nothing about the handshake.
+  // `?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);
   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);
 
@@ -402,7 +407,7 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
     // every one of those the roster IS the product description. Serving them the core set would publish Hermoso as
     // a 22-tool server on ~430 directory pages. So an UNSTATED scope here resolves to the full pre-core-first
     // default rather than to the session default; an explicit `?tools=` still wins, exactly as it does below.
-    registerTools(server, { only: scope?.groups || [...DEFAULT_TOOL_GROUPS], directory: scope?.directory || false, widgetHost, hosted: true }); // metadata only — tools/list never invokes a handler, and tools/call can't reach here
+    registerTools(server, { only: scope?.groups || [...DEFAULT_TOOL_GROUPS], directory: scope?.directory || false, widgetHost, hosted: true, ext: extAsked(req) }); // 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
@@ -517,7 +522,7 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
       // 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, connectors, widgetHost, 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
+      registerTools(server, { only: scope.groups, directory: scope.directory || false, 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
       const transport = new StreamableHTTPServerTransport({
         // CSPRNG, per the spec's SHOULD for session ids (Math.random() is not one).
         sessionIdGenerator: () => 'sess_' + randomUUID().replace(/-/g, ''),