hermoso 0.1.142 → 0.1.152

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.
 
-**681 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
+**709 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.
 
 **What it connects to.** Ad platforms: Meta, Google Ads, TikTok Ads, LinkedIn Ads, Reddit Ads, X Ads,
@@ -22,6 +22,47 @@ ad-build tool accepts); build and read campaigns on your own ad accounts with yo
 competitors with no brand drafted and no channel connected; or generate a file with nothing connected at all and
 just download it. Use the one piece you need, or all of it together.
 
+## Which surface should your agent use?
+
+Two shapes, and the right one is decided by **what your client can do**, not by which we prefer.
+
+| Your client | Use | Why |
+| --- | --- | --- |
+| **Runs in a browser** — Claude.ai, ChatGPT, Claude Desktop | the hosted connector `https://app.hermoso.ai/mcp` | It cannot spawn a local process, so a URL is the only shape it has. Nothing to install, no key to paste, and the full toolset arrives with your saved brand context. This is the right answer for these clients, not a lesser one. |
+| **Can run a shell** — Claude Code, Cursor, Codex, Cline, OpenClaw, Hermes, your own scripts | the CLI, `npm install -g hermoso` | A tool manifest is loaded into every session whether or not a tool is called. A shell command costs nothing until it runs, and it reaches **every** tool rather than the default roster. |
+
+**The measured difference** (2026-08-24, counted as real tool definitions rather than estimated from bytes):
+
+| | tools in range | loaded per session |
+| --- | --- | --- |
+| Hosted connector, default roster | 291 | **166,043 tokens** |
+| Hosted connector, `?tools=all` | 703 | **456,392 tokens** |
+| stdio server (`npx -y hermoso mcp`) | 269 | **153,257 tokens** |
+| **CLI** | **all 681** | **0** |
+
+The CLI answers the same questions on demand instead, and only when asked:
+
+```bash
+npx -y hermoso tools --search reddit   # every matching tool, name + one line   2,459 tokens
+npx -y hermoso tools plan_ad           # one tool's full argument schema           633 tokens
+npx -y hermoso call plan_ad --json '{"product":"…"}'   # run it
+```
+
+So a terminal agent reaches its first call in roughly **3.4K tokens with the whole roster in range**, against
+**153K for a fraction of it**. `tools` and `tools <name>` read a registry bundled in the package — no key, no
+network, no sign-in — so an agent can browse the entire product before anyone signs in. Only `call` spends, and
+only that needs `hermoso auth login` once.
+
+**Both at once is fine, and is what we suggest for Claude Code.** One `hermoso auth login` covers the CLI *and*
+lets `claude mcp add hermoso -- npx -y hermoso mcp` pick the key up with no `env` block, so the agent can reach for
+a native tool when it wants structured results and shell out when it wants breadth. If you only want one, take the
+CLI: it covers strictly more.
+
+**When the connector is still the better trade on a shell-capable client:** a session that is going to make many
+calls into one area. `enable_tools({groups:['ads']})` turns campaign management on in a single free call and the
+tools are then native — no shell quoting, structured results. One shell round trip beats loading a 221K-token
+group for a single tool; the reverse is true once a session settles into that area.
+
 ## Instant: the hosted Claude.ai connector
 
 Paste **`https://app.hermoso.ai/mcp`** into Claude → Settings → Connectors → *Add custom connector*, approve with
@@ -77,7 +118,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 681 tools cover
+### What the 709 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
@@ -180,6 +221,21 @@ hermoso research "Liquid Death’s longest-running ads"
 
 Add `--json` to any command for machine output.
 
+**Those shortcuts are the common path, not the limit.** Every tool the MCP server has is reachable here too,
+including the ad-campaign and analytics groups a connector leaves out of its default roster:
+
+```bash
+hermoso tools                          # every tool, grouped, name + one line
+hermoso tools --group ads --search reddit   # narrow it
+hermoso tools create_meta_campaign     # that tool's full argument schema
+hermoso call create_meta_campaign --json '{"name":"…"}'   # run it
+hermoso create_meta_campaign --name "…"                   # same thing, shorter
+```
+
+`call` goes through the same handler, the same argument validation and the same confirm/spend gates the MCP
+server uses — there is no second implementation to drift. `tools` and `tools <name>` read a registry bundled in
+the package, so they need no key, no network and no sign-in.
+
 ## 3. Claude skills — slash commands that wrap the CLI
 
 `skills/` holds four installable skills: `hermoso-generate`, `hermoso-ad-from-brand`,
