hermoso 0.1.251 → 0.1.253

package/README.md

@@ -8,6 +8,13 @@ campaigns behind them — all over [MCP](https://modelcontextprotocol.io) tools,
 **841 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
 catalog with exact per-render credit costs plus the full capability map.
 
+**Most of it costs nothing.** Publishing and scheduling posts, building and managing paid campaigns, analytics
+and insights, comments and DMs, connectors, brand profiles and team seats are **free on every plan**, with no
+per-post or per-channel fee and no seat pricing. Credits are spent only on running an AI model (image, video,
+voice, text, planning, post-production) and on Ad Spy research, and posting an ad you already rendered is never a
+second charge. The one exception is X (Twitter), where posting and reads bill a few credits per call because X
+charges per API request.
+
 **What it connects to.** 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 — **ten** channels: Facebook, Instagram, Threads, TikTok,
@@ -149,7 +156,7 @@ session, run `/mcp`, find the server and press Authenticate. Measured against Cl
 
 Your agent now has the full studio **with your workspace's context**: the brand profile, products, logos and
 learned memory you set up in the web app apply automatically (`get_brand` shows what's saved; omit `brand` in
-`plan_ad`/`plan_variations` to use it). Renders bill your Hermoso credits — same prices as the Studio. Only AI model runs and Ad Spy research spend credits; publishing, scheduling, ads management and analytics are free on every plan (X is the one per-call exception).
+`plan_ad`/`plan_variations` to use it). Renders bill your Hermoso credits — same prices as the Studio. Only AI model runs and Ad Spy research spend credits; publishing, scheduling, ads management and analytics are free on every plan (posting to X and reading X data are the one per-call exception, managing X ads is free).
 
 ## 1. MCP server (stdio) — Claude Code / Cursor / Codex
 

package/mcp/hermoso-mcp.mjs

@@ -17,10 +17,13 @@ const server = new McpServer({ name: 'hermoso-mcp', version: '1.0.0' }, {
   instructions: MCP_INSTRUCTIONS,
 });
 
-// Roster scoping, same groups as the hosted connector's ?tools= (see registerTools). The DEFAULT is every group
-// except `ads` and `analytics` (OPT_IN_TOOL_GROUPS) — together ~254k of the ~365k full roster, so the default is
-// ~112k. Both are held out on SIZE alone, and nothing is lost: `enable_tools` switches either on mid-session with
-// no reconnect. HERMOSO_TOOLS=all restores the full roster; HERMOSO_TOOLS=create,channels narrows it further.
+// Roster scoping, same groups as the hosted connector's ?tools= (see registerTools). SINCE 2026-09-17 THE DEFAULT
+// IS CORE-FIRST: the `core` group plus the handful of tools that make a connection drivable, measured at ~6K tokens
+// against ~87K for the old default of every group but the opt-in three. Nothing is lost — everything else is held
+// out of the LIST on SIZE alone, and `find_tools` finds it, `call_tool` runs it and a direct tools/call to a name
+// you already know still works. `enable_tools` LISTS a whole group mid-session for a client that re-lists (stdio
+// does). HERMOSO_TOOLS=all restores the full roster; HERMOSO_TOOLS=create,channels narrows it further; and
+// MCP_CORE_FIRST=1 opts this process into the small core-first roster (the default is the full roster: see mcp/tools.mjs).
 // An unknown group EXITS rather than silently serving all of them — a scoped connection you did not get is
 // worse than one you were told you could not have.
 // Both env names are read: HERMOSO_TOOLS is the current prefix, HEIST_TOOLS the pre-rebrand name that is live in

package/mcp/http.mjs

@@ -15,7 +15,7 @@
 import { randomUUID } from 'node:crypto';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { registerTools, MCP_INSTRUCTIONS, parseToolScope } from './tools.mjs';
+import { registerTools, MCP_INSTRUCTIONS, parseToolScope, DEFAULT_TOOL_GROUPS } from './tools.mjs';
 import { mcpCtx, connectedProviders } from './client.mjs';
 
 // Mount the remote connector onto the Express app. No-op unless explicitly enabled + auth-backed.
@@ -234,8 +234,11 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
   // `?tools=research,create` narrows the roster this connection advertises (see registerTools). Read here rather
   // than inside registerTools so BOTH the anonymous discovery handshake and a real session honour the same query,
   // and so an unknown group is refused at the door with the valid list instead of silently serving every group.
