@zackbart/connecta 0.41.0 → 0.42.0

package/dist/program-result.js

@@ -3,3 +3,5 @@ export const PROGRAM_RESULT_INLINE_BYTES = 1024 * 1024;
 /** Leave room for the bridge envelope and six-character JSON escapes per byte. */
 export const PROGRAM_RESULT_PAGE_BYTES = 32 * 1024;
 export const PROGRAM_RESULT_WIRE_BYTES = 240 * 1024;
+/** What `connecta.result(id, { all: true })` delivers unless the executor says less. */
+export const PROGRAM_RESULT_READ_BYTES = 1.5 * 1024 * 1024;

package/dist/program-source.js

@@ -6,7 +6,7 @@ const FENCE = /^```[\w-]*\s*\n([\s\S]*?)\n?```$/;
 /** Intake accepts one JavaScript fence, optionally surrounded by prose. */
 const PROGRAM_FENCE = /^```(?:js|javascript)?[ \t]*\r?\n([\s\S]*?)\r?\n```[ \t]*$/gm;
 /** Leading whitespace and comments, which may precede the arrow expression. */
-const LEADING_TRIVIA = /^(?:\s+|\/\/[^\n]*|\/\*[\s\S]*?\*\/)+/;
+export const LEADING_TRIVIA = /^(?:\s+|\/\/[^\n]*|\/\*[\s\S]*?\*\/)+/;
 /** One character of an identifier, keyword, or number; `\\` for escapes. */
 const WORD = /[\w$\\\u0080-\uffff]/;
 /**

package/dist/program-writes.js

@@ -3,9 +3,35 @@ import { toolError } from "./tool-error.js";
 // Await each dispatched write once; never conceal an unknown outcome.
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import { Effect } from "effect";
+import { clipText, MAX_TOOL_ERROR_BYTES } from "./errors.js";
 import { classifyWriteOutcome } from "./write-outcome.js";
 /** Writes one program may send (`execute.maxWrites`), unless configured. */
 export const DEFAULT_MAX_WRITES = CONFIG_DEFAULTS.execute.maxWrites;
