Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

20.6 KB
Raw Blame
import { getManagementKey, lockManagementKey } from './management-key'
import { createAdminClient } from '#/lib/admin'
import type { AdminConnection } from '#/lib/admin'

import { getOvResult, isOvClientError } from '#/lib/ov-client'

/** Credentials captured with the query scope; undefined reads the current tab key. */
export type GatewayConnection = AdminConnection & { managementKey?: string }

/** Wire protocol an upstream speaks; the gateway never converts between them. */
export type Protocol = 'anthropic' | 'chat' | 'responses'
export type Vendor =
  | 'generic'
  | 'anthropic'
  | 'openai'
  | 'deepseek'
  | 'ark'
  | 'byteplus'
export type AuthMode = 'managed' | 'passthrough'
/** Header the upstream key is sent in. */
export type KeyHeader = 'authorization' | 'api-key' | 'x-api-key'

/** Sources recall searches, in display order. */
export const CONTEXT_TYPES = ['memory', 'resource', 'skill'] as const
export type ContextType = (typeof CONTEXT_TYPES)[number]

/** Categories for "Limit by category", in display order. */
export const QUOTA_BUCKETS = [
  'events',
  'entities',
  'preferences',
  'experiences',
  'resources',
  'skills',
] as const
export type QuotaBucket = (typeof QUOTA_BUCKETS)[number]

/** A tool from OpenViking MCP, using its original name. */
export type GatewayTool = {
  name: string
  description: string
  annotations?: { readOnlyHint?: boolean } & Record<string, unknown>
}

/** Request types in the log, in the order the type filter lists them. */
export const LOG_KINDS = [
  'user',
  'continuation',
  'auxiliary',
  'subagent',
  'count',
  'passthrough',
  'capture',
] as const
export type LogKind = (typeof LOG_KINDS)[number]

export type CaptureStatus = 'active' | 'disabled' | 'retrying' | 'paused'

type UpstreamSettings = {
  name: string
  protocol: Protocol
  base_url: string
  /** Append the selected protocol's endpoint path to base_url. */
  append_endpoint_path: boolean
  auth_mode: AuthMode
  key_header: KeyHeader
  models: string[]
  /** Name clients use → model sent to the upstream. */
  aliases: Record<string, string>
  priority: number
  enabled: boolean
  vendor: Vendor
  allow_gateway_tools: boolean
  /**
   * Send back the reasoning clients drop from relayed replies; null follows
   * the vendor (see `replaysReasoning`).
   */
  replay_reasoning: boolean | null
  coding_plan: boolean
  allow_coding_plan: boolean
  cache_min_tokens: number
  /** Upstream model name → context window in tokens. */
  context_windows: Record<string, number>
}

/** An upstream as listed by the gateway; secrets are never returned. */
export type Upstream = UpstreamSettings & {
  id: string
  revision: number
  has_api_key: boolean
  header_names?: string[]
}

/**
 * Body of `PUT upstreams/{id}`. A blank `api_key` keeps the stored key; a
 * header with a blank value keeps its stored value; omitted headers are retained.
 * Changing base_url clears retained API-key and header secrets.
 */
export type UpstreamInput = UpstreamSettings & {
  api_key: string
  headers: Record<string, string>
}

/** Every field of a context profile (the gateway's `Policy`). */
export type ProfileSettings = {
  name: string
  recall: boolean
  profile: boolean
  profile_max_tokens: number
  capture: boolean
  context_types: ContextType[]
  quotas: Partial<Record<QuotaBucket, number>>
  max_tokens: number
  session_max_tokens: number
  score_threshold: number
  recall_timeout: number
  query_max_chars: number
  show_recall: boolean
  commit_tokens: number
  keep_recent_messages: number
  idle_seconds: number
  compaction: boolean
  compaction_threshold: number
  summary_max_tokens: number
  context_window: number | null
  agent_windows: boolean
  window_soft_ratio: number
  window_hard_ratio: number
  gateway_tools: boolean
  show_tool_calls: boolean
  disabled_tools: string[]
  tool_max_rounds: number | null
  tool_timeout_seconds: number
  tool_result_bytes: number
  tool_total_seconds: number | null
  tool_total_tokens: number | null
  /** Clients may override the other settings with `X-OpenViking-Context`. */
  client_overrides: boolean
}

