@scrylog/cli 0.1.0

package/src/usage/README.md

@@ -0,0 +1,323 @@
+# Usage Limits API
+
+The Usage Limits API provides subscription usage data for AI coding agent providers (Claude Code, OpenAI Codex, OpenCode Go) via a single unified endpoint.
+
+## Endpoint
+
+```
+GET /api/usage
+```
+
+Returns current usage data for all configured providers, sourced from the daemon's in-memory cache (refreshed every 5 minutes by default).
+
+Usage collection is optional. Set `usage.enabled` to `false` in the scrylog config to stop all periodic Claude/Codex/OpenCode Go usage probes while keeping session monitoring enabled:
+
+```json
+{
+  "usage": {
+    "enabled": false
+  }
+}
+```
+
+When disabled, the daemon does not register the usage collector and does not make external usage requests. This is a normal operational state, not an error.
+
+## Response format
+
+```typescript
+interface UsageState {
+  providers: UsageProviderEntry[];
+  lastRefreshedAt: number; // Unix timestamp in milliseconds
+}
+```
+
+### `UsageProviderEntry`
+
+All providers share the same response shape. No discriminated union.
+
+```typescript
+interface UsageProviderEntry {
+  provider: string;                    // "claude" | "opencode-go"
+  accountId: string | null;            // stable account identifier for grouping across hosts
+  available: boolean;                  // credentials detected on this machine?
+  status: "ok" | "error" | "unavailable" | "pending";
+  metadata?: {
+    dataSource?: string;               // "oauth", "web", "cli"
+    accountEmail?: string | null;
+    accountOrganization?: string | null;
+    subscriptionType?: string | null;  // "pro", "free"
+    rateLimitTier?: string | null;
+    workspaceId?: string | null;       // OpenCode Go
+    workspaceName?: string | null;     // OpenCode Go
+  };
+  errors?: string[];                   // only when status === "error"
+  windows?: UsageWindow[];             // standardized usage windows
+  cost?: ProviderCostSnapshot | null;  // optional overage/cost data
+  updatedAt?: string;                  // ISO 8601
+}
+```
+
+### `UsageWindow`
+
+```typescript
+interface UsageWindow {
+  id: string;              // "session", "weekly", "monthly", "designs"
+  title: string;           // "Current Session", "Weekly"
+  usedPercent: number;     // 0-100
+  used?: number;           // absolute usage (requests, tokens, credits)
+  limit?: number;          // absolute limit
+  windowMinutes?: number;  // window duration
+  resetsAt?: string | null; // ISO 8601 timestamp
+  resetInSec?: number;     // seconds until reset (computed if missing)
+}
+```
+
+### `ProviderCostSnapshot`
+
+```typescript
+interface ProviderCostSnapshot {
+  used: number;
+  limit: number;
+  currency: string;        // "USD"
+  period: string;          // "Monthly"
+  resetsAt?: string | null;
+  updatedAt: string;       // ISO 8601
+}
+```
+
+## Account identification (`accountId`)
+
+`accountId` is designed to be **stable across hosts** so that a future mobile/web app can group usage by account.
+
+| Provider | `accountId` strategy | Example |
+|---|---|---|
+| **Claude** | 1. Email (Web API) → 2. `claude-{subscriptionType}-{rateLimitTier}-{scopesHash}` (Keychain fallback) | `"user@acme.com"` or `"claude-pro-default_claude_ai-0db07b08"` |
+| **OpenCode Go** | `workspaceId` from `_server` response | `"wrk_01KQ0X20G68BQG4KV5Q969Z5GV"` |
+| **Codex** | 1. `account_id` from `tokens` object → 2. `sub` claim from access token JWT | `"388604f4-d26c-4167-bb85-13616dc80a39"` |
+
+When `status === "unavailable"` or `status === "error"` with no identity data, `accountId` is `null`.
+
+## Status semantics
+
+| Status | Meaning | `windows` | `errors` | `accountId` |
+|---|---|---|---|---|
+| `ok` | Data fetched successfully | Present | Absent | Computed from best available source |
+| `error` | Credentials found but fetch failed | Absent | Present | From creds metadata if available |
+| `unavailable` | No credentials on this machine | Absent | Absent | `null` |
+| `pending` | First poll not yet complete | Absent | Absent | `null` |
+
+## Example responses
+
+### All providers available with data
+
+```json
+{
+  "providers": [
+    {
+      "provider": "claude",
+      "accountId": "claude-pro-default_claude_ai-0db07b08",
+      "available": true,
+      "status": "ok",
+      "metadata": {
+        "dataSource": "oauth",
+        "accountEmail": null,
+        "subscriptionType": "pro",
+        "rateLimitTier": "default_claude_ai"
+      },
+      "windows": [
+        { "id": "session", "title": "Current Session", "usedPercent": 0, "windowMinutes": 300, "resetsAt": "2026-04-30T09:40:00Z", "resetInSec": 11537 },
+        { "id": "weekly", "title": "Weekly", "usedPercent": 36, "windowMinutes": 10080, "resetsAt": "2026-04-30T17:00:00Z", "resetInSec": 37937 },
+        { "id": "claude-design", "title": "Designs", "usedPercent": 0, "windowMinutes": 10080, "resetsAt": null }
+      ],
+      "cost": null,
+      "updatedAt": "2026-04-30T06:27:42Z"
+    },
+    {
+      "provider": "opencode-go",
+      "accountId": "wrk_01KQ0X20G68BQG4KV5Q969Z5GV",
+      "available": true,
+      "status": "ok",
+      "metadata": {
+        "dataSource": "web",
+        "workspaceId": "wrk_01KQ0X20G68BQG4KV5Q969Z5GV",
+        "workspaceName": "Default"
+      },
+      "windows": [
+        { "id": "session", "title": "Rolling", "usedPercent": 16, "resetInSec": 12094, "resetsAt": "2026-04-30T09:49:18Z" },
+        { "id": "weekly", "title": "Weekly", "usedPercent": 29, "resetInSec": 322336, "resetsAt": "2026-05-04T00:00:00Z" },
+        { "id": "monthly", "title": "Monthly", "usedPercent": 33, "resetInSec": 2134791, "resetsAt": "2026-05-24T23:27:35Z" }
+      ],
+      "updatedAt": "2026-04-30T06:27:44Z"
+    }
+  ],
+  "lastRefreshedAt": 1777530462243
+}
+```
+
+### Provider unavailable (no credentials)
+
+```json
+{
+  "providers": [
+    {
+      "provider": "claude",
+      "accountId": null,
+      "available": false,
+      "status": "unavailable"
+    }
+  ],
+  "lastRefreshedAt": 1777528387102
+}
+```
+
+### Provider with fetch errors
+
+```json
+{
+  "providers": [
+    {
+      "provider": "claude",
+      "accountId": null,
+      "available": true,
+      "status": "error",
+      "errors": ["oauth: Server error: 401", "web: Session cookie invalid"]
+    }
+  ],
+  "lastRefreshedAt": 1777528387102
+}
+```
+
+## Architecture
+
+```
+DaemonStore
+  └── usage: UsageState
+        └── providers: UsageProviderEntry[]
+
+UsageCollector (polls every 5 min)
+  ├── ClaudeUsageProvider
+  │     ├── ClaudeSourcePlanner (decides oauth/web/cli/auto)
+  │     ├── ClaudeKeychainResolver → AnthropicOAuthUsageClient
+  │     ├── ClaudeWebResolver → AnthropicWebUsageClient
+  │     └── ClaudeCliResolver → ClaudeCliProbeClient
+  │     └── mapClaudeToEntry(oauthCreds) → UsageProviderEntry + accountId
+  ├── CodexUsageProvider
+  │     └── CodexAuthResolver → CodexOAuthUsageClient
+  │     └── mapCodexToEntry() → UsageProviderEntry + accountId
+  └── OpenCodeGoUsageProvider
+        ├── OpenCodeGoWebResolver
+        └── OpenCodeGoUsageClient (resolves workspace id+name)
+        └── mapOpenCodeGoToEntry() → UsageProviderEntry + accountId
+```
+
+## Universal API (React Native / Testing)
+
+For consumers that already hold credentials (React Native apps, test scripts, external integrations):
+
+```typescript
+import { UsageApi } from "scrylog/usage";
+
+// Claude OAuth — token from SecureStore / user input
+const entry = await UsageApi.claude.fromOAuthToken({
+  accessToken: "sk-ant-oat01-...",
+});
+
+// Claude OAuth + Web extras (designs, routines, overage cost)
+const entry = await UsageApi.claude.fromOAuthTokenWithWebExtras(
+  { accessToken: "sk-ant-oat01-..." },
+  { cookieHeader: "sessionKey=abc; intercom-id=xyz" }
+);
+
+// Claude Web — session cookies from WebView / cookie jar
+const entry = await UsageApi.claude.fromWebSession({
+  cookieHeader: "sessionKey=abc; ...",
+});
+
+// OpenCode Go — cookies + serverFnId
+const entry = await UsageApi.opencodeGo.fromCookies({
+  cookies: "sessionId=abc; csrf=xyz",
+  serverFnId: "def39973...",
+});
+
+// Codex OAuth — token from ~/.codex/auth.json
+const entry = await UsageApi.codex.fromOAuthToken({
+  accessToken: "eyJhbGciOiJIUzI1NiIs...",
+});
+```
+
+All methods return `Promise<UsageProviderEntry>`. They never throw — on failure they return `status: "error"` with `errors` populated.
+
+### Raw clients (advanced)
+
+If you need the raw provider-specific snapshot before mapping:
+
+```typescript
+import { AnthropicOAuthUsageClient, CodexOAuthUsageClient } from "scrylog/usage";
+
+const claudeClient = new AnthropicOAuthUsageClient();
+const claudeSnapshot = await claudeClient.fetch({ accessToken: "..." });
+
+const codexClient = new CodexOAuthUsageClient();
+const codexSnapshot = await codexClient.fetch({ accessToken: "...", accountId: "..." });
+```
+
+These clients use the global `fetch` and have no Node.js or platform dependencies.
+
+## Security
+
+- OAuth tokens and browser cookies are read from OS stores (macOS Keychain, Chrome/Safari cookie databases)
+- Credentials are held in memory **only** during the HTTP call
+- Never written to disk, never logged, never included in API responses
+- Chrome cookie decryption uses AES-128-CBC via Keychain "Chrome Safe Storage"
+
+## Configuration
+
+```typescript
+// scrylog.config.json
+{
+  "usage": {
+    "enabled": true,
+    "pollIntervalMs": 300000,
+    "providers": ["claude", "opencode-go", "codex"],
+    "claude": {
+      "dataSource": "auto",
+      "webExtrasEnabled": true
+    },
+    "codex": {
+      "dataSource": "auto"
+    },
+    "opencodeGo": {
+      "serverFnId": "def39973159c7f0483d8793a822b8dbb10d067e12c65455fcb4608459ba0234f"
+    }
+  }
+}
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `enabled` | `true` | Enable usage collection |
+| `pollIntervalMs` | `300000` | Polling interval (5 minutes) |
+| `providers` | `["claude", "opencode-go"]` | 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"` |
+| `opencodeGo.serverFnId` | hardcoded | Server function ID for workspace resolution |
+
+## Platform support
+
+| Feature | macOS | Linux | WSL | Windows |
+|---|---|---|---|---|
+| Claude OAuth (Keychain) | ✅ | ❌ | ❌ | ❌ |
+| 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) |
+| OpenCode Go (browser cookies) | ✅ | ✅ | ✅ | ❌ (Chrome: DPAPI not implemented) |
+
+## Adding a new provider
+
+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
+5. No changes needed to `UsageState`, Zod schemas, or API route

