Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

54.3 KB
Raw Blame
import { presentationText, type PresentationLocalizer } from './presentationLocalization.js';
export { splitQuestionReferences } from './questionReferences.js';

export interface InteractionRequestLike {
  kind?: string;
  requestId?: string;
  [key: string]: unknown;
}

export interface PendingInteractionLike {
  /** Local presentation only: an answer already being edited keeps focus. */
  retainedDraft?: boolean;
  request: InteractionRequestLike;
  persistId?: string;
}

export interface AskQuestion {
  question: string;
  header?: string;
  options?: Array<{ label: string; description?: string }>;
  multiSelect?: boolean;
}

/** A late answer is ordinary user input, with the original question attached. */
export function formatAsyncQuestionSupplement(
  questions: readonly AskQuestion[],
  answers: Record<string, string>,
): string {
  const replies = questions.flatMap((q) => {
    const answer = answers[q.question] ?? (q.header ? answers[q.header] : undefined);
    return typeof answer === 'string' && answer.trim()
      ? [{ question: q.question, answer: answer.trim() }] : [];
  });
  return replies.map(({ question, answer }) => `${question.split('\n').map((line) => `> ${line}`).join('\n')}\n\n${answer}`).join('\n\n');
}

/** Only a confirmed cancellation permits delivery as a new user message. A
 * missing pending request alone cannot distinguish expiry from an accepted
 * answer whose receipt was lost (including an answer on another device). */
export async function asyncQuestionNeedsSupplement(
  resolve: () => Promise<{ accepted: boolean } | void>,
  readMessage: () => Promise<unknown>,
  requestId: string,
): Promise<boolean> {
  let timer: ReturnType<typeof setTimeout> | undefined;
  try {
    const receipt = await Promise.race([
      resolve(),
      new Promise<never>((_, reject) => {
        timer = setTimeout(() => reject(new Error('Interaction receipt timeout')), 15_000);
      }),
    ]);
    if (receipt && receipt.accepted === true) return false;
  } catch {
    // Read the original Host row before deciding whether another delivery is safe.
  } finally {
    if (timer) clearTimeout(timer);
  }
  const raw = await readMessage();
  const content = typeof raw === 'string' ? JSON.parse(raw) : raw;
  if (content && typeof content === 'object' && 'requestId' in content && content.requestId === requestId && 'status' in content) {
    if (content.status === 'answered') return false;
    if (content.status === 'cancelled') return true;
  }
  throw new Error('Interaction decision was not confirmed');
}

export interface IssueDraft {
  title: string;
  body: string;
  type: 'bug' | 'feature';
}

export interface IssueEnv {
  appVersion: string;
  platform: string;
  arch: string;
  osVersion?: string;
  harness?: 'Claude Code' | 'Codex' | 'Pi';
  modelId?: string;
}

export interface IssueConfirmPayload {
  draft: IssueDraft;
  env: IssueEnv;
}

export interface PermissionReviewPresentation {
  sourceDescription?: string;
  autoReviewUnavailable: boolean;
  /** Why Auto-review asked; null for ordinary Ask-mode prompts. */
  autoReviewReason: string | null;
  canAlwaysAllow: boolean;
  code: string;
  description: string | null;
  riskSummary: string | null;
  summary: InteractionDecisionSummary;
  title: string;
  toolName: string;
}

export interface AskQuestionReviewPresentation {
  allowsCustomAnswer: boolean;
  current: AskQuestion | null;
  currentIndex: number;
  currentNumber: number;
  header: string | null;
  multiSelect: boolean;
  optionCount: number;
  pageLabel: string;
  summary: InteractionDecisionSummary;
  title: string;
  totalCount: number;
}

export interface IssueConfirmReviewPresentation {
  bodyCharCount: number;
  canSubmit: boolean;
  envLabel: string;
  issueTypeLabel: string;
  summary: InteractionDecisionSummary;
  titleCharCount: number;
}

export interface PlanOutlineItem {
  id: string;
  title: string;
  level: 1 | 2 | 3;
  line: number;
  preview: string;
}

export interface PlanReviewEvidencePresentation {
  compactPath: string | null;
  fileName: string | null;
  filePath: string | null;
  hasPlanText: boolean;
  outlineItems: PlanOutlineItem[];
  outlineOverflowCount: number;
  outlineTotalCount: number;
  summary: InteractionDecisionSummary;
}

export interface InteractionDecisionSummary {
  title: string;
  detail: string;
}

export interface InteractionResolveActionPresentation {
  disabled: boolean;
  disabledReason: string | null;
  label: string;
}

export interface PendingInteractionQueueItemPresentation {
  active: boolean;
  kind: string;
  label: string;
  positionLabel: string;
  requestId: string | null;
  title: string;
}

export interface PendingInteractionQueuePresentation {
  active: PendingInteractionQueueItemPresentation | null;
  countLabel: string;
  hint: string;
  items: PendingInteractionQueueItemPresentation[];
  overflowCount: number;
  readOnly: boolean;
  title: string;
  totalCount: number;
}

export function buildInteractionResolveActionPresentation(input: {
  armed?: boolean;
  busy?: boolean;
  busyLabel?: string;
  confirmLabel?: string;
  invalidReason?: string | null;
  label: string;
  readOnlyReason?: string | null;
  requestId?: string | null;
}, localizer?: PresentationLocalizer): InteractionResolveActionPresentation {
  if (input.readOnlyReason) {
    return {
      disabled: true,
      disabledReason: input.readOnlyReason,
      label: input.label,
    };
  }
  if (!input.requestId) {
    return {
      disabled: true,
      disabledReason: presentationText(localizer, 'interaction.panel.missingRequestId', '这个远程交互缺少 requestId,无法回传决定。'),
      label: input.label,
    };
  }
  if (input.busy) {
    return {
      disabled: true,
      disabledReason: presentationText(localizer, 'interaction.panel.submittingHint', '正在把决定回传到电脑端,请不要重复提交。'),
      label: input.busyLabel
        ?? presentationText(localizer, 'interaction.presentation.action.submitting', '提交中'),
    };
  }
  if (input.invalidReason) {
    return {
      disabled: true,
      disabledReason: input.invalidReason,
      label: input.label,
    };
  }
  return {
    disabled: false,
    disabledReason: null,
    label: input.armed && input.confirmLabel ? input.confirmLabel : input.label,
  };
}

export function canStartInteractionResolve(input: {
  requestId?: string | null;
  submittingRequestId?: string | null;
}): boolean {
  return !!input.requestId && input.submittingRequestId !== input.requestId;
}

