Skip to content

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

30.4 KB
Raw Blame
import { defaultHttpTransport, type HttpTransport } from "./adapters/http-transport.js";
import {
  defaultResourcePackager,
  type ResourcePackager,
} from "./adapters/resource-packager.js";
import {
  buildContextSearchBody,
  contextRequestTimeoutMs,
  normalizeContextEntry,
} from "./shared/recall-core.mjs";

export type FindResultItem = {
  uri: string;
  level?: number;
  abstract?: string;
  overview?: string;
  category?: string;
  score?: number;
  match_reason?: string;
};

export type FindResult = {
  memories?: FindResultItem[];
  resources?: FindResultItem[];
  skills?: FindResultItem[];
  total?: number;
};

export type SearchContextEntry = {
  uri: string;
  category?: string;
  score?: number;
  detail?: string;
  text?: string;
  origin?: string;
};

export type SearchContextResult = {
  entries?: SearchContextEntry[];
  rendered?: string;
  digest?: string;
  stats?: Record<string, unknown>;
};

export type SearchContextOptions = {
  sessionId?: string;
  limit?: number;
  scoreThreshold?: number;
  contextType?: string | string[];
  queryExpansion?: "off" | "auto";
  recallCompress?: "off" | "server" | "auto";
  maxTokens?: number;
  detail?: "abstract" | "overview" | "full";
  dedupTurns?: number;
  peerScope?: "actor" | "all";
  actorPeerId?: string;
  requestTimeoutMs?: number;
};

export type FsListEntry = string | Record<string, unknown>;

export type FsListResult = FsListEntry[];

export type CaptureMode = "semantic" | "keyword";
function userSessionUri(sessionId: string): string {
  return `viking://~/sessions/${encodeURIComponent(sessionId)}`;
}

export type OpenVikingClientOptions = {
  transport?: HttpTransport;
  headers?: Record<string, string>;
  resourcePackager?: ResourcePackager;
  now?: () => number;
  sleep?: (ms: number) => Promise<void>;
};

export type CommitSessionResult = {
  effective_enable_working_memory?: boolean;
  session_id: string;
  /** "accepted" (async), "skipped" (no archive), "completed", "failed", or "timeout" (wait mode). */
  status: string;
  task_id?: string;
  archive_uri?: string;
  archived?: boolean;
  reset_context?: boolean;
  /** Present when wait=true and extraction completed. Keyed by category. */
  memories_extracted?: Record<string, number>;
  error?: string;
  trace_id?: string;
};

export type OVMemoryPolicySwitch = {
  enabled?: boolean;
};

export type OVMemoryPolicy = {
  self?: OVMemoryPolicySwitch;
  peer?: OVMemoryPolicySwitch;
  memory_types?: string[];
};

export type TaskResult = {
  task_id: string;
  task_type: string;
  status: string;
  created_at: number;
  updated_at: number;
  resource_id?: string;
  result?: Record<string, unknown>;
  error?: string;
};

export type OVMessagePart = {
  type: string;
  text?: string;
  uri?: string;
  abstract?: string;
  context_type?: string;
  tool_id?: string;
  tool_name?: string;
  tool_input?: unknown;
  tool_output?: string;
  tool_status?: string;
  skill_uri?: string;
  duration_ms?: number;
  prompt_tokens?: number;
  completion_tokens?: number;
  tool_output_ref?: string;
  tool_output_truncated?: boolean;
  tool_output_original_chars?: number;
  tool_output_preview_chars?: number;
  tool_output_sha256?: string;
  tool_output_storage_uri?: string;
  tool_output_mime_type?: string;
  tool_output_source_ref?: string;
  tool_output_source_offset?: number;
  tool_output_source_limit?: number;
  tool_output_externalization_error?: string;
  tool_output_group_id?: string;
  tool_output_externalized_reason?: string;
  tool_output_group_original_chars?: number;
  tool_output_group_budget_chars?: number;
};

