opencode-plugboard 0.18.0 → 0.20.0

package/src/usage.ts

@@ -23,12 +23,13 @@
  * at 0 and its call counted in `unpricedRequests`.
  */
 
-import { APP_NAME_PATTERN } from "./config.js"
+import { APP_NAME_PATTERN, type BudgetMetric, type BudgetWindow } from "./config.js"
 import { isPlugError, type CallContext, type CatalogCost, type CatalogModel, type ModelCaller, type ModelRef, type PlugError, type PlugEvent, type PlugRequest, type PlugUsage, type ServedModel } from "./contract.js"
 import { errorMessage, log, logError } from "./log.js"
 import type { Outcome } from "./metrics.js"
 import { parseModelRef } from "./models.js"
 import type { StoragePort } from "./session/host.js"
+import { sanitizeEndUser } from "./user.js"
 
 /** Upper bounds of the latency buckets in ms; one more bucket holds everything above the last. */
 export const LATENCY_BOUNDS_MS: ReadonlyArray<number> = [100, 250, 500, 1_000, 2_500, 5_000, 10_000, 30_000, 60_000, 120_000, 300_000, 600_000]
@@ -115,7 +116,7 @@ export interface UsageCounts<Latency = LatencyHistogram> {
   cacheMisses: number
   /** Retries on the next target of an alias after a failure before any output. */
   fallbacks: number
-  /** Calls refused with 429 by a concurrency cap or a requests-per-minute limit (also counted in `requests` and `errors.client`). */
+  /** Calls refused with 429 by a concurrency cap, a requests-per-minute limit or a budget (also counted in `requests` and `errors.client`). */
   limited: number
   /** Answered calls that spent tokens but had no price in the catalog (their cost counts as 0). */
   unpricedRequests: number
@@ -123,9 +124,19 @@ export interface UsageCounts<Latency = LatencyHistogram> {
   lastRequestAt?: string
 }
 
+/** One end user's counts (src/user.ts, #57): HTTP requests on the model routes, tokens and cost of the answered calls. */
+export interface UserUsage {
+  requests: number
+  /** Total tokens of those calls (the five kinds summed). */
+  tokens: number
+  costUsd: number
+}
+
 /** One stored day, at `usage/<app>/<date>`. */
 export interface DayRecord extends UsageCounts {
   perModel: Record<string, ModelUsage>
+  /** Per end user (see `USERS_PER_DAY`). Older stored days have none. */
+  users: Record<string, UserUsage>
 }
 
 /** Counters with latency percentiles, as a report carries them. */
@@ -137,13 +148,28 @@ export interface UsageDay extends UsageTotals {
   perModel: Record<string, ModelUsage>
 }
 
+/** One ceiling of an app's budget, with what its current window has used (`GET /v1/usage`, see `src/budgets.ts`). */
+export interface BudgetStatus {
+  readonly metric: BudgetMetric
+  readonly window: BudgetWindow
+  readonly limit: number
+  /** Counted so far in the current window; a cost is in USD. */
+  readonly used: number
+  /** ISO 8601 time the current window ends and its count starts again. */
+  readonly resetsAt: string
+}
+
 export interface UsageAppReport {
   /** Sums over the days of the range. */
   totals: UsageTotals
   /** Per model, summed over the range. The key is `provider/model`; the variant is not part of it. */
   models: Record<string, ModelUsage>
+  /** Per end user, summed over the range (src/user.ts). Past `USERS_PER_DAY` a day's extra users are under `_other`. With `user`, only that user. */
+  users?: Record<string, UserUsage>
   /** Days with any record in the range, oldest first. */
   days: UsageDay[]
+  /** The app's budget state, when option `budgets` sets one for it. Read from the current window, not from the range. */
+  budgets?: BudgetStatus[]
 }
 
 /** The result of `GET /v1/usage` and of the `opencode-plugboard.usage` RPC (`src/rpc.ts`). */
@@ -166,6 +192,8 @@ export interface UsageQuery {
   readonly to?: string
   /** One app. Absent: every app. */
   readonly app?: string
+  /** One end user (src/user.ts): `users` of each app then lists only that user. Absent: every user. */
+  readonly user?: string
 }
 
 // ---------------------------------------------------------------- pure helpers
@@ -200,6 +228,7 @@ export function emptyDay(): DayRecord {
     limited: 0,
     unpricedRequests: 0,
     perModel: {},
+    users: {},
   }
 }
 
