@zackbart/connecta 0.38.0 → 0.40.0

package/dist/providers/docs/lib/schemas.js

@@ -1,7 +1,8 @@
 // Effect declarations are the catalog and runtime decoder for every named Docs tool.
+import { routeDescription } from "../../../agent-routes.js";
 import { Schema } from "effect";
 import { Integer, isMinChars, isMaxChars } from "../../../http/json-schema.js";
-import { fieldsInput } from "../../../http/fields.js";
+import { fieldsContract } from "../../../http/fields.js";
 import { REQUEST_KINDS } from "./requests.js";
 const matches = (pattern) => Schema.makeFilter((value) => new RegExp(pattern).test(value), {
     expected: `a string matching ${pattern}`,
@@ -12,27 +13,6 @@ const Request = Schema.Record(Schema.String, Schema.Record(Schema.String, Schema
     expected: "exactly one reviewed Docs request kind",
     toJsonSchema: () => ({ minProperties: 1, maxProperties: 1, propertyNames: { enum: [...REQUEST_KINDS] } }),
 }));
-export const GET_DOCUMENT_INPUT = Schema.Struct({
-    "documentId": Schema.String.check(isMinChars(1), isMaxChars(256), matches("^[A-Za-z0-9_-]+$")).annotate({
-        description: "Document id: the part after /d/ in its URL, or a Drive file id for a Google Doc.",
-    }),
-    "tabId": Schema.optionalKey(Schema.String.check(isMinChars(1), isMaxChars(128), matches("^[A-Za-z0-9._-]+$")).annotate({
-        description: "Render only this tab (from a previous get_document); omit for every tab.",
-    })),
-    "maxChars": Schema.optionalKey(Integer.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(1000000)).annotate({
-        description: "Characters of text kept across all rendered tabs, 0 to 1000000; defaults to 20000. Connecta's cap. Longer text ends with a truncation marker. Above the default, call directly (call_tool, connecta.result to page): execute_code carries at most 256 KiB per result.",
-    })),
-    "withIndexes": Schema.optionalKey(Schema.Boolean.annotate({
-        description: "Add each tab's elements: every paragraph, table, and table of contents with UTF-16 startIndex and endIndex, 64 KiB per page (connecta's cap); page with cursor.",
-    })),
-    "cursor": Schema.optionalKey(Schema.String.check(isMinChars(1)).annotate({
-        description: "Opaque page.nextCursor from the previous indexed read; keep the same arguments and document revision.",
-    })),
-    "suggestions": Schema.optionalKey(Schema.Literals(["inline", "accepted", "rejected"]).annotate({
-        description: "How suggested edits read: inline (editors' default; the indexes edits use), or a preview with all accepted or all rejected (indexes not valid for edits).",
-    })),
-    fields: Schema.optionalKey(fieldsInput("Dot paths to keep in the result. Page and truncation metadata are always returned.")),
-});
 export const GET_DOCUMENT_OUTPUT = Schema.Struct({
     "documentId": Schema.optionalKey(Schema.String),
     "title": Schema.optionalKey(Schema.String),
@@ -60,6 +40,28 @@ export const GET_DOCUMENT_OUTPUT = Schema.Struct({
     "dropped": Schema.optionalKey(Schema.Array(Schema.String)),
     "truncated": Schema.optionalKey(Schema.Array(Schema.String)),
 });
+export const GET_DOCUMENT_FIELDS = fieldsContract("result", GET_DOCUMENT_OUTPUT, "Page and truncation metadata are always returned.");
+export const GET_DOCUMENT_INPUT = Schema.Struct({
+    "documentId": Schema.String.check(isMinChars(1), isMaxChars(256), matches("^[A-Za-z0-9_-]+$")).annotate({
+        description: "Document id: the part after /d/ in its URL, or a Drive file id for a Google Doc.",
+    }),
+    "tabId": Schema.optionalKey(Schema.String.check(isMinChars(1), isMaxChars(128), matches("^[A-Za-z0-9._-]+$")).annotate({
+        description: "Render only this tab (from a previous get_document); omit for every tab.",
+    })),
+    "maxChars": Schema.optionalKey(Integer.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(1000000)).annotate({
+        description: routeDescription((phrases) => `Characters of text kept across all rendered tabs, 0 to 1000000; defaults to 20000. Connecta's cap. Longer text ends with a truncation marker. Above the default, ${phrases.callDirectlyAndPage}${phrases.program ? `: ${phrases.program} carries at most 256 KiB per result` : ""}.`),
+    })),
+    "withIndexes": Schema.optionalKey(Schema.Boolean.annotate({
+        description: "Add each tab's elements: every paragraph, table, and table of contents with UTF-16 startIndex and endIndex, 64 KiB per page (connecta's cap); page with cursor.",
+    })),
+    "cursor": Schema.optionalKey(Schema.String.check(isMinChars(1)).annotate({
+        description: "Opaque page.nextCursor from the previous indexed read; keep the same arguments and document revision.",
+    })),
+    "suggestions": Schema.optionalKey(Schema.Literals(["inline", "accepted", "rejected"]).annotate({
+        description: "How suggested edits read: inline (editors' default; the indexes edits use), or a preview with all accepted or all rejected (indexes not valid for edits).",
+    })),
+    fields: Schema.optionalKey(GET_DOCUMENT_FIELDS.input),
+});
 export const CREATE_DOCUMENT_INPUT = Schema.Struct({
     "title": Schema.String.check(isMinChars(1), isMaxChars(1000), matches("^[^\\r\\n]*$")).annotate({
         description: "Document title, one line. Connecta's 1,000-character cap.",

package/dist/providers/docs/safety.js

@@ -1,6 +1,7 @@
 import { Effect } from "effect";
 import { RequestSecrets } from "../../http/services.js";
 import { googleSafety } from "../_shared/google/kit.js";
+import { pathWithholds } from "../_shared/rest/value-safety.js";
 /** ImageProperties.contentUri delegates the requester's image access for 30 minutes.
  * Keep ordinary authored links/sourceUri, but withhold that vendor capability on
  * every document response, including tabs, headers and suggested image changes.
@@ -29,6 +30,7 @@ export function docsSafety(operations) {
                 };
                 return visit(data);
             },
+            withholds: () => pathWithholds({ paths: ["imageProperties.contentUri"], anyDepth: true }),
         },
     };
 }

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

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

package/dist/providers/docs/tools.js

@@ -4,7 +4,7 @@ import { Effect, Option } from "effect";
 import { canonicalJson } from "../../canonical-json.js";
 import { ConnectorCallError } from "../../errors.js";
 import { Refusal } from "../../http/errors.js";
-import { fieldsProblem, selectFields } from "../../http/fields.js";
+import { selectFields } from "../../http/fields.js";
 import { Recovery } from "../../http/services.js";
 import { requestSentSecrets, redactBeforeCut } from "../../sent-secrets.js";
 import { providerCallFailure } from "../../write-outcome.js";
@@ -515,9 +515,7 @@ export function docsTools({ connection }) {
             ...(tool.writeSteps ? { writeSteps: tool.writeSteps } : {}),
             run: (args) => Effect.gen(function* () {
                 const fields = isRead ? args["fields"] : undefined;
-                const problem = isRead
-                    ? fieldsProblem(fields, new Set(Object.keys(schemas.GET_DOCUMENT_OUTPUT.fields)), "the result")
-                    : undefined;
+                const problem = isRead ? schemas.GET_DOCUMENT_FIELDS.problem(fields) : undefined;
                 if (problem)
                     return yield* Effect.fail(new Refusal({ error: problem }));
                 const operation = yield* Effect.serviceOption(Operation);

package/dist/providers/drive/api.js

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

package/dist/providers/drive/lib/contracts.js

@@ -1,10 +1,13 @@
 // Drive named tool contracts, kept separate from the workflow programs.
+import { routeDescription } from "../../../agent-routes.js";
 import { Schema } from "effect";
 import { Integer, isMinChars, isMaxChars } from "../../../http/json-schema.js";
 const matchesPattern = (pattern) => Schema.makeFilter((value) => pattern.test(value), {
     expected: `a string matching ${pattern.source}`,
     toJsonSchema: () => ({ pattern: pattern.source }),
 });
+/** maxBytes on every read: a program receives the default; only a direct call raises it. */
+const MAX_BYTES_DESCRIPTION = routeDescription((phrases) => `Serialized bytes of the whole result; defaults to 196608${phrases.program ? `, what ${phrases.program} can receive` : ""}. Raise it, to 4194304, ${phrases.onlyDirectRead}.`);
 export const search_files = {
     input: Schema.Struct({
         "query": Schema.optionalKey(Schema.String.check(isMaxChars(2048)).annotate({
@@ -35,7 +38,7 @@ export const search_files = {
             "description": "Opaque page.nextCursor from the previous page. Pass it back unchanged with the same arguments.",
         })),
         "maxBytes": Schema.optionalKey(Integer.check(Schema.isGreaterThanOrEqualTo(65536), Schema.isLessThanOrEqualTo(4194304)).annotate({
-            "description": "Serialized bytes of the whole result; defaults to 196608, what execute_code can receive. Raise it, to 4194304, only for a direct call_tool read.",
+            "description": MAX_BYTES_DESCRIPTION,
         })),
     }),
     output: Schema.Struct({
@@ -81,7 +84,7 @@ export const list_folder_items = {
             "description": "Opaque page.nextCursor from the previous page. Pass it back unchanged with the same arguments.",
         })),
         "maxBytes": Schema.optionalKey(Integer.check(Schema.isGreaterThanOrEqualTo(65536), Schema.isLessThanOrEqualTo(4194304)).annotate({
-            "description": "Serialized bytes of the whole result; defaults to 196608, what execute_code can receive. Raise it, to 4194304, only for a direct call_tool read.",
+            "description": MAX_BYTES_DESCRIPTION,
         })),
     }),
     output: Schema.Struct({
@@ -150,7 +153,7 @@ export const get_file_content = {
             "description": "Characters (code points) of text kept, 1 to 100000; defaults to 20000. Longer text ends with a truncation marker. Binaries ignore it.",
         })),
         "maxBytes": Schema.optionalKey(Integer.check(Schema.isGreaterThanOrEqualTo(65536), Schema.isLessThanOrEqualTo(4194304)).annotate({
-            "description": "Serialized bytes of the whole result; defaults to 196608, what execute_code can receive. Raise it, to 4194304, only for a direct call_tool read.",
+            "description": MAX_BYTES_DESCRIPTION,
         })),
     }),
     output: Schema.Struct({
@@ -177,7 +180,7 @@ export const list_permissions = {
             "description": "Opaque page.nextCursor from the previous page. Pass it back unchanged with the same arguments.",
         })),
         "maxBytes": Schema.optionalKey(Integer.check(Schema.isGreaterThanOrEqualTo(65536), Schema.isLessThanOrEqualTo(4194304)).annotate({
-            "description": "Serialized bytes of the whole result; defaults to 196608, what execute_code can receive. Raise it, to 4194304, only for a direct call_tool read.",
+            "description": MAX_BYTES_DESCRIPTION,
         })),
     }),
     output: Schema.Struct({
@@ -214,7 +217,7 @@ export const list_shared_drives = {
             "description": "Opaque page.nextCursor from the previous page. Pass it back unchanged with the same arguments.",
         })),
         "maxBytes": Schema.optionalKey(Integer.check(Schema.isGreaterThanOrEqualTo(65536), Schema.isLessThanOrEqualTo(4194304)).annotate({
-            "description": "Serialized bytes of the whole result; defaults to 196608, what execute_code can receive. Raise it, to 4194304, only for a direct call_tool read.",
+            "description": MAX_BYTES_DESCRIPTION,
         })),
     }),
     output: Schema.Struct({

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

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

package/dist/providers/drive/tools.js

@@ -1,3 +1,4 @@
+import { routePhrases } from "../../agent-routes.js";
 import { asRecord, asArray, compact } from "../_shared/json.js";
 import { decodeBase64, decodeBase64url } from "../../bytes.js";
 // Google Drive named workflows, bounded projections and bound continuation on the provider kit.
@@ -8,7 +9,7 @@ import { Classification, Dispatches, Signal } from "../../http/services.js";
 import { RESULT_BUDGET_BYTES, clampText, jsonBytes } from "../_shared/google/result-size.js";
 import { googleOutcomeOf, googleFailureMessage } from "../_shared/google/kit.js";
 import { read, write } from "../../http/tools.js";
-import { fieldsInput, fieldsProblem, selectFields } from "../../http/fields.js";
+import { fieldsContract, selectFields } from "../../http/fields.js";
 import { catalogSchema } from "../../http/json-schema.js";
 import { Refusal } from "../../http/errors.js";
 import { Operation } from "../../runtime/call.js";
@@ -432,7 +433,7 @@ function capped(ctx, whole, max, partial, fits) {
     if (fits(byChars))
         return { content: byChars, contentTruncated: true };
     // The bytes bind first: the most characters that fit, by binary search.
-    const raise = `maxBytes (up to ${MAX_RESULT_BYTES}, for a direct call_tool only)`;
+    const raise = `maxBytes (up to ${MAX_RESULT_BYTES}, ${routePhrases(ctx).directOnly})`;
     let low = 0;
     let high = Math.min(total, max);
     while (low < high) {
@@ -586,7 +587,7 @@ function readContent(client, ctx, fileId, maxChars, maxBytes) {
             format: "unavailable",
             contentTruncated: false,
             note: limit < BINARY_INLINE_BYTES
-                ? `A binary file of ${bytes} does not fit this result's maxBytes (${maxBytes}), which holds ${limit} bytes of file; no content is returned. Raise maxBytes, up to ${MAX_RESULT_BYTES} for a direct call_tool only, to read up to ${BINARY_INLINE_BYTES} bytes, or open webViewLink.`
+                ? `A binary file of ${bytes} does not fit this result's maxBytes (${maxBytes}), which holds ${limit} bytes of file; no content is returned. Raise maxBytes, up to ${MAX_RESULT_BYTES} ${routePhrases(ctx).directOnly}, to read up to ${BINARY_INLINE_BYTES} bytes, or open webViewLink.`
                 : `A binary file of ${bytes} is past this connection's ${BINARY_INLINE_BYTES}-byte inline cap; no content is returned. Open webViewLink.`,
         });
         // Metadata that already says too large saves the download; metadata that
@@ -1112,7 +1113,7 @@ function guarded(tool) {
                 return result;
             const raisable = "maxBytes" in tool.contract.input.fields;
             throw new ConnectorCallError("connector_call_failed", tool.annotations.readOnlyHint
-                ? `This ${tool.name} result serializes to ${bytes} bytes, past ${raisable ? `this call's maxBytes of ${budget}` : `the ${budget} bytes one result may carry`}; nothing is returned. ${raisable ? `Raise maxBytes (up to ${MAX_RESULT_BYTES}, for a direct call_tool only), or narrow the request.` : "Read the item in Drive instead."}`
+                ? `This ${tool.name} result serializes to ${bytes} bytes, past ${raisable ? `this call's maxBytes of ${budget}` : `the ${budget} bytes one result may carry`}; nothing is returned. ${raisable ? `Raise maxBytes (up to ${MAX_RESULT_BYTES}, ${routePhrases(ctx).directOnly}), or narrow the request.` : "Read the item in Drive instead."}`
                 : `${tool.name} applied, but its result serializes to ${bytes} bytes, past the ${budget} bytes one result may carry, so it is not returned. Re-read the item with get_file; do not repeat the write.`, { retryable: false });
         }),
     };
@@ -1122,16 +1123,10 @@ function buildTool(connection, tool) {
     const isList = ["search_files", "list_folder_items", "list_permissions", "list_shared_drives"].includes(tool.name);
     const output = asRecord(catalogSchema(tool.contract.output, "output"));
     const row = isList ? asRecord(asRecord(asRecord(output["properties"])["items"])["items"]) : output;
-    const roots = new Set(Object.keys(asRecord(row["properties"])));
+    const fields = isRead ? fieldsContract(isList ? "item" : "result", row) : undefined;
     const input = Schema.Struct({
         ...tool.contract.input.fields,
-        ...(isRead
-            ? {
-                fields: Schema.optionalKey(fieldsInput(isList
-                    ? "Dot paths to keep in each item; only narrows the result."
-                    : "Dot paths to keep in the result; only narrows the result.")),
-            }
-            : {}),
+        ...(fields ? { fields: Schema.optionalKey(fields.input) } : {}),
     });
     const spec = {
         name: tool.name,
@@ -1140,8 +1135,8 @@ function buildTool(connection, tool) {
         output: tool.contract.output,
         ...(tool.writeSteps ? { writeSteps: tool.writeSteps } : {}),
         run: (args) => Effect.gen(function* () {
-            const fields = args["fields"];
-            const problem = isRead ? fieldsProblem(fields, roots, isList ? "an item" : "the result") : undefined;
+            const selected = args["fields"];
+            const problem = fields?.problem(selected);
             if (problem)
                 return yield* Effect.fail(new Refusal({ error: problem }));
             const active = yield* Effect.serviceOption(Operation);
@@ -1161,9 +1156,9 @@ function buildTool(connection, tool) {
                 ? isList
                     ? {
                         ...result,
-                        items: asArray(result["items"]).map((item) => retainTruncated(item, selectFields(item, fields))),
+                        items: asArray(result["items"]).map((item) => retainTruncated(item, selectFields(item, selected))),
                     }
-                    : retainTruncated(result, selectFields(result, fields))
+                    : retainTruncated(result, selectFields(result, selected))
                 : result;
         }).pipe(Effect.catchDefect((error) => error instanceof ConnectorCallError ? Effect.fail(new Refusal({ error })) : Effect.die(error))),
     };

package/dist/providers/forms/api.js

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

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Finding forms and joining answers\n\nThe Forms API cannot list or search forms. Find the file through Drive, or use\nthe id after `/forms/d/` in its edit URL. The `/forms/d/e/…` responder link is\nnot a form id. A form id is also its Drive file id.\n\nA form contains items; an item may ask one question, several grid questions,\nor no question. Responses join by `questionId`, never by `itemId`. Named\nresponse reads label answers with the current question titles in form order;\nan answer to a deleted question has no title. A response may contain several\nvalues or uploaded-file references for one question. File ids join to Drive.\n\n## Reading complete responses\n\nResponses and respondent emails can contain personal information. Filter and\naggregate in `execute_code`, returning named answers only when the task needs\nthem. `submittedAfter` is exclusive UTC: retain the newest `lastSubmittedTime`\nfor the next incremental read. Google does not promise a stable response\nsnapshot. A continuation inside a changed vendor page fails `conflict`; start\nagain or use that newest timestamp.\n\nLarge grids continue inside the same item: `questionsFrom` places the returned\nrows. `omittedQuestionIds` identifies answers left out for size; read those ids\nwith `get_response`. The structural hatch exposes quiz grading and correct\nanswers, images, and option navigation that named projections omit. Temporary\nimage access destinations remain withheld.\n\n## Editing without losing structure\n\nRead the form's current revision before editing. A stale revision refuses the\nbatch as `conflict`; re-read and rebuild the requested edit. A revision guards\nconcurrent changes and does not make a repeated write safe.\n\nCreation sets only title and Drive file name. Add descriptions or questions\nafterward. `updateItem` can replace grading, images and section navigation;\nread the full item through the hatch first and use a precise `updateMask`.\nItem locations are indexes, while response answers use question ids.\n\nPublishing, sharing, deleting forms, and watch administration are outside this\nconnection. Responses are read-only; no tool submits or deletes a response.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `forms_api_details`, `forms_api_read`, `forms_api_search`, `get_form`, `list_responses`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 25, at most 100). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Hatch:** `forms_api_search` finds this API's operations and reads no account data, `forms_api_details` shows one operation's contract, and `forms_api_read` calls a reviewed read. `forms_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 5 operations are refused by design; use `forms_api_details` with the method and path to 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.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
+    "content": "## Finding forms and joining answers\n\nThe Forms API cannot list or search forms. Find the file through Drive, or use\nthe id after `/forms/d/` in its edit URL. The `/forms/d/e/…` responder link is\nnot a form id. A form id is also its Drive file id.\n\nA form contains items; an item may ask one question, several grid questions,\nor no question. Responses join by `questionId`, never by `itemId`. Named\nresponse reads label answers with the current question titles in form order;\nan answer to a deleted question has no title. A response may contain several\nvalues or uploaded-file references for one question. File ids join to Drive.\n\n## Reading complete responses\n\nResponses and respondent emails can contain personal information. Filter and\naggregate in `execute_code`, returning named answers only when the task needs\nthem. `submittedAfter` is exclusive UTC: retain the newest `lastSubmittedTime`\nfor the next incremental read. Google does not promise a stable response\nsnapshot. A continuation inside a changed vendor page fails `conflict`; start\nagain or use that newest timestamp.\n\nLarge grids continue inside the same item: `questionsFrom` places the returned\nrows. `omittedQuestionIds` identifies answers left out for size; read those ids\nwith `get_response`. The structural hatch exposes quiz grading and correct\nanswers, images, and option navigation that named projections omit. Temporary\nimage access destinations remain withheld.\n\n## Editing without losing structure\n\nRead the form's current revision before editing. A stale revision refuses the\nbatch as `conflict`; re-read and rebuild the requested edit. A revision guards\nconcurrent changes and does not make a repeated write safe.\n\nCreation sets only title and Drive file name. Add descriptions or questions\nafterward. `updateItem` can replace grading, images and section navigation;\nread the full item through the hatch first and use a precise `updateMask`.\nItem locations are indexes, while response answers use question ids.\n\nPublishing, sharing, deleting forms, and watch administration are outside this\nconnection. Responses are read-only; no tool submits or deletes a response.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `forms_api_details`, `forms_api_read`, `forms_api_search`, `get_form`, `list_responses`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 25, at most 100). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Hatch:** `forms_api_search` finds this API's operations and reads no account data, `forms_api_details` shows one operation's contract, and `forms_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `forms_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 5 operations are refused by design; use `forms_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: A revision-guarded batch update returned ABORTED or FAILED_PRECONDITION with HTTP 400 or 409.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
     "instructionsHeading": "Connection instructions"
 };

package/dist/providers/forms/tools.js

@@ -8,7 +8,7 @@ import { encodeForAgent, redactBeforeCut, redactSentSecrets } from "../../sent-s
 import { Integer, isMaxChars, isMinChars } from "../../http/json-schema.js";
 import { boundCursor, StandardPage } from "../../http/paging.js";
 import { read, write } from "../../http/tools.js";
-import { fieldsInput, fieldsProblem, selectFields } from "../../http/fields.js";
+import { fieldsContract, selectFields } from "../../http/fields.js";
 import { Refusal } from "../../http/errors.js";
 import { Operation } from "../../runtime/call.js";
 import { formsIndex, FORMS_REQUEST_KINDS } from "./lib/hatch.js";
@@ -551,6 +551,9 @@ const BatchRecord = optional({
     replyCount: Integer,
     createdItemCount: Integer,
 });
+const FORM_FIELDS = fieldsContract("result", FormRecord, "Page and cut metadata are preserved.");
+const RESPONSE_FIELDS = fieldsContract("result", ResponseRecord, "Cut and recovery metadata are preserved.");
+const RESPONSE_ITEM_FIELDS = fieldsContract("item", ResponseRecord, "It only narrows safe data.");
 const contextOf = Effect.gen(function* () {
     const operation = yield* Effect.serviceOption(Operation);
     if (Option.isNone(operation) || !operation.value)
@@ -609,12 +612,12 @@ export function formsTools({ connection }) {
             input: Schema.Struct({
                 formId,
                 cursor,
-                fields: Schema.optionalKey(fieldsInput("Dot paths to keep in the form; page and cut metadata is preserved.")),
+                fields: Schema.optionalKey(FORM_FIELDS.input),
             }),
             output: FormRecord,
             run: (args) => Effect.gen(function* () {
                 const ctx = yield* contextOf;
-                const problem = fieldsProblem(args.fields, new Set(Object.keys(FormRecord.fields)), "the form");
+                const problem = FORM_FIELDS.problem(args.fields);
                 if (problem)
                     return yield* Effect.fail(new Refusal({ error: problem }));
                 const formId = args["formId"];
@@ -764,7 +767,7 @@ export function formsTools({ connection }) {
             name: "list_responses",
             description: "List a Google Form's submitted responses, each answer labeled with its question's title in form order. Long answers are cut; get_response reads one whole.",
             input: Schema.Struct({
-                fields: Schema.optionalKey(fieldsInput("Dot paths to keep in each response item; only narrows safe data.")),
+                fields: Schema.optionalKey(RESPONSE_ITEM_FIELDS.input),
                 formId,
                 submittedAfter: Schema.optionalKey(Schema.String.check(pattern("^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?Z$")).annotate({
                     description: "Exclusive submitted-after UTC instant, e.g. 2026-10-01T00:00:00Z.",
@@ -783,7 +786,7 @@ export function formsTools({ connection }) {
             writeSteps: pairedReads,
             run: (args) => Effect.gen(function* () {
                 const ctx = yield* contextOf;
-                const problem = fieldsProblem(args.fields, new Set(Object.keys(ResponseRecord.fields)), "a response item");
+                const problem = RESPONSE_ITEM_FIELDS.problem(args.fields);
                 if (problem)
                     return yield* Effect.fail(new Refusal({ error: problem }));
                 const formId = args["formId"];
@@ -918,13 +921,13 @@ export function formsTools({ connection }) {
                 questionIds: Schema.optionalKey(Schema.Array(id("Question id from get_form or omittedQuestionIds."))
                     .check(Schema.isMinLength(1), Schema.isMaxLength(MAX_QUESTION_IDS), Schema.isUnique())
                     .annotate({ description: "Return only these questions for a large response." })),
-                fields: Schema.optionalKey(fieldsInput("Dot paths to keep in the response; cut and recovery metadata is preserved.")),
+                fields: Schema.optionalKey(RESPONSE_FIELDS.input),
             }),
             output: ResponseRecord,
             writeSteps: pairedReads,
             run: (args) => Effect.gen(function* () {
                 const ctx = yield* contextOf;
-                const problem = fieldsProblem(args.fields, new Set(Object.keys(ResponseRecord.fields)), "the response");
+                const problem = RESPONSE_FIELDS.problem(args.fields);
                 if (problem)
                     return yield* Effect.fail(new Refusal({ error: problem }));
                 const formId = args["formId"];

package/dist/providers/github/api.js

@@ -112,6 +112,7 @@ export function githubConnection() {
                 return { method: op.method, template: op.path };
             },
             redact: (data, op) => githubSafety.redact(data, op.method, op.template),
+            withholds: (op) => githubSafety.withholds(op.method, op.template),
             withholdsErrors: () => true,
         },
         sensitiveFields: { names: [], choice: "drop" },

package/dist/providers/github/lib/discovery.js

@@ -42,7 +42,7 @@ class RepositoryIndex extends OperationIndex {
             if (method === "GET" &&
                 error instanceof ConnectorCallError &&
                 error.code === "invalid_args" &&
-                error.message.includes(" operation in the pinned API index ") &&
+                error.message.includes(" operation at that path in the pinned API index ") &&
                 /^\/repos\/[^/]+\/[^/]+\/(?:commits|compare)\/[^/]+\/.+/.test(path))
                 throw new ConnectorCallError("invalid_args", `${error.message} Encode '/' inside refs as %2F.`);
             throw error;

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Choose the target\n\nAct as the configured GitHub App. `list_scopes` identifies its configured grants\nand reachable repositories. An exact repository grant can narrow its parent\norganization grant. Organization access covers repository operations, including\nfuture repositories in the installation, rather than organization administration.\nA repository rename keeps its ID-bound grant; a replacement at the old name does\nnot inherit it. A transfer cannot use the old installation's token.\n\nUse `search_scoped` for literal-word data search across installations. Each item\ncarries its partition and verified repository. Search completeness can be false\nat GitHub's search limit; narrow the selected scopes or terms when that matters.\nInstallation tokens do not override GitHub's own code-search restrictions.\nKeep the same `limit` with every named-list cursor. Omission uses 30, so a\ncursor issued with limit 30 can continue without an explicit limit.\n\n## Join the right identifiers\n\nAn issue or pull request number belongs to one owner/repository pair; a numeric\nrecord ID is a different identifier. An issue-list response can contain pull\nrequests: the `pull_request` property distinguishes them. Issue IDs returned for\npull requests are not necessarily the PR IDs from the pull-request endpoint.\nReviews join by pull request number; their `commit_id` identifies the reviewed\nrevision. Compare review and head commit IDs when deciding whether feedback is\ncurrent. Issue comments and pull-request review comments are different resources.\n\nRead files at an explicit Git ref when a stable revision matters. Nested contents\npaths are relative: `/repos/alice/widget/contents/lib/index.ts` reads that file,\nand `/repos/alice/widget/contents` lists the root directory. No dot segments,\nempty segments, backslashes or encoded traversal are accepted. In `commits/{ref}`\nand `compare/{basehead}`, encode branch-name slashes as `%2F`, for example\n`commits/feature%2Fx` or `compare/main...feature%2Fx`. Refs stay inside the selected\nrepository; owner-prefixed object refs and cross-repository compares are unavailable.\nFor a PR list, use `head:\"alice:feature/x\"`: the required `login:branch` filter\nselects this repository's PRs and never reads the login's repository. A bare\n`head` branch is refused because GitHub silently ignores it. `base` stays a branch name.\nContents are\nbase64 encoded; decode the inline content before interpreting it. Directory\nlistings have a vendor cap and are not recursive. Missing inline content or a\nmissing patch does not establish an empty file or an unchanged diff. Raw diff,\nlog/archive downloads, secret/admin operations and arbitrary GraphQL are unavailable.\n\n## Release and merge semantics\n\nPublishing a draft release updates that release's `draft` to false. Deleting a\nrelease does not delete its Git tag. Resolve the intended repository and existing\nrelease before changing it; a tag name is not a numeric release ID.\n\nUse `merge_pull_request` for merges. It requires the expected head SHA and a\nsame-repository head and base, plus explicit workflow-write access. GitHub's\natomic SHA guard binds the head rather than the base: a concurrent base retarget\ncan introduce workflow changes after the preflight. A response with `merged:false`\nis a failed merge, not a completed one. Inspect current PR state before a new attempt.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `github_api_details`, `github_api_read`, `github_api_search`, `list_scopes`, `search_scoped`, 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 30, 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:** `github_api_search` finds this API's operations and reads no account data, `github_api_details` shows one operation's contract, and `github_api_read` calls a reviewed read. `github_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 5 operations are refused by design; use `github_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: HTTP 409 is a conflict; a merged:false response and the expected-SHA/same-repository preflight also refuse a merge.\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": "## Choose the target\n\nAct as the configured GitHub App. `list_scopes` identifies its configured grants\nand reachable repositories. An exact repository grant can narrow its parent\norganization grant. Organization access covers repository operations, including\nfuture repositories in the installation, rather than organization administration.\nA repository rename keeps its ID-bound grant; a replacement at the old name does\nnot inherit it. A transfer cannot use the old installation's token.\n\nUse `search_scoped` for literal-word data search across installations. Each item\ncarries its partition and verified repository. Search completeness can be false\nat GitHub's search limit; narrow the selected scopes or terms when that matters.\nInstallation tokens do not override GitHub's own code-search restrictions.\nKeep the same `limit` with every named-list cursor. Omission uses 30, so a\ncursor issued with limit 30 can continue without an explicit limit.\n\n## Join the right identifiers\n\nAn issue or pull request number belongs to one owner/repository pair; a numeric\nrecord ID is a different identifier. An issue-list response can contain pull\nrequests: the `pull_request` property distinguishes them. Issue IDs returned for\npull requests are not necessarily the PR IDs from the pull-request endpoint.\nReviews join by pull request number; their `commit_id` identifies the reviewed\nrevision. Compare review and head commit IDs when deciding whether feedback is\ncurrent. Issue comments and pull-request review comments are different resources.\n\nRead files at an explicit Git ref when a stable revision matters. Nested contents\npaths are relative: `/repos/alice/widget/contents/lib/index.ts` reads that file,\nand `/repos/alice/widget/contents` lists the root directory. No dot segments,\nempty segments, backslashes or encoded traversal are accepted. In `commits/{ref}`\nand `compare/{basehead}`, encode branch-name slashes as `%2F`, for example\n`commits/feature%2Fx` or `compare/main...feature%2Fx`. Refs stay inside the selected\nrepository; owner-prefixed object refs and cross-repository compares are unavailable.\nFor a PR list, use `head:\"alice:feature/x\"`: the required `login:branch` filter\nselects this repository's PRs and never reads the login's repository. A bare\n`head` branch is refused because GitHub silently ignores it. `base` stays a branch name.\nContents are\nbase64 encoded; decode the inline content before interpreting it. Directory\nlistings have a vendor cap and are not recursive. Missing inline content or a\nmissing patch does not establish an empty file or an unchanged diff. Raw diff,\nlog/archive downloads, secret/admin operations and arbitrary GraphQL are unavailable.\n\n## Release and merge semantics\n\nPublishing a draft release updates that release's `draft` to false. Deleting a\nrelease does not delete its Git tag. Resolve the intended repository and existing\nrelease before changing it; a tag name is not a numeric release ID.\n\nUse `merge_pull_request` for merges. It requires the expected head SHA and a\nsame-repository head and base, plus explicit workflow-write access. GitHub's\natomic SHA guard binds the head rather than the base: a concurrent base retarget\ncan introduce workflow changes after the preflight. A response with `merged:false`\nis a failed merge, not a completed one. Inspect current PR state before a new attempt.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `github_api_details`, `github_api_read`, `github_api_search`, `list_scopes`, `search_scoped`, 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 30, 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:** `github_api_search` finds this API's operations and reads no account data, `github_api_details` shows one operation's contract, and `github_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `github_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 5 operations are refused by design; use `github_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: HTTP 409 is a conflict; a merged:false response and the expected-SHA/same-repository preflight also refuse a merge.\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": "Repository instructions"
 };

package/dist/providers/github/tools.js

@@ -3,7 +3,7 @@ import { api } from "../../connectors/api.js";
 import { deriveContext } from "../../derived-context.js";
 import { ConnectorCallError } from "../../errors.js";
 import { Refusal } from "../../http/errors.js";
-import { fieldsInput, fieldsProblem, selectFields } from "../../http/fields.js";
+import { fieldsContract, selectFields } from "../../http/fields.js";
 import { hatch } from "../../http/hatch.js";
 import { githubPage } from "../../http/hatch-paging.js";
 import { Integer, isMinChars } from "../../http/json-schema.js";
@@ -44,10 +44,9 @@ const common = {
         default: 30,
     })),
     cursor: Schema.optionalKey(text("Opaque page.nextCursor from this same search or scope listing.")),
-    fields: Schema.optionalKey(fieldsInput("Dot paths into each item; only narrows already-safe data.")),
 };
-const scopeNames = new Set(["org", "repo", "owner", "id", "full_name", "access", "workflows"]);
-const searchNames = new Set(["scope", "repository", "item"]);
+const SCOPE_FIELDS = fieldsContract("item", ScopeRow, "It only narrows already-safe data.");
+const SEARCH_FIELDS = fieldsContract("item", SearchRow, "Vendor fields are under item, e.g. item.title; it only narrows already-safe data.", "an item (vendor fields are under item)");
 const contextOf = Effect.gen(function* () {
     const op = yield* Effect.serviceOption(Operation);
     if (Option.isNone(op) || !op.value)
@@ -74,6 +73,36 @@ function selectors(input, policy) {
         return { repo: `${t.owner}/${t.repo}`, access: grant.access };
     });
 }
+const SEARCH_TERMS = /^[a-z0-9_. -]{1,128}$/i;
+const BOOLEAN_TERMS = /\b(?:OR|NOT|AND)\b/i;
+/**
+ * Record every selector problem by shape alone: a refusal never repeats a
+ * submitted org or repository, and list_scopes names the configured grants.
+ */
+function selectorIssues(problems, input, policy) {
+    input?.forEach((item, index) => {
+        const value = row(item), at = `/scopes/${index}`;
+        if ((value.org === undefined) === (value.repo === undefined))
+            return problems.add(at, 'exactly one key: {"org": "<org>"} for an org-wide grant or {"repo": "<owner>/<repo>"}', value.org === undefined ? "neither org nor repo" : "both org and repo");
+        let admitted = false;
+        try {
+            if (value.org !== undefined)
+                admitted = policy.scopes.some((scope) => scope.org === policy.owner(value.org));
+            else {
+                const parts = typeof value.repo === "string" ? value.repo.split("/") : [];
+                admitted = !!policy.scope(target(parts[0], parts.length === 2 ? parts[1] : undefined));
+            }
+        }
+        catch (error) {
+            if (!(error instanceof ConnectorCallError))
+                throw error;
+        }
+        if (!admitted)
+            problems.add(`${at}/${value.org !== undefined ? "org" : "repo"}`, value.org !== undefined
+                ? "an organization configured for org-wide access; list_scopes names them"
+                : '"<owner>/<repo>" of a configured repository or one in a configured org; list_scopes names them');
+    });
+}
 function searchPartitions(scopes) {
     const orgs = new Set(scopes.flatMap((scope) => (scope.org ? [scope.org] : [])));
     const repos = new Map();
@@ -232,18 +261,30 @@ export function restConnector(id, auth, policy) {
             throw new ConnectorCallError("invalid_args", `This cursor was issued with limit ${position.limit}; repeat limit ${position.limit} or start a new listing.`);
         return position;
     };
-    const namesCheck = (fields, names) => checked(() => {
-        const bad = fieldsProblem(fields, names, "an item");
-        if (bad)
-            throw bad;
-    });
     const scopesTool = read(connection, {
         name: "list_scopes",
         description: "List configured GitHub grants locally, or verified reachable repositories for one configured owner. Without owner this reads configuration without network access.",
-        input: Schema.Struct({ owner: Schema.optionalKey(text("Configured owner; omit for local grants.")), ...common }),
+        input: Schema.Struct({
+            owner: Schema.optionalKey(text("Configured owner; omit for local grants.")),
+            ...common,
+            fields: Schema.optionalKey(SCOPE_FIELDS.input),
+        }),
         output: Schema.Struct({ items: Schema.Array(ScopeRow), page: StandardPage }),
+        check: (args, problems) => {
+            SCOPE_FIELDS.issues(problems, args.fields);
+            if (args.owner === undefined)
+                return;
+            try {
+                policy.owner(args.owner);
+            }
+            catch (error) {
+                if (!(error instanceof ConnectorCallError))
+                    throw error;
+                // Without owner, the listing reads the configured grants locally.
+                problems.add("/owner", "a configured owner; omit owner to list the configured grants");
+            }
+        },
         run: (args) => Effect.gen(function* () {
-            yield* namesCheck(args.fields, scopeNames);
             const limit = args.limit ?? 30, normalized = { ...args, limit };
             const raw = yield* decode("list_scopes", normalized);
             const position = yield* checked(() => parse(raw, limit));
@@ -309,15 +350,18 @@ export function restConnector(id, auth, policy) {
                 .check(Schema.isMinLength(1), Schema.isMaxLength(100))
                 .annotate({ description: "Optional subset of the configured scopes." })),
             ...common,
+            fields: Schema.optionalKey(SEARCH_FIELDS.input),
         }),
         output: Schema.Struct({ items: Schema.Array(SearchRow), page: StandardPage, incomplete_results: Schema.Boolean }),
+        check: (args, problems) => {
+            // Rows wrap the vendor's record under item, so a vendor field is item.<field>.
+            SEARCH_FIELDS.issues(problems, args.fields);
+            if (!SEARCH_TERMS.test(args.terms) || BOOLEAN_TERMS.test(args.terms))
+                problems.add("/terms", "literal words of letters, digits, spaces, _ . or -, at most 128 characters, without qualifiers such as is:open or label:x and without OR, AND or NOT; kind and scopes select the rest");
+            selectorIssues(problems, args.scopes, policy);
+        },
         run: (args) => Effect.gen(function* () {
-            yield* namesCheck(args.fields, searchNames);
-            const selected = yield* checked(() => {
-                if (!/^[a-z0-9_. -]{1,128}$/i.test(args.terms) || /\b(?:OR|NOT|AND)\b/i.test(args.terms))
-                    throw new ConnectorCallError("invalid_args", "Search terms must be literal words, without qualifiers or Boolean operators.");
-                return args.scopes === undefined ? policy.scopes : selectors(args.scopes, policy);
-            });
+            const selected = yield* checked(() => args.scopes === undefined ? policy.scopes : selectors(args.scopes, policy));
             const partitions = yield* checked(() => searchPartitions(selected)), limit = args.limit ?? 30, normalized = { ...args, limit };
             const raw = yield* decode("search_scoped", normalized), at = yield* checked(() => parse(raw, limit));
             const partitionIndex = at.partition ?? 0, page = at.page ?? 1;