From 9262c5c89818d31097b1b68fcf74af967ab7c5e5 Mon Sep 17 00:00:00 2001
From: Tal Weiss <major.tal@gmail.com>
Date: Mon, 27 Apr 2026 20:37:37 +0200
Subject: [PATCH] feat(sdk,cli,mcp): agent-DX blob CDN diagnostics (v1.45)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Coordinated public-repo half of the v1.33 agent-DX blob CDN release. All additive — no existing API surface broken.

SDK (sdk/src/namespaces/blobs.{ts,types.ts}):

- Widen blobs.put return into AssetRef: keeps the snake_case fields for back-compat AND adds size, contentSha256, contentType, immutableUrl, etag, sri, contentDigest, cacheKind, cdn:{version,invalidationId,invalidationStatus,ready,hint}.

- buildAssetRef derives etag/sri/contentDigest locally from the SHA so the SDK surface is stable across gateway versions.

- New helpers: client.blobs.diagnoseUrl(projectId, url) and client.blobs.waitFresh(projectId, {url, sha256, timeoutMs?}). Signed slightly differently from the spec scenarios (added projectId first arg) for consistency with put/get/ls.

- 8 new tests in blobs.test.ts (22 total).

CLI (cli/lib/blob.mjs, cli/lib/cdn.mjs, cli/cli.mjs, openclaw/scripts/cdn.mjs):

- run402 blob diagnose <url> — exit 0 on SHA match, 1 otherwise (shell-loop friendly).

- run402 cdn wait-fresh <url> --sha <hex> [--timeout <secs>] — polls until fresh.

- Both --help docs include exit-code semantics and the vantage caveat.

MCP tools (src/tools/blob-{diagnose,wait-fresh}.ts, src/index.ts):

- diagnose_public_url + wait_for_cdn_freshness with explicit agent guidance ('mutable URLs only').

- wait_for_cdn_freshness returns isError=true on timeout so agents branch into the immutableUrl fallback.

Docs (SKILL.md, cli/llms-cli.txt):

- 'Prefer immutableUrl in generated HTML/CSS/JS' guidance with reasoning (read-after-write correctness, integrity via SRI).

- New tool sections for diagnose_public_url + wait_for_cdn_freshness.

Notes:

- sync.test.ts updated for the new SURFACE rows + cdn namespace; the llms.txt-alignment assertion fails locally until the private-repo PR merges (it reads ~/Developer/run402-private/site/llms.txt). CI in the public repo skips the suite when the path is absent.

- Version is already 1.45.0 (chore: bump in 143f408). After this PR merges, run npm publish in coordination with the v1.33 backend cutover.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 SKILL.md                          |  37 ++++-
 cli/cli.mjs                       |   8 +-
 cli/lib/blob.mjs                  |  65 +++++++-
 cli/lib/cdn.mjs                   | 130 ++++++++++++++++
 cli/llms-cli.txt                  |  19 ++-
 openclaw/scripts/cdn.mjs          |   1 +
 sdk/src/namespaces/blobs.test.ts  | 244 ++++++++++++++++++++++++++++++
 sdk/src/namespaces/blobs.ts       | 211 +++++++++++++++++++++++++-
 sdk/src/namespaces/blobs.types.ts | 143 ++++++++++++++++-
 src/index.ts                      |  16 ++
 src/tools/blob-diagnose.ts        |  49 ++++++
 src/tools/blob-wait-fresh.ts      |  61 ++++++++
 sync.test.ts                      |  10 +-
 13 files changed, 980 insertions(+), 14 deletions(-)
 create mode 100644 cli/lib/cdn.mjs
 create mode 100644 openclaw/scripts/cdn.mjs
 create mode 100644 src/tools/blob-diagnose.ts
 create mode 100644 src/tools/blob-wait-fresh.ts

diff --git a/SKILL.md b/SKILL.md
index ad9755c9..811bf6d3 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -109,7 +109,14 @@ Upload a blob (any size, up to 5 TiB) to project storage via direct-to-S3 presig
 - `immutable` (optional, default: `false`) — If true with `sha256`, also produces a content-addressed URL that gets `Cache-Control: immutable`.
 - `sha256` (optional) — Required when `immutable: true`. Client-asserted hash; gateway verifies if S3 returns one.
 
-**Returns:** `{ key, size_bytes, sha256, url, immutable_url? }`. `url` is the CDN URL (on `pr-<public_id>.run402.com`); `immutable_url` is the content-addressed variant when applicable.
+**Returns:** an `AssetRef`: `{ key, size_bytes, sha256, visibility, url, immutable_url, size, contentSha256, contentType, immutableUrl, etag, sri, contentDigest, cacheKind, cdn: { version, invalidationId, invalidationStatus, ready, hint } }`. The legacy snake_case fields (`size_bytes`, `sha256`, `immutable_url`) are kept for back-compat; the camelCase fields are the v1.45 agent-DX surface.
+
+**Prefer `immutableUrl` in generated HTML/CSS/JS code.** Reasoning:
+- Read-after-write correctness: the immutable URL is bound to the SHA at upload time and was never previously cached. The mutable `url` is "eventually fresh" — invalidation is asynchronous, so a `<script>` tag pointing at it may load the OLD version for seconds-to-minutes after a re-upload.
+- Built-in integrity: pair `immutableUrl` with `integrity={sri}` on `<script>` and `<link>` tags so browsers verify the hash before executing.
+- No follow-up calls needed: an agent emitting `<script src={immutableUrl} integrity={sri}>` doesn't need to call `wait_for_cdn_freshness` afterwards. Use the mutable `url` only when the URL must remain stable across re-uploads.
+
+If you must use the mutable `url` (e.g. you're updating an `<img>` referenced by an external system that won't accept a new URL), call `wait_for_cdn_freshness` before publishing the change. **Mutable URLs only**; never call wait_for_cdn_freshness on `immutableUrl`.
 
 Supersedes `upload_file` (deprecated).
 
@@ -157,6 +164,34 @@ Generate a time-boxed S3 presigned GET URL for a private blob. Use this to share
 
 **Returns:** `{ url, expires_at }`.
 
+### diagnose_public_url
+
+Returns the live CDN state for a public blob URL — expected vs observed SHA, CloudFront cache headers, recent invalidation status, vantage. Use this when a deployed asset shows the wrong version or you suspect cache staleness.
+
+**Parameters:**
+- `project_id` (required) — Project ID that owns the URL
+- `url` (required) — Full blob URL (e.g. `https://app.run402.com/_blob/avatar.png`)
+
+**Returns:** the diagnose envelope including `expectedSha256`, `observedSha256`, `cache.{xCache,ageSeconds,cacheKind}`, `invalidation.{id,status}`, `vantage: "gateway-us-east-1"`, `probeMethod: "GET_RANGE_0_0"`, `probeMayHaveWarmedCache: true`, and a human-readable `hint` with actionable next steps.
+
+**Vantage caveat:** The probe is single-region (us-east-1). Other CloudFront PoPs may serve different cached states. The `probeMayHaveWarmedCache: true` field warns that the probe itself populates the cache for that PoP, so subsequent reads from elsewhere may differ.
+
+**Errors:**
+- 403 — URL belongs to a different project than your apikey
+- 400 — URL is not on `*.run402.com` AND not on one of your active custom domains (SSRF guard)
+
+### wait_for_cdn_freshness
+
+Polls the CDN until a **mutable** blob URL serves the expected SHA-256, or the timeout elapses. **For mutable URLs only** — for immutable URLs (the `immutableUrl` field returned by `blob_put`), no waiting is needed; they're bound at upload time and never previously cached.
+
+**Parameters:**
+- `project_id` (required) — Project ID that owns the URL
+- `url` (required) — Mutable blob URL to poll
+- `sha256` (required) — Expected hex SHA-256
+- `timeout_ms` (optional, default 60_000, max 600_000) — Max wait in milliseconds
+
+**Returns:** `{ fresh, observedSha256, attempts, elapsedMs, vantage }`. The tool returns `isError=true` on timeout so an agent can branch into a fallback (typically: switch to the immutableUrl, which is always immediately correct).
+
 ### upload_file (deprecated)
 
 Legacy file upload. **Deprecated — sunset 2026-06-01.** Use `blob_put` instead.
