Skip to content
Python
16.7 KB
Raw Blame
import type {
  ImportIssue,
  ImportJob,
  LiveSyncHealth,
  MemoryProcessingSummary,
  SourceResponse,
} from "@one-memory/contracts";
import type { CoreReader, ReadOutcome } from "./core-client.js";
import {
  validateImportIssues,
  validateImportJob,
  validateImportJobs,
  validateLiveSync,
  validateProcessing,
  validateSources,
} from "./core-responses.js";
import {
  describePipeline,
  type PipelineSummary,
  pipelineLine,
} from "./status-report.js";
import { PRODUCT } from "./version.js";

type ReadState =
  | { state: "ok" }
  | {
      state: "denied" | "unavailable" | "not_found" | "invalid" | "not_checked";
      code: string;
    };

const SCHEMA_VERSION = 1;

function sourceTotal(
  sources: SourceResponse[],
  key: "imported_conversations" | "imported_messages",
): number {
  return sources.reduce((total, source) => total + source[key], 0);
}

export interface SourcesDocument {
  schema_version: 1;
  product: string;
  state: ReadState["state"];
  code?: string;
  sources: Array<Record<string, unknown>>;
  /** Every grant of every user (`GET /api/v1/source-grants`). Absent when
   * Core is too old to list them; `sources` is the default user's view. */
  grants?: SourceGrant[];
}

/** One source grant. Only Hermes has grants for users other than `local`,
 * one per Hermes profile root. */
export interface SourceGrant {
  user_id: string;
  source_id: string;
  root_label: string | null;
  root_path: string | null;
  authorized: boolean;
  revoked_at: string | null;
  sync_enabled: boolean;
}

export interface SyncDocument {
  schema_version: 1;
  product: string;
  state: "ok" | "partial" | Exclude<ReadState["state"], "ok">;
  code?: string;
  sources: Array<Record<string, unknown>>;
}

export interface ProgressDocument {
  schema_version: 1;
  product: string;
  state: "ok" | "active" | "partial";
  imports: {
    state: ReadState["state"];
    code?: string;
    totals_state: ReadState;
    imported_conversations: number | null;
    imported_messages: number | null;
    jobs: Array<Record<string, unknown>>;
    issues?: Array<Record<string, unknown>>;
    issues_state?: ReadState;
    returned: number;
    validated: number;
    output_truncated: boolean;
  };
  generation: {
    summary_state: ReadState;
    summary: Record<string, unknown> | null;
  };
  /** The SDK mode and last evolve per user; absent on an older Core. */
  pipeline?: PipelineSummary | null;
}

export async function readSources(
  reader: CoreReader,
): Promise<SourcesDocument> {
  const result = validated(
    await reader<unknown>("/api/v1/sources"),
    validateSources,
  );
  if (result.state !== "ok") {
    return {
      schema_version: SCHEMA_VERSION,
      product: PRODUCT,
      ...result,
      sources: [],
    };
  }
  const grants = await readSourceGrants(reader);
  return {
    schema_version: SCHEMA_VERSION,
    product: PRODUCT,
    state: "ok",
    // `/api/v1/sources` is the default user's view of every source.
    sources: result.data.map((source) => ({
      ...projectSource(source),
      user_id: "local",
    })),
    ...(grants === null ? {} : { grants }),
  };
}

/** The grants of every user, or null when Core cannot list them (an older
 * Core answers 404): the source list is then shown as before. */
async function readSourceGrants(
  reader: CoreReader,
): Promise<SourceGrant[] | null> {
  let outcome: ReadOutcome<unknown>;
  try {
    outcome = await reader<unknown>("/api/v1/source-grants");
  } catch {
    return null;
  }
  if (outcome.state !== "ok") return null;
  const value = outcome.data;
  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
  const items = (value as { grants?: unknown }).grants;
  if (!Array.isArray(items)) return null;
  const grants: SourceGrant[] = [];
  const text = (candidate: unknown): string | null =>
    typeof candidate === "string" && candidate.length <= 4096
      ? candidate
      : null;
  for (const item of items) {
    if (!item || typeof item !== "object" || Array.isArray(item)) return null;
    const grant = item as Record<string, unknown>;
    if (
      typeof grant.user_id !== "string" ||
      !/^[A-Za-z0-9._-]{1,64}$/.test(grant.user_id) ||
      typeof grant.source_id !== "string" ||
      !/^[a-z0-9][a-z0-9-]{0,127}$/.test(grant.source_id) ||
      typeof grant.authorized !== "boolean"
    ) {
      return null;
    }
    grants.push({
      user_id: grant.user_id,
      source_id: grant.source_id,
      root_label: text(grant.root_label),
      root_path: text(grant.root_path),
      authorized: grant.authorized,
      revoked_at: text(grant.revoked_at),
      sync_enabled: grant.sync_enabled === true,
    });
  }
  return grants;
}