@@ -198,7 +254,7 @@ Then invoke `/hermoso-ad-from-brand an ad for yourbrand.com — our hero product
 | `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 brands`) 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_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. |
 
 `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

@@ -22,6 +22,11 @@
 import { readFile, writeFile, mkdir, chmod } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { createRequire } from 'node:module';
+// READ THE REAL VERSION. This line printed a hard-coded "1.0.0" while package.json shipped 0.1.151 — so the
+// one command a user runs to find out what they have installed reported a version that has never existed.
+// Read from package.json so it cannot drift again; a bump is already a release step, and this now follows it.
+const CLI_VERSION = (() => { try { return createRequire(import.meta.url)('../package.json').version; } catch { return '0.0.0'; } })();
 
 const CONFIG_DIR = path.join(os.homedir(), '.hermoso');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
@@ -78,7 +83,7 @@ async function main() {
     return console.log(`✓ Saved. API: ${apiBase}${cfg.token ? ' · token stored' : ''}`);
   }
   if (group === 'version' || flags.version) {
-    console.log(`hermoso-cli 1.0.0 · API ${cfg.apiBase || process.env.HERMOSO_API_BASE || 'https://app.hermoso.ai'} · ${cfg.token ? 'authed' : 'no token — run: hermoso auth login --token <key>'}`);
+    console.log(`hermoso-cli ${CLI_VERSION} · API ${cfg.apiBase || process.env.HERMOSO_API_BASE || 'https://app.hermoso.ai'} · ${cfg.token ? 'authed' : 'no token — run: hermoso auth login --token <key>'}`);
     return;
   }
 

package/mcp/client.mjs

@@ -240,11 +240,71 @@ export async function pollJob(id, { intervalMs = 3000, timeoutMs = 10 * 60 * 100
   }
 }
 
