hermoso 0.1.262 → 0.1.263

package/README.md

@@ -174,7 +174,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 **Settings → Agents & API**.
+   from the **MCP & CLI** tab, under **Terminal & API keys**.
 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.
 

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 under Agents & 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 in the app on 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

@@ -365,6 +365,16 @@ export async function submitJob(type, input, { label = '' } = {}) {
 export async function getJob(id) { return apiGet(`/api/jobs/${encodeURIComponent(id)}`); } // → publicJob
 export function jobResult(job) { const r = job?.result; return r && Object.prototype.hasOwnProperty.call(r, 'data') ? r.data : r; }
 
+// HOW LONG A RENDER TOOL HOLDS ITS CALLER, in ms. `cap` is the transport's own maximum (45s hosted, 10min local) and
+// stays the answer for anything that is not a usable number — absent, negative, NaN — so a garbled ask can never
+// lengthen a wait or turn into "forever". 0 means "do not wait at all". PURE, so a check runs it.
+export function jobWaitMs(requested, cap) {
+  if (requested === undefined || requested === null || requested === '') return cap;
+  const n = Number(requested);
+  if (!Number.isFinite(n) || n < 0) return 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;
   for (;;) {
@@ -373,7 +383,10 @@ export async function pollJob(id, { intervalMs = 3000, timeoutMs = 10 * 60 * 100
     if (job.status === 'done') return { job, result: jobResult(job) };
     if (job.status === 'error') throw new Error(job.error || 'Render failed');
     if (Date.now() > deadline) throw Object.assign(new Error('Render timed out — check `hermoso jobs get ' + id + '`'), { jobId: id });
-    await new Promise(r => setTimeout(r, intervalMs));
+    // NEVER SLEEP PAST THE DEADLINE. A 3s interval made every wait 3s-granular: a caller who asked for 1s was held 3s,
+    // and one who asked for 29s was held 30s, which is the whole 30-second step budget the ask exists to stay inside.
+    // The defaults (45s, 10min) are whole multiples of the interval, so they poll exactly as they always have.
+    await new Promise(r => setTimeout(r, Math.min(intervalMs, Math.max(50, deadline - Date.now()))));
   }
 }
 

package/mcp/http.mjs

@@ -130,7 +130,7 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
       how_to_connect: {
         oauth: `Open ${BASE}/oauth/authorize through your client's own connector flow (a browser is required).`,
         no_browser_stdio: `Add Hermoso as a STDIO command instead of a URL: run \`npx -y hermoso mcp\` with the environment variable HERMOSO_TOKEN set to a key from ${BASE}/#developers. THE TOKEN IS NOT OPTIONAL HERE: a sandbox that could not open a browser for OAuth cannot open one for \`hermoso auth login\` either, so plain stdio with no token connects and then has no account to act on. (On your own machine, where a browser exists, \`npx -y hermoso auth login\` once replaces the token.)`,
-        no_browser_header: `Keep this URL and send an \`Authorization: Bearer <key>\` header. Create the key at ${BASE}/#developers (Settings ▸ Agents & API). A key in the URL query does NOT work and is not supported.`,
+        no_browser_header: `Keep this URL and send an \`Authorization: Bearer <key>\` header. Create the key at ${BASE}/#developers (the MCP & CLI tab, under Terminal & API keys). A key in the URL query does NOT work and is not supported.`,
       },
       // Named so an agent can branch on it rather than parsing prose.
       retry_will_not_help: true,

package/mcp/public-url.mjs

@@ -0,0 +1,102 @@
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// THE ONE ABSOLUTISER — a served path becomes a URL the CALLER can open (2026-09-20)
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════
+//
+// WHAT WENT WRONG. A render that has not moved to the durable asset host is recorded as a served path
+// (`/generated/…`), and every tool turned that into a link by prefixing `API_BASE`. `API_BASE` is the address the
+// tool layer uses to CALL the app, and on the hosted transport and the `/v1` passthrough that is a loopback
+// self-call (`http://127.0.0.1:<port>`) so a tool's own `/api` calls never leave the instance. Correct for
+// calling; wrong for a link handed to somebody on the other side of the internet. `list_library` answered
+// `http://127.0.0.1:8080/generated/…` to a REST caller on 2026-09-20, and it had its own hand-written copy of the
+// prefixing, which is why fixing `abs()` alone would not have closed it.
+//
+// THE RULE. The base used to CALL the API and the origin used to LINK to an asset are two different facts:
+//   • a LOCAL caller (stdio, the CLI) shares a machine with whatever `API_BASE` names, so that base is the right
+//     link, loopback included (a self-hoster on localhost gets a localhost link, which is what they can open);
+//   • a REMOTE caller (hosted MCP, `/v1`) can never reach a loopback or private address, so one is NEVER emitted:
+//     a served path is joined to the PUBLIC origin, and an already-absolute URL that names an unroutable host has
+//     its origin replaced. That second half is what makes this a guarantee rather than a fix for one call site: a
+//     row stored with a loopback origin months ago is repaired on the way out too.
+//
+// PURE, NO IMPORTS. This file is a byte-twin of `cli/mcp/public-url.mjs` (every `.mjs` in both directories is),
+// and `lib/public-api-v1-mount.mjs` imports it directly, so `/v1` and the tools cannot disagree about what a
+// public link is. It deliberately does NOT live in `client.mjs`: that module reads the API base at import time,
+// and importing it from the server before `HEIST_API_BASE` is set would pin every tool's self-call to the default.
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+/** Where a public link points when nothing better is configured. The app's own origin serves `/generated/…`. */
+export const PUBLIC_ORIGIN_DEFAULT = 'https://app.hermoso.ai';
+
+/**
+ * TRUE for a hostname no caller outside this machine or network can reach: loopback, the unspecified address,
+ * RFC 1918 private ranges, link-local (which includes the cloud metadata address), CGNAT, IPv6 loopback /
+ * unique-local / link-local, and the conventional internal suffixes. An unparseable host counts as unroutable:
+ * a link we cannot read is not one to hand out. PURE.
+ */
+export function isUnroutableHost(hostname) {
+  let h = String(hostname ?? '').trim().toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
+  if (!h) return true;
+  if (h.startsWith('::ffff:')) h = h.slice(7); // an IPv4-mapped IPv6 literal is judged as the IPv4 it carries
+  if (h === 'localhost' || h.endsWith('.localhost') || h.endsWith('.local') || h.endsWith('.internal') || h.endsWith('.lan')) return true;
+  if (h === '::' || h === '::1' || /^f[cd][0-9a-f]{2}:/.test(h) || /^fe[89ab][0-9a-f]:/.test(h)) return true;
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(h);
+  if (m) {
+    const [a, b] = [Number(m[1]), Number(m[2])];
+    if (a === 0 || a === 10 || a === 127) return true;
+    if (a === 169 && b === 254) return true;
+    if (a === 172 && b >= 16 && b <= 31) return true;
+    if (a === 192 && b === 168) return true;
+    if (a === 100 && b >= 64 && b <= 127) return true;
+    return false;
+  }
+  // A bare single-label name ("app", "hermoso-internal") only resolves inside a private network.
+  if (!h.includes('.') && !h.includes(':')) return true;
+  return false;
+}
+
+/** A configured origin, or null when it is absent, unparseable, not http(s), or unroutable. PURE. */
+function usableOrigin(candidate) {
+  const s = String(candidate ?? '').trim();
+  if (!s) return null;
+  let u; try { u = new URL(s); } catch { return null; }
+  if (u.protocol !== 'https:' && u.protocol !== 'http:') return null;
+  if (isUnroutableHost(u.hostname)) return null;
+  return u.origin;
+}
+
+/**
+ * THE PUBLIC ORIGIN. Configured (`APP_PUBLIC_URL`, the name server.js reads, then the two older spellings),
+ * never asserted by a caller, and never a request's Host header. A configured value that is itself unroutable is
+ * IGNORED rather than honoured: this function's one job is that its answer can be opened from outside. PURE.
+ */
+export function publicOrigin(env = {}) {
+  return usableOrigin(env?.APP_PUBLIC_URL) || usableOrigin(env?.APP_URL) || usableOrigin(env?.PUBLIC_BASE) || PUBLIC_ORIGIN_DEFAULT;
+}
+
+/**
+ * Absolutise an asset reference for the caller who will open it.
+ *
+ * @param {string} u       a served path (`/generated/x.mp4`), or an already-absolute URL
+ * @param {object} o
+ * @param {string} o.base    the base the tool layer CALLS the API on (may be loopback)
+ * @param {boolean} o.remote true when the caller is not on this machine (hosted MCP, `/v1`)
+ * @param {object} o.env     where a configured public origin is read from
+ *
+ * Anything that is not a string, is empty, or is not http(s) / a served path (a `data:` URI, a bare id) is
+ * returned untouched: this decides where a link points, never whether a value is a link. PURE.
+ */
+export function absolutizeAssetUrl(u, { base = '', remote = false, env = {} } = {}) {
+  if (typeof u !== 'string' || !u) return u;
+  const pub = publicOrigin(env);
+  if (u.startsWith('/') && !u.startsWith('//')) {
+    const b = String(base || '').replace(/\/+$/, '');
+    let baseHost = null; try { baseHost = new URL(b).hostname; } catch { baseHost = null; }
+    // No usable base at all is treated like an unroutable one: a bare path is not a link for anybody.
+    const useBase = b && baseHost !== null && !(remote && isUnroutableHost(baseHost));
+    return (useBase ? b : pub) + u;
+  }
+  if (!remote || !/^https?:\/\//i.test(u)) return u;
+  let parsed; try { parsed = new URL(u); } catch { return u; }
+  if (!isUnroutableHost(parsed.hostname)) return u;
+  return pub + parsed.pathname + parsed.search + parsed.hash;
+}

package/mcp/tools.mjs

@@ -4,7 +4,8 @@
 // Spend tools hit routes guarded by gateSpend → requireAuth; locally the dev account always resolves (no auth
 // needed today), and the SAME guard becomes authoritative under real auth — so this honors no-anon-spend as-is.
 import { z } from 'zod';
-import { apiGet, apiPost, apiPut, apiPatch, apiDelete, apiSSE, submitJob, getJob, jobResult, pollJob, toRef, localRefVerdict, apiUpload, apiUploadUrl, isRemote, API_BASE, PROFILE, ENV_PREFIX, mcpCtx, storeSuffix, forgetWorkspaceScope, toolCtx, reportToolError, reportDeadEnd, hostRendersWidgets, connectedProviders, setPinnedProfile } from './client.mjs';
+import { absolutizeAssetUrl, publicOrigin } from './public-url.mjs';
+import { apiGet, apiPost, apiPut, apiPatch, apiDelete, apiSSE, submitJob, getJob, jobResult, pollJob, jobWaitMs, toRef, localRefVerdict, apiUpload, apiUploadUrl, isRemote, API_BASE, PROFILE, ENV_PREFIX, mcpCtx, storeSuffix, forgetWorkspaceScope, toolCtx, reportToolError, reportDeadEnd, hostRendersWidgets, connectedProviders, setPinnedProfile } from './client.mjs';
 import { readFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -23,7 +24,13 @@ import { recordToolOutcome, toolHealth, healthLabel, healthPenalty } from './too
 import { withHints } from './tool-hints.mjs';
 
 const JOB_TIMEOUT = +(process.env.HERMOSO_JOB_TIMEOUT_MS || process.env.HEIST_JOB_TIMEOUT_MS || 10 * 60 * 1000);
-const abs = (u) => (u && u.startsWith('/') ? API_BASE + u : u); // /generated/x.mp4 → clickable absolute URL
+// /generated/x.mp4 → a URL THE CALLER can open. `API_BASE` is the base this layer CALLS the app on, and on the hosted
+// transport and the `/v1` passthrough that is a loopback self-call — so prefixing it handed a remote caller
+// `http://127.0.0.1:8080/generated/…` (live on /v1 2026-09-20). The rule lives in public-url.mjs, the ONE absolutiser:
+// a local caller keeps the base it shares a machine with, a remote one never receives a loopback or private host.
+// EVERY link this file builds goes through here. Never prefix `API_BASE` onto a path by hand: `list_library` did, which
+// is exactly how the one tool that lists served paths was the one that leaked.
+const abs = (u) => absolutizeAssetUrl(u, { base: API_BASE, remote: isRemote(), env: process.env });
 // Null-valued keys are STRIPPED from structuredContent (2026-07-20): the SDK validates results against outputSchema
 // server-side, and zod .optional() rejects null — a single null field (e.g. editCredits:null on a key-less deploy)
 // bricked the whole tool result with a protocol-level validation error. Every field in our schemas is optional, so
@@ -307,7 +314,12 @@ async function imageBlock(url) {
   // render inherits the behaviour instead of having to remember it. Fails OPEN: an unknown client keeps the block.
   if (hostRendersWidgets()) return null;
   try {
-    const r = await fetch(url); if (!r.ok) return null;
+    // The link the CALLER gets is public (abs()); the bytes WE read to inline it are on this instance. Reading our own
+    // served file back through the public edge would be a round trip out and in for a file on local disk, so a URL
+    // under the public origin is fetched on the base this layer already calls the app on. The link is never rewritten.
+    const own = publicOrigin(process.env) + '/';
+    const src = typeof url === 'string' && url.startsWith(own) && isRemote() ? API_BASE + '/' + url.slice(own.length) : url;
+    const r = await fetch(src); if (!r.ok) return null;
     const ct = (r.headers.get('content-type') || 'image/jpeg').split(';')[0];
     if (!/^image\//.test(ct)) return null;
     const buf = Buffer.from(await r.arrayBuffer());
@@ -478,9 +490,20 @@ const publishWrap = (fn) => {
 // RESUMABLE handle instead of dying (the agent polls get_job, which now attaches the poster on done).
 async function renderJob(type, input, label) {
   const job = await submitJob(type, input, { label });
-  const remote = !!mcpCtx.getStore(); // AsyncLocalStorage ctx only exists on the remote transport
+  const ctx = mcpCtx.getStore(); // AsyncLocalStorage ctx only exists on the remote transport
+  const remote = !!ctx;
+  // THE ONE PLACE A RENDER TOOL WAITS, SO THE ONE PLACE A CALLER'S WAIT IS HONOURED (2026-09-20). `/v1/tools` puts a
+  // caller's `?wait=` on the context as `waitMs`; nothing else sets it, so with it absent this is the same 45s / 10min
+  // it always was. It can only SHORTEN the wait (jobWaitMs caps it at the transport's own maximum), and it is read
+  // AFTER submitJob on purpose: the job is queued through the identical POST /api/jobs — same spend gate, same
+  // pre-queue credit check, same reserve and settle in the worker — whether or not anybody waits for it. Waiting was
+  // never part of what a render costs, so not waiting cannot change it, and there is no second submit path to drift.
+  const waitMs = jobWaitMs(ctx?.waitMs, remote ? 45_000 : JOB_TIMEOUT);
+  // wait=0: answer the moment the job is queued. Not even one poll — pollJob sleeps between reads, and a caller with a
+  // 30s step budget (an automation platform) asked for the handle, not for a status.
+  if (waitMs <= 0) return { jobId: job.id, url: null, stillRendering: true, raw: null };
   try {
-    const { result } = await pollJob(job.id, { timeoutMs: remote ? 45_000 : JOB_TIMEOUT });
+    const { result } = await pollJob(job.id, { timeoutMs: waitMs });
     const url = abs(result?.video || result?.image || result?.url);
     // creditsUsed AND the delivered geometry ride out here deliberately. The widget's own registered
     // description promises "the model that rendered it and credits spent", and the pill only ever appeared
@@ -19123,7 +19146,7 @@ function memoryNoteVerdict(text) {
     const kind = a.kind && a.kind !== 'all' ? a.kind : null;
     const lim = Math.min(60, Math.max(1, +a.limit || 20));
     const assets = list.filter(x => x && x.url && (!kind || x.kind === kind)).slice(0, lim)
-      .map(x => ({ url: /^https?:/.test(x.url) ? x.url : `${API_BASE}${x.url}`, kind: x.kind || '', model: x.model || '', ageHours: x.at ? Math.round((Date.now() - x.at) / 36e5) : undefined }));
+      .map(x => ({ url: abs(x.url), kind: x.kind || '', model: x.model || '', ageHours: x.at ? Math.round((Date.now() - x.at) / 36e5) : undefined }));
     if (!assets.length) return ok('The Library is empty for this workspace — render something first.', { assets: [] });
     return ok(`${assets.length} asset${assets.length === 1 ? '' : 's'} (newest first):\n` + assets.map((x, i) => `  ${i + 1}. [${x.kind || '?'}${x.model ? ' · ' + x.model : ''}${x.ageHours != null ? ' · ' + x.ageHours + 'h ago' : ''}] ${x.url}`).join('\n'), { assets });
   }));
@@ -19139,7 +19162,7 @@ function memoryNoteVerdict(text) {
     annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   }, wrap(async ({ url, name }) => {
     const absolute = abs(url);
-    const dl = `${API_BASE}/api/download?url=${encodeURIComponent(url)}${name ? `&name=${encodeURIComponent(name)}` : ''}`;
+    const dl = abs(`/api/download?url=${encodeURIComponent(url)}${name ? `&name=${encodeURIComponent(name)}` : ''}`);
     return ok(`Asset: ${absolute}\nDownload: ${dl}`, { url: absolute, downloadUrl: dl });
   }));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermoso",
-  "version": "0.1.262",
+  "version": "0.1.263",
   "mcpName": "io.github.hermoso-ai/hermoso",
   "description": "Marketing on autopilot, run from your own AI agent. 847 tools. Publishing, scheduling, ad campaign management, comments, DMs and analytics cost no credits on every plan; credits are only for generating creative and for Ad Spy research. 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: Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn, Pinterest, Bluesky and Telegram. 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. Also brand onboarding, 50+ image and video generation models, ad scoring, competitor teardowns, Google Drive and OneDrive, a CLI and installable Claude skills.",
   "type": "module",