@zackbart/connecta 0.38.0 → 0.40.0

package/dist/providers/sheets/tools.js

@@ -1,3 +1,4 @@
+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";
@@ -8,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";
@@ -150,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) {
@@ -449,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;
                     }
@@ -470,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;
@@ -702,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,4 @@
+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.
@@ -11,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. */
@@ -1799,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;
@@ -1818,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/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"
 };

package/dist/providers/tithely/api.js

@@ -1,3 +1,4 @@
+import { Routes, routePhrases } from "../../agent-routes.js";
 import { asRecord, asArray } from "../_shared/json.js";
 // Tithe.ly's giving API (v1) as a kit vendor: the operations,
 // what its statuses mean, its credential, its in-band refusal, the probe, and
@@ -389,9 +390,10 @@ function keyPairProblem(values) {
 /** Operator-held Basic keys, resolved per request; a mismatched pair is refused before anything leaves. */
 export const authenticate = Effect.gen(function* () {
     const values = yield* (yield* Credentials).values.pipe(Effect.mapError((error) => new Refusal({ error })));
+    const routes = yield* Routes;
     const pair = keyPairProblem(values);
     if (typeof pair === "string") {
-        return yield* failed(new ConnectorCallError("auth_required", `${pair} Call authorize_connector for recovery options; an operator adds the keys on this connection in the operator UI.`));
+        return yield* failed(new ConnectorCallError("auth_required", `${pair} ${routePhrases(routes).authorizeFor("recovery options")}; an operator adds the keys on this connection in the operator UI.`));
     }
     return { Authorization: `Basic ${btoa(`${pair.publicKey}:${pair.privateKey}`)}` };
 });

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Giving data is pastoral\n\nDonor names, emails, addresses, and gift amounts are pastoral data. Reduce\ninside `execute_code`: page, filter, and total there, and return the\naggregate (sums by fund, month, or donor count), not donor rows, unless the\ntask needs named people.\n\n## Ids and joins\n\n- Ids carry their kind: `org_` organization, `user_` donor account, `ch_`\n  charge, `rc_` recurring gift, `pm_` payment method. Read them from the list\n  tools; never guess one.\n- Tithe.ly lists charges and recurring gifts only for one organization or one\n  donor, so pass `organizationId` or `accountId`.\n- A charge carries its donor's name and email, its organization's name, and\n  its payment method, so most joins need no second read.\n- `list_accounts` covers every account these keys can see; `scope: \"api\"`\n  narrows it to accounts created through this API.\n- The named reads project Tithe.ly's records. A field a projection omits, such\n  as an account's phone and postal address, comes back from `tithely_api_read`\n  on that record's path.\n\n## Money, dates and funds\n\n- A fund is a Tithe.ly giving type: `giving_type` in Tithe.ly's records,\n  `fund` in projections.\n- Projections give amounts as integer `…Cents` and dates as ISO 8601 UTC\n  `…At`. Tithe.ly's own records, from `tithely_api_read`, keep string cents\n  and Unix seconds.\n- `depositedAt` may be `\"pending\"`. There is no deposits resource: net amount\n  and fees live on each charge.\n- A charge a recurring gift produced has `recurring: true`; a one-time gift\n  has `recurring: false`.\n\n## Writes\n\n- Every write moves money or changes a donor's records. Bodies are form\n  fields in integer cents and Unix seconds.\n- `POST /refunds/{charge_id}` refunds a whole charge.\n  `DELETE /recurring/{recurring_id}` stops future charges and refunds nothing.\n- Card and bank tokens, which `POST /charge-once` and `POST /payment-methods`\n  need, come only from Tithely.js in a donor's browser. An agent cannot\n  create one.\n- Tithe.ly reports most refusals as HTTP 200 with `status: \"fail\"` and a\n  reason but no code. They arrive as `connector_call_failed`; read the reason\n  before deciding what to do next.\n\n## Not available\n\nOnly Tithe.ly's API v1 is reachable; its undocumented v2 is not.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `list_accounts`, `list_charges`, `list_organizations`, `list_payment_methods`, `list_recurring_charges`, `tithely_api_details`, `tithely_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. Paged `list_*` and `search_*` reads take `limit` (default 25, at most 99). 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:** `tithely_api_search` finds this API's operations and reads no account data, `tithely_api_details` shows one operation's contract, and `tithely_api_read` calls a reviewed read. `tithely_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": "## Giving data is pastoral\n\nDonor names, emails, addresses, and gift amounts are pastoral data. Reduce\ninside `execute_code`: page, filter, and total there, and return the\naggregate (sums by fund, month, or donor count), not donor rows, unless the\ntask needs named people.\n\n## Ids and joins\n\n- Ids carry their kind: `org_` organization, `user_` donor account, `ch_`\n  charge, `rc_` recurring gift, `pm_` payment method. Read them from the list\n  tools; never guess one.\n- Tithe.ly lists charges and recurring gifts only for one organization or one\n  donor, so pass `organizationId` or `accountId`.\n- A charge carries its donor's name and email, its organization's name, and\n  its payment method, so most joins need no second read.\n- `list_accounts` covers every account these keys can see; `scope: \"api\"`\n  narrows it to accounts created through this API.\n- The named reads project Tithe.ly's records. A field a projection omits, such\n  as an account's phone and postal address, comes back from `tithely_api_read`\n  on that record's path.\n\n## Money, dates and funds\n\n- A fund is a Tithe.ly giving type: `giving_type` in Tithe.ly's records,\n  `fund` in projections.\n- Projections give amounts as integer `…Cents` and dates as ISO 8601 UTC\n  `…At`. Tithe.ly's own records, from `tithely_api_read`, keep string cents\n  and Unix seconds.\n- `depositedAt` may be `\"pending\"`. There is no deposits resource: net amount\n  and fees live on each charge.\n- A charge a recurring gift produced has `recurring: true`; a one-time gift\n  has `recurring: false`.\n\n## Writes\n\n- Every write moves money or changes a donor's records. Bodies are form\n  fields in integer cents and Unix seconds.\n- `POST /refunds/{charge_id}` refunds a whole charge.\n  `DELETE /recurring/{recurring_id}` stops future charges and refunds nothing.\n- Card and bank tokens, which `POST /charge-once` and `POST /payment-methods`\n  need, come only from Tithely.js in a donor's browser. An agent cannot\n  create one.\n- Tithe.ly reports most refusals as HTTP 200 with `status: \"fail\"` and a\n  reason but no code. They arrive as `connector_call_failed`; read the reason\n  before deciding what to do next.\n\n## Not available\n\nOnly Tithe.ly's API v1 is reachable; its undocumented v2 is not.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `list_accounts`, `list_charges`, `list_organizations`, `list_payment_methods`, `list_recurring_charges`, `tithely_api_details`, `tithely_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. Paged `list_*` and `search_*` reads take `limit` (default 25, at most 99). 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:** `tithely_api_search` finds this API's operations and reads no account data, `tithely_api_details` shows one operation's contract, and `tithely_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `tithely_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": "Account instructions"
 };