-// Read a local image path → data URI (so --ref local files force Nano-Banana compositing); pass http(s) URLs through.
+// ── A REFERENCE THAT IS NOT A URL IS A LOCAL PATH, AND ON THE HOSTED CONNECTOR THERE IS NO SUCH THING ──────────
+// ChatGPT renders an image in its OWN sandbox and hands that path straight to generate_video. We opened it and
+// leaked `ENOENT: no such file or directory, open 'sandbox:/mnt/data/…'`, a Node filesystem error sitting where an
+// instruction belongs (reproduced on the live hosted connector 2026-08-24). `upload_file` has answered this
+// correctly since it was written; this says the same thing at the ONE seam every render tool with a file-ish input
+// already passes through (generate_image refImages, make_thumbnail faceImages + logo, generate_video refImage,
+// generate_avatar image), so a render tool added tomorrow inherits the refusal instead of having to remember it.
+// TWO DISTINCT REASONS, deliberately not collapsed into one:
+//   • A NON-FILE URI SCHEME (sandbox:, file:, blob:, gs:, s3:) is never a readable path on ANY surface, so it is
+//     refused on stdio too. `sandbox:/mnt/data/x.png` does not fail because we are hosted; it fails because that
+//     string was never a path.
+//   • A BARE PATH while hosted names the caller's disk, which we cannot see. Refusing is not merely the politer
+//     answer: hosted MCP tool code runs INSIDE our own container, so readFile() there reads OUR filesystem, and a
+//     path that happened to exist would be base64'd into a data: URI and shipped to a video model.
+// A Windows drive letter (`C:\\shots\\hero.png`) looks exactly like a one-character scheme, so a scheme needs two or
+// more characters to count. That path must still open on stdio.
+const REF_SCHEME_NOTE = {
+  sandbox: 'That is a path inside your own sandbox, which only your process can read.',
+  file: 'A file:// URL is not something I can open.',
+  blob: 'A blob: URL only exists inside the browser tab that created it.',
+};
+// VERIFIED ON THE LIVE HOSTED CONNECTOR 2026-08-24 rather than assumed: upload_file with `dataUri` returned a real
+// assets.hermoso.ai URL, and upload_file with `path` refused with its own message. So "call upload_file first" on
+// its own would walk the caller into the same wall. The SOURCE is the part that has to be named.
+const REF_WAYS_OUT = 'Send the bytes instead of a path. Pass the image as a `data:` URI (data:image/png;base64,…), or put it at a public https URL and pass that. Both work here. If you want a reusable Hermoso URL first, call upload_file with `dataUri` or `url` (its `path` source is refused on the hosted connector for this same reason).';
+
+// PURE, so tools/local-ref-refusal-check.mjs runs the real decision instead of reading it.
+export function localRefVerdict(src, { remote = false } = {}) {
+  const s = String(src ?? '').trim();
+  if (!s) return { action: 'skip' };
+  if (/^(https?:|data:)/i.test(s)) return { action: 'pass', value: s };
+  const m = /^([a-z][a-z0-9+.-]+):/i.exec(s);
+  if (m) return { action: 'refuse', reason: 'scheme', scheme: m[1].toLowerCase() };
+  if (remote) return { action: 'refuse', reason: 'hosted' };
+  return { action: 'read' };
+}
+
+export function localRefMessage(src, verdict, { remote = false } = {}) {
+  const s = String(src ?? '').trim().slice(0, 120);
+  const head = verdict.reason === 'scheme'
+    ? `\`${s}\` is a ${verdict.scheme}: URI, not a file I can open.${REF_SCHEME_NOTE[verdict.scheme] ? ` ${REF_SCHEME_NOTE[verdict.scheme]}` : ''}`
+    : `\`${s}\` is a local file path, and on the hosted connector I cannot see your disk.`;
+  const tail = verdict.reason === 'scheme' && !remote ? ' If you meant a file on this machine, pass its real filesystem path.' : '';
+  return `${head} Nothing was rendered and nothing was charged.\n\n${REF_WAYS_OUT}${tail}`;
+}
+
+// `status: 400` is what files this as `user` on the error board. /api/errors/report rebuilds the error from
+// ALLOWLISTED fields and deliberately will not read a `_userInput` marker off an untrusted reporter (a caller could
+// otherwise file its own crash under "the user's fault"), so the status is the honest channel: 400 is in the
+// ledger's AUTHORED_USER_STATUSES. `_userInput` is set too, for the in-process classifier, and it is the accurate
+// marker of the two here since this is a bad ARGUMENT rather than a capability we decline to offer.
+const refRefusal = (msg) => Object.assign(new Error(msg), { status: 400, _userInput: true });
+
+// Read a local image path → data URI (so --ref local files force Nano-Banana compositing); pass http(s) and data
+// URLs through; refuse anything we cannot open, with the way out named.
 export async function toRef(srcOrPath) {
-  if (!srcOrPath) return null;
-  if (/^(https?:|data:)/.test(srcOrPath)) return srcOrPath;
-  const buf = await readFile(srcOrPath);
+  const remote = isRemote();
+  const v = localRefVerdict(srcOrPath, { remote });
+  if (v.action === 'skip') return null;
+  if (v.action === 'pass') return v.value;
+  if (v.action === 'refuse') throw refRefusal(localRefMessage(srcOrPath, v, { remote }));
+  let buf;
+  // Even on stdio a raw ENOENT is a filesystem error where an instruction belongs.
+  try { buf = await readFile(srcOrPath); }
+  catch (e) { throw refRefusal(`I couldn't open \`${String(srcOrPath).trim().slice(0, 120)}\` (${e?.code || 'the read failed'}). Nothing was rendered and nothing was charged.\n\nCheck the path is right, or send the bytes instead: ${REF_WAYS_OUT}`); }
   const ext = path.extname(srcOrPath).toLowerCase().replace('.', '');
   const mime = ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : ext === 'gif' ? 'image/gif' : 'image/jpeg';
   return `data:${mime};base64,${buf.toString('base64')}`;

package/mcp/http.mjs

@@ -66,22 +66,38 @@ export function mountRemoteMcp(app, { verifyBearer, publicBaseUrl } = {}) {
 
   // Per-session Streamable-HTTP transports. Each authenticated session gets its own McpServer with the same tools.
   //
-  // ── A SESSION IS EXPENSIVE, AND THIS MAP IS WHY PROD OOM'd (2026-08-01) ───────────────────────────────────────
-  // registerTools() builds 248 tool definitions with their zod schemas: **~36 MB of RETAINED heap per McpServer**
-  // (measured, node --expose-gc, 25 instances). This map used to be unbounded and never expired — the only removal
-  // was transport.onclose, which never fires for a client that simply goes away. Prod took 238 `initialize`
-  // handshakes in 49 minutes (238 × 36 MB = ~8.6 GB) on a 4 GiB, maxScale=1 instance and died of
+  // ── A SESSION WAS EXPENSIVE, AND THIS MAP IS WHY PROD OOM'd (2026-08-01, again 2026-08-24) ───────────────────
+  // registerTools() used to rebuild all 681 tool definitions with their zod schemas on EVERY `initialize`:
+  // **114.36 MB of RETAINED heap per McpServer** (measured, node --expose-gc, 25 instances; 114.48 MB measured
+  // again end-to-end through this very transport). The older note here said ~36 MB — true at the 248-tool roster
+  // it was written against, and 3.2x stale by August. This map used to be unbounded and never expired — the only
+  // removal was transport.onclose, which never fires for a client that simply goes away. Prod took 238
+  // `initialize` handshakes in 49 minutes on a 4 GiB, maxScale=1 instance and died of
   // `FATAL ERROR: Reached heap limit` six times in that hour, every crash a full outage.
   //
+  // THE CAP AND THE TTL WERE NEVER THE FIX, AND 2026-08-24 PROVED IT: they worked exactly as designed (peak
+  // concurrent sessions measured at exactly SESSION_MAX) and prod still crashed four times in twelve hours,
+  // because the cost is CHURN, not retention — one client opened ~175 sessions in 65 minutes. Worse, the cap was
+  // FEEDING the churn: 157 of 258 session closures in a 3-day window were 'over cap', each one answering that
+  // client's next call with a 404, which obliges it to re-initialize, which allocates another full roster and
+  // evicts somebody else. A self-sustaining spiral. The durable fix is in mcp/tools.mjs: the tool definitions are
+  // static per process, so they are built ONCE and replayed. A session now costs **3.06-3.19 MB** — 36x less —
+  // and it is the per-`initialize` figure, not the per-live-session one, that decides whether this survives a
+  // retry storm. See tools/mcp-tool-canon-check.mjs.
+  //
   // The 400-on-a-session-miss below was the ACCELERANT: a client that cannot re-initialize opens a NEW session
   // instead of reusing its own, so the leak fed itself. Both are fixed here — bound + expire the map, and answer
   // the one status code that obliges a client to re-initialize.
-  const SESSION_MAX = Math.max(2, Number(process.env.MCP_SESSION_MAX || 16));            // ~580 MB ceiling for MCP
+  // 16 was sized against the old 114 MB session (~1.8 GB). At 3.1 MB it buys ~50 MB, so the cap is now far more
+  // conservative than the heap requires — deliberately left alone here so the memory fix lands as ONE measurable
+  // change; it is env-tunable with no deploy (`--update-env-vars MCP_SESSION_MAX=64` ≈ 200 MB) and raising it is
+  // what finally stops the over-cap eviction churn described above.
+  const SESSION_MAX = Math.max(2, Number(process.env.MCP_SESSION_MAX || 16));
   const SESSION_IDLE_MS = Math.max(1000, Number(process.env.MCP_SESSION_IDLE_MS || 30 * 60e3)); // 1s floor so the expiry is TESTABLE; a short TTL is merely wasteful now that eviction is recoverable
   const sessions = new Map(); // mcp-session-id -> { transport, server, user, lastSeen }  (insertion-ordered = LRU)
   const challenge = (res) => res.status(401).set('WWW-Authenticate', `Bearer resource_metadata="${BASE}/.well-known/oauth-protected-resource"`).json({ error: 'Authentication required' });
 
-  // Tear a session down for real — dropping the map entry alone would leave the 36 MB McpServer reachable from
+  // Tear a session down for real — dropping the map entry alone would leave the McpServer reachable from
   // the transport's own callbacks. Deleting FIRST makes this re-entrant-safe: transport.close() fires onclose,
   // which calls back in here, and the second pass is a no-op.
   function dropSession(id, why) {
@@ -195,7 +211,7 @@ export function mountRemoteMcp(app, { verifyBearer, publicBaseUrl } = {}) {
       // liberal in what we accept, because the entire point of this fix is that nothing here bricks a client.
       if (sid && !init) return sessionGone(res);
       // 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 pay 36 MB to build a server whose only job would be to reject the request.
+      // 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
@@ -219,7 +235,7 @@ export function mountRemoteMcp(app, { verifyBearer, publicBaseUrl } = {}) {
       await server.connect(transport);
       // If the handshake never completes (client drops, initialize rejected), nothing is in the map and both
       // objects are otherwise reachable only from this request's still-open response — close them explicitly
-      // rather than leaving 36 MB pinned by a dead socket.
+      // rather than leaving a session pinned by a dead socket.
       res.on('close', () => { if (!transport.sessionId || !sessions.has(transport.sessionId)) { try { transport.close(); } catch {} try { server.close(); } catch {} } });
     } else {
       // Touch = LRU. Re-inserting moves the key to the end of the Map's insertion order, so the cap evicts the