export function buildPermissionDecisionSummary(input: {
  toolName: string;
  riskSummary: string | null;
  canAlwaysAllow: boolean;
}, localizer?: PresentationLocalizer): InteractionDecisionSummary {
  if (input.riskSummary) {
    return {
      title: presentationText(localizer, 'interaction.presentation.permission.highRiskTitle', '高风险授权需要二次确认'),
      detail: presentationText(localizer, 'interaction.presentation.permission.highRiskDetail', '先核对命令内容,再点一次确认允许;不确定就拒绝。'),
    };
  }
  if (input.canAlwaysAllow) {
    return {
      title: presentationText(localizer, 'interaction.presentation.permission.sessionAllowTitle', '可以只允许一次,也可以本任务总是允许'),
      detail: presentationText(localizer, 'interaction.presentation.permission.tool', `工具: ${input.toolName}`, { tool: input.toolName }),
    };
  }
  return {
    title: presentationText(localizer, 'interaction.presentation.permission.allowTitle', '允许后电脑端会继续执行'),
    detail: presentationText(localizer, 'interaction.presentation.permission.tool', `工具: ${input.toolName}`, { tool: input.toolName }),
  };
}

export function buildPermissionReviewPresentation(
  request: InteractionRequestLike,
  localizer?: PresentationLocalizer,
): PermissionReviewPresentation {
  const toolName = permissionToolName(request);
  const input = permissionInput(request);
  const riskSummary = permissionRiskSummary(request, localizer);
  const canAlwaysAllow = sessionScopedPermissionSuggestions(request.suggestions).length > 0;
  const sourceDescription = permissionSourceDescription(request);
  let description = permissionDescription(request);
  // IM retains its combined body; UI titles must describe the operation only.
  if (sourceDescription && description?.startsWith(sourceDescription)) {
    if (description === sourceDescription) description = null;
    else if (description.startsWith(`${sourceDescription}\n\n`)) {
      description = readString(description.slice(sourceDescription.length + 2));
    }
  }

  return {
    autoReviewUnavailable: permissionAutoReviewUnavailable(request),
    autoReviewReason: permissionAutoReviewUnavailable(request) ? null : permissionAutoReviewReason(request),
    ...(sourceDescription ? { sourceDescription } : {}),
    canAlwaysAllow,
    code: formatPermissionInput(toolName, input),
    description,
    riskSummary,
    summary: buildPermissionDecisionSummary({ toolName, riskSummary, canAlwaysAllow }, localizer),
    title: permissionTitle(request, localizer),
    toolName,
  };
}

export function buildAskQuestionProgressSummary(input: {
  currentIndex: number;
  total: number;
  multiSelect: boolean;
}, localizer?: PresentationLocalizer): InteractionDecisionSummary {
  const total = Math.max(1, input.total);
  const current = Math.min(Math.max(0, input.currentIndex), total - 1) + 1;
  return {
    title: presentationText(localizer, 'interaction.presentation.ask.progress', `第 ${current}/${total} 个问题`, {
      current,
      total,
    }),
    detail: input.multiSelect
      ? presentationText(localizer, 'interaction.presentation.ask.multiSelect', '可多选,也可以输入其他回答。')
      : presentationText(localizer, 'interaction.presentation.ask.singleSelect', '选择一个回答,或输入其他回答。'),
  };
}

export function buildAskQuestionReviewPresentation(input: {
  currentIndex: number;
  questions: readonly AskQuestion[];
}, localizer?: PresentationLocalizer): AskQuestionReviewPresentation {
  const totalCount = input.questions.length;
  if (totalCount === 0) {
    return {
      allowsCustomAnswer: false,
      current: null,
      currentIndex: 0,
      currentNumber: 0,
      header: null,
      multiSelect: false,
      optionCount: 0,
      pageLabel: '0/0',
      summary: {
        title: presentationText(localizer, 'interaction.presentation.ask.emptyTitle', '没有具体问题'),
        detail: presentationText(localizer, 'interaction.presentation.ask.emptyDetail', '可以提交空回答让电脑端继续。'),
      },
      title: presentationText(localizer, 'interaction.presentation.ask.waiting', 'Agent 正在等待确认'),
      totalCount: 0,
    };
  }

  const currentIndex = Math.min(Math.max(0, input.currentIndex), totalCount - 1);
  const current = input.questions[currentIndex] ?? null;
  const multiSelect = current?.multiSelect === true;
  const optionCount = current?.options?.length ?? 0;
  const currentNumber = currentIndex + 1;

  return {
    allowsCustomAnswer: true,
    current,
    currentIndex,
    currentNumber,
    header: current?.header?.trim() || null,
    multiSelect,
    optionCount,
    pageLabel: `${currentNumber}/${totalCount}`,
    summary: buildAskQuestionProgressSummary({
      currentIndex,
      total: totalCount,
      multiSelect,
    }, localizer),
    title: current?.question
      || presentationText(localizer, 'interaction.presentation.ask.waiting', 'Agent 正在等待确认'),
    totalCount,
  };
}

export function buildPlanReviewDecisionSummary(input: {
  outlineCount: number;
  hasFilePath: boolean;
  edited: boolean;
}, localizer?: PresentationLocalizer): InteractionDecisionSummary {
  const outline = input.outlineCount > 0
    ? presentationText(localizer, 'interaction.presentation.plan.outlineCount', `${input.outlineCount} 个章节`, { count: input.outlineCount })
    : presentationText(localizer, 'interaction.presentation.plan.noOutline', '无章节目录');
  const file = input.hasFilePath
    ? presentationText(localizer, 'interaction.presentation.plan.hasFile', '有计划文件')
    : presentationText(localizer, 'interaction.presentation.plan.noFile', '无计划文件路径');
  return {
    title: input.edited
      ? presentationText(localizer, 'interaction.presentation.plan.editedTitle', '已编辑计划,批准后按当前版本执行')
      : presentationText(localizer, 'interaction.presentation.plan.approveTitle', '批准后电脑端会按计划继续执行'),
    detail: `${outline} · ${file}`,
  };
}

export function buildPlanReviewEvidencePresentation(input: {
  edited: boolean;
  filePath?: string | null;
  maxOutlineItems?: number;
  plan: string;
}, localizer?: PresentationLocalizer): PlanReviewEvidencePresentation {
  const outline = extractPlanOutline(input.plan);
  const maxOutlineItems = Math.max(0, Math.floor(input.maxOutlineItems ?? 3));
  const filePath = input.filePath?.trim() || null;
  const outlineItems = maxOutlineItems === 0 ? [] : outline.slice(0, maxOutlineItems);

  return {
    compactPath: filePath ? compactPlanReviewPath(filePath) : null,
    fileName: filePath ? basenameFromPath(filePath) : null,
    filePath,
    hasPlanText: input.plan.trim().length > 0,
    outlineItems,
    outlineOverflowCount: Math.max(0, outline.length - outlineItems.length),
    outlineTotalCount: outline.length,
    summary: buildPlanReviewDecisionSummary({
      edited: input.edited,
      hasFilePath: !!filePath,
      outlineCount: outline.length,
    }, localizer),
  };
}

export function buildIssueConfirmDecisionSummary(input: {
  type: IssueDraft['type'];
  canSubmit: boolean;
}): InteractionDecisionSummary {
  return {
    title: input.canSubmit ? '草稿完整,可以确认提交' : '补齐标题和正文后才能提交',
    detail: input.type === 'bug' ? '类型: Bug' : '类型: Feature',
  };
}

