Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import Constants from 'expo-constants';
import { DirectLinkTransport } from './DirectLinkTransport';
import { tryMobilePeerInvoke, resetMobilePeer } from './peerFileRegistry';
import { isHistoryViewUnavailable, type HistoryWorkPatch } from '@cindy/maker-shared/message-window';
import { findRemoteHistoryView } from '@/session/remoteHistoryView';
import { createBackgroundConnection } from './backgroundConnection';
import { invokeWithHistoryViewCapability } from './historyViewCapability';
import { createRecoveryDiagnostics, settleMeasuredSnapshot, type RecoveryPhase } from './recoveryDiagnostics';
import { confirmTrackedSubscription, SubscriptionAcknowledgements } from './subscriptionAcknowledgements';
import { AppState, Platform } from 'react-native';
import { mobileDebugLog } from '@/debug/mobileDebugLog';
import { dispatchCredentialSwitchOutcome } from '@/session/credentialSwitchOutcome';
import { mobileRuntimeIdentity } from '@/debug/mobileRuntimeIdentity';
import {
DeviceLinkClient,
createDirectRuntimeBridge,
isSharedTaskPeer,
probeSharedTaskHost,
sharedTaskTopics,
SHARED_TASK_CAPABILITY,
DeviceLinkError,
CONTROLLER_CAPABILITY_MAKER_EVENT_BATCH_V1,
CONTROLLER_CAPABILITY_SESSION_TEXT_SNAPSHOT_V1,
CONTROLLER_CAPABILITY_SESSION_LIST_MESSAGES_V1,
CONTROLLER_CAPABILITY_PROVIDER_LOGO_KINDS_V2,
DEVICE_LINK_CAPABILITY_COMPACT_MESSAGE_HISTORY_V1,
DL_SUBSCRIBE_CHANNEL,
DL_UNSUBSCRIBE_CHANNEL,
FILE_BROWSER_EVENT_CHANNEL,
PROTOCOL_VERSION,
REMOTE_RESOURCE_CHANGED_CHANNEL,
parseRemoteResourceChangedPayload,
type DeviceLinkConnectionIssue,
type DeviceLinkStatus,
type DeviceView,
type Envelope,
type InvokeResultPayload,
type LinkAcceptPayload,
type PresenceSnapshot,
type PushPayload,
type RemoteResourceChangedPayload,
type Topic,
decodeModelSpeedPayload,
} from '@cindy/device-link';
import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, type ReactNode } from 'react';
import { PROJECT_ALIASES_GET_CHANNEL, PROJECT_ALIASES_CHANGED_CHANNEL } from '@cindy/maker-shared/project-alias-sync';
import {
acceptRemoteProjectAliasesChanged,
refreshRemoteProjectAliases,
removeRemoteProjectAliases,
setRemoteProjectAliasesAccount,
suspendRemoteProjectAliases,
suspendRemoteProjectAliasesForReleasedTopics,
} from '@/session/remoteProjectAliases';
import { deviceLinkWsUrl, DEVICE_LINK_API_BASE_URL } from '@/config/env';
import { MOBILE_VISUAL_MOCK_ENABLED } from '@/config/env';
import { useAuth } from '@/auth/AuthContext';
import { useSelfHostedRelayRouteGeneration } from './selfHostedRelay';
import { currentSelfHostedRelayFrameAuth } from './selfHostedRelayFrameAuth';
import {
getActiveSelfHostedRelay,
getSelfHostedRelayRouteGeneration,
waitForSelfHostedRelayRoute,
} from './selfHostedRelayRouting';
import { getMobileAuthOwner, isMobileAuthOwnerCurrent } from '@/auth/authOwnerGeneration';
import { useSharedTaskApi } from './useSharedTaskApi';
import {
applyAccessRevokedFrame,
withAccessRevokedHandling,
} from '@/device-link/accessRevoked';
import {
clearAllDeviceProviders,
evictDeviceProviders,
type DeviceProvidersPayload,
} from '@/device-link/deviceProvidersCache';
import {
clearAllProviderShareCatalogs,
evictProviderShareCatalogs,
} from '@/device-link/providerShareCatalogCache';
import {
evictAgentCapabilitiesForDevice,
resetAgentCapabilitiesCache,
} from '@/session/agentCapabilitiesCache';
import { createDeviceCatalogRefresh } from '@/device-link/deviceCatalogRefresh';
import { evictComposerPaletteCacheForDevice, resetComposerPaletteCache } from '@/session/composerPaletteCache';
import {
evictTaskTagCatalog,
resetTaskTagCatalogCache,
writeTaskTagCatalog,
} from '@/session/taskTagCatalogCache';
import { clearAllDeviceModelMeta, evictDeviceModelMeta } from '@/device-link/deviceModelMetaCache';
import { dispatchFileBrowserWatchEvent } from '@/device-link/fileBrowserWatch';
import {
handlePeerLinkCloseFrame,
invalidatePeerLinkState,
liftRehydrateSuppressionForNewConnection,
liftRehydrateSuppressionOnExplicitOpen,
updateRehydrateSuppressionOnLinkClose,
} from '@/device-link/linkClose';
import { resolveMobileInvokeTimeoutMs } from '@/device-link/invokeTimeouts';
import {
classifySnapshotBatchFailure,
rehydrateDeviceLinkPeer,
type DeviceLinkRehydrateSendOptions,
} from '@/device-link/rehydrate';
import {
PeerRecoveryOpenIntentRegistry,
PeerRecoveryScheduler,
type PeerRecoveryResult,
} from '@/device-link/peerRecoveryScheduler';
import {
clearSessionScheduleIndexCache,
invalidateOfflineScheduleIndexFailureFor,
invalidateScheduleIndexForDevice,
invalidateScheduleIndexesAfterLinkRecovery,
} from '@/session/scheduleIndex';
import { isTransientRemoteError } from '@/device-link/remoteRetry';
import {
runSessionMessagesSnapshotSingleFlight,
runSessionPendingInteractionsSnapshotSingleFlight,
runSessionProjectionSnapshotSingleFlight,
} from '@/device-link/sessionSnapshotSingleFlight';
import { createRnWebSocket } from '@/device-link/rnWebSocket';
import {
DEVICE_LINK_VOICE_DICTIONARY_SNAPSHOT_CHANNEL,
type MobileGoalStatusPayload,
type MobileVoiceDictionarySnapshotResult,
} from '@cindy/maker-shared/device-link-contract';
import {
DeviceLinkTopicRegistry,
markHeldRemoteTopicsSubscribed,
markRemoteTopicsUnsubscribed,
normalizeDeviceLinkTopics,
resolvePeerRecoveryPlan,
topicsMissingRemoteAck,
} from '@/device-link/topicRegistry';
import {
applyRemoteProjectOrderPush,
resetRemoteProjectOrderPushFence,
SIDEBAR_PROJECT_ORDER_CHANGED_CHANNEL,
} from '@/session/remoteProjectOrder';
import { remoteSessionStore } from '@/session/remoteSessionStore';
import { applyMobileVoiceDictionarySnapshot } from '@/session/mobileVoiceDictionaryCache';
import { revokedDevicesStore } from '@/device-link/revokedDevicesStore';
import {
acquireDeviceSendSlot,
buildDeviceResponsivenessProbeArgs,
classifyDeviceSendFailure,
classifyDeviceSendSuccess,
classifyLinkOpenFailure,
clearDeviceResponsivenessTrackingFor,
createDeviceSendCohort,
DEVICE_RESPONSIVENESS_PROBE_CHANNEL,
isDeviceProbeDue,
noteAppLifecycleState,
resetDeviceResponsivenessTracking,
settleDeviceSend,
unresponsiveDevicesStore,
} from '@/device-link/unresponsiveDevicesStore';
import { remoteScheduleEventStore } from '@/scheduler/remoteScheduleEvents';
import { buildMobileDeviceName } from '@/device-link/mobileDeviceIdentity';
import {
capturePresenceAvailabilityEpoch,
clearPresenceWipeTimer,
clearPresenceWipeTimers,
createPresenceAvailabilityEpochs,
extendPresenceWipeTimerFloor,
getOrCreatePresenceTrackedRequest,
isInvokeResultReachabilityEvidence,
isPresenceAvailabilityEpochCurrent,
isPresenceEligibleForRemoteRequest,
markPresenceAvailabilityEpoch,
reconcileAvailabilityAfterInboundFrame,
reconcileOfflineVerdictAfterResponse,
type PresenceTrackedRequest,
type PresenceUnavailableVerdict,
type PresenceWipeTimerEntry,
resetPresenceAvailabilityEpochs,
resetPresenceAvailabilityForConnection,
schedulePresenceWipeTimer,
updatePresenceAvailability,
} from '@/device-link/presenceRecovery';
import { createOfflineMirrorWipeQueue } from '@/device-link/offlineMirrorWipeQueue';
import {
bridgeLatestMessagePage,
listMessagesWithPayloadRetry,
shouldKeepOlderMessagesAffordance,
} from '@/session/messagePaging';
import type { InputProjection, PendingInteraction, RemoteMessage } from '@/session/types';
import { prepareVisualMockDeviceLinkContext } from '@/debug/visualMock';
import { meterDeviceLinkInvokes, recordDeviceLinkPush } from '@/debug/deviceLinkTraffic';
import { decodeGzipBase64TextBounded } from '@/utils/gzipBase64';
import { jankMetricsEnabled, recordInvokeSent, recordInvokeTransfer, recordPushHandled } from '@/debug/jankMetrics';
import { localNetworkStore, type NetworkState } from '@/device-link/localNetworkStatus';
export interface DeviceLinkContextValue {
status: DeviceLinkStatus;
/** Current online relay capability; undefined while not connected. */
sharedTaskAvailable?: boolean;
/** Peers with queued, running, or retrying recovery work. Read-only UI projection. */
recoveringDeviceIds: ReadonlySet<string>;
/** 连接层可分类的失败原因(鉴权失效/被顶号/超限/版本不符);null = 无异常 */
connectionIssue: DeviceLinkConnectionIssue | null;
presenceVersion: number;
connectionEpoch: number;
/** Current remote ACK identity; null until every requested topic is confirmed. */
getSubscriptionIdentity?(deviceId: string, topics: readonly Topic[]): number | null;
lastPresenceSnapshot: PresenceSnapshot | null;
/** 当前 relay 连接代内的逐设备 availability;null = 本代尚无权威 verdict。 */
getPresenceAvailability(deviceId: string): boolean | null;
/**
* Read the account device roster. `fresh` starts a new REST snapshot instead of
* joining a request that may have started before the caller's reconciliation fence.
*/
readDeviceList(options?: { fresh?: boolean }): Promise<{ devices: DeviceView[] }>;
openLink(deviceId: string): Promise<LinkAcceptPayload>;
/** 丢弃已结算的开链缓存并真正重开;并发重开仍按设备单飞。 */
reopenLink(deviceId: string): Promise<LinkAcceptPayload>;
closeLink(deviceId: string): void;
/** Acquire before background grace ends; always release on settlement/cancellation. Hard deadline enforced by lifecycle. */
beginBackgroundTransition?(): () => void;
/**
* opts.preSend:在连接就绪并从 invoke 队列出队后、实际发送前的同步检查点。抛错即
* 中止本次发送(错误原样上抛)。供写序敏感的调用方(patchHomeSession 的 isLatest
* 屏障)把「过期即放弃」判定贴到实际发送点——重连或排队期间写可能被同字段新写
* 取代,等待前的检查不够晚。
*/
invoke<T = unknown>(
deviceId: string,
channel: string,
args?: unknown[],
opts?: { preSend?: () => void; background?: boolean },
): Promise<T>;
// `owner` is a stable id for the mounted consumer (e.g. `session:<id>`, `device:<id>`),
// so repeated subscribes from resync/retry are idempotent and a topic is only released
// when its last owner unsubscribes.
subscribe(owner: string, deviceId: string, topics: string[]): Promise<void>;
unsubscribe(owner: string, deviceId: string, topics: string[]): Promise<void>;
/** 被控端 runtime Agent roster 发生变化时通知当前控制端页面。 */
onAgentsChanged: (listener: (deviceId: string) => void) => () => void;
/** 模块中立的远程资源失效事件;页面收到后按 collection/ref 重拉。 */
onRemoteResourceChanged: (
listener: (deviceId: string, payload: RemoteResourceChangedPayload) => void,
) => () => void;
}
const DeviceLinkContext = createContext<DeviceLinkContextValue | null>(null);
const recoveryDiagnostics = new WeakMap<DeviceLinkClient, ReturnType<typeof createRecoveryDiagnostics>>();
/**
* 本控制端声明的端到端可选能力(link-open 与 subscribe 两处共用同一份,漏一处会让
* 被控端按能力缺失降级)。被控端只在看到对应能力后才发送新 wire 形状。
*/
const CONTROLLER_CAPABILITIES = [
CONTROLLER_CAPABILITY_SESSION_LIST_MESSAGES_V1,
SHARED_TASK_CAPABILITY,
CONTROLLER_CAPABILITY_SESSION_TEXT_SNAPSHOT_V1,
CONTROLLER_CAPABILITY_PROVIDER_LOGO_KINDS_V2,
// maker:event 微批:被控端把同一会话的连续事件合并成一帧,本端拆包后逐条消费
// (见 remoteSessionStore 的 MAKER_EVENT_BATCH_CHANNEL 分支)。
CONTROLLER_CAPABILITY_MAKER_EVENT_BATCH_V1,
DEVICE_LINK_CAPABILITY_COMPACT_MESSAGE_HISTORY_V1,
];
// 任意目标端真实应答的独立时序证据。它不等同于 presence verdict,也不参与 IPC/DB
// 响应性熔断;只用于判定并发返回的 unavailable 是否已被更晚目标应答推翻。
const remoteResponseEvidenceEpochs = createPresenceAvailabilityEpochs();
const remoteResponseEvidenceListeners = new Set<(deviceId: string) => void>();
const remoteAgentRosterListeners = new Set<(deviceId: string) => void>();
const remoteTaskTagsChangedListeners = new Set<(deviceId: string, tags: unknown) => void>();
export function subscribeRemoteTaskTagsChanged(
listener: (deviceId: string, tags: unknown) => void,
): () => void {
remoteTaskTagsChangedListeners.add(listener);
return () => {
remoteTaskTagsChangedListeners.delete(listener);
};
}
const remoteFavoritesChangedListeners = new Set<(deviceId: string) => void>();
const remoteProjectAliasesChangedListeners = new Set<(deviceId: string) => void>();
export function subscribeRemoteProjectAliasesChanged(listener: (deviceId: string) => void): () => void {
remoteProjectAliasesChangedListeners.add(listener);
return () => { remoteProjectAliasesChangedListeners.delete(listener); };
}
export function subscribeRemoteFavoritesChanged(listener: (deviceId: string) => void): () => void {
remoteFavoritesChangedListeners.add(listener);
return () => { remoteFavoritesChangedListeners.delete(listener); };
}
/**
* 被控端 `maker:orca:worker-changed`(payload `{leadSessionId}`)。只在控制端持有
* `session:<leadSessionId>` topic 时送达(会话页聚焦期间);收到后按 Lead 重拉 Worker 列表。
*/
const remoteOrcaWorkerChangedListeners = new Set<(deviceId: string, leadSessionId: string) => void>();
export function subscribeRemoteOrcaWorkerChanged(
listener: (deviceId: string, leadSessionId: string) => void,
): () => void {
remoteOrcaWorkerChangedListeners.add(listener);
return () => { remoteOrcaWorkerChangedListeners.delete(listener); };
}
const remoteBotChangedListeners = new Set<(deviceId: string, channel: string, payload: unknown) => void>();
export function subscribeRemoteBotChanges(listener: (deviceId: string, channel: string, payload: unknown) => void): () => void {
remoteBotChangedListeners.add(listener);
return () => { remoteBotChangedListeners.delete(listener); };
}
const remoteResourceChangedListeners = new Set<(
deviceId: string,
payload: RemoteResourceChangedPayload,
) => void>();
// 永久 link-close 后被抑制后台重建的设备(见 updateRehydrateSuppressionOnLinkClose)。
// 模块级(与 remoteResponseEvidenceEpochs 同模式):sendOpenLink 等模块级函数也需要
// 在显式重开成功时解除抑制。解除点:transport-timeout/权威 presence 可用快照/
// 新 relay 连接代际/显式 openLink 成功。
const rehydrateSuppressedDeviceIds = new Set<string>();
function markRemoteResponseEvidence(deviceId: string): void {
markPresenceAvailabilityEpoch(remoteResponseEvidenceEpochs, deviceId);
for (const listener of remoteResponseEvidenceListeners) listener(deviceId);
}
function subscribeRemoteResponseEvidence(
listener: (deviceId: string) => void,
): () => void {
remoteResponseEvidenceListeners.add(listener);
return () => remoteResponseEvidenceListeners.delete(listener);
}
function subscribeRemoteAgentRoster(
listener: (deviceId: string) => void,
): () => void {
remoteAgentRosterListeners.add(listener);
return () => remoteAgentRosterListeners.delete(listener);
}
function subscribeRemoteResourceChanged(
listener: (deviceId: string, payload: RemoteResourceChangedPayload) => void,
): () => void {
remoteResourceChangedListeners.add(listener);
return () => remoteResourceChangedListeners.delete(listener);
}
/**
* 退后台断开连接前的宽限:几秒内切回前台的快速 App 切换不触发整套
* 断连 → 重连 → 补齐,弱网下这套循环的代价远高于让 socket 多活两秒。
*/
const BACKGROUND_STOP_GRACE_MS = 2_500;
/** 断开前最多等最后一轮 heavy unsubscribe 应答;超时仍停止,避免后台 socket 久留。 */
const BACKGROUND_FINAL_UNSUBSCRIBE_WAIT_MS = 1_000;
/**
* 回前台时若「宽限计时器还挂着」但后台时长已超过此阈值,说明 JS 在计时器触发前
* 被 iOS 挂起——socket 大概率已被系统回收,但状态机还认为 online。此时主动换新
* 连接,别等心跳(~20s)才发现假活。
*/
const BACKGROUND_SUSPEND_SUSPECT_MS = 10_000;
/** 桌面端 presence 闪断宽限:短暂离线不立刻清空该设备的会话镜像与能力缓存。 */
const PRESENCE_OFFLINE_WIPE_GRACE_MS = 5_000;
/**
* 重连刚 online 时给乐观补齐留出的最小确认窗:覆盖连接就绪等待(1.5s)与
* 一次普通 invoke 往返,但只在旧 timer 剩余时间更短时向后延,不随抖动无限重置。
*/
const RECONNECT_MIN_WIPE_GRACE_MS = 3_000;
/**
* 断连补齐时拉的最新窗口大小。与 `hasMoreOlderMessages` 的判定共用同一个数:满页即说明这一页
* 上沿之外服务端还有历史,store 据此丢弃无法确认相接的更早缓存段(见 setLatestMessageWindow
* 与 #1222)。
*/
const RECONNECT_MESSAGE_WINDOW_LIMIT = 80;
// Provider remount / account switch must not reuse an in-flight snapshot key
// from an older DeviceLinkClient instance. Keep epochs process-monotonic.
let nextDeviceLinkConnectionEpoch = 0;
const SESSION_TOPIC_PREFIX = 'session:';
/**
* `session:<id>` 订阅停了 = 该会话的实时行从此不再送到本端(退后台释放重量级订阅、离开会话
* 取消订阅)。窗口「已验证连续」区间的上界因此不能再被之后到达的 push 续算 —— 与它之间可能漏了
* 任意多行(见 remoteSessionStore 的 sessionWindowCoverage)。socket 掉线走不带 sessionId 的整体
* 失效:那影响所有订阅。
*/
function noteSessionLiveStreamsInterrupted(topics: readonly string[]): void {
for (const topic of topics) {
if (!topic.startsWith(SESSION_TOPIC_PREFIX)) continue;
const sessionId = topic.slice(SESSION_TOPIC_PREFIX.length);
if (sessionId) remoteSessionStore.noteLiveStreamInterrupted(sessionId);
}
}
/**
* `session:<id>` 订阅被远端 ACK = 从此刻起该会话的行会被推过来。屏幕侧刻意不等 ACK 就拉页
* (`void subscribe(...)`),所以「页落库时订阅是否已 ACK」正是 store 判断尾部可不可信的依据
* (见 remoteSessionStore 的 `liveTailTrusted`)。ACK 本身不点亮既有区间:ACK 之前的空窗里可能
* 已经漏了行。
*/
function noteSessionLiveStreamsAcked(topics: readonly string[]): void {
for (const topic of topics) {
if (!topic.startsWith(SESSION_TOPIC_PREFIX)) continue;
const sessionId = topic.slice(SESSION_TOPIC_PREFIX.length);
if (sessionId) remoteSessionStore.noteLiveStreamAcked(sessionId);
}
}
export function DeviceLinkProvider({ children }: { children: ReactNode }) {
if (MOBILE_VISUAL_MOCK_ENABLED) {
return <VisualMockDeviceLinkProvider>{children}</VisualMockDeviceLinkProvider>;
}
const auth = useAuth();
// 官方中转 ↔ 自建中转切换时,与换账号走同一条重建连接的路径(见下方 client effect 依赖)。
const relayRouteGeneration = useSelfHostedRelayRouteGeneration();
const [directBridge] = useState(() => createDirectRuntimeBridge());
const sharedTaskApi = useSharedTaskApi();
const currentDataOwnerIdRef = useRef<string | null>(auth.user?.id ?? null);
currentDataOwnerIdRef.current = auth.user?.id ?? null;
useLayoutEffect(() => {
setRemoteProjectAliasesAccount(auth.isAuthenticated ? auth.user?.id ?? null : null, auth.accountGeneration);
}, [auth.accountGeneration, auth.isAuthenticated, auth.user?.id]);
const clientRef = useRef<DeviceLinkClient | null>(null);
const registryRef = useRef(new DeviceLinkTopicRegistry());
const [subscriptionVersion, setSubscriptionVersion] = useState(0);
const remoteSubscribedTopicsRef = useRef(new SubscriptionAcknowledgements(
() => setSubscriptionVersion((version) => version + 1),
));
// A local reliable ACK reset may happen after the last durable topic/open owner is gone,
// while the client still holds an in-flight reliable frame. Preserve a per-peer transient
// open intent until that exact peer is ready again; never promote it to a shared WSS reset.
const forcedPeerRecoveryIntentRef = useRef(new PeerRecoveryOpenIntentRegistry());
// 每台远端的补齐任务、rerun 与退避均由自己的状态槽管理;调度器只共享最多
// 六个并发恢复名额,不共享失败结论。run callback 经 ref 接最新 React 闭包。
const runPeerRecoveryRef = useRef<(deviceId: string) => Promise<PeerRecoveryResult>>(
async () => ({ retry: false }),
);
const peerRecoverySchedulerRef = useRef<PeerRecoveryScheduler | null>(null);
if (!peerRecoverySchedulerRef.current) {
peerRecoverySchedulerRef.current = new PeerRecoveryScheduler(
(deviceId) => runPeerRecoveryRef.current(deviceId),
{
onError: (deviceId, error) => mobileDeviceLinkLogger.warn(
`peer recovery failed unexpectedly device=${deviceId.slice(0, 8)}`,
error,
),
},
);
}
const recoveringDeviceIds = useSyncExternalStore(
peerRecoverySchedulerRef.current.subscribe,
peerRecoverySchedulerRef.current.getActiveDeviceIds,
);
const presenceWipeTimersRef = useRef(
new Map<string, PresenceWipeTimerEntry>(),
);
const [offlineMirrorWipeQueue] = useState(() => createOfflineMirrorWipeQueue(markOfflineDeviceMirrors));
const clearOnePresenceWipeTimer = useCallback((timers: Map<string, PresenceWipeTimerEntry>, deviceId: string) => {
clearPresenceWipeTimer(timers, deviceId, clearTimeout);
offlineMirrorWipeQueue.cancel(deviceId);
}, [offlineMirrorWipeQueue]);
const clearAllPresenceWipeTimers = useCallback((timers: Map<string, PresenceWipeTimerEntry>) => {
clearPresenceWipeTimers(timers, clearTimeout);
offlineMirrorWipeQueue.clear();
}, [offlineMirrorWipeQueue]);
const openLinkInFlightRef = useRef(
new Map<string, PresenceTrackedRequest<LinkAcceptPayload>>(),
);
const presenceWipeTimerDeps = useMemo(() => ({
...basePresenceWipeTimerDeps,
wipe: offlineMirrorWipeQueue.enqueue,
deferWipe: offlineMirrorWipeQueue.enqueue,
isConfirmationInFlight: (deviceId: string) =>
openLinkInFlightRef.current.get(deviceId)?.pending === true,
}), [offlineMirrorWipeQueue]);
const presenceAvailableByDeviceRef = useRef(new Map<string, boolean>());
const rosterConsumerRef = useRef<(() => (devices: DeviceView[]) => void) | null>(null);
const rosterRequestRef = useRef<{ client: DeviceLinkClient | null; epoch: number; promise: Promise<{ devices: DeviceView[] }> } | null>(null);
const rosterRequestGenerationRef = useRef(0);
const presenceAvailabilityEpochsRef = useRef(createPresenceAvailabilityEpochs());
const presencePendingRecoveryDeviceIdsRef = useRef(new Set<string>());
const presenceUnavailableVerdictsRef = useRef(
new Map<string, PresenceUnavailableVerdict>(),
);
// 后台释放 heavy session 订阅期间仍保留 registry 所有权;此时 unsubscribe ack
// 可以修正 stale offline verdict,但不能顺带触发 rehydrate 把刚释放的订阅加回来。
const backgroundReleaseInFlightRef = useRef(false);
const backgroundTransitions = useRef(new Set<Promise<void>>());
const beginBackgroundTransition = useCallback(() => {
let settle!: () => void;
const pending = new Promise<void>((resolve) => { settle = resolve; });
backgroundTransitions.current.add(pending);
return () => {
backgroundTransitions.current.delete(pending);
settle();
};
}, []);
// 每次后台释放都翻代。subscribe 即使跨 background→active 才收到 ACK,也只能在
// 发起代仍为当前代时登记远端 ACK,避免迟到成功覆盖较新的 unsubscribe。
const backgroundReleaseGenerationRef = useRef(0);
const [status, setStatus] = useState<DeviceLinkStatus>('stopped');
const [sharedTaskAvailable, setSharedTaskAvailable] = useState<boolean | undefined>();
const [connectionIssue, setConnectionIssue] = useState<DeviceLinkConnectionIssue | null>(null);
const [presenceVersion, setPresenceVersion] = useState(0);
const [connectionEpoch, setConnectionEpoch] = useState(0);
// status callback 中先同步推进 ref,再触发 rehydrate;React state 的下一次 render
// 才会把同一代暴露给页面。这样全局补齐与页面首开使用完全相同的 single-flight key。
const connectionEpochRef = useRef(0);
const [lastPresenceSnapshot, setLastPresenceSnapshot] = useState<PresenceSnapshot | null>(null);
const accountGenerationRef = useRef<number | null>(null);
// Home and direct task entry share the same in-flight roster read. Evidence
// belongs to the connection that started it, not whichever one finishes it.
const readDeviceList = useCallback((options: { fresh?: boolean } = {}): Promise<{ devices: DeviceView[] }> => {
const client = clientRef.current;
const epoch = connectionEpochRef.current;
const pending = rosterRequestRef.current;
if (!options.fresh && pending?.client === client && pending.epoch === epoch) return pending.promise;
const generation = ++rosterRequestGenerationRef.current;
const apply = rosterConsumerRef.current?.();
const promise = auth.apiFetch<{ devices: DeviceView[] }>('/api/device-link/devices', {
baseUrl: DEVICE_LINK_API_BASE_URL, timeoutMs: 12_000,
}).then((result) => {
// A fresh read supersedes every older roster consumer, even when the older
// response arrives first and would otherwise outrank the new snapshot.
if (rosterRequestGenerationRef.current === generation) apply?.(result.devices);
return result;
});
rosterRequestRef.current = { client, epoch, promise };
void promise.finally(() => {
if (rosterRequestRef.current?.promise === promise) rosterRequestRef.current = null;
}).catch(() => undefined);
return promise;
}, [auth.apiFetch, auth.accountGeneration]);
const clearPerAccountDeviceLinkState = useCallback(() => {
remoteSessionStore.clear();
clearSessionScheduleIndexCache();
remoteScheduleEventStore.clearAll();
revokedDevicesStore.clearAll();
resetDeviceResponsivenessTracking();
clearAllDeviceProviders();
clearAllProviderShareCatalogs();
clearAllDeviceModelMeta();
resetAgentCapabilitiesCache();
resetComposerPaletteCache();
resetTaskTagCatalogCache();
setLastPresenceSnapshot(null);
setPresenceVersion((version) => version + 1);
}, []);
/**
* availability 放在 ref 里供 transport 同步读取;每次真实的三态变化也必须发布给
* Context consumers。before / after 比较避免 rehydrate 重试重复写 false 时制造
* 无意义渲染,也避免只清 verdict、availability 仍为 unknown 时误报变化。
*/
const publishPresenceAvailabilityMutation = useCallback(<T,>(
deviceId: string,
mutate: (availabilityByDevice: Map<string, boolean>) => T,
): T => {
const availabilityByDevice = presenceAvailableByDeviceRef.current;
const before = availabilityByDevice.get(deviceId) ?? null;
const result = mutate(availabilityByDevice);
const after = availabilityByDevice.get(deviceId) ?? null;
if (before !== after) setPresenceVersion((version) => version + 1);
return result;
}, []);
const sendOpenLinkOnce = useCallback((
client: DeviceLinkClient,
deviceId: string,
allowProbe = false,
refreshSettled = false,
pendingReplyRecovery = false,
) => {
const connectionEpoch = connectionEpochRef.current;
const releaseGeneration = backgroundReleaseGenerationRef.current;
const checkAvailability = () => {
if (pendingReplyRecovery && (
clientRef.current !== client
|| connectionEpochRef.current !== connectionEpoch
|| backgroundReleaseGenerationRef.current !== releaseGeneration
|| backgroundReleaseInFlightRef.current
|| AppState.currentState !== 'active'
|| client.getStatus() !== 'online'
|| revokedDevicesStore.has(deviceId)
|| client.isOutboundExplicitlyClosed(deviceId)
|| rehydrateSuppressedDeviceIds.has(deviceId)
|| !client.hasPendingRequestsTo(deviceId)
)) {
throw new DeviceLinkError('NOT_CONNECTED', 'pending reply recovery is no longer current');
}
if (presenceAvailableByDeviceRef.current.get(deviceId) === false) {
const disabled = presenceUnavailableVerdictsRef.current.get(deviceId)?.kind === 'disabled';
throw new DeviceLinkError(disabled ? 'REMOTE_DISABLED' : 'DEVICE_OFFLINE', 'remote device is unavailable');
}
};
return getOrCreatePresenceTrackedRequest(
openLinkInFlightRef.current,
presenceAvailabilityEpochsRef.current,
remoteResponseEvidenceEpochs,
deviceId,
() => sendOpenLinkWithAccessHandling(client, deviceId, allowProbe, checkAvailability, pendingReplyRecovery),
{ retainSuccessful: true, refreshSettled },
);
}, []);
const restorePendingReplyLinks = useCallback((client: DeviceLinkClient, refreshSettled = false) => {
// A running business probe owns the breaker/scheduler slot until its reply
// arrives. Restore only its transport: queuing this handshake behind that
// probe would make each wait for the other until timeout + backoff.
// Reuse the connection's single-flight cache; send no new business request
// and neither consume nor settle the existing probe's slot.
for (const deviceId of unresponsiveDevicesStore.getSnapshot()) {
if (!client.hasPendingRequestsTo(deviceId)) continue;
void sendOpenLinkOnce(client, deviceId, false, refreshSettled, true).request.catch(() => undefined);
}
}, [sendOpenLinkOnce]);
const refreshProjectAliasesForClient = useCallback((
client: DeviceLinkClient,
deviceId: string,
invalidated = false,
ownerStamp?: unknown,
): void => {
const epoch = connectionEpochRef.current;
const isCurrent = () => clientRef.current === client
&& client.getStatus() === 'online'
&& connectionEpochRef.current === epoch
&& remoteSubscribedTopicsRef.current.get(deviceId)?.has('sessions') === true
&& registryRef.current.hasTopic(deviceId, 'sessions')
&& !backgroundReleaseInFlightRef.current
&& !revokedDevicesStore.has(deviceId)
&& presenceAvailableByDeviceRef.current.get(deviceId) !== false;
// A delayed push from a suspended peer must not restore its previous owner watermark.
if (!isCurrent() || (invalidated && !acceptRemoteProjectAliasesChanged(deviceId, ownerStamp, isCurrent))) return;
void refreshRemoteProjectAliases(deviceId, () => sendInvokeWithAccessHandling(
client, deviceId, PROJECT_ALIASES_GET_CHANNEL, [], {
preSend: () => {
if (!isCurrent()) throw new DeviceLinkError('NOT_CONNECTED', 'project alias read superseded');
},
},
), isCurrent, invalidated);
}, []);
const sendTrackedSubscribe = useCallback(async (
client: DeviceLinkClient,
deviceId: string,
topics: readonly Topic[],
) => {
const releaseGeneration = backgroundReleaseGenerationRef.current;
topics = sharedTaskTopics(deviceId, topics);
const record = recoveryDiagnostics.get(client)?.capture(deviceId, connectionEpochRef.current);
await confirmTrackedSubscription({
isCurrent: () => presenceAvailableByDeviceRef.current.get(deviceId) !== false && !backgroundReleaseInFlightRef.current
&& backgroundReleaseGenerationRef.current === releaseGeneration && clientRef.current === client,
generation: () => `${connectionEpochRef.current}:${remoteSubscribedTopicsRef.current.generation(deviceId)}`,
missing: () => topicsMissingRemoteAck(remoteSubscribedTopicsRef.current, deviceId, topics)
.filter((topic) => registryRef.current.hasTopic(deviceId, topic)),
send: (toSend) => sendSubscribeWithAccessHandling(
client,
deviceId,
toSend,
() => (
presenceAvailableByDeviceRef.current.get(deviceId) !== false
&& !backgroundReleaseInFlightRef.current
&& toSend.every((topic) => registryRef.current.hasTopic(deviceId, topic))
),
),
acknowledge: (toSend) => {
// 只有仍被持有、真正记进 ACK 表的 topic 才算订阅生效(中途被释放的那些不算)。
const held = markHeldRemoteTopicsSubscribed(remoteSubscribedTopicsRef.current, registryRef.current, deviceId, toSend);
noteSessionLiveStreamsAcked(held);
if (held.length > 0) record?.('subscription', 'applied', held.length);
mobileDebugLog('debug', 'recovery', 'subscription acknowledged', { topicCount: held.length });
},
});
if (topics.includes('sessions')) refreshProjectAliasesForClient(client, deviceId);
}, [refreshProjectAliasesForClient]);
// 熔断 open 设备的显式代表性探测:openLink 建链(成功按不定论,不关熔断),
// 再发一条真正穿过被控端 runInvoke → dispatchLocalInvoke → local-db 的最小读,
// 由 sendInvoke 内部的熔断收尾决定开合(真实回包 → 关;超时 → 加深退避)。
// 错误全吞:结果已在 send 层按熔断语义上报,这里不需要二次处理。
const probeUnresponsiveDevice = useCallback(
async (client: DeviceLinkClient, deviceId: string): Promise<void> => {
try {
if (isSharedTaskPeer(deviceId)) {
const owner = getMobileAuthOwner();
await probeSharedTaskHost(deviceId, {
isCurrent: () => clientRef.current === client && isMobileAuthOwnerCurrent(owner),
get: (sharedTaskId) => sharedTaskApi.get(sharedTaskId),
openLink: () => sendOpenLinkOnce(client, deviceId, true).request,
invoke: (channel, args) => sendInvokeWithAccessHandling(client, deviceId, channel, args, { allowProbe: true }),
});
return;
}
await sendOpenLinkOnce(client, deviceId, true).request;
await sendInvokeWithAccessHandling(
client,
deviceId,
DEVICE_RESPONSIVENESS_PROBE_CHANNEL,
buildDeviceResponsivenessProbeArgs(),
{ allowProbe: true },
);
} catch {
// swallow — settle 已在 sendOpenLink / sendInvoke 内完成。
}
},
[sendOpenLinkOnce, sharedTaskApi],
);
const hasOutboundPeerRecoveryIntent = useCallback((
client: DeviceLinkClient,
deviceId: string,
) => (
!client.isOutboundExplicitlyClosed(deviceId)
&& (
registryRef.current.snapshotDevice(deviceId) !== null
|| client.hasPendingRequestsTo(deviceId)
)
), []);
const requestForcedPeerRecovery = useCallback((
client: DeviceLinkClient,
deviceId: string,
): boolean => {
if (!hasOutboundPeerRecoveryIntent(client, deviceId)) {
forcedPeerRecoveryIntentRef.current.cancel(deviceId);
return false;
}
forcedPeerRecoveryIntentRef.current.request(deviceId);
return true;
}, [hasOutboundPeerRecoveryIntent]);
const runPeerRecovery = useCallback(async (
client: DeviceLinkClient,
targetDeviceId: string,
): Promise<PeerRecoveryResult> => {
if (
client !== clientRef.current
|| client.getStatus() !== 'online'
|| backgroundReleaseInFlightRef.current
) {
return { retry: false };
}
// 撤权、权威离线、远控关闭和永久 link-close 都只终止本 peer 的恢复。
if (
revokedDevicesStore.has(targetDeviceId)
|| client.isOutboundExplicitlyClosed(targetDeviceId)
|| !isPresenceEligibleForRemoteRequest(
presenceAvailableByDeviceRef.current,
targetDeviceId,
)
|| rehydrateSuppressedDeviceIds.has(targetDeviceId)
) {
return { retry: false };
}
// 熔断 peer 只跑自己的代表性探测;它等待/超时不会占住其它设备的恢复状态。
if (unresponsiveDevicesStore.has(targetDeviceId)) {
if (isDeviceProbeDue(targetDeviceId)) {
await probeUnresponsiveDevice(client, targetDeviceId);
}
return { retry: unresponsiveDevicesStore.has(targetDeviceId) };
}
const durablePlan = registryRef.current.snapshotDevice(targetDeviceId);
const forcedGeneration = forcedPeerRecoveryIntentRef.current.getGeneration(targetDeviceId);
const forcedOpen = forcedGeneration !== undefined
&& hasOutboundPeerRecoveryIntent(client, targetDeviceId);
if (forcedGeneration !== undefined && !forcedOpen) {
forcedPeerRecoveryIntentRef.current.cancel(targetDeviceId);
}
const plan = resolvePeerRecoveryPlan(
targetDeviceId,
durablePlan,
forcedOpen,
);
if (!plan) return { retry: false };
// 只失效当前 peer 的旧成功快照和瞬时链路失败,避免 A 的恢复改变 B 的节流状态。
invalidateScheduleIndexesAfterLinkRecovery(targetDeviceId);
const result = await rehydrateDeviceLinkPeer(plan, {
isCancelled: () => (
backgroundReleaseInFlightRef.current
|| client !== clientRef.current
|| client.getStatus() !== 'online'
|| revokedDevicesStore.has(targetDeviceId)
|| client.isOutboundExplicitlyClosed(targetDeviceId)
|| !isPresenceEligibleForRemoteRequest(
presenceAvailableByDeviceRef.current,
targetDeviceId,
)
|| rehydrateSuppressedDeviceIds.has(targetDeviceId)
|| unresponsiveDevicesStore.has(targetDeviceId)
),
capturePresenceEpoch: (deviceId) =>
capturePresenceAvailabilityEpoch(
presenceAvailabilityEpochsRef.current,
deviceId,
),
captureResponseEvidenceEpoch: (deviceId) =>
capturePresenceAvailabilityEpoch(
remoteResponseEvidenceEpochs,
deviceId,
),
isPresenceEpochCurrent: (deviceId, capturedPresenceEpoch) =>
isPresenceAvailabilityEpochCurrent(
presenceAvailabilityEpochsRef.current,
deviceId,
capturedPresenceEpoch,
),
isResponseEvidenceEpochCurrent: (
deviceId,
capturedResponseEvidenceEpoch,
) => isPresenceAvailabilityEpochCurrent(
remoteResponseEvidenceEpochs,
deviceId,
capturedResponseEvidenceEpoch,
),
createDeviceSendCohort: (deviceId) => createDeviceSendCohort(deviceId),
openLink: (deviceId) => sendOpenLinkOnce(client, deviceId),
subscribe: (deviceId, topics) => sendTrackedSubscribe(client, deviceId, topics),
requestSessionsReseed: (deviceId) => remoteSessionStore.requestReseed(deviceId),
onDeviceReachable: (deviceId) => {
// 重连后没有全量 presence;目标端真实应答足以收口上一代遗留清理,
// 但不伪造 available=true,仍服从之后到达的权威 presence。
clearOnePresenceWipeTimer(presenceWipeTimersRef.current, deviceId);
remoteScheduleEventStore.clearDeviceMirrorInvalidation(deviceId);
invalidateOfflineScheduleIndexFailureFor(deviceId);
},
onDeviceRemoteDisabled: (deviceId) => {
clearOnePresenceWipeTimer(presenceWipeTimersRef.current, deviceId);
publishPresenceAvailabilityMutation(deviceId, (availabilityByDevice) => {
availabilityByDevice.set(deviceId, false);
});
presenceUnavailableVerdictsRef.current.set(deviceId, {
kind: 'disabled',
responseEvidenceEpoch: capturePresenceAvailabilityEpoch(
remoteResponseEvidenceEpochs,
deviceId,
),
});
presencePendingRecoveryDeviceIdsRef.current.add(deviceId);
clearDeviceResponsivenessTrackingFor(deviceId);
remoteSubscribedTopicsRef.current.delete(deviceId);
wipeUnavailableDeviceMirror(deviceId);
},
onDeviceUnavailable: (deviceId) => {
suspendRemoteProjectAliases(deviceId);
if (isSharedTaskPeer(deviceId)) {
// Logical peers have no same-account presence entry. Preserve the
// existing bounded peer retry instead of waiting for an impossible
// physical-presence transition. Never restart the shared relay.
remoteSubscribedTopicsRef.current.delete(deviceId);
clearDeviceResponsivenessTrackingFor(deviceId);
setPresenceVersion((version) => version + 1);
return;
}
publishPresenceAvailabilityMutation(deviceId, (availabilityByDevice) => {
availabilityByDevice.set(deviceId, false);
});
presenceUnavailableVerdictsRef.current.set(deviceId, {
kind: 'offline',
responseEvidenceEpoch: capturePresenceAvailabilityEpoch(
remoteResponseEvidenceEpochs,
deviceId,
),
});
presencePendingRecoveryDeviceIdsRef.current.add(deviceId);
clearDeviceResponsivenessTrackingFor(deviceId);
remoteSubscribedTopicsRef.current.delete(deviceId);
scheduleUnavailableDeviceMirrorWipe(
presenceWipeTimersRef.current,
presenceAvailableByDeviceRef.current,
deviceId,
presenceWipeTimerDeps,
);
},
rebuildSessionSnapshot: (deviceId, sessionId, opts) => {
const epoch = connectionEpochRef.current;
const releaseGeneration = backgroundReleaseGenerationRef.current;
return rebuildSessionSnapshot(client, deviceId, sessionId, epoch, {
...opts,
subscriptionIdentity: remoteSubscribedTopicsRef.current.identity(deviceId, sharedTaskTopics(deviceId, ['sessions', `session:${sessionId}`])),
}, () => client === clientRef.current
&& client.getStatus() === 'online'
&& connectionEpochRef.current === epoch
&& backgroundReleaseGenerationRef.current === releaseGeneration
&& !backgroundReleaseInFlightRef.current
&& !revokedDevicesStore.has(deviceId)
&& !client.isOutboundExplicitlyClosed(deviceId));
},
});
if (
forcedGeneration !== undefined
&& result.linkOpened
&& client === clientRef.current
&& forcedPeerRecoveryIntentRef.current.complete(targetDeviceId, forcedGeneration)
) {
// `complete` performs the generation-checked removal in the condition above.
}
const forcedOpenStillPending = forcedPeerRecoveryIntentRef.current.has(targetDeviceId)
&& client === clientRef.current
&& client.getStatus() === 'online'
&& !revokedDevicesStore.has(targetDeviceId)
&& hasOutboundPeerRecoveryIntent(client, targetDeviceId)
&& isPresenceEligibleForRemoteRequest(
presenceAvailableByDeviceRef.current,
targetDeviceId,
)
&& !rehydrateSuppressedDeviceIds.has(targetDeviceId);
return {
retry: result.transientFailures > 0
|| unresponsiveDevicesStore.has(targetDeviceId)
|| forcedOpenStillPending,
};
}, [
probeUnresponsiveDevice,
clearOnePresenceWipeTimer,
presenceWipeTimerDeps,
hasOutboundPeerRecoveryIntent,
publishPresenceAvailabilityMutation,
sendOpenLinkOnce,
sendTrackedSubscribe,
]);
const rehydrateWithClient = useCallback((
client: DeviceLinkClient,
targetDeviceId?: string,
): Promise<void> => {
if (
client !== clientRef.current
|| client.getStatus() !== 'online'
|| backgroundReleaseInFlightRef.current
) {
return Promise.resolve();
}
const scheduler = peerRecoverySchedulerRef.current;
scheduler?.resume();
if (targetDeviceId) {
scheduler?.request(targetDeviceId);
} else {
// Relay 重连 / App 回前台可能漏过日程推送:在通知页面恢复前统一失效
// 旧成功快照和本机断线负缓存。单 peer 恢复仍只清自己的缓存。
invalidateScheduleIndexesAfterLinkRecovery();
const deviceIds = new Set(registryRef.current.deviceIds());
for (const deviceId of forcedPeerRecoveryIntentRef.current.deviceIds()) {
deviceIds.add(deviceId);
}
for (const deviceId of unresponsiveDevicesStore.getSnapshot()) {
deviceIds.add(deviceId);
}
scheduler?.requestMany(deviceIds);
}
return Promise.resolve();
}, []);
useEffect(() => {
runPeerRecoveryRef.current = (deviceId) => {
const client = clientRef.current;
if (!client) return Promise.resolve({ retry: false });
return runPeerRecovery(client, deviceId);
};
}, [runPeerRecovery]);
useEffect(() => {
const accountGenerationChanged =
accountGenerationRef.current !== auth.accountGeneration;
accountGenerationRef.current = auth.accountGeneration;
if (!auth.isAuthenticated) {
clientRef.current?.stop();
clientRef.current = null;
registryRef.current.clear();
remoteSubscribedTopicsRef.current.clear();
forcedPeerRecoveryIntentRef.current.clear();
peerRecoverySchedulerRef.current?.clear();
clearAllPresenceWipeTimers(presenceWipeTimersRef.current);
openLinkInFlightRef.current.clear();
presenceAvailableByDeviceRef.current.clear();
resetPresenceAvailabilityEpochs(presenceAvailabilityEpochsRef.current);
resetPresenceAvailabilityEpochs(remoteResponseEvidenceEpochs);
presencePendingRecoveryDeviceIdsRef.current.clear();
presenceUnavailableVerdictsRef.current.clear();
backgroundReleaseInFlightRef.current = false;
setStatus('stopped');
setSharedTaskAvailable(undefined);
setConnectionIssue(null);
// 登出 / 进程内切号:清掉所有 per-account 残留,避免下一个账号串到上一个账号的数据。
// - 供应商目录是 module 级单例缓存(useDeviceProviders 按 deviceId 命中),不随组件卸载清;
// - lastPresenceSnapshot 是本 context 的 state,home 屏据它 patch 设备列表。
// 二者若不重置,切号后会短暂看到 / 用到上一个账号的桌面端与供应商数据。
clearPerAccountDeviceLinkState();
return;
}
// 账号切换期间 isAuthenticated 始终为 true,不能依赖上面的登出分支。
// effect cleanup 只负责 transport;新账号建连前必须同步清掉旧账号的任务、
// 调度、设备与 presence 投影,避免无设备的新账号永远保留旧快照。
if (accountGenerationChanged) {
clearPerAccountDeviceLinkState();
// Topic intent is account-owned too. Keeping the previous account's owners here would make
// the new client's first online recovery subscribe device ids that its Home never selected.
registryRef.current.clear();
remoteSubscribedTopicsRef.current.clear();
forcedPeerRecoveryIntentRef.current.clear();
}
// 新账号/新 client 必须从空的 peer 生命周期表开始;旧连接迟到的恢复结果
// 会被 scheduler generation 丢弃,不能写回新账号。
peerRecoverySchedulerRef.current?.clear();
// 旧 client 的连接问题(如被自建中转移除的 4410)属于旧连接;cleanup 先退订再 stop,
// 新 client 不会替它清掉,这里显式清空。
setConnectionIssue(null);
// 这个 client 只服务创建时的那一代路由;路由一变 effect 会重建 client。
const clientRelayRoute = getSelfHostedRelayRouteGeneration();
const getAccessToken = auth.getAccessToken;
const client = new DeviceLinkClient({
directRuntime: directBridge.runtime,
getWsUrl: () => deviceLinkWsUrl(),
// 自建中转用中转凭证 + CindyRelay,账号 token 绝不发往中转(docs/self-hosted-relay-plan.md §5.2)。
// 先等本账号的中转设置读完,避免冷启动先连上官方再切走;取 token 期间路由变了就放弃这一轮,
// 不让官方 token 与 CindyRelay 方案、中转地址拼到同一次握手里。
getToken: async () => {
await waitForSelfHostedRelayRoute();
if (getSelfHostedRelayRouteGeneration() !== clientRelayRoute) return null;
const relay = getActiveSelfHostedRelay();
if (relay) return relay.credential;
const token = await getAccessToken();
return getSelfHostedRelayRouteGeneration() === clientRelayRoute ? token : null;
},
authorizationScheme: () => (getActiveSelfHostedRelay() ? 'CindyRelay' : 'Bearer'),
// 自建中转的设备签名(docs/self-hosted-relay-plan.md §16);官方中转返回 null。
// 收到的消息在分发前核对主人签发的设备证书与帧签名,防止中转替换权限请求的展示内容。
frameAuth: currentSelfHostedRelayFrameAuth,
getHello: () => ({
capabilities: [SHARED_TASK_CAPABILITY],
deviceName: mobileDeviceName(),
platform: Platform.OS,
appVersion: Constants.expoConfig?.version ?? '0.0.0',
remoteControlEnabled: false,
busy: false,
}),
createWebSocket: createRnWebSocket,
logger: mobileDeviceLinkLogger,
// 弱网减流量:声明可解 gzip,大结果压缩、内容未变的结果只回标记(被控端支持时)。
transferCodec: { gunzipBase64: decodeGzipBase64TextBounded },
invokeMetrics: { enabled: jankMetricsEnabled, record: recordInvokeTransfer },
// Mobile 具备按 deviceId 独立 openLink/订阅/快照恢复能力。可靠 ACK
// 耗尽时只复位该 peer,共享 WSS 和其它远端继续工作;恢复仍只使用所有
// Desktop 版本都支持的 link-open,不增加 wire/capability 要求。
peerFailurePolicy: 'isolate-peer',
// 手机弱网(切基站 / 弱 WiFi)下 TCP 半开假活远比桌面常见,收紧心跳把
// 半开检测从默认 ~60s(20s×3 tick)压到 ~20s(10s×2 tick);检测到即
// fail 全部 pending invoke,不让用户操作干等 30s 请求超时。仅手机端
// opt-in 覆盖,桌面端默认曲线不变。
timing: {
pingIntervalMs: 10_000,
pongMissLimit: 1,
getTokenTimeoutMs: 10_000,
handshakeTimeoutMs: 12_000,
// 请求超时收紧到 15s(默认 30s):被控端卡死时 30s 才失败让用户干等半分钟,
// 也把熔断器凑齐「连续超时」信号的时间拖长一倍。长执行通道(desktop-cmd:run /
// worktree:create / schedule 等)在 sendInvoke 按 invokeTimeouts 解析规则单独放宽,
// 与桌面控制端同一张协议契约表,不受此默认值影响。
requestTimeoutMs: 15_000,
},
});
meterDeviceLinkInvokes(client);
clientRef.current = client;
const catalogRefresh = createDeviceCatalogRefresh({
connectionEpoch: () => connectionEpochRef.current,
canRead: (deviceId) => client === clientRef.current
&& client.getStatus() === 'online'
&& !backgroundReleaseInFlightRef.current
&& !unresponsiveDevicesStore.has(deviceId)
&& !revokedDevicesStore.has(deviceId)
&& presenceAvailableByDeviceRef.current.get(deviceId) !== false,
readProviders: (deviceId) => sendInvokeWithAccessHandling<DeviceProvidersPayload>(
client, deviceId, 'maker:provider:list',
[{ capabilities: [CONTROLLER_CAPABILITY_PROVIDER_LOGO_KINDS_V2] }],
),
readCapabilities: (deviceId, agent) => sendInvokeWithAccessHandling<unknown>(
client, deviceId, 'maker:get-capabilities', [agent],
),
});
const rehydrate = (deviceId?: string) => {
catalogRefresh.wake(deviceId);
return rehydrateWithClient(client, deviceId);
};
mobileDebugLog('debug', 'device-link', 'runtime identity', mobileRuntimeIdentity());
const diagnostics = createRecoveryDiagnostics(
(event) => mobileDeviceLinkLogger.info('recovery phase', event),
() => connectionEpochRef.current,
);
recoveryDiagnostics.set(client, diagnostics);
if (AppState.currentState === 'active') diagnostics.foreground();
let networkPathChanged = false;
let lastConnectedNetworkType: string | undefined;
const recoverNetwork = (urgent: boolean) => {
const replaceOldPath = networkPathChanged;
networkPathChanged = false;
// Only this phone's established connection used the lost route. Keep
// handshakes and congestion backoff on their existing recovery path.
if (replaceOldPath && client.getStatus() === 'online') {
client.restartConnection('network-path-changed');
} else {
client.notifyNetworkChanged({ urgent });
}
};
const offIssue = client.onConnectionIssue(setConnectionIssue);
const offStatus = client.onStatusChange((next) => {
setStatus(next);
setSharedTaskAvailable(next === 'online' ? client.hasServerCapability(SHARED_TASK_CAPABILITY) : undefined);
if (next !== 'online') {
catalogRefresh.clear();
openLinkInFlightRef.current.clear();
remoteSubscribedTopicsRef.current.clear();
// 掉线:所有会话的实时行都可能从此漏收,窗口连续性结论的上界不再可续算。
remoteSessionStore.noteLiveStreamInterrupted();
// Relay 连接故障才暂停全部 peer;重新 online 后它们各自重新进入恢复队列。
peerRecoverySchedulerRef.current?.pause();
return;
}
// A new authenticated connection already supersedes any retained old path.
networkPathChanged = false;
// presence 是当前在线控制端收到的 delta,server 不会在 hello-ack 后重放
// 全量快照。进入新连接代际先丢弃旧 verdict:后台期间若设备从 unavailable
// 恢复,旧 false 不能永久挡住本轮 rehydrate。上一代仍 pending 的镜像清理
// 保留原宽限截止点:计时器把新连接尚无 verdict 的 unknown 当作未确认恢复,
// 只有当前代明确 available=true 才取消,避免重连瞬间按旧 false 提前清空镜像。
const staleUnavailableDeviceIds = resetPresenceAvailabilityForConnection(
presenceAvailableByDeviceRef.current,
presencePendingRecoveryDeviceIdsRef.current,
);
// 新连接代际 = 世界重置:永久关闭抑制不跨代际(断线期间对方状态未知,
// 新代按乐观补齐;若对方仍拒绝,入站永久 link-close 会重新建立抑制)。
liftRehydrateSuppressionForNewConnection(rehydrateSuppressedDeviceIds);
// 上一连接代的 rehydrate verdict 已被降为 unknown;新连接的 late response
// 不能再借旧 verdict 清理当前代状态。权威 presence 会在 delta 到达时重建。
for (const deviceId of staleUnavailableDeviceIds) {
presenceUnavailableVerdictsRef.current.delete(deviceId);
}
for (const deviceId of staleUnavailableDeviceIds) {
extendPresenceWipeTimerFloor(
presenceWipeTimersRef.current,
presenceAvailableByDeviceRef.current,
deviceId,
RECONNECT_MIN_WIPE_GRACE_MS,
presenceWipeTimerDeps,
);
}
connectionEpochRef.current = ++nextDeviceLinkConnectionEpoch;
setConnectionEpoch(connectionEpochRef.current);
resetRemoteProjectOrderPushFence();
suspendRemoteProjectAliases();
restorePendingReplyLinks(client);
void rehydrate();
// A new controller receives only presence deltas. Read the roster once so
// an already-offline host is known even when opening directly into history.
void readDeviceList().catch(() => undefined);
});
const offPeerTransportReset = client.onPeerTransportReset(({ deviceId }) => {
// 这是本地 ACK 超时,不是对端可达证据:只失效该 peer 的建链缓存和
// 订阅 ACK,再排该 peer 恢复;presence、其它 peer 与共享 WSS 均不动。
resetRemoteProjectOrderPushFence(deviceId);
suspendRemoteProjectAliases(deviceId);
const shouldRecover = requestForcedPeerRecovery(client, deviceId);
invalidatePeerLinkState(
deviceId,
openLinkInFlightRef.current,
remoteSubscribedTopicsRef.current,
noteSessionLiveStreamsInterrupted,
);
if (shouldRecover) void rehydrate(deviceId);
});
const applyPresence = (snap: PresenceSnapshot) => {
markPresenceAvailabilityEpoch(presenceAvailabilityEpochsRef.current, snap.deviceId);
// presence 变化代表目标链路代际变化(offline / remote-disabled / 恢复都一样):
// 上一代成功 link 不能跨代复用,下一次请求必须重新 link-open 确认。
openLinkInFlightRef.current.delete(snap.deviceId);
setLastPresenceSnapshot(snap);
setPresenceVersion((n) => n + 1);
const presence = updatePresenceAvailability(
presenceAvailableByDeviceRef.current,
snap,
presencePendingRecoveryDeviceIdsRef.current,
);
if (presence.available) {
presenceUnavailableVerdictsRef.current.delete(snap.deviceId);
} else {
// Relay presence 是权威 availability verdict,普通目标应答不能推翻。
suspendRemoteProjectAliases(snap.deviceId);
presenceUnavailableVerdictsRef.current.set(snap.deviceId, {
kind: snap.online && !snap.remoteControlEnabled ? 'disabled' : 'presence',
responseEvidenceEpoch: capturePresenceAvailabilityEpoch(
remoteResponseEvidenceEpochs,
snap.deviceId,
),
});
}
const wipeTimers = presenceWipeTimersRef.current;
if (!presence.available) {
// 权威离线/关闭远控只取消对应 peer,不碰其它远端的在途恢复与退避。
peerRecoverySchedulerRef.current?.cancel(snap.deviceId);
// Relay 的权威 presence 已说明目标离线或关闭远控:此前 INVOKE_TIMEOUT
// 只能视为这次可用性变化的下游症状,不再代表桌面 IPC/DB 卡死。立即清除
// 响应性计数并翻代,让在途请求随后到达的 timeout 也无法重建误熔断。
// 清理响应性状态会触发 rehydrate,但 presence 仍是 unavailable 时该设备会被
// availablePlans 过滤,不再立即重放一批注定 DEVICE_OFFLINE 的请求。
clearDeviceResponsivenessTrackingFor(snap.deviceId);
// 订阅跟踪必须立即失效(不进宽限):桌面端断开可能已丢失订阅者状态,
// 恢复后的 rehydrate 靠 topicsMissingRemoteAck 判断要不要重发 subscribe,
// 跟踪不清会误判「已订阅」而跳过重订阅,push 流静默断掉。重订阅本身
// 便宜且服务端幂等;需要宽限的只是下面会引起界面闪烁的缓存清理。
remoteSubscribedTopicsRef.current.delete(snap.deviceId);
if (snap.online && !snap.remoteControlEnabled) {
// 用户在桌面端显式关闭了远控:立即清,镜像不该多留一秒
clearOnePresenceWipeTimer(wipeTimers, snap.deviceId);
wipeUnavailableDeviceMirror(snap.deviceId);
return;
}
// 桌面端离线:给一个短宽限。弱网下桌面端会反复闪断,每次都立即清空
// 会话镜像 + 能力缓存会让手机端界面整片消失重建、随后一轮 re-fetch 风暴;
// 宽限内恢复在线则取消清理(presence.recovered 分支照常触发补齐)。
scheduleUnavailableDeviceMirrorWipe(
wipeTimers,
presenceAvailableByDeviceRef.current,
snap.deviceId,
presenceWipeTimerDeps,
);
return;
}
clearOnePresenceWipeTimer(wipeTimers, snap.deviceId);
remoteScheduleEventStore.clearDeviceMirrorInvalidation(snap.deviceId);
// 每个「可用」快照都清该设备的 DEVICE_OFFLINE 负缓存(review P1 ×2):
// 主机在手机连上 relay 之前就离线时,presence 只在变化时广播,首个在线
// 快照 recovered=false——只挂 recovered 会漏掉这次恢复,徽标停留到无关
// 触发。逐设备且幂等(map 单点查删),不影响其它设备的风暴止损。
invalidateOfflineScheduleIndexFailureFor(snap.deviceId);
// 注意:普通 available=true 快照**不**解除永久关闭后的重建抑制——在线
// ≠ 对方重新授权或本机用户主动重开(对方结束链路后一直在线是常态)。
// 解除点只有:transport-timeout / 新连接代际 / 显式 openLink 成功
// (见 linkClose.ts 的具名 lift 入口)。
if (presence.recovered) void rehydrate(snap.deviceId);
};
const offPresence = client.onPresenceChanged(applyPresence);
rosterConsumerRef.current = () => {
const epoch = connectionEpochRef.current;
const presenceEpoch = presenceAvailabilityEpochsRef.current.next;
const responseEpoch = remoteResponseEvidenceEpochs.next;
return (devices) => {
if (clientRef.current !== client || connectionEpochRef.current !== epoch || client.getStatus() !== 'online') return;
for (const device of devices) {
const available = device.online && device.remoteControlEnabled;
const disabled = device.online && !device.remoteControlEnabled;
const wasDisabled = presenceUnavailableVerdictsRef.current.get(device.deviceId)?.kind === 'disabled';
if (device.isSelf || (presenceAvailableByDeviceRef.current.get(device.deviceId) === available && disabled === wasDisabled)
|| (presenceAvailabilityEpochsRef.current.byDevice.get(device.deviceId) ?? 0) > presenceEpoch
|| (!device.online && (remoteResponseEvidenceEpochs.byDevice.get(device.deviceId) ?? 0) > responseEpoch)) continue;
applyPresence({ ...device, deviceName: device.name, platform: device.platform ?? '',
appVersion: device.appVersion ?? '', lastSeenAt: Date.parse(device.lastSeenAt ?? '') || 0 });
}
};
};
const offFrame = client.onFrame((env) => routeFrameMeasured(env, {
currentDataOwnerId: currentDataOwnerIdRef.current,
onAccessRevoked: (deviceId) => {
clearOnePresenceWipeTimer(presenceWipeTimersRef.current, deviceId);
if (isSharedTaskPeer(deviceId)) setPresenceVersion((version) => version + 1);
catalogRefresh.cancel(deviceId);
removeRemoteProjectAliases(deviceId);
remoteSubscribedTopicsRef.current.delete(deviceId);
forcedPeerRecoveryIntentRef.current.cancel(deviceId);
peerRecoverySchedulerRef.current?.cancel(deviceId);
},
onLinkClosed: (deviceId, reason) => {
resetMobilePeer(deviceId);
if (isSharedTaskPeer(deviceId)) setPresenceVersion((version) => version + 1);
catalogRefresh.cancel(deviceId);
resetRemoteProjectOrderPushFence(deviceId);
suspendRemoteProjectAliases(deviceId);
updateRehydrateSuppressionOnLinkClose(
rehydrateSuppressedDeviceIds,
deviceId,
reason,
);
invalidatePeerLinkState(
deviceId,
openLinkInFlightRef.current,
remoteSubscribedTopicsRef.current,
noteSessionLiveStreamsInterrupted,
);
// transport-timeout = 被控端对本机的可靠重试耗尽后的 peer 级瞬时重置
// (relay 保持在线,不会有 presence 变化来触发恢复)。立即 rehydrate
// 重建链路与订阅:入口自带 online 检查、in-flight 去重与退避,幂等。
// 其它 reason(user/toggle-off/shutdown/revoked)维持原语义:只失效,
// 不自动重建。
if (reason === 'transport-timeout') {
const shouldRecover = requestForcedPeerRecovery(client, deviceId);
// 收到该帧本身就是对端可达的直接证据:先冲销遗留的 presence=false /
// 离线判定(否则本轮 rehydrate 会把该设备从 availablePlans 排除,
// 重建根本不会发起)。两段冲销:markRemoteResponseEvidence 走既有
// 证据链(epoch 比较,推翻并发窗口内的 offline verdict);
// reconcileAvailabilityAfterInboundFrame 补盖无 verdict 的 stale
// presence=false(入站帧无时序歧义,disabled 判定仍保留)。
// revoked/熔断/in-flight 去重等保护由 rehydrate 自身的既有门把守。
markRemoteResponseEvidence(deviceId);
publishPresenceAvailabilityMutation(deviceId, (availabilityByDevice) => (
reconcileAvailabilityAfterInboundFrame(
availabilityByDevice,
presencePendingRecoveryDeviceIdsRef.current,
presenceUnavailableVerdictsRef.current,
deviceId,
)
));
// 直接可达证据必须同步收口此前 unavailable presence 建的镜像清理
// 计时器:该 timer 的触发条件是 availability 非明确 true——若随后的
// open/subscribe/rehydrate 瞬时失败或停在 unknown,遗留 timer 仍会
// 把刚被本帧证明可达的设备的会话/调度/能力镜像误删。
// (markRemoteResponseEvidence 的证据链只在命中可推翻的 offline
// verdict 时才顺带清 timer,覆盖不了无 verdict 的 stale 路径。)
clearOnePresenceWipeTimer(presenceWipeTimersRef.current, deviceId);
if (shouldRecover) void rehydrate(deviceId);
} else {
forcedPeerRecoveryIntentRef.current.cancel(deviceId);
}
},
onProjectAliasesChanged: (deviceId, ownerStamp) => refreshProjectAliasesForClient(client, deviceId, true, ownerStamp),
onProviderChanged: (deviceId) => {
catalogRefresh.notify(deviceId);
},
onAgentsChanged: (deviceId) => {
for (const listener of remoteAgentRosterListeners) listener(deviceId);
},
}));
// 与 transport-timeout link-close 同族的链路死锁自救(互为兜底):对端还在按
// 可靠流给本机发帧,而本机侧 link 未就绪——典型成因是 link-accept 在弱网丢失
// 后互等(发送端等 ACK、接收端等 link)。transport-timeout 是对端主动通知
// (best-effort,本身可能丢帧);本回调是本机从入站帧自行推断,通知丢了也能
// 自救。client 层已做 30s/peer 节流。收到帧即对端可达的直接证据,处理与
// transport-timeout 分支一致:冲销遗留离线判定 → rehydrate 重建链路与订阅
// (online 检查 / in-flight 去重 / 退避 / revoked 与永久关闭抑制等既有门全部
// 由 rehydrate 把守;特别地,永久关闭抑制**不在此解除**——对端用户显式关闭
// 后即使迟到帧还在飞,也不把用户关掉的链路自动建回来)。
const offBeforeLink = client.onReliableFrameBeforeLink((deviceId) => {
// 先失效 peer 级缓存(与 transport-timeout 分支同序):收到 before-link 帧
// 说明 client 层 link 已不在就绪态,但 openLinkInFlightRef 可能还留着已
// resolved 的旧建链结果、remoteSubscribedTopicsRef 还留着旧 ACK——不清掉,
// rehydrate 会复用旧 open、跳过 subscribe,后续请求继续排进未就绪的可靠流
// (review P2)。
invalidatePeerLinkState(
deviceId,
openLinkInFlightRef.current,
remoteSubscribedTopicsRef.current,
noteSessionLiveStreamsInterrupted,
);
const shouldRecover = requestForcedPeerRecovery(client, deviceId);
markRemoteResponseEvidence(deviceId);
publishPresenceAvailabilityMutation(deviceId, (availabilityByDevice) => (
reconcileAvailabilityAfterInboundFrame(
availabilityByDevice,
presencePendingRecoveryDeviceIdsRef.current,
presenceUnavailableVerdictsRef.current,
deviceId,
)
));
clearOnePresenceWipeTimer(presenceWipeTimersRef.current, deviceId);
if (shouldRecover) void rehydrate(deviceId);
return shouldRecover;
});
client.start();
const offResponseEvidence = subscribeRemoteResponseEvidence((deviceId) => {
if (client === clientRef.current && isSharedTaskPeer(deviceId)) setPresenceVersion((version) => version + 1);
const currentEpoch = capturePresenceAvailabilityEpoch(
remoteResponseEvidenceEpochs,
deviceId,
);
if (!publishPresenceAvailabilityMutation(deviceId, (availabilityByDevice) => (
reconcileOfflineVerdictAfterResponse(
availabilityByDevice,
presencePendingRecoveryDeviceIdsRef.current,
presenceUnavailableVerdictsRef.current,
deviceId,
currentEpoch,
)
))) {
return;
}
clearOnePresenceWipeTimer(presenceWipeTimersRef.current, deviceId);
void rehydrate(deviceId);
});
// 熔断状态变化触发 rehydrate:unresponsive 集合的新增与移除都各触发一次
// (review P1 + 注释勘误):
// - 设备恢复(移除):补一次 rehydrate,把 open 期间被跳过的订阅/快照拉回来;
// - 设备进入 open(新增):也要触发一次——熔断可能由普通页面请求凑满超时打开,
// 此刻若没有已在跑的 rehydrate 退避循环,代表性探测根本无人发起,
// 主动恢复永远不会启动。触发的这轮会因 stillOpenDevices>0 进入 2s→30s
// 退避循环,成为探测心跳(窗口未到的轮次零管道流量,到点自动发探测)。
let lastUnresponsiveSnapshot = unresponsiveDevicesStore.getSnapshot();
const offUnresponsive = unresponsiveDevicesStore.subscribe(() => {
const next = unresponsiveDevicesStore.getSnapshot();
const changedDeviceIds = new Set<string>();
for (const deviceId of next) {
if (!lastUnresponsiveSnapshot.has(deviceId)) changedDeviceIds.add(deviceId);
}
for (const deviceId of lastUnresponsiveSnapshot) {
if (!next.has(deviceId)) changedDeviceIds.add(deviceId);
}
lastUnresponsiveSnapshot = next;
for (const deviceId of changedDeviceIds) {
void rehydrate(deviceId);
}
});
const releaseHeavyTopics = (): Promise<void>[] => {
const releases: Promise<void>[] = [];
for (const plan of registryRef.current.snapshot()) {
const heavy = plan.topics.filter((topic) => topic.startsWith(SESSION_TOPIC_PREFIX));
if (heavy.length === 0) continue;
markRemoteTopicsUnsubscribed(remoteSubscribedTopicsRef.current, plan.deviceId, heavy);
noteSessionLiveStreamsInterrupted(heavy);
if (client.getStatus() === 'online') {
releases.push(sendUnsubscribe(client, plan.deviceId, heavy));
}
}
return releases;
};
const backgroundConnection = createBackgroundConnection({
isBackground: () => AppState.currentState === 'background',
releaseTopics: releaseHeavyTopics,
pendingTransitions: () => [...backgroundTransitions.current],
stop: () => client.stop(),
connect: () => client.connectNow('appstate-active', {
overrideCongestionCooldown: true,
keepInFlightAttempt: true,
}),
graceMs: BACKGROUND_STOP_GRACE_MS,
releaseWaitMs: BACKGROUND_FINAL_UNSUBSCRIBE_WAIT_MS,
suspendMs: BACKGROUND_SUSPEND_SUSPECT_MS,
report: (event) => mobileDebugLog('debug', 'device-link', 'background lifecycle', event),
});
noteAppLifecycleState(AppState.currentState);
let refreshNetworkState = () => {};
const sub = AppState.addEventListener('change', (next) => {
// 先于下面的恢复动作记账:回前台后 rehydrate 新发的请求属于新生命周期。
noteAppLifecycleState(next);
if (next === 'active') {
refreshNetworkState();
diagnostics.foreground();
const resumingFromBackground = backgroundReleaseInFlightRef.current;
backgroundReleaseInFlightRef.current = false;
// 回前台立刻重连:绕开断线后遗留的指数退避计时器(可能 park 到 30s),
// 让"打开 App → 打开会话"路径快速恢复在线,而不是干等退避。
// overrideCongestionCooldown:用户显式回前台是拥塞冷却的合法豁免——
// 冷却默认只拦请求路径的 un-park(waitUntilOnline),不拦真人操作。
backgroundConnection.active();
// A short background stay can preserve a socket whose route changed.
// Replace a known old path; otherwise probe without the hint cooldown.
if (client.getStatus() === 'online') recoverNetwork(true);
// A short background stay retains successful handshakes on the same relay.
// Refresh those once per return, while sharing pending opens and repeated active hints.
restorePendingReplyLinks(client, resumingFromBackground);
// 快速切换(连接被宽限保住、始终 online)不会有 online 状态转换,这条显式
// 补齐就是断档回填的唯一触发点;其余路径下它因 status 未 online 而空转。
void rehydrate();
}
if (next === 'background') {
diagnostics.background();
backgroundReleaseInFlightRef.current = true;
backgroundReleaseGenerationRef.current += 1;
suspendRemoteProjectAliases();
// App 生命周期暂停全部恢复执行,但各 peer 状态仍彼此独立;回前台统一
// 重新排队,旧代请求的迟到结果不会创建重试。
peerRecoverySchedulerRef.current?.pause();
// 立即释放重量级 session:<id> 订阅(趁 socket 还活着、iOS 尚未挂起 JS):
// 被控桌面以「有人订阅该会话流」为防打扰信号压制手机系统推送,锁屏/切后台
// 后若订阅残留(宽限窗、挂起延迟最长可拖到 server 60s 空闲清扫),恰好在
// 用户离开的瞬间完成的任务就永远收不到通知。只动远端订阅与 ack 簿记,
// registry 所有权保留 —— 回前台的 rehydrate 会因 ack 已清而重新订阅。
backgroundConnection.background();
}
});
// Loaded inside the authenticated lifecycle; old native builds keep their
// existing heartbeat fallback if the optional runtime module is unavailable.
let disposed = false;
let networkSubscription: { remove(): void } | undefined;
let previousNetwork: NetworkState | undefined;
void import('expo-network').then(({ addNetworkStateListener, getNetworkStateAsync }) => {
if (disposed) return;
let networkRevision = 0;
const onNetworkState = (network: NetworkState) => {
if (disposed) return;
networkRevision += 1;
localNetworkStore.update(network);
if (localNetworkStore.getSnapshot().status === 'unavailable') {
// A phone-wide outage is not evidence against any individual computer.
resetDeviceResponsivenessTracking();
}
const urgent = previousNetwork !== undefined && (
previousNetwork.type !== network.type
|| previousNetwork.isConnected !== network.isConnected
|| previousNetwork.isInternetReachable !== network.isInternetReachable
);
previousNetwork = network;
mobileDebugLog('debug', 'device-link', 'network path notification', { type: network.type, connected: network.isConnected, reachable: network.isInternetReachable, appState: AppState.currentState, urgent });
// Native lookup failures can report UNKNOWN with isConnected=false.
// They neither prove route loss nor consume an earlier confirmed loss.
if (!network.type || network.type === 'UNKNOWN') {
if (AppState.currentState === 'active') client.notifyNetworkChanged({ urgent });
return;
}
// Reachability/capability notifications alone are not route changes:
// preserve the full weak-network probe budget for those hints.
if (network.isConnected === false) networkPathChanged = true;
if (network.isConnected === true && network.type !== 'NONE') {
if (lastConnectedNetworkType !== undefined && lastConnectedNetworkType !== network.type) {
networkPathChanged = true;
}
lastConnectedNetworkType = network.type;
}
if (AppState.currentState !== 'active' || network.isConnected === false) return;
recoverNetwork(urgent);
};
networkSubscription = addNetworkStateListener(onNetworkState);
refreshNetworkState = () => {
if (typeof getNetworkStateAsync !== 'function') return;
const revision = ++networkRevision;
void getNetworkStateAsync().then((network) => {
if (!disposed && revision === networkRevision) onNetworkState(network);
}).catch(() => { /* Keep listener evidence when the native lookup fails. */ });
};
refreshNetworkState();
}).catch(() => {
console.warn('[device-link] network listener unavailable; using heartbeat recovery');
});
return () => {
disposed = true;
diagnostics.background();
recoveryDiagnostics.delete(client);
networkSubscription?.remove();
localNetworkStore.update();
sub.remove();
backgroundConnection.dispose();
backgroundTransitions.current.clear();
offUnresponsive();
offResponseEvidence();
offBeforeLink();
offFrame();
catalogRefresh.dispose();
offPresence();
offPeerTransportReset();
offStatus();
offIssue();
client.stop();
rosterConsumerRef.current = null;
rosterRequestRef.current = null;
peerRecoverySchedulerRef.current?.clear();
clearAllPresenceWipeTimers(presenceWipeTimersRef.current);
openLinkInFlightRef.current.clear();
remoteSubscribedTopicsRef.current.clear();
forcedPeerRecoveryIntentRef.current.clear();
presenceAvailableByDeviceRef.current.clear();
resetPresenceAvailabilityEpochs(presenceAvailabilityEpochsRef.current);
resetPresenceAvailabilityEpochs(remoteResponseEvidenceEpochs);
presencePendingRecoveryDeviceIdsRef.current.clear();
presenceUnavailableVerdictsRef.current.clear();
backgroundReleaseInFlightRef.current = false;
if (clientRef.current === client) clientRef.current = null;
};
}, [
auth.accountGeneration,
auth.getAccessToken,
auth.isAuthenticated,
relayRouteGeneration,
clearPerAccountDeviceLinkState,
clearOnePresenceWipeTimer,
clearAllPresenceWipeTimers,
presenceWipeTimerDeps,
publishPresenceAvailabilityMutation,
rehydrateWithClient,
restorePendingReplyLinks,
requestForcedPeerRecovery,
readDeviceList,
refreshProjectAliasesForClient,
]);
const openLink = useCallback(
async (deviceId: string) => {
registryRef.current.trackOpenLink(deviceId);
return sendOpenLinkOnce(requireClient(clientRef.current), deviceId).request;
},
[sendOpenLinkOnce],
);
const reopenLink = useCallback(
async (deviceId: string) => {
registryRef.current.trackOpenLink(deviceId);
return sendOpenLinkOnce(
requireClient(clientRef.current),
deviceId,
false,
true,
).request;
},
[sendOpenLinkOnce],
);
const closeLink = useCallback((deviceId: string) => {
resetMobilePeer(deviceId);
registryRef.current.untrackOpenLink(deviceId);
forcedPeerRecoveryIntentRef.current.cancel(deviceId);
openLinkInFlightRef.current.delete(deviceId);
clientRef.current?.closeLink(deviceId, 'user');
}, []);
const invoke = useCallback(async <T,>(
deviceId: string,
channel: string,
args: unknown[] = [],
opts?: { preSend?: () => void; background?: boolean },
) => {
const preSend = () => {
if (presenceAvailableByDeviceRef.current.get(deviceId) === false) {
const disabled = presenceUnavailableVerdictsRef.current.get(deviceId)?.kind === 'disabled';
throw new DeviceLinkError(disabled ? 'REMOTE_DISABLED' : 'DEVICE_OFFLINE', 'remote device is unavailable');
}
opts?.preSend?.();
};
preSend();
const client = requireClient(clientRef.current);
const result = await invokeWithHistoryViewCapability(
channel,
async () => {
// Reuse the existing peer-scoped handshake cache and its invalidation.
// A late accept from an obsolete link must not declare a downgrade.
const tracked = sendOpenLinkOnce(client, deviceId);
const accepted = await tracked.request;
if (clientRef.current !== client || openLinkInFlightRef.current.get(deviceId) !== tracked) {
throw new DeviceLinkError('NOT_CONNECTED', 'history link was superseded');
}
preSend();
return accepted;
},
async () => {
if (!isSharedTaskPeer(deviceId)) {
const result = await tryMobilePeerInvoke(deviceId, channel, args);
preSend();
if (clientRef.current !== client) throw new DeviceLinkError('NOT_CONNECTED', 'link changed');
if (result) {
return withAccessRevokedHandling(deviceId, async () => unwrapInvoke<T>(result, channel));
}
}
return sendInvokeWithAccessHandling<T>(client, deviceId, channel, args, { preSend, background: opts?.background });
},
);
// Existing list refreshes also reconcile optional project display names. This read
// is single-flight and never changes task-list success or connection recovery.
if (channel === 'local-db:sessions:list') refreshProjectAliasesForClient(client, deviceId);
return result;
}, [refreshProjectAliasesForClient, sendOpenLinkOnce]);
const subscribe = useCallback(async (owner: string, deviceId: string, topics: string[]) => {
topics = sharedTaskTopics(deviceId, topics);
// `owner` is the stable id of the mounted consumer (e.g. `session:<id>`). Tracking is
// idempotent per (owner, topic), so resync/retry resubscribes don't accumulate. The
// server subscribe is idempotent, so it's safe to (re)send the requested topics.
registryRef.current.trackSubscribe(owner, deviceId, topics);
await sendTrackedSubscribe(
requireClient(clientRef.current),
deviceId,
normalizeDeviceLinkTopics(topics),
);
}, [sendTrackedSubscribe]);
const unsubscribe = useCallback(async (owner: string, deviceId: string, topics: string[]) => {
topics = sharedTaskTopics(deviceId, topics);
// Drop only this owner's hold; release (server unsubscribe) the topics whose last owner
// just left. If a focused screen blurs before subscribe acknowledgement, a later cleanup may
// ask to unsubscribe an already-released owner; resend only topics that are currently unheld
// so unsubscribe-before-subscribe delivery cannot leave a stale heavy stream alive.
const released = registryRef.current.untrackSubscribe(owner, deviceId, topics);
const releasedSet = new Set<string>(released);
const staleUnheld = topics.filter((topic) =>
isDeviceLinkTopic(topic) && !releasedSet.has(topic) && !registryRef.current.hasTopic(deviceId, topic));
const toSend = normalizeDeviceLinkTopics([...new Set([...released, ...staleUnheld])]);
markRemoteTopicsUnsubscribed(remoteSubscribedTopicsRef.current, deviceId, toSend);
suspendRemoteProjectAliasesForReleasedTopics(deviceId, toSend);
noteSessionLiveStreamsInterrupted(toSend);
if (toSend.length === 0 || presenceAvailableByDeviceRef.current.get(deviceId) === false) return;
await sendUnsubscribe(
requireClient(clientRef.current),
deviceId,
toSend,
(topic) => presenceAvailableByDeviceRef.current.get(deviceId) !== false && !registryRef.current.hasTopic(deviceId, topic),
);
}, []);
const getPresenceAvailability = useCallback((deviceId: string): boolean | null => (
isSharedTaskPeer(deviceId) ? clientRef.current?.isLinkReady(deviceId) ?? false
: presenceAvailableByDeviceRef.current.get(deviceId) ?? null
), []);
const value = useMemo<DeviceLinkContextValue>(() => ({
beginBackgroundTransition,
status,
sharedTaskAvailable,
recoveringDeviceIds,
connectionIssue,
presenceVersion,
connectionEpoch,
lastPresenceSnapshot,
getSubscriptionIdentity: (deviceId, topics) => remoteSubscribedTopicsRef.current.identity(deviceId, sharedTaskTopics(deviceId, topics)),
getPresenceAvailability,
readDeviceList,
openLink,
reopenLink,
closeLink,
invoke,
subscribe,
unsubscribe,
onAgentsChanged: subscribeRemoteAgentRoster,
onRemoteResourceChanged: subscribeRemoteResourceChanged,
}), [
beginBackgroundTransition,
closeLink,
recoveringDeviceIds,
connectionEpoch,
connectionIssue,
getPresenceAvailability,
readDeviceList,
invoke,
lastPresenceSnapshot,
openLink,
reopenLink,
presenceVersion,
status,
sharedTaskAvailable,
subscribe,
unsubscribe,
subscribeRemoteAgentRoster,
subscribeRemoteResourceChanged,
subscriptionVersion,
]);
return <DeviceLinkContext.Provider value={value}>
<DirectLinkTransport key={`${auth.accountGeneration}:${connectionEpoch}`} bridge={directBridge}
owner={`${auth.accountGeneration}:${connectionEpoch}`} enabled={auth.isAuthenticated && status === 'online'} />
{children}
</DeviceLinkContext.Provider>;
}
function VisualMockDeviceLinkProvider({ children }: { children: ReactNode }) {
const [value, setValue] = useState<DeviceLinkContextValue | null>(null);
useEffect(() => {
let mounted = true;
void prepareVisualMockDeviceLinkContext().then((context) => {
if (mounted) setValue(context);
});
return () => { mounted = false; };
}, []);
if (!value) return null;
return <DeviceLinkContext.Provider value={value}>{children}</DeviceLinkContext.Provider>;
}
type RouteFrameHandlers = {
currentDataOwnerId?: string | null;
onAccessRevoked?: (deviceId: string) => void;
onLinkClosed?: (deviceId: string, reason?: string) => void;
onProviderChanged?: (deviceId: string) => void;
onAgentsChanged?: (deviceId: string) => void;
onProjectAliasesChanged?: (deviceId: string, ownerStamp: unknown) => void;
};
/** routeFrame plus per-channel push handling time while local diagnostics record. */
function routeFrameMeasured(env: Envelope, handlers: RouteFrameHandlers): void {
if (!jankMetricsEnabled() || env.kind !== 'push') {
routeFrame(env, handlers);
return;
}
const started = performance.now();
try {
routeFrame(env, handlers);
} finally {
const channel = (env.payload as PushPayload | null)?.channel;
recordPushHandled(typeof channel === 'string' ? channel : '(unknown)', performance.now() - started);
}
}
export function routeFrame(env: Envelope, handlers: RouteFrameHandlers = {}): void {
const peerLinkClosed = handlePeerLinkCloseFrame(
env,
(deviceId, reason) => handlers.onLinkClosed?.(deviceId, reason),
);
if (applyAccessRevokedFrame(env)) {
if (env.src) handlers.onAccessRevoked?.(env.src);
return;
}
if (peerLinkClosed) return;
if (env.kind !== 'push' || !env.src) return;
const rawPush = env.payload as PushPayload;
const push = { ...rawPush, payload: decodeModelSpeedPayload(rawPush.channel, rawPush.payload) };
recordDeviceLinkPush(push.channel, push.payload);
dispatchCredentialSwitchOutcome(env.src, push.channel, push.payload);
if (push.channel === 'local-db:task-tags:changed') {
writeTaskTagCatalog(
handlers.currentDataOwnerId,
env.src,
(push.payload as { tags?: unknown })?.tags,
);
for (const listener of remoteTaskTagsChangedListeners)
listener(env.src, (push.payload as { tags?: unknown })?.tags);
}
if (push.channel === 'maker:model-favorites:changed') {
for (const listener of remoteFavoritesChangedListeners) listener(env.src);
return;
}
if (push.channel === PROJECT_ALIASES_CHANGED_CHANNEL) {
handlers.onProjectAliasesChanged?.(env.src, push.ownerStamp);
for (const listener of remoteProjectAliasesChangedListeners) listener(env.src);
return;
}
if (push.channel === 'maker:provider:changed') {
handlers.onProviderChanged?.(env.src);
return;
}
if (push.channel === 'maker:agents:changed') {
handlers.onAgentsChanged?.(env.src);
return;
}
if (push.channel === 'maker:orca:worker-changed') {
const leadSessionId = (push.payload as { leadSessionId?: unknown } | null)?.leadSessionId;
if (typeof leadSessionId !== 'string' || !leadSessionId) return;
for (const listener of remoteOrcaWorkerChangedListeners) listener(env.src, leadSessionId);
return;
}
if (push.channel === 'maker:bot-delegation:changed' || push.channel === 'maker:bot-direct-message:changed') {
for (const listener of remoteBotChangedListeners) listener(env.src, push.channel, push.payload);
return;
}
if (push.channel === REMOTE_RESOURCE_CHANGED_CHANNEL) {
const payload = parseRemoteResourceChangedPayload(push.payload);
if (!payload) return;
for (const listener of remoteResourceChangedListeners) listener(env.src, payload);
return;
}
if (push.channel === 'maker:schedule:event') {
remoteScheduleEventStore.apply(env.src, push.payload);
}
if (push.channel === SIDEBAR_PROJECT_ORDER_CHANGED_CHANNEL) {
applyRemoteProjectOrderPush(env.src, push.payload, {
controllerDataOwnerId: handlers.currentDataOwnerId ?? null,
ownerStamp: push.ownerStamp,
ownerStampPresent: Object.prototype.hasOwnProperty.call(push, 'ownerStamp'),
});
return;
}
if (push.channel === FILE_BROWSER_EVENT_CHANNEL) {
// 文件树变更是 workdir 域事件,与会话 store 无关,单独分发给文件浏览页。
dispatchFileBrowserWatchEvent(push.payload);
return;
}
if (push.channel === DEVICE_LINK_VOICE_DICTIONARY_SNAPSHOT_CHANNEL) {
// 只读全量快照由桌面主动推送,不经过 remoteControlEnabled 控制门禁。
// env.src 是 relay 写入的来源设备,缓存按它分片,不能信任 payload 自报 host。
void applyMobileVoiceDictionarySnapshot(
env.src,
push.payload as MobileVoiceDictionarySnapshotResult,
);
return;
}
const historySessionId = (push.payload as { sessionId?: unknown } | null)?.sessionId;
const historyView = typeof historySessionId === 'string' ? findRemoteHistoryView(env.src, historySessionId) : undefined;
if (push.channel === 'maker:history-view-changed') {
historyView?.invalidate();
return;
}
if (push.channel === 'maker:history-work-patch') {
historyView?.applyWorkPatch(push.payload as HistoryWorkPatch);
return;
}
remoteSessionStore.applyRemotePush(env.src, push.channel, push.payload);
const patch = (push.payload as { patch?: { clearedAt?: unknown; status?: unknown } } | null)?.patch;
if (historyView && push.channel === 'local-db:sessions:patched'
&& (patch?.status === 'deleted' || patch?.status === 'archived')) {
historyView.setActive(false);
historyView.reset();
} else if (historyView && push.channel === 'local-db:sessions:patched' && typeof patch?.clearedAt === 'string') {
// reset switches the screen back to its raw mirror until the fresh view arrives.
// Retire that mirror too so a failed refresh cannot reveal pre-clear messages.
remoteSessionStore.invalidateSessionMessageWindow(historySessionId as string, env.src);
historyView.reset();
} else if (historyView?.getSnapshot().ready && (push.channel === 'local-db:messages:created' || push.channel === 'maker:status-changed')) historyView.invalidate();
}
async function rebuildSessionSnapshot(
client: DeviceLinkClient,
deviceId: string,
sessionId: string,
connectionEpoch: number,
opts: DeviceLinkRehydrateSendOptions | undefined,
isCurrent: () => boolean,
): Promise<void> {
const record = recoveryDiagnostics.get(client)?.capture(deviceId, connectionEpoch);
const measured = <T,>(phase: RecoveryPhase, read: Promise<T>, apply: (value: T) => boolean) =>
settleMeasuredSnapshot(read, apply, (outcome) => record?.(phase, outcome));
// 这四个并发请求是同一轮补齐:一次路由抖动可能让它们同时等满超时,但这只
// 代表一个独立故障观测。共享显式 cohort,避免单轮 fan-out 直接凑满 3 次阈值。
const sendOpts: SendInvokeOptions = {
responsivenessCohort:
opts?.responsivenessCohort ?? createDeviceSendCohort(deviceId),
};
const projectionEpochAtRequestStart =
remoteSessionStore.captureInputProjectionAuthorityEpoch(sessionId);
const messageDetailEnteredAtRequestStart =
remoteSessionStore.hasSessionMessageDetailEntered(sessionId);
const messageAuthorityAtRequestStart = messageDetailEnteredAtRequestStart
? remoteSessionStore.captureSessionMessageAuthority(sessionId)
: null;
const unenteredMessageAuthorityAtRequestStart = messageDetailEnteredAtRequestStart
? null
: remoteSessionStore.captureUnenteredSessionMessageAuthority(sessionId);
const snapshotScope = { deviceId, sessionId, connectionEpoch, subscriptionIdentity: opts?.subscriptionIdentity };
const pendingSnapshotAtRequestStart = remoteSessionStore.getPendingInteractions(sessionId);
// 四路快照独立拉取、独立落库:断连补齐窗口本就脆弱,一个子请求失败不应拖垮
// 其余(旧实现共用一个 catch,任一失败三份快照全丢)。goal 覆盖断连窗口内
// 丢失的 maker:goal:status-changed push;model-pref / turn-cost 无对应查询通道,
// 暂不在补齐范围(需扩桌面端 invoke 白名单)。
const applyHistory = (value: RemoteMessage[], moreBeyondWindow: boolean) => {
if (!isCurrent()) return false;
if (Array.isArray(value)) {
// moreBeyondWindow:这一页上沿之外服务端还有历史(满 80 条,或被 device-link 裁过行)。为真时
// store 不保留接不上已验证区间的缓存段 —— 断连期间漏收的 push 可能正落在两段之间,保留就在
// 窗口里留下孤岛,而漏收的量不大时两侧时间差很小、时间阈值的空洞检测发现不了(#1222)。
// readHistory 会先补读到接上为止,接上的旧段因此得以保留。
const windowOptions = { moreBeyondWindow };
if (messageAuthorityAtRequestStart) {
return remoteSessionStore.setLatestMessageWindow(sessionId, value, {
...windowOptions,
authority: messageAuthorityAtRequestStart,
});
} else if (
unenteredMessageAuthorityAtRequestStart
&& remoteSessionStore.canCommitUnenteredSessionMessageWindow(
unenteredMessageAuthorityAtRequestStart,
deviceId,
)
) {
// 从未打开过的 regular 仍承担首页/全局消息镜像;但请求飞行期间只要发生过
// enter / leave / forget / clear,生命周期 fence 就会失效,旧重连响应不得越过
// 新生命周期。Store 同时校验 regular retention 与物理设备归属,避免旧设备响应
// 写回新 shard。
return remoteSessionStore.setLatestMessageWindow(sessionId, value, windowOptions);
}
}
return false;
};
const applyPending = (value: PendingInteraction[]) => {
if (!isCurrent()) return false;
if (Array.isArray(value)) {
remoteSessionStore.setPendingInteractions(sessionId, value, { finalizeStreaming: true, deviceId });
return true;
}
return false;
};
const applyProjection = (value: InputProjection) => {
if (!isCurrent()) return false;
if (value) {
return remoteSessionStore.setInputProjectionIfCurrent(
sessionId,
value,
projectionEpochAtRequestStart,
);
}
return false;
};
const applyGoal = (value: MobileGoalStatusPayload | null | undefined) => {
if (!isCurrent()) return false;
// undefined = 未拿到/未知(兼容形态的空返回),不能当作权威「无 goal」落库——
// 那会把在世的 goal 卡清掉直到下一条 push;只有显式 null 才代表确认无 goal。
if (value !== undefined) {
remoteSessionStore.setGoalStatus(sessionId, value);
return true;
}
return false;
};
const historyView = findRemoteHistoryView(deviceId, sessionId);
const readRawHistory = () => runSessionMessagesSnapshotSingleFlight(
snapshotScope,
RECONNECT_MESSAGE_WINDOW_LIMIT,
messageAuthorityAtRequestStart
? { kind: 'detail', generation: messageAuthorityAtRequestStart.generation }
: {
kind: 'unentered',
generation: unenteredMessageAuthorityAtRequestStart?.generation ?? -1,
resetEpoch: unenteredMessageAuthorityAtRequestStart?.resetEpoch ?? -1,
},
() => sendInvokeWithAccessHandling<RemoteMessage[]>(
client,
deviceId,
'local-db:messages:list',
[sessionId, { limit: RECONNECT_MESSAGE_WINDOW_LIMIT }],
sendOpts,
),
);
const readHistory = async () => {
if (historyView) {
if (!historyView.isActive()) return false;
await historyView.refresh(false, opts?.subscriptionIdentity != null);
if (!isCurrent() || !historyView.isActive()
|| findRemoteHistoryView(deviceId, sessionId) !== historyView) return false;
const snapshot = historyView.getSnapshot();
if (!snapshot.error && snapshot.ready) return true;
if (!isHistoryViewUnavailable(snapshot.error)) throw snapshot.error;
}
const latest = await readRawHistory();
if (!Array.isArray(latest)) return applyHistory(latest, false);
// 断线期间漏收超过一页时,最新一页接不上已验证区间;先往前补读,避免旧历史被整段丢弃。
const page = await bridgeLatestMessagePage(
{ messages: latest, limit: RECONNECT_MESSAGE_WINDOW_LIMIT, reducedByPayloadTooLarge: false },
{
needsBridge: (rows, more) =>
remoteSessionStore.latestMessageWindowNeedsBridge(sessionId, rows, more),
readBefore: (before) => listMessagesWithPayloadRetry(
(limit) => sendInvokeWithAccessHandling<RemoteMessage[]>(
client,
deviceId,
'local-db:messages:list',
[sessionId, { limit, before }],
sendOpts,
),
),
isCurrent,
},
);
return applyHistory(page.messages, shouldKeepOlderMessagesAffordance(page));
};
const [history, pending, projection, goal] = await Promise.all([
measured('history', readHistory(), (applied) => applied),
measured('pending', runSessionPendingInteractionsSnapshotSingleFlight(
snapshotScope,
pendingSnapshotAtRequestStart,
() => sendInvokeWithAccessHandling<PendingInteraction[]>(
client,
deviceId,
'maker:get-pending-interactions',
[sessionId],
sendOpts,
),
), applyPending),
measured('projection', runSessionProjectionSnapshotSingleFlight(
snapshotScope,
projectionEpochAtRequestStart,
() => sendInvokeWithAccessHandling<InputProjection>(
client,
deviceId,
'maker:input:get-projection',
[sessionId],
sendOpts,
),
), applyProjection),
measured('goal', sendInvokeWithAccessHandling<MobileGoalStatusPayload | null | undefined>(
client,
deviceId,
'maker:goal:get-status',
[sessionId],
sendOpts,
), applyGoal),
]);
// 任一子快照瞬时失败 → 上抛让 rehydrate 计入重试;永久失败(老被控端无 goal
// 通道的 CHANNEL_NOT_ALLOWED、权限撤销等)吞掉,重试没有意义。同批若已有
// fulfilled 目标应答,兄弟 unavailable 只能算局部瞬态,不能升级为整机 verdict。
const batchFailure = classifySnapshotBatchFailure([
history,
pending,
projection,
goal,
]);
if (batchFailure.kind === 'partial-transient') {
throw Object.assign(new Error('partial snapshot needs retry'), {
code: 'INVOKE_TIMEOUT',
});
}
if (batchFailure.kind === 'reject') throw batchFailure.error;
}
// 掉线/重连窗口里发起请求时,先有界等待连接就绪的上限。够一次健康重连握手完成
// (通常 <1s),又短到连不上时能快速失败、让上层 withTransientRemoteRetry 重试,
// 而不是把单次 client.invoke park 在退避 gap 里干等十几秒。
const CONNECT_READY_TIMEOUT_MS = 1_500;
// 发请求前确保连接就绪:online 直接放行;否则促成立即重连并有界等待上线,
// 超时抛 NOT_CONNECTED(transient)交由上层重试 —— 把"等整个退避 gap"压成"等一次重连"。
function ensureOnlineForRequest(client: DeviceLinkClient, deviceId?: string): Promise<void> {
if (client.getStatus() === 'online' || (deviceId && client.hasOfflineDirectPath(deviceId))) return Promise.resolve();
return client.waitUntilOnline(CONNECT_READY_TIMEOUT_MS);
}
function sendOpenLinkWithAccessHandling(
client: DeviceLinkClient,
deviceId: string,
allowProbe = false,
preSend?: () => void,
pendingReplyRecovery = false,
): Promise<LinkAcceptPayload> {
return withAccessRevokedHandling(deviceId, () => sendOpenLink(client, deviceId, allowProbe, preSend, pendingReplyRecovery));
}
async function sendOpenLink(
client: DeviceLinkClient,
deviceId: string,
allowProbe = false,
preSend?: () => void,
pendingReplyRecovery = false,
): Promise<LinkAcceptPayload> {
preSend?.();
// 熔断门禁放在连接等待之前:open 时快速失败,不消耗 1.5s 重连等待也不上管道。
// Reply transport must not compete with the business request it is restoring.
// The provider's preSend guard limits this exemption to current pending work.
const slot = pendingReplyRecovery ? null : acquireDeviceSendSlot(deviceId, undefined, { allowProbe });
try {
await ensureOnlineForRequest(client);
} catch (err) {
if (slot) settleDeviceSend(deviceId, slot, 'inconclusive');
throw err;
}
try {
preSend?.();
const accepted = await client.openLink(deviceId, {
controllerName: mobileDeviceName(),
protocolVersion: PROTOCOL_VERSION,
appVersion: Constants.expoConfig?.version ?? '0.0.0',
capabilities: CONTROLLER_CAPABILITIES,
});
// link-accept 只证明链路层活着,不证明 invoke 路径健康(review P1):事故形态
// 正是 link-open 在被控端 IPC/DB 路径之外应答正常、invoke 全部挂死——若凭
// link-accept 关熔断,恢复流程会立刻放进订阅 + 快照 + 业务 invoke 突发,3 次
// 超时后再 open,形成周期性风暴。这里按不定论处理:不关熔断也不计失败;
// openLink 若是探测,单飞席位随之释放、退避窗口不动,紧随其后的 subscribe
// (真实 invoke 通道)会立即接棒成为新探测,由它的回包决定开合。
if (slot) settleDeviceSend(deviceId, slot, 'inconclusive');
markRemoteResponseEvidence(deviceId);
// 显式 openLink 成功 = 链路已重建:解除永久关闭后的重建抑制。
liftRehydrateSuppressionOnExplicitOpen(rehydrateSuppressedDeviceIds, deviceId);
return accepted;
} catch (err) {
// 超时仍计失败:link-open 都等不到回包说明被控端连链路层都没在应答。
// 终态 relay 应答(REMOTE_DISABLED / DEVICE_OFFLINE / VERSION_MISMATCH)
// 关熔断,把 UI 让给对应的可操作错误态(review P1:否则设备被永远探测)。
if (slot) settleDeviceSend(deviceId, slot, classifyLinkOpenFailure(err));
throw err;
}
}
interface SendInvokeOptions {
preSend?: () => void;
background?: boolean;
/** 同一轮明确 fan-out 共享;普通独立请求省略。 */
responsivenessCohort?: number;
/** 仅主动的代表性 half-open 探测允许领取 probe 席位。 */
allowProbe?: boolean;
}
function sendInvokeWithAccessHandling<T>(
client: DeviceLinkClient,
deviceId: string,
channel: string,
args: unknown[],
opts?: SendInvokeOptions,
): Promise<T> {
return withAccessRevokedHandling(deviceId, () => sendInvoke<T>(client, deviceId, channel, args, opts));
}
async function sendInvoke<T>(
client: DeviceLinkClient,
deviceId: string,
channel: string,
args: unknown[],
opts?: SendInvokeOptions,
): Promise<T> {
recordInvokeSent(channel);
// 熔断门禁放在连接等待之前:open 时快速失败,不消耗 1.5s 重连等待也不上管道。
// 同一轮显式 fan-out 复用 cohort;普通调用省略时每次 acquire 都是独立观测。
const slot = acquireDeviceSendSlot(deviceId, opts?.responsivenessCohort, {
allowProbe: opts?.allowProbe,
});
try {
await ensureOnlineForRequest(client, deviceId);
// 连接就绪后先检查一次:重连等待期间调用方状态可能已失效
// (写被同字段新写取代),抛错即中止发送。
opts?.preSend?.();
} catch (err) {
// 未真正发送(等待连接失败 / preSend 中止):对设备响应性不定论。
settleDeviceSend(deviceId, slot, 'inconclusive');
throw err;
}
let result: InvokeResultPayload;
let preSendFailed = false;
try {
// 长执行通道(desktop-cmd:run / worktree:create 等)按协议契约表放宽超时,
// 与桌面控制端用法对齐,避免 mobile 收紧的默认 15s 误伤合法慢操作。
result = await client.invoke(
deviceId,
{ channel, args },
// 长通道(media / 文件搜索 / schedule 就绪窗口等)按 invokeTimeouts 解析
// 规则保留更长窗口,避免 mobile 收紧的默认 15s 误伤合法慢操作。
resolveMobileInvokeTimeoutMs(channel, args),
{ background: opts?.background, preSend: () => {
try {
opts?.preSend?.();
} catch (err) {
preSendFailed = true;
throw err;
}
} },
);
} catch (err) {
// A queued call rejected by its local guard is not a remote timeout.
settleDeviceSend(deviceId, slot, preSendFailed ? 'inconclusive' : classifyDeviceSendFailure(err));
throw err;
}
// 收到 invoke-result 帧即为目标设备真实回包(即使 ok:false 的业务错误)。但
// dispatch 特判通道(media/voice)的成功不走 IPC/DB 路径,且持有探测席位时
// 只有指定探测通道能关熔断(纯内存 IPC handler 的回包不算)——按通道 +
// 席位分类收尾(review P1 多轮收敛,见 classifyDeviceSendSuccess)。
settleDeviceSend(deviceId, slot, classifyDeviceSendSuccess(channel, slot.decision === 'probe'));
if (isInvokeResultReachabilityEvidence(result)) {
markRemoteResponseEvidence(deviceId);
}
return unwrapInvoke<T>(result, channel);
}
async function sendSubscribeWithAccessHandling(
client: DeviceLinkClient,
deviceId: string,
topics: readonly string[],
shouldSend?: () => boolean,
): Promise<boolean> {
if (!shouldSend) {
await withAccessRevokedHandling(
deviceId,
() => sendSubscribe(client, deviceId, topics),
);
return true;
}
// 本地取消不能穿过 withAccessRevokedHandling 的成功路径:该 wrapper 会把任何
// fulfilled operation 当作目标端可达证据并清掉 revoked。用不属于协议错误的
// sentinel 退出 wrapper,只有实际 invoke 的结果才允许更新撤权状态。
const notSent = Symbol('subscribe-not-sent');
try {
await withAccessRevokedHandling(deviceId, async () => {
if (!await sendSubscribe(client, deviceId, topics, shouldSend)) throw notSent;
});
return true;
} catch (err) {
if (err === notSent) return false;
throw err;
}
}
async function sendSubscribe(
client: DeviceLinkClient,
deviceId: string,
topics: readonly string[],
shouldSend?: () => boolean,
): Promise<boolean> {
// subscribe 同样走隧道请求超时等待(默认 15s),一样计入并受熔断限制(见 sendInvoke 注释)。
const slot = acquireDeviceSendSlot(deviceId);
try {
await ensureOnlineForRequest(client, deviceId);
} catch (err) {
settleDeviceSend(deviceId, slot, 'inconclusive');
throw err;
}
// ensureOnlineForRequest 最长等待 1.5s;期间 App 可能已退后台并开始释放
// heavy topics。真正 invoke 前再检查一次,避免迟到 subscribe 覆盖 unsubscribe。
if (shouldSend && !shouldSend()) {
settleDeviceSend(deviceId, slot, 'inconclusive');
return false;
}
let result: InvokeResultPayload;
try {
result = await client.invoke(deviceId, {
channel: DL_SUBSCRIBE_CHANNEL,
args: [{
topics,
controllerName: mobileDeviceName(),
capabilities: CONTROLLER_CAPABILITIES,
}],
});
} catch (err) {
settleDeviceSend(deviceId, slot, classifyDeviceSendFailure(err));
throw err;
}
// subscribe/unsubscribe 是控制帧,被控端 dispatch 在 runInvoke 之前特判应答
// (review P1):IPC/DB 卡死时照常回包,成功不能作为熔断恢复证据——探测窗口
// 到点时页面卸载恰好发的一条控制帧会抢占探测席位并误关熔断。与 openLink
// 同语义:成功按不定论,超时仍计失败(连控制帧都不应答 = 彻底无响应)。
settleDeviceSend(deviceId, slot, 'inconclusive');
if (isInvokeResultReachabilityEvidence(result)) {
markRemoteResponseEvidence(deviceId);
}
unwrapInvoke(result);
return true;
}
async function sendUnsubscribe(
client: DeviceLinkClient,
deviceId: string,
topics: readonly string[],
shouldSendTopic?: (topic: string) => boolean,
): Promise<void> {
const slot = acquireDeviceSendSlot(deviceId);
try {
await ensureOnlineForRequest(client, deviceId);
} catch (err) {
settleDeviceSend(deviceId, slot, 'inconclusive');
throw err;
}
// Scope may be reacquired while ensureOnlineForRequest is waiting. Filter immediately
// before client.invoke (there is no await between this check and enqueueing the frame),
// so an older cleanup can never land after a newer subscribe and tear it down again.
const toSend = shouldSendTopic ? topics.filter(shouldSendTopic) : topics;
if (toSend.length === 0) {
settleDeviceSend(deviceId, slot, 'inconclusive');
return;
}
let result: InvokeResultPayload;
try {
result = await client.invoke(deviceId, {
channel: DL_UNSUBSCRIBE_CHANNEL,
args: [{ topics: toSend }],
});
} catch (err) {
settleDeviceSend(deviceId, slot, classifyDeviceSendFailure(err));
throw err;
}
// 控制帧成功按不定论,不作熔断恢复证据(同 sendSubscribe,review P1)。
settleDeviceSend(deviceId, slot, 'inconclusive');
if (isInvokeResultReachabilityEvidence(result)) {
markRemoteResponseEvidence(deviceId);
}
unwrapInvoke(result);
}
function unwrapInvoke<T = unknown>(result: InvokeResultPayload, channel?: string): T {
if (result.ok) return decodeModelSpeedPayload(channel, result.result) as T;
if (result.error.code === 'IPC_ERROR') throw new Error(result.error.message);
throw new DeviceLinkError(result.error.code, result.error.message);
}
function requireClient(client: DeviceLinkClient | null): DeviceLinkClient {
if (!client) throw new DeviceLinkError('NOT_CONNECTED', 'device-link client is not ready');
return client;
}
function markOfflineDeviceMirrors(deviceIds: readonly string[]): void {
// 普通离线只清依赖在线连接的 live 投影,保留 session/messages。这样用户切回
// 刚看过的会话时先看到 last-known 内容,恢复后 marker 失效会触发后台窗口对账。
// 批量入口:同一波离线两个 store 各 notify 一次,而不是每台各 notify 一轮——
// 逐台通知时设备数超过 React 嵌套更新上限即致命退出(2026-09-10)。
remoteSessionStore.markDevicesOffline(deviceIds);
for (const deviceId of deviceIds) {
invalidateScheduleIndexForDevice(deviceId);
evictDeviceProviders(deviceId);
evictProviderShareCatalogs(deviceId);
evictDeviceModelMeta(deviceId);
evictAgentCapabilitiesForDevice(deviceId);
evictComposerPaletteCacheForDevice(deviceId);
}
remoteScheduleEventStore.invalidateDeviceMirrors(deviceIds);
}
function wipeUnavailableDeviceMirror(deviceId: string): void {
evictTaskTagCatalog(deviceId);
resetRemoteProjectOrderPushFence(deviceId);
removeRemoteProjectAliases(deviceId);
invalidateScheduleIndexForDevice(deviceId);
remoteSessionStore.removeDevice(deviceId);
remoteScheduleEventStore.clearDevice(deviceId);
remoteScheduleEventStore.clearDeviceMirrorInvalidation(deviceId);
// Drop the cached provider catalog so a returning/re-granted device re-fetches it
// instead of serving a list frozen from a previous connection.
evictDeviceProviders(deviceId);
evictProviderShareCatalogs(deviceId);
evictDeviceModelMeta(deviceId);
// 能力表与供应商目录同时机驱逐:桌面端重连 / 升级 / 重新授权后必须重取,
// 否则模型 / 权限 / plan 支持度会先按旧能力渲染并接受点击。
evictAgentCapabilitiesForDevice(deviceId);
evictComposerPaletteCacheForDevice(deviceId);
}
const basePresenceWipeTimerDeps = {
now: Date.now,
setTimer: (callback: () => void, delayMs: number) =>
setTimeout(callback, delayMs),
clearTimer: clearTimeout,
};
function scheduleUnavailableDeviceMirrorWipe(
timers: Map<string, PresenceWipeTimerEntry>,
availabilityByDevice: ReadonlyMap<string, boolean>,
deviceId: string,
deps: typeof basePresenceWipeTimerDeps & { wipe(deviceId: string): void },
): void {
schedulePresenceWipeTimer(
timers,
availabilityByDevice,
deviceId,
PRESENCE_OFFLINE_WIPE_GRACE_MS,
deps,
);
}
function isDeviceLinkTopic(topic: string): boolean {
return topic === 'sessions' || topic.startsWith('session:');
}
function mobileDeviceName(): string {
return buildMobileDeviceName({
constantsDeviceName: Constants.deviceName,
platform: Platform.OS,
});
}
type MobileDeviceLinkLogLevel = 'debug' | 'info' | 'warn' | 'error';
const mobileDeviceLinkLogger = {
debug: (...args: unknown[]) => logMobileDeviceLink('debug', args),
info: (...args: unknown[]) => logMobileDeviceLink('info', args),
warn: (...args: unknown[]) => logMobileDeviceLink('warn', args),
error: (...args: unknown[]) => logMobileDeviceLink('error', args),
};
function logMobileDeviceLink(level: MobileDeviceLinkLogLevel, args: unknown[]): void {
mobileDebugLog(level, 'device-link', ...args);
if (!__DEV__ && level === 'debug') return;
if (level === 'error') {
console.error('[device-link]', ...args);
return;
}
if (level === 'warn') {
console.warn('[device-link]', ...args);
return;
}
if (level === 'info') {
console.info('[device-link]', ...args);
return;
}
console.debug('[device-link]', ...args);
}
export function useDeviceLink(): DeviceLinkContextValue {
const ctx = useContext(DeviceLinkContext);
if (!ctx) throw new Error('useDeviceLink must be used inside DeviceLinkProvider');
return ctx;
}