Skip to content
Python
21.2 KB
Raw Blame
import { classifyModelRemove } from "@one-memory/operations";
import axios from "axios";

/**
 * Only paths proven side-effect free by reading the Core handlers belong here.
 * Legacy recall can schedule a reindex and source detect walks the host tree,
 * so neither is a status read.
 */
const READ_ONLY_PATHS = [
  "/api/v1/call-events",
  // Read-only: the registry plus a scan of the vector store's collection names.
  "/api/v1/embedding-spaces",
  "/api/v1/embedding-switches/current",
  "/api/v1/import-jobs",
  "/api/v1/live-sync",
  "/api/v1/memory-processing",
  "/api/v1/model-profiles",
  "/api/v1/source-grants",
  "/api/v1/sources",
  "/api/v2/home-summary",
  "/api/v2/memory-library",
  "/api/v2/user-profile",
  "/api/v2/user-profile/versions",
  "/api/v1/settings/memory-mode",
  "/api/v1/settings/memory-features",
  "/api/v1/settings/ui-language",
  "/api/v2/evolve",
] as const;
/** One evolve run's receipt (`memhub evolve --wait`). */
const EVOLVE_RUN =
  /^\/api\/v2\/evolve\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
const SDK_MEMORY_DETAIL = /^\/api\/v2\/memories\/[A-Za-z0-9][\w.-]{0,127}$/;
/** Status of one `POST /api/v2/memories` addition, by its request id. */
const MEMORY_ADDITION =
  /^\/api\/v2\/memories\/additions\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;

/** Contract (C0, H25): the one-time loopback code exchange for `memhub ui`.
 * It is a POST because it mints a short-lived code; the CLI sends the bearer
 * token only to Core, never to the browser. */
const UI_SESSION_PATH = "/api/v1/ui/session";

export function createUiSessionRequest(attachment: {
  host: string;
  port: number;
  apiToken: string;
  timeoutMs?: number;
}): () => Promise<
  { state: "ok"; data: unknown } | { state: "unavailable"; code: string }
> {
  const client = axios.create({
    baseURL: `http://${attachment.host}:${attachment.port}`,
    headers: { Authorization: `Bearer ${attachment.apiToken}` },
    timeout: attachment.timeoutMs ?? 5_000,
    proxy: false,
    maxRedirects: 0,
    maxContentLength: MAX_RESPONSE_BYTES,
    // The exchange POST carries only a tiny `{}` body; `maxBodyLength: 0`
    // (used by the GET-only reader) means "no body allowed", which axios
    // rejects with ERR_BAD_REQUEST.
    maxBodyLength: 32 * 1024,
    validateStatus: () => true,
  });
  return async () => {
    let response: { status: number; data: unknown };
    try {
      response = await client.post(UI_SESSION_PATH, {});
    } catch {
      return { state: "unavailable" as const, code: "transport_failed" };
    }
    if (response.status === 200) {
      return { state: "ok" as const, data: response.data };
    }
    if (response.status === 503) {
      return {
        state: "unavailable" as const,
        code: "ui_web_assets_unavailable",
      };
    }
    return { state: "unavailable" as const, code: `http_${response.status}` };
  };
}

const IMPORT_JOB =
  /^\/api\/v1\/import-jobs\/[A-Za-z0-9][\w.-]{0,127}(?:\/issues)?$/;
const OPERATION_RECEIPT =
  /^\/api\/v1\/(?:source-connections|model-profile-creations|model-probe-operations)\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
/**
 * Core registers these static routes before `/{memory_id}`, so a memory whose
 * id happens to be one of them would reach a different handler: `graph`
 * initializes the HY bridge, `ask` answers questions. Neither is a detail read.
 */
export const RESERVED_MEMORY_SEGMENTS = ["ask", "graph"] as const;

/** A response larger than this is refused before it is buffered. */
const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;

/** `rejected` is Core refusing the request itself (400/409/422: a bad filter,
 * an ambiguous id). It is not "Core is busy" — only a transport failure or a
 * 5xx is `unavailable`. */
export type ReadOutcome<T> =
  | { state: "ok"; data: T }
  | {
      state: "denied" | "unavailable" | "not_found" | "rejected";
      code: string;
    };

export type CoreReader = <T>(
  path: string,
  params?: Record<string, string | number>,
  options?: { signal?: AbortSignal },
) => Promise<ReadOutcome<T>>;

