@phnx-labs/agents-cli 1.22.54 → 1.22.56

package/dist/lib/share/worker-template.js

@@ -1,78 +1,90 @@
-// The Cloudflare Worker that fronts the R2 share bucket.
-//
-// One tiny Worker does both sides:
-//   - PUT  /<username>/<slug>  — write-gated by authorizeWrite's THREE principals
-//     (not a fallback chain — each is a distinct legitimate identity):
-//       1. Static WRITE_TOKEN (BYO Cloudflare) — checked first when the presented
-//          bearer equals env.WRITE_TOKEN. owner = env.SHARE_NAMESPACE or the
-//          path's first segment.
-//       2. Phoenix bearer — otherwise GET ${env.PHOENIX_ID_BASE}/api/v1/auth/me
-//          with that bearer → {userId,email}; 401 if absent/invalid.
-//          customMetadata.owner = userId (stable). The path's first segment MUST
-//          equal handleFromEmail(email) (the public handle, e.g. muqsitnawaz),
-//          so one user cannot write another's prefix (403 namespace mismatch).
-//          A __handles/<handle> claim binds the handle to the first userId that
-//          writes it; a different userId gets 409 handle taken.
-//       3. __share HMAC cookie — the signed-in viewer's identity cookie (same
-//          {userId,email} identityFromCookie verifies for GET). Lets the shared
-//          page's inline visibility control PATCH with credentials:'include' and
-//          no bearer; SameSite=Lax blocks it cross-site, and the same namespace/
-//          owner checks confine it to the holder's own pages. Applies to PUT,
-//          PATCH, and DELETE alike, since all three share authorizeWrite.
-//     A managed deployment sets PHOENIX_ID_BASE; BYO sets WRITE_TOKEN; the
-//     platform endpoint may set both. Fail loud (401) when none authenticates.
-//     Writes the body to R2 via the BUCKET binding, storing visibility
-//     (public|unlisted|me|org), owner, org_domain (org only), an optional
-//     expires-at, plus provenance (agent/session/host/repo/date), a label, and
-//     any `--meta` entries in object metadata. me/org require a Phoenix
-//     identity (BYO WRITE_TOKEN cannot publish them). org from a public inbox
-//     domain is 400. Overwriting an existing slug first copies the current
-//     object to <slug>/rev-<ts>-<rand> (revision history) unless
-//     x-share-no-revision is set.
-//   - PATCH /<username>/<slug> — authenticated metadata-only edit. Rewrites the
-//     exact existing body with all HTTP/custom metadata preserved except the
-//     explicitly requested label/arbitrary metadata changes; never revisions.
-//     Conditional put (onlyIf etagMatches) so a concurrent republish 409s
-//     instead of rolling the body back. Phoenix requires customMetadata.owner
-//     === auth.owner (fail closed when the stamp is missing); WRITE_TOKEN is
-//     the admin repair path.
-//   - GET  /<username>/<slug>  — public|unlisted are anonymous; me requires the
-//     Phoenix owner, org requires a same-domain Phoenix identity (Bearer, then
-//     HMAC cookie, then phoenix_ticket). Unauthenticated me/org 302s to
-//     Phoenix login (or 401 JSON if PHOENIX_ID_BASE is unset). 410s (and lazily
-//     deletes) once its expiry has passed. A bucket lifecycle rule is the durable
-//     sweeper; this is the immediate gate.
-//   - GET  /<username>/<slug>?revisions=json — machine-readable history of the
-//     retained prior versions under that slug, newest first.
-//   - GET  /<username>         — public gallery of that user's shares (HTML).
-//   - GET  /<username>?format=json — public machine-readable listing of that user's
-//     ACTIVE shares (`agents artifacts share list`). Same single-segment path as the HTML
-//     gallery and gated on the SAME "does <username>/ hold any object" check, so it
-//     only intercepts a genuine namespace — a legacy flat slug with ?format=json
-//     still serves its real content, never a fake empty listing.
-//   - GET  /<slug>             — backward-compat flat slug (legacy shares before
-//     per-user namespaces).
-//
-// Emitted as a string, so it compiles into `dist/**` and ships with no
-// package.json#files change. `provision.ts` uploads
-// this verbatim as an ES-module Worker with a BUCKET (R2) binding + a WRITE_TOKEN secret.
-/**
- * Render the Worker source. Pure — the R2 binding + token are wired at deploy time.
- *
- * The literal below still spells the CLI `agents share` in its provenance comment,
- * its root response, and its gallery title, even though the command is now
- * `agents artifacts share` (RUSH-2580). That is deliberate: `hashWorkerScript` of
- * this exact text is what `shareTemplateStatus` compares a provisioned endpoint's
- * recorded `templateHash` against, so editing ANY byte here marks every already-
- * deployed endpoint `outdated` — which makes `agents artifacts share list` refuse
- * until its owner re-runs `agents artifacts share update`. Cosmetic renames are not
- * worth that; change this text only alongside a real Worker behavior change.
- */
+import { buildSync } from 'esbuild';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+let bundledWorker;
+let nodeWorkerScript;
+/** Bundle the Worker renderer into an ES module plus workerd-compiled WASM modules. */
+export function renderWorkerBundle() {
+    if (bundledWorker)
+        return bundledWorker;
+    const result = buildSync({
+        stdin: {
+            contents: renderWorkerSource(),
+            loader: 'js',
+            resolveDir: dirname(fileURLToPath(import.meta.url)),
+            sourcefile: 'agents-share-worker.js',
+        },
+        bundle: true,
+        format: 'esm',
+        platform: 'browser',
+        target: 'es2022',
+        write: false,
+        outdir: 'worker-bundle',
+        assetNames: '[name]-[hash]',
+        minify: true,
+        // Fonts are plain data and can live in JavaScript. WASM must remain a
+        // compiled module: workerd deliberately forbids runtime code generation,
+        // so esbuild's `binary` loader produces a bundle that works in Node but
+        // throws "Wasm code generation disallowed by embedder" in Cloudflare.
+        loader: { '.wasm': 'copy', '.woff': 'binary' },
+    });
+    const script = result.outputFiles.find((output) => output.path.endsWith('.js'));
+    if (!script)
+        throw new Error('Worker bundling produced no JavaScript output.');
+    const modules = result.outputFiles
+        .filter((output) => output.path.endsWith('.wasm'))
+        .map((output) => ({
+        name: output.path.split('/').pop(),
+        contentType: 'application/wasm',
+        contents: new Uint8Array(output.contents),
+    }));
+    if (modules.length !== 2) {
+        throw new Error(`Worker bundling produced ${modules.length} WASM modules; expected yoga and resvg.`);
+    }
+    bundledWorker = { script: script.text, modules };
+    return bundledWorker;
+}
+/** Single-file representation for direct Node tests, which cannot import compiled WASM modules. */
 export function renderWorkerScript() {
-    return `// GENERATED by agents-cli agents share setup — do not edit here; edit
+    if (nodeWorkerScript)
+        return nodeWorkerScript;
+    const result = buildSync({
+        stdin: {
+            contents: renderWorkerSource(),
+            loader: 'js',
+            resolveDir: dirname(fileURLToPath(import.meta.url)),
+            sourcefile: 'agents-share-worker.js',
+        },
+        bundle: true,
+        format: 'esm',
+        platform: 'browser',
+        target: 'es2022',
+        write: false,
+        minify: true,
+        loader: { '.wasm': 'binary', '.woff': 'binary' },
+    });
+    const output = result.outputFiles[0];
+    if (!output)
+        throw new Error('Worker test bundling produced no JavaScript output.');
+    nodeWorkerScript = output.text;
+    return nodeWorkerScript;
+}
+/** Unbundled Worker source. Kept separate so esbuild can resolve npm modules. */
+export function renderWorkerSource() {
+    return `import satori, { init as initSatori } from 'satori/wasm';
+import initYoga from 'yoga-wasm-web';
+import { Resvg, initWasm as initResvg } from '@resvg/resvg-wasm';
+import yogaWasm from 'yoga-wasm-web/dist/yoga.wasm';
+import resvgWasm from '@resvg/resvg-wasm/index_bg.wasm';
+import interRegular from '@fontsource/inter/files/inter-latin-400-normal.woff';
+import interBold from '@fontsource/inter/files/inter-latin-700-normal.woff';
+import jetbrainsMono from '@fontsource/jetbrains-mono/files/jetbrains-mono-latin-600-normal.woff';
+
+// GENERATED by agents-cli agents share setup — do not edit here; edit
 // src/lib/share/worker-template.ts and re-run setup.
 export const hooks = {
   verifyPhoenixToken: defaultVerifyPhoenixToken,
+  renderOgCard: renderOgCard,
 };
 
 export default {
@@ -91,6 +103,21 @@ export default {
       return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain' } });
     }
 
+    // POST /__ticket — mint a short-lived, single-navigation login ticket for the
+    // authenticated owner (PHNX-3370). The CLI (which holds the Phoenix bearer)
+    // calls this, then opens the owner's page with ?phoenix_ticket=<t> so the
+    // browser trades it for the __share cookie and the inline visibility control
+    // goes live. The ticket is SELF-signed with the Worker's own HMAC secret — no
+    // external ticket service — and carries the SAME identity authorizeWrite
+    // already proved, so it grants nothing the caller didn't already have.
+    if (request.method === 'POST' && firstSeg === '__ticket') {
+      const auth = await authorizeWrite(request, env);
+      if (auth.error) return auth.error;
+      const ticket = await signSelfTicket({ userId: auth.owner, email: auth.email || '' }, env);
+      if (!ticket) return json({ error: 'ticket minting is not configured' }, 501);
+      return json({ ticket: ticket }, 200);
+    }
+
     if (request.method === 'PUT') {
       const auth = await authorizeWrite(request, env);
       if (auth.error) return auth.error;
@@ -162,6 +189,8 @@ export default {
       const date = readText('date');
       const avatar = readText('avatar');
       const label = readText('label');
+      const ogTitle = readText('og-title');
+      const ogDescription = readText('og-description');
       const labelSource = request.headers.get('x-share-label-source') || '';
       let extraMeta = {};
       // The -u meta companion carries the whole raw object percent-encoded, so a
@@ -210,6 +239,8 @@ export default {
       if (avatar) customMetadata['avatar'] = avatar;
       if (label) customMetadata['label'] = label;
       if (labelSource) customMetadata['label-source'] = labelSource;
+      if (ogTitle) customMetadata['og-title'] = ogTitle;
+      if (ogDescription) customMetadata['og-description'] = ogDescription;
 
       // Revision retention (RUSH-2683): R2 has no native object versioning, so a
       // republish over an EXISTING key first copies the current object to
@@ -238,6 +269,10 @@ export default {
         httpMetadata: { contentType },
         customMetadata,
       });
+      // A managed republish may change the title/description. Invalidate only
+      // its generated sibling so the next crawler receives a fresh card; BYO
+      // publishes send no OG metadata and keep their explicitly uploaded cover.
+      if (ogTitle) await env.BUCKET.delete(path + '.png');
       return json({ ok: true, url: url.origin + '/' + path, expiresAt: expiresAt || null, unlisted: visibility === 'unlisted', visibility }, 200);
     }
 
@@ -263,6 +298,7 @@ export default {
       if (!edit || typeof edit !== 'object') return json({ error: 'PATCH body must be an object' }, 400);
       const metadata = { ...(existing.customMetadata || {}) };
       const previousVisibility = metadata.visibility || 'public';
+      let visibilityChanged = false;
       if (Object.prototype.hasOwnProperty.call(edit, 'label')) {
         if (edit.label !== null && typeof edit.label !== 'string') return json({ error: 'label must be a string or null' }, 400);
         if (typeof edit.label === 'string' && (edit.label.trim() !== edit.label || !edit.label || edit.label.length > 200)) return json({ error: 'label must be 1-200 trimmed characters' }, 400);
@@ -289,6 +325,7 @@ export default {
           }
         }
         metadata.visibility = visibility;
+        visibilityChanged = visibility !== previousVisibility;
         // org_domain is meaningful only for org — set it there, drop the stale
         // value on any move away from org so it can never gate a later read.
         if (visibility === 'org') metadata.org_domain = emailDomain(auth.email);
@@ -327,6 +364,16 @@ export default {
       if (existing.etag) putOpts.onlyIf = { etagMatches: existing.etag };
       const putResult = await env.BUCKET.put(path, existing.body, putOpts);
       if (putResult === null) return json({ error: 'conflict', key: path }, 409);
+      // A generated cover copies the canonical visibility gate into its own R2
+      // metadata. Invalidate it after a successful visibility rewrite so the
+      // next cover GET re-gates and renders from the canonical page. Explicitly
+      // uploaded BYO siblings carry no marker and remain independent assets.
+      if (visibilityChanged) {
+        const cover = await env.BUCKET.get(path + '.png');
+        if (cover && cover.customMetadata && cover.customMetadata['og-generated'] === 'true') {
+          await env.BUCKET.delete(path + '.png');
+        }
+      }
       return json({ ok: true, url: url.origin + '/' + path, label: metadata.label || null, meta: extraMetaOf(metadata), visibility: metadata.visibility || 'public', previousVisibility: previousVisibility }, 200);
     }
 
@@ -383,6 +430,79 @@ export default {
         );
       }
 
+      // Managed OG cover: generated siblings are caches, never visibility
+      // authorities. Gate every request against the current canonical page and
+      // bind each cached render to that page's etag. Re-read after rendering and
+      // after storing so a concurrent PATCH cannot publish a card from the old
+      // visibility/title/description snapshot. Explicit BYO siblings carry no
+      // generated marker and continue through the ordinary object route below.
+      if (segments.length === 2 && path.endsWith('.png')) {
+        let existingCover = await env.BUCKET.get(path);
+        if (!existingCover || (existingCover.customMetadata && existingCover.customMetadata['og-generated'] === 'true')) {
+          const pagePath = path.slice(0, -4);
+          const viewer = await resolveViewer(request, env, url);
+          if (viewer.redirect) return viewer.redirect;
+          for (let attempt = 0; attempt < 3; attempt += 1) {
+            const page = await env.BUCKET.get(pagePath);
+            if (!page) return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain' } });
+            const pageVisibility = (page.customMetadata && page.customMetadata.visibility) || 'public';
+            if (viewer.error && isIdentityGated(pageVisibility)) return viewer.error;
+            const denied = gateVisibility(url, env, page, viewer.identity || null);
+            if (denied) return denied;
+
+            if (existingCover && existingCover.customMetadata['og-source-etag'] === page.etag) {
+              const current = await env.BUCKET.get(pagePath);
+              if (!current || current.etag !== page.etag) { existingCover = null; continue; }
+              const currentDenied = gateVisibility(url, env, current, viewer.identity || null);
+              if (currentDenied) return currentDenied;
+              return new Response(request.method === 'HEAD' ? null : existingCover.body, {
+                status: 200,
+                headers: managedCoverHeaders(pageVisibility),
+              });
+            }
+
+            const pageHtml = await page.text();
+            const meta = page.customMetadata || {};
+            let png;
+            try {
+              png = await hooks.renderOgCard({
+                title: meta['og-title'] || extractHtmlMeta(pageHtml, 'title') || meta.label || segments[1],
+                description: meta['og-description'] || extractHtmlMeta(pageHtml, 'description') || '',
+                handle: segments[0],
+                visibility: pageVisibility,
+                orgDomain: meta.org_domain || '',
+              });
+            } catch (error) {
+              const detail = error instanceof Error ? error.message : String(error);
+              return new Response('OG card render failed: ' + detail, {
+                status: 500,
+                headers: { 'content-type': 'text/plain; charset=utf-8' },
+              });
+            }
+            const beforeStore = await env.BUCKET.get(pagePath);
+            if (!beforeStore || beforeStore.etag !== page.etag) { existingCover = null; continue; }
+            await env.BUCKET.put(path, png, {
+              httpMetadata: { contentType: 'image/png' },
+              customMetadata: { ...meta, 'og-generated': 'true', 'og-source-etag': page.etag },
+            });
+            const beforeServe = await env.BUCKET.get(pagePath);
+            if (!beforeServe || beforeServe.etag !== page.etag) {
+              const justStored = await env.BUCKET.get(path);
+              if (justStored && justStored.customMetadata && justStored.customMetadata['og-source-etag'] === page.etag) {
+                await env.BUCKET.delete(path);
+              }
+              existingCover = null;
+              continue;
+            }
+            return new Response(request.method === 'HEAD' ? null : png, {
+              status: 200,
+              headers: managedCoverHeaders(pageVisibility),
+            });
+          }
+          return new Response('cover changed during rendering; retry', { status: 503, headers: { 'content-type': 'text/plain', 'retry-after': '1' } });
+        }
+      }
+
       const obj = await env.BUCKET.get(path);
       if (!obj) return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain' } });
       const expiresAt = obj.customMetadata && obj.customMetadata['expires-at'];
@@ -694,7 +814,7 @@ async function renderRevisions(bucket, origin, key, method, identityGated) {
 // before it ever reaches this Worker; see RESERVED_META_KEYS in publish.ts).
 // One list, reused both to strip a same-named --meta collision on write and
 // to split arbitrary --meta entries back out on read.
-var RESERVED_METADATA_KEYS = ['expires-at', 'published-at', 'visibility', 'owner', 'org_domain', 'agent', 'session', 'host', 'repo', 'date', 'avatar', 'label', 'label-source'];
+var RESERVED_METADATA_KEYS = ['expires-at', 'published-at', 'visibility', 'owner', 'org_domain', 'agent', 'session', 'host', 'repo', 'date', 'avatar', 'label', 'label-source', 'og-title', 'og-description', 'og-generated', 'og-source-etag'];
 var PUBLIC_INBOX_DOMAINS = ['gmail.com', 'googlemail.com', 'outlook.com', 'hotmail.com', 'live.com', 'icloud.com', 'me.com'];
 var SHARE_COOKIE = '__Host-phoenix_share';
 var SHARE_COOKIE_MAX_AGE = 604800;
@@ -1140,6 +1260,18 @@ function isIdentityGated(visibility) {
   return visibility === 'me' || visibility === 'org';
 }
 
+function managedCoverHeaders(visibility) {
+  const headers = new Headers({ 'content-type': 'image/png' });
+  if (isIdentityGated(visibility)) {
+    headers.set('cache-control', 'private, no-store');
+    headers.set('X-Robots-Tag', 'noindex');
+  } else {
+    headers.set('cache-control', 'public, max-age=31536000, immutable');
+    if (visibility === 'unlisted') headers.set('X-Robots-Tag', 'noindex');
+  }
+  return headers;
+}
+
 // Gate a me/org read given the ALREADY-RESOLVED viewer identity. Pure/sync: the
 // caller resolves the viewer once (it also needs the identity for the ownership
 // check) and both the page GET and the ?revisions=json path share this gate.
@@ -1257,6 +1389,66 @@ async function signShareCookie(identity, env) {
   return SHARE_COOKIE + '=' + value + '; HttpOnly; Secure; Path=/; SameSite=Lax; Max-Age=' + SHARE_COOKIE_MAX_AGE;
 }
 
+// A short-lived login ticket, self-signed with the same HMAC secret as the cookie
+// but DOMAIN-SEPARATED (the signature covers a 'ticket:'-prefixed payload), so a
+// ticket value can never be replayed as a cookie value or vice versa. It rides in
+// the ?phoenix_ticket= param for exactly one navigation; resolveViewer verifies it
+// locally and exchanges it for the __share cookie. TTL is deliberately tiny — it
+// only has to survive the round-trip from CLI mint to the browser opening the URL.
+var SELF_TICKET_MAX_AGE = 120;
+
+async function signSelfTicket(identity, env) {
+  const secret = typeof env.WRITE_TOKEN === 'string' ? env.WRITE_TOKEN : '';
+  if (!secret || !identity || !identity.userId) return '';
+  const exp = Math.floor(Date.now() / 1000) + SELF_TICKET_MAX_AGE;
+  const payload = identity.userId + '|' + (identity.email || '') + '|' + exp;
+  const sig = await hmacHex(secret, 'ticket:' + payload);
+  return toB64Url(payload) + '.' + sig;
+}
+
+async function verifySelfTicket(ticket, env) {
+  const secret = typeof env.WRITE_TOKEN === 'string' ? env.WRITE_TOKEN : '';
+  if (!secret || !ticket) return null;
+  const dot = ticket.lastIndexOf('.');
+  if (dot < 1) return null;
+  let payload;
+  try {
+    payload = fromB64Url(ticket.slice(0, dot));
+  } catch {
+    return null;
+  }
+  const sig = ticket.slice(dot + 1);
+  const expected = await hmacHex(secret, 'ticket:' + payload);
+  if (!safeEqual(sig, expected)) return null;
+  const first = payload.indexOf('|');
+  const last = payload.lastIndexOf('|');
+  if (first < 0 || last <= first) return null;
+  const userId = payload.slice(0, first);
+  const email = payload.slice(first + 1, last);
+  const exp = Number(payload.slice(last + 1));
+  if (!userId || !Number.isFinite(exp) || Math.floor(Date.now() / 1000) > exp) return null;
+  return { userId: userId, email: email };
+}
+
+// Single-use enforcement for a self-signed ticket: claim its signature the first
+// time it is redeemed, and reject any later presentation of the same ticket. The
+// HMAC + short TTL stop forgery and bound the window, but without this a ticket the
+// CLI printed (--json / --no-open / a browser-open failure) could be replayed by
+// anyone who captured that output before it expired, minting the owner's 7-day
+// cookie a second time. Get-then-put mirrors claimHandle's one-time-claim pattern;
+// the marker rides a __-prefixed key (GET-blocked, excluded from every listing).
+async function consumeSelfTicket(env, sig) {
+  if (!sig) return false;
+  const key = '__ticket-used/' + sig;
+  const existing = await env.BUCKET.get(key);
+  if (existing) return false;
+  await env.BUCKET.put(key, '1', {
+    httpMetadata: { contentType: 'text/plain' },
+    customMetadata: { visibility: 'unlisted' },
+  });
+  return true;
+}
+
 async function identityFromCookie(request, env) {
   const secret = typeof env.WRITE_TOKEN === 'string' ? env.WRITE_TOKEN : '';
   if (!secret) return null;
@@ -1316,7 +1508,17 @@ async function resolveViewer(request, env, url) {
   if (cookieId) return { identity: cookieId };
   const ticket = url.searchParams.get('phoenix_ticket');
   if (!ticket) return {};
-  const redeemed = await redeemTicket(ticket, env);
+  // Prefer the locally-verifiable self-signed ticket (PHNX-3370, no network), and
+  // enforce single use by claiming its signature on first redemption — a captured
+  // ticket replayed within its TTL finds it already spent. Fall back to the
+  // external identity-server redeem for tickets it issued.
+  let redeemed = await verifySelfTicket(ticket, env);
+  if (redeemed) {
+    const sig = ticket.slice(ticket.lastIndexOf('.') + 1);
+    if (!(await consumeSelfTicket(env, sig))) redeemed = null;
+  } else {
+    redeemed = await redeemTicket(ticket, env);
+  }
   if (!redeemed) return { error: json({ error: 'invalid ticket' }, 401) };
   const cookie = await signShareCookie(redeemed, env);
   if (!cookie) return { error: json({ error: 'phoenix login is not configured' }, 401) };
@@ -1327,6 +1529,61 @@ async function resolveViewer(request, env, url) {
   return { redirect: new Response(null, { status: 302, headers: headers }) };
 }
 
+function extractHtmlMeta(html, field) {
+  const pattern = field === 'title'
+    ? /<title[^>]*>([\\s\\S]*?)<\\/title>/i
+    : /<meta[^>]+(?:name|property)=["'](?:description|og:description)["'][^>]+content=["']([^"']*)["'][^>]*>/i;
+  const match = pattern.exec(html);
+  return match ? match[1].replace(/<[^>]*>/g, '').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').trim() : '';
+}
+
+let rendererReady;
+async function renderOgCard(input) {
+  if (!rendererReady) {
+    rendererReady = Promise.all([
+      initYoga(yogaWasm).then(function (yoga) { initSatori(yoga); }),
+      initResvg(resvgWasm),
+    ]);
+  }
+  await rendererReady;
+  const visibilityLabels = {
+    public: 'PUBLIC',
+    unlisted: 'UNLISTED',
+    me: 'ONLY YOU',
+    org: input.orgDomain ? 'ANYONE AT ' + input.orgDomain.toUpperCase() : 'ORGANIZATION',
+  };
+  const node = {
+    type: 'div',
+    props: {
+      style: { width: '100%', height: '100%', display: 'flex', flexDirection: 'column', background: '#0a0a0a', color: '#f5f5f5', padding: '68px 76px 58px', fontFamily: 'Inter' },
+      children: [
+        { type: 'div', props: { style: { display: 'flex', color: '#a3e635', fontFamily: 'JetBrains Mono', fontSize: 25, fontWeight: 600, letterSpacing: '-0.5px' }, children: 'AGI · agents-cli.sh' } },
+        { type: 'div', props: { style: { display: 'flex', flexDirection: 'column', flexGrow: 1, justifyContent: 'center', maxWidth: 1050 }, children: [
+          { type: 'div', props: { style: { display: 'flex', fontSize: 66, lineHeight: 1.06, fontWeight: 700, letterSpacing: '-2.8px', maxHeight: 218, overflow: 'hidden' }, children: input.title || 'Shared artifact' } },
+          input.description ? { type: 'div', props: { style: { display: 'flex', marginTop: 24, color: '#a3a3a3', fontSize: 27, lineHeight: 1.35, maxHeight: 74, overflow: 'hidden' }, children: input.description } } : null,
+        ].filter(Boolean) } },
+        { type: 'div', props: { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', borderTop: '1px solid #262626', paddingTop: 25, fontSize: 21, color: '#a3a3a3' }, children: [
+          { type: 'div', props: { style: { display: 'flex' }, children: [
+            { type: 'span', props: { style: { color: '#737373' }, children: 'shared by ' } },
+            { type: 'span', props: { style: { marginLeft: 7, color: '#f5f5f5', fontWeight: 700 }, children: '@' + input.handle } },
+          ] } },
+          { type: 'div', props: { style: { display: 'flex', border: '1px solid #3f3f46', borderRadius: 999, padding: '9px 17px', color: '#d4d4d8', fontFamily: 'JetBrains Mono', fontSize: 16, letterSpacing: '1px' }, children: visibilityLabels[input.visibility] || 'PUBLIC' } },
+        ] } },
+      ],
+    },
+  };
+  const svg = await satori(node, {
+    width: 1200,
+    height: 630,
+    fonts: [
+      { name: 'Inter', data: interRegular, weight: 400, style: 'normal' },
+      { name: 'Inter', data: interBold, weight: 700, style: 'normal' },
+      { name: 'JetBrains Mono', data: jetbrainsMono, weight: 600, style: 'normal' },
+    ],
+  });
+  return new Resvg(svg, { fitTo: { mode: 'width', value: 1200 } }).render().asPng();
+}
+
 async function defaultVerifyPhoenixToken(request, env) {
   const presented = (request.headers.get('authorization') || '').replace(/^Bearer\\s+/i, '');
   if (!presented) return null;

package/dist/lib/view-types.d.ts

@@ -21,7 +21,12 @@ export interface ViewJsonVersion {
         amount: number;
         currency: string;
     } | null;
-    /** Human-readable usage refresh error, when the live refresh could not populate a snapshot. */
+    /**
+     * Human-readable reason a usage snapshot is absent: a live-refresh failure, or
+     * (without `--refresh`, on a never-cached account) a plain "not collected yet"
+     * pending state. Always a full sentence — never the internal `'stale'` cache
+     * sentinel, which `usageErrorForDisplay` normalizes away (PHNX-3348).
+     */
     usageError?: string | null;
     windows: Array<{
         key: 'session' | 'week' | 'sonnet_week' | 'month';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.54",
+  "version": "1.22.56",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
@@ -86,8 +86,11 @@
     "@homebridge/node-pty-prebuilt-multiarch"
   ],
   "dependencies": {
+    "@fontsource/inter": "^5.3.0",
+    "@fontsource/jetbrains-mono": "^5.3.0",
     "@homebridge/node-pty-prebuilt-multiarch": "0.13.1",
     "@inquirer/prompts": "8.5.2",
+    "@resvg/resvg-wasm": "^2.6.2",
     "@types/proper-lockfile": "4.1.4",
     "@xterm/headless": "6.0.0",
     "@zed-industries/agent-client-protocol": "0.4.5",
@@ -98,17 +101,20 @@
     "commander": "15.0.0",
     "croner": "10.0.1",
     "diff": "9.0.0",
+    "esbuild": "^0.28.2",
     "lru-cache": "11.5.2",
     "marked": "15.0.12",
     "marked-terminal": "7.3.0",
     "ora": "9.4.1",
     "proper-lockfile": "4.1.2",
+    "satori": "0.12.2",
     "shlex": "3.0.0",
     "simple-git": "3.36.0",
     "smol-toml": "1.7.0",
     "unbash": "4.0.5",
     "ws": "^8.21.0",
-    "yaml": "2.9.0"
+    "yaml": "2.9.0",
+    "yoga-wasm-web": "^0.3.3"
   },
   "devDependencies": {
     "@types/diff": "8.0.0",