export type OVMessage = {
  id: string;
  role: string;
  parts: OVMessagePart[];
  created_at: string;
};

export type PreArchiveAbstract = {
  archive_id: string;
  abstract: string;
};

export type SessionContextResult = {
  latest_archive_overview: string;
  pre_archive_abstracts: PreArchiveAbstract[];
  messages: OVMessage[];
  estimatedTokens: number;
  stats: {
    totalArchives: number;
    includedArchives: number;
    droppedArchives: number;
    failedArchives: number;
    activeTokens: number;
    archiveTokens: number;
  };
};

export type ToolResultReadResult = {
  tool_result_id: string;
  content: string;
  offset: number;
  limit: number;
  offset_unit: "unicode_code_point";
  total_chars: number;
  has_more: boolean;
  metadata?: Record<string, unknown>;
};

export type ToolResultSearchResult = {
  tool_result_id: string;
  matches: Array<{
    offset: number;
    offset_unit: "unicode_code_point";
    snippet: string;
  }>;
};

export type ToolResultListResult = {
  tool_results: Array<Record<string, unknown>>;
};

export type SessionArchiveResult = {
  archive_id: string;
  abstract: string;
  overview: string;
  messages: OVMessage[];
};

export type AddResourceInput = {
  pathOrUrl: string;
  to?: string;
  parent?: string;
  reason?: string;
  instruction?: string;
  wait?: boolean;
  strict?: boolean;
  ignoreDirs?: string;
  include?: string;
  exclude?: string;
  preserveStructure?: boolean;
};

export type AddResourceResult = {
  status?: string;
  root_uri?: string;
  temp_uri?: string;
  source_path?: string;
  warnings?: string[];
  errors?: string[];
  queue_status?: unknown;
  meta?: unknown;
};

export type AddSkillInput = {
  path?: string;
  data?: unknown;
  wait?: boolean;
};

export type AddSkillResult = {
  status?: string;
  uri?: string;
  name?: string;
  auxiliary_files?: number;
  queue_status?: unknown;
};

export const DEFAULT_PHASE2_POLL_TIMEOUT_MS = 300_000;

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

export class OpenVikingClient {
  private readonly transport: HttpTransport;
  private readonly configuredHeaders: Record<string, string>;
  private readonly now: () => number;
  private readonly sleep: (ms: number) => Promise<void>;
  private readonly resourcePackager: ResourcePackager;

  constructor(
    private readonly baseUrl: string,
    private readonly apiKey: string,
    private readonly defaultAgentId: string,
    private readonly timeoutMs: number,
    /** When set, sent so ROOT keys or trusted deployments can select tenant identity. */
    private readonly accountId: string = "",
    private readonly userId: string = "",
    /** When set, logs routing for find + session writes (tenant headers + paths; never apiKey). */
    private readonly routingDebugLog?: (message: string) => void,
	    optionsOrLegacyUserScope: OpenVikingClientOptions | boolean = {},
	    _legacyAgentScope?: boolean,
	    legacyOptions?: OpenVikingClientOptions,
	  ) {
	    const options =
	      typeof optionsOrLegacyUserScope === "object" && optionsOrLegacyUserScope !== null
	        ? optionsOrLegacyUserScope
	        : (legacyOptions ?? {});
	    this.transport = options.transport ?? defaultHttpTransport;
    this.configuredHeaders = options.headers ?? {};
	    this.now = options.now ?? Date.now;
	    this.sleep = options.sleep ?? sleep;
    this.resourcePackager = options.resourcePackager ?? defaultResourcePackager;
  }

  getDefaultAgentId(): string {
    return this.defaultAgentId;
  }

  private resolveTenantHeaders():
    | { apiKey?: string; accountId?: string; userId?: string }
  {
    const apiKey = this.apiKey.trim();
    const accountId = this.accountId.trim();
    const userId = this.userId.trim();
    return {
      ...(apiKey ? { apiKey } : {}),
      ...(accountId ? { accountId } : {}),
      ...(userId ? { userId } : {}),
    };
  }