export function buildIssueConfirmReviewPresentation(input: {
  draft: IssueDraft;
  env: IssueEnv;
  uiLanguage?: string;
}): IssueConfirmReviewPresentation {
  const title = input.draft.title.trim();
  const body = input.draft.body.trim();
  const canSubmit = title.length > 0 && body.length > 0;
  const envParts = [
    input.env.appVersion,
    input.env.platform,
    input.env.arch,
    input.env.osVersion,
    input.env.harness,
    input.env.modelId,
    input.uiLanguage,
  ].filter((part): part is string => typeof part === 'string' && part.trim().length > 0);

  return {
    bodyCharCount: body.length,
    canSubmit,
    envLabel: envParts.join(' / '),
    issueTypeLabel: input.draft.type === 'bug' ? 'Bug' : 'Feature',
    summary: buildIssueConfirmDecisionSummary({
      type: input.draft.type,
      canSubmit,
    }),
    titleCharCount: title.length,
  };
}

export function interactionKind(item: PendingInteractionLike): string {
  return typeof item.request.kind === 'string' ? item.request.kind : 'interaction';
}

export function interactionDisplayTitle(kind: string, localizer?: PresentationLocalizer): string {
  const known = ['plan_review', 'permission', 'ask_user_question', 'issue_confirm', 'plugin_setup', 'input_handoff'];
  const key = known.includes(kind) ? kind : 'fallback';
  const fallback: Record<string, string> = {
    plan_review: '需要确认执行计划',
    permission: '需要授权电脑端操作',
    ask_user_question: '需要回答 Agent 问题',
    issue_confirm: '需要确认 Issue 内容',
    plugin_setup: '需要在电脑端配置插件',
    input_handoff: '需要你代为输入',
    fallback: '需要处理远程请求',
  };
  return presentationText(localizer, `interaction.kinds.${key}.title`, fallback[key]);
}

export function interactionDisplayHint(
  kind: string,
  readOnly = false,
  localizer?: PresentationLocalizer,
): string {
  if (readOnly) {
    return presentationText(localizer, 'interaction.presentation.queue.readOnlyHint', '协同只读模式,仅展示电脑端请求。');
  }
  const fallback: Record<string, string> = {
    plan_review: '先看计划,必要时反馈修改,确认后电脑端才继续执行。',
    permission: '只把本次决定回传给当前电脑端任务。',
    ask_user_question: '回答会保存草稿,提交后电脑端继续。',
    issue_confirm: '确认标题和正文后再提交。',
    plugin_setup: '配置要在电脑端完成,这里可以取消这次请求。',
    fallback: '手机版会按桌面端的请求顺序处理。',
  };
  const key = Object.prototype.hasOwnProperty.call(fallback, kind) ? kind : 'fallback';
  return presentationText(localizer, `interaction.presentation.queue.hint.${key}`, fallback[key]);
}

export function interactionKindLabel(kind: string, localizer?: PresentationLocalizer): string {
  const known = ['plan_review', 'permission', 'ask_user_question', 'issue_confirm', 'plugin_setup', 'input_handoff'];
  const key = known.includes(kind) ? kind : 'fallback';
  const fallback: Record<string, string> = {
    plan_review: '计划',
    permission: '授权',
    ask_user_question: '问题',
    issue_confirm: 'Issue',
    plugin_setup: '插件',
    input_handoff: '代输入',
    fallback: '请求',
  };
  return presentationText(localizer, `interaction.kinds.${key}.label`, fallback[key]);
}

/**
 * 控制端(手机 / 另一台桌面)对一张待处理交互卡实际能做什么。
 *
 * 被控桌面会把**所有** pending interaction 经 device-link 推给控制端,但控制端
 * 能给出终局决定的只有权限 / 提问 / 计划三类。其余必须回被控端完成:
 * plugin_setup 的 run_action 要开 OAuth 或写可信本地设置(被控端 IPC 边界只放
 * cancel 过来,见 desktop `interactionResolveOrigin`),issue_confirm 只在桌面提交。
 *
 * - `resolvable`:控制端能终结这张卡。
 * - `cancel-only`:控制端做不完,但能取消,把会话从等待里放出来。
 * - `desktop-only`:控制端只能展示,等被控端处理。
 */
export type RemoteInteractionHandling = 'resolvable' | 'cancel-only' | 'desktop-only';

const REMOTE_RESOLVABLE_KINDS = new Set(['permission', 'ask_user_question', 'plan_review']);

export function remoteInteractionHandling(item: PendingInteractionLike): RemoteInteractionHandling {
  const kind = interactionKind(item);
  if (REMOTE_RESOLVABLE_KINDS.has(kind)) return 'resolvable';
  // 代输入: the controller fills each step through the signed per-step channel
  // and sends value-less decisions (done / cancel / stay / refresh) through resolve.
  if (kind === 'input_handoff') return item.request.terminal === true ? 'desktop-only' : 'resolvable';
  // `cancel-only` 必须与 buildPluginSetupCancelDecision 判定一致,否则调用方只看
  // handling 就以为「能取消」,而实际拿不到 decision(#530 review):
  // - terminal 快照是被控端收尾展示用的最后一帧,已经不 actionable;
  // - revision 缺失 / 非法时被控端无法裁决这条命令,也就没有取消入口。
  if (kind === 'plugin_setup' && item.request.terminal !== true
    && pluginSetupCancelRevision(item.request) !== null) {
    return 'cancel-only';
  }
  return 'desktop-only';
}

/**
 * 这张卡是否有资格独占控制端输入框。
 *
 * 只有控制端能终结的卡才可以——控制端做不完的卡若也替换输入框,用户既处理不了
 * 卡、又发不出消息,整个会话在手机上被锁死(只能回电脑端解),这是必须避免的
 * 死锁:任何被控端新增的 interaction kind 默认都落进「不阻塞」这一侧。
 */
export function interactionBlocksRemoteComposer(item: PendingInteractionLike | null | undefined): boolean {
  // 代输入 is a Host-owned wait that outlives the turn; the owner keeps the composer.
  if (item && interactionKind(item) === 'input_handoff') return false;
  return !!item && remoteInteractionHandling(item) === 'resolvable';
}

/**
 * 输入框是否该被这一批待处理卡接管。
 *
 * 判据必须是**整个 pending 集合**,不能是「当前正在看的那张卡」:队列里同时有
 * 权限卡和 plugin_setup 时,用户切到 plugin_setup 只是换了查看对象,那张权限卡
 * 仍在等回答 —— 若按当前卡放开 composer,用户就绕过了仍待处理的阻塞交互
 * (#530 review P1)。只有整批都是本端终结不了的卡时,输入框才回来。
 */
export function pendingInteractionsBlockRemoteComposer(
  interactions: readonly PendingInteractionLike[],
): boolean {
  return interactions.some((item) => interactionBlocksRemoteComposer(item));
}

/**
 * plugin_setup 的远端取消决定。
 *
 * 被控端只接受 `expectedRevision` 与当前快照一致的命令(不一致 = 控制端看到的是
 * 旧快照,被控端会改为重新体检并推新快照),因此 revision 缺失时不构造决定——
 * 调用方据此不给取消入口,而不是发一条注定被丢弃的命令。
 */
