@sentientui/mcp 0.19.0 → 0.20.0

package/dist/index.cjs

@@ -25,9 +25,10 @@ var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
 // src/api-client.ts
 var ApiError = class extends Error {
-  constructor(status, message) {
+  constructor(status, message, detail) {
     super(message);
     this.status = status;
+    this.detail = detail;
     this.name = "ApiError";
   }
 };
@@ -44,8 +45,14 @@ var ApiClient = class {
   async post(path, body) {
     return this.request("POST", path, body);
   }
+  async patch(path, body) {
+    return this.request("PATCH", path, body);
+  }
+  async delete(path, body) {
+    return this.request("DELETE", path, body);
+  }
   async request(method, path, body, isRetry = false) {
-    var _a2, _b;
+    var _a2, _b, _c;
     const res = await fetch(`${this.baseUrl}/v1/mgmt${path}`, {
       method,
       headers: __spreadValues({
@@ -62,7 +69,9 @@ var ApiClient = class {
         return this.request(method, path, body, true);
       }
     }
-    throw new ApiError(res.status, String((_b = (_a2 = errBody.error) != null ? _a2 : errBody.message) != null ? _b : res.statusText));
+    const code = String((_b = (_a2 = errBody.error) != null ? _a2 : errBody.message) != null ? _b : res.statusText);
+    const human = (_c = errBody.message) != null ? _c : errBody.reason;
+    throw new ApiError(res.status, code, typeof human === "string" && human !== code ? human : void 0);
   }
 };
 
@@ -141,7 +150,7 @@ function localDate(iso, timeZone) {
 }
 function apiErrorGuidance(err, extra) {
   if (extra && Object.prototype.hasOwnProperty.call(extra, err.message)) {
-    return extra[err.message];
+    return extra[err.message] + detailSuffix(err);
   }
   switch (err.message) {
     case "insufficient_scope":
@@ -150,6 +159,15 @@ function apiErrorGuidance(err, extra) {
       return "Demo mode is read-only. Create a SentientUI account and sign in (or use a project server key) to make changes.";
     case "insufficient_role":
       return "Your account role does not permit this action \u2014 it needs the account owner or an admin.";
+    // The mgmt write routes answer a viewer with `role_required` (and origins
+    // with `not_authorized`), not `insufficient_role` — so every role refusal
+    // fell through to the generic 403 "check your key has access" advice and
+    // sent the agent re-authenticating for a permission it already had wrong.
+    case "role_required":
+    case "not_authorized":
+      return `Your role on this project cannot make this change \u2014 it needs an editor or admin.${detailSuffix(err)}`;
+    case "ai_unavailable":
+      return "AI generation is unavailable on the SentientUI server right now (no model is configured). Nothing was queued \u2014 retry later.";
     default:
       break;
   }
@@ -181,10 +199,25 @@ function apiErrorGuidance(err, extra) {
     return `This feature requires a higher plan (${err.message}). Upgrade your SentientUI plan, then try again.`;
   }
   if (err.status === 403) {
-    return `Access denied (${err.message}). Check that your key or login has access to this project.`;
+    return `Access denied (${err.message}). Check that your key or login has access to this project.${detailSuffix(err)}`;
+  }
+  if (err.status === 404) {
+    return `Not found (${err.message}). The project, component, variant, goal or cell does not exist, or this credential cannot see it (an sk_ server key sees only its own project). Re-read the ids with list_projects, list_components, list_goals or get_cell_matrix and retry with an exact id.` + detailSuffix(err);
+  }
+  if (err.status === 400) {
+    return `The API rejected the arguments (${err.message}).${detailSuffix(err)} Correct the input and retry \u2014 repeating the same call will fail the same way.`;
+  }
+  if (err.status === 409) {
+    return `Conflict (${err.message}): the target's current state does not allow this.${detailSuffix(err)} Read its current state first, then retry the step that makes this valid.`;
+  }
+  if (err.status === 502 || err.status === 503 || err.status === 504) {
+    return `SentientUI is temporarily unavailable (${err.status} ${err.message}). Nothing changed \u2014 wait a moment and retry.`;
   }
   return null;
 }
+function detailSuffix(err) {
+  return err.detail ? ` Server says: ${untrusted(err.detail, 300)}` : "";
+}
 async function settled(p) {
   try {
     return { ok: true, value: await p };
@@ -297,6 +330,37 @@ function registerProjectTools(server, client) {
       };
     }, CREATE_PROJECT_GUIDANCE)
   );
+  server.registerTool(
+    "add_origin",
+    {
+      title: "Add allowed origin",
+      description: "Allow-list a site origin (scheme + host, e.g. https://www.example.com) so the SDK's events from it are accepted. Idempotent: an origin already on the list is left as is. Removing an origin is dashboard-only. Needs an editor/admin login or the project's sk_ server key. Confirm the exact origin with the user first \u2014 an allowed origin can send events into this project.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        origin: import_zod2.z.string().min(1).max(500).describe("The site origin, e.g. https://www.example.com (a pasted page URL is reduced to its origin)")
+      },
+      outputSchema: {
+        origins: import_zod2.z.array(import_zod2.z.string()).describe("The full allow-list after the change")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, origin }) => {
+      var _a2;
+      const id = encodeURIComponent(projectId);
+      const res = await client.post(`/projects/${id}/origins`, { origin });
+      const origins = (_a2 = res.origins) != null ? _a2 : [];
+      return {
+        content: [{
+          type: "text",
+          text: `Allowed origins: ${origins.map((o) => untrusted(o)).join(", ") || "(none)"}. Events from these origins are accepted (other API instances pick the change up within ~30 seconds, when their key cache expires).`
+        }],
+        structuredContent: { origins }
+      };
+    }, {
+      invalid_origin: "That is not a usable origin. Pass a scheme and host, e.g. https://www.example.com.",
+      origin_required: "An origin is required, e.g. https://www.example.com."
+    })
+  );
   server.registerTool(
     "list_projects",
     {
@@ -341,13 +405,16 @@ function registerProjectTools(server, client) {
     "get_project_stats",
     {
       title: "Project health stats",
-      description: "Get health stats for a project: event volume, session count, agent calls, and status.",
+      description: "Get ingestion health for a project: status, events and sessions in the last 24 hours, the time of the last event, and the all-time count of calls to the SentientUI agent API (/v1/agent) \u2014 NOT MCP tool calls.",
       inputSchema: { projectId: projectIdSchema },
       outputSchema: {
         status: import_zod2.z.string().describe("Overall project health status"),
         events24h: import_zod2.z.number().describe("Events in the last 24 hours"),
         sessions24h: import_zod2.z.number().describe("Sessions in the last 24 hours"),
-        agentCalls: import_zod2.z.number().describe("Total agent (MCP/API) calls"),
+        // Was "Total agent (MCP/API) calls" — but the count comes from
+        // agent_events, which only the /v1/agent endpoint writes. MCP tool calls
+        // are never in it, so an agent read its own activity as missing.
+        agentCalls: import_zod2.z.number().describe("All-time calls to the /v1/agent agent API (not MCP tool calls)"),
         lastEventAt: import_zod2.z.string().nullable().describe("ISO timestamp of the last event, or null")
       },
       annotations: {
@@ -364,7 +431,7 @@ function registerProjectTools(server, client) {
         `Status: ${stats.status}`,
         `Events (24h): ${stats.events24h}`,
         `Sessions (24h): ${stats.sessions24h}`,
-        `Agent calls (total): ${stats.agentCalls}`,
+        `Agent API calls (/v1/agent, all-time): ${stats.agentCalls}`,
         `Last event: ${(_a2 = stats.lastEventAt) != null ? _a2 : "never"}`
       ].join("\n");
       return {
@@ -1111,7 +1178,10 @@ function registerPersonaTools(server, client) {
     "get_persona_breakdown",
     {
       title: "Persona breakdown",
-      description: "Get the distribution of visitor persona clusters with session counts and reliability scores." + UNTRUSTED_FIELDS_NOTE,
+      // Takes no range/from/to on purpose: the API computes it over every
+      // retained session and has no window. Saying so stops an agent from
+      // reading it beside a 7d get_variant_performance as the same period.
+      description: "Get the distribution of visitor persona clusters with session counts and reliability scores, over ALL retained human sessions (not windowed \u2014 this has no range input, unlike the conversion tools)." + UNTRUSTED_FIELDS_NOTE,
       inputSchema: { projectId: projectIdSchema },
       _meta: uiMeta("persona-breakdown"),
       outputSchema: {
@@ -1172,8 +1242,13 @@ function registerGoalTools(server, client) {
   server.registerTool(
     "get_goal_funnel",
     {
-      title: "Goal funnel",
-      description: "Get goal hit counts and unique-session conversion rates for a window (default: last 30 calendar days), plus a per-variant breakdown. NOTE: the per-variant completionRate values are ALL-TIME (bounded only by plan retention), NOT windowed \u2014 a variant completion rate needs the full assignment history as its denominator, so it does not change when you narrow `range`, and retired components keep appearing in it. Only hits/uniqueSessions/conversionRate/revenue respect the window. This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report." + UNTRUSTED_FIELDS_NOTE,
+      // Named get_goal_funnel for compatibility (renaming a published tool
+      // breaks every saved prompt and host allow-list), but it is NOT a funnel:
+      // agents asked it for step drop-off and reported per-goal rates as funnel
+      // stages. The title and the first words of the description now say what
+      // it is, and point to the real funnel tool.
+      title: "Goal conversions (per goal \u2014 not a step funnel)",
+      description: "Per-goal conversion summary \u2014 NOT a step funnel (for step-by-step drop-off use list_funnels + get_funnel_report). Gets goal hit counts and unique-session conversion rates for a window (default: last 30 calendar days), plus a per-variant breakdown. NOTE: the per-variant completionRate values are ALL-TIME (bounded only by plan retention), NOT windowed \u2014 a variant completion rate needs the full assignment history as its denominator, so it does not change when you narrow `range`, and retired components keep appearing in it. Only hits/uniqueSessions/conversionRate/revenue respect the window. Per-variant rates are descriptive, not joined to the evidence verdicts \u2014 for whether an arm is ahead, use get_variant_performance." + UNTRUSTED_FIELDS_NOTE,
       inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
       _meta: uiMeta("goal-funnel"),
       outputSchema: {
@@ -1563,7 +1638,9 @@ function registerLayoutTools(server, client) {
     "get_layout_stats",
     {
       title: "Layout stats",
-      description: "Get per-persona section layout rankings and bandit reward weights." + UNTRUSTED_FIELDS_NOTE,
+      // No window by design: these are the bandit's cumulative pulls and reward,
+      // the state serving reads — not a report over a period.
+      description: "Get per-persona section layout rankings with bandit pulls and average reward \u2014 the cumulative learning state serving uses (not windowed; there is no range input). avgReward is a reward signal, not a conversion rate." + UNTRUSTED_FIELDS_NOTE,
       inputSchema: { projectId: projectIdSchema },
       _meta: uiMeta("layout-stats"),
       outputSchema: {
@@ -1615,7 +1692,7 @@ function registerVariantWriteTools(server, client) {
     "create_variant",
     {
       title: "Create managed variant",
-      description: "Create a NO-CODE managed text variant for a component (content stored in SentientUI, rendered by <AdaptiveText>). Use this ONLY for text-only variants the user wants without a code change. For variants that will live in the codebase (full components \u2014 copy, markup, styling), use get_variant_brief and write the variant in code instead; those auto-register on deploy and do not need create_variant. Requires a paid plan (server keys are Starter+; anonymous demo tokens are read-only).",
+      description: "Create a NO-CODE managed text variant for a component (content stored in SentientUI, rendered by <AdaptiveText>). Use this ONLY for text-only variants the user wants without a code change. For variants that will live in the codebase (full components \u2014 copy, markup, styling), use get_variant_brief and write the variant in code instead; those auto-register on deploy and do not need create_variant. Works on every plan with an editor/admin login or the project's sk_ server key (anonymous demo tokens are read-only). The variant is created as a DRAFT \u2014 it serves no traffic until activated with update_variant (status 'active'). Confirm the text with the user before calling.",
       inputSchema: {
         projectId: projectIdSchema,
         componentId: import_zod10.z.string().min(1).max(200).describe("The component ID to add a variant to"),
@@ -1649,7 +1726,7 @@ function registerVariantWriteTools(server, client) {
       return {
         content: [{
           type: "text",
-          text: `Managed text variant created: ${result.variantId} ("${result.displayName}") for component ${componentId}${contentNote}. It is in draft state \u2014 activate it from the dashboard. Reminder: this is a no-code managed variant; for code-native variants, edit the code instead (see get_variant_brief).`
+          text: `Managed text variant created: ${result.variantId} ("${result.displayName}") for component ${componentId}${contentNote}. It is a draft and serves no traffic yet \u2014 after the user confirms, activate it with update_variant (status 'active'), or delete it with delete_variant_draft. Reminder: this is a no-code managed variant; for code-native variants, edit the code instead (see get_variant_brief).`
         }],
         structuredContent: {
           variantId: result.variantId,
@@ -1665,20 +1742,24 @@ function registerVariantWriteTools(server, client) {
     "pause_variant",
     {
       title: "Pause variant",
-      description: "Pause a variant, stopping traffic from being assigned to it.",
+      description: "Pause a variant: no new traffic is assigned to it until it is resumed. This changes what live visitors see, so CONFIRM with the user before calling. Undo with resume_variant.",
       inputSchema: {
         projectId: projectIdSchema,
-        componentId: import_zod10.z.string().describe("The component ID"),
-        variantId: import_zod10.z.string().describe("The variant ID to pause")
+        componentId: import_zod10.z.string().min(1).max(200).describe("The component ID"),
+        variantId: import_zod10.z.string().min(1).max(200).describe("The variant ID to pause")
       },
       outputSchema: {
         variantId: import_zod10.z.string(),
         componentId: import_zod10.z.string(),
         paused: import_zod10.z.literal(true).describe("The variant is now paused")
       },
+      // destructiveHint was false, so hosts that gate destructive tools behind a
+      // confirmation ran this without asking — yet it pulls a live arm out of
+      // serving for every visitor. It is reversible (resume_variant), but the
+      // hint is about the change to the environment, not about undo.
       annotations: {
         readOnlyHint: false,
-        destructiveHint: false,
+        destructiveHint: true,
         idempotentHint: true,
         openWorldHint: false
       }
@@ -1689,17 +1770,194 @@ function registerVariantWriteTools(server, client) {
       return {
         content: [{
           type: "text",
-          text: `Variant ${variantId} in component ${componentId} has been paused. No new traffic will be assigned to it.`
+          text: `Variant ${untrusted(variantId)} in component ${untrusted(componentId)} is paused. No new traffic will be assigned to it. Undo with resume_variant.`
         }],
         structuredContent: { variantId, componentId, paused: true }
       };
     })
   );
+  server.registerTool(
+    "resume_variant",
+    {
+      title: "Resume variant",
+      description: "Resume a paused variant so it is assigned traffic again \u2014 works for a manual pause (pause_variant) and for a guardrail auto-pause (see list_guardrail_events). Resuming a guardrail-paused arm puts a variant the guardrail judged harmful back in front of visitors, so CONFIRM with the user first.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        componentId: import_zod10.z.string().min(1).max(200).describe("The component ID"),
+        variantId: import_zod10.z.string().min(1).max(200).describe("The paused variant ID to resume")
+      },
+      outputSchema: {
+        variantId: import_zod10.z.string(),
+        componentId: import_zod10.z.string(),
+        paused: import_zod10.z.literal(false).describe("The variant is no longer paused")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, componentId, variantId }) => {
+      const id = encodeURIComponent(projectId);
+      await client.post(`/projects/${id}/guardrails/${encodeURIComponent(componentId)}/unpause`, {
+        variantIds: [variantId]
+      });
+      return {
+        content: [{
+          type: "text",
+          text: `Variant ${untrusted(variantId)} in component ${untrusted(componentId)} is resumed and will be assigned traffic again.`
+        }],
+        structuredContent: { variantId, componentId, paused: false }
+      };
+    })
+  );
+  server.registerTool(
+    "update_variant",
+    {
+      title: "Update managed variant",
+      description: "Edit a NO-CODE managed variant (one created with create_variant or in the dashboard): its display name, its text, or its status \u2014 'active' starts serving it to visitors, 'draft' takes it back out of rotation. Code-native variants cannot be edited here (change the code). Overwriting text or activating changes what live visitors see, so CONFIRM with the user first. Omit a field to leave it unchanged.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        componentId: import_zod10.z.string().min(1).max(200).describe("The component ID"),
+        variantId: import_zod10.z.string().min(1).max(200).describe("The managed variant ID (dm_\u2026)"),
+        displayName: import_zod10.z.string().min(1).max(200).optional().describe("New display name"),
+        content: import_zod10.z.string().max(1e4).optional().describe("New text content (replaces the old text)"),
+        status: import_zod10.z.enum(["draft", "active"]).optional().describe("'active' serves it; 'draft' stops serving it")
+      },
+      outputSchema: {
+        variantId: import_zod10.z.string(),
+        componentId: import_zod10.z.string(),
+        changed: import_zod10.z.array(import_zod10.z.string()).describe("Fields that were sent for update"),
+        status: import_zod10.z.enum(["draft", "active"]).nullable().describe("The new status, or null when unchanged")
+      },
+      // Destructive: the previous text is overwritten, not versioned.
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, componentId, variantId, displayName, content, status }) => {
+      const changed = [
+        ...displayName !== void 0 ? ["displayName"] : [],
+        ...content !== void 0 ? ["content"] : [],
+        ...status !== void 0 ? ["status"] : []
+      ];
+      if (changed.length === 0) {
+        return {
+          content: [{ type: "text", text: "Nothing to update \u2014 pass displayName, content and/or status." }],
+          isError: true
+        };
+      }
+      const id = encodeURIComponent(projectId);
+      await client.patch(`/projects/${id}/variants`, { componentId, variantId, displayName, content, status });
+      const statusNote = status === "active" ? " It is now ACTIVE and will be assigned traffic." : status === "draft" ? " It is now a draft and no longer serves traffic." : "";
+      return {
+        content: [{
+          type: "text",
+          text: `Managed variant ${untrusted(variantId)} in component ${untrusted(componentId)} updated (${changed.join(", ")}).${statusNote}`
+        }],
+        structuredContent: { variantId, componentId, changed, status: status != null ? status : null }
+      };
+    }, {
+      // PATCH matches managed variants only, so a code-native id answers a
+      // bare not_found that read as "that variant does not exist".
+      not_found: "No MANAGED variant with that id exists in this component. Code-native variants (declared in <Adaptive variants>) are edited in the code, not here \u2014 check ids with list_components (a wrong projectId answers the same way)."
+    })
+  );
+  server.registerTool(
+    "delete_variant_draft",
+    {
+      title: "Delete draft variant",
+      description: "Permanently delete a managed variant that is still a DRAFT (never activated). Active variants cannot be deleted \u2014 pause or retire them instead. CONFIRM with the user first: this cannot be undone.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        componentId: import_zod10.z.string().min(1).max(200).describe("The component ID"),
+        variantId: import_zod10.z.string().min(1).max(200).describe("The draft managed variant ID (dm_\u2026)")
+      },
+      outputSchema: {
+        variantId: import_zod10.z.string(),
+        componentId: import_zod10.z.string(),
+        deleted: import_zod10.z.literal(true)
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, componentId, variantId }) => {
+      const id = encodeURIComponent(projectId);
+      await client.delete(`/projects/${id}/variants`, { componentId, variantId });
+      return {
+        content: [{
+          type: "text",
+          text: `Draft variant ${untrusted(variantId)} in component ${untrusted(componentId)} was deleted.`
+        }],
+        structuredContent: { variantId, componentId, deleted: true }
+      };
+    }, {
+      // The API's DELETE matches managed drafts only, so an active or
+      // code-native variant answers a bare not_found — say why.
+      not_found: "No managed DRAFT variant with that id exists in this component. Active and code-native variants cannot be deleted \u2014 use pause_variant or retire_variant instead (check ids with list_components; a wrong projectId answers the same way)."
+    })
+  );
+  server.registerTool(
+    "retire_variant",
+    {
+      title: "Retire variant",
+      description: "Retire (archive) an ACTIVE variant: it stops serving and moves to the archived list. Works for code-native variants that were removed from the code and linger. A promoted (pinned) variant must be unpromoted in the dashboard first. CONFIRM with the user first; undo with restore_variant.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        componentId: import_zod10.z.string().min(1).max(200).describe("The component ID"),
+        variantId: import_zod10.z.string().min(1).max(200).describe("The active variant ID to retire")
+      },
+      outputSchema: {
+        variantId: import_zod10.z.string(),
+        componentId: import_zod10.z.string(),
+        status: import_zod10.z.literal("retired")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, componentId, variantId }) => {
+      const id = encodeURIComponent(projectId);
+      await client.post(`/projects/${id}/variants/retire`, { componentId, variantId });
+      return {
+        content: [{
+          type: "text",
+          text: `Variant ${untrusted(variantId)} in component ${untrusted(componentId)} is retired and no longer serves. Undo with restore_variant.`
+        }],
+        structuredContent: { variantId, componentId, status: "retired" }
+      };
+    }, {
+      variant_promoted: "This variant is promoted (pinned as the winner), so it cannot be retired. Unpromote it in the dashboard first, then retry.",
+      not_found: "No ACTIVE variant with that id exists in this component (it may already be retired, or still a draft), or the projectId is wrong. Check ids with list_components."
+    })
+  );
+  server.registerTool(
+    "restore_variant",
+    {
+      title: "Restore variant",
+      description: "Bring a RETIRED variant back to active so it serves again. For a managed draft that was never activated use update_variant (status 'active') instead. Restoring does not clear a pause \u2014 use resume_variant for that. CONFIRM with the user first.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        componentId: import_zod10.z.string().min(1).max(200).describe("The component ID"),
+        variantId: import_zod10.z.string().min(1).max(200).describe("The retired variant ID to restore")
+      },
+      outputSchema: {
+        variantId: import_zod10.z.string(),
+        componentId: import_zod10.z.string(),
+        status: import_zod10.z.literal("active")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, componentId, variantId }) => {
+      const id = encodeURIComponent(projectId);
+      await client.post(`/projects/${id}/variants/restore`, { componentId, variantId });
+      return {
+        content: [{
+          type: "text",
+          text: `Variant ${untrusted(variantId)} in component ${untrusted(componentId)} is active again. If it was also paused, call resume_variant.`
+        }],
+        structuredContent: { variantId, componentId, status: "active" }
+      };
+    })
+  );
   server.registerTool(
     "refresh_insights",
     {
       title: "Refresh insights",
-      description: "Trigger fresh AI insight generation for a project. Returns immediately; use get_insights in ~15 seconds to see results.",
+      // The plan and role gates were undocumented, so agents on Free called it
+      // and got a bare 403 they could not explain to the user.
+      description: "Trigger fresh AI insight generation for a project (a paid model call). Needs the Starter plan or higher and an editor/admin role (anonymous demo tokens are read-only); advisor recommendations additionally need Growth or higher. Returns immediately; call get_insights in ~15 seconds to see results.",
       inputSchema: { projectId: projectIdSchema },
       outputSchema: {
         projectId: import_zod10.z.string(),
@@ -1751,11 +2009,21 @@ var BEST_PRACTICE_PRIORS = {
     "Make the CTA specific and benefit-led.",
     "Add a single strong proof point; remove competing distractions."
   ],
-  marketplace: [
-    "Reduce choice overload: guide the visitor to a clear next step.",
-    "Surface trust and liquidity signals (ratings, counts, recency).",
-    "Make the primary action on each listing obvious.",
-    "Reassure on safety/guarantees near the point of decision."
+  // Keys must be the project context types the API accepts (projects.ts
+  // VALID_CONTEXT_TYPES: saas | ecommerce | marketing | landing | internal).
+  // A `marketplace` key sat here that no project could ever have, while
+  // marketing and internal projects silently fell through to the generic list.
+  marketing: [
+    'Make the page answer "what is this and why should I care" in the first screen.',
+    "Give each section one job and one next step; cut competing CTAs.",
+    "Put the strongest proof (named customers, a hard number) near the primary CTA.",
+    "Match the copy to where the visitor came from (campaign, search intent)."
+  ],
+  internal: [
+    "Optimize for task completion, not persuasion: make the next step obvious.",
+    "Reduce steps and fields; prefill what the system already knows.",
+    "Use plain, specific labels over marketing copy.",
+    "Make errors and empty states say exactly what to do next."
   ]
 };
 var GENERIC_PRIORS = [
@@ -2286,12 +2554,12 @@ function registerAgentTrafficTools(server, client) {
     "get_agent_traffic",
     {
       title: "Agent traffic",
-      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Defaults to the last 30 days; pass from/to for a custom period (agent logs are retained 30 days on Free/Starter, 90 on Growth+). Agent traffic is tracked separately and never counted in conversion rate." + UNTRUSTED_FIELDS_NOTE,
-      inputSchema: {
-        projectId: projectIdSchema,
-        from: import_zod14.z.string().optional().describe("Period start (ISO 8601 date or timestamp). Defaults to 30 days ago."),
-        to: import_zod14.z.string().optional().describe("Period end (ISO 8601 date or timestamp). Defaults to now.")
-      },
+      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Defaults to the last 30 calendar days; pass range (7d/30d/90d/all) or from/to (YYYY-MM-DD) like every other windowed tool (agent logs are retained 30 days on Free/Starter, 90 on Growth+). Agent traffic is tracked separately and never counted in conversion rate." + UNTRUSTED_FIELDS_NOTE,
+      // This tool alone took ad-hoc ISO from/to with no range token and echoed
+      // no window, while every other windowed tool used rangeInputSchema — so
+      // agents passed range:'7d' here, it was silently dropped, and 30 days of
+      // traffic was reported as a week. The endpoint uses the shared resolver.
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
       outputSchema: {
         totals: import_zod14.z.object({ crawler: import_zod14.z.number(), api: import_zod14.z.number(), browser: import_zod14.z.number() }),
         engines: import_zod14.z.array(
@@ -2305,20 +2573,18 @@ function registerAgentTrafficTools(server, client) {
           })
         ),
         intents: import_zod14.z.object({ user: import_zod14.z.number(), search: import_zod14.z.number(), training: import_zod14.z.number(), other: import_zod14.z.number() }).describe("Crawler fetches by purpose: user = an assistant answering a real person live"),
-        topPaths: import_zod14.z.array(import_zod14.z.object({ path: import_zod14.z.string(), count: import_zod14.z.number(), engines: import_zod14.z.number() }))
+        topPaths: import_zod14.z.array(import_zod14.z.object({ path: import_zod14.z.string(), count: import_zod14.z.number(), engines: import_zod14.z.number() })),
+        window: windowOutputSchema
       },
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    withApiErrorGuidance(async ({ projectId, from, to }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       const id = encodeURIComponent(projectId);
-      const qs = new URLSearchParams();
-      if (from) qs.set("from", from);
-      if (to) qs.set("to", to);
-      const query = qs.toString();
       const s = await client.get(
-        `/projects/${id}/agent-activity/summary${query ? `?${query}` : ""}`
+        `/projects/${id}/agent-activity/summary${rangeQuery({ range, from, to })}`
       );
-      const structuredContent = { totals: s.totals, engines: s.engines, intents: s.intents, topPaths: s.topPaths };
+      const structuredContent = { totals: s.totals, engines: s.engines, intents: s.intents, topPaths: s.topPaths, window: s.window };
+      const win = windowLine(s.window);
       const total = s.totals.crawler + s.totals.api + s.totals.browser;
       if (total === 0) {
         return {
@@ -2330,6 +2596,7 @@ function registerAgentTrafficTools(server, client) {
         };
       }
       const lines = [
+        ...win ? [win] : [],
         `Agent traffic: ${s.totals.crawler} crawler fetches, ${s.totals.api} agent API calls, ${s.totals.browser} agentic browser sessions.`,
         `Live user fetches: ${s.intents.user} \xB7 Search index: ${s.intents.search} \xB7 Training: ${s.intents.training}${s.intents.other ? ` \xB7 Other: ${s.intents.other}` : ""} (a "live user fetch" = an AI assistant reading your site to answer a real person).`,
         "",
@@ -2420,7 +2687,7 @@ var personaOutput = import_zod15.z.object({
 var cellOutput = import_zod15.z.object({
   slotId: import_zod15.z.string(),
   persona: import_zod15.z.string(),
-  status: import_zod15.z.string().describe("pending | generating | live | error | rejected"),
+  status: import_zod15.z.string().describe("pending | generating | review (waiting for approval) | live | error | rejected"),
   requestedBy: import_zod15.z.string(),
   armId: import_zod15.z.string().nullable(),
   rationale: import_zod15.z.string().nullable(),
@@ -2460,6 +2727,10 @@ function registerCellTools(server, client) {
         personas: import_zod15.z.array(personaOutput),
         cells: import_zod15.z.array(cellOutput),
         autoFill: import_zod15.z.boolean(),
+        // The API has always sent this; without it in the schema zod stripped
+        // it, and generate_cell had no way to know a version would wait for a
+        // human instead of publishing.
+        reviewMode: import_zod15.z.boolean().optional().describe("True when generated versions wait for approval (review_cell) instead of publishing automatically"),
         // Nullable: a project with no persona set at all reports null, not a
         // string. That is the NORMAL state since the default vocabulary was
         // emptied, so a non-nullable schema failed output validation on most
@@ -2476,7 +2747,7 @@ function registerCellTools(server, client) {
       const byCell = new Map(data.cells.map((c) => [`${c.slotId}::${c.persona}`, c]));
       const lines = [
         `Slots: ${data.slots.map((s) => `${untrusted(s.displayName)}${s.live === false ? " [draft]" : ""}`).join(", ") || "(none published)"}`,
-        `Auto-fill on first miss: ${data.autoFill ? "ON" : "off"} \xB7 persona source: ${(_a2 = data.personaSource) != null ? _a2 : 'none (one "everyone" row)'}`
+        `Auto-fill on first miss: ${data.autoFill ? "ON" : "off"} \xB7 review before publishing: ${data.reviewMode ? "ON (approve with review_cell)" : "off"} \xB7 persona source: ${(_a2 = data.personaSource) != null ? _a2 : 'none (one "everyone" row)'}`
       ];
       for (const p of data.personas) {
         const states = data.slots.map((s) => {
@@ -2561,7 +2832,12 @@ function registerCellTools(server, client) {
     "generate_cell",
     {
       title: "Generate a cell version",
-      description: "Queue AI generation of a version for one (persona, slot) cell. The worker writes it asynchronously (usually under a minute), brand-locked, and it goes live as a named option the optimizer explores. Also works to regenerate or retry a failed cell. Requires a paid plan (anonymous demo tokens are read-only).",
+      // The old copy promised "goes live, usually under a minute" — but with
+      // review mode on the worker parks the version for a human (status
+      // 'review') and nothing serves until someone approves it, and the queue
+      // can defer a cell (retry backoff, the plan's monthly generation cap). An
+      // agent relayed "it's live" for versions no visitor would ever see.
+      description: "Queue AI generation of a version for one (persona, slot) cell; the worker writes it asynchronously, brand-locked. If the project has review mode on, the finished version WAITS for approval (list_cell_reviews / review_cell) and serves nobody until approved; otherwise it publishes automatically as a named option the optimizer explores. Also regenerates or retries a failed cell. Generation volume is capped per plan (Free included). Check get_cell_matrix for progress. Confirm with the user before calling \u2014 each generation is a model call against the plan quota.",
       inputSchema: {
         projectId: projectIdSchema,
         slotId: import_zod15.z.string().min(1).max(128).describe("The slot id (a matrix column)"),
@@ -2570,28 +2846,130 @@ function registerCellTools(server, client) {
       outputSchema: {
         slotId: import_zod15.z.string(),
         persona: import_zod15.z.string(),
-        status: import_zod15.z.literal("pending").describe("Queued \u2014 check get_cell_matrix for progress")
+        status: import_zod15.z.literal("pending").describe("Queued \u2014 check get_cell_matrix for progress"),
+        reviewMode: import_zod15.z.boolean().nullable().describe("True: the version will wait for review_cell approval. False: it publishes automatically. Null: could not be read.")
       },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     withApiErrorGuidance(async ({ projectId, slotId, persona }) => {
       const id = encodeURIComponent(projectId);
       await client.post(`/projects/${id}/cells/generate`, { slotId, persona });
+      const matrix = await settled(client.get(`/projects/${id}/cells`));
+      const reviewMode = matrix.ok && typeof matrix.value.reviewMode === "boolean" ? matrix.value.reviewMode : null;
+      const next = reviewMode === true ? "Review mode is ON: when it is written it will WAIT for approval and serve nobody until then \u2014 list it with list_cell_reviews and approve or reject it with review_cell (after the user decides)." : reviewMode === false ? "Review mode is off: once written it publishes automatically and the optimizer starts exploring it." : 'Could not read whether review mode is on \u2014 check get_cell_matrix: status "review" means it is waiting for approval (review_cell), "live" means it is serving.';
       return {
         content: [
           {
             type: "text",
-            text: `Writing a version of ${untrusted(slotId, 64)} for ${untrusted(persona, 64)} \u2014 it usually goes live in under a minute. Check get_cell_matrix (status flips pending \u2192 live) or get_cell_detail for the story once it lands.`
+            text: `Queued a version of ${untrusted(slotId, 64)} for ${untrusted(persona, 64)}. It is written asynchronously (the queue may defer it \u2014 retries back off, and the plan caps generations). ${next} Track it with get_cell_matrix or get_cell_detail.`
           }
         ],
-        structuredContent: { slotId, persona, status: "pending" }
+        structuredContent: { slotId, persona, status: "pending", reviewMode }
       };
     })
   );
+  server.registerTool(
+    "list_cell_reviews",
+    {
+      title: "Versions waiting for review",
+      description: "Generated versions waiting for approval (review mode): which slot and visitor type, the proposed text or layout, and why it was written. Approve or reject each with review_cell after the user decides." + UNTRUSTED_FIELDS_NOTE,
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        reviews: import_zod15.z.array(
+          import_zod15.z.object({
+            slotId: import_zod15.z.string(),
+            slotName: import_zod15.z.string(),
+            persona: import_zod15.z.string(),
+            personaDisplay: import_zod15.z.string(),
+            content: import_zod15.z.string().nullable().describe("Proposed text, when the version is text (null for a block/layout version)"),
+            rationale: import_zod15.z.string().nullable(),
+            refinedFrom: import_zod15.z.string().nullable().describe("Live version this one would replace; that version keeps serving until approval"),
+            updatedAt: import_zod15.z.string()
+          })
+        )
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      var _a2;
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/cell-reviews`);
+      const reviews = ((_a2 = data.reviews) != null ? _a2 : []).map((r) => {
+        var _a3, _b, _c;
+        return {
+          slotId: r.slotId,
+          slotName: r.slotName,
+          persona: r.persona,
+          personaDisplay: r.personaDisplay,
+          content: typeof ((_a3 = r.pendingArm) == null ? void 0 : _a3.content) === "string" ? r.pendingArm.content : null,
+          rationale: (_b = r.rationale) != null ? _b : null,
+          refinedFrom: (_c = r.refinedFrom) != null ? _c : null,
+          updatedAt: String(r.updatedAt)
+        };
+      });
+      if (reviews.length === 0) {
+        return {
+          content: [{ type: "text", text: "No generated versions are waiting for review." }],
+          structuredContent: { reviews }
+        };
+      }
+      const lines = reviews.map(
+        (r) => [
+          `- ${untrusted(r.slotName, 60)} (slotId ${untrusted(r.slotId, 64)}) for ${untrusted(r.personaDisplay, 60)} (persona ${untrusted(r.persona, 64)})`,
+          r.content !== null ? `  Proposed text: ${untrusted(r.content, 300)}` : "  Proposed: a designed block/layout (preview it in the dashboard)",
+          r.rationale ? `  Why: ${untrusted(r.rationale, 300)}` : null,
+          r.refinedFrom ? `  Would replace ${untrusted(r.refinedFrom, 64)}, which keeps serving until approval.` : null
+        ].filter((l) => l !== null).join("\n")
+      );
+      lines.push("", "Approve or reject each with review_cell (slotId + persona) once the user has decided.");
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent: { reviews } };
+    })
+  );
+  server.registerTool(
+    "review_cell",
+    {
+      title: "Approve or reject a generated version",
+      description: "Approve or reject ONE generated version waiting for review (see list_cell_reviews). 'approve' publishes it to live visitors of that type; 'reject' discards it (a rejected refinement leaves the current live version in place). This is the human decision review mode exists for \u2014 only call it with the user's explicit go-ahead.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        slotId: import_zod15.z.string().min(1).max(128).describe("The slot id of the version under review"),
+        persona: import_zod15.z.string().min(1).max(64).describe("The persona key of the version under review"),
+        action: import_zod15.z.enum(["approve", "reject"]),
+        feedback: import_zod15.z.string().max(2e3).optional().describe("Optional reviewer note, stored with a rejection")
+      },
+      outputSchema: {
+        slotId: import_zod15.z.string(),
+        persona: import_zod15.z.string(),
+        action: import_zod15.z.enum(["approve", "reject"]),
+        status: import_zod15.z.string().describe("live (approved, or a rejected refinement whose incumbent keeps serving) | rejected"),
+        armId: import_zod15.z.string().nullable().describe("The published option id, on approval")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, slotId, persona, action, feedback }) => {
+      var _a2, _b;
+      const id = encodeURIComponent(projectId);
+      const res = await client.post(`/projects/${id}/cells/review`, {
+        slotId,
+        persona,
+        action,
+        feedback
+      });
+      const status = (_a2 = res.status) != null ? _a2 : action === "approve" ? "live" : "rejected";
+      const text = action === "approve" ? `Approved: the version for ${untrusted(persona, 64)} in ${untrusted(slotId, 64)} is now live${res.armId ? ` as option ${untrusted(res.armId, 64)}` : ""}.` : status === "live" ? `Rejected: the proposed refinement for ${untrusted(persona, 64)} in ${untrusted(slotId, 64)} was discarded; the current live version keeps serving.` : `Rejected: the version for ${untrusted(persona, 64)} in ${untrusted(slotId, 64)} was discarded; that visitor type keeps seeing the original.`;
+      return {
+        content: [{ type: "text", text }],
+        structuredContent: { slotId, persona, action, status, armId: (_b = res.armId) != null ? _b : null }
+      };
+    }, {
+      not_found: "No version is waiting for review in that cell (it may already have been approved or rejected). Check list_cell_reviews.",
+      publish_failed: "Approval could not publish this version (the slot may be full of options, or its configuration changed). It stays in review \u2014 check the reason in get_cell_detail or the dashboard, then retry."
+    })
+  );
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.19.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.20.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {
@@ -2706,6 +3084,11 @@ async function main() {
       "SENTIENTUI_API_KEY is set but empty. Set it to a real server key (sk_\u2026), or unset it entirely to use anonymous demo mode."
     );
   }
+  if (apiKey && /^pk_/i.test(apiKey)) {
+    throw new Error(
+      "SENTIENTUI_API_KEY is a pk_ publishable key \u2014 that key is for the browser SDK and cannot read or manage project data. Use the project's sk_ server key (Dashboard \u2192 Settings \u2192 API keys \u2192 Server key), or connect by URL (https://api.sentient-ui.com/mcp) and sign in."
+    );
+  }
   if (!apiKey) {
     apiKey = await resolveDemoToken();
     refreshApiKey = refreshDemoToken;