Skip to content

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

11.5 KB
Raw Blame
// Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
// SPDX-License-Identifier: AGPL-3.0

/** Arbitrary JSON object returned by APIs without a dedicated result type. */
export type JsonObject = Record<string, unknown>;
/** One target URI or multiple target scopes. */
export type TargetURI = string | string[];
/** Header values accepted without requiring the DOM-only `HeadersInit` alias. */
export type ClientHeaders =
  Headers | Record<string, string> | [string, string][];
/** Temporary upload storage mode supported by the OpenViking server. */
export type UploadMode = "local" | "shared";
/** Resource post-ingest processing modes accepted by addResource. */
export type ProcessingMode = "semantic_and_vectors" | "vectors_only";
/** Observer response format supported by HTTP observer APIs. */
export type ObserverFormat = "table" | "json";
/** Conflict policy accepted when importing an OVPack. */
export type PackConflictPolicy = "fail" | "overwrite" | "skip";
/** Vector handling strategy accepted when importing an OVPack. */
export type PackVectorMode = "auto" | "recompute" | "require";

/** Connection, identity and transport configuration. */
export interface ClientConfig {
  baseUrl: string;
  apiKey?: string;
  account?: string;
  user?: string;
  actorPeerId?: string;
  timeout?: number;
  headers?: ClientHeaders;
  fetch?: typeof globalThis.fetch;
  profile?: boolean;
  uploadMode?: UploadMode;
}

/** A Node.js local path or remote URL accepted by resource APIs. */
export type UploadSource = string;

/** Options shared by OVPack import and restore operations. */
export interface ImportPackOptions {
  onConflict?: PackConflictPolicy;
  vectorMode?: PackVectorMode;
}

/** Options for creating a filesystem snapshot. */
export interface GitCommitOptions {
  message: string;
  paths?: string[];
  branch?: string;
  authorName?: string;
  authorEmail?: string;
}
/** Options for restoring a filesystem snapshot. */
export interface GitRestoreOptions {
  sourceCommit: string;
  projectDir?: string;
  branch?: string;
  dryRun?: boolean;
  message?: string;
  authorName?: string;
  authorEmail?: string;
}
/** Raw file returned by a snapshot lookup. */
export interface GitBlob {
  oid: string;
  size: number;
  bytes: Uint8Array;
}

