@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.5

package/packages/agentsam-brand/README.md

@@ -1,21 +1,116 @@
 # @inneranimalmedia/agentsam-sdk-brand
 
-Deterministic **Brand Intelligence** for AgentSam.
+**Brand compiler** — not just an image optimizer CLI.
 
 ```text
-repository.snapshot  →  brand.scan  →  brand.resolve  →  brand.plan  →  (apply/verify)
+drop anything → ingest/classify → brand.pack.json (source of truth)
+                                      │
+                    ┌─────────────────┼─────────────────┐
+                    ▼                 ▼                 ▼
+              localhost studio      ZIP export     production publish
 ```
 
-- **Brand ≠ Theme.** Theme is a projection; Brand is authority.
-- **No LLM required** for scan/resolve/plan skeleton.
-- **Same file authority** as security/knowledge (Merkle + gitignore via snapshot).
-- States stay separated: `observed` → `inferred` → `declared` → `resolved`.
+## BrandPack v2
+
+`brand.pack.json` owns:
+
+| Graph node | Purpose |
+|---|---|
+| `assets[]` | Role-tagged masters + semantic derivatives |
+| `tokens` | color / type / space / radius / motion |
+| `rules` | logo clearspace, forbidden ops, template requirements |
+| `provenance` | source → transforms → sha256 |
+| `delivery` | Images / Stream / R2 policy (`role_canonical`) |
+
+ZIP, `studio.html`, CSS tokens, icons, and CF uploads are **compiled representations**.
+
+### CLI
+
+```bash
+# Ingest folder, previous build zip/tar/gz, or HTML/CSS for token extraction
+agentsam brand ingest ./exports --brand acme --template product-saas
+
+# Compile dist + studio + zip export
+agentsam brand build --from .agentsam/brand/packs/acme
+
+# Preview studio (prefers studio.html)
+agentsam brand preview --from .agentsam/brand/dist/acme
+
+agentsam brand templates
+agentsam brand roles
+agentsam brand presets
+```
+
+### Asset roles (examples)
+
+`logo.primary` · `favicon` · `icon.app` · `hero.landscape` · `social.og` · `product.raw` · `motion.hero` · `model.product` · `type.body` · `token.color`
+
+A 512px logo and a 512px app icon are **different assets**.
+
+### Semantic derivatives
+
+- **DERIVABLE** — system knows how to make it (often on-demand via Cloudflare Images)
+- **MATERIALIZED** — file included in this pack export
+
+Shared responsive ladder: `320…2560` — roles pick a subset. Logos get raster fallbacks (256/512/1024), not a giant ladder.
+
+### Format families
+
+Logo/vector, raster, photography, favicon, app-icon, social, video, motion-graphics, 3D, fonts (licensing gate), tokens, theme, docs, archives (zip/tar/gz containers).
+
+Fonts default to `licensing.redistributable: false` — never dumped into client ZIPs until confirmed.
+
+### Templates
+
+`web-app` · `mobile-app` · `marketing-site` · `product-saas` · `spatial-3d`
+
+### V1 still works
+
+```bash
+agentsam brand pack --brand acme --asset app-icon --source ./master.png --preset app-icon --out ./acme.zip
+agentsam brand promote --brand acme --asset logo --source - --preset logo
+```
+
+Delivery policy id: **`canonical_png`** / per-role **`role_canonical`**. Prefer high-quality masters; let Cloudflare Images negotiate AVIF/WebP.
+
+No product brand defaults (`agentsam` as brand id is rejected in the wizard).
+
+## Image / media processors (pluggable)
+
+**Do not** depend on abandoned `@squoosh/cli` (npm 0.7.3 — Node 12–16 only; crashes on Node 22+).
+
+Public UX:
+
+```bash
+agentsam brand optimize ./hero.png --role hero.landscape --target web
+agentsam brand optimize ./logo.png --role logo.primary --processor sharp
+agentsam brand processors   # sharp | squoosh (binary) | native | cloudflare
+```
+
+Internally:
+
+```text
+Asset Pipeline
+  ├── sharp          ← dependable Node path
+  ├── squoosh        ← maintained Homebrew/Scoop binary (optional)
+  ├── native         ← ImageMagick
+  ├── cloudflare     ← edge DERIVABLE (retain master)
+  ├── wasm / go      ← Studio preview / heavy queued jobs (scheduler hooks)
+```
+
+Role-aware policies choose formats (logo → lossless/SVG path; hero → AVIF+WebP; screenshots → sharper WebP). Semantic delivery names (`acme-showroom-hero-1280.avif`) are aliases — `asset.id` stays the machine identity. Cloudflare custom metadata / R2 `customMetadata` / BrandPack own SEO+provenance — not EXIF alone.
+
+## Website composition (sibling package)
+
+BrandPack owns **what the brand is**. Page experiences live in **`@inneranimalmedia/theme-scenes`**:
+
+- `SECTION_CONTENT` → scene kinds (hero, bridge, product.demo, gallery, …)
+- Route refs + asset roles (no hardcoded CDN / nav URLs in scenes)
+- Demo adapters (`agentsam-mini-composer`, `database-editor`) — real product surfaces, not fake Meaux cards
+- Themes: `foundation` → `inneranimal` → `agentsam` / `autodidact`
 
 ```bash
-agentsam brand scan --json
-agentsam brand resolve
-agentsam plan brand --goap
-agentsam brand --write   # writes .agentsam/brand/{evidence,resolved,contract}.json
+npm --prefix packages/theme-scenes test
 ```
 