export function buildPluginSetupCancelDecision(
  request: InteractionRequestLike,
): { kind: 'plugin_setup'; action: 'cancel'; expectedRevision: number } | null {
  const revision = pluginSetupCancelRevision(request);
  if (revision === null) return null;
  return { kind: 'plugin_setup', action: 'cancel', expectedRevision: revision };
}

/**
 * 可用于取消命令的 revision;不是 plugin_setup、或 revision 缺失 / 非法时为 null。
 * 被控端要求 `expectedRevision` 是非负整数(见 parseGhostSetupInteractionCommand)。
 */
function pluginSetupCancelRevision(request: InteractionRequestLike): number | null {
  if (request.kind !== 'plugin_setup') return null;
  const revision = request.revision;
  if (typeof revision !== 'number' || !Number.isInteger(revision) || revision < 0) return null;
  return revision;
}

/**
 * 被控端 setup 步骤的稳定枚举。
 *
 * 这里是**副本**,不是从 Desktop import 的(packages 不得依赖 apps)。正本在
 * `apps/desktop/src/shared/ghost.ts`(`GhostSetupStepPhase` /
 * `GHOST_SETUP_ERROR_CODES` / `GhostSetupActionKind`),两端由跨端契约绑定:
 * 正本增删值时必须同步这里,否则控制端会把新值当未知丢弃(降级展示,不会崩)。
 */
export const REMOTE_PLUGIN_SETUP_PHASES = [
  'pending',
  'action_running',
  'waiting_external',
  'verifying',
  'satisfied',
  'failed',
  'cancelled',
] as const;
export type RemotePluginSetupPhase = (typeof REMOTE_PLUGIN_SETUP_PHASES)[number];

export const REMOTE_PLUGIN_SETUP_ERROR_CODES = [
  'ACTION_FAILED',
  'ACTION_STALE',
  'AUTH_CANCELLED',
  'AUTH_FAILED',
  'AUTH_NETWORK',
  'AUTH_SERVICE_UNAVAILABLE',
  'INLINE_INVALID',
  'INLINE_UNAVAILABLE',
  'SAVE_FAILED',
  'WINDOW_CLOSED',
  'TARGET_UNAVAILABLE',
  'ASSESSMENT_FAILED',
  'TIMEOUT',
] as const;
export type RemotePluginSetupErrorCode = (typeof REMOTE_PLUGIN_SETUP_ERROR_CODES)[number];

export const REMOTE_PLUGIN_SETUP_ACTION_KINDS = [
  'oauth_connect',
  'open_plugin_settings',
  'manage_connection',
  'open_client_settings',
  'inline_form',
] as const;
export type RemotePluginSetupActionKind = (typeof REMOTE_PLUGIN_SETUP_ACTION_KINDS)[number];

export interface RemotePluginSetupStep {
  id: string;
  title: string;
  description: string | null;
  /** 非白名单值(被控端更新引入的新 phase)降级为 null,只是少显示一个徽标。 */
  phase: RemotePluginSetupPhase | null;
  errorCode: RemotePluginSetupErrorCode | null;
  actionKind: RemotePluginSetupActionKind | null;
  /**
   * inline_form 字段的**标签**,用于说明「电脑端要填什么」。
   * 只有 label,永远没有值:Secret 不进 interaction snapshot(见
   * `docs/dev-rules/plugin-security-and-authoring.md` §4)。
   */
  inlineFieldLabel: string | null;
}

export interface RemotePluginSetupGroup {
  id: string;
  /** any_of 且组内不止一项 → UI 要提示「选择一种配置方式」,别让用户以为要全做。 */
  anyOf: boolean;
  steps: RemotePluginSetupStep[];
}

export interface RemotePluginSetupPresentation {
  ghostName: string | null;
  /** 只接受 data:image/ 的内联图标;其它形态(远程 URL 等)一律丢弃。 */
  iconDataUrl: string | null;
  intro: string | null;
  groups: RemotePluginSetupGroup[];
  satisfiedCount: number;
  stepCount: number;
  /** 被控端已 settle 的收尾帧:不再 actionable,UI 不给可点动作。 */
  terminal: boolean;
}

/**
 * plugin_setup 卡在控制端的**只读**投影。
 *
 * 控制端不渲染表单、也不触发动作(Secret 输入与 OAuth 都必须留在被控端,见
 * plugin-security-and-authoring.md §4 与 desktop 的 interactionResolveOrigin),
 * 但被控端下发的状态信息足以让用户看懂「哪个插件、卡在哪一步、为什么失败、
 * 回电脑端要做什么」,再决定是去电脑端处理还是取消。
 *
 * 入参来自远端 payload,一律按白名单收敛:未知 phase / errorCode / action kind
 * 降级为 null 而不是原样透传,避免把被控端新版本的值直接喂给文案查表。
 */
export function buildRemotePluginSetupPresentation(
  request: InteractionRequestLike,
): RemotePluginSetupPresentation {
  const empty: RemotePluginSetupPresentation = {
    ghostName: null,
    iconDataUrl: null,
    intro: null,
    groups: [],
    satisfiedCount: 0,
    stepCount: 0,
    terminal: false,
  };
  // 作为导出的 shared API 显式挡住误用:换个 kind 传进来时返回空投影,而不是
  // 从任意 request 上刮字段、让调用错误看起来「正常返回」。
  if (request.kind !== 'plugin_setup') return empty;

  const ghost = isPlainRecord(request.ghost) ? request.ghost : null;
  const rawSteps = Array.isArray(request.steps) ? request.steps : [];
  const groups: RemotePluginSetupGroup[] = [];
  const groupsById = new Map<string, RemotePluginSetupGroup>();
  let satisfiedCount = 0;
  let stepCount = 0;

  rawSteps.forEach((rawStep, index) => {
    if (!isPlainRecord(rawStep)) return;
    const title = trimmedOrNull(rawStep.title);
    if (!title) return;
    const phase = pickFromAllowlist(rawStep.phase, REMOTE_PLUGIN_SETUP_PHASES);
    const action = isPlainRecord(rawStep.action) ? rawStep.action : null;
    const actionKind = pickFromAllowlist(action?.kind, REMOTE_PLUGIN_SETUP_ACTION_KINDS);
    const step: RemotePluginSetupStep = {
      id: trimmedOrNull(rawStep.id) ?? `step-${index}`,
      title,
      description: trimmedOrNull(rawStep.description),
      phase,
      errorCode: pickFromAllowlist(rawStep.errorCode, REMOTE_PLUGIN_SETUP_ERROR_CODES),
      actionKind,
      inlineFieldLabel: actionKind === 'inline_form' ? inlineSecretFieldLabel(action) : null,
    };
    stepCount += 1;
    if (phase === 'satisfied') satisfiedCount += 1;

    // 分组按首次出现顺序保留。
    const rawGroupId = trimmedOrNull(rawStep.groupId);
    if (rawGroupId === null) {
      // 缺 groupId 的步骤各自成组,并且**不进 groupsById**:合成的 id 与被控端真实
      // groupId 共用一个命名空间,一旦撞名(远端某组恰好就叫合成出来的那个名字),
      // 两批互不相关的配置要求会被并成一组、还套上 any_of 语义,让用户以为「二选
      // 一」而漏做另一半(#657 review)。生成身份只用于本地展示,不参与查表。
      groups.push({ id: `ungrouped-${index}`, anyOf: false, steps: [step] });
      return;
    }
    const existing = groupsById.get(rawGroupId);
    if (existing) {
      existing.steps.push(step);
      if (rawStep.groupMode === 'any_of') existing.anyOf = true;
      return;
    }
    const group: RemotePluginSetupGroup = {
      id: rawGroupId,
      anyOf: rawStep.groupMode === 'any_of',
      steps: [step],
    };
    groupsById.set(rawGroupId, group);
    groups.push(group);
  });

  return {
    ghostName: trimmedOrNull(ghost?.name),
    iconDataUrl: inlineImageDataUrl(ghost?.iconDataUrl),
    intro: trimmedOrNull(request.intro),
    // 单项组没有「任选其一」的语义,提示只会让用户困惑。
    groups: dedupeGroupIds(groups).map((group) => ({
      ...group,
      anyOf: group.anyOf && group.steps.length > 1,
    })),
    satisfiedCount,
    stepCount,
    terminal: request.terminal === true,
  };
}

