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。

16.2 KB
Raw Blame
/**
 * remoteCollabHandoff —— device-link 远程会话**开启协同**的执行与终态判定(issue #1170)。
 * ---------------------------------------------------------------------------
 * device-link 项目的 Lead / Worker / team 真身都在被控端,控制端只是镜像。围绕
 * 「草稿开了协同」这件事,三轮 review 收敛出两条方向相反的时序约束:
 *
 *   ① **首轮必须排在协同之后** —— 否则用户开了协同,首轮 Lead 却没有 cindy_orca 工具。
 *   ② **提交点之后不得插入远程等待** —— 被控端 `maker:create-session` 返回 sessionId
 *      那一刻就是提交点;此后每多一步 await,「对端会话已建好、用户输入还只在内存里」的
 *      窗口就长一分。而本函数是一次隧道往返,可能一路走到 invoke 默认 30s 超时。
 *
 * 两者只能靠**把等待挪到导航之后**同时满足:草稿路由登记完 `setPending` /
 * `setPendingGoal`(载荷带上 `remoteCollab`)就立刻 navigate;`CCAgentSessionView`
 * 消费 pending 时先 await 本函数、再发首轮 / 起目标。于是新建页不卡、用户输入已经交到
 * 会话视图手里,而首轮仍由同一个 await 串在协同之后。
 *
 * 另外两条不变量:
 *   · **隧道超时不是权威失败** —— 超时只删掉控制端的等待项,被控端那次 enableOrca 仍在跑
 *     (device-link ipc.ts 对 INVOKE_TIMEOUT 的既有判定就是「远端仍存活」)。所以超时后要
 *     回查被控端 DB 的权威终态再定性,查不到才 fail-closed 降级。
 *   · **镜像回流绝不能 await** —— `refreshRemoteDeviceSessions` 对瞬态错误有最长约 6.75 秒
 *     的退避重试。协同 tab 解析不到 worker 时会 fallback `listWorkersByLead`,worker 变更
 *     另有 ORCA_WORKER_CHANGED 推送兜底,镜像慢一拍能自愈 —— 本来就不值得等。
 *
 * 抽成一处的原因与 `remoteSessionHandoff` 相同:草稿的「发送」与「新建目标」两条路径
 * 逐字重复这段收尾,而 #807 的 review 反复证明**两处逐字重复漏改一处不会有任何编译或
 * 测试信号**。顺带满足 newMakerProjectPicker 那条守卫:组件不再自己 import 回流函数,
 * 回流只经共享 helper 使用。
 */
import {
  isTransientRemoteError,
  refreshRemoteDeviceSessions,
} from '@/features/device-link/refreshRemoteSessions';
import { createLogger } from '@/lib/logger';
import {
  agentCapabilitiesForDevice,
  makerApiForDevice,
  orcaWorkflowsForDevice,
} from '@/lib/makerTransport';
import { extractIpcError } from '@/utils/ipcError';
import {
  createDeferredUiAssignment,
  rememberDeferredUiAssignment,
  type DeferredUiAssignment,
} from './deferredUiAssignment';
import { buildDraftWorkerInitialTask } from './draftWorkerHandoff';

const log = createLogger('remoteCollabHandoff');

function remoteWorkerPermissionModeUnsupportedError(): Error {
  return new Error(
    '[DEVICE_LINK_CHANNEL_NOT_ALLOWED] controlled device does not support Orca Team Worker permission mode',
  );
}

async function readRemoteCollabCapabilities(
  deviceId: string,
  options: Pick<EnableOrcaOptions, 'workerAgent' | 'agentDeviceId'>,
): Promise<{
  supportsOrcaWorkerPermissionMode?: boolean;
  supportsDeferredOrcaUiAssignment?: boolean;
}> {
  // Worker 的 Agent 在另一台电脑运行时,那个 Agent 不一定装在被控电脑上;这些是整台电脑的协议位,
  // 改用被控电脑一定注册的 Claude Code 读。
  const probeAgent = typeof options.agentDeviceId === 'string' ? 'claude-code' : options.workerAgent;
  const raw = await agentCapabilitiesForDevice(deviceId, probeAgent);
  if (
    !raw
    || typeof raw !== 'object'
    || Array.isArray(raw)
    || (raw as Record<string, unknown>).supportsOrcaWorkerPermissionMode !== true
  ) {
    throw remoteWorkerPermissionModeUnsupportedError();
  }
  // 旧被控端会静默丢掉 Worker 的 Agent 位置、把 Worker 建在 Lead 那里:弹窗之后降级了就直接失败。
  if (
    options.agentDeviceId !== undefined
    && (raw as Record<string, unknown>).supportsOrcaWorkerAgentDevice !== true
  ) {
    throw new Error(
      '[DEVICE_LINK_CHANNEL_NOT_ALLOWED] controlled device does not support choosing the Worker agent location',
    );
  }
  return raw;
}

