@zackbart/connecta 0.24.4 → 0.25.0

package/dist/operator-ui/model.d.ts

@@ -1,9 +1,41 @@
 import type { CatalogAccessObservation, CatalogDriftReport } from "../types.js";
+/**
+ * Which call path a tool takes, decided on the server by the same
+ * `isExplicitlyReadOnly` predicate discovery and invocation use
+ * (`src/tool-safety.ts`) and never re-derived in the browser: a second copy of
+ * the rule is a second place for it to be wrong.
+ *
+ * - `runs_in_programs` — explicitly read-only, so `execute_code` may call it.
+ * - `needs_approval` — everything else, which crosses `call_destructive_tool`.
+ *
+ * Planned resumable writes add a third value for a config `approval: "never"`
+ * exemption; the badge renders from a table keyed by this union so that value
+ * is one entry, not a new branch.
+ */
+export type UiToolSafety = "runs_in_programs" | "needs_approval";
 export interface UiTool {
     name: string;
     address: string;
     description?: string;
+    /** Absent only in payloads older than the field; the page then shows no badge. */
+    safety?: UiToolSafety;
 }
+/**
+ * What went wrong with a connector, as a closed set the server chooses from.
+ * The browser keys both its on-screen description and a fixed fix prompt off
+ * this. There is deliberately no message beside it: a connector's status
+ * message can quote a downstream error body, so it goes to the deployment's
+ * log and never into the operator payload.
+ *
+ * `auth_required` splits by who has to act: a downstream OAuth grant
+ * (`oauth_required`, which also covers an expired or revoked grant — the
+ * status seam cannot tell those apart), an operator-managed credential slot
+ * (`credential_required`), or a secret that lives in deployment configuration
+ * (`auth_required`).
+ */
+export type UiProblem = "connector_unavailable" | "oauth_required" | "credential_required" | "auth_required" | "credential_mismatch" | "catalog_failed";
+/** A stored credential that cannot be used, by cause. */
+export type UiCredentialProblem = "credential_mismatch" | "credential_unreadable";
 interface UiCredentialField {
     name: string;
     label: string;
@@ -26,6 +58,8 @@ interface UiCredential {
     updatedAt?: string;
     testable: boolean;
     error?: string;
+    /** Present exactly when `error` is: the cause, for the fix prompt. */
+    problem?: UiCredentialProblem;
     /**
      * Something true and non-blocking about a working credential — today, that
      * the vault still holds fields the connector has stopped declaring.
@@ -45,7 +79,12 @@ export interface UiConnector {
         manageSharedAuth: boolean;
         connectPersonal: boolean;
     };
-    message?: string;
+    /**
+     * Why this connector is not usable, when it is not. See `UiProblem`. The
+     * only failure detail the payload carries; the status message behind it is
+     * logged on the server, not shipped.
+     */
+    problem?: UiProblem;
     authorizationUrl?: string;
     toolCount: number;
     tools: UiTool[];
@@ -77,6 +116,12 @@ export interface UiData {
     credentialManagement: CredentialManagementCapability;
     /** True when this interactive human may manage any visible OAuth connector. */
     oauthManagement: boolean;
+    /**
+     * Names of the `/mcp/<name>` pools this identity's grant admits. A pool
+     * whose grant refuses or throws is absent, exactly as the endpoint answers
+     * it with a 404, so the page never enumerates a pool its reader cannot open.
+     */
+    pools?: string[];
 }
 export interface FilteredUiConnector {
     connector: UiConnector;

package/dist/operator-ui/setup-commands.js

@@ -0,0 +1,53 @@
+/**
+ * Client setup snippets for one MCP endpoint: the deployment's `/mcp` or a
+ * `/mcp/<pool>`. Three formats and no more — Claude Code's CLI, Codex's CLI,
+ * and the `mcpServers` JSON most other clients read — because a longer list
+ * is a list to keep current.
+ *
+ * None of them carries a credential. A client authenticates through the
+ * deployment's inbound auth — OAuth discovery where that is configured — and
+ * a token pasted into a snippet on this page would be one rendered by it.
+ */
+/**
+ * The name a client files this server under. Derived from the deployment's
+ * configured server name, reduced to the characters every client CLI accepts
+ * unquoted, with the pool appended so two endpoints never collide.
+ */
+export function clientServerName(serverName, pool) {
+    const base = (serverName ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48) || "connecta";
+    return pool ? `${base}-${pool}` : base;
+}
+/** The URL for a pool: `/mcp` plus its name, which config limits to `[a-z0-9_-]`. */
+export function poolEndpointUrl(mcpUrl, pool) {
+    return `${mcpUrl.replace(/\/+$/, "")}/${encodeURIComponent(pool)}`;
+}
+/** POSIX single-quoting, only when the value needs it. */
+function shellWord(value) {
+    return /^[A-Za-z0-9_./:@%+=,~-]+$/.test(value)
+        ? value
+        : `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+export function clientSetupCommands(name, url) {
+    return [
+        {
+            id: "claude",
+            label: "Claude Code",
+            text: `claude mcp add --transport http ${shellWord(name)} ${shellWord(url)}`,
+        },
+        {
+            id: "codex",
+            label: "Codex",
+            text: `codex mcp add ${shellWord(name)} --url ${shellWord(url)}`,
+        },
+        {
+            id: "json",
+            label: "JSON config",
+            text: JSON.stringify({ mcpServers: { [name]: { type: "http", url } } }, null, 2),
+        },
+    ];
+}

package/dist/operator-ui/view.js

@@ -13,8 +13,8 @@ export function pageForPath(path) {
 export function info(message) {
     return { message, tone: "info" };
 }
-export function failure(message) {
-    return { message, tone: "error" };
+export function failure(message, fix) {
+    return fix ? { message, tone: "error", fix } : { message, tone: "error" };
 }
 export function initialState(page) {
     return {
@@ -150,6 +150,42 @@ export function connectorSummaryParts(summary) {
         { text: toolCountLabel(summary.tools), tone: "neutral" },
     ];
 }
+/**
+ * The badge for each call path, keyed by the server's classification so the
+ * planned third state is a row here rather than a new branch in a component.
+ */
+export const TOOL_SAFETY_BADGE = {
+    runs_in_programs: {
+        label: "runs in programs",
+        tone: "ok",
+        title: "Explicitly read-only: execute_code programs may call it without asking.",
+    },
+    needs_approval: {
+        label: "needs approval",
+        tone: "warn",
+        title: "Not explicitly read-only: calls cross call_destructive_tool, where the host asks first.",
+    },
+};
+/**
+ * What the page says about a connector that is not usable, one fixed sentence
+ * per problem kind the server classified. This is the only account of a
+ * failure the Connections page renders: a connector's status message can quote
+ * a downstream error body, and a downstream error body can quote the secret
+ * that was just rejected, so the raw text stays in the deployment's log and
+ * never reaches the payload or the DOM. The fix prompt beside it is keyed off
+ * the same kind.
+ */
+const PROBLEM_COPY = {
+    connector_unavailable: "Unavailable: its status check or catalog load failed, or did not finish in time. The deployment's log has the downstream error.",
+    oauth_required: "Needs OAuth authorization: no grant is stored, or the stored grant expired or was revoked.",
+    credential_required: "Needs a credential: nothing usable is stored in its credential slot.",
+    auth_required: "Needs authorization. Its secret lives in deployment configuration, not on this page.",
+    credential_mismatch: "The stored credential does not match the fields this connector declares, so it cannot be used.",
+    catalog_failed: "Connected, but its tool catalog could not be loaded, so none of its tools are served.",
+};
+export function problemCopy(problem) {
+    return problem ? PROBLEM_COPY[problem] ?? null : null;
+}
 /** Who owns this connector's downstream credentials, in two words. */
 export function authScopeLabel(scope) {
     return scope === "personal" ? "personal auth" : "shared auth";

package/dist/program-source.js

@@ -0,0 +1,205 @@
+// Program source handling shared by every executor. Web-API only: execute_code
+// runs it before handing a program to QuickJS or a Dynamic Worker, and the
+// QuickJS normalizer runs it too for callers that drive that executor directly.
+/** A whole-program markdown fence, as QuickJS's normalizer recognizes one. */
+const FENCE = /^```[\w-]*\s*\n([\s\S]*?)\n?```$/;
+/** Leading whitespace and comments, which may precede the arrow expression. */
+const LEADING_TRIVIA = /^(?:\s+|\/\/[^\n]*|\/\*[\s\S]*?\*\/)+/;
+/** One character of an identifier, keyword, or number; `\\` for escapes. */
+const WORD = /[\w$\\\u0080-\uffff]/;
+/**
+ * Words after which a `/` begins a regular expression rather than dividing.
+ * Any other word is an identifier or a literal, which a `/` divides.
+ */
+const REGEX_AFTER_WORD = new Set([
+    "await", "case", "delete", "do", "else", "in", "instanceof", "new", "of",
+    "return", "throw", "typeof", "void", "yield",
+]);
+/**
+ * Remove the statement terminators after a program's arrow expression:
+ * `async () => { … };`, with any whitespace or comments around the trailing
+ * semicolons, becomes `async () => { … }` with those comments kept. Both
+ * executors evaluate a program as a parenthesized expression, where a
+ * terminator is a syntax error on QuickJS and, on a Dynamic Worker, either the
+ * same error or a program that silently returns `undefined`. Models often end
+ * a program with `};`, so P1 accepts it on both.
+ *
+ * Deliberately narrow, so it cannot broaden what a program is: only a program
+ * whose first token is `async` or `(` — what QuickJS treats as a function
+ * expression — and only when every semicolon at bracket depth zero trails it,
+ * with nothing but whitespace and comments after. `async () => 1; 2();` keeps
+ * both its semicolons, and a bare statement body is never touched, since its
+ * trailing `;` can be an empty loop body. A whole-program markdown fence is
+ * looked through, and dropped when a terminator came out from under it.
+ *
+ * A small lexer, not a parser: it skips strings, template literals (with
+ * `${}` nesting), comments, and regular expressions, telling a regex from a
+ * division by the token before it. Any source it cannot close — an
+ * unterminated string or comment, unbalanced brackets — comes back unchanged,
+ * so the executor reports the same error it always did.
+ */
+export function withoutProgramTerminator(code) {
+    const fenced = FENCE.exec(code.trim())?.[1];
+    const source = fenced === undefined ? code : fenced.trim();
+    const stripped = stripTerminators(source);
+    return stripped === source ? code : stripped;
+}
+function stripTerminators(source) {
+    const head = source.replace(LEADING_TRIVIA, "");
+    if (!/^async\b/.test(head) && !head.startsWith("("))
+        return source;
+    const n = source.length;
+    let depth = 0;
+    /** Bracket depth at which each open template substitution resumes its template. */
+    const substitutions = [];
+    /** Positions of the top-level semicolons, all of which must trail. */
+    const terminators = [];
+    /**
+     * The previous significant token: a punctuator character or a word, with a
+     * string, template, or regex literal recorded as `0` — a value, like a number.
+     */
+    let previous = "";
+    let i = 0;
+    /** Scan template text from `from` to its closing backtick or next `${`. */
+    const template = (from) => {
+        for (let j = from; j < n; j++) {
+            const c = source[j];
+            if (c === "\\") {
+                j++;
+            }
+            else if (c === "`") {
+                return j + 1;
+            }
+            else if (c === "$" && source[j + 1] === "{") {
+                substitutions.push(depth);
+                depth++;
+                return j + 2;
+            }
+        }
+        return undefined;
+    };
+    while (i < n) {
+        const c = source[i];
+        if (/\s/.test(c)) {
+            i++;
+            continue;
+        }
+        if (c === "/" && source[i + 1] === "/") {
+            const end = source.indexOf("\n", i);
+            i = end === -1 ? n : end;
+            continue;
+        }
+        if (c === "/" && source[i + 1] === "*") {
+            const end = source.indexOf("*/", i + 2);
+            if (end === -1)
+                return source;
+            i = end + 2;
+            continue;
+        }
+        if (c === ";") {
+            if (depth === 0)
+                terminators.push(i);
+            previous = ";";
+            i++;
+            continue;
+        }
+        // Code after a top-level semicolon means the program is more than one
+        // expression; that is for the executor to refuse, not for us to repair.
+        if (terminators.length > 0)
+            return source;
+        if (c === '"' || c === "'") {
+            let j = i + 1;
+            while (j < n && source[j] !== c) {
+                if (source[j] === "\n")
+                    return source;
+                j += source[j] === "\\" ? 2 : 1;
+            }
+            if (j >= n)
+                return source;
+            i = j + 1;
+            previous = "0";
+            continue;
+        }
+        if (c === "`") {
+            const end = template(i + 1);
+            if (end === undefined)
+                return source;
+            i = end;
+            previous = source[end - 1] === "`" ? "0" : "{";
+            continue;
+        }
+        if (c === "}" && substitutions.at(-1) === depth - 1) {
+            substitutions.pop();
+            depth--;
+            const end = template(i + 1);
+            if (end === undefined)
+                return source;
+            i = end;
+            previous = source[end - 1] === "`" ? "0" : "{";
+            continue;
+        }
+        if (c === "/" && startsRegex(previous)) {
+            let j = i + 1;
+            let inClass = false;
+            for (; j < n; j++) {
+                const r = source[j];
+                if (r === "\n")
+                    return source;
+                if (r === "\\")
+                    j++;
+                else if (r === "[")
+                    inClass = true;
+                else if (r === "]")
+                    inClass = false;
+                else if (r === "/" && !inClass)
+                    break;
+            }
+            if (j >= n)
+                return source;
+            i = j + 1;
+            while (i < n && /[\w$]/.test(source[i]))
+                i++;
+            previous = "0";
+            continue;
+        }
+        if (WORD.test(c)) {
+            let j = i + 1;
+            while (j < n && WORD.test(source[j]))
+                j++;
+            previous = source.slice(i, j);
+            i = j;
+            continue;
+        }
+        if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}") {
+            if (depth === 0)
+                return source;
+            depth--;
+        }
+        previous = c;
+        i++;
+    }
+    if (depth !== 0 || substitutions.length > 0 || terminators.length === 0) {
+        return source;
+    }
+    let out = "";
+    let from = 0;
+    for (const at of terminators) {
+        out += source.slice(from, at);
+        from = at + 1;
+    }
+    return out + source.slice(from);
+}
+/** Whether a `/` after `previous` opens a regular expression. */
+function startsRegex(previous) {
+    if (previous === "")
+        return true;
+    if (WORD.test(previous[0])) {
+        // A number or an identifier divides; a keyword introduces an operand.
+        return REGEX_AFTER_WORD.has(previous);
+    }
+    // After a closing bracket a value precedes; after any other punctuator
+    // an operand is expected.
+    return previous !== ")" && previous !== "]" && previous !== "}";
+}