package/dist/providers/vercel/api.js

@@ -456,7 +456,7 @@ export function transformGuide(guide, options) {
     const base = Object.values(VERCEL_VERDICTS).filter((verdict) => verdict === "refuse").length;
     const total = vercelIndex.ops.filter((op) => VERCEL_VERDICTS[`${op.method} ${op.path}`] === "refuse" ||
         PIN_DISCOVERY_REFUSALS[`${op.method} ${op.path}`] !== undefined).length;
-    const sentence = `${base} operations are refused by design; use \`vercel_api_details\` with the method and path to inspect the original operation summary and its separate refusal.`;
+    const sentence = `${base} operations are refused by design; use \`vercel_api_details\` with the method and path to see each summary and refusal,`;
     const lines = guide.content.split("\n");
     const targets = lines.flatMap((line, position) => line.startsWith("- **Hatch:** `vercel_api_search` ") && line.includes(sentence) ? [position] : []);
     const position = targets[0];

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Projects, deployments and domains\n\nResolve a team by slug, a project by name, and deployments by the observed\nproject id. Team ids start with `team_`, project ids with `prj_`, and deployment\nids with `dpl_`. A deployment hostname and a deployment id identify the same\ndeployment; an alias can later point to a different deployment.\n\nSome project paths accept a project name, but a deployment list's projectId\nfilter requires the observed `prj_` id. Resolve the name before listing its\ndeployments; an empty result for a guessed name does not prove absence.\nComplete each identifier lookup before starting the reads that depend on it.\n\n<!-- when: unpinned -->\nThe configured team is a routing default, not a restriction. Explicit teamId\nor slug selects another team the token can reach; teamId: null selects personal\nscope. Vercel token permissions determine access. Prefer an explicit team when\njoining resources across several calls.\n<!-- end -->\n\n<!-- when: pinned -->\nThe deployment confines this connection to one team. A supplied team slug must\nbelong to that team; personal scope and foreign teams are refused. Project and\ndeployment references require ownership reads. Global/account and transfer\noperations without a verifiable team boundary remain unavailable. A team list\nreturns only the pinned team.\n<!-- end -->\n\nRead deployment state before its build events. Runtime logs diagnose requests\nafter a deployment built; build logs explain a failed build. Narrow time windows\nbefore raising collection limits. Generic reads refuse live follow streams;\nuse the bounded build/runtime readers. Deployment timestamps are milliseconds.\n\nProject domains and deployment aliases are different joins: a project domain\nbelongs to the project, while an alias identifies its assigned deployment.\nRead a pending domain's verification instructions before changing DNS.\n\n## Environment changes\n\nResolve environment-variable ids using metadata, including target, branch and\ncustom environment. A key can have distinct production and preview values.\nExisting values cannot be retrieved. Supply new values only when the task asks\nfor a change; confirm the returned id and metadata.\n\nEnvironment changes apply to future deployments. A new deployment is a separate\nwrite. Promoting an existing deployment does not rebuild it or update embedded\nenvironment values. After an uncertain update, reconcile observable metadata\nsuch as id, targets and comment; reading metadata cannot verify a secret value.\n\n## Explicit files and credentials\n\nDeployment files can reference previously uploaded digests. File uploads accept\nexplicit bytes and never read a path on the agent's machine. Decrypted-value,\ncredential-minting, protection-bypass-link, signing and domain move-out operations\nare refused; use Vercel's dashboard for those workflows.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `list_teams`, `vercel_api_details`, `vercel_api_search`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `vercel_api_read`, put it in `query[page.param]` or `body[page.param]`, as `page.in` specifies. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 20, at most 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:** `vercel_api_search` finds this API's operations and reads no account data, `vercel_api_details` shows one operation's contract, and `vercel_api_read` calls a reviewed read. `vercel_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 29 operations are refused by design; use `vercel_api_details` with the method and path to inspect the original operation summary and its separate refusal. Use details for refused methods outside the read/write call schemas; those methods remain unavailable.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. It documents no conflict.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
+    "content": "## Projects, deployments and domains\n\nResolve a team by slug, a project by name, and deployments by the observed\nproject id. Team ids start with `team_`, project ids with `prj_`, and deployment\nids with `dpl_`. A deployment hostname and a deployment id identify the same\ndeployment; an alias can later point to a different deployment.\n\nSome project paths accept a project name, but a deployment list's projectId\nfilter requires the observed `prj_` id. Resolve the name before listing its\ndeployments; an empty result for a guessed name does not prove absence.\nComplete each identifier lookup before starting the reads that depend on it.\n\n<!-- when: unpinned -->\nThe configured team is a routing default, not a restriction. Explicit teamId\nor slug selects another team the token can reach; teamId: null selects personal\nscope. Vercel token permissions determine access. Prefer an explicit team when\njoining resources across several calls.\n<!-- end -->\n\n<!-- when: pinned -->\nThe deployment confines this connection to one team. A supplied team slug must\nbelong to that team; personal scope and foreign teams are refused. Project and\ndeployment references require ownership reads. Global/account and transfer\noperations without a verifiable team boundary remain unavailable. A team list\nreturns only the pinned team.\n<!-- end -->\n\nRead deployment state before its build events. Runtime logs diagnose requests\nafter a deployment built; build logs explain a failed build. Narrow time windows\nbefore raising collection limits. Generic reads refuse live follow streams;\nuse the bounded build/runtime readers. Deployment timestamps are milliseconds.\n\nProject domains and deployment aliases are different joins: a project domain\nbelongs to the project, while an alias identifies its assigned deployment.\nRead a pending domain's verification instructions before changing DNS.\n\n## Environment changes\n\nResolve environment-variable ids using metadata, including target, branch and\ncustom environment. A key can have distinct production and preview values.\nExisting values cannot be retrieved. Supply new values only when the task asks\nfor a change; confirm the returned id and metadata.\n\nEnvironment changes apply to future deployments. A new deployment is a separate\nwrite. Promoting an existing deployment does not rebuild it or update embedded\nenvironment values. After an uncertain update, reconcile observable metadata\nsuch as id, targets and comment; reading metadata cannot verify a secret value.\n\n## Explicit files and credentials\n\nDeployment files can reference previously uploaded digests. File uploads accept\nexplicit bytes and never read a path on the agent's machine. Decrypted-value,\ncredential-minting, protection-bypass-link, signing and domain move-out operations\nare refused; use Vercel's dashboard for those workflows.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `list_teams`, `vercel_api_details`, `vercel_api_search`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `vercel_api_read`, put it in `query[page.param]` or `body[page.param]`, as `page.in` specifies. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 20, at most 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:** `vercel_api_search` finds this API's operations and reads no account data, `vercel_api_details` shows one operation's contract, and `vercel_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `vercel_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 29 operations are refused by design; use `vercel_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. It documents no conflict.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
     "instructionsHeading": "Account instructions"
 };