/**
 * 超时后回查被控端权威终态的次数与间隔。
 *
 * 等待已经挪到导航之后(见文件头),不再占着新建页、也不再压着用户的输入,所以这里可以
 * 比「挡在导航前」时期给得从容一些。但仍然**有界** —— 被控端可能永远不返回,无界等待只会
 * 把首轮永久挂起;查不到就 fail-closed 按失败降级,绝不把「没建成」猜成「建成了」。
 */
const TIMEOUT_RECOVERY_ATTEMPTS = 6;
const TIMEOUT_RECOVERY_DELAY_MS = 3000;
/**
 * 整段回查的总时限。
 *
 * 只限次数不限时间是不够的:链路「可连但每个 invoke 都黑洞」时,每次 listWorkersByLead
 * 自己就要走满 30s 隧道超时,6 次串行 + 5×3s 退避 ≈ 3 分钟 —— 而这段时间 composer 是
 * 锁住的、首轮压着不发。次数上限只约束了退避总和(15s),没约束探针自身的耗时
 * (codex P2 第五轮)。
 *
 * 所以再加一道总 deadline:两者谁先到都停,回查最坏 30s 收尾,叠加最初 enableOrca 的
 * 30s 超时,composer 最坏锁约 1 分钟而不是 3 分钟。超时后仍走 fail-closed 降级,
 * 并由 finally 的镜像回流让被控端稍后提交的情况自愈。
 */
const TIMEOUT_RECOVERY_DEADLINE_MS = 30_000;

const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));

/**
 * `DEVICE_LINK_TIMEOUT` **不是权威失败** —— 隧道超时只删掉控制端的等待项,被控端那次
 * enableOrca 仍在继续跑(device-link ipc.ts 对 INVOKE_TIMEOUT 的判定就是「远端仍存活」)。
 * 把它和 PRECONDITION_FAILED / INVALID_PARAMS 这类权威拒绝混为一谈,会让「被控端起 Worker
 * 慢了一点」被当成「协同没开起来」:首轮照普通单会话发出,而团队其实马上就建好了
 * (issue #1170 codex P1 第二轮)。
 */
function isAmbiguousTimeout(err: unknown): boolean {
  return extractIpcError(err)?.code === 'DEVICE_LINK_TIMEOUT';
}

/**
 * 超时后回查被控端 DB 的权威终态:worker 已落库 = 团队真的建成了。
 *
 * 用 `listWorkersByLead` 而不是 `getByLeadSession`:非空 worker 列表同时证明 team 与首个
 * Worker 都已提交(team 建了但 worker 还没落库的中间态按未完成处理,fail-closed),而且
 * 顺带拿到 reveal 需要的 workerSessionId。
 *
 * 归属用调用方手里的 deviceId(`orcaWorkflowsForDevice`),不重新解析易失的 session origin。
 */
async function recoverTimedOutTeam(
  p: RemoteCollabEnableParams,
): Promise<{ focusWorkerSessionId: string } | null> {
  const deadline = Date.now() + TIMEOUT_RECOVERY_DEADLINE_MS;
  for (let attempt = 0; attempt < TIMEOUT_RECOVERY_ATTEMPTS; attempt += 1) {
    // 次数与时间两道闸,谁先到都停 —— 探针自身可能各走满 30s 隧道超时(见常量注释)。
    if (Date.now() >= deadline) {
      log.warn(`[${p.logTag}] remote team probe hit the overall deadline`, {
        leadSessionId: p.leadSessionId,
        attempt,
      });
      return null;
    }
    if (attempt > 0) await delay(TIMEOUT_RECOVERY_DELAY_MS);
    try {
      const workers = await orcaWorkflowsForDevice(p.deviceId).listWorkersByLead(p.leadSessionId);
      const workerSessionId = workers?.[0]?.sessionId;
      if (workerSessionId) {
        log.info(`[${p.logTag}] remote enableOrca timed out but the team is committed`, {
          leadSessionId: p.leadSessionId,
          attempt,
        });
        return { focusWorkerSessionId: workerSessionId };
      }
    } catch (probeErr) {
      // 回查本身失败要**分性质**,不能一律放弃剩余预算(codex P2 第三轮):
      // 触发回查的前提就是链路刚抖过(enableOrca 超时),第一次回查撞上同一段抖动
      // 是常态。此时直接 return null,等于「因为链路抖所以判定协同没建成」——
      // 而被控端那次 enableOrca 很可能正在跑完。
      //
      // 判据复用 device-link 既有的 isTransientRemoteError(同一条传输、同一类判断,
      // 永久错误优先、未知错误不重试)。为它另写一份等价判据,正是本 PR 一路在消灭的形状。
      const transient = isTransientRemoteError(
        probeErr instanceof Error ? probeErr.message : String(probeErr),
      );
      log.warn(`[${p.logTag}] probing remote team after timeout failed`, {
        attempt,
        transient,
        error: probeErr,
      });
      // 永久错误(被控端版本过旧 / 远程已禁用)重试多少次都是同一个结果 → 立即降级。
      if (!transient) return null;
      // 瞬态错误:继续用完剩余轮次;全部用尽后走循环外的 fail-closed。
    }
  }
  return null;
}

