@scrylog/cli 0.1.4 → 0.3.0

package/src/tui/model.ts

@@ -0,0 +1,295 @@
+import type { DetectionReason, ProcessInfo, SessionModel, SessionState, SessionTool } from "../shared/types";
+import type { SessionListItem } from "../shared/session-view";
+import { formatDuration, truncate } from "../shared/utils";
+import { BRAND } from "./theme";
+
+export type DashboardView = "sessions" | "usage";
+export type DashboardMode = "list" | "search" | "detail" | "message" | "bindings";
+export type SessionToolFilter = SessionTool | "all";
+export type SessionStateFilter = SessionState | "all";
+
+export interface DashboardFilters {
+  query: string;
+  actionableOnly: boolean;
+  tool: SessionToolFilter;
+  state: SessionStateFilter;
+}
+
+export type DashboardRow = ProjectHeaderRow | SessionRow | GapRow;
+
+export interface ProjectHeaderRow {
+  kind: "project-header";
+  projectKey: string;
+  projectName: string;
+}
+
+export interface SessionRow {
+  kind: "session";
+  projectKey: string;
+  session: SessionListItem;
+}
+
+export interface GapRow {
+  kind: "gap";
+  projectKey: string;
+}
+
+export interface SessionColumnWidths {
+  session: number;
+  state: number;
+  tool: number;
+  summary: number;
+}
+
+export const TOOL_FILTERS: SessionToolFilter[] = ["all", "opencode", "claude", "codex", "copilotcli", "shell", "unknown"];
+export const STATE_FILTERS: SessionStateFilter[] = ["all", "working", "waiting-input", "idle", "shell", "unknown"];
+export const WORKING_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export const STATE_COLORS: Record<string, string> = {
+  working: BRAND.stateWorking,
+  idle: BRAND.stateIdle,
+  "waiting-input": BRAND.violet,
+  shell: BRAND.accentBlue,
+  error: BRAND.danger,
+  unknown: BRAND.grey,
+};
+
+export function applySessionFilters(
+  sessions: SessionListItem[],
+  filters: DashboardFilters,
+  standaloneMaxAgeHours: number,
+): SessionListItem[] {
+  const query = filters.query.toLowerCase();
+  const cutoff = standaloneMaxAgeHours > 0 ? Date.now() - standaloneMaxAgeHours * 3_600_000 : 0;
+  return sessions.filter((session) => {
+    if (session.parentSessionId) {
+      if (session.state !== "working" && session.state !== "waiting-input") return false;
+    } else if (cutoff > 0 && session.source === "standalone" && session.lastActivity < cutoff) {
+      return false;
+    }
+    if (filters.actionableOnly && !(session.hasAttention ?? session.state === "waiting-input")) return false;
+    if (filters.tool !== "all" && session.tool !== filters.tool) return false;
+    if (filters.state !== "all" && session.state !== filters.state) return false;
+    if (!query) return true;
+    const searchable = [
+      session.id,
+      session.tool,
+      session.state,
+      session.summary,
+      session.project?.displayName,
+      session.project?.compactLabel,
+      session.project?.branch,
+      session.displayName,
+      session.tmux?.session,
+      session.herdr?.workspace,
+      session.herdr?.name,
+      session.herdr?.tab,
+      session.herdr?.agent,
+      session.currentPath,
+    ].filter(Boolean).join(" ").toLowerCase();
+    return searchable.includes(query);
+  });
+}
+
+export function cycleFilters(filters: DashboardFilters): DashboardFilters {
+  const nextTool = TOOL_FILTERS[(TOOL_FILTERS.indexOf(filters.tool) + 1) % TOOL_FILTERS.length] ?? "all";
+  if (nextTool !== "all") return { ...filters, tool: nextTool, state: "all" };
+  const nextState = STATE_FILTERS[(STATE_FILTERS.indexOf(filters.state) + 1) % STATE_FILTERS.length] ?? "all";
+  return { ...filters, tool: "all", state: nextState };
+}
+
+function sessionSortWeight(session: SessionListItem): number {
+  // Active work first (working/waiting), then idle workloads.
+  const statePenalty = session.state === "working" ? 0 : session.state === "waiting-input" ? 20 : 60;
+  const toolPenalty = session.tool === "unknown" ? 30 : session.tool === "shell" ? 20 : 0;
+  return statePenalty + toolPenalty;
+}
+
+function groupSortWeight(group: { sessions: SessionListItem[] }): number {
+  const minWeight = Math.min(...group.sessions.map(sessionSortWeight));
+  return group.sessions.every((session) => !session.project) ? 1000 + minWeight : minWeight;
+}
+
+export function buildRows(sessions: SessionListItem[], narrow = false): DashboardRow[] {
+  const roots = sessions.filter((session) => !session.parentSessionId);
+  const childrenByParent = new Map<string, SessionListItem[]>();
+  for (const session of sessions) {
+    if (!session.parentSessionId) continue;
+    const children = childrenByParent.get(session.parentSessionId) ?? [];
+    children.push(session);
+    childrenByParent.set(session.parentSessionId, children);
+  }
+
+  const groups = new Map<string, { projectName: string; sessions: SessionListItem[] }>();
+  for (const session of roots) {
+    const key = getProjectGroupKey(session);
+    const group = groups.get(key);
+    if (group) {
+      group.sessions.push(session);
+    } else {
+      groups.set(key, {
+        projectName: session.project?.displayName ?? (session.source === "standalone"
+          ? (session.tool !== "unknown" ? session.tool : "standalone")
+          : session.source === "herdr"
+          ? session.herdr?.workspace ?? "herdr"
+          : session.tmux?.session ?? key),
+        sessions: [session],
+      });
+    }
+  }
+
+  const recency = (group: { sessions: SessionListItem[] }) => Math.max(...group.sessions.map((s) => s.lastActivity));
+  const sortedGroups = [...groups.entries()].sort(
+    ([, left], [, right]) => groupSortWeight(left) - groupSortWeight(right) || recency(right) - recency(left),
+  );
+  const rows: DashboardRow[] = sortedGroups.length > 0 ? [{ kind: "gap", projectKey: "__initial-gap__" }] : [];
+  sortedGroups.forEach(([projectKey, group], groupIndex) => {
+    if (groupIndex > 0) rows.push({ kind: "gap", projectKey });
+    group.sessions.sort((left, right) => sessionSortWeight(left) - sessionSortWeight(right) || right.lastActivity - left.lastActivity);
+    rows.push({ kind: "project-header", projectKey, projectName: group.projectName });
+    for (const session of group.sessions) {
+      rows.push({ kind: "session", projectKey, session });
+      if (!narrow) {
+        const children = (childrenByParent.get(session.id) ?? []).sort(
+          (left, right) => sessionSortWeight(left) - sessionSortWeight(right) || right.lastActivity - left.lastActivity,
+        );
+        for (const child of children) rows.push({ kind: "session", projectKey, session: child });
+      }
+    }
+  });
+  return rows;
+}
+
+function getProjectGroupKey(session: SessionListItem): string {
+  return session.project?.repositoryIdentityPath
+    ?? session.project?.gitRootPath
+    ?? session.project?.sourcePath
+    ?? session.project?.displayName
+    ?? (session.source === "standalone"
+      ? `standalone:${session.tool}`
+      : session.source === "herdr"
+      ? `herdr:${session.herdr?.workspaceId ?? session.herdr?.workspace ?? session.herdr?.paneId ?? session.id}`
+      : session.tmux?.session ?? session.id);
+}
+
+export function moveSelection(rows: DashboardRow[], selectedId: string | undefined, direction: 1 | -1): string | undefined {
+  if (rows.length === 0) return selectedId;
+  if (!selectedId) {
+    const candidates = direction > 0 ? rows : [...rows].reverse();
+    return candidates.find((row): row is SessionRow => row.kind === "session")?.session.id;
+  }
+  const current = rows.findIndex((row) => row.kind === "session" && row.session.id === selectedId);
+  if (current < 0) return undefined;
+  for (let index = current + direction; index >= 0 && index < rows.length; index += direction) {
+    const row = rows[index];
+    if (row?.kind === "session") return row.session.id;
+  }
+  return selectedId;
+}
+
+export function visibleRowWindow(rows: DashboardRow[], selectedId: string | undefined, limit: number): DashboardRow[] {
+  if (rows.length <= limit) return rows;
+  const selected = rows.findIndex((row) => row.kind === "session" && row.session.id === selectedId);
+  const start = Math.max(0, Math.min(selected - Math.floor(limit / 2), rows.length - limit));
+  return rows.slice(start, start + limit);
+}
+
+export function stateGlyph(state: string, spinnerFrame = 0): string {
+  if (state === "working") return WORKING_FRAMES[spinnerFrame % WORKING_FRAMES.length] ?? WORKING_FRAMES[0]!;
+  if (state === "idle") return "○";
+  if (state === "waiting-input") return "?";
+  if (state === "shell") return ">";
+  if (state === "error") return "✗";
+  return "?";
+}
+
+function formatBranchLabel(session: SessionListItem): string {
+  if (!session.project?.isGitRepository) return "";
+  return session.project.branch || "detached";
+}
+
+export function formatTargetLabel(session: SessionListItem, narrow = false): string {
+  let base: string;
+  if (session.parentSessionId) {
+    base = `    ↳ ${truncate(session.summary || session.id, narrow ? 22 : 26)}`;
+  } else if (session.tmux) {
+    const label = session.displayName?.trim()
+      || session.tmux.session?.trim()
+      || session.id;
+    base = `  ▸ ${label}`;
+  } else if (session.herdr) {
+    const label = session.displayName?.trim()
+      || session.herdr.tab?.trim()
+      || session.herdr.agent?.trim()
+      || session.herdr.paneId;
+    base = `  ▹ ${label}`;
+  } else {
+    const placeholder = session.activeTool
+      ? `[${session.activeTool}]`
+      : (session.id.includes(":") ? session.id.split(":")[1]!.slice(0, 8) : session.id.slice(0, 8));
+    base = `  ◇ ${placeholder}`;
+  }
+  const branch = formatBranchLabel(session);
+  return branch ? `${base}@${branch}` : base;
+}
+
+export type SessionToolMode = "text" | "monogram" | "icons";
+
+export function sessionColumnWidths(width: number, toolMode: SessionToolMode = "text", toolContentWidth = 0): SessionColumnWidths {
+  const narrow = width < 110;
+  const available = Math.max(36, width - 9);
+  if (narrow) {
+    const enhanced = toolMode !== "text";
+    const state = 11;
+    // On very narrow widths the summary column is a few truncated characters;
+    // drop it entirely and hand its space to the session column. The budget
+    // matches the pane's real content width (borders + padding + gutter) so
+    // rows fill from border to border.
+    if (width < 100) {
+      const filledAvailable = Math.max(36, width - 6);
+      const tool = Math.max(5, (toolContentWidth || (toolMode === "text" ? 10 : 7)) + 1);
+      return { session: Math.max(14, filledAvailable - state - tool), state, tool, summary: 0 };
+    }
+    const tool = toolMode === "text"
+      ? Math.min(12, Math.max(9, Math.floor(available * 0.18)))
+      : toolMode === "icons" ? 7 : 8;
+    const session = Math.min(enhanced ? 32 : 28, Math.max(14, Math.floor(available * (enhanced ? 0.4 : 0.34))));
+    return { session, state, tool, summary: Math.max(8, available - session - state - tool) };
+  }
+  const state = 11;
+  const tool = toolMode === "text" ? 13 : toolMode === "icons" ? 3 : 5;
+  if (toolMode !== "text") {
+    const remaining = available - state - tool;
+    const session = Math.min(72, Math.max(30, Math.floor(remaining * 0.55)));
+    return { session, state, tool, summary: Math.max(8, available - session - state - tool) };
+  }
+  const session = Math.min(40, Math.max(30, available - state - tool - 39));
+  return { session, state, tool, summary: Math.max(8, available - session - state - tool) };
+}
+
+export function formatStatusCell(session: SessionListItem, spinnerFrame: number): string {
+  const glyph = stateGlyph(session.state, spinnerFrame);
+  return `${glyph} (${formatDuration(session.stableForMs ?? 0)})`;
+}
+
+export function activeChildCounts(sessions: SessionListItem[]): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const session of sessions) {
+    if (!session.parentSessionId || (session.state !== "working" && session.state !== "waiting-input")) continue;
+    counts.set(session.parentSessionId, (counts.get(session.parentSessionId) ?? 0) + 1);
+  }
+  return counts;
+}
+
+export function sessionAttachCommand(session: SessionListItem, insideTmux: boolean): string[] | null {
+  if (session.source === "tmux" && session.tmux) {
+    return insideTmux
+      ? ["tmux", "switch-client", "-t", session.tmux.session]
+      : ["tmux", "attach-session", "-t", session.tmux.session];
+  }
+  if (session.source === "herdr" && session.herdr?.terminalId) {
+    return ["herdr", "terminal", "attach", session.herdr.terminalId];
+  }
+  return null;
+}
+