+/** Unknown writes one run retains and reports. */
+const MAX_REPORTED_WRITES = 10;
+/** UTF-16 code units per write, so its UTF-8 size can reach three times this. */
+const RETAINED_UNITS = 4 * MAX_TOOL_ERROR_BYTES;
+/** Serialized bytes of the whole report: two full messages, or more shorter ones. */
+const MAX_REPORT_BYTES = 2 * MAX_TOOL_ERROR_BYTES;
+/** Room kept for what joins the result after the report: counters and a quoted address. */
+const RESULT_RESERVE = 256;
+const CHECK_UNKNOWN_WRITE = "Read its target to see whether it applied before anything depends on it.";
+const UNKNOWN_WRITE_ARGS = "Echoed arguments may be partial or absent; use your original arguments for further calls.";
+const NO_PROGRAM_RERUN = "Do not rerun this program: writes it already sent would repeat. If a tool's words call for a further call, send only that operation, as a new call.";
+const encoder = new TextEncoder();
+const serializedBytes = (value) => encoder.encode(JSON.stringify(value)).length;
+/** `text` clipped so its JSON string fits `room` bytes, or nothing when not even the marker does. */
+function fitted(text, room) {
+    let budget = room;
+    let clipped = clipText(text, budget);
+    for (let size = serializedBytes(clipped); size > room; size = serializedBytes(clipped)) {
+        if (budget <= 0)
+            return undefined;
+        budget = Math.floor((budget * room) / size) - 1;
+        clipped = clipText(text, Math.max(0, budget));
+    }
+    return clipped;
+}
 /** What a dispatched write's outcome says about whether it landed. */
 export function writeStateOf(outcome) {
     const state = classifyWriteOutcome(outcome.ok
@@ -19,22 +45,33 @@ export function writeStateOf(outcome) {
     if (state !== "unknown" || outcome.ok)
         return state;
     const { error } = outcome;
+    const text = outcome.failureText ?? error.message;
     const handoff = (error.code === "auth_required" || error.code === "downstream_oauth_required") &&
         error.nextAction &&
-        "tool" in error.nextAction &&
-        error.nextAction.tool === "authorize_connector"
+        error.connector !== undefined
         ? {
             code: error.code,
-            ...(error.connector !== undefined ? { connector: error.connector } : {}),
+            connector: error.connector,
             ...(error.recovery !== undefined ? { recovery: error.recovery } : {}),
-            nextAction: error.nextAction,
+            // This terminal result carries no handoff fields, so it never holds a link:
+            // the agent fetches one, whatever the call's own error was given.
+            nextAction: {
+                tool: "authorize_connector",
+                arguments: { connector: error.connector },
+                operatorHandoff: "Give the URL and instructions it returns to the operator.",
+            },
             ...(error.retry !== undefined ? { retry: error.retry } : {}),
         }
         : undefined;
-    if (!error.uncertainCall && !handoff)
-        return state;
     return {
         state,
+        failure: {
+            ...(outcome.resolved ? { address: `${outcome.resolved.connector.id}.${outcome.resolved.toolName}` } : {}),
+            code: error.code,
+            ...(error.toolAnswered ? { toolAnswered: true } : {}),
+            text: text.slice(0, RETAINED_UNITS),
+            cut: text.length > RETAINED_UNITS,
+        },
         ...(error.uncertainCall ? { uncertainCall: error.uncertainCall } : {}),
         ...(error.uncertainCall && error.details?.stage !== undefined
             ? {
@@ -61,6 +98,8 @@ export class ProgramWrites {
     closed = false;
     inFlight = new Set();
     states = [];
+    unknownWrites = [];
+    unknownWritesTruncated = false;
     uncertainCalls = [];
     uncertainCallsTruncated = false;
     deadlines = [];
@@ -90,6 +129,10 @@ export class ProgramWrites {
             recorded = true;
             const state = typeof completion === "string" ? completion : completion.state;
             if (typeof completion !== "string") {
+                if (this.unknownWrites.length < MAX_REPORTED_WRITES)
+                    this.unknownWrites.push(completion.failure);
+                else
+                    this.unknownWritesTruncated = true;
                 if (completion.uncertainCall) {
                     if (this.uncertainCalls.length < 10)
                         this.uncertainCalls.push(completion.uncertainCall);
@@ -105,6 +148,10 @@ export class ProgramWrites {
             done();
         };
     }
+    /** Whether this run dispatched any write, whatever became of it. */
+    get sent() {
+        return this.states.length > 0 || this.inFlight.size > 0;
+    }
     /** Wait for dispatched writes, each bounded by its host-call deadline. */
     drain() {
         return Effect.promise(async () => {
@@ -112,7 +159,29 @@ export class ProgramWrites {
                 await Promise.all(this.inFlight);
         });
     }
-    finish(result) {
+    /**
+     * What each unknown write said, checked against the run's final credentials and only
+     * then cut, so a credential a later call registered matches whole. A retained text
+     * was itself cut, so it also loses any unfinished tail. `room` bounds the serialized report.
+     */
+    report(secrets, room) {
+        const entries = [];
+        let truncated = this.unknownWritesTruncated;
+        let left = room;
+        for (const { text, cut, ...facts } of this.unknownWrites) {
+            left -= serializedBytes(facts) + 12;
+            if (left < 0)
+                return { entries, truncated: true };
+            const message = fitted(cut ? secrets.redactOpenTail(text) : secrets.text(text), Math.min(left, MAX_TOOL_ERROR_BYTES));
+            if (message === undefined)
+                truncated = true;
+            else
+                left -= serializedBytes(message);
+            entries.push({ ...facts, ...(message === undefined ? {} : { message }) });
+        }
+        return { entries, truncated };
+    }
+    finish(result, secrets, maxResultChars) {
         if (this.states.length === 0)
             return result;
         const writes = {
@@ -125,11 +194,8 @@ export class ProgramWrites {
             // the result, as a direct call reports it: its code and handoff, never
             // retryable, with the write's outcome unknown.
             const handoff = this.handoff;
-            return toolError({
+            const facts = {
                 code: handoff?.code ?? "write_outcome_unknown",
-                message: handoff
-                    ? "A write this program sent failed authorization after it left, so whether it took effect is unknown, and that is the result rather than what the program returned. It will not be sent again. Check its target before doing anything that depends on it, and give nextAction to the operator to recover the connector. Argument echoes may be partial or absent; use the original arguments if reconciliation requires another call."
-                    : "A write this program sent has no known outcome, so that is the result rather than what the program returned. It will not be sent again. Check its target before doing anything that depends on it. Argument echoes may be partial or absent; use the original arguments if reconciliation requires another call.",
                 retryable: false,
                 ...(handoff ? { ...handoff, reconciliationRequired: true, writeOutcome: "unknown" } : {}),
                 ...(this.deadlines.length > 0 ? { details: this.deadlines[0] } : {}),
@@ -141,6 +207,24 @@ export class ProgramWrites {
                         : {}),
                 ...(this.uncertainCallsTruncated ? { uncertainCallsTruncated: true } : {}),
                 writes,
+            };
+            const advice = handoff
+                ? `A write this program sent failed authorization after it left, so its outcome is unknown and the program's return was discarded. It will not be resent. ${CHECK_UNKNOWN_WRITE} Then give what nextAction returns to the operator to recover the connector. ${NO_PROGRAM_RERUN} ${UNKNOWN_WRITE_ARGS}`
+                : `A write this program sent has an unknown outcome, and the program's return was discarded. It will not be resent. ${CHECK_UNKNOWN_WRITE} ${NO_PROGRAM_RERUN} ${UNKNOWN_WRITE_ARGS}`;
+            const { entries, truncated } = this.report(secrets, Math.min(MAX_REPORT_BYTES, maxResultChars - RESULT_RESERVE - serializedBytes({ error: { ...facts, message: advice } })));
+            // The first tool's own words lead, once: they may be the only way forward. An
+            // authorization verdict keeps its lead, since recovery starts with the connector.
+            const quoted = handoff ? undefined : entries.find((entry) => entry.toolAnswered && entry.message !== undefined);
+            const words = quoted?.message;
+            if (quoted)
+                delete quoted.message;
+            return toolError({
+                message: quoted
+                    ? `${quoted.address ?? "A tool"} answered: ${words}\n\nGive the user any approval link or request id above. ${advice}`
+                    : advice,
+                ...(entries.length > 0 ? { unknownWrites: entries } : {}),
+                ...(truncated ? { unknownWritesTruncated: true } : {}),
+                ...facts,
             });
         }
         return result.isError ? withWrites(result, writes) : result;
@@ -149,20 +233,29 @@ export class ProgramWrites {
 /**
  * An error result from a program that sent writes, carrying their counts: a
  * program that fails after writing is not a program that is safe to repeat.
+ * Whatever ended the run, once a write has landed the program is not retryable
+ * and no wait window invites it (INV-9). A failed write is proven not applied,
+ * so failed writes alone leave the failure's own verdict standing.
  */
 function withWrites(result, writes) {
     const structured = result.structuredContent;
     const error = structured?.error;
+    const { retryAfterMs, ...failure } = error !== null && typeof error === "object"
+        ? error
+        : {
+            retryAfterMs: undefined,
+            code: "executor_failed",
+            message: result.content[0]?.text ?? "",
+            retryable: false,
+        };
+    const landed = writes.succeeded > 0;
     const annotated = toolError({
-        ...(error !== null && typeof error === "object"
-            ? error
-            : {
-                code: "executor_failed",
-                message: result.content[0]?.text ?? "",
-                retryable: false,
-            }),
+        ...failure,
+        ...(landed ? { retryable: false } : retryAfterMs !== undefined ? { retryAfterMs } : {}),
         writes,
-        note: "This run attempted writes, counted in writes; those that succeeded are not undone. Check them before running the task again.",
+        note: landed
+            ? "This run completed writes, counted in writes, and they are not undone. Running this program again would repeat them: check them, then send only what is left."
+            : "This run attempted writes, counted in writes, and none applied. Check them before running the task again.",
     });
     if (structured && error !== null && typeof error === "object") {
         const { error: _replaced, ...rest } = structured;

package/dist/provider.d.ts

@@ -127,17 +127,10 @@ export interface ProviderGuideBlocks<O> {
 export interface ProviderKitFacts {
     /** `manifest(vendor)`: every operation the provider's tools send, as `"METHOD /path"`. */
     readonly operations: readonly string[];
-    /** The `limit` default and maximum every paged read declares. */
-    readonly pageSize?: {
-        readonly default: number;
-        readonly max: number;
-    };
     /** The hatch's tool prefix and its reviewed verdict per `"METHOD /path"`. */
     readonly hatch?: {
         readonly name: string;
         readonly verdicts: Readonly<Record<string, "read" | "write" | "destructive" | "refuse">>;
-        /** Separate-cursor paging opts into the generated hatch paging convention. */
-        readonly paging?: "argument" | "parameter";
         readonly fieldsRoot?: string;
     };
     /**
@@ -152,12 +145,6 @@ export interface ProviderKitFacts {
     };
     /** Whether a write takes an idempotency key the vendor honors, checked against the built tools. */
     readonly idempotencyKey?: boolean;
-    /**
-     * Set only when the hatch refuses a write carrying a withheld placeholder
-     * value; the Withheld values convention promises exactly that. The kit sets
-     * it for its standard hatch; kit write builders refuse the same markers.
-     */
-    readonly refusesWithheld?: true;
 }
 /** Connection facts a provider renders around its maintained guide. */
 export interface ProviderGuideInput {

package/dist/provider.js

@@ -112,13 +112,11 @@ function kitFacts(kit) {
     }
     return Object.freeze({
         operations: Object.freeze([...kit.operations]),
-        ...(kit.pageSize ? { pageSize: Object.freeze({ ...kit.pageSize }) } : {}),
         ...(kit.hatch
             ? {
                 hatch: Object.freeze({
                     name: kit.hatch.name,
                     verdicts: Object.freeze({ ...kit.hatch.verdicts }),
-                    ...(kit.hatch.paging ? { paging: kit.hatch.paging } : {}),
                     ...(kit.hatch.fieldsRoot ? { fieldsRoot: kit.hatch.fieldsRoot } : {}),
                 }),
             }
@@ -127,7 +125,6 @@ function kitFacts(kit) {
             ? { errors: Object.freeze({ ...kit.errors, conflicts: Object.freeze([...kit.errors.conflicts]) }) }
             : {}),
         ...(kit.idempotencyKey !== undefined ? { idempotencyKey: kit.idempotencyKey } : {}),
-        ...(kit.refusesWithheld ? { refusesWithheld: true } : {}),
     });
 }
 /**

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

@@ -9,7 +9,7 @@ import { asRecord, asArray } from "../json.js";
 // bytes, and failure phases for product recovery.
 import { Effect, Option } from "effect";
 import { deriveContext } from "../../../derived-context.js";
-import { ConnectorCallError } from "../../../errors.js";
+import { ConnectorCallError, tokenPrefix } from "../../../errors.js";
 import { Refusal, StatusFailure, toConnectorCallError, } from "../../../http/errors.js";
 import { Classification, Dispatches, Signal } from "../../../http/services.js";
 import { callMemo, Operation } from "../../../runtime/call.js";
@@ -65,7 +65,7 @@ export function googleErrors(product, options = {}) {
         detail: ({ status, body }) => {
             const message = asRecord(asRecord(body)["error"])["message"];
             // The body arrives redacted whole, before anything here cuts it.
-            const said = typeof message === "string" ? message.trim().slice(0, 500) : "";
+            const said = typeof message === "string" ? tokenPrefix(message.trim(), 500) : "";
             return said ? `${provider}: ${said}${/[.!?]$/.test(said) ? "" : "."}` : `${provider} returned HTTP ${status}.`;
         },
         classify: [

package/dist/providers/breeze/api.js

@@ -3,7 +3,7 @@ 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";
+import { ConnectorCallError, resendAdvice, tokenPrefix } from "../../errors.js";
 import { Refusal } from "../../http/errors.js";
 import { Credentials, RequestSecrets } from "../../http/services.js";
 import { get, Summary, vendor } from "../../http/vendor.js";
@@ -555,7 +555,7 @@ function shortText(value, secrets) {
     // 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;
+    return text.length > 300 ? `${tokenPrefix(text, 300)}…` : text;
 }
 /**
  * Breeze can report a failure inside a 200: `{ success: false, errors: … }`

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. 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.",
+    "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- **Hatch:** `breeze_api_search` finds operations, `breeze_api_details` shows one contract, `breeze_api_read` calls a reviewed read and `breeze_api_write` a reviewed write.\n- **Errors:** `not_found` means the record does not exist; this API tells absence from a permission gap.",
     "instructionsHeading": "Church instructions"
 };

package/dist/providers/ccb/api.js

@@ -4,7 +4,7 @@ import { CCB_MEDIA_TYPE, CCB_ENVIRONMENTS, CCB_READ_SCOPES, CCB_WRITE_SCOPES, CC
 // Pushpay ChMS v2 JSON contracts, OAuth, status meanings, admission and privacy.
 // The legacy per-church XML API is outside this provider's scope.
 import { Effect, Schema } from "effect";
-import { ConnectorCallError } from "../../errors.js";
+import { ConnectorCallError, tokenPrefix } from "../../errors.js";
 import { OperationIndex } from "../_shared/rest/operation-index.js";
 import { checked, indexedVendor } from "../_shared/rest/kit.js";
 import { valueSafety } from "../_shared/rest/value-safety.js";
@@ -432,7 +432,7 @@ function errorDetail(payload, status) {
                 parts.push(message.trim());
         }
     }
-    const detail = parts.join("; ").slice(0, 500);
+    const detail = tokenPrefix(parts.join("; "), 500);
     return detail ? `CCB HTTP ${status}: ${detail}${/[.!?]$/.test(detail) ? "" : "."}` : `CCB returned HTTP ${status}.`;
 }
 export const errors = {

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. 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.",
+    "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- **Hatch:** `ccb_api_search` finds operations, `ccb_api_details` shows one contract, `ccb_api_read` calls a reviewed read and `ccb_api_write` a reviewed write. 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- **Errors:** `not_found` means the record does not exist; this API tells absence from a permission gap.",
     "instructionsHeading": "Church instructions"
 };

package/dist/providers/cloudflare/api.js

@@ -4,7 +4,7 @@ import { responseMedia } from "../_shared/rest/response-media.js";
 import { EXCLUSIVE_PATH_IDS } from "./lib/path-bounds.js";
 import { RESPONSE_MEDIA } from "./lib/response-media.js";
 import { Effect, Option, Schema } from "effect";
-import { ConnectorCallError } from "../../errors.js";
+import { ConnectorCallError, tokenPrefix } from "../../errors.js";
 import { Refusal, StatusFailure, toConnectorCallError, } from "../../http/errors.js";
 import { Budget, Credentials, Classification, Dispatches, Signal } from "../../http/services.js";
 import { restSafety } from "../../http/safety.js";
@@ -236,7 +236,7 @@ export function describeErrors(errors) {
                 continue;
             }
             const code = typeof entry.code === "number" ? entry.code : undefined;
-            const message = typeof entry.message === "string" ? entry.message.slice(0, 500) : "Unknown error";
+            const message = (typeof entry.message === "string" && tokenPrefix(entry.message, 500)) || "Unknown error";
             parts.push(code === undefined ? message : `${code}: ${message}`);
             if (Array.isArray(entry.error_chain))
                 walk(entry.error_chain);

package/dist/providers/cloudflare/index.js

@@ -116,6 +116,8 @@ export const cloudflare = defineApiProvider({
     defaultCallAdmission: (options) => admissionPolicy(options.maxConcurrency ?? 6),
     credential: (options) => (options.auth.type === "globalApiKey" ? GLOBAL_API_KEY_CREDENTIAL : API_TOKEN_CREDENTIAL),
     authenticate,
+    // The Global API Key scheme's account email names the account; X-Auth-Key proves it.
+    publicIdentifierHeaders: ["x-auth-email"],
     errors: cloudflareErrors,
     inBandRefusals: true,
     idempotencyKey: false,

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Accounts, domains and records\n\nResolve account and zone ids before acting. A zone is a domain, found by its name;\nits account id joins it to the account inventory. Cloudflare ids are normally\n32-character hex strings. A default id routes a request; a pin limits its scope.\n\nDNS TTL is in seconds; TTL 1 means automatic. Read the record before changing it.\nPATCH changes supplied fields; PUT replaces the record, so preserve its type,\nname and content. Read state before replacing, rolling back or purging. Prefer\na targeted cache purge by files, tags, hosts or prefixes over purging everything.\n\nHatch data keeps Cloudflare's vendor envelope. For example, select DNS record\nidentities with `fields: [\"result.id\", \"result.name\"]`; a list stays under\n`data.result`. Named account and zone lists keep projected rows with camelCase\naccount and name-server fields.\n\n## Workers, storage and analytics\n\nWorker script source is code; secret binding values are separate and unavailable.\nKV values are application data. Encode a slash inside a KV key or R2 object key\nas `%2F`. R2 requires API-token authentication, rather than a Global API Key.\n\nGraphQL Analytics uses accountTag and zoneTag for account/zone identities.\nFilter every accounts/zones field by equality or an explicit set of those ids.\nA pinned query uses one operation per document and every declared fragment.\nAnalytics Engine SQL is read-only; D1 SQL and Durable Object queries can write.\nAI inference, previews and outbound checks can cost money or activate work.\n\n## Disqualifiers and recovery\n\nCredential minting, rotation, stored secrets, private session captures and signed\nupload or deployment links are unavailable. Use the Cloudflare dashboard for\ncredential administration. A Global API Key cannot change user settings or\nmemberships through this connection.\n\nAfter an authentication failure, use `verify_credential` once to distinguish a\nrejected credential from a permission gap. An operator replaces the credential;\nrepeating the failed request does not add permissions. Cloudflare's global limit\ncounts dashboard traffic and all tokens together, so reduce requests as well as\nhonoring the returned wait.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `cloudflare_api_details`, `cloudflare_api_search`, `list_accounts`, `list_zones`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `cloudflare_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 20, at most 50). 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- **Envelope fields:** hatch data keeps the vendor envelope. Select declared fields with `fields: [\"result.id\", \"result.name\"]`; array traversal also accepts `result[].id`. Named reads keep their projected fields.\n- **Hatch:** `cloudflare_api_search` finds this API's operations and reads no account data, `cloudflare_api_details` shows one operation's contract, and `cloudflare_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `cloudflare_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 70 operations are refused by design; use `cloudflare_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.",
+    "content": "## Accounts, domains and records\n\nResolve account and zone ids before acting. A zone is a domain, found by its name;\nits account id joins it to the account inventory. Cloudflare ids are normally\n32-character hex strings. A default id routes a request; a pin limits its scope.\n\nDNS TTL is in seconds; TTL 1 means automatic. Read the record before changing it.\nPATCH changes supplied fields; PUT replaces the record, so preserve its type,\nname and content. Read state before replacing, rolling back or purging. Prefer\na targeted cache purge by files, tags, hosts or prefixes over purging everything.\n\nA hatch list stays under `data.result`. Named account and zone lists use camelCase\naccount and name-server fields.\n\n## Workers, storage and analytics\n\nWorker script source is code; secret binding values are separate and unavailable.\nKV values are application data. Encode a slash inside a KV key or R2 object key\nas `%2F`. R2 requires API-token authentication, rather than a Global API Key.\n\nGraphQL Analytics uses accountTag and zoneTag for account/zone identities.\nFilter every accounts/zones field by equality or an explicit set of those ids.\nA pinned query uses one operation per document and every declared fragment.\nAnalytics Engine SQL is read-only; D1 SQL and Durable Object queries can write.\nAI inference, previews and outbound checks can cost money or activate work.\n\n## Disqualifiers and recovery\n\nCredential minting, rotation, stored secrets, private session captures and signed\nupload or deployment links are unavailable. Use the Cloudflare dashboard for\ncredential administration. A Global API Key cannot change user settings or\nmemberships through this connection.\n\nAfter an authentication failure, use `verify_credential` once to distinguish a\nrejected credential from a permission gap. An operator replaces the credential;\nrepeating the failed request does not add permissions. Cloudflare's global limit\ncounts dashboard traffic and all tokens together, so reduce requests as well as\nhonoring the returned wait.\n\n## Conventions\n\n- **Envelope fields:** hatch data keeps the vendor envelope: select `result.id`, or `result[].id` across a list. Named reads keep their projected fields.\n- **Hatch:** `cloudflare_api_search` finds operations, `cloudflare_api_details` shows one contract, `cloudflare_api_read` calls a reviewed read and `cloudflare_api_write` a reviewed write. 70 operations are refused by design; use `cloudflare_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Errors:** `not_found` means the record does not exist; this API tells absence from a permission gap.",
     "instructionsHeading": "Account instructions"
 };

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Find the document first\n\nDocument ids join Docs to Drive: take the part after `/d/` in a document URL,\nor find the file by name through a Google Drive connection. An id the person\nprovides works as is. Docs has no\naccount-data search or listing; its operation search discovers API methods.\nA missing document may be absent or inaccessible to the mapped Workspace user.\n\n## Read before editing\n\nThe rendering follows document tabs, including nested tabs. Headers, footers,\nfloating images and comments are not rendered; `notRendered` names omitted\nkinds. Suggested insertions and deletions can appear together without marks.\nAn accepted or rejected suggestions preview cannot supply edit indexes.\nIndexed rows page with `page.nextCursor`; keep the same arguments, starting\nwith `maxChars: 0` when only indexes are needed.\n\nUse the inline view's UTF-16 start/end indexes and revision to plan edits.\nIndexes shift after each edit, including earlier requests in the same atomic\nbatch. Apply independent deletions from the end backwards. A revision is a\nprecondition, never an idempotency key. Re-read and recompute after a revision\nconflict.\n\nStyles, named ranges, headers and footers live in the complete document\nresource. Read it with\n`docs_api_read({path:\"/documents/doc_123\",query:{includeTabsContent:true}})`\nwhen a rendering cannot answer the task. Paths omit `/v1`; the hatch reply is\n`{status,data}`, with the vendor document in `data` (a program call's\n`delivery.data.data`). A Docs\ncreate payload sets a title only; initial text is a separate edit. Appending\njoins the final paragraph, so begin with a newline when a new paragraph is\nintended. A broad text replacement can rewrite every tab.\nBatch kinds include `updateTextStyle` for formatting, `insertTable`,\n`createParagraphBullets`, and `deleteContentRange`.\n\n## Recover a partial create\n\nIf creation succeeded but initial text failed, keep the created document id.\nAppend the missing text directly only when the failure proves Google refused\nit. Otherwise read that document and add only what is missing. Creating again\nwould make another document. If the create reply lost its id, search Drive for\nthe title before attempting a fresh create.\n\nPreview comment and suggestion mutations are unavailable. Comments belong to\nDrive. Copying a template or choosing a destination folder also belongs to\nDrive; a Docs create starts in My Drive's root.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `docs_api_details`, `docs_api_search`, `get_document`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. Keep the original method, path, filters, page size, fields and headers. 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:** `docs_api_search` finds this API's operations and reads no account data, `docs_api_details` shows one operation's contract, and `docs_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `docs_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. An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: A revision-guarded batch update returned ABORTED or FAILED_PRECONDITION with HTTP 400 or 409; The document content or revision changed during indexed content paging.\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": "## Find the document first\n\nDocument ids join Docs to Drive: take the part after `/d/` in a document URL,\nor find the file by name through a Google Drive connection. An id the person\nprovides works as is. Docs has no\naccount-data search or listing; its operation search discovers API methods.\nA missing document may be absent or inaccessible to the mapped Workspace user.\n\n## Read before editing\n\nThe rendering follows document tabs, including nested tabs. Headers, footers,\nfloating images and comments are not rendered; `notRendered` names omitted\nkinds. Suggested insertions and deletions can appear together without marks.\nAn accepted or rejected suggestions preview cannot supply edit indexes.\nIndexed rows page with `page.nextCursor`; keep the same arguments, starting\nwith `maxChars: 0` when only indexes are needed.\n\nUse the inline view's UTF-16 start/end indexes and revision to plan edits.\nIndexes shift after each edit, including earlier requests in the same atomic\nbatch. Apply independent deletions from the end backwards. A revision is a\nprecondition, never an idempotency key. Re-read and recompute after a revision\nconflict.\n\nStyles, named ranges, headers and footers live in the complete document\nresource. Read it with\n`docs_api_read({path:\"/documents/<id>\",query:{includeTabsContent:true}})`\nwhen a rendering cannot answer the task. Paths omit `/v1`; the hatch reply is\n`{status,data}`, with the vendor document in `data` (a program call's\n`delivery.data.data`). A Docs\ncreate payload sets a title only; initial text is a separate edit. Appending\njoins the final paragraph, so begin with a newline when a new paragraph is\nintended. A broad text replacement can rewrite every tab.\nBatch kinds include `updateTextStyle` for formatting, `insertTable`,\n`createParagraphBullets`, and `deleteContentRange`.\n\n## Recover a partial create\n\nIf creation succeeded but initial text failed, keep the created document id.\nAppend the missing text directly only when the failure proves Google refused\nit. Otherwise read that document and add only what is missing. Creating again\nwould make another document. If the create reply lost its id, search Drive for\nthe title before attempting a fresh create.\n\nPreview comment and suggestion mutations are unavailable. Comments belong to\nDrive. Copying a template or choosing a destination folder also belongs to\nDrive; a Docs create starts in My Drive's root.\n\n## Conventions\n\n- **Hatch:** `docs_api_search` finds operations, `docs_api_details` shows one contract, `docs_api_read` calls a reviewed read and `docs_api_write` a reviewed write.\n- **Errors:** An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: A revision-guarded batch update returned ABORTED or FAILED_PRECONDITION with HTTP 400 or 409; The document content or revision changed during indexed content paging.",
     "instructionsHeading": "Connection instructions"
 };

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Finding files and joining Workspace products\n\nDrive searches file data; operation discovery searches API capabilities.\nUse file ids from reads, Drive URLs or the person: an id they give, such as\n`pdf1`, works as is. The same id identifies a Google Doc,\nSheet, Slides deck or Form in its product connector. Shared-drive ids identify\nmembership and the root folder; folder parents determine inherited access.\nA missing file and a file the delegated user cannot see fail alike.\n\nDrive query values use single quotes: `name contains 'budget'`,\n`mimeType = 'application/pdf'`, `'folder_123' in parents`, or\n`modifiedTime > '2026-01-01T00:00:00'`. Trashed files are excluded by default.\n`incompleteSearch: true` means Google did not search every corpus; narrow the\nquery or choose a single shared drive. It is never an exact count.\n\n`maxBytes` is the byte budget and `limit` is rows per page; keep a high limit\nfor large folders and continue with the same listing arguments. Named `fields`\nmay narrow and `maxBytes` may change between pages. Hatch paths omit `/drive/v3`.\n\n## Content and file decisions\n\nThe content workflow exports Docs as Markdown, Sheets as CSV of the first\nsheet only, and Slides as text. Other text files retain their declared charset.\nSmall binary files can be returned as base64. A drawing, unsupported native\nfile, folder, shortcut or oversized binary returns an unavailable explanation.\nFor a shortcut, read its target id instead. Drive exports at most 10 MB.\n\nContent containing sent credentials is withheld as a whole binary value; there\nis no partial-content recovery around that boundary. Withheld MIME, shortcut,\nfolder or parent metadata cannot decide a subsequent read or move. Re-read\nthrough a safe source before trying the workflow again.\n\n## Access and recovery\n\nA file or copy inherits its destination folder's access. Read permission holders\nbefore moving, copying or creating in a shared folder, and read them again after\nchanging access. Inherited permissions name the parent folder or shared drive\nthat must be changed instead. An owner cannot be removed or replaced here.\n\nAll new grants use `share_file`, which sends no notification email by default.\nConfirm intent before granting `anyone` or domain access. Permission creation\nthrough the hatch is refused, including public-link grants; the named workflow\nowns grantee validation and notification behavior.\n\nContent updates replace the complete content. A create with an uncertain outcome\nneeds a search for the intended file before another create. Recoverable trash\ncan be restored for 30 days. Permanent deletion, ownership transfer, watch\nregistration, credential minting and generic media transport are outside the\nhatch. Use the named content and upload workflows for bounded bytes.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `drive_api_details`, `drive_api_read`, `drive_api_search`, `list_folder_items`, `list_permissions`, `list_shared_drives`, `search_files`, 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:** `drive_api_search` finds this API's operations and reads no account data, `drive_api_details` shows one operation's contract, and `drive_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `drive_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 51 operations are refused by design; use `drive_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. An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: A Drive source page changed before its local cursor resumed.\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": "## Finding files and joining Workspace products\n\nDrive searches file data; operation discovery searches API capabilities.\nUse file ids from reads, Drive URLs or the person: an id they give works as is.\nThe same id identifies a Google Doc, Sheet, Slides deck or Form in its product\nconnector. Shared-drive ids identify\nmembership and the root folder; folder parents determine inherited access.\nA missing file and a file the delegated user cannot see fail alike.\n\nDrive query values use single quotes: `name contains 'budget'`,\n`mimeType = 'application/pdf'`, `'folder_123' in parents`, or\n`modifiedTime > '2026-01-01T00:00:00'`. Trashed files are excluded by default.\n`incompleteSearch: true` means Google did not search every corpus; narrow the\nquery or choose a single shared drive. It is never an exact count.\n\n`maxBytes` is the byte budget and `limit` is rows per page; keep a high limit\nfor large folders and continue with the same listing arguments. Named `fields`\nmay narrow and `maxBytes` may change between pages. Hatch paths omit `/drive/v3`.\n\n## Content and file decisions\n\nThe content workflow exports Docs as Markdown, Sheets as CSV of the first\nsheet only, and Slides as text. Other text files retain their declared charset.\nSmall binary files can be returned as base64. A drawing, unsupported native\nfile, folder, shortcut or oversized binary returns an unavailable explanation.\nFor a shortcut, read its target id instead. Drive exports at most 10 MB.\n\nContent containing sent credentials is withheld as a whole binary value; there\nis no partial-content recovery around that boundary. Withheld MIME, shortcut,\nfolder or parent metadata cannot decide a subsequent read or move. Re-read\nthrough a safe source before trying the workflow again.\n\n## Access and recovery\n\nA file or copy inherits its destination folder's access. Read permission holders\nbefore moving, copying or creating in a shared folder, and read them again after\nchanging access. Inherited permissions name the parent folder or shared drive\nthat must be changed instead. An owner cannot be removed or replaced here.\n\nAll new grants use `share_file`, which sends no notification email by default.\nConfirm intent before granting `anyone` or domain access. Permission creation\nthrough the hatch is refused, including public-link grants; the named workflow\nowns grantee validation and notification behavior.\n\nContent updates replace the complete content. A create with an uncertain outcome\nneeds a search for the intended file before another create. Recoverable trash\ncan be restored for 30 days. Permanent deletion, ownership transfer, watch\nregistration, credential minting and generic media transport are outside the\nhatch. Use the named content and upload workflows for bounded bytes.\n\n## Conventions\n\n- **Hatch:** `drive_api_search` finds operations, `drive_api_details` shows one contract, `drive_api_read` calls a reviewed read and `drive_api_write` a reviewed write. 51 operations are refused by design; use `drive_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Errors:** An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: A Drive source page changed before its local cursor resumed.",
     "instructionsHeading": "Connection instructions"
 };

package/dist/providers/forms/index.js

@@ -94,6 +94,7 @@ export const forms = defineApiProvider({
     errors,
     safety: () => safety,
     probe,
+    blocks: { keys: ["writes"], select: (options) => (options.readOnly ? [] : ["writes"]) },
     guide: (options) => ({
         context: [
             `Purpose: ${options.purpose}`,

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Finding forms and joining answers\n\nThe Forms API cannot list or search forms. Find the file through Drive, or use\nthe id after `/forms/d/` in its edit URL. The `/forms/d/e/…` responder link is\nnot a form id. A form id is also its Drive file id.\n\nA form contains items; an item may ask one question, several grid questions,\nor no question. Responses join by `questionId`, never by `itemId`. Named\nresponse reads label answers with the current question titles in form order;\nan answer to a deleted question has no title. A response may contain several\nvalues or uploaded-file references for one question. File ids join to Drive.\n\n## Reading complete responses\n\nResponses and respondent emails can contain personal information. Filter and\naggregate in `execute_code`, returning named answers only when the task needs\nthem. `submittedAfter` is exclusive UTC: retain the newest `lastSubmittedTime`\nfor the next incremental read. Google does not promise a stable response\nsnapshot. A continuation inside a changed vendor page fails `conflict`; start\nagain or use that newest timestamp.\n\nLarge grids continue inside the same item: `questionsFrom` places the returned\nrows. `omittedQuestionIds` identifies answers left out for size; read those ids\nwith `get_response`. The structural hatch exposes quiz grading and correct\nanswers, images, and option navigation that named projections omit. Temporary\nimage access destinations remain withheld.\n\n## Editing without losing structure\n\nRead the form's current revision before editing. A stale revision refuses the\nbatch as `conflict`; re-read and rebuild the requested edit. A revision guards\nconcurrent changes and does not make a repeated write safe.\n\nCreation sets only title and Drive file name. Add descriptions or questions\nafterward. `updateItem` can replace grading, images and section navigation;\nread the full item through the hatch first and use a precise `updateMask`.\nItem locations are indexes, while response answers use question ids.\n\nPublishing, sharing, deleting forms, and watch administration are outside this\nconnection. Responses are read-only; no tool submits or deletes a response.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `forms_api_details`, `forms_api_read`, `forms_api_search`, `get_form`, `list_responses`, 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:** `forms_api_search` finds this API's operations and reads no account data, `forms_api_details` shows one operation's contract, and `forms_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `forms_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 5 operations are refused by design; use `forms_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. An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: A revision-guarded batch update returned ABORTED or FAILED_PRECONDITION with HTTP 400 or 409.\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": "## Finding forms and joining answers\n\nThe Forms API cannot list or search forms. Find the file through Drive, or use\nthe id after `/forms/d/` in its edit URL. The `/forms/d/e/…` responder link is\nnot a form id. A form id is also its Drive file id.\n\nA form contains items; an item may ask one question, several grid questions,\nor no question. Responses join by `questionId`, never by `itemId`. Named\nresponse reads label answers with the current question titles in form order;\nan answer to a deleted question has no title. A response may contain several\nvalues or uploaded-file references for one question. File ids join to Drive.\n\n## Reading complete responses\n\nResponses and respondent emails can contain personal information. Filter and\naggregate in `execute_code`, returning named answers only when the task needs\nthem. `submittedAfter` is exclusive UTC: retain the newest `lastSubmittedTime`\nfor the next incremental read. Google does not promise a stable response\nsnapshot. A continuation inside a changed vendor page fails `conflict`; start\nagain or use that newest timestamp.\n\nLarge grids continue inside the same item: `questionsFrom` places the returned\nrows. `omittedQuestionIds` identifies answers left out for size; read those ids\nwith `get_response`. The structural hatch exposes quiz grading and correct\nanswers, images, and option navigation that named projections omit. Temporary\nimage access destinations remain withheld.\n\n<!-- when: writes -->\n## Editing without losing structure\n\nRead the form's current revision before editing. A stale revision refuses the\nbatch as `conflict`; re-read and rebuild the requested edit. A revision guards\nconcurrent changes and does not make a repeated write safe.\n\nCreation sets only title and Drive file name. Add descriptions or questions\nafterward. `updateItem` can replace grading, images and section navigation;\nread the full item through the hatch first and use a precise `updateMask`.\nItem locations are indexes, while response answers use question ids.\n\nPublishing, sharing, deleting forms, and watch administration are outside this\nconnection. Responses are read-only; no tool submits or deletes a response.\n<!-- end -->\n\n## Conventions\n\n- **Hatch:** `forms_api_search` finds operations, `forms_api_details` shows one contract, `forms_api_read` calls a reviewed read and `forms_api_write` a reviewed write. 5 operations are refused by design; use `forms_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Errors:** An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: A revision-guarded batch update returned ABORTED or FAILED_PRECONDITION with HTTP 400 or 409.",
     "instructionsHeading": "Connection instructions"
 };