-Progression (generic, not brand-only): `@inneranimalmedia/agentsam-sdk/progression`
+See `packages/theme-scenes/README.md`. Studio shell (Moon Glass → Brand Studio) sits above both packages in a later tranche.

package/packages/agentsam-brand/bin/agentsam-brand.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runBrandAssetCommand, runBrandPromoteWizard } from '../src/index.js';
+import { cancel, confirm, intro, isCancel, note, outro, select, text } from '@clack/prompts';
+
+const code = await runBrandAssetCommand(process.argv.slice(2), {
+  runWizard: runBrandPromoteWizard,
+  prompts: { intro, outro, cancel, isCancel, select, text, confirm, note },
+});
+process.exitCode = typeof code === 'number' ? code : 0;

package/packages/agentsam-brand/package.json

@@ -1,22 +1,54 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk-brand",
   "version": "0.1.0",
-  "private": true,
+  "description": "Deterministic Brand Intelligence + portable brand-asset promotion SDK for AgentSam (inspect, derive, plan, promote, publish, verify).",
   "type": "module",
-  "description": "Deterministic Brand Intelligence for AgentSam — scan/resolve/contract evidence on shared repository.snapshot authority",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22 <25"
+  },
+  "dependencies": {
+    "sharp": "^0.34.5"
+  },
   "main": "./src/index.js",
+  "bin": {
+    "agentsam-brand": "./bin/agentsam-brand.mjs"
+  },
   "exports": {
     ".": "./src/index.js",
     "./scan": "./src/scan.js",
     "./resolve": "./src/resolve.js",
     "./contract": "./src/contract.js",
     "./plan": "./src/plan.js",
-    "./goap-actions": "./src/goap-actions.js"
+    "./goap-actions": "./src/goap-actions.js",
+    "./assets": "./src/index.js",
+    "./presets": "./src/presets/index.js",
+    "./cli": "./src/cli/controller.js",
+    "./package.json": "./package.json"
   },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "pack:dry": "npm pack --dry-run"
   },
-  "engines": {
-    "node": ">=22 <25"
-  }
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SamPrimeaux/agentsam-sdk.git",
+    "directory": "packages/agentsam-brand"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "keywords": [
+    "agentsam",
+    "brand",
+    "assets",
+    "promotion",
+    "r2",
+    "images"
+  ]
 }

package/packages/agentsam-brand/src/adapters/cloudflare-images.js