-  // ABSENT, the DEFAULT is every group except `ads` and `analytics` (OPT_IN_TOOL_GROUPS) — together ~254k of the
-  // ~365k full roster, so an eagerly-loading client gets ~112k. `?tools=all` restores the full roster.
+  // ABSENT, an AUTHENTICATED session resolves to the CORE-FIRST default (see defaultToolGroups in tools.mjs): the
+  // core tools plus a few that make the connection drivable, with everything else held out of the LIST on size and
+  // reachable through find_tools + call_tool. `?tools=all` restores the full roster for one connection and
+  // `MCP_CORE_FIRST=1` opts this process into the small core-first roster; the default is the full roster. The anonymous discovery path above is
+  // deliberately NOT core-first — see the comment on its registerTools call.
   // The scope fixed here is the STARTING roster, not a cage: `enable_tools` widens it mid-session and the SDK
   // notifies the client. That is deliberate — the old comment's "tools/list must not change under a live client"
   // was the right instinct for a scope the SERVER changes silently, and the wrong one for a change the CLIENT
@@ -260,7 +263,14 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
     // scope to and nothing honest to read — and a registry crawler or an agent deciding whether to connect MUST
     // see the real catalog, not a zero-connector one. registerTools treats an absent `connectors` exactly like a
     // failed read: full roster. Do not "fix" this by reading the workspace off the request; it is forgeable.
-    registerTools(server, { only: scope?.groups, directory: scope?.directory || false, widgetHost: isWidgetHost(clientInfoOf(req.body), req) , hosted: true }); // metadata only — tools/list never invokes a handler, and tools/call can't reach here
+    // ── AND THE ANONYMOUS ROSTER IS NOT CORE-FIRST, DELIBERATELY (2026-09-17) ──────────────────────────────────
+    // An authenticated session pays for its roster on every turn, which is the whole argument for core-first. This
+    // request pays for nothing and is nobody's turn: it is a registry crawler (registry.modelcontextprotocol.io,
+    // Glama, Smithery), OpenAI's own submission scanner, or an agent deciding whether to connect at all — and for
+    // every one of those the roster IS the product description. Serving them the core set would publish Hermoso as
+    // a 22-tool server on ~430 directory pages. So an UNSTATED scope here resolves to the full pre-core-first
+    // default rather than to the session default; an explicit `?tools=` still wins, exactly as it does below.
+    registerTools(server, { only: scope?.groups || [...DEFAULT_TOOL_GROUPS], directory: scope?.directory || false, widgetHost: isWidgetHost(clientInfoOf(req.body), req) , hosted: true }); // metadata only — tools/list never invokes a handler, and tools/call can't reach here
     if (typeof onAnonDiscovery === 'function' && methodsOf(req.body).includes('tools/list')) { try { onAnonDiscovery({ client: clientInfoOf(req.body), ua: String(req.headers['user-agent'] || '').slice(0, 120), src: srcOf(req) }); } catch {} }
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
     res.on('close', () => { try { transport.close(); server.close(); } catch {} });

package/mcp/tool-cost.mjs