/**
 * 保证组 id 在本次投影内唯一(渲染层拿它当 list key)。
 *
 * 合成的 `ungrouped-*` 已经不参与合并,但仍可能与被控端某个真实 groupId 撞名;
 * 那只是展示身份重复,不该退化成重复 key。id 不回传被控端,改写是安全的。
 */
function dedupeGroupIds(groups: RemotePluginSetupGroup[]): RemotePluginSetupGroup[] {
  const used = new Set<string>();
  return groups.map((group) => {
    let id = group.id;
    for (let suffix = 2; used.has(id); suffix += 1) id = `${group.id}-${suffix}`;
    used.add(id);
    return id === group.id ? group : { ...group, id };
  });
}

function trimmedOrNull(value: unknown): string | null {
  if (typeof value !== 'string') return null;
  const trimmed = value.trim();
  return trimmed.length > 0 ? trimmed : null;
}

function pickFromAllowlist<T extends string>(value: unknown, allowed: readonly T[]): T | null {
  return typeof value === 'string' && (allowed as readonly string[]).includes(value)
    ? (value as T)
    : null;
}

function inlineSecretFieldLabel(action: Record<string, unknown> | null): string | null {
  const form = isPlainRecord(action?.form) ? action.form : null;
  const fields = Array.isArray(form?.fields) ? form.fields : [];
  const first = fields.length > 0 && isPlainRecord(fields[0]) ? fields[0] : null;
  return trimmedOrNull(first?.label);
}

function inlineImageDataUrl(value: unknown): string | null {
  return typeof value === 'string' && value.startsWith('data:image/') ? value : null;
}

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

export function buildPendingInteractionQueuePresentation(
  interactions: readonly PendingInteractionLike[],
  options: {
    maxVisible?: number;
    readOnly?: boolean;
  } = {},
  localizer?: PresentationLocalizer,
): PendingInteractionQueuePresentation {
  const sorted = sortPendingInteractions(interactions);
  const totalCount = sorted.length;
  const maxVisible = Math.max(1, options.maxVisible ?? 4);
  const readOnly = options.readOnly === true;
  const items = sorted.slice(0, maxVisible).map((item, index) => {
    const kind = interactionKind(item);
    return {
      active: index === 0,
      kind,
      label: interactionKindLabel(kind, localizer),
      positionLabel: interactionPositionLabel(index, localizer),
      requestId: readRequestId(item),
      title: interactionDisplayTitle(kind, localizer),
    };
  });
  const active = items[0] ?? null;
  const activeKind = active?.kind ?? 'interaction';

  return {
    active,
    countLabel: totalCount > 1
      ? presentationText(localizer, 'interaction.presentation.queue.count', `${totalCount} 个`, { count: totalCount })
      : presentationText(localizer, 'interaction.panel.queuePositionCurrent', '当前'),
    hint: interactionDisplayHint(activeKind, readOnly, localizer),
    items,
    overflowCount: Math.max(0, totalCount - items.length),
    readOnly,
    title: active
      ? active.title
      : presentationText(localizer, 'interaction.presentation.queue.empty', '没有待处理请求'),
    totalCount,
  };
}

const INTERACTION_PRIORITY: Record<string, number> = {
  plan_review: 0,
  permission: 1,
  ask_user_question: 2,
  issue_confirm: 3,
  // 控制端做不完的卡排在能处理的卡之后,免得它抢走 active 位、把用户按在一张
  // 只能回电脑端处理的卡上(手机侧另有不阻塞输入框的兜底,见
  // interactionBlocksRemoteComposer)。
  plugin_setup: 4,
  // Answerable on the controller, but never ahead of a question the turn is blocked on.
  input_handoff: 3,
};

export function interactionPriority(item: PendingInteractionLike): number {
  return INTERACTION_PRIORITY[interactionKind(item)] ?? 100;
}

export function sortPendingInteractions(
  interactions: readonly PendingInteractionLike[],
): PendingInteractionLike[] {
  return interactions
    .map((item, index) => ({ item, index }))
    .sort((a, b) => Number(b.item.retainedDraft === true) - Number(a.item.retainedDraft === true)
      || interactionPriority(a.item) - interactionPriority(b.item) || a.index - b.index)
    .map(({ item }) => item);
}

export function selectActivePendingInteraction(
  interactions: readonly PendingInteractionLike[],
): PendingInteractionLike | null {
  return sortPendingInteractions(interactions)[0] ?? null;
}

export function readRequestId(item: PendingInteractionLike): string | null {
  const requestId = item.request.requestId;
  return typeof requestId === 'string' && requestId.length > 0 ? requestId : null;
}

function interactionPositionLabel(index: number, localizer?: PresentationLocalizer): string {
  if (index === 0) return presentationText(localizer, 'interaction.panel.queuePositionCurrent', '当前');
  if (index === 1) return presentationText(localizer, 'interaction.panel.queuePositionNext', '接着');
  return presentationText(localizer, 'interaction.panel.queuePositionNth', `第 ${index + 1}`, {
    index: index + 1,
  });
}

/** What a permission card asks about, independent of harness tool naming. */
export type PermissionActionKind = 'command' | 'file-read' | 'file-write' | 'plugin' | 'browser' | 'tool';

export interface PermissionActionSummary {
  kind: PermissionActionKind;
  /** Plugin or MCP server the call goes to, when known. */
  subject?: string;
  /** The exact operation in readable form: command line, paths, or arguments. */
  preview: string;
}

const COMMAND_TOOLS = new Set(['bash', 'powershell', 'exec', 'shell', 'run_command', 'local_shell']);
const FILE_READ_TOOLS = new Set(['read', 'glob', 'grep', 'find', 'ls']);
const FILE_WRITE_TOOLS = new Set(['edit', 'write', 'multiedit', 'notebookedit', 'file_change', 'apply_patch', 'patch']);