package/dist/providers/notion.js

@@ -89,7 +89,7 @@ function notionFailure(status, body, headers) {
         return new ConnectorCallError("unavailable", `${labelled} Notion is overloaded; retry after the reported window.`, { retryAfterMs: retryAfter ?? 5_000 });
     }
     if (status === 401) {
-        return new ConnectorCallError("auth_required", `${labelled} The Notion integration token is missing or invalid — an operator must set a valid token on /credentials.`);
+        return new ConnectorCallError("auth_required", `${labelled} The Notion integration token is missing or invalid. Call authorize_connector for recovery options. When available, an operator can set a valid token in this connection in the operator UI.`);
     }
     if (status === 403) {
         return new ConnectorCallError("connector_call_failed", `${labelled} The token is valid but this integration is not allowed to perform this operation. An operator must enable the matching capability on the Notion integration (comment capabilities are off by default) or share the object with it. Re-authorizing will not help.`, { retryable: false });
@@ -133,7 +133,7 @@ const send = guardedFetch({
     authenticate: async (ctx) => {
         const token = (await ctx.credential?.get())?.trim();
         if (!token) {
-            throw new ConnectorCallError("auth_required", "No Notion integration token is configured for this connector — an operator must add one on /credentials before any Notion call can run.");
+            throw new ConnectorCallError("auth_required", "No Notion integration token is configured for this connector. Call authorize_connector for recovery options. When available, an operator can add the token in this connection in the operator UI.");
         }
         return { Authorization: `Bearer ${token}` };
     },

package/dist/providers/revenuecat.js

@@ -5,7 +5,7 @@ import { defined } from "../connectors/api.js";
 export const REVENUECAT_MCP_ENDPOINT = "https://mcp.revenuecat.ai/mcp";
 /**
  * Reviewed reads, every `Read` row of RevenueCat's tool reference as read on
- * 2026-08-30 (P5). The list is a superset: plan, platform, and beta enrollment
+ * 2026-09-21 (P5). The list is a superset: plan, platform, and beta enrollment
  * gate parts of the catalog, so a name this account never returns costs
  * nothing while an unlisted new one fails closed.
  */
@@ -23,7 +23,11 @@ const READ_ONLY_TOOLS = new Set([
     // Products and prices
     "get-product",
     "get-product-store-state",
+    // Deprecated in RevenueCat's reference — superseded by the plan family's
+    // own read-back below — but still served, so the classification stands.
     "get-product-store-state-operation",
+    "get-product-store-state-plan",
+    "list-product-store-state-plans",
     "list-products",
     // Entitlements
     "get-entitlement",
@@ -100,19 +104,36 @@ const WRITE_TOOLS = new Map([
     ["archive-product", "destructive"],
     ["create-product", "additive"],
     // Named `create-`, but "Configure prices for a product": the price set
-    // already exists, so this overwrites it, and it is money-facing.
+    // already exists, so this overwrites it, and it is money-facing. Deprecated
+    // in RevenueCat's reference; products are priced through the plan family
+    // below, but the tool is still served, so the classification stands.
     ["create-product-prices", "destructive"],
     // "Fills *missing* App Store subscription territory prices" — by
-    // RevenueCat's own word it writes only where nothing is set.
+    // RevenueCat's own word it writes only where nothing is set. Deprecated in
+    // RevenueCat's reference; still served, so the classification stands.
     ["equalize-subscription-prices", "additive"],
-    // An upsert.
+    // An upsert. Deprecated in RevenueCat's reference — the store-state plan
+    // family below replaces it — but still served, so the classification stands.
     ["set-product-store-state", "destructive"],
     // Sends products to Apple for review.
     ["submit-products-to-store", "destructive"],
     ["unarchive-product", "destructive"],
     ["update-product", "destructive"],
     // Reserves a new App Store Connect review screenshot slot; replaces nothing.
+    // Deprecated in RevenueCat's reference; still served, so the classification
+    // stands.
     ["upload-product-store-state-screenshot", "additive"],
+    // Product store state plans, the workflow RevenueCat deprecated
+    // `set-product-store-state` for. Create brings a draft into being and
+    // touches nothing else; plan recomputes an existing plan's proposed change,
+    // overwriting its previous planning; apply pushes the whole plan into
+    // RevenueCat and the app stores; update and discard act on an existing plan
+    // by name. Every step past create is asynchronous.
+    ["create-product-store-state-plan", "additive"],
+    ["plan-product-store-state-plan", "destructive"],
+    ["apply-product-store-state-plan", "destructive"],
+    ["update-product-store-state-plan", "destructive"],
+    ["discard-product-store-state-plan", "destructive"],
     // Entitlements
     ["archive-entitlement", "destructive"],
     // Attach adds membership and removes nothing; detach is the destructive half.
@@ -135,6 +156,11 @@ const WRITE_TOOLS = new Map([
     // Targeting and audiences
     ["create-audience", "additive"],
     ["update-audience", "destructive"],
+    // Targeting rules follow the verb: create brings one into being, update
+    // and delete act on a rule the project already has.
+    ["create-targeting-rule", "additive"],
+    ["update-targeting-rule", "destructive"],
+    ["delete-targeting-rule", "destructive"],
     // Paywalls
     ["attach-offering-to-paywall", "destructive"],
     ["detach-offering-from-paywall", "destructive"],
@@ -204,7 +230,8 @@ function sharedUsageGuide() {
 - Customer and subscription objects are large, and a customer's history is larger. Page with the cursor the list returned rather than raising the page size, and reduce inside \`execute_code\` — select the fields the question needs and return those, not the whole object.
 - Whether a customer should have access is \`gives_access\` on each subscription from \`list-subscriptions\`, which RevenueCat calls the authoritative flag. \`status\` and \`expires_date\` describe the store-side state and disagree with it during grace periods, billing retries, and promotional grants — answer access questions from \`gives_access\` and say which subscription it came from.
 - \`get-chart-data\` is the metrics path: read \`get-chart-options-schema\` for the chart you want before calling it, rather than guessing an option name. \`get-overview-metrics\` and \`get-revenue-metric\` answer the summary questions in one call.
-- \`create-paywall-ai\`, \`edit-paywall-ai\`, and \`set-product-store-state\` are asynchronous. They return a task or operation id; poll it with \`get-paywall-ai-task\` or \`get-product-store-state-operation\` rather than assuming the work finished when the call returned.
+- \`create-paywall-ai\` and \`edit-paywall-ai\` are asynchronous. Poll the task id they return with \`get-paywall-ai-task\` rather than assuming the work finished when the call returned.
+- Store changes ride the plan workflow, not the deprecated direct tools: \`create-product-store-state-plan\`, then \`plan-product-store-state-plan\`, then \`apply-product-store-state-plan\`. Every step past the create is asynchronous — read the plan back with \`get-product-store-state-plan\` between steps instead of assuming the last one finished.
 - This connection's tool list is not a fixed set. RevenueCat gates parts of its MCP catalog by plan, platform, and beta enrollment — paywall AI editing, benchmarks, experiments, virtual currencies, and the account-billing tools are the usual absentees — so search this connector for what it actually exposes rather than assuming a documented tool is here.
 - \`render-paywall-screenshot\` is unclassified on purpose because RevenueCat's reference gives it no access column. The current server marks it read-only, which Connecta preserves; without that annotation it fails closed onto \`call_destructive_tool\`.
 - RevenueCat meters API v2 per minute and per domain, and the domains differ: 480 requests per minute for customer information and virtual currencies, 60 for project configuration and audiences, 25 for charts and metrics. It answers a breach with \`429\`, a \`Retry-After\` header, and a \`backoff_ms\` field. Back off on that rather than retrying immediately, and expect chart sweeps to hit the ceiling long before customer reads do.

package/dist/providers/stripe.d.ts

@@ -28,8 +28,9 @@ export interface StripeOAuthOptions extends StripeCommonOptions {
  * Static credentials have one fixed mode, including Stripe Connect calls.
  *
  * Both static shapes belong here: a key the deployment supplies as a literal
- * header, and one the operator pastes at `/credentials`. Neither can discover
- * its own mode — a restricted key answers for exactly one — so both declare it.
+ * header, and one the operator pastes into the connection in the operator UI.
+ * Neither can discover its own mode, since a restricted key answers for
+ * exactly one, so both declare it.
  */
 export interface StripeHeaderOptions extends StripeCommonOptions {
     auth: Exclude<RemoteMcpAuth, {

package/dist/providers/vercel.js

@@ -138,7 +138,7 @@ function vercelTransport(baseUrl) {
         authenticate: async (ctx) => {
             const token = (await ctx.credential?.get())?.trim();
             if (!token) {
-                throw new ConnectorCallError("auth_required", "No Vercel access token is configured for this connector. An operator must add one on /credentials before any Vercel call can run.");
+                throw new ConnectorCallError("auth_required", "No Vercel access token is configured for this connector. Call authorize_connector for recovery options. When available, an operator can add the token in this connection in the operator UI.");
             }
             return { Authorization: `Bearer ${token}` };
         },

package/dist/registry.d.ts

@@ -58,7 +58,7 @@ export interface RegistryOptions {
     /**
      * Cap on inline result size before truncation + get_result paging. Must be a
      * whole number of bytes >= 1; anything else warns at startup and falls back
-     * to the default 50_000.
+     * to the default 24_000.
      */
     maxResultBytes?: number | undefined;
     results?: {