pantheon-opencode 1.5.0-beta.14 → 1.5.0-beta.16

package/src/pantheon/provider-capabilities.ts

@@ -1,221 +0,0 @@
-/**
- * Exact provider usage contract and the independent V1/V2 capability probes.
- *
- * This module deliberately does not inspect credentials, call a provider, read
- * the TUI, calculate percentages, or derive token counts from text. A provider
- * is supported only when it supplies the complete numeric contract below.
- *
- * @module provider-capabilities
- */
-
-/** The only capability statuses exposed by the usage contract. */
-export const USAGE_STATUS = {
-  SUPPORTED: 'SUPPORTED',
-  UNSUPPORTED: 'UNSUPPORTED',
-} as const
-
-export type UsageStatus = (typeof USAGE_STATUS)[keyof typeof USAGE_STATUS]
-
-/** Exact token counters supplied by the provider. No totals are inferred. */
-export interface ExactProviderUsage {
-  inputTokens: number
-  outputTokens: number
-}
-
-/** Exact context limit supplied by the provider. */
-export interface ExactProviderLimit {
-  contextTokens: number
-}
-
-/**
- * Minimum complete provider payload accepted by either capability probe.
- * `resetAt`, when present, is an exact non-negative numeric provider value;
- * date strings and other reset representations are unsupported.
- */
-export interface ExactProviderUsageData {
-  sessionId: string
-  providerId: string
-  modelId: string
-  usage: ExactProviderUsage
-  limit: ExactProviderLimit
-  resetAt?: number
-}
-
-/** Stream event metadata required for de-duplication and freshness ordering. */
-export interface ProviderUsageEvent extends ExactProviderUsageData {
-  eventId: string
-  partId: string
-  /** Optional provider sequence. When supplied, it must be an integer. */
-  sequence?: number
-  /** Optional provider observation time in milliseconds or another numeric scale. */
-  observedAt?: number
-}
-
-/** A complete snapshot that has passed the exact contract validation. */
-export interface ProviderUsageSnapshot extends ProviderUsageEvent {}
-
-export type CapabilityProbeVersion = 'v1' | 'v2'
-
-export type CapabilityProbeReason =
-  | 'MISSING_SESSION_ID'
-  | 'MISSING_PROVIDER_ID'
-  | 'MISSING_MODEL_ID'
-  | 'MISSING_USAGE'
-  | 'MISSING_LIMIT'
-  | 'INVALID_USAGE'
-  | 'INVALID_LIMIT'
-  | 'INVALID_RESET'
-
-export type ProviderCapabilityResult =
-  | {
-      apiVersion: CapabilityProbeVersion
-      status: typeof USAGE_STATUS.SUPPORTED
-      data: ExactProviderUsageData
-    }
-  | {
-      apiVersion: CapabilityProbeVersion
-      status: typeof USAGE_STATUS.UNSUPPORTED
-      reason: CapabilityProbeReason
-    }
-
-type UnknownRecord = Record<string, unknown>
-
-function isRecord(value: unknown): value is UnknownRecord {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-function isNonEmptyString(value: unknown): value is string {
-  return typeof value === 'string' && value.trim().length > 0
-}
-
-function isFiniteNonNegativeNumber(value: unknown): value is number {
-  return typeof value === 'number' && Number.isFinite(value) && value >= 0
-}
-
-function hasOnlyKeys(value: UnknownRecord, allowed: readonly string[]): boolean {
-  return Object.keys(value).every((key) => allowed.includes(key))
-}
-
-function unsupported(
-  apiVersion: CapabilityProbeVersion,
-  reason: CapabilityProbeReason,
-): ProviderCapabilityResult {
-  return { apiVersion, status: USAGE_STATUS.UNSUPPORTED, reason }
-}
-
-/**
- * Validate the complete exact payload without coercion or estimation.
- *
- * This is intentionally shared only as a validator. V1 and V2 entry points
- * below remain separate capability probes and do not fall back to one another.
- */
-function probeExactData(
-  apiVersion: CapabilityProbeVersion,
-  input: unknown,
-): ProviderCapabilityResult {
-  if (!isRecord(input)) return unsupported(apiVersion, 'MISSING_SESSION_ID')
-
-  if (!isNonEmptyString(input.sessionId)) {
-    return unsupported(apiVersion, 'MISSING_SESSION_ID')
-  }
-  if (!isNonEmptyString(input.providerId)) {
-    return unsupported(apiVersion, 'MISSING_PROVIDER_ID')
-  }
-  if (!isNonEmptyString(input.modelId)) {
-    return unsupported(apiVersion, 'MISSING_MODEL_ID')
-  }
-  if (!isRecord(input.usage)) return unsupported(apiVersion, 'MISSING_USAGE')
-  if (!isRecord(input.limit)) return unsupported(apiVersion, 'MISSING_LIMIT')
-  if (!hasOnlyKeys(input.usage, ['inputTokens', 'outputTokens'])) {
-    return unsupported(apiVersion, 'INVALID_USAGE')
-  }
-  if (!hasOnlyKeys(input.limit, ['contextTokens'])) {
-    return unsupported(apiVersion, 'INVALID_LIMIT')
-  }
-
-  const usage = input.usage
-  if (!isFiniteNonNegativeNumber(usage.inputTokens)) {
-    return unsupported(apiVersion, 'INVALID_USAGE')
-  }
-  if (!isFiniteNonNegativeNumber(usage.outputTokens)) {
-    return unsupported(apiVersion, 'INVALID_USAGE')
-  }
-
-  const limit = input.limit
-  if (!isFiniteNonNegativeNumber(limit.contextTokens)) {
-    return unsupported(apiVersion, 'INVALID_LIMIT')
-  }
-
-  let resetAt: number | undefined
-  if ('reset' in input) return unsupported(apiVersion, 'INVALID_RESET')
-  if ('resetAt' in input) {
-    const value = input.resetAt
-    if (!isFiniteNonNegativeNumber(value)) return unsupported(apiVersion, 'INVALID_RESET')
-    resetAt = value
-  }
-
-  const data: ExactProviderUsageData = {
-    sessionId: input.sessionId,
-    providerId: input.providerId,
-    modelId: input.modelId,
-    usage: {
-      inputTokens: usage.inputTokens,
-      outputTokens: usage.outputTokens,
-    },
-    limit: { contextTokens: limit.contextTokens },
-  }
-  if (resetAt !== undefined) data.resetAt = resetAt
-
-  return { apiVersion, status: USAGE_STATUS.SUPPORTED, data }
-}
-
-/**
- * Probe the V1 exact payload shape supplied by a caller.
- *
- * V1 does not inherit V2 capability, credentials, cache, or lifecycle data.
- * The caller must pass the exact payload after its host-specific extraction.
- */
-export function probeV1Capability(input: unknown): ProviderCapabilityResult {
-  return probeExactData('v1', input)
-}
-
-/**
- * Probe the V2 exact payload shape supplied by a caller.
- *
- * V2 is intentionally independent from V1: no V1 event, retry, cache, or
- * fallback value is consulted when the exact payload is absent.
- */
-export function probeV2Capability(input: unknown): ProviderCapabilityResult {
-  return probeExactData('v2', input)
-}
-
-/** Validate one complete stream event using the same exact data contract. */
-export function validateProviderUsageEvent(input: unknown): ProviderUsageEvent | null {
-  if (!isRecord(input)) return null
-  if (!isNonEmptyString(input.eventId) || !isNonEmptyString(input.partId)) return null
-
-  const data = probeExactData('v1', input)
-  if (data.status !== USAGE_STATUS.SUPPORTED) return null
-
-  let sequence: number | undefined
-  if ('sequence' in input) {
-    const value = input.sequence
-    if (!isFiniteNonNegativeNumber(value) || !Number.isInteger(value)) return null
-    sequence = value
-  }
-  let observedAt: number | undefined
-  if ('observedAt' in input) {
-    const value = input.observedAt
-    if (!isFiniteNonNegativeNumber(value)) return null
-    observedAt = value
-  }
-
-  const event: ProviderUsageEvent = {
-    ...data.data,
-    eventId: input.eventId,
-    partId: input.partId,
-  }
-  if (sequence !== undefined) event.sequence = sequence
-  if (observedAt !== undefined) event.observedAt = observedAt
-  return event
-}

package/src/pantheon/provider-stream-tracker.ts

@@ -1,182 +0,0 @@
-/**
- * Pure provider stream usage tracker.
- *
- * The tracker stores only complete exact provider snapshots. It has no timers,
- * polling, persistence, TUI dependency, provider client, credential fallback,
- * token/cost estimation, or compaction/FSM integration.
- *
- * @module provider-stream-tracker
- */
-
-import {
-  type ProviderUsageEvent,
-  type ProviderUsageSnapshot,
-  USAGE_STATUS,
-  type UsageStatus,
-  validateProviderUsageEvent,
-} from './provider-capabilities.ts'
-
-export type TrackerUpdateReason = 'PUBLISHED' | 'DUPLICATE' | 'STALE' | 'OUT_OF_SCOPE' | 'INVALID'
-
-export interface ProviderStreamTrackerOptions {
-  /** Optional exact stream scope. Events from another stream are unsupported. */
-  sessionId?: string
-  providerId?: string
-  modelId?: string
-  /** Injectable sink called only after a complete snapshot is stored. */
-  onSnapshot?: (snapshot: ProviderUsageSnapshot) => void
-}
-
-export interface ProviderStreamTrackerResult {
-  status: UsageStatus
-  published: boolean
-  reason: TrackerUpdateReason
-  snapshot?: ProviderUsageSnapshot
-}
-
-export interface ProviderStreamTracker {
-  /** Ingest one raw event without coercion or heuristic recovery. */
-  ingest(input: unknown): ProviderStreamTrackerResult
-  /** Read one complete snapshot for an isolated session/provider/model stream. */
-  getSnapshot(
-    sessionId: string,
-    providerId: string,
-    modelId: string,
-  ): ProviderUsageSnapshot | undefined
-  /** Read all complete snapshots, each isolated by stream identity. */
-  snapshots(): ProviderUsageSnapshot[]
-  /** Remove all in-memory stream state. */
-  clear(): void
-}
-
-interface StreamState {
-  snapshot: ProviderUsageSnapshot
-  eventIds: Set<string>
-  partIds: Set<string>
-  orderKind?: 'sequence' | 'observedAt'
-  orderValue?: number
-}
-
-function streamKey(sessionId: string, providerId: string, modelId: string): string {
-  return JSON.stringify([sessionId, providerId, modelId])
-}
-
-function copySnapshot(snapshot: ProviderUsageSnapshot): ProviderUsageSnapshot {
-  const copy: ProviderUsageSnapshot = {
-    eventId: snapshot.eventId,
-    partId: snapshot.partId,
-    sessionId: snapshot.sessionId,
-    providerId: snapshot.providerId,
-    modelId: snapshot.modelId,
-    usage: { ...snapshot.usage },
-    limit: { ...snapshot.limit },
-  }
-  if (snapshot.resetAt !== undefined) copy.resetAt = snapshot.resetAt
-  if (snapshot.sequence !== undefined) copy.sequence = snapshot.sequence
-  if (snapshot.observedAt !== undefined) copy.observedAt = snapshot.observedAt
-  return copy
-}
-
-function result(
-  status: UsageStatus,
-  reason: TrackerUpdateReason,
-  snapshot?: ProviderUsageSnapshot,
-): ProviderStreamTrackerResult {
-  return snapshot === undefined
-    ? { status, published: false, reason }
-    : { status, published: true, reason, snapshot: copySnapshot(snapshot) }
-}
-
-function isInScope(event: ProviderUsageEvent, options: ProviderStreamTrackerOptions): boolean {
-  return (
-    (options.sessionId === undefined || options.sessionId === event.sessionId) &&
-    (options.providerId === undefined || options.providerId === event.providerId) &&
-    (options.modelId === undefined || options.modelId === event.modelId)
-  )
-}
-
-function isStale(event: ProviderUsageEvent, state: StreamState): boolean {
-  if (event.sequence !== undefined) {
-    if (state.orderKind === 'sequence' && state.orderValue !== undefined) {
-      return event.sequence <= state.orderValue
-    }
-    return false
-  }
-
-  if (event.observedAt !== undefined) {
-    if (state.orderKind === 'observedAt' && state.orderValue !== undefined) {
-      return event.observedAt <= state.orderValue
-    }
-    return state.orderKind === 'sequence'
-  }
-
-  return state.orderKind !== undefined
-}
-
-function updateOrder(event: ProviderUsageEvent, state: StreamState): void {
-  if (event.sequence !== undefined) {
-    state.orderKind = 'sequence'
-    state.orderValue = event.sequence
-  } else if (event.observedAt !== undefined) {
-    state.orderKind = 'observedAt'
-    state.orderValue = event.observedAt
-  }
-}
-
-/**
- * Create an in-memory tracker. With no scope options, multiple streams are
- * tracked independently by their session/provider/model identity.
- */
-export function createProviderStreamTracker(
-  options: ProviderStreamTrackerOptions = {},
-): ProviderStreamTracker {
-  const streams = new Map<string, StreamState>()
-
-  return {
-    ingest(input: unknown): ProviderStreamTrackerResult {
-      const event = validateProviderUsageEvent(input)
-      if (event === null) return result(USAGE_STATUS.UNSUPPORTED, 'INVALID')
-      if (!isInScope(event, options)) return result(USAGE_STATUS.UNSUPPORTED, 'OUT_OF_SCOPE')
-
-      const key = streamKey(event.sessionId, event.providerId, event.modelId)
-      const state = streams.get(key)
-      if (state?.eventIds.has(event.eventId) || state?.partIds.has(event.partId)) {
-        return result(USAGE_STATUS.SUPPORTED, 'DUPLICATE')
-      }
-
-      if (state !== undefined && isStale(event, state)) {
-        state.eventIds.add(event.eventId)
-        state.partIds.add(event.partId)
-        return result(USAGE_STATUS.SUPPORTED, 'STALE')
-      }
-
-      const nextState: StreamState = state ?? {
-        snapshot: event,
-        eventIds: new Set<string>(),
-        partIds: new Set<string>(),
-      }
-      nextState.snapshot = event
-      nextState.eventIds.add(event.eventId)
-      nextState.partIds.add(event.partId)
-      updateOrder(event, nextState)
-      streams.set(key, nextState)
-
-      const snapshot = copySnapshot(event)
-      options.onSnapshot?.(snapshot)
-      return result(USAGE_STATUS.SUPPORTED, 'PUBLISHED', snapshot)
-    },
-
-    getSnapshot(sessionId: string, providerId: string, modelId: string) {
-      const state = streams.get(streamKey(sessionId, providerId, modelId))
-      return state === undefined ? undefined : copySnapshot(state.snapshot)
-    },
-
-    snapshots() {
-      return [...streams.values()].map((state) => copySnapshot(state.snapshot))
-    },
-
-    clear() {
-      streams.clear()
-    },
-  }
-}

package/src/pantheon/retry-policy.ts

@@ -1,212 +0,0 @@
-/**
- * R1 — Per-error-type retry + provider cooldown (LiteLLM pattern).
- *
- * Pure library (no SDK, no I/O). When a delegation fails, the error is
- * classified (auth | rate_limit | timeout | other), the per-error-type
- * retry policy from routing.yml `retry_policy` is applied with exponential
- * backoff, and provider cooldown state (routing.yml `cooldown`) is tracked
- * in-memory: after `allowed_fails` consecutive failures a provider is
- * skipped for `cooldown_time_seconds`; a success resets the counter.
- *
- * YAGNI: no usage-based routing, no Redis — a simple in-memory cooldown
- * map plus config.
- *
- * @module retry-policy
- */
-
-// ─── Types ─────────────────────────────────────────────────────────────
-
-/** Error classes a delegation failure can be classified into. */
-export type ErrorType = 'auth' | 'rate_limit' | 'timeout' | 'other'
-
-/** Max retries per error class (routing.yml `retry_policy`). */
-export interface RetryPolicy {
-  auth: number
-  rate_limit: number
-  timeout: number
-  other: number
-}
-
-/** Provider cooldown config (routing.yml `cooldown`). */
-export interface CooldownConfig {
-  /** Consecutive failures before the provider is skipped. */
-  allowedFails: number
-  /** How long the provider stays skipped, in seconds. */
-  cooldownTimeSeconds: number
-}
-
-/** Defaults matching routing.yml `retry_policy`. */
-export const DEFAULT_RETRY_POLICY: RetryPolicy = {
-  auth: 0,
-  rate_limit: 3,
-  timeout: 2,
-  other: 1,
-}
-
-/** Defaults matching routing.yml `cooldown`. */
-export const DEFAULT_COOLDOWN: CooldownConfig = {
-  allowedFails: 3,
-  cooldownTimeSeconds: 60,
-}
-
-// ─── Error classification ──────────────────────────────────────────────
-
-const AUTH_RE = /(auth|unauthorized|401|403|api[ _-]?key|invalid credential|permission denied)/i
-const RATE_LIMIT_RE = /(rate[ _-]?limit|429|too many requests|quota|throttl)/i
-const TIMEOUT_RE = /(timeout|timed out|deadline|504|408|etimedout)/i
-
-/**
- * Classify a thrown error into one of the four retry-policy buckets.
- * Message-based matching (LiteLLM pattern); unknown errors → 'other'.
- */
-export function classifyError(err: unknown): ErrorType {
-  const message = err instanceof Error ? err.message : String(err ?? '')
-  if (AUTH_RE.test(message)) return 'auth'
-  if (RATE_LIMIT_RE.test(message)) return 'rate_limit'
-  if (TIMEOUT_RE.test(message)) return 'timeout'
-  return 'other'
-}
-
-// ─── Exponential backoff ───────────────────────────────────────────────
-
-/**
- * Exponential backoff delay for a retry attempt (0-based): base * 2^attempt,
- * capped at maxMs. attempt 0 → base, attempt 1 → 2x base, etc.
- */
-export function computeBackoffMs(attempt: number, baseMs = 1000, maxMs = 30_000): number {
-  const delay = baseMs * 2 ** attempt
-  return Math.min(delay, maxMs)
-}
-
-// ─── Provider cooldown tracker ─────────────────────────────────────────
-
-interface CooldownEntry {
-  fails: number
-  cooldownUntil: number
-}
-
-/**
- * In-memory provider cooldown state. After `allowedFails` consecutive
- * failures a provider is skipped until `cooldownUntil`; a success resets
- * the counter. The clock is injectable for tests.
- */
-export class ProviderCooldownTracker {
-  private readonly state = new Map<string, CooldownEntry>()
-  readonly config: CooldownConfig
-
-  constructor(config: CooldownConfig = DEFAULT_COOLDOWN) {
-    this.config = config
-  }
-
-  /** Record one failure for a provider; trips cooldown at allowedFails. */
-  recordFailure(provider: string): void {
-    const entry = this.state.get(provider) ?? { fails: 0, cooldownUntil: 0 }
-    entry.fails += 1
-    if (entry.fails >= this.config.allowedFails) {
-      entry.cooldownUntil = Date.now() + this.config.cooldownTimeSeconds * 1000
-    }
-    this.state.set(provider, entry)
-  }
-
-  /** Record a success — resets the failure counter (no spurious cooldown). */
-  recordSuccess(provider: string): void {
-    this.state.delete(provider)
-  }
-
-  /**
-   * Whether the provider is currently skipped. Expired cooldowns are
-   * cleared; entries that never tripped (cooldownUntil 0) are kept so the
-   * consecutive-failure counter survives the check.
-   */
-  isInCooldown(provider: string, now = Date.now()): boolean {
-    const entry = this.state.get(provider)
-    if (entry === undefined) return false
-    if (entry.cooldownUntil > now) return true
-    if (entry.cooldownUntil > 0) this.state.delete(provider)
-    return false
-  }
-
-  /** Remaining cooldown time in ms (0 when not in cooldown). */
-  remainingCooldownMs(provider: string, now = Date.now()): number {
-    const entry = this.state.get(provider)
-    if (entry === undefined) return 0
-    return Math.max(0, entry.cooldownUntil - now)
-  }
-
-  /** Current consecutive failure count for a provider. */
-  failCount(provider: string): number {
-    return this.state.get(provider)?.fails ?? 0
-  }
-}
-
-// ─── Retry policy engine ───────────────────────────────────────────────
-
-export type RetryDecisionReason = 'policy' | 'cooldown'
-
-export interface RetryDecision {
-  shouldRetry: boolean
-  /** Retries still available for this error class (0 when exhausted). */
-  retriesRemaining: number
-  /** Backoff delay to wait before the next attempt (ms). */
-  delayMs: number
-  /** Why the decision was made: policy budget or provider cooldown. */
-  reason: RetryDecisionReason
-}
-
-/**
- * Combines error classification, the per-error-type retry policy, and the
- * provider cooldown tracker into one decision point. Enforcement: when a
- * delegation fails, call `decide(provider, err, attemptsUsed)`; when the
- * result is content, call `recordSuccess`; when the budget is exhausted,
- * call `recordFailure` so the cooldown can trip.
- */
-export class RetryPolicyEngine {
-  private readonly cooldown: ProviderCooldownTracker
-  readonly policy: RetryPolicy
-  readonly backoffBaseMs: number
-
-  constructor(
-    policy: RetryPolicy = DEFAULT_RETRY_POLICY,
-    cooldown?: ProviderCooldownTracker,
-    backoffBaseMs = 1000,
-  ) {
-    this.policy = policy
-    this.backoffBaseMs = backoffBaseMs
-    this.cooldown = cooldown ?? new ProviderCooldownTracker()
-  }
-
-  /**
-   * Decide whether a failed dispatch should be retried.
-   *
-   * @param provider provider name (cooldown key, e.g. "opencode")
-   * @param err the failure (classified into auth/rate_limit/timeout/other)
-   * @param attemptsUsed retries already consumed for this dispatch
-   * @param now injectable clock (tests)
-   */
-  decide(provider: string, err: unknown, attemptsUsed: number, now = Date.now()): RetryDecision {
-    if (this.cooldown.isInCooldown(provider, now)) {
-      return { shouldRetry: false, retriesRemaining: 0, delayMs: 0, reason: 'cooldown' }
-    }
-    const type = classifyError(err)
-    const retriesRemaining = Math.max(0, this.policy[type] - attemptsUsed)
-    if (retriesRemaining <= 0) {
-      return { shouldRetry: false, retriesRemaining: 0, delayMs: 0, reason: 'policy' }
-    }
-    return {
-      shouldRetry: true,
-      retriesRemaining,
-      delayMs: computeBackoffMs(attemptsUsed, this.backoffBaseMs),
-      reason: 'policy',
-    }
-  }
-
-  /** Record a failure (feeds the cooldown tracker). */
-  recordFailure(provider: string, _err: unknown): void {
-    this.cooldown.recordFailure(provider)
-  }
-
-  /** Record a success (resets the provider's failure counter). */
-  recordSuccess(provider: string): void {
-    this.cooldown.recordSuccess(provider)
-  }
-}