function previewOf(value: unknown): string {
  const text = typeof value === 'string' ? value : stringifyCompact(value);
  return text.length > 500 ? `${text.slice(0, 500)}...` : text;
}

/** Progressive `call_tool.args` may arrive as a JSON string (issue #350); approval parses it the same way. */
function argsObject(value: unknown): Record<string, unknown> {
  if (typeof value === 'string') {
    try { value = JSON.parse(value); } catch { return {}; }
  }
  return isRecord(value) ? value : {};
}

/** One-line arguments after the tool name; empty when there are none. */
function argsPreview(args: Record<string, unknown>): string {
  if (!Object.keys(args).length) return '';
  const text = JSON.stringify(args) ?? '';
  return text.length > 500 ? `${text.slice(0, 500)}...` : text;
}

/** `mcp__server__tool` or `mcp:server:tool`; plain string scan, no backtracking on model-controlled names. */
function parseMcpToolName(toolName: string): { server: string; tool: string } | null {
  const rest = toolName.startsWith('mcp__') ? toolName.slice(5) : toolName.startsWith('mcp:') ? toolName.slice(4) : null;
  if (!rest) return null;
  const underscore = rest.indexOf('__');
  const colon = rest.indexOf(':');
  const cut = underscore < 0 ? colon : colon < 0 ? underscore : Math.min(underscore, colon);
  if (cut <= 0) return null;
  const sepLength = rest.startsWith('__', cut) ? 2 : 1;
  const server = rest.slice(0, cut);
  const tool = rest.slice(cut + sepLength);
  return tool ? { server, tool } : null;
}

function shellQuote(arg: string): string {
  return /^[A-Za-z0-9_\/.:=@%+,-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
}

function commandText(input: Record<string, unknown>): string | null {
  const command = input.command ?? input.cmd;
  if (typeof command === 'string' && command.trim()) return command;
  // argv arrays: quote each element so "one value with a space" and "two values" stay distinguishable.
  if (Array.isArray(command) && command.length > 0 && command.every((part) => typeof part === 'string')) {
    return command.map(shellQuote).join(' ');
  }
  return null;
}

function filePaths(input: Record<string, unknown>, search: boolean): string | null {
  const path = readString(input.file_path) ?? readString(input.path) ?? readString(input.notebook_path);
  // A search reads everything under its path: show the query and where it looks.
  const query = search ? readString(input.pattern) ?? readString(input.query) : null;
  const direct = query ? (path ? `${query} \u2192 ${path}` : query) : path;
  if (direct) return direct;
  const changes = Array.isArray(input.changes) ? input.changes : isRecord(input.changes) ? Object.keys(input.changes) : [];
  const lines = changes.map((change) => {
    if (typeof change === 'string') return change;
    if (!isRecord(change) || !readString(change.path)) return null;
    // Keep what distinguishes delete / update / move and the patch itself.
    const kind = isRecord(change.kind) ? readString(change.kind.type) : readString(change.kind);
    const move = isRecord(change.kind) ? readString(change.kind.move_path) : null;
    const head = `${kind ? `${kind} ` : ''}${change.path}${move ? ` \u2192 ${move}` : ''}`;
    const diff = readString(change.diff);
    return diff ? `${head}\n${diff}` : head;
  }).filter((line): line is string => !!line);
  if (!lines.length) return null;
  const text = lines.join('\n');
  return text.length > 500 ? `${text.slice(0, 500)}...` : text;
}

/** Browser step: the action plus every other argument, so recipes, typed text and sites stay visible. */
function browserStep(args: Record<string, unknown>): string {
  const action = readString(args.action);
  if (!action) return previewOf(args);
  const { action: _action, ...rest } = args;
  return [action, argsPreview(rest)].filter(Boolean).join(' ');
}

/**
 * Classify a permission request so every surface can say in plain words what is
 * being confirmed. Unknown tools keep their name and compact JSON arguments.
 */
export function describePermissionAction(toolName: string, input: Record<string, unknown>): PermissionActionSummary {
  const name = toolName.toLowerCase();
  // Progressive MCP dispatchers: mcp__server__call_tool / mcp:server:call_tool → inner tool.
  const innerName = readString(input.name);
  const innerArgs = argsObject(input.args);
  if (name.includes('browser') || innerName === 'browser') {
    return { kind: 'browser', preview: browserStep(innerName === 'browser' ? innerArgs : input) };
  }
  if (/(^|[_:])ghost_call$/.test(name) && readString(input.ghost_id)) {
    // ghost_call { tool: 'call_tool', args: { name, args } } dispatches one level deeper.
    const tool = readString(input.tool);
    const dispatched = tool === 'call_tool' && readString(innerArgs.name);
    const call = dispatched || tool;
    const args = dispatched ? argsObject(innerArgs.args) : innerArgs;
    return { kind: 'plugin', subject: readString(input.ghost_id)!, preview: [call, argsPreview(args)].filter(Boolean).join(' ') || previewOf(input) };
  }
  if (COMMAND_TOOLS.has(name)) {
    const command = commandText(input);
    // The same relative command in two repositories is not the same operation: keep the cwd.
    const cwd = readString(input.cwd) ?? readString(input.workdir);
    if (command) return { kind: 'command', preview: cwd ? `${command}\n# cwd: ${cwd}` : command };
  }
  if (FILE_READ_TOOLS.has(name) || FILE_WRITE_TOOLS.has(name)) {
    const paths = filePaths(input, FILE_READ_TOOLS.has(name) && name !== 'read');
    if (paths) return { kind: FILE_READ_TOOLS.has(name) ? 'file-read' : 'file-write', preview: paths };
  }
  const mcp = parseMcpToolName(toolName);
  if (mcp) {
    const dispatched = mcp.tool === 'call_tool' && innerName;
    const args = dispatched ? innerArgs : input;
    return { kind: 'plugin', subject: mcp.server, preview: [dispatched || mcp.tool, argsPreview(args)].filter(Boolean).join(' ') };
  }
  return { kind: 'tool', preview: previewOf(input) };
}

export function formatPermissionInput(toolName: string, input: Record<string, unknown>): string {
  return describePermissionAction(toolName, input).preview;
}

export function permissionTitle(
  request: InteractionRequestLike,
  localizer?: PresentationLocalizer,
): string {
  // Harness titles are often English or name an internal tool ("exec"); say what happens instead.
  const action = describePermissionAction(permissionToolName(request), permissionInput(request));
  if (action.kind === 'plugin' && action.subject) {
    return presentationText(localizer, 'interaction.presentation.permission.titlePlugin', `允许使用插件「${action.subject}」?`, { plugin: action.subject });
  }
  if (action.kind !== 'tool' && action.kind !== 'plugin') {
    const key = { command: 'titleCommand', 'file-read': 'titleFileRead', 'file-write': 'titleFileWrite', browser: 'titleBrowser' }[action.kind];
    const fallback = { command: '允许运行这条命令?', 'file-read': '允许读取文件?', 'file-write': '允许修改文件?', browser: '允许浏览器执行这一步?' }[action.kind];
    return presentationText(localizer, `interaction.presentation.permission.${key}`, fallback);
  }
  const explicit = readString(request.title);
  if (explicit) return explicit;
  const displayName = readString(request.displayName);
  const toolName = readString(request.toolName) || 'tool';
  const tool = displayName || toolName;
  return presentationText(localizer, 'interaction.presentation.permission.title', `允许使用 ${tool}?`, { tool });
}

export function permissionSourceDescription(request: InteractionRequestLike): string | null {
  const metadata = request.metadata;
  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) return null;
  const source = (metadata as Record<string, unknown>).imSourceDescription;
  return typeof source === 'string' ? source : null;
}