export type CoreContextQuery = <T>(
  body: object,
  options?: { signal?: AbortSignal },
) => Promise<ReadOutcome<T>>;

export function createCoreReader(attachment: {
  host: string;
  port: number;
  apiToken: string;
  timeoutMs?: number;
}): CoreReader {
  const client = axios.create({
    baseURL: `http://${attachment.host}:${attachment.port}`,
    headers: { Authorization: `Bearer ${attachment.apiToken}` },
    timeout: attachment.timeoutMs ?? 5_000,
    proxy: false,
    maxRedirects: 0,
    maxContentLength: MAX_RESPONSE_BYTES,
    maxBodyLength: 0,
    validateStatus: () => true,
  });
  return async <T>(
    path: string,
    params?: Record<string, string | number>,
    options?: { signal?: AbortSignal },
  ) => {
    if (!isReadOnlyPath(path)) {
      throw new Error("core_read_path_not_allowed");
    }
    let response: { status: number; data: unknown };
    try {
      const config =
        params || options?.signal
          ? {
              ...(params ? { params } : {}),
              ...(options?.signal ? { signal: options.signal } : {}),
            }
          : undefined;
      response = await client.get(path, config);
    } catch {
      return { state: "unavailable" as const, code: "transport_failed" };
    }
    if (response.status === 200) {
      return { state: "ok" as const, data: response.data as T };
    }
    if (response.status === 401 || response.status === 403) {
      return { state: "denied" as const, code: `http_${response.status}` };
    }
    if (response.status === 404) {
      return { state: "not_found" as const, code: "http_404" };
    }
    if ([400, 409, 422].includes(response.status)) {
      return {
        state: "rejected" as const,
        code: detailCode(response.data, response.status),
      };
    }
    return {
      state: "unavailable" as const,
      code: unavailableCode(response.data, response.status),
    };
  };
}

/** A 503 that names `embedding_unavailable` keeps it: the search could not
 * embed its query, which needs another fix than "try again later". */
function unavailableCode(value: unknown, status: number): string {
  return status === 503 && detailCode(value, status) === EMBEDDING_UNAVAILABLE
    ? EMBEDDING_UNAVAILABLE
    : `http_${status}`;
}

export const EMBEDDING_UNAVAILABLE = "embedding_unavailable";

/** Core's stable `detail` code when it sent one, else the bare status. */
function detailCode(value: unknown, status: number): string {
  const detail =
    value && typeof value === "object" && !Array.isArray(value)
      ? (value as { detail?: unknown }).detail
      : undefined;
  return typeof detail === "string" && /^[a-z0-9_.:-]{1,128}$/.test(detail)
    ? detail
    : `http_${status}`;
}

/**
 * Context search is semantically read-only but intentionally uses POST so the
 * private query and filters are carried in a bounded body, never in a URL.
 */
export function createCoreContextQuery(attachment: {
  host: string;
  port: number;
  apiToken: string;
  timeoutMs?: number;
}): CoreContextQuery {
  const client = axios.create({
    baseURL: `http://${attachment.host}:${attachment.port}`,
    headers: { Authorization: `Bearer ${attachment.apiToken}` },
    timeout: attachment.timeoutMs ?? 30_000,
    proxy: false,
    maxRedirects: 0,
    maxContentLength: MAX_RESPONSE_BYTES,
    maxBodyLength: 32 * 1024,
    validateStatus: () => true,
  });
  return async <T>(body: object, options?: { signal?: AbortSignal }) => {
    let response: { status: number; data: unknown };
    try {
      response = await client.post(
        "/api/v2/context/search",
        body,
        options?.signal ? { signal: options.signal } : undefined,
      );
    } catch {
      return { state: "unavailable" as const, code: "transport_failed" };
    }
    if (response.status === 200) {
      return { state: "ok" as const, data: response.data as T };
    }
    if (response.status === 401 || response.status === 403) {
      return { state: "denied" as const, code: `http_${response.status}` };
    }
    if (response.status === 404) {
      return { state: "not_found" as const, code: "http_404" };
    }
    return {
      state: "unavailable" as const,
      code: unavailableCode(response.data, response.status),
    };
  };
}