export type Profile = ProfileSettings & { id: string; revision: number }

/** A gateway key as listed; the secret itself is only returned once. */
export type GatewayKey = {
  id: string
  revision: number
  name: string
  /**
   * An OpenViking API key used directly. It stores no binding, so name,
   * policy_id, upstream_ids and models are empty; the gateway applies the
   * account's defaults to each request.
   */
  source?: 'openviking'
  policy_id: string
  upstream_ids: string[]
  models: string[]
  user_id: string
  /** First characters of the secret: 12 of a gateway key (`ovgw_Ab3dE9x`), 8 of an OpenViking API key. */
  prefix: string
  /** Epoch seconds. */
  created_at: number
}

export type IssuedKey = GatewayKey & { key: string }

/** Gateway keys that use an upstream or a context profile; undefined while keys are unknown. */
export function keysUsing(
  keys: GatewayKey[] | undefined,
  target: { upstreamId: string } | { profileId: string },
): number | undefined {
  return keys?.filter((key) =>
    'upstreamId' in target
      ? key.upstream_ids.includes(target.upstreamId)
      : key.policy_id === target.profileId,
  ).length
}

/**
 * Who a new key acts as: a user of this account, whose key OpenViking Server
 * looks up itself, or that user's OpenViking key pasted by the admin.
 */
export type KeyOwner = { user_id?: string; openviking_key?: string }

export type KeyRequest = KeyOwner & {
  name: string
  policy_id: string
  upstream_ids: string[]
  models: string[]
}

/** A user of this account a key can act as; root is never one of them. */
export type KeyUser = {
  user_id: string
  role: 'admin' | 'user'
  /**
   * False when the server can't read the user's key, e.g. it keeps only a
   * hash. OpenViking servers that predate the field omit it.
   */
  api_key_available?: boolean
}

export type CacheStats = {
  requests: number
  input_tokens: number
  cached_tokens: number
  cache_hit_ratio: number
}

/** Last OpenViking health check of the gateway process that answered. */
export type OpenVikingHealth = {
  status: string
  healthy?: boolean
  version?: string
  auth_mode?: string
  reason?: string
}

/** A conversation whose latest long model calls all missed the prompt cache. */
export type CacheMiss = {
  upstream_id: string
  model: string
  /** Long calls in a row without a cache hit. */
  streak: number
  /** Epoch seconds of the newest call. */
  last_at: number
}

export type CacheAlerts = {
  /** Conversations missing the cache; null without any. */
  misses: {
    conversations: number
    /** Shortest streak and smallest first-call input among them. */
    streak: number
    input_tokens: number
    /** All are Anthropic conversations that never wrote the cache either. */
    no_writes: boolean
    /** The newest three conversations. */
    recent: CacheMiss[]
  } | null
  /** Ids of upstreams whose long calls have not hit the cache lately, sorted. */
  unreported: string[]
}

export type Overview = {
  /** Model requests in the sample (memory-sync events excluded). */
  requests: number
  /** Epoch seconds of the newest model request, or null. */
  last_request_at: number | null
  output_tokens: number
  cache: { first_call: CacheStats; continuation: CacheStats }
  degradations: Record<string, number>
  openviking: OpenVikingHealth
  recall_count: number
  /** Requests that made a recall decision. */
  recall_requests: number
  /** Average recall time in ms over `recall_requests`. */
  recall_ms: number
  /** Conversations whose latest saving status is retrying or paused. */
  capture_issues: { retrying: number; paused: number }
  sample_limit: number
  /** Days the request log keeps records. */
  log_retention_days: number
  /** Conversations and upstreams missing the prompt cache; null without any. */
  cache_alerts: CacheAlerts | null
}

