pi-cloudflare 0.6.2 → 0.6.4

package/README.md

@@ -22,6 +22,11 @@ helper**, distributed both as a native Pi package and an
   | `cf_builds_*`   | Workers Builds insights                  |
   | `cf_obs_*`      | Workers logs/metrics/traces              |
 
+Large upstream text results (e.g. full Worker bundles) are truncated to
+32 KiB per text block with a recovery hint instead of landing verbatim in
+agent context. Override locally with `PI_CLOUDFLARE_MAX_TEXT_BYTES` when a
+task genuinely needs more.
+
 Requires Node 20.19+ (or 22.12+) and network access. Native Pi installation
 also requires Pi package support. No browser, wrangler CLI, or API token is
 needed to install; the docs tools work immediately after install.
@@ -86,6 +91,7 @@ In `~/.pi/agent/settings.json`:
   "pi-cloudflare": {
     "servers": { "builds": false }, // disable individual servers
     "connectTimeoutMs": 30000,
+    // Env override also available: PI_CLOUDFLARE_MAX_TEXT_BYTES (default 32768)
   },
 }
 ```

package/dist/proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAA;AAGxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,0DAA0D;IAC1D,UAAU,EAAE,OAAO,CAAA;IACnB,OAAO,EAAE,CACP,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,cAAc,CAAC,CAAA;CAC7B;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC;AAeD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,YAAY,EAAE,EACrB,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAChF,gBAAgB,EAAE,CAkBpB;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,KAAK,CAAC;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,YAAY,EAAE,CAAA;IACrB,QAAQ,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAA;CACvC,CAAC,GACD,gBAAgB,EAAE,CAIpB"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAA;AAGxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAGnD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,0DAA0D;IAC1D,UAAU,EAAE,OAAO,CAAA;IACnB,OAAO,EAAE,CACP,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,cAAc,CAAC,CAAA;CAC7B;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC;AAeD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,YAAY,EAAE,EACrB,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAChF,gBAAgB,EAAE,CAkBpB;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,KAAK,CAAC;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,YAAY,EAAE,CAAA;IACrB,QAAQ,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAA;CACvC,CAAC,GACD,gBAAgB,EAAE,CAIpB"}

package/dist/proxy.js

@@ -1,4 +1,5 @@
 import { Type } from 'typebox';
+import { capToolResultText } from './result-caps.js';
 function toToolContent(result) {
     if (typeof result !== 'object' || result === null) {
         return { content: [{ type: 'text', text: String(result) }] };
@@ -28,7 +29,7 @@ export function buildToolRegistrations(prefix, tools, callUpstream) {
             parameters: Type.Unsafe(tool.inputSchema),
             execute: async (_toolCallId, params) => {
                 const result = await callUpstream(tool.name, params ?? {});
-                return toToolContent(result);
+                return capToolResultText(name, toToolContent(result));
             },
         };
     });

package/dist/proxy.js.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAyB9B,SAAS,aAAa,CAAC,MAAe;IACpC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAClD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;IAC9D,CAAC;IACD,MAAM,MAAM,GAAG,MAAkD,CAAA;IACjE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAE,MAAM,CAAC,OAAqC,CAAC,CAAC,CAAC,EAAE,CAAA;IAClG,MAAM,MAAM,GACV,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAA+B,CAAA;IAC5F,OAAO,OAAO,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,MAAM,CAAC,OAAO;QAC1D,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE;QACpC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAc,EACd,KAAqB,EACrB,YAAiF;IAEjF,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,MAAM,IAAI,GAAG,GAAG,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACpC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE;YAC1C,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,WAAW,EAAE;YACrD,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAA;QAChD,OAAO;YACL,IAAI;YACJ,KAAK,EAAE,IAAI;YACX,WAAW;YACX,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC;YACzC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE;gBACrC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,IAAI,EAAE,CAAC,CAAA;gBAC1D,OAAO,aAAa,CAAC,MAAM,CAAC,CAAA;YAC9B,CAAC;SACF,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,qBAAqB,CACnC,WAIE;IAEF,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,EAAE,CACxC,sBAAsB,CAAC,UAAU,CAAC,MAAM,EAAE,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,CACjF,CAAA;AACH,CAAC"}
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAG9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAuBpD,SAAS,aAAa,CAAC,MAAe;IACpC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAClD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;IAC9D,CAAC;IACD,MAAM,MAAM,GAAG,MAAkD,CAAA;IACjE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAE,MAAM,CAAC,OAAqC,CAAC,CAAC,CAAC,EAAE,CAAA;IAClG,MAAM,MAAM,GACV,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAA+B,CAAA;IAC5F,OAAO,OAAO,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,MAAM,CAAC,OAAO;QAC1D,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE;QACpC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAc,EACd,KAAqB,EACrB,YAAiF;IAEjF,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,MAAM,IAAI,GAAG,GAAG,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACpC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE;YAC1C,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,WAAW,EAAE;YACrD,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAA;QAChD,OAAO;YACL,IAAI;YACJ,KAAK,EAAE,IAAI;YACX,WAAW;YACX,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC;YACzC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE;gBACrC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,IAAI,EAAE,CAAC,CAAA;gBAC1D,OAAO,iBAAiB,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;YACvD,CAAC;SACF,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,qBAAqB,CACnC,WAIE;IAEF,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,EAAE,CACxC,sBAAsB,CAAC,UAAU,CAAC,MAAM,EAAE,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,CACjF,CAAA;AACH,CAAC"}

package/dist/result-caps.d.ts

@@ -0,0 +1,23 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Guardrail against unbounded upstream MCP text results landing verbatim in
+ * agent context. Provenance: one `cf_bindings_workers_get_worker_code` call
+ * returned the entire deployed Worker bundle as multipart text (~6 MB), and
+ * the agent fetched it twice — 12 MB of session JSONL for a metadata
+ * question. Every proxied tool result passes through here.
+ *
+ * Text blocks larger than the cap are replaced with a bounded preview plus
+ * an exact recovery hint (which tool was called, total vs returned bytes).
+ * Errors and non-text content pass through untouched.
+ */
+export declare const DEFAULT_MAX_TEXT_BYTES = 32768;
+export declare const MAX_TEXT_BYTES_ENV = "PI_CLOUDFLARE_MAX_TEXT_BYTES";
+/**
+ * Cap every text block of a proxied `CallToolResult`. Returns the original
+ * object when nothing exceeds the cap so small results stay referentially
+ * identical.
+ */
+export declare function capToolResultText(toolName: string, result: CallToolResult, maxBytes?: number): CallToolResult;
+/** Resolve the effective per-text-block cap (exported for tests and docs). */
+export declare function maxTextBytes(): number;
+//# sourceMappingURL=result-caps.d.ts.map

package/dist/result-caps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-caps.d.ts","sourceRoot":"","sources":["../src/result-caps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAA;AAExE;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,sBAAsB,QAAS,CAAA;AAC5C,eAAO,MAAM,kBAAkB,iCAAiC,CAAA;AA4ChE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,EACtB,QAAQ,GAAE,MAA6B,GACtC,cAAc,CAchB;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,IAAI,MAAM,CAErC"}

package/dist/result-caps.js

@@ -0,0 +1,75 @@
+/**
+ * Guardrail against unbounded upstream MCP text results landing verbatim in
+ * agent context. Provenance: one `cf_bindings_workers_get_worker_code` call
+ * returned the entire deployed Worker bundle as multipart text (~6 MB), and
+ * the agent fetched it twice — 12 MB of session JSONL for a metadata
+ * question. Every proxied tool result passes through here.
+ *
+ * Text blocks larger than the cap are replaced with a bounded preview plus
+ * an exact recovery hint (which tool was called, total vs returned bytes).
+ * Errors and non-text content pass through untouched.
+ */
+export const DEFAULT_MAX_TEXT_BYTES = 32_768;
+export const MAX_TEXT_BYTES_ENV = 'PI_CLOUDFLARE_MAX_TEXT_BYTES';
+const TRUNCATION_SUFFIX_RESERVE = 1024;
+function configuredMaxBytes() {
+    const raw = process.env[MAX_TEXT_BYTES_ENV];
+    if (!raw)
+        return DEFAULT_MAX_TEXT_BYTES;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0)
+        return DEFAULT_MAX_TEXT_BYTES;
+    return parsed;
+}
+function byteLength(text) {
+    return Buffer.byteLength(text, 'utf8');
+}
+function truncateUtf8(text, maxBytes) {
+    if (byteLength(text) <= maxBytes)
+        return text;
+    const buffer = Buffer.from(text, 'utf8').subarray(0, maxBytes);
+    // Avoid emitting a half-decoded trailing character.
+    return buffer.toString('utf8').replace(/\uFFFD+$/, '');
+}
+function truncationNotice(toolName, totalBytes, returnedBytes) {
+    return (`\n\n[pi-cloudflare] TRUNCATED: '${toolName}' returned ${totalBytes} bytes of text; ` +
+        `showing the first ${returnedBytes} bytes to protect agent context. ` +
+        `Re-run with a narrower query, a specific module/path argument, or pagination ` +
+        `instead of fetching the full payload again. ` +
+        `Override locally with ${MAX_TEXT_BYTES_ENV} if you genuinely need more.`);
+}
+function isTextBlock(block) {
+    return (!!block &&
+        typeof block === 'object' &&
+        block.type === 'text' &&
+        typeof block.text === 'string');
+}
+/**
+ * Cap every text block of a proxied `CallToolResult`. Returns the original
+ * object when nothing exceeds the cap so small results stay referentially
+ * identical.
+ */
+export function capToolResultText(toolName, result, maxBytes = configuredMaxBytes()) {
+    if (!result || !Array.isArray(result.content))
+        return result;
+    let truncated = false;
+    const content = result.content.map((block) => {
+        if (!isTextBlock(block))
+            return block;
+        const total = byteLength(block.text);
+        if (total <= maxBytes)
+            return block;
+        truncated = true;
+        const notice = truncationNotice(toolName, total, maxBytes);
+        const previewBytes = Math.max(0, maxBytes - byteLength(notice) - TRUNCATION_SUFFIX_RESERVE);
+        return { ...block, text: `${truncateUtf8(block.text, previewBytes)}${notice}` };
+    });
+    if (!truncated)
+        return result;
+    return { ...result, content };
+}
+/** Resolve the effective per-text-block cap (exported for tests and docs). */
+export function maxTextBytes() {
+    return configuredMaxBytes();
+}
+//# sourceMappingURL=result-caps.js.map

package/dist/result-caps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-caps.js","sourceRoot":"","sources":["../src/result-caps.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cloudflare",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Cloudflare Agent Plugin and native Pi extension providing official skills and cf_-prefixed MCP tools.",
   "keywords": [
     "agent-plugin",
@@ -51,7 +51,7 @@
     "perf:check": "node scripts/performance-audit.mjs --check",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepublishOnly": "npm run build",
-    "test": "node --test test/config.test.mjs test/servers.test.mjs test/proxy.test.mjs test/oauth.test.mjs test/token-store.test.mjs test/auth-recovery.test.mjs test/api-token.test.mjs test/plugin.test.mjs",
+    "test": "node --test test/config.test.mjs test/servers.test.mjs test/proxy.test.mjs test/oauth.test.mjs test/token-store.test.mjs test/auth-recovery.test.mjs test/api-token.test.mjs test/result-caps.test.mjs test/plugin.test.mjs",
     "pretest": "npm run build"
   },
   "dependencies": {
@@ -62,10 +62,10 @@
     "@types/node": "^22.0.0",
     "oxfmt": "^0.66.0",
     "oxlint": "^1.81.0",
-    "typescript": "^5.9.0"
+    "typescript": "^6.0.3"
   },
   "engines": {
-    "node": "^20.19.0 || ^22.12.0 || >=23"
+    "node": ">=24"
   },
   "pi": {
     "extensions": [

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pi-cloudflare",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Cloudflare skills and cf_-prefixed MCP tools, with a native Pi adapter and an Agent Plugins 1.0 portable runtime.",
   "author": {
     "name": "0xPlayerOne",

package/skills/cloudflare-api-token/SKILL.md

@@ -57,7 +57,9 @@ Same-origin `/api/v4/*` in page context carries the session:
 ## After creation: validation matrix (live-proven 2026-09-06)
 
 - Run `CLOUDFLARE_API_TOKEN=<paste-once> node scripts/verify-api-token.mjs` (identity, token status, Workers scripts read).
-- Then one live read per relied-upon group, all passing on the reference token: `GET /user`, `GET /accounts`, Workers scripts list, KV namespaces list, R2 buckets list, D1 databases list, Hyperdrive configs list, zones list, zone routes list, account read, memberships list, audit-logs list (proves Logs Read).
-- Known non-gaps, do not chase: `GET /user/tokens/:id` returns `9109` by design (tokens cannot manage tokens); zone-analytics `10000` without the Zone Analytics group is correct least privilege (observability rollups go through the separate obs MCP, not this token); Workers Tail needs a websocket (group presence + dashboard UI is the check).
+- Then one live read per relied-upon group, all passing on the reference token: `GET /user`, `GET /accounts`, Workers scripts list, KV namespaces list, R2 buckets list, D1 databases list, Hyperdrive configs list, zones list, zone routes list, account read, memberships list, audit-logs list (proves Logs Read), `GET /accounts/{id}/workers/observability/usage` with millisecond-epoch `from`/`to` (proves Workers Observability Read — live-proven 2026-09-10 on both accounts).
+- Zone Cache Rules Edit (only when granted): `GET /zones/:id/rulesets/phases/http_request_cache_settings/entrypoint` — expect `200` with the entrypoint, or `10003` (no entrypoint yet) which also proves the group is present. Live-proven 2026-09-09: created zone rule `landing-marketplace-edge-300s` (`http.host eq "pinkbinder.shop" and starts_with(http.request.uri.path, "/api/marketplace")`, edge+browser TTL 300s override-origin) after adding this group.
+- Known non-gaps, do not chase: `GET /user/tokens/:id` returns `9109` by design (tokens cannot manage tokens); zone-analytics `10000` without the Zone Analytics group is correct least privilege (observability rollups go through the separate obs MCP, not this token); Workers Tail needs a websocket (group presence + dashboard UI is the check); Logpush jobs `401` (no Logpush group exposed to API tokens — dashboard only, verified 2026-09-10).
+- Workers Builds (live-proven 2026-09-07): `GET /accounts/{id}/builds/builds/{uuid}` plus `/logs` read; trigger PATCH and build-token DELETE verified with the Edit level.
 - Template drift is real: the dashboard template grows over time (Builds/Agents/Containers/Observability/Pages appeared after the doc was written). Enumerate required groups per task from `docs/api-token.md`; never assume the template equals the need.
 - A 403 naming a missing group later means extend-then-verify, not a new token: same flow, one more row.

package/skills/cloudflare-token-scopes/SKILL.md

@@ -26,6 +26,23 @@ Prefer updating in place: the secret survives, wiring stays intact, and the chan
 - Same-origin `/api/v4/*` in page context carries the session (persistent browser, headed for dashboard pages). `Content-Type: application/json` required.
 - Verify after: re-GET the token and diff policies, then exercise one live read per changed group. A 403 afterward means the group mapping was wrong, not the mechanism.
 
+## When you cannot self-serve: hand off with the exact spec
+
+PUT needs a token that can manage tokens (API tokens get `9109` by design),
+and the dashboard path needs a headed browser plus a human for Turnstile.
+When neither is available, do not guess — hand the human the exact row to
+add:
+
+- Derive the group from the failing call, not from memory: the tool plus
+  endpoint determines it (e.g. `/accounts/{id}/builds/*` → Workers Builds
+  Configuration).
+- Derive the level from the HTTP method: GET → Read, anything else → Edit.
+- Include the scope: account-scoped groups need every managed account
+  included under Account Resources.
+- Format it as dashboard rows so the human pastes without translating:
+  `Account | Workers Builds Configuration | Edit`, one line per row, exact
+  labels.
+
 ## When update is the wrong tool
 
 - Secret lost or leaked → cloudflare-token-roll (no public roll route; UI flow).