@@ -0,0 +1,453 @@
+/**
+ * Cloudflare Images delivery adapter.
+ *
+ * Prefer shared transport `@inneranimalmedia/agentsam-cloudflare-images` for
+ * credentials, delivery URLs, and HTTP. This Brand adapter retains BrandPack
+ * publish policy (canonical PNG) and will thin-wrap the shared package next.
+ *
+ * HARD RULE: An asset is "on Cloudflare Images" ONLY when POST
+ * /accounts/{account_id}/images/v1 returns success + non-empty result.id.
+ *
+ * Account-level identity (never infer from R2):
+ *   CLOUDFLARE_ACCOUNT_ID            — management/API identity (non-secret)
+ *   CLOUDFLARE_IMAGES_ACCOUNT_HASH   — delivery namespace (non-secret)
+ *   CLOUDFLARE_IMAGES_API_TOKEN      — secret Bearer credential (canonical)
+ *   CLOUDFLARE_API_TOKEN             — broader compatibility fallback
+ *
+ * R2 keys, WEBSITE_ASSETS bindings, and D1 rows are never evidence of Images.
+ */
+
+/** Cloudflare-hosted Images accepts these inputs (plan-dependent for some). */
+export const CLOUDFLARE_IMAGES_PLATFORM_INPUT_TYPES = Object.freeze([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/svg+xml',
+  'image/heic',
+  'image/avif',
+]);
+
+/**
+ * Canonical PNG publishing policy (not a Cloudflare limitation):
+ * prefer a canonical PNG as the Images delivery source so CF can negotiate
+ * WebP/AVIF output. Explicit WebP/AVIF/SVG archives stay in storage (R2).
+ */
+export const CANONICAL_PNG_DELIVERY_POLICY_TYPES = Object.freeze(['image/png']);
+
+/** @deprecated Use CANONICAL_PNG_DELIVERY_POLICY_TYPES */
+export const AGENTSAM_IMAGES_DELIVERY_POLICY_TYPES = CANONICAL_PNG_DELIVERY_POLICY_TYPES;
+
+export function resolveCloudflareImagesCredentials(env = process.env) {
+  const accountId = String(env.CLOUDFLARE_ACCOUNT_ID || '').trim();
+  const accountHash = String(env.CLOUDFLARE_IMAGES_ACCOUNT_HASH || '').trim();
+  // Canonical least-privilege token first; broader session token as fallback.
+  // CLOUDFLARE_IMAGES_TOKEN retained as deprecated alias only.
+  const tokenSource = env.CLOUDFLARE_IMAGES_API_TOKEN
+    ? 'CLOUDFLARE_IMAGES_API_TOKEN'
+    : env.CLOUDFLARE_API_TOKEN
+      ? 'CLOUDFLARE_API_TOKEN'
+      : env.CLOUDFLARE_IMAGES_TOKEN
+        ? 'CLOUDFLARE_IMAGES_TOKEN'
+        : null;
+  const apiToken = tokenSource ? String(env[tokenSource] || '').trim() : '';
+  return {
+    accountId,
+    accountHash,
+    apiToken,
+    tokenEnv: tokenSource,
+    // Opaque credential — never validate by shape/prefix (cfat_ or otherwise)
+    tokenConfigured: Boolean(apiToken),
+  };
+}
+
+/** Public delivery base — derived from account hash, not independently configured. */
+export function cloudflareImagesDeliveryBase(accountHash) {
+  const hash = String(accountHash || '').trim();
+  if (!hash) return null;
+  return `https://imagedelivery.net/${hash}`;
+}
+
+/**
+ * Construct a delivery URL only from verified Images identity.
+ * Prefer Cloudflare-returned variants[] over reconstruction when available.
+ */
+export function cloudflareImageUrl({ accountHash, imageId, variant = 'public' } = {}) {
+  const hash = String(accountHash || '').trim();
+  const id = String(imageId || '').trim();
+  const v = String(variant || 'public').trim() || 'public';
+  if (!hash || !id) return null;
+  return `https://imagedelivery.net/${hash}/${id}/${v}`;
+}
+
+export function resolveCloudflareImagesConfig(env = process.env) {
+  const creds = resolveCloudflareImagesCredentials(env);
+  const deliveryBase = cloudflareImagesDeliveryBase(creds.accountHash);
+  return {
+    provider: 'cloudflare-images',
+    accountId: creds.accountId || null,
+    accountHash: creds.accountHash || null,
+    deliveryBase,
+    apiTokenConfigured: creds.tokenConfigured,
+    tokenEnv: creds.tokenEnv,
+    authMode: 'bearer_api_token',
+    requiredPermission: 'Account → Images → Write',
+    apiUploadPath: '/accounts/{account_id}/images/v1',
+  };
+}
+
+export class CloudflareImagesDeliveryAdapter {
+  constructor({
+    accountId,
+    accountHash,
+    apiToken,
+    env = process.env,
+    /**
+     * Default: canonical PNG-only delivery source.
+     * Pass CLOUDFLARE_IMAGES_PLATFORM_INPUT_TYPES to allow full CF input set.
+     */
+    acceptedContentTypes = [...CANONICAL_PNG_DELIVERY_POLICY_TYPES],
+    fetchImpl = globalThis.fetch,
+  } = {}) {
+    const resolved = resolveCloudflareImagesCredentials(env);
+    this.provider = 'cloudflare-images';
+    this.accountId = String(accountId ?? resolved.accountId ?? '').trim();
+    this.accountHash = String(accountHash ?? resolved.accountHash ?? '').trim();
+    this.apiToken = String(apiToken ?? resolved.apiToken ?? '').trim();
+    this.tokenEnv = apiToken
+      ? 'constructor'
+      : resolved.tokenEnv;
+    this.acceptedContentTypes = new Set(acceptedContentTypes);
+    this.policy = 'canonical_png';
+    this.fetchImpl = fetchImpl;
+  }
+
+  get deliveryBase() {
+    return cloudflareImagesDeliveryBase(this.accountHash);
+  }
+
+  authHeaders() {
+    return { Authorization: `Bearer ${this.apiToken}` };
+  }
+
+  /**
+   * Capability snapshot. `authorized` stays false until verifyConnection() succeeds.
+   */
+  async capabilities() {
+    const configured = Boolean(this.accountId && this.apiToken);
+    return {
+      provider: this.provider,
+      available: true,
+      configured,
+      authorized: false,
+      account_resolved: Boolean(this.accountId),
+      account_hash_resolved: Boolean(this.accountHash),
+      delivery_base: this.deliveryBase,
+      token_env: this.tokenEnv,
+      auth_mode: 'bearer_api_token',
+      required_permission: 'Account → Images → Write',
+      api_path: '/accounts/{account_id}/images/v1',
+      // Policy vs platform — do not conflate
+      delivery_policy_types: [...CANONICAL_PNG_DELIVERY_POLICY_TYPES],
+      /** @deprecated alias */
+      agentsam_delivery_policy_types: [...CANONICAL_PNG_DELIVERY_POLICY_TYPES],
+      cloudflare_platform_input_types: [...CLOUDFLARE_IMAGES_PLATFORM_INPUT_TYPES],
+      accepted_content_types: [...this.acceptedContentTypes],
+      policy: this.policy,
+    };
+  }
+
+  /**
+   * Live verify against Cloudflare Images API (stats).
+   * Env presence alone is never proof of authorization.
+   */
+  async verifyConnection() {
+    const config = {
+      account_id: this.accountId || null,
+      account_hash: this.accountHash || null,
+      delivery_base: this.deliveryBase,
+      token_env: this.tokenEnv,
+      auth_mode: 'bearer_api_token',
+      required_permission: 'Account → Images → Write',
+    };
+
+    if (!this.accountId || !this.apiToken) {
+      return {
+        ok: false,
+        provider: this.provider,
+        configured: false,
+        authorized: false,
+        reason: 'not_configured',
+        error: 'cloudflare_images_credentials_required',
+        hint: 'Set CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_IMAGES_API_TOKEN (Images Write)',
+        config,
+      };
+    }
+
+    const url = `https://api.cloudflare.com/client/v4/accounts/${this.accountId}/images/v1/stats`;
+    let res;
+    let body;
+    try {
+      res = await this.fetchImpl(url, {
+        method: 'GET',
+        headers: this.authHeaders(),
+      });
+      body = await res.json().catch(() => ({}));
+    } catch (err) {
+      return {
+        ok: false,
+        provider: this.provider,
+        configured: true,
+        authorized: false,
+        reason: 'network_error',
+        error: String(err?.message || err),
+        config,
+      };
+    }
+
+    const authorized = Boolean(res.ok && body?.success !== false);
+    return {
+      ok: authorized,
+      provider: this.provider,
+      configured: true,
+      authorized,
+      reason: authorized ? 'verified' : 'api_unauthorized',
+      error: authorized
+        ? null
+        : (body?.errors?.[0]?.message || `cf_images_verify_failed:${res.status}`),
+      http_status: res.status,
+      stats: authorized ? (body?.result || null) : null,
+      config: {
+        ...config,
+        // Mirror Local Studio / dashboard vocabulary
+        authentication: 'API token',
+        permission: authorized ? 'Images Write ✓' : 'Images Write unverified',
+      },
+    };
+  }
+
+  async supports({ contentType } = {}) {
+    const mime = String(contentType || '').toLowerCase();
+    return this.acceptedContentTypes.has(mime);
+  }
+
+  /**
+   * @returns {Promise<{
+   *   ok: boolean,
+   *   provider: 'cloudflare-images',
+   *   status: 'planned'|'published'|'failed'|'skipped',
+   *   provider_receipt?: object,
+   *   error?: string,
+   * }>}
+   */
+  async upload({
+    filePath,
+    fileName,
+    contentType = 'image/png',
+    metadata = {},
+    dryRun = false,
+    sourceSha256 = null,
+    sourceStorage = null,
+  } = {}) {
+    const mime = String(contentType || metadata.contentType || 'image/png').toLowerCase();
+    if (!(await this.supports({ contentType: mime }))) {
+      return {
+        ok: true,
+        provider: this.provider,
+        status: 'skipped',
+        reason: 'canonical_png_delivery_policy',
+        content_type: mime,
+        note: 'Canonical PNG policy: prefer PNG as Images delivery source; other formats remain storage-only. Cloudflare itself accepts broader inputs.',
+      };
+    }
+
+    if (dryRun) {
+      return {
+        ok: true,
+        provider: this.provider,
+        status: 'planned',
+        dry_run: true,
+        provider_receipt: null,
+        account_id: this.accountId || null,
+        account_hash: this.accountHash || null,
+        source: sourceStorage || null,
+      };
+    }
+
+    if (!this.accountId || !this.apiToken) {
+      return {
+        ok: false,
+        provider: this.provider,
+        status: 'failed',
+        error: 'cloudflare_images_credentials_required',
+        reason: 'not_configured',
+      };
+    }
+
+    const fs = await import('node:fs');
+    const form = new FormData();
+    const buf = fs.readFileSync(filePath);
+    form.append('file', new Blob([buf], { type: mime }), fileName || 'image.png');
+    const metaPayload = {
+      ...metadata,
+      ...(sourceSha256 ? { source_sha256: String(sourceSha256).replace(/^sha256:/, '') } : {}),
+    };
+    if (Object.keys(metaPayload).length) {
+      form.append('metadata', JSON.stringify(metaPayload));
+    }
+
+    const url = `https://api.cloudflare.com/client/v4/accounts/${this.accountId}/images/v1`;
+    let res;
+    let body;
+    try {
+      res = await this.fetchImpl(url, {
+        method: 'POST',
+        headers: this.authHeaders(),
+        body: form,
+      });
+      body = await res.json().catch(() => ({}));
+    } catch (err) {
+      return {
+        ok: false,
+        provider: this.provider,
+        status: 'failed',
+        error: String(err?.message || err),
+        reason: 'network_error',
+      };
+    }
+
+    const imageId = body?.result?.id ? String(body.result.id).trim() : '';
+    const errCode = body?.errors?.[0]?.code;
+    const errMsg = body?.errors?.[0]?.message || '';
+    // Idempotent: CF Images 5409 Resource already exists — treat as skip, not fatal
+    if (errCode === 5409 || /already exists/i.test(errMsg)) {
+      const existingId = String(metadata?.id || metadata?.image_id || fileName || '').trim();
+      return {
+        ok: true,
+        provider: this.provider,
+        status: 'exists',
+        reason: 'resource_already_exists',
+        http_status: res.status,
+        error_code: 5409,
+        provider_receipt: existingId
+          ? {
+            account_id: this.accountId,
+            account_hash: this.accountHash || null,
+            delivery_base: this.deliveryBase,
+            image_id: existingId,
+            provider_asset_id: existingId,
+            variants: [],
+            note: 'Image id already present in Cloudflare Images; upload skipped',
+          }
+          : null,
+        note: 'Cloudflare Images id already exists (5409). Pass --force with a new --version or delete the remote id.',
+      };
+    }
+    if (!res.ok || body?.success === false || !imageId) {
+      return {
+        ok: false,
+        provider: this.provider,
+        status: 'failed',
+        error:
+          errMsg
+          || (!imageId && res.ok ? 'cloudflare_images_missing_result_id' : `cf_images_upload_failed:${res.status}`),
+        reason: !imageId && res.ok ? 'missing_result_id' : 'api_error',
+        http_status: res.status,
+        error_code: errCode ?? null,
+      };
+    }
+
+    const variants = Array.isArray(body.result?.variants) ? body.result.variants : [];
+    return {
+      ok: true,
+      provider: this.provider,
+      status: 'published',
+      provider_receipt: {
+        // Account-level + image-level identity — never from R2
+        account_id: this.accountId,
+        account_hash: this.accountHash || null,
+        delivery_base: this.deliveryBase,
+        image_id: imageId,
+        provider_asset_id: imageId,
+        filename: body.result?.filename || fileName || null,
+        // Receipt truth from Cloudflare — prefer over reconstructed URLs
+        variants,
+        uploaded_at: body.result?.uploaded || null,
+        requireSignedURLs: body.result?.requireSignedURLs ?? null,
+        source_sha256: sourceSha256 || null,
+        // Provenance only — NEVER evidence that Images ≡ R2
+        source: sourceStorage
+          ? {
+            storage_provider: sourceStorage.provider || null,
+            bucket: sourceStorage.bucket || null,
+            key: sourceStorage.key || null,
+          }
+          : null,
+      },
+    };
+  }
+
+  /** Fetch one image by id — used by integration verify. */
+  async get(imageId) {
+    if (!this.accountId || !this.apiToken || !imageId) {
+      return { ok: false, error: 'not_configured_or_missing_id' };
+    }
+    const url = `https://api.cloudflare.com/client/v4/accounts/${this.accountId}/images/v1/${encodeURIComponent(imageId)}`;
+    const res = await this.fetchImpl(url, {
+      headers: this.authHeaders(),
+    });
+    const body = await res.json().catch(() => ({}));
+    const id = body?.result?.id ? String(body.result.id) : '';
+    return {
+      ok: Boolean(res.ok && body?.success && id),
+      provider: this.provider,
+      provider_receipt: id
+        ? {
+          account_id: this.accountId,
+          account_hash: this.accountHash || null,
+          delivery_base: this.deliveryBase,
+          image_id: id,
+          provider_asset_id: id,
+          variants: body.result?.variants || [],
+          filename: body.result?.filename || null,
+          uploaded_at: body.result?.uploaded || null,
+        }
+        : null,
+      http_status: res.status,
+    };
+  }
+
+  async delete(imageId) {
+    if (!this.accountId || !this.apiToken || !imageId) {
+      return { ok: false, error: 'not_configured_or_missing_id' };
+    }
+    const url = `https://api.cloudflare.com/client/v4/accounts/${this.accountId}/images/v1/${encodeURIComponent(imageId)}`;
+    const res = await this.fetchImpl(url, {
+      method: 'DELETE',
+      headers: this.authHeaders(),
+    });
+    const body = await res.json().catch(() => ({}));
+    return { ok: Boolean(res.ok && body?.success !== false), http_status: res.status };
+  }
+}
+
+/** True only when a real Images publish receipt exists. */
+export function isCloudflareImagesPublished(delivery) {
+  if (!delivery || delivery.provider !== 'cloudflare-images') return false;
+  if (delivery.status !== 'published') return false;
+  const id = delivery.provider_receipt?.provider_asset_id
+    || delivery.provider_receipt?.image_id
+    || delivery.provider_asset_id;
+  return Boolean(id && String(id).trim());
+}
+
+/**
+ * Canonical PNG delivery-source policy.
+ * Not a Cloudflare API limitation — CF accepts broader inputs.
+ * policy: 'canonical_png' | 'agentsam' (alias) | 'platform'
+ */
+export function mayUploadToCloudflareImages(contentType, { policy = 'canonical_png' } = {}) {
+  const mime = String(contentType || '').toLowerCase();
+  if (policy === 'platform') return CLOUDFLARE_IMAGES_PLATFORM_INPUT_TYPES.includes(mime);
+  return CANONICAL_PNG_DELIVERY_POLICY_TYPES.includes(mime);
+}