@zackbart/connecta 0.34.0 → 0.34.1

package/dist/operator-ui/health.js

@@ -0,0 +1,52 @@
+/**
+ * The next steady evidence. A settled connector takes its current row; one
+ * being read again keeps its previous evidence when this identity has any.
+ * Returns `previous` itself when nothing changed, so it can live in React
+ * state. A new identity starts empty.
+ */
+export function steadyHealth(state, previous) {
+    const same = previous?.generation === state.generation ? previous : null;
+    const contract = state.contract?.role === "maintainer" && state.data ? state.contract : null;
+    // No contract on screen: keep what was shown until the next one arrives.
+    if (!contract || !state.data)
+        return same ?? { generation: state.generation, rows: Object.create(null) };
+    const reading = new Set(state.data.connectors.filter((c) => c.status === "loading").map((c) => c.id));
+    const held = same?.rows ?? Object.create(null);
+    const rows = Object.create(null);
+    let changed = !same || Object.keys(held).length !== contract.live.connectors.length;
+    for (const live of contract.live.connectors) {
+        const before = Object.hasOwn(held, live.id) ? held[live.id] : undefined;
+        if (before && reading.has(live.id)) {
+            rows[live.id] = before;
+            continue;
+        }
+        const failed = Object.hasOwn(state.connectorFailures, live.id) && Boolean(state.connectorFailures[live.id]);
+        if (before?.live === live && before.failed === failed)
+            rows[live.id] = before;
+        else {
+            rows[live.id] = { live, failed };
+            changed = true;
+        }
+    }
+    return changed ? { generation: state.generation, rows } : same;
+}
+/** The contract each view renders health from, with every live row replaced by its steady evidence. */
+export function shownHealth(contract, health) {
+    const signals = Object.create(null);
+    if (!contract)
+        return { contract, signals };
+    let replaced = false;
+    const connectors = contract.live.connectors.map((live) => {
+        const row = Object.hasOwn(health.rows, live.id) ? health.rows[live.id] : undefined;
+        if (row?.failed)
+            signals[live.id] = { failed: true };
+        if (!row || row.live === live)
+            return live;
+        replaced = true;
+        return row.live;
+    });
+    return {
+        contract: replaced ? { ...contract, live: { ...contract.live, connectors } } : contract,
+        signals,
+    };
+}

package/dist/operator-ui/overview.js

@@ -13,7 +13,7 @@ function affects(paths) {
     return paths.length ? `Affects ${joinList(paths)}` : "No endpoint serves it";
 }
 /**
- * One row per connector that is not healthy, failing first, then one per
+ * One row per connector that is not healthy, in config order, then one per
  * agent that sits in an endpoint without a working token. Each row carries
  * the fix the rest of the UI already offers for it.
  */
@@ -26,7 +26,7 @@ export function attentionItems(contract, options = {}) {
         const live = contract.live.connectors.find((c) => c.id === config.id);
         if (!live)
             continue;
-        const signals = options.signals?.[config.id] ?? {};
+        const signals = options.signals && Object.hasOwn(options.signals, config.id) ? options.signals[config.id] : {};
         const verdict = connectorVerdict(live, signals);
         if ((verdict.tone !== "warn" && verdict.tone !== "danger") || !verdict.action)
             continue;
@@ -71,15 +71,6 @@ export function attentionItems(contract, options = {}) {
                 fix: null,
             });
         }
-        else {
-            // Healthy but drifted: the live tool list differs from the reviewed one.
-            connectors.push({
-                ...base,
-                problem: "has a changed tool list",
-                body: affects(paths),
-                fix: { kind: "catalog_drift", connectorId: config.id },
-            });
-        }
     }
     const agents = contract.agents
         .filter((agent) => agent.pools.length && agent.token.state !== "issued")
@@ -101,11 +92,9 @@ export function attentionItems(contract, options = {}) {
             fix: null,
         };
     });