type EnableOrcaOptions = Parameters<typeof window.electronAPI.maker.enableOrca>[1];

export interface RemoteCollabEnableParams {
  /** 被控设备 deviceId —— Worker 在这台机器上 spawn。 */
  deviceId: string;
  /** 刚在被控端建出的 Lead 会话 id。 */
  leadSessionId: string;
  /**
   * enableOrca 入参。**必须按被控端的模型 / 供应商目录收窄**(草稿侧走
   * `draftEnableOrcaOptions(collab, deviceProviders, …)`)—— 拿控制端目录配出来的模型
   * 在被控端多半不存在,会撞它的精确 preflight。
   */
  options: EnableOrcaOptions;
  /** 新建 Lead 的待发送输入,仅供不支持 deferred handoff 的老被控端兼容。 */
  pendingLeadInput?: string;
  /** 日志前缀,用于区分是哪条创建路径(如 'draft send' / 'draft goal')。 */
  logTag: string;
}

/**
 * 隧道到被控端 enableOrca,回传可用于 navigate state 的 reveal 载荷。
 *
 * **权威失败按原样抛出**:调用方各自决定降级语气(草稿两条路径都是
 * `getCollaborationStartErrorMessage(err, t, { remoteDevice: true })` + 继续单会话)。
 * 这里不吞错 —— 吞掉就没人告诉用户「协同没开起来」,而会话已经建好了。
 *
 * **隧道超时先回查再定性**(见 `isAmbiguousTimeout`):超时只说明响应没回来,不说明被控端
 * 没建成。直接当失败放行,会让「被控端起 Worker 慢了几秒」变成「用户明确开了协同,首轮却以
 * 普通单会话跑」。回查到 worker 已落库就照成功返回;查不到才把原始超时抛出去降级。
 */
