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。

17.7 KB
Raw Blame
/**
 * deviceProvidersCache —— 被控端供应商目录的 deviceId-aware 缓存核心(**纯逻辑,零 react-native**)。
 *
 * 刻意不 import react-native / hook,便于 node 环境单测直接验证缓存语义(对齐 tokens.ts /
 * monoFont.ts 的拆分约定)。React hook 在 `./useDeviceProviders.ts` 里消费本模块。
 *
 * 语义对齐桌面 `useDeviceProviders`:按 deviceId 隔离 + inflight 去重 + 代际驱逐
 * (evict 时自增代际,作废在途 fetch 的回写,防设备切换 / 重连后串旧供应商)。
 */
import type { ProviderView } from '@cindy/model-providers/registry';

/** PROVIDER_LIST 隧道回包:目录 + 被控端「模型显示/隐藏」override 快照(旧被控端无)。 */
export interface DeviceProvidersPayload {
  providers: ProviderView[];
  /** Host-owned display order; absent on older hosts. */
  providerOrder?: string[];
  /** key = `${agent}:${providerId}:${modelId}`;undefined = 旧被控端,调用方不过滤。 */
  modelVisibilityOverrides?: Record<string, boolean>;
}

/** 被控端供应商目录的取数器(通常 = `() => transport.listProviders()`)。 */
export type DeviceProvidersFetcher = () => Promise<DeviceProvidersPayload>;

/** Recognize both transport codes and the host's serialized IPC error prefix. */
function providerErrorCode(error: unknown): string | undefined {
  const code = error && typeof error === 'object' ? (error as { code?: unknown }).code : undefined;
  if (typeof code === 'string' && code !== 'IPC_ERROR') return code;
  const message = error instanceof Error ? error.message : typeof error === 'string' ? error : '';
  return /^(?:Error invoking remote method '[^']+': Error: )?\[([A-Z0-9_]+)\]/.exec(message)?.[1];
}

/** Short retries and mounted-picker recovery must recognize the same IPC forms. */
export function isDeviceProvidersVisibilityNotReadyError(error: unknown): boolean {
  return providerErrorCode(error) === 'MODEL_VISIBILITY_NOT_READY';
}

/** Only an explicitly unsupported channel permits the legacy capabilities fallback. */
export function isDeviceProvidersUnsupportedError(error: unknown): boolean {
  const code = providerErrorCode(error);
  return code === 'CHANNEL_NOT_ALLOWED' || code === 'DEVICE_LINK_CHANNEL_NOT_ALLOWED';
}

/**
 * Apply the host-owned display order (Desktop semantics): explicitly ordered ids first,
 * new ids append in catalog order. Payloads without an order are returned unchanged.
 */
export function orderDeviceProviders(payload: DeviceProvidersPayload): DeviceProvidersPayload {
  if (!Array.isArray(payload.providerOrder)) return payload;
  const byId = new Map(payload.providers.map(provider => [provider.id, provider]));
  const providers: ProviderView[] = [];
  const seen = new Set<string>();
  for (const id of payload.providerOrder) {
    const provider = byId.get(id);
    if (!provider || seen.has(id)) continue;
    seen.add(id);
    providers.push(provider);
  }
  for (const provider of payload.providers) {
    if (seen.has(provider.id)) continue;
    seen.add(provider.id);
    providers.push(provider);
  }
  return { ...payload, providers };
}

async function requestDeviceProviders(
  fetcher: DeviceProvidersFetcher,
  isCurrent: () => boolean,
): Promise<DeviceProvidersPayload> {
  for (let attempt = 0; ; attempt++) {
    try {
      return orderDeviceProviders(await fetcher());
    } catch (error) {
      if (!isDeviceProvidersVisibilityNotReadyError(error) || attempt >= 2 || !isCurrent()) throw error;
      await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
      if (!isCurrent()) throw error;
    }
  }
}

