hermoso 0.1.449 → 0.1.451

package/mcp/arg-guard.mjs

@@ -0,0 +1,112 @@
+// AN ARGUMENT A TOOL DOES NOT TAKE IS NEVER SILENTLY DROPPED (2026-10-26, customer report).
+//
+// meta_post_insights was called with `platform: 'instagram'` instead of `target`. The MCP SDK parses arguments with
+// the tool's zod object, which STRIPS unknown keys, so the handler never saw `platform`, defaulted to Facebook and read
+// Facebook metrics for an Instagram media — a confident wrong answer, with nothing saying an argument was ignored.
+// The same strip happens on /v1 (z.object) and the Studio agent reads `input.<name>` and nothing else.
+//
+// ONE RULE FOR EVERY SURFACE, applied where each surface parses: an argument the schema does not declare is named
+// back to the caller, with the declared argument it most likely meant (modes: argGuardMode). The default refuses only a
+// probable typo/synonym of a real argument and otherwise runs the call with the note first in its answer, because hosts
+// and agent frameworks were never measured for what they add to `arguments` (the advertised schemas already say
+// additionalProperties:false, and call_tool has refused every undeclared key since 2026-09-30). Every unknown key is
+// logged by NAME (never value) so the blast radius of full `reject` is measured from production before anyone flips it.
+// Keys starting with `_` are host metadata (`_meta`, `_hermoso…`) and are never named.
+//
+// Byte-identical in mcp/ and cli/mcp/ (the CLI ships rooted at cli/), and imported by server.js for /v1 and the Studio.
+
+export const UNKNOWN_ARGS_SYM = Symbol.for('hermoso.unknownArgs');
+
+/**
+ * 'typo' (default) | 'reject' | 'warn' | 'off' from the environment value. Anything unrecognised is `typo`:
+ *   typo   — REFUSED when an unknown key is a likely misspelling or synonym of a declared one (the customer's
+ *            `platform` for `target`: running without it gives a confidently wrong answer); otherwise the call runs
+ *            and its answer starts with the note;
+ *   reject — every unknown key refuses the call (what call_tool has done since 2026-09-30);
+ *   warn   — never refuses, always notes; off — the old silent strip.
+ */
+export function argGuardMode(v = (typeof process !== 'undefined' ? process.env?.HERMOSO_UNKNOWN_ARGS : '')) {
+  const s = String(v || '').trim().toLowerCase();
+  return s === 'reject' || s === 'off' || s === 'warn' ? s : 'typo';
+}
+/** Whether this mode refuses this set of unknown keys. */
+export function argGuardRefuses(mode, unknown = [], declared = []) {
+  if (!unknown.length || mode === 'off' || mode === 'warn') return false;
+  if (mode === 'reject') return true;
+  return unknown.some((k) => !!didYouMean(k, declared));
+}
+
+/**
+ * The argument names a schema declares, or null when it accepts any key (so nothing can be called unknown).
+ * Accepts a zod raw shape ({name: zodType}), a zod object, or a JSON Schema object (the Studio's input_schema).
+ */
+export function declaredArgKeys(schema) {
+  if (!schema || typeof schema !== 'object') return null;
+  // JSON Schema (checked AFTER zod: a zod v4 object also carries `type: 'object'`)
+  if (typeof schema.safeParse !== 'function' && (schema.type === 'object' || (schema.properties && typeof schema.properties === 'object'))) {
+    if (schema.additionalProperties === true || (schema.additionalProperties && typeof schema.additionalProperties === 'object')) return null;
+    return Object.keys(schema.properties || {});
+  }
+  // zod object
+  if (typeof schema.safeParse === 'function') {
+    const def = schema._zod?.def || schema._def || {};
+    const shape = typeof schema.shape === 'object' ? schema.shape : (typeof def.shape === 'function' ? def.shape() : def.shape);
+    if (!shape || typeof shape !== 'object') return null;
+    const cat = def.catchall;
+    const loose = (cat && (cat._zod?.def?.type || cat._def?.typeName) && !/never/i.test(String(cat._zod?.def?.type || cat._def?.typeName))) || def.unknownKeys === 'passthrough';
+    return loose ? null : Object.keys(shape);
+  }
+  // raw shape: every value is a zod type
+  const vals = Object.values(schema);
+  if (vals.length && vals.every((v) => v && typeof v === 'object' && typeof v.safeParse === 'function')) return Object.keys(schema);
+  if (!vals.length) return [];
+  return null;
+}
+
+/** The keys of `args` the schema does not declare (host `_` metadata excluded). [] when there are none or none can be judged. */
+export function unknownArgs(declared, args) {
+  if (!Array.isArray(declared) || !args || typeof args !== 'object' || Array.isArray(args)) return [];
+  const known = new Set(declared);
+  return Object.keys(args).filter((k) => !known.has(k) && !k.startsWith('_'));
+}
+
+function lev(a, b) {
+  a = a.toLowerCase(); b = b.toLowerCase();
+  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) d[0][j] = j;
+  for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+  return d[a.length][b.length];
+}
+// Words agents reach for that name the same idea under a different argument (the customer's case is the first row).
+const ALIASES = {
+  platform: ['target', 'platforms', 'channel', 'channels', 'network', 'source', 'sources'],
+  network: ['platform', 'target', 'channel'],
+  channel: ['channels', 'platform', 'target'],
+  count: ['limit', 'max', 'n'], max: ['limit'], max_results: ['limit'], maxResults: ['limit'], page_size: ['limit'], pageSize: ['limit'],
+  page: ['cursor'], next: ['cursor'], nextCursor: ['cursor'], after: ['cursor'],
+  text: ['message', 'caption', 'body'], message: ['text', 'caption'], caption: ['message', 'text'],
+  url: ['imageUrl', 'videoUrl', 'link', 'image', 'video'], image: ['imageUrl'], video: ['videoUrl'],
+  id: ['postId', 'mediaId', 'commentId', 'videoId', 'conversationId'],
+};
+/** The declared argument `key` most likely meant, or ''. */
+export function didYouMean(key, declared = []) {
+  const k = String(key);
+  const alias = (ALIASES[k] || []).find((a) => declared.includes(a));
+  if (alias) return alias;
+  const lower = declared.find((d) => d.toLowerCase() === k.toLowerCase() || d.toLowerCase().replace(/_/g, '') === k.toLowerCase().replace(/_/g, ''));
+  if (lower) return lower;
+  if (/id$/i.test(k) && k.length > 2 && declared.includes('id') && !declared.some((d) => /id$/i.test(d) && d !== 'id')) return 'id'; // jobId / job_id for a tool whose only id is `id`
+  let best = '', bd = Infinity;
+  for (const d of declared) { const x = lev(k, d); if (x < bd) { bd = x; best = d; } }
+  return bd <= Math.max(2, Math.floor(k.length / 3)) ? best : '';
+}
+
+/** The one sentence every surface prints. `rejected` words it as a refusal; otherwise as a note on a call that ran. */
+export function unknownArgsNote(tool, unknown = [], declared = [], { rejected = false } = {}) {
+  if (!unknown.length) return '';
+  const named = unknown.map((k) => { const m = didYouMean(k, declared); return `\`${k}\`${m ? ` (did you mean \`${m}\`?)` : ''}`; }).join(', ');
+  const takes = declared.length ? ` ${tool || 'This tool'} takes: ${declared.join(', ')}.` : ` ${tool || 'This tool'} takes no arguments.`;
+  return rejected
+    ? `Unknown argument${unknown.length > 1 ? 's' : ''} ${named} for ${tool || 'this tool'} — nothing was run.${takes}`
+    : `⚠ Ignored unknown argument${unknown.length > 1 ? 's' : ''} ${named}: ${tool || 'this tool'} does not take ${unknown.length > 1 ? 'them' : 'it'}, so the call ran WITHOUT ${unknown.length > 1 ? 'them' : 'it'}. Check the answer below still matches what you asked, or call again with the right name.${takes}`;
+}

package/mcp/client.mjs

@@ -146,7 +146,7 @@ async function unwrap(res, { read = false } = {}) {
     // ledger with the tool name off x-hermoso-tool. wrap() reports ONLY the errors that lack this marker — a local
     // throw, a schema rejection, a socket reset — which is what stops the twins double-counting every 4xx.
     // `connectUrl` rides a not-connected 401 with the brand already in it, so a hint never rebuilds the link.
-    throw Object.assign(new Error(msg), { status: res.status, _viaApi: true, ...(body?.connector ? { connector: body.connector } : {}), ...(typeof body?.connectUrl === 'string' ? { connectUrl: body.connectUrl } : {}), ...(body?.meta?.videoChoice && typeof body.meta.videoChoice === 'object' ? { videoChoice: body.meta.videoChoice } : {}), ...(body?.metaAuthHold === true ? { metaAuthHold: true } : {}), ...(body?.meta?.welcomeClaim && typeof body.meta.welcomeClaim === 'object' && body.meta.welcomeClaim.url ? { welcomeClaim: { credits: Number(body.meta.welcomeClaim.credits) || 0, url: String(body.meta.welcomeClaim.url) } } : {}), ...(body?.remedy && typeof body.remedy === 'object' && typeof body.remedy.code === 'string' ? { remedy: body.remedy } : {}) }); // `remedy` (2026-10-25): the server's structured next step (a publish outcome, Meta's security hold), handed on whole to wrap()'s _meta and /v1 // `videoChoice` rides a 402 for a video the caller expects and cannot afford (server videoChoiceFor) — wrap() spells its options out instead of a bare top-up line
+    throw Object.assign(new Error(msg), { status: res.status, _viaApi: true, ...(typeof body?.code === 'string' ? { apiCode: body.code } : {}), ...(body?.connector ? { connector: body.connector } : {}), ...(typeof body?.connectUrl === 'string' ? { connectUrl: body.connectUrl } : {}), ...(body?.meta?.videoChoice && typeof body.meta.videoChoice === 'object' ? { videoChoice: body.meta.videoChoice } : {}), ...(body?.metaAuthHold === true ? { metaAuthHold: true } : {}), ...(body?.meta?.welcomeClaim && typeof body.meta.welcomeClaim === 'object' && body.meta.welcomeClaim.url ? { welcomeClaim: { credits: Number(body.meta.welcomeClaim.credits) || 0, url: String(body.meta.welcomeClaim.url) } } : {}), ...(body?.remedy && typeof body.remedy === 'object' && typeof body.remedy.code === 'string' ? { remedy: body.remedy } : {}) }); // `remedy` (2026-10-25): the server's structured next step (a publish outcome, Meta's security hold), handed on whole to wrap()'s _meta and /v1 // `videoChoice` rides a 402 for a video the caller expects and cannot afford (server videoChoiceFor) — wrap() spells its options out instead of a bare top-up line
   }
   // WHAT THIS CALL WAS CHARGED (2026-10-19). A paid route answers {data, creditsUsed}, and the unwrap below drops the
   // sibling, so a synchronous paid tool's reply could never say what it cost. It is added to the running tool call's

package/mcp/tools.mjs

@@ -12,6 +12,7 @@ import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 // The UTF-16 well-formedness law — see wellFormedServer() below for why it is applied here, and
 // ./well-formed.mjs for why that specifier is the only one that can work in a byte-identical twin.
 import { wellFormedValue, wellFormedString } from './well-formed.mjs';
+import { UNKNOWN_ARGS_SYM, argGuardMode, argGuardRefuses, declaredArgKeys, didYouMean, unknownArgs, unknownArgsNote } from './arg-guard.mjs'; // an undeclared argument is named back, never silently stripped (2026-10-26)
 // WHICH CONNECTOR A TOOL NEEDS — the same table and the same decision the Studio chat applies (lib/studio-roster.mjs
 // re-exports every symbol from here). `./roster-scope.mjs` is the only specifier that resolves in a byte-identical
 // twin, for the same reason ./well-formed.mjs is. See applyToolGates() for the seam and roster-scope.mjs for the law.
@@ -2085,6 +2086,15 @@ export function inboxReplyTarget(id) {
  * eight vendors disagree about all of them; what comes OUT is always the same, so an agent writes one loop.
  * Returns null when there is no id or no text — an item you can neither quote nor answer is noise.
  */
+// THE SENTENCE A PARTLY-READ SOURCE CONTRIBUTES TO list_inbox `notes`, or '' when it read whole. A route reports a
+// part it could not read as `unreadable: [...]` beside its own `note` (the Meta DM inbox, the conversation list); the
+// note is the route's words, and the label says which source they belong to. PURE, so a check runs it.
+export function inboxShortNote(src, d) {
+  const bad = Array.isArray(d?.unreadable) ? d.unreadable : [];
+  if (!bad.length) return '';
+  const said = typeof d?.note === 'string' && d.note.trim() ? d.note.trim() : bad.map((u) => String(u?.error || 'could not be read')).join('; ');
+  return `${src?.label || 'A source'}s were not read in full: ${said.slice(0, 600)}`;
+}
 export function normalizeInboxItem(source, row = {}) {
   const src = BY_SOURCE.get(source);
   if (!src) return null;
@@ -2805,7 +2815,7 @@ export const undeclaredArgsText = (name, extra, h) => {
   const shape = h && h.inputSchema && h.inputSchema.shape;
   const takes = shape && typeof shape === 'object' ? Object.keys(shape) : [];
   const brandNote = extra.includes('brand') ? ` ${name} acts on the profile this connection is on — pin another with use_brand first, then call it again.` : '';
-  return `${name} does not take ${extra.map((k) => `\`${k}\``).join(', ')}, so nothing was run: an argument a tool does not declare would be silently ignored.${brandNote} It takes: ${takes.length ? takes.join(', ') : '(no arguments)'}.`;
+  return `${name} does not take ${extra.map((k) => { const m = didYouMean(k, takes); return `\`${k}\`${m ? ` (did you mean \`${m}\`?)` : ''}`; }).join(', ')}, so nothing was run: an argument a tool does not declare would be silently ignored.${brandNote} It takes: ${takes.length ? takes.join(', ') : '(no arguments)'}.`;
 };
 export async function legacyToolAnswer(name, request, extra, ctx) {
   const spec = LEGACY_TOOL_NAMES[name];
@@ -3574,14 +3584,43 @@ function registerWidgetHostSplits(rawServer, ctx, opts) {
 const _wfWrapped = new WeakMap();
 // EXPORTED so tools/well-formed-law-check.mjs can RUN the real seam over real fixtures rather than read it. It is
 // not part of the module's public surface in any other sense — `registerTools` is the only caller.
+// UNKNOWN ARGUMENTS ON A HOST'S OWN tools/call (2026-10-26, customer report — see mcp/arg-guard.mjs). The SDK parses
+// `arguments` with the tool's zod object, which strips an undeclared key before any handler sees it, so the only place
+// the raw keys exist is the SDK's validateToolInput. It is wrapped ONCE per server instance: a refusal throws (the SDK
+// turns that into an isError result), and a key that is noted rather than refused rides the parsed args under a
+// symbol until withUnknownArgsNote puts the sentence at the top of the answer.
+export function guardUnknownArgs(server) {
+  if (!server || typeof server.validateToolInput !== 'function' || server[UNKNOWN_ARGS_SYM]) return server;
+  const orig = server.validateToolInput;
+  const guarded = async function (tool, args, toolName) {
+    const declared = declaredArgKeys(tool?.inputSchema);
+    const unknown = unknownArgs(declared, args);
+    const mode = argGuardMode();
+    if (unknown.length && mode !== 'off') {
+      try { console.error(`[mcp-unknown-arg] tool=${toolName} keys=${unknown.join(',')} mode=${mode}`); } catch {}
+      if (argGuardRefuses(mode, unknown, declared)) throw new Error(unknownArgsNote(toolName, unknown, declared, { rejected: true }));
+    }
+    const out = await orig.call(this, tool, args, toolName);
+    if (unknown.length && mode !== 'off' && out && typeof out === 'object') { try { Object.defineProperty(out, UNKNOWN_ARGS_SYM, { value: unknownArgsNote(toolName, unknown, declared), enumerable: false, configurable: true }); } catch {} }
+    return out;
+  };
+  try { Object.defineProperty(server, 'validateToolInput', { value: guarded, configurable: true, writable: true }); Object.defineProperty(server, UNKNOWN_ARGS_SYM, { value: true }); } catch {}
+  return server;
+}
+export function withUnknownArgsNote(result, args) {
+  const note = args && typeof args === 'object' ? args[UNKNOWN_ARGS_SYM] : '';
+  if (!note || !result || typeof result !== 'object' || !Array.isArray(result.content)) return result;
+  return { ...result, content: [{ type: 'text', text: note }, ...result.content] };
+}
 export function wellFormedServer(rawServer) {
+  guardUnknownArgs(rawServer);
   return new Proxy(rawServer, {
     get(t, p) {
       if (p === 'registerTool') return (name, def, handler) => {
         let safe = _wfWrapped.get(handler);
         if (!safe) {
           safe = async (args, extra) => {
-            try { return wellFormedValue(await handler(args, extra)); }
+            try { return wellFormedValue(withUnknownArgsNote(await handler(args, extra), args)); }
             catch (e) {
               try { const m = wellFormedString(e?.message); if (e && m !== e.message) e.message = m; } catch {}
               throw e;
@@ -4477,6 +4516,12 @@ function buildTools(rawServer, opts = {}, sink = null) {
       try {
         const d = await apiGet(whole ? src.readAll : src.read, q);
         const rows = Array.isArray(d) ? d : (d.comments || d.replies || d.mentions || d.reviews || d.messages || d.events || d.items || d.data || []);
+        // A SOURCE THAT READ ONLY PART OF ITSELF SAYS SO (2026-10-26, customer report: Instagram DMs at limit >= 32 came
+        // back as 0 items and NO note, because the DM inbox route reported its failure in `unreadable` + `note` and this
+        // loop only ever read the rows). Any route answering `unreadable` has its sentence carried into `notes`, on both
+        // branches, so a short list is never mistaken for a quiet inbox.
+        const short = inboxShortNote(src, d);
+        if (short) notes.push(short);
         if (whole) { for (const r of rows) { const it = normalizeInboxItem(src.source, r); if (it) items.push(it); } continue; } // already one row per conversation
         // A DM FOLDS TO ONE ITEM AND CARRIES THE ID YOU ANSWER TO — see foldConversationRows. Deriving this from
         // `kind` rather than naming the two sources means a third DM channel inherits it by declaring its kind.
@@ -4488,6 +4533,9 @@ function buildTools(rawServer, opts = {}, sink = null) {
         const use = src.dmReplyId ? foldConversationRows(rows, d?.[src.dmReplyId]) : rows;
         for (const r of use) { const it = normalizeInboxItem(src.source, src.dmReplyId && typeof d?.conversationId === 'string' && !r.conversationId ? { ...r, conversationId: d.conversationId } : r); if (it) items.push(it); }
       } catch (e) {
+        // AN ID THAT DOES NOT RESOLVE ENDS THE CALL AS AN ERROR (2026-10-26, customer report: an unconnected pageId
+        // answered "0 items"). The caller named a Page; reading nothing from it is not a quiet inbox, it is a wrong id.
+        if (e?.apiCode === 'meta_page_not_connected') return { content: [{ type: 'text', text: String(e.message) }], isError: true };
         // NAMED, never swallowed. A connector that is simply not linked is not worth a line; anything else is.
         const msg = String(e?.message || e);
         if (e?.status === 401 || /not connected/i.test(msg)) continue;
@@ -5057,7 +5105,7 @@ function buildTools(rawServer, opts = {}, sink = null) {
     inputSchema: {
       ...MANAGE_BRAND,
       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)'),
+      target: z.enum(['facebook', 'instagram']).optional().describe('which metric set to ask for; an Instagram media id is detected and read as Instagram either way (default: Facebook for a Facebook id)'),
       account: z.string().optional().describe('which Instagram account — an @handle or id from list_connector_accounts("instagram"). Needed when several are linked, and the way an Instagram Login (standalone) account is reached; omit for the one Page-linked account.'),
       pageId: z.string().optional().describe('Page id — omit when only one Page is connected'),
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermoso",
-  "version": "0.1.449",
+  "version": "0.1.451",
   "mcpName": "io.github.hermoso-ai/hermoso",
   "description": "AI marketing agent and AI ad generator, run from your own AI agent. 933 tools. No markup on models. Publishing, scheduling, ad campaign management, comments, DMs and analytics are free on every plan. AD PLATFORMS: Meta, Google Ads, TikTok Ads, LinkedIn Ads, Reddit Ads, X Ads, Pinterest Ads, Snapchat Ads, Microsoft Advertising, Apple Search Ads, ChatGPT Ads and AppLovin Ads, plus product feeds in Google Merchant Center. PUBLISHING AND SCHEDULING: Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn, Pinterest, Bluesky, Telegram and Google Business Profile. INSTAGRAM DM AUTOMATIONS: a keyword comment, a DM, a story reply or an ig.me link gets an automatic private reply from the brand. 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",