pi-sdk-web 0.4.11 → 0.5.0

package/dist/server.js

@@ -817,6 +817,34 @@ export class PiWebServer {
                 notifyType: "info",
             });
         }
+        // Usage extension: the /usage command collects data (via custom(), whose
+        // factory runs the collection) and keeps its cache file up to date.
+        // Aggregate the cache into structured data and send it as a dedicated
+        // message; the frontend renders its own usage panel (independent
+        // integration in usage-render.ts - no effect on other commands).
+        if (name === "usage") {
+            try {
+                const { buildUsageData } = await import("./usage-render.js");
+                const data = buildUsageData();
+                if (data) {
+                    this.broadcast({ type: "usage_data", data });
+                }
+                else {
+                    this.broadcast({
+                        type: "extension_ui_request",
+                        id: crypto.randomUUID(),
+                        method: "notify",
+                        title: "/usage",
+                        message: "No usage data found. Run `/usage` in the TUI first to build the usage cache.",
+                        notifyType: "info",
+                    });
+                }
+            }
+            catch {
+                // integration failed silently - command output (if any) already
+                // broadcast above
+            }
+        }
     }
     buildCommandContext(hasUI) {
         const sm = this.session.sessionManager;

package/dist/static/app.js

@@ -355,6 +355,9 @@ class PiWebClient {
       case 'scoped_models':
         this.handleScopedModels(data.data);
         break;
+      case 'usage_data':
+        this.renderUsagePanel(data.data);
+        break;
       case 'sessions':
         this.handleSessions(data.data);
         break;
@@ -1705,7 +1708,19 @@ class PiWebClient {
       if (e.key === 'Escape' && this.modalOverlay && this.modalOverlay.style.display !== 'none') {
         this.closeModal();
       }
+      const usageOverlay = document.getElementById('usage-overlay');
+      if (e.key === 'Escape' && usageOverlay && usageOverlay.style.display !== 'none') {
+        this.closeUsagePanel();
+      }
     });
+    const usageClose = document.getElementById('usage-close');
+    if (usageClose) usageClose.addEventListener('click', () => this.closeUsagePanel());
+    const usageOverlayEl = document.getElementById('usage-overlay');
+    if (usageOverlayEl) {
+      usageOverlayEl.addEventListener('click', (e) => {
+        if (e.target === usageOverlayEl) this.closeUsagePanel();
+      });
+    }
   }
 
   // ------------------------------------------------------------------
@@ -1950,6 +1965,279 @@ class PiWebClient {
     }, type === 'error' ? 8000 : 5000);
   }
 
