feat(sdk): paste-and-go AssetRef with scriptTag/linkTag/imgTag emitters

v1.45 best-DX: agents call blobs.put with immutable:true and paste asset.scriptTag() / asset.linkTag() / asset.imgTag() into generated HTML. Each emitter returns a ready-to-use tag with src/href set to a content-hashed URL on pr-<public_id>.run402.com (the host guaranteed to work through the v1.33 CDN), integrity set to the SRI hash, and crossorigin set so browsers verify the bytes.

AssetRef widening:

- cdnUrl: the immutable-form auto-subdomain URL — what scriptTag/linkTag/imgTag bind to. Null on non-immutable or private uploads.

- cdnMutableUrl: mutable-form auto-subdomain URL. Eventual-consistency caveats apply; prefer cdnUrl in code.

- url / immutable_url / immutableUrl (preferred-host forms) — kept for backward compat and direct-API consumers (e.g. blobs.get). Currently NOT served through the v1.33 CDN behavior on claimed subdomains / custom domains; followup tracked separately.

Tag emitter ergonomics:

- scriptTag({ type?, defer?, async? }): bakes integrity + crossorigin

- linkTag({ rel = 'stylesheet', as? }): bakes integrity + crossorigin

- imgTag(alt = ''): no SRI (HTML5 spec), but URL is content-hashed so still stable across re-deploys

- HTML attribute escaping for url + alt

- Throw with actionable hint when called on non-immutable uploads

Tests:

- 4 new test cases (immutable widening, tag emitter shapes, HTML escaping, non-immutable error)

- Existing 22 tests still green; total now 25

Coordinated with run402-private: the gateway emits the new cdn_url + cdn_immutable_url fields on the upload-completion response. Older gateway versions (without the new fields) still work — the SDK leaves cdnUrl/cdnMutableUrl null and the tag emitters throw with the immutable-only hint, which surfaces on the first call rather than during upload.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MajorTal

SKILL.md

@@ -109,14 +109,32 @@ 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:** 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.
+**Returns:** an `AssetRef`. The agent-DX way to use it: **upload with `immutable: true`, then call `result.scriptTag()`, `result.linkTag()`, or `result.imgTag()` and paste the output directly into your generated HTML.** The tag emitters return ready-to-use HTML with `src` / `href` set to a content-hashed URL on `pr-<public_id>.run402.com`, `integrity` set to the SRI hash, and `crossorigin` set so browsers verify the bytes.
 