/** One request-log record (metadata only); every field but `time` is optional. */
export type LogRecord = {
  /** Epoch seconds. */
  time: number
  request_id?: string
  kind?: LogKind
  model?: string
  status?: number
  upstream_id?: string
  session?: string
  protocol?: Protocol
  credential_id?: string
  replay_hits?: number
  recall_count?: number
  recall_ms?: number
  recall_reason?: string
  capture_status?: CaptureStatus
  capture_reason?: string
  /** Epoch seconds or null. */
  capture_retry_at?: number | null
  tool_skip_reason?: string
  tool_stop_reason?: string
  hidden_rounds?: number
  hidden_upstream_calls?: number
  hidden_added_tokens?: number
  first_upstream_input_tokens?: number
  first_upstream_output_tokens?: number
  first_upstream_cached_tokens?: number
  first_upstream_cache_write_tokens?: number
  hidden_upstream_input_tokens?: number
  hidden_upstream_output_tokens?: number
  hidden_upstream_cached_tokens?: number
  hidden_upstream_cache_write_tokens?: number
  degradation?: string
  /** Anchor of the cut whose replacement this request used. */
  compaction_applied?: string
  /**
   * Why compaction failed. The full history was sent, except for
   * `still_over_threshold`, where the summary was written and kept.
   */
  compaction_failed?: string
  /** Estimated size of the summary written for this request. */
  compaction_tokens?: number
  compaction_ms?: number
  /** Estimated context size and the window it was compared with. */
  context_tokens?: number
  context_window?: number
  /** Current context window, while the model manages its own windows. */
  window?: number
  window_reset?: boolean
  window_reminder?: 'soft' | 'hard'
  input_tokens?: number
  output_tokens?: number
  cached_tokens?: number
  cache_write_tokens?: number
  cache_min_tokens?: number
  cache_eligible?: boolean
  duration_ms?: number
  /** Profile fields the client set with `X-OpenViking-Context`; values are not logged. */
  context_override?: string[]
}

/** Where clients reach the gateway. */
export type ConnectionInfo = {
  base_url: string
  public_url_configured: boolean
}

export type GatewayAccess = {
  managed: boolean
  can_write_objects: boolean
  can_import_vlm: boolean
  can_issue_for_others: boolean
  role: string
  account_id: string
  user_id: string
  warnings: string[]
}

export type VlmImportResult = {
  imported: Array<{ id: string; name: string }>
  needs_confirmation: Array<{ id: string; name: string }>
  skipped: Array<{ id: string; reason: string }>
}

export type UpstreamTestResult = {
  url?: string
  ok: boolean
  kind?: 'connection' | 'model'
  status?: number
  reason?: string
  response?: {
    http_version: string
    status: number
    reason: string
    headers: Record<string, string | string[]>
    body: string
    truncated?: boolean
  }
}

/** Conversation to resync, taken from a log record. */
export type ResyncTarget = { session: string; protocol: Protocol }

export type GatewayErrorReason = string

const UNAVAILABLE = [
  'not_enabled',
  'trusted_mode_unsupported',
  'openviking_unreachable',
]

/** A failed gateway call: HTTP status, the server's own message, and a category. */
export class GatewayError extends Error {
  readonly status?: number
  readonly detail: string
  readonly reason: GatewayErrorReason
  readonly keyCount?: number
  readonly requiredVersion?: string

  constructor(
    detail: string,
    status?: number,
    cause?: unknown,
    reason?: GatewayErrorReason,
    metadata?: Record<string, unknown>,
  ) {
    super(detail, cause ? { cause } : undefined)
    this.name = 'GatewayError'
    this.detail = detail
    this.status = status
    this.reason = reason ?? classify(status)
    this.keyCount =
      typeof metadata?.key_count === 'number' ? metadata.key_count : undefined
    this.requiredVersion =
      typeof metadata?.required_version === 'string'
        ? metadata.required_version
        : undefined
  }

  /** True when the gateway itself is off, misconfigured, down or missing. */
  get unavailable(): boolean {
    return UNAVAILABLE.includes(this.reason)
  }
}

const STATUS_REASONS: Partial<Record<number, GatewayErrorReason>> = {
  400: 'invalid',
  401: 'unauthorized',
  403: 'forbidden',
  404: 'not_found',
  409: 'conflict',
  422: 'invalid',
}

function classify(status?: number): GatewayErrorReason {
  return (status === undefined ? undefined : STATUS_REASONS[status]) ?? 'other'
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value)
}