export async function readSync(reader: CoreReader): Promise<SyncDocument> {
  const result = validated(
    await reader<unknown>("/api/v1/live-sync"),
    validateLiveSync,
  );
  if (result.state !== "ok") {
    return {
      schema_version: SCHEMA_VERSION,
      product: PRODUCT,
      ...result,
      sources: [],
    };
  }
  const sources = result.data.map(projectSync);
  return {
    schema_version: SCHEMA_VERSION,
    product: PRODUCT,
    state: result.data.some(
      (item) => item.state === "degraded" || item.state === "unavailable",
    )
      ? "partial"
      : "ok",
    sources,
  };
}

export async function readProgress(
  reader: CoreReader,
  options: { jobId?: string; issues: boolean; limit: number },
): Promise<ProgressDocument> {
  const importsPath = options.jobId
    ? `/api/v1/import-jobs/${options.jobId}`
    : "/api/v1/import-jobs";
  // Generation progress comes from `memory-processing` alone: under SDK
  // authority the per-task list (`/api/v1/memory-tasks`) is retired and empty.
  const [importsRead, sourcesRead, processingRead, issuesRead] =
    await Promise.all([
      reader<unknown>(importsPath),
      reader<unknown>("/api/v1/sources"),
      reader<unknown>("/api/v1/memory-processing"),
      options.jobId && options.issues
        ? reader<unknown>(`/api/v1/import-jobs/${options.jobId}/issues`)
        : Promise.resolve(null),
    ]);

  const imports = options.jobId
    ? validated(importsRead, (value) => {
        const job = validateImportJob(value);
        return job && job.job_id === options.jobId ? [job] : null;
      })
    : validated(importsRead, validateImportJobs);
  const processing = validated(processingRead, validateProcessing);
  const sources = validated(sourcesRead, validateSources);
  const issues =
    options.jobId && options.issues && issuesRead
      ? validated(issuesRead, (value) =>
          validateImportIssues(value, options.jobId as string),
        )
      : null;

  const jobs = imports.state === "ok" ? imports.data : [];
  const issueItems = issues?.state === "ok" ? issues.data : [];
  const importState = stateOnly(imports);
  const summaryState = stateOnly(processing);

  const hasReadFailure =
    importState.state !== "ok" ||
    sources.state !== "ok" ||
    summaryState.state !== "ok" ||
    (issues !== null && issues.state !== "ok");
  const hasProblem =
    jobs.some((job) =>
      ["paused", "interrupted", "failed"].includes(job.status),
    ) ||
    (processing.state === "ok" &&
      (processing.data.failed > 0 ||
        processing.data.waiting_for_model > 0 ||
        processing.data.blocked_stages.length > 0)) ||
    issueItems.length > 0;
  const hasActive =
    jobs.some((job) => ["pending", "running"].includes(job.status)) ||
    (processing.state === "ok" &&
      (processing.data.pending > 0 || processing.data.running > 0));

  return {
    schema_version: SCHEMA_VERSION,
    product: PRODUCT,
    state:
      hasReadFailure || hasProblem ? "partial" : hasActive ? "active" : "ok",
    imports: {
      ...importState,
      totals_state: stateOnly(sources),
      imported_conversations:
        sources.state === "ok"
          ? sourceTotal(sources.data, "imported_conversations")
          : null,
      imported_messages:
        sources.state === "ok"
          ? sourceTotal(sources.data, "imported_messages")
          : null,
      jobs: jobs.slice(0, options.limit).map(projectImportJob),
      ...(issues
        ? {
            issues:
              issues.state === "ok"
                ? issues.data.slice(0, options.limit).map(projectImportIssue)
                : [],
            ...(issues.state === "ok"
              ? {}
              : { issues_state: stateOnly(issues) }),
          }
        : {}),
      returned: Math.min(jobs.length, options.limit),
      validated: jobs.length,
      output_truncated:
        jobs.length > options.limit || issueItems.length > options.limit,
    },
    generation: {
      summary_state: summaryState,
      summary:
        processing.state === "ok" ? projectProcessing(processing.data) : null,
    },
    pipeline:
      processingRead.state === "ok"
        ? describePipeline(processingRead.data)
        : null,
  };
}