export function permissionDescription(request: InteractionRequestLike): string | null {
  return readString(request.description);
}

/** Auto-review's own explanation for asking (metadata.autoReviewReason), shown as the card's "why". */
export function permissionAutoReviewReason(request: InteractionRequestLike): string | null {
  return isRecord(request.metadata) ? readString(request.metadata.autoReviewReason) : null;
}

export function permissionAutoReviewUnavailable(request: InteractionRequestLike): boolean {
  return isRecord(request.metadata) && request.metadata.autoReviewUnavailable === true;
}

export function permissionToolName(request: InteractionRequestLike): string {
  return readString(request.toolName) || 'Tool';
}

export function permissionInput(request: InteractionRequestLike): Record<string, unknown> {
  return isRecord(request.input) ? request.input : {};
}

export function permissionRiskSummary(
  request: InteractionRequestLike,
  localizer?: PresentationLocalizer,
): string | null {
  const action = describePermissionAction(permissionToolName(request), permissionInput(request));
  if (action.kind !== 'command') return null;
  const command = action.preview.trim();
  if (!command) return null;
  if (!isHighRiskShellCommand(command)) return null;
  return presentationText(localizer, 'interaction.presentation.permission.risk', '这个命令可能修改系统、仓库或外部服务状态。允许前请确认你信任当前任务和命令内容。');
}

export function sessionScopedPermissionSuggestions(suggestions: unknown): unknown[] {
  if (!Array.isArray(suggestions)) return [];
  return suggestions.filter((suggestion) =>
    isRecord(suggestion) && suggestion.destination === 'session'
  );
}

export function buildPermissionDecision(
  behavior: 'allow' | 'deny',
  opts: {
    reason?: string;
    updatedInput?: Record<string, unknown>;
    permissionUpdates?: unknown[];
  } = {},
): Record<string, unknown> {
  return {
    kind: 'permission',
    behavior,
    updatedInput: opts.updatedInput,
    reason: opts.reason,
    permissionUpdates: opts.permissionUpdates && opts.permissionUpdates.length > 0
      ? opts.permissionUpdates
      : undefined,
  };
}

function isHighRiskShellCommand(command: string): boolean {
  return /(^|[;&|]\s*)(sudo|rm\s+-[^\n;|&]*r|git\s+reset\s+--hard|git\s+push|curl\b[^\n|]*\|\s*(sh|bash)|wget\b[^\n|]*\|\s*(sh|bash)|chmod\s+-R|chown\s+-R|pkill|killall)\b/i
    .test(command);
}

export function normalizeAskQuestions(value: unknown): AskQuestion[] {
  if (!Array.isArray(value)) return [];
  return value.flatMap((item) => {
    if (!isRecord(item)) return [];
    const question = readString(item.question);
    if (!question) return [];
    const options = Array.isArray(item.options)
      ? item.options.flatMap((option) => {
        if (!isRecord(option)) return [];
        const label = readString(option.label);
        if (!label) return [];
        const description = readString(option.description);
        return [{ label, ...(description ? { description } : {}) }];
      })
      : undefined;
    return [{
      question,
      header: readString(item.header) ?? undefined,
      options,
      multiSelect: item.multiSelect === true,
    }];
  });
}

export function answerKey(question: AskQuestion): string {
  return question.question;
}

export function encodeMultiSelectAnswer(
  options: readonly { label: string }[],
  selectedLabels: ReadonlySet<string>,
  customInput: string,
): string {
  const parts = options
    .filter((option) => selectedLabels.has(option.label))
    .map((option) => option.label);
  const custom = customInput.trim();
  if (custom) parts.push(custom);
  return JSON.stringify(parts);
}

export function selectionFromAnswer(question: AskQuestion, answer: string | undefined): {
  selectedLabels: Set<string>;
  customInput: string;
  showCustomInput: boolean;
} {
  const options = question.options ?? [];
  const optionLabels = new Set(options.map((option) => option.label));
  if (!answer) {
    return { selectedLabels: new Set(), customInput: '', showCustomInput: false };
  }
  if (question.multiSelect) {
    try {
      const parsed = JSON.parse(answer);
      if (Array.isArray(parsed)) {
        const labels = parsed.filter((item): item is string => typeof item === 'string');
        const custom = labels.find((label) => !optionLabels.has(label)) ?? '';
        return {
          selectedLabels: new Set(labels.filter((label) => optionLabels.has(label))),
          customInput: custom,
          showCustomInput: custom.length > 0,
        };
      }
    } catch {
      return { selectedLabels: new Set(), customInput: '', showCustomInput: false };
    }
  }
  if (!optionLabels.has(answer)) {
    return { selectedLabels: new Set(), customInput: answer, showCustomInput: true };
  }
  return { selectedLabels: new Set([answer]), customInput: '', showCustomInput: false };
}

/**
 * Option labels that are really the model's own "none of these fit" escape
 * hatch. Claude Code's native AskUserQuestion prompt tells the model not to add
 * an "Other" option (the host UI provides a free-text entry automatically), but
 * harnesses whose tool schema carries no such note still produce labels like
 * "其他(回复说明)" or "Other (please specify)".
 *
 * A host question card must replace such an option with its own free-text
 * entry instead of rendering (and submitting) the literal label: the model wrote
 * the option expecting the user's explanation, so receiving only the label back
 * reads as an empty answer. See `visibleAskOptions`.
 *
 * Only a leading "other"-style token is recognized, so labels that merely
 * mention an explanation inside a substantive choice (e.g. "sensor_height 要改
 * (回复说明数值)" or "其他任务") are not escape hatches and stay selectable.
 */
