Skip to content

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

8.1 KB
Raw Blame
import type { OVConfig } from "./config.js";
import type { OvHttpRequestOptions } from "./shared/ov-http.mjs";
import { createOvHttp } from "./shared/ov-http.mjs";

// --- OV API Response Shapes ---
// All OV responses wrap in: { status: "ok"|"error", result: T, error?: {...}, ... }
// This client normalizes to { ok, result } internally.
//
// Scope: session plumbing only — health, the OV session and its commit, plus the
// raw `fetchJSON` the shared recall/sync/profile modules are built on. Search,
// content reads, filesystem operations and resource ingest are the model's
// business and reach the server over MCP (`lib/mcp-bridge.mjs`), so their REST
// wrappers are gone rather than kept as a second, drifting path to the same
// endpoints.

export interface OVSessionMeta {
  session_id: string;
  message_count: number;
  total_message_count?: number;
  commit_count: number;
  pending_tokens?: number;
  memories_extracted?: Record<string, number>;
  last_commit_at?: string;
}

export interface OVSessionContext {
  latest_archive_overview: string | null;
  pre_archive_abstracts: any[];
  messages: any[];
  estimatedTokens: number;
  stats: {
    totalArchives: number;
    includedArchives: number;
    droppedArchives: number;
    failedArchives: number;
    activeTokens: number;
    archiveTokens: number;
  };
}

export interface OVCommitResult {
  /**
   * `accepted` = phase 1 wrote `history/archive_NNN/messages.jsonl` and a
   * background task is generating the Working Memory; `skipped` = nothing to
   * archive (see `reason`, e.g. `no_messages`). Older builds omit the field.
   */
  status?: "accepted" | "skipped" | string;
  /** Whether phase 1 created an archive. */
  archived?: boolean;
  effective_enable_working_memory?: boolean;
  reason?: string;
  task_id?: string;
  /** `null` on a `skipped` commit — the server sends the key either way. */
  archive_uri?: string | null;
  trace_id?: string;
}

export interface OVCommitResponse {
  result: OVCommitResult | null;
  traceId?: string;
  error?: any;
  status?: number;
}

export interface OVResponse<T> {
  ok: boolean;
  result: T | null;
  error?: any;
  status?: number;
  traceId?: string;
}

export class OVClient {
  private http: ReturnType<typeof createOvHttp>;
  connected: boolean = false;

  /** Read-only access to config (for value access across modules). */
  readonly cfg: OVConfig;

  constructor(config: OVConfig) {
    this.cfg = config;
    this.http = createOvHttp(
      { ...config, baseUrl: config.endpoint.replace(/\/+$/, "") },
      { defaultTimeoutMs: 10000, resolveActorPeerId: () => config.peerId },
    );
  }

  /** Core fetch wrapper. Returns { ok, result } after parsing OV's { status, result } envelope. */
  async fetchJSON<T>(path: string, init?: RequestInit, options?: OvHttpRequestOptions): Promise<OVResponse<T>> {
    return this.http(path, init, options);
  }

  // ========== Health ==========

  async health(): Promise<boolean> {
    const res = await this.fetchJSON<any>("/health", undefined, { timeoutMs: 5000 });
    this.connected = res.ok;
    return res.ok;
  }

  // ========== Sessions ==========

  /** GET /api/v1/sessions/{id} — session metadata */
  async getSession(sessionId: string, autoCreate = false): Promise<OVSessionMeta | null> {
    const q = autoCreate ? "?auto_create=true" : "";
    const res = await this.fetchJSON<OVSessionMeta>(
      `/api/v1/sessions/${encodeURIComponent(sessionId)}${q}`,
      undefined, { timeoutMs: 5000 },
    );
    return res.ok ? res.result : null;
  }

  /** GET /api/v1/sessions/{id}/context — assembled context with archive overview */
  async getSessionContext(sessionId: string, tokenBudget = 128000): Promise<OVSessionContext | null> {
    const res = await this.fetchJSON<OVSessionContext>(
      `/api/v1/sessions/${encodeURIComponent(sessionId)}/context?token_budget=${tokenBudget}`,
      undefined, { timeoutMs: 10000 },
    );
    return res.ok ? res.result : null;
  }