package/src/usage/api.ts

@@ -0,0 +1,99 @@
+import { AnthropicOAuthUsageClient } from "./clients/anthropic-oauth-usage";
+import { AnthropicWebUsageClient } from "./clients/anthropic-web-usage";
+import { CodexOAuthUsageClient } from "./clients/codex-oauth-usage";
+import { OpenCodeGoUsageClient } from "./clients/opencode-go-usage";
+import { mapClaudeToEntry, mapCodexToEntry, mapOpenCodeGoToEntry } from "./mappers";
+import type { ClaudeOAuthCredentials, ClaudeWebSession, CodexOAuthCredentials, UsageProviderEntry } from "./types";
+
+export const UsageApi = {
+  claude: {
+    async fromOAuthToken(creds: ClaudeOAuthCredentials): Promise<UsageProviderEntry> {
+      const client = new AnthropicOAuthUsageClient();
+      try {
+        const snapshot = await client.fetch(creds);
+        return mapClaudeToEntry(snapshot, [], true, creds);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return mapClaudeToEntry(null, [message], true, creds);
+      }
+    },
+
+    async fromWebSession(session: ClaudeWebSession): Promise<UsageProviderEntry> {
+      const client = new AnthropicWebUsageClient();
+      try {
+        const snapshot = await client.fetch(session);
+        return mapClaudeToEntry(snapshot, [], true, null);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return mapClaudeToEntry(null, [message], true, null);
+      }
+    },
+
+    async fromOAuthTokenWithWebExtras(
+      oauthCreds: ClaudeOAuthCredentials,
+      webSession: ClaudeWebSession,
+    ): Promise<UsageProviderEntry> {
+      const oauthClient = new AnthropicOAuthUsageClient();
+      const webClient = new AnthropicWebUsageClient();
+
+      let snapshot = await oauthClient.fetch(oauthCreds).catch((err: unknown) => {
+        const message = err instanceof Error ? err.message : String(err);
+        return null;
+      });
+
+      if (!snapshot) {
+        const message = "OAuth fetch failed; cannot retrieve usage data";
+        return mapClaudeToEntry(null, [message], true, oauthCreds);
+      }
+
+      // Merge OAuth credential metadata into snapshot for accountId generation
+      if (snapshot.subscriptionType === null && oauthCreds.subscriptionType) {
+        snapshot = { ...snapshot, subscriptionType: oauthCreds.subscriptionType };
+      }
+      if (snapshot.rateLimitTier === null && oauthCreds.rateLimitTier) {
+        snapshot = { ...snapshot, rateLimitTier: oauthCreds.rateLimitTier };
+      }
+
+      // Best-effort web extras (designs, routines, cost)
+      try {
+        const webSnapshot = await webClient.fetch(webSession);
+        if (snapshot.extraRateWindows.length === 0 && webSnapshot.extraRateWindows.length > 0) {
+          snapshot = { ...snapshot, extraRateWindows: webSnapshot.extraRateWindows };
+        }
+        if (!snapshot.providerCost && webSnapshot.providerCost) {
+          snapshot = { ...snapshot, providerCost: webSnapshot.providerCost };
+        }
+      } catch {
+        // Ignore web extras failures — do not change status to error
+      }
+
+      return mapClaudeToEntry(snapshot, [], true, oauthCreds);
+    },
+  },
+
+  opencodeGo: {
+    async fromCookies(creds: { cookies: string; serverFnId: string }): Promise<UsageProviderEntry> {
+      const client = new OpenCodeGoUsageClient();
+      try {
+        const snapshot = await client.fetch(creds);
+        return mapOpenCodeGoToEntry(snapshot, [], true);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return mapOpenCodeGoToEntry(null, [message], true);
+      }
+    },
+  },
+
+  codex: {
+    async fromOAuthToken(creds: CodexOAuthCredentials): Promise<UsageProviderEntry> {
+      const client = new CodexOAuthUsageClient();
+      try {
+        const snapshot = await client.fetch(creds);
+        return mapCodexToEntry(snapshot, [], true, creds);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return mapCodexToEntry(null, [message], true, creds);
+      }
+    },
+  },
+};

