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
// Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
// SPDX-License-Identifier: AGPL-3.0
import { OpenVikingError } from "./errors.js";
import {
nodeImagePathToDataURI,
nodePathToBlob,
packOutputPath,
writeResponseToFile,
} from "./node-files.js";
import { OpenVikingTransport, type TransportOptions } from "./transport.js";
import type {
AddResourceOptions,
AclSpec,
BatchAddMessagesOptions,
BatchWriteOperation,
BatchWriteOptions,
ClientConfig,
CommitSessionOptions,
CompileOptions,
CreateSessionOptions,
ExperienceOutcomeOptions,
ExperienceTrajectoryOptions,
FindOptions,
FindResult,
GitBlob,
GitCommitOptions,
GitRestoreOptions,
JsonObject,
ListPage,
ListOptions,
GetSkillOptions,
GrepOptions,
GlobOptions,
ImportPackOptions,
Message,
ObserverFormat,
PreflightAssetOptions,
ReindexOptions,
RequestOptions,
ResolveAssetsOptions,
SearchContextOptions,
SearchContextResult,
SearchOptions,
SetTagsOptions,
TaskListOptions,
TreeOptions,
TreePage,
UpdateSessionConfigOptions,
UpdateWatchOptions,
WaitOptions,
WriteOptions,
} from "./types.js";
const compact = (value: JsonObject): JsonObject =>
Object.fromEntries(
Object.entries(value).filter(
([, item]) => item !== undefined && item !== null,
),
);
const mergeExtra = (
body: JsonObject,
extra: JsonObject | undefined,
protectedKeys: readonly string[] = [],
): JsonObject => {
const protectedFields = new Set(protectedKeys);
for (const [key, value] of Object.entries(extra ?? {})) {
if (key in body || protectedFields.has(key))
throw new TypeError(`OpenViking: extra cannot override ${key}`);
if (value !== undefined && value !== null) body[key] = value;
}
return body;
};
const pathPart = (value: string): string => encodeURIComponent(value);
/** Normalize a short OpenViking URI to the canonical `viking://` form. */
export const normalizeURI = (uri: string): string =>
uri.startsWith("viking://") ? uri : `viking://${uri.replace(/^\/+/, "")}`;
/** HTTP client for an existing OpenViking server. */
export class OpenVikingClient {
readonly baseUrl: string;
private readonly transport: OpenVikingTransport;
/** Create a client with explicit connection and identity configuration. */
constructor(config: ClientConfig) {
this.transport = new OpenVikingTransport(config);
this.baseUrl = this.transport.baseUrl;
}
private request<T>(
method: string,
path: string,
options: TransportOptions = {},
): Promise<T> {
return this.transport.request<T>(method, path, options);
}
private async upload(file: Blob, filename = "upload"): Promise<string> {
const form = new FormData();
form.set("file", file, filename);
if (this.transport.uploadMode)
form.set("upload_mode", this.transport.uploadMode);
const result = await this.request<{ temp_file_id: string }>(
"POST",
"/api/v1/resources/temp_upload",
{ form },
);
if (!result?.temp_file_id)
throw new OpenVikingError(
"Upload response did not include temp_file_id",
{ code: "INTERNAL" },
);
return result.temp_file_id;
}
private async downloadToFile(
path: string,
body: JsonObject,
output: string,
signal?: AbortSignal,
): Promise<string> {
return this.transport.consume(
"POST",
path,
{ body, ...(signal ? { signal } : {}) },
async (response) => {
if (
!response.ok ||
response.headers.get("content-type")?.includes("json")
)
return this.transport.parseResponse<never>(response);
return writeResponseToFile(response, output);
},
);
}
/** Add a remote URL or Node.js local file/directory as a resource. */
async addResource(
source: string,
options: AddResourceOptions = {},
): Promise<JsonObject> {
if (options.to && options.parent)
throw new TypeError("OpenViking: cannot specify both to and parent");
const body: JsonObject = compact({
to: options.to,
parent: options.parent,
create_parent: options.createParent,
reason: options.reason,
instruction: options.instruction,
wait: options.wait,
strict: options.strict,
ignore_dirs: options.ignoreDirs,
include: options.include,
exclude: options.exclude,
directly_upload_media: options.directlyUploadMedia,
preserve_structure: options.preserveStructure,
watch_interval: options.watchInterval,
processing_mode: options.processingMode,
args:
options.args && Object.keys(options.args).length
? options.args
: undefined,
tags: options.tags,
acl: options.acl,
tag_mode:
options.tags !== undefined || options.tagMode === "clear"
? (options.tagMode ?? "replace")
: undefined,
telemetry: options.telemetry,
});
const local = await nodePathToBlob(source);
if (local) {
body.temp_file_id = await this.upload(local.blob, local.filename);
body.source_name = local.sourceName;
} else body.path = source;
return this.request("POST", "/api/v1/resources", {
body: mergeExtra(body, options.extra),
});
}
/** Install a skill from inline data or an existing Node.js path. */
async addSkill(
source: unknown,
options: WaitOptions & { targetUri?: string; extra?: JsonObject } = {},
): Promise<JsonObject> {
const body: JsonObject = compact({
wait: options.wait ?? false,
telemetry: options.telemetry,
target_uri: options.targetUri,
});
const local =
typeof source === "string"
? await nodePathToBlob(source, { allowInlineContent: true })
: undefined;
if (local)
body.temp_file_id = await this.upload(local.blob, local.filename);
else body.data = source;
return this.request("POST", "/api/v1/skills", {
body: mergeExtra(body, options.extra),
});
}
/** List installed skills. */
listSkills(
options: { nodeLimit?: number; targetUri?: string } = {},
): Promise<JsonObject> {
return this.request("GET", "/api/v1/skills", {
query: {
node_limit: options.nodeLimit ?? 1000,
target_uri: options.targetUri,
},
});
}
/** Search installed skills semantically. */
findSkills(
query: string,
options: {
limit?: number;
scoreThreshold?: number;
level?: number[];
targetUri?: string;
telemetry?: unknown;
} = {},
): Promise<JsonObject> {
return this.request("POST", "/api/v1/skills/find", {
body: compact({
query,
limit: options.limit ?? 10,
score_threshold: options.scoreThreshold,
level: options.level,
target_uri: options.targetUri,
telemetry: options.telemetry,
}),
});
}
/** Validate skill data without installing it. */
validateSkill(
data: unknown,
options: {
strict?: boolean;
sourcePath?: string;
skillDirName?: string;
targetUri?: string;
} = {},
): Promise<JsonObject> {
return this.request("POST", "/api/v1/skills/validate", {
body: compact({
data,
strict: options.strict ?? false,
source_path: options.sourcePath,
skill_dir_name: options.skillDirName,
target_uri: options.targetUri,
}),
});
}
/** Get an installed skill. */
getSkill(name: string, options: GetSkillOptions = {}): Promise<JsonObject> {
return this.request("GET", `/api/v1/skills/${pathPart(name)}`, {
query: {
include_content: options.includeContent,
include_files: options.includeFiles ?? true,
include_source: options.includeSource ?? false,
level: options.level,
target_uri: options.targetUri,
},
});
}
/** Replace an installed skill. */
async updateSkill(
name: string,
source: unknown,
options: WaitOptions & {
sourceMetadata?: JsonObject;
targetUri?: string;
extra?: JsonObject;
} = {},
): Promise<JsonObject> {
const body: JsonObject = compact({
wait: options.wait ?? false,
source_metadata: options.sourceMetadata,
target_uri: options.targetUri,
telemetry: options.telemetry,
});
const local =
typeof source === "string"
? await nodePathToBlob(source, { allowInlineContent: true })
: undefined;
if (local)
body.temp_file_id = await this.upload(local.blob, local.filename);
else body.data = source;
return this.request("PUT", `/api/v1/skills/${pathPart(name)}`, {
body: mergeExtra(body, options.extra),
});
}
/** Delete an installed skill. */
deleteSkill(name: string, targetUri?: string): Promise<JsonObject> {
return this.request("DELETE", `/api/v1/skills/${pathPart(name)}`, {
query: { target_uri: targetUri },
});
}
/** List resource watches. */
listWatches(
options: { activeOnly?: boolean; toUri?: string } = {},
): Promise<JsonObject> {
return this.request("GET", "/api/v1/watches", {
query: {
active_only: options.activeOnly ?? false,
to_uri: options.toUri ? normalizeURI(options.toUri) : undefined,
},
});
}
/** Get a watch by task ID. */
getWatch(taskId: string, toUri?: string): Promise<JsonObject> {
return this.request("GET", `/api/v1/watches/${pathPart(taskId)}`, {
query: { to_uri: toUri ? normalizeURI(toUri) : undefined },
});
}
/** Partially update a watch. */
updateWatch(
ref: { taskId?: string; toUri?: string },
changes: UpdateWatchOptions,
): Promise<JsonObject> {
if (!ref.taskId && !ref.toUri) {
throw new TypeError("OpenViking: watch reference is required");
}
return this.request(
"PATCH",
ref.taskId
? `/api/v1/watches/${pathPart(ref.taskId)}`
: "/api/v1/watches",
{
query: { to_uri: ref.toUri ? normalizeURI(ref.toUri) : undefined },
body: compact({
watch_interval: changes.watchInterval,
is_active: changes.isActive,
reason: changes.reason,
instruction: changes.instruction,
}),
},
);
}
/** Delete a watch. */
deleteWatch(ref: { taskId?: string; toUri?: string }): Promise<JsonObject> {
if (!ref.taskId && !ref.toUri)
throw new TypeError("OpenViking: watch reference is required");
return this.request(
"DELETE",
ref.taskId
? `/api/v1/watches/${pathPart(ref.taskId)}`
: "/api/v1/watches",
{ query: { to_uri: ref.toUri ? normalizeURI(ref.toUri) : undefined } },
);
}
/** Trigger a watch immediately. */
triggerWatch(ref: { taskId?: string; toUri?: string }): Promise<JsonObject> {
if (!ref.taskId && !ref.toUri)
throw new TypeError("OpenViking: watch reference is required");
return this.request(
"POST",
ref.taskId
? `/api/v1/watches/${pathPart(ref.taskId)}/trigger`
: "/api/v1/watches/trigger",
{ query: { to_uri: ref.toUri ? normalizeURI(ref.toUri) : undefined } },
);
}
/** Find relevant content without session context. */
async find(query: string, options: FindOptions = {}): Promise<FindResult> {
return this.searchRequest("find", query, options);
}
/** Search relevant content with optional session context. */
async search(
query: string,
options: SearchOptions = {},
): Promise<FindResult> {
return this.searchRequest("search", query, options);
}
private async searchRequest(
kind: "find" | "search",
query: string,
options: FindOptions | SearchOptions,
): Promise<FindResult> {
let imageUrl: string | undefined;
if (typeof options.image === "string") {
imageUrl = (await nodeImagePathToDataURI(options.image)) ?? options.image;
}
const body = compact({
query,
target_uri: options.targetUri,
image_url: imageUrl,
session_id:
kind === "search" ? (options as SearchOptions).sessionId : undefined,
events_time_decay_protection: options.eventsTimeDecayProtection,
search_type:
kind === "search" ? (options as SearchOptions).searchType : undefined,
limit: options.limit,
node_limit: options.nodeLimit,
score_threshold: options.scoreThreshold,
filter: options.filter,
context_type: options.contextType,
telemetry: options.telemetry,
since: options.since,
until: options.until,
time_field: options.timeField,
level: options.level,
tags: options.tags,
include_provenance: options.includeProvenance,
read_content: options.readContent,
});
return this.request("POST", `/api/v1/search/${kind}`, {
body: mergeExtra(body, options.extra),
});
}
/** Assemble injection-ready context on the server. */
async searchContext(
query: string,
options: SearchContextOptions = {},
): Promise<SearchContextResult> {
let imageUrl: string | undefined;
if (typeof options.image === "string")
imageUrl = (await nodeImagePathToDataURI(options.image)) ?? options.image;
const body = compact({
query,
mode: "context",
search_type: options.searchType,
image_url: imageUrl,
session_id: options.sessionId,
limit: options.limit,
node_limit: options.nodeLimit,
score_threshold: options.scoreThreshold,
filter: options.filter,
context_type: options.contextType,
include_provenance: options.includeProvenance,
tags: options.tags,
since: options.since,
until: options.until,
time_field: options.timeField,
events_time_decay_protection: options.eventsTimeDecayProtection,
query_expansion: options.queryExpansion,
max_tokens: options.maxTokens,
quotas: options.quotas,
purpose: options.purpose,
detail: options.detail,
dedup_turns: options.dedupTurns,
exclude_uris: options.excludeUris,
peer_scope: options.peerScope,
other_peer_penalty: options.otherPeerPenalty,
rewrite: options.rewrite,
rewrite_max_bullets: options.rewriteMaxBullets,
telemetry: options.telemetry,
});
return this.request("POST", "/api/v1/search/search", {
body: mergeExtra(body, options.extra),
});
}
/** Search file contents by pattern. */
grep(
uri: string,
pattern: string,
options: GrepOptions = {},
): Promise<JsonObject> {
return this.request("POST", "/api/v1/search/grep", {
body: compact({
uri: normalizeURI(uri),
pattern,
case_insensitive: options.caseInsensitive ?? false,
node_limit: options.nodeLimit ?? 256,
level_limit: options.levelLimit,
exclude_uri: options.excludeUri
? normalizeURI(options.excludeUri)
: undefined,
tags: options.tags,
include_tags: options.includeTags || undefined,
}),
});
}
/** Find files by glob pattern. */
glob(
pattern: string,
uri = "viking://",
options: GlobOptions | number = {},
): Promise<JsonObject> {
const resolvedOptions: GlobOptions =
typeof options === "number" ? { nodeLimit: options } : options;
return this.request("POST", "/api/v1/search/glob", {
body: compact({
pattern,
uri: normalizeURI(uri),
node_limit: resolvedOptions.nodeLimit ?? 256,
tags: resolvedOptions.tags,
include_tags: resolvedOptions.includeTags || undefined,
}),
});
}
/** List directory contents. */
async list(uri: string, options: ListOptions = {}): Promise<unknown[]> {
return (await this.listPage(uri, options)).result;
}
/** List directory contents with pagination metadata. */
async listPage(uri: string, options: ListOptions = {}): Promise<ListPage> {
const envelope = await this.transport.requestEnvelope<unknown[]>(
"GET",
"/api/v1/fs/ls",
{
query: {
uri: normalizeURI(uri),
simple: options.simple ?? false,
recursive: options.recursive ?? false,
output: options.output ?? "original",
abs_limit: options.absLimit ?? 256,
include_abstract: options.includeAbstract,
include_overview: options.includeOverview,
overview_limit: options.overviewLimit ?? 4000,
show_all_hidden: options.showAllHidden ?? false,
node_limit: options.nodeLimit ?? 1000,
offset: options.offset,
limit: options.limit,
sort_by: options.sortBy,
sort_order: options.sortOrder,
extra_fields: options.extraFields,
tags: options.tags,
include_tags: options.includeTags || undefined,
},
},
);
return {
result: envelope.result ?? [],
hasMore: envelope.has_more ?? false,
};
}
/** Return a directory tree. */
async tree(uri: string, options: TreeOptions = {}): Promise<JsonObject[]> {
return (await this.treePage(uri, options)).result;
}
/** Return a directory tree with pagination metadata. */
async treePage(uri: string, options: TreeOptions = {}): Promise<TreePage> {
const envelope = await this.transport.requestEnvelope<JsonObject[]>(
"GET",
"/api/v1/fs/tree",
{
query: {
uri: normalizeURI(uri),
output: options.output ?? "original",
abs_limit: options.absLimit ?? 128,
include_abstract: options.includeAbstract,
include_overview: options.includeOverview,
overview_limit: options.overviewLimit ?? 4000,
show_all_hidden: options.showAllHidden ?? false,
directories_only: options.directoriesOnly || undefined,
node_limit: options.nodeLimit ?? 1000,
level_limit: options.levelLimit ?? 3,
offset: options.offset,
limit: options.limit,
extra_fields: options.extraFields,
tags: options.tags,
include_tags: options.includeTags || undefined,
},
},
);
return {
result: envelope.result ?? [],
hasMore: envelope.has_more ?? false,
};
}
/** Return URI metadata. */
stat(uri: string): Promise<JsonObject> {
return this.request("GET", "/api/v1/fs/stat", {
query: { uri: normalizeURI(uri) },
});
}
/** Return URI logical attributes. */
attrs(uri: string): Promise<JsonObject> {
return this.request("GET", "/api/v1/fs/attrs", {
query: { uri: normalizeURI(uri) },
});
}
/** Create a directory. */
mkdir(uri: string, description?: string, acl?: AclSpec): Promise<void> {
return this.request("POST", "/api/v1/fs/mkdir", {
body: compact({ uri: normalizeURI(uri), description, acl }),
});
}
aclGet(uri: string): Promise<JsonObject> {
return this.request("GET", "/api/v1/acl", {
query: { uri: normalizeURI(uri) },
});
}
aclSet(uri: string, acl: AclSpec): Promise<JsonObject> {
return this.request("PUT", "/api/v1/acl", {
body: { uri: normalizeURI(uri), ...acl },
});
}
aclGrant(
uri: string,
principal: string,
level: "read" | "write" | "manage",
): Promise<JsonObject> {
return this.request("POST", "/api/v1/acl/grant", {
body: { uri: normalizeURI(uri), principal, level },
});
}
aclRevoke(uri: string, principal: string): Promise<JsonObject> {
return this.request("POST", "/api/v1/acl/revoke", {
body: { uri: normalizeURI(uri), principal },
});
}
aclDelete(uri: string): Promise<JsonObject> {
return this.request("DELETE", "/api/v1/acl", {
query: { uri: normalizeURI(uri) },
});
}
/** Remove a resource or directory. */
remove(
uri: string,
options: {
recursive?: boolean;
wait?: boolean;
/** @deprecated Accepted for compatibility and ignored. */
timeout?: number;
} = {},
): Promise<void> {
return this.request("DELETE", "/api/v1/fs", {
query: {
uri: normalizeURI(uri),
recursive: options.recursive ?? false,
wait: options.wait ?? false,
},
});
}
/** Move a URI. */
move(fromUri: string, toUri: string): Promise<void> {
return this.request("POST", "/api/v1/fs/mv", {
body: { from_uri: normalizeURI(fromUri), to_uri: normalizeURI(toUri) },
});
}
/** Read text content. */
read(uri: string, offset = 0, limit = -1): Promise<string> {
return this.request("GET", "/api/v1/content/read", {
query: { uri: normalizeURI(uri), offset, limit },
});
}
/** Download raw stored bytes. */
downloadBytes(uri: string): Promise<Uint8Array> {
return this.transport.consume(
"GET",
"/api/v1/content/download",
{ query: { uri: normalizeURI(uri) } },
async (response) => {
if (
!response.ok ||
response.headers.get("content-type")?.includes("json")
)
return this.transport.parseResponse<never>(response);
return new Uint8Array(await response.arrayBuffer());
},
);
}
/** Read L0 abstract content. */
abstract(uri: string): Promise<string> {
return this.request("GET", "/api/v1/content/abstract", {
query: { uri: normalizeURI(uri) },
});
}
/** Read L1 overview content. */
overview(uri: string): Promise<string> {
return this.request("GET", "/api/v1/content/overview", {
query: { uri: normalizeURI(uri) },
});
}
/** Write text content, including an empty string used to clear a file. */
write(
uri: string,
content: string,
options: WriteOptions = {},
): Promise<JsonObject> {
const body = compact({
uri: normalizeURI(uri),
content,
mode: options.mode,
processing_mode: options.processingMode,
tags: options.tags,
acl: options.acl,
tag_mode:
options.tags !== undefined || options.tagMode === "clear"
? (options.tagMode ?? "replace")
: undefined,
wait: options.wait,
telemetry: options.telemetry,
});
return this.request("POST", "/api/v1/content/write", {
body: mergeExtra(body, options.extra),
});
}
/** Apply file writes in one request and refresh their indexes once. */
batchWrite(
rootUri: string,
operations: BatchWriteOperation[],
options: BatchWriteOptions = {},
): Promise<JsonObject> {
const body = compact({
root_uri: normalizeURI(rootUri),
operations: operations.map((operation) =>
compact({
uri: normalizeURI(operation.uri),
content: operation.content,
content_base64: operation.contentBase64,
mode: operation.mode,
tags: operation.tags,
tag_mode: operation.tagMode,
acl: operation.acl,
}),
),
wait: options.wait,
telemetry: options.telemetry,
processing_mode: options.processingMode,
defer_processing: options.deferProcessing,
});
return this.request("POST", "/api/v1/content/batch-write", {
body: mergeExtra(body, options.extra),
});
}
/** Set retrieval tags. */
setTags(
uri: string,
tags?: string[],
options: SetTagsOptions = {},
): Promise<JsonObject> {
const body = compact({
uri: normalizeURI(uri),
tags,
mode: options.mode ?? "replace",
recursive: options.recursive ?? false,
telemetry: options.telemetry,
});
return this.request("POST", "/api/v1/fs/attrs/set_tags", {
body: mergeExtra(body, options.extra, [
"uri",
"tags",
"mode",
"recursive",
"telemetry",
]),
});
}
/** Rebuild indexes for a URI. */
reindex(uri: string, options: ReindexOptions = {}): Promise<JsonObject> {
const body = compact({
uri: normalizeURI(uri),
mode: options.mode ?? "vectors_only",
wait: options.wait ?? true,
force: options.force || undefined,
recursive: options.recursive ?? true,
tags: options.tags,
tag_mode:
options.tags !== undefined || options.tagMode === "clear"
? (options.tagMode ?? "replace")
: undefined,
});
return this.request("POST", "/api/v1/content/reindex", {
body: mergeExtra(body, options.extra, ["force", "tags", "tag_mode"]),
});
}
/** Create a session. */
createSession(options: CreateSessionOptions = {}): Promise<JsonObject> {
const body = compact({
session_id: options.sessionId,
memory_policy: options.memoryPolicy,
memory_extraction_config: options.memoryExtractionConfig,
telemetry: options.telemetry,
});
if ("autoCommitPolicy" in options)
body.auto_commit_policy = options.autoCommitPolicy ?? null;
return this.request("POST", "/api/v1/sessions", {
body: mergeExtra(body, options.extra),
});
}
/** List sessions visible to the caller. */
listSessions(): Promise<unknown[]> {
return this.request("GET", "/api/v1/sessions");
}
/** Get one session. */
getSession(sessionId: string, autoCreate = false): Promise<JsonObject> {
return this.request("GET", `/api/v1/sessions/${pathPart(sessionId)}`, {
query: { auto_create: autoCreate || undefined },
});
}
/** Update mutable session memory extraction settings. */
updateSessionConfig(
sessionId: string,
options: UpdateSessionConfigOptions,
): Promise<JsonObject> {
const body = compact({
memory_extraction_config: options.memoryExtractionConfig,
telemetry: options.telemetry,
});
if ("autoCommitPolicy" in options)
body.auto_commit_policy = options.autoCommitPolicy ?? null;
return this.request(
"PATCH",
`/api/v1/sessions/${pathPart(sessionId)}/config`,
{
body: mergeExtra(body, options.extra),
},
);
}
/** Test whether a session exists. */
async sessionExists(sessionId: string): Promise<boolean> {
try {
await this.getSession(sessionId);
return true;
} catch (error) {
if (error instanceof OpenVikingError && error.code === "NOT_FOUND")
return false;
throw error;
}
}
/** Delete a session. */
deleteSession(sessionId: string): Promise<void> {
return this.request("DELETE", `/api/v1/sessions/${pathPart(sessionId)}`);
}
/** Assemble session context within a token budget. */
getSessionContext(
sessionId: string,
tokenBudget = 128_000,
): Promise<JsonObject> {
return this.request(
"GET",
`/api/v1/sessions/${pathPart(sessionId)}/context`,
{ query: { token_budget: tokenBudget } },
);
}
/** Get a committed session archive. */
getSessionArchive(sessionId: string, archiveId: string): Promise<JsonObject> {
return this.request(
"GET",
`/api/v1/sessions/${pathPart(sessionId)}/archives/${pathPart(archiveId)}`,
);
}
/** Append one message to a session. */
addMessage(sessionId: string, message: Message): Promise<JsonObject> {
if (message.content === undefined && !message.parts?.length) {
throw new TypeError("OpenViking: message requires content or parts");
}
const content = message.parts?.length ? undefined : message.content;
return this.request(
"POST",
`/api/v1/sessions/${pathPart(sessionId)}/messages`,
{
body: compact({
role: message.role,
content,
parts: message.parts?.length ? message.parts : undefined,
created_at: message.createdAt,
peer_id: message.peerId,
turn_id: message.turnId,
message_kind: message.messageKind,
source_message_ids: message.sourceMessageIds,
telemetry: message.telemetry,
}),
},
);
}
/** Append multiple messages to a session. */
batchAddMessages(
sessionId: string,
messages: Message[],
telemetry?: unknown,
): Promise<JsonObject>;
batchAddMessages(
sessionId: string,
messages: Message[],
options?: BatchAddMessagesOptions,
): Promise<JsonObject> {
const normalizedOptions =
options !== null &&
typeof options === "object" &&
("telemetry" in options || "extra" in options)
? options
: { telemetry: options };
return this.request(
"POST",
`/api/v1/sessions/${pathPart(sessionId)}/messages/batch`,
{
body: mergeExtra(
compact({
messages: messages.map((message) => {
if (message.content === undefined && !message.parts?.length) {
throw new TypeError(
"OpenViking: each message requires content or parts",
);
}
const parts = message.parts?.length ? message.parts : undefined;
return compact({
role: message.role,
content: parts ? undefined : message.content,
parts,
created_at: message.createdAt,
peer_id: message.peerId,
turn_id: message.turnId,
message_kind: message.messageKind,
source_message_ids: message.sourceMessageIds,
});
}),
telemetry: normalizedOptions.telemetry,
}),
normalizedOptions.extra,
),
},
);
}
/** Commit a session and extract memories. */
commitSession(
sessionId: string,
keepRecentCount?: number,
telemetry?: unknown,
eventTags?: string[],
): Promise<JsonObject>;
commitSession(
sessionId: string,
options?: CommitSessionOptions,
): Promise<JsonObject>;
commitSession(
sessionId: string,
optionsOrKeepRecentCount: CommitSessionOptions | number = {},
telemetry?: unknown,
eventTags?: string[],
): Promise<JsonObject> {
let options: CommitSessionOptions;
if (typeof optionsOrKeepRecentCount === "number") {
options = { keepRecentCount: optionsOrKeepRecentCount };
if (telemetry !== undefined) options.telemetry = telemetry;
if (eventTags !== undefined) options.eventTags = eventTags;
} else {
options = optionsOrKeepRecentCount;
}
const body = compact({
enable_working_memory: options.enableWorkingMemory,
keep_recent_count: options.keepRecentCount,
retention_mode: options.retentionMode,
keep_recent_turn_count: options.keepRecentTurnCount,
retained_message_token_budget: options.retainedMessageTokenBudget,
min_raw_tail_steps: options.minRawTailSteps,
extraction_metadata:
options.eventTags === undefined
? undefined
: { event: { tags: options.eventTags } },
telemetry: options.telemetry,
});
return this.request(
"POST",
`/api/v1/sessions/${pathPart(sessionId)}/commit`,
{ body: mergeExtra(body, options.extra) },
);
}
/** Export a resource subtree to a local OVPack file. */
async exportOVPack(
uri: string,
to: string,
includeVectors = false,
options: RequestOptions = {},
): Promise<string> {
const output = await packOutputPath(to, uri, "export");
return this.downloadToFile(
"/api/v1/pack/export",
{ uri: normalizeURI(uri), include_vectors: includeVectors },
output,
options.signal,
);
}
/** Back up public scopes to a local restore-only OVPack file. */
async backupOVPack(
to: string,
includeVectors = false,
options: RequestOptions = {},
): Promise<string> {
const output = await packOutputPath(to, undefined, "openviking-backup");
return this.downloadToFile(
"/api/v1/pack/backup",
{ include_vectors: includeVectors },
output,
options.signal,
);
}
/** Import a local OVPack file under a parent URI. */
async importOVPack(
source: string,
parent: string,
options: ImportPackOptions = {},
): Promise<string> {
const local = await nodePathToBlob(source, { allowDirectory: false });
if (!local)
throw new TypeError(
"OpenViking: importOVPack requires an existing Node.js local file",
);
const result = await this.request<{ uri: string }>(
"POST",
"/api/v1/pack/import",
{
body: compact({
parent: normalizeURI(parent),
temp_file_id: await this.upload(local.blob, local.filename),
on_conflict: options.onConflict,
vector_mode: options.vectorMode,
}),
},
);
return result.uri;
}
/** Restore a local OVPack backup file. */
async restoreOVPack(
source: string,
options: ImportPackOptions = {},
): Promise<string> {
const local = await nodePathToBlob(source, { allowDirectory: false });
if (!local)
throw new TypeError(
"OpenViking: restoreOVPack requires an existing Node.js local file",
);
const result = await this.request<{ uri: string }>(
"POST",
"/api/v1/pack/restore",
{
body: compact({
temp_file_id: await this.upload(local.blob, local.filename),
on_conflict: options.onConflict,
vector_mode: options.vectorMode,
}),
},
);
return result.uri;
}
/** Start an asynchronous Compile task. */
compile(
fromUris: string[],
to: string,
skill: string,
options: CompileOptions = {},
): Promise<JsonObject> {
const body = compact({
from: fromUris,
to,
skill,
instruction: options.instruction,
args:
options.args && Object.keys(options.args).length
? options.args
: undefined,
});
return this.request("POST", "/api/v1/compile", {
body: mergeExtra(body, options.extra, ["instruction", "args"]),
});
}
/** Get a background task. */
async getTask(taskId: string): Promise<JsonObject | null> {
try {
return await this.request("GET", `/api/v1/tasks/${pathPart(taskId)}`);
} catch (error) {
if (
error instanceof OpenVikingError &&
(error.code === "NOT_FOUND" || error.statusCode === 404)
) {
return null;
}
throw error;
}
}
cancelTask(taskId: string): Promise<JsonObject> {
return this.request(
"POST",
`/api/v1/tasks/${pathPart(taskId)}/cancel`,
) as Promise<JsonObject>;
}
/** List background tasks. */
listTasks(options: TaskListOptions = {}): Promise<unknown[]> {
return this.request("GET", "/api/v1/tasks", {
query: {
task_type: options.taskType,
status: options.status,
resource_id: options.resourceId,
limit: options.limit,
},
});
}
/**
* Wait for queued processing to finish.
* @param timeout - Deprecated. Accepted for compatibility and ignored.
*/
waitProcessed(timeout?: number): Promise<JsonObject> {
return this.request("POST", "/api/v1/system/wait", {
body: {},
});
}
/** Check the raw server health endpoint. */
async health(options: RequestOptions = {}): Promise<boolean> {
return this.transport.consume(
"GET",
"/health",
options,
async (response) =>
response.ok &&
((await response.json()) as { status?: string }).status === "ok",
);
}
/** Check filesystem/index consistency. */
checkConsistency(uri: string): Promise<JsonObject> {
return this.request("POST", "/api/v1/system/consistency", {
body: { uri: normalizeURI(uri) },
});
}
/** Return aggregate observer status. */
getStatus(format?: ObserverFormat): Promise<JsonObject> {
return this.request("GET", "/api/v1/observer/system", {
query: { format },
});
}
/** Return queue observer status. */
queueStatus(format?: ObserverFormat): Promise<JsonObject> {
return this.request("GET", "/api/v1/observer/queue", {
query: { format },
});
}
/** Return VikingDB observer status. */
vikingDBStatus(format?: ObserverFormat): Promise<JsonObject> {
return this.request("GET", "/api/v1/observer/vikingdb", {
query: { format },
});
}
/** Return model observer status. */
modelsStatus(format?: ObserverFormat): Promise<JsonObject> {
return this.request("GET", "/api/v1/observer/models", {
query: { format },
});
}
/** Return whether the observer system reports healthy. */
async isHealthy(): Promise<boolean> {
return (await this.getStatus()).is_healthy === true;
}
/** Create a filesystem snapshot. */
gitCommit(options: GitCommitOptions): Promise<JsonObject> {
return this.request("POST", "/api/v1/snapshot/commit", {
body: compact({
message: options.message,
paths: options.paths,
branch: options.branch ?? "main",
author_name: options.authorName,
author_email: options.authorEmail,
}),
});
}
/** Restore filesystem content from a previous snapshot. */
gitRestore(options: GitRestoreOptions): Promise<JsonObject> {
return this.request("POST", "/api/v1/snapshot/restore", {
body: compact({
project_dir: options.projectDir,
source_commit: options.sourceCommit,
branch: options.branch ?? "main",
dry_run: options.dryRun ?? false,
message: options.message,
author_name: options.authorName,
author_email: options.authorEmail,
}),
});
}
/** Return snapshot metadata or a raw file from a snapshot. */
gitShow(targetRef: string, path?: string): Promise<JsonObject | GitBlob> {
return this.transport.consume(
"GET",
"/api/v1/snapshot/show",
{ query: { target_ref: targetRef, path } },
async (response) => {
if (
response.ok &&
response.headers
.get("content-type")
?.startsWith("application/octet-stream")
) {
const bytes = new Uint8Array(await response.arrayBuffer());
return {
oid: response.headers.get("x-snapshot-oid") ?? "",
size: Number(
response.headers.get("x-snapshot-size") ?? bytes.length,
),
bytes,
};
}
return this.transport.parseResponse<JsonObject>(response);
},
);
}
/** Return snapshot history from newest to oldest. */
gitLog(branch = "main", limit = 20, paths?: string[]): Promise<JsonObject[]> {
return this.request("GET", "/api/v1/snapshot/log", {
query: { branch, limit, paths },
});
}
/** Compare one file between two snapshot refs. */
gitDiff(path: string, toRef: string, fromRef?: string): Promise<JsonObject> {
return this.request("GET", "/api/v1/snapshot/diff", {
query: {
path: normalizeURI(path),
from: fromRef,
to: toRef,
},
});
}
/** Return the account `.ovgitignore` content. */
async gitGetIgnore(): Promise<string> {
const result = await this.request<unknown>(
"GET",
"/api/v1/snapshot/ignore",
);
return typeof result === "string" ? result : "";
}
/** Set the account `.ovgitignore` content. */
async gitSetIgnore(content: string): Promise<void> {
await this.request("PUT", "/api/v1/snapshot/ignore", {
body: { content },
});
}
/** Delete the account `.ovgitignore` file. */
async gitDeleteIgnore(): Promise<void> {
await this.request("DELETE", "/api/v1/snapshot/ignore");
}
/** Create a tenant account and its first administrator. */
adminCreateAccount(
accountId: string,
adminUserId: string,
options: { userConfig?: JsonObject; seed?: string } = {},
): Promise<JsonObject> {
return this.request("POST", "/api/v1/admin/accounts", {
body: compact({
account_id: accountId,
admin_user_id: adminUserId,
user_config: options.userConfig,
seed: options.seed,
}),
});
}
/** List tenant accounts, in creation order. `name` supports wildcard (* and ?) matching. */
adminListAccounts(
options: { name?: string; limit?: number; page?: number } = {},
): Promise<unknown[]> {
return this.request("GET", "/api/v1/admin/accounts", {
query: {
name: options.name,
limit: options.limit,
page: options.limit !== undefined ? (options.page ?? 1) : undefined,
},
});
}
/** Delete a tenant account. */
adminDeleteAccount(accountId: string): Promise<JsonObject> {
return this.request(
"DELETE",
`/api/v1/admin/accounts/${pathPart(accountId)}`,
);
}
/** Return credential-free metadata for one account; rejects with NOT_FOUND if absent. */
adminGetAccount(accountId: string): Promise<JsonObject> {
return this.request("GET", `/api/v1/admin/accounts/${pathPart(accountId)}`);
}
/** Register a user in an account. */
adminRegisterUser(
accountId: string,
userId: string,
role: string,
options: { userConfig?: JsonObject; seed?: string } = {},
): Promise<JsonObject> {
return this.request(
"POST",
`/api/v1/admin/accounts/${pathPart(accountId)}/users`,
{
body: compact({
user_id: userId,
role,
user_config: options.userConfig,
seed: options.seed,
}),
},
);
}
/** List users in an account, in creation order. `name` supports wildcard (* and ?) matching. */
adminListUsers(
accountId: string,
options: {
limit?: number;
name?: string;
role?: string;
page?: number;
} = {},
): Promise<unknown[]> {
return this.request(
"GET",
`/api/v1/admin/accounts/${pathPart(accountId)}/users`,
{
query: {
limit: options.limit,
name: options.name,
role: options.role,
page: options.limit !== undefined ? (options.page ?? 1) : undefined,
},
},
);
}
/** Remove a user from an account. */
adminRemoveUser(accountId: string, userId: string): Promise<JsonObject> {
return this.request(
"DELETE",
`/api/v1/admin/accounts/${pathPart(accountId)}/users/${pathPart(userId)}`,
);
}
/** One user's credential-free membership info (user_id, role); rejects NOT_FOUND if absent. Never returns api_key/key_prefix. */
adminGetUser(accountId: string, userId: string): Promise<JsonObject> {
return this.request(
"GET",
`/api/v1/admin/accounts/${pathPart(accountId)}/users/${pathPart(userId)}`,
);
}
/** Change a user's role. */
adminSetRole(
accountId: string,
userId: string,
role: string,
): Promise<JsonObject> {
return this.request(
"PUT",
`/api/v1/admin/accounts/${pathPart(accountId)}/users/${pathPart(userId)}/role`,
{ body: { role } },
);
}
/** Regenerate a user's API key. */
adminRegenerateKey(
accountId: string,
userId: string,
seed?: string,
): Promise<JsonObject> {
return this.request(
"POST",
`/api/v1/admin/accounts/${pathPart(accountId)}/users/${pathPart(userId)}/key`,
{ body: seed === undefined ? undefined : { seed } },
);
}
/** Return the effective Agent Evolution switch for the caller's account. */
adminGetAgentEvolution(): Promise<JsonObject> {
return this.request("GET", "/api/v1/admin/agent-evolution");
}
/** Persist and hot-reload Agent Evolution for the caller's account. */
adminSetAgentEvolution(enabled: boolean): Promise<JsonObject> {
return this.request("PUT", "/api/v1/admin/agent-evolution", {
body: { enabled },
});
}
/** Return effective and explicitly overridden settings for one account. */
adminGetAccountSettings(accountId: string): Promise<JsonObject> {
return this.request(
"GET",
`/api/v1/admin/accounts/${pathPart(accountId)}/settings`,
);
}
/** Update the allowlisted Agent Evolution setting for one account. */
adminSetAccountAgentEvolution(
accountId: string,
enabled: boolean,
): Promise<JsonObject> {
return this.request(
"PATCH",
`/api/v1/admin/accounts/${pathPart(accountId)}/settings`,
{ body: { agent_evolution: { enabled } } },
);
}
/** List trajectories that consumed an Experience. */
listExperienceTrajectories(
experienceUri: string,
options: ExperienceTrajectoryOptions = {},
): Promise<JsonObject> {
return this.request(
"GET",
"/api/v1/agent-evolution/experiences/trajectories",
{
query: {
experience_uri: normalizeURI(experienceUri),
limit: options.limit,
offset: options.offset,
start_date: options.startDate,
end_date: options.endDate,
},
},
);
}
/** Return the outcome distribution for an Experience. */
getExperienceOutcomes(
experienceUri: string,
options: ExperienceOutcomeOptions = {},
): Promise<JsonObject> {
return this.request("GET", "/api/v1/agent-evolution/experiences/outcomes", {
query: {
experience_uri: normalizeURI(experienceUri),
start_date: options.startDate,
end_date: options.endDate,
},
});
}
/** Parse and validate an OpenViking Assets manifest. */
resolveOpenVikingAssets(
manifestYaml: string,
options: ResolveAssetsOptions = {},
): Promise<JsonObject> {
const body = compact({
manifest_yaml: manifestYaml,
catalog_yaml: options.catalogYaml,
manifest_label: options.manifestLabel,
catalog_label: options.catalogLabel,
});
return this.request("POST", "/api/v1/openviking-assets/resolve", {
body: mergeExtra(body, options.extra),
});
}
/** Verify read access to one Git asset. */
preflightOpenVikingAsset(
name: string,
repoUrl: string,
options: PreflightAssetOptions = {},
): Promise<JsonObject> {
const body = compact({
name,
connector: "git",
repo_url: repoUrl,
branch: options.branch,
commit: options.commit,
auth_config: options.authConfig,
});
return this.request("POST", "/api/v1/openviking-assets/preflight", {
body: mergeExtra(body, options.extra),
});
}
}