  /** POST /api/v1/sessions/{id}/commit — commit session for archiving + extraction */
  async commitSessionResponse(
    sessionId: string,
    keepRecentCount = 0,
    timeoutMs = 30000,
    enableWorkingMemory?: boolean,
  ): Promise<OVCommitResponse> {
    const res = await this.fetchJSON<OVCommitResult>(
      `/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`,
      { method: "POST", body: JSON.stringify({ keep_recent_count: keepRecentCount, enable_working_memory: enableWorkingMemory }) },
      { timeoutMs },
    );
    if (res.ok && res.result && !res.result.trace_id && res.traceId) {
      res.result.trace_id = res.traceId;
    }
    return {
      result: res.ok ? res.result : null,
      traceId: res.traceId,
      error: res.error,
      status: res.status,
    };
  }

  /**
   * Working Memory of one archive: `GET /content/read?uri=<archive_uri>/.overview.md`.
   *
   * This reads the Working Memory that belongs to a *specific* commit, keyed by
   * the `archive_uri` that commit returned — unlike `getSessionContext`, whose
   * `latest_archive_overview` reflects whatever the session's newest archive is
   * and can point at an older `/context` summary that this takeover did not
   * produce. Returns null until commit phase 2 writes the sidecar (the server
   * answers 404 until then). Other read failures throw so takeover can log a
   * read failure separately from an unfinished archive. The sidecar is stored as
   * OKF Markdown — `---\n<yaml>\n---\n\n<body>\n` — and `content/read` only
   * strips that framing for memory URIs, not session archives, so the
   * frontmatter is removed here. A file present but empty counts as not ready
   * (null), so a poller cannot be fooled by an empty write. Takeover reads it
   * inside pi event handlers, so one read is capped well below their budget.
   */
  async readArchiveOverview(archiveUri: string, timeoutMs = 5000): Promise<string | null> {
    const base = String(archiveUri ?? "").trim().replace(/\/+$/, "");
    if (!base) return null;
    const res = await this.fetchJSON<string>(
      `/api/v1/content/read?uri=${encodeURIComponent(`${base}/.overview.md`)}`,
      undefined, { timeoutMs },
    );
    if (!res.ok) {
      if (res.status === 404) return null;
      const detail = res.error?.message || res.error?.code || `HTTP ${res.status ?? 0}`;
      throw new Error(`archive overview read failed: ${detail}`);
    }
    if (typeof res.result !== "string") return null;
    const body = stripFrontmatter(res.result);
    return body.trim() ? body : null;
  }

  /**
   * Terminal state of one archive, from the markers the server itself uses
   * (`Session._archive_terminal_state`): `.done` once commit phase 2 completed
   * — it is written last, after the Working Memory when that is enabled, and
   * records `enable_working_memory: false` when it is not — and `.failed.json`
   * once phase 2 failed for good. "pending" while neither exists; null when the
   * server could not be asked. Unlike task records, the markers do not expire.
   */
  async getArchiveState(archiveUri: string, timeoutMs = 10000): Promise<"completed" | "failed" | "pending" | null> {
    const base = String(archiveUri ?? "").trim().replace(/\/+$/, "");
    if (!base) return null;
    const deadline = Date.now() + timeoutMs;
    for (const [marker, state] of [[".done", "completed"], [".failed.json", "failed"]] as const) {
      const remaining = deadline - Date.now();
      if (remaining <= 0) return null;
      const res = await this.fetchJSON<string>(
        `/api/v1/content/read?uri=${encodeURIComponent(`${base}/${marker}`)}`,
        undefined, { timeoutMs: Math.min(5000, remaining) },
      );
      if (res.ok) return state;
      if (res.status !== 404) return null;
    }
    return "pending";
  }
}

/**
 * Drop a leading `---` … `---` YAML frontmatter block, together with the blank
 * line the server writes after it (its sidecars render as `---\n<yaml>\n---\n\n
 * <body>\n`). Reused rule from the experimental fork's client.
 */
function stripFrontmatter(text: string): string {
  const m = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
  if (!m) return text;
  return text.slice(m[0].length).replace(/^(?:[ \t]*\r?\n)+/, "");
}