@@ -235,7 +264,7 @@ export function tokenBreakdown(usage: PlugUsage): UsageTokens {
   }
 }
 
-const totalTokens = (tokens: UsageTokens): number => tokens.input + tokens.cacheRead + tokens.cacheWrite + tokens.output + tokens.reasoning
+export const totalTokens = (tokens: UsageTokens): number => tokens.input + tokens.cacheRead + tokens.cacheWrite + tokens.output + tokens.reasoning
 
 /**
  * The USD cost of one call, or undefined when the model has no applicable price. Mirrors OpenCode's
@@ -283,9 +312,22 @@ export function sumDays(parts: ReadonlyArray<DayRecord>): DayRecord {
       total.perModel[model] = { requests: sum.requests + usage.requests, tokens: sum.tokens + usage.tokens, costUsd: sum.costUsd + usage.costUsd }
     }
   }
+  total.users = sumUsers(parts)
   return total
 }
 
+/** Per end user, summed over the day records (`only`: that user alone). */
+function sumUsers(parts: ReadonlyArray<DayRecord>, only?: string): Record<string, UserUsage> {
+  const out: Record<string, UserUsage> = {}
+  for (const part of parts)
+    for (const [user, usage] of Object.entries(part.users ?? {})) {
+      if (only !== undefined && user !== only) continue
+      const sum = out[user] ?? { requests: 0, tokens: 0, costUsd: 0 }
+      out[user] = { requests: sum.requests + usage.requests, tokens: sum.tokens + usage.tokens, costUsd: sum.costUsd + usage.costUsd }
+    }
+  return out
+}
+
 /** A day's counters with latency percentiles, as a report carries them. */
 export function summaryOf(day: DayRecord): UsageTotals {
   return {
@@ -316,6 +358,11 @@ export function fromJson(value: unknown): DayRecord {
     const usage = object(item)
     perModel[model] = { requests: nonNegative(usage.requests), tokens: nonNegative(usage.tokens), costUsd: nonNegative(usage.costUsd) }
   }
+  const users: Record<string, UserUsage> = {}
+  for (const [user, item] of Object.entries(object(raw.users))) {
+    const usage = object(item)
+    users[user] = { requests: nonNegative(usage.requests), tokens: nonNegative(usage.tokens), costUsd: nonNegative(usage.costUsd) }
+  }
   return {
     requests: nonNegative(raw.requests),
     errors: { client: nonNegative(errors.client), server: nonNegative(errors.server), timeout: nonNegative(errors.timeout), disconnected: nonNegative(errors.disconnected) },
@@ -335,6 +382,7 @@ export function fromJson(value: unknown): DayRecord {
     unpricedRequests: nonNegative(raw.unpricedRequests),
     ...(typeof raw.lastRequestAt === "string" ? { lastRequestAt: raw.lastRequestAt } : {}),
     perModel,
+    users,
   }
 }
 
@@ -382,6 +430,8 @@ export interface RequestUsage {
   readonly status: number
   readonly outcome: Outcome
   readonly ms: number
+  /** The end user of the request, when kept (src/user.ts). */
+  readonly user?: string
 }
 
 /** One model call, when it ended. `answered` when its stream finished with an answer; `cache` when the response cache applied. */
@@ -392,6 +442,8 @@ export interface CallUsage {
   readonly answered: boolean
   readonly cache?: "hit" | "miss"
   readonly usage?: PlugUsage
+  /** The end user of the call, when kept (src/user.ts). */
+  readonly user?: string
 }
 
 export interface UsageRecorder {
@@ -399,8 +451,12 @@ export interface UsageRecorder {
   limited(app: string): void
   fallback(app: string): void
   call(input: CallUsage): void
+  /** The USD cost of a call's tokens under the serving catalog's price for `ref`, or undefined when unpriced (`x-plugboard-usage`, #52). */
+  price(ref: ModelRef, tokens: UsageTokens): Promise<number | undefined>
   /** A report for the range and app (defaults as `resolveRange`). A bad input is a 400 `PlugError`. */
   query(input: UsageQuery): Promise<UsageReport | PlugError>
+  /** The sum of one app's days from `from` to `to` (UTC, inclusive, `YYYY-MM-DD`), memory first. Read by the budget check; a storage failure rejects. */
+  spent(app: string, from: string, to: string): Promise<DayRecord>
 }
 
 export interface UsageRecorderDeps {
@@ -427,6 +483,18 @@ async function readDay(storage: StoragePort, key: string): Promise<DayRecord | u
   }
 }
 
+/** Distinct end users a day keeps per app. Later users count under `_other` (the key cannot be an end user: no `_`). */
+export const USERS_PER_DAY = 200
+const OTHER_USER = "_other"
+
+/** The counts of one end user in a day, created on first use; past the cap the request counts under `_other`. */
+function userSlot(day: DayRecord, user: string): UserUsage {
+  if (day.users[user]) return day.users[user]
+  const distinct = Object.keys(day.users).length - (day.users[OTHER_USER] ? 1 : 0)
+  const key = distinct < USERS_PER_DAY ? user : OTHER_USER
+  return (day.users[key] ??= { requests: 0, tokens: 0, costUsd: 0 })
+}
+
 const addTokens = (into: UsageTokens, from: UsageTokens): UsageTokens => ({
   input: into.input + from.input,
   cacheRead: into.cacheRead + from.cacheRead,
@@ -541,6 +609,7 @@ export function createUsageRecorder(deps: UsageRecorderDeps): UsageRecorder {
         day.latency.sumMs += ms
         day.latency.buckets[bucketIndex(ms)] = (day.latency.buckets[bucketIndex(ms)] ?? 0) + 1
         day.lastRequestAt = new Date(at).toISOString()
+        if (input.user !== undefined) userSlot(day, input.user).requests++
       })
     },
 
@@ -578,14 +647,32 @@ export function createUsageRecorder(deps: UsageRecorderDeps): UsageRecorder {
           day.tokens = addTokens(day.tokens, tokens)
           day.costUsd += price
           if (unpriced) day.unpricedRequests++
+          if (input.user !== undefined) {
+            const slot = userSlot(day, input.user)
+            slot.tokens += totalTokens(tokens)
+            slot.costUsd += price
+          }
         })
       })().catch((error) => logError("usage.record_failed", { app: input.app, error: errorMessage(error) }))
     },
 