/** Reads the message out of FastAPI, gateway and OpenViking error bodies. */
function readDetail(body: unknown): string | undefined {
  if (!isRecord(body)) return typeof body === 'string' ? body : undefined
  const { detail, error } = body
  if (typeof detail === 'string') return detail
  if (Array.isArray(detail)) {
    const messages = detail
      .map((item) => (isRecord(item) ? item.msg : item))
      .filter((item): item is string => typeof item === 'string')
    if (messages.length) return messages.join('; ')
  }
  if (isRecord(error) && typeof error.message === 'string') {
    return error.message
  }
  return undefined
}

function readReason(body: unknown): string | undefined {
  return isRecord(body) && typeof body.reason === 'string'
    ? body.reason
    : undefined
}

/** Normalizes anything a gateway call can throw into a `GatewayError`. */
export function toGatewayError(error: unknown): GatewayError {
  if (error instanceof GatewayError) return error
  if (isOvClientError(error)) {
    return new GatewayError(
      readDetail(error.responseBody) ?? error.message,
      error.statusCode,
      error,
      readReason(error.responseBody),
      isRecord(error.responseBody) ? error.responseBody : undefined,
    )
  }
  return new GatewayError(
    error instanceof Error ? error.message : String(error),
    undefined,
    error,
  )
}

const BASE_PATH = '/gateway/admin'

type Method = 'GET' | 'POST' | 'PUT' | 'DELETE'

type RequestOptions = {
  query?: Record<string, unknown>
  body?: unknown
  headers?: Record<string, string>
}

/** One OpenViking Server call; any failure becomes a `GatewayError`. */
async function call<T>(
  connection: GatewayConnection,
  method: Method,
  url: string,
  options: RequestOptions = {},
): Promise<T> {
  const body =
    options.body === undefined
      ? {}
      : {
          body: options.body,
          headers: { 'Content-Type': 'application/json', ...options.headers },
        }
  try {
    return await getOvResult<T>(
      createAdminClient(connection).request({
        method,
        url,
        query: options.query,
        headers: options.headers,
        ...body,
      }),
    )
  } catch (error) {
    throw toGatewayError(error)
  }
}

/** Calls the gateway's management API through OpenViking Server. */
async function send<T>(
  connection: GatewayConnection,
  method: Method,
  segments: string[],
  options?: Omit<RequestOptions, 'headers'>,
): Promise<T> {
  const url = [BASE_PATH, ...segments.map(encodeURIComponent)].join('/')
  const managementKey =
    connection.managementKey ?? getManagementKey(connection.baseUrl)
  try {
    return await call<T>(connection, method, url, {
      ...options,
      query: { ...options?.query, account_id: connection.accountId },
      headers: managementKey
        ? { 'X-OpenViking-Gateway-Management-Key': managementKey }
        : undefined,
    })
  } catch (error) {
    const failure = toGatewayError(error)
    // Lock only a stored key, not a candidate or a key replaced meanwhile.
    if (
      failure.reason === 'management_key_invalid' &&
      managementKey === getManagementKey(connection.baseUrl)
    ) {
      lockManagementKey(connection.baseUrl, true)
    }
    throw failure
  }
}

/**
 * Gateway address for clients; also the layout's availability probe. A 404
 * means the OpenViking server has no OpenViking Gateway management at all.
 */
export async function getConnectionInfo(
  connection: GatewayConnection,
): Promise<ConnectionInfo> {
  try {
    return await send<ConnectionInfo>(connection, 'GET', ['guides'])
  } catch (error) {
    const failure = toGatewayError(error)
    if (failure.status !== 404) throw failure
    throw new GatewayError(failure.detail, 404, failure, 'not_enabled')
  }
}

/** Pass `managementKey` in the connection to check a candidate key. */
export async function getAccess(
  connection: GatewayConnection,
): Promise<GatewayAccess> {
  try {
    return await send<GatewayAccess>(connection, 'GET', ['access'])
  } catch (error) {
    const failure = toGatewayError(error)
    if (failure.status === 404)
      throw new GatewayError(failure.detail, 404, failure, 'not_enabled')
    throw failure
  }
}

export const importVlm = (connection: GatewayConnection) =>
  send<VlmImportResult>(connection, 'POST', ['upstreams', 'import-vlm'])