  private resolveActorPeerHeader(actorPeerId?: string): string | undefined {
    const value = actorPeerId?.trim();
    return value || undefined;
  }

  private resolveDefaultActorPeerHeader(): string {
    const peerPrefix = this.defaultAgentId.trim();
    return peerPrefix ? `${peerPrefix}_main` : "main";
  }

  private async emitRoutingDebug(
    label: string,
    detail: Record<string, unknown>,
    actorPeerId?: string,
  ): Promise<void> {
    if (!this.routingDebugLog) {
      return;
    }
    const tenantHeaders = this.resolveTenantHeaders();
    const actorPeerHeader = this.resolveActorPeerHeader(actorPeerId);
    this.routingDebugLog(
      `openviking: ${label} ` +
        JSON.stringify({
          ...detail,
          X_OpenViking_Account: tenantHeaders.accountId ?? null,
          X_OpenViking_User: tenantHeaders.userId ?? null,
          X_OpenViking_Actor_Peer: actorPeerHeader ?? null,
          session_vfs_hint: detail.sessionId
            ? userSessionUri(String(detail.sessionId))
            : undefined,
        }),
    );
  }

  private async request<T>(
    path: string,
    init: RequestInit = {},
    requestTimeoutMs?: number,
    actorPeerId?: string,
  ): Promise<T> {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), requestTimeoutMs ?? this.timeoutMs);
    try {
      const headers = new Headers(init.headers ?? {});
      const tenantHeaders = this.resolveTenantHeaders();
      if (tenantHeaders.apiKey) {
        headers.set("X-API-Key", tenantHeaders.apiKey);
      }
      if (tenantHeaders.accountId) {
        headers.set("X-OpenViking-Account", tenantHeaders.accountId);
      }
      if (tenantHeaders.userId) {
        headers.set("X-OpenViking-User", tenantHeaders.userId);
      }
      const actorPeerHeader = this.resolveActorPeerHeader(actorPeerId);
      if (actorPeerHeader) {
        headers.set("X-OpenViking-Actor-Peer", actorPeerHeader);
      }
      for (const [key, value] of Object.entries(this.configuredHeaders)) {
        if (key && typeof value === "string" && value.trim()) {
          headers.set(key, value);
        }
      }
      if (init.body && !(init.body instanceof FormData) && !headers.has("Content-Type")) {
        headers.set("Content-Type", "application/json");
      }

      const response = await this.transport(`${this.baseUrl}${path}`, {
        ...init,
        headers,
        signal: controller.signal,
      });

      // Only a body that arrived whole but is not JSON falls back to `{}`. A
      // body cut off by a timeout, reset or early close after the headers
      // rejects, so a write is not reported as stored and a read is not
      // reported as empty.
      const payload = (await response.json().catch((error: unknown) => {
        if (!(error instanceof SyntaxError)) throw error;
        return {};
      })) as {
        status?: string;
        result?: T;
        error?: { code?: string; message?: string; trace_id?: string };
      };

      if (!response.ok || payload.status === "error") {
        const code = payload.error?.code ? ` [${payload.error.code}]` : "";
        const message = payload.error?.message ?? `HTTP ${response.status}`;
        const traceId = payload.error?.trace_id;
        throw new Error(
          `OpenViking request failed${code}: ${message}` +
            (traceId ? ` (trace_id=${traceId})` : ""),
        );
      }

      return (payload.result ?? payload) as T;
    } finally {
      clearTimeout(timer);
    }
  }

  async healthCheck(requestTimeoutMs?: number, actorPeerId?: string): Promise<void> {
    await this.request<{ status: string }>(
      "/health",
      {},
      requestTimeoutMs,
      actorPeerId ?? this.resolveDefaultActorPeerHeader(),
    );
  }

  async createSession(
    sessionId: string,
    options?: { memoryPolicy?: OVMemoryPolicy },
  ): Promise<{ session_id: string; user?: unknown }> {
    const body: Record<string, unknown> = { session_id: sessionId };
    if (options?.memoryPolicy) {
      body.memory_policy = options.memoryPolicy;
    }
    return this.request<{ session_id: string; user?: unknown }>(
      "/api/v1/sessions",
      { method: "POST", body: JSON.stringify(body) },
    );
  }

  async ensureSession(
    sessionId: string,
    options?: { memoryPolicy?: OVMemoryPolicy },
  ): Promise<boolean> {
    try {
      await this.createSession(sessionId, options);
      return true;
    } catch (err) {
      const message = err instanceof Error ? err.message : String(err);
      if (message.includes("[ALREADY_EXISTS]")) {
        return false;
      }
      throw err;
    }
  }

  async find(
    query: string,
    options: {
      targetUri?: string;
      limit?: number;
      scoreThreshold?: number;
      contextType?: string | string[];
      actorPeerId?: string;
    },
    legacyActorPeerId?: string,
  ): Promise<FindResult> {
    const targetUri = options.targetUri?.trim().replace(/\/+$/, "") ?? "";
    const body: {
      query: string;
      target_uri?: string;
      limit?: number;
      score_threshold?: number;
      context_type?: string | string[];
    } = {
      query,
      limit: options.limit,
      score_threshold: options.scoreThreshold,
      context_type: options.contextType,
    };
    if (targetUri) {
      body.target_uri = targetUri;
    }
    const actorPeerId = this.resolveActorPeerHeader(options.actorPeerId ?? legacyActorPeerId);
    const tenantHeaders = this.resolveTenantHeaders();
    this.routingDebugLog?.(
      `openviking: find POST ${this.baseUrl}/api/v1/search/find ` +
        JSON.stringify({
          X_OpenViking_Account: tenantHeaders.accountId ?? null,
          X_OpenViking_User: tenantHeaders.userId ?? null,
          X_OpenViking_Actor_Peer: actorPeerId ?? null,
          target_uri: targetUri || null,
          target_uri_input: options.targetUri,
          query:
            query.length > 4000
              ? `${query.slice(0, 4000)}…(+${query.length - 4000} more chars)`
              : query,
          limit: body.limit,
          score_threshold: body.score_threshold ?? null,
          context_type: body.context_type ?? null,
        }),
    );
    return this.request<FindResult>("/api/v1/search/find", {
      method: "POST",
      body: JSON.stringify(body),
    }, undefined, actorPeerId);
  }

  async searchContext(
    query: string,
    options: SearchContextOptions = {},
  ): Promise<SearchContextResult> {
    const contractConfig = {
      recallLimit: options.limit,
      recallRewrite: options.recallCompress,
      recallLimitConfigured: options.limit !== undefined,
      recallMaxTokens: options.maxTokens,
      recallMaxTokensConfigured: options.maxTokens !== undefined,
      scoreThreshold: options.scoreThreshold,
      recallQueryExpansion: options.queryExpansion,
      recallQueryExpansionConfigured: options.queryExpansion !== undefined,
      recallDedupTurns: options.dedupTurns,
      recallPeerScope: options.peerScope,
      recallContextTimeoutMs: options.requestTimeoutMs,
      timeoutMs: this.timeoutMs,
    };
    const body = {
      ...buildContextSearchBody(contractConfig, { sessionId: options.sessionId }),
      ...(options.dedupTurns === 0 ? { dedup_turns: 0 } : {}),
      query,
      ...(options.contextType !== undefined ? { context_type: options.contextType } : {}),
      ...(options.detail !== undefined ? { detail: options.detail } : {}),
    };
    const requestTimeoutMs = contextRequestTimeoutMs(contractConfig, body);
    const actorPeerId = this.resolveActorPeerHeader(options.actorPeerId);
    const tenantHeaders = this.resolveTenantHeaders();
    this.routingDebugLog?.(
      `openviking: context search POST ${this.baseUrl}/api/v1/search/search ` +
        JSON.stringify({
          X_OpenViking_Account: tenantHeaders.accountId ?? null,
          X_OpenViking_User: tenantHeaders.userId ?? null,
          X_OpenViking_Actor_Peer: actorPeerId ?? null,
          session_id: body.session_id ?? null,
          query:
            query.length > 4000
              ? `${query.slice(0, 4000)}…(+${query.length - 4000} more chars)`
              : query,
          purpose: body.purpose,
          quotas: body.quotas ?? null,
          score_threshold: body.score_threshold,
          context_type: body.context_type ?? null,
          query_expansion: body.query_expansion ?? null,
          max_tokens: body.max_tokens ?? null,
          detail: body.detail ?? null,
          dedup_turns: body.dedup_turns ?? 0,
          peer_scope: body.peer_scope ?? null,
        }),
    );
    const result = await this.request<SearchContextResult>("/api/v1/search/search", {
      method: "POST",
      body: JSON.stringify(body),
    }, requestTimeoutMs, actorPeerId);
    return {
      ...result,
      entries: Array.isArray(result.entries)
        ? result.entries.map((entry) => ({ ...entry, ...normalizeContextEntry(entry) }))
        : result.entries,
    };
  }

  async read(uri: string, actorPeerId?: string, requestTimeoutMs?: number): Promise<string> {
    return this.request<string>(
      `/api/v1/content/read?uri=${encodeURIComponent(uri)}`,
      {},
      requestTimeoutMs,
      actorPeerId,
    );
  }

  async list(
    uri: string,
    options?: {
      recursive?: boolean;
      simple?: boolean;
      output?: "agent" | "original";
      absLimit?: number;
      showAllHidden?: boolean;
      nodeLimit?: number;
      actorPeerId?: string;
    },
  ): Promise<FsListResult> {
    const normalizedUri = uri.trim().replace(/\/+$/, "");
    const params = new URLSearchParams({
      uri: normalizedUri,
      recursive: String(options?.recursive ?? false),
      simple: String(options?.simple ?? false),
      output: options?.output ?? "agent",
      abs_limit: String(options?.absLimit ?? 256),
      show_all_hidden: String(options?.showAllHidden ?? false),
      node_limit: String(options?.nodeLimit ?? 1000),
    });
    return this.request<FsListResult>(
      `/api/v1/fs/ls?${params.toString()}`,
      {},
      undefined,
      options?.actorPeerId,
    );
  }

  async readToolResult(
    sessionId: string,
    toolResultId: string,
    options?: { offset?: number; limit?: number; includeMetadata?: boolean },
  ): Promise<ToolResultReadResult> {
    const params = new URLSearchParams();
    if (options?.offset !== undefined) params.set("offset", String(options.offset));
    if (options?.limit !== undefined) params.set("limit", String(options.limit));
    if (options?.includeMetadata !== undefined) {
      params.set("include_metadata", String(options.includeMetadata));
    }
    const query = params.toString();
    return this.request<ToolResultReadResult>(
      `/api/v1/sessions/${encodeURIComponent(sessionId)}/tool-results/${encodeURIComponent(toolResultId)}${query ? `?${query}` : ""}`,
      {},
    );
  }

  async searchToolResult(
    sessionId: string,
    toolResultId: string,
    queryText: string,
    options?: { limit?: number; contextChars?: number },
  ): Promise<ToolResultSearchResult> {
    const params = new URLSearchParams({ q: queryText });
    if (options?.limit !== undefined) params.set("limit", String(options.limit));
    if (options?.contextChars !== undefined) {
      params.set("context_chars", String(options.contextChars));
    }
    return this.request<ToolResultSearchResult>(
      `/api/v1/sessions/${encodeURIComponent(sessionId)}/tool-results/${encodeURIComponent(toolResultId)}/search?${params.toString()}`,
      {},
    );
  }

  async listToolResults(
    sessionId: string,
    options?: { toolName?: string; limit?: number },
  ): Promise<ToolResultListResult> {
    const params = new URLSearchParams();
    if (options?.toolName) params.set("tool_name", options.toolName);
    if (options?.limit !== undefined) params.set("limit", String(options.limit));
    const query = params.toString();
    return this.request<ToolResultListResult>(
      `/api/v1/sessions/${encodeURIComponent(sessionId)}/tool-results${query ? `?${query}` : ""}`,
      {},
    );
  }

  async uploadTempFile(filePath: string, actorPeerId?: string): Promise<string> {
    const form = await this.resourcePackager.createTempUploadBody(filePath);
    const result = await this.request<{ temp_file_id: string }>(
      "/api/v1/resources/temp_upload",
      { method: "POST", body: form },
      undefined,
      actorPeerId,
    );
    if (!result.temp_file_id) {
      throw new Error("OpenViking temp upload did not return temp_file_id");
    }
    return result.temp_file_id;
  }

  async addResource(input: AddResourceInput, actorPeerId?: string): Promise<AddResourceResult> {
    const pathOrUrl = input.pathOrUrl.trim();
    if (!pathOrUrl) {
      throw new Error("pathOrUrl is required");
    }
    if (input.to && input.parent) {
      throw new Error("Cannot specify both 'to' and 'parent'.");
    }

    const body: Record<string, unknown> = {
      to: input.to,
      parent: input.parent,
      reason: input.reason ?? "",
      instruction: input.instruction ?? "",
      wait: input.wait ?? false,
      strict: input.strict ?? false,
      ignore_dirs: input.ignoreDirs,
      include: input.include,
      exclude: input.exclude,
    };
    if (typeof input.preserveStructure === "boolean") {
      body.preserve_structure = input.preserveStructure;
    }

    let packagedSource: Awaited<ReturnType<ResourcePackager["prepareResourceSource"]>> | undefined;
    try {
      packagedSource = await this.resourcePackager.prepareResourceSource(pathOrUrl);
      if (packagedSource.kind === "remote") {
        body.path = packagedSource.path;
      } else {
        if (packagedSource.sourceName) {
          body.source_name = packagedSource.sourceName;
        }
        body.temp_file_id = await this.uploadTempFile(packagedSource.uploadPath, actorPeerId);
      }
      return this.request<AddResourceResult>(
        "/api/v1/resources",
        { method: "POST", body: JSON.stringify(body) },
        undefined,
        actorPeerId,
      );
    } finally {
      await this.resourcePackager.cleanup(packagedSource);
    }
  }

  async addSkill(input: AddSkillInput, actorPeerId?: string): Promise<AddSkillResult> {
    const hasPath = typeof input.path === "string" && input.path.trim().length > 0;
    const hasData = input.data !== undefined && input.data !== null;
    if (hasPath === hasData) {
      throw new Error("Provide exactly one of 'path' or 'data' for skill import.");
    }

    const body: Record<string, unknown> = {
      wait: input.wait ?? false,
    };
    let packagedSource: Awaited<ReturnType<ResourcePackager["prepareLocalUploadSource"]>> | undefined;
    try {
      if (hasPath) {
        const skillPath = input.path!.trim();
        packagedSource = await this.resourcePackager.prepareLocalUploadSource(skillPath);
        if (packagedSource.kind !== "upload") {
          throw new Error(`Path is not a file or directory: ${skillPath}`);
        }
        body.temp_file_id = await this.uploadTempFile(packagedSource.uploadPath, actorPeerId);
      } else {
        body.data = input.data;
      }
      return this.request<AddSkillResult>(
        "/api/v1/skills",
        { method: "POST", body: JSON.stringify(body) },
        undefined,
        actorPeerId,
      );
    } finally {
      await this.resourcePackager.cleanup(packagedSource);
    }
  }

  async addSessionMessage(
    sessionId: string,
    role: string,
    parts: Array<{
      type: "text" | "tool" | "context";
      text?: string;
      tool_name?: string;
      tool_output?: string;
      tool_status?: string;
      tool_input?: Record<string, unknown>;
      tool_id?: string;
      tool_output_ref?: string;
      tool_output_truncated?: boolean;
      tool_output_original_chars?: number;
      tool_output_preview_chars?: number;
      tool_output_sha256?: string;
      tool_output_storage_uri?: string;
      tool_output_mime_type?: string;
      tool_output_source_ref?: string;
      tool_output_source_offset?: number;
      tool_output_source_limit?: number;
      tool_output_group_id?: string;
      tool_output_externalized_reason?: string;
      tool_output_group_original_chars?: number;
      tool_output_group_budget_chars?: number;
      uri?: string;
      abstract?: string;
      context_type?: "memory" | "resource" | "skill";
    }>,
    actorPeerId?: string,
    createdAt?: string,
    peerId?: string,
  ): Promise<void> {
    const body: {
      role: string;
      peer_id?: string;
      parts: typeof parts;
      created_at?: string;
    } = { role, parts };
    if (createdAt) {
      body.created_at = createdAt;
    }
    if (peerId) {
      body.peer_id = peerId;
    }
    await this.emitRoutingDebug(
      "session message POST (with parts)",
      {
        path: `/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
        sessionId,
        role,
        peer_id: peerId ?? null,
        partCount: parts.length,
        created_at: createdAt ?? null,
      },
      actorPeerId,
    );
    await this.request<{ session_id: string }>(
      `/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
      {
        method: "POST",
        body: JSON.stringify(body),
      },
      undefined,
      actorPeerId,
    );
  }

  /** GET session — server auto-creates if absent; returns session meta including message stats and token usage. */
  async getSession(sessionId: string, actorPeerId?: string): Promise<{
    message_count?: number;
    commit_count?: number;
    last_commit_at?: string;
    pending_tokens?: number;
    llm_token_usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
  }> {
    return this.request<{
      message_count?: number;
      commit_count?: number;
      last_commit_at?: string;
      pending_tokens?: number;
      llm_token_usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
    }>(
      `/api/v1/sessions/${encodeURIComponent(sessionId)}`,
      { method: "GET" },
      undefined,
      actorPeerId,
    );
  }

  /**
   * Commit a session: archive (Phase 1) and extract memories (Phase 2).
   *
   * wait=false (default): returns immediately after Phase 1 with task_id.
   * wait=true: after Phase 1, polls GET /tasks/{task_id} until Phase 2
   *   completes (or times out), then returns the merged result.
   */
  async commitSession(
    sessionId: string,
    options?: {
      wait?: boolean;
      enableWorkingMemory?: boolean;
      /**
       * WM v2: number of most-recent messages to keep live after commit.
       * Forwarded as `keep_recent_count` in the POST body. 0 (default)
       * preserves the pre-v2 "archive everything" behavior.
      */
      keepRecentCount?: number;
      /** Start empty context in the same session after archiving. */
      resetContext?: boolean;
      /** Opt in to the server's turn-aware defaults instead of message-count retention. */
      retentionMode?: "turn_budget";
      agentId?: string;
    },
  ): Promise<CommitSessionResult> {
    const keepRecentCount =
      options?.keepRecentCount != null && Number.isFinite(options.keepRecentCount)
        ? Math.max(0, Math.floor(options.keepRecentCount))
        : 0;
    await this.emitRoutingDebug(
      "session commit POST (archive + memory extraction)",
      {
        path: `/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`,
        sessionId,
        wait: options?.wait ?? false,
        keepRecentCount,
        retentionMode: options?.retentionMode,
      },
      options?.agentId,
    );
    const body: Record<string, unknown> = {};
    if (options?.enableWorkingMemory !== undefined) {
      body.enable_working_memory = options.enableWorkingMemory;
    }
    if (options?.retentionMode === "turn_budget") {
      body.retention_mode = "turn_budget";
    } else if (keepRecentCount > 0) {
      body.keep_recent_count = keepRecentCount;
    }
    if (options?.resetContext) {
      body.reset_context = true;
    }
    const result = await this.request<CommitSessionResult>(
      `/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`,
      { method: "POST", body: JSON.stringify(body) },
      undefined,
      options?.agentId,
    );

    if (options?.resetContext && result.reset_context !== true) {
      throw new Error("OpenViking server did not confirm reset_context; upgrade the server with the plugin.");
    }

    if (!options?.wait || !result.task_id) {
      return result;
    }

    // Client-side poll until Phase 2 finishes
    const deadline = this.now() + DEFAULT_PHASE2_POLL_TIMEOUT_MS;
    const pollInterval = 500;
    while (this.now() < deadline) {
      await this.sleep(pollInterval);
      const task = await this.getTask(result.task_id, options.agentId).catch(() => null);
      if (!task) break;
      if (task.status === "completed") {
        const taskResult = (task.result ?? {}) as Record<string, unknown>;
        const memoriesExtracted = (taskResult.memories_extracted ?? {}) as Record<string, number>;
        result.status = "completed";
        result.memories_extracted = memoriesExtracted;
        return result;
      }
      if (task.status === "failed") {
        result.status = "failed";
        result.error = task.error;
        return result;
      }
    }
    result.status = "timeout";
    return result;
  }

  /** Poll a background task by ID. */
  async getTask(taskId: string, actorPeerId?: string): Promise<TaskResult> {
    return this.request<TaskResult>(
      `/api/v1/tasks/${encodeURIComponent(taskId)}`,
      { method: "GET" },
      undefined,
      actorPeerId,
    );
  }

  async getSessionContext(
    sessionId: string,
    tokenBudget: number = 128_000,
    actorPeerId?: string,
  ): Promise<SessionContextResult> {
    return this.request(
      `/api/v1/sessions/${encodeURIComponent(sessionId)}/context?token_budget=${tokenBudget}`,
      { method: "GET" },
      undefined,
      actorPeerId,
    );
  }

  async getSessionArchive(
    sessionId: string,
    archiveId: string,
    actorPeerId?: string,
  ): Promise<SessionArchiveResult> {
    return this.request(
      `/api/v1/sessions/${encodeURIComponent(sessionId)}/archives/${encodeURIComponent(archiveId)}`,
      { method: "GET" },
      undefined,
      actorPeerId,
    );
  }

  async grepSessionArchives(
    sessionId: string,
    pattern: string,
    options: {
      archiveId?: string;
      caseInsensitive?: boolean;
      nodeLimit?: number;
      levelLimit?: number;
    } = {},
  ): Promise<{
    matches: Array<{ line: number; uri: string; content: string }>;
    count: number;
    match_count?: number;
    files_scanned?: number;
  }> {
    const baseUri = `${userSessionUri(sessionId)}/history`;
    const uri = options.archiveId ? `${baseUri}/${options.archiveId}` : baseUri;
    return this.request(
      "/api/v1/search/grep",
      {
        method: "POST",
        body: JSON.stringify({
          uri,
          pattern,
          case_insensitive: options.caseInsensitive ?? true,
          ...(options.nodeLimit !== undefined ? { node_limit: options.nodeLimit } : {}),
          ...(options.levelLimit !== undefined ? { level_limit: options.levelLimit } : {}),
        }),
      },
    );
  }

  async deleteSession(sessionId: string): Promise<void> {
    await this.request(`/api/v1/sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE" });
  }
  async deleteUri(uri: string, actorPeerId?: string): Promise<void> {
    await this.request(`/api/v1/fs?uri=${encodeURIComponent(uri)}&recursive=false`, {
      method: "DELETE",
    }, undefined, actorPeerId);
  }
}