-**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.
+```ts
+const logo = await client.blobs.put(projectId, "logo.png", { bytes }, { immutable: true });
+html += logo.imgTag("Company logo");
+// → <img src="https://pr-abc.run402.com/_blob/logo-3a7fc02e.png" alt="Company logo">
 
-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`.
+const app = await client.blobs.put(projectId, "app.js", { content }, { immutable: true });
+html += app.scriptTag({ type: "module" });
+// → <script src="https://pr-abc.run402.com/_blob/app-deadbeef.js" type="module" integrity="sha256-…" crossorigin></script>
+
+const styles = await client.blobs.put(projectId, "styles.css", { content }, { immutable: true });
+html += styles.linkTag();
+// → <link rel="stylesheet" href="https://pr-abc.run402.com/_blob/styles-aabbccdd.css" integrity="sha256-…" crossorigin>
+```
+
+**Why this is the recommended path.** The URL the emitters use (`cdnUrl`) is content-addressed (no cache invalidation, no `wait_for_cdn_freshness`), served from the auto-subdomain `pr-<public_id>.run402.com` (the host that's guaranteed to work through the v1.33 CDN), and stable across re-deploys of the same content. SRI guarantees the browser refuses execution on byte mismatch. There are no decisions for the agent to make.
+
+**Other AssetRef fields** for advanced use:
+- `cdnUrl` — the content-addressed auto-subdomain URL the tag emitters use. Use this directly if you're not generating HTML (e.g. CSS `url()` references, JSON data URLs).
+- `cdnMutableUrl` — mutable form of the auto-subdomain URL. Eventual-consistency caveats apply; prefer `cdnUrl` for generated code.
+- `url` / `immutableUrl` (preferred-host forms) — the URL on the project's pretty host (claimed subdomain or custom domain when configured). Currently NOT served through the CDN — keep using these for direct-API consumers (e.g. `client.blobs.get`), not in `<script>`/`<img>` embeds.
+- `etag`, `sri`, `contentDigest` — the integrity values the tag emitters bake in. Useful if you're constructing tags by hand for an unsupported context.
+- `cdn: { version, invalidationId, invalidationStatus, ready, hint }` — CloudFront invalidation envelope. For immutable uploads `cdn.ready === true` and no further work is required.
+
+The legacy `size_bytes`, `sha256`, `immutable_url` fields stay populated for back-compat with pre-v1.45 callers.
 
 Supersedes `upload_file` (deprecated).
 

cli/llms-cli.txt

@@ -408,16 +408,28 @@ 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 (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}>`.
+`put` response (an `AssetRef`) — the agent-DX way:
+
+```js
+const asset = await client.blobs.put(projectId, key, { bytes }, { immutable: true });
+html += asset.scriptTag();          // <script src=... integrity=... crossorigin></script>
+html += asset.linkTag();            // <link rel="stylesheet" href=... integrity=... crossorigin>
+html += asset.imgTag("Company logo"); // <img src=... alt="Company logo">
+```
+
+Always upload with `immutable: true` when you plan to embed in HTML/CSS/JS. The tag emitters require it (they bind to a SHA), and the resulting URL is content-addressed → never needs cache invalidation, never breaks on re-deploys, never needs `cdn wait-fresh` follow-up.
+
+Other AssetRef fields for advanced use:
+- `cdnUrl` — the content-addressed URL the emitters use directly. `https://pr-<public_id>.run402.com/_blob/<key-without-ext>-<8hex>.<ext>`. Served via the v1.33 CDN; guaranteed-reachable.
+- `cdnMutableUrl` — mutable URL on the auto-subdomain. Eventual-consistency caveats; prefer `cdnUrl` in code.
+- `url` / `immutableUrl` (preferred-host forms) — URL on the project's pretty host (claimed subdomain / custom domain when configured). Currently NOT served through the CDN — keep using for direct-API consumers (e.g. `run402 blob get`), not in `<script>`/`<img>` embeds.
+- `etag` — strong `"sha256-<hex>"` ETag (when `immutable`).
+- `sri` — `sha256-<base64>` for `<script integrity={sri}>` if you must construct tags by hand.
 - `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.
+**Agent loop pattern (mutable URL only):** if you must use a stable mutable URL across re-uploads, `run402 cdn wait-fresh <mutable-url> --sha <new-sha>` blocks until the CDN serves the new SHA. **Don't call wait-fresh on immutable URLs** — they're correct from the moment of upload.
 
 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.
 

sdk/src/namespaces/blobs.test.ts

@@ -327,6 +327,8 @@ describe("blobs.put — AssetRef widening (v1.45)", () => {
           immutable_suffix: SHA.slice(0, 8),
           url: "https://app.run402.com/_blob/x.txt",
           immutable_url: "https://app.run402.com/_blob/x-ba7816bf.txt",
+          cdn_url: "https://pr-abc.run402.com/_blob/x.txt",
+          cdn_immutable_url: "https://pr-abc.run402.com/_blob/x-ba7816bf.txt",
         });
       }
       throw new Error("unexpected: " + call.url);
@@ -344,6 +346,9 @@ describe("blobs.put — AssetRef widening (v1.45)", () => {
     assert.equal(result.contentSha256, SHA);
     assert.equal(result.immutableUrl, "https://app.run402.com/_blob/x-ba7816bf.txt");
     assert.equal(result.contentType, "text/plain");
+    // v1.45 cdn-reachable URLs (auto-subdomain, guaranteed-working).
+    assert.equal(result.cdnUrl, "https://pr-abc.run402.com/_blob/x-ba7816bf.txt");
+    assert.equal(result.cdnMutableUrl, "https://pr-abc.run402.com/_blob/x.txt");
     // Integrity fields derived from the SHA.
     assert.equal(result.etag, `"sha256-${SHA}"`);
     assert.match(result.sri ?? "", /^sha256-[A-Za-z0-9+/]+={0,2}$/);
@@ -352,7 +357,134 @@ describe("blobs.put — AssetRef widening (v1.45)", () => {
     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/);
+    assert.match(result.cdn.hint ?? "", /Use cdnUrl/);
+  });
+
+  it("scriptTag/linkTag/imgTag emit ready-to-paste tags with SRI + crossorigin", async () => {
+    const SHA = "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad";
+    const { fetch } = mockFetch((call) => {
+      if (call.url.endsWith("/storage/v1/uploads")) {
+        return json({
+          upload_id: "u_t",
+          mode: "single",
+          part_count: 1,
+          parts: [{ part_number: 1, url: "https://s3.test/u_t/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: "app.js",
+          size_bytes: 3,
+          sha256: SHA,
+          visibility: "public",
+          content_type: "text/javascript",
+          immutable_suffix: SHA.slice(0, 8),
+          url: "https://app.run402.com/_blob/app.js",
+          immutable_url: "https://app.run402.com/_blob/app-ba7816bf.js",
+          cdn_url: "https://pr-abc.run402.com/_blob/app.js",
+          cdn_immutable_url: "https://pr-abc.run402.com/_blob/app-ba7816bf.js",
+        });
+      }
+      throw new Error("unexpected: " + call.url);
+    });
+    const sdk = makeSdk(fetch);
+    const asset = await sdk.blobs.put("prj_known", "app.js", { content: "abc" }, { immutable: true });
+
+    // Default scriptTag.
+    const tag = asset.scriptTag();
+    assert.match(tag, /^<script /);
+    assert.match(tag, /src="https:\/\/pr-abc\.run402\.com\/_blob\/app-ba7816bf\.js"/);
+    assert.match(tag, /integrity="sha256-[A-Za-z0-9+/]+={0,2}"/);
+    assert.match(tag, /crossorigin/);
+
+    // Module + defer.
+    const moduleTag = asset.scriptTag({ type: "module", defer: true });
+    assert.match(moduleTag, /type="module"/);
+    assert.match(moduleTag, / defer /);
+
+    // Default linkTag (stylesheet).
+    const link = asset.linkTag();
+    assert.match(link, /^<link /);
+    assert.match(link, /rel="stylesheet"/);
+    assert.match(link, /href="https:\/\/pr-abc\.run402\.com\/_blob\/app-ba7816bf\.js"/);
+    assert.match(link, /integrity="sha256-/);
+
+    // Custom rel + as (preload).
+    const preload = asset.linkTag({ rel: "preload", as: "font" });
+    assert.match(preload, /rel="preload"/);
+    assert.match(preload, /as="font"/);
+
+    // imgTag with alt.
+    const img = asset.imgTag("Company logo");
+    assert.match(img, /^<img /);
+    assert.match(img, /src="https:\/\/pr-abc\.run402\.com\/_blob\/app-ba7816bf\.js"/);
+    assert.match(img, /alt="Company logo"/);
+    // No SRI on <img>.
+    assert.equal(/integrity=/.test(img), false);
+  });
+
+  it("tag emitters escape HTML special chars in alt + url + sri", async () => {
+    // sha256 of "abc"
+    const SHA = "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad";
+    // URL with characters that need attribute escaping.
+    const HOSTILE_URL = "https://pr-abc.run402.com/_blob/a&b\"c<d>.png";
+    const { fetch } = mockFetch((call) => {
+      if (call.url.endsWith("/storage/v1/uploads")) {
+        return json({
+          upload_id: "u_e", mode: "single", part_count: 1,
+          parts: [{ part_number: 1, url: "https://s3.test/u_e/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: 'a&b"c<d>.png',
+          size_bytes: 3, sha256: SHA, visibility: "public",
+          content_type: "image/png", immutable_suffix: SHA.slice(0, 8),
+          url: HOSTILE_URL, immutable_url: HOSTILE_URL,
+          cdn_url: HOSTILE_URL, cdn_immutable_url: HOSTILE_URL,
+        });
+      }
+      throw new Error("unexpected: " + call.url);
+    });
+    const sdk = makeSdk(fetch);
+    const asset = await sdk.blobs.put("prj_known", 'a&b"c<d>.png', { content: "abc" }, { immutable: true });
+    const img = asset.imgTag('Bad <alt> "quoted"');
+    assert.match(img, /alt="Bad &lt;alt&gt; &quot;quoted&quot;"/);
+    assert.match(img, /a&amp;b&quot;c&lt;d&gt;\.png/);
+  });
+
+  it("tag emitters throw on non-immutable uploads with an actionable hint", async () => {
+    const { fetch } = mockFetch((call) => {
+      if (call.url.endsWith("/storage/v1/uploads")) {
+        return json({
+          upload_id: "u_n", mode: "single", part_count: 1,
+          parts: [{ part_number: 1, url: "https://s3.test/u_n/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.png", size_bytes: 3, sha256: null, visibility: "public",
+          content_type: "image/png", immutable_suffix: null,
+          url: "https://app.run402.com/_blob/x.png", immutable_url: null,
+          cdn_url: "https://pr-abc.run402.com/_blob/x.png", cdn_immutable_url: null,
+        });
+      }
+      throw new Error("unexpected: " + call.url);
+    });
+    const sdk = makeSdk(fetch);
+    const asset = await sdk.blobs.put("prj_known", "x.png", { content: "abc" });
+    assert.throws(() => asset.scriptTag(), /immutable: true/);
+    assert.throws(() => asset.linkTag(), /immutable: true/);
+    assert.throws(() => asset.imgTag(), /immutable: true/);
   });
 
   it("leaves integrity fields null on non-immutable upload (sha256 not computed)", async () => {

sdk/src/namespaces/blobs.ts

@@ -82,13 +82,27 @@ interface UploadCompleteResponse {
   etag?: string;
   url: string | null;
   immutable_url: string | null;
+  /** v1.45+ agent-DX URLs from the gateway. Always on the auto-subdomain
+   *  (`pr-<public_id>.run402.com`) which is guaranteed to work through the
+   *  v1.33 CDN path. May be null on private uploads or older gateway
+   *  versions that don't emit them. */
+  cdn_url?: string | null;
+  cdn_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>;
 }
 
+function escapeHtmlAttr(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
 /**
  * Convert hex (e.g. `"abcd…"`) to base64 in environments that have either
  * Buffer (Node) or `btoa` (browsers). The helper is here because Browser SDK
@@ -132,6 +146,12 @@ function buildAssetRef(
   const sri = sha ? `sha256-${hexToBase64(sha)}` : null;
   const contentDigest = sha ? `sha-256=:${hexToBase64(sha)}:` : null;
 
+  // v1.45 agent-DX URLs — guaranteed CDN-reachable on the auto-subdomain.
+  // Older gateway versions don't emit them; null in that case (callers fall
+  // back to the preferred-host `url` / `immutableUrl`).
+  const cdnUrl = resp.cdn_immutable_url ?? null;
+  const cdnMutableUrl = resp.cdn_url ?? 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.
@@ -144,10 +164,23 @@ function buildAssetRef(
     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."),
+        ? "Use cdnUrl + scriptTag()/linkTag()/imgTag() — paste-and-go."
+        : "For mutable URLs, propagation is asynchronous. Prefer cdnUrl (immutable, content-hashed) for generated HTML/CSS/JS, or call wait_for_cdn_freshness."),
   };
 
+  // Emitter helpers. Throw with an actionable hint when the SHA is null
+  // (non-immutable upload) — the agent should re-upload with `immutable:
+  // true` to get content-hashed URLs that pair with SRI.
+  function requireImmutable(name: string): { url: string; sri: string } {
+    if (!cdnUrl || !sri) {
+      throw new Error(
+        `${name}() requires an immutable upload (pass { immutable: true } to blobs.put). ` +
+          `Without immutable, there is no SHA to bind for SRI and the URL would change on re-upload.`,
+      );
+    }
+    return { url: cdnUrl, sri };
+  }
+
   return {
     key: resp.key,
     size_bytes: resp.size_bytes,
@@ -159,11 +192,44 @@ function buildAssetRef(
     contentSha256: sha,
     contentType,
     immutableUrl: resp.immutable_url,
+    cdnUrl,
+    cdnMutableUrl,
     etag,
     sri,
     contentDigest,
     cacheKind,
     cdn,
+
+    scriptTag(opts) {
+      const { url, sri } = requireImmutable("scriptTag");
+      const attrs: string[] = [`src="${escapeHtmlAttr(url)}"`];
+      if (opts?.type === "module") attrs.push(`type="module"`);
+      if (opts?.defer) attrs.push("defer");
+      if (opts?.async) attrs.push("async");
+      attrs.push(`integrity="${escapeHtmlAttr(sri)}"`);
+      attrs.push("crossorigin");
+      return `<script ${attrs.join(" ")}></script>`;
+    },
+
+    linkTag(opts) {
+      const { url, sri } = requireImmutable("linkTag");
+      const rel = opts?.rel ?? "stylesheet";
+      const attrs: string[] = [`rel="${escapeHtmlAttr(rel)}"`];
+      attrs.push(`href="${escapeHtmlAttr(url)}"`);
+      if (opts?.as) attrs.push(`as="${escapeHtmlAttr(opts.as)}"`);
+      attrs.push(`integrity="${escapeHtmlAttr(sri)}"`);
+      attrs.push("crossorigin");
+      return `<link ${attrs.join(" ")}>`;
+    },
+
+    imgTag(alt) {
+      // <img> doesn't take SRI per HTML5 spec — agents who need integrity
+      // for images should fetch + verify Content-Digest server-side. We
+      // still require immutable so the URL is stable across re-deploys.
+      const { url } = requireImmutable("imgTag");
+      const a = alt ?? "";
+      return `<img src="${escapeHtmlAttr(url)}" alt="${escapeHtmlAttr(a)}">`;
+    },
   };
 }