@@ -0,0 +1,103 @@
+// ── WHAT A TOOL COSTS, AS find_tools REPORTS IT (2026-09-17) ───────────────────────────────────────────────────
+//
+// An agent choosing between two tools should be able to see the price before it calls one, the way it can see the
+// parameters. Monid's `inspect` does exactly this and their docs tell the agent to read the live price rather than
+// trust the doc — "it is the source of truth, not this document". Ours has to hold the same line.
+//
+// THERE IS NO PER-TOOL PRICE TABLE IN THIS PRODUCT, AND INVENTING ONE WOULD BE THE WRONG FIX. Credits are spent
+// per MODEL RUN, and what a run costs depends on the model, the resolution and the length — which is why the only
+// exact numbers live in the live catalog `/api/generate/status` serves and `hermoso_capabilities` prints. A number
+// written into this file would be a second, stale answer to a question the server already answers correctly
+// ([[unsourced-capability-comments]]). So: THIS MODULE CLASSIFIES, IT NEVER PRICES. Every digit find_tools shows
+// comes from that same live catalog, fetched once per process and quoted as a range; when the catalog has not been
+// read the row says the class and no number, which is honest rather than guessed.
+//
+// THE CLASSIFICATION IS THE SERVER'S OWN ONE SENTENCE, MAPPED ONTO THE GROUP MARKERS. `COST_MODEL_SENTENCE` in
+// server.js — the one copy every surface prints — says credits are spent on exactly two things, running an AI
+// model and Ad Spy research, with X as the single per-call exception, and that everything else (publishing,
+// scheduling, campaign management, analytics, comments, DMs, connectors, brands, team) is free on every plan.
+// Those two things are the `create` and `research` groups, which each tool declares by the `server.group()` marker
+// it was written under and which `tools/tool-group-truth-check.mjs` already holds true. So the rule derives from
+// two things that are independently maintained, not from a hand-list of 841 names:
+//
+//     group `create`   → 'model'     (it runs a model — image, video, voice, text, planning, post-production)
+//     group `research` → 'research'  (Ad Spy: our own research key pays the vendor)
+//     provider `x`     → 'percall'   (X bills us per API request; the documented exception)
+//     everything else  → 'free'
+//
+// THE TWO EXCEPTION SETS BELOW ARE THE READS THAT LIVE INSIDE THOSE GROUPS — a Library listing or a job poll is
+// filed under `create` because that is the section it was written in, and it spends nothing. They are the only
+// hand-maintained part, they are small, and `tools/tool-cost-health-check.mjs` cross-examines them against each
+// tool's OWN description: a tool whose description says "0 credits" or "Free, read-only" may not be classed paid,
+// and one whose description states its OWN price ("Spends credits" at a sentence start, or a "Paid (…)" clause)
+// may not be classed free. That makes the two statements check each other instead of drifting apart. The claim has
+// to be about THIS tool: three genuinely free tools merely CONTAIN the words — hermoso_credits prints the rule
+// itself, list_creators explains that generating a fresh face costs credits, and set_competitor_watch says the
+// weekly RUN spends — so a loose match would have mis-flagged all three.
+//
+// PURE, NO IMPORTS, so the checks RUN these functions and so the cli twin — which ships without lib/ and without a
+// repo around it — resolves the same specifier the server copy does.
+
+// Reads inside `create`. Each is a lookup or a poll: it returns something we already hold and runs no model.
+export const CREATE_FREE_READS = Object.freeze([
+  'get_job', 'list_library', 'fetch_asset', 'list_skills', 'get_skill',
+  'list_product_photos', 'fetch_app_screens', 'list_hooks',
+  'list_meta_posts', 'list_published_posts', 'post_performance', 'diagnose_posts', 'backfill_posts',
+]);
+// Reads inside `research`. `find_competitors` says "0 credits" in its own description (it is the discovery model,
+// billed to us, not a paid ad-data call); the watch tools only write and read a stored preference — the weekly
+// run that spends is a job, not this call.
+export const RESEARCH_FREE_READS = Object.freeze(['find_competitors', 'list_watch_findings', 'set_competitor_watch']);
+
+export const COST_CLASSES = Object.freeze(['free', 'model', 'research', 'percall']);
+
+/**
+ * The cost CLASS of one tool. `group` is the registry's own marker for it; `provider` is toolProvider(name).
+ * Unknown/unmapped ⇒ 'free', which matches the server's sentence: everything that is not a model run or Ad Spy
+ * research is free on every plan.
+ */
+export function toolCostClass(name, group, provider = null) {
+  const n = String(name || '');
+  if (provider === 'x') return 'percall';                     // X charges per API request — the one exception
+  if (group === 'create') return CREATE_FREE_READS.includes(n) ? 'free' : 'model';
+  if (group === 'research') return RESEARCH_FREE_READS.includes(n) ? 'free' : 'research';
+  return 'free';
+}
+
+// The sentence each class prints. NO DIGITS HERE — see the header. `range` is filled in by the caller from the
+// live catalog when it has read one.
+export function costLabel(cls, range = '') {
+  if (cls === 'percall') return 'a few credits per call (X charges per API request)';
+  if (cls === 'research') return 'credits (Ad Spy research)';
+  if (cls === 'model') return range ? `credits — ${range}` : 'credits (runs a model; hermoso_capabilities has the exact per-model figure)';
+  return 'free';
+}
+
+/**
+ * The one range find_tools quotes, built from the SAME payload hermoso_capabilities prints
+ * (`GET /api/generate/status`). Returns '' when the catalog has not been read — an absent number is never
+ * replaced by a guessed one ([[failed-read-is-not-empty]]).
+ *
+ * `kind` picks which catalog to read: a video tool is priced by the video models, an image tool by the image ones.
+ * Anything else gets the whole span, which is the honest answer for a tool that could route to either.
+ */
+export function creditRangeFrom(status, kind = 'any') {
+  if (!status || typeof status !== 'object') return '';
+  const nums = [];
+  const eat = (rows) => { for (const m of rows || []) {
+    if (typeof m?.credits === 'number') nums.push(m.credits);
+    else if (m?.credits && typeof m.credits === 'object') for (const v of Object.values(m.credits)) if (typeof v === 'number') nums.push(v);
+    if (m?.creditsBySize) for (const v of Object.values(m.creditsBySize)) if (typeof v === 'number') nums.push(v);
+  } };
+  if (kind === 'image' || kind === 'any') eat(status.options?.image?.models);
+  if (kind === 'video' || kind === 'any') eat(status.options?.video?.models);
+  const ok = nums.filter((n) => Number.isFinite(n) && n > 0);
+  if (!ok.length) return '';
+  const lo = Math.min(...ok), hi = Math.max(...ok);
+  return lo === hi ? `${lo} credits` : `${lo}-${hi} credits by model/length/resolution`;
+}
+
+// Which catalog a generation tool is priced from. Deliberately tiny and name-shaped: a tool it does not recognise
+// gets the class label with no number, which is the safe direction.
+export const costKindOf = (name) => (/video|avatar|sizzle|explainer|stitch|reframe|upscale|recast|dub|clip|subtitle|beat|finish|multiply|motion/i.test(String(name || '')) ? 'video'
+  : /image|thumbnail|photo|static|render_ad|template/i.test(String(name || '')) ? 'image' : 'any');