package/src/tui/state.ts

@@ -0,0 +1,77 @@
+import type { SessionModel } from "../shared/types";
+import type { SessionListItem, SessionViewCounts } from "../shared/session-view";
+import type { UsageState } from "../usage/types";
+import { cycleFilters, type DashboardFilters, type DashboardMode, type DashboardView } from "./model";
+
+export interface DashboardState {
+  view: DashboardView;
+  mode: DashboardMode;
+  sessions: SessionListItem[];
+  counts: SessionViewCounts | null;
+  usage: UsageState;
+  selectedSessionId?: string;
+  detail?: SessionModel;
+  message?: string;
+  daemonConnected: boolean;
+  filters: DashboardFilters;
+}
+
+export const INITIAL_DASHBOARD_STATE: DashboardState = {
+  view: "sessions",
+  mode: "list",
+  sessions: [],
+  counts: null,
+  usage: { providers: [], lastRefreshedAt: 0 },
+  daemonConnected: true,
+  filters: { query: "", actionableOnly: false, tool: "all", state: "all" },
+};
+
+export type DashboardAction =
+  | { type: "sessions-loaded"; sessions: SessionListItem[]; counts: SessionViewCounts }
+  | { type: "usage-loaded"; usage: UsageState }
+  | { type: "connection"; connected: boolean }
+  | { type: "select"; id?: string }
+  | { type: "view"; view: DashboardView }
+  | { type: "search" }
+  | { type: "query"; query: string }
+  | { type: "toggle-actionable" }
+  | { type: "cycle-filters" }
+  | { type: "detail"; session: SessionModel }
+  | { type: "message"; message: string }
+  | { type: "bindings" }
+  | { type: "close-overlay" };
+
+export function dashboardReducer(state: DashboardState, action: DashboardAction): DashboardState {
+  switch (action.type) {
+    case "sessions-loaded": {
+      const selectedSessionId = action.sessions.some((session) => session.id === state.selectedSessionId)
+        ? state.selectedSessionId
+        : undefined;
+      return { ...state, sessions: action.sessions, counts: action.counts, selectedSessionId, daemonConnected: true };
+    }
+    case "usage-loaded":
+      return { ...state, usage: action.usage };
+    case "connection":
+      return { ...state, daemonConnected: action.connected };
+    case "select":
+      return { ...state, selectedSessionId: action.id };
+    case "view":
+      return { ...state, view: action.view, mode: "list", detail: undefined, message: undefined };
+    case "search":
+      return { ...state, mode: "search" };
+    case "query":
+      return { ...state, filters: { ...state.filters, query: action.query } };
+    case "toggle-actionable":
+      return { ...state, filters: { ...state.filters, actionableOnly: !state.filters.actionableOnly } };
+    case "cycle-filters":
+      return { ...state, filters: cycleFilters(state.filters) };
+    case "detail":
+      return { ...state, mode: "detail", detail: action.session, message: undefined };
+    case "message":
+      return { ...state, mode: "message", message: action.message, detail: undefined };
+    case "bindings":
+      return { ...state, mode: "bindings", detail: undefined, message: undefined };
+    case "close-overlay":
+      return { ...state, mode: "list", detail: undefined, message: undefined };
+  }
+}