export const getOverview = (connection: GatewayConnection) =>
  send<Overview>(connection, 'GET', ['overview'])

/** Newest-first request log; the gateway caps `limit` at 1,000. */
export const listLogs = (connection: GatewayConnection, limit = 200) =>
  send<LogRecord[]>(connection, 'GET', ['logs'], { query: { limit } })

export const listUpstreams = (connection: GatewayConnection) =>
  send<Upstream[]>(connection, 'GET', ['upstreams'])

/** OpenViking MCP tools, read with the caller's OpenViking key (root: a key issued in this account). */
export const listTools = (connection: GatewayConnection) =>
  send<GatewayTool[]>(connection, 'GET', ['tools'])

/** Creates or replaces an upstream. Build the body with `toUpstreamInput`. */
export const saveUpstream = (
  connection: GatewayConnection,
  id: string,
  input: UpstreamInput,
) => send<Upstream>(connection, 'PUT', ['upstreams', id], { body: input })

/** Fails with reason `conflict` while keys still use the upstream. */
export const deleteUpstream = (connection: GatewayConnection, id: string) =>
  send<{ deleted: boolean }>(connection, 'DELETE', ['upstreams', id])

/** Checks connectivity, or sends one small generation request when a model is given. */
export const testUpstream = (
  connection: GatewayConnection,
  id: string,
  model?: string,
) =>
  send<UpstreamTestResult>(connection, 'POST', ['upstreams', id, 'test'], {
    body: model ? { model } : {},
  })

export const listProfiles = (connection: GatewayConnection) =>
  send<Profile[]>(connection, 'GET', ['policies'])

/** Creates or replaces a profile. Build the body with `toProfileSettings`. */
export const saveProfile = (
  connection: GatewayConnection,
  id: string,
  settings: ProfileSettings,
) => send<Profile>(connection, 'PUT', ['policies', id], { body: settings })

/** Fails with reason `conflict` while keys still use the profile. */
export const deleteProfile = (connection: GatewayConnection, id: string) =>
  send<{ deleted: boolean }>(connection, 'DELETE', ['policies', id])

export const listKeys = (connection: GatewayConnection) =>
  send<GatewayKey[]>(connection, 'GET', ['keys'])

const KEY_USER_ROLES: readonly string[] = ['admin', 'user']

/**
 * Users of the current account a key can act as. The server says only
 * whether it can read each user's key; the key never reaches the browser.
 */
export async function listKeyUsers(
  connection: GatewayConnection,
): Promise<KeyUser[]> {
  const users = await call<Array<Omit<KeyUser, 'role'> & { role: string }>>(
    connection,
    'GET',
    `/api/v1/admin/accounts/${encodeURIComponent(connection.accountId)}/users`,
    { query: { include_credentials: false } },
  )
  return users.filter((user): user is KeyUser =>
    KEY_USER_ROLES.includes(user.role),
  )
}

/**
 * Issues a key; the response is the only time the secret is available. For a
 * `user_id`, OpenViking Server sends that user's stored key to the gateway.
 */
export const issueKey = (connection: GatewayConnection, request: KeyRequest) =>
  send<IssuedKey>(connection, 'POST', ['keys'], { body: request })

export const revokeKey = (connection: GatewayConnection, id: string) =>
  send<{ deleted: boolean }>(connection, 'DELETE', ['keys', id])

/** Starts a fresh OpenViking session for one conversation of a key. */
export const resyncCapture = (
  connection: GatewayConnection,
  keyId: string,
  target: ResyncTarget,
) =>
  send<{ status: string; message: string }>(
    connection,
    'POST',
    ['keys', keyId, 'capture', 'reset'],
    { body: target },
  )

/** Revokes every key of an OpenViking user and deletes their gateway conversations. */
export const deleteUserData = (connection: GatewayConnection, userId: string) =>
  send<{ deleted: boolean }>(connection, 'DELETE', ['users', userId, 'data'])

/**
 * Random id for a new upstream or profile. Uses `getRandomValues`, which,
 * unlike `randomUUID`, also works when Studio is served over plain HTTP.
 */
export function newObjectId(): string {
  const bytes = crypto.getRandomValues(new Uint8Array(8))
  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join(
    '',
  )
}