export function renderSourcesText(document: SourcesDocument): string {
  if (document.state !== "ok") {
    return "暂时无法读取应用连接状态,请确认后台正在运行后重试。\n";
  }
  const lines = [`已发现 ${document.sources.length} 个应用:`];
  for (const source of document.sources) {
    lines.push(
      `- ${source.display_name}:${source.authorized ? "已连接" : source.available ? "可连接" : "未发现"};处理${source.sync_enabled === true ? "已开启" : "已冻结"}`,
      `  已导入 ${source.imported_conversations} 个会话 · ${source.imported_messages} 条消息`,
    );
  }
  if (document.sources.length === 0) lines.push("(没有来源)");
  // The list above is the default user's (`local`). Another user's grant,
  // a Hermes profile, is listed with its user so it is not mistaken for it.
  const others = (document.grants ?? []).filter(
    (grant) => grant.user_id !== "local",
  );
  if (others.length > 0) {
    lines.push("其他用户的连接:");
    for (const grant of others) {
      const name =
        document.sources.find((source) => source.source_id === grant.source_id)
          ?.display_name ?? grant.source_id;
      lines.push(
        `- ${name}(用户 ${grant.user_id}):${grant.authorized ? "已连接" : grant.revoked_at ? "已撤销" : "未连接"};处理${grant.sync_enabled ? "已开启" : "已冻结"}${grant.root_path ? `;目录 ${grant.root_path}` : ""}`,
      );
    }
  }
  lines.push("");
  return lines.join("\n");
}

export function renderSyncText(document: SyncDocument): string {
  if (!["ok", "partial"].includes(document.state)) {
    return `同步状态读取未完成:${document.state}(${document.code})\n`;
  }
  const lines = [`同步状态:${document.state}`];
  for (const source of document.sources) {
    lines.push(
      `- ${source.source_id}  ${source.state}  模式=${source.mode}  最近错误=${source.last_error_code ?? "无"}`,
    );
  }
  if (document.sources.length === 0) lines.push("(没有同步来源)");
  lines.push("");
  return lines.join("\n");
}

export function renderProgressText(document: ProgressDocument): string {
  const lines = [
    document.state === "ok"
      ? "导入与整理已完成。"
      : document.state === "active"
        ? "正在导入和整理,你可以继续使用。"
        : "部分任务需要处理。",
    document.imports.imported_messages === null
      ? "累计导入:暂时无法读取"
      : `累计导入:${document.imports.imported_conversations} 个会话 · ${document.imports.imported_messages} 条消息`,
    `导入任务:${document.imports.validated} 个`,
  ];
  if (document.imports.issues) {
    lines.push(`需要留意的导入记录:${document.imports.issues.length} 条`);
  }
  lines.push(
    document.generation.summary
      ? `记忆整理:待处理 ${document.generation.summary.pending} · 进行中 ${document.generation.summary.running} · 等待模型 ${document.generation.summary.waiting_for_model} · 失败 ${document.generation.summary.failed}`
      : "记忆整理:暂时无法读取",
  );
  if (document.pipeline) {
    lines.push(`记忆模式:${pipelineLine(document.pipeline)}`);
    for (const [userId, user] of Object.entries(
      document.pipeline.evolve_users,
    )) {
      lines.push(
        `  进化 ${userId}:${user.last_run_at ?? "尚未进化"}${
          user.last_error ? `(失败:${user.last_error})` : ""
        }`,
      );
    }
  }
  if (document.imports.output_truncated) {
    lines.push("这里只显示汇总;完整记录请使用 --json。");
  }
  lines.push("");
  return lines.join("\n");
}

export function sourceProgressExitCode(
  document: SourcesDocument | SyncDocument | ProgressDocument,
): number {
  return document.state === "ok" || document.state === "active" ? 0 : 1;
}