package/src/tui/theme.ts

@@ -0,0 +1,110 @@
+/**
+ * Scrylog brand palette (source: brand guide, OpenTUI-compatible ANSI sheet).
+ *
+ * Single source of truth for every color used by the TUI: change a value here
+ * (or swap the whole object for an alternate theme) and the whole UI follows.
+ */
+export const BRAND = {
+  /** Main Teal/Cyan — primary brand color (xterm 80). */
+  primary: "#5CCCCC",
+  /** Accent Light Blue (xterm 159). */
+  accentBlue: "#A1E6FF",
+  /** Highlight Violet (xterm 177). */
+  violet: "#CFA6FF",
+  /** Detail Grey — secondary text (xterm 246). */
+  grey: "#A0A0A0",
+  /** Background Dark (xterm 234). */
+  bgDark: "#1A1A1A",
+  /** Modal / floating panel surface (near-black, kept from legacy scheme). */
+  surface: "#11151c",
+  /** Functional colors kept unchanged (no palette equivalent). */
+  danger: "#f05252",
+  warning: "#f5a524",
+
+  /** Legacy chrome visuals preserved by design: pane borders and separators. */
+  border: "#495365",
+  /** Selected session row background (legacy slate). */
+  selection: "#263244",
+  /** Fallback foreground for rows whose state has no mapping. */
+  fallback: "#d8dee9",
+
+  /** Session state colors (palette-family tints). */
+  stateWorking: "#E8BC5D",
+  stateIdle: "#6BD9A4",
+  /** Usage semaphore ≥90% (soft coral, danger family). */
+  usageHigh: "#E28686",
+} as const;
+
+export interface ProviderVisual {
+  name: string;
+  short: string;
+  brandColor: string;
+  borderColor: string;
+  /** Alternative brand color readable on dark terminal backgrounds. */
+  onDarkColor?: string;
+  tileColor?: string;
+  terminalAsset?: URL;
+  graphicsAsset?: URL;
+}
+
+/** Third-party provider brand colors: data, not brand palette. */
+export const PROVIDER_BRANDS: Record<string, ProviderVisual> = {
+  claude: {
+    name: "Claude",
+    short: "CL",
+    brandColor: "#d97757",
+    borderColor: "#d97757",
+    terminalAsset: new URL("./assets/providers/claude-terminal.png", import.meta.url),
+    graphicsAsset: new URL("./assets/providers/claude.png", import.meta.url),
+  },
+  codex: {
+    name: "Codex",
+    short: "CX",
+    brandColor: "#539af8",
+    borderColor: "#539af8",
+    terminalAsset: new URL("./assets/providers/openai-terminal.png", import.meta.url),
+    graphicsAsset: new URL("./assets/providers/openai.png", import.meta.url),
+  },
+  "opencode-go": {
+    name: "OpenCode Go",
+    short: "OC",
+    brandColor: "#111111",
+    onDarkColor: "#c8cdd8",
+    borderColor: BRAND.grey,
+    tileColor: "#f3f3f3",
+    terminalAsset: new URL("./assets/providers/opencode-terminal.png", import.meta.url),
+    graphicsAsset: new URL("./assets/providers/opencode.png", import.meta.url),
+  },
+  copilot: {
+    name: "Copilot",
+    short: "CP",
+    brandColor: "#c8cdd8",
+    borderColor: BRAND.grey,
+    graphicsAsset: new URL("./assets/providers/copilot.png", import.meta.url),
+  },
+  shell: {
+    name: "Shell",
+    short: "SH",
+    brandColor: "#c8cdd8",
+    borderColor: BRAND.grey,
+    graphicsAsset: new URL("./assets/providers/shell.png", import.meta.url),
+  },
+  unknown: {
+    name: "Unknown",
+    short: "?",
+    brandColor: BRAND.grey,
+    borderColor: BRAND.grey,
+    graphicsAsset: new URL("./assets/providers/unknown.png", import.meta.url),
+  },
+};
+
+export const BRAND_MARK = {
+  /** Blocks: front-view crystal ball + prompt + circuit pedestal, brand palette. */
+  art: [
+    { fg: BRAND.accentBlue, content: "  ▗▄▄▄▄▄▄▖" },
+    { fg: BRAND.primary, content: " ▐▓▒░░░░▒▓▌" },
+    { fg: BRAND.primary, content: " ░ ◉◈◉ ›_ ░" },
+    { fg: BRAND.violet, content: " ▜▓▒░░░░▒▓▛" },
+    { fg: BRAND.violet, content: "  ▐█╿██╵█▌" },
+  ],
+} as const;

