feat: add OAuth provider usage tracking

Add an Effect-backed /usage service and generated SDK contract for OAuth usage from Anthropic Claude, OpenAI ChatGPT, GitHub Copilot, and Google Antigravity. Keep credentials read-only, cache snapshots in process by active credential identity, deduplicate in-flight work by complete auth state, and surface stale or provider-specific failures without refreshing tokens.

Add an app-scoped, route-aware TUI usage resource with /usage commands, detail and sidebar views, background refresh, threshold toasts, config, keybinding metadata, and documentation. Refresh usage after every successful credential replacement and ignore late foreground responses after navigation, newer requests, or intervening dialogs.

Cover provider normalization, credential rotation and concurrency, Antigravity local-cache behavior, Copilot origin safety and independent AI-credit accounting, HttpApi/OpenAPI parity, and TUI lifecycle, command, formatting, and toast behavior.

Author: CasualDeveloper

packages/opencode/src/effect/app-runtime.ts

@@ -46,6 +46,7 @@ import { Worktree } from "@/worktree"
 import { Installation } from "@/installation"
 import { ShareNext } from "@/share/share-next"
 import { SessionShare } from "@/share/session"
+import { Usage } from "@/usage/usage"
 import { Npm } from "@opencode-ai/core/npm"
 import { memoMap } from "@opencode-ai/core/effect/memo-map"
 import { BackgroundJob } from "@/background/job"
@@ -105,6 +106,7 @@ export const AppLayer = AppNodeBuilderV1.build(
     Installation.node,
     ShareNext.node,
     SessionShare.node,
+    Usage.node,
   ]),
 ).pipe(Layer.provideMerge(AppNodeBuilderV1.build(Ripgrep.node)), Layer.provideMerge(Observability.layer))
 

packages/opencode/src/server/routes/instance/httpapi/api.ts

@@ -24,6 +24,7 @@ import { QuestionApi } from "./groups/question"
 import { SessionApi } from "./groups/session"
 import { SyncApi } from "./groups/sync"
 import { TuiApi } from "./groups/tui"
+import { UsageApi } from "./groups/usage"
 import { WorkspaceApi } from "./groups/workspace"
 import { makeApi } from "@opencode-ai/protocol/api"
 import { LocationMiddleware } from "@opencode-ai/server/location"
@@ -73,6 +74,7 @@ export const InstanceHttpApi = HttpApi.make("opencode-instance")
   .addHttpApi(SessionApi)
   .addHttpApi(SyncApi)
   .addHttpApi(TuiApi)
+  .addHttpApi(UsageApi)
   .addHttpApi(WorkspaceApi)
   .middleware(SchemaErrorMiddleware)
 

packages/opencode/src/server/routes/instance/httpapi/groups/usage.ts

