@zackbart/connecta 0.37.1 → 0.39.0

package/dist/providers/planning-center/skill.generated.js

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Identity first\n\nA People person id joins records across products. Resolve people by identity,\nthen join on `person_id`; names can repeat. A membership, scheduled person,\nworkflow card and person each have their own record id.\n\n`get_me` identifies the token's user and the organization's time zone. Bare\ndates mean the organization's local day; use a timestamp with an offset for\nan exact boundary. Name filters are exact unless their value ends in `%`.\n\nAn old person id may have been merged. Read `/people/v2/person_mergers` with\n`where[person_to_remove_id]`, follow `person_to_keep_id`, then read that profile.\nAn empty history does not establish that a person was merged.\n\nReduce pastoral information inside `execute_code` and return aggregates unless\nthe task needs named people. A named projection omits some safe vendor fields;\nread the indexed record when the task needs those fields.\n\n<!-- when: people -->\n## People and follow-up\n\nResolve a person before changing their profile. An omitted attribute leaves\nthe current value alone; `null` clears it. Archiving a person is reversible;\ndeleting a profile is permanent.\n\nWorkflow cards join people to a workflow and its ordered steps. Resolve both\nthe card id and its person id before acting on a card. Snoozing needs a duration;\npromoting a card completes its step, while skipping moves on without completing\nit. A workflow card note and a profile note are different records. Profile note\ncategories can notify their subscribers.\n\nCustom field values need their field-definition records to supply names and\ndata types. Form answers similarly join submissions, values and fields; the\nAPI cannot submit a form on someone's behalf.\n<!-- end -->\n\n<!-- when: lists -->\nSaved People lists are live cross-product queries. Their results are only as\nfresh as their last refresh. Refreshing a list can fire its automations, such\nas adding a person to a workflow, and is a write even when the task is a count.\n<!-- end -->\n\n<!-- when: services -->\n## Services plans and schedules\n\nResolve the service type before finding a dated plan. Plan times define the\nservice dates. `get_plan` combines the plan, order of service and scheduled\nteam; a cut section can be read through its indexed items or team-members path.\nItem durations are seconds, so divide by 60 when reporting minutes.\n\nScheduling needs a team and may need a position. `C` means confirmed, `U`\nunconfirmed and `D` declined. Preparing a notification and sending it are\ndifferent actions. A song item's identity comes from its song and arrangement;\nmusical keys are not credentials. Services cannot upload a file through this\nconnection.\n<!-- end -->\n\n<!-- when: groups -->\n## Groups membership joins\n\nUse a group's membership records to distinguish leaders from members. On this\nAPI version memberships carry no person attributes; `include=person` supplies\nnames, and the related person id supplies contact details and other product\nrecords. The API can change memberships and group settings, but cannot create\na group, create a meeting or record group attendance.\n<!-- end -->\n\n<!-- when: check-ins -->\n## Check-Ins occurrences\n\nAn event is recurring; its event period is a dated occurrence. Period counts\nare the efficient attendance answer. Individual check-ins join a person to a\nperiod, and date filtering uses the period's start, not the check-in's creation\ntime. The API cannot check anyone in or out.\n<!-- end -->\n\n<!-- when: calendar -->\n## Calendar occurrences\n\nEvent instances expand recurrence into occurrences. A booking can return a\n`BookedEvent` stub when the user lacks access to its event. Events, instances\nand times are read-only; tags, resources, rooms and folders have write APIs.\n<!-- end -->\n\n<!-- when: registrations -->\n## Registrations\n\nA signup describes a registration event. Its attendee records join back to\nPeople and distinguish active, waitlisted and canceled attendees. This API\ncannot register someone.\n<!-- end -->\n\n<!-- when: giving -->\n## Giving amounts and donor joins\n\nAmounts are integer cents with an explicit currency. A donation's designations\nallocate it across funds; do not count a donation once per designation. Join\ndonors by person id and funds by fund id. Recurring schedules and the donations\nthey produce are different records. Creating/editing a donation, refunding it\nor committing a batch changes financial records; named giving tools only read.\n<!-- end -->\n\n<!-- when: publishing -->\n## Publishing\n\nEpisodes, channels and resources are available through the indexed API. A public\nChurch Center link and a media resource are different things; use the record\nthe task asks for. Signed download URL generation is refused because the\nprivate link would remain withheld.\n<!-- end -->\n\n<!-- when: webhooks -->\n## Webhooks\n\nA subscription names an event and callback destination. Signing keys, private\ndownload destinations and opaque event/delivery payloads or headers remain\nwithheld. Status and event metadata are available for audits.\nWebhook signing-key rotation is refused: the new credential cannot be returned\nor installed on the receiver through this connection.\n<!-- end -->\n\n<!-- when: api -->\n## Organization API\n\nThe organization API includes application metadata and personal-access-token\ninventory. Inventory records describe tokens; they do not return their values.\nRevoking a token is a write and may interrupt another integration, including\nthis connection if its own token is revoked.\n<!-- end -->\n\n<!-- when: limited -->\n## Product boundary\n\nSome products are unavailable on this connection. People lists and their rules\nare unavailable because they can query another product. Webhook payloads and\nchanges to existing subscriptions are unavailable because their ids do not name\ntheir product. A new subscription must name a reachable product's event.\n\nStored workflow cards, notes, custom fields and form answers remain readable\nwhen reachable: staff or automations may have copied information into them.\nThe connection does not infer the provenance of those stored records.\n<!-- end -->\n\n## Not available\n\nOnly reviewed product versions and indexed operations are callable. File\nuploads use a separate host this connection does not reach. Credentials and\nprivate calendar access codes cannot be recovered through a tool.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `list_person_field_data`, `list_person_notes`, `list_workflow_cards`, `list_workflows`, `pco_api_details`, `pco_api_search`, `search_people`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `pco_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 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<!-- when: services -->\n- **Paging:** For `list_person_schedules`, `list_plans`, `list_service_types`, `list_teams`, pass `page.nextCursor` as the top-level `cursor`.\n<!-- end -->\n<!-- when: groups -->\n- **Paging:** For `list_group_memberships`, `list_groups`, pass `page.nextCursor` as the top-level `cursor`.\n<!-- end -->\n<!-- when: giving -->\n- **Paging:** For `list_donations`, `list_funds`, pass `page.nextCursor` as the top-level `cursor`.\n<!-- end -->\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:** `pco_api_search` finds this API's operations and reads no account data, `pco_api_details` shows one operation's contract, and `pco_api_read` calls a reviewed read. `pco_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 2 operations are refused by design; use `pco_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. `conflict` means: HTTP 409 for duplicate records in People.\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": "## Identity first\n\nA People person id joins records across products. Resolve people by identity,\nthen join on `person_id`; names can repeat. A membership, scheduled person,\nworkflow card and person each have their own record id.\n\n`get_me` identifies the token's user and the organization's time zone. Bare\ndates mean the organization's local day; use a timestamp with an offset for\nan exact boundary. Name filters are exact unless their value ends in `%`.\n\nAn old person id may have been merged. Read `/people/v2/person_mergers` with\n`where[person_to_remove_id]`, follow `person_to_keep_id`, then read that profile.\nAn empty history does not establish that a person was merged.\n\nReduce pastoral information inside `execute_code` and return aggregates unless\nthe task needs named people. A named projection omits some safe vendor fields;\nread the indexed record when the task needs those fields.\n\n<!-- when: people -->\n## People and follow-up\n\nResolve a person before changing their profile. An omitted attribute leaves\nthe current value alone; `null` clears it. Archiving a person is reversible;\ndeleting a profile is permanent.\n\nWorkflow cards join people to a workflow and its ordered steps. Resolve both\nthe card id and its person id before acting on a card. Snoozing needs a duration;\npromoting a card completes its step, while skipping moves on without completing\nit. A workflow card note and a profile note are different records. Profile note\ncategories can notify their subscribers.\n\nCustom field values need their field-definition records to supply names and\ndata types. Form answers similarly join submissions, values and fields; the\nAPI cannot submit a form on someone's behalf.\n<!-- end -->\n\n<!-- when: lists -->\nSaved People lists are live cross-product queries. Their results are only as\nfresh as their last refresh. Refreshing a list can fire its automations, such\nas adding a person to a workflow, and is a write even when the task is a count.\n<!-- end -->\n\n<!-- when: services -->\n## Services plans and schedules\n\nResolve the service type before finding a dated plan. Plan times define the\nservice dates. `get_plan` combines the plan, order of service and scheduled\nteam; a cut section can be read through its indexed items or team-members path.\nItem durations are seconds, so divide by 60 when reporting minutes.\n\nScheduling needs a team and may need a position. `C` means confirmed, `U`\nunconfirmed and `D` declined. Preparing a notification and sending it are\ndifferent actions. A song item's identity comes from its song and arrangement;\nmusical keys are not credentials. Services cannot upload a file through this\nconnection.\n<!-- end -->\n\n<!-- when: groups -->\n## Groups membership joins\n\nUse a group's membership records to distinguish leaders from members. On this\nAPI version memberships carry no person attributes; `include=person` supplies\nnames, and the related person id supplies contact details and other product\nrecords. The API can change memberships and group settings, but cannot create\na group, create a meeting or record group attendance.\n<!-- end -->\n\n<!-- when: check-ins -->\n## Check-Ins occurrences\n\nAn event is recurring; its event period is a dated occurrence. Period counts\nare the efficient attendance answer. Individual check-ins join a person to a\nperiod, and date filtering uses the period's start, not the check-in's creation\ntime. The API cannot check anyone in or out.\n<!-- end -->\n\n<!-- when: calendar -->\n## Calendar occurrences\n\nEvent instances expand recurrence into occurrences. A booking can return a\n`BookedEvent` stub when the user lacks access to its event. Events, instances\nand times are read-only; tags, resources, rooms and folders have write APIs.\n<!-- end -->\n\n<!-- when: registrations -->\n## Registrations\n\nA signup describes a registration event. Its attendee records join back to\nPeople and distinguish active, waitlisted and canceled attendees. This API\ncannot register someone.\n<!-- end -->\n\n<!-- when: giving -->\n## Giving amounts and donor joins\n\nAmounts are integer cents with an explicit currency. A donation's designations\nallocate it across funds; do not count a donation once per designation. Join\ndonors by person id and funds by fund id. Recurring schedules and the donations\nthey produce are different records. Creating/editing a donation, refunding it\nor committing a batch changes financial records; named giving tools only read.\n<!-- end -->\n\n<!-- when: publishing -->\n## Publishing\n\nEpisodes, channels and resources are available through the indexed API. A public\nChurch Center link and a media resource are different things; use the record\nthe task asks for. Signed download URL generation is refused because the\nprivate link would remain withheld.\n<!-- end -->\n\n<!-- when: webhooks -->\n## Webhooks\n\nA subscription names an event and callback destination. Signing keys, private\ndownload destinations and opaque event/delivery payloads or headers remain\nwithheld. Status and event metadata are available for audits.\nWebhook signing-key rotation is refused: the new credential cannot be returned\nor installed on the receiver through this connection.\n<!-- end -->\n\n<!-- when: api -->\n## Organization API\n\nThe organization API includes application metadata and personal-access-token\ninventory. Inventory records describe tokens; they do not return their values.\nRevoking a token is a write and may interrupt another integration, including\nthis connection if its own token is revoked.\n<!-- end -->\n\n<!-- when: limited -->\n## Product boundary\n\nSome products are unavailable on this connection. People lists and their rules\nare unavailable because they can query another product. Webhook payloads and\nchanges to existing subscriptions are unavailable because their ids do not name\ntheir product. A new subscription must name a reachable product's event.\n\nStored workflow cards, notes, custom fields and form answers remain readable\nwhen reachable: staff or automations may have copied information into them.\nThe connection does not infer the provenance of those stored records.\n<!-- end -->\n\n## Not available\n\nOnly reviewed product versions and indexed operations are callable. File\nuploads use a separate host this connection does not reach. Credentials and\nprivate calendar access codes cannot be recovered through a tool.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `list_person_field_data`, `list_person_notes`, `list_workflow_cards`, `list_workflows`, `pco_api_details`, `pco_api_search`, `search_people`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `pco_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 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<!-- when: services -->\n- **Paging:** For `list_person_schedules`, `list_plans`, `list_service_types`, `list_teams`, pass `page.nextCursor` as the top-level `cursor`.\n<!-- end -->\n<!-- when: groups -->\n- **Paging:** For `list_group_memberships`, `list_groups`, pass `page.nextCursor` as the top-level `cursor`.\n<!-- end -->\n<!-- when: giving -->\n- **Paging:** For `list_donations`, `list_funds`, pass `page.nextCursor` as the top-level `cursor`.\n<!-- end -->\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:** `pco_api_search` finds this API's operations and reads no account data, `pco_api_details` shows one operation's contract, and `pco_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `pco_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 2 operations are refused by design; use `pco_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. `conflict` means: HTTP 409 for duplicate records in People.\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": "Organization instructions"
 };

