@zackbart/connecta 0.39.0 → 0.41.0

package/dist/provider-call-facts.js

@@ -133,9 +133,13 @@ export function renewedAfterUnauthorized(request, sent, fresh) {
 export function refusalRequest(error) {
     return error !== null && typeof error === "object" ? refusals.get(error) : undefined;
 }
-export function knownProviderFailure(error) {
-    if (error !== null && typeof error === "object")
+/** A local refusal may additionally name the physical request it prevented. */
+export function knownProviderFailure(error, unsent) {
+    if (error !== null && typeof error === "object") {
         knownFailures.add(error);
+        if (unsent && !unsent.dispatched)
+            refusals.set(error, unsent);
+    }
     return error;
 }
 export function isKnownProviderFailure(error) {

package/dist/provider.d.ts

@@ -89,8 +89,8 @@ export declare const PROVIDER_COMMON: {
     };
     instructions: Field<unknown, unknown, true>;
     title: Field<unknown, unknown, true>;
-    authScope: Field<unknown, unknown, true>;
     purpose: Field<unknown, unknown, true>;
+    authScope: Field<unknown, unknown, true>;
     maxResultBytes: Field<unknown, unknown, true>;
 };
 /** The provider's maintained, connection-independent usage guide. */

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

@@ -92,8 +92,8 @@ export declare const GOOGLE_WORKSPACE_OPTIONS: import("../../../config-schema.js
         };
         instructions: import("../../../config-schema.js").Field<unknown, unknown, true>;
         title: import("../../../config-schema.js").Field<unknown, unknown, true>;
-        baseUrl: import("../../../config-schema.js").Field<unknown, unknown, true>;
         purpose: import("../../../config-schema.js").Field<unknown, unknown, true>;
+        baseUrl: import("../../../config-schema.js").Field<unknown, unknown, true>;
         maxResultBytes: import("../../../config-schema.js").Field<unknown, unknown, true>;
         readOnly: import("../../../config-schema.js").Field<unknown, unknown, true>;
         subject: import("../../../config-schema.js").Field<unknown, unknown, true>;

package/dist/providers/breeze/index.js

@@ -75,7 +75,7 @@ export const breeze = defineApiProvider({
                 ? [`Paged lists return ${options.defaultPageSize} items by default on this connection.`]
                 : []),
         ],
-        summary: "Church records: profile-field decoding, occurrence/person joins, decimal giving, and archival API caveats.",
+        summary: "Load for Breeze people, giving records, paging and guarded updates.",
         required: true,
     }),
     hatch: {

package/dist/providers/ccb/index.js

@@ -81,7 +81,7 @@ export const ccb = defineApiProvider({
                 ? [`Named lists default to ${options.defaultPerPage} rows on this connection.`]
                 : []),
         ],
-        summary: `${options.environment === "sandbox" ? "Sandbox" : "Production"} CCB, ${options.mode === "identity" ? "per person" : "church-wide"}: id resolution, sensitive data, paging, rate limits, hatches.`,
+        summary: "Load for CCB person ids, sensitive data, paging, rate limits and guarded writes.",
         required: true,
     }),
     pageSize: { default: 25, max: 100 },

package/dist/providers/cloudflare/index.js

