@zackbart/connecta 0.41.0 → 0.42.0

package/dist/providers/github/api.js

@@ -8,7 +8,7 @@ import { INTERNAL_READS, MERGE, READ_PERMISSIONS, RELEASE_PERMISSIONS } from "./
 import { errorMeanings } from "../../http/errors.js";
 import { ConnectorCallError } from "../../errors.js";
 import { guardedClient } from "../../http/client.js";
-import { captureClassifierFacts, StatusFailure } from "../../http/errors.js";
+import { captureClassifierFacts, StatusFailure, } from "../../http/errors.js";
 import { resultSafety } from "../../http/safety.js";
 import { connect, get, operations } from "../../http/vendor.js";
 const repository = { owner: Schema.String, repo: Schema.String };
@@ -25,7 +25,7 @@ export function rejectedToken(status, headers) {
     const numbers = captureClassifierFacts(undefined, errors, headers)?.numbers;
     return !rateLimited(status, numbers?.["retryAfterMs"], numbers?.["remaining"]);
 }
-const AUTH = "Verify the GitHub App key, installation, repository selection and required permissions.";
+const AUTH = "GitHub rejected the credential (HTTP 401). Verify the GitHub App ID, private key and installation.";
 const FAILED = "The GitHub API request failed; downstream error text is withheld.";
 function rate(input) {
     if (!rateLimited(input.status, input.retryAfterMs, input.numbers["remaining"]))
@@ -39,7 +39,99 @@ function rate(input) {
         advice: " Honor the retry timing before trying again.",
     };
 }