package/src/usage/README.md

@@ -297,7 +297,7 @@ These clients use the global `fetch` and have no Node.js or platform dependencie
 |---|---|---|
 | `enabled` | `true` | Enable usage collection |
 | `pollIntervalMs` | `300000` | Polling interval (5 minutes) |
-| `providers` | `["claude", "opencode-go"]` | Which providers to poll |
+| `providers` | `["claude", "opencode-go", "codex"]` | Which providers to poll |
 | `claude.dataSource` | `"auto"` | `"auto"`, `"oauth"`, `"web"`, or `"cli"` |
 | `claude.webExtrasEnabled` | `true` | Enrich OAuth/CLI with Web API extras |
 | `codex.dataSource` | `"auto"` | `"auto"` or `"oauth"` |
@@ -311,7 +311,7 @@ These clients use the global `fetch` and have no Node.js or platform dependencie
 | Claude OAuth (`~/.claude/.credentials.json`) | ⚠️ (fallback only) | ✅ | ✅ | ✅ |
 | Claude Web (browser cookies) | ✅ (Chrome + Safari) | ✅ (Chrome/Chromium) | ✅ (Chrome/Chromium) | ❌ (Chrome: DPAPI not implemented) |
 | Claude CLI (PTY probe) | ✅ (`script` wrapper) | ⚠️ (no PTY wrapper) | ⚠️ (no PTY wrapper) | ⚠️ (no PTY wrapper) |