package/mcp/tool-health.mjs

@@ -0,0 +1,103 @@
+// ── IS THIS TOOL WORKING RIGHT NOW? (2026-09-17) ───────────────────────────────────────────────────────────────
+//
+// Monid's discover puts a health status and a median run time on every row, and hides an endpoint that is in
+// outage. That is worth copying: an agent picking between two tools should not have to discover by spending a
+// minute and a credit that one of them has failed its last nine calls.
+//
+// WHERE THE NUMBERS COME FROM, AND WHY NOT FROM THE ERROR LEDGER ALONE. The error ledger is the right instinct —
+// it is our record of what users hit — but it records only FAILURES, with no successes and no durations, so a
+// failure RATE and a typical duration cannot be computed from it at all. A ledger read is also an HTTP round trip
+// per find_tools call, which is exactly the cost this feature must not add. So health is measured where the calls
+// already pass: `wrap()` in mcp/tools.mjs, the one seam every tool handler returns through, and the same seam that
+// FEEDS the error ledger via reportToolError. Same signal, in process, free, and it carries the two things the
+// ledger cannot: the successes and the clock.
+//
+// WHAT IT IS AND IS NOT. It is THIS PROCESS's recent experience, which on the hosted server is every caller's
+// calls and on stdio is this session's. It is therefore evidence, not a fleet statistic — and the difference is
+// stated in the wording find_tools prints. NO RECENT CALLS IS SAID AS SUCH, never rendered as healthy
+// ([[failed-read-is-not-empty]]): "we have not seen this tool run lately" and "this tool works" are different
+// claims and the second one is the dangerous one to guess.
+//
+// BOUNDED BY CONSTRUCTION. At most HEALTH_TOOLS_MAX tools are tracked (LRU), at most HEALTH_SAMPLES_MAX outcomes
+// each, and anything older than HEALTH_WINDOW_MS is dropped on read. Worst case is a few tens of kilobytes, on a
+// process that already holds a 350K-token tool canon. No timer, no I/O, no allocation on the read path beyond the
+// window filter — a find_tools call that scans 841 rows must stay cheap.
+//
+// PURE-ISH AND DEPENDENCY-FREE: one module-level Map and functions over it, so the check RUNS this rather than
+// reading it, and so the cli twin (no lib/, no repo) resolves the same specifier as the server copy.
+
+export const HEALTH_WINDOW_MS = 60 * 60 * 1000;   // an hour: long enough to see a pattern, short enough to be "now"
+export const HEALTH_SAMPLES_MAX = 20;             // per tool
+export const HEALTH_TOOLS_MAX = 400;              // distinct tools tracked, LRU by last write
+export const HEALTH_FAILING_RATE = 0.6;           // "nearly all failing" — ranked last, and said out loud
+export const HEALTH_DEGRADED_RATE = 0.25;
+export const HEALTH_MIN_CALLS = 3;                // below this, one bad call is noise, not a verdict
+
+const _tools = new Map(); // name -> [{ at, ok, ms }]  (insertion-ordered ⇒ LRU)
+
+/** Record one finished tool call. Never throws — a health write may not break a tool's own answer. */
+export function recordToolOutcome(name, opts) {
+  try {
+    // DESTRUCTURED INSIDE THE try, NOT IN THE PARAMETER LIST. A default only fires on `undefined`, so
+    // `recordToolOutcome(name, null)` threw a TypeError BEFORE the try could catch it — and this function is
+    // called from inside `wrap()`, where a throw would replace a tool's real answer with a health-bookkeeping
+    // error. Measured: the check's "a bad write never throws" assertion went red on exactly that call.
+    const { ok, ms = 0, now = Date.now() } = opts || {};
+    const n = String(name || '');
+    if (!n) return;
+    let arr = _tools.get(n);
+    if (arr) _tools.delete(n); else arr = [];       // re-insert ⇒ this tool is the most recently used
+    arr.push({ at: now, ok: !!ok, ms: Number(ms) || 0 });
+    if (arr.length > HEALTH_SAMPLES_MAX) arr.splice(0, arr.length - HEALTH_SAMPLES_MAX);
+    _tools.set(n, arr);
+    while (_tools.size > HEALTH_TOOLS_MAX) _tools.delete(_tools.keys().next().value);
+  } catch { /* health is never load-bearing */ }
+}
+
+/** Test seam only — the checks need a clean slate between sections. */
+export function _resetToolHealth() { _tools.clear(); }
+export function _healthSize() { return _tools.size; }
+
+/**
+ * The verdict for one tool. Shapes:
+ *   { state: 'unseen' }                                    — nothing recent; SAY SO, never "healthy"
+ *   { state: 'healthy'|'degraded'|'failing', calls, failures, failRate, medianMs }
+ */
+export function toolHealth(name, now = Date.now()) {
+  const arr = (_tools.get(String(name || '')) || []).filter((s) => now - s.at <= HEALTH_WINDOW_MS);
+  if (!arr.length) return { state: 'unseen', calls: 0 };
+  const calls = arr.length;
+  const failures = arr.filter((s) => !s.ok).length;
+  const failRate = failures / calls;
+  const times = arr.map((s) => s.ms).filter((m) => m > 0).sort((a, b) => a - b);
+  const medianMs = times.length ? times[Math.floor(times.length / 2)] : 0;
+  // A SINGLE FAILED CALL IS NOT A VERDICT. Below HEALTH_MIN_CALLS the honest answer is that we have seen it run,
+  // with however many failures, and nothing stronger — so it stays 'healthy' for ranking and the counts are
+  // printed beside it. Above it, the rate decides.
+  const state = calls >= HEALTH_MIN_CALLS && failRate >= HEALTH_FAILING_RATE ? 'failing'
+    : calls >= HEALTH_MIN_CALLS && failRate >= HEALTH_DEGRADED_RATE ? 'degraded'
+      : 'healthy';
+  return { state, calls, failures, failRate, medianMs };
+}
+
+/** One short phrase for a find_tools row. `unseen` says it is unseen; it never reads as an endorsement. */
+export function healthLabel(h) {
+  if (!h || h.state === 'unseen') return 'no recent calls';
+  const t = h.medianMs ? `, ~${h.medianMs >= 1000 ? `${(h.medianMs / 1000).toFixed(1)}s` : `${h.medianMs}ms`} typical` : '';
+  if (h.state === 'healthy') return `${h.calls}/${h.calls - h.failures} recent calls ok${t}`.replace(/^(\d+)\/(\d+)/, '$2 of $1');
+  return `${h.state.toUpperCase()}: ${h.failures} of ${h.calls} recent calls failed${t}`;
+}
+
+/**
+ * The rank penalty a row carries. 0 = nothing wrong. Higher sorts LATER.
+ * A tool that cannot run at all (a connector this workspace has not made) and a tool that is failing its calls are
+ * both worse picks than a working one — but NEITHER IS HIDDEN, because "we have no such tool" is the single most
+ * expensive wrong answer this product can give ([[prompt-rosters-go-stale]]).
+ */
+export function healthPenalty(h, hold = null) {
+  let p = 0;
+  if (hold) p += 2;                                  // not connected / host policy / directory cage
+  if (h?.state === 'failing') p += 2;
+  else if (h?.state === 'degraded') p += 1;
+  return p;
+}