@@ -75,7 +75,7 @@ function usageGuide(options) {
     const { auth, accountId, zoneId, pin } = settings(options);
     return {
         heading: "Cloudflare usage",
-        summary: "Configured Cloudflare REST credential: resolve domain/account ids, then inspect DNS, Workers, R2, KV or analytics.",
+        summary: "Load for Cloudflare DNS, Workers, R2, KV and analytics; resolve account and zone ids before calls.",
         context: [
             `Connector purpose: ${options.purpose}`,
             `This connection already has an operator-configured ${auth === "apiToken" ? "scoped API token" : "Global API Key"}; there is no sign-in step.`,

package/dist/providers/docs/index.js

@@ -101,7 +101,7 @@ export const docs = defineApiProvider({
             "Workspace delegation is configured by the deployment. Each call acts as the mapped Workspace user; document access follows that user's Drive sharing.",
             ...(options.readOnly ? ["This connection is read-only."] : []),
         ],
-        summary: "Docs by id: tabs, UTF-16 edit indexes, revisions and partial-create recovery.",
+        summary: "Load for Docs tabs, UTF-16 edit indexes, revision checks and partial-create recovery.",
         required: true,
     }),
     hatch: {

package/dist/providers/drive/index.js

@@ -105,7 +105,7 @@ export const drive = defineApiProvider({
             `Connection purpose: ${options.purpose}`,
             "Acts as the Workspace user deployment config maps from the admitted caller or pool owner. No caller argument selects an account. An unmapped or ownerless caller has no access unless the deployment fixes a shared account.",
         ],
-        summary: "Each caller's Drive files, bounded content, recoverable trash and quiet sharing.",
+        summary: "Load for Drive file discovery, bounded content, recoverable trash and sharing.",
         required: true,
     }),
     tools: driveTools,

package/dist/providers/forms/index.js

@@ -101,7 +101,7 @@ export const forms = defineApiProvider({
             ...(options.readOnly ? ["This connection is read-only."] : []),
         ],
         instructions: options.instructions,
-        summary: "Each caller's own forms: questions by id, labeled responses, revision-checked batch edits.",
+        summary: "Load for form questions, labeled responses and revision-checked batch edits.",
         // Required: whose forms they are, that Drive lists them, and the
         // revision-checked edit sequence are conventions no schema can carry.
         required: true,

package/dist/providers/github/index.js

@@ -39,7 +39,7 @@ export const github = defineProvider({
                 "The App identity is already configured. Installation access is resolved on use; ask the operator to repair configuration only after an auth failure.",
                 ...(options.readOnly === true ? ["This connection is read-only; every write is refused."] : []),
             ],
-            summary: "GitHub App repository reads, scoped data search, release writes and guarded merges.",
+            summary: "Load for GitHub repository searches, releases and guarded merges.",
             required: true,
         });
         const credential = options.app.privateKey === undefined

package/dist/providers/gmail/index.js

@@ -133,7 +133,7 @@ export const gmail = defineApiProvider({
             "A missing subject fails auth_required; ask the operator to repair configuration after an auth failure.",
             ...(options.readOnly ? ["This connection is read-only; draft writes are refused."] : []),
         ],
-        summary: "Each caller's own mailbox: Gmail search syntax, capped bodies, reply threading, drafts that never send.",
+        summary: "Load for Gmail search, capped message bodies, threaded replies and drafts that never send.",
         required: true,
     }),
     tools: gmailTools,

package/dist/providers/granola/index.js

@@ -46,7 +46,7 @@ export const granola = defineApiProvider({
     probe,
     guide: (options) => ({
         heading: "Granola usage",
-        summary: "Read workspace notes and transcripts; discover accessible spaces and folders before filtering.",
+        summary: "Load for workspace notes and transcripts; discover accessible spaces and folders before filtering.",
         context: [
             `Workspace purpose: ${options.purpose}`,
             "One shared workspace API key over REST. This connection exposes only reviewed reads.",

package/dist/providers/overflow/index.js

@@ -87,7 +87,7 @@ export const overflow = defineApiProvider({
                 ? [`Paged lists return ${options.defaultPageSize} items by default on this connection.`]
                 : []),
         ],
-        summary: "Giving records: asset-specific status, per-field money units, donor joins and deposit reconciliation.",
+        summary: "Load for giving statuses, money units, donor joins and deposit reconciliation.",
         required: true,
     }),
     hatch: {

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

@@ -44,7 +44,7 @@ export const planningCenter = defineApiProvider({
     },
     guide: (options) => ({
         heading: "Planning Center usage",
-        summary: "People ids join reachable products; use their local dates, units, roles and documented status values.",
+        summary: "Load when joining Planning Center products by person id or interpreting dates, units, roles and statuses.",
         required: true,
         context: [
             `Purpose: ${options.purpose.trim()}`,

package/dist/providers/planning-center/lib/constants.d.ts

@@ -55,4 +55,4 @@ export declare const PLANNING_CENTER_MAX_RESPONSE_BYTES: number;
  */
 export declare const PLANNING_CENTER_ADMISSION: ConnectorCallAdmissionPolicy;
 /** Planning Center refuses a request without a descriptive one (HTTP 403). */
-export declare const DEFAULT_USER_AGENT = "connecta/0.39.0 (+https://github.com/zackbart/connecta)";
+export declare const DEFAULT_USER_AGENT = "connecta/0.41.0 (+https://github.com/zackbart/connecta)";

package/dist/providers/quickbooks/api.js

@@ -58,32 +58,35 @@ export const customerWrite = post("writeCustomer", "/customer", {
 }).annotate(Summary, "Create a customer or sparsely update naming fields through named tools only");
 export const invoiceWrite = post("createInvoice", "/invoice", {
     query: { minorversion: Schema.Literal("75"), requestid: Schema.String },
-    payload: Schema.Struct({
-        CustomerRef: Schema.Struct({ value: PublicId }),
-        CurrencyRef: Schema.Struct({ value: Schema.String }),
-        ExchangeRate: Schema.Number,
-        TxnDate: Schema.String,
-        DueDate: Schema.String,
-        DocNumber: Schema.String,
-        Line: Schema.Array(Schema.Struct({
-            Amount: Schema.Number,
-            DetailType: Schema.Literal("SalesItemLineDetail"),
-            SalesItemLineDetail: Schema.Struct({
-                ItemRef: Schema.Struct({ value: PublicId }),
-                Qty: Schema.Literal(1),
-                UnitPrice: Schema.Number,
-            }),
-        })),
-        EmailStatus: Schema.Literal("NotSet"),
-        AllowIPNPayment: Schema.Literal(false),
-        AllowOnlinePayment: Schema.Literal(false),
-        AllowOnlineCreditCardPayment: Schema.Literal(false),
-        AllowOnlineACHPayment: Schema.Literal(false),
-        AllowOnlinePayPalPayment: Schema.Literal(false),
-        AllowOnlineAffirmPayment: Schema.Literal(false),
-    }),
+    payload: Schema.Union([
+        Schema.Struct({
+            CustomerRef: Schema.Struct({ value: PublicId }),
+            CurrencyRef: Schema.Struct({ value: Schema.String }),
+            ExchangeRate: Schema.Number,
+            TxnDate: Schema.String,
+            DueDate: Schema.String,
+            DocNumber: Schema.String,
+            Line: Schema.Array(Schema.Struct({
+                Amount: Schema.Number,
+                DetailType: Schema.Literal("SalesItemLineDetail"),
+                SalesItemLineDetail: Schema.Struct({
+                    ItemRef: Schema.Struct({ value: PublicId }),
+                    Qty: Schema.Literal(1),
+                    UnitPrice: Schema.Number,
+                }),
+            })),
+            EmailStatus: Schema.Literal("NotSet"),
+            AllowIPNPayment: Schema.Literal(false),
+            AllowOnlinePayment: Schema.Literal(false),
+            AllowOnlineCreditCardPayment: Schema.Literal(false),
+            AllowOnlineACHPayment: Schema.Literal(false),
+            AllowOnlinePayPalPayment: Schema.Literal(false),
+            AllowOnlineAffirmPayment: Schema.Literal(false),
+        }),
+        Schema.Struct({ Id: PublicId, SyncToken, sparse: Schema.Literal(true), DocNumber: Schema.String }),
+    ]),
     success: Schema.Struct({ Invoice: RecordShape }),
-}).annotate(Summary, "Create a real unsent service invoice through create_invoice only");
+}).annotate(Summary, "Create an unsent service invoice or sparsely update an eligible unsent invoice number through named tools only");
 export const QuickBooksApi = vendor("QuickBooks Online", companyInfo, queryRecords, customerWrite, invoiceWrite, ...Object.values(recordReads), ...Object.values(reportReads));
 export const QUICKBOOKS_INDEX = vendorIndex(QuickBooksApi, {
     prefix: "quickbooks",

package/dist/providers/quickbooks/index.js

@@ -62,7 +62,7 @@ export const quickbooks = defineApiProvider({
                 : "This connection is read-only. Set readOnly: false in deployment code to enable bounded named writes.",
             "Contact details, bank/card/tax identifiers, credentials and private links are withheld on every read.",
         ],
-        summary: "QuickBooks Online accounting reads and explicitly enabled customer/service-invoice writes.",
+        summary: "Load for QuickBooks accounting reads and enabled customer or service-invoice writes.",
         required: true,
     }),
     hatch: {

package/dist/providers/quickbooks/lib/writes.js

@@ -85,6 +85,61 @@ export function quickbooksWrites(connection, realmId) {
                 .send(customerWrite, { query: { ...version, requestid: requestId }, payload: { ...body, sparse: true } })
                 .pipe(Effect.map(({ data }) => namedRecord(object(data)["Customer"]))),
         }),
+        write(connection, {
+            name: "update_unsent_invoice",
+            destructive: true,
+            idempotent: false,
+            description: "Sparsely change only DocNumber on an observed unsent US-company USD invoice. Requires caller-observed Id and SyncToken. Preflight refuses unknown, send-ready, delivered or payment-enabled state and stale versions. No delivery/payment settings are changed. Reconcile unknown outcomes by reading the Id; never replay.",
+            input: Schema.Struct({
+                requestId: RequestId,
+                Id: PublicId,
+                SyncToken,
+                docNumber: Schema.String.check(matches("^[A-Za-z0-9][A-Za-z0-9_-]{0,20}$")),
+            }),
+            check: (args, problems) => {
+                if (args.docNumber === "AUTO_GENERATE")
+                    problems.add("docNumber", "an explicit document number other than AUTO_GENERATE");
+            },
+            output: NamedRecordShape,
+            writeSteps: { company: "once", invoice: "once", write: "once" },
+            run: (args) => Effect.gen(function* () {
+                const company = object(object((yield* connection.send(companyInfo, { params: { id: realmId }, query: version }, { step: "company", effect: "read" })).data)["CompanyInfo"]);
+                if (company["Id"] !== realmId || company["Country"] !== "US")
+                    return yield* refuse("Invoice number updates require a verified US company.");
+                yield* charge;
+                const invoice = object(object((yield* connection.send(recordReads["invoices"], { params: { id: args.Id }, query: version }, { step: "invoice", effect: "read" })).data)["Invoice"]);
+                if (invoice["Id"] !== args.Id || invoice["SyncToken"] !== args.SyncToken)
+                    return yield* refuse("Invoice version changed; read and review the current invoice before a new intent.");
+                if (invoice["EmailStatus"] !== "NotSet" ||
+                    invoice["DeliveryInfo"] !== undefined ||
+                    object(invoice["CurrencyRef"])["value"] !== "USD" ||
+                    ![
+                        "AllowIPNPayment",
+                        "AllowOnlinePayment",
+                        "AllowOnlineCreditCardPayment",
+                        "AllowOnlineACHPayment",
+                        "AllowOnlinePayPalPayment",
+                        "AllowOnlineAffirmPayment",
+                    ].every((key) => invoice[key] === false))
+                    return yield* refuse("Only observed unsent USD invoices with explicit NotSet, no delivery information and all payment flags false qualify. Unknown state is refused.");
+                yield* charge;
+                const { data, status } = yield* connection.send(invoiceWrite, {
+                    query: { ...version, requestid: args.requestId },
+                    payload: { Id: args.Id, SyncToken: args.SyncToken, sparse: true, DocNumber: args.docNumber },
+                });
+                const updated = object(object(data)["Invoice"]);
+                if (updated["Id"] !== args.Id ||
+                    updated["DocNumber"] !== args.docNumber ||
+                    updated["SyncToken"] === args.SyncToken)
+                    return yield* Effect.fail(new StatusFailure({
+                        status,
+                        headers: new Headers(),
+                        body: undefined,
+                        operation: { method: "POST", template: "/invoice" },
+                    }));
+                return namedRecord(updated);
+            }),
+        }),
         write(connection, {
             name: "create_invoice",
             destructive: true,

package/dist/providers/quickbooks/safety.js

@@ -3,6 +3,13 @@ import { ConnectorCallError } from "../../errors.js";
 import { withholdEmbeddedUrls } from "../_shared/rest/value-safety.js";
 import { QUICKBOOKS_INDEX } from "./api.js";
 const scalars = [
+    "EmailStatus",
+    "AllowIPNPayment",
+    "AllowOnlinePayment",
+    "AllowOnlineCreditCardPayment",
+    "AllowOnlineACHPayment",
+    "AllowOnlinePayPalPayment",
+    "AllowOnlineAffirmPayment",
     "Id",
     "SyncToken",
     "DisplayName",
@@ -72,6 +79,7 @@ export const RecordShape = Schema.Struct({
     ...optional(scalars),
     ...optional(references),
     ...optional(details),
+    DeliveryInfo: Schema.optionalKey(Schema.Unknown),
     MetaData: Schema.optionalKey(Schema.Unknown),
     Line: Schema.optionalKey(Schema.Unknown),
     LinkedTxn: Schema.optionalKey(Schema.Unknown),
@@ -128,6 +136,8 @@ function safeRecord(value) {
     for (const key of references)
         if (source[key])
             out[key] = pick(source[key], ["value", "name", "type"]);
+    if (source["DeliveryInfo"] !== undefined)
+        out["DeliveryInfo"] = pick(source["DeliveryInfo"], ["DeliveryType", "DeliveryTime"]);
     if (source["MetaData"])
         out["MetaData"] = pick(source["MetaData"], ["CreateTime", "LastUpdatedTime"]);
     for (const key of details)
@@ -197,11 +207,13 @@ function recordPath(path) {
         return recordPath(rest);
     const picked = head === "MetaData"
         ? ["CreateTime", "LastUpdatedTime"]
-        : head === "LinkedTxn"
-            ? ["TxnId", "TxnType", "TxnLineId"]
-            : references.includes(head)
-                ? ["value", "name", "type"]
-                : undefined;
+        : head === "DeliveryInfo"
+            ? ["DeliveryType", "DeliveryTime"]
+            : head === "LinkedTxn"
+                ? ["TxnId", "TxnType", "TxnLineId"]
+                : references.includes(head)
+                    ? ["value", "name", "type"]
+                    : undefined;
     if (!picked)
         return "dropped";
     if (rest.length === 0)

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. 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.",
+    "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.\n`update_unsent_invoice` changes only DocNumber, with caller-observed Id and\nSyncToken. It reads the US company and invoice before dispatch and requires USD,\nexplicit NotSet, no DeliveryInfo and every payment flag explicitly false.\nMissing state, send-ready and delivered invoices are refused. It preserves all\nomitted settings through sparse:true and never substitutes a newer version.\nNo date edits are exposed. This removes documented autosend prerequisites;\napplying them to updates is an inference, not an Intuit update-specific no-email\nguarantee. NotSet cannot prove that no historical delivery ever occurred.\nRead the known Id after an uncertain response; never blindly resend.\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/index.js

@@ -110,7 +110,7 @@ export const sheets = defineApiProvider({
             ...(options.readOnly ? ["This connection is read-only."] : []),
         ],
         instructions: options.instructions,
-        summary: "Each caller's own spreadsheets by id: A1 ranges, cell-paged reads, RAW or USER_ENTERED writes, formatting and structure.",
+        summary: "Load for spreadsheet A1 ranges, paged cells, RAW/USER_ENTERED writes and formatting.",
         // Whose spreadsheets they are, how Drive finds them, and the cell-write
         // meanings of null and "" are conventions no schema carries.
         required: true,

package/dist/providers/slides/index.js

@@ -130,7 +130,7 @@ export const slides = defineApiProvider({
             "Generic thumbnails/preview links are refused; get_slide_thumbnail is the reviewed short-lived-link workflow. The generic batch retains only the 49 shipped request kinds; no extra preview methods are admitted.",
             ...(options.readOnly ? ["This connection is read-only; writes are refused."] : []),
         ],
-        summary: "Each caller's decks: text, notes, layouts, comments, guarded edits and indexed Slides JSON operations.",
+        summary: "Load for deck text, notes, layouts, comments and guarded Slides edits.",
         required: true,
     }),
     tools: slidesTools,

package/dist/providers/stripe/index.js

@@ -53,8 +53,8 @@ function usageGuide(options) {
     return {
         heading: "Stripe usage",
         summary: options.mode === "production"
-            ? "PRODUCTION: real money. One configured live-mode key over REST; resolve ids before acting."
-            : "Sandbox: test data only. One configured test-mode key over REST; resolve ids before acting.",
+            ? "Load for live Stripe payments, refunds and invoices; real money, resolve ids before acting."
+            : "Load for sandbox Stripe payments, refunds and invoices; test data, resolve ids before acting.",
         context: [
             `Mode: ${options.mode}. Connector purpose: ${options.purpose}`,
             copy.warning,

package/dist/providers/tithely/index.js

@@ -73,7 +73,7 @@ function usageGuide(options) {
                 ? [`List tools return ${options.defaultPageSize} rows by default on this connection.`]
                 : []),
         ],
-        summary: `${live ? "Live" : "Test"} giving: donor-data reduction, cents and ISO dates, ids that join, and the approval-gated write hatch.`,
+        summary: "Load for giving records, donor joins, cents, ISO dates and guarded writes.",
         // Required: the reduction rule for donor data and the id joins live only
         // in the guide. No schema can carry either.
         required: true,

package/dist/providers/vercel/api.js

@@ -414,6 +414,7 @@ export function usageGuide(options) {
     options = pinOptions(options);
     const team = defaultTeam(options);
     return {
+        summary: "Load for Vercel team scope, project/deployment ids, build events, runtime logs and guarded writes.",
         context: [
             `Vercel REST access token is already configured. Account purpose: ${options.purpose}`,
             options.pin

package/dist/registry.js

@@ -20,7 +20,7 @@ import { attachOAuthSealer, vaultOAuthSealer } from "./oauth-sealing.js";
 import { boundedStatus, failureRecord, failureStatus, logFailure, ownStatus } from "./operator-record.js";
 import { ObservedOutputSchemas } from "./result-shapes.js";
 import { ContinuationBinding, OperationCredentials, ContinuationStorage, operationView, setViewService, duringViewEffect, } from "./runtime/call.js";
-import { hasNativeStorage, registerNativeStorage } from "./runtime/native-storage.js";
+import { getNativeStorage, hasNativeStorage, registerNativeStorage } from "./runtime/native-storage.js";
 import { observeStorageWrites } from "./runtime/request-reads.js";
 import { attachStorageDigestKey } from "./storage-digest.js";
 import { requestReads } from "./runtime/request-scope.js";
@@ -31,7 +31,7 @@ import { Storage } from "./runtime/services.js";
 import { SharedRead } from "./runtime/shared-read.js";
 import { runOnPartition, storageCompareAndSet, storageDelete, storageGet, storageGetMany, storageSet, storageList, } from "./runtime/storage.js";
 import { redactCatalog, sentSecretsFor, sentSecretsForRequest } from "./sent-secrets.js";
-import { GUIDE_SUMMARY_LENGTH, normalizeGuideSummary } from "./skills.js";
+import { GUIDE_SUMMARY_LENGTH, normalizeGuideSummary, connectorGuide, connectorGuideSummary } from "./skills.js";
 import { jsonCodec, OAUTH_HANDOFF_TTL_SECONDS, oauthHandoffKeys, resultKeys, scopes, stashExpiryKeys, stashLedgerKeys, } from "./storage/keys.js";
 import { assertStaticToolNames, hasControlCharacters } from "./tool-name.js";
 import { carryToolClassification, classifyTool } from "./tool-safety.js";
@@ -298,6 +298,13 @@ export class Registry {
                     `normalization; the discovery bound is ${GUIDE_SUMMARY_LENGTH}. ` +
                     "Shorten it or omit it to derive one.");
             }
+            // Advisory English-language heuristic: a task verb or operation noun
+            // distinguishes actionable guidance from credential/scope facts. Never
+            // log guide text, which may contain deployment-private information.
+            if (connectorGuide(c) !== undefined &&
+                !/\b(load|use|when|read|reads|write|writes|search|query|inspect|resolve|list|review|edit|create|update|deploy|paging|reconciliation|accounting)\b/i.test(connectorGuideSummary(c) ?? "")) {
+                opts.logger.warn(`Connector "${c.id}" guide needs an actionable summary; say when to load it with usageGuide.summary.`);
+            }
             this.connectors.set(c.id, c);
             if (c.callAdmission !== undefined) {
                 this.callAdmission.set(c.id, new ConnectorCallAdmissionController(c.id, c.callAdmission));
@@ -874,16 +881,21 @@ export class Registry {
                 // ID after failure or timeout, including a late header commit.
                 const remaining = Math.max(0, writeDeadline - (yield* Clock.currentTimeMillis));
                 const written = yield* Effect.gen(function* () {
-                    for (let index = keys.length - 1; index >= 0; index--) {
+                    const multi = getNativeStorage(self.opts.storage)?.setMany;
+                    for (let index = keys.length - 1; index >= 0;) {
+                        const first = multi && index > 0 ? Math.max(1, index - 63) : index;
                         const before = yield* Clock.currentTimeMillis;
                         if (before >= writeDeadline || before >= chunkExpiry)
                             return false;
                         pendingWrite = true;
-                        yield* storageSet(keys[index], chunks[index], { expiresAtMs: chunkExpiry }).pipe(Effect.tap(() => Effect.sync(() => {
+                        yield* (multi && index > 0
+                            ? multi(Array.from({ length: index - first + 1 }, (_, offset) => [keys[index - offset], chunks[index - offset]]), { expiresAtMs: chunkExpiry })
+                            : storageSet(keys[index], chunks[index], { expiresAtMs: chunkExpiry })).pipe(Effect.tap(() => Effect.sync(() => {
                             pendingWrite = false;
                         })));
                         if ((yield* Clock.currentTimeMillis) >= writeDeadline)
                             return false;
+                        index = first - 1;
                     }
                     return true;
                 }).pipe(Effect.timeoutOrElse({ duration: Duration.millis(remaining), orElse: () => Effect.succeed(false) }), Effect.onError(() => release.pipe(Effect.ignore)));

package/dist/resource-read.js

@@ -1,8 +1,10 @@
+import { utilityRecovery } from "./utility-recovery.js";
 import { Effect } from "effect";
 import { classifyCallError, ConnectorCallError } from "./errors.js";
 import { InvocationFailure, timed } from "./invocation.js";
 import { withDeadlineEffect } from "./runtime/run.js";
 import { sentSecretsFor } from "./sent-secrets.js";
+import { downstreamOrigin, isSkillResource } from "./skill-origin.js";
 import { hasControlCharacters } from "./tool-name.js";
 const encoder = new TextEncoder();
 const URI_HINT = "Use resource://<connectorId>/<encodeURIComponent(downstreamUri)> with a whole-connector grant.";
@@ -26,13 +28,26 @@ function resourceTarget(registry, raw) {
     const connector = registry.getResourceConnector(match[1]);
     if (!connector?.readResource) {
         throw new InvocationFailure({
-            code: "unknown_address",
+            ...utilityRecovery(connector ? "unsupported_capability" : "unknown_address", "No resource reader is available."),
+            code: connector ? "unsupported_capability" : "unknown_address",
             message: `No resource reader is available for this address. ${URI_HINT}`,
             retryable: false,
         });
     }
     return { connector, uri };
 }
+/** Frame skill text for a program; native resources/read keeps exact bytes and never comes here. */
+function labelSkillText(contents, connectorId, uri) {
+    const items = contents?.contents;
+    if (!Array.isArray(items))
+        return contents;
+    return {
+        ...contents,
+        contents: items.map((item) => typeof item?.text === "string" && (isSkillResource(uri) || isSkillResource(String(item.uri ?? "")))
+            ? { ...item, text: `${downstreamOrigin(connectorId)}\n\n${item.text}` }
+            : item),
+    };
+}
 /** A protocol read, under the same request scope, call permit and deadline as tools. */
 export function readResource(registry, raw, options) {
     let connector;
@@ -68,7 +83,7 @@ export function readResource(registry, raw, options) {
             },
             catch: (error) => error,
         }));
-        return options.sentSecrets.redact(contents);
+        return labelSkillText(options.sentSecrets.redact(contents), target.connector.id, target.uri);
     })), {
         timeoutMs: options.timeoutMs,
         ...(options.signal ? { signal: options.signal } : {}),
@@ -98,6 +113,10 @@ export function readResource(registry, raw, options) {
                 retry: "Retry connecta.read with the same resource URI after the operator completes recovery.",
             };
         }
+        if (["unavailable", "unsupported_capability", "input_required_unsupported"].includes(details.code) &&
+            !details.nextAction) {
+            details = { ...details, nextAction: utilityRecovery(details.code, details.message).nextAction };
+        }
         return Effect.fail(new InvocationFailure(options.sentSecrets.redact(details)));
     }));
 }

package/dist/route-names.js

@@ -0,0 +1,44 @@
+/**
+ * `meta`: the six meta-tools. `code`: in-program wording, selected only by the
+ * eval code arm. `native` and `native-code`: native pools without and with
+ * `execute_code`.
+ */
+const NAMES = {
+    meta: Object.freeze({
+        search: "search_tools",
+        read: "call_tool",
+        write: "call_destructive_tool",
+        program: "execute_code",
+        authorize: "authorize_connector",
+        skills: "skills",
+    }),
+    code: Object.freeze({
+        search: "connecta.search inside execute_code",
+        read: "connecta.call inside execute_code",
+        write: "connecta.call inside execute_code",
+        program: "execute_code",
+        authorize: "authorize_connector",
+        skills: "skills",
+    }),
+    native: Object.freeze({
+        search: "your host's tool search",
+        read: "the original native tool",
+        write: "the original native tool",
+        program: "your host's tool search",
+        authorize: "the returned authorization handoff",
+        skills: "skills",
+    }),
+    "native-code": Object.freeze({
+        search: "your host's tool search",
+        read: "the original native tool",
+        write: "the original native tool",
+        program: "execute_code",
+        authorize: "the returned authorization handoff",
+        skills: "skills",
+    }),
+};
+/** The six-tool surface's names: the default wherever no other surface applies. */
+export const META_ROUTES = NAMES.meta;
+export function routeNames(surface) {
+    return NAMES[surface];
+}

package/dist/routes/activity-context.js

@@ -8,6 +8,7 @@ export function operatorActivityContext(context, authz) {
     return {
         sink: activity.store,
         recordTool: activity.recordTool,
+        recordOperation: activity.recordOperation,
         actor: authz.actor,
         ...(principal
             ? { principalActor: { kind: authz.actor.kind, id: principal.id, namespace: principal.namespace } }