-    return [
-        ...connectors.filter((item) => item.tone === "danger"),
-        ...connectors.filter((item) => item.tone === "warn"),
-        ...agents,
-    ];
+    // Severity changes as individual details settle. Config order keeps surviving
+    // rows in place without waiting for the slowest connector's read.
+    return [...connectors, ...agents];
 }
 /** The numbers above the list, counted from the same map the page draws. */
 export function overviewHeadline(contract, map, items, signals = {}) {
@@ -113,7 +102,7 @@ export function overviewHeadline(contract, map, items, signals = {}) {
         const live = contract.live.connectors.find((c) => c.id === config.id);
         if (!live)
             return [];
-        const health = connectorVerdict(live, signals[config.id]);
+        const health = connectorVerdict(live, Object.hasOwn(signals, config.id) ? signals[config.id] : undefined);
         return [{ id: config.id, title: config.title ?? config.id, tone: health.tone, label: health.label }];
     });
     const healthy = bar.filter((entry) => entry.tone === "ok").length;

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

@@ -318,9 +318,8 @@ export declare function problemCopy(problem: UiProblem | undefined): string | nu
  * error. The two used to share the red box, so the row contradicted itself.
  */
 export declare function problemTone(problem: UiProblem): "warn" | "danger";
-/** What the page knows about a connector beyond its live status: catalog drift and a failed detail read. */
+/** What the page knows about a connector beyond its live status: a failed detail read. */
 export interface ConnectorSignals {
-    drift?: boolean;
     failed?: boolean;
 }
 /** One connector's health everywhere it is shown: badge tone, status word, and the one action beside it. */
@@ -328,12 +327,12 @@ export interface ConnectorVerdict {
     tone: "ok" | "warn" | "danger" | "neutral";
     label: string;
     /** The link to the Connection tab, or null when the connector is fine. */
-    action: "Connect" | "Replace key" | "Inspect" | "Review" | null;
+    action: "Connect" | "Replace key" | "Inspect" | null;
 }
 /**
  * The verdict the Connectors list, the Overview, Endpoints and a connector's
  * page all show. The server's problem code comes first, then a failed detail
- * read on this page, then a non-ok status, then catalog drift. A problem
+ * read on this page, then a non-ok status. Catalog drift is informational. A problem
  * outranks the status, so a connector whose catalog failed is never
  * "Connected". A failed read marks its connector `connector_unavailable` in
  * the store, so that one code beside a failed read is the page's own and

package/dist/operator-ui/view.js

@@ -425,7 +425,7 @@ function problemAction(problem) {
 /**
  * The verdict the Connectors list, the Overview, Endpoints and a connector's
  * page all show. The server's problem code comes first, then a failed detail
- * read on this page, then a non-ok status, then catalog drift. A problem
+ * read on this page, then a non-ok status. Catalog drift is informational. A problem
  * outranks the status, so a connector whose catalog failed is never
  * "Connected". A failed read marks its connector `connector_unavailable` in
  * the store, so that one code beside a failed read is the page's own and
@@ -443,8 +443,6 @@ export function connectorVerdict(live, signals = {}) {
         const tone = connectorStatusTone(live.status) === "warn" ? "warn" : "danger";
         return { tone, label: connectorStatusLabel(live.status), action: tone === "warn" ? "Connect" : "Inspect" };
     }
-    if (signals.drift)
-        return { tone: "warn", label: "Catalog drift", action: "Review" };
     return { tone: "ok", label: "Connected", action: null };
 }
 /**
@@ -469,7 +467,15 @@ function driftTotal(drift) {
 export function driftState(drift) {
     if (!drift)
         return "unavailable";
-    return driftTotal(drift) > 0 ? "warning" : "clean";
+    if (driftTotal(drift) > 0)
+        return "warning";
+    if (drift.reviewedBaseline !== true ||
+        drift.verification !== "complete" ||
+        !drift.schemaCoverage ||
+        drift.schemaCoverage.unpinned > 0 ||
+        drift.schemaCoverage.pinned === 0)
+        return "unavailable";
+    return "clean";
 }
 /** Every category with its count, so a clean report still shows its zeros. */
 export function driftCounts(drift) {
@@ -483,16 +489,28 @@ export function driftCounts(drift) {
 }
 /** One line naming the state and when it was observed. Never what drifted. */
 export function driftSummary(drift) {
-    const state = driftState(drift);
-    if (state === "unavailable") {
+    if (!drift)
         return "No catalog refresh yet.";
-    }
-    const observed = formatDate(drift?.observedAt);
+    const observed = formatDate(drift.observedAt);
     const when = observed ? ` · observed ${observed}` : "";
-    if (state === "clean")
-        return `Matches the reviewed manifest${when}`;
     const total = driftTotal(drift);
-    return `${total} difference${total === 1 ? "" : "s"} from the reviewed manifest${when}`;
+    const difference = total
+        ? `${total} difference${total === 1 ? "" : "s"}${drift.reviewedBaseline === false ? "" : " from the reviewed manifest"} · `
+        : "";
+    if (drift.reviewedBaseline === false)
+        return `${difference}No reviewed baseline${when}`;
+    if (drift.verification === "unavailable")
+        return `${difference}Schema verification unavailable${when}`;
+    const coverage = drift.schemaCoverage;
+    if (!coverage || coverage.pinned === 0)
+        return `${difference}Schemas not pinned${when}`;
+    if (coverage.unpinned > 0)
+        return `${difference}Partial schema coverage (${coverage.pinned} pinned, ${coverage.unpinned} not pinned)${when}`;
+    if (driftState(drift) === "clean")
+        return `Matches the reviewed manifest${when}`;
+    if (!total)
+        return `Schema verification unavailable${when}`;
+    return `${difference.replace(/ · $/, "")}${when}`;
 }
 /**
  * Only http/https may become a clickable href — the browser half of the gate

package/dist/provider.d.ts

@@ -19,6 +19,8 @@ export interface ProviderOptions {
     authScope?: "shared" | "personal";
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
+    /** Serve only read-classified tools on every endpoint. Defaults to false. */
+    readOnly?: boolean;
     /** Optional per-runtime downstream call-admission policy. */
     callAdmission?: ConnectorCallAdmissionPolicy;
 }