+// GitHub's permission and scope headers are vendor-controlled text. A header
+// that is not wholly the documented shape is dropped, never partly repeated,
+// so nothing but a bounded permission or scope name reaches an agent.
+const PERMISSION = /^[a-z][a-z0-9_]{0,63}=(?:read|write|admin)$/;
+const OAUTH_SCOPE = /^[a-z][a-z0-9_]{0,31}(?::[a-z][a-z0-9_]{0,31})?$/;
+const MAX_ALTERNATIVES = 4;
+const MAX_NAMES = 8;
+/** `a=read,b=read; c=read` lists alternative sets, each needing all its members. */
+function acceptedPermissions(header) {
+    if (!header?.trim())
+        return undefined;
+    const sets = header.split(";").map((set) => set.split(",").map((name) => name.trim()));
+    if (sets.length > MAX_ALTERNATIVES ||
+        sets.some((set) => set.length > MAX_NAMES || set.some((name) => !PERMISSION.test(name))))
+        return undefined;
+    return sets.map((set) => set.join(" and ")).join(", or ");
+}
+function scopeNames(header) {
+    if (!header?.trim())
+        return undefined;
+    const names = header.split(",").map((name) => name.trim());
+    return names.length <= MAX_NAMES && names.every((name) => OAUTH_SCOPE.test(name)) ? names : undefined;
+}
+/** The accepted scopes this token does not already hold; an unreadable held list cannot subtract. */
+function missingScopes(accepted, held) {
+    const needed = scopeNames(accepted);
+    if (!needed)
+        return undefined;
+    const has = scopeNames(held) ?? [];
+    const missing = needed.filter((name) => !has.includes(name));
+    return missing.length > 0 ? missing.join(", ") : undefined;
+}
+const WITHHELD = "its reason is withheld";
+const WAIT = "After a burst of requests, wait a minute before one retry.";
+const ALL_REFUSED = "If every GitHub call through this connection is refused, verify the App ID, private key and installation.";
+const OTHER_CAUSES = "An unmarked secondary rate limit, an IP allow list or a repository or organization policy can also refuse a request with sufficient permissions, and repeated invalid credentials can lock out authentication with a 403.";
+const REMEDIES = "A rate limit or lockout clears with time; a confirmed permission or repository gap needs the App owner and installation owner; a confirmed policy or IP restriction needs an administrator.";
+/**
+ * A 403 establishes a refusal and not its cause: classification never reads
+ * GitHub's prose, and the permission headers describe the endpoint rather than
+ * this token. Each message says what is known, what is likely, then what to do.
+ */
+function refused({ headers, operation, status }) {
+    // Only the App's own JWT is in play here, so no repository grant can explain it.
+    if (operation.template === "/app/installations")
+        return {
+            code: "auth_required",
+            retryable: false,
+            words: () => `GitHub refused the App's own request to list its installations (HTTP ${status}), before any repository permission applied; ${WITHHELD}. A lockout after repeated invalid credentials is likely, and an unmarked secondary rate limit, IP allow list or policy is possible. ${WAIT} If it persists, verify the GitHub App ID and private key.`,
+        };
+    const repository = operation.context?.["repository"];
+    const where = repository ? `for ${repository}` : "for this resource";
+    if (/^required(?:;|$)/i.test(headers["x-github-sso"] ?? ""))
+        return denied(`GitHub refused this request ${where}: the organization enforces SAML single sign-on and this credential is not authorized for it. An organization owner must authorize it; replacing the key will not change this.`);
+    const accepted = acceptedPermissions(headers["x-accepted-github-permissions"]);
+    const scopes = accepted ? undefined : missingScopes(headers["x-accepted-oauth-scopes"], headers["x-oauth-scopes"]);
+    const requested = operation.context?.["permissions"];
+    const need = accepted
+        ? ` This endpoint accepts ${accepted}.`
+        : scopes
+            ? ` This endpoint lists the OAuth scope ${scopes}, which this token does not report.`
+            : requested
+                ? ` This call requested ${requested}.`
+                : "";
+    return denied(`GitHub refused this request ${where} (HTTP ${status}); ${WITHHELD}.${need} The likely cause is access the App or its installation does not hold. ${OTHER_CAUSES} Report this as an access gap and continue with other repositories; do not reset the credential or switch tools on this result alone. ${WAIT} ${REMEDIES} ${ALL_REFUSED}`);
+}
+function denied(message) {
+    return { code: "provider_permission_denied", retryable: false, words: () => message };
+}
+/**
+ * GitHub documents a mint's 422 as a validation failure or spam protection, so
+ * the status alone never establishes a permission gap. `missing` is the positive
+ * evidence: requested permissions absent from GitHub's own installation record.
+ */
+function refusedToken({ status, operation }) {
+    if ((status !== 422 && status !== 403) || !/^\/app\/installations\/\d+\/access_tokens$/.test(operation.template))
+        return undefined;
+    const repository = operation.context?.["repository"], requested = operation.context?.["permissions"], missing = operation.context?.["missing"];
+    const asked = `GitHub would not issue an installation token${repository ? ` for ${repository}` : ""}${requested ? ` with ${requested}` : ""} (HTTP ${status})`;
+    if (missing)
+        return denied(`${asked}. The installation does not hold ${missing}. Report this as an access gap; other reads may still work. The App owner must grant that permission and the installation owner must approve it; replacing the key will not add it.`);
+    if (status === 422)
+        return {
+            code: "connector_call_failed",
+            retryable: false,
+            words: () => `${asked}; ${WITHHELD}. GitHub documents this status for validation failures and spam protection, so a missing permission or repository is possible but not established. Report this failure; other reads may still work. Wait before one retry, and if it persists check the permissions and repositories granted to this installation.`,
+        };
+    return denied(`${asked}; ${WITHHELD}. A suspended installation, an IP allow list or policy, an unmarked secondary rate limit or a lockout after repeated invalid credentials can each cause this. Report this failure; other repositories may still work. ${WAIT} ${ALL_REFUSED}`);
+}
 export const errors = {
+    headers: ["x-accepted-github-permissions", "x-accepted-oauth-scopes", "x-oauth-scopes", "x-github-sso"],
+    // An SSO challenge carries a long signed URL, read only as far as its keyword.
+    maxHeaderChars: 512,
     numericFacts: {
         retryAfterMs: {
             header: "retry-after",
@@ -79,8 +171,9 @@ export const errors = {
             }
             : undefined,
         rate,
+        refusedToken,
     ],
-    detail: ({ status: code }) => code === 401 || code === 403
+    detail: ({ status: code }) => code === 401
         ? AUTH
         : code === 409
             ? "GitHub reported a conflict. Read the current state."
@@ -89,7 +182,7 @@ export const errors = {
                 : FAILED,
     statuses: {
         401: () => ({ code: "auth_required", retryable: false }),
-        403: () => ({ code: "auth_required", retryable: false }),
+        403: refused,
         404: () => ({ code: "connector_call_failed", retryable: false }),
         409: () => ({ code: "conflict", retryable: false, advice: " before resubmitting" }),
     },
@@ -144,8 +237,7 @@ export function githubConnection() {
 export const kit = {
     operations: operations(GitHubApi),
     pageSize: { default: 30, max: 100 },
-    hatch: { name: GITHUB_HATCH.name, verdicts: GITHUB_HATCH.verdicts, paging: "argument" },
+    hatch: { name: GITHUB_HATCH.name, verdicts: GITHUB_HATCH.verdicts },
     errors: errorMeanings(errors),
     idempotencyKey: false,
-    refusesWithheld: true,
 };

package/dist/providers/github/index.js

@@ -1,5 +1,6 @@
 import { array, keys, optionsOf } from "../../config-schema.js";
 import { ConnectorCallError } from "../../errors.js";
+import { carryConnectorVocabulary } from "../../operation-vocabulary.js";
 import { delegatesEachCall, knownProviderFailure } from "../../provider-call.js";
 import { defineProvider, PROVIDER_COMMON } from "../../provider.js";
 import { kit } from "./api.js";
@@ -9,6 +10,7 @@ import { parseScopes, ScopePolicy } from "./lib/scope.js";
 import { skill } from "./skill.generated.js";
 /** One GitHub App, multiple owner installations, explicit org/repo grants. */
 export const github = defineProvider({
+    blocks: { keys: ["writes"], select: (options) => (options.readOnly ? [] : ["writes"]) },
     name: "github",
     title: "GitHub",
     kind: "api",
@@ -36,7 +38,7 @@ export const github = defineProvider({
             context: [
                 `Act as the GitHub App. Reachable configuration: ${policy.summary()}.`,
                 `Purpose: ${options.purpose}`,
-                "The App identity is already configured. Installation access is resolved on use; ask the operator to repair configuration only after an auth failure.",
+                "The App identity is already configured. Installation access is resolved on use; ask the operator to repair configuration only after an auth or permission failure.",
                 ...(options.readOnly === true ? ["This connection is read-only; every write is refused."] : []),
             ],
             summary: "Load for GitHub repository searches, releases and guarded merges.",
@@ -50,7 +52,7 @@ export const github = defineProvider({
             }
             : undefined;
         // Each call goes to its REST boundary, whose write-outcome verdict stands.
-        return delegatesEachCall({
+        const connector = delegatesEachCall({
             id,
             title: options.title ?? "GitHub",
             // Preserve the REST tools' existing MCP result envelope.
@@ -79,5 +81,8 @@ export const github = defineProvider({
                 return { state: "ok", message: "GitHub App configured; installation access is resolved lazily on use." };
             },
         });
+        // Search reads hatch operations through this outer object, not the REST one.
+        carryConnectorVocabulary(rest, connector);
+        return connector;
     },
 });

package/dist/providers/github/lib/auth.d.ts

@@ -7,6 +7,8 @@ export interface GitHubApp {
     privateKey?: string;
 }
 export type Permissions = Readonly<Record<string, "read" | "write">>;
+/** Reviewed permission names only, in GitHub's own `name=access` spelling. */
+export declare const permissionWords: (permissions: Permissions) => string;
 export declare class AppAuth {
     readonly app: GitHubApp;
     readonly policy: ScopePolicy;
@@ -21,7 +23,7 @@ export declare class AppAuth {
     constructor(app: GitHubApp, policy: ScopePolicy);
     private key;
     /** `write` sends the request once: a failure that may follow the change is not retryable. */
-    json(request: GuardedRequest, bearer: string, ctx: ConnectorContext, write?: boolean): Promise<unknown>;
+    json(request: GuardedRequest, bearer: string, ctx: ConnectorContext, write?: boolean, context?: Readonly<Record<string, string>>): Promise<unknown>;
     private invalidate;
     rejectToken(bearer: string): Promise<void>;
     private installation;

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

@@ -5,10 +5,15 @@ import { errors, rejectedToken } from "../api.js";
 import { appJwt, privateKeyDer } from "./key.js";
 import { target } from "./scope.js";
 import { sentSecretsFor } from "../../../sent-secrets.js";
+/** Reviewed permission names only, in GitHub's own `name=access` spelling. */
+export const permissionWords = (permissions) => Object.entries(permissions)
+    .map(([name, access]) => `${name}=${access}`)
+    .join(" and ");
 const MAX_ENTRIES = 256;
 const REFRESH_MARGIN = 60_000;
 const INSTALLATION_TTL = 300_000;
 const REPOSITORY_TTL = 300_000;
+const MAX_NAMED = 3;
 function boundedSet(map, key, value) {
     if (!map.has(key) && map.size >= MAX_ENTRIES)
         map.delete(map.keys().next().value);
@@ -17,6 +22,23 @@ function boundedSet(map, key, value) {
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
+const ACCESS = { read: 1, write: 2, admin: 3 };
+/** Well-formed entries only; an empty or malformed record proves nothing. */
+function heldPermissions(value) {
+    const held = Object.entries(record(value)).filter((entry) => typeof entry[1] === "string" && ACCESS[entry[1]] !== undefined);
+    return held.length > 0 ? Object.fromEntries(held) : undefined;
+}
+/**
+ * Requested permissions the installation's own record lacks, the only evidence
+ * that names a refused mint a permission gap. Metadata read is implicit for every App.
+ */
+function missingPermissions(installation, requested) {
+    const held = installation.permissions;
+    if (!held)
+        return undefined;
+    const missing = Object.entries(requested).filter(([name, access]) => name !== "metadata" && (ACCESS[held[name] ?? ""] ?? 0) < ACCESS[access]);
+    return missing.length > 0 ? Object.fromEntries(missing) : undefined;
+}
 export class AppAuth {
     app;
     policy;
@@ -83,7 +105,7 @@ export class AppAuth {
         };
     }
     /** `write` sends the request once: a failure that may follow the change is not retryable. */
-    async json(request, bearer, ctx, write = false) {
+    async json(request, bearer, ctx, write = false, context) {
         ctx.signal?.throwIfAborted();
         return this.send({
             classification: write ? "write" : "read",
@@ -99,7 +121,7 @@ export class AppAuth {
                     status: response.status,
                     headers: response.headers,
                     body: undefined,
-                    operation: { method: request.method, template: request.path },
+                    operation: { method: request.method, template: request.path, ...(context ? { context } : {}) },
                 }), captureClassifierFacts(undefined, errors, response.headers));
                 throw toConnectorCallError(failure, errors, {
                     classification: write ? "write" : "read",
@@ -152,13 +174,15 @@ export class AppAuth {
                 if (typeof account.login !== "string" || account.login.toLowerCase() !== owner)
                     continue;
                 if (!Number.isSafeInteger(row.id) || Number(row.id) <= 0 || row.suspended_at != null) {
-                    throw new ConnectorCallError("auth_required", "Install or unsuspend the GitHub App on the configured owner.");
+                    throw new ConnectorCallError("provider_permission_denied", "Install or unsuspend the GitHub App on the configured owner. The App credential works, so resetting it will not help.");
                 }
+                const permissions = heldPermissions(row.permissions);
                 found = {
                     id: Number(row.id),
                     owner,
                     all: row.repository_selection === "all",
                     organization: account.type === "Organization",
+                    ...(permissions ? { permissions } : {}),
                     expires: Date.now() + INSTALLATION_TTL,
                 };
             }
@@ -168,9 +192,9 @@ export class AppAuth {
                 throw new ConnectorCallError("connector_call_failed", "The GitHub installation list exceeded its paging bound; no partial mapping was cached.");
         }
         if (!found)
-            throw new ConnectorCallError("auth_required", "Install the GitHub App on the configured owner and grant the configured repositories.");
+            throw new ConnectorCallError("provider_permission_denied", "Install the GitHub App on the configured owner and grant the configured repositories. The App credential works, so resetting it will not help.");
         if (this.policy.repositories(owner) === undefined && (!found.all || !found.organization)) {
-            throw new ConnectorCallError("auth_required", "Org scopes require an organization installation with All repositories selected, including future repositories.");
+            throw new ConnectorCallError("provider_permission_denied", "Org scopes require an organization installation with All repositories selected, including future repositories.");
         }
         ctx.signal?.throwIfAborted();
         // Compare-and-set by entry identity. A slower request cannot overwrite a
@@ -180,7 +204,7 @@ export class AppAuth {
         if (this.policy.repositories(owner) === undefined) {
             const bound = this.orgInstallations.get(owner);
             if (bound !== undefined && bound !== resolved.id)
-                throw new ConnectorCallError("auth_required", "The organization grant is bound to a different installation. Reconfigure after reviewing the replacement installation.");
+                throw new ConnectorCallError("provider_permission_denied", "The organization grant is bound to a different installation. Reconfigure after reviewing the replacement installation.");
             this.orgInstallations.set(owner, resolved.id);
         }
         if (this.installations.get(cacheKey) === previous)
@@ -196,7 +220,7 @@ export class AppAuth {
         // GitHub requires an installation token for /installation/repositories.
         // Mint with the App JWT, metadata only, and never give this resolver token
         // to the hosted server or a caller-selected REST operation.
-        const resolver = await this.mint(owner, installation, key, undefined, { metadata: "read" }, ctx, "resolver");
+        const resolver = await this.mint(owner, installation, key, undefined, { metadata: "read" }, ctx, owner, "resolver");
         const found = new Map();
         const configured = this.policy.scopes.filter((scope) => scope.repo?.startsWith(`${owner}/`));
         for (let page = 1; page <= 100; page++) {
@@ -228,7 +252,7 @@ export class AppAuth {
             if (!this.grants.has(grant.repo) && repo)
                 this.grants.set(grant.repo, repo.id);
             if (!this.grants.has(grant.repo))
-                throw new ConnectorCallError("auth_required", "A configured repository grant could not be bound in this installation.");
+                throw new ConnectorCallError("provider_permission_denied", `The configured grant ${grant.repo} could not be bound in this installation: select that repository for the GitHub App, or remove the grant. Until then this owner's repositories stay unavailable. The App credential works, so resetting it will not help.`);
             if (!repo) {
                 const renamed = [...found.values()].find((candidate) => candidate.id === this.grants.get(grant.repo));
                 if (renamed)
@@ -245,7 +269,7 @@ export class AppAuth {
         }
         const resolved = this.repositories.get(cacheKey);
         if (!resolved || resolved.expires <= Date.now())
-            throw new ConnectorCallError("auth_required", "The repository is not reachable in the configured installation. Verify its selection or current name.");
+            throw new ConnectorCallError("provider_permission_denied", "This repository is not reachable in the configured installation. Verify its selection or current name; other repositories may still work. The App credential works, so resetting it will not help.");
         return resolved;
     }
     authorizeId(repo, permissions) {
@@ -281,9 +305,11 @@ export class AppAuth {
                 ids.push(repo.id);
             }
         const repositorySet = names ? [...new Set(ids)].sort((a, b) => a - b) : undefined;
-        return this.mint(owner, installation, key, repositorySet, permissions, ctx);
+        // Each name is now bound to a repository this installation returned.
+        const named = names && names.length <= MAX_NAMED ? names.map((name) => `${owner}/${name}`).join(", ") : owner;
+        return this.mint(owner, installation, key, repositorySet, permissions, ctx, named);
     }
-    async mint(owner, installation, key, repositorySet, permissions, ctx, purpose = "operation") {
+    async mint(owner, installation, key, repositorySet, permissions, ctx, repository, purpose = "operation") {
         const permissionSet = Object.fromEntries(Object.entries(permissions).sort(([a], [b]) => a.localeCompare(b)));
         const cacheKey = JSON.stringify([key.fingerprint, installation.id, repositorySet ?? "all", permissionSet, purpose]);
         const previous = this.tokens.get(cacheKey);
@@ -296,6 +322,7 @@ export class AppAuth {
         catch {
             throw new ConnectorCallError("auth_required", "The GitHub App key could not sign an RS256 JWT. Replace the key.");
         }
+        const missing = missingPermissions(installation, permissionSet);
         let response;
         try {
             response = record(await this.json({
@@ -303,7 +330,11 @@ export class AppAuth {
                 method: "POST",
                 path: `/app/installations/${installation.id}/access_tokens`,
                 body: { permissions: permissionSet, ...(repositorySet ? { repository_ids: repositorySet } : {}) },
-            }, jwt, ctx));
+            }, jwt, ctx, false, {
+                repository,
+                permissions: permissionWords(permissionSet),
+                ...(missing ? { missing: permissionWords(missing) } : {}),
+            }));
         }
         catch (error) {
             // Re-resolve on the next call, never replay this call. Fence a slow

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

@@ -23,6 +23,7 @@ export function contentsPath(path) {
     workflowPath(relative);
     return match[1] + encodeURIComponent(relative);
 }
+const COMMIT_SUBRESOURCE = /^(\/repos\/[^/]+\/[^/]+\/commits\/)([^/]+)(\/(?:check-runs|check-suites|status|statuses))$/;
 // Prefer the deployed coverage for natural queries. Explicit paths and queries
 // without reviewed matches retain full-pin refusal discovery. Metadata, contract
 // lookup, validation and the manifest still use the complete immutable pin.
@@ -35,6 +36,15 @@ class RepositoryIndex extends OperationIndex {
             const match = super.resolve(method, `${path}/root`);
             return { ...match, params: { ...match.params, path: "" } };
         }
+        // The shared index admits an encoded slash only in a final parameter, so a
+        // branch like feature%2Fx is checked as commits/{ref} itself, then bound to
+        // its reviewed CI read. Nothing here widens the path the request is sent to.
+        const nested = method === "GET" ? COMMIT_SUBRESOURCE.exec(path) : null;
+        if (nested && /%2f/i.test(nested[2])) {
+            const { params } = super.resolve(method, `${nested[1]}${nested[2]}`);
+            const match = super.resolve(method, `${nested[1]}ref${nested[3]}`);
+            return { ...match, params: { ...match.params, ref: params.ref } };
+        }
         try {
             return super.resolve(method, contentsPath(path));
         }
@@ -55,7 +65,7 @@ class RepositoryIndex extends OperationIndex {
                 if (param.name === "path")
                     param.description =
                         "Canonical relative file or directory path; nested paths such as src/index.ts are accepted. For the root directory use /repos/{owner}/{repo}/contents without a final path.";
-        if (["/repos/{owner}/{repo}/commits/{ref}", "/repos/{owner}/{repo}/compare/{basehead}"].includes(op.path))
+        if (/^\/repos\/\{owner\}\/\{repo\}\/(?:commits\/\{ref\}(?:\/[a-z-]+)?|compare\/\{basehead\})$/.test(op.path))
             for (const param of contract.parameters)
                 if (param.name === "ref" || param.name === "basehead")
                     param.description =

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

@@ -32,6 +32,14 @@ export const READ_PERMISSIONS = {
     "GET /repos/{owner}/{repo}/actions/runs/{run_id}": { actions: "read" },
     "GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs": { actions: "read" },
     "GET /repos/{owner}/{repo}/actions/jobs/{job_id}": { actions: "read" },
+    "GET /repos/{owner}/{repo}/commits/{ref}/check-runs": { checks: "read" },
+    "GET /repos/{owner}/{repo}/commits/{ref}/check-suites": { checks: "read" },
+    "GET /repos/{owner}/{repo}/check-runs/{check_run_id}": { checks: "read" },
+    "GET /repos/{owner}/{repo}/check-runs/{check_run_id}/annotations": { checks: "read" },
+    "GET /repos/{owner}/{repo}/check-suites/{check_suite_id}": { checks: "read" },
+    "GET /repos/{owner}/{repo}/check-suites/{check_suite_id}/check-runs": { checks: "read" },
+    "GET /repos/{owner}/{repo}/commits/{ref}/status": { statuses: "read" },
+    "GET /repos/{owner}/{repo}/commits/{ref}/statuses": { statuses: "read" },
 };
 export const RELEASE_PERMISSIONS = {
     "POST /repos/{owner}/{repo}/releases": { contents: "write" },

package/dist/providers/github/safety.js

@@ -98,6 +98,45 @@ const RESPONSE_PATHS = {
         "redact": [],
         "keep": ["commit.verification.signature"],
     },
+    "GET /repos/{owner}/{repo}/check-suites/{check_suite_id}": {
+        "redact": ["repository.temp_clone_token"],
+        "keep": [
+            "repository.security_and_analysis.advanced_security",
+            "repository.security_and_analysis.secret_scanning",
+            "repository.security_and_analysis.secret_scanning_ai_detection",
+            "repository.security_and_analysis.secret_scanning_delegated_alert_dismissal",
+            "repository.security_and_analysis.secret_scanning_delegated_bypass",
+            "repository.security_and_analysis.secret_scanning_delegated_bypass_options",
+            "repository.security_and_analysis.secret_scanning_delegated_bypass_options.reviewers",
+            "repository.security_and_analysis.secret_scanning_non_provider_patterns",
+        ],
+    },
+    "GET /repos/{owner}/{repo}/commits/{ref}/check-suites": {
+        "redact": ["check_suites[].repository.temp_clone_token"],
+        "keep": [
+            "check_suites[].repository.security_and_analysis.advanced_security",
+            "check_suites[].repository.security_and_analysis.secret_scanning",
+            "check_suites[].repository.security_and_analysis.secret_scanning_ai_detection",
+            "check_suites[].repository.security_and_analysis.secret_scanning_delegated_alert_dismissal",
+            "check_suites[].repository.security_and_analysis.secret_scanning_delegated_bypass",
+            "check_suites[].repository.security_and_analysis.secret_scanning_delegated_bypass_options",
+            "check_suites[].repository.security_and_analysis.secret_scanning_delegated_bypass_options.reviewers",
+            "check_suites[].repository.security_and_analysis.secret_scanning_non_provider_patterns",
+        ],
+    },
+    "GET /repos/{owner}/{repo}/commits/{ref}/status": {
+        "redact": ["repository.temp_clone_token"],
+        "keep": [
+            "repository.security_and_analysis.advanced_security",
+            "repository.security_and_analysis.secret_scanning",
+            "repository.security_and_analysis.secret_scanning_ai_detection",
+            "repository.security_and_analysis.secret_scanning_delegated_alert_dismissal",
+            "repository.security_and_analysis.secret_scanning_delegated_bypass",
+            "repository.security_and_analysis.secret_scanning_delegated_bypass_options",
+            "repository.security_and_analysis.secret_scanning_delegated_bypass_options.reviewers",
+            "repository.security_and_analysis.secret_scanning_non_provider_patterns",
+        ],
+    },
     "GET /repos/{owner}/{repo}/compare/{basehead}": {
         "redact": [],
         "keep": [

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. 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.",
+    "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## Read CI state\n\nA commit's CI lives in two systems, so read both: `commits/{ref}/check-runs` holds\nActions and App checks, and `commits/{ref}/status` holds older commit statuses. A\nstatus of `pending` with no statuses means none were posted, not that CI is running.\nCheck-run annotations give failing paths and lines, since log downloads are unavailable.\n\n## When access is refused\n\n`provider_permission_denied` is a refusal: usually a gap in the App's access to that\nrepository or permission, though a policy, an unmarked rate limit or a lockout can\nalso cause it. Report the gap and continue; other repositories may still work. Do not\nreset the credential or switch tools on this alone. `auth_required` is the failure\nthat points at the credential itself.\n\n<!-- when: writes -->\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<!-- end -->\n\n## Conventions\n\n- **Hatch:** `github_api_search` finds operations, `github_api_details` shows one contract, `github_api_read` calls a reviewed read and `github_api_write` a reviewed write. 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- **Errors:** An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: HTTP 409 is a conflict; a merged:false response and the expected-SHA/same-repository preflight also refuse a merge.",
     "instructionsHeading": "Repository instructions"
 };

package/dist/providers/github/tools.js

@@ -16,6 +16,7 @@ import { tracksEveryRequest } from "../../provider-call.js";
 import { checked } from "../_shared/rest/kit.js";
 import { withholdEmbeddedUrlsIn } from "../_shared/rest/value-safety.js";
 import { githubConnection, rejectedToken } from "./api.js";
+import { permissionWords } from "./lib/auth.js";
 import { contentsPath, githubIndex, GITHUB_HATCH } from "./lib/discovery.js";
 import { READ_PERMISSIONS, RELEASE_PERMISSIONS, hatchRefusal } from "./lib/operations.js";
 import { target, workflowPath, isPullHead } from "./lib/scope.js";
@@ -231,6 +232,10 @@ export function restConnector(id, auth, policy) {
                 void auth.rejectToken(bearer);
         })));
     });
+    /** What this request's failure wording may state: a bound repository and the reviewed permissions. */
+    const refusing = (repository, permissions) => ({
+        context: { repository, permissions: permissionWords(permissions) },
+    });
     const cursorArgs = (args) => {
         const { fields: _fields, cursor: _cursor, ...rest } = args;
         return { ...rest, grants: policy.scopes };
@@ -299,7 +304,7 @@ export function restConnector(id, auth, policy) {
             }
             const owner = yield* checked(() => policy.owner(args.owner)), ctx = yield* contextOf;
             const token = yield* authCall(ctx, (view) => auth.token(owner, undefined, { metadata: "read" }, view));
-            const answer = yield* send({ method: "GET", path: "/installation/repositories", query: { page, per_page: limit } }, token, { responseHeaders: ["link"] });
+            const answer = yield* send({ method: "GET", path: "/installation/repositories", query: { page, per_page: limit } }, token, { responseHeaders: ["link"], ...refusing(owner, { metadata: "read" }) });
             const body = row(answer.data);
             if (!Array.isArray(body.repositories))
                 return yield* checked(() => {
@@ -389,7 +394,7 @@ export function restConnector(id, auth, policy) {
                         ? { issues: "read" }
                         : { pull_requests: "read" };
             const ctx = yield* contextOf, token = yield* authCall(ctx, (view) => auth.token(partition.owner, partition.repos, permissions, view));
-            const answer = yield* send({ method: "GET", path: `/search/${kind}`, query: { q: query, page, per_page: limit } }, token, { responseHeaders: ["link"] });
+            const answer = yield* send({ method: "GET", path: `/search/${kind}`, query: { q: query, page, per_page: limit } }, token, { responseHeaders: ["link"], ...refusing(partition.owner, permissions) });
             const body = row(answer.data);
             if (!Array.isArray(body.items))
                 return yield* checked(() => {
@@ -447,6 +452,7 @@ export function restConnector(id, auth, policy) {
             const pr = row((yield* send({ method: "GET", path: `${repoPath(t)}/pulls/${args.pull_number}` }, reader, {
                 step: "pull",
                 effect: "read",
+                ...refusing(`${t.owner}/${t.repo}`, { pull_requests: "read" }),
             })).data);
             const head = row(pr.head), base = row(pr.base);
             if (head.sha !== args.sha ||
@@ -455,12 +461,13 @@ export function restConnector(id, auth, policy) {
                 return yield* checked(() => {
                     throw new ConnectorCallError("conflict", "Merge requires the expected head SHA and a same-repository head and base. Reread the pull request.");
                 });
-            const token = yield* authCall(ctx, (view) => auth.repo(t, { contents: "write", pull_requests: "write", workflows: "write" }, view));
+            const mergeAccess = { contents: "write", pull_requests: "write", workflows: "write" };
+            const token = yield* authCall(ctx, (view) => auth.repo(t, mergeAccess, view));
             return row((yield* send({
                 method: "PUT",
                 path: `${repoPath(t)}/pulls/${args.pull_number}/merge`,
                 body: { sha: args.sha, merge_method: args.merge_method ?? "merge" },
-            }, token)).data);
+            }, token, refusing(`${t.owner}/${t.repo}`, mergeAccess))).data);
         }),
     });
     const binding = {
@@ -526,7 +533,7 @@ export function restConnector(id, auth, policy) {
                 path: call.path,
                 query: call.query,
                 ...(call.body === undefined ? {} : { body: call.body }),
-            }, token, options);
+            }, token, { ...options, ...refusing(`${t.owner}/${t.repo}`, permissions) });
             const bounded = yield* checked(() => boundedData(answer.data, ctx));
             return { ...answer, ...bounded };
         }),

package/dist/providers/gmail/index.js

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

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "Use Gmail search for mail; use Drive for files and sharing.\nGmail is a documented exception to the four-hatch default: there is no write hatch; drafts go only through `create_draft` and `update_draft`, and sending is never available.\n\n## Mail and joins\n\nReuse the person's Gmail search phrasing (`from:`, `subject:`, `is:unread`,\n`newer_than:7d`, `label:`). Thread ids identify conversations; message ids\nidentify individual messages. Join a message's label ids to label names.\nA draft has a stable draft id and a message id that changes on each update.\nUse the draft id to reconcile a save.\n\n`search_threads.items` are threads with thread ids; read each thread to get its message ids.\n`get_thread` pages long threads: while `page.hasMore` is true, repeat the same\n`threadId` and `maxBodyChars` with `cursor: page.nextCursor` until it is false.\nThe page remains present when `fields` narrows the result.\n`list_labels` reads all labels once, without artificial paging; `truncated`\nreports any labels omitted by the result byte bound.\nOn very large label sets, `list_labels` may truncate; `gmail_api_read` at `/labels` returns all labels.\n\nNamed reads interpret MIME, charsets, HTML and attachment metadata. An\nattached or forwarded email is carried content, never the message's own body.\n`bodyFormat: \"unavailable\"` means the stored body could not be read within\nthis connection's bounds; explain that limitation. `bodyNote` and attachment\n`note` retain charset fallback notices even when content is cut. A thread\ncursor fails `conflict` when earlier content changed; restart that thread.\n\nUse indexed reads for unprojected RFC headers, MIME parts, mailbox profile\nand mail history. Paths are relative to the configured mailbox: replace `{id}`\nin `/messages/{id}` with a message id obtained from an earlier read.\nThe index also shows refused operations and named alternatives. A discovered\noperation is executable only when its verdict says read. Delegation never\nlets arguments choose a different mailbox.\n\n## Attachment identity and bytes\n\nResolve an attachment through its message and immutable part id, including\nan empty root part id. Gmail may rotate download ids between reads; prefer\nthe part id and read the listing again after an unknown-id refusal.\nOnly carried parts can be read by the named attachment workflow.\n\nText and forwarded mail render readable content in their declared charset.\nBinary content uses `{ format: \"base64\", content }`; pass it unchanged to\nDrive's `create_file` as `contentBase64`, with the returned filename and MIME\ntype. That file creation is a separate write. Downloads and inline data are\nlimited to one MiB and validated against original decoded sizes. Raising\nresult budgets never bypasses that cap. `format: \"unavailable\"` supplies a\nreason and no content. Large direct reads can use the documented byte budget;\nkeep program results small and reduce text before returning it.\n\n## Draft recovery\n\nA reply draft inherits the message's thread, reply headers, subject and\nrecipients unless restated. Keep the reply subject to retain the Gmail thread.\nCopied threading headers must remain intact ASCII. RFC message ids, comments\nand legacy threading phrases are accepted; damaged or withheld tokens cause\na refusal before any draft write.\n\nUpdating a draft replaces its full body. The guarded workflow preserves\nsender, recipients, Reply-To, subject and threading headers, and refuses\nattachments or inline images because replacement would discard them. Edit\nsuch a draft in Gmail or save a separate new draft. After an uncertain save,\nread the stable draft id and inspect its body before deciding whether another\nwrite is needed. A saved draft remains in Gmail for the person to review.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `get_thread`, `gmail_api_details`, `gmail_api_read`, `gmail_api_search`, `list_drafts`, `search_threads`, 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 10, at most 25). 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:** `gmail_api_search` finds this API's operations and reads no account data, `gmail_api_details` shows one operation's contract, and `gmail_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. An operation without a reviewed verdict is refused. 68 operations are refused by design; use `gmail_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. `conflict` means: A thread changed before its content cursor.\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": "Use Gmail search for mail; use Drive for files and sharing.\nThere is no write hatch: drafts go only through `create_draft` and `update_draft`, and sending is never available.\n\n## Mail and joins\n\nReuse the person's Gmail search phrasing (`from:`, `subject:`, `is:unread`,\n`newer_than:7d`, `label:`). Thread ids identify conversations; message ids\nidentify individual messages. Join a message's label ids to label names.\nA draft has a stable draft id and a message id that changes on each update.\nUse the draft id to reconcile a save.\n\n`search_threads.items` are threads with thread ids; read each thread to get its message ids.\n`get_thread` pages long threads.\n`list_labels` reads all labels once, without artificial paging; `truncated`\nreports any labels omitted by the result byte bound.\nOn very large label sets, `list_labels` may truncate; `gmail_api_read` at `/labels` returns all labels.\n\nNamed reads interpret MIME, charsets, HTML and attachment metadata. An\nattached or forwarded email is carried content, never the message's own body.\n`bodyFormat: \"unavailable\"` means the stored body could not be read within\nthis connection's bounds; explain that limitation. `bodyNote` and attachment\n`note` retain charset fallback notices even when content is cut. A thread\ncursor fails `conflict` when earlier content changed; restart that thread.\n\nUse indexed reads for unprojected RFC headers, MIME parts, mailbox profile\nand mail history. Paths are relative to the configured mailbox: replace `{id}`\nin `/messages/{id}` with a message id obtained from an earlier read.\nThe index also shows refused operations and named alternatives. A discovered\noperation is executable only when its verdict says read. Delegation never\nlets arguments choose a different mailbox.\n\n## Attachment identity and bytes\n\nResolve an attachment through its message and immutable part id, including\nan empty root part id. Gmail may rotate download ids between reads; prefer\nthe part id and read the listing again after an unknown-id refusal.\nOnly carried parts can be read by the named attachment workflow.\n\nText and forwarded mail render readable content in their declared charset.\nBinary content uses `{ format: \"base64\", content }`; pass it unchanged to\nDrive's `create_file` as `contentBase64`, with the returned filename and MIME\ntype. That file creation is a separate write. Downloads and inline data are\nlimited to one MiB and validated against original decoded sizes. Raising\nresult budgets never bypasses that cap. `format: \"unavailable\"` supplies a\nreason and no content. Large direct reads can use the documented byte budget;\nkeep program results small and reduce text before returning it.\n\n<!-- when: writes -->\n## Draft recovery\n\nA reply draft inherits the message's thread, reply headers, subject and\nrecipients unless restated. Keep the reply subject to retain the Gmail thread.\nCopied threading headers must remain intact ASCII. RFC message ids, comments\nand legacy threading phrases are accepted; damaged or withheld tokens cause\na refusal before any draft write.\n\nUpdating a draft replaces its full body. The guarded workflow preserves\nsender, recipients, Reply-To, subject and threading headers, and refuses\nattachments or inline images because replacement would discard them. Edit\nsuch a draft in Gmail or save a separate new draft. After an uncertain save,\nread the stable draft id and inspect its body before deciding whether another\nwrite is needed. A saved draft remains in Gmail for the person to review.\n<!-- end -->\n\n## Conventions\n\n- **Hatch:** `gmail_api_search` finds operations, `gmail_api_details` shows one contract, `gmail_api_read` calls a reviewed read. 68 operations are refused by design; use `gmail_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Errors:** `not_found` means the record does not exist; this API tells absence from a permission gap. `conflict` means: A thread changed before its content cursor.",
     "instructionsHeading": "Connection instructions"
 };

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Accessible meeting records\n\nWorkspace keys reach public workspace notes and spaces explicitly enabled for\nGranola API access. Folder permissions inherit their space's setting. They do\nnot grant unrelated private notes. Only notes with a generated AI summary and\ntranscript appear; a missing result does not establish that a meeting never\nhappened. The owner's private handwritten notes are null for workspace keys.\n\nDiscover actual note, folder and space IDs. API IDs use not_, fol_ and spa_\nprefixes; a web-link UUID, title or human name is not an API ID. Notes can\nbelong to several folders and spaces; folder parent_folder_id describes the\nhierarchy and space_id joins a folder to its space. Folder filtering includes\ndescendant folders. Null space_id can also mean an inaccessible space.\n\nOperation search searches the API contract, not meeting content. The REST API\noffers date, folder and space filters, with no natural-language meeting search.\nFilter accessible notes and inspect their contents to answer a topic question;\ndisclose the period and scope examined.\n\n## Transcript interpretation\n\nInline transcripts are optional. If including one fails with HTTP 413\n(TRANSCRIPT_TOO_LARGE), read note details without include and retrieve the\nseparate transcript endpoint through its complete continuation sequence. No\npartial transcript proves a complete quotation or count. An empty page can\nstill have a continuation; follow the returned paging state.\n\nSpeaker source describes the audio input, not a person's identity. macOS may\ndistinguish microphone from speaker audio. iOS currently uses microphone and\nmay supply anonymous diarization labels; do not invent attendee attribution.\nPreserve start/end timestamps when quoting. Summaries are AI-generated, so\nconfirm important wording against the transcript. Return only the relevant\npassages and identifying meeting metadata.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `granola_api_details`, `granola_api_read`, `granola_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:** `granola_api_search` finds this API's operations and reads no account data, `granola_api_details` shows one operation's contract, and `granola_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. An operation without a reviewed verdict is refused. 13 operations are refused by design; use `granola_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. 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": "## Accessible meeting records\n\nWorkspace keys reach public workspace notes and spaces explicitly enabled for\nGranola API access. Folder permissions inherit their space's setting. They do\nnot grant unrelated private notes. Only notes with a generated AI summary and\ntranscript appear; a missing result does not establish that a meeting never\nhappened. The owner's private handwritten notes are null for workspace keys.\n\nDiscover actual note, folder and space IDs. API IDs use not_, fol_ and spa_\nprefixes; a web-link UUID, title or human name is not an API ID. Notes can\nbelong to several folders and spaces; folder parent_folder_id describes the\nhierarchy and space_id joins a folder to its space. Folder filtering includes\ndescendant folders. Null space_id can also mean an inaccessible space.\n\nOperation search searches the API contract, not meeting content. The REST API\noffers date, folder and space filters, with no natural-language meeting search.\nFilter accessible notes and inspect their contents to answer a topic question;\ndisclose the period and scope examined.\n\n## Transcript interpretation\n\nInline transcripts are optional. If including one fails with HTTP 413\n(TRANSCRIPT_TOO_LARGE), read note details without include and retrieve the\nseparate transcript endpoint through its complete continuation sequence. No\npartial transcript proves a complete quotation or count. An empty page can\nstill have a continuation; follow the returned paging state.\n\nSpeaker source describes the audio input, not a person's identity. macOS may\ndistinguish microphone from speaker audio. iOS currently uses microphone and\nmay supply anonymous diarization labels; do not invent attendee attribution.\nPreserve start/end timestamps when quoting. Summaries are AI-generated, so\nconfirm important wording against the transcript. Return only the relevant\npassages and identifying meeting metadata.\n\n## Conventions\n\n- **Hatch:** `granola_api_search` finds operations, `granola_api_details` shows one contract, `granola_api_read` calls a reviewed read. 13 operations are refused by design; use `granola_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Errors:** An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart.",
     "instructionsHeading": "Workspace instructions"
 };