export function isReadOnlyPath(path: string): boolean {
  if ((READ_ONLY_PATHS as readonly string[]).includes(path)) return true;
  if (IMPORT_JOB.test(path)) return true;
  if (OPERATION_RECEIPT.test(path)) return true;
  if (MEMORY_ADDITION.test(path)) return true;
  if (EVOLVE_RUN.test(path)) return true;
  if (!SDK_MEMORY_DETAIL.test(path)) return false;
  const segment = path.slice("/api/v2/memories/".length);
  return !(RESERVED_MEMORY_SEGMENTS as readonly string[]).includes(segment);
}

/** A write accepted by the unified Memory Server entry.
 *
 * `request_id` is the idempotency key: Core keys the write on it, so a retry
 * with the same id and the same messages is answered from the first write, and
 * the same id with different messages is refused (409). A retry without the
 * original id is a new write.
 */
export interface MemoryWriteReceipt {
  request_id: string;
  state: string;
  created_at: string;
  updated_at: string;
  detail?: string;
  raw_ids?: string[];
  memory_ids?: string[];
}

export interface OpenAIMessage {
  role: "user" | "assistant" | "tool";
  content: string;
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === "object" && !Array.isArray(value);
}

export function parseOpenAIMessages(value: unknown): OpenAIMessage[] | null {
  const candidate = Array.isArray(value)
    ? value
    : isRecord(value) && Array.isArray(value.messages)
      ? value.messages
      : null;
  if (candidate === null || candidate.length < 1 || candidate.length > 200)
    return null;
  const messages: OpenAIMessage[] = [];
  for (const item of candidate) {
    if (!isRecord(item)) return null;
    if (!["user", "assistant", "tool"].includes(String(item.role))) return null;
    if (
      typeof item.content !== "string" ||
      item.content.length < 1 ||
      item.content.length > 12_000
    )
      return null;
    messages.push({
      role: item.role as OpenAIMessage["role"],
      content: item.content,
    });
  }
  return messages.some((message) => message.role === "user") ? messages : null;
}

/** A6: submit a write through the durable entry every entry shares.
 *
 * The CLI is one of several doors (MCP, scanner, hooks); all land in the same
 * queue. Nothing here calls HY directly.
 */
/** The attachment the CLI gets from Runtime discovery.
 *
 * Named here rather than importing `RuntimeAttachment`, so this module stays
 * usable in tests that fake discovery without importing runtime-control.
 */
export interface RuntimeAttachmentLike {
  readonly host: string;
  readonly port: number;
  readonly apiToken: string;
}

function baseUrlOf(attachment: RuntimeAttachmentLike): string {
  return `http://${attachment.host}:${attachment.port}`;
}

export type MemoryWriteOutcome =
  | { state: "accepted"; receipt: MemoryWriteReceipt }
  | { state: "rejected"; code: string; http_status: number }
  | { state: "unknown"; code: string };

export async function submitMemoryWrite(
  attachment: RuntimeAttachmentLike,
  request: {
    session: string;
    source: string;
    request_id: string;
    messages: readonly OpenAIMessage[];
    memory_at?: string;
    priority?: "live" | "normal";
    /** Whose memory this is. Omitted for the default user (`local`). */
    user_id?: string;
  },
): Promise<MemoryWriteOutcome> {
  let response: { status: number; data: unknown };
  try {
    response = await axios.post<MemoryWriteReceipt>(
      `${baseUrlOf(attachment)}/api/v2/memory-writes`,
      {
        request_id: request.request_id,
        session_id: request.session,
        source_id: request.source,
        messages: [...request.messages],
        ...(request.memory_at === undefined
          ? {}
          : { memory_at: request.memory_at }),
        ...(request.priority === undefined
          ? {}
          : { priority: request.priority }),
        ...(request.user_id === undefined || request.user_id === "local"
          ? {}
          : { user_id: request.user_id }),
      },
      {
        headers: { Authorization: `Bearer ${attachment.apiToken}` },
        timeout: 15_000,
        proxy: false,
        maxRedirects: 0,
        maxContentLength: MAX_RESPONSE_BYTES,
        validateStatus: () => true,
      },
    );
  } catch {
    // The request may or may not have reached Core; the same request id makes
    // a retry safe.
    return { state: "unknown", code: "transport_result_unknown" };
  }
  if (response.status >= 200 && response.status < 300) {
    return { state: "accepted", receipt: response.data as MemoryWriteReceipt };
  }
  if (response.status >= 400 && response.status < 500) {
    return {
      state: "rejected",
      code: detailCode(response.data, response.status),
      http_status: response.status,
    };
  }
  return { state: "unknown", code: `http_${response.status}_result_unknown` };
}

