UHD_Media_Tool/apps/web/app/api/agent.ts

import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import {
  AgentGoalReport,
  AgentRun,
  AgentRunDetail,
  type AgentRunEvent,
  type AgentRunMessage,
  AgentRunMode,
  type AgentRunStatus,
  agentRunEventFromRow,
  cursorPage,
} from "@umt/contracts";
import { MOCK_RUNS, mockCreateRun, mockDetail, mockEventsAfter } from "~/components/agent/mock.ts";
import { TTL_SECOND } from "~/lib/api.ts";
import { apiMutate, apiParsed, cleanParams } from "./parse.ts";
import { useSettings } from "./settings.ts";

// Agent 会话(W2-D:GET/POST /agent/runs、GET /agent/runs/{id}?afterSeq=、/messages、/abort),
// 形状一律取 contracts(AgentRun / AgentRunDetail / AgentGoalReport)。
// ?mock=1(或 VITE_AGENT_MOCK=1)只作演示开关:不连后端,用本地假数据预览交互;
// 仅开发构建或后端 pi.provider = "fake" 时生效,生产构建连真实模型时忽略(见 agentMockAllowed)。

export const AGENT_BASE = "/api/v1/agent/runs";

/** 运行模式:execute = 授权内执行;plan_only = 只调查出方案,不执行写能力 */
export const AgentMode = AgentRunMode;
export type AgentMode = AgentRunMode;

export type AgentRunView = AgentRun;
/** 服务端从业务表汇总的目标完成度(不采信模型文本) */
export const GoalReport = AgentGoalReport;
export type GoalReport = AgentGoalReport;
export type RunMessage = AgentRunMessage;
export type RunDetail = AgentRunDetail;
export type RunSnapshot = Omit<RunDetail, "events" | "nextAfterSeq">;

const RunPage = cursorPage(AgentRun);

/**
 * 演示开关是否可用:只在开发构建(import.meta.env.DEV)或后端 pi.provider = "fake"(脚本化假模型)时生效。
 * 生产构建连着真实模型时一律忽略 ?mock=1 / VITE_AGENT_MOCK,并清掉 sessionStorage 里记住的开关,
 * 避免把演示数据当成真实运行展示(验收 S7 / AT78)。
 */
export function agentMockAllowed(o: { dev: boolean; provider?: string | null | undefined }): boolean {
  return o.dev || o.provider === "fake";
}

interface MockFlagStore {
  getItem(k: string): string | null;
  setItem(k: string, v: string): void;
  removeItem(k: string): void;
}

const MOCK_KEY = "umt-agent-mock";

/** 纯函数:按是否允许、构建期开关、URL 参数与会话存储决定是否进演示模式(单测覆盖) */
export function resolveAgentMock(o: {
  allowed: boolean;
  envFlag?: string | undefined;
  search: string;
  storage?: MockFlagStore | null;
}): boolean {
  if (!o.allowed) {
    try {
      o.storage?.removeItem(MOCK_KEY);
    } catch {
      // 存储不可用时无事可清
    }
    return false;
  }
  if (o.envFlag === "1") return true;
  const p = new URLSearchParams(o.search);
  try {
    if (!o.storage) return p.get("mock") === "1";
    if (p.get("mock") === "1") o.storage.setItem(MOCK_KEY, "1");
    if (p.get("mock") === "0") o.storage.removeItem(MOCK_KEY);
    return o.storage.getItem(MOCK_KEY) === "1";
  } catch {
    return p.get("mock") === "1";
  }
}

/** 最近一次读到的后端 pi.provider 是否为 fake(由 useAgentMockGate 从 /settings 缓存同步) */
let fakeProvider = false;

export function agentMockEnabled(): boolean {
  if (typeof window === "undefined") return false;
  let storage: MockFlagStore | null = null;
  try {
    storage = window.sessionStorage;
  } catch {
    storage = null;
  }
  return resolveAgentMock({
    allowed: agentMockAllowed({ dev: import.meta.env.DEV, provider: fakeProvider ? "fake" : null }),
    envFlag: import.meta.env.VITE_AGENT_MOCK,
    search: window.location.search,
    storage,
  });
}

/** Agent 页的列表/详情 hook 里调用:同步后端 provider,再判断演示开关 */
function useAgentMockGate(): boolean {
  const settings = useSettings();
  fakeProvider = settings.data?.pi?.provider === "fake";
  return agentMockEnabled();
}

export const agentKeys = {
  all: ["agent"] as const,
  runs: (status?: AgentRunStatus) => ["agent", "list", status ?? "all"] as const,
  run: (id: string) => ["agent", "detail", id] as const,
};

const RUNNING: AgentRunStatus[] = ["queued", "running", "waiting"];
export const isRunActive = (s: AgentRunStatus | undefined) => !!s && RUNNING.includes(s);

