hermoso 0.1.16 → 0.1.20

package/mcp/client.mjs

@@ -13,11 +13,15 @@ export const mcpCtx = new AsyncLocalStorage();
 
 export const API_BASE = (process.env.HERMOSO_API_BASE || 'https://app.hermoso.ai').replace(/\/+$/, '');
 const TOKEN = process.env.HERMOSO_TOKEN || '';
-export const PROFILE = process.env.HERMOSO_PROFILE || 'default';
+// PINNED profile, or '' when unpinned. MUST stay unset by default: the server resolves an API key's profile as
+// header > key.keyProfileId > 'default' (adapters/auth/middleware.js), so always sending the header permanently
+// masks the brand `use_brand` saved against the key — connectors on any non-default brand then look disconnected.
+export const PROFILE = process.env.HERMOSO_PROFILE || '';
 
 function headers(extra = {}) {
   const ctx = mcpCtx.getStore();
-  const h = { 'Content-Type': 'application/json', 'x-hermoso-user': ctx?.profile || PROFILE, ...extra };
+  const prof = ctx?.profile || PROFILE; // omitted when unpinned so the key's saved brand wins server-side
+  const h = { 'Content-Type': 'application/json', ...(prof ? { 'x-hermoso-user': prof } : {}), ...extra };
   const tok = ctx?.token || TOKEN;
   if (tok) h.Authorization = `Bearer ${tok}`;
   return h;
@@ -35,7 +39,12 @@ async function unwrap(res) {
 }
 
 export async function apiGet(p, query) {
-  const qs = query ? '?' + new URLSearchParams(query).toString() : '';
+  // URLSearchParams stringifies undefined/null as the LITERAL "undefined"/"null" — so an omitted optional param
+  // arrives as a truthy string and silently changes server behaviour. Live 2026-07-27: list_google_ads_campaigns
+  // sent since=undefined&until=undefined, the server saw two truthy values, took the BETWEEN branch, and its
+  // digit-strip reduced them to '' → GAQL "segments.date BETWEEN '' and ''". Drop empties before building the qs.
+  const clean = query && Object.fromEntries(Object.entries(query).filter(([, v]) => v !== undefined && v !== null && v !== ''));
+  const qs = clean && Object.keys(clean).length ? '?' + new URLSearchParams(clean).toString() : '';
   const res = await fetch(`${API_BASE}${p}${qs}`, { headers: headers() });
   return unwrap(res);
 }

package/mcp/tools.mjs

@@ -272,7 +272,7 @@ function registerAppResources(server) {
 // the whole {key:{value}} map, so a per-key READ resolves the value out of it. WRITES go through `PUT /api/store/:key`,
 // which union-merges the sync stores server-side (adapters/sync-merge.js) so a snapshot never clobbers another device's
 // concurrent work. Keys are per-profile namespaced exactly like the webapp's pk() (bare for default, `<base>.<id>` else).
-const pk = (base) => (PROFILE !== 'default' ? `${base}.${PROFILE}` : base);
+const pk = (base) => (PROFILE && PROFILE !== 'default' ? `${base}.${PROFILE}` : base); // '' (unpinned) behaves like default
 async function readStore(base) {
   let dump; try { dump = await apiGet('/api/store/bootstrap'); } catch { return null; }
   const raw = dump && dump[pk(base)] && dump[pk(base)].value;
@@ -406,6 +406,41 @@ export function registerTools(server) {
 
   // BILLING SURFACE (read → top-up → plan/auto-reload): hermoso_credits (balance) → buy_credits (top-up link) →
   // billing_status (full picture + your role) → upgrade_plan / set_auto_reload (admin-only, pay-on-Stripe / in-app).
+
+  // ── FEEDBACK: let the AGENT report a bug or ask for a capability we don't have ────────────────────────────────
+  // Dave 2026-07-26: someone driving Hermoso from OpenClaw/Claude/Cursor hits a bug or a missing capability mid-task.
+  // Today that feedback dies in their terminal. These two tools turn the agent itself into the reporter — it already
+  // has the exact context (what it tried, what came back), which is better than anything a human would retype later.
+  // Both just email the team. Free, no credits.
+  server.registerTool('report_bug', {
+    title: 'Report a bug',
+    description: "Report a bug in Hermoso to the team. Use this when something in Hermoso genuinely misbehaves — a tool errors unexpectedly, returns a wrong or malformed result, a render comes back broken, or documented behaviour doesn't match what happened. Include what you were trying to do, the exact tool call and arguments, and what came back. Do NOT use it for out-of-credits, a policy refusal, or a missing capability (use request_feature for that). Free, no credits.",
+    inputSchema: {
+      summary: z.string().describe('one-line summary of the bug'),
+      details: z.string().describe('what you were doing, the tool + arguments you called, what you expected, and what actually happened (paste the exact error)'),
+      severity: z.enum(['low', 'medium', 'high']).optional().describe('high = blocks the task or loses paid work; medium = wrong output but workable; low = cosmetic'),
+    },
+    outputSchema: { ok: z.boolean().optional(), message: z.string().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  }, wrap(async ({ summary, details, severity }) => {
+    const d = await apiPost('/api/feedback/report', { kind: 'bug', summary, details, severity: severity || 'medium' });
+    return ok(d.message || 'Reported — thanks. The team gets this by email with your account attached.', d);
+  }));
+
+  server.registerTool('request_feature', {
+    title: 'Request a feature',
+    description: "Ask the Hermoso team for a capability that doesn't exist yet. Use this when you need something Hermoso genuinely can't do — an unsupported platform or channel, a missing model, an export format, a tool that would have completed the user's task but isn't available. Say what the user was trying to achieve, not just the feature name — the use case is what gets built. Free, no credits.",
+    inputSchema: {
+      summary: z.string().describe('one line: the capability you need'),
+      details: z.string().describe("what the user was actually trying to achieve, why the current tools couldn't do it, and what you'd expect the capability to do"),
+    },
+    outputSchema: { ok: z.boolean().optional(), message: z.string().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  }, wrap(async ({ summary, details }) => {
+    const d = await apiPost('/api/feedback/report', { kind: 'feature', summary, details });
+    return ok(d.message || 'Sent — thanks. The team reads every one of these.', d);
+  }));
+
   server.registerTool('billing_status', {
     title: 'Billing status',
     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.",
@@ -521,6 +556,184 @@ export function registerTools(server) {
     return ok(`Now acting on ${hit.name} (${hit.id}) — brand, memory, renders and Library all scope to it.`, { ok: true, brand: hit });
   }));
 
+
+
+  // ---------- META engagement + insights (organic performance and the comment thread under a post) ----------
+  server.registerTool('meta_page_insights', {
+    title: 'Facebook Page + Instagram insights',
+    description: 'Organic performance for the brand’s connected Facebook Page and its linked Instagram account — impressions, reach, engagement, follower/fan counts. This is ORGANIC reach; use meta_insights for paid ad performance.',
+    inputSchema: {
+      pageId: z.string().optional().describe('Page id — omit when the brand has exactly one Page connected'),
+      period: z.enum(['day', 'week', 'days_28']).optional().describe('window (default week)'),
+    },
+    outputSchema: { pageName: z.string().optional(), page: z.array(z.any()).optional(), instagram: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/meta/page-insights', { pageId: a.pageId, period: a.period });
+    const fmt = (arr) => (arr || []).map(m => `  • ${m.name}: ${m.value ?? '—'}`).join('\n');
+    return ok(`${d.pageName} (${d.period})\nFacebook:\n${fmt(d.page) || '  (none)'}${d.instagram ? `\nInstagram:\n${fmt(d.instagram)}` : ''}${d.pageError ? `\n(page: ${d.pageError})` : ''}${d.instagramError ? `\n(instagram: ${d.instagramError})` : ''}`, d);
+  }));
+
+  server.registerTool('meta_post_insights', {
+    title: 'Insights for one Facebook/Instagram post',
+    description: 'Performance for a single organic post — impressions/reach, engagement and clicks on Facebook; reach, likes, comments, saves and shares on Instagram. Use it to find which organic posts earned their reach before turning one into a paid ad.',
+    inputSchema: {
+      postId: z.string().describe('post/media id returned by post_to_meta'),
+      target: z.enum(['facebook', 'instagram']).optional().describe('which metric set to ask for (default facebook)'),
+      pageId: z.string().optional().describe('Page id — omit when only one Page is connected'),
+    },
+    outputSchema: { postId: z.string().optional(), metrics: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/meta/post-insights', { postId: a.postId, target: a.target, pageId: a.pageId });
+    return ok(`${d.target} post ${d.postId}:\n${(d.metrics || []).map(m => `• ${m.name}: ${m.value ?? '—'}`).join('\n') || '(no metrics)'}`, d);
+  }));
+
+  server.registerTool('list_meta_comments', {
+    title: 'Read comments on a Meta post',
+    description: 'Read the comments under a Facebook Page post or Instagram media object — customer questions, objections and the exact language real people use about the product. Good raw material for ad copy, and the first step before replying or moderating.',
+    inputSchema: {
+      postId: z.string().describe('post/media id'),
+      pageId: z.string().optional().describe('Page id — omit when only one Page is connected'),
+      limit: z.number().optional().describe('how many comments (1–50, default 25)'),
+    },
+    outputSchema: { count: z.number().optional(), comments: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/meta/comments', { postId: a.postId, pageId: a.pageId, limit: a.limit });
+    const lines = (d.comments || []).map(c => `• ${c.author || '(unknown)'}: ${String(c.text).replace(/\s+/g, ' ').slice(0, 90)} — ${c.id}${c.hidden ? ' [hidden]' : ''}${c.likes ? ` · ${c.likes} likes` : ''}`);
+    return ok(`${d.count} comment(s) on ${d.postId}:\n${lines.join('\n') || '(none)'}`, d);
+  }));
+
+  server.registerTool('reply_to_meta_comment', {
+    title: 'Reply to a Facebook/Instagram comment',
+    description: 'Post a public reply to a comment on the brand’s Facebook or Instagram post. This is PUBLIC and posted as the brand — show the user the exact wording and get their go-ahead first.',
+    inputSchema: {
+      commentId: z.string().describe('comment id from list_meta_comments'),
+      message: z.string().describe('reply text'),
+      pageId: z.string().optional().describe('Page id — omit when only one Page is connected'),
+    },
+    outputSchema: { ok: z.boolean().optional(), id: z.string().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/meta/comment/reply', { commentId: a.commentId, message: a.message, pageId: a.pageId });
+    return ok(`Replied to comment ${a.commentId} (${d.id}).`, d);
+  }));
+
+  server.registerTool('moderate_meta_comment', {
+    title: 'Hide, unhide or delete a Meta comment',
+    description: 'Moderate a comment on the brand’s Facebook or Instagram post. Prefer hide over delete — hiding is reversible and invisible to the commenter. Deleting is PERMANENT and requires confirm:true after the user has agreed.',
+    inputSchema: {
+      commentId: z.string().describe('comment id from list_meta_comments'),
+      action: z.enum(['hide', 'unhide', 'delete']).optional().describe('default hide'),
+      confirm: z.boolean().optional().describe('required (true) only for delete'),
+      pageId: z.string().optional().describe('Page id — omit when only one Page is connected'),
+    },
+    outputSchema: { ok: z.boolean().optional(), action: z.string().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/meta/comment/moderate', { commentId: a.commentId, action: a.action, confirm: a.confirm, pageId: a.pageId });
+    return ok(`Comment ${d.commentId}: ${d.action}d.`, d);
+  }));
+
+  // ---------- THREADS read + manage (needs a connected Threads account; insights/replies/delete need Meta review) ----
+  server.registerTool('list_threads_posts', {
+    title: 'List your Threads posts',
+    description: 'List recent posts on the brand’s connected Threads account (id, text, media, permalink, timestamp). Use it to find a post id for threads_insights, list_threads_replies, reply_to_thread or delete_thread.',
+    inputSchema: { limit: z.number().optional().describe('how many posts (1–50, default 15)') },
+    outputSchema: { username: z.string().optional(), count: z.number().optional(), posts: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/threads/posts', { limit: a.limit });
+    const lines = (d.posts || []).map(p => `• ${String(p.text || '(no text)').replace(/\s+/g, ' ').slice(0, 80)} — ${p.id} · ${String(p.timestamp || '').slice(0, 10)} · ${p.permalink || ''}`);
+    return ok(`@${d.username} — ${d.count} post(s):\n${lines.join('\n') || '(none)'}`, d);
+  }));
+
+  server.registerTool('threads_insights', {
+    title: 'Threads insights',
+    description: 'Performance for ONE Threads post (views, likes, replies, reposts, quotes, shares) when postId is given, or for the whole account (plus follower count) when it is omitted. Use it to report results or to learn which posts worked before writing more.',
+    inputSchema: { postId: z.string().optional().describe('post id from list_threads_posts — omit for account-level insights') },
+    outputSchema: { scope: z.string().optional(), metrics: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/threads/insights', { postId: a.postId });
+    const lines = (d.metrics || []).map(m => `• ${m.name}: ${m.values?.[0]?.value ?? m.total_value?.value ?? '—'}`);
+    return ok(`${d.scope === 'post' ? `Post ${d.postId}` : `@${d.username} (account)`}\n${lines.join('\n') || '(no metrics returned)'}`, d);
+  }));
+
+  server.registerTool('list_threads_replies', {
+    title: 'List replies on a Threads post',
+    description: 'Read the replies on a Threads post. Set conversation:true to walk the entire thread rather than only direct replies. Use before reply_to_thread so you answer with the actual conversation in view.',
+    inputSchema: {
+      postId: z.string().describe('post id from list_threads_posts'),
+      conversation: z.boolean().optional().describe('true = the whole thread, not just direct replies'),
+      limit: z.number().optional().describe('how many replies (1–50, default 25)'),
+    },
+    outputSchema: { count: z.number().optional(), replies: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/threads/replies', { postId: a.postId, conversation: a.conversation ? 'true' : undefined, limit: a.limit });
+    const lines = (d.replies || []).map(r => `• @${r.username}: ${String(r.text || '').replace(/\s+/g, ' ').slice(0, 90)} — ${r.id}${r.hide_status === 'HIDDEN' ? ' [hidden]' : ''}`);
+    return ok(`${d.count} repl(ies) on ${d.postId}:\n${lines.join('\n') || '(none)'}`, d);
+  }));
+
+  server.registerTool('reply_to_thread', {
+    title: 'Reply on Threads',
+    description: 'Post a reply to a Threads post — the brand’s own or someone else’s. This PUBLISHES publicly under the brand’s account, so show the user the exact wording and get their go-ahead first.',
+    inputSchema: {
+      replyToId: z.string().describe('the post id being replied to'),
+      text: z.string().describe('reply text (max 500 characters)'),
+    },
+    outputSchema: { ok: z.boolean().optional(), id: z.string().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/threads/reply', { replyToId: a.replyToId, text: a.text });
+    return ok(`Replied on Threads (${d.id}).`, d);
+  }));
+
+  server.registerTool('hide_thread_reply', {
+    title: 'Hide or unhide a Threads reply',
+    description: 'Hide a reply on the brand’s Threads post (or unhide it with hide:false) — for spam and abuse moderation.',
+    inputSchema: {
+      replyId: z.string().describe('reply id from list_threads_replies'),
+      hide: z.boolean().optional().describe('false to UNHIDE (default true)'),
+    },
+    outputSchema: { ok: z.boolean().optional(), hidden: z.boolean().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/threads/reply/hide', { replyId: a.replyId, hide: a.hide });
+    return ok(`Reply ${a.replyId} ${d.hidden ? 'hidden' : 'unhidden'}.`, d);
+  }));
+
+  server.registerTool('delete_thread', {
+    title: 'Delete a Threads post',
+    description: 'Permanently delete one of the brand’s Threads posts. IRREVERSIBLE — you must confirm with the user first, then pass confirm:true.',
+    inputSchema: {
+      postId: z.string().describe('post id from list_threads_posts'),
+      confirm: z.boolean().describe('must be true; only set it after the user has explicitly agreed to the deletion'),
+    },
+    outputSchema: { ok: z.boolean().optional(), deleted: z.string().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/threads/delete', { postId: a.postId, confirm: a.confirm });
+    return ok(`Deleted Threads post ${d.deleted}.`, d);
+  }));
+
+  server.registerTool('search_threads_keyword', {
+    title: 'Search Threads by keyword',
+    description: 'Search PUBLIC Threads posts for a keyword or topic — competitor listening, finding what people say about a product, or sourcing real customer language for ad copy. Distinct from search_threads, which reads a specific profile.',
+    inputSchema: {
+      q: z.string().describe('keyword or phrase'),
+      searchType: z.enum(['TOP', 'RECENT']).optional().describe('TOP (default) or RECENT'),
+    },
+    outputSchema: { count: z.number().optional(), posts: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/threads/search', { q: a.q, searchType: a.searchType });
+    const lines = (d.posts || []).map(p => `• @${p.username}: ${String(p.text || '').replace(/\s+/g, ' ').slice(0, 90)} — ${p.permalink || p.id}`);
+    return ok(`${d.count} result(s) for "${d.q}":\n${lines.join('\n') || '(none)'}`, d);
+  }));
+
   // ---------- META publishing + ads management (needs a connected Meta account: Settings ▸ Connectors ▸ Meta) ----------
   server.registerTool('list_meta_pages', {
     title: 'List Meta pages & ad accounts',
@@ -780,6 +993,7 @@ export function registerTools(server) {
       budgetResourceName: z.string().optional().describe('reuse an existing budget instead of creating one'),
       channelType: z.enum(['SEARCH', 'DISPLAY']).optional().describe('default SEARCH'),
       searchPartners: z.boolean().optional().describe('SEARCH only — also serve on Google search partners (default false)'),
+      dryRun: z.boolean().optional().describe('validate the config against Google without creating anything — proves the account accepts writes and that the fields are valid. Nothing is written and no budget is consumed'),
       loginCustomerId: z.string().optional().describe('manager id if operating through an MCC'),
     },
     outputSchema: { ok: z.boolean().optional(), campaignResourceName: z.string().optional(), campaignId: z.string().optional(), status: z.string().optional(), budgetResourceName: z.string().optional() },
@@ -2164,7 +2378,7 @@ export function registerTools(server) {
       try {
         const cur = save === true ? null : await apiGet('/api/brand/current').catch(() => null);
         if (save === true || !cur?.hasBrand) {
-          const bk = PROFILE !== 'default' ? `heist.brand.v1.${PROFILE}` : 'heist.brand.v1'; // mirror the webapp's per-profile key namespacing
+          const bk = PROFILE && PROFILE !== 'default' ? `heist.brand.v1.${PROFILE}` : 'heist.brand.v1'; // mirror the webapp's per-profile key namespacing
           await apiPut(`/api/store/${encodeURIComponent(bk)}`, { value: JSON.stringify(p) });
           saved = true;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermoso",
-  "version": "0.1.16",
+  "version": "0.1.20",
   "mcpName": "io.github.hermoso-ai/hermoso",
   "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",