@@ -82,8 +84,11 @@ export declare const CALL_ADMISSION: Omit<Field<unknown, ConnectorCallAdmissionP
     parse(value: unknown, path: string): ConnectorCallAdmissionPolicy;
     readonly shape: typeof admissionPolicy.shape;
 };
+/** Validate the common connector policy before a deployment can serve. */
+export declare const READ_ONLY: Field<boolean, boolean | undefined, true>;
 /** Options every maintained provider shares. */
 export declare const PROVIDER_COMMON: {
+    readOnly: Field<boolean, boolean | undefined, true>;
     callAdmission: Omit<Field<unknown, ConnectorCallAdmissionPolicy | undefined, true>, "parse"> & {
         parse(value: unknown, path: string): ConnectorCallAdmissionPolicy;
         readonly shape: typeof admissionPolicy.shape;
@@ -129,7 +134,7 @@ export interface ProviderContext {
      * Common connector options the deployment set, and only those, ready to
      * spread into `remoteMcp()` or `api()` options.
      */
-    readonly connectorOptions: Readonly<Pick<ProviderOptions, "authScope" | "maxResultBytes" | "callAdmission">>;
+    readonly connectorOptions: Readonly<Pick<ProviderOptions, "authScope" | "maxResultBytes" | "callAdmission" | "readOnly">>;
     /**
      * Render the maintained skill with this connection's context and the
      * deployment's instructions. Instructions are appended; they never replace

package/dist/provider.js

@@ -50,9 +50,17 @@ export const CALL_ADMISSION = {
         return policy;
     },
 };
+/** Validate the common connector policy before a deployment can serve. */
+export const READ_ONLY = opaque({
+    check(value, path) {
+        if (typeof value !== "boolean")
+            throw new ConfigError(`${path} must be a boolean.`);
+    },
+});
 /** Options every maintained provider shares. */
 export const PROVIDER_COMMON = {
     ...keys("title", "authScope", "purpose", "instructions", "maxResultBytes"),
+    readOnly: READ_ONLY,
     callAdmission: CALL_ADMISSION,
 };
 const PROVIDER_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
@@ -127,6 +135,7 @@ export function defineProvider(definition) {
         const connector = frozen.create(id, resolved, {
             ...(frozen.classify !== undefined ? { classify: frozen.classify } : {}),
             connectorOptions: {
+                ...(options.readOnly !== undefined ? { readOnly: options.readOnly } : {}),
                 ...(options.authScope !== undefined ? { authScope: options.authScope } : {}),
                 ...(options.maxResultBytes !== undefined ? { maxResultBytes: options.maxResultBytes } : {}),
                 ...(options.callAdmission !== undefined ? { callAdmission: options.callAdmission } : {}),
@@ -178,6 +187,8 @@ function asProvider(provider, shape, id, options, build) {
     let connector;
     try {
         options = assertKnownOptions(options, `${factory}(${JSON.stringify(id)})`, shape);
+        if (options?.readOnly !== undefined)
+            READ_ONLY.parse(options.readOnly, `${factory}(${JSON.stringify(id)}).readOnly`);
         const admission = options == null ? undefined : options.callAdmission;
         if (admission !== undefined)
             CALL_ADMISSION.parse(admission, `${factory}(${JSON.stringify(id)}).callAdmission`);
@@ -188,12 +199,18 @@ function asProvider(provider, shape, id, options, build) {
     }
     const describe = connector.describe?.bind(connector);
     const ownDescribe = Object.getOwnPropertyDescriptor(connector, "describe");
+    const ownReadOnly = Object.getOwnPropertyDescriptor(connector, "readOnly");
     // Keep the receiver of prototype methods (including private fields). When
     // the description cannot be replaced, inherit the whole connector instead
     // of copying it: decorators may inherit their id, methods, and review.
-    const stamped = Object.isExtensible(connector) && (!ownDescribe || ownDescribe.configurable)
+    const stamped = Object.isExtensible(connector) &&
+        (!ownDescribe || ownDescribe.configurable) &&
+        (options.readOnly === undefined || !ownReadOnly || ownReadOnly.configurable)
         ? connector
         : Object.create(connector);
+    if (options.readOnly !== undefined) {
+        Object.defineProperty(stamped, "readOnly", { value: options.readOnly, enumerable: true, configurable: true });
+    }
     Object.defineProperty(stamped, "describe", {
         configurable: true,
         enumerable: false,

package/dist/providers/_shared/google/workspace.d.ts

@@ -100,6 +100,8 @@ export interface GoogleWorkspaceOptions {
     callAdmission?: ConnectorCallAdmissionPolicy;
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
+    /** Serve only read-classified tools on every endpoint. Defaults to false. */
+    readOnly?: boolean;
     /** API base override for a proxy or test double. */
     baseUrl?: string;
 }
@@ -144,6 +146,7 @@ export declare const GOOGLE_WORKSPACE_OPTIONS: import("../../../config-schema.js
         };
         instructions: import("../../../config-schema.js").Field<unknown, unknown, true>;
         title: import("../../../config-schema.js").Field<unknown, unknown, true>;
+        readOnly: import("../../../config-schema.js").Field<unknown, unknown, true>;
         maxResultBytes: import("../../../config-schema.js").Field<unknown, unknown, true>;
         purpose: import("../../../config-schema.js").Field<unknown, unknown, true>;
         subject: import("../../../config-schema.js").Field<unknown, unknown, true>;

package/dist/providers/_shared/google/workspace.js

@@ -61,7 +61,7 @@ import { tagWorkspaceSubject } from "../../../workspace-subject.js";
 import { delegatedToken, forgetDelegatedToken, parseServiceAccount, } from "./service-account.js";
 /** The closed options every Workspace provider accepts; see `assertKnownOptions`. */
 export const GOOGLE_WORKSPACE_OPTIONS = optionsOf()({
-    ...keys("purpose", "subject", "title", "instructions", "maxResultBytes", "baseUrl"),
+    ...keys("purpose", "subject", "title", "instructions", "maxResultBytes", "baseUrl", "readOnly"),
     // A string is the key's JSON; only the object form has keys to check.
     serviceAccount: optionsOf()(keys("clientEmail", "privateKey", "clientId")),
     callAdmission: CALL_ADMISSION,

package/dist/providers/basecamp/index.d.ts

@@ -27,6 +27,8 @@ export interface BasecampOptions {
     instructions?: string;
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
+    /** Serve only read-classified tools on every endpoint. Defaults to false. */
+    readOnly?: boolean;
     /**
      * Optional per-runtime policy. There is no default: Basecamp's API documents
      * several dynamically adjusted limits (GET versus POST, per second, hour,

package/dist/providers/breeze/index.d.ts

@@ -27,6 +27,8 @@ export interface BreezeOptions {
     callAdmission?: ConnectorCallAdmissionPolicy;
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
+    /** Serve only read-classified tools on every endpoint. Defaults to false. */
+    readOnly?: boolean;
     /** Default `list_people` page size. Defaults to 100; connecta's cap is 1,000. */
     defaultPageSize?: number;
 }

package/dist/providers/ccb/index.d.ts

@@ -98,6 +98,8 @@ export interface CcbOptions {
     callAdmission?: ConnectorCallAdmissionPolicy;
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
+    /** Serve only read-classified tools on every endpoint. Defaults to false. */
+    readOnly?: boolean;
 }
 /** A maintained Church Community Builder (Pushpay ChMS) v2 connection. */
 export declare const ccb: import("../../provider.js").ProviderFactory<CcbOptions>;

package/dist/providers/ccb/index.js

@@ -1651,7 +1651,7 @@ function defaultTitle(environment, mode, writable) {
 }
 /** The closed options ccb() accepts; see `assertKnownOptions`. */
 const CCB_OPTIONS = optionsOf()({
-    ...keys("purpose", "title", "instructions", "environment", "mode", "clientId", "clientSecret", "access", "scopes", "subdomain", "defaultPerPage", "maxResultBytes"),
+    ...keys("purpose", "title", "instructions", "environment", "mode", "clientId", "clientSecret", "access", "scopes", "subdomain", "defaultPerPage", "maxResultBytes", "readOnly"),
     callAdmission: CALL_ADMISSION,
 });
 /** A maintained Church Community Builder (Pushpay ChMS) v2 connection. */

package/dist/providers/cloudflare/index.d.ts

@@ -15,6 +15,8 @@ interface CloudflareCommonOptions {
     instructions?: string;
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
+    /** Serve only read-classified tools on every endpoint. Defaults to false. */
+    readOnly?: boolean;
 }
 /** Cloudflare's hosted MCP server (`search` and `execute`) over OAuth. */
 export interface CloudflareOAuthOptions extends CloudflareCommonOptions {

package/dist/providers/cloudflare/index.js

@@ -68,6 +68,10 @@ const GLOBAL_API_KEY_CREDENTIAL = {
  */
 const CLOUDFLARE_MCP_CLASSIFICATION = {
     tools: {
+        docs: {
+            verdict: "read",
+            reason: "Searches Cloudflare documentation without executing API methods.",
+        },
         search: {
             verdict: "read",
             reason: "Searches the Cloudflare OpenAPI contract without executing API methods.",
@@ -116,7 +120,7 @@ function keyUsageGuide(auth, options) {
 
 REST with ${scheme}. Connector purpose: ${options.purpose}${auth === "globalApiKey" ? global_warning.trimEnd() : ""}${pin}${defaultLine}${key}${shared}${key_tail}${instructionsSection(options.instructions)}`;
 }
-const COMMON = keys("title", "authScope", "purpose", "instructions", "maxResultBytes");
+const COMMON = keys("title", "authScope", "purpose", "instructions", "maxResultBytes", "readOnly");
 const KEY_COMMON = keys("accountId", "zoneId", "baseUrl", "maxConcurrency");
 const PIN = optionsOf()(keys("accountIds", "zoneIds"));
 /** The closed options cloudflare() accepts, selected by `auth.type`; see `assertKnownOptions`. */