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

[MajorTal]

Summary

The agent-DX rewrite of client.blobs.put return shape. The agent's flow becomes one line:

const asset = await client.blobs.put(p, "logo.png", { bytes }, { immutable: true });
html += asset.imgTag("Company logo");
// → <img src="https://pr-abc.run402.com/_blob/logo-3a7fc02e.png" alt="Company logo">

const styles = await client.blobs.put(p, "styles.css", { content }, { immutable: true });
html += styles.linkTag();
// → <link rel="stylesheet" href="https://pr-abc.run402.com/_blob/styles-aabbccdd.css" integrity="sha256-…" crossorigin>

const app = await client.blobs.put(p, "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>

No URL-form decision (just paste it), no SRI plumbing (baked in), no wait_for_cdn_freshness follow-up (URL is content-addressed → always served correctly first try).

Changes

AssetRef

• NEW cdnUrl — content-addressed URL on pr-<public_id>.run402.com, the host guaranteed to work through the v1.33 /_blob/* CDN behavior. Null on non-immutable or private uploads.
• NEW cdnMutableUrl — mutable form on auto-subdomain. Eventual-consistency caveats; prefer cdnUrl for generated code.
• NEW scriptTag(opts?) / linkTag(opts?) / imgTag(alt?) — paste-and-go HTML tag emitters. Throw with an actionable hint on non-immutable uploads.
• All existing fields (url, immutable_url, immutableUrl, etag, sri, contentDigest, cdn) kept unchanged.

Tag emitters

• scriptTag({ type?, defer?, async? }) — emits <script> with integrity + crossorigin.
• linkTag({ rel = "stylesheet", as? }) — emits <link> with integrity + crossorigin. Supports preload / prefetch via rel.
• imgTag(alt = "") — emits <img> with src + alt. No integrity (HTML5 doesn't support SRI on <img>), but the URL is content-hashed so it's still stable across re-deploys.
• All inputs HTML-attribute-escaped.
• Throw on non-immutable uploads with a hint pointing at { immutable: true }.

Docs

• SKILL.md — blob_put rewritten to lead with the tag-emitter flow. AssetRef field reference reorganized so the agent-DX fields come first.
• cli/llms-cli.txt — same agent-DX guidance for the CLI / SDK reference section.

Coordinated change

Pairs with the gateway PR run402-private#73 which emits cdn_url + cdn_immutable_url on the upload-completion response. The SDK falls back gracefully against older gateway versions: cdnUrl is null and the tag emitters throw with an actionable hint.

Test plan

• npx tsc --noEmit clean (SDK + MCP + CLI)
• SDK blob tests pass: 25 / 25 (4 new — cdnUrl widening, tag-emitter shape, HTML attribute escaping, non-immutable error)
• Existing tests still pass: client.blobs.put, get, ls, rm, sign, diagnoseUrl, waitFresh
• After merge: rebuild SDK + smoke-test against deployed gateway: full upload returns the new fields populated, tag emitters render valid HTML pointing at the auto-subdomain URL, browser fetch of that URL returns 200 with matching SHA

Followup (separate PR)

Make claimed subdomains and custom domains serve /_blob/* through the v1.33 CDN. Today they 404 from BlobRoutingV2 because the KVS values lack project_id. The SDK steers agents around this via the auto-subdomain URL — but it's worth fixing so result.url (preferred host) becomes embed-safe too.

🤖 Generated with Claude Code