export function isFreeTextAskOptionLabel(label: string): boolean {
  const normalized = label.trim().toLowerCase();
  if (!normalized) return false;
  // "Other" / "Other (please specify)" / "其他(回复说明)" are escape hatches;
  // "Other tasks" / "その他の質問" are substantive options. A bare space must not
  // count as the boundary — only end-of-label or a separator/parenthesis does.
  return /^(?:其他(?:答案|选项)?|其它(?:答案|选项)?|other|others|something else|その他|기타)(?=$|\s*[((【[::,,、.。\-—-…])/.test(normalized);
}

/**
 * Options one host question card should render.
 *
 * Model-authored free-text entries are dropped: they mean the same thing as the
 * host's own "type your own answer" row, so rendering both would show duplicate
 * escape hatches and let a click submit the placeholder label as an answer. The
 * host row is the single entry that remains (it also covers the case where the
 * filtered list becomes empty — callers fall back to free-form input).
 */
export function visibleAskOptions<T extends { label: string }>(options: readonly T[] | undefined): T[] {
  return (options ?? []).filter((option) => !isFreeTextAskOptionLabel(option.label));
}

export function buildAskUserQuestionDecision(answers: Record<string, string>): Record<string, unknown> {
  return { kind: 'ask_user_question', answers };
}

export function planReviewPlan(request: InteractionRequestLike): string {
  return readString(request.plan) ?? '';
}

export function planReviewFilePath(request: InteractionRequestLike): string {
  return readString(request.planFilePath) ?? '';
}

export function buildPlanReviewDecision(
  approved: boolean,
  plan: string,
  feedback?: string,
): Record<string, unknown> {
  const trimmedFeedback = feedback?.trim() ?? '';
  return {
    kind: 'plan_review',
    behavior: approved ? 'allow' : 'deny',
    editedPlan: approved ? plan : undefined,
    reason: approved ? undefined : trimmedFeedback || undefined,
  };
}

/**
 * Strip an optional ATX closing sequence from a heading title ("## Title ##" → "Title"):
 * trailing whitespace, then a '#' run, then the whitespace separating it from the title.
 *
 * Linear replacement for `value.replace(/\s+#+\s*$/, '')` — that regex backtracks
 * polynomially on uncontrolled heading text with long whitespace runs (CodeQL ReDoS). Like
 * the original, the '#' run is only stripped when it is whitespace-separated from the title,
 * so text such as "Title##" is preserved.
 */
function stripAtxHeadingClosing(value: string): string {
  const isWs = (ch: string) => /\s/.test(ch);
  let end = value.length;
  while (end > 0 && isWs(value[end - 1])) end -= 1;
  const afterTrailingWs = end;
  while (end > 0 && value[end - 1] === '#') end -= 1;
  if (end === afterTrailingWs) return value; // no '#' run → leave for the caller's trim()
  if (end === 0 || !isWs(value[end - 1])) return value; // '#'s not whitespace-separated → keep
  while (end > 0 && isWs(value[end - 1])) end -= 1;
  return value.slice(0, end);
}

export function extractPlanOutline(markdown: string): PlanOutlineItem[] {
  const lines = markdown.split(/\r?\n/);
  const items: PlanOutlineItem[] = [];
  let fenceMarker: '```' | '~~~' | null = null;

  for (let index = 0; index < lines.length; index += 1) {
    const line = lines[index];
    const fence = readFenceMarker(line);
    if (fenceMarker) {
      if (fence === fenceMarker) fenceMarker = null;
      continue;
    }
    if (fence) {
      fenceMarker = fence;
      continue;
    }

    // `\s+(\S.*)` (not `\s+(.+)`) keeps the separator and title char-classes disjoint so the
    // match stays linear — `\s+` vs `.+` overlap on whitespace and CodeQL flags it as a
    // polynomial ReDoS. The title is trimmed below, so requiring a non-space first char is fine.
    const match = /^(#{1,3})\s+(\S.*)$/.exec(line);
    if (!match) continue;
    const title = stripAtxHeadingClosing(match[2]).trim();
    if (!title) continue;
    const lineNumber = index + 1;
    items.push({
      id: `plan-heading-${lineNumber}`,
      title,
      level: match[1].length as 1 | 2 | 3,
      line: lineNumber,
      preview: readHeadingPreview(lines, index + 1),
    });
  }

  return items;
}

export function normalizeIssueConfirm(request: InteractionRequestLike): IssueConfirmPayload | null {
  if (!isRecord(request.draft)) return null;
  const title = readString(request.draft.title);
  const body = readString(request.draft.body);
  const type = request.draft.type === 'feature' ? 'feature' : request.draft.type === 'bug' ? 'bug' : null;
  if (!title || !body || !type) return null;
  const env = isRecord(request.env) ? request.env : {};
  return {
    draft: { title, body, type },
    env: {
      appVersion: readString(env.appVersion) ?? 'unknown',
      platform: readString(env.platform) ?? 'unknown',
      arch: readString(env.arch) ?? 'unknown',
      osVersion: readString(env.osVersion) ?? undefined,
      harness: readIssueHarness(env.harness),
      modelId: normalizeIssueModelId(env.modelId),
    },
  };
}

function readIssueHarness(value: unknown): IssueEnv['harness'] {
  return value === 'Claude Code' || value === 'Codex' || value === 'Pi' ? value : undefined;
}

function normalizeIssueModelId(value: unknown): string | undefined {
  if (typeof value !== 'string') return undefined;
  const normalized = value.trim().replace(/\s+/g, ' ').slice(0, 200).trim();
  return normalized || undefined;
}

export function buildIssueConfirmDecision(
  confirmed: true,
  draft: IssueDraft,
  uiLanguage?: string,
): Record<string, unknown>;
export function buildIssueConfirmDecision(
  confirmed: false,
): Record<string, unknown>;
export function buildIssueConfirmDecision(
  confirmed: boolean,
  draft?: IssueDraft,
  uiLanguage = currentUiLanguage(),
): Record<string, unknown> {
  if (!confirmed || !draft) return { confirmed: false };
  return {
    confirmed: true,
    title: draft.title.trim(),
    body: draft.body.trim(),
    type: draft.type,
    uiLanguage,
  };
}

export function currentUiLanguage(): string {
  try {
    return Intl.DateTimeFormat().resolvedOptions().locale || 'zh-CN';
  } catch {
    return 'zh-CN';
  }
}

function stringifyCompact(value: unknown): string {
  return JSON.stringify(value, null, 2);
}

function readHeadingPreview(lines: string[], startIndex: number): string {
  let fenceMarker: '```' | '~~~' | null = null;
  for (let index = startIndex; index < lines.length; index += 1) {
    const line = lines[index];
    const fence = readFenceMarker(line);
    if (fenceMarker) {
      if (fence === fenceMarker) fenceMarker = null;
      continue;
    }
    if (fence) {
      fenceMarker = fence;
      continue;
    }
    if (/^#{1,6}\s+/.test(line)) return '';
    const trimmed = line.trim();
    if (!trimmed) continue;
    return trimmed.length > 80 ? `${trimmed.slice(0, 80)}...` : trimmed;
  }
  return '';
}

function compactPlanReviewPath(filePath: string): string {
  const normalized = filePath.trim();
  if (normalized.length <= 42) return normalized;
  const name = basenameFromPath(normalized);
  if (name.length >= 36) return `...${name.slice(-36)}`;
  return `.../${name}`;
}

function basenameFromPath(filePath: string): string {
  const parts = filePath.split(/[\\/]+/).filter(Boolean);
  return parts[parts.length - 1] ?? filePath;
}

function readFenceMarker(line: string): '```' | '~~~' | null {
  const match = /^\s{0,3}(```|~~~)/.exec(line);
  return match ? match[1] as '```' | '~~~' : null;
}

function readString(value: unknown): string | null {
  return typeof value === 'string' && value.length > 0 ? value : null;
}

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