+    price: priceOf,
+    async spent(app, from, to) {
+      const parts: DayRecord[] = []
+      const last = Date.parse(`${to}T00:00:00Z`)
+      for (let at = Date.parse(`${from}T00:00:00Z`); at <= last; at += DAY_MS) {
+        const entry = await load(app, utcDate(at), false)
+        if (entry) parts.push(entry.day)
+      }
+      return sumDays(parts)
+    },
+
     async query(input) {
       const at = now()
       if (input.app !== undefined && !APP_NAME_PATTERN.test(input.app))
         return { status: 400, kind: "invalid_request", code: "invalid_app", param: "app", message: "`app` must be an app name from the keys configuration" }
+      if (input.user !== undefined && sanitizeEndUser(input.user) === undefined)
+        return { status: 400, kind: "invalid_request", code: "invalid_user", param: "user", message: "`user` must be 1 to 64 characters of A-Z, a-z, 0-9, `.`, `_`, `@`, `:` or `-`" }
       const range = resolveRange(input, at)
       if (isPlugError(range)) return range
       const prefix = input.app === undefined ? KEY_PREFIX : keyOf(input.app, "")
@@ -618,7 +705,7 @@ export function createUsageRecorder(deps: UsageRecorderDeps): UsageRecorder {
         const total = sumDays(rows.map((row) => row.day))
         appTotals.push(total)
         const days: UsageDay[] = rows.map((row) => ({ date: row.date, ...summaryOf(row.day), perModel: { ...row.day.perModel } }))
-        apps[app] = { totals: summaryOf(total), models: { ...total.perModel }, days }
+        apps[app] = { totals: summaryOf(total), models: { ...total.perModel }, users: sumUsers(rows.map((row) => row.day), input.user), days }
       }
       return { from: range.from, to: range.to, generatedAt: new Date(at).toISOString(), totals: summaryOf(sumDays(appTotals)), apps }
     },