// 缓存按被控设备隔离;代际同桌面(evict 时自增,作废在途 fetch 的回写)。
const cache = new Map<string, DeviceProvidersPayload>();
const inflight = new Map<string, Promise<DeviceProvidersPayload>>();
const readGeneration = new WeakMap<Promise<DeviceProvidersPayload>, number>();
const deviceGen = new Map<string, number>();
const listeners = new Map<string, Set<(payload: DeviceProvidersPayload) => void>>();
const errorListeners = new Map<string, Set<(error: unknown) => void>>();

/** Fresh reads also report failure to mounted pickers without reviving stale catalogs. */
export function subscribeDeviceProvidersError(deviceId: string, listener: (error: unknown) => void): () => void {
  const bucket = errorListeners.get(deviceId) ?? new Set<(error: unknown) => void>();
  bucket.add(listener);
  errorListeners.set(deviceId, bucket);
  return () => {
    bucket.delete(listener);
    if (bucket.size === 0) errorListeners.delete(deviceId);
  };
}

function notifyDeviceProvidersError(deviceId: string, error: unknown): void {
  // A downgraded host cannot serve any of the cached provider routes. Retire only
  // that device's snapshot; an empty success notification would incorrectly mark it ready.
  if (isDeviceProvidersUnsupportedError(error)) cache.delete(deviceId);
  for (const listener of errorListeners.get(deviceId) ?? []) listener(error);
}

// 各设备缓存写入时的连接代际(模块级,组件卸载不丢):hook 用它对「重连时未挂载 /
// 正看其它设备」的旧缓存做重连判定(codex review P1)——组件本地 ref 会随卸载
// 丢失,旧设备再打开会被当首次挂载、采信断线前缓存。
const deviceFetchEpoch = new Map<string, number>();

/** hook 在缓存命中 / 拉取完成后标记该设备缓存所属的连接代际。 */
export function markDeviceFetchEpoch(deviceId: string, epoch: number): void {
  deviceFetchEpoch.set(deviceId, epoch);
}

/** 读该设备缓存写入时的连接代际;无记录 = 该设备从未标记(首次挂载语义)。 */
export function getDeviceFetchEpoch(deviceId: string): number | undefined {
  return deviceFetchEpoch.get(deviceId);
}

function notifyDeviceProviders(deviceId: string, payload: DeviceProvidersPayload): void {
  for (const listener of listeners.get(deviceId) ?? []) listener(payload);
}

/** 订阅某设备缓存的新快照;provider revision push 刷新后通知已挂载 hook。 */
export function subscribeDeviceProviders(
  deviceId: string,
  listener: (payload: DeviceProvidersPayload) => void,
): () => void {
  const bucket = listeners.get(deviceId) ?? new Set<(payload: DeviceProvidersPayload) => void>();
  bucket.add(listener);
  listeners.set(deviceId, bucket);
  return () => {
    bucket.delete(listener);
    if (bucket.size === 0) listeners.delete(deviceId);
  };
}

/** 读缓存命中(同步),供 hook 初始化 state 用。 */
export function getCachedDeviceProviders(deviceId: string): DeviceProvidersPayload | undefined {
  return cache.get(deviceId);
}

/**
 * 取某被控设备的供应商目录(带缓存 + inflight 去重 + 代际作废)。纯逻辑、可单测。
 * fetcher 注入,便于按 deviceId 绑定 transport,也便于测试。
 */