package/dist/providers/vercel/tools.js

@@ -4,7 +4,7 @@ import { Effect, Schema } from "effect";
 import { ConnectorCallError } from "../../errors.js";
 import { Refusal } from "../../http/errors.js";
 import { read, write, list } from "../../http/tools.js";
-import { fieldsProblem, selectFields } from "../../http/fields.js";
+import { fieldsContract, selectFields } from "../../http/fields.js";
 import { vercelPage } from "../../http/hatch-paging.js";
 import { schema, typedParams } from "../_shared/rest/kit.js";
 import { refuseWithheldUpload } from "../_shared/rest/value-safety.js";
@@ -66,6 +66,7 @@ const ENV_SCHEMA = {
     },
     required: ["id", "key", "type"],
 };
+const ENV_FIELDS = fieldsContract("item", ENV_SCHEMA, "Values cannot be restored.");
 /** Deliberately omits `value`, even though redaction already removed it. */
 function envMetadata(value) {
     const variable = record(value);
@@ -158,7 +159,7 @@ export function vercelTools({ connection, options, }) {
                     type: "array",
                     maxItems: 50,
                     items: { type: "string", minLength: 1, maxLength: 200 },
-                    description: "Dot paths to keep in each metadata item; values cannot be restored.",
+                    description: ENV_FIELDS.description,
                 },
             }, ["projectId"]),
             outputSchema: {
@@ -171,7 +172,7 @@ export function vercelTools({ connection, options, }) {
             },
             run: (args) => Effect.gen(function* () {
                 const fields = args["fields"];
-                const problem = fieldsProblem(fields, new Set(Object.keys(ENV_SCHEMA.properties)), "an environment metadata item");
+                const problem = ENV_FIELDS.problem(fields);
                 if (problem)
                     throw problem;
                 const { data } = yield* send("GET", `/v10/projects/${segment(args["projectId"])}/env`, {

package/dist/registry.d.ts

@@ -71,8 +71,10 @@ export interface RegistryOptions {
         maxStashBytes?: number;
         maxStashEntries?: number;
     } | undefined;
+    /** Route names every context carries unless a call names its own; meta by default. */
+    routes?: import("./types.js").AgentRouteNames | undefined;
 }
-export type ConnectorOperationOptions = Pick<ConnectorContext, "signal" | "timeoutMs" | "defer">;
+export type ConnectorOperationOptions = Pick<ConnectorContext, "signal" | "timeoutMs" | "defer" | "routes">;
 /**
  * The registry surface a per-connection MCP server consumes: every meta-tool
  * (`src/meta-tools.ts`) and the `execute_code` sandbox bridge (`src/execute.ts`)
@@ -84,6 +86,7 @@ export type ConnectorOperationOptions = Pick<ConnectorContext, "signal" | "timeo
  */
 /** Host-admitted identity and endpoint bindings for result paging. */
 export interface ResultIdentity {
+    pool: string | null;
     subject: string | null;
     principal: string | null;
     endpoint: string;
@@ -124,8 +127,11 @@ export interface RegistryView {
     recheckResultAccess(dependencies: readonly ProgramResultDependency[], classification: "read" | "write", signal?: AbortSignal): Promise<boolean>;
     /** Reserve deployment-wide capacity before writing a paging envelope's chunks. */
     stashResult(id: string, chunks: readonly string[], ttlSeconds: number): Promise<boolean>;
-    /** Local declared-vs-stored credential mismatch, with no downstream I/O. */
-    credentialDriftFor(id: string): Promise<string | undefined>;
+    /**
+     * Local declared-vs-stored credential mismatch, with no downstream I/O. With
+     * `requestScope`, the read joins that request's read memo.
+     */
+    credentialDriftFor(id: string, requestScope?: object): Promise<string | undefined>;
     /** Value-free shape learned from successful calls, never a provider declaration. */
     observedOutputSchema(connectorId: string, definition: ToolDef): ToolDef["outputSchema"] | undefined;
     /** Passively learn one successful unwrapped result; failures stay isolated. */
@@ -287,7 +293,7 @@ export declare class Registry implements RegistryView {
     describeStaticTools(id: string): ToolDef[] | undefined;
     private validateClassification;
     getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, scope?: RegistryScope): Promise<ToolDef[]>;
-    credentialDriftFor(id: string): Promise<string | undefined>;
+    credentialDriftFor(id: string, requestScope?: object): Promise<string | undefined>;
     /** Age of a complete cache entry; reads never refresh it. */
     catalogAgeMs(id: string): number | null;
     /** Pure lookup shared by status probes and operator catalog refreshes. */

package/dist/registry.js

@@ -1,4 +1,5 @@
 import { wrapViewCredentials } from "./runtime/call.js";
+import { META_ROUTES } from "./agent-routes.js";
 import { sha256Hex } from "./bytes.js";
 import { catalogRevision } from "./catalog-revision.js";
 import { authCall, authInvoke } from "./auth/native.js";
@@ -20,11 +21,15 @@ import { boundedStatus, failureRecord, failureStatus, logFailure, ownStatus } fr
 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 { observeStorageWrites } from "./runtime/request-reads.js";
+import { attachStorageDigestKey } from "./storage-digest.js";
+import { requestReads } from "./runtime/request-scope.js";
+import { credentialReads } from "./credential-reads.js";
 import { provideRegistryPrograms, registryEdgeProgram, registryProgram } from "./runtime/registry.js";
 import { causeError, runEdge } from "./runtime/run.js";
 import { Storage } from "./runtime/services.js";
 import { SharedRead } from "./runtime/shared-read.js";
-import { runOnPartition, storageCompareAndSet, storageDelete, storageGet, storageSet, storageList, } from "./runtime/storage.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 { jsonCodec, OAUTH_HANDOFF_TTL_SECONDS, oauthHandoffKeys, resultKeys, scopes, stashExpiryKeys, stashLedgerKeys, } from "./storage/keys.js";
@@ -105,12 +110,14 @@ function namespaced(storage, prefix) {
         list: async (keyPrefix) => (await storage.list(prefix + keyPrefix)).map((key) => key.slice(prefix.length)),
         compareAndSet: (k, expected, next, o) => storage.compareAndSet(prefix + k, expected, next, o),
     };
+    observeStorageWrites(edge, { storage, prefix });
     return hasNativeStorage(storage)
         ? registerNativeStorage(edge, {
             // Select against the underlying current methods at dispatch. A
             // namespace created during a decoration regains the native path when
             // that decoration is restored, without capturing stale capabilities.
             get: (key) => storageGet(prefix + key).pipe(Effect.provideService(Storage, storage)),
+            getMany: (keys) => storageGetMany(keys.map((key) => prefix + key)).pipe(Effect.provideService(Storage, storage)),
             set: (key, value, options) => storageSet(prefix + key, value, options).pipe(Effect.provideService(Storage, storage)),
             delete: (key) => storageDelete(prefix + key).pipe(Effect.provideService(Storage, storage)),
             list: (keyPrefix) => storageList(prefix + keyPrefix).pipe(Effect.provideService(Storage, storage), Effect.map((keys) => keys.map((key) => key.slice(prefix.length)))),
@@ -459,8 +466,12 @@ export class Registry {
         let credentialProgram;
         if (this.opts.credentialVault && credentialConfig) {
             const vault = this.opts.credentialVault;
+            // The credential a call sends: always read fresh. It records what it
+            // saw in the request's memo, so a later status or detail read in the
+            // same request is never older than what was sent.
+            const fresh = credentialReads(vault, requestReads(requestScope), true);
             credentialProgram = Effect.tryPromise({
-                try: () => vault.getAll(id, this.opts.credentialOwner),
+                try: () => fresh.getAll(id, this.opts.credentialOwner),
                 catch: (error) => error,
             }).pipe(Effect.flatMap((values) => {
                 const shape = storedCredentialShape(credentialConfig, values);
@@ -485,6 +496,7 @@ export class Registry {
             ...(this.opts.oauthClientName !== undefined ? { oauthClientName: this.opts.oauthClientName } : {}),
             ...(credentialAccess ? { credential: credentialAccess } : {}),
             requestScope,
+            routes: this.opts.routes ?? META_ROUTES,
             ...callOptions,
         }, scope?.caller);
         setViewService(context, OperationCredentials, credentialProgram);
@@ -500,7 +512,11 @@ export class Registry {
             storage: this.opts.catalogStorage ?? this.opts.storage,
             partition: this.catalogPartition(scope),
             credentialRevision: () => catalogRevision(this.opts.credentialVault),
-            sharedPartition: JSON.stringify([baseUrl, this.opts.publicUrl ?? null, scope?.caller?.pool ?? null]),
+            sharedPartition: JSON.stringify([
+                baseUrl,
+                this.opts.publicUrl ?? null,
+                (scope?.caller ?? scope?.operatorCaller)?.pool ?? null,
+            ]),
             defaultTtlMs: (this.opts.toolCacheTtlSeconds ?? CONFIG_DEFAULTS.discovery.catalogTtlSeconds) * 1000,
             minTtlMs: (this.opts.catalogMinTtlSeconds ?? CONFIG_DEFAULTS.discovery.catalogMinTtlSeconds) * 1000,
             maxTtlMs: (this.opts.catalogMaxTtlSeconds ?? CONFIG_DEFAULTS.discovery.catalogMaxTtlSeconds) * 1000,
@@ -515,6 +531,7 @@ export class Registry {
                 }
                 : {}),
         });
+        attachStorageDigestKey(context, this.opts.credentialVault);
         sentSecretsFor(context);
         wrapViewCredentials(context);
         attachOAuthPartition(context, this.oauthPartition);
@@ -601,7 +618,7 @@ export class Registry {
      * connector's namespace. Backs connecta.result.
      */
     resultIdentity() {
-        return { subject: null, principal: null, endpoint: "/mcp", origin: null };
+        return { pool: null, subject: null, principal: null, endpoint: "/mcp", origin: null };
     }
     recheckResultAccess(_dependencies, _classification, _signal) {
         return Promise.resolve(true);
@@ -763,8 +780,8 @@ export class Registry {
     getTools(id, baseUrl, requestScope, callOptions = {}, scope) {
         return runEdge(registryEdgeProgram(Registry.prototype, this, "getTools", id, baseUrl, requestScope, callOptions, scope));
     }
-    credentialDriftFor(id) {
-        return runEdge(registryEdgeProgram(Registry.prototype, this, "credentialDriftFor", id));
+    credentialDriftFor(id, requestScope) {
+        return runEdge(registryEdgeProgram(Registry.prototype, this, "credentialDriftFor", id, requestScope));
     }
     /** Age of a complete cache entry; reads never refresh it. */
     catalogAgeMs(id) {
@@ -944,13 +961,16 @@ export class Registry {
                     return yield* load.join(signal);
                 }));
             }),
-            credentialDriftFor: (self, id) => Effect.gen(function* () {
+            credentialDriftFor: (self, id, requestScope) => Effect.gen(function* () {
                 const credential = self.connectors.get(id)?.credential;
                 const vault = self.opts.credentialVault;
                 if (!credential || !vault)
                     return undefined;
+                // Memoized per request: drift only labels a status or detail view.
+                // A dispatch reads its credential fresh (contextFor).
+                const reader = requestScope ? credentialReads(vault, requestReads(requestScope)) : vault;
                 return yield* Effect.tryPromise({
-                    try: () => vault.getAll(id, self.opts.credentialOwner),
+                    try: () => reader.getAll(id, self.opts.credentialOwner),
                     catch: (error) => error,
                 }).pipe(Effect.map((values) => {
                     const shape = storedCredentialShape(credential, values);
@@ -968,8 +988,13 @@ export class Registry {
                 const withObservations = (status) => self.withCatalogObservations(id, baseUrl, status, scope);
                 return duringViewEffect(ctx, () => Effect.gen(function* () {
                     if (connector.credential) {
+                        // Memoized per request: this read only picks the status shown.
+                        // The probe that follows reads the credential it sends fresh.
+                        const vault = self.opts.credentialVault;
                         const values = yield* Effect.tryPromise({
-                            try: () => self.opts.credentialVault?.getAll(id, self.opts.credentialOwner) ?? Promise.resolve(null),
+                            try: () => vault
+                                ? credentialReads(vault, requestReads(requestScope)).getAll(id, self.opts.credentialOwner)
+                                : Promise.resolve(null),
                             catch: (error) => error,
                         });
                         const shape = storedCredentialShape(connector.credential, values);
@@ -1080,6 +1105,7 @@ class ScopedRegistryView {
         return {
             subject: this.scope.subjectKey ?? null,
             principal: this.scope.principalKey ?? null,
+            pool: this.scope.caller?.pool ?? null,
             endpoint: this.scope.endpoint ?? "/mcp",
             origin: this.scope.origin ?? null,
         };
@@ -1090,8 +1116,8 @@ class ScopedRegistryView {
     resultsStorage() {
         return this.scope.subjectKey ? this.root.scopedStorage(this.scope.subjectKey) : this.root.resultsStorage();
     }
-    credentialDriftFor(id) {
-        return runEdge(registryEdgeProgram(ScopedRegistryView.prototype, this, "credentialDriftFor", id));
+    credentialDriftFor(id, requestScope) {
+        return runEdge(registryEdgeProgram(ScopedRegistryView.prototype, this, "credentialDriftFor", id, requestScope));
     }
     observedOutputSchema(connectorId, definition) {
         return this.registryFor(connectorId)?.observedOutputSchema(connectorId, definition);
@@ -1147,9 +1173,11 @@ class ScopedRegistryView {
                 }
                 return carryCatalogFreshness(tools, visible);
             }),
-            credentialDriftFor: (self, id) => Effect.suspend(() => {
+            credentialDriftFor: (self, id, requestScope) => Effect.suspend(() => {
                 const registry = self.registryFor(id);
-                return registry ? registryProgram(registry, "credentialDriftFor", id) : Effect.succeed(undefined);
+                return registry
+                    ? registryProgram(registry, "credentialDriftFor", id, requestScope)
+                    : Effect.succeed(undefined);
             }),
             statusFor: (self, ...args) => Effect.suspend(() => {
                 const registry = self.registryFor(args[0]);