hermoso 0.1.7 → 0.1.9

package/bin/hermoso.mjs

@@ -4,14 +4,14 @@
 // in skills/ wrap these commands. Same /api as the MCP server.
 //
 //   npm i -g  (from this repo)  OR  node bin/hermoso.mjs <cmd>
-//   hermoso auth login --token <key>                   # key from app.hermoso.ai → Settings → Agents & API
+//   hermoso auth login                                 # browser sign-in (loopback, like gh/heroku); --token <key> for CI
 //   hermoso capabilities                                 # learn valid model ids + costs (run first)
 //   hermoso create --brand Flourish --product "protein pancakes" --format image
 //   hermoso generate image --prompt "…" --ref ./bag.png --wait
 //
 // Auth today: none locally (the server resolves the dev account). `hermoso auth login --token <t>` stores a Bearer
 // for when real auth lands — the seam, not a requirement.
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, chmod } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
@@ -19,7 +19,15 @@ const CONFIG_DIR = path.join(os.homedir(), '.hermoso');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 
 async function loadConfig() { try { return JSON.parse(await readFile(CONFIG_FILE, 'utf8')); } catch { return {}; } }
-async function saveConfig(c) { await mkdir(CONFIG_DIR, { recursive: true }); await writeFile(CONFIG_FILE, JSON.stringify(c, null, 2)); }
+// config.json holds a long-lived hmk_ account bearer (full billing/spend authority) — write it OWNER-ONLY (dir 0700,
+// file 0600) so a co-tenant on a shared machine can't read the key and spend the victim's credits (aws/gh/docker do the
+// same). mode on mkdir/writeFile is pre-umask, so also chmod after in case an existing dir/file kept looser perms.
+async function saveConfig(c) {
+  await mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  try { await chmod(CONFIG_DIR, 0o700); } catch {}
+  await writeFile(CONFIG_FILE, JSON.stringify(c, null, 2), { mode: 0o600 });
+  try { await chmod(CONFIG_FILE, 0o600); } catch {}
+}
 
 // ---- minimal arg parser: positionals + --flags (--flag value | --flag=value | boolean --flag) ----
 function parse(argv) {

package/mcp/tools.mjs

@@ -8,7 +8,16 @@ import { apiGet, apiPost, apiPut, apiSSE, submitJob, getJob, jobResult, pollJob,
 
 const JOB_TIMEOUT = +(process.env.HERMOSO_JOB_TIMEOUT_MS || 10 * 60 * 1000);
 const abs = (u) => (u && u.startsWith('/') ? API_BASE + u : u); // /generated/x.mp4 → clickable absolute URL
-const ok = (text, data) => ({ content: [{ type: 'text', text }], structuredContent: data ?? {} });
+// 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
+// absent is always valid; array ELEMENTS are kept as-is (dropping them would shift indices).
+// Quote tokens MINTED THIS PROCESS (buy_credits): possession of a well-formed string must not authorize a charge —
+// only a token this server actually issued in a quote turn does. Process-local by design (a restart invalidates
+// outstanding quotes → the agent simply re-quotes; no charge can slip through).
+const _mintedQuotes = new Set();
+const stripNulls = (v) => { if (Array.isArray(v)) return v.map(stripNulls); if (v && typeof v === 'object') { const o = {}; for (const [k, x] of Object.entries(v)) { if (x !== null) o[k] = stripNulls(x); } return o; } return v; };
+const ok = (text, data) => ({ content: [{ type: 'text', text }], structuredContent: data == null ? {} : stripNulls(data) });
 // Video-return variant: attaches the clip's first frame as an inline image block (Claude can't play mp4 in chat,
 // but a poster makes the result VISIBLE, mirroring generate_image). Falls back to plain ok() when frames fail.
 const stillMsg = (r) => `Still rendering — job ${r.jobId}. This is NORMAL: video renders take 1–3 minutes and each get_job call waits up to ~45s, so it can take several calls. Keep calling get_job with this id until status is done or error — do NOT ask the user whether to keep waiting, and do NOT re-fire the render on another model (that double-charges). Only surface a problem after ~6 minutes of polling.`;
@@ -36,7 +45,7 @@ export const MCP_INSTRUCTIONS = [
   '• CREATE (finished ads): draft_brand → plan_ad → render_ad (Studio quality pipeline) or generate_image / generate_video / generate_avatar; make_template_ad (native HTML formats); remix_static / recast_motion / reframe_video / upscale_video / dub_video / change_voice / finish_video / fix_beat / stitch_video; plan_variations + score_ad.',
   '• RAW MODEL PLAYGROUND: generate_image / generate_video (useBrand:false) for prompt-only renders, generate_voice for text-to-speech, generate_text for the writing models — against any of 30+ image / video / voice / writing model ids (exact costs in hermoso_capabilities), no ad framing.',
   '• ACCOUNT: hermoso_credits, billing_status, buy_credits (one-click top-up / first-purchase link), upgrade_plan / set_auto_reload (admin), list_jobs / get_job.',
-  'No anonymous spend — tools/call needs a bearer. Out of credits → buy_credits: with a saved card + admin rights it one-click charges after an explicit confirm:true (state the exact price first); the FIRST purchase is a Stripe link your human pays, which saves the card. Always report the final media URL to the user.',
+  'No anonymous spend — tools/call needs a bearer. Out of credits → buy_credits: with a saved card + admin rights it one-click charges after an explicit confirm:true + the returned quote_token (state the exact price first); the FIRST purchase is a Stripe link your human pays, which saves the card. Always report the final media URL to the user.',
 ].join('\n');
 // Inline the finished image so Claude RENDERS it in chat instead of just linking it (MCP image content block).
 // Skipped silently for huge files / fetch errors — the URL in the text always works.
@@ -65,7 +74,7 @@ const wrap = (fn) => async (args, extra) => {
   catch (e) {
     let msg = `Error: ${e?.message || e}`;
     // credit outages need an actionable path the agent can relay — the web app has a top-up gate; here the URL is it
-    if (/not enough credits/i.test(msg)) msg += `\nRun buy_credits to top up (credit packs): with a saved card it quotes then one-click charges on confirm:true; with no card yet it returns a checkout link your human pays once (the card saves for one-click after). billing_status shows your balance, plan + billing role; if you're an admin, upgrade_plan moves to a bigger monthly plan (a person pays on Stripe). hermoso_credits shows the balance; hermoso_capabilities lists per-model credit costs.`;
+    if (/not enough credits/i.test(msg)) msg += `\nRun buy_credits to top up (credit packs): with a saved card it quotes (quoteToken included) then one-click charges on confirm:true + quote_token; with no card yet it returns a checkout link your human pays once (the card saves for one-click after). billing_status shows your balance, plan + billing role; if you're an admin, upgrade_plan moves to a bigger monthly plan (a person pays on Stripe). hermoso_credits shows the balance; hermoso_capabilities lists per-model credit costs.`;
     return { content: [{ type: 'text', text: msg }], isError: true };
   }
 };
@@ -96,7 +105,160 @@ const JOB_OUT = {
   stillRendering: z.boolean().optional().describe('true when the render is still in progress — keep polling get_job with jobId'),
 };
 
+// ── ChatGPT Apps SDK components (ADDITIVE — Claude/Cursor/other clients ignore extra _meta + ui:// resources) ──
+// Contract pinned from developers.openai.com/apps-sdk on 2026-07-19 (see docs/apps-sdk-notes.md):
+//   • a tool declares its widget via tool _meta['openai/outputTemplate'] = 'ui://widget/<name>.html'
+//   • that URI is a normal MCP resource with mimeType 'text/html+skybridge' (self-contained HTML+inline JS,
+//     runs in ChatGPT's sandboxed skybridge iframe)
+//   • the widget reads the tool's structuredContent from window.openai.toolOutput and re-renders on the
+//     'openai:set_globals' window event; setWidgetState persists small UI state across re-renders
+//   • every host the iframe loads media from must be allowlisted in resource _meta['openai/widgetCSP']
+const UI_MIME = 'text/html+skybridge';
+const AD_RESULT_URI = 'ui://widget/ad-result.html';
+const CAPABILITIES_URI = 'ui://widget/capabilities.html';
+// Where the widgets' <img>/<video> srcs live: served app media + the R2 asset origins (GEN_PUBLIC_BASE/R2_PUBLIC_BASE).
+const WIDGET_CSP = { connect_domains: [], resource_domains: ['https://app.hermoso.ai', 'https://assets.hermoso.ai', 'https://*.r2.dev'] };
+const openaiMeta = (template, invoking, invoked) => ({ 'openai/outputTemplate': template, 'openai/toolInvocation/invoking': invoking, 'openai/toolInvocation/invoked': invoked }); // status strings ≤64 chars
+
+// String.raw so regex backslashes inside the inline widget JS survive the template literal (no ${} used).
+const AD_RESULT_HTML = String.raw`<div id="root"></div>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  #root { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', sans-serif; color: #16181c; }
+  @media (prefers-color-scheme: dark) { #root { color: #ececf1; } }
+  .card { max-width: 520px; border: 1px solid rgba(128,128,128,.28); border-radius: 14px; overflow: hidden; background: rgba(128,128,128,.05); }
+  .media img, .media video { display: block; width: 100%; height: auto; max-height: 72vh; object-fit: contain; background: rgba(0,0,0,.85); }
+  .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(140px, 1fr)); gap: 4px; padding: 4px; background: rgba(0,0,0,.85); }
+  .grid img { width: 100%; height: auto; display: block; border-radius: 8px; }
+  .meta { display: flex; align-items: center; flex-wrap: wrap; gap: 6px; padding: 9px 12px; font-size: 12.5px; }
+  .pill { border: 1px solid rgba(128,128,128,.35); border-radius: 999px; padding: 2px 9px; opacity: .85; }
+  .spacer { flex: 1; }
+  .wordmark { font-size: 11px; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; opacity: .4; }
+  .empty { padding: 18px 16px; font-size: 13px; opacity: .75; }
+</style>
+<script>
+(function () {
+  var root = document.getElementById('root');
+  function esc(s) { return String(s == null ? '' : s).replace(/[&<>"']/g, function (c) { return '&#' + c.charCodeAt(0) + ';'; }); }
+  function looksVideo(u) { return /\.(mp4|webm|mov|m4v)([?#]|$)/i.test(String(u || '')); }
+  function render() {
+    var out = (window.openai && window.openai.toolOutput) || {};
+    var raw = out.raw || {};
+    var pills = '';
+    if (out.model) pills += '<span class="pill">' + esc(out.model) + '</span>';
+    var credits = out.creditsUsed != null ? out.creditsUsed : (out.credits != null ? out.credits : raw.creditsUsed);
+    if (credits != null) pills += '<span class="pill">' + esc(credits) + ' credits</span>';
+    var footer = '<div class="meta">' + pills + '<span class="spacer"></span><span class="wordmark">Hermoso</span></div>';
+    var slides = Array.isArray(raw.images) && raw.images.length ? raw.images : null;
+    var vid = out.video || raw.video || null;
+    var img = out.image || raw.image || null;
+    var any = out.url || raw.url || null;
+    if (!vid && !img && any) { if (looksVideo(any)) { vid = any; } else { img = any; } }
+    var body;
+    if (out.stillRendering) body = '<div class="empty">Still rendering' + (out.jobId ? ' — job ' + esc(out.jobId) : '') + '. Video renders take 1–3 minutes; the finished ad appears here.</div>';
+    else if (slides) body = '<div class="grid">' + slides.map(function (u) { return '<img src="' + esc(u) + '" alt="carousel slide" loading="lazy">'; }).join('') + '</div>';
+    else if (vid) body = '<div class="media"><video controls muted autoplay loop playsinline preload="metadata" src="' + esc(vid) + '"></video></div>';
+    else if (img) body = '<div class="media"><img src="' + esc(img) + '" alt="generated ad"></div>';
+    else body = '<div class="empty">No media in this result yet.</div>';
+    root.innerHTML = '<div class="card">' + body + footer + '</div>';
+  }
+  render();
+  window.addEventListener('openai:set_globals', render);
+})();
+</script>`;
+
+const CAPABILITIES_HTML = String.raw`<div id="root"></div>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  #root { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', sans-serif; color: #16181c; font-size: 13px; max-width: 560px; }
+  @media (prefers-color-scheme: dark) { #root { color: #ececf1; } }
+  .bar { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; padding: 4px 0 10px; }
+  .chip { font: inherit; color: inherit; background: transparent; border: 1px solid rgba(128,128,128,.4); border-radius: 999px; padding: 3px 11px; cursor: pointer; opacity: .75; }
+  .chip.on { opacity: 1; border-color: currentColor; font-weight: 600; }
+  .q { font: inherit; color: inherit; background: rgba(128,128,128,.1); border: 1px solid rgba(128,128,128,.3); border-radius: 8px; padding: 4px 9px; flex: 1; min-width: 120px; }
+  .list { border: 1px solid rgba(128,128,128,.25); border-radius: 12px; overflow: hidden; }
+  .row { display: flex; flex-wrap: wrap; gap: 4px 10px; align-items: baseline; padding: 8px 12px; }
+  .row + .row { border-top: 1px solid rgba(128,128,128,.18); }
+  .mid { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; font-weight: 600; }
+  .lbl { opacity: .65; font-size: 12px; }
+  .right { margin-left: auto; display: flex; flex-wrap: wrap; gap: 4px 8px; align-items: baseline; }
+  .kind { font-size: 10.5px; text-transform: uppercase; letter-spacing: .05em; opacity: .55; }
+  .badge { font-size: 10.5px; border: 1px solid rgba(128,128,128,.35); border-radius: 999px; padding: 1px 7px; opacity: .8; }
+  .cost { font-size: 12px; font-variant-numeric: tabular-nums; white-space: nowrap; }
+  .none { padding: 16px; opacity: .7; }
+  .foot { display: flex; justify-content: space-between; padding: 8px 2px 2px; font-size: 11.5px; opacity: .55; }
+  .wordmark { font-weight: 700; letter-spacing: .08em; text-transform: uppercase; }
+</style>
+<script>
+(function () {
+  var root = document.getElementById('root');
+  var saved = (window.openai && window.openai.widgetState) || {};
+  var filter = saved.filter || 'all';
+  var q = saved.q || '';
+  var KINDS = ['all', 'image', 'video', 'voice', 'writing'];
+  function esc(s) { return String(s == null ? '' : s).replace(/[&<>"']/g, function (c) { return '&#' + c.charCodeAt(0) + ';'; }); }
+  function items() {
+    var out = (window.openai && window.openai.toolOutput) || {};
+    var opt = out.options || {};
+    var list = [];
+    ((opt.image && opt.image.models) || []).forEach(function (m) {
+      list.push({ kind: 'image', id: m.id, label: m.label || '', cost: m.credits != null ? m.credits + ' cr' : '', badges: [m.best ? 'best' : '', m.hiRes ? '2K' : '', m.refs && m.refs.max ? 'refs ≤' + m.refs.max : ''] });
+    });
+    ((opt.video && opt.video.models) || []).forEach(function (m) {
+      var cost = (m.durations || []).map(function (d) { var c = m.credits && m.credits[d]; return d + 's=' + (c == null ? '?' : c) + 'cr'; }).join(' · ');
+      list.push({ kind: 'video', id: m.id, label: m.label || '', cost: cost, badges: [m.best ? 'best' : '', m.audio ? 'audio' : 'silent', m.refs && m.refs.required ? 'image-to-video' : ''] });
+    });
+    ((opt.voice && opt.voice.engines) || []).forEach(function (e) {
+      list.push({ kind: 'voice', id: e.id, label: e.label || '', cost: e.creditsPer1k != null ? e.creditsPer1k + ' cr/1k chars' : '', badges: [(e.voices || []).length ? e.voices.length + ' voices' : ''] });
+    });
+    ((opt.llm && opt.llm.models) || []).forEach(function (m) {
+      list.push({ kind: 'writing', id: m.id, label: m.label || '', cost: m.credits != null ? m.credits + ' cr' : '', badges: [] });
+    });
+    return list;
+  }
+  function row(it) {
+    var badges = it.badges.filter(Boolean).map(function (b) { return '<span class="badge">' + esc(b) + '</span>'; }).join('');
+    return '<div class="row"><span class="mid">' + esc(it.id) + '</span><span class="lbl">' + esc(it.label) + '</span><span class="right"><span class="kind">' + esc(it.kind) + '</span>' + badges + '<span class="cost">' + esc(it.cost) + '</span></span></div>';
+  }
+  function persist() { try { if (window.openai && window.openai.setWidgetState) window.openai.setWidgetState({ filter: filter, q: q }); } catch (e) {} }
+  function list() {
+    Array.prototype.forEach.call(root.querySelectorAll('.chip'), function (b) { b.classList.toggle('on', b.getAttribute('data-k') === filter); });
+    var all = items();
+    var needle = q.toLowerCase();
+    var vis = all.filter(function (it) { return (filter === 'all' || it.kind === filter) && (!needle || (it.id + ' ' + it.label).toLowerCase().indexOf(needle) >= 0); });
+    document.getElementById('list').innerHTML = vis.map(row).join('') || '<div class="none">No matching models.</div>';
+    document.getElementById('count').textContent = vis.length + ' of ' + all.length + ' models · costs in Hermoso credits';
+  }
+  function shell() {
+    var chips = KINDS.map(function (k) { return '<button type="button" class="chip" data-k="' + k + '">' + k.charAt(0).toUpperCase() + k.slice(1) + '</button>'; }).join('');
+    root.innerHTML = '<div class="bar">' + chips + '<input id="q" class="q" type="search" placeholder="Filter models…"></div><div id="list" class="list"></div><div class="foot"><span id="count"></span><span class="wordmark">Hermoso</span></div>';
+    var inp = document.getElementById('q');
+    inp.value = q;
+    inp.addEventListener('input', function () { q = inp.value; persist(); list(); });
+    Array.prototype.forEach.call(root.querySelectorAll('.chip'), function (b) {
+      b.addEventListener('click', function () { filter = b.getAttribute('data-k'); persist(); list(); });
+    });
+    list();
+  }
+  shell();
+  window.addEventListener('openai:set_globals', list);
+})();
+</script>`;
+
+function registerAppResources(server) {
+  const reg = (name, uri, description, html) => {
+    const meta = { 'openai/widgetDescription': description, 'openai/widgetPrefersBorder': true, 'openai/widgetCSP': WIDGET_CSP };
+    server.registerResource(name, uri, { description, mimeType: UI_MIME, _meta: meta },
+      async () => ({ contents: [{ uri, mimeType: UI_MIME, text: html, _meta: meta }] }));
+  };
+  reg('hermoso-ad-result', AD_RESULT_URI, 'Shows the finished Hermoso ad — the image, auto-playing video, or carousel — with the model that rendered it and credits spent.', AD_RESULT_HTML);
+  reg('hermoso-capabilities', CAPABILITIES_URI, 'Browsable Hermoso model catalog: image/video/voice/writing models with exact per-render credit costs and a filter row.', CAPABILITIES_HTML);
+}
+
 export function registerTools(server) {
+  registerAppResources(server); // ChatGPT Apps SDK widget templates — inert decoration for every other client
   // ---------- read-only / discovery ----------
   server.registerTool('hermoso_capabilities', {
     title: 'Hermoso capabilities',
@@ -107,11 +269,12 @@ export function registerTools(server) {
       canEdit: z.boolean().optional().describe('whether image editing is enabled on this account'),
       canAvatar: z.boolean().optional().describe('whether talking-avatar generation is enabled'),
       canPublish: z.boolean().optional().describe('whether ad publishing is enabled'),
-      editCredits: z.number().optional().describe('credit cost of one image edit'),
+      editCredits: z.number().nullable().optional().describe('credit cost of one image edit (null when image editing is not configured)'),
       options: z.any().optional().describe('the live model catalog — image/video/voice/llm model lists with per-model credit costs'),
       recipes: z.array(z.any()).optional().describe('the creative recipe catalog (id + label per recipe)'),
     },
     annotations: { readOnlyHint: true, openWorldHint: false },
+    _meta: openaiMeta(CAPABILITIES_URI, 'Loading the model catalog…', 'Model catalog ready'),
   }, wrap(async () => {
     const d = await apiGet('/api/generate/status');
     const img = (d.options?.image?.models || []).map(m => `${m.id} (${m.label}, ${m.credits}cr${m.refs ? `, ≤${m.refs.max} reference images` : ''}${m.hiRes ? ', 2K' : ''}${m.best ? ', best' : ''})`).join('; ');
@@ -148,10 +311,11 @@ export function registerTools(server) {
   // the human pays once — that card then saves for one-click forever. Packs only — subscriptions are in-app.
   server.registerTool('buy_credits', {
     title: 'Buy credits',
-    description: "Out of credits? Top up with a credit PACK. Call with no argument to list the available packs (id · credits · price). If the account has a saved card and you have billing-admin rights, calling with `pack` quotes the exact charge and calling again with confirm:true charges the saved card instantly (same one-click top-up as the app — no redirect). If there's no saved card yet, you get a Stripe checkout URL to hand your human for the FIRST purchase; their card saves for one-click after that. Packs only; subscriptions are managed by a person in Settings → Billing.",
+    description: "Out of credits? Top up with a credit PACK. Call with no argument to list the available packs (id · credits · price). If the account has a saved card and you have billing-admin rights, calling with `pack` quotes the exact charge and calling again with confirm:true AND the quote's quote_token charges the saved card instantly (same one-click top-up as the app — no redirect). If there's no saved card yet, you get a Stripe checkout URL to hand your human for the FIRST purchase; their card saves for one-click after that. Packs only; subscriptions are managed by a person in Settings → Billing.",
     inputSchema: {
       pack: z.string().optional().describe('the pack id to buy (e.g. pack-2k) — omit to list the available packs first'),
       confirm: z.boolean().optional().describe('set true to actually charge the saved card for `pack` (required for the one-click charge; ignored on the checkout-link path)'),
+      quote_token: z.string().optional().describe('the quoteToken returned by the quote step — REQUIRED (with confirm:true) to charge; it binds the exact pack + price you quoted (10-minute validity) and makes a retried confirm idempotent'),
     },
     outputSchema: {
       packs: z.array(z.any()).optional().describe('available credit packs ({id, credits, priceUsd}) when listing'),
@@ -163,7 +327,7 @@ export function registerTools(server) {
       packId: z.string().optional().describe('the pack id the checkout link buys'),
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, // confirm:true charges the saved card (one-click top-up); link path charges nothing
-  }, wrap(async ({ pack, confirm }) => {
+  }, wrap(async ({ pack, confirm, quote_token }) => {
     const cfg = await apiGet('/api/billing/config');
     const packs = (cfg.packs || []).map(p => ({ id: p.id, credits: p.credits, priceUsd: p.priceUsd }));
     if (!pack) {
@@ -176,8 +340,28 @@ export function registerTools(server) {
     try { st = await apiGet('/api/billing/status'); } catch {}
     if (st?.paymentMethodOnFile && st?.isAdmin) {
       const card = st.card ? `${st.card.brand} ····${st.card.last4}` : 'the saved card';
-      if (!confirm) return ok(`Ready to charge ${card} $${match.priceUsd} for ${match.credits.toLocaleString()} credits (one-click, no redirect — same as the app's Add credits button). Confirm with your human if they haven't already asked for this, then call buy_credits again with pack="${match.id}" and confirm:true.`, { quote: { packId: match.id, credits: match.credits, priceUsd: match.priceUsd, card: st.card || null } });
-      const d = await apiPost('/api/billing/topup', { packId: match.id, idempotencyKey: (globalThis.crypto?.randomUUID?.() || String(Date.now())) });
+      // QUOTE-TOKEN CONTRACT (2026-07-20): the quote mints a token binding {pack, price, 10-min expiry}; the charge
+      // REQUIRES it, enforced here in tool code where the agent can't route around it. (1) confirm:true on a FIRST
+      // call can never move money — a prompt-injected agent is forced through a user-visible quote turn; (2) the token
+      // doubles as the Stripe idempotency key (server builds tp:<account>:<key>), so a lost-response retry of the SAME
+      // confirm dedups at Stripe instead of double-charging (the app's fix #15 class — the old fresh-UUID-per-call
+      // re-introduced it); (3) the LIVE price is re-checked at charge time — a catalog change between quote and
+      // confirm re-quotes instead of silently charging a price the human never saw. '|' separator: pack prices can
+      // carry decimals, so '.' would split wrong.
+      const mintQuote = () => {
+        const t = `qt1|${match.id}|${match.priceUsd}|${Math.floor(Date.now() / 1000) + 600}|${(globalThis.crypto?.randomUUID?.() || String(Date.now())).slice(0, 8)}`;
+        _mintedQuotes.add(t); if (_mintedQuotes.size > 50) _mintedQuotes.delete(_mintedQuotes.values().next().value); // bounded
+        return ok(`Ready to charge ${card} $${match.priceUsd} for ${match.credits.toLocaleString()} credits (one-click, no redirect — same as the app's Add credits button). Confirm with your human if they haven't already asked for this, then call buy_credits again with pack="${match.id}", confirm:true and quote_token="${t}" (valid 10 minutes).`, { quote: { packId: match.id, credits: match.credits, priceUsd: match.priceUsd, card: st.card || null, quoteToken: t, expiresInSeconds: 600 } });
+      };
+      if (!confirm || !quote_token) return mintQuote();
+      const qp = String(quote_token).split('|');
+      if (!_mintedQuotes.has(String(quote_token)) || qp[0] !== 'qt1' || qp.length < 5 || qp[1] !== match.id || Number(qp[3]) < Math.floor(Date.now() / 1000) || Number(qp[2]) !== match.priceUsd) return mintQuote(); // UNMINTED (forged/other-process — c3d6081 review: format-only validation was trivially forgeable, the token MUST come from a real quote in THIS process; a restart just re-quotes) / expired / wrong-pack / price-moved → fresh quote, never a surprise charge
+      let d;
+      try { d = await apiPost('/api/billing/topup', { packId: match.id, idempotencyKey: String(quote_token), expectedPriceUsd: match.priceUsd }); } // expectedPriceUsd: server-side price binding (409s if the catalog moved under the quote)
+      catch (e) {
+        if (e?.status === 403) return ok(`This key doesn't have billing-admin rights on the account, so it can't charge the saved card. Ask a workspace admin to top up (app Settings → Billing → Add credits, or their own buy_credits call).`, { packs });
+        throw e;
+      }
       return ok(`Done — charged ${card} $${match.priceUsd}; ${match.credits.toLocaleString()} credits are on the account now. (Receipt lands in Settings → Billing → invoice history.)`, d);
     }
     const d = await apiPost('/api/billing/checkout-link', { packId: pack });
@@ -191,7 +375,7 @@ export function registerTools(server) {
     description: "Show this account's billing at a glance: current plan (id + label + monthly price), credit balance, whether auto-reload is on, whether a card is on file, and whether YOU (this key) have ADMIN rights to change billing. Read-only, free. Call it before upgrade_plan / set_auto_reload to know what's possible — members have read-only billing.",
     inputSchema: {}, outputSchema: {
       plan: z.any().optional().describe('the current plan ({id, label, monthlyUsd})'),
-      balanceCredits: z.number().optional().describe('the current credit balance'),
+      balanceCredits: z.number().nullable().optional().describe('the current credit balance'),
       autoReload: z.any().optional().describe('auto-reload config ({enabled, thresholdCredits, reloadCredits, available})'),
       paymentMethodOnFile: z.boolean().optional().describe('whether a card is saved for one-click charges'),
       card: z.any().optional().describe('the saved card ({brand, last4}) when present'),
@@ -356,6 +540,7 @@ export function registerTools(server) {
       model: z.string().optional().describe('the product-facing label of the model that rendered it'),
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    _meta: openaiMeta(AD_RESULT_URI, 'Rendering your ad image…', 'Ad image ready'),
   }, wrap(async ({ prompt, refImages, useBrand, aspectRatio, model, imageSize }) => {
     const refs = refImages?.length ? (await Promise.all(refImages.map(toRef))).filter(Boolean) : undefined;
     const d = await apiPost('/api/generate/image', { prompt, refImages: refs, useBrand: useBrand !== false, aspectRatio, model, imageSize }); // explicit boolean so the server's saved-brand hydration default is unambiguous
@@ -426,6 +611,7 @@ export function registerTools(server) {
       input: z.any().optional().describe('the assembled render input (dry run only — resolved model, duration, scenes)'),
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    _meta: openaiMeta(AD_RESULT_URI, 'Rendering your video ad…', 'Video ad ready'),
   }, wrap(async (a) => {
     const { input, jobType, notes } = await apiPost('/api/render/assemble', a); // a passes wholesale — resolution/captions/endCard/music/lockup/ttsVoice ride the body
     // LAW 8: render_ad honors render_plan.structure/duration — a >single-clip creative assembles as stitched ACTS
@@ -445,6 +631,7 @@ export function registerTools(server) {
     },
     outputSchema: { ...JOB_OUT },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    _meta: openaiMeta(AD_RESULT_URI, 'Building your template ad…', 'Template ad ready'),
   }, wrap(async (a) => {
     const r = await renderJob('templatead', { config: a.config }, 'MCP template ad');
     if (Array.isArray(r?.raw?.images) && r.raw.images.length) { // carousel: one PNG per slide → list every URL + inline the first slide
@@ -475,6 +662,38 @@ export function registerTools(server) {
     return okVideo(`Finished video ready: ${r.url}  [job ${r.jobId}]`, r);
   }));
 
+
+  server.registerTool('post_edit', {
+    title: 'Post-production edit',
+    description: "MECHANICAL post-production on an EXISTING rendered video (its served mp4 URL) — an ordered plan of whitelisted primitives executed by ffmpeg (+ Chrome for typeset cards) in seconds for ~2 credits flat, NO AI model, the original untouched (returns a NEW video). The lane for: append a branded end card ('add an end card with our logo and website' — ADDS its seconds, never re-renders), trim, speed (0.5-2x), mute (whole or a window), audio_gain (-20..+6 dB), fade_out, corner logo watermark, anti-AI film grain. Up to 6 ops per plan, applied in order. Brand assets (name/domain/logo/accent) load from the workspace brand automatically; override per-call if needed. NEVER use generate_video/render_ad for these mechanical asks.",
+    inputSchema: {
+      videoUrl: z.string().describe('the served URL of the video to edit'),
+      ops: z.array(z.object({
+        op: z.enum(['trim', 'speed', 'mute', 'audio_gain', 'fade_out', 'append_card', 'watermark', 'grain']),
+        start: z.number().optional().describe('trim/mute window start (s)'),
+        end: z.number().optional().describe('trim/mute window end (s)'),
+        factor: z.number().optional().describe('speed 0.5-2'),
+        db: z.number().optional().describe('audio_gain -20..+6 dB'),
+        seconds: z.number().optional().describe('fade_out 0.3-3s / append_card 2-5s'),
+        headline: z.string().optional().describe('append_card: line instead of the brand name'),
+        sub: z.string().optional().describe('append_card: small line under it (defaults to the brand website)'),
+        corner: z.enum(['tl', 'tr', 'bl', 'br']).optional().describe('watermark corner (default br)'),
+        intensity: z.enum(['default', 'strong']).optional().describe('grain look'),
+      })).describe('the ordered edit plan (max 6 ops)'),
+      brandName: z.string().optional().describe('override the workspace brand name'),
+      domain: z.string().optional().describe('override the brand website'),
+      accent: z.string().optional().describe('override the brand accent hex'),
+    },
+    outputSchema: { ...JOB_OUT },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  }, wrap(async (a) => {
+    let b = {};
+    try { const bk = PROFILE !== 'default' ? `heist.brand.v1.${PROFILE}` : 'heist.brand.v1'; b = JSON.parse((await apiGet(`/api/store/${encodeURIComponent(bk)}`))?.value || 'null') || {}; } catch {}
+    const pal = (Array.isArray(b.palette) ? b.palette : []).filter(c => /^#[0-9a-f]{6}$/i.test(String(c || '')));
+    const r = await renderJob('postedit', { videoUrl: a.videoUrl, ops: (a.ops || []).slice(0, 6), brandName: a.brandName || b.name || '', domain: a.domain || b.domain || '', logo: b.logo || '', accent: a.accent || pal[0] || '' }, 'MCP post edit');
+    return okVideo(`Edited video ready: ${r.url}${Array.isArray(r?.raw?.applied) ? `  (${r.raw.applied.join(', ')})` : ''}  [job ${r.jobId}]`, r);
+  }));
+
   server.registerTool('fix_beat', {
     title: 'Fix a video beat',
     description: "Surgically re-render ONE time window (1.5-8s) of an existing rendered video and splice it back on the VIDEO TRACK ONLY — the rest of the video and ALL audio stay byte-identical. Use when one beat/shot is broken ('the shot at 8 seconds glitches') and a full re-render would waste the parts that worked; bills only the replacement clip's seconds (~1/3 of a full render). Do NOT pick a window covering spoken dialogue (a video-only splice under speech breaks lip-sync) — pass speechWindows to enforce this.",
@@ -510,6 +729,7 @@ export function registerTools(server) {
     },
     outputSchema: { ...JOB_OUT },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    _meta: openaiMeta(AD_RESULT_URI, 'Rendering your video…', 'Video ready'),
   }, wrap(async (a) => {
     const refImage = a.refImage ? await toRef(a.refImage) : undefined;
     // an agent that NAMES a model made a deliberate pick — modelExplicit gives it the server-side ask-don't-swap
@@ -529,6 +749,7 @@ export function registerTools(server) {
     },
     outputSchema: { ...JOB_OUT },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    _meta: openaiMeta(AD_RESULT_URI, 'Rendering your avatar clip…', 'Avatar clip ready'),
   }, wrap(async (a) => {
     const image = await toRef(a.image);
     const r = await renderJob('avatar', { ...a, image }, 'MCP avatar');
@@ -998,6 +1219,29 @@ export function registerTools(server) {
   }));
 
   // ---------- assets ----------
+
+  server.registerTool('list_library', {
+    title: 'List library',
+    description: "Browse this workspace's Library — every image/video generated in the Studio, newest first (the same Library the web app shows). Returns served URLs you can open directly or hand to fetch_asset for a download link, plus each asset's kind, model, and age. Free, read-only.",
+    inputSchema: {
+      kind: z.enum(['image', 'video', 'all']).optional().describe("filter by asset kind (default 'all')"),
+      limit: z.number().optional().describe('max assets to return (default 20, max 60)'),
+    },
+    outputSchema: { assets: z.array(z.object({ url: z.string(), kind: z.string().optional(), model: z.string().optional(), ageHours: z.number().optional() })).optional() },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  }, wrap(async (a) => {
+    const ak = PROFILE !== 'default' ? `heist.assets.v1.${PROFILE}` : 'heist.assets.v1';
+    let list = [];
+    try { list = JSON.parse((await apiGet(`/api/store/${encodeURIComponent(ak)}`))?.value || 'null') || []; } catch {}
+    if (!Array.isArray(list)) list = [];
+    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 }));
+    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 });
+  }));
+
   server.registerTool('fetch_asset', {
     title: 'Fetch asset',
     description: 'Resolve a generated asset reference (a /generated/… path or any URL) to a clickable absolute URL + a direct download URL.',

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hermoso",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "mcpName": "io.github.hermoso-ai/hermoso",
-  "description": "Generate finished VIDEO ADS, image ads and UGC avatar ads for any brand with AI \u2014 and spy on competitor ads across the Meta, Google and LinkedIn ad libraries plus TikTok/Instagram/YouTube organic. MCP server, CLI and Claude skills for Hermoso, the AI ad studio: brand onboarding, 30+ image/video models, finished-ad pipeline (script, voiceover, music, brand end card), ad scoring and competitor teardowns.",
+  "description": "Generate finished VIDEO ADS, image ads and UGC avatar ads for any brand with AI — and spy on competitor ads across the Meta, Google and LinkedIn ad libraries plus TikTok/Instagram/YouTube organic. MCP server, CLI and Claude skills for Hermoso, the AI ad studio: brand onboarding, 30+ image/video models, finished-ad pipeline (script, voiceover, music, brand end card), ad scoring and competitor teardowns.",
   "type": "module",
   "bin": {
     "hermoso": "bin/hermoso.mjs"