export async function fetchDeviceProviders(
  deviceId: string,
  fetcher: DeviceProvidersFetcher,
): Promise<DeviceProvidersPayload> {
  const cached = cache.get(deviceId);
  if (cached) return cached;
  // 重连期间 fresh 在途时 join fresh(greptile P1:重连请求覆盖 fresh 目录)——
  // connectionEpoch 变化会让 useDeviceProviders 重跑 effect 发起普通请求;该请求
  // 捕获与 fresh 相同的代际,晚于 fresh 返回仍通过 isCurrent() 覆盖共享缓存。
  // fresh 结果即工作站最新真相,普通读取 join 它语义正确且不会产生竞争请求。
  const fp = freshInflight.get(deviceId);
  if (fp) return joinProviderRead(deviceId, fp, () => fetchDeviceProviders(deviceId, fetcher));
  const ip = inflight.get(deviceId);
  if (ip) return joinProviderRead(deviceId, ip, () => fetchDeviceProviders(deviceId, fetcher));

  // 捕获发起时代际;回调里若代际已变(被 evict)则认为本次请求作废,不回写 cache / 不动 inflight。
  const startGen = deviceGen.get(deviceId) ?? 0;
  const isCurrent = (): boolean => (deviceGen.get(deviceId) ?? 0) === startGen;

  const p = requestDeviceProviders(fetcher, isCurrent)
    .then((res) => {
      const payload: DeviceProvidersPayload = {
        providers: res?.providers ?? [],
        ...(res?.modelVisibilityOverrides !== undefined
          ? { modelVisibilityOverrides: res.modelVisibilityOverrides }
          : {}),
      };
      if (isCurrent()) {
        cache.set(deviceId, payload);
        inflight.delete(deviceId);
        notifyDeviceProviders(deviceId, payload);
      }
      return payload;
    })
    .catch((e) => {
      if (isCurrent()) {
        inflight.delete(deviceId);
        notifyDeviceProvidersError(deviceId, e);
      }
      throw e;
    });
  inflight.set(deviceId, p);
  readGeneration.set(p, startGen);
  void p.finally(() => {
    if (inflight.get(deviceId) === p) inflight.delete(deviceId);
  }).catch(() => undefined);
  return p;
}

/** A revision retires the result, not the physical request. New readers wait for
 * it to settle, then share one current-generation read instead of flooding the link. */
function joinProviderRead(
  deviceId: string,
  pending: Promise<DeviceProvidersPayload>,
  next: () => Promise<DeviceProvidersPayload>,
): Promise<DeviceProvidersPayload> {
  const generation = getDeviceProvidersGen(deviceId);
  if (readGeneration.get(pending) === generation) return pending;
  return pending.catch(() => undefined).then(() => {
    if (getDeviceProvidersGen(deviceId) !== generation) throw new Error('Provider read superseded');
    return next();
  });
}

/** Catalog push refresh owns the replacement read; mounted hooks only retire
 * readiness. Keep in-flight slots so a burst cannot start overlapping reads. */
export function invalidateDeviceProvidersForRefresh(deviceId: string): void {
  cache.delete(deviceId);
  deviceGen.set(deviceId, getDeviceProvidersGen(deviceId) + 1);
  notifyDeviceProvidersGen(deviceId, 'fresh-invalidate');
}

/**
 * 强制刷新取某被控设备的供应商目录(codex review P2):**跳过缓存命中短路**——
 * 即使缓存仍存在也执行 fetcher 访问工作站,成功后回写缓存并推送 payload 订阅者。
 * 用途:提交终检的 revalidate(缓存命中分支要拿到工作站当前真相,而不是旧目录),
 * 与普通读取的 cache-first 语义区分。
 * 不复用普通 fetch 的在途请求(greptile review P1):普通请求可能发起于工作站目录
 * 变更之前、本地代际尚未递增——fresh 语义是「强制访问工作站拿当前真相」,join
 * 旧请求会拿过期目录当已知目录。fresh 自身并发仍经独立 inflight 槽去重。
 */
const freshInflight = new Map<string, Promise<DeviceProvidersPayload>>();

