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 i18n from '#/i18n/core'
import { parseSessionArchive, parseSessionMessages } from './parse-messages'
import {
deleteSessionBySessionId,
getContentRead,
getSessionIdArchiveByArchiveId,
getSessions,
getSessionBySessionId,
getSessionIdContext,
postBotV1Chat,
postSessions,
postSessionIdCommit,
postSessionIdMessages,
} from '#/gen/ov-client/sdk.gen'
import {
getOvResult,
normalizeOvClientError,
OvClientError,
ovClient,
} from '#/lib/ov-client'
import { fetchSse } from '#/lib/sse'
import { parseSessionMemoryDiff } from './memory-diff'
import type { BotChatRequest, BotChatResponse } from '@ov-server/bot/v1/chat'
import type { SessionMemoryDiff } from './memory-diff'
import type { Message, MessagePart } from './types/message'
import type {
AddMessageResult,
CommitSessionResult,
CreateSessionResult,
DeleteSessionResult,
SessionArchiveResult,
SessionContextResult,
SessionListItem,
SessionMeta,
} from '@ov-server/api/v1/sessions'
// ---------------------------------------------------------------------------
// Session CRUD
// ---------------------------------------------------------------------------
export async function fetchSessions(): Promise<SessionListItem[]> {
const result = await getOvResult<SessionListItem[]>(getSessions())
return Array.isArray(result) ? result : []
}
export async function fetchSession(sessionId: string): Promise<SessionMeta> {
return getOvResult<SessionMeta>(
getSessionBySessionId({
path: { session_id: sessionId },
}),
)
}
export async function createSession(
sessionId?: string,
): Promise<CreateSessionResult> {
return getOvResult<CreateSessionResult>(
postSessions({
body: sessionId ? { session_id: sessionId } : undefined,
}),
)
}
export async function fetchSessionContext(
sessionId: string,
tokenBudget?: number,
): Promise<SessionContextResult> {
return getOvResult<SessionContextResult>(
getSessionIdContext({
path: { session_id: sessionId },
query:
tokenBudget === undefined ? undefined : { token_budget: tokenBudget },
}),
)
}
export async function fetchSessionArchive(
sessionId: string,
archiveId: string,
): Promise<SessionArchiveResult> {
return getOvResult<SessionArchiveResult>(
getSessionIdArchiveByArchiveId({
path: { archive_id: archiveId, session_id: sessionId },
}),
)
}
export async function deleteSession(
sessionId: string,
): Promise<DeleteSessionResult> {
return getOvResult<DeleteSessionResult>(
deleteSessionBySessionId({
path: { session_id: sessionId },
}),
)
}
// ---------------------------------------------------------------------------
// Session Messages
// ---------------------------------------------------------------------------
export type SessionHistorySource = 'api' | 'content' | 'none'
async function fetchArchiveFileMessages(
session: SessionMeta,
archiveId: string,
): Promise<Message[]> {
// Use the server's session URI: hosted user space names need not match user IDs.
if (!session.uri) {
throw new OvClientError({
code: 'INVALID_SESSION_ARCHIVE',
message: i18n.t('studio:errors.sessionUriMissing'),
})
}
const result = await getOvResult<unknown>(
getContentRead({
query: {
uri: `${session.uri.replace(/\/+$/, '')}/history/${archiveId}/messages.jsonl`,
offset: 0,
limit: -1,
raw: true,
} as Parameters<typeof getContentRead>[0]['query'] & { raw?: boolean },
}),
)
return parseSessionArchive(result, archiveId)
}
function deduplicateMessages(messages: Message[]): Message[] {
const seen = new Set<string>()
return messages.filter((message) => {
if (seen.has(message.id)) return false
seen.add(message.id)
return true
})
}
const SESSION_ARCHIVE_CONCURRENCY = 4
async function mapWithConcurrency<T, TResult>(
items: T[],
concurrency: number,
mapper: (item: T, index: number) => Promise<TResult>,
): Promise<TResult[]> {
const results = new Array<TResult>(items.length)
let nextIndex = 0
async function worker() {
while (nextIndex < items.length) {
const index = nextIndex
nextIndex += 1
results[index] = await mapper(items[index], index)
}
}
await Promise.all(
Array.from({ length: Math.min(concurrency, items.length) }, () => worker()),
)
return results
}
function isMissingArchive(error: unknown): boolean {
const normalized = normalizeOvClientError(error)
return normalized.statusCode === 404 || normalized.code === 'NOT_FOUND'
}
/**
* Fetch the complete message history.
*
* `/context` only contains messages after the latest completed archive, so
* archived messages must be loaded separately and prepended in archive order.
*/
export async function fetchSessionMessages(
sessionId: string,
sessionMeta?: SessionMeta,
historySource: SessionHistorySource = 'api',
): Promise<Message[]> {
const context = await getOvResult<SessionContextResult>(
getSessionIdContext({
path: { session_id: sessionId },
}),
)
if (historySource === 'none') return parseSessionMessages(context.messages)
let commitCount = 0
let session = sessionMeta
try {
session ??= await fetchSession(sessionId)
commitCount = Math.max(0, Math.floor(session.commit_count || 0))
} catch {
// Older servers may not expose session details. Current context is still
// useful, so preserve the previous behavior as a fallback.
}
const archiveIds = Array.from(
{ length: commitCount },
(_, index) => `archive_${String(index + 1).padStart(3, '0')}`,
)
const archives = await mapWithConcurrency(
archiveIds,
SESSION_ARCHIVE_CONCURRENCY,
async (archiveId) => {
try {
return historySource === 'content'
? await fetchArchiveFileMessages(session!, archiveId)
: parseSessionMessages(
(await fetchSessionArchive(sessionId, archiveId)).messages,
)
} catch (error) {
if (isMissingArchive(error)) return null
throw error
}
},
)
const archivedMessages = archives.flatMap((archive) => archive ?? [])
return deduplicateMessages([
...archivedMessages,
...parseSessionMessages(context.messages),
])
}
// Share four slots across title backfills from both conversation entry points.
let activeTitleRequests = 0
const titleWaiters: Array<() => void> = []
export async function fetchSessionFirstTitle(
sessionId: string,
): Promise<string> {
if (activeTitleRequests >= 4) {
await new Promise<void>((resolve) => titleWaiters.push(resolve))
} else {
activeTitleRequests += 1
}
try {
const session = await fetchSession(sessionId)
const count = Math.max(0, Math.floor(session.commit_count || 0))
for (let index = 1; index <= count; index += 1) {
try {
const archive = await fetchSessionArchive(
sessionId,
`archive_${String(index).padStart(3, '0')}`,
)
const title = firstUserTitle(archive.messages)
if (title) return title
} catch (error) {
if (!isMissingArchive(error)) throw error
}
}
return firstUserTitle((await fetchSessionContext(sessionId)).messages)
} finally {
const next = titleWaiters.shift()
if (next) next()
else activeTitleRequests -= 1
}
}
function firstUserTitle(value: unknown): string {
const first = parseSessionMessages(value).find(
(message) =>
message.role === 'user' &&
message.parts.some((part) => part.type === 'text' && part.text.trim()),
)
return (
first?.parts
.flatMap((part) => (part.type === 'text' ? [part.text] : []))
.join(' ')
.replace(/\s+/g, ' ')
.trim()
.slice(0, 60) || ''
)
}
export async function fetchSessionMemoryDiffs(
session: SessionMeta,
): Promise<SessionMemoryDiff[]> {
const commitCount = Math.max(0, Math.floor(session.commit_count || 0))
if (commitCount === 0) return []
const sessionUri =
session.uri?.replace(/\/+$/, '') ||
`viking://user/${session.user.user_id}/sessions/${session.session_id}`
const archiveIds = Array.from(
{ length: commitCount },
(_, index) => `archive_${String(index + 1).padStart(3, '0')}`,
)
const results = await mapWithConcurrency(
archiveIds,
SESSION_ARCHIVE_CONCURRENCY,
async (archiveId) => {
try {
const result = await getOvResult<unknown>(
getContentRead({
query: {
limit: -1,
offset: 0,
raw: true,
uri: `${sessionUri}/history/${archiveId}/memory_diff.json`,
} as Parameters<typeof getContentRead>[0]['query'] & {
raw?: boolean
},
}),
)
return parseSessionMemoryDiff(result, archiveId)
} catch (error) {
if (isMissingArchive(error)) return null
throw error
}
},
)
return results
.flatMap((result) => (result ? [result] : []))
.sort((left, right) => right.archiveId.localeCompare(left.archiveId))
}
export async function addMessage(
sessionId: string,
role: 'user' | 'assistant',
content?: string,
parts?: Array<Record<string, unknown>>,
): Promise<AddMessageResult> {
return getOvResult<AddMessageResult>(
postSessionIdMessages({
path: { session_id: sessionId },
body: {
role,
content: parts ? undefined : content,
parts: parts ?? undefined,
},
}),
)
}
export async function commitSession(
sessionId: string,
keepRecentCount?: number,
): Promise<CommitSessionResult> {
return getOvResult<CommitSessionResult>(
postSessionIdCommit({
body:
keepRecentCount === undefined
? undefined
: { keep_recent_count: keepRecentCount },
path: { session_id: sessionId },
}),
)
}
export async function fetchSessionToolResults(
sessionId: string,
options: { limit?: number; toolName?: string } = {},
): Promise<unknown> {
const response = await ovClient.instance.get(
`/api/v1/sessions/${encodeURIComponent(sessionId)}/tool-results`,
{
params: {
limit: options.limit,
tool_name: options.toolName || undefined,
},
},
)
return getOvResult<unknown>(Promise.resolve(response))
}
export async function fetchSessionToolResult(
sessionId: string,
toolResultId: string,
options: { includeMetadata?: boolean; limit?: number; offset?: number } = {},
): Promise<unknown> {
const response = await ovClient.instance.get(
`/api/v1/sessions/${encodeURIComponent(sessionId)}/tool-results/${encodeURIComponent(
toolResultId,
)}`,
{
params: {
include_metadata: options.includeMetadata,
limit: options.limit,
offset: options.offset,
},
},
)
return getOvResult<unknown>(Promise.resolve(response))
}
export async function searchSessionToolResult(
sessionId: string,
toolResultId: string,
query: string,
options: { contextChars?: number; limit?: number } = {},
): Promise<unknown> {
const response = await ovClient.instance.get(
`/api/v1/sessions/${encodeURIComponent(sessionId)}/tool-results/${encodeURIComponent(
toolResultId,
)}/search`,
{
params: {
context_chars: options.contextChars,
limit: options.limit,
q: query,
},
},
)
return getOvResult<unknown>(Promise.resolve(response))
}
// ---------------------------------------------------------------------------
// Bot Chat
// ---------------------------------------------------------------------------
function extractErrorMessage(text: string, fallback: string): string {
if (!text.trim()) return fallback
try {
const parsed = JSON.parse(text) as unknown
if (parsed && typeof parsed === 'object') {
const record = parsed as Record<string, unknown>
if (typeof record.detail === 'string') return record.detail
const error = record.error
if (error && typeof error === 'object') {
const message = (error as Record<string, unknown>).message
if (typeof message === 'string') return message
}
}
} catch {
// Fall through to raw text.
}
return text
}
function buildFetchHeaders(): Record<string, string> {
const conn = ovClient.getConnection()
const headers: Record<string, string> = { 'Content-Type': 'application/json' }
const apiKey = conn.apiKey || conn.adminApiKey
if (apiKey) headers['X-API-Key'] = apiKey
if (conn.identityHeaders) {
if (conn.accountId) headers['X-OpenViking-Account'] = conn.accountId
if (conn.userId) headers['X-OpenViking-User'] = conn.userId
}
return headers
}
export async function fetchBotHealth(): Promise<unknown> {
const baseUrl = ovClient.getOptions().baseUrl
const response = await fetch(`${baseUrl}/bot/v1/health`, {
method: 'GET',
headers: buildFetchHeaders(),
})
if (!response.ok) {
const text = await response.text().catch(() => '')
throw new OvClientError({
code: response.status === 503 ? 'BOT_MODE_DISABLED' : 'BOT_HEALTH_FAILED',
message: extractErrorMessage(
text,
i18n.t('studio:errors.botHealth', { status: response.status }),
),
responseBody: text,
statusCode: response.status,
})
}
return response.json().catch(() => ({ status: 'ok' }))
}
/**
* Send a streaming chat request and return standards-compliant SSE messages.
*/
export async function sendChatStream(
request: BotChatRequest,
signal?: AbortSignal,
): Promise<ReturnType<typeof fetchSse>> {
const baseUrl = ovClient.getOptions().baseUrl
const conn = ovClient.getConnection()
return fetchSse(`${baseUrl}/bot/v1/chat/stream`, {
method: 'POST',
headers: {
...buildFetchHeaders(),
Accept: 'text/event-stream',
},
body: JSON.stringify({
...request,
user_id: request.user_id || conn.userId || undefined,
stream: true,
}),
signal,
})
}
/** Send a non-streaming chat request. */
export async function sendChat(
request: BotChatRequest,
): Promise<BotChatResponse> {
const conn = ovClient.getConnection()
const response = await postBotV1Chat({
body: {
...request,
user_id: request.user_id || conn.userId || undefined,
},
throwOnError: true,
} as unknown as NonNullable<Parameters<typeof postBotV1Chat<true>>[0]>)
return response.data as BotChatResponse
}
export type InterruptChatSessionResult = {
interrupted: boolean
}
export type SteerChatSessionResult = {
accepted: boolean
}
export async function steerChatSession(
sessionId: string,
request: BotChatRequest,
): Promise<SteerChatSessionResult> {
const baseUrl = ovClient.getOptions().baseUrl
const conn = ovClient.getConnection()
const response = await fetch(
`${baseUrl}/bot/v1/sessions/${encodeURIComponent(sessionId)}/steer`,
{
method: 'POST',
headers: buildFetchHeaders(),
body: JSON.stringify({
...request,
session_id: sessionId,
user_id: request.user_id || conn.userId || undefined,
}),
},
)
if (!response.ok) {
const text = await response.text().catch(() => '')
throw new OvClientError({
code: 'BOT_STEER_FAILED',
message: extractErrorMessage(
text,
i18n.t('studio:errors.botSteer', { status: response.status }),
),
responseBody: text,
statusCode: response.status,
})
}
return response.json().catch(() => ({ accepted: false }))
}
export async function interruptChatSession(
sessionId: string,
): Promise<InterruptChatSessionResult> {
const baseUrl = ovClient.getOptions().baseUrl
const response = await fetch(
`${baseUrl}/bot/v1/sessions/${encodeURIComponent(sessionId)}/interrupt`,
{
method: 'POST',
headers: buildFetchHeaders(),
},
)
if (!response.ok) {
const text = await response.text().catch(() => '')
throw new OvClientError({
code: 'BOT_INTERRUPT_FAILED',
message: extractErrorMessage(
text,
i18n.t('studio:errors.botInterrupt', { status: response.status }),
),
responseBody: text,
statusCode: response.status,
})
}
return response.json().catch(() => ({ interrupted: false }))
}
// ---------------------------------------------------------------------------
// Part serialization helpers (Message → API request format)
// ---------------------------------------------------------------------------
export function serializeParts(
parts: MessagePart[],
): Array<Record<string, unknown>> {
return parts.flatMap((part) => {
if (part.type === 'text') {
return [{ type: 'text', text: part.text }]
}
if (part.type === 'image_url') {
return [
{
type: 'image_url',
image_url: { ...part.image_url },
},
]
}
if (part.type === 'context') {
return [
{
type: 'context',
uri: part.uri,
context_type: part.context_type,
abstract: part.abstract,
},
]
}
if (
part.type === 'reasoning' ||
part.type === 'iteration' ||
part.type === 'tool_result'
)
return []
// tool
const d: Record<string, unknown> = {
type: 'tool',
tool_id: part.tool_id,
tool_name: part.tool_name,
tool_uri: part.tool_uri,
skill_uri: part.skill_uri,
tool_status: part.tool_status,
}
if (part.tool_input) d.tool_input = part.tool_input
if (part.tool_output) d.tool_output = part.tool_output
if (part.duration_ms != null) d.duration_ms = part.duration_ms
if (part.prompt_tokens != null) d.prompt_tokens = part.prompt_tokens
if (part.completion_tokens != null)
d.completion_tokens = part.completion_tokens
return [d]
})
}