-| Codex OAuth (`~/.codex/auth.json`) | ✅ | ✅ | ✅ | ✅ (filepath) |
+| Codex OAuth + owner CLI recovery | ✅ | ✅ | ✅ | ⚠️ (CLI launch is experimental) |
 | OpenCode Go (browser cookies) | ✅ | ✅ | ✅ | ❌ (Chrome: DPAPI not implemented) |
 
 ## Adding a new provider
@@ -319,5 +319,5 @@ These clients use the global `fetch` and have no Node.js or platform dependencie
 1. Create resolver + client in `src/usage/resolvers/` and `src/usage/clients/`
 2. Create provider in `src/usage/providers/<name>.ts` that returns `{ entry: UsageProviderEntry, snapshot: any }`
 3. Add mapper in `src/usage/mappers.ts`: `map<Name>ToEntry(snapshot, errors, available)` — include `accountId` computation
-4. Register in `UsageCollector.poll()` with availability pre-check
+4. Register in `UsageCollector.poll()`; the provider returns an unavailable entry when credentials are absent
 5. No changes needed to `UsageState`, Zod schemas, or API route

package/src/usage/clients/anthropic-oauth-usage.ts

@@ -1,27 +1,91 @@
 import type { UsageClient } from "../client";
 import type { ClaudeOAuthCredentials, ClaudeUsageSnapshot, NamedRateWindowLegacy, ProviderCostSnapshotLegacy, RateWindowLegacy } from "../types";