+  // ------------------------------------------------------------------
+  // Usage panel (dedicated big panel for /usage, rendered from the
+  // server-aggregated usage_data payload)
+  // ------------------------------------------------------------------
+
+  renderUsagePanel(data) {
+    if (!data || !data.tabs) return;
+    this.usageData = data;
+    this.usageTab = 'thisWeek';
+    this.usageView = 'table';
+    this.usageExpanded = new Set();
+    const overlay = document.getElementById('usage-overlay');
+    if (!overlay) return;
+    overlay.style.display = 'flex';
+    this.renderUsageTabs();
+    this.renderUsageBody();
+  }
+
+  closeUsagePanel() {
+    const overlay = document.getElementById('usage-overlay');
+    if (overlay) overlay.style.display = 'none';
+  }
+
+  renderUsageTabs() {
+    const tabsEl = document.getElementById('usage-tabs');
+    if (!tabsEl) return;
+    const labels = {
+      today: 'Today',
+      thisWeek: 'This Week',
+      lastWeek: 'Last Week',
+      last30Days: 'Last 30 Days',
+      allTime: 'All Time',
+    };
+    tabsEl.innerHTML = '';
+    for (const key of Object.keys(labels)) {
+      const tab = document.createElement('span');
+      tab.className = 'usage-tab' + (key === this.usageTab ? ' active' : '');
+      tab.textContent = labels[key];
+      tab.addEventListener('click', () => {
+        this.usageTab = key;
+        this.usageExpanded.clear();
+        this.renderUsageTabs();
+        this.renderUsageBody();
+      });
+      tabsEl.appendChild(tab);
+    }
+    // View switcher: Table / Insights / Graph
+    const viewsEl = document.getElementById('usage-views');
+    if (viewsEl) {
+      viewsEl.innerHTML = '';
+      for (const [key, label] of [['table', 'Table'], ['insights', 'Insights'], ['graph', 'Graph']]) {
+        const v = document.createElement('span');
+        v.className = 'usage-view' + (key === this.usageView ? ' active' : '');
+        v.textContent = label;
+        v.addEventListener('click', () => {
+          this.usageView = key;
+          this.renderUsageTabs();
+          this.renderUsageBody();
+        });
+        viewsEl.appendChild(v);
+      }
+    }
+  }
+
+  fmtTokens(n) {
+    if (n >= 1e9) return (n / 1e9).toFixed(2) + 'B';
+    if (n >= 1e6) return (n / 1e6).toFixed(2) + 'M';
+    if (n >= 1e3) return (n / 1e3).toFixed(1) + 'K';
+    return String(Math.round(n));
+  }
+
+  fmtCost(c) {
+    if (!c || c <= 0) return '-';
+    if (c < 0.01) return '$' + c.toFixed(4);
+    if (c < 10) return '$' + c.toFixed(2);
+    return '$' + c.toFixed(1);
+  }
+
+  usageRow(stat) {
+    const t = stat.tokens || {};
+    return [
+      this.fmtTokens(t.input),
+      this.fmtTokens(t.output),
+      this.fmtTokens((t.cacheRead || 0) + (t.cacheWrite || 0)),
+      this.fmtTokens((t.total === undefined ? (t.input || 0) + (t.output || 0) + (t.cacheRead || 0) + (t.cacheWrite || 0) : t.total)),
+      this.fmtCost(stat.cost),
+      String(stat.messages),
+      String(stat.sessions),
+    ];
+  }
+
+  renderUsageBody() {
+    const body = document.getElementById('usage-body');
+    if (!body) return;
+    const period = this.usageData.tabs[this.usageTab];
+    if (!period) return;
+    body.innerHTML = '';
+    body.scrollTop = 0;
+
+    if (this.usageView === 'table') {
+      const table = document.createElement('table');
+      table.className = 'usage-table';
+      const head = document.createElement('thead');
+      head.innerHTML = '<tr><th>Provider / Model</th><th>Msgs</th><th>Cost</th><th>Tokens</th><th>↑In</th><th>↓Out</th><th>Cache</th><th>Sessions</th></tr>';
+      table.appendChild(head);
+      const tbody = document.createElement('tbody');
+
+      const rowFor = (name, stat, isModel, isTotals) => {
+        const tr = document.createElement('tr');
+        if (isTotals) tr.className = 'usage-totals';
+        else if (isModel) tr.className = 'usage-model-row';
+        else tr.className = 'usage-provider-row';
+        const nameTd = document.createElement('td');
+        nameTd.className = 'usage-name';
+        nameTd.textContent = name;
+        const [, cost, tokens, input, output, cache, msgs, sessions] = [null, this.fmtCost(stat.cost), this.fmtTokens(stat.tokens ? stat.tokens.total : 0), this.fmtTokens(stat.tokens ? stat.tokens.input : 0), this.fmtTokens(stat.tokens ? stat.tokens.output : 0), this.fmtTokens(stat.tokens ? (stat.tokens.cacheRead + stat.tokens.cacheWrite) : 0), String(stat.messages), String(stat.sessions)];
+        tr.appendChild(nameTd);
+        for (const cell of [msgs, cost, tokens, input, output, cache, sessions]) {
+          const td = document.createElement('td');
+          td.textContent = cell;
+          td.className = 'usage-num';
+          tr.appendChild(td);
+        }
+        return tr;
+      };
+
+      for (const p of period.providers) {
+        const key = 'p:' + p.name;
+        const expanded = this.usageExpanded.has(key);
+        const tr = rowFor(p.name, p, false, false);
+        tr.classList.add('usage-clickable');
+        tr.addEventListener('click', () => {
+          if (this.usageExpanded.has(key)) this.usageExpanded.delete(key);
+          else this.usageExpanded.add(key);
+          this.renderUsageBody();
+        });
+        tbody.appendChild(tr);
+        if (expanded) {
+          for (const m of p.models || []) {
+            tbody.appendChild(rowFor('  └ ' + m.name, m, true, false));
+          }
+        }
+      }
+      const totals = period.totals;
+      tbody.appendChild(rowFor('Total', totals, false, true));
+      table.appendChild(tbody);
+      body.appendChild(table);
+    } else if (this.usageView === 'insights') {
+      const list = document.createElement('div');
+      list.className = 'usage-insights';
+      const ins = period.insights || [];
+      if (ins.length === 0) {
+        list.innerHTML = '<div class="usage-insight">No insights for this period.</div>';
+      }
+      for (const i of ins) {
+        const div = document.createElement('div');
+        div.className = 'usage-insight ' + (i.kind === 'alarm' ? 'alarm' : 'structure');
+        const stat = document.createElement('span');
+        stat.className = 'usage-insight-stat';
+        stat.textContent = i.stat;
+        const text = document.createElement('span');
+        text.textContent = i.headline;
+        div.appendChild(stat);
+        div.appendChild(text);
+        if (i.advice) {
+          const advice = document.createElement('div');
+          advice.className = 'usage-insight-advice';
+          advice.textContent = i.advice;
+          div.appendChild(advice);
+        }
+        list.appendChild(div);
+      }
+      body.appendChild(list);
+    } else if (this.usageView === 'graph') {
+      // Simple CSS bar chart: cost per provider (this period) + hourly tokens trend
+      const container = document.createElement('div');
+      container.className = 'usage-graph';
+      if (period.providers.length === 0) {
+        container.innerHTML = '<div class="usage-insight">No data for this period.</div>';
+        body.appendChild(container);
+        return;
+      }
+      const maxCost = Math.max(...period.providers.map((p) => p.cost), 1e-9);
+      let html = '<div class="usage-graph-title">Cost by provider</div><div class="usage-bars">';
+      for (const p of period.providers) {
+        const w = ((p.cost / maxCost) * 100).toFixed(1);
+        html += `<div class="usage-bar-row"><span class="usage-bar-label">${this.escapeHtml(p.name)}</span><div class="usage-bar-track"><div class="usage-bar" style="width:${w}%"></div></div><span class="usage-bar-val">${this.fmtCost(p.cost)}</span></div>`;
+      }
+      html += '</div>';
+      // Hourly tokens trend for the current tab. The server provides one
+      // global hourly series + per-tab windows; filtering (per tab) and
+      // gap-filling are render-side concerns.
+      const hourly = this.usageData.hourly ? this.usageData.hourly : null;
+      const window = (this.usageData.tabWindow || {})[this.usageTab] || null;
+      if (hourly && hourly.length > 0) {
+        // Filter to the tab's window, then fill the x-axis with a
+        // continuous hour sequence so idle hours appear as empty columns.
+        // Axis start rule: if the earliest data predates the period start,
+        // show the whole period (zeros included); if data only exists
+        // inside the period, start from the first hour with data (e.g.
+        // allTime never starts at epoch - it starts at first usage).
+        let seq = hourly;
+        if (window && window[1] > window[0]) {
+          const H = 3600_000;
+          const inWindow = hourly.filter((b) => b.hour >= window[0] && b.hour < window[1]);
+          const periodStartHour = Math.floor(window[0] / H) * H;
+          // Rule: compare the GLOBAL earliest data hour with the period
+          // start. If data predates the period (global first < period
+          // start), show the whole period (zeros included). Only when the
+          // very first usage ever is inside this period do we start from
+          // the first data hour (e.g. allTime starts at first usage, not
+          // epoch).
+          const globalFirstHour = hourly[0].hour; // hourly is time-sorted
+          const startHour = globalFirstHour > periodStartHour ? globalFirstHour : periodStartHour;
+          const endHour = Math.floor(window[1] / H) * H;
+          const byHour = new Map(inWindow.map((b) => [b.hour, b]));
+          seq = [];
+          for (let h = startHour; h <= endHour; h += H) {
+            const b = byHour.get(h);
+            seq.push(b ? { ...b } : { hour: h, cost: 0, tokens: 0, messages: 0 });
+          }
+        }
+        // Cap the column count (~120) so very long windows (allTime) stay
+        // manageable; the hourly chart scrolls horizontally to show idle
+        // hours, so a generous count is fine.
+        let buckets = seq;
+        const maxCols = 120;
+        if (buckets.length > maxCols) {
+          const step = Math.ceil(buckets.length / maxCols);
+          const agg = [];
+          for (let i = 0; i < buckets.length; i += step) {
+            const slice = buckets.slice(i, Math.min(i + step, buckets.length));
+            const start = slice[0].hour;
+            const end = slice[slice.length - 1].hour + 3600_000;
+            agg.push({
+              hour: start,
+              tokens: slice.reduce((s, b) => s + b.tokens, 0),
+              cost: slice.reduce((s, b) => s + b.cost, 0),
+              messages: slice.reduce((s, b) => s + b.messages, 0),
+              spanEnd: end,
+              spanCount: slice.length,
+            });
+          }
+          buckets = agg;
+        }
+        const maxT = Math.max(...buckets.map((b) => b.tokens), 1e-9);
+        // Fixed-height bars (px) - avoids percentage-height resolution
+        // issues in nested flex containers.
+        const BAR_MAX_PX = 96;
+        // Label every ~6th column with its time (sparse to avoid crowding).
+        const labelStep = Math.ceil(buckets.length / 8);
+        html += '<div class="usage-graph-title" style="margin-top:14px">Hourly tokens (recent)</div><div class="usage-hourly">';
+        for (let i = 0; i < buckets.length; i++) {
+          const b = buckets[i];
+          const hPx = b.tokens > 0 ? Math.max(2, Math.round((b.tokens / maxT) * BAR_MAX_PX)) : 0;
+          const d = new Date(b.hour);
+          const spanText = b.spanCount ? ` (${b.spanCount}h)` : '';
+          const showLabel = i % labelStep === 0 || i === buckets.length - 1;
+          const label = showLabel
+            ? d.toLocaleDateString(undefined, { month: 'numeric', day: 'numeric' }) + '\n' + d.toLocaleTimeString(undefined, { hour: '2-digit' })
+            : '';
+          // Day/night banding: hour 6..17 (local) = day, else night
+          const hourOfDay = d.getHours();
+          const band = hourOfDay >= 6 && hourOfDay < 18 ? 'day' : 'night';
+          html += `<div class="usage-hour-col ${band}" title="${d.toLocaleString()}${spanText} — ${this.fmtTokens(b.tokens)}"><div class="usage-hour-bar-wrap"><div class="usage-hour-bar" style="height:${hPx}px"></div></div><div class="usage-hour-label">${this.escapeHtml(label).replace(/\n/g, '<br>')}</div></div>`;
+        }
+        html += '</div>';
+      }
+      container.innerHTML = html;
+      body.appendChild(container);
+    }
+  }
+
   handleModels(models) {
     if (this.modalMode !== 'model') return;
     const items = (models || []).map((m) => ({

package/dist/static/index.html

@@ -55,6 +55,15 @@
     </div>
   </div>
   <div id="toast-container"></div>
+  <div id="usage-overlay" style="display:none">
+    <div id="usage-panel">
+      <div id="usage-title">Usage</div>
+      <div id="usage-tabs"></div>
+      <div id="usage-views"></div>
+      <div id="usage-body"></div>
+      <div id="usage-close">Close (Esc)</div>
+    </div>
+  </div>
   <script src="vendor/marked.min.js"></script>
   <script src="app.js"></script>
 </body>

package/dist/static/style.css

@@ -785,8 +785,8 @@ body {
   background: var(--code-bg);
   border: 1px solid var(--border);
   border-radius: 8px;
-  width: 480px;
-  max-width: 90vw;
+  width: min(720px, 92vw);
+  max-width: none;
   max-height: 70vh;
   display: flex;
   flex-direction: column;
@@ -1181,3 +1181,297 @@ body {
 #abort-btn:active {
   opacity: 0.8;
 }
+
+/* ======================================================================
+   Usage panel (dedicated large panel for /usage)
+   ====================================================================== */
+#usage-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.6);
+  display: none;
+  align-items: center;
+  justify-content: center;
+  z-index: 150;
+}
+
+#usage-panel {
+  background: var(--modal-bg);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  width: min(1100px, 94vw);
+  height: min(85vh, 800px);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+#usage-title {
+  padding: 10px 16px;
+  font-weight: bold;
+  font-size: 15px;
+  border-bottom: 1px solid var(--border);
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+#usage-tabs {
+  display: flex;
+  gap: 2px;
+  padding: 8px 12px 4px;
+  border-bottom: 1px solid var(--border);
+  flex-wrap: wrap;
+}
+
+.usage-tab, .usage-view {
+  padding: 4px 12px;
+  font-size: 12px;
+  border-radius: 4px;
+  cursor: pointer;
+  color: var(--muted);
+}
+
+.usage-tab.active, .usage-view.active {
+  background: var(--accent);
+  color: var(--bg);
+  font-weight: 600;
+}
+
+#usage-views {
+  display: flex;
+  gap: 2px;
+  padding: 4px 12px 8px;
+  border-bottom: 1px solid var(--border);
+}
+
+#usage-body {
+  flex: 1;
+  overflow-y: auto;
+  padding: 8px 12px;
+}
+
+.usage-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 12px;
+}
+
+.usage-table th {
+  text-align: right;
+  padding: 4px 8px;
+  color: var(--dim);
+  font-weight: 600;
+  border-bottom: 1px solid var(--border);
+  font-size: 11px;
+}
+
+.usage-table th:first-child {
+  text-align: left;
+}
+
+.usage-table td {
+  padding: 3px 8px;
+  border-bottom: 1px solid var(--border);
+  white-space: nowrap;
+}
+
+.usage-name {
+  text-align: left;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 340px;
+}
+
+.usage-num {
+  text-align: right;
+  font-family: monospace;
+}
+
+.usage-provider-row {
+  cursor: pointer;
+  font-weight: 600;
+}
+
+.usage-provider-row:hover {
+  background: var(--tool-pending-bg);
+}
+
+.usage-model-row {
+  color: var(--muted);
+  font-size: 11px;
+}
+
+.usage-totals {
+  font-weight: 700;
+  border-top: 2px solid var(--border);
+}
+
+.usage-insights {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.usage-insight {
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 8px 12px;
+  font-size: 13px;
+  display: flex;
+  align-items: baseline;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+
+.usage-insight.alarm {
+  border-left: 3px solid var(--error);
+}
+
+.usage-insight-stat {
+  font-weight: 700;
+  color: var(--accent);
+  font-family: monospace;
+  white-space: nowrap;
+}
+
+.usage-insight-advice {
+  width: 100%;
+  color: var(--dim);
+  font-size: 12px;
+}
+
+.usage-graph-title {
+  font-size: 13px;
+  font-weight: 600;
+  margin-bottom: 6px;
+  color: var(--text);
+}
+
+.usage-bars {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.usage-bar-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 12px;
+}
+
+.usage-bar-label {
+  width: 200px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  text-align: right;
+}
+
+.usage-bar-track {
+  flex: 1;
+  height: 14px;
+  background: var(--tool-pending-bg);
+  border-radius: 3px;
+  overflow: hidden;
+}
+
+.usage-bar {
+  height: 100%;
+  background: var(--accent);
+  border-radius: 3px;
+}
+
+.usage-bar-val {
+  width: 70px;
+  text-align: right;
+  font-family: monospace;
+  color: var(--muted);
+}
+
+.usage-hourly {
+  position: relative;
+  display: flex;
+  align-items: flex-end;
+  gap: 2px;
+  height: 120px;
+  /* fixed-width columns; long windows scroll horizontally - the chart is
+     the one place inside the panel where x-scrolling is acceptable */
+  overflow-x: auto;
+}
+
+/* Zero baseline spanning the whole chart, just above the time labels. */
+.usage-hourly::after {
+  content: '';
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 24px;
+  border-bottom: 1px solid var(--border);
+  pointer-events: none;
+}
+
+.usage-hour-bar-wrap {
+  flex: 1;
+  display: flex;
+  align-items: flex-end;
+  min-height: 0;
+}
+
+.usage-hour-col {
+  flex: 0 0 20px;
+  width: 20px;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+}
+
+/* Day/night banding: 6:00-17:59 = day (warm tint), rest = night (cool tint) */
+.usage-hour-col.day {
+  background: color-mix(in srgb, var(--accent) 5%, transparent);
+}
+
+.usage-hour-col.night {
+  background: color-mix(in srgb, var(--muted) 12%, transparent);
+}
+
+.usage-hour-bar-wrap {
+  flex: 1;
+  display: flex;
+  align-items: flex-end;
+  min-height: 0;
+}
+
+.usage-hour-label {
+  font-size: 9px;
+  color: var(--dim);
+  text-align: center;
+  line-height: 1.15;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  height: 22px;
+  margin-top: 2px;
+}
+
+.usage-hour-bar {
+  width: 100%;
+  background: var(--accent);
+  opacity: 0.75;
+  border-radius: 2px 2px 0 0;
+}
+
+#usage-close {
+  padding: 8px 16px;
+  text-align: right;
+  font-size: 12px;
+  color: var(--dim);
+  cursor: pointer;
+  border-top: 1px solid var(--border);
+}
+
+#usage-close:hover {
+  color: var(--text);
+}