export async function enableRemoteCollabForSession(
  p: RemoteCollabEnableParams,
): Promise<{
  focusWorkerSessionId: string;
  deferredUiAssignment?: DeferredUiAssignment;
  assignmentUnconfirmed?: boolean;
}> {
  // 弹窗展示时的 capability 只是一份快照。真正 mutation 前重新向同一被控端确认,
  // 防止断线重连后设备降级到旧版本、把显式权限字段静默忽略。
  const capabilities = await readRemoteCollabCapabilities(p.deviceId, p.options);
  const deferDelegateTask =
    p.options.deferDelegateTask === true
    && capabilities.supportsDeferredOrcaUiAssignment === true;
  // 老被控端没有 deferred capability:删掉新字段,沿用它的 enableOrca 即时派单。
  // 不能在新通道失败后再回退即时派发,否则响应丢失时会把同一任务派两遍。
  // Even when the capability probe says “new”, preserve the pending Lead text on the wire:
  // the peer may reconnect/downgrade between capability and mutation. A new handler defers this
  // wrapped text until history is ready; an old handler still receives the context it cannot query.
  const enableOptions = (() => {
    const compatible = { ...p.options };
    compatible.delegateTask = buildDraftWorkerInitialTask(
      compatible.delegateTask,
      p.pendingLeadInput,
    );
    if (!deferDelegateTask) delete compatible.deferDelegateTask;
    return compatible;
  })();
  const withDeferredAssignment = (
    workerSessionId: string,
    snapshotBeforeMs: number | null,
    assignmentUnconfirmed = false,
  ) => {
    const deferredUiAssignment = deferDelegateTask && snapshotBeforeMs !== null
      ? createDeferredUiAssignment({
            // The later assignment can rely on queryable history, so retain the user's raw task;
            // the legacy Pending Lead input wrapper above exists only for the one-shot enable wire.
            options: p.options,
            workerSessionId,
            snapshotBeforeMs,
            deviceId: p.deviceId,
        })
      : undefined;
    rememberDeferredUiAssignment(p.leadSessionId, deferredUiAssignment);
    return {
      focusWorkerSessionId: workerSessionId,
      ...(deferredUiAssignment ? { deferredUiAssignment } : {}),
      ...(assignmentUnconfirmed ? { assignmentUnconfirmed: true } : {}),
    };
  };
  try {
    const result = await makerApiForDevice(p.deviceId).enableOrca(
      p.leadSessionId,
      enableOptions,
    );
    return withDeferredAssignment(
      result.workerSessionId,
      result.dispatched === false && Number.isFinite(result.uiAssignmentSnapshotBeforeMs)
        ? result.uiAssignmentSnapshotBeforeMs
        : null,
    );
  } catch (err) {
    if (!isAmbiguousTimeout(err)) throw err;
    const recovered = await recoverTimedOutTeam(p);
    // enableOrca 响应丢失时拿不到被控端时间;这些 defer 调用只用于刚创建、尚无历史的
    // Lead,0 可安全表达「等第一条 user 行」,同时不依赖控制端/被控端时钟同步。
    // 响应丢失时无法证明实际被控端采用了 deferred handler,也无法证明任务尚未派发。
    // 只恢复 Team 可见性,不生成可二次派发的 receipt。
    if (recovered) {
      return withDeferredAssignment(
        recovered.focusWorkerSessionId,
        null,
        deferDelegateTask,
      );
    }
    throw err;
  } finally {
    // 被控端刚建出的 worker session 还没进控制端注册表。fire-and-forget(见文件头 ②)。
    //
    // 放在 finally 而不是成功分支里,拿到两件事:
    //  · 超时回查判定为「没建成」后仍刷一次 —— 被控端可能在回查窗口之后才提交,刷新让
    //    orcaRole 回流,CCAgentSessionView 的 external-enable 边沿检测据此补开协同 tab,
    //    UI 最终与被控端的真实状态收敛(降级只影响首轮,不会永久错判)。
    //  · finally 在 catch(含回查)之后才执行,所以这次刷新不会早于被控端提交的判定结果 ——
    //    成功路径上 enableOrca 返回即代表 DB 已提交,回查路径上则已经确认过 worker 落库。
    void refreshRemoteDeviceSessions(p.deviceId).catch((err) => {
      log.warn(`[${p.logTag}] refresh remote sessions after enableOrca failed`, err);
    });
  }
}

/**
 * SessionView 侧的消费入口:发首轮 / 起目标之前先把协同开起来。
 *
 * 两处 pending 消费(首条消息、新建目标)共用这一份 —— 逐字重复两遍正是本 PR 反复踩过的
 * 形状。**永不抛出**:协同开不起来时会话本身仍然可用,首轮照单会话继续,只是要如实告诉
 * 用户「这条仍会发出去」(否则用户会以为没发,再提交一次)。
 *
 * 返回 true 表示协同已就绪(调用方据此展开协同 tab)。
 */
export async function consumePendingRemoteCollab(
  pending: { deviceId: string; options: Record<string, unknown>; pendingLeadInput?: string },
  ctx: {
    leadSessionId: string;
    logTag: string;
    /** 失败时的用户可见提示;调用方注入以复用视图的 i18n / toast。 */
    onFailed: (err: unknown) => void;
    /** Team 已建成,但延迟派单响应丢失,不能安全重试。 */
    onAssignmentUnconfirmed?: () => void;
  },
): Promise<{ ok: boolean; deferredUiAssignment?: DeferredUiAssignment }> {
  try {
    const result = await enableRemoteCollabForSession({
      deviceId: pending.deviceId,
      leadSessionId: ctx.leadSessionId,
      options: pending.options as Parameters<typeof window.electronAPI.maker.enableOrca>[1],
      pendingLeadInput: pending.pendingLeadInput,
      logTag: ctx.logTag,
    });
    if (result.assignmentUnconfirmed) ctx.onAssignmentUnconfirmed?.();
    return { ok: true, deferredUiAssignment: result.deferredUiAssignment };
  } catch (err) {
    log.error(`[${ctx.logTag}] remote enableOrca failed (continuing as single session)`, err);
    ctx.onFailed(err);
    return { ok: false };
  }
}