+import { classifyUsageError, UsageError } from "../errors";
 
-export class AuthenticationError extends Error {
+export class AuthenticationError extends UsageError {
   constructor(message: string) {
-    super(message);
+    super("invalid-credentials", message);
     this.name = "AuthenticationError";
   }
 }
 
-export class ScopeError extends Error {
+export class ScopeError extends UsageError {
   constructor(message: string) {
-    super(message);
+    super("forbidden", message);
     this.name = "ScopeError";
   }
 }
 
-export class ParseError extends Error {
+export class ParseError extends UsageError {
   constructor(message: string) {
-    super(message);
+    super("invalid-response", message);
     this.name = "ParseError";
   }
 }
 
+export interface OAuthProfileIdentity {
+  email: string | null;
+  organizationId: string | null;
+}
+
+function readTrimmedString(record: Record<string, unknown> | undefined | null, keys: string[]): string | null {
+  if (!record || typeof record !== "object" || Array.isArray(record)) return null;
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return null;
+}
+
+export function parseOAuthProfile(data: unknown): OAuthProfileIdentity {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    return { email: null, organizationId: null };
+  }
+  const root = data as Record<string, unknown>;
+  const account = root["account"] as Record<string, unknown> | null | undefined;
+  const organization = root["organization"] as Record<string, unknown> | null | undefined;
+  const email = readTrimmedString(account, ["emailAddress", "email_address", "email"])
+    ?? readTrimmedString(root, ["emailAddress", "email_address", "email"]);
+  const organizationId = readTrimmedString(organization, ["uuid"])
+    ?? readTrimmedString(root, ["organizationUuid", "organization_uuid"]);
+  return { email, organizationId };
+}
+
+export async function fetchOAuthProfile(
+  accessToken: string,
+  options?: { signal?: AbortSignal },
+): Promise<OAuthProfileIdentity> {
+  let res: Response;
+  try {
+    res = await fetch("https://api.anthropic.com/api/oauth/profile", {
+      signal: options?.signal,
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: "application/json",
+        "Content-Type": "application/json",
+      },
+    });
+  } catch (error) {
+    throw classifyUsageError(error);
+  }
+  if (res.status === 401) {
+    throw new AuthenticationError("OAuth profile unauthorized");
+  }
+  if (res.status >= 500) {
+    throw new UsageError("transient", `OAuth profile server error: ${res.status}`);
+  }
+  if (!res.ok) {
+    throw new UsageError("invalid-response", `Unexpected OAuth profile response: ${res.status}`);
+  }
+  let data: unknown;
+  try {
+    data = await res.json();
+  } catch {
+    throw new ParseError("OAuth profile response was not valid JSON");
+  }
+  return parseOAuthProfile(data);
+}
+
 interface OAuthUsageResponse {
   five_hour?: { utilization?: number | null; resets_at?: string | null } | null;
   seven_day?: { utilization?: number | null; resets_at?: string | null } | null;
@@ -89,15 +153,20 @@ function toRateWindow(
 
 export class AnthropicOAuthUsageClient implements UsageClient<ClaudeOAuthCredentials, ClaudeUsageSnapshot> {
   async fetch(creds: ClaudeOAuthCredentials, options?: { signal?: AbortSignal }): Promise<ClaudeUsageSnapshot> {
-    const res = await fetch("https://api.anthropic.com/api/oauth/usage", {
-      signal: options?.signal,
-      headers: {
-        Authorization: `Bearer ${creds.accessToken}`,
-        Accept: "application/json",
-        "Content-Type": "application/json",
-        "anthropic-beta": "oauth-2025-04-20",
-      },
-    });
+    let res: Response;
+    try {
+      res = await fetch("https://api.anthropic.com/api/oauth/usage", {
+        signal: options?.signal,
+        headers: {
+          Authorization: `Bearer ${creds.accessToken}`,
+          Accept: "application/json",
+          "Content-Type": "application/json",
+          "anthropic-beta": "oauth-2025-04-20",
+        },
+      });
+    } catch (error) {
+      throw classifyUsageError(error);
+    }
 
     if (res.status === 401) {
       throw new AuthenticationError("OAuth token expired or invalid");
@@ -107,13 +176,23 @@ export class AnthropicOAuthUsageClient implements UsageClient<ClaudeOAuthCredent
       if (body.includes("user:profile")) {
         throw new ScopeError("Token missing required scope user:profile");
       }
-      throw new Error(`Server error: ${res.status}`);
+      throw new ScopeError(`OAuth access forbidden (${res.status})`);
     }
+    if (res.status === 429) {
+      const retryAfter = Number(res.headers.get("retry-after"));
+      throw new UsageError("rate-limited", "OAuth usage request rate limited", Number.isFinite(retryAfter) ? retryAfter * 1000 : undefined);
+    }
+    if (res.status >= 500) throw new UsageError("transient", `OAuth usage server error: ${res.status}`);
     if (!res.ok) {
-      throw new Error(`Server error: ${res.status}`);
+      throw new UsageError("invalid-response", `Unexpected OAuth usage response: ${res.status}`);
     }
 
-    const data = (await res.json()) as OAuthUsageResponse;
+    let data: OAuthUsageResponse;
+    try {
+      data = (await res.json()) as OAuthUsageResponse;
+    } catch {
+      throw new ParseError("OAuth usage response was not valid JSON");
+    }
 
     if (!data.five_hour || typeof data.five_hour.utilization !== "number") {
       throw new ParseError("Missing five_hour.utilization");
@@ -170,9 +249,10 @@ export class AnthropicOAuthUsageClient implements UsageClient<ClaudeOAuthCredent
       updatedAt: new Date(),
       accountEmail: null,
       accountOrganization: null,
+      accountOrganizationId: null,
       loginMethod: null,
-      subscriptionType: null,
-      rateLimitTier: null,
+      subscriptionType: creds.subscriptionType ?? null,
+      rateLimitTier: creds.rateLimitTier ?? null,
     };
   }
 }