shraga 0.1.58 → 0.1.60

package/dist/client/index.html

@@ -13,8 +13,8 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-Dhv0RZ8g.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-nyZagTjP.css">
+    <script type="module" crossorigin src="/assets/index-NHccVXR_.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-LCOnn8yS.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.58",
+  "version": "0.1.60",
   "description": "The teammate you delegate coding to — a self-hostable, multi-user AI coding agent web UI (Claude Code, with a pluggable engine seam).",
   "type": "module",
   "main": "./src/index.ts",
@@ -59,6 +59,7 @@
     "@livx.cc/mcp-firebase": "^0.1.14",
     "@radix-ui/react-accordion": "^1.2.2",
     "@radix-ui/react-dialog": "^1.1.4",
+    "@radix-ui/react-hover-card": "^1.1.23",
     "@radix-ui/react-scroll-area": "^1.2.2",
     "@radix-ui/react-slot": "^1.1.1",
     "@tailwindcss/typography": "^0.5.19",

package/src/client/components/MachineStats.tsx

@@ -1,10 +1,22 @@
 import { useEffect, useState } from 'react';
 import type { AgentSocket, ServerEvent } from '@/lib/ws';
 import { cn } from '@/lib/utils';
+import { HoverCard, HoverCardContent, HoverCardTrigger } from './ui/hover-card';
 
 type Sample = Extract<ServerEvent, { type: 'stats' }>['sample'];
 
+export interface UsageLimit {
+  kind: string;
+  group: string;
+  percent: number;
+  severity: string;
+  resetsAt: string | null;
+  scopeLabel?: string;
+}
+export interface Usage { subscriptionType: string | null; limits: UsageLimit[] }
+
 const WINDOW = 120;
+const USAGE_POLL_MS = 60_000;
 
 interface Props {
   socket: AgentSocket | null;
@@ -39,31 +51,184 @@ export function MachineStats({ socket, getToken }: Props) {
   const latest = samples[samples.length - 1];
 
   return (
-    <div className="flex items-center justify-center gap-2 text-[10px] text-muted-foreground/60">
+    // Wraps: three metrics do not fit one row in the w-64 sidebar (~302px of content, ~223px of box),
+    // and no amount of label/glyph trimming closes that gap without shrinking the CPU/MEM sparklines.
+    // w-full pins the row to the container so a wrapped line still centres against the sidebar.
+    <div className="w-full flex flex-wrap items-center justify-center gap-x-2 gap-y-0.5 text-[10px] text-muted-foreground/60">
       <Metric label="cpu" value={latest.cpu} series={samples.map(s => s.cpu)} />
       <Metric label="mem" value={latest.mem} series={samples.map(s => s.mem)} />
+      <ClaudeUsageMetric getToken={getToken} />
+    </div>
+  );
+}
+
+// Claude Code subscription usage. Absent entirely unless the server can PROVE this box is on a
+// subscription — it answers 204 otherwise, and 204 (like any failure here) renders nothing.
+function ClaudeUsageMetric({ getToken }: { getToken: () => Promise<string | null> }) {
+  const [usage, setUsage] = useState<Usage | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    const poll = async () => {
+      try {
+        const t = await getToken();
+        if (!t) return;
+        const r = await fetch('/api/claude-usage', { headers: { Authorization: `Bearer ${t}` } });
+        if (!alive) return;
+        // 204 = not a subscription deployment. Anything non-OK = fail closed, same outcome.
+        if (r.status !== 200) { setUsage(null); return; }
+        const d: Usage = await r.json();
+        if (!alive || !d?.limits?.length) return;
+        setUsage(d);
+      } catch (err) {
+        console.warn('[MachineStats] claude usage poll failed', err);
+        if (alive) setUsage(null);
+      }
+    };
+    void poll();
+    const id = setInterval(poll, USAGE_POLL_MS);
+    return () => { alive = false; clearInterval(id); };
+  }, [getToken]);
+
+  return <UsageMetric usage={usage} />;
+}
+
+/** Pure render — null usage (204, or any failure) renders NOTHING. Split from the fetching shell so
+ *  the gate and the labelling are testable without a network or a DOM. */
+export function UsageMetric({ usage }: { usage: Usage | null }) {
+  const top = usage && binding(usage.limits);
+  if (!usage || !top) return null;
+
+  // No `series`: usage has no server-side history to seed from, so it renders a GAUGE (full from the
+  // first paint) instead of a sparkline that would plot tab-uptime and be empty for the first minutes.
+  // No `title` either — the breakdown lives in the hover card below; a native tooltip on the same
+  // element would race it, appear a second late, and repeat the card word for word.
+  return (
+    <HoverCard openDelay={120} closeDelay={80}>
+      <HoverCardTrigger asChild>
+        <span className="cursor-default">
+          <Metric label="usage" value={top.percent} severity={top.severity} />
+        </span>
+      </HoverCardTrigger>
+      <HoverCardContent>
+        <UsageCard usage={usage} />
+      </HoverCardContent>
+    </HoverCard>
+  );
+}
+
+/** The hover breakdown: one row per reported window. Exported bare so the rows can be asserted
+ *  without driving a real hover (Radix only mounts the content once open). */
+export function UsageCard({ usage }: { usage: Usage }) {
+  const top = binding(usage.limits);
+  return (
+    <div className="text-[11px] leading-tight">
+      <div className="flex items-baseline justify-between gap-2 pb-2 text-muted-foreground">
+        <span className="uppercase tracking-wide">claude usage</span>
+        {usage.subscriptionType && <span className="tabular-nums">{usage.subscriptionType} plan</span>}
+      </div>
+      <div className="flex flex-col gap-3">
+        {usage.limits.map((l, i) => {
+          const until = untilLabel(l.resetsAt);
+          const isTop = l === top;
+          return (
+            <div key={`${l.kind}-${i}`} data-headline={isTop || undefined} className={cn('flex flex-col gap-1', !isTop && 'opacity-60')}>
+              <div className="flex items-baseline justify-between gap-2">
+                <span className={cn('truncate', isTop && 'font-medium')}>
+                  {isTop && <span className="mr-1 text-muted-foreground" aria-hidden>▸</span>}
+                  {windowLabel(l)}
+                </span>
+                <span className={cn('tabular-nums shrink-0', level(l.percent, l.severity))}>{l.percent}%</span>
+              </div>
+              <Gauge value={l.percent} className={cn('w-full', level(l.percent, l.severity))} />
+              <span className="text-[10px] text-muted-foreground">{until ? `resets in ${until}` : 'no reset reported'}</span>
+            </div>
+          );
+        })}
+      </div>
+      <div className="mt-3 border-t pt-2 text-[10px] text-muted-foreground">▸ is the window the strip is showing</div>
     </div>
   );
 }
 