export async function fetchDeviceProvidersFresh(
  deviceId: string,
  fetcher: DeviceProvidersFetcher,
): Promise<DeviceProvidersPayload> {
  const fp = freshInflight.get(deviceId);
  // After an obsolete read settles, all waiters share the replacement started
  // after this call. Re-entering fresh would invalidate a sibling waiter's new
  // read and send a duplicate; independent fresh calls still bypass cache below.
  if (fp) return joinProviderRead(deviceId, fp, () => fetchDeviceProviders(deviceId, fetcher));

  // fresh 语义 = 强制访问工作站拿当前真相。仅当确有普通请求在途时才作废它
  // (greptile/copilot/codex review P1/P2):旧普通请求若在 fresh 之后返回,仍会
  // 通过 isCurrent() 回写旧目录覆盖 fresh 结果——代际 +1 使更早请求失效并清掉
  // 普通 inflight 槽。**无普通在途时不得推进代际**(codex review P2):守卫
  // resolveSubmitGuardCatalog 在 fetch 前记录 genAt,fresh 自推进会让守卫误判
  // 为外部驱逐而丢弃结果;仅在确有在途时推进,守卫下一轮重跑(普通在途已清)
  // 即收敛,gen 保持稳定时 fetch 前后一致直接采信。
  const ip = inflight.get(deviceId);
  if (ip && readGeneration.get(ip) !== getDeviceProvidersGen(deviceId)) {
    return joinProviderRead(deviceId, ip, () => fetchDeviceProviders(deviceId, fetcher));
  }
  if (ip) {
    inflight.delete(deviceId);
    deviceGen.set(deviceId, (deviceGen.get(deviceId) ?? 0) + 1);
    // 内部作废(greptile/codex review P1/P2):hook 不得因此启动替代普通请求——
    // fresh 自身会写缓存并经 payload 订阅恢复;若 hook 重拉普通请求会与 fresh
    // 竞争(同代际、较晚返回仍通过 isCurrent() 把 fresh 结果覆盖回旧目录)。
    notifyDeviceProvidersGen(deviceId, 'fresh-invalidate');
  }

  const startGen = deviceGen.get(deviceId) ?? 0;
  const isCurrent = (): boolean => (deviceGen.get(deviceId) ?? 0) === startGen;

  const p = requestDeviceProviders(fetcher, isCurrent)
    .then((res) => {
      const payload: DeviceProvidersPayload = {
        providers: res?.providers ?? [],
        ...(res?.modelVisibilityOverrides !== undefined
          ? { modelVisibilityOverrides: res.modelVisibilityOverrides }
          : {}),
      };
      if (isCurrent()) {
        cache.set(deviceId, payload);
        notifyDeviceProviders(deviceId, payload);
      }
      return payload;
    })
    .catch((error: unknown) => {
      if (isCurrent()) notifyDeviceProvidersError(deviceId, error);
      throw error;
    });
  freshInflight.set(deviceId, p);
  readGeneration.set(p, startGen);
  void p.finally(() => {
    if (freshInflight.get(deviceId) === p) freshInflight.delete(deviceId);
  }).catch(() => undefined);
  return p;
}

/** device-link:被控设备切换 / 下线时驱逐其供应商缓存(只清该设备 + 代际自增作废在途)。 */
export function evictDeviceProviders(deviceId: string): void {
  cache.delete(deviceId);
  inflight.delete(deviceId);
  freshInflight.delete(deviceId);
  deviceGen.set(deviceId, (deviceGen.get(deviceId) ?? 0) + 1);
  notifyDeviceProvidersGen(deviceId, 'evict');
}

/**
 * 读某设备当前的缓存代际(evict 一次 +1)。useDeviceProviders 的 ready 判定用:
 * 置位 readyFor 时记录当时代际,之后代际不一致 = 目录已被驱逐、正在重拉(或重拉失败),
 * ready 必须为 false —— 否则旧 payload 会在重拉窗口期继续被当作就绪目录(codex review P2)。
 */
export function getDeviceProvidersGen(deviceId: string): number {
  return deviceGen.get(deviceId) ?? 0;
}