package/dist/providers/planning-center/tools.js

@@ -1,3 +1,4 @@
+import { asRecord, compact } from "../_shared/json.js";
 // Curated Planning Center workflows over the standard provider kit.
 import { Effect, Schema } from "effect";
 import { ConnectorCallError } from "../../errors.js";
@@ -6,7 +7,7 @@ import { Integer, isMinChars, emptyRequired } from "../../http/json-schema.js";
 import { read, write, list as standardList } from "../../http/tools.js";
 import { PLANNING_CENTER_APPS, MAX_PAGE_SIZE, planningCenterCall } from "./api.js";
 import { excludedApps } from "./lib/guide.js";
-import { asRecord, compact, resources, indexIncluded, relId, related, relatedMany, pick, attribute, writeDocument, pageOf, } from "./lib/json-api.js";
+import { resources, indexIncluded, relId, related, relatedMany, pick, attribute, writeDocument, pageOf, } from "./lib/json-api.js";
 const fail = (code, message, options) => Effect.fail(new Refusal({ error: new ConnectorCallError(code, message, options) }));
 const pattern = (source) => Schema.makeFilter((value) => typeof value !== "string" || new RegExp(source).test(value), {
     toJsonSchema: () => ({ pattern: source }),

package/dist/providers/quickbooks/safety.js

@@ -139,43 +139,91 @@ function safeRecord(value) {
         out["LinkedTxn"] = source["LinkedTxn"].map((row) => pick(row, ["TxnId", "TxnType", "TxnLineId"]));
     return out;
 }
+const REPORT_KEYS = new Set([
+    "Header",
+    "Columns",
+    "Column",
+    "Rows",
+    "Row",
+    "Summary",
+    "ColData",
+    "ColTitle",
+    "ColType",
+    "MetaData",
+    "Name",
+    "Value",
+    "Option",
+    "Time",
+    "ReportName",
+    "DateMacro",
+    "ReportBasis",
+    "StartPeriod",
+    "EndPeriod",
+    "SummarizeColumnsBy",
+    "Currency",
+    "value",
+    "id",
+    "type",
+    "group",
+]);
+const ENTITIES = ["Customer", "Vendor", "Account", "Item", "Invoice", "Bill", "Payment", "BillPayment"];
+const COMPANY_KEYS = [
+    "Id",
+    "SyncToken",
+    "CompanyName",
+    "LegalName",
+    "Country",
+    "FiscalYearStartMonth",
+    "SupportedLanguages",
+];
 // Report trees retain vendor hierarchy, column metadata and empty strings. No index has a fixed metric meaning.
 function reportTree(value) {
     if (Array.isArray(value))
         return value.map(reportTree);
     if (typeof value !== "object" || value === null)
         return scalar(value);
-    const keys = new Set([
-        "Header",
-        "Columns",
-        "Column",
-        "Rows",
-        "Row",
-        "Summary",
-        "ColData",
-        "ColTitle",
-        "ColType",
-        "MetaData",
-        "Name",
-        "Value",
-        "Option",
-        "Time",
-        "ReportName",
-        "DateMacro",
-        "ReportBasis",
-        "StartPeriod",
-        "EndPeriod",
-        "SummarizeColumnsBy",
-        "Currency",
-        "value",
-        "id",
-        "type",
-        "group",
-    ]);
     return Object.fromEntries(Object.entries(value)
-        .filter(([key]) => keys.has(key))
+        .filter(([key]) => REPORT_KEYS.has(key))
         .map(([key, entry]) => [key, reportTree(entry)]));
 }
+/** What `safeRecord` does to a path within a record: returns it whole, trims it to picked fields, or drops it. */
+function recordPath(path) {
+    const [head, ...rest] = path;
+    if (head === undefined)
+        return "trimmed";
+    if (scalars.includes(head))
+        return rest.length ? "dropped" : "whole";
+    if (details.includes(head) || head === "Line")
+        return recordPath(rest);
+    const picked = head === "MetaData"
+        ? ["CreateTime", "LastUpdatedTime"]
+        : head === "LinkedTxn"
+            ? ["TxnId", "TxnType", "TxnLineId"]
+            : references.includes(head)
+                ? ["value", "name", "type"]
+                : undefined;
+    if (!picked)
+        return "dropped";
+    if (rest.length === 0)
+        return "trimmed";
+    return rest.length === 1 && picked.includes(rest[0]) ? "whole" : "dropped";
+}
+/** The closed projection as a discovery hint: a path it always drops is withheld. */
+function quickbooksWithholds(template) {
+    return (path) => {
+        const names = path.map((segment) => segment.replace(/\[\]$/, ""));
+        if (template.startsWith("/reports/"))
+            return !names.every((name) => REPORT_KEYS.has(name));
+        if (template.startsWith("/companyinfo/"))
+            return (names[0] !== "CompanyInfo" || names.length > 2 || (names.length === 2 && !COMPANY_KEYS.includes(names[1])));
+        const [root, ...rest] = template === "/query" && names[0] === "QueryResponse" ? names.slice(1) : names;
+        if (template === "/query" && names[0] !== "QueryResponse")
+            return true;
+        if (root === undefined)
+            return false;
+        return !ENTITIES.includes(root) || recordPath(rest) === "dropped";
+    };
+}
 export function quickbooksSafety(options) {
     return {
         reviewed: {
@@ -188,32 +236,25 @@ export function quickbooksSafety(options) {
                 return { method: op.method, template: op.path };
             },
             withholdsErrors: () => true,
+            withholds: (operation) => quickbooksWithholds(operation.template),
             redact: (body, operation) => {
                 const root = object(body);
                 if (operation.template.startsWith("/reports/"))
                     return reportTree(root);
                 if (operation.template.startsWith("/companyinfo/"))
                     return {
-                        CompanyInfo: pick(root["CompanyInfo"], [
-                            "Id",
-                            "SyncToken",
-                            "CompanyName",
-                            "LegalName",
-                            "Country",
-                            "FiscalYearStartMonth",
-                            "SupportedLanguages",
-                        ]),
+                        CompanyInfo: pick(root["CompanyInfo"], COMPANY_KEYS),
                     };
                 if (operation.template === "/query") {
                     const query = object(root["QueryResponse"]);
                     return {
                         QueryResponse: Object.fromEntries(Object.entries(query)
-                            .filter(([key]) => ["Customer", "Vendor", "Account", "Item", "Invoice", "Bill", "Payment", "BillPayment"].includes(key) && Array.isArray(query[key]))
+                            .filter(([key]) => ENTITIES.includes(key) && Array.isArray(query[key]))
                             .map(([key, rows]) => [key, rows.map(safeRecord)])),
                     };
                 }
                 return Object.fromEntries(Object.entries(root)
-                    .filter(([key]) => ["Customer", "Vendor", "Account", "Item", "Invoice", "Bill", "Payment", "BillPayment"].includes(key))
+                    .filter(([key]) => ENTITIES.includes(key))
                     .map(([key, record]) => [key, safeRecord(record)]));
             },
         },

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Accounting identity and joins\n\nAn Id identifies a record inside this company and record family. DocNumber is\na human label, may repeat, and is not an Id. SyncToken is the public record\nversion used for concurrency control, not an OAuth credential. References carry\nthe target Id in value; invoice CustomerRef joins Customer, bill VendorRef\njoins Vendor, and payment Line.LinkedTxn joins invoices or bills.\n\nAccounting Payment and BillPayment records describe received and paid money;\nreading them does not execute a payment. Desktop, Payments, Payroll, attachments,\nand unreviewed accounting entities are outside this connection.\n\n## Money, time and reports\n\nAmounts use decimal currency units, never integer cents. Preserve CurrencyRef\nand ExchangeRate when combining transactions; never sum unlike currencies.\nTxnDate is the company's accounting date, not a UTC instant. MetaData timestamps\ncarry their own offset. Customer and vendor searches omit inactive records\nunless the Active filter explicitly selects them.\n\nReports are trees with Header, Columns, nested Rows and section summaries.\nRead column types and metadata together with row values; column order and\nsection labels can change. Empty amount strings mean no value, not zero.\nDo not flatten away section identity or add totals to their component rows.\nCheck the returned period, basis, currency and NoReportData option before\ncomparing reports. Aging is an as-of snapshot, rather than a transaction range.\n\nReturn aggregates and the few identifying records the task needs; avoid\ncopying full customer or vendor directories into the conversation.\n\n\n## Named writes and reconciliation\n\nThe connector defaults to read-only. Deployment code must set `readOnly: false`\nto expose named writes; endpoint and pool read-only policies still apply. The\nAPI hatch remains read-only. `create_customer` accepts DisplayName and optional\nCompanyName. `update_customer` requires caller-observed Id and SyncToken and\nchanges only those naming fields with sparse:true. Omitted CompanyName stays\nunchanged. A stale-version conflict never fetches a newer version or overwrites\nit. Read and review the current record before proposing a new update.\nDisplayName must be unique across customers, vendors and employees.\n\n`create_invoice` creates a real accounting transaction, never a draft, for a\nverified US company and a customer using USD. This bounds the no-email claim\nto the reviewed US autosend contract and money to two-decimal USD units. First\nobserve an active customer with its CurrencyRef and active Service item Ids.\nSupply currency USD, a positive explicit exchange rate, accounting and\ndue dates, a reconciliation DocNumber and 1–20 lines. Each line is one service\nunit with an explicit positive amount in decimal currency units, supplied as a\nstring with exactly two fractional digits. No prices, dates or exchange rates\nare defaulted or fetched. Preflight reads verify the fixed company Country is US\nand recheck customer currency and item activity/type; they are not an atomic snapshot. Vendor validation can still\nreject changed references. Taxes and totals are computed by QuickBooks: inspect\nthe returned currency, exchange rate and totals; line sums are not a promise of\nan untaxed total. Locale/company tax requirements may reject this narrow body.\nNo customer/item creation happens implicitly.\nEach additional request charges the call-admission budget before dispatch.\nContradictory returned references, dates, rate or service prices produce an\nunknown outcome; reconcile through reads rather than repeating the write.\n\nInvoice email status is fixed to NotSet; online, IPN, credit-card, ACH, PayPal\nand Affirm payment flags are fixed false. No email field or send operation is\nexposed. Company invoice-autosend opt-in does not supply the documented\nNeedToSend request state. This prevents this creation request from asking Intuit\nto email the invoice, including when the customer has an email on file.\nInvoice updates are unavailable: preserving an existing send-ready state has\nnot been established safe, while resetting it would change payment settings.\nDeletes, voids, email delivery, charges, refunds, other accounting writes and\narbitrary mutations are unavailable.\n\nEvery write requires a caller-generated `requestId`: 1–50 ASCII letters,\ndigits, underscores or hyphens, starting with a letter or digit. Keep it stable\nfor the exact intent and unique across requests/tools for this company. It is\nsent in Intuit's requestid query parameter with minorversion 75, rather than an\nidempotency header. Intuit documents recognizing the same content and ID and\nreturning the original response; no retention duration is established. This\nnever permits automatic replay. A dispatched write is sent once even after\n401, timeout, server failure or an invalid success response.\n\nAfter an unknown customer-create outcome, search exact DisplayName, including\ninactive records when needed, and inspect the match. For an invoice, search\nDocNumber plus CustomerRef and inspect currency, dates, lines and computed\namounts. DocNumber can repeat, so it alone proves nothing. Reconcile and report\nambiguity before considering another create; never generate a fresh requestId\nand blindly repeat a potentially committed intent. Unknown update outcomes\nneed a read of the known Id and version. A requestId is not a lookup endpoint or\na permanent duplicate-prevention guarantee.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `quickbooks_api_details`, `quickbooks_api_search`, `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:** `quickbooks_api_search` finds this API's operations and reads no account data, `quickbooks_api_details` shows one operation's contract, and `quickbooks_api_read` calls a reviewed read. An operation without a reviewed verdict is refused. 3 operations are refused by design; use `quickbooks_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. An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: Intuit fault 5010 for a stale SyncToken; Intuit fault 6240 for a duplicate DisplayName.\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": "## Accounting identity and joins\n\nAn Id identifies a record inside this company and record family. DocNumber is\na human label, may repeat, and is not an Id. SyncToken is the public record\nversion used for concurrency control, not an OAuth credential. References carry\nthe target Id in value; invoice CustomerRef joins Customer, bill VendorRef\njoins Vendor, and payment Line.LinkedTxn joins invoices or bills.\n\nAccounting Payment and BillPayment records describe received and paid money;\nreading them does not execute a payment. Desktop, Payments, Payroll, attachments,\nand unreviewed accounting entities are outside this connection.\n\n## Money, time and reports\n\nAmounts use decimal currency units, never integer cents. Preserve CurrencyRef\nand ExchangeRate when combining transactions; never sum unlike currencies.\nTxnDate is the company's accounting date, not a UTC instant. MetaData timestamps\ncarry their own offset. Customer and vendor searches omit inactive records\nunless the Active filter explicitly selects them.\n\nReports are trees with Header, Columns, nested Rows and section summaries.\nRead column types and metadata together with row values; column order and\nsection labels can change. Empty amount strings mean no value, not zero.\nDo not flatten away section identity or add totals to their component rows.\nCheck the returned period, basis, currency and NoReportData option before\ncomparing reports. Aging is an as-of snapshot, rather than a transaction range.\n\nReturn aggregates and the few identifying records the task needs; avoid\ncopying full customer or vendor directories into the conversation.\n\n\n## Named writes and reconciliation\n\nThe connector defaults to read-only. Deployment code must set `readOnly: false`\nto expose named writes; endpoint and pool read-only policies still apply. The\nAPI hatch remains read-only. `create_customer` accepts DisplayName and optional\nCompanyName. `update_customer` requires caller-observed Id and SyncToken and\nchanges only those naming fields with sparse:true. Omitted CompanyName stays\nunchanged. A stale-version conflict never fetches a newer version or overwrites\nit. Read and review the current record before proposing a new update.\nDisplayName must be unique across customers, vendors and employees.\n\n`create_invoice` creates a real accounting transaction, never a draft, for a\nverified US company and a customer using USD. This bounds the no-email claim\nto the reviewed US autosend contract and money to two-decimal USD units. First\nobserve an active customer with its CurrencyRef and active Service item Ids.\nSupply currency USD, a positive explicit exchange rate, accounting and\ndue dates, a reconciliation DocNumber and 1–20 lines. Each line is one service\nunit with an explicit positive amount in decimal currency units, supplied as a\nstring with exactly two fractional digits. No prices, dates or exchange rates\nare defaulted or fetched. Preflight reads verify the fixed company Country is US\nand recheck customer currency and item activity/type; they are not an atomic snapshot. Vendor validation can still\nreject changed references. Taxes and totals are computed by QuickBooks: inspect\nthe returned currency, exchange rate and totals; line sums are not a promise of\nan untaxed total. Locale/company tax requirements may reject this narrow body.\nNo customer/item creation happens implicitly.\nEach additional request charges the call-admission budget before dispatch.\nContradictory returned references, dates, rate or service prices produce an\nunknown outcome; reconcile through reads rather than repeating the write.\n\nInvoice email status is fixed to NotSet; online, IPN, credit-card, ACH, PayPal\nand Affirm payment flags are fixed false. No email field or send operation is\nexposed. Company invoice-autosend opt-in does not supply the documented\nNeedToSend request state. This prevents this creation request from asking Intuit\nto email the invoice, including when the customer has an email on file.\nInvoice updates are unavailable: preserving an existing send-ready state has\nnot been established safe, while resetting it would change payment settings.\nDeletes, voids, email delivery, charges, refunds, other accounting writes and\narbitrary mutations are unavailable.\n\nEvery write requires a caller-generated `requestId`: 1–50 ASCII letters,\ndigits, underscores or hyphens, starting with a letter or digit. Keep it stable\nfor the exact intent and unique across requests/tools for this company. It is\nsent in Intuit's requestid query parameter with minorversion 75, rather than an\nidempotency header. Intuit documents recognizing the same content and ID and\nreturning the original response; no retention duration is established. This\nnever permits automatic replay. A dispatched write is sent once even after\n401, timeout, server failure or an invalid success response.\n\nAfter an unknown customer-create outcome, search exact DisplayName, including\ninactive records when needed, and inspect the match. For an invoice, search\nDocNumber plus CustomerRef and inspect currency, dates, lines and computed\namounts. DocNumber can repeat, so it alone proves nothing. Reconcile and report\nambiguity before considering another create; never generate a fresh requestId\nand blindly repeat a potentially committed intent. Unknown update outcomes\nneed a read of the known Id and version. A requestId is not a lookup endpoint or\na permanent duplicate-prevention guarantee.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `quickbooks_api_details`, `quickbooks_api_search`, `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:** `quickbooks_api_search` finds this API's operations and reads no account data, `quickbooks_api_details` shows one operation's contract, and `quickbooks_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. An operation without a reviewed verdict is refused. 3 operations are refused by design; use `quickbooks_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: Intuit fault 5010 for a stale SyncToken; Intuit fault 6240 for a duplicate DisplayName.\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": "Company instructions"
 };

package/dist/providers/sheets/api.js

@@ -121,6 +121,7 @@ export const safety = {
             return { method: op.method, template: op.path };
         },
         redact: (data, op) => values.redact(data, op.method, op.template),
+        withholds: (op) => values.withholds(op.method, op.template),
         withholdsErrors: (op) => values.withholdsErrors(sheetsIndex.ops.find((entry) => entry.method === op.method && entry.path === op.template)),
     },
     sensitiveFields: { names: [], choice: "drop" },

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Find the workbook and resolve ranges\n\nSheets starts from a spreadsheet id. A spreadsheet id the person gives works\nas is; search Drive only for a name. The Drive file id is\nthe spreadsheet id. Moving, sharing and trashing the file also belong to Drive.\nRead `get_spreadsheet` first to resolve sheet titles, numeric sheet ids and named\nranges before writing. Sheet id zero is valid; a tab's position is not its id.\n\nA1 ranges use sheet titles; structural GridRanges use numeric sheet ids with\nzero-based, end-exclusive row and column indexes. Quote titles containing\nspaces or punctuation and double apostrophes: `'Alice''s costs'!A1:D7`.\nA bare title may resolve to a named range; quote it to address the whole tab.\n\n## Read cell meaning\n\nDisplayed values reflect spreadsheet locale and number formats. Use\nunformatted numbers for arithmetic and formulas when inspecting expressions.\nDate serials count days from 1899-12-30; interpret dates using the workbook's\ntime zone. Trailing empty rows and cells may be absent. An empty range is a\nvalid result, not proof that the sheet is missing.\n\nWhole-row content reads can resume partway through a range. A named range or\nwhole-sheet reference may be re-read and earlier rows skipped; rowOffset is\nrelative to Google's echoed range. Reduce amounts inside execute_code before\nreturning them. Read an oversized cell separately to recover its full text.\n\n## Edit and reconcile\n\nUse RAW for external data; USER_ENTERED can turn leading equals signs into\nformulas. In cell writes, null leaves a cell unchanged and an empty string\nclears it. Clearing preserves formatting and validation. `append_values` is\npinned to INSERT_ROWS and inserts rows after the detected table. A vendor append using\nOVERWRITE can replace existing cells below that table.\n\nRead just before replacing another person's cells. Sheets has no revision\nprecondition or replay key: concurrent edits can be overwritten. After an\nuncertain append, read the target table and identify the row before adding\nanything missing. After an uncertain workbook create, search Drive by title\nbefore creating another workbook.\n\nStructural batches apply atomically, but can delete rows, sheets or\nprotections. An oversized reply may be summarized after the edit saved;\ninspect the workbook to recover details. Preview comment mutations and\nexternal data-source configuration, refresh and administration are outside\nthis connection. Developer-metadata searches and data-filter reads are\nread-only even though their wire method is POST.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `get_values`, `sheets_api_details`, `sheets_api_search`, 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:** `sheets_api_search` finds this API's operations and reads no account data, `sheets_api_details` shows one operation's contract, and `sheets_api_read` calls a reviewed read. `sheets_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. 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": "## Find the workbook and resolve ranges\n\nSheets starts from a spreadsheet id. A spreadsheet id the person gives works\nas is; search Drive only for a name. The Drive file id is\nthe spreadsheet id. Moving, sharing and trashing the file also belong to Drive.\nRead `get_spreadsheet` first to resolve sheet titles, numeric sheet ids and named\nranges before writing. Sheet id zero is valid; a tab's position is not its id.\n\nA1 ranges use sheet titles; structural GridRanges use numeric sheet ids with\nzero-based, end-exclusive row and column indexes. Quote titles containing\nspaces or punctuation and double apostrophes: `'Alice''s costs'!A1:D7`.\nA bare title may resolve to a named range; quote it to address the whole tab.\n\n## Read cell meaning\n\nDisplayed values reflect spreadsheet locale and number formats. Use\nunformatted numbers for arithmetic and formulas when inspecting expressions.\nDate serials count days from 1899-12-30; interpret dates using the workbook's\ntime zone. Trailing empty rows and cells may be absent. An empty range is a\nvalid result, not proof that the sheet is missing.\n\nWhole-row content reads can resume partway through a range. A named range or\nwhole-sheet reference may be re-read and earlier rows skipped; rowOffset is\nrelative to Google's echoed range. Reduce amounts inside execute_code before\nreturning them. Read an oversized cell separately to recover its full text.\n\n## Edit and reconcile\n\nUse RAW for external data; USER_ENTERED can turn leading equals signs into\nformulas. In cell writes, null leaves a cell unchanged and an empty string\nclears it. Clearing preserves formatting and validation. `append_values` is\npinned to INSERT_ROWS and inserts rows after the detected table. A vendor append using\nOVERWRITE can replace existing cells below that table.\n\nRead just before replacing another person's cells. Sheets has no revision\nprecondition or replay key: concurrent edits can be overwritten. After an\nuncertain append, read the target table and identify the row before adding\nanything missing. After an uncertain workbook create, search Drive by title\nbefore creating another workbook.\n\nStructural batches apply atomically, but can delete rows, sheets or\nprotections. An oversized reply may be summarized after the edit saved;\ninspect the workbook to recover details. Preview comment mutations and\nexternal data-source configuration, refresh and administration are outside\nthis connection. Developer-metadata searches and data-filter reads are\nread-only even though their wire method is POST.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `get_values`, `sheets_api_details`, `sheets_api_search`, 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:** `sheets_api_search` finds this API's operations and reads no account data, `sheets_api_details` shows one operation's contract, and `sheets_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `sheets_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. 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": "Connection instructions"
 };

package/dist/providers/sheets/tools.js

@@ -1,3 +1,5 @@
+import { routePhrases } from "../../agent-routes.js";
+import { asRecord, asArray, compact } from "../_shared/json.js";
 // Google Sheets named projections, bounded cell reads and guarded writes.
 import { Effect, Option, Schema } from "effect";
 import { ConnectorCallError } from "../../errors.js";
@@ -7,7 +9,7 @@ import { clampText, jsonBytes, RESULT_BUDGET_BYTES } from "../_shared/google/res
 import { encodeForAgent, redactBeforeCut } from "../../sent-secrets.js";
 import { read, write } from "../../http/tools.js";
 import { boundCursor } from "../../http/paging.js";
-import { fieldsInput, fieldsProblem, selectFields } from "../../http/fields.js";
+import { fieldsContract, selectFields } from "../../http/fields.js";
 import { Operation } from "../../runtime/call.js";
 import { sheetsIndex } from "./lib/hatch.js";
 import { SHEETS_ADMITTED_KINDS, SHEETS_REFUSED_KINDS, sheetsExternalDataProblem } from "./lib/requests.js";
@@ -38,15 +40,6 @@ const MAX_CELL_CHARS = 50_000;
 const MAX_WRITE_CELLS = 50_000;
 /** Named ranges a metadata read lists before reporting a size cut. */
 const MAX_NAMED_RANGES = 200;
-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));
-}
 function text(value) {
     return typeof value === "string" && value !== "" ? value : undefined;
 }
@@ -158,19 +151,19 @@ function cappedCell(ctx, whole, max, cut) {
     return `${value.slice(0, max)}[… ${value.length - max} more characters truncated; read this cell alone with maxCellChars up to ${MAX_CELL_CHARS} for the rest]`;
 }
 /** Refuse a row no page of `budget` bytes can hold, rather than overrun the cap. */
-function rowTooLarge(range, row, needed, budget) {
-    return new ConnectorCallError("invalid_args", `Row ${row} of ${range} needs a page of ${needed} bytes with the page's own fields, more than this page's maxBytes of ${budget}; narrow the range's columns or lower maxCellChars${raiseBytes(needed)}.`);
+function rowTooLarge(range, row, needed, budget, phrases) {
+    return new ConnectorCallError("invalid_args", `Row ${row} of ${range} needs a page of ${needed} bytes with the page's own fields, more than this page's maxBytes of ${budget}; narrow the range's columns or lower maxCellChars${raiseBytes(needed, phrases)}.`);
 }
 /** Refuse a page too small for even one range's own fields. */
-function pageTooSmall(range, needed, budget) {
-    return new ConnectorCallError("invalid_args", `A page reporting ${range} needs ${needed} bytes before any of its rows, more than this page's maxBytes of ${budget}; shorten the range${raiseBytes(needed)}.`);
+function pageTooSmall(range, needed, budget, phrases) {
+    return new ConnectorCallError("invalid_args", `A page reporting ${range} needs ${needed} bytes before any of its rows, more than this page's maxBytes of ${budget}; shorten the range${raiseBytes(needed, phrases)}.`);
 }
-function raiseBytes(needed) {
+function raiseBytes(needed, phrases) {
     if (needed > MAX_PAGE_BYTES)
         return "";
     return needed <= DEFAULT_PAGE_BYTES
         ? `, or raise maxBytes to at least ${needed}`
-        : `, or raise maxBytes to at least ${needed} (above ${DEFAULT_PAGE_BYTES}, only for a direct call_tool read: execute_code cannot receive it)`;
+        : `, or raise maxBytes to at least ${needed} (above ${DEFAULT_PAGE_BYTES}, ${phrases.onlyDirectRead}${phrases.program ? `: ${phrases.program} cannot receive it` : ""})`;
 }
 /** Refuse a row no page of `budget` cells can hold, rather than overrun the cap. */
 function rowTooWide(range, row, width, budget) {
@@ -457,7 +450,7 @@ export function sheetsTools({ connection }) {
                     })) + 1;
                     if (bytes + fields > byteBudget) {
                         if (valueRanges.length === 0)
-                            throw pageTooSmall(echoed, bytes + fields, byteBudget);
+                            throw pageTooSmall(echoed, bytes + fields, byteBudget, routePhrases(ctx));
                         next = { i: resume.i + index, s: before };
                         break;
                     }
@@ -478,7 +471,7 @@ export function sheetsTools({ connection }) {
                         const size = jsonBytes(capped) + 1;
                         if (bytes + size > byteBudget) {
                             if (empty)
-                                throw rowTooLarge(echoed, dropped + 1, bytes + size, byteBudget);
+                                throw rowTooLarge(echoed, dropped + 1, bytes + size, byteBudget, routePhrases(ctx));
                             break;
                         }
                         cells += width;
@@ -710,15 +703,13 @@ export function sheetsTools({ connection }) {
         };
         if (!declaration.annotations.readOnlyHint)
             return write(connection, { ...spec, destructive: declaration.annotations.destructiveHint });
+        const contract = fieldsContract("result", declaration.output, "Truncation and content continuation metadata remain available.");
         return read(connection, {
             ...spec,
-            input: Schema.Struct({
-                ...declaration.input.fields,
-                fields: Schema.optionalKey(fieldsInput("Dot paths to keep; truncation and content continuation metadata remain available.")),
-            }),
+            input: Schema.Struct({ ...declaration.input.fields, fields: Schema.optionalKey(contract.input) }),
             run: (args) => Effect.gen(function* () {
                 const { fields, ...rest } = args;
-                const problem = fieldsProblem(fields, new Set(Object.keys(declaration.output.fields)), "the Sheets result");
+                const problem = contract.problem(fields);
                 if (problem)
                     return yield* Effect.fail(new Refusal({ error: problem }));
                 const result = yield* spec.run(rest);

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Find and read a deck\n\nSlides cannot search or list decks. Find the file through Drive, or take the\npresentation id from `/presentation/d/<id>/` in its URL. A presentation is a\nDrive file; finding one does not grant permission to open it. A user-given id\nworks as is; no Drive lookup is needed to use it.\n\n`get_presentation` reads text in page order, with speaker notes, alt text and\nplaceholder ids. `get_page` opens groups and reads a slide, layout, master or\nnotes page. A slide's `index` is zero-based. Resolve a layout's placeholders\nwith `list_layouts` and `get_page` before filling a new slide.\nNamed-read `fields` narrows data while preserving `page` and `truncated` cut disclosures.\n\nText and notes have independent continuation. Pass an element's `textCursor`\nor a slide's `elementsCursor` to `get_page` with that slide's id; pass a\n`notesCursor` with its `notesPageId`. A deck's `layoutsCursor` continues in\n`list_layouts`. Content cursors bind to the deck's revision and the text they\ncontinue; a changed deck requires a fresh read. Follow continuation even when\na result contains fewer rows than requested.\n\nFor styles, transforms, HTML comment content, anchors' ranges or other full\nstructural JSON, use `slides_api_read`. Operation details use the legacy\n`presentationsId` spelling for presentations.get; pages and batch updates use\n`presentationId`. These are path parameter names, not query arguments.\nSpell colons and unreserved characters literally in hatch paths; encode other\ncharacters within one id segment. Named tools handle their own id encoding.\n\n`slides_api_read` with `{path: \"/presentations/<id>\"}` returns `{status,data}`;\nthe vendor presentation is `data`. A Connecta call's result delivery wraps that\ntool value in its own `data`; follow its result handle for large JSON.\nContent cursors belong to the named reading tools and are separate from that delivery handle.\n\n`get_slide_thumbnail` returns a link that opens as the delegated person for\nabout 30 minutes. Keep it private. Generic thumbnail/preview operations are\nrefused; use the named thumbnail workflow.\n\n## Edit at the version you read\n\nRead before editing and use its `revisionId` as the write precondition.\nRevision ids are preconditions, not replay keys. `create_slide` adds an empty\nslide; read its placeholder ids before inserting text. `replace_all_text`\nreplaces literal text, with `matchCase` and an optional `requiredRevisionId`.\nEach write returns the new `revisionId` for the next one. A `conflict` means\nthe deck changed since your read: re-read, rebuild the requests, and send them\nwith the new `revisionId`. A failure that says the write applied means Google\nanswered 2xx: do not repeat it; re-read. No Slides tool shares, moves or deletes\nthe deck file.\n\n`batch_update_presentation` takes the existing reviewed Request kinds.\nThe generic batch hatch uses `POST /presentations/deck1:batchUpdate` with\n`body: {requests: [{insertText: {objectId: \"shape1\", text: \"Hello\"}}],\nwriteControl: {requiredRevisionId: \"revision-from-read\"}}`. It retains the\nsame request-kind and revision guards. No additional preview capabilities are\nadmitted by indexing the complete Discovery document.\n\n## Comments can save separately\n\nA comment thread's `commentId` identifies the thread; its head post and\nreplies have their own `postId`. Authors' `user` ids are stable; display names\nare labels. Anchors join to page and object ids; speaker-note comments belong\nto the notes page. Reading comments requires comment access. A view-only\naccount may be refused rather than receiving an apparently empty list.\n\nResolve, reopen or reassign a thread with `update_comment_thread`; edit its\ntext with `update_comment_post`. Reassignment requires content. Only the\npost's author can edit or delete that post. Comments notify people as in the\nSlides editor.\n\n`create_comment` sends one `insertComment` by itself. When one edit changes\nthe deck and adds or changes comments, send it as one `batch_update_presentation`\ncall: `insertComment`, `addCommentReply`, `updateCommentPost`, `deleteComment`\nand `deleteCommentReply` are Request kinds and share a batch with deck kinds\nsuch as `updateTextStyle`, under the same `requiredRevisionId`. Slides saves\nthe deck part and the comment part separately, so a successful mixed batch can\nsave the deck without confirming the comments. When `commentUpdateState` is not\n`ALL_SAVED`, or the result says comment saves are unconfirmed, read the deck and\n`list_comments`, report the deck part and the comment part each as saved or\nunconfirmed, and send neither the batch nor its comment part again. Keep every\ncreated id for reconciliation.\n\n`create_comment_reply` sends one reply by itself. The write hatch keeps\ncomment-save state and advice in envelope-level `warnings`, even with\n`fields: [\"replies\"]`; Google's own state remains in vendor `data` when supplied.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `get_page`, `get_presentation`, `list_comments`, `list_layouts`, `slides_api_details`, `slides_api_search`, 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:** `slides_api_search` finds this API's operations and reads no account data, `slides_api_details` shows one operation's contract, and `slides_api_read` calls a reviewed read. `slides_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 1 operation is refused by design; use `slides_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. 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 content or revision bound to a named continuation cursor changed; restart the read.\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 and read a deck\n\nSlides cannot search or list decks. Find the file through Drive, or take the\npresentation id from `/presentation/d/<id>/` in its URL. A presentation is a\nDrive file; finding one does not grant permission to open it. A user-given id\nworks as is; no Drive lookup is needed to use it.\n\n`get_presentation` reads text in page order, with speaker notes, alt text and\nplaceholder ids. `get_page` opens groups and reads a slide, layout, master or\nnotes page. A slide's `index` is zero-based. Resolve a layout's placeholders\nwith `list_layouts` and `get_page` before filling a new slide.\nNamed-read `fields` narrows data while preserving `page` and `truncated` cut disclosures.\n\nText and notes have independent continuation. Pass an element's `textCursor`\nor a slide's `elementsCursor` to `get_page` with that slide's id; pass a\n`notesCursor` with its `notesPageId`. A deck's `layoutsCursor` continues in\n`list_layouts`. Content cursors bind to the deck's revision and the text they\ncontinue; a changed deck requires a fresh read. Follow continuation even when\na result contains fewer rows than requested.\n\nFor styles, transforms, HTML comment content, anchors' ranges or other full\nstructural JSON, use `slides_api_read`. Operation details use the legacy\n`presentationsId` spelling for presentations.get; pages and batch updates use\n`presentationId`. These are path parameter names, not query arguments.\nSpell colons and unreserved characters literally in hatch paths; encode other\ncharacters within one id segment. Named tools handle their own id encoding.\n\n`slides_api_read` with `{path: \"/presentations/<id>\"}` returns `{status,data}`;\nthe vendor presentation is `data`. A Connecta call's result delivery wraps that\ntool value in its own `data`; follow its result handle for large JSON.\nContent cursors belong to the named reading tools and are separate from that delivery handle.\n\n`get_slide_thumbnail` returns a link that opens as the delegated person for\nabout 30 minutes. Keep it private. Generic thumbnail/preview operations are\nrefused; use the named thumbnail workflow.\n\n## Edit at the version you read\n\nRead before editing and use its `revisionId` as the write precondition.\nRevision ids are preconditions, not replay keys. `create_slide` adds an empty\nslide; read its placeholder ids before inserting text. `replace_all_text`\nreplaces literal text, with `matchCase` and an optional `requiredRevisionId`.\nEach write returns the new `revisionId` for the next one. A `conflict` means\nthe deck changed since your read: re-read, rebuild the requests, and send them\nwith the new `revisionId`. A failure that says the write applied means Google\nanswered 2xx: do not repeat it; re-read. No Slides tool shares, moves or deletes\nthe deck file.\n\n`batch_update_presentation` takes the existing reviewed Request kinds.\nThe generic batch hatch uses `POST /presentations/deck1:batchUpdate` with\n`body: {requests: [{insertText: {objectId: \"shape1\", text: \"Hello\"}}],\nwriteControl: {requiredRevisionId: \"revision-from-read\"}}`. It retains the\nsame request-kind and revision guards. No additional preview capabilities are\nadmitted by indexing the complete Discovery document.\n\n## Comments can save separately\n\nA comment thread's `commentId` identifies the thread; its head post and\nreplies have their own `postId`. Authors' `user` ids are stable; display names\nare labels. Anchors join to page and object ids; speaker-note comments belong\nto the notes page. Reading comments requires comment access. A view-only\naccount may be refused rather than receiving an apparently empty list.\n\nResolve, reopen or reassign a thread with `update_comment_thread`; edit its\ntext with `update_comment_post`. Reassignment requires content. Only the\npost's author can edit or delete that post. Comments notify people as in the\nSlides editor.\n\n`create_comment` sends one `insertComment` by itself. When one edit changes\nthe deck and adds or changes comments, send it as one `batch_update_presentation`\ncall: `insertComment`, `addCommentReply`, `updateCommentPost`, `deleteComment`\nand `deleteCommentReply` are Request kinds and share a batch with deck kinds\nsuch as `updateTextStyle`, under the same `requiredRevisionId`. Slides saves\nthe deck part and the comment part separately, so a successful mixed batch can\nsave the deck without confirming the comments. When `commentUpdateState` is not\n`ALL_SAVED`, or the result says comment saves are unconfirmed, read the deck and\n`list_comments`, report the deck part and the comment part each as saved or\nunconfirmed, and send neither the batch nor its comment part again. Keep every\ncreated id for reconciliation.\n\n`create_comment_reply` sends one reply by itself. The write hatch keeps\ncomment-save state and advice in envelope-level `warnings`, even with\n`fields: [\"replies\"]`; Google's own state remains in vendor `data` when supplied.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `get_page`, `get_presentation`, `list_comments`, `list_layouts`, `slides_api_details`, `slides_api_search`, 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:** `slides_api_search` finds this API's operations and reads no account data, `slides_api_details` shows one operation's contract, and `slides_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `slides_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 1 operation is refused by design; use `slides_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; The content or revision bound to a named continuation cursor changed; restart the read.\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": "Connection instructions"
 };

package/dist/providers/slides/tools.js

@@ -1,3 +1,6 @@
+import { routePhrases } from "../../agent-routes.js";
+import { asRecord, asArray, compact } from "../_shared/json.js";
+import { decodeBase64url } from "../../bytes.js";
 // Google Slides named workflows on real kit schemas, with bound content continuation.
 import { Effect, Option, Schema } from "effect";
 import { ConnectorCallError } from "../../errors.js";
@@ -9,7 +12,7 @@ import { SLIDES_INDEX } from "./api.js";
 import * as contracts from "./lib/schemas.js";
 import { read, write } from "../../http/tools.js";
 import { Operation } from "../../runtime/call.js";
-import { fieldsInput, fieldsProblem, selectFields } from "../../http/fields.js";
+import { fieldsContract, selectFields } from "../../http/fields.js";
 import { Refusal } from "../../http/errors.js";
 import { boundCursor } from "../../http/paging.js";
 /** Slides per page of get_presentation. Slides itself returns the whole deck. */
@@ -52,7 +55,7 @@ const MAX_ECHO_CHARS = 100;
 /**
  * The comment kinds of Slides' Request. A batch carrying any of them has
  * comment changes Slides saves apart from the deck's, and only `ALL_SAVED`
- * says they all landed (#696).
+ * says they all landed.
  */
 /** The comment save states that say every comment change in a batch landed, or none was asked for. */
 const COMMENTS_SETTLED = new Set(["NO_UPDATES_REQUESTED", "ALL_SAVED"]);
@@ -121,15 +124,6 @@ const COMMENT_DECK_FIELDS = "presentationId,revisionId,commentsViewMode,comments
     "slides(objectId,commentAnchors,slideProperties(notesPage(objectId,commentAnchors)))," +
     "layouts(objectId,commentAnchors),masters(objectId,commentAnchors),notesMaster(objectId,commentAnchors)";
 const COMMENT_PAGE_FIELDS = "objectId,revisionId,commentsViewMode,comments,commentAnchors";
-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));
-}
 function text(value) {
     return typeof value === "string" && value !== "" ? value : undefined;
 }
@@ -226,9 +220,7 @@ function decodeCursor(value, expected) {
     const refuse = (why) => new ConnectorCallError("invalid_args", `${why} Omit cursor to start from the beginning.`);
     let cursor;
     try {
-        const base64 = String(value).replace(/-/g, "+").replace(/_/g, "/");
-        const binary = atob(base64 + "=".repeat((4 - (base64.length % 4)) % 4));
-        cursor = JSON.parse(new TextDecoder().decode(Uint8Array.from(binary, (character) => character.charCodeAt(0))));
+        cursor = JSON.parse(new TextDecoder().decode(decodeBase64url(String(value), true)));
     }
     catch {
         throw refuse("cursor is not one this connection issued; pass page.nextCursor back unchanged.");
@@ -1808,9 +1800,13 @@ export function slidesTools({ connection }) {
                 if (bytes <= BRIDGE_BYTES)
                     return result;
                 if (bytes <= MAX_IDS_RESULT_BYTES) {
+                    // Only a surface that runs programs is told what a program can carry.
+                    const { program } = routePhrases(ctx);
+                    if (!program)
+                        return result;
                     return {
                         ...result,
-                        note: `${result.note ?? ""} At ${bytes} bytes this result is more than execute_code can carry (${BRIDGE_BYTES}): call the tool directly and page it with connecta.result.`.trim(),
+                        note: `${result.note ?? ""} At ${bytes} bytes this result is more than ${program} can carry (${BRIDGE_BYTES}): call the tool directly and page it with connecta.result.`.trim(),
                     };
                 }
                 // Past any result: the save state and how to recover the ids stay;
@@ -1827,27 +1823,24 @@ export function slidesTools({ connection }) {
     return declarations.map((declaration) => {
         const isRead = declaration.annotations.readOnlyHint === true;
         const isList = declaration.name.startsWith("list_");
-        const rowNames = new Set(Object.keys(declaration.name === "list_layouts" ? contracts.LayoutRow.fields : contracts.CommentRow.fields));
-        const names = isList
-            ? rowNames
-            : new Set(Object.keys(declaration.output.fields));
+        const fields = isRead
+            ? isList
+                ? fieldsContract("item", declaration.name === "list_layouts" ? contracts.LayoutRow : contracts.CommentRow, "Truncation metadata is preserved.")
+                : fieldsContract("result", declaration.output, "Page and truncation metadata are preserved.")
+            : undefined;
         const spec = {
             name: declaration.name,
             description: declaration.description,
-            input: isRead
+            input: fields
                 ? Schema.Struct({
                     ...declaration.input.fields,
-                    fields: Schema.optionalKey(fieldsInput(isList
-                        ? "Dot paths to keep in each item; truncation metadata is preserved."
-                        : "Dot paths to keep in the result; page and truncation metadata are preserved.")),
+                    fields: Schema.optionalKey(fields.input),
                 })
                 : declaration.input,
             output: declaration.output,
             ...(declaration.writeSteps ? { writeSteps: declaration.writeSteps } : {}),
             run: (args) => Effect.gen(function* () {
-                const problem = isRead
-                    ? fieldsProblem(args["fields"], names, isList ? "a Slides list item" : "the result")
-                    : undefined;
+                const problem = fields?.problem(args["fields"]);
                 if (problem)
                     return yield* Effect.fail(new Refusal({ error: problem }));
                 const current = yield* Effect.serviceOption(Operation);

package/dist/providers/stripe/index.js

@@ -1,3 +1,4 @@
+import { readOnlyNotice } from "../_shared/guide.js";
 import { keys, optionsOf, variants } from "../../config-schema.js";
 import { defineApiProvider } from "../../http/provider.js";
 import { authenticate, connectedAccount, MAX_RESPONSE_BYTES, READ_CAP_MS, MODE_COPY, probe, safety, stripeErrors, StripeApi, stripeIndex, stripeBinding, STRIPE_PAGES, STRIPE_VERDICTS, } from "./api.js";
@@ -63,7 +64,7 @@ function usageGuide(options) {
                     `Connected account: ${account}. Every call acts as this Connect account; the platform account's own objects are out of reach here.`,
                 ]
                 : []),
-            ...(options.readOnly === true ? ["This connection is read-only: every write is refused."] : []),
+            ...readOnlyNotice(options.readOnly === true),
         ],
         required: true,
     };

package/dist/providers/stripe/safety.js

@@ -1,4 +1,4 @@
-// Stripe's reviewed value-safety table (#801), on the shared mechanism in
+// Stripe's reviewed value-safety table, on the shared mechanism in
 // `../_shared/rest/value-safety.ts`: every operation the detector flags in the
 // pinned spec (`evidence/value-safety.json`) has one verdict here, and
 // `provider.safety.node.test.ts` runs the shared harness over it.
@@ -48,7 +48,7 @@
 // - Issuing card numbers and CVCs come back only as expansions, which the
 //   connector refuses on every Issuing path (`api.ts`); the card operations
 //   also redact both fields.
-// Embedded URL verdict (#812): reviewed paths + global signing parameters.
+// Embedded URL verdict: reviewed paths + global signing parameters.
 // Evidence: digest-verified Stripe v2555, components/schemas/charge's
 // failure_message ("Message to user further explaining reason for charge
 // failure") and charge_outcome.seller_message (Stripe's human-readable

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Account and money\n\nBefore investigating a payment or moving money, confirm the account and mode\nwith `get_stripe_account_info`. A Connect account's objects belong to that\naccount, rather than the platform's account. Sandbox objects do not establish anything about live\ncustomers, revenue or payouts.\n\nResolve ids before acting. Stripe ids identify types: `cus_` customer, `sub_`\nsubscription, `ch_` charge, `pi_` PaymentIntent, `in_` invoice and `acct_`\naccount. A plausible-looking id can refer to a different object or to nobody.\n\nAmounts are integers in the currency's minor unit: 1099 is 10.99 USD, while\n10 is 10 JPY. Keep currencies separate when totaling balances or payments.\n\n## Payment investigations\n\nA PaymentIntent's `latest_charge` joins it to the charge holding the payment's\n`outcome`, `failure_code` and `failure_message`. Follow that reference to\nexplain a decline. Search supports a documented field set for each resource;\ncharge search has no `payment_intent` field. Resolve the parent and follow its\nreference when the needed relationship is not searchable.\n\nSearch is eventually consistent; use a direct object read to reconcile a\nrecent write. A POST's idempotency key identifies the exact operation and\nparameters. Stripe v1 may prune keys after 24 hours, so reconcile the object\nbefore attempting the operation outside that window. A new key can create a\nsecond payment or refund.\n\nIn v1 requests, an empty string (`\"\"`) or `null` unsets a field.\n\n## Data reduction and boundaries\n\nKeep only the customer and payment facts the question needs. Reduce lists to\ncounts, totals or matching records before returning them to the conversation.\nUse the account and balance summaries when their projections answer the task;\nother account fields and balance transactions are available through the API.\n\nCredential creation, customer/account sign-in links, secret payload expansions,\nfull Issuing card details, file uploads and the meter-event stream are outside\nthis connection's surface. Use the Dashboard or application server for those\nflows. Single meter events remain available. A guest Checkout payment page is\navailable only when it is unbound to a Customer or Account and cannot manage\nsaved payment methods; use a payment link or hosted invoice for other cases.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `stripe_api_details`, `stripe_api_read`, `stripe_api_search`, 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:** `stripe_api_search` finds this API's operations and reads no account data, `stripe_api_details` shows one operation's contract, and `stripe_api_read` calls a reviewed read. `stripe_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 15 operations are refused by design; use `stripe_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. A write that takes `idempotencyKey` may be repeated with the same key and arguments while the vendor retains it.\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. `conflict` means: HTTP 409 when the request conflicts with another request, including a concurrent use of the same idempotency key; HTTP 429 with code lock_timeout when another request holds the object's lock.\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": "## Account and money\n\nBefore investigating a payment or moving money, confirm the account and mode\nwith `get_stripe_account_info`. A Connect account's objects belong to that\naccount, rather than the platform's account. Sandbox objects do not establish anything about live\ncustomers, revenue or payouts.\n\nResolve ids before acting. Stripe ids identify types: `cus_` customer, `sub_`\nsubscription, `ch_` charge, `pi_` PaymentIntent, `in_` invoice and `acct_`\naccount. A plausible-looking id can refer to a different object or to nobody.\n\nAmounts are integers in the currency's minor unit: 1099 is 10.99 USD, while\n10 is 10 JPY. Keep currencies separate when totaling balances or payments.\n\n## Payment investigations\n\nA PaymentIntent's `latest_charge` joins it to the charge holding the payment's\n`outcome`, `failure_code` and `failure_message`. Follow that reference to\nexplain a decline. Search supports a documented field set for each resource;\ncharge search has no `payment_intent` field. Resolve the parent and follow its\nreference when the needed relationship is not searchable.\n\nSearch is eventually consistent; use a direct object read to reconcile a\nrecent write. A POST's idempotency key identifies the exact operation and\nparameters. Stripe v1 may prune keys after 24 hours, so reconcile the object\nbefore attempting the operation outside that window. A new key can create a\nsecond payment or refund.\n\nIn v1 requests, an empty string (`\"\"`) or `null` unsets a field.\n\n## Data reduction and boundaries\n\nKeep only the customer and payment facts the question needs. Reduce lists to\ncounts, totals or matching records before returning them to the conversation.\nUse the account and balance summaries when their projections answer the task;\nother account fields and balance transactions are available through the API.\n\nCredential creation, customer/account sign-in links, secret payload expansions,\nfull Issuing card details, file uploads and the meter-event stream are outside\nthis connection's surface. Use the Dashboard or application server for those\nflows. Single meter events remain available. A guest Checkout payment page is\navailable only when it is unbound to a Customer or Account and cannot manage\nsaved payment methods; use a payment link or hosted invoice for other cases.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `stripe_api_details`, `stripe_api_read`, `stripe_api_search`, 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:** `stripe_api_search` finds this API's operations and reads no account data, `stripe_api_details` shows one operation's contract, and `stripe_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `stripe_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 15 operations are refused by design; use `stripe_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. A write that takes `idempotencyKey` may be repeated with the same key and arguments while the vendor retains it.\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. `conflict` means: HTTP 409 when the request conflicts with another request, including a concurrent use of the same idempotency key; HTTP 429 with code lock_timeout when another request holds the object's lock.\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": "Account instructions"
 };