/** Ask Runtime to scan one source now, returning the import job it started.
 *
 * Returns null when the source cannot be synced (`live_sync_unavailable`, HTTP
 * 409). That is a property of the source, not a transport failure, so the
 * caller reports it as "not synced" rather than "the command failed".
 */
export async function submitScan(
  attachment: RuntimeAttachmentLike,
  sourceId: string,
): Promise<ScanJob | null> {
  const response = await axios.post<ScanJob>(
    `${baseUrlOf(attachment)}/api/v1/sources/${encodeURIComponent(sourceId)}/sync`,
    undefined,
    {
      headers: { Authorization: `Bearer ${attachment.apiToken}` },
      timeout: 15_000,
      proxy: false,
      maxRedirects: 0,
      maxContentLength: MAX_RESPONSE_BYTES,
      validateStatus: () => true,
    },
  );
  if (response.status === 409) return null;
  if (response.status >= 400) {
    throw new Error(`scan_rejected http_${response.status}`);
  }
  return response.data;
}

/** The import job a scan starts. Only the fields the CLI reports. */
export interface ScanJob {
  readonly job_id: string;
  readonly source_id: string;
  readonly status: string;
}

/** Ask Runtime to copy its committed database to `target`.
 *
 * The server decides the final path; the CLI reports what it was told, rather
 * than assuming its own argument survived unchanged.
 */
export async function submitBackup(
  attachment: RuntimeAttachmentLike,
  target: string,
): Promise<BackupResult> {
  const response = await axios.post<BackupResult>(
    `${baseUrlOf(attachment)}/api/v1/backup`,
    { target },
    {
      headers: { Authorization: `Bearer ${attachment.apiToken}` },
      timeout: 120_000,
      proxy: false,
      maxRedirects: 0,
      maxContentLength: MAX_RESPONSE_BYTES,
      validateStatus: () => true,
    },
  );
  if (response.status === 422) {
    throw new Error("backup_target_outside_data_dir");
  }
  if (response.status >= 400) {
    throw new Error(`backup_rejected http_${response.status}`);
  }
  return response.data;
}

export interface BackupResult {
  readonly target: string;
  readonly bytes: number;
}

/** Ask Runtime to delete a model profile.
 *
 * Returns false when the server refused: 404 for an unknown id, 409 for the
 * profile that is currently active. Those are properties of the profile, not
 * transport failures, so the caller distinguishes them rather than throwing.
 */
export async function deleteModelProfile(
  attachment: RuntimeAttachmentLike,
  profileId: string,
): Promise<boolean> {
  const response = await axios.delete(
    `${baseUrlOf(attachment)}/api/v1/model-profiles/${encodeURIComponent(profileId)}`,
    {
      headers: { Authorization: `Bearer ${attachment.apiToken}` },
      timeout: 15_000,
      proxy: false,
      maxRedirects: 0,
      maxContentLength: MAX_RESPONSE_BYTES,
      validateStatus: () => true,
    },
  );
  // The shared classifier is the single judge of "refused because of the
  // profile itself" (404 unknown id / 409 still active) versus a transport
  // failure, preferring Core's stable detail over the bare status. Only the
  // former is a `false`; anything else that is not 2xx must throw rather than
  // look like "already gone".
  const detail = (response.data as { detail?: unknown } | undefined)?.detail;
  const classified = classifyModelRemove(response.status, detail);
  if (classified.state === "refused") return false;
  if (classified.state === "unknown") {
    throw new Error(`model_remove_rejected http_${response.status}`);
  }
  return true;
}

/** Read back a write's outcome, or null when the id was never accepted.
 *
 * Unknown must be distinguishable from failed: "never accepted" and "accepted
 * and failed" lead the caller to different actions.
 */
export async function readMemoryWrite(
  attachment: RuntimeAttachmentLike,
  requestId: string,
  /** A receipt belongs to the user that submitted it; omit for `local`. */
  userId?: string,
): Promise<MemoryWriteReceipt | null> {
  try {
    const response = await axios.get<MemoryWriteReceipt>(
      `${baseUrlOf(attachment)}/api/v2/memory-writes/${encodeURIComponent(requestId)}`,
      {
        ...(userId === undefined || userId === "local"
          ? {}
          : { params: { user_id: userId } }),
        headers: { Authorization: `Bearer ${attachment.apiToken}` },
        timeout: 10_000,
        proxy: false,
        maxRedirects: 0,
        maxContentLength: MAX_RESPONSE_BYTES,
      },
    );
    return response.data;
  } catch (error) {
    if (axios.isAxiosError(error) && error.response?.status === 404)
      return null;
    throw error;
  }
}