diff --git a/cli/cli.mjs b/cli/cli.mjs
index 3160bfcc..8b68ed93 100755
--- a/cli/cli.mjs
+++ b/cli/cli.mjs
@@ -28,9 +28,10 @@ Commands:
   deploy      Deploy a full-stack app or static site (requires active tier)
   functions   Manage serverless functions (deploy, invoke, logs, list, delete)
   secrets     Manage project secrets (set, list, delete)
-  blob        Direct-to-S3 blob storage (put, get, ls, rm, sign) — up to 5 TiB
+  blob        Direct-to-S3 blob storage (put, get, ls, rm, sign, diagnose) — up to 5 TiB
   storage     Legacy file storage (deprecated — sunset 2026-06-01, use 'blob')
   sites       Deploy static sites
+  cdn         CloudFront CDN diagnostics (wait-fresh) for public blob URLs
   subdomains  Manage custom subdomains (claim, list, delete)
   domains     Manage custom domains (add, list, status, delete)
   apps        Browse and manage the app marketplace
@@ -129,6 +130,11 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "cdn": {
+    const { run } = await import("./lib/cdn.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "sites": {
     const { run } = await import("./lib/sites.mjs");
     await run(sub, rest);
diff --git a/cli/lib/blob.mjs b/cli/lib/blob.mjs
index 01826eb8..8ef74bc4 100644
--- a/cli/lib/blob.mjs
+++ b/cli/lib/blob.mjs
@@ -46,6 +46,7 @@ Usage:
   run402 blob ls [options]
   run402 blob rm <key> [options]
   run402 blob sign <key> [options]
+  run402 blob diagnose <url> [options]
 
 Options:
   --project <id>      Project ID (defaults to active project from 'run402 projects use')
@@ -150,6 +151,32 @@ Options:
 
 Examples:
   run402 blob sign reports/2025-q4.pdf --project abc123 --ttl 600
+`,
+  diagnose: `run402 blob diagnose — Inspect the live CDN state for a public blob URL
+
+Usage:
+  run402 blob diagnose <url> [options]
+
+Arguments:
+  <url>               Full blob URL (e.g. https://app.run402.com/_blob/avatar.png)
+
+Options:
+  --project <id>      Project ID (defaults to active project)
+
+Output:
+  - Prints the JSON envelope on stdout (parseable by agent shell loops).
+  - Vantage caveat ("# probed once from gateway-us-east-1; not a global view")
+    on stderr — visible to TTY operators, ignored by piped consumers.
+
+Exit codes:
+  0   observed SHA matches the gateway's expected SHA
+  1   observed SHA does not match (or probe returned no SHA)
+
+Agent loop pattern:
+  until run402 blob diagnose <url>; do sleep 1; done
+
+Examples:
+  run402 blob diagnose https://app.run402.com/_blob/avatar.png
 `,
 };
 
@@ -445,6 +472,33 @@ async function rm(projectId, argv) {
 // sign
 // ---------------------------------------------------------------------------
 
+async function diagnose(projectId, argv) {
+  const opts = parseArgs(argv);
+  opts.project = opts.project || projectId;
+  const resolvedId = resolveProjectId(opts.project);
+  if (opts.positional.length === 0) die("URL required");
+  const url = opts.positional[0];
+
+  try {
+    const env = await getSdk().blobs.diagnoseUrl(resolvedId, url);
+    // Always print the JSON envelope for agent consumption (parseable).
+    console.log(JSON.stringify(env, null, 2));
+    // Vantage caveat to stderr so a TTY operator sees it; agent shell loops
+    // that pipe stdout into another tool aren't affected.
+    process.stderr.write(
+      `\n# probed once from ${env.vantage}; not a global view\n`,
+    );
+    // Exit code: 0 if observed === expected, 1 otherwise. Lets agents
+    // shell-script `until run402 blob diagnose <url>; do sleep 1; done`.
+    if (env.observedSha256 && env.observedSha256 === env.expectedSha256) {
+      process.exit(0);
+    }
+    process.exit(1);
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
 async function sign(projectId, argv) {
   const opts = parseArgs(argv);
   opts.project = opts.project || projectId;
@@ -518,11 +572,12 @@ export async function run(sub, args) {
   }
   const defaultProject = process.env.RUN402_PROJECT ?? null;
   switch (sub) {
-    case "put":   await put(defaultProject, args); break;
-    case "get":   await get(defaultProject, args); break;
-    case "ls":    await ls(defaultProject, args); break;
-    case "rm":    await rm(defaultProject, args); break;
-    case "sign":  await sign(defaultProject, args); break;
+    case "put":      await put(defaultProject, args); break;
+    case "get":      await get(defaultProject, args); break;
+    case "ls":       await ls(defaultProject, args); break;
+    case "rm":       await rm(defaultProject, args); break;
+    case "sign":     await sign(defaultProject, args); break;
+    case "diagnose": await diagnose(defaultProject, args); break;
     default:
       console.error(`Unknown subcommand: ${sub}`);
       console.log(HELP);
diff --git a/cli/lib/cdn.mjs b/cli/lib/cdn.mjs
new file mode 100644
index 00000000..73c72190
--- /dev/null
+++ b/cli/lib/cdn.mjs
@@ -0,0 +1,130 @@
+/**
+ * run402 cdn — CloudFront CDN diagnostics for public blob URLs.
+ *
+ * Usage:
+ *   run402 cdn wait-fresh <url> --sha <sha256> [--timeout <seconds>] [--project <id>]
+ *
+ * Wraps the SDK's `client.blobs.waitFresh(...)`. Polls the gateway diagnose
+ * endpoint until the URL serves the expected SHA, then exits 0. On timeout,
+ * exits 1 (agent shell loops can chain a fallback action).
+ *
+ * **Mutable URLs only.** For immutable URLs (the `immutableUrl` field
+ * returned by `run402 blob put --immutable`), no waiting is needed — they
+ * are bound to a SHA at upload time and never previously cached.
+ */
+
+import { resolveProjectId } from "./config.mjs";
+import { getSdk } from "./sdk.mjs";
+import { reportSdkError } from "./sdk-errors.mjs";
+
+const HELP = `run402 cdn — CloudFront CDN diagnostics for public blob URLs
+
+Usage:
+  run402 cdn wait-fresh <url> --sha <sha256> [options]
+
+Subcommands:
+  wait-fresh    Poll the CDN until a mutable URL serves the expected SHA-256
+
+Examples:
+  run402 cdn wait-fresh https://app.run402.com/_blob/avatar.png --sha abc...
+
+For details: run402 cdn wait-fresh --help
+`;
+
+const SUB_HELP = {
+  "wait-fresh": `run402 cdn wait-fresh — Poll the CDN for an expected SHA on a mutable URL
+
+Usage:
+  run402 cdn wait-fresh <url> --sha <sha256> [options]
+
+Arguments:
+  <url>               Full mutable blob URL to poll (e.g.
+                      https://app.run402.com/_blob/avatar.png)
+
+Options:
+  --sha <hex>         Expected hex SHA-256. Required.
+  --timeout <secs>    Max wait in seconds. Default 60.
+  --project <id>      Project ID (defaults to active project)
+
+Output:
+  Prints a JSON result on stdout when polling ends:
+    { "fresh": true|false, "observedSha256": "...", "attempts": N,
+      "elapsedMs": ..., "vantage": "gateway-us-east-1" }
+
+Exit codes:
+  0   the URL served the expected SHA before the timeout
+  1   the URL did NOT match within the timeout (or the project resolution failed)
+
+Notes:
+  - For IMMUTABLE URLs (returned as 'immutableUrl' from 'run402 blob put
+    --immutable'), no waiting is needed. Use this command only for the
+    mutable 'url' field, after a re-upload to an existing public key.
+  - The probe is single-vantage (us-east-1). Other CloudFront PoPs may
+    serve different cached states until invalidation propagates.
+
+Examples:
+  run402 cdn wait-fresh https://app.run402.com/_blob/avatar.png --sha ba78...
+  run402 cdn wait-fresh https://app.run402.com/_blob/avatar.png --sha ba78... --timeout 120
+`,
+};
+
+function die(msg, code = 1) {
+  console.error(JSON.stringify({ status: "error", message: msg }));
+  process.exit(code);
+}
+
+function parseArgs(args) {
+  const opts = { positional: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--sha") opts.sha = args[++i];
+    else if (a === "--timeout") opts.timeout = Number(args[++i]);
+    else if (a === "--project") opts.project = args[++i];
+    else if (a.startsWith("--")) die(`Unknown option: ${a}`);
+    else opts.positional.push(a);
+  }
+  return opts;
+}
+
+async function waitFresh(projectId, argv) {
+  const opts = parseArgs(argv);
+  opts.project = opts.project || projectId;
+  const resolvedId = resolveProjectId(opts.project);
+  if (opts.positional.length === 0) die("URL required");
+  const url = opts.positional[0];
+  if (!opts.sha) die("--sha is required");
+
+  const timeoutMs = (opts.timeout ?? 60) * 1000;
+  try {
+    const result = await getSdk().blobs.waitFresh(resolvedId, {
+      url,
+      sha256: opts.sha.toLowerCase(),
+      timeoutMs,
+    });
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.fresh ? 0 : 1);
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === "--help" || sub === "-h") {
+    console.log(HELP);
+    process.exit(0);
+  }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
+    console.log(SUB_HELP[sub] || HELP);
+    process.exit(0);
+  }
+  const defaultProject = process.env.RUN402_PROJECT ?? null;
+  switch (sub) {
+    case "wait-fresh":
+      await waitFresh(defaultProject, args);
+      break;
+    default:
+      console.error(`Unknown subcommand: ${sub}`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
diff --git a/cli/llms-cli.txt b/cli/llms-cli.txt
index 17033f52..aac7f44f 100644
--- a/cli/llms-cli.txt
+++ b/cli/llms-cli.txt
@@ -393,6 +393,8 @@ Direct-to-S3 blob storage. Works for any size from 1 byte up to 5 TiB. No bucket
 - `run402 blob ls [--project <id>] [--prefix <p>] [--limit <n>]`
 - `run402 blob rm <key> [--project <id>]`
 - `run402 blob sign <key> [--project <id>] [--ttl <seconds>]`
+- `run402 blob diagnose <url> [--project <id>]` — inspect live CDN state for a public URL
+- `run402 cdn wait-fresh <url> --sha <hex> [--timeout <secs>] [--project <id>]` — poll a mutable URL until it serves the expected SHA-256
 
 Examples:
 
@@ -402,16 +404,27 @@ run402 blob put ./dist/**/*.png --project abc123 --key assets/
 run402 blob put huge.bin --project abc123 --immutable
 run402 blob get images/logo.png --output /tmp/logo.png --project abc123
 run402 blob ls --project abc123 --prefix images/
+run402 blob diagnose https://app.run402.com/_blob/avatar.png --project abc123
+run402 cdn wait-fresh https://app.run402.com/_blob/avatar.png --sha ba78... --timeout 120
 ```
 
-`put` response (public blobs) includes:
-- `url` — stable URL on the project's CDN subdomain: `https://pr-<public_id>.run402.com/_blob/<key>`, also `https://<claimed-subdomain>.run402.com/_blob/<key>` and any mapped custom domain. Cached at CloudFront edge.
-- `immutable_url` (only when `--immutable`) — content-hashed URL: `https://<host>/_blob/<key-without-ext>-<8hex>.<ext>`. Resolves to the same S3 object but safe to cache eternally (`Cache-Control: public, max-age=31536000, immutable`).
+`put` response (an `AssetRef`) includes both legacy snake_case and v1.45 camelCase fields:
+- `url` / (no camelCase alias) — stable mutable URL: `https://pr-<public_id>.run402.com/_blob/<key>`, also any claimed subdomain or mapped custom domain. Cached at CloudFront edge; invalidation is asynchronous on overwrite.
+- `immutable_url` / `immutableUrl` (only when `--immutable`) — content-hashed URL: `https://<host>/_blob/<key-without-ext>-<8hex>.<ext>`. Bound to a SHA at upload time; never previously cached. **Prefer this in generated HTML/CSS/JS code** — it doesn't need waiting and pairs with `sri` for browser SRI verification.
+- `etag` — strong `"sha256-<hex>"` ETag (when `--immutable`).
+- `sri` — `sha256-<base64>` for `<script integrity={sri}>` and `<link integrity={sri}>`.
+- `contentDigest` — RFC 9530 `sha-256=:<base64>:` for HTTP integrity.
+- `cacheKind` — `"immutable" | "mutable" | "private"`.
+- `cdn.{version,invalidationId,invalidationStatus,ready,hint}` — CloudFront invalidation envelope; `cdn.ready === true` for immutable uploads.
+
+**Agent guidance.** When emitting HTML/CSS/JS that links a just-uploaded asset, use `immutableUrl` + `integrity={sri}`. Read-after-write is correct and you don't need a follow-up `cdn wait-fresh` poll. Use the mutable `url` only when the URL must remain stable across re-uploads; in that case, `run402 cdn wait-fresh <url> --sha <new-sha>` blocks until the CDN serves the new SHA.
 
 Resume: state is persisted to `~/.run402/uploads/<upload_id>.json`. Ctrl-C mid-upload and re-run the same `blob put` command — it picks up where it left off. Pass `--no-resume` to start fresh.
 
 Private blobs (`--private`): no CDN URL returned; read via authenticated gateway path `GET /storage/v1/blob/<key>` with apikey, or via `run402 blob sign` for time-boxed external sharing.
 
+`diagnose` exit codes are shell-loop-friendly: `0` when the CDN serves the gateway's expected SHA, `1` otherwise. So `until run402 blob diagnose <url>; do sleep 1; done` blocks until the CDN catches up. Vantage: probes are single-region (us-east-1); the `# probed once from gateway-us-east-1; not a global view` line on stderr is the explicit caveat.
+
 #### Uploading from edge functions
 
 From within a deployed function, use the HTTP API directly:
diff --git a/openclaw/scripts/cdn.mjs b/openclaw/scripts/cdn.mjs
new file mode 100644
index 00000000..0f4b0431
--- /dev/null
+++ b/openclaw/scripts/cdn.mjs
@@ -0,0 +1 @@
+export { run } from "../../cli/lib/cdn.mjs";
diff --git a/sdk/src/namespaces/blobs.test.ts b/sdk/src/namespaces/blobs.test.ts
index ecf88a8f..1236e2f4 100644
--- a/sdk/src/namespaces/blobs.test.ts
+++ b/sdk/src/namespaces/blobs.test.ts
@@ -296,3 +296,247 @@ describe("blobs.sign", () => {
     assert.equal(result.expires_in, 3600);
   });
 });
+
+// ---------------------------------------------------------------------------
+// v1.45 — AssetRef widened return + diagnoseUrl + waitFresh
+// ---------------------------------------------------------------------------
+
+describe("blobs.put — AssetRef widening (v1.45)", () => {
+  it("populates camelCase aliases + integrity fields for immutable upload", async () => {
+    // sha256 of "abc"
+    const SHA = "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad";
+    const { fetch } = mockFetch((call) => {
+      if (call.url.endsWith("/storage/v1/uploads")) {
+        return json({
+          upload_id: "u_a",
+          mode: "single",
+          part_count: 1,
+          parts: [{ part_number: 1, url: "https://s3.test/u_a/p1", byte_start: 0, byte_end: 2 }],
+        });
+      }
+      if (call.url.startsWith("https://s3.test/")) {
+        return new Response("", { status: 200, headers: { etag: '"e"' } });
+      }
+      if (call.url.endsWith("/complete")) {
+        return json({
+          key: "x.txt",
+          size_bytes: 3,
+          sha256: SHA,
+          visibility: "public",
+          content_type: "text/plain",
+          immutable_suffix: SHA.slice(0, 8),
+          url: "https://app.run402.com/_blob/x.txt",
+          immutable_url: "https://app.run402.com/_blob/x-ba7816bf.txt",
+        });
+      }
+      throw new Error("unexpected: " + call.url);
+    });
+    const sdk = makeSdk(fetch);
+    const result = await sdk.blobs.put("prj_known", "x.txt", { content: "abc" }, { immutable: true });
+
+    // Legacy snake_case fields stay populated for back-compat.
+    assert.equal(result.size_bytes, 3);
+    assert.equal(result.sha256, SHA);
+    assert.equal(result.url, "https://app.run402.com/_blob/x.txt");
+    assert.equal(result.immutable_url, "https://app.run402.com/_blob/x-ba7816bf.txt");
+    // New camelCase aliases.
+    assert.equal(result.size, 3);
+    assert.equal(result.contentSha256, SHA);
+    assert.equal(result.immutableUrl, "https://app.run402.com/_blob/x-ba7816bf.txt");
+    assert.equal(result.contentType, "text/plain");
+    // Integrity fields derived from the SHA.
+    assert.equal(result.etag, `"sha256-${SHA}"`);
+    assert.match(result.sri ?? "", /^sha256-[A-Za-z0-9+/]+={0,2}$/);
+    assert.match(result.contentDigest ?? "", /^sha-256=:[A-Za-z0-9+/]+={0,2}:$/);
+    // Cache kind + cdn envelope.
+    assert.equal(result.cacheKind, "immutable");
+    assert.equal(result.cdn.version, "blob-gateway-v2");
+    assert.equal(result.cdn.ready, true);
+    assert.match(result.cdn.hint ?? "", /immutableUrl is ready immediately/);
+  });
+
+  it("leaves integrity fields null on non-immutable upload (sha256 not computed)", async () => {
+    const { fetch } = mockFetch((call) => {
+      if (call.url.endsWith("/storage/v1/uploads")) {
+        return json({
+          upload_id: "u_b",
+          mode: "single",
+          part_count: 1,
+          parts: [{ part_number: 1, url: "https://s3.test/u_b/p1", byte_start: 0, byte_end: 2 }],
+        });
+      }
+      if (call.url.startsWith("https://s3.test/")) {
+        return new Response("", { status: 200, headers: { etag: '"e"' } });
+      }
+      if (call.url.endsWith("/complete")) {
+        return json({
+          key: "y.txt",
+          size_bytes: 3,
+          sha256: null,
+          visibility: "public",
+          content_type: null,
+          immutable_suffix: null,
+          url: "https://app.run402.com/_blob/y.txt",
+          immutable_url: null,
+        });
+      }
+      throw new Error("unexpected: " + call.url);
+    });
+    const sdk = makeSdk(fetch);
+    const result = await sdk.blobs.put("prj_known", "y.txt", { content: "abc" });
+    assert.equal(result.contentSha256, null);
+    assert.equal(result.etag, null);
+    assert.equal(result.sri, null);
+    assert.equal(result.contentDigest, null);
+    assert.equal(result.cacheKind, "mutable");
+    assert.equal(result.cdn.ready, false);
+    assert.match(result.cdn.hint ?? "", /Prefer immutableUrl|wait_for_cdn_freshness/);
+  });
+
+  it("propagates a gateway-emitted cdn envelope verbatim when present", async () => {
+    const { fetch } = mockFetch((call) => {
+      if (call.url.endsWith("/storage/v1/uploads")) {
+        return json({
+          upload_id: "u_c",
+          mode: "single",
+          part_count: 1,
+          parts: [{ part_number: 1, url: "https://s3.test/u_c/p1", byte_start: 0, byte_end: 2 }],
+        });
+      }
+      if (call.url.startsWith("https://s3.test/")) {
+        return new Response("", { status: 200, headers: { etag: '"e"' } });
+      }
+      if (call.url.endsWith("/complete")) {
+        return json({
+          key: "z.txt",
+          size_bytes: 3,
+          sha256: null,
+          visibility: "public",
+          content_type: "text/plain",
+          immutable_suffix: null,
+          url: "https://app.run402.com/_blob/z.txt",
+          immutable_url: null,
+          cdn: {
+            version: "blob-gateway-v2",
+            invalidationId: "I-1234",
+            invalidationStatus: "InProgress",
+            hint: "Invalidation is asynchronous; use wait_for_cdn_freshness.",
+          },
+        });
+      }
+      throw new Error("unexpected: " + call.url);
+    });
+    const sdk = makeSdk(fetch);
+    const result = await sdk.blobs.put("prj_known", "z.txt", { content: "abc" });
+    assert.equal(result.cdn.invalidationId, "I-1234");
+    assert.equal(result.cdn.invalidationStatus, "InProgress");
+    assert.match(result.cdn.hint ?? "", /asynchronous/);
+  });
+});
+
+describe("blobs.diagnoseUrl", () => {
+  it("GETs /storage/v1/blobs/diagnose with the URL query-encoded", async () => {
+    const { fetch, calls } = mockFetch(() =>
+      json({
+        projectId: "prj_known",
+        key: "avatar.png",
+        expectedSha256: "abc",
+        observedSha256: "abc",
+        vantage: "gateway-us-east-1",
+        probeMethod: "GET_RANGE_0_0",
+        acceptEncoding: "identity",
+        observedAt: "2026-04-27T00:00:00Z",
+        probeMayHaveWarmedCache: true,
+        canonicalUrl: "https://app.run402.com/_blob/avatar.png",
+        pathKind: "blob-mutable",
+        cache: { xCache: "Hit from cloudfront", ageSeconds: 5, cacheKind: "mutable" },
+        invalidation: { id: null, status: null },
+        hint: "CDN is serving the current SHA.",
+      }),
+    );
+    const sdk = makeSdk(fetch);
+    const env = await sdk.blobs.diagnoseUrl(
+      "prj_known",
+      "https://app.run402.com/_blob/avatar.png",
+    );
+    assert.equal(env.observedSha256, "abc");
+    assert.equal(env.vantage, "gateway-us-east-1");
+    assert.equal(env.probeMethod, "GET_RANGE_0_0");
+    assert.equal(env.probeMayHaveWarmedCache, true);
+    assert.match(
+      calls[0]!.url,
+      /\/storage\/v1\/blobs\/diagnose\?url=https%3A%2F%2Fapp\.run402\.com%2F_blob%2Favatar\.png/,
+    );
+  });
+
+  it("throws ProjectNotFound for unknown project", async () => {
+    const { fetch } = mockFetch(() => json({}));
+    const sdk = makeSdk(fetch);
+    await assert.rejects(
+      sdk.blobs.diagnoseUrl("prj_missing", "https://app.run402.com/_blob/x"),
+      ProjectNotFound,
+    );
+  });
+});
+
+describe("blobs.waitFresh", () => {
+  function envelope(observed: string | null) {
+    return {
+      projectId: "prj_known",
+      key: "k",
+      expectedSha256: "ff",
+      observedSha256: observed,
+      vantage: "gateway-us-east-1" as const,
+      probeMethod: "GET_RANGE_0_0" as const,
+      acceptEncoding: "identity",
+      observedAt: "2026-04-27T00:00:00Z",
+      probeMayHaveWarmedCache: true as const,
+      canonicalUrl: "https://app.run402.com/_blob/k",
+      pathKind: "blob-mutable" as const,
+      cache: { xCache: null, ageSeconds: null, cacheKind: "mutable" as const },
+      invalidation: { id: null, status: null },
+      hint: "",
+    };
+  }
+
+  it("returns fresh: true once observedSha256 matches expected", async () => {
+    let calls = 0;
+    const { fetch } = mockFetch(() => {
+      calls++;
+      // First two calls return the old SHA, third returns the new one.
+      return json(envelope(calls < 3 ? "00".repeat(32) : "ff"));
+    });
+    const sdk = makeSdk(fetch);
+    const result = await sdk.blobs.waitFresh("prj_known", {
+      url: "https://app.run402.com/_blob/k",
+      sha256: "ff",
+      timeoutMs: 5_000,
+    });
+    assert.equal(result.fresh, true);
+    assert.equal(result.observedSha256, "ff");
+    assert.ok(result.attempts >= 3);
+    assert.equal(result.vantage, "gateway-us-east-1");
+  });
+
+  it("returns fresh: false on timeout (no exception thrown)", async () => {
+    const { fetch } = mockFetch(() => json(envelope("00".repeat(32))));
+    const sdk = makeSdk(fetch);
+    const result = await sdk.blobs.waitFresh("prj_known", {
+      url: "https://app.run402.com/_blob/k",
+      sha256: "ff",
+      timeoutMs: 250,
+    });
+    assert.equal(result.fresh, false);
+    assert.ok(result.attempts >= 1);
+    assert.ok(result.elapsedMs >= 250 - 50);
+  });
+
+  it("throws ProjectNotFound for unknown project", async () => {
+    const { fetch } = mockFetch(() => json({}));
+    const sdk = makeSdk(fetch);
+    await assert.rejects(
+      sdk.blobs.waitFresh("prj_missing", { url: "https://app.run402.com/_blob/k", sha256: "ff" }),
+      ProjectNotFound,
+    );
+  });
+});
diff --git a/sdk/src/namespaces/blobs.ts b/sdk/src/namespaces/blobs.ts
index 768f8b16..886f4275 100644
--- a/sdk/src/namespaces/blobs.ts
+++ b/sdk/src/namespaces/blobs.ts
@@ -10,6 +10,9 @@
 import type { Client } from "../kernel.js";
 import { ApiError, ProjectNotFound } from "../errors.js";
 import type {
+  BlobCacheKind,
+  BlobCdnEnvelope,
+  BlobDiagnoseEnvelope,
   BlobLsOptions,
   BlobLsResult,
   BlobPutOptions,
@@ -17,6 +20,8 @@ import type {
   BlobPutSource,
   BlobSignOptions,
   BlobSignResult,
+  BlobWaitFreshOptions,
+  BlobWaitFreshResult,
 } from "./blobs.types.js";
 
 function encodeKey(key: string): string {
@@ -62,6 +67,106 @@ interface UploadInitResponse {
   part_count: number;
 }
 
+/**
+ * Gateway upload-completion response shape (legacy snake_case fields plus
+ * any new agent-DX fields the gateway emits). Used internally by `put` to
+ * widen into the AssetRef return type the SDK exposes.
+ */
+interface UploadCompleteResponse {
+  key: string;
+  size_bytes: number;
+  sha256: string | null;
+  visibility: "public" | "private";
+  content_type: string | null;
+  immutable_suffix: string | null;
+  etag?: string;
+  url: string | null;
+  immutable_url: string | null;
+  /** Optional: future gateway versions emit a `cdn` envelope on completion
+   *  with the CloudFront invalidation ID + status for mutable overwrites
+   *  (and `ready: true` for immutable uploads). When absent (current
+   *  gateway), the SDK fills in safe defaults from local information. */
+  cdn?: Partial<BlobCdnEnvelope>;
+}
+
+/**
+ * Convert hex (e.g. `"abcd…"`) to base64 in environments that have either
+ * Buffer (Node) or `btoa` (browsers). The helper is here because Browser SDK
+ * builds may run without `Buffer`.
+ */
+function hexToBase64(hex: string): string {
+  const len = hex.length;
+  const bytes = new Uint8Array(len / 2);
+  for (let i = 0; i < len; i += 2) {
+    bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+  }
+  // Prefer Buffer when available (faster on Node).
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const g = globalThis as unknown as { Buffer?: any; btoa?: (s: string) => string };
+  if (g.Buffer) return g.Buffer.from(bytes).toString("base64");
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return g.btoa ? g.btoa(s) : "";
+}
+
+/**
+ * Widen the gateway's snake_case completion response into the AssetRef
+ * shape (which adds camelCase aliases + locally-derived integrity fields
+ * for any URL the consumer is about to embed in code). For non-immutable
+ * uploads where the SHA is null, the integrity fields are null and the
+ * agent guidance steers them to use `--immutable` before linking.
+ */
+function buildAssetRef(
+  resp: UploadCompleteResponse,
+  contentType: string,
+): BlobPutResult {
+  const sha = resp.sha256;
+  const immutable = !!resp.immutable_url;
+  const cacheKind: BlobCacheKind =
+    resp.visibility === "private"
+      ? "private"
+      : immutable
+      ? "immutable"
+      : "mutable";
+  const etag = sha ? `"sha256-${sha}"` : null;
+  const sri = sha ? `sha256-${hexToBase64(sha)}` : null;
+  const contentDigest = sha ? `sha-256=:${hexToBase64(sha)}:` : null;
+
+  // The cdn envelope: prefer what the gateway returns; fall back to
+  // best-effort defaults so older gateway versions don't break the SDK
+  // surface. immutable URLs are always-ready by definition.
+  const cdnFromGw = resp.cdn ?? {};
+  const cdn: BlobCdnEnvelope = {
+    version: cdnFromGw.version ?? "blob-gateway-v2",
+    invalidationId: cdnFromGw.invalidationId ?? null,
+    invalidationStatus: cdnFromGw.invalidationStatus ?? null,
+    ready: cdnFromGw.ready ?? immutable,
+    hint:
+      cdnFromGw.hint ??
+      (immutable
+        ? "immutableUrl is ready immediately."
+        : "For mutable URLs, propagation is asynchronous. Prefer immutableUrl in generated HTML/CSS/JS, or call wait_for_cdn_freshness."),
+  };
+
+  return {
+    key: resp.key,
+    size_bytes: resp.size_bytes,
+    sha256: sha,
+    visibility: resp.visibility,
+    url: resp.url,
+    immutable_url: resp.immutable_url,
+    size: resp.size_bytes,
+    contentSha256: sha,
+    contentType,
+    immutableUrl: resp.immutable_url,
+    etag,
+    sri,
+    contentDigest,
+    cacheKind,
+    cdn,
+  };
+}
+
 export class Blobs {
   constructor(private readonly client: Client) {}
 
@@ -145,7 +250,7 @@ export class Blobs {
     const completeBody = init.mode === "multipart"
       ? { parts: partEtags.map((e, i) => ({ part_number: i + 1, etag: `"${e.etag}"` })) }
       : {};
-    return this.client.request<BlobPutResult>(
+    const completion = await this.client.request<UploadCompleteResponse>(
       `/storage/v1/uploads/${init.upload_id}/complete`,
       {
         method: "POST",
@@ -157,6 +262,110 @@ export class Blobs {
         context: "completing upload",
       },
     );
+
+    // Widen the gateway response into the v1.45 AssetRef return type. Older
+    // gateway versions don't emit the `cdn` envelope; `buildAssetRef` fills
+    // safe defaults derived from the SHA + visibility so the SDK surface is
+    // stable across gateway versions.
+    return buildAssetRef(completion, contentType);
+  }
+
+  /**
+   * Diagnose a public blob URL. Returns a JSON envelope describing the live
+   * CDN state (expected vs observed SHA, cache headers, recent invalidation
+   * status, vantage). The gateway probes the URL once from us-east-1 with
+   * `Range: bytes=0-0` and returns within 5 s even if the inner probe is
+   * slow.
+   *
+   * **Vantage caveat:** the result reflects ONE CloudFront PoP at the time
+   * of the call. Other PoPs may serve different cached states. The
+   * `probeMayHaveWarmedCache: true` field reminds the agent that the probe
+   * itself populates the cache, so a subsequent read may differ.
+   *
+   * The URL must belong to the requesting project — cross-project URLs are
+   * rejected by the gateway with `403`. SSRF is enforced gateway-side: only
+   * `*.run402.com` and the project's active custom domains are accepted.
+   *
+   * @example
+   *   const diag = await client.blobs.diagnoseUrl("prj_abc", "https://app.run402.com/_blob/avatar.png");
+   *   if (diag.observedSha256 !== diag.expectedSha256) console.log(diag.hint);
+   */
+  async diagnoseUrl(projectId: string, url: string): Promise<BlobDiagnoseEnvelope> {
+    const project = await this.client.getProject(projectId);
+    if (!project) throw new ProjectNotFound(projectId, "diagnosing blob URL");
+
+    const path = `/storage/v1/blobs/diagnose?url=${encodeURIComponent(url)}`;
+    return this.client.request<BlobDiagnoseEnvelope>(path, {
+      headers: {
+        apikey: project.anon_key,
+        Authorization: `Bearer ${project.anon_key}`,
+      },
+      context: "diagnosing blob URL",
+    });
+  }
+
+  /**
+   * Poll the CDN until a mutable URL serves the expected SHA-256, or the
+   * timeout elapses. **For mutable URLs only** — for immutable URLs (the
+   * `immutableUrl` returned by `put`) no waiting is needed; they're bound
+   * at upload time and never previously cached.
+   *
+   * Default `timeoutMs` is 60_000 (60 s). The helper polls the gateway's
+   * diagnose endpoint with exponential backoff bounded by 1 s; each poll
+   * may itself warm the cache for the probed PoP, so subsequent reads from
+   * other PoPs may still be stale until invalidation propagation completes.
+   *
+   * @example
+   *   await client.blobs.waitFresh("prj_abc", {
+   *     url: result.url,           // the mutable URL from blobs.put
+   *     sha256: result.contentSha256,
+   *     timeoutMs: 30_000,
+   *   });
+   */
+  async waitFresh(
+    projectId: string,
+    opts: BlobWaitFreshOptions,
+  ): Promise<BlobWaitFreshResult> {
+    const project = await this.client.getProject(projectId);
+    if (!project) throw new ProjectNotFound(projectId, "waiting for CDN freshness");
+
+    const expected = opts.sha256.toLowerCase();
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    const start = Date.now();
+
+    let attempts = 0;
+    let observed: string | null = null;
+    let delay = 100;
+    while (Date.now() - start < timeoutMs) {
+      attempts++;
+      try {
+        const envelope = await this.diagnoseUrl(projectId, opts.url);
+        observed = envelope.observedSha256;
+        if (observed && observed.toLowerCase() === expected) {
+          return {
+            fresh: true,
+            observedSha256: observed,
+            attempts,
+            elapsedMs: Date.now() - start,
+            vantage: "gateway-us-east-1",
+          };
+        }
+      } catch {
+        // Swallow & retry — `diagnoseUrl` can fail on transient gateway
+        // hiccups (e.g. ALB cycling). The next poll re-attempts.
+      }
+      const remaining = timeoutMs - (Date.now() - start);
+      if (remaining <= 0) break;
+      await new Promise((r) => setTimeout(r, Math.min(delay, remaining)));
+      delay = Math.min(delay * 2, 1000);
+    }
+    return {
+      fresh: false,
+      observedSha256: observed,
+      attempts,
+      elapsedMs: Date.now() - start,
+      vantage: "gateway-us-east-1",
+    };
   }
 
   /**
diff --git a/sdk/src/namespaces/blobs.types.ts b/sdk/src/namespaces/blobs.types.ts
index 940c66eb..24515ad3 100644
--- a/sdk/src/namespaces/blobs.types.ts
+++ b/sdk/src/namespaces/blobs.types.ts
@@ -23,13 +23,154 @@ export interface BlobPutOptions {
   immutable?: boolean;
 }
 
-export interface BlobPutResult {
+/**
+ * Cache-kind hint for a blob URL. Mirrors the gateway's
+ * `X-Run402-Blob-Cache-Kind` response header. Agents key on this when
+ * deciding whether they need to wait for CDN freshness after an upload.
+ */
+export type BlobCacheKind = "immutable" | "mutable" | "private";
+
+/**
+ * CloudFront invalidation status for a mutable URL. Returned by the gateway's
+ * upload-completion response when an invalidation was triggered (e.g. a
+ * re-upload to an existing public mutable key). `ready: true` is the
+ * immutable-URL signal — no waiting needed.
+ */
+export interface BlobCdnEnvelope {
+  /** Blob CDN config version. Currently `"blob-gateway-v2"`. */
+  version: string;
+  /** CloudFront invalidation ID for the mutable URL, when one was triggered. */
+  invalidationId: string | null;
+  /** Status of the invalidation at the time of the upload response. */
+  invalidationStatus: "InProgress" | "Completed" | "Failed" | null;
+  /** `true` for immutable URLs (always ready); omitted/false for mutable. */
+  ready?: boolean;
+  /** Human-readable nudge ("Use immutableUrl or call wait_for_cdn_freshness."). */
+  hint: string | null;
+}
+
+/**
+ * Stable URL reference returned by `client.blobs.put`. Includes both the
+ * legacy snake_case fields (back-compat with pre-v1.45 SDK) and the v1.45+
+ * agent-DX fields:
+ *
+ *   - `immutableUrl` — content-addressed URL; correct from upload time, no
+ *     wait. Prefer this in generated HTML/CSS/JS code.
+ *   - `etag`, `sri`, `contentDigest` — strong integrity headers derived from
+ *     the SHA-256, suitable for `<script integrity=...>` and Subresource
+ *     Integrity verification.
+ *   - `cdn` — CloudFront invalidation envelope (mostly meaningful for
+ *     mutable overwrites; immutable URLs always have `cdn.ready = true`).
+ *
+ * The legacy fields (`size_bytes`, `sha256`, `immutable_url`) are kept for
+ * back-compat — existing consumers that destructure those keys continue to
+ * work unchanged.
+ */
+export interface AssetRef {
+  // ---- v1.0+ legacy fields (back-compat) -----------------------------------
   key: string;
   size_bytes: number;
   sha256: string | null;
   visibility: BlobVisibility;
   url: string | null;
   immutable_url: string | null;
+  // ---- v1.45+ agent-DX fields ---------------------------------------------
+  /** Same value as `size_bytes`, just the camelCase form used by the new
+   *  agent-facing surface. */
+  size: number;
+  /** Hex SHA-256 of the bytes. Same as `sha256` (camelCase alias). */
+  contentSha256: string | null;
+  /** Effective Content-Type (auto-detected from the key extension when not
+   *  set explicitly via `BlobPutOptions.contentType`). */
+  contentType: string;
+  /** Same value as `immutable_url`. Camel-case alias for the v1.45+ surface.
+   *  **Prefer this in generated HTML/CSS/JS** — it never needs cache
+   *  invalidation. */
+  immutableUrl: string | null;
+  /** Strong ETag of the form `"sha256-<hex>"`. Null when `sha256` is null
+   *  (only computed when `--immutable` was passed at upload). */
+  etag: string | null;
+  /** Browser SRI form: `sha256-<base64>`. Use as the `integrity` attribute
+   *  value in `<script>`/`<link>` tags. */
+  sri: string | null;
+  /** RFC 9530 `Content-Digest` value, `sha-256=:<base64>:`. */
+  contentDigest: string | null;
+  /** Semantic cache-kind hint matching the gateway's response header. */
+  cacheKind: BlobCacheKind;
+  /** CloudFront invalidation envelope for the mutable URL. Always populated;
+   *  for immutable uploads `cdn.ready === true`. */
+  cdn: BlobCdnEnvelope;
+}
+
+/**
+ * Return type of `client.blobs.put`. v1.45 widens this to AssetRef; the
+ * legacy fields stay for back-compat.
+ */
+export type BlobPutResult = AssetRef;
+
+/** Response envelope from `client.blobs.diagnoseUrl(...)`. */
+export interface BlobDiagnoseEnvelope {
+  projectId: string;
+  key: string;
+  /** SHA the gateway DB believes is current for `(projectId, key)`. */
+  expectedSha256: string | null;
+  /** SHA actually returned by the probe (`X-Run402-Content-Sha256` header). */
+  observedSha256: string | null;
+  /** Probe vantage. The agent is told the probe is single-region. */
+  vantage: "gateway-us-east-1";
+  /** Probe method — `"GET_RANGE_0_0"` (NOT HEAD; HEAD can hit a different
+   *  cached variant). */
+  probeMethod: "GET_RANGE_0_0";
+  /** Accept-Encoding used by the probe. */
+  acceptEncoding: string;
+  /** ISO timestamp of the probe. */
+  observedAt: string;
+  /** Always `true` — the probe itself populates the cache, so subsequent
+   *  reads may differ. Agents are told this explicitly. */
+  probeMayHaveWarmedCache: true;
+  /** The URL the probe actually fetched (after URL normalization). */
+  canonicalUrl: string;
+  /** Which URL kind we resolved against (`'blob-immutable'` or
+   *  `'blob-mutable'`). `/_cas/<sha>` is deferred from this change. */
+  pathKind: "blob-mutable" | "blob-immutable";
+  cache: {
+    xCache: string | null;
+    ageSeconds: number | null;
+    cacheKind: BlobCacheKind | null;
+  };
+  invalidation: {
+    id: string | null;
+    status: "InProgress" | "Completed" | "Failed" | null;
+  };
+  /** Human-readable hint with actionable next-steps for the agent. */
+  hint: string;
+}
+
+/**
+ * Options for `client.blobs.waitFresh(projectId, opts)`. The URL is the
+ * mutable public URL you want to wait on (typically `result.url` from a
+ * preceding `blobs.put` call).
+ *
+ * **Mutable URLs only.** For immutable URLs (`immutableUrl`) no waiting is
+ * needed — they are bound to a SHA at upload time and were never previously
+ * cached.
+ */
+export interface BlobWaitFreshOptions {
+  /** The mutable URL to poll (e.g. `https://app.run402.com/_blob/avatar.png`). */
+  url: string;
+  /** Expected hex SHA-256. Polling exits when `observedSha256 === sha256`. */
+  sha256: string;
+  /** Default 60_000 ms. */
+  timeoutMs?: number;
+}
+
+/** Result of `client.blobs.waitFresh(...)`. */
+export interface BlobWaitFreshResult {
+  fresh: boolean;
+  observedSha256: string | null;
+  attempts: number;
+  elapsedMs: number;
+  vantage: "gateway-us-east-1";
 }
 
 export interface BlobLsOptions {
diff --git a/src/index.ts b/src/index.ts
index 93e609fa..bdc7b49f 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -43,6 +43,8 @@ import { blobGetSchema, handleBlobGet } from "./tools/blob-get.js";
 import { blobLsSchema, handleBlobLs } from "./tools/blob-ls.js";
 import { blobRmSchema, handleBlobRm } from "./tools/blob-rm.js";
 import { blobSignSchema, handleBlobSign } from "./tools/blob-sign.js";
+import { blobDiagnoseSchema, handleBlobDiagnose } from "./tools/blob-diagnose.js";
+import { blobWaitFreshSchema, handleBlobWaitFresh } from "./tools/blob-wait-fresh.js";
 
 // New tools — functions & secrets CRUD
 import { listFunctionsSchema, handleListFunctions } from "./tools/list-functions.js";
@@ -250,6 +252,20 @@ server.tool(
   async (args) => handleBlobSign(args),
 );
 
+server.tool(
+  "diagnose_public_url",
+  "Returns the live CDN state for a public blob URL (probed once from gateway-us-east-1 — NOT a global view). Use this when a deployed asset shows the wrong version or you suspect cache staleness. The result includes `expectedSha256` (from gateway DB), `observedSha256` (what CloudFront just served), recent `invalidation` status, and a human-readable `hint` with actionable next-steps. The `probeMayHaveWarmedCache: true` field warns that the probe itself populates the cache, so subsequent reads from elsewhere may differ. URLs outside the requesting project return 403; non-`*.run402.com` URLs return 400 unless they're on one of your active custom domains.",
+  blobDiagnoseSchema,
+  async (args) => handleBlobDiagnose(args),
+);
+
+server.tool(
+  "wait_for_cdn_freshness",
+  "Polls the CDN until a MUTABLE blob URL serves the expected SHA-256, or the timeout elapses. **For mutable URLs only** — for immutable URLs (the `immutableUrl` returned by `blob_put`), no waiting is needed; they're bound to a SHA at upload time and never previously cached. Use this after a re-upload to an existing public mutable key when an end-user-visible URL must reflect the new content before continuing. The probe is single-vantage (us-east-1). On timeout, the tool returns isError=true so an agent can branch into a fallback — typically: switch to the immutableUrl.",
+  blobWaitFreshSchema,
+  async (args) => handleBlobWaitFresh(args),
+);
+
 server.tool(
   "upload_file",
   "(DEPRECATED — use blob_put. Sunset 2026-06-01.) Upload text content to project storage. Returns the storage key and size.",
diff --git a/src/tools/blob-diagnose.ts b/src/tools/blob-diagnose.ts
new file mode 100644
index 00000000..1135eb5b
--- /dev/null
+++ b/src/tools/blob-diagnose.ts
@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { getSdk } from "../sdk.js";
+import { mapSdkError } from "../errors.js";
+
+/**
+ * MCP tool `diagnose_public_url`.
+ *
+ * Returns the gateway's diagnose envelope for a public blob URL: expected
+ * vs observed SHA, CloudFront cache state, recent invalidation status,
+ * vantage. The probe is single-region (us-east-1); the response self-
+ * documents this via `vantage` and `probeMayHaveWarmedCache: true`.
+ *
+ * Cross-project URLs return 403 (the gateway enforces project ownership);
+ * non-`*.run402.com` URLs return 400 SSRF-guard error unless the URL is on
+ * one of the requesting project's active custom domains.
+ */
+export const blobDiagnoseSchema = {
+  project_id: z.string().describe("Project ID that owns the URL"),
+  url: z.string().describe("Full blob URL (e.g. https://app.run402.com/_blob/avatar.png)"),
+};
+
+type Args = { project_id: string; url: string };
+
+export async function handleBlobDiagnose(
+  args: Args,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  try {
+    const env = await getSdk().blobs.diagnoseUrl(args.project_id, args.url);
+    const matched =
+      env.observedSha256 != null && env.observedSha256 === env.expectedSha256;
+    const summary = matched
+      ? `OK: CDN serving the current SHA (probed once from ${env.vantage}; not a global view).`
+      : `DIVERGENT: expected ${env.expectedSha256 ?? "<unknown>"} vs observed ${env.observedSha256 ?? "<no x-run402-content-sha256>"} (${env.vantage}).`;
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            `${summary}\n\nHint: ${env.hint}\n\n` +
+            "```json\n" +
+            JSON.stringify(env, null, 2) +
+            "\n```",
+        },
+      ],
+    };
+  } catch (err) {
+    return mapSdkError(err, "diagnosing public blob URL");
+  }
+}
diff --git a/src/tools/blob-wait-fresh.ts b/src/tools/blob-wait-fresh.ts
new file mode 100644
index 00000000..4bde6993
--- /dev/null
+++ b/src/tools/blob-wait-fresh.ts
@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { getSdk } from "../sdk.js";
+import { mapSdkError } from "../errors.js";
+
+/**
+ * MCP tool `wait_for_cdn_freshness`.
+ *
+ * Polls the gateway's diagnose endpoint until the URL serves the expected
+ * SHA-256, or the timeout elapses. **Mutable URLs only** — for immutable
+ * URLs (the `immutableUrl` field returned by `blob_put`) no waiting is
+ * needed; they're bound to a SHA at upload time and never previously cached.
+ */
+export const blobWaitFreshSchema = {
+  project_id: z.string().describe("Project ID that owns the URL"),
+  url: z.string().describe("Mutable blob URL to poll (e.g. https://app.run402.com/_blob/avatar.png)"),
+  sha256: z.string().describe("Expected hex SHA-256 (from a preceding upload)"),
+  timeout_ms: z
+    .number()
+    .int()
+    .min(1_000)
+    .max(600_000)
+    .optional()
+    .describe("Max wait in milliseconds (1 000 – 600 000, default 60 000)"),
+};
+
+type Args = {
+  project_id: string;
+  url: string;
+  sha256: string;
+  timeout_ms?: number;
+};
+
+export async function handleBlobWaitFresh(
+  args: Args,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  try {
+    const result = await getSdk().blobs.waitFresh(args.project_id, {
+      url: args.url,
+      sha256: args.sha256,
+      timeoutMs: args.timeout_ms ?? 60_000,
+    });
+    const headline = result.fresh
+      ? `FRESH: CDN now serving the expected SHA after ${result.attempts} probe(s) over ${result.elapsedMs}ms (vantage ${result.vantage}).`
+      : `TIMEOUT: CDN still serving SHA ${result.observedSha256 ?? "<none>"} after ${result.attempts} probe(s) over ${result.elapsedMs}ms. The URL may eventually catch up — re-try, or use the immutableUrl.`;
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            `${headline}\n\n` +
+            "```json\n" +
+            JSON.stringify(result, null, 2) +
+            "\n```",
+        },
+      ],
+      isError: result.fresh ? undefined : true,
+    };
+  } catch (err) {
+    return mapSdkError(err, "waiting for CDN freshness");
+  }
+}
diff --git a/sync.test.ts b/sync.test.ts
index f43ab3b2..badbcc04 100644
--- a/sync.test.ts
+++ b/sync.test.ts
@@ -59,7 +59,7 @@ function parseSubcommands(filePath: string): string[] {
 /** Parse CLI commands as "module:subcommand" pairs */
 function parseCliCommands(): string[] {
   const cmds: string[] = [];
-  for (const mod of ["allowance", "tier", "projects", "image", "storage", "blob", "functions", "secrets", "sites", "subdomains", "domains", "apps", "email", "message", "agent", "ai", "auth", "sender-domain", "billing", "contracts", "webhooks", "service"]) {
+  for (const mod of ["allowance", "tier", "projects", "image", "storage", "blob", "cdn", "functions", "secrets", "sites", "subdomains", "domains", "apps", "email", "message", "agent", "ai", "auth", "sender-domain", "billing", "contracts", "webhooks", "service"]) {
     for (const sub of parseSubcommands(join(__dirname, "cli/lib", `${mod}.mjs`))) {
       cmds.push(`${mod}:${sub}`);
     }
@@ -73,7 +73,7 @@ function parseCliCommands(): string[] {
 /** Parse OpenClaw commands as "module:subcommand" pairs */
 function parseOpenClawCommands(): string[] {
   const cmds: string[] = [];
-  for (const mod of ["allowance", "tier", "projects", "image", "storage", "blob", "functions", "secrets", "sites", "subdomains", "domains", "apps", "email", "message", "agent", "ai", "auth", "sender-domain", "billing", "contracts", "webhooks", "service"]) {
+  for (const mod of ["allowance", "tier", "projects", "image", "storage", "blob", "cdn", "functions", "secrets", "sites", "subdomains", "domains", "apps", "email", "message", "agent", "ai", "auth", "sender-domain", "billing", "contracts", "webhooks", "service"]) {
     for (const sub of parseSubcommands(join(__dirname, "openclaw/scripts", `${mod}.mjs`))) {
       cmds.push(`${mod}:${sub}`);
     }
@@ -169,6 +169,9 @@ const SURFACE: Capability[] = [
   { id: "blob_ls",           endpoint: "GET /storage/v1/blobs",                  mcp: "blob_ls",        cli: "blob:ls",          openclaw: "blob:ls" },
   { id: "blob_rm",           endpoint: "DELETE /storage/v1/blob/{key}",          mcp: "blob_rm",        cli: "blob:rm",          openclaw: "blob:rm" },
   { id: "blob_sign",         endpoint: "POST /storage/v1/blob/{key}/sign",       mcp: "blob_sign",      cli: "blob:sign",        openclaw: "blob:sign" },
+  // v1.45: agent-DX blob CDN diagnostics (CLI: blob diagnose / cdn wait-fresh).
+  { id: "diagnose_public_url",   endpoint: "GET /storage/v1/blobs/diagnose",       mcp: "diagnose_public_url",     cli: "blob:diagnose",     openclaw: "blob:diagnose" },
+  { id: "wait_for_cdn_freshness", endpoint: "GET /storage/v1/blobs/diagnose (poll)", mcp: "wait_for_cdn_freshness",  cli: "cdn:wait-fresh",    openclaw: "cdn:wait-fresh" },
 
   // ── Functions ────────────────────────────────────────────────────────────
   { id: "deploy_function",   endpoint: "POST /projects/v1/admin/:id/functions",              mcp: "deploy_function",   cli: "functions:deploy", openclaw: "functions:deploy" },
@@ -348,6 +351,9 @@ const SDK_BY_CAPABILITY: Record<string, string | null> = {
   blob_ls: "blobs.ls",
   blob_rm: "blobs.rm",
   blob_sign: "blobs.sign",
+  // v1.45: agent-DX blob CDN diagnostics
+  diagnose_public_url: "blobs.diagnoseUrl",
+  wait_for_cdn_freshness: "blobs.waitFresh",
 
   // Functions
   deploy_function: "functions.deploy",