package/src/usage/client.ts

@@ -0,0 +1,3 @@
+export interface UsageClient<T, R> {
+  fetch(creds: T, options?: { signal?: AbortSignal }): Promise<R>;
+}

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

@@ -0,0 +1,178 @@
+import type { UsageClient } from "../client";
+import type { ClaudeOAuthCredentials, ClaudeUsageSnapshot, NamedRateWindowLegacy, ProviderCostSnapshotLegacy, RateWindowLegacy } from "../types";
+
+export class AuthenticationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AuthenticationError";
+  }
+}
+
+export class ScopeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ScopeError";
+  }
+}
+
+export class ParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ParseError";
+  }
+}
+
+interface OAuthUsageResponse {
+  five_hour?: { utilization?: number | null; resets_at?: string | null } | null;
+  seven_day?: { utilization?: number | null; resets_at?: string | null } | null;
+  seven_day_sonnet?: { utilization?: number | null; resets_at?: string | null } | null;
+  seven_day_opus?: { utilization?: number | null; resets_at?: string | null } | null;
+  seven_day_design?: { utilization?: number | null; resets_at?: string | null } | null;
+  seven_day_routines?: { utilization?: number | null; resets_at?: string | null } | null;
+  extra_usage?: {
+    is_enabled?: boolean;
+    monthly_limit?: number;
+    used_credits?: number;
+    currency?: string;
+    utilization?: number;
+  } | null;
+  [key: string]: unknown;
+}
+
+const DESIGN_ALTERNATES = [
+  "seven_day_design",
+  "seven_day_claude_design",
+  "claude_design",
+  "design",
+  "seven_day_omelette",
+  "omelette",
+  "omelette_promotional",
+];
+
+const ROUTINES_ALTERNATES = [
+  "seven_day_routines",
+  "seven_day_claude_routines",
+  "claude_routines",
+  "routines",
+  "routine",
+  "seven_day_cowork",
+  "cowork",
+];
+
+function pickWindow(data: OAuthUsageResponse, keys: string[]): { utilization?: number | null; resets_at?: string | null } | null {
+  for (const key of keys) {
+    const val = data[key];
+    if (val && typeof val === "object" && "utilization" in val) {
+      return val as { utilization?: number | null; resets_at?: string | null };
+    }
+  }
+  return null;
+}
+
+function toRateWindow(
+  utilization: number | null | undefined,
+  resetsAt: string | null | undefined,
+  windowMinutes: number,
+): RateWindowLegacy {
+  const usedPercent = typeof utilization === "number" ? Math.max(0, Math.min(100, utilization)) : 0;
+  const resetsAtDate = resetsAt ? new Date(resetsAt) : null;
+  const resetDescription = resetsAtDate && !Number.isNaN(resetsAtDate.getTime())
+    ? resetsAtDate.toLocaleString()
+    : null;
+  return {
+    usedPercent,
+    windowMinutes,
+    resetsAt: resetsAtDate && !Number.isNaN(resetsAtDate.getTime()) ? resetsAtDate : null,
+    resetDescription,
+  };
+}
+
+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",
+      },
+    });
+
+    if (res.status === 401) {
+      throw new AuthenticationError("OAuth token expired or invalid");
+    }
+    if (res.status === 403) {
+      const body = await res.text();
+      if (body.includes("user:profile")) {
+        throw new ScopeError("Token missing required scope user:profile");
+      }
+      throw new Error(`Server error: ${res.status}`);
+    }
+    if (!res.ok) {
+      throw new Error(`Server error: ${res.status}`);
+    }
+
+    const data = (await res.json()) as OAuthUsageResponse;
+
+    if (!data.five_hour || typeof data.five_hour.utilization !== "number") {
+      throw new ParseError("Missing five_hour.utilization");
+    }
+
+    const primary = toRateWindow(data.five_hour.utilization, data.five_hour.resets_at, 300);
+    const secondary = data.seven_day
+      ? toRateWindow(data.seven_day.utilization, data.seven_day.resets_at, 10080)
+      : null;
+
+    const opusWindow = pickWindow(data, ["seven_day_sonnet", "seven_day_opus"]);
+    const opus = opusWindow ? toRateWindow(opusWindow.utilization, opusWindow.resets_at, 10080) : null;
+
+    const extraRateWindows: NamedRateWindowLegacy[] = [];
+    const designWindow = pickWindow(data, DESIGN_ALTERNATES);
+    if (designWindow && typeof designWindow.utilization === "number") {
+      extraRateWindows.push({
+        id: "claude-design",
+        title: "Designs",
+        window: toRateWindow(designWindow.utilization, designWindow.resets_at, 10080),
+      });
+    }
+    const routinesWindow = pickWindow(data, ROUTINES_ALTERNATES);
+    if (routinesWindow && typeof routinesWindow.utilization === "number") {
+      extraRateWindows.push({
+        id: "claude-routines",
+        title: "Daily Routines",
+        window: toRateWindow(routinesWindow.utilization, routinesWindow.resets_at, 10080),
+      });
+    }
+
+    let providerCost: ProviderCostSnapshotLegacy | null = null;
+    if (data.extra_usage?.is_enabled) {
+      const used = (data.extra_usage.used_credits ?? 0) / 100;
+      const limit = (data.extra_usage.monthly_limit ?? 0) / 100;
+      const currency = (data.extra_usage.currency || "USD").trim();
+      providerCost = {
+        used,
+        limit,
+        currencyCode: currency || "USD",
+        period: "Monthly",
+        resetsAt: null,
+        updatedAt: new Date(),
+      };
+    }
+
+    return {
+      source: "oauth",
+      primary,
+      secondary,
+      opus,
+      extraRateWindows,
+      providerCost,
+      updatedAt: new Date(),
+      accountEmail: null,
+      accountOrganization: null,
+      loginMethod: null,
+      subscriptionType: null,
+      rateLimitTier: null,
+    };
+  }
+}