// ── 代际变更订阅 ────────────────────────────────────────────────────────────
// evict/clearAll 只改模块级 Map,不通知 payload 订阅者,React 不会重渲染 ——
// 单靠渲染期的代际比对,ready 的失效要等下一次碰巧渲染(codex review P2)。
// 这里给代际变化一条主动推送通道,hook 收到即立即使 ready 失效。
/**
 * 代际失效原因(codex review P2):evict/clearAll 是**外部驱逐**——hook 应清空展示
 * 并主动重拉;fetchDeviceProvidersFresh 作废普通在途是**内部作废**——fresh 自身会
 * 写缓存并经 payload 订阅恢复,若 hook 再启动普通请求会与 fresh 竞争(普通请求
 * 捕获同一代际、较晚返回仍通过 isCurrent() 把 fresh 结果覆盖回旧目录)。
 */
export type DeviceProvidersGenInvalidationReason = 'evict' | 'fresh-invalidate';

const genListeners = new Map<string, Set<(reason: DeviceProvidersGenInvalidationReason) => void>>();

/** 订阅某设备的缓存代际变更(evict/clearAll/fresh 作废时触发);返回退订函数。 */
export function subscribeDeviceProvidersGen(
  deviceId: string,
  listener: (reason: DeviceProvidersGenInvalidationReason) => void,
): () => void {
  const bucket = genListeners.get(deviceId) ?? new Set<(reason: DeviceProvidersGenInvalidationReason) => void>();
  bucket.add(listener);
  genListeners.set(deviceId, bucket);
  return () => {
    bucket.delete(listener);
    if (bucket.size === 0) genListeners.delete(deviceId);
  };
}

function notifyDeviceProvidersGen(
  deviceId: string,
  reason: DeviceProvidersGenInvalidationReason,
): void {
  for (const listener of genListeners.get(deviceId) ?? []) listener(reason);
}

/**
 * 账号登出 / 进程内切号时清空**全部**被控设备的供应商缓存。
 *
 * 这是 module 级单例缓存,不随 React 组件卸载清空。若不在登出时清,下一个登录账号会通过
 * `getCachedDeviceProviders` 命中上一个账号留下的被控端供应商目录(跨账号串数据)。除清
 * cache / inflight 外,对每个已知 deviceId 自增代际,作废所有仍在途 fetch 的回写,防其在
 * clear 之后又把旧数据写回。
 */
export function clearAllDeviceProviders(): void {
  // fresh-only 在途设备也要纳入代际作废(greptile/copilot/codex review P1/P2):
  // 只有 freshInflight 在途时(如提交终检触发的 fresh 拉取),登出后旧响应仍会
  // 通过 isCurrent() 回写并广播,造成跨账号残留。
  const ids = new Set<string>([
    ...cache.keys(),
    ...inflight.keys(),
    ...freshInflight.keys(),
    ...deviceGen.keys(),
  ]);
  // 先清空三张 Map,再通知(codex review P2:清空缓存后再通知订阅者)——hook 的
  // gen 订阅收到 'evict' 会立即 fetchDeviceProviders 重拉,若通知发生在清空之前,
  // 重拉只会命中旧账号缓存或加入旧请求,随后 Map 被清掉,既没真正访问新账号,
  // 也没有 payload 通知恢复 hook,目录长期停在 ready=false。
  cache.clear();
  inflight.clear();
  freshInflight.clear();
  for (const id of ids) {
    deviceGen.set(id, (deviceGen.get(id) ?? 0) + 1);
    notifyDeviceProvidersGen(id, 'evict');
    // 注意:不再推送空 payload(codex review P2:清空账号缓存时不要把空载荷标为
    // 就绪)——payload 订阅回调把任何 payload 视为已确认快照,会重新置位
    // readyFor/readyGen,最终暴露为 ready:true 的 loaded-empty 目录;且
    // [deviceId, maker] effect 不因重新登录重跑,新账号目录永不重拉。清空展示
    // 与未就绪由 hook 的 gen 失效订阅承担(清 payload + 保持未就绪 + 主动重拉),
    // 见 useDeviceProviders。登出后短窗口残留由该订阅的清空兜底(copilot P2 意图)。
  }
}