@@ -659,12 +746,24 @@ export function withUsage(inner: ModelCaller, recorder: UsageRecorder | undefine
             if (event.type === "finish") {
               answered = event.reason !== "error"
               usage = event.usage
+              if (answered && context.onUsage) {
+                // The header is set before the finish reaches the front-end, so a non-streaming answer carries it.
+                const ref = served ? parseModelRef(served.model) : request.ref
+                const tokens = tokenBreakdown(usage ?? {})
+                const costUsd = ref ? await recorder.price(ref, tokens) : undefined
+                context.onUsage({
+                  inputTokens: usage?.inputTokens ?? 0,
+                  outputTokens: usage?.outputTokens ?? 0,
+                  cacheReadTokens: usage?.cacheReadTokens ?? 0,
+                  ...(costUsd === undefined ? {} : { costUsd }),
+                })
+              }
             }
             yield event
           }
         } finally {
           const ref = served ? parseModelRef(served.model) : request.ref
-          recorder.call({ app: context.app, ...(ref ? { ref } : {}), answered, ...(cache ? { cache } : {}), ...(usage ? { usage } : {}) })
+          recorder.call({ app: context.app, ...(ref ? { ref } : {}), answered, ...(cache ? { cache } : {}), ...(usage ? { usage } : {}), ...(request.user === undefined ? {} : { user: request.user }) })
         }
       })()
     },

package/src/user.ts

@@ -0,0 +1,55 @@
+/**
+ * The end user of a request (#57): the caller's own id for one of its users, read from the body
+ * (OpenAI `user`, Anthropic `metadata.user_id`; Gemini has none). It labels a session title, the
+ * request log line and the per-user usage counts. It never names a path: a value is only ever a
+ * string key in a record.
+ *
+ * A value is kept only when it is trimmed and at most 64 characters of `A-Z a-z 0-9 . _ @ : -`.
+ * Anything else is dropped, and the response says so with `x-plugboard-user-dropped: 1`. A blank
+ * value is no user at all (neither kept nor reported).
+ *
+ * Pure: no node imports, so the request decoders (`request.ts` files) can use it (I20).
+ */
+
+export const USER_DROPPED_HEADER = "x-plugboard-user-dropped"
+
+const END_USER = /^[A-Za-z0-9._@:-]{1,64}$/
+
+/** The user id to keep, or undefined when the value is absent, blank or not allowed. */
+export function sanitizeEndUser(raw: unknown): string | undefined {
+  if (typeof raw !== "string") return undefined
+  const trimmed = raw.trim()
+  return END_USER.test(trimmed) ? trimmed : undefined
+}
+
+/** True when the caller sent a value that is not kept. Absent and blank values are not dropped. */
+export function endUserDropped(raw: unknown): boolean {
+  if (raw === undefined || raw === null) return false
+  if (typeof raw === "string" && raw.trim() === "") return false
+  return sanitizeEndUser(raw) === undefined
+}
+
+/** `body.user`, the OpenAI-shaped field. */
+export const bodyUser = (body: unknown): unknown => (typeof body === "object" && body !== null ? (body as { user?: unknown }).user : undefined)
+
+/** `body.metadata.user_id`, the Anthropic-shaped field. */
+export function bodyUserId(body: unknown): unknown {
+  const metadata = typeof body === "object" && body !== null ? (body as { metadata?: unknown }).metadata : undefined
+  return typeof metadata === "object" && metadata !== null ? (metadata as { user_id?: unknown }).user_id : undefined
+}
+
+/** The `user` member of a `PlugRequest` (spread into it), empty when no user is kept. */
+export const userField = (raw: unknown): { user?: string } => {
+  const user = sanitizeEndUser(raw)
+  return user === undefined ? {} : { user }
+}
+
+/**
+ * For a route, after the body is read: sets `x-plugboard-user-dropped` when the value is not kept (the
+ * headers are still open then), and names the kept user in the request log fields.
+ */
+export function noteEndUser(response: { setHeader(name: string, value: string): unknown }, info: { user?: string }, raw: unknown): void {
+  if (endUserDropped(raw)) response.setHeader(USER_DROPPED_HEADER, "1")
+  const user = sanitizeEndUser(raw)
+  if (user !== undefined) info.user = user
+}