clay-server 5.2.0-beta.9 → 5.2.1-beta.1

package/lib/public/modules/vendor-usage-overview.js

@@ -0,0 +1,323 @@
+// vendor-usage-overview.js - Top-bar usage overview for every tracked vendor.
+//
+// This is a read-only projection of the owner-scoped `vendor_usage_overview`
+// message. It sits beside the existing active-session usage pill and never
+// touches rejection, warning or scheduling state in app-rate-limit.js.
+
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+import { iconHtml, refreshIcons } from './icons.js';
+import { overviewVendors, allVendors } from './vendor-usage-model.js';
+import { fillListPopover } from './vendor-usage-list.js';
+
+var LIST_KEY = "__all";
+
+var groupEl = null;
+var records = {};
+var tickTimer = null;
+var outsideHandler = null;
+var keyHandler = null;
+var blurHandler = null;
+var requestCounter = 0;
+var pendingRequestId = null;
+
+// `refresh` asks the server to read account usage for vendors that support it;
+// the server caches, so repeating it is cheap. Replies echo the request id.
+function requestOverview(refresh) {
+  var ws = getWs();
+  if (!ws || ws.readyState !== 1) return;
+  pendingRequestId = "vu-" + (++requestCounter) + "-" + Date.now().toString(36);
+  var message = { type: "vendor_usage_get", slug: store.get('currentSlug') || undefined, requestId: pendingRequestId };
+  if (refresh) message.refresh = true;
+  ws.send(JSON.stringify(message));
+}
+
+// A reply is shown only for the project, user and request it was asked for.
+// A delayed reply from before a project or account change is dropped.
+export function handleVendorUsageOverview(msg) {
+  if (!msg || msg.error) return;
+  var slug = store.get('currentSlug');
+  if (slug && msg.slug !== slug) return;
+  if ((msg.userId || null) !== (store.get('myUserId') || null)) return;
+  if (msg.requestId !== undefined && msg.requestId !== pendingRequestId) return;
+  var vendors = Array.isArray(msg.vendors) ? msg.vendors : [];
+  store.set({ vendorUsageOverview: { slug: msg.slug, serverNowMs: msg.serverNowMs, receivedAtMs: Date.now(), vendors: vendors } });
+}
+
+function el(tag, className, text) {
+  var node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function closePopover(restoreFocus) {
+  var open = store.get('vendorUsageOpen');
+  if (!open) return;
+  store.set({ vendorUsageOpen: null });
+  var record = records[open];
+  if (restoreFocus && record && typeof record.chip.focus === "function") record.chip.focus();
+}
+
+function sourceNote(view) {
+  var note = view.lastObservedText ? "Latest report " + view.lastObservedText : "Not observed yet in this project";
+  if (view.sourceSessionId !== null && view.sourceSessionId !== undefined) note += " from session #" + view.sourceSessionId;
+  note += ".";
+  if (view.otherSourceCount > 0) note += " " + view.otherSourceCount + " other session" + (view.otherSourceCount === 1 ? "" : "s") + " reported separately and are not combined.";
+  return note;
+}
+
+function ensurePopover(record, view) {
+  if (!record.pop) {
+    var pop = el("div", "vendor-usage-popover");
+    pop.setAttribute("role", "dialog");
+    record.title = el("div", "vendor-usage-popover-title");
+    record.rows = el("div", "vendor-usage-rows");
+    record.notes = el("div", "vendor-usage-notes");
+    pop.appendChild(record.title);
+    pop.appendChild(record.rows);
+    pop.appendChild(record.notes);
+    // The link is created once and only updated, so keyboard focus on it
+    // survives refreshes.
+    record.link = el("a", "vendor-usage-link");
+    record.link.target = "_blank";
+    record.link.rel = "noopener";
+    record.linkLabel = el("span", "", "Open usage dashboard");
+    record.link.appendChild(record.linkLabel);
+    record.link.insertAdjacentHTML("beforeend", iconHtml("external-link"));
+    pop.appendChild(record.link);
+    record.item.appendChild(pop);
+    record.pop = pop;
+  }
+  record.pop.setAttribute("aria-label", view.name + " usage");
+  record.title.textContent = view.name;
+  record.rows.textContent = "";
+  view.rows.forEach(function (row) {
+    var line = el("div", "vendor-usage-row" + (row.warning ? " warning" : "") + (row.stale ? " stale" : ""));
+    line.appendChild(el("span", "vendor-usage-row-label", row.label));
+    var parts = [];
+    if (row.source === "account") { if (row.value) parts.push(row.value); } else if (row.percentText) parts.push(row.percentText);
+    if (row.resetText) parts.push("resets in " + row.resetText);
+    var value = el("span", "vendor-usage-row-value");
+    value.appendChild(el("span", "", parts.length ? parts.join(" \u00b7 ") : "Limit window"));
+    var origin = row.source === "account" ? "account, " : (row.origin === "history" ? "session record, " : "session, ");
+    value.appendChild(el("span", "vendor-usage-row-age", origin + row.observedText + (row.stale ? " (stale)" : "") + (row.origin === "history" ? " (earlier session record)" : "")));
+    line.appendChild(value);
+    record.rows.appendChild(line);
+  });
+  record.notes.textContent = "";
+  if (view.status) record.notes.appendChild(el("div", "vendor-usage-note", view.status));
+  if (view.accountCount > 0 && view.accountSource) record.notes.appendChild(el("div", "vendor-usage-note", "Account figures: " + view.accountSource + ". Units are the vendor's own and are not converted."));
+  if (view.observedCount > 0) {
+    record.notes.appendChild(el("div", "vendor-usage-note", sourceNote(view)));
+    record.notes.appendChild(el("div", "vendor-usage-note", "Session rows come from your own sessions in this project; another account or session may differ."));
+  }
+  if (view.href) {
+    if (record.link.getAttribute("href") !== view.href) record.link.href = view.href;
+    record.link.title = view.linkTitle || "";
+    record.link.style.display = "";
+  } else {
+    record.link.style.display = "none";
+  }
+}
+
+function removePopover(record) {
+  if (record.pop) { record.pop.remove(); record.pop = null; }
+}
+
+// The popover is absolutely positioned under its chip, right-aligned; a measured
+// shift keeps it inside the viewport.
+function placePopover(pop) {
+  if (typeof pop.getBoundingClientRect !== "function") return;
+  pop.style.marginRight = "";
+  var bounds = pop.getBoundingClientRect();
+  var viewport = document.documentElement.clientWidth;
+  var shift = bounds.left < 8 ? 8 - bounds.left : Math.min(0, viewport - 8 - bounds.right);
+  if (shift) pop.style.marginRight = (-shift) + "px";
+}
+
+function shellWindow() { return typeof window !== "undefined" ? window : null; }
+
+function bindDismissal(open) {
+  if (open && !outsideHandler) {
+    outsideHandler = function (event) {
+      if (groupEl && !groupEl.contains(event.target)) closePopover(false);
+    };
+    keyHandler = function (event) {
+      if (event.key === "Escape") { closePopover(true); }
+    };
+    // A click inside a split pane or contextual iframe never reaches this
+    // document; focus moving into the frame blurs the shell window instead.
+    blurHandler = function () {
+      if (document.activeElement && document.activeElement.tagName === "IFRAME") closePopover(false);
+    };
+    document.addEventListener("pointerdown", outsideHandler, true);
+    document.addEventListener("keydown", keyHandler, true);
+    if (shellWindow()) shellWindow().addEventListener("blur", blurHandler);
+  } else if (!open && outsideHandler) {
+    document.removeEventListener("pointerdown", outsideHandler, true);
+    document.removeEventListener("keydown", keyHandler, true);
+    if (blurHandler && shellWindow()) shellWindow().removeEventListener("blur", blurHandler);
+    outsideHandler = null;
+    keyHandler = null;
+    blurHandler = null;
+  }
+}
+
+function removeGroup() {
+  if (groupEl) { groupEl.remove(); groupEl = null; }
+  records = {};
+  bindDismissal(false);
+  if (tickTimer) { clearInterval(tickTimer); tickTimer = null; }
+}
+
+function createRecord(view) {
+  var item = el("span", "vendor-usage-item");
+  var chip = el("button", "top-bar-pill vendor-usage-chip");
+  chip.type = "button";
+  chip.setAttribute("data-vendor", view.vendor);
+  chip.setAttribute("aria-haspopup", "dialog");
+  var record = { item: item, chip: chip, icon: null, text: el("span", "vendor-usage-chip-text"), pop: null };
+  chip.appendChild(record.text);
+  chip.addEventListener("click", function () {
+    var opening = store.get('vendorUsageOpen') !== view.vendor;
+    store.set({ vendorUsageOpen: opening ? view.vendor : null });
+    if (opening) requestOverview(true);
+  });
+  item.appendChild(chip);
+  return record;
+}
+
+function updateChip(record, view, open) {
+  record.chip.className = "top-bar-pill vendor-usage-chip " + (view.warning ? "pill-warning" : "pill-dim") + (view.known ? "" : " unknown") + (view.stale ? " stale" : "");
+  record.chip.setAttribute("aria-expanded", open ? "true" : "false");
+  record.chip.setAttribute("aria-label", view.summary + ". Show details");
+  record.chip.title = view.summary;
+  if (view.icon) {
+    if (!record.icon) {
+      record.icon = el("img", "usage-check-vendor-icon");
+      record.icon.alt = "";
+      record.chip.insertBefore(record.icon, record.text);
+    }
+    if (record.icon.getAttribute("src") !== view.icon) record.icon.setAttribute("src", view.icon);
+  }
+  if (record.text.textContent !== view.text) record.text.textContent = view.text;
+}
+
+function updateListChip(record, listViews, open) {
+  var known = listViews.filter(function (view) { return view.known; }).length;
+  var summary = "Usage for " + listViews.length + " vendor" + (listViews.length === 1 ? "" : "s") + ", " + known + " with figures";
+  record.chip.className = "top-bar-pill vendor-usage-chip vendor-usage-list-chip pill-dim";
+  record.chip.setAttribute("aria-expanded", open ? "true" : "false");
+  record.chip.setAttribute("aria-label", summary + ". Show all vendors");
+  record.chip.title = summary;
+  if (!record.icon) {
+    record.icon = el("span", "vendor-usage-list-icon");
+    record.icon.insertAdjacentHTML("beforeend", iconHtml("gauge"));
+    record.chip.insertBefore(record.icon, record.text);
+  }
+  var text = known + "/" + listViews.length;
+  if (record.text.textContent !== text) record.text.textContent = text;
+}
+
+function ensureListPopover(record, listViews) {
+  if (!record.pop) {
+    var pop = el("div", "vendor-usage-popover vendor-usage-list-popover");
+    pop.setAttribute("role", "dialog");
+    pop.setAttribute("aria-label", "Usage by vendor");
+    record.title = el("div", "vendor-usage-popover-title", "Usage by vendor");
+    record.rows = el("div", "vendor-usage-rows");
+    pop.appendChild(record.title);
+    pop.appendChild(record.rows);
+    record.item.appendChild(pop);
+    record.pop = pop;
+  }
+  fillListPopover(record.rows, listViews, el);
+}
+
+// Updates stable elements in place. Chips, the popover and its link are never
+// recreated while they stay relevant, so focus survives refreshes.
+export function renderVendorUsageOverview() {
+  var actions = document.querySelector("#top-bar .top-bar-actions");
+  if (!actions) return;
+  var overview = store.get('vendorUsageOverview');
+  var info = store.get('vendorInfo');
+  var views = overviewVendors(info, overview, Date.now());
+  var listViews = allVendors(info, overview, Date.now());
+  if (listViews.length === 0) {
+    if (store.get('vendorUsageOpen')) store.set({ vendorUsageOpen: null });
+    removeGroup();
+    return;
+  }
+  var open = store.get('vendorUsageOpen');
+  if (open && open !== LIST_KEY && !views.some(function (view) { return view.vendor === open; })) {
+    open = null;
+    store.set({ vendorUsageOpen: null });
+  }
+  if (!groupEl) {
+    groupEl = el("div", "vendor-usage-overview");
+    groupEl.id = "vendor-usage-overview";
+    groupEl.setAttribute("role", "group");
+    groupEl.setAttribute("aria-label", "Vendor usage");
+  }
+  var anchor = document.getElementById("rate-limit-usage-link") || document.getElementById("skip-perms-pill");
+  if (groupEl.parentNode !== actions || groupEl.nextSibling !== anchor) actions.insertBefore(groupEl, anchor);
+  var present = {};
+  views.forEach(function (view, index) {
+    present[view.vendor] = true;
+    var record = records[view.vendor] || (records[view.vendor] = createRecord(view));
+    if (groupEl.children[index] !== record.item) groupEl.insertBefore(record.item, groupEl.children[index] || null);
+    updateChip(record, view, open === view.vendor);
+    if (open === view.vendor) {
+      var created = !record.pop;
+      ensurePopover(record, view);
+      placePopover(record.pop);
+      if (created) bindDismissal(true);
+    } else {
+      removePopover(record);
+    }
+  });
+  // The list entry is always last and reaches every installed vendor.
+  present[LIST_KEY] = true;
+  var listRecord = records[LIST_KEY] || (records[LIST_KEY] = createRecord({ vendor: LIST_KEY }));
+  if (groupEl.children[views.length] !== listRecord.item) groupEl.insertBefore(listRecord.item, groupEl.children[views.length] || null);
+  updateListChip(listRecord, listViews, open === LIST_KEY);
+  if (open === LIST_KEY) {
+    var listCreated = !listRecord.pop;
+    ensureListPopover(listRecord, listViews);
+    placePopover(listRecord.pop);
+    if (listCreated) bindDismissal(true);
+  } else {
+    removePopover(listRecord);
+  }
+  Object.keys(records).forEach(function (vendor) {
+    if (present[vendor]) return;
+    records[vendor].item.remove();
+    delete records[vendor];
+  });
+  if (!open) bindDismissal(false);
+  refreshIcons();
+  // Relative times only change slowly; one light timer keeps them honest.
+  if (!tickTimer) tickTimer = setInterval(renderVendorUsageOverview, 30000);
+}
+
+export function initVendorUsageOverview() {
+  store.subscribe(function (state, prev) {
+    var identityChanged = state.currentSlug !== prev.currentSlug || state.myUserId !== prev.myUserId;
+    if (identityChanged) {
+      // Another project or account must start unknown and ignore any reply
+      // that was requested before the change.
+      pendingRequestId = null;
+      if (state.vendorUsageOverview) {
+        store.set({ vendorUsageOverview: null, vendorUsageOpen: null });
+        if (state.connected) requestOverview(true);
+        return;
+      }
+    }
+    if (state.connected && (!prev.connected || identityChanged)) requestOverview(true);
+    if (state.vendorUsageOverview !== prev.vendorUsageOverview || state.vendorInfo !== prev.vendorInfo
+        || state.currentVendor !== prev.currentVendor || state.vendorUsageOpen !== prev.vendorUsageOpen) {
+      renderVendorUsageOverview();
+    }
+  });
+}

package/lib/public/style.css

@@ -6,23 +6,23 @@
 @import url("css/linear.css");
 @import url("css/base.css?v=20260828-type1");
 @import url("css/icon-strip.css?v=20260828-surfaces4");
-@import url("css/title-bar.css?v=20260828-project-header1");
+@import url("css/title-bar.css?v=20261018-workbench-controls2");
 @import url("css/clay-workspace.css?v=20261010-tint");
 @import url("css/pane.css");
 @import url("css/worker-proposal.css");
 @import url("css/workspace-assignment.css");
 @import url("css/session-actions.css?v=20260828-contrast1");
-@import url("css/sidebar.css?v=20260828-session-list3");
+@import url("css/sidebar.css?v=20261018-quick-appearance");
 @import url("css/session-folders.css");
-@import url("css/overlays.css?v=20260827-brand3");
+@import url("css/overlays.css?v=20261018-topbar-gap");
 @import url("css/menus.css");
-@import url("css/messages.css?v=20260828-delegated-muted1");
+@import url("css/messages.css?v=20261018-worker-notice");
 @import url("css/generated-images.css?v=20260829-save-details1");
 @import url("css/rewind.css");
 @import url("css/elicitation-form.css");
 @import url("css/input.css?v=20261002-stop-inline1");
 @import url("css/pending-message-queue.css?v=20260914-queue1");
-@import url("css/filebrowser.css?v=20260829-terminal-canvas1");
+@import url("css/filebrowser.css?v=20261018-workbench-region");
 @import url("css/git-panel.css");
 @import url("css/git-placard.css");
 @import url("css/diff.css");
@@ -53,7 +53,7 @@
 @import url("css/session-search.css");
 @import url("css/tooltip.css");
 @import url("css/mates.css?v=20260407");
-@import url("css/command-palette.css?v=20260910-ask-clay-controls1");
+@import url("css/command-palette.css?v=20261018-topbar-gap");
 @import url("css/mention.css");
 @import url("css/debate.css");
 @import url("css/home-debate-planning.css");
@@ -61,21 +61,22 @@
 @import url("css/home-mate-settings.css");
 @import url("css/mate-avatar-gallery.css");
 @import url("css/home-mate-model-picker.css");
-@import url("css/project-mate-creation.css");
+@import url("css/project-mate-creation.css?v=20261018-clay-choices");
 @import url("css/home-debate-live.css");
 @import url("css/notifications-center.css");
 @import url("css/tui-attention.css?v=20260829-terminal-canvas1");
 @import url("css/pwa-mobile.css?v=20260824f");
 @import url("css/avatar-imprints.css?v=20260829-imprints1");
 
-@import url("css/projects-hub.css");
+@import url("css/projects-hub.css?v=20261018-welcome-art");
+@import url("css/project-start.css");
 
 @import url("./css/shared-browser.css");
 
 @import url("./css/mcp-skills-workbench.css");
 @import url("css/skills-workbench.css");
 
-@import url("css/right-workbench.css");
+@import url("css/right-workbench.css?v=20261018-workbench-region");
 
 @import url("css/mate-conversation.css");
 
@@ -88,7 +89,9 @@
 @import url("css/server-settings-system.css");
 
 @import url("css/project-settings-modal.css");
+@import url("css/settings-shell.css");
 
 @import url("css/clay-tool-activity.css");
 
-@import url("css/contextual-clay.css");
+@import url("css/contextual-clay.css?v=20261018-loading-scene");
+@import url("css/mate-loading-scene.css");

package/lib/sdk-bridge.js

@@ -731,6 +731,7 @@ function createSDKBridge(opts) {
       "mcp__clay-workspace__read_workspace_receipt": true,
       "mcp__clay-workspace__inspect_workspace_change": true,
       "mcp__clay-workspace__control_project_workspace": true,
+      "mcp__clay-workspace__read_vendor_usage": true,
       "mcp__clay-workspace__read_project_records": true,
       "mcp__clay-workspace__inspect_project_record_change": true,
       "mcp__clay-workspace__control_project_records": true,
@@ -1734,6 +1735,9 @@ function createSDKBridge(opts) {
     var hasSharedBrowserCatalog = sessionToolDefs.some(function (definition) { return definition.name === "shared_browser"; });
     var recoverBrowserTools = needsCatalogRecovery("browser", 6) && hasSharedBrowserCatalog;
     var recoverIssueTools = needsCatalogRecovery("issues", 1) && hasIssueCatalog;
+    var notesCatalogVersion = require("./session-notes-mcp-server").CATALOG_VERSION;
+    var hasNotesCatalog = sessionToolDefs.some(function (definition) { return definition.name === "write_note"; });
+    var recoverNoteTools = needsCatalogRecovery("notes", notesCatalogVersion) && hasNotesCatalog;
     function queryContextAvailable() {
       if (queryRetired()) return false;
       if (Number(session._sdkQueryGeneration || 0) !== queryGeneration) return false;
@@ -1929,7 +1933,7 @@ function createSDKBridge(opts) {
       dynamicTools: sessionToolDefs,
       // Conversation-scoped catalogs persist definitions. A stale authorized Driver
       // gets this exact-query bridge; its handlers still reauthorize live.
-      sessionMcpServer: (recoverMateSchedules || recoverIssueTools || recoverQuestionTools || recoverBrowserTools || recoverLinearTools || recoverYouTools || recoverExternalTools) ? getSessionMcpServer(session, queryGeneration) : undefined,
+      sessionMcpServer: (recoverMateSchedules || recoverIssueTools || recoverQuestionTools || recoverBrowserTools || recoverLinearTools || recoverYouTools || recoverExternalTools || recoverNoteTools) ? getSessionMcpServer(session, queryGeneration) : undefined,
       onRecoveryAdmission: function(waiting) {
         if (!queryContextAvailable()) return;
         if (waiting) session._providerRecoveryWaiting = queryGeneration;
@@ -2177,6 +2181,7 @@ function createSDKBridge(opts) {
       if (hasLinearCatalog) markCatalog("linear", 1);
       if (hasSharedBrowserCatalog) markCatalog("browser", 6);
       if (hasIssueCatalog) markCatalog("issues", 1);
+      if (hasNotesCatalog) markCatalog("notes", notesCatalogVersion);
     }
     session.streamPromise = processQueryStream(session, catalogCandidate, queryContract).catch(function(err) {
     });

package/lib/sdk-message-processor.js

@@ -46,6 +46,10 @@ function attachMessageProcessor(ctx) {
     sm.sendAndRecord(session, obj, clientObj);
   }
 
+  function observeQuota(session, message, observedAtMs) {
+    if (typeof sm.notifyQuotaObserved === "function") sm.notifyQuotaObserved(session, message, observedAtMs);
+  }
+
   function recordTurnActivity(session, activity) {
     // An authoritative input card owns progress until its request settles.
     var awaitingInput = ["pendingPermissions", "pendingAskUser", "pendingElicitations", "pendingUserDialogs"].some(function (key) {
@@ -892,7 +896,7 @@ function attachMessageProcessor(ctx) {
     } else if (parsed.yokeType === "rate_limit") {
       var info = parsed.rateLimitInfo;
       if (info.source === "account_snapshot") {
-        quotaSnapshots.recordQuotaSnapshot(session, info, sendAndRecord);
+        quotaSnapshots.recordQuotaSnapshot(session, info, sendAndRecord, observeQuota);
         return;
       }
       console.log("[sdk-bridge] rate_limit_event for session " + session.localId + ": status=" + info.status + " resetsAt=" + info.resetsAt + " isUsingOverage=" + info.isUsingOverage + " isProcessing=" + session.isProcessing);
@@ -907,6 +911,7 @@ function attachMessageProcessor(ctx) {
           resetsAt: info.resetsAt * 1000,
           status: info.status,
         });
+        observeQuota(session, { type: "rate_limit_usage", vendor: session.vendor || "claude", rateLimitType: info.rateLimitType, resetsAt: info.resetsAt * 1000, status: info.status }, Date.now());
       }
 
       // Warning/rejection handling (existing behavior)
@@ -925,6 +930,9 @@ function attachMessageProcessor(ctx) {
           overageResetsAt: info.overageResetsAt ? info.overageResetsAt * 1000 : null,
           overageDisabledReason: info.overageDisabledReason || null,
         });
+        if (info.rateLimitType && info.utilization) {
+          observeQuota(session, { type: "rate_limit", vendor: session.vendor || "claude", rateLimitType: info.rateLimitType, utilization: info.utilization }, Date.now());
+        }
         // Track rejection for auto-continue / scheduled message support
         if (info.status === "rejected" && info.resetsAt) {
           session.rateLimitResetsAt = info.resetsAt * 1000;

package/lib/sdk-quota-snapshot.js

@@ -1,4 +1,4 @@
-function recordQuotaSnapshot(session, info, sendAndRecord) {
+function recordQuotaSnapshot(session, info, sendAndRecord, observe) {
   var message = {
     type: "rate_limit_usage",
     sessionId: session.localId,
@@ -10,6 +10,9 @@ function recordQuotaSnapshot(session, info, sendAndRecord) {
     }),
   };
   if (Number.isFinite(info.observedAtMs)) message.observedAtMs = info.observedAtMs;
+  // The overview records every live observation, including an unchanged one:
+  // deduplication below only avoids re-recording identical history.
+  if (typeof observe === "function") observe(session, message, Number.isFinite(info.observedAtMs) ? info.observedAtMs : Date.now());
   var snapshots = session._quotaSnapshots || (session._quotaSnapshots = Object.create(null));
   var key = JSON.stringify([session.ownerId, session.vendor, info.limitId]);
   var serialized = JSON.stringify(message);
@@ -18,7 +21,22 @@ function recordQuotaSnapshot(session, info, sendAndRecord) {
   sendAndRecord(session, message);
 }
 
+// Observation listeners feed the owner-scoped vendor overview. They never
+// influence rejection handling or scheduling.
+function attachQuotaObservers(sm) {
+  // Idempotent: the processor and the overview may attach in either order.
+  if (typeof sm.addOnQuotaObserved === "function") return;
+  var listeners = [];
+  sm.addOnQuotaObserved = function (fn) { if (typeof fn === "function") listeners.push(fn); };
+  sm.notifyQuotaObserved = function (session, message, observedAtMs) {
+    for (var i = 0; i < listeners.length; i++) {
+      try { listeners[i](session, message, observedAtMs); } catch (e) { /* the overview is optional */ }
+    }
+  };
+}
+
 function attachQuotaSnapshots(sm) {
+  attachQuotaObservers(sm);
   if (typeof sm.addOnSessionViewed !== "function") return;
   sm.addOnSessionViewed(function (session, ws, send) {
     var seen = Object.create(null);
@@ -34,4 +52,4 @@ function attachQuotaSnapshots(sm) {
   });
 }
 
-module.exports = { recordQuotaSnapshot: recordQuotaSnapshot, attachQuotaSnapshots: attachQuotaSnapshots };
+module.exports = { recordQuotaSnapshot: recordQuotaSnapshot, attachQuotaSnapshots: attachQuotaSnapshots, attachQuotaObservers: attachQuotaObservers };

package/lib/server-github-stars.js

@@ -0,0 +1,39 @@
+// server-github-stars.js - GET /api/github-stars for the top-bar Star link.
+//
+// Read-only. Returns the cached public star count of the fixed Clay
+// repository (null when not yet known). No request input reaches GitHub, and
+// nothing about the caller is sent or stored.
+
+var githubStarCount = require("./github-star-count");
+
+function attachGithubStars(ctx) {
+  var cache = ctx.cache || githubStarCount.createGithubStarCount();
+
+  function json(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+    res.end(JSON.stringify(body));
+  }
+
+  function handleRequest(req, res, url) {
+    if (url !== "/api/github-stars") return false;
+    if (req.method !== "GET") {
+      res.writeHead(405, { "Content-Type": "application/json", "Allow": "GET" });
+      res.end(JSON.stringify({ error: "Method not allowed." }));
+      return true;
+    }
+    if (!ctx.isRequestAuthed(req)) {
+      json(res, 401, { error: "Sign in to continue." });
+      return true;
+    }
+    cache.get().then(function (snapshot) {
+      json(res, 200, snapshot);
+    }, function () {
+      json(res, 200, { repo: githubStarCount.REPO, stars: null, fetchedAt: null });
+    });
+    return true;
+  }
+
+  return { handleRequest: handleRequest };
+}
+
+module.exports = { attachGithubStars: attachGithubStars };