@zackbart/connecta 0.37.1 → 0.39.0

package/dist/providers/_shared/rest/value-safety.js

@@ -1,4 +1,5 @@
-// Value safety for every REST vendor (decision 0005): no tool response,
+import { isRecord } from "../json.js";
+// Value safety for every REST vendor: no tool response,
 // success or error, returns a credential (API, service, or bypass tokens,
 // signing secrets, bearer URLs, private keys, temporary credentials, auth
 // headers, authorization verifiers) or a stored secret value (environment
@@ -34,7 +35,7 @@
 // Sent-secret redaction runs first, in the provider kit's parse pass, so a
 // rule that decides on a value can find the placeholder where the vendor
 // wrote what the rule matches. Every such decision input fails closed
-// (#703): an altered type discriminator applies every resource rule; an
+//: an altered type discriminator applies every resource rule; an
 // altered label or type makes a secret record or a header rule; an altered
 // URL scheme or parameter name withholds the whole URL or its value; an
 // altered key withholds its value; a placeholder that may stand for a
@@ -204,10 +205,7 @@ export function credentialName(name) {
     const normalized = normalizedName(name);
     return containsCredential(normalized) || CREDENTIAL_SUFFIX.test(normalized);
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** A rule's test over one decision input; an input redaction altered passes it (#703). */
+/** A rule's test over one decision input; an input redaction altered passes it. */
 function decides(input, test) {
     return typeof input === "string" && (redactionAltered(input) || test(input));
 }
@@ -215,7 +213,7 @@ function decides(input, test) {
 const PLACEHOLDER_KEYS = new WeakSet();
 /**
  * Whether redaction altered one of a record's keys, so no key-based decision
- * about it can be read (#703). Parsed JSON keeps its keys; text the kit
+ * about it can be read. Parsed JSON keeps its keys; text the kit
  * redacted whole and a result hook parsed after it (NDJSON, log streams) can
  * carry the placeholder in one.
  */
@@ -226,7 +224,7 @@ function keysAltered(value) {
 const SCHEME_PREFIX = /^(?:[a-z][a-z0-9+.-]*(?::\/{0,2})?)?$/i;
 /**
  * Whether redaction altered the scheme a whole-string URL decision reads
- * (#703): the text is no longer URL-shaped, everything before its first
+ *: the text is no longer URL-shaped, everything before its first
  * placeholder could begin a URL, and more than placeholders follows it. A
  * URL a vendor sends holds no whitespace.
  */
@@ -434,7 +432,7 @@ function endsValue(text, at) {
 /**
  * Where a word at `start` holds a placeholder in place of a link's scheme
  * and host (`[redacted]/pkg?token=…`, `https:[redacted]…`), or `-1`:
- * redaction took the authority that makes text a link (#703). A Markdown
+ * redaction took the authority that makes text a link. A Markdown
  * label (`[redacted](…)`) is not one; its destination is read as a link.
  */
 function markerLed(text, start) {
@@ -524,7 +522,7 @@ function linkSpan(text, start, host, inline) {
 /**
  * Visit each destination once, respecting its CommonMark close and encoded
  * delimiters. Redaction (`failClosed`) also reads a link whose scheme and
- * host redaction took (#703); admission never does.
+ * host redaction took; admission never does.
  */
 function* linkSpans(text, failClosed = false) {
     const markers = failClosed && redactionAltered(text);
@@ -585,7 +583,7 @@ function credentialQuery(text) {
     const fragment = decoded.indexOf("#");
     if (fragment >= 0) {
         const words = decodeLinkText(decoded.slice(fragment + 1));
-        // A fragment redaction altered cannot be read (#703).
+        // A fragment redaction altered cannot be read.
         if (/token|secret|key|code|auth/i.test(words) || alteredFragment(words))
             return true;
     }
@@ -597,7 +595,7 @@ function credentialQuery(text) {
         const equals = pair.indexOf("=");
         at = end + 1;
         // A component redaction altered with no readable name (its name, or its `=`, taken) may be a
-        // credential parameter's value, however encoded (#703).
+        // credential parameter's value, however encoded.
         if (pair !== REDACTED && redactionAltered(equals < 0 ? pair : pair.slice(0, equals)))
             return true;
         if (equals < 0)
@@ -615,7 +613,7 @@ function withholdLinkQueries(text) {
     let out = "";
     let copied = 0;
     for (const { cut, open, end, start, host } of linkSpans(text, true)) {
-        // A parameter name redaction altered cannot be read, so the whole link goes (#703).
+        // A parameter name redaction altered cannot be read, so the whole link goes.
         const whole = alteredLink(text.slice(host, end));
         if (!whole && (cut < 0 || !credentialQuery(text.slice(cut, end))))
             continue;
@@ -640,7 +638,7 @@ function withholdLinkQueries(text) {
     }
     return copied === 0 ? text : out + text.slice(copied);
 }
-/** Whether redaction altered a parameter name in a link's own path, query, or fragment (#703). */
+/** Whether redaction altered a parameter name in a link's own path, query, or fragment. */
 function alteredLink(link) {
     return redactionAltered(link) && parameterNames(decodeLinkText(link)).some(redactionAltered);
 }
@@ -676,7 +674,7 @@ function withholdSigningParams(anchored) {
 }
 const NAME_CHAR = /[\w.%~;-]/;
 const NAME_ESCAPE = new RegExp(Array.from("abcdefghijklmnopqrstuvwxyz0123456789_.~-", signingName).join("|"), "iy");
-/** Where a parameter's value ends, reading placeholders and character references whole (#703). */
+/** Where a parameter's value ends, reading placeholders and character references whole. */
 function valueEnd(text, at, inferred) {
     while (at < text.length) {
         const reference = Math.max(characterReferenceEnd(text, at, inferred), bareReferenceEnd(text, at, inferred));
@@ -693,7 +691,7 @@ function valueEnd(text, at, inferred) {
 }
 /**
  * The next placeholder that may hide a signing parameter, at or after `from`,
- * and its value boundary when a name is recognized (#703). Redaction may have taken a signing name, its
+ * and its value boundary when a name is recognized. Redaction may have taken a signing name, its
  * `=`, and the start of its value, so a placeholder followed by any of a
  * value's base64 or base64url characters (`+`, `/`, `=`, `-`, `_` included)
  * or `%` escapes goes with them, however short. References count when they
@@ -956,7 +954,7 @@ function labelsOf(value) {
 }
 /**
  * Whether a record's label names a credential, so its value or args are one.
- * A label redaction altered, or keys that may hide one, does too (#703).
+ * A label redaction altered, or keys that may hide one, does too.
  */
 function credentialLabelled(value) {
     if (!isRecord(value))
@@ -966,17 +964,17 @@ function credentialLabelled(value) {
         (isRecord(target) && keysAltered(target)) ||
         labelsOf(value).some((label) => decides(label, credentialName)));
 }
-/** A record typed as a secret (`secret_text`); a type redaction altered may have been one (#703). */
+/** A record typed as a secret (`secret_text`); a type redaction altered may have been one. */
 function typedSecret(value) {
     return keysAltered(value) || decides(value["type"], (type) => /secret/i.test(type));
 }
-/** A list item typed as an environment variable; a type redaction altered may have been one (#703). */
+/** A list item typed as an environment variable; a type redaction altered may have been one. */
 function envTyped(value) {
     if (!isRecord(value))
         return false;
     return keysAltered(value) || decides(String(value["type"]), (type) => /env/i.test(type));
 }
-/** A header, cookie, or query rule (`request.headers`, `header`, `cookie`, `query`, …); likewise (#703). */
+/** A header, cookie, or query rule (`request.headers`, `header`, `cookie`, `query`, …); likewise. */
 function headerLike(value) {
     return isRecord(value) && (keysAltered(value) || decides(value["type"], (type) => /header|cookie|query/i.test(type)));
 }
@@ -989,7 +987,7 @@ function headerValues(value) {
     if (isRecord(value))
         return Object.fromEntries(Object.keys(value).map((name) => [name, REDACTED]));
     if (Array.isArray(value)) {
-        // A pair whose keys redaction altered may hold its value under any of them (#703).
+        // A pair whose keys redaction altered may hold its value under any of them.
         return value.map((item) => !isRecord(item)
             ? item
             : keysAltered(item)
@@ -1120,7 +1118,7 @@ function scrubEnv(value, depth) {
     if (depth > 32)
         return REDACTED;
     if (Array.isArray(value)) {
-        // A `NAME=value` string, or one whose name and `=` redaction may have taken (#703).
+        // A `NAME=value` string, or one whose name and `=` redaction may have taken.
         return value.map((item) => typeof item === "string" && (item.includes("=") || redactionAltered(item)) ? REDACTED : scrubEnv(item, depth + 1));
     }
     if (!isRecord(value))
@@ -1159,7 +1157,7 @@ function scrubValues(value, depth) {
     }
     return out;
 }
-/** Every rule's paths and withheld fields: the rule for an object whose type redaction altered (#703). */
+/** Every rule's paths and withheld fields: the rule for an object whose type redaction altered. */
 const ANY_RULE = new WeakMap();
 function anyRule(resources) {
     let rule = ANY_RULE.get(resources);
@@ -1172,7 +1170,7 @@ function anyRule(resources) {
 }
 /**
  * What a record's type discriminator selects. A type redaction altered, or
- * one an altered key may hide, selects every rule at once (#703).
+ * one an altered key may hide, selects every rule at once.
  */
 function typed(record, key, rules, any) {
     const type = record[key];
@@ -1247,7 +1245,7 @@ function heuristic(value, exempt) {
             if (!exempt.reviewedUrls)
                 return URL_SHAPE.test(current) ? sanitizeUrl(current) : current;
             // A placeholder's own brackets are not Markdown; a URL whose scheme redaction
-            // altered may still carry userinfo, so it is withheld whole (#703).
+            // altered may still carry userinfo, so it is withheld whole.
             const altered = redactionAltered(current);
             if (TEXT.test(altered ? current.replaceAll(REDACTED, "") : current))
                 return current;
@@ -1269,7 +1267,7 @@ function heuristic(value, exempt) {
             const normalized = normalizedName(key);
             const review = Object.hasOwn(exempt.fields, key) ? exempt.fields[key] : undefined;
             if (!placeholders && redactionAltered(key)) {
-                // A key redaction altered may have named a credential (#703).
+                // A key redaction altered may have named a credential.
                 out[key] = withheld(item);
             }
             else if (review?.verdict === "redact") {
@@ -1313,7 +1311,7 @@ function heuristic(value, exempt) {
                 typeof item === "string" &&
                 (URL_SHAPE.test(item) || alteredScheme(item))) {
                 // An external destination can carry its secret in the path; relative paths stay.
-                // One whose scheme redaction altered does not parse, so it is withheld (#703).
+                // One whose scheme redaction altered does not parse, so it is withheld.
                 out[key] = originOnly(item);
             }
             else if (typeof item === "string" && verbatim?.has(key)) {
@@ -1340,6 +1338,53 @@ function acceptsCredential(schema, depth) {
         acceptsCredential(node.items, depth + 1) ||
         (node.anyOf ?? []).some((branch) => acceptsCredential(branch, depth + 1)));
 }
+const ENV_VALUE_NAMES = ENV_VALUE_FIELDS.map(normalizedName);
+/** `data[].id` segments as tokens, a list's items as `[]`: `["data", "[]", "id"]`. */
+function tokensOf(segments) {
+    return segments.flatMap((segment) => segment === "[]"
+        ? ["[]"]
+        : segment.endsWith("[]")
+            ? [normalizedName(segment.slice(0, -2)), "[]"]
+            : [normalizedName(segment)]);
+}
+/**
+ * A best-effort hint for discovery over rules that change every non-null value
+ * they reach: a path is withheld when it sits at or inside a reviewed redaction
+ * path (matched from the body's root, or at any depth with `anyDepth`), or any
+ * of its names satisfies the name rule, which also sees the parent's name.
+ * Paths carry their list markers: a reviewed `[]` needs a declared list there,
+ * while a named segment also reaches every item of a list. Rules that can leave
+ * a value unchanged (`url:`, `origin:` or `#url` sanitizing, `[?…]`, `@keys`)
+ * are not hints. Names compare normalized, and `{}` or `*` matches any name.
+ */
+export function pathWithholds(rules) {
+    const patterns = (rules.paths ?? []).flatMap((raw) => {
+        const { mode, segments } = parsePath(raw);
+        if (mode !== "redact" || segments.some((segment) => segment.startsWith("[?") || segment === "@keys"))
+            return [];
+        return [segments.map((segment) => (segment === "[]" ? "[]" : segment === "{}" ? "*" : normalizedName(segment)))];
+    });
+    const reaches = (pattern, tokens, from) => {
+        let at = from;
+        for (const part of pattern) {
+            if (part !== "[]")
+                while (tokens[at] === "[]")
+                    at += 1;
+            if (at >= tokens.length || (part === "[]" ? tokens[at] !== "[]" : part !== "*" && part !== tokens[at]))
+                return false;
+            at += 1;
+        }
+        return true;
+    };
+    return (path) => {
+        const tokens = tokensOf(path);
+        const names = tokens.filter((token) => token !== "[]");
+        if (rules.names && names.some((name, at) => rules.names(name, names[at - 1] ?? "")))
+            return true;
+        const starts = rules.anyDepth ? tokens.flatMap((token, at) => (token === "[]" ? [] : [at])) : [0];
+        return patterns.some((pattern) => starts.some((at) => reaches(pattern, tokens, at)));
+    };
+}
 /** A vendor's value-safety mechanism over its reviewed table and pinned index. */
 export function valueSafety(table, index) {
     const fields = table.fields ?? {};
@@ -1349,9 +1394,42 @@ export function valueSafety(table, index) {
         const key = `${method} ${template}`;
         return Object.hasOwn(table.operations, key) ? table.operations[key] : undefined;
     };
+    const hints = new Map();
+    const redactedNames = Object.entries(fields)
+        .filter(([, review]) => review.verdict === "redact")
+        .map(([name]) => normalizedName(name));
+    const keptNames = Object.entries(fields)
+        .filter(([, review]) => review.verdict === "keep")
+        .map(([name]) => normalizedName(name));
+    const scopeParents = scopeMaps.map(normalizedName);
     return {
         table,
         verdict,
+        withholds(method, template) {
+            const key = `${method} ${template}`;
+            let hint = hints.get(key);
+            if (!hint) {
+                const reviewed = verdict(method, template);
+                const env = table.envBodies?.test(template) === true;
+                const kept = new Set([
+                    ...keptNames,
+                    ...(reviewed && reviewed.verdict !== "refuse" ? (reviewed.keep ?? []) : []).map((path) => trailOf(path).map(normalizedName).at(-1)),
+                ]);
+                hint =
+                    reviewed?.verdict === "refuse"
+                        ? () => true
+                        : pathWithholds({
+                            paths: reviewed?.verdict === "redact" ? reviewed.paths : [],
+                            names: (name, parent) => redactedNames.includes(name) ||
+                                (env && ENV_VALUE_NAMES.includes(name)) ||
+                                (parent === "deployhooks" && name === "url") ||
+                                // The suffix rule scrubs only strings, so only the whole-value credential rule hints.
+                                (!kept.has(name) && !scopeParents.includes(parent) && containsCredential(name)),
+                        });
+                hints.set(key, hint);
+            }
+            return hint;
+        },
         refusal(method, template) {
             const reviewed = verdict(method, template);
             return reviewed?.verdict === "refuse" ? `Connecta refuses ${method} ${template}. ${reviewed.reason}` : undefined;
@@ -1367,7 +1445,7 @@ export function valueSafety(table, index) {
                 }
                 const resources = table.embeddedUrls.resources;
                 if (resources) {
-                    // A type redaction altered takes every resource's reviewed text paths (#703).
+                    // A type redaction altered takes every resource's reviewed text paths.
                     const all = [...new Set(Object.values(resources.paths).flat())];
                     const any = () => all;
                     const scan = (value, depth) => {

package/dist/providers/breeze/api.js

@@ -1,3 +1,6 @@
+import { Routes, routePhrases } from "../../agent-routes.js";
+import { pathWithholds } from "../_shared/rest/value-safety.js";
+import { asRecord } from "../_shared/json.js";
 // Breeze's reviewed GET-only vendor. HTTP methods do not establish safety: see tools.ts.
 import { Effect, Schema } from "effect";
 import { ConnectorCallError, resendAdvice } from "../../errors.js";
@@ -9,12 +12,6 @@ import { openapi } from "./openapi.generated.js";
 export const DEFAULT_PAGE_SIZE = 100;
 export const MAX_PAGE_SIZE = 1000;
 export const BREEZE_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
-export function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-export function asArray(value) {
-    return Array.isArray(value) ? value : [];
-}
 // --- The read hatch's allowlist ----------------------------------------------
 /** Reviewed observational endpoints and their documented query names. GET alone establishes nothing. */
 export const READ_ENDPOINTS = new Map([
@@ -472,10 +469,11 @@ export const admit = (url) => {
 };
 export const authenticate = Effect.gen(function* () {
     const values = yield* (yield* Credentials).values.pipe(Effect.mapError((error) => new Refusal({ error })));
+    const routes = yield* Routes;
     const key = values?.["value"]?.trim();
     if (!key)
         return yield* Effect.fail(new Refusal({
-            error: new ConnectorCallError("auth_required", "No Breeze API key is configured for this connector. Call authorize_connector for recovery options. When available, an operator can add the key in this connection in the operator UI."),
+            error: new ConnectorCallError("auth_required", `No Breeze API key is configured for this connector. ${routePhrases(routes).authorizeFor("recovery options")}. When available, an operator can add the key in this connection in the operator UI.`),
         }));
     return { "Api-Key": key };
 });
@@ -542,6 +540,9 @@ export const breezeSafety = {
             })(),
         }),
         redact: (body, op) => withoutCalendarFeeds(op.template, body),
+        withholds: (op) => op.template === "/events/calendars/list"
+            ? pathWithholds({ names: (name) => name === "address" || name === "embedkey" })
+            : () => false,
         withholdsErrors: () => false,
     },
     sensitiveFields: { names: [], choice: "drop" },
@@ -551,7 +552,7 @@ function shortText(value, secrets) {
         return value.trim() || undefined;
     if (value === undefined || value === null)
         return undefined;
-    // The kit redacted the answer's values and kept its keys (#703); serialized, a key is text
+    // The kit redacted the answer's values and kept its keys; serialized, a key is text
     // the cut below could split, so the whole text is checked before it is cut.
     const text = secrets.redact(JSON.stringify(value));
     return text.length > 300 ? `${text.slice(0, 300)}…` : text;

package/dist/providers/breeze/index.js

@@ -1,8 +1,10 @@
+import { readOnlyNotice } from "../_shared/guide.js";
+import { asRecord } from "../_shared/json.js";
 import { skill } from "./skill.generated.js";
 import { keys, optionsOf } from "../../config-schema.js";
 import { PROVIDER_COMMON } from "../../connectors/option-shapes.js";
 import { defineApiProvider } from "../../http/provider.js";
-import { accountSummary, admit, asRecord, authenticate, BreezeApi, breezeSafety, BREEZE_MAX_RESPONSE_BYTES, BREEZE_INDEX, BREEZE_VERDICTS, BREEZE_NAMED, breezePeoplePage, DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, errors, result, } from "./api.js";
+import { accountSummary, admit, authenticate, BreezeApi, breezeSafety, BREEZE_MAX_RESPONSE_BYTES, BREEZE_INDEX, BREEZE_VERDICTS, BREEZE_NAMED, breezePeoplePage, DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, errors, result, } from "./api.js";
 import { breezeTools } from "./tools.js";
 export const BREEZE_HOST_SUFFIX = ".breezechms.com";
 const SUBDOMAIN_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
@@ -68,7 +70,7 @@ export const breeze = defineApiProvider({
             `Church database: ${normalizeSubdomain(options.subdomain)}${BREEZE_HOST_SUFFIX}.`,
             `Church purpose: ${options.purpose}`,
             "Calendar feed addresses and embed keys are always removed; profile details follow the requested vendor detail level.",
-            ...(options.readOnly ? ["This connection is read-only: every write is refused."] : []),
+            ...readOnlyNotice(options.readOnly),
             ...(options.defaultPageSize !== undefined
                 ? [`Paged lists return ${options.defaultPageSize} items by default on this connection.`]
                 : []),

package/dist/providers/breeze/skill.generated.js

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Church records\n\nBreeze ChMS (now Tithely Church Management) holds people, tags, events,\nattendance, forms, volunteers and giving. People carry contact information,\nbirthdates and family ties; giving reveals donors and amounts. Reduce records\nin code and return only the names, counts or totals the task needs.\n\n## Ids and joins\n\nIds are numeric strings. Resolve them from the relevant inventory before\nwriting. Events have an occurrence id and a series `eventId`; attendance,\nvolunteers and check-in use the occurrence id. Event and pledge lists can lag\nup to 15 minutes behind the site. An all-zero MySQL date means no time was\nrecorded, including no check-out.\n\nProfile `details` use field ids, not names. Resolve field and option ids from\n`list_profile_fields`; multiple-choice filters join option ids with `-`.\nA person-name lookup requires listing people and matching in code. Form entry\nresponses similarly join to that form's field ids.\n\n## Giving\n\nGiving, funds and pledges use archival endpoints removed from the public\nreference in 2023. They can change or vanish without notice. Amounts are\nexact decimal strings: reduce them with integer-cent arithmetic, and read the\ncurrency from `get_account_summary`. A split gift's fund amounts belong to\nits fund ids. Tithe.ly deposits sync in batches, so recent gifts can be absent.\nEditing a giving transaction may return a new payment id.\nUse `limit: 1000` when reducing broad giving ranges: each local page refetches\nthe bounded vendor list, so larger windows avoid repeated full-list fetches.\n\n## Required sequences\n\nCheck for an existing person before adding one: creation does not deduplicate.\nResolve profile fields before updating them. Text, dates (M/D/YYYY) and option\nids use `response`; email, phone, address and family-role values use `details`.\nNamed person writes take these entries in `values`.\nFamily changes can remove previous associations. Attendance check-out records\na departure time; removing attendance deletes the record instead.\n\nBreeze sends writes as GET requests too. Query names ending in `_json` take\nJSON-encoded strings. The named person writes encode their typed profile values\nfor you. The account-log `object_json` is a serialized affected-object value;\nits free-text description has no stable schema. Events and account logs have\nvendor caps: narrow the date range when the result fills its limit.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `breeze_api_details`, `breeze_api_search`, `list_attendance`, `list_contributions`, `list_funds`, `list_people`, `list_profile_fields`, `list_tags`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `breeze_api_read`, put it in `query[page.param]` or `body[page.param]`, as `page.in` specifies. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 100, at most 1000). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Hatch:** `breeze_api_search` finds this API's operations and reads no account data, `breeze_api_details` shows one operation's contract, and `breeze_api_read` calls a reviewed read. `breeze_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. It documents no conflict.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
+    "content": "## Church records\n\nBreeze ChMS (now Tithely Church Management) holds people, tags, events,\nattendance, forms, volunteers and giving. People carry contact information,\nbirthdates and family ties; giving reveals donors and amounts. Reduce records\nin code and return only the names, counts or totals the task needs.\n\n## Ids and joins\n\nIds are numeric strings. Resolve them from the relevant inventory before\nwriting. Events have an occurrence id and a series `eventId`; attendance,\nvolunteers and check-in use the occurrence id. Event and pledge lists can lag\nup to 15 minutes behind the site. An all-zero MySQL date means no time was\nrecorded, including no check-out.\n\nProfile `details` use field ids, not names. Resolve field and option ids from\n`list_profile_fields`; multiple-choice filters join option ids with `-`.\nA person-name lookup requires listing people and matching in code. Form entry\nresponses similarly join to that form's field ids.\n\n## Giving\n\nGiving, funds and pledges use archival endpoints removed from the public\nreference in 2023. They can change or vanish without notice. Amounts are\nexact decimal strings: reduce them with integer-cent arithmetic, and read the\ncurrency from `get_account_summary`. A split gift's fund amounts belong to\nits fund ids. Tithe.ly deposits sync in batches, so recent gifts can be absent.\nEditing a giving transaction may return a new payment id.\nUse `limit: 1000` when reducing broad giving ranges: each local page refetches\nthe bounded vendor list, so larger windows avoid repeated full-list fetches.\n\n## Required sequences\n\nCheck for an existing person before adding one: creation does not deduplicate.\nResolve profile fields before updating them. Text, dates (M/D/YYYY) and option\nids use `response`; email, phone, address and family-role values use `details`.\nNamed person writes take these entries in `values`.\nFamily changes can remove previous associations. Attendance check-out records\na departure time; removing attendance deletes the record instead.\n\nBreeze sends writes as GET requests too. Query names ending in `_json` take\nJSON-encoded strings. The named person writes encode their typed profile values\nfor you. The account-log `object_json` is a serialized affected-object value;\nits free-text description has no stable schema. Events and account logs have\nvendor caps: narrow the date range when the result fills its limit.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `breeze_api_details`, `breeze_api_search`, `list_attendance`, `list_contributions`, `list_funds`, `list_people`, `list_profile_fields`, `list_tags`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `breeze_api_read`, put it in `query[page.param]` or `body[page.param]`, as `page.in` specifies. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 100, at most 1000). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Hatch:** `breeze_api_search` finds this API's operations and reads no account data, `breeze_api_details` shows one operation's contract, and `breeze_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `breeze_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. It documents no conflict.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
     "instructionsHeading": "Church instructions"
 };

package/dist/providers/breeze/tools.js

@@ -1,17 +1,16 @@
+import { asArray, asRecord } from "../_shared/json.js";
+import { compact } from "../_shared/json.js";
 // Breeze's curated surface: projections and profile encoders earn named tools; the standard hatch supplies coverage.
 import { Effect, Schema } from "effect";
 import { ConnectorCallError } from "../../errors.js";
 import { Refusal } from "../../http/errors.js";
 import { Integer, isMinChars, isMaxChars } from "../../http/json-schema.js";
 import { RequestSecrets, Classification } from "../../http/services.js";
-import { fieldsInput, fieldsProblem, selectFields } from "../../http/fields.js";
+import { fieldsContract, selectFields } from "../../http/fields.js";
 import { read, list, write as writeTool } from "../../http/tools.js";
-import { asArray, asRecord, READ_ENDPOINTS } from "./api.js";
+import { READ_ENDPOINTS } from "./api.js";
 const DEFAULT_EVENT_LIMIT = 100;
 const ObjectValue = Schema.Record(Schema.String, Schema.Unknown);
-function compact(value) {
-    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
-}
 function timestamp(value) {
     if (value === undefined)
         return undefined;
@@ -219,6 +218,7 @@ const Result_list_events = Schema.Struct({
 });
 const Row_list_events = Result_list_events.fields.events.value;
 const SelectedEvent = Schema.Struct(Object.fromEntries(Object.entries(Row_list_events.fields).map(([name, schema]) => [name, Schema.optionalKey(schema)])));
+const EVENT_FIELDS = fieldsContract("item", SelectedEvent);
 const Result_list_attendance = Schema.Struct({
     "attendance": Schema.Array(Schema.Struct({
         "personId": Schema.String,
@@ -528,7 +528,7 @@ export function breezeTools({ connection, pageSize: defaultPageSize, }) {
                     description: "Instances returned, 1 to Breeze's 1000. Defaults to 100.",
                     default: 100,
                 })),
-                fields: Schema.optionalKey(fieldsInput("Dot paths to keep in each event item.")),
+                fields: Schema.optionalKey(EVENT_FIELDS.input),
             }),
             output: Schema.Struct({
                 items: Schema.Array(SelectedEvent),
@@ -536,7 +536,7 @@ export function breezeTools({ connection, pageSize: defaultPageSize, }) {
                 truncated: Schema.optionalKey(Schema.Array(Schema.String)),
             }),
             run: (args) => Effect.gen(function* () {
-                const error = fieldsProblem(args.fields, new Set(Object.keys(Row_list_events.fields)), "an event item");
+                const error = EVENT_FIELDS.problem(args.fields);
                 if (error)
                     return yield* Effect.fail(new Refusal({ error }));
                 const result = yield* load_list_events(args);

package/dist/providers/ccb/api.js

@@ -1,3 +1,5 @@
+import { asRecord, asArray } from "../_shared/json.js";
+import { routePhrases } from "../../agent-routes.js";
 import { CCB_MEDIA_TYPE, CCB_ENVIRONMENTS, CCB_READ_SCOPES, CCB_WRITE_SCOPES, CCB_SENSITIVE_FIELDS, } from "./lib/constants.js";
 // Pushpay ChMS v2 JSON contracts, OAuth, status meanings, admission and privacy.
 // The legacy per-church XML API is outside this provider's scope.
@@ -56,12 +58,6 @@ export const CCB_ADMISSION = {
         },
     ],
 };
-function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-function asArray(value) {
-    return Array.isArray(value) ? value : [];
-}
 // ---------------------------------------------------------------------------
 // Admission partitions
 // ---------------------------------------------------------------------------
@@ -470,7 +466,7 @@ export const errors = {
     statuses: {
         401: () => ({
             code: "auth_required",
-            words: (detail) => `${detail} CCB rejected the connection's access token. Call authorize_connector for this connector.`,
+            words: (detail, routes) => `${detail} CCB rejected the connection's access token. ${routePhrases(routes).authorizeFor("this connector")}.`,
             advice: ", then retry",
         }),
         403: () => ({

package/dist/providers/ccb/index.js

@@ -1,3 +1,4 @@
+import { readOnlyNotice } from "../_shared/guide.js";
 import { CCB_ENVIRONMENTS, CCB_MEDIA_TYPE } from "./lib/constants.js";
 import { skill } from "./skill.generated.js";
 import { keys, optionsOf } from "../../config-schema.js";
@@ -46,6 +47,11 @@ export const ccb = defineApiProvider({
         note: "./providers/ccb merged GitHub/Cloudflare/CCB step-2 snapshot measures 391,649 B standalone gzip-9 before recording these bundle facts, Node 26.12.0 with zlib-ng 1.3.1; recomputed with the combined opt-in hatch support. Earlier step-2 standalone gzip snapshot at ffd64b04, CI run 40080865116 static job, Node 22.23.3, against main ce0c7492 (345,272 B). Includes the reviewed 385-operation request/response index. Shared Effect is paid once per deployment; provider entries are reported, uncapped and non-additive (#703) (#899).",
     },
     skill,
+    // The guide resolves a person from individuals and a household from families.
+    searchSynonyms: [
+        ["person", "individual"],
+        ["household", "family"],
+    ],
     options: CCB_OPTIONS,
     displayTitle: (options) => defaultTitle(options.environment, options.mode, writable(options)),
     description: (options) => `Church Community Builder (Pushpay ChMS) — ${routingLine(options.environment, options.mode, writable(options))}: ${options.purpose}`,
@@ -70,7 +76,7 @@ export const ccb = defineApiProvider({
             ...(!writable(options)
                 ? ["Configured scopes permit only reads: ccb_api_write is omitted and writes are refused."]
                 : []),
-            ...(options.readOnly ? ["This connection is read-only: every write is refused."] : []),
+            ...readOnlyNotice(options.readOnly),
             ...(options.defaultPerPage !== undefined
                 ? [`Named lists default to ${options.defaultPerPage} rows on this connection.`]
                 : []),

package/dist/providers/ccb/skill.generated.js

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## People, households and groups\n\nCCB v2 addresses records by integer ids. Resolve a person from the individual\nlist and a household from families; never guess ids. Family membership and\nchurch group membership join by individual id. A membership role belongs to\nthat group, rather than being a property of the person everywhere.\n\nIdentity Auth acts with the signed-in person's permissions. A permission\nrefusal can mean that person lacks access even when the connection is healthy.\n\n## Events and attendance\n\nAn event is a series; its dated occurrence is a separate identity. Attendance\njoins need both the event id and occurrence. Preserve the vendor's date and\ntime-zone meaning instead of treating every occurrence as UTC midnight.\n\n## Pastoral and financial records\n\nNotes, background checks, pledges and giving metrics can be sensitive. Read\nonly what the task needs and reduce those records inside execute_code before\nreturning an answer. Gift metrics are counts by period, with a range of at\nmost twelve months. Per-gift transactions and amounts belong to the legacy\nv1 XML API, which this v2 connector does not reach.\n\n## Vendor call rates and recovery\n\nCCB meters endpoints separately per API client. Individual profile reads have\nno burst; individual advanced searches allow one call per five seconds, and\ncategory schedule lists allow one per two seconds. Prefer list pages over a\nloop of individual gets. Other deployments sharing the client spend from the\nsame vendor allowance.\n\nFor a profile edit, resolve the individual first and preserve fields outside\nthe requested change. Use `ccb_api_write` for the edit; the host may ask the\nuser to confirm. After an ambiguous update, read that profile to determine\nwhat actually changed before deciding whether another write is needed.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `ccb_api_details`, `ccb_api_read`, `ccb_api_search`, `list_event_attendees`, `list_events`, `list_families`, `list_group_members`, `list_groups`, `list_individual_groups`, `list_individual_notes`, `list_individuals`, `search_records`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 25, at most 100). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Hatch:** `ccb_api_search` finds this API's operations and reads no account data, `ccb_api_details` shows one operation's contract, and `ccb_api_read` calls a reviewed read. `ccb_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 14 operations are refused by design; use `ccb_api_details` with the method and path to inspect the original operation summary and its separate refusal. Use details for refused methods outside the read/write call schemas; those methods remain unavailable.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. It documents no conflict.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
+    "content": "## People, households and groups\n\nCCB v2 addresses records by integer ids. Resolve a person from the individual\nlist and a household from families; never guess ids. Family membership and\nchurch group membership join by individual id. A membership role belongs to\nthat group, rather than being a property of the person everywhere.\n\nIdentity Auth acts with the signed-in person's permissions. A permission\nrefusal can mean that person lacks access even when the connection is healthy.\n\n## Events and attendance\n\nAn event is a series; its dated occurrence is a separate identity. Attendance\njoins need both the event id and occurrence. Preserve the vendor's date and\ntime-zone meaning instead of treating every occurrence as UTC midnight.\n\n## Pastoral and financial records\n\nNotes, background checks, pledges and giving metrics can be sensitive. Read\nonly what the task needs and reduce those records inside execute_code before\nreturning an answer. Gift metrics are counts by period, with a range of at\nmost twelve months. Per-gift transactions and amounts belong to the legacy\nv1 XML API, which this v2 connector does not reach.\n\n## Vendor call rates and recovery\n\nCCB meters endpoints separately per API client. Individual profile reads have\nno burst; individual advanced searches allow one call per five seconds, and\ncategory schedule lists allow one per two seconds. Prefer list pages over a\nloop of individual gets. Other deployments sharing the client spend from the\nsame vendor allowance.\n\nFor a profile edit, resolve the individual first and preserve fields outside\nthe requested change. Use `ccb_api_write` for the edit; the host may ask the\nuser to confirm. After an ambiguous update, read that profile to determine\nwhat actually changed before deciding whether another write is needed.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `ccb_api_details`, `ccb_api_read`, `ccb_api_search`, `list_event_attendees`, `list_events`, `list_families`, `list_group_members`, `list_groups`, `list_individual_groups`, `list_individual_notes`, `list_individuals`, `search_records`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 25, at most 100). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Hatch:** `ccb_api_search` finds this API's operations and reads no account data, `ccb_api_details` shows one operation's contract, and `ccb_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `ccb_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 14 operations are refused by design; use `ccb_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. It documents no conflict.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
     "instructionsHeading": "Church instructions"
 };

package/dist/providers/ccb/tools.js

@@ -1,3 +1,4 @@
+import { asRecord, asArray } from "../_shared/json.js";
 // CCB v2 curated projections, bound numbered pages and reviewed POST data search.
 import { Effect, Schema } from "effect";
 import { ConnectorCallError } from "../../errors.js";
@@ -7,12 +8,6 @@ import { Refusal } from "../../http/errors.js";
 import { Integer, isMinChars, isMaxChars } from "../../http/json-schema.js";
 import { read, list } from "../../http/tools.js";
 import { callCcb, DEFAULT_PER_PAGE, SEARCH_DOMAINS, CCB_INDEX, ccbPageInfo, } from "./api.js";
-function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-function asArray(value) {
-    return Array.isArray(value) ? value : [];
-}
 function compact(value) {
     return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined && entry !== null));
 }

package/dist/providers/cloudflare/api.js

@@ -1,3 +1,4 @@
+import { decodeBase64 } from "../../bytes.js";
 // Cloudflare's pinned REST contracts, confinement, framing and failure semantics.
 import { responseMedia } from "../_shared/rest/response-media.js";
 import { EXCLUSIVE_PATH_IDS } from "./lib/path-bounds.js";
@@ -396,8 +397,7 @@ export class RawUpload {
 }
 export function bytesFromBase64(value, field) {
     try {
-        const binary = atob(value);
-        return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+        return decodeBase64(value);
     }
     catch {
         return invalid(`${field} must be valid base64.`);
@@ -433,7 +433,7 @@ class CloudflareIndex extends OperationIndex {
         for (const name of EXCLUSIVE_PATH_IDS[`${match.op.method} ${match.op.path}`] ?? []) {
             if (Number(decodeURIComponent(match.params[name])) < 1) {
                 throw new ConnectorCallError("invalid_args", `Not sent: Cloudflare path parameter ${name} must be at least 1. Read cloudflare_api_details for the pinned contract.`, {
-                    validation: { issues: [{ path: `/path/${name}`, code: "minimum", expected: "at least 1" }] },
+                    validation: { issues: [{ path: `/path/${name}`, expected: "at least 1" }] },
                 });
             }
         }
@@ -528,6 +528,13 @@ export const safety = () => {
                 }
                 : SAFETY.redact(body, operation.method, canonical(operation)),
             withholdsErrors: (operation) => operation.method === "POST" && operation.template === "/graphql" ? false : reviewed.withholdsErrors(operation),
+            // The table applies to the envelope and again to its result, as redact does.
+            withholds: (operation) => {
+                const hint = reviewed.withholds(operation);
+                return (path) => hint(path) ||
+                    (path[0] === "result" && hint(path.slice(1))) ||
+                    (path[0] === "result[]" && hint(["[]", ...path.slice(1)]));
+            },
         },
         sensitiveFields: { names: [], choice: "drop" },
     };

package/dist/providers/cloudflare/index.js

@@ -1,3 +1,4 @@
+import { readOnlyNotice } from "../_shared/guide.js";
 import { skill } from "./skill.generated.js";
 import { keys, optionsOf, variants } from "../../config-schema.js";
 import { CALL_ADMISSION } from "../../provider.js";
@@ -90,7 +91,7 @@ function usageGuide(options) {
                 : ["No additional deployment pin: the credential's vendor permissions define its reachable estate."]),
             ...(accountId ? [`Default account id: ${accountId}.`] : []),
             ...(zoneId ? [`Default zone id: ${zoneId}.`] : []),
-            ...(options.readOnly ? ["This connection is read-only: every write is refused."] : []),
+            ...readOnlyNotice(options.readOnly),
         ],
         required: true,
     };

package/dist/providers/cloudflare/safety.js

@@ -1,4 +1,4 @@
-// Cloudflare's reviewed value-safety table (#801), on the shared mechanism in
+// Cloudflare's reviewed value-safety table, on the shared mechanism in
 // `../_shared/rest/value-safety.ts`: every operation the detector flags in
 // the pinned spec (`value-safety.candidates.json`) has one verdict here, and
 // `value-safety.node.test.ts` runs the shared harness over it.
@@ -16,7 +16,7 @@
 // Paths are dot paths into the data a tool returns (Cloudflare's `result`,
 // or the whole body when it is not an envelope); lists are traversed
 // implicitly and `*` matches every key of an object.
-// Embedded URL verdict (#812): reviewed paths + global signing parameters.
+// Embedded URL verdict: reviewed paths + global signing parameters.
 // Evidence: digest-verified schema revision 843eae2fbf4fe774ef9c91021dd34017ac9c970a:
 // builds_BuildLogsResponse.lines (timestamp/log-message tuples),
 // pages_deployment_log.data.line and workers-observability_query_results
@@ -869,7 +869,7 @@ const OPERATIONS = {
         key,
         safe(DESCRIBED_ONLY, "geo_restrictions", "policy_restrictions", "certificates.geo_restrictions"),
     ])),
-    // Round 3 (#801): candidates the consolidated detector surfaced (the union
+    // Round 3: candidates the consolidated detector surfaced (the union
     // of the two former detectors, with transfer, claim, invite, key, signing,
     // and webhook families).
     [`GET ${A}/abuse-reports/submitted/{report_id}`]: safe("An abuse report; the authorization statement is the reporter's text."),