@@ -0,0 +1,60 @@
+import { responseSchema } from "@/usage/types"
+import { Schema, SchemaGetter } from "effect"
+import { HttpApi, HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+import { Authorization } from "../middleware/authorization"
+import { InstanceContextMiddleware } from "../middleware/instance-context"
+import { WorkspaceRoutingMiddleware, WorkspaceRoutingQueryFields } from "../middleware/workspace-routing"
+import { described } from "./metadata"
+
+const root = "/usage"
+const QueryRefresh = Schema.String.check(Schema.isPattern(/^\s*(true|false|1|0)\s*$/i)).pipe(
+  Schema.decodeTo(Schema.Boolean, {
+    decode: SchemaGetter.transform((value) => {
+      const normalized = value.trim().toLowerCase()
+      return normalized === "true" || normalized === "1"
+    }),
+    encode: SchemaGetter.transform((value) => (value ? "true" : "false")),
+  }),
+)
+
+export const UsageQuerySchema = Schema.Struct({
+  ...WorkspaceRoutingQueryFields,
+  provider: Schema.optional(Schema.String),
+  refresh: Schema.optional(QueryRefresh),
+})
+export const UsagePaths = {
+  get: root,
+} as const
+
+export const UsageApi = HttpApi.make("usage")
+  .add(
+    HttpApiGroup.make("usage")
+      .add(
+        HttpApiEndpoint.get("get", UsagePaths.get, {
+          query: UsageQuerySchema,
+          success: described(responseSchema, "Usage response"),
+        }).annotateMerge(
+          OpenApi.annotations({
+            identifier: "usage.get",
+            summary: "Get usage",
+            description: "Fetch usage limits for authenticated providers.",
+          }),
+        ),
+      )
+      .annotateMerge(
+        OpenApi.annotations({
+          title: "usage",
+          description: "Experimental HttpApi usage routes.",
+        }),
+      )
+      .middleware(InstanceContextMiddleware)
+      .middleware(WorkspaceRoutingMiddleware)
+      .middleware(Authorization),
+  )
+  .annotateMerge(
+    OpenApi.annotations({
+      title: "opencode experimental HttpApi",
+      version: "0.0.1",
+      description: "Experimental HttpApi surface for selected instance routes.",
+    }),
+  )

packages/opencode/src/server/routes/instance/httpapi/handlers/usage.ts

@@ -0,0 +1,17 @@
+import { Usage } from "@/usage/usage"
+import { Effect } from "effect"
+import { HttpApiBuilder } from "effect/unstable/httpapi"
+import { InstanceHttpApi } from "../api"
+import { UsageQuerySchema } from "../groups/usage"
+
+export const usageHandlers = HttpApiBuilder.group(InstanceHttpApi, "usage", (handlers) =>
+  Effect.gen(function* () {
+    const usage = yield* Usage.Service
+
+    const get = Effect.fn("UsageHttpApi.get")(function* (ctx: { query: typeof UsageQuerySchema.Type }) {
+      return yield* usage.getResponse(ctx.query).pipe(Effect.orDie)
+    })
+
+    return handlers.handle("get", get)
+  }),
+)

packages/opencode/src/server/routes/instance/httpapi/public.ts

@@ -71,6 +71,7 @@ const QueryParameterSchemas: Record<string, OpenApiSchema> = {
   "GET /api/session start": { type: "number" },
   "GET /api/session roots": QueryBooleanOpenApi,
   "GET /api/session/{sessionID}/message limit": { type: "number" },
+  "GET /usage refresh": { type: "boolean" },
 }
 
 const LegacyComponentDescriptions: Record<string, string> = {
@@ -269,6 +270,7 @@ function applyLegacySchemaOverrides(spec: OpenApiSpec) {
   }
   if (schemas.GlobalSession?.properties?.project)
     schemas.GlobalSession.properties.project = nullable(schemas.GlobalSession.properties.project)
+  applyUsageSchemaNullability(schemas)
   const providerOptions = schemas.ProviderConfig?.properties?.options
   if (providerOptions) providerOptions.additionalProperties = {}
   const model = schemas.ProviderConfig?.properties?.models?.additionalProperties
@@ -278,6 +280,35 @@ function applyLegacySchemaOverrides(spec: OpenApiSpec) {
   if (syncInfo?.properties) makePropertiesNullable(syncInfo.properties)
 }
 
+function applyUsageSchemaNullability(schemas: Record<string, OpenApiSchema>) {
+  const result = schemas.UsageResult
+  const properties = result?.properties
+  const snapshot = properties?.snapshot
+  if (!snapshot) return
+  properties.snapshot = nullable(snapshot)
+  makeUsageSnapshotNullable(snapshot)
+}
+
+function makeUsageSnapshotNullable(schema: OpenApiSchema) {
+  const target = schema.anyOf?.find((item) => item.type !== "null") ?? schema
+  const properties = target.properties
+  if (!properties) return
+  const window = typeof properties.windows?.items === "object" ? properties.windows.items : undefined
+  if (window?.properties) {
+    if (window.properties.windowMinutes) window.properties.windowMinutes = nullable(window.properties.windowMinutes)
+    if (window.properties.resetsAt) window.properties.resetsAt = nullable(window.properties.resetsAt)
+  }
+  const credits = properties.credits
+  if (credits) {
+    if (credits.properties?.balance) credits.properties.balance = nullable(credits.properties.balance)
+    if (credits.properties?.total) credits.properties.total = nullable(credits.properties.total)
+    if (credits.properties?.used) credits.properties.used = nullable(credits.properties.used)
+    if (credits.properties?.remaining) credits.properties.remaining = nullable(credits.properties.remaining)
+    properties.credits = nullable(credits)
+  }
+  if (properties.planType) properties.planType = nullable(properties.planType)
+}
+
 function normalizeComponentDescriptions(spec: OpenApiSpec) {
   for (const [name, schema] of Object.entries(spec.components?.schemas ?? {})) {
     const description = LegacyComponentDescriptions[name]

packages/opencode/src/server/routes/instance/httpapi/server.ts

@@ -47,6 +47,7 @@ import { Snapshot } from "@/snapshot"
 import { Storage } from "@/storage/storage"
 import { ToolRegistry } from "@/tool/registry"
 import { Truncate } from "@/tool/truncate"
+import { Usage } from "@/usage/usage"
 import { Worktree } from "@/worktree"
 import { RuntimeFlags } from "@/effect/runtime-flags"
 import { MoveSession } from "@opencode-ai/core/control-plane/move-session"
@@ -105,6 +106,7 @@ import { layer as locationLayer } from "@opencode-ai/server/location"
 import { sessionLocationLayer } from "@opencode-ai/server/middleware/session-location"
 import { PtyEnvironment } from "@opencode-ai/server/pty-environment"
 import { schemaErrorLayer as v2SchemaErrorLayer } from "@opencode-ai/server/middleware/schema-error"
+import { usageHandlers } from "./handlers/usage"
 import { workspaceHandlers } from "./handlers/workspace"
 import { instanceContextLayer } from "./middleware/instance-context"
 import { workspaceRoutingLayer } from "./middleware/workspace-routing"
@@ -167,6 +169,7 @@ const instanceApiRoutes = HttpApiBuilder.layer(InstanceHttpApi).pipe(
     sessionHandlers,
     syncHandlers,
     tuiHandlers,
+    usageHandlers,
     workspaceHandlers,
   ]),
 )
@@ -252,6 +255,7 @@ const app = LayerNode.group([
   Command.node,
   Truncate.node,
   ToolRegistry.node,
+  Usage.node,
   Format.node,
   Project.node,
   Vcs.node,