package/mcp/tool-hints.mjs

@@ -0,0 +1,57 @@
+// ── HINTS: THE NEXT STEP, NAMED (2026-09-17) ───────────────────────────────────────────────────────────────────
+//
+// This product already tells an agent what to do next, constantly and well — "connect it under Settings ▸
+// Connectors, then call again", "run buy_credits to top up", "call find_tools then call_tool", "reconnect with
+// ?tools=all". Every one of those is a SENTENCE inside a wall of other sentences, so reading it is a parsing job
+// an agent may or may not do. Monid rides a `Hints` block on its responses — server-suggested next command,
+// related endpoints, caveats — and tells the agent to prefer hints over guessing. That is the cheap half we were
+// missing: the advice exists, it just was not addressable.
+//
+// SO THIS ADDS A FIELD AND REMOVES NOTHING. The prose stays exactly as it was, because it is what a model
+// actually reads and because half our hosts show only the text. The hint is the same advice, keyed, for a client
+// or an agent that wants to branch on it rather than match a string.
+//
+// WHERE IT RIDES. `_meta`, which the MCP spec makes the sanctioned extension point on any result ("any result MAY
+// carry it"), so every client that does not know the key ignores it. This file already puts the structured error
+// marker there for the same reason. NOT `structuredContent`: a tool declares an outputSchema and a caller may
+// validate against it, and a next-step suggestion is not part of any tool's output contract.
+//
+// THE SHAPE IS {do, why} AND NOTHING ELSE. `do` is the action, written as the call to make where there is one, so
+// it can be executed without interpretation; `why` is the reason, so an agent can decide rather than obey. No
+// severity, no codes, no nesting — a richer shape would need a schema, a version and a migration, and the whole
+// value here is that it is free to add wherever we already write the sentence.
+//
+// PURE, NO IMPORTS — same twin-safety rule as roster-scope.mjs and well-formed.mjs.
+
+export const HINTS_KEY = 'hermoso.ai/hints';
+export const HINTS_MAX = 4;          // a list nobody reads is not a hint; keep it to the next step, not a plan
+export const HINT_DO_MAX = 200, HINT_WHY_MAX = 300;
+
+/** Normalise a hint list. Drops anything without a `do`, trims, caps. Never throws. */
+export function normalizeHints(hints) {
+  try {
+    const out = [];
+    for (const h of Array.isArray(hints) ? hints : []) {
+      const doIt = String(h?.do ?? '').replace(/\s+/g, ' ').trim().slice(0, HINT_DO_MAX);
+      if (!doIt) continue;                                   // a hint with no action is noise
+      out.push({ do: doIt, why: String(h?.why ?? '').replace(/\s+/g, ' ').trim().slice(0, HINT_WHY_MAX) });
+      if (out.length >= HINTS_MAX) break;
+    }
+    return out;
+  } catch { return []; }
+}
+
+/**
+ * Attach hints to a tool result without touching anything already on it — including an existing `_meta`, which
+ * carries the structured error marker on every failure and must survive.
+ * A result with no usable hints comes back BY REFERENCE, unchanged: adding an empty key to every reply in the
+ * product would be pure weight.
+ */
+export function withHints(result, hints) {
+  const list = normalizeHints(hints);
+  if (!list.length || !result || typeof result !== 'object') return result;
+  return { ...result, _meta: { ...(result._meta || {}), [HINTS_KEY]: list } };
+}
+
+/** Read them back — the shape a check and a client both use, so neither has to know the key. */
+export const hintsOf = (result) => (result && result._meta && Array.isArray(result._meta[HINTS_KEY])) ? result._meta[HINTS_KEY] : [];