-function level(v: number) {
+/** Human name for a window, derived ONLY from what the payload actually states. `weekly_*` is never
+ *  printed as "weekly"/"7 days": that window rolls on a ~72h cadence, so the kind name is a lie and
+ *  only resets_at (rendered separately) tells the truth about its length. */
+export function windowLabel(l: UsageLimit): string {
+  if (l.scopeLabel) return `${l.scopeLabel} window`;
+  if (l.kind === 'session') return 'current session';
+  if (l.kind === 'weekly_all') return 'all models';
+  return l.kind.replace(/_/g, ' ');
+}
+
+/** The window that gates you first is simply the FULLEST one, whichever kind it is.
+ *  We deliberately ignore the endpoint's `is_active`: observed live on prod, `weekly_all` reports
+ *  `is_active: false` while genuinely accruing (1%, a real future resets_at, corroborated by
+ *  seven_day.utilization: 1.0). So the flag marks the window the vendor considers CURRENTLY binding,
+ *  not "this window is running" — filtering on it under-reports and is falsely reassuring. */
+export function binding(limits: UsageLimit[]): UsageLimit | null {
+  return limits.reduce<UsageLimit | null>((best, l) => (!best || l.percent > best.percent ? l : best), null);
+}
+
+/** Human "time until reset", derived from resets_at only — never from the limit's kind name.
+ *  Rounded to whole minutes FIRST so a value handed in as exactly 4h does not render "3h 59m"
+ *  because a few milliseconds elapsed between building it and reading the clock. */
+export function untilLabel(iso: string | null): string | null {
+  if (!iso) return null;
+  const ms = new Date(iso).getTime() - Date.now();
+  if (!Number.isFinite(ms) || ms <= 0) return null;
+  const min = Math.round(ms / 60_000);
+  if (min < 1) return '1m';
+  if (min < 60) return `${min}m`;
+  const h = Math.floor(min / 60), m = min % 60;
+  if (h < 48) return m ? `${h}h ${m}m` : `${h}h`;
+  const d = Math.floor(h / 24), rh = h % 24;
+  return rh ? `${d}d ${rh}h` : `${d}d`;
+}
+
+/** Only severities we have actually SEEN mean something here. The vendor's vocabulary is not
+ *  documented and not fully observed, so an unrecognised value falls through to the percentage
+ *  thresholds — treating "anything that isn't normal" as elevated would paint the widget a
+ *  permanent amber the first time the endpoint adds a benign new word. */
+const ELEVATED: Record<string, string> = { critical: 'text-red-500', exceeded: 'text-red-500', warning: 'text-amber-500', warn: 'text-amber-500' };
+
+function level(v: number, severity?: string) {
+  const known = severity ? ELEVATED[severity] : undefined;
+  if (known) return known;
   return v >= 90 ? 'text-red-500' : v >= 75 ? 'text-amber-500' : 'text-emerald-500';
 }
 
-function Metric({ label, value, series }: { label: string; value: number; series: number[] }) {
+function Metric({ label, value, series, title, severity }: { label: string; value: number; series?: number[]; title?: string; severity?: string }) {
+  const tone = level(value, severity);
+  // Plain-text fallback only where nothing richer exists (cpu/mem). The usage metric passes no title:
+  // it owns a hover card, and a native tooltip on the same element would double up on it.
+  const tip = title ?? (series ? `${label} ${value}% — last ${series.length} samples` : undefined);
   return (
-    <span className="flex items-center gap-1" title={`${label} ${value}% — last ${series.length} samples`}>
+    <span className="flex items-center gap-1" title={tip}>
       <span className="uppercase tracking-wide">{label}</span>
-      <Sparkline series={series} className={level(value)} />
-      <span className={cn('tabular-nums', level(value))}>{value}%</span>
+      {series ? <Sparkline series={series} className={tone} /> : <Gauge value={value} className={tone} />}
+      <span className={cn('tabular-nums', tone)}>{value}%</span>
     </span>
   );
 }
 
+// Same 40x12 footprint as the sparkline, so the strip stays one row of like-sized glyphs — but it
+// shows a single CURRENT value and is therefore correct and complete on the very first render.
+function Gauge({ value, className }: { value: number; className?: string }) {
+  const W = 40, H = 12, w = (Math.max(0, Math.min(100, value)) / 100) * W;
+  return (
+    <svg width={W} height={H} viewBox={`0 0 ${W} ${H}`} className={cn('overflow-visible', className)} preserveAspectRatio="none">
+      <rect x={0} y={H / 2 - 2} width={W} height={4} rx={2} fill="currentColor" opacity={0.2} />
+      {w > 0 && <rect x={0} y={H / 2 - 2} width={w} height={4} rx={2} fill="currentColor" />}
+    </svg>
+  );
+}
+
 // Inline SVG sparkline (0-100 domain) — no chart lib, fixed viewBox so it scales crisply.
 function Sparkline({ series, className }: { series: number[]; className?: string }) {
   const W = 40, H = 12;
   const n = series.length;
+  if (n < 2) return null; // one point is a dot at x=0, not a trend — draw nothing until it's real
   const pts = series.map((v, i) => {
     const x = n > 1 ? (i / (n - 1)) * W : 0;
     const y = H - (Math.max(0, Math.min(100, v)) / 100) * H;

package/src/client/components/ui/hover-card.tsx

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import * as HoverCardPrimitive from '@radix-ui/react-hover-card';
+import { cn } from '@/lib/utils';
+
+const HoverCard = HoverCardPrimitive.Root;
+const HoverCardTrigger = HoverCardPrimitive.Trigger;
+
+/** Portalled + collision-aware by default: the only consumer today sits in the bottom-left corner of
+ *  a fixed 256px sidebar, so the card MUST be free to flip upward and slide rightward into the main
+ *  pane instead of being clipped by the sidebar box or the viewport edge. */
+const HoverCardContent = React.forwardRef<
+  React.ElementRef<typeof HoverCardPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof HoverCardPrimitive.Content>
+>(({ className, align = 'start', side = 'top', sideOffset = 8, collisionPadding = 8, ...props }, ref) => (
+  <HoverCardPrimitive.Portal>
+    <HoverCardPrimitive.Content
+      ref={ref}
+      align={align}
+      side={side}
+      sideOffset={sideOffset}
+      collisionPadding={collisionPadding}
+      className={cn(
+        'z-50 w-64 rounded-md border bg-card p-3 text-card-foreground shadow-md outline-none',
+        'data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
+        className
+      )}
+      {...props}
+    />
+  </HoverCardPrimitive.Portal>
+));
+HoverCardContent.displayName = HoverCardPrimitive.Content.displayName;
+
+export { HoverCard, HoverCardTrigger, HoverCardContent };

package/src/server/boot.ts

@@ -57,6 +57,7 @@ import { syncVendorRepos } from './vendor-sync.ts';
 import { SelfUpgrade } from './self-upgrade/index.ts';
 import { initEngines, getAvailableEngines, getEngine } from './engine/index.ts';
 import { statsSampler } from './stats.ts';
+import { claudeUsage } from './claude-usage.ts';
 import { getAll as getAllContacts } from './contacts.ts';
 import { artifactsRouter } from './artifacts/artifacts.routes.ts';
 import { handleArtifactToolUse } from './artifacts/artifacts.handler.ts';
@@ -224,6 +225,17 @@ app.get('/api/stats', requireAuth, (_req, res) => {
   res.json({ samples: statsSampler.getStats() });
 });
 
+// Claude Code subscription usage for this box. 204 (not an error, not an empty object) is the
+// deliberate answer whenever we cannot PROVE a subscription — no credentials file, no user:profile
+// scope, or any upstream failure — so the client renders nothing rather than a misleading gauge.
+// Deliberately NOT gated on the active engine: the question is whether Claude Code is configured
+// with a subscription on this host, not which runtime happens to be selected right now.
+app.get('/api/claude-usage', requireAuth, async (_req, res) => {
+  const usage = await claudeUsage.get();
+  if (!usage) return void res.status(204).end();
+  res.json(usage);
+});
+
 app.get('/api/sessions', requireAuth, async (req, res) => {
   const user = (req as any).user;
   // Exclude PTY-only sessions — a standalone/terminal-first shell is not a conversation.

package/src/server/claude-usage.ts

@@ -0,0 +1,148 @@
+// Claude Code subscription usage, read from Anthropic's OAuth usage endpoint using the credentials
+// the Claude Code CLI maintains on this box. Fails CLOSED: every error path returns null, and the
+// caller renders nothing — a broken or zeroed gauge is worse than no gauge.
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const TAG = '[claude-usage]';
+
+/** The endpoint gates on the OAuth token carrying this scope; without it it answers
+ *  403 permission_error and the deployment is effectively API-key-only for our purposes. */
+const REQUIRED_SCOPE = 'user:profile';
+
+/** One limit window as the endpoint reports it. `resetsAt` is passed through verbatim: the caller
+ *  derives any human label from it. NEVER label a `weekly_*` kind "weekly"/"7 days" — that window
+ *  actually rolls on a ~72h cadence, so only resets_at tells the truth. */
+export interface ClaudeUsageLimit {
+  kind: string;
+  group: string;
+  percent: number;
+  severity: string;
+  resetsAt: string | null;
+  /** Present on scoped limits, e.g. a per-model window. */
+  scopeLabel?: string;
+}
+
+export interface ClaudeUsage {
+  subscriptionType: string | null;
+  limits: ClaudeUsageLimit[];
+}
+
+export class ClaudeUsageOptions {
+  credentialsPath = path.join(homedir(), '.claude', '.credentials.json');
+  endpoint = 'https://api.anthropic.com/api/oauth/usage';
+  /** How long a completed upstream result (success OR failure) is reused for. Concurrent callers are
+   *  deduped separately onto one in-flight request, so a reload storm or a wall of open tabs costs at
+   *  most one upstream call per window — this endpoint answers 429 aggressively. Failures are cached
+   *  on the same terms, so a 403/API-key box does not retry on every client poll. */
+  ttlMs = 60_000;
+  timeoutMs = 8_000;
+}
+
+export class ClaudeUsageReader {
+  public options: ClaudeUsageOptions;
+  private cache: { at: number; value: ClaudeUsage | null } | null = null;
+  /** The one upstream request currently in flight, shared by every caller that arrives while it runs.
+   *  Without this the TTL is useless against a stampede: the cache is only written once the request
+   *  RESOLVES, so N simultaneous callers all miss and all hit upstream. */
+  private inflight: Promise<ClaudeUsage | null> | null = null;
+
+  public constructor(options?: Partial<ClaudeUsageOptions>) {
+    this.options = { ...new ClaudeUsageOptions(), ...options };
+  }
+
+  /** null => this box is not on a Claude subscription, or we could not prove that it is. */
+  async get(): Promise<ClaudeUsage | null> {
+    const now = Date.now();
+    if (this.cache && now - this.cache.at < this.options.ttlMs) return this.cache.value;
+    if (this.inflight) return this.inflight;
+    // Clear inflight before the value is handed out, so a rejection can never wedge the reader:
+    // the next call past the TTL starts a fresh request.
+    this.inflight = this.fetchUsage()
+      .then((value) => { this.cache = { at: Date.now(), value }; return value; })
+      .finally(() => { this.inflight = null; });
+    return this.inflight;
+  }
+
+  private async fetchUsage(): Promise<ClaudeUsage | null> {
+    // Re-read the file EVERY time: accessToken lives ~8h and the Claude Code SDK rewrites this file
+    // when it refreshes. A token cached in memory goes stale; a fresh file read never does.
+    const creds = await this.readCredentials();
+    if (!creds) return null;
+
+    try {
+      const res = await fetch(this.options.endpoint, {
+        headers: {
+          Authorization: `Bearer ${creds.accessToken}`,
+          'anthropic-beta': 'oauth-2025-04-20',
+          // MANDATORY. Without a claude-code/<version> UA the endpoint drops us into an aggressively
+          // rate-limited bucket and answers 429 persistently.
+          'User-Agent': `claude-code/${claudeCodeVersion()}`,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(this.options.timeoutMs),
+      });
+      if (!res.ok) {
+        console.warn(`${TAG} usage endpoint returned ${res.status}; hiding widget`);
+        return null;
+      }
+      const body: any = await res.json();
+      const limits = Array.isArray(body?.limits) ? body.limits.map(toLimit).filter(Boolean) as ClaudeUsageLimit[] : [];
+      if (!limits.length) {
+        console.warn(`${TAG} usage response carried no limits[]; hiding widget`);
+        return null;
+      }
+      return { subscriptionType: creds.subscriptionType, limits };
+    } catch (err) {
+      console.warn(`${TAG} usage lookup failed:`, (err as Error).message);
+      return null;
+    }
+  }
+
+  private async readCredentials(): Promise<{ accessToken: string; subscriptionType: string | null } | null> {
+    try {
+      const raw = await readFile(this.options.credentialsPath, 'utf8');
+      const oauth = JSON.parse(raw)?.claudeAiOauth;
+      if (!oauth?.accessToken || typeof oauth.accessToken !== 'string') return null;
+      if (!Array.isArray(oauth.scopes) || !oauth.scopes.includes(REQUIRED_SCOPE)) {
+        console.warn(`${TAG} oauth token lacks the ${REQUIRED_SCOPE} scope; hiding widget`);
+        return null;
+      }
+      return { accessToken: oauth.accessToken, subscriptionType: oauth.subscriptionType ?? null };
+    } catch (err) {
+      // ENOENT is the ordinary API-key deployment, not a fault — keep it quiet at debug level.
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT') console.debug(`${TAG} no credentials file at ${this.options.credentialsPath} (API-key deployment)`);
+      else console.warn(`${TAG} could not read credentials:`, (err as Error).message);
+      return null;
+    }
+  }
+}
+
+function toLimit(l: any): ClaudeUsageLimit | null {
+  if (!l || typeof l.percent !== 'number' || !Number.isFinite(l.percent)) return null;
+  return {
+    kind: String(l.kind ?? 'unknown'),
+    group: String(l.group ?? 'unknown'),
+    percent: Math.max(0, Math.min(100, Math.round(l.percent))),
+    severity: String(l.severity ?? 'normal'),
+    resetsAt: typeof l.resets_at === 'string' ? l.resets_at : null,
+    scopeLabel: l.scope?.model?.display_name ?? undefined,
+  };
+}
+
+let cachedVersion: string | null = null;
+/** Best effort — the endpoint gates on the `claude-code/` PREFIX, not the exact number, so a stale
+ *  fallback still keeps us out of the throttled bucket. */
+function claudeCodeVersion(): string {
+  if (cachedVersion) return cachedVersion;
+  try {
+    const require = createRequire(import.meta.url);
+    cachedVersion = require('@anthropic-ai/claude-agent-sdk/package.json').version || '2.0.0';
+  } catch { cachedVersion = '2.0.0'; }
+  return cachedVersion!;
+}
+
+export const claudeUsage = new ClaudeUsageReader();