export function unreadSources(
  state: Exclude<ReadState["state"], "ok">,
  code: string,
): SourcesDocument {
  return {
    schema_version: SCHEMA_VERSION,
    product: PRODUCT,
    state,
    code,
    sources: [],
  };
}

export function unreadSync(
  state: Exclude<ReadState["state"], "ok">,
  code: string,
): SyncDocument {
  return {
    schema_version: SCHEMA_VERSION,
    product: PRODUCT,
    state,
    code,
    sources: [],
  };
}

export function unreadProgress(
  state: Exclude<ReadState["state"], "ok">,
  code: string,
): ProgressDocument {
  const failed = { state, code } as const;
  return {
    schema_version: SCHEMA_VERSION,
    product: PRODUCT,
    state: "partial",
    imports: {
      ...failed,
      totals_state: failed,
      imported_conversations: null,
      imported_messages: null,
      jobs: [],
      returned: 0,
      validated: 0,
      output_truncated: false,
    },
    generation: {
      summary_state: failed,
      summary: null,
    },
  };
}

function validated<T>(
  outcome: ReadOutcome<unknown>,
  validate: (value: unknown) => T | null,
):
  | { state: "ok"; data: T }
  | { state: Exclude<ReadState["state"], "ok">; code: string } {
  if (outcome.state !== "ok") {
    // A Core refusal of the request itself reads as an invalid answer here.
    const state = outcome.state === "rejected" ? "invalid" : outcome.state;
    return { state, code: outcome.code };
  }
  const data = validate(outcome.data);
  return data === null
    ? { state: "invalid", code: "response_invalid" }
    : { state: "ok", data };
}

function stateOnly(result: { state: string; code?: string }): ReadState {
  return result.state === "ok"
    ? { state: "ok" }
    : {
        state: result.state as Exclude<ReadState["state"], "ok">,
        code: result.code ?? "read_failed",
      };
}

function projectSource(source: SourceResponse): Record<string, unknown> {
  return {
    source_id: source.source_id,
    display_name: source.display_name,
    storage_kinds: source.storage_kinds,
    available: source.available,
    authorized: source.authorized,
    detected: source.detected,
    root_label: source.root_label,
    candidate_kind: source.candidate_kind,
    location_state: source.location_state ?? "unknown",
    imported_messages: source.imported_messages,
    imported_conversations: source.imported_conversations,
    capabilities: source.capabilities,
    sync_completeness: source.sync_completeness,
    sync_enabled: source.sync_enabled,
  };
}

function projectSync(health: LiveSyncHealth): Record<string, unknown> {
  return {
    source_id: health.source_id,
    mode: health.mode,
    state: health.state,
    last_job_id: health.last_job_id,
    last_attempt_at: health.last_attempt_at,
    last_success_at: health.last_success_at,
    last_error_code: health.last_error_code,
  };
}

function projectImportJob(job: ImportJob): Record<string, unknown> {
  return {
    job_id: job.job_id,
    source_id: job.source_id,
    operation: job.operation ?? "history",
    status: job.status,
    phase: job.phase,
    discovered: job.discovered,
    discovered_targets: job.discovered_targets,
    emitted: job.emitted,
    stored: job.stored,
    revised: job.revised,
    merged: job.merged,
    skipped: job.skipped,
    errors: job.errors,
    created_at: job.created_at,
    updated_at: job.updated_at,
  };
}

function projectImportIssue(issue: ImportIssue): Record<string, unknown> {
  return {
    issue_id: issue.issue_id,
    job_id: issue.job_id,
    kind: issue.kind,
    conversation_id: issue.conversation_id,
    reason: issue.reason,
    created_at: issue.created_at,
  };
}

function projectProcessing(
  summary: MemoryProcessingSummary,
): Record<string, unknown> {
  return {
    pending: summary.pending,
    fresh_pending: summary.fresh_pending,
    backlog_pending: summary.backlog_pending,
    outside_window_pending: summary.outside_window_pending,
    running: summary.running,
    waiting_for_model: summary.waiting_for_model,
    completed: summary.completed,
    failed: summary.failed,
    blocked_stages: summary.blocked_stages.map((stage) => ({
      kind: stage.kind,
      reason: stage.reason,
      count: stage.count,
    })),
  };
}