Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
import { resolveApiKeyAuth, createApiKeyHeaders } from '#/lib/connection/auth'
import type { ApiKeyAuth } from '#/lib/connection/auth'
import axios from 'axios'
import type { ServerMode } from '#/lib/connection/health'
import { createClient } from '#/gen/ov-client/client'
import {
deleteAdminAccountByAccountId,
deleteAdminAccountIdUserByUserId,
getAdminAccountIdUsers,
getAdminAccounts,
getOvResult,
postAdminAccountIdUserIdKey,
postAdminAccounts,
putAdminAccountIdUserIdRole,
} from '#/lib/ov-client'
import type { UserMemoryPolicy } from './user-memory-policy'
export type AdminUserRole = 'admin' | 'root' | 'user'
export type AdminConnection = {
accountId: string
apiKey: string
baseUrl: string
userId: string
}
export type AdminAccount = {
accountId: string
createdAt?: string
userCount: number
}
export type AdminUser = {
accountId: string
apiKey?: string
keyPrefix?: string
role: string
userId: string
}
export type CreateAccountInput = {
accountId: string
adminUserId: string
}
export type CreateUserInput = {
memoryPolicy?: UserMemoryPolicy
accountId: string
role: string
userId: string
}
export type KeyResult = {
accountId?: string
apiKey: string
userId?: string
}
export type UpdateUserRoleInput = {
accountId: string
role: AdminUserRole
userId: string
}
export type ProbeState = 'ok' | 'error' | 'skipped'
export type CapabilityDetailCode =
| 'accountAdminAvailable'
| 'adminModeRequired'
| 'controlKeyRequired'
| 'dataKeyRequired'
| 'rootAvailable'
| 'tenantDataAvailable'
| 'trustedIdentityRequired'
| 'trustedKeyRequired'
export type CapabilityProbeResult = {
detail?: string
detailCode?: CapabilityDetailCode
errorCode?: string
statusCode?: number
state: ProbeState
}
export type StudioConnectionProbe = {
admin: CapabilityProbeResult
data: CapabilityProbeResult
}
export type ProbeConnectionInput = {
apiKeyAuth?: ApiKeyAuth
skipAdmin?: boolean
dataRootUri?: string
accountId: string
adminApiKey: string
apiKey: string
baseUrl: string
serverMode: ServerMode
userId: string
}
function isRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === 'object' && !Array.isArray(value)
}
function asString(value: unknown): string | undefined {
return typeof value === 'string' ? value : undefined
}
function asNumber(value: unknown): number {
return typeof value === 'number' && Number.isFinite(value) ? value : 0
}
function normalizeBaseUrl(baseUrl: string): string {
return baseUrl.trim().replace(/\/+$/, '')
}
function setOptionalHeader(
headers: Record<string, string>,
name: string,
value: string,
): void {
const trimmed = value.trim()
if (trimmed) {
headers[name] = trimmed
}
}
export function createAdminClient(connection: AdminConnection) {
const headers: Record<string, string> = {
Accept: 'application/json',
}
setOptionalHeader(headers, 'X-API-Key', connection.apiKey)
return createClient({
axios: axios.create(),
baseURL: normalizeBaseUrl(connection.baseUrl),
headers,
throwOnError: true,
})
}
function getErrorMessage(error: unknown): string {
if (axios.isAxiosError(error)) {
const data = error.response?.data
if (isRecord(data) && isRecord(data.error)) {
const message = asString(data.error.message)
if (message) {
return message
}
}
if (error.response?.status) {
return `HTTP ${error.response.status}`
}
}
return error instanceof Error ? error.message : String(error)
}
function createProbeClient(baseUrl: string) {
return axios.create({
baseURL: normalizeBaseUrl(baseUrl),
headers: {
Accept: 'application/json',
},
})
}
function setApiKeyHeader(
headers: Record<string, string>,
apiKey: string,
auth: ApiKeyAuth = 'header',
): void {
Object.assign(headers, createApiKeyHeaders(apiKey, auth))
}
function probeError(error: unknown): CapabilityProbeResult {
const response = axios.isAxiosError(error) ? error.response : undefined
const payload: unknown = response?.data
return {
detail: getErrorMessage(error),
errorCode:
isRecord(payload) && isRecord(payload.error)
? asString(payload.error.code)
: undefined,
statusCode: response?.status,
state: 'error',
}
}
async function probeAdminAccess(
input: ProbeConnectionInput,
): Promise<CapabilityProbeResult> {
if (input.serverMode === 'checking' || input.serverMode === 'offline') {
return { state: 'skipped' }
}
if (input.serverMode === 'dev') {
return {
detailCode: 'adminModeRequired',
state: 'skipped',
}
}
// Check the control-plane credential's authenticated role. Listing users is
// also available to ordinary users and cannot prove management permission.
const controlKey = input.adminApiKey.trim()
if (!controlKey) {
return {
detailCode:
input.serverMode === 'trusted'
? 'trustedKeyRequired'
: 'controlKeyRequired',
state: 'skipped',
}
}
const client = createProbeClient(input.baseUrl)
const headers: Record<string, string> = {}
setApiKeyHeader(headers, controlKey)
try {
const { data } = await client.get<unknown>('/health', { headers })
if (isRecord(data) && data.role === 'root') {
return { detailCode: 'rootAvailable', state: 'ok' }
}
if (
isRecord(data) &&
data.role === 'admin' &&
input.accountId.trim() &&
data.account_id === input.accountId.trim()
) {
return { detailCode: 'accountAdminAvailable', state: 'ok' }
}
return {
errorCode: 'PERMISSION_DENIED',
statusCode: 403,
state: 'error',
}
} catch (error) {
return probeError(error)
}
}
async function probeDataAccess(
input: ProbeConnectionInput,
): Promise<CapabilityProbeResult> {
if (input.serverMode === 'checking' || input.serverMode === 'offline') {
return { state: 'skipped' }
}
const apiKey =
input.apiKey || (input.serverMode === 'trusted' ? input.adminApiKey : '')
if (input.serverMode !== 'dev' && !apiKey) {
return {
detailCode:
input.serverMode === 'trusted'
? 'trustedKeyRequired'
: 'dataKeyRequired',
state: 'skipped',
}
}
if (
input.serverMode === 'trusted' &&
(!input.accountId.trim() || !input.userId.trim())
) {
return {
detailCode: 'trustedIdentityRequired',
state: 'skipped',
}
}
const client = createProbeClient(input.baseUrl)
const headers: Record<string, string> = {}
setApiKeyHeader(
headers,
input.apiKey || (input.serverMode === 'trusted' ? input.adminApiKey : ''),
input.apiKeyAuth ?? resolveApiKeyAuth(input.baseUrl),
)
if (input.serverMode === 'trusted') {
setOptionalHeader(headers, 'X-OpenViking-Account', input.accountId)
setOptionalHeader(headers, 'X-OpenViking-User', input.userId)
}
try {
await client.get('/api/v1/fs/ls', {
headers,
params: {
node_limit: 1,
output: 'agent',
uri: input.dataRootUri ?? 'viking://',
},
})
return {
detailCode: 'tenantDataAvailable',
state: 'ok',
}
} catch (error) {
return probeError(error)
}
}
export async function probeStudioConnection(
input: ProbeConnectionInput,
): Promise<StudioConnectionProbe> {
const [admin, data] = await Promise.all([
input.skipAdmin
? Promise.resolve({ state: 'skipped' as const })
: probeAdminAccess(input),
probeDataAccess(input),
])
return { admin, data }
}
function normalizeAccount(value: unknown): AdminAccount | null {
if (!isRecord(value) || value.status === 'deleting') {
return null
}
const accountId = asString(value.account_id)
if (!accountId) {
return null
}
return {
accountId,
createdAt: asString(value.created_at),
userCount: asNumber(value.user_count),
}
}
function normalizeUser(accountId: string, value: unknown): AdminUser | null {
if (!isRecord(value)) {
return null
}
const userId = asString(value.user_id)
if (!userId) {
return null
}
return {
accountId,
apiKey: asString(value.api_key),
keyPrefix: asString(value.key_prefix),
role: asString(value.role) || 'user',
userId,
}
}
function normalizeKeyResult(value: unknown): KeyResult {
if (!isRecord(value)) {
return { apiKey: '' }
}
return {
accountId: asString(value.account_id),
apiKey: asString(value.user_key) || asString(value.api_key) || '',
userId: asString(value.user_id) || asString(value.admin_user_id),
}
}
export async function fetchAdminAccounts(
connection: AdminConnection,
): Promise<AdminAccount[]> {
const result = await getOvResult<unknown[]>(
getAdminAccounts({
client: createAdminClient(connection),
}),
)
return result
.map((item) => normalizeAccount(item))
.filter((item): item is AdminAccount => Boolean(item))
}
export async function fetchAdminUsers(
connection: AdminConnection,
accountId: string,
): Promise<AdminUser[]> {
const result = await getOvResult<unknown[]>(
getAdminAccountIdUsers({
client: createAdminClient(connection),
path: {
account_id: accountId,
},
}),
)
return result
.map((item) => normalizeUser(accountId, item))
.filter((item): item is AdminUser => Boolean(item))
}
/** List selectable identities without returning their API keys to the wizard. */
export async function fetchAdminUserDirectory(
connection: AdminConnection,
accountId: string,
): Promise<AdminUser[]> {
const result = await getOvResult<unknown[]>(
createAdminClient(connection).get({
url: '/api/v1/admin/accounts/{account_id}/users',
path: { account_id: accountId },
query: { include_credentials: false },
}),
)
return result
.map((item) => normalizeUser(accountId, item))
.filter((item): item is AdminUser => Boolean(item))
}
export type AdminUserPage = {
users: AdminUser[]
total: number
accountTotal: number
managerCount: number
keyCount: number
}
export async function fetchAdminUsersPage(
connection: AdminConnection,
accountId: string,
options: { page: number; pageSize: number; search: string },
): Promise<AdminUserPage> {
const result = await getOvResult<{
users: unknown[]
total: number
account_total: number
manager_count: number
key_count: number
}>(
createAdminClient(connection).get({
url: '/api/v1/admin/accounts/{account_id}/users',
path: { account_id: accountId },
query: {
page: options.page,
limit: options.pageSize,
query: options.search.trim() || undefined,
include_summary: true,
},
}),
)
return {
users: result.users
.map((item) => normalizeUser(accountId, item))
.filter((item): item is AdminUser => Boolean(item)),
total: result.total,
accountTotal: result.account_total,
managerCount: result.manager_count,
keyCount: result.key_count,
}
}
export async function createAdminAccount(
connection: AdminConnection,
input: CreateAccountInput,
): Promise<KeyResult> {
const result = await getOvResult<unknown>(
postAdminAccounts({
body: {
account_id: input.accountId,
admin_user_id: input.adminUserId,
},
client: createAdminClient(connection),
}),
)
return normalizeKeyResult(result)
}
export async function deleteAdminAccount(
connection: AdminConnection,
accountId: string,
): Promise<string> {
const result = await getOvResult<{ task_id: string }>(
deleteAdminAccountByAccountId({
client: createAdminClient(connection),
path: {
account_id: accountId,
},
}),
)
return result.task_id
}
export async function createAdminUser(
connection: AdminConnection,
input: CreateUserInput,
): Promise<KeyResult> {
const result = await getOvResult<unknown>(
createAdminClient(connection).post({
url: '/api/v1/admin/accounts/{account_id}/users',
headers: { 'Content-Type': 'application/json' },
body: {
role: input.role,
user_id: input.userId,
...(input.memoryPolicy
? { user_config: { memory_policy: input.memoryPolicy } }
: {}),
},
path: {
account_id: input.accountId,
},
}),
)
return normalizeKeyResult(result)
}
export async function regenerateAdminUserKey(
connection: AdminConnection,
accountId: string,
userId: string,
): Promise<KeyResult> {
const result = await getOvResult<unknown>(
postAdminAccountIdUserIdKey({
client: createAdminClient(connection),
path: {
account_id: accountId,
user_id: userId,
},
}),
)
return normalizeKeyResult({
...(isRecord(result) ? result : {}),
account_id: accountId,
user_id: userId,
})
}
export async function removeAdminUser(
connection: AdminConnection,
accountId: string,
userId: string,
): Promise<void> {
await getOvResult<unknown>(
deleteAdminAccountIdUserByUserId({
client: createAdminClient(connection),
path: {
account_id: accountId,
user_id: userId,
},
}),
)
}
export async function updateAdminUserRole(
connection: AdminConnection,
input: UpdateUserRoleInput,
): Promise<void> {
await getOvResult<unknown>(
putAdminAccountIdUserIdRole({
body: {
role: input.role,
},
client: createAdminClient(connection),
path: {
account_id: input.accountId,
user_id: input.userId,
},
}),
)
}
export type UserMemorySettings = { memory_policy: UserMemoryPolicy }
export async function fetchUserMemorySettings(
connection: AdminConnection,
accountId: string,
userId: string,
): Promise<UserMemorySettings> {
return getOvResult<UserMemorySettings>(
createAdminClient(connection).get({
url: '/api/v1/admin/accounts/{account_id}/users/{user_id}/settings',
path: { account_id: accountId, user_id: userId },
}),
)
}
export async function updateUserMemorySettings(
connection: AdminConnection,
accountId: string,
userId: string,
memoryPolicy: UserMemoryPolicy,
): Promise<UserMemorySettings> {
return getOvResult<UserMemorySettings>(
createAdminClient(connection).patch({
url: '/api/v1/admin/accounts/{account_id}/users/{user_id}/settings',
path: { account_id: accountId, user_id: userId },
headers: { 'Content-Type': 'application/json' },
body: { memory_policy: memoryPolicy },
}),
)
}
export type AdminGroup = { group_id: string; member_count: number }
const groupsUrl = '/api/v1/admin/accounts/{account_id}/groups'
export function fetchAdminGroups(connection: AdminConnection) {
return getOvResult<AdminGroup[]>(
createAdminClient(connection).get({
url: groupsUrl,
path: { account_id: connection.accountId },
}),
)
}
export function createAdminGroup(connection: AdminConnection, groupId: string) {
return getOvResult<AdminGroup>(
createAdminClient(connection).post({
url: groupsUrl,
path: { account_id: connection.accountId },
headers: { 'Content-Type': 'application/json' },
body: { group_id: groupId },
}),
)
}
export function deleteAdminGroup(connection: AdminConnection, groupId: string) {
return getOvResult<{ deleted: boolean }>(
createAdminClient(connection).delete({
url: `${groupsUrl}/{group_id}`,
path: { account_id: connection.accountId, group_id: groupId },
}),
)
}
export function fetchAdminGroupMembers(
connection: AdminConnection,
groupId: string,
) {
return getOvResult<{ group_id: string; members: string[] }>(
createAdminClient(connection).get({
url: `${groupsUrl}/{group_id}/members`,
path: { account_id: connection.accountId, group_id: groupId },
}),
)
}
export function updateAdminGroupMember(
connection: AdminConnection,
groupId: string,
userId: string,
add: boolean,
) {
const client = createAdminClient(connection)
const options = {
url: `${groupsUrl}/{group_id}/members/{user_id}`,
path: {
account_id: connection.accountId,
group_id: groupId,
user_id: userId,
},
}
return getOvResult<unknown>(
add ? client.put(options) : client.delete(options),
)
}