export function useAgentRuns(status?: AgentRunStatus) {
  const mock = useAgentMockGate();
  return useInfiniteQuery({
    queryKey: [...agentKeys.runs(status), mock],
    initialPageParam: undefined as string | undefined,
    queryFn: async ({ pageParam, signal }) => {
      if (mock) return { items: MOCK_RUNS().filter((r) => !status || r.status === status), nextCursor: null };
      return apiParsed(RunPage, AGENT_BASE, { params: cleanParams({ status, cursor: pageParam, limit: 30 }), signal });
    },
    getNextPageParam: (last) => last.nextCursor ?? undefined,
    refetchInterval: (q) =>
      q.state.data?.pages.some((p) => p.items.some((r) => isRunActive(r.status))) ? 5 * TTL_SECOND : false,
  });
}

/** 取一个足够大的 afterSeq,只拿 run / 追加消息 / 目标汇报,不拉事件(事件由 useAgentStream 增量读) */
const NO_EVENTS = 2 ** 31 - 1;

export function useAgentRun(id: string | undefined) {
  const mock = useAgentMockGate();
  return useQuery({
    queryKey: [...agentKeys.run(id ?? ""), mock],
    enabled: !!id,
    queryFn: async ({ signal }): Promise<RunSnapshot> => {
      if (mock) return mockDetail(id ?? "");
      const d = await apiParsed(AgentRunDetail, `${AGENT_BASE}/:id`, {
        pathParams: { id: id ?? "" },
        params: { afterSeq: NO_EVENTS, limit: 1 },
        signal,
      });
      return { run: d.run, messages: d.messages, report: d.report };
    },
    refetchInterval: (q) => (isRunActive(q.state.data?.run.status) ? 3 * TTL_SECOND : false),
  });
}

/** 事件回放:after 为已拿到的最大 seq(-1 = 从头);按 nextAfterSeq 翻页直到最新 */
export async function fetchRunEvents(id: string, after: number, signal?: AbortSignal): Promise<AgentRunEvent[]> {
  if (agentMockEnabled()) return mockEventsAfter(id, after);
  const out: AgentRunEvent[] = [];
  let cursor = after;
  for (let page = 0; page < 20; page++) {
    const d = await apiParsed(AgentRunDetail, `${AGENT_BASE}/:id`, {
      pathParams: { id },
      params: { afterSeq: cursor, limit: 500 },
      signal,
    });
    for (const row of d.events) {
      try {
        out.push(agentRunEventFromRow(row));
      } catch {
        // 未知/不合法事件跳过,不让一条坏事件打断整段回放
      }
    }
    if (d.nextAfterSeq === null || d.nextAfterSeq <= cursor) break;
    cursor = d.nextAfterSeq;
  }
  return out;
}

export function useCreateAgentRun() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: async (input: { goal: string; mode: AgentMode }) => {
      if (agentMockEnabled()) return mockCreateRun(input.goal, input.mode);
      return apiMutate(AGENT_BASE, { body: { goal: input.goal, mode: input.mode } }).then((d) => AgentRun.parse(d));
    },
    onSuccess: () => qc.invalidateQueries({ queryKey: agentKeys.all }),
  });
}

export function useAbortAgentRun() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: async (id: string) => {
      if (agentMockEnabled()) return mockDetail(id, { abort: true }).run;
      return apiMutate(`${AGENT_BASE}/:id/abort`, { pathParams: { id }, body: { reason: "用户在控制台中止" } }).then(
        (d) => AgentRun.parse(d),
      );
    },
    onSuccess: () => qc.invalidateQueries({ queryKey: agentKeys.all }),
  });
}

export function useAppendAgentMessage() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: async ({ id, text }: { id: string; text: string }) => {
      if (agentMockEnabled()) return mockDetail(id, { append: text }).run;
      return apiMutate(`${AGENT_BASE}/:id/messages`, { pathParams: { id }, body: { text } }).then((d) =>
        AgentRun.parse(d),
      );
    },
    onSuccess: (_d, v) => qc.invalidateQueries({ queryKey: agentKeys.run(v.id) }),
  });
}

export const RUN_STATUS_LABEL: Record<AgentRunStatus, string> = {
  queued: "排队中",
  running: "运行中",
  waiting: "等待中",
  succeeded: "已完成",
  failed: "失败",
  cancelled: "已中止",
  budget_exceeded: "超出预算",
};

export const RUN_STATUS_TONE: Record<AgentRunStatus, "success" | "warning" | "destructive" | "neutral"> = {
  queued: "neutral",
  running: "neutral",
  waiting: "warning",
  succeeded: "success",
  failed: "destructive",
  cancelled: "neutral",
  budget_exceeded: "warning",
};

export const REPORT_STATE: Record<
  GoalReport["state"],
  { label: string; tone: "success" | "warning" | "destructive" | "neutral" }
> = {
  no_actions: { label: "没有产生业务动作", tone: "neutral" },
  waiting: { label: "已提交,等待下载/入库", tone: "warning" },
  completed: { label: "已核验入库", tone: "success" },
  partial: { label: "部分完成", tone: "warning" },
  failed: { label: "未达成", tone: "destructive" },
};