package/dist/ui-context.js

@@ -200,12 +200,54 @@ export class WebUIContext {
     setHeader() { }
     custom() {
         // Pi's custom() shows an extension-drawn TUI component. Web has no TUI
-        // renderer, so a full component can't be displayed. Same headless stub
-        // as Pi's RPC mode (rpc-mode.ts: "Custom UI not supported in RPC mode"):
-        // settle immediately so commands awaiting the panel don't hang.
-        // Commands whose extensions branch on hasUI (magic-context ctx-status)
-        // are routed to their text fallback by executeCommand (hasUI:false);
-        // any other custom() caller just gets a no-op close.
+        // renderer, so the component can't be *displayed* - but the factory is
+        // still invoked with no-op stubs so the extension's own logic runs
+        // (e.g. /usage starts its data collection inside the factory), then we
+        // settle immediately: display-only panels (user-driven close) would
+        // otherwise hang the command forever, and data-producing panels
+        // (loader -> done(value)) have their result read from the extension's
+        // own cache file afterwards when needed (see usage-render.ts). So
+        // custom() never blocks the command.
+        // Extensions that branch on hasUI before custom (magic-context
+        // ctx-status) are routed to their text fallback by executeCommand
+        // (hasUI:false) and never reach this.
+        try {
+            // Arguments are (factory, options) at runtime; the declared
+            // signature stays interface-compatible, read them dynamically.
+            const args = arguments;
+            const factory = args[0];
+            const options = args[1];
+            if (typeof factory === "function") {
+                // No-op TUI stub: enough surface for factories that need a render
+                // handle; rendering itself is never performed on Web.
+                const stubTui = {
+                    requestRender: () => { },
+                    invalidate: () => { },
+                    setFocus: () => { },
+                    getWidth: () => 100,
+                };
+                // Theme stub: color helpers degrade to plain text.
+                const stubTheme = {
+                    fg: (_k, s) => s,
+                    bold: (s) => s,
+                    dim: (s) => s,
+                    get theme() {
+                        return undefined;
+                    },
+                };
+                const component = factory(stubTui, stubTheme, {}, () => { });
+                // Component built and its logic ran (data collection started);
+                // NOT disposed - async work inside may still be running and own
+                // its resources. settle immediately.
+                void component;
+            }
+            if (options && typeof options.onHandle === "function") {
+                options.onHandle({ setHidden: () => { }, focus: () => { } });
+            }
+        }
+        catch {
+            // factory threw - ignore, still settle
+        }
         return Promise.resolve(undefined);
     }
     pasteToEditor() { }

package/dist/usage-render.js

@@ -0,0 +1,410 @@
+/**
+ * Usage extension integration (independent module).
+ *
+ * pi-usage-extension's `/usage` command draws a TUI dashboard via
+ * ctx.ui.custom() which Web cannot render. However, running the command
+ * (through WebUIContext.custom() which now executes the factory) makes the
+ * extension collect usage data and write its cache file
+ * (`~/.pi/agent/usage-extension-cache.json`). This module reads that cache
+ * after the command runs and renders an equivalent summary as Markdown,
+ * shown as a titled modal - without coupling into the main server flow.
+ *
+ * Cache format (v7): { version, names: string[], files: { [sessionFile]: {
+ *   size, mtimeMs, sessionId, cwd, parentSession,
+ *   messages: 13-tuple[][], toolUsages: 5-tuple[][] } } }
+ * message tuple: [provider, model, cost, inputTokens, outputTokens,
+ *   cacheReadTokens, cacheWriteTokens, timestampMs, thinkingLevel,
+ *   reasoningTokens, afterCompaction(0|1), source(0 assistant|1 auxiliary),
+ *   sourceId]
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+export const USAGE_CACHE_FILE = "usage-extension-cache.json";
+const USAGE_CACHE_DIRS = [
+    join(process.env.PI_HOME?.replace(/^~/, homedir()) ?? homedir(), ".pi", "agent"),
+    join(homedir(), ".pi", "agent"),
+];
+function findCachePath() {
+    for (const dir of USAGE_CACHE_DIRS) {
+        const p = join(dir, USAGE_CACHE_FILE);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/** mtime of the usage cache file, or null when absent. */
+export function usageCacheMtime() {
+    const path = findCachePath();
+    if (!path)
+        return null;
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read and normalize the usage cache; null when absent/unreadable. */
+export function loadUsageCache() {
+    const path = findCachePath();
+    if (!path)
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const names = raw.names ?? [];
+        const files = [];
+        for (const file of Object.values(raw.files ?? {})) {
+            const f = file;
+            const messages = [];
+            if (Array.isArray(f.messages)) {
+                for (const tuple of f.messages) {
+                    if (!Array.isArray(tuple) || tuple.length !== 13)
+                        continue;
+                    const provider = names[tuple[0]];
+                    const model = names[tuple[1]];
+                    const thinkingLevel = names[tuple[8]];
+                    if (typeof provider !== "string" || typeof model !== "string")
+                        continue;
+                    messages.push({
+                        provider,
+                        model,
+                        thinkingLevel,
+                        cost: Number(tuple[2]) || 0,
+                        input: Number(tuple[3]) || 0,
+                        output: Number(tuple[4]) || 0,
+                        cacheRead: Number(tuple[5]) || 0,
+                        cacheWrite: Number(tuple[6]) || 0,
+                        timestamp: Number(tuple[7]) || 0,
+                        reasoning: Number(tuple[9]) || 0,
+                        afterCompaction: tuple[10] === 1,
+                        source: tuple[11] === 1 ? "auxiliary" : "assistant",
+                    });
+                }
+            }
+            files.push({
+                messages,
+                sessionId: f.sessionId ?? "",
+                cwd: f.cwd ?? "",
+                parentSession: f.parentSession ?? "",
+            });
+        }
+        return { files, names };
+    }
+    catch {
+        return null;
+    }
+}
+function startOfDay(ts) {
+    const d = new Date(ts);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+function startOfWeek(ts) {
+    const d = new Date(ts);
+    const day = d.getDay() === 0 ? 6 : d.getDay() - 1;
+    d.setHours(0, 0, 0, 0);
+    d.setDate(d.getDate() - day);
+    return d.getTime();
+}
+function emptyTotals() {
+    return { cost: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, messages: 0, sessions: new Set() };
+}
+function fmt(n) {
+    return n >= 1e9
+        ? `${(n / 1e9).toFixed(2)}B`
+        : n >= 1e6
+            ? `${(n / 1e6).toFixed(2)}M`
+            : n >= 1e3
+                ? `${(n / 1e3).toFixed(1)}K`
+                : `${Math.round(n)}`;
+}
+function fmtCost(n) {
+    return `$${n.toFixed(n >= 1 ? 2 : 4)}`;
+}
+/** Render a Markdown usage summary (today / this week / all time). */
+export function renderUsageSummary() {
+    const cache = loadUsageCache();
+    if (!cache) {
+        return "## Usage\n\nNo usage data found. Run `/usage` in the TUI first to build the usage cache.";
+    }
+    const now = Date.now();
+    const todayStart = startOfDay(now);
+    const weekStart = startOfWeek(now);
+    const today = emptyTotals();
+    const week = emptyTotals();
+    const all = emptyTotals();
+    const byModel = new Map();
+    for (const file of cache.files) {
+        for (const m of file.messages) {
+            const t = m.timestamp;
+            const targets = [all];
+            if (t >= todayStart)
+                targets.push(today);
+            if (t >= weekStart)
+                targets.push(week);
+            for (const target of targets) {
+                target.cost += m.cost;
+                target.input += m.input;
+                target.output += m.output;
+                target.cacheRead += m.cacheRead;
+                target.cacheWrite += m.cacheWrite;
+                target.messages += 1;
+                target.sessions.add(file.sessionId);
+            }
+            const key = `${m.provider}/${m.model}`;
+            const byModelEntry = byModel.get(key) ?? emptyTotals();
+            byModelEntry.cost += m.cost;
+            byModelEntry.input += m.input;
+            byModelEntry.output += m.output;
+            byModelEntry.cacheRead += m.cacheRead;
+            byModelEntry.cacheWrite += m.cacheWrite;
+            byModelEntry.messages += 1;
+            byModel.set(key, byModelEntry);
+        }
+    }
+    const row = (label, t) => `| ${label} | ${fmt(t.input)} | ${fmt(t.output)} | ${fmt(t.cacheRead)} | ${fmt(t.cacheWrite)} | $${t.cost.toFixed(4)} | ${t.messages} | ${t.sessions.size} |`;
+    const lines = [
+        "## Usage",
+        "",
+        "| Period | Input | Output | Cache R | Cache W | Cost | Msgs | Sessions |",
+        "| --- | --- | --- | --- | --- | --- | --- | --- |",
+        row("Today", today),
+        row("This week", week),
+        row("All time", all),
+    ];
+    if (byModel.size > 0) {
+        const sorted = [...byModel.entries()].sort((a, b) => b[1].cost - a[1].cost).slice(0, 10);
+        lines.push("", "### By model (all time)", "", "| Model | Input | Output | Cost | Msgs |", "| --- | --- | --- | --- | --- |");
+        for (const [key, t] of sorted) {
+            lines.push(`| ${key} | ${fmt(t.input)} | ${fmt(t.output)} | $${t.cost.toFixed(4)} | ${t.messages} |`);
+        }
+    }
+    return lines.join("\n");
+}
+const TAB_KEYS = ["today", "thisWeek", "lastWeek", "last30Days", "allTime"];
+function emptyTokens() {
+    return { total: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+}
+function addTokens(a, b) {
+    a.total += b.total;
+    a.input += b.input;
+    a.output += b.output;
+    a.cacheRead += b.cacheRead;
+    a.cacheWrite += b.cacheWrite;
+}
+/** Format a cost value the way the extension does (0 -> "-"). */
+export function formatUsageCost(cost) {
+    if (cost === 0)
+        return "-";
+    if (cost < 0.01)
+        return `$${cost.toFixed(4)}`;
+    if (cost < 1)
+        return `$${cost.toFixed(2)}`;
+    if (cost < 10)
+        return `$${cost.toFixed(2)}`;
+    if (cost < 100)
+        return `$${cost.toFixed(1)}`;
+    return `$${Math.round(cost)}`;
+}
+/** Format a token count compactly (12.3K, 4.5M, ...). */
+export function formatUsageTokens(n) {
+    if (n >= 1e9)
+        return `${(n / 1e9).toFixed(2)}B`;
+    if (n >= 1e6)
+        return `${(n / 1e6).toFixed(2)}M`;
+    if (n >= 1e3)
+        return `${(n / 1e3).toFixed(1)}K`;
+    return `${Math.round(n)}`;
+}
+function periodStart(key, now) {
+    const d = new Date(now);
+    d.setHours(0, 0, 0, 0);
+    if (key === "today")
+        return d.getTime();
+    const day = d.getDay() === 0 ? 6 : d.getDay() - 1; // Monday start
+    if (key === "thisWeek") {
+        d.setDate(d.getDate() - day);
+        return d.getTime();
+    }
+    if (key === "lastWeek") {
+        d.setDate(d.getDate() - day - 7);
+        return d.getTime();
+    }
+    if (key === "last30Days") {
+        return d.getTime() - 29 * 24 * 3600 * 1000;
+    }
+    return 0; // allTime
+}
+/**
+ * Aggregate the cache into the structured payload the web panel renders.
+ * Returns null when no cache exists yet.
+ */
+export function buildUsageData() {
+    const cache = loadUsageCache();
+    if (!cache)
+        return null;
+    const now = Date.now();
+    // per-tab accumulators
+    const tabs = {};
+    for (const key of TAB_KEYS) {
+        tabs[key] = { providers: new Map(), totals: { messages: 0, cost: 0, tokens: emptyTokens(), sessions: new Set() } };
+    }
+    // hourly buckets (all providers, global) - the render side filters per tab
+    const hourly = new Map();
+    const hourStart = (ts) => Math.floor(ts / 3600_000) * 3600_000;
+    for (const file of cache.files) {
+        for (const m of file.messages) {
+            const ts = m.timestamp;
+            {
+                const bucket = hourly.get(hourStart(ts));
+                if (bucket) {
+                    bucket.cost += m.cost;
+                    bucket.tokens += m.input + m.output + m.cacheRead + m.cacheWrite;
+                    bucket.messages += 1;
+                }
+                else {
+                    hourly.set(hourStart(ts), { cost: m.cost, tokens: m.input + m.output + m.cacheRead + m.cacheWrite, messages: 1 });
+                }
+            }
+            for (const key of TAB_KEYS) {
+                const start = periodStart(key, now);
+                if (ts < start)
+                    continue;
+                const tab = tabs[key];
+                tab.totals.messages += 1;
+                tab.totals.cost += m.cost;
+                addTokens(tab.totals.tokens, {
+                    total: m.input + m.output + m.cacheRead + m.cacheWrite,
+                    input: m.input,
+                    output: m.output,
+                    cacheRead: m.cacheRead,
+                    cacheWrite: m.cacheWrite,
+                });
+                tab.totals.sessions.add(file.sessionId);
+                let prov = tab.providers.get(m.provider);
+                if (!prov) {
+                    prov = {
+                        messages: 0, cost: 0, tokens: emptyTokens(), sessions: new Set(), models: new Map(),
+                    };
+                    tab.providers.set(m.provider, prov);
+                }
+                prov.messages += 1;
+                prov.cost += m.cost;
+                addTokens(prov.tokens, {
+                    total: m.input + m.output + m.cacheRead + m.cacheWrite,
+                    input: m.input,
+                    output: m.output,
+                    cacheRead: m.cacheRead,
+                    cacheWrite: m.cacheWrite,
+                });
+                prov.sessions.add(file.sessionId);
+                let model = prov.models.get(m.model);
+                if (!model) {
+                    model = { messages: 0, cost: 0, tokens: emptyTokens(), sessions: new Set() };
+                    prov.models.set(m.model, model);
+                }
+                model.messages += 1;
+                model.cost += m.cost;
+                addTokens(model.tokens, {
+                    total: m.input + m.output + m.cacheRead + m.cacheWrite,
+                    input: m.input,
+                    output: m.output,
+                    cacheRead: m.cacheRead,
+                    cacheWrite: m.cacheWrite,
+                });
+                model.sessions.add(file.sessionId);
+            }
+        }
+    }
+    const payload = { tabs: {}, hourly: [], tabWindow: {}, collectedAt: usageCacheMtime() };
+    // Graph x-axis windows per tab: [start, end]. today: midnight->now;
+    // thisWeek: monday->now; lastWeek: monday->next Monday; last30Days:
+    // start->now; allTime: 0 -> now (frontend clips to first data).
+    for (const key of TAB_KEYS) {
+        const start = periodStart(key, now);
+        let end = now;
+        if (key === "lastWeek") {
+            const d = new Date(now);
+            d.setHours(0, 0, 0, 0);
+            const day = d.getDay() === 0 ? 6 : d.getDay() - 1;
+            d.setDate(d.getDate() - day);
+            end = d.getTime();
+        }
+        payload.tabWindow[key] = [start, end];
+    }
+    for (const key of TAB_KEYS) {
+        const tab = tabs[key];
+        const providers = [...tab.providers.entries()]
+            .sort((a, b) => b[1].cost - a[1].cost)
+            .map(([name, p]) => ({
+            name,
+            messages: p.messages,
+            cost: p.cost,
+            tokens: p.tokens,
+            sessions: p.sessions.size,
+            models: [...p.models.entries()]
+                .sort((a, b) => b[1].cost - a[1].cost)
+                .map(([mname, m]) => ({
+                name: mname,
+                messages: m.messages,
+                cost: m.cost,
+                tokens: m.tokens,
+                sessions: m.sessions.size,
+            })),
+        }));
+        // Simple insights: top provider share + largest model cost (alarms
+        // when material), plus a structure line for overall usage.
+        const insights = [];
+        const totalCost = tab.totals.cost;
+        const totalTokens = tab.totals.tokens.total;
+        if (totalCost > 0 && providers.length > 0) {
+            const top = providers[0];
+            const share = (top.cost / totalCost) * 100;
+            if (share >= 20) {
+                insights.push({
+                    kind: "alarm",
+                    stat: `${share.toFixed(0)}%`,
+                    headline: `${top.name} drives ${share.toFixed(0)}% of cost ($${top.cost.toFixed(2)})`,
+                    advice: "Consider switching cheaper models for routine work.",
+                });
+            }
+            if (top.models.length > 0) {
+                const topModel = [...top.models].sort((a, b) => b.cost - a.cost)[0];
+                if (topModel.cost / totalCost >= 0.3) {
+                    insights.push({
+                        kind: "alarm",
+                        stat: formatUsageCost(topModel.cost),
+                        headline: `${topModel.name} is the costliest model (${((topModel.cost / totalCost) * 100).toFixed(0)}% of total)`,
+                        advice: "Check whether its output quality justifies the price.",
+                    });
+                }
+            }
+        }
+        else if (tab.totals.messages === 0) {
+            insights.push({ kind: "structure", stat: "-", headline: "No usage recorded for this period.", advice: "" });
+        }
+        if (tab.totals.messages > 0) {
+            insights.push({
+                kind: "structure",
+                stat: formatUsageTokens(totalTokens),
+                headline: `${tab.totals.messages.toLocaleString()} messages, ${formatUsageTokens(totalTokens)} tokens total`,
+                advice: totalCost > 0 ? `Spent ${formatUsageCost(totalCost)} across ${tab.totals.sessions.size} session(s).` : "",
+            });
+        }
+        payload.tabs[key] = {
+            providers,
+            totals: {
+                messages: tab.totals.messages,
+                cost: tab.totals.cost,
+                tokens: tab.totals.tokens,
+                sessions: tab.totals.sessions.size,
+            },
+            insights,
+        };
+    }
+    payload.hourly = [...hourly.entries()]
+        .sort((a, b) => a[0] - b[0])
+        .map(([hour, v]) => ({ hour, cost: v.cost, tokens: v.tokens, messages: v.messages }));
+    return payload;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sdk-web",
-  "version": "0.4.11",
+  "version": "0.5.0",
   "description": "Browser Web access for Pi (AI coding agent) via the Pi SDK - standalone module, zero modification to Pi itself",
   "type": "module",
   "bin": {
@@ -11,7 +11,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json && node -e \"require('node:fs').cpSync('../static', 'dist/static', { recursive: true }); require('node:fs').mkdirSync('dist/pi-bin', { recursive: true }); require('node:fs').renameSync('dist/pii-cli.js', 'dist/pi-bin/pii-cli.js'); require('node:fs').cpSync('../pii/pii', 'dist/pi-bin/pii'); require('node:fs').cpSync('../server', 'dist/pi-bin/server', { recursive: true, filter: (s) => !s.includes('__pycache__') })\"",
+    "build": "tsc -p tsconfig.json && node -e \"require('node:fs').cpSync('../static', 'dist/static', { recursive: true }); require('node:fs').mkdirSync('dist/pi-bin', { recursive: true }); require('node:fs').renameSync('dist/pii-cli.js', 'dist/pi-bin/pii-cli.js'); require('node:fs').chmodSync('dist/pi-bin/pii-cli.js', 0o755); require('node:fs').cpSync('../pii/pii', 'dist/pi-bin/pii'); require('node:fs').cpSync('../server', 'dist/pi-bin/server', { recursive: true, filter: (s) => !s.includes('__pycache__') })\"",
     "dev": "tsx src/cli.ts",
     "verify": "tsx src/verify-sdk.ts",
     "prepublishOnly": "npm run build"