/** Per-request cancellation options. */
export interface RequestOptions {
  signal?: AbortSignal;
}
/** Options shared by asynchronous processing APIs. */
export interface WaitOptions {
  wait?: boolean;
  /** @deprecated Accepted for compatibility and ignored. */
  timeout?: number;
  telemetry?: unknown;
}
/** Writable direct grants and inheritance mode. */
export interface AclSpec {
  acl_mode?: "inherit" | "restricted";
  entries?: { principal: string; level: "read" | "write" | "manage" }[];
}
/** Resource import options. */
export interface AddResourceOptions extends WaitOptions {
  acl?: AclSpec;
  to?: string;
  parent?: string;
  createParent?: boolean;
  reason?: string;
  instruction?: string;
  strict?: boolean;
  ignoreDirs?: string;
  include?: string;
  exclude?: string;
  directlyUploadMedia?: boolean;
  preserveStructure?: boolean;
  watchInterval?: number;
  processingMode?: ProcessingMode;
  args?: JsonObject;
  tags?: string[];
  tagMode?: "replace" | "append" | "clear";
  extra?: JsonObject;
}
/** Content write options. */
export interface WriteOptions extends WaitOptions {
  acl?: AclSpec;
  mode?: string;
  processingMode?: ProcessingMode;
  tags?: string[];
  tagMode?: "replace" | "append" | "clear";
  extra?: JsonObject;
}
/** One file write in a batch. */
export interface BatchWriteOperation {
  uri: string;
  content?: string;
  contentBase64?: string;
  mode?: "replace" | "append" | "create" | "upsert";
  tags?: string[];
  tagMode?: "replace" | "append" | "clear";
  acl?: AclSpec;
}
/** Batch-write request options. */
export interface BatchWriteOptions extends WaitOptions {
  deferProcessing?: boolean;
  processingMode?: ProcessingMode;
  extra?: JsonObject;
}
/** Compile request options. */
export interface CompileOptions {
  instruction?: string;
  args?: JsonObject;
  extra?: JsonObject;
}
/** Retrieval tag update options. */
export interface SetTagsOptions {
  mode?: "replace" | "append" | "clear";
  recursive?: boolean;
  telemetry?: unknown;
  extra?: JsonObject;
}
/** Reindex request options. */
export interface ReindexOptions {
  mode?: string;
  wait?: boolean;
  force?: boolean;
  recursive?: boolean;
  tags?: string[];
  tagMode?: "replace" | "append" | "clear";
  extra?: JsonObject;
}
/** Semantic retrieval options shared by find and search. */
export interface FindOptions {
  targetUri?: TargetURI;
  image?: string;
  limit?: number;
  nodeLimit?: number;
  scoreThreshold?: number;
  filter?: JsonObject;
  contextType?: unknown;
  telemetry?: unknown;
  since?: string;
  until?: string;
  timeField?: string;
  level?: number[];
  tags?: string[];
  includeProvenance?: boolean;
  readContent?: boolean;
  eventsTimeDecayProtection?: string | null;
  extra?: JsonObject;
}
/** Session-aware retrieval options. */
export interface SearchOptions extends FindOptions {
  sessionId?: string;
  searchType?: "semantic" | "keywords";
}
/** Server-side context assembly options. */
export interface SearchContextOptions {
  searchType?: "semantic" | "keywords";
  image?: string;
  sessionId?: string;
  limit?: number;
  nodeLimit?: number;
  scoreThreshold?: number;
  filter?: JsonObject;
  contextType?: unknown;
  includeProvenance?: boolean;
  tags?: string[];
  since?: string;
  until?: string;
  timeField?: string;
  eventsTimeDecayProtection?: string | null;
  queryExpansion?: "off" | "auto";
  maxTokens?: number;
  quotas?: Record<string, number>;
  purpose?: "chat" | "coding";
  detail?: string | Record<string, string>;
  dedupTurns?: number;
  excludeUris?: string[];
  peerScope?: "actor" | "all";
  otherPeerPenalty?: number | Record<string, number>;
  rewrite?: boolean | "auto";
  rewriteMaxBullets?: number;
  telemetry?: unknown;
  extra?: JsonObject;
}
/** Content grep options. */
export interface GrepOptions {
  caseInsensitive?: boolean;
  nodeLimit?: number;
  levelLimit?: number;
  excludeUri?: string;
  tags?: string[];
  includeTags?: boolean;
}
/** File glob options. */
export interface GlobOptions {
  nodeLimit?: number;
  tags?: string[];
  includeTags?: boolean;
}
/** Directory listing options. */
export interface ListOptions {
  simple?: boolean;
  recursive?: boolean;
  output?: string;
  absLimit?: number;
  includeAbstract?: boolean;
  includeOverview?: boolean;
  overviewLimit?: number;
  showAllHidden?: boolean;
  nodeLimit?: number;
  offset?: number;
  limit?: number;
  sortBy?: "name" | "mtime";
  sortOrder?: "asc" | "desc";
  extraFields?: Array<"locked" | "id" | "count">;
  tags?: string[];
  includeTags?: boolean;
}
/** Directory tree options. */
export interface TreeOptions {
  output?: string;
  absLimit?: number;
  includeAbstract?: boolean;
  includeOverview?: boolean;
  overviewLimit?: number;
  showAllHidden?: boolean;
  directoriesOnly?: boolean;
  nodeLimit?: number;
  levelLimit?: number;
  offset?: number;
  limit?: number;
  extraFields?: Array<"locked" | "id" | "count">;
  tags?: string[];
  includeTags?: boolean;
}
/** Directory listing page with pagination metadata. */
export interface ListPage {
  result: unknown[];
  hasMore: boolean;
}
/** Directory tree page with pagination metadata. */
export interface TreePage {
  result: JsonObject[];
  hasMore: boolean;
}
/** Session message payload. */
export interface Message {
  role: string;
  content?: string;
  parts?: JsonObject[];
  createdAt?: string;
  peerId?: string;
  turnId?: string;
  messageKind?:
    "user_query" | "assistant_step" | "tool_transport" | "checkpoint";
  sourceMessageIds?: string[];
  telemetry?: unknown;
}
/** Session creation options. */
export interface CreateSessionOptions {
  sessionId?: string;
  memoryPolicy?: JsonObject;
  autoCommitPolicy?: JsonObject | null;
  memoryExtractionConfig?: MemoryExtractionConfig;
  telemetry?: unknown;
  extra?: JsonObject;
}
/** Event-memory extraction settings shared by session create and update. */
export interface MemoryExtractionConfig {
  events?: {
    tags?: string[];
  };
}
/** Mutable session configuration. */
export interface UpdateSessionConfigOptions {
  memoryExtractionConfig?: MemoryExtractionConfig;
  autoCommitPolicy?: JsonObject | null;
  telemetry?: unknown;
  extra?: JsonObject;
}
/** Batch message request options. */
export interface BatchAddMessagesOptions {
  telemetry?: unknown;
  extra?: JsonObject;
}
/** Session commit and turn-retention options. */
export interface CommitSessionOptions {
  /** Override only Working Memory for this commit; null inherits the session policy. */
  enableWorkingMemory?: boolean | null;
  keepRecentCount?: number;
  retentionMode?: "turn_budget";
  keepRecentTurnCount?: number;
  retainedMessageTokenBudget?: number;
  minRawTailSteps?: number;
  eventTags?: string[];
  telemetry?: unknown;
  extra?: JsonObject;
}
/** Pagination options for Experience trajectories. */
export interface ExperienceTrajectoryOptions {
  limit?: number;
  offset?: number;
  startDate?: string;
  endDate?: string;
}
/** Date filters for Experience outcome aggregation. */
export interface ExperienceOutcomeOptions {
  startDate?: string;
  endDate?: string;
}
/** Manifest resolver options. */
export interface ResolveAssetsOptions {
  catalogYaml?: string;
  manifestLabel?: string;
  catalogLabel?: string;
  extra?: JsonObject;
}
/** One-shot Git credentials for asset preflight. */
export interface AssetGitAuth {
  username?: string;
  token?: string;
}
/** Git asset preflight options. */
export interface PreflightAssetOptions {
  branch?: string;
  commit?: string;
  authConfig?: AssetGitAuth;
  extra?: JsonObject;
}
/** Background task filters. */
export interface TaskListOptions {
  taskType?: string;
  status?: string;
  resourceId?: string;
  limit?: number;
}
/** Options for retrieving an installed skill. */
export interface GetSkillOptions {
  includeContent?: boolean;
  includeFiles?: boolean;
  includeSource?: boolean;
  level?: number;
  targetUri?: string;
}
/** Fields that can be changed on a watch task. */
export interface UpdateWatchOptions {
  watchInterval?: number;
  isActive?: boolean;
  reason?: string;
  instruction?: string;
}
/** One retrieval hit. Only fields the retrieval pipeline populates are typed;
 * `search_tags` is surfaced under `tags` to match the tags filter parameter. */
export interface MatchedContext {
  uri?: string;
  context_type?: string;
  level?: number;
  abstract?: string;
  score?: number;
  origin_score?: number | null;
  time_score?: number | null;
  tags?: string[];
  [key: string]: unknown;
}
/** Grouped semantic retrieval results. */
export interface FindResult {
  memories?: MatchedContext[];
  resources?: MatchedContext[];
  skills?: MatchedContext[];
  [key: string]: unknown;
}
/** One assembled context entry. */
export interface SearchContextEntry {
  uri?: string;
  category?: string;
  score?: number;
  detail?: string;
  text?: string;
  origin?: string;
}
/** Injection-ready server-side context. */
export interface SearchContextResult {
  entries?: SearchContextEntry[];
  rendered?: string;
  digest?: string;
  stats?: JsonObject;
}
/** Error payload returned by OpenViking. */
export interface APIErrorInfo {
  code?: string;
  message?: string;
  details?: JsonObject;
}
/** Standard OpenViking HTTP response envelope. */
export interface ResponseEnvelope<T> {
  status?: string;
  result?: T;
  has_more?: boolean;
  error?: APIErrorInfo;
  telemetry?: unknown;
  profile?: string[];
  detail?: unknown;
}