export interface OnboardingState {
  status: string;
  selected_source_ids: string[];
  started_at: string | null;
  completed_at: string | null;
}

/** Send onboarding back to its first-run state.
 *
 * Returns null when the endpoint is not there, so an older runtime degrades to
 * "not available" instead of failing the command. Only the completion flag
 * moves: memories, sources and settings live in other tables, which is what
 * makes this the honest way to see the cold-start screens again.
 */
export async function resetOnboarding(
  attachment: RuntimeAttachmentLike,
): Promise<OnboardingState | null> {
  try {
    const response = await axios.post<OnboardingState>(
      `${baseUrlOf(attachment)}/api/v1/onboarding/reset`,
      undefined,
      {
        headers: { Authorization: `Bearer ${attachment.apiToken}` },
        timeout: 15_000,
        proxy: false,
        maxRedirects: 0,
        maxContentLength: MAX_RESPONSE_BYTES,
      },
    );
    return response.data;
  } catch {
    return null;
  }
}

export async function readScanRoots(
  attachment: RuntimeAttachmentLike,
): Promise<{
  schema_version: number;
  revision: number;
  roots: unknown[];
} | null> {
  try {
    const response = await axios.get<{
      schema_version: number;
      revision: number;
      roots: unknown[];
    }>(`${baseUrlOf(attachment)}/api/v1/scan-roots`, {
      headers: { Authorization: `Bearer ${attachment.apiToken}` },
      timeout: 10_000,
      proxy: false,
      maxRedirects: 0,
      maxContentLength: MAX_RESPONSE_BYTES,
    });
    return response.data;
  } catch {
    return null;
  }
}

/** A direct Core write whose refusal carries Core's stable code. */
export type CoreWriteResult =
  | { ok: true; data: unknown }
  | { ok: false; code: string };

async function coreWrite(
  attachment: RuntimeAttachmentLike,
  method: "post" | "delete",
  pathname: string,
  body: Record<string, unknown>,
  timeout = 10_000,
): Promise<CoreWriteResult> {
  let response: { status: number; data: unknown };
  try {
    response = await axios.request({
      method,
      url: `${baseUrlOf(attachment)}${pathname}`,
      data: body,
      headers: { Authorization: `Bearer ${attachment.apiToken}` },
      timeout,
      proxy: false,
      maxRedirects: 0,
      maxContentLength: MAX_RESPONSE_BYTES,
      validateStatus: () => true,
    });
  } catch {
    return { ok: false, code: "transport_failed" };
  }
  if (response.status >= 200 && response.status < 300) {
    return { ok: true, data: response.data };
  }
  return { ok: false, code: detailCode(response.data, response.status) };
}

export async function addScanRoot(
  attachment: RuntimeAttachmentLike,
  body: { root: string; source?: string; recursive?: boolean },
): Promise<CoreWriteResult> {
  return coreWrite(attachment, "post", "/api/v1/scan-roots", body);
}

export async function removeScanRoot(
  attachment: RuntimeAttachmentLike,
  body: { root: string },
): Promise<CoreWriteResult> {
  return coreWrite(attachment, "delete", "/api/v1/scan-roots", body);
}

export async function readAdapters(
  attachment: RuntimeAttachmentLike,
): Promise<{ schema_version: number; adapters: unknown[] } | null> {
  try {
    const response = await axios.get<{
      schema_version: number;
      adapters: unknown[];
    }>(`${baseUrlOf(attachment)}/api/v1/adapters`, {
      headers: { Authorization: `Bearer ${attachment.apiToken}` },
      timeout: 10_000,
      proxy: false,
      maxRedirects: 0,
      maxContentLength: MAX_RESPONSE_BYTES,
    });
    return response.data;
  } catch {
    return null;
  }
}

export async function probeAdapter(
  attachment: RuntimeAttachmentLike,
  source: string,
): Promise<CoreWriteResult> {
  return coreWrite(
    attachment,
    "post",
    